Beautiful UI by default. One <link> tag. No class soup. No build step required.
QuantumCSS gives your HTML taste so you don’t have to think about it. Buttons look like buttons. Cards look like cards. Forms look like forms. You write semantic markup; QuantumCSS makes it look good.
<link rel="stylesheet" href="quantum.min.css">
<nav>
<a href="/">Home</a>
<a href="/about">About</a>
</nav>
<main>
<div class="card">
<h2>Just write HTML</h2>
<p>QuantumCSS handles the presentation.</p>
<button>Get Started</button>
</div>
</main>
No utility classes. No configuration. That markup renders a polished, dark-mode-ready UI with glassmorphism, smooth transitions, and responsive spacing out of the box.
Think of QuantumCSS as the SQLite of UI frameworks:
The inspiration is macOS Aqua: when Apple shipped those translucent, luminous buttons in 2000, every developer got beauty for free. NSButton didn’t require 14 utility classes. It just looked right. QuantumCSS aims for that same quality – a design system with built-in taste.
QuantumCSS has an opinionated layering model. Reach for the next layer only when the previous one isn’t enough:
| Layer | What it does | Example |
|---|---|---|
| 1. Semantic defaults | Bare HTML elements look great | <button>, <input>, <table> |
| 2. Component classes | Small vocabulary for things HTML can’t express | card, badge, toast, avatar |
| 3. Utility escape hatch | Fine-grained overrides when you need them | text-center, mt-4, bg-primary |
Most pages need only layers 1 and 2. Layer 3 exists for the 20% of cases where you need precise control.
This layering matters for AI-assisted development. Compare a card component:
<!-- Tailwind: ~180 characters of classes -->
<div class="bg-white rounded-lg shadow-lg p-6 border border-gray-200
dark:bg-gray-800 dark:border-gray-700">
<h3 class="text-lg font-semibold text-gray-900 dark:text-white mb-2">Title</h3>
<p class="text-gray-600 dark:text-gray-300">Description</p>
<button class="mt-4 px-4 py-2 bg-blue-600 text-white rounded-md
hover:bg-blue-700 transition-colors">Action</button>
</div>
<!-- QuantumCSS: 18 characters -->
<div class="card">
<h2>Title</h2>
<p>Description</p>
<button>Action</button>
</div>
Same visual result. 10x fewer tokens. That efficiency compounds across every page, every component, every prompt.
The product is a static CSS library — one file, no HTML class scan, no tree-shaking build step for consumers.
quantum-base.css → quantum-icons.css → quantum-components.css
→ quantum-animations.css → quantum-utilities.css
→ dist/quantum.min.css
| Layer | Source | Owns |
|---|---|---|
| Tokens & defaults | src/styles/quantum-base.css |
--q-* design tokens, bare element styles |
| Icons | src/styles/quantum-icons.css |
Icon mask utilities |
| Components | src/styles/quantum-components.css |
Named UI (cards, shells, dialogs, Starlight widgets) |
| Animations | src/styles/quantum-animations.css |
Keyframes and .ani-* |
| Utilities | src/styles/quantum-utilities.css |
Finite atomic escape hatch only |
Ownership rule: never define the same class in both components and utilities. Named UI → components; atomics → utilities. The list of component-owned names is in src/styles/component-owned-classes.json.
Theming is CSS variables only (--q-*, html[data-theme]). Optional: kitchen-sink Theme Designer knobs or npx quantumcss theme for a variable overlay. See SKILL.md for AI-oriented usage rules and AGENTS.md for maintainer conventions.
<link rel="stylesheet" href="https://unpkg.com/@howssatoshi/quantumcss/dist/quantum.min.css">
npm install @howssatoshi/quantumcss
Then either link the CSS directly:
<link rel="stylesheet" href="node_modules/@howssatoshi/quantumcss/dist/quantum.min.css">
Or use the CLI to emit a theme variable overlay:
npx quantumcss theme
QuantumCSS resets and styles base elements so bare markup looks polished:
h1-h6, p, blockquote, code, pre with proper scale and spacinginput, textarea, select, button with focus glow, transitions, and validation statestable, th, td with alternating rows and clean bordersul, ol, li with sensible defaultsa with color, hover transitions, and underline behaviorQuantumCSS follows prefers-color-scheme by default. No toggle needed – it just works. When you do want manual control:
document.documentElement.setAttribute('data-theme', 'light');
To make dark/light deterministic, set a default or lock it:
<html lang="en" data-theme="dark" data-theme-default="dark" data-theme-locked>
When no storage, locked default, or data-theme-default is present, you can disable OS-based auto-detection with:
window.StarlightConfig = { theme: { autoDetect: false } };
If you use .starlight-stars, put starlight-layout on <body> so unpositioned content paints above the starfield:
<body class="starlight-layout">
<div class="starlight-stars ani-nebula" aria-hidden="true"></div>
<main><h1>Full-strength type</h1></main>
</body>
Spacing tokens automatically scale down on narrow screens via CSS custom properties. A --q-space-8 that gives 2rem on desktop becomes 1.5rem on mobile. No breakpoint classes needed for basic responsiveness.
prefers-contrast: more, forced-colors: active)prefers-reduced-motion)For UI patterns that HTML doesn’t natively express, QuantumCSS provides a small vocabulary of semantic classes:
| Class | What it renders |
|---|---|
card / starlight-card |
Glass-effect container with border, shadow, padding |
badge |
Inline status indicator (add badge-success, badge-error, etc.) |
alert |
Notification banner (add alert-warning, alert-success, etc.) |
toast |
Floating notification |
nav-header |
Sticky glassmorphic navigation bar |
btn-primary |
Gradient call-to-action button |
btn-outline / btn-ghost |
Secondary button variants |
dialog |
Centered modal; auto-sizes to content and viewport |
accordion |
Collapsible content sections |
tab-list / tab-panel |
Tabbed interface |
dashboard |
Responsive 3-column grid |
search |
Search input with icon container |
timeline |
Vertical event timeline |
These compose the full Starlight design system – a cosmic, glassmorphic aesthetic with smooth gradients and subtle depth.
<!-- A complete dashboard with almost no classes -->
<header class="nav-header">
<span>My App</span>
<nav>
<a href="/dashboard">Dashboard</a>
<a href="/settings">Settings</a>
</nav>
</header>
<main class="dashboard">
<div class="card">
<h3>Users</h3>
<span class="badge badge-success">+12%</span>
<p>12,543 active</p>
</div>
<div class="card">
<h3>Revenue</h3>
<p>$48,210</p>
</div>
<div class="card">
<h3>Orders</h3>
<p>1,893 this month</p>
</div>
</main>
When you need fine-grained control, QuantumCSS includes a finite static utility catalog (not a content-scan JIT). These are the exception, not the rule:
<!-- Override spacing on a specific element -->
<div class="card mt-8 text-center">...</div>
<!-- Custom grid layout -->
<div class="grid grid-cols-2 gap-4">...</div>
Utilities live in src/styles/quantum-utilities.css and ship inside dist/quantum.min.css. Prefer semantic component classes first.
Spacing, colors, typography, layout, and common responsive/hover variants used by the examples are pre-baked. Run npx quantumcss manifest for architecture notes, or browse quantum-utilities.css for the catalog.
All design tokens use the --q- prefix and can be overridden:
:root {
--q-color-starlight-blue: #00d4ff; /* accent color */
--q-color-starlight-peach: #ffb38a; /* secondary accent */
--q-bg-primary: #08081a; /* background */
}
The default theme is “Starlight” – a cosmic glassmorphic aesthetic with translucent surfaces, soft gradients, and depth-aware shadows. It ships with:
npx quantumcss init # Create theme-only quantum.config.json
npx quantumcss theme # Emit CSS variable overlay (theme-overlay.css)
npx quantumcss theme custom-theme.css # Custom overlay path
npx quantumcss scaffold blog index.html # Copy a starter template
npx quantumcss manifest design-system.json # Architecture notes for AI agents
The full library is static: npm run build concatenates the style layers into dist/quantum.min.css with no HTML scanning. Theme knobs only change CSS variables.
Working examples in the examples/ directory:
| Template | Description |
|---|---|
| portfolio.html | Landing page with timeline |
| blog.html | Blog layout |
| news.html | News portal |
| shopping.html | E-commerce store |
| admin-panel.html | Admin dashboard |
| analytics-dashboard.html | Analytics view |
| chat-messaging.html | Chat interface |
| email-client.html | Email inbox |
| music-streaming.html | Music player |
| video-streaming.html | Video platform |
| login.html | Sign-in / auth page |
| kitchen-sink.html | Full component reference |
will-change and hardware transformsFor AI-assisted UI generation, use the project skill:
SKILL.md — token-efficient markup rules, components, theming, and guardrailsLoad or paste SKILL.md into your agent system prompt. Prefer bare HTML → component classes → utilities.
We welcome contributions! Please see CONTRIBUTING.md for details.
QuantumCSS ships as static CSS. Install the package and link the built file — there is no PostCSS runtime and no HTML content scan.
<link rel="stylesheet" href="node_modules/@howssatoshi/quantumcss/dist/quantum.min.css">
Optional extras from the same package:
quantumcss theme / require('@howssatoshi/quantumcss/theme') — emit a small :root variable overlay from quantum.config.jsonquantumcss scaffold <template> — copy an example page and the CSS beside it@howssatoshi/quantumcss/starlight.js — theme / OS bootstrap helpersThe npm tarball intentionally excludes examples/ and the legacy JIT generator. Run npm run test:pack in this repo to verify the published surface.
MIT – see LICENSE.