One static file (quantum.min.css). Fewest classes, correct trees, readable light/dark.
No JIT. No invented classes.
examples/kitchen-sink.html orsrc/styles/quantum-components.css / quantum-utilities.css<link rel="stylesheet" href="https://unpkg.com/@howssatoshi/quantumcss@latest/dist/quantum.min.css">
<script src="https://unpkg.com/@howssatoshi/quantumcss@latest/src/starlight.js"></script>
Attr on <html> |
Role |
|---|---|
data-theme |
Active (light / dark) — never on body |
data-theme-default |
Fallback |
data-theme-storage="path" |
Per-pathname localStorage (avoids multi-demo pollution) |
data-theme-locked |
Always use default; ignore storage |
Auto-detection runs only when there is no saved preference, no data-theme-locked, and no explicit data-theme-default. To disable it in that fallback case, set this before starlight.js:
<script>window.StarlightConfig = { theme: { autoDetect: false } };</script>
<!-- GOOD --><div class="card"><h2>Title</h2><p>Body.</p><button class="btn-primary">Go</button></div>
<!-- BAD --> <div class="bg-white_5 rounded-xl border p-6 backdrop-blur-md">…
Opacity: bg-white_5 not bg-white/5.
| Role | Use |
|---|---|
| Headings + body reading | Bare h1–h3, bare p — no text-secondary on long copy |
| Lead / supporting | text-secondary (short only) |
| Captions / meta | text-muted or text-sm text-muted |
| Brand accent word | text-gradient (uses --q-color-starlight-*) |
Do not paint entire heroes or card descriptions with text-secondary — light pages look washed out.
<html lang="en" data-theme="dark" data-theme-default="dark">
<body class="starlight-layout">
<div class="starlight-stars ani-nebula" aria-hidden="true"></div>
<header class="nav-header">…</header>
<main class="p-8"><div class="max-w-6xl mx-auto">…</div></main>
</body>
.starlight-layoutlifts all direct children (except.starlight-stars) above the starfield viaposition: relative; z-index: 1. Without it, unpositioned elements (headings, paragraphs, tables) render behind the opaque star layer and appear dimmed. The nav-header keeps its ownsticky; z-index: 100via@layer components..ani-nebuladrifts/scales the starfield at a fixed 55% opacity; it does not pulse text contrast, andprefers-reduced-motionrenders it static.
<html lang="en" data-theme="light" data-theme-default="light" data-theme-storage="path">
<body>
<!-- no starlight-stars -->
<header class="nav-header">…</header>
<main class="p-8"><div class="max-w-6xl mx-auto">…</div></main>
</body>
Rules: skip starfield; few cards; override --q-color-starlight-* for brand; solid ink is default (do not force light grey body text).
bare · btn-primary · btn-outline · btn-ghost · btn-secondary · btn-starlight · btn btn-glossy · btn-sm / btn-lg
card · card-premium · starlight-card · glass · surface-1 / surface-2
Badges: badge badge-{primary,secondary,success,warning,error}
Alerts: alert alert-{success,warning,error,info}
<input type="checkbox" id="nav-toggle" class="nav-toggle">
<header class="nav-header">
<a href="/" class="nav-logo"><i class="icon-starlight"></i><span class="text-gradient font-bold">Brand</span></a>
<nav class="nav-links" aria-label="Primary"><a href="#a">A</a></nav>
<button class="btn-primary">CTA</button>
<label for="nav-toggle" class="nav-hamburger" aria-label="Menu">
<span class="nav-hamburger-icon"><span></span><span></span><span></span></span>
</label>
</header>
<div class="nav-drawer"><div class="nav-drawer-inner"><a href="#a">A</a></div></div>
<div class="search has-icon"><i class="icon-search"></i>
<input type="search" class="search-input" placeholder="Search…"></div>
<div class="dashboard">
<div class="starlight-card stat-card">
<span class="stat-label">Label</span>
<span class="stat-value">98</span>
<div class="stat-trend up"><i class="icon-trend-up"></i> 2%</div>
</div>
</div>
<div class="table-premium-container">
<div class="table-premium-header">
<div class="table-premium-title">Title</div>
<div class="table-premium-filters"></div>
</div>
<table class="table-premium">
<thead><tr><th>A</th><th>B</th></tr></thead>
<tbody><tr><td>1</td><td>2</td></tr></tbody>
</table>
</div>
starlight.js)<div data-accordion>
<div class="accordion-item active">
<div class="accordion-header">
<span>Question?</span>
<i class="icon-chevron-down accordion-icon"></i>
</div>
<div class="accordion-content"><p>Answer.</p></div>
</div>
</div>
No accordion-group.
starlight.js)tab-list > tab-button (data-tab) + tab-panel (id)
dialog-overlay > dialog > dialog-close (+ hidden to hide)
Default .dialog hugs short copy, grows for forms/tables, and clamps to the viewport (dvh + safe-area). Optional: dialog-sm · dialog-lg · dialog-full. Override --q-dialog-max-width / --q-dialog-form-width if you need a different measure — do not write per-app width media queries.
timeline > timeline-item > timeline-dot + timeline-content
Bare <form> or:
<form class="form">
<label>Name <input class="input" type="text"></label>
<label>Note <textarea class="input"></textarea></label>
<label>Pick <select class="input">…</select></label>
<div class="form-row">
<div><div class="font-semibold">SMS</div><div class="text-sm text-muted">Optional</div></div>
<label class="toggle toggle-starlight">
<input type="checkbox" class="toggle-input"><span class="toggle-slider"></span>
</label>
</div>
<button type="submit" class="btn-primary">Send</button>
</form>
Put .input on text, email, select, and textarea.
Icon field / label row / divider
<label for="email">Email</label>
<div class="field has-icon">
<i class="icon-mail field-icon" aria-hidden="true"></i>
<input class="input" id="email" type="email" placeholder="you@company.com">
</div>
<div class="label-row">
<label for="password">Password</label>
<a href="#forgot" class="text-sm text-muted">Forgot?</a>
</div>
<div class="form-divider"><span class="text-sm text-muted">or continue with</span></div>
<main class="auth-shell">
<div class="auth-card">
<header class="text-center mb-8">…brand…</header>
<section class="starlight-card">
<form class="form-stack">
<div>
<label for="email">Email</label>
<div class="field has-icon">
<i class="icon-mail field-icon" aria-hidden="true"></i>
<input class="input" id="email" type="email" required>
</div>
</div>
<div class="form-row">…toggle…</div>
<button type="submit" class="btn-starlight btn-shine w-full">Sign in</button>
</form>
<div class="form-divider"><span class="text-sm text-muted">or</span></div>
<div class="grid grid-cols-2 gap-3">
<button type="button" class="btn-outline w-full">GitHub</button>
<button type="button" class="btn-outline w-full">Google</button>
</div>
</section>
</div>
</main>
Full demo: examples/login.html. Classes: auth-shell · auth-card · form-stack · field has-icon · field-icon · label-row · form-divider · btn-shine.
aside-nav (full tree in kitchen-sink) · layout-admin-2col · layout-email-3col · layout-chat-2col · auth-shell
icon-starlight icon-search icon-close icon-home-fill icon-heart icon-heart-fill
icon-sun icon-moon icon-chevron-down icon-chevron-right icon-mail icon-phone
icon-calendar icon-clock-fill icon-cart icon-globe icon-user icon-settings
icon-check-circle-fill icon-trend-up icon-trend-down
Full list: kitchen-sink → Quantum Icons (or quantum-icons.css).
flex grid grid-cols-1…6 gap-* p-*/m-* text-sm…2xl font-bold
w-full max-w-6xl hidden md:grid-cols-2 hover:scale-105
Breakpoints: sm 640 · md 768 · lg 1024 · xl 1280
:root {
--q-color-starlight-blue: #00d4ff;
--q-color-starlight-peach: #ffb38a;
--q-color-starlight-orange: #ff7e5f;
--q-color-primary: #3b82f6;
}
.text-gradient follows starlight peach→blue tokens.
Reading text tokens (--q-light-text*) stay ink — do not repurpose brand primary as body color.
p for body; not every block a glass carddata-accordion| Ask | Emit |
|---|---|
| Landing | Light or dark skeleton + nav + cards + bare type |
| FAQ | Accordion snippet |
| Table | table-premium snippet |
| Form | bare form or .form + .input · icon fields .field.has-icon |
| Login / auth | Dark skeleton + auth-shell / auth-card + form-stack |
| Hospitality | Light skeleton; hierarchy table above |
quantum.min.css (+ starlight.js if needed)?text-secondary)?Kitchen-sink raw: https://raw.githubusercontent.com/macroadster/quantumcss/main/examples/kitchen-sink.html