quantumcss

QuantumCSS

Quantum CSS License Bundle Size

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.

Philosophy

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.

The three layers

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.

Token efficiency

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.

Architecture

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.

Quick Start

CDN (no build step)

<link rel="stylesheet" href="https://unpkg.com/@howssatoshi/quantumcss/dist/quantum.min.css">

npm

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

What You Get for Free

Every HTML element, styled

QuantumCSS resets and styles base elements so bare markup looks polished:

Automatic dark/light mode

QuantumCSS 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 } };

Dark pages with a starfield

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>

Responsive spacing

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.

Accessibility

Component Classes

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>

Utility Escape Hatch

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.

Available utilities

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.

Theming

CSS custom properties

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 */
}

Starlight design system

The default theme is “Starlight” – a cosmic glassmorphic aesthetic with translucent surfaces, soft gradients, and depth-aware shadows. It ships with:

CLI

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.

Demo Pages

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

Performance

AI agents

For AI-assisted UI generation, use the project skill:

Load or paste SKILL.md into your agent system prompt. Prefer bare HTML → component classes → utilities.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

For consumers

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:

The npm tarball intentionally excludes examples/ and the legacy JIT generator. Run npm run test:pack in this repo to verify the published surface.

License

MIT – see LICENSE.