css-is-awesome 1.1.0

package/figma-tokens/tokens.json

@@ -0,0 +1,144 @@
+{
+  "brand": {
+    "primary": { "value": "#3A5FCD", "type": "color" },
+    "primary-hover": { "value": "#2E4A99", "type": "color" },
+    "primary-active": { "value": "#1E3A8A", "type": "color" },
+    "secondary": { "value": "#FF6B6B", "type": "color" },
+    "secondary-hover": { "value": "#E85555", "type": "color" },
+    "secondary-active": { "value": "#CC5555", "type": "color" },
+    "accent": { "value": "#0099FF", "type": "color" },
+    "accent-hover": { "value": "#0088E6", "type": "color" }
+  },
+  "color-light": {
+    "background-default": { "value": "#FFFFFF", "type": "color" },
+    "background-subtle": { "value": "#F8F6F0", "type": "color" },
+    "background-navbar": { "value": "#FAFAFA", "type": "color" },
+    "surface-default": { "value": "#FFFFFF", "type": "color" },
+    "surface-subtle": { "value": "#F8F6F0", "type": "color" },
+    "surface-muted": { "value": "#F5F5F5", "type": "color" },
+    "surface-emphasis": { "value": "#E5E5E5", "type": "color" },
+    "text-primary": { "value": "#0F0F0F", "type": "color" },
+    "text-secondary": { "value": "#525252", "type": "color" },
+    "text-muted": { "value": "#6B6B6B", "type": "color" },
+    "text-inverse": { "value": "#FFFFFF", "type": "color" },
+    "text-link": { "value": "#384FFF", "type": "color" },
+    "text-link-hover": { "value": "#2A3ACC", "type": "color" },
+    "border-default": { "value": "#E5E5E5", "type": "color" },
+    "border-subtle": { "value": "#F5F5F5", "type": "color" },
+    "border-emphasis": { "value": "#D4D4D4", "type": "color" },
+    "border-focus": { "value": "#384FFF", "type": "color" },
+    "action-primary-default": { "value": "#3A5FCD", "type": "color" },
+    "action-primary-hover": { "value": "#2E4A99", "type": "color" },
+    "action-primary-active": { "value": "#1E3A8A", "type": "color" },
+    "action-secondary-default": { "value": "#FF6B6B", "type": "color" },
+    "action-secondary-hover": { "value": "#E85555", "type": "color" },
+    "action-secondary-active": { "value": "#CC5555", "type": "color" },
+    "success-default": { "value": "#10B981", "type": "color" },
+    "success-hover": { "value": "#059669", "type": "color" },
+    "success-subtle": { "value": "#ECFDF5", "type": "color" },
+    "success-text": { "value": "#065F46", "type": "color" },
+    "warning-default": { "value": "#F59E0B", "type": "color" },
+    "warning-hover": { "value": "#D97706", "type": "color" },
+    "warning-subtle": { "value": "#FFFBEB", "type": "color" },
+    "warning-text": { "value": "#92400E", "type": "color" },
+    "error-default": { "value": "#DC2626", "type": "color" },
+    "error-hover": { "value": "#B91C1C", "type": "color" },
+    "error-subtle": { "value": "#FEF2F2", "type": "color" },
+    "error-text": { "value": "#991B1B", "type": "color" },
+    "info-default": { "value": "#3A5FCD", "type": "color" },
+    "info-hover": { "value": "#2E4A99", "type": "color" },
+    "info-subtle": { "value": "#EFF6FF", "type": "color" },
+    "info-text": { "value": "#1E3A8A", "type": "color" }
+  },
+  "color-dark": {
+    "background-default": { "value": "#0A0A0A", "type": "color" },
+    "background-subtle": { "value": "#151515", "type": "color" },
+    "background-navbar": { "value": "#1A1A1A", "type": "color" },
+    "surface-default": { "value": "#151515", "type": "color" },
+    "surface-subtle": { "value": "#1F1F1F", "type": "color" },
+    "surface-muted": { "value": "#2A2A2A", "type": "color" },
+    "surface-emphasis": { "value": "#353535", "type": "color" },
+    "text-primary": { "value": "#FFFFFF", "type": "color" },
+    "text-secondary": { "value": "#B8B8B8", "type": "color" },
+    "text-muted": { "value": "#768194", "type": "color" },
+    "text-inverse": { "value": "#0A0A0A", "type": "color" },
+    "text-link": { "value": "#0099FF", "type": "color" },
+    "text-link-hover": { "value": "#5EBBFF", "type": "color" },
+    "border-default": { "value": "#2A2A2A", "type": "color" },
+    "border-subtle": { "value": "#1F1F1F", "type": "color" },
+    "border-emphasis": { "value": "#404040", "type": "color" },
+    "border-focus": { "value": "#0099FF", "type": "color" },
+    "action-primary-default": { "value": "#60A5FA", "type": "color" },
+    "action-primary-hover": { "value": "#3B82F6", "type": "color" },
+    "action-primary-active": { "value": "#2563EB", "type": "color" },
+    "action-secondary-default": { "value": "#F87171", "type": "color" },
+    "action-secondary-hover": { "value": "#EF4444", "type": "color" },
+    "action-secondary-active": { "value": "#DC2626", "type": "color" },
+    "success-default": { "value": "#34D399", "type": "color" },
+    "success-hover": { "value": "#10B981", "type": "color" },
+    "warning-default": { "value": "#FBBF24", "type": "color" },
+    "warning-hover": { "value": "#F59E0B", "type": "color" },
+    "error-default": { "value": "#F87171", "type": "color" },
+    "error-hover": { "value": "#EF4444", "type": "color" },
+    "info-default": { "value": "#60A5FA", "type": "color" },
+    "info-hover": { "value": "#3B82F6", "type": "color" }
+  },
+  "spacing": {
+    "0": { "value": "0", "type": "spacing" },
+    "2xs": { "value": "0.25rem", "type": "spacing" },
+    "xs": { "value": "0.5rem", "type": "spacing" },
+    "sm": { "value": "0.75rem", "type": "spacing" },
+    "md": { "value": "1rem", "type": "spacing" },
+    "lg": { "value": "1.5rem", "type": "spacing" },
+    "xl": { "value": "2rem", "type": "spacing" },
+    "2xl": { "value": "3rem", "type": "spacing" },
+    "3xl": { "value": "4rem", "type": "spacing" },
+    "4xl": { "value": "6rem", "type": "spacing" }
+  },
+  "font-size": {
+    "xs": { "value": "0.75rem", "type": "fontSizes" },
+    "sm": { "value": "0.875rem", "type": "fontSizes" },
+    "base": { "value": "1rem", "type": "fontSizes" },
+    "lg": { "value": "1.125rem", "type": "fontSizes" },
+    "xl": { "value": "1.25rem", "type": "fontSizes" },
+    "2xl": { "value": "1.5rem", "type": "fontSizes" },
+    "3xl": { "value": "1.875rem", "type": "fontSizes" },
+    "4xl": { "value": "2.25rem", "type": "fontSizes" },
+    "5xl": { "value": "3rem", "type": "fontSizes" },
+    "6xl": { "value": "3.75rem", "type": "fontSizes" }
+  },
+  "font-weight": {
+    "light": { "value": "300", "type": "fontWeights" },
+    "normal": { "value": "400", "type": "fontWeights" },
+    "medium": { "value": "500", "type": "fontWeights" },
+    "semibold": { "value": "600", "type": "fontWeights" },
+    "bold": { "value": "700", "type": "fontWeights" },
+    "black": { "value": "900", "type": "fontWeights" }
+  },
+  "line-height": {
+    "none": { "value": "1", "type": "lineHeights" },
+    "tight": { "value": "1.25", "type": "lineHeights" },
+    "snug": { "value": "1.375", "type": "lineHeights" },
+    "normal": { "value": "1.5", "type": "lineHeights" },
+    "relaxed": { "value": "1.625", "type": "lineHeights" },
+    "loose": { "value": "2", "type": "lineHeights" }
+  },
+  "border-radius": {
+    "none": { "value": "0", "type": "borderRadius" },
+    "sm": { "value": "0.25rem", "type": "borderRadius" },
+    "md": { "value": "0.375rem", "type": "borderRadius" },
+    "lg": { "value": "0.5rem", "type": "borderRadius" },
+    "xl": { "value": "0.75rem", "type": "borderRadius" },
+    "2xl": { "value": "1rem", "type": "borderRadius" },
+    "full": { "value": "9999px", "type": "borderRadius" }
+  },
+  "shadow": {
+    "sm": { "value": "0 1px 2px 0 rgb(0 0 0 / 0.05)", "type": "boxShadow" },
+    "md": { "value": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)", "type": "boxShadow" },
+    "lg": { "value": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)", "type": "boxShadow" },
+    "xl": { "value": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)", "type": "boxShadow" },
+    "2xl": { "value": "0 25px 50px -12px rgb(0 0 0 / 0.25)", "type": "boxShadow" },
+    "inner": { "value": "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)", "type": "boxShadow" },
+    "none": { "value": "none", "type": "boxShadow" }
+  }
+}

package/llm.txt

@@ -0,0 +1,183 @@
+# css-is-awesome — single-fetch summary for AI agents
+
+> If you're an AI agent (Claude Code, Cursor, Copilot, Aider, Gemini, etc.)
+> working with or installing css-is-awesome, this file is your entry point.
+> One read, then dispatch to the deeper docs by filename.
+
+## What cia is
+
+A token-driven SCSS design system. **Mixin-first** (since v0.8) — the mixin
+is the API, the class/tag/selector is the consumer's choice. The npm package
+ships **zero JavaScript** by hard rule.
+
+## How consumers install it (the primary path)
+
+```bash
+npm install css-is-awesome
+npm install -D sass
+```
+
+```scss
+// in a component stylesheet (or their app.scss) — mixins only, emits no :root
+@use 'css-is-awesome/api' as cia;
+
+.checkout-cta { @include cia.btn(primary); }
+.faq-item     { @include cia.accordion; }
+.modal        { @include cia.modal; }
+```
+
+```html
+<!-- in their HTML. NO data-theme attribute is needed for a single theme file. -->
+<link rel="stylesheet" href="/cia/themes/boilerplate/theme.css">
+```
+
+**Selector model — get this right, it is the most common thing agents get wrong.**
+Every theme emits `:root, :root[data-theme="<name>"]`. The bare `:root` means one
+theme file dropped in as `theme.css` restyles the page with NO markup change.
+`<html data-theme="name">` is **optional** for a single theme file, and **required
+only** for the multi-theme bundle (`public/theme.css`), which carries all 24
+themes and strips the bare `:root` so they do not collide. Do NOT tell a consumer
+they must set an attribute matching their theme file — if they swap the file and
+forget, older cia rendered a page with no tokens at all, and that failure was
+silent.
+
+**Two-import model.** `css-is-awesome/api` is a zero-emit authoring barrel — import it in each component/`.module.scss` and only call mixins; emit the tokens once from the root/global stylesheet (`@use 'css-is-awesome';` or a `<link>`ed theme file). **Next.js / Turbopack:** the barrel WORKS under Turbopack — the showcase app runs Next 16 on Turbopack for dev and build with `css-is-awesome/scss/api` in all 116 stylesheets. Do not steer consumers to the leaf module; `scss/mixins` lacks `btn`, `card-base`, `stack`, `grid` and `animate`. Two setup notes: Sass ignores package.json `exports`, so add `node_modules` to `sassOptions.loadPaths`; and if you hit `Two forwarded modules both define a mixin named stack`, drop your own styles dir from `loadPaths`. That was ONE consumer report and is NOT reproducible in standard Sass — cia's internal forwards are `./`-relative, which Sass resolves without consulting load paths (asserted by validate-package). Treat it as a bundler-resolver deviation, not a Sass rule.
+
+## What cia provides (one-line each)
+
+- **Mixins** — `cia.btn`, `cia.card`, `cia.accordion`, `cia.modal`, `cia.tooltip`, `cia.dropdown`, `cia.tabs`, `cia.copy-button`, `cia.stepper`, `cia.progress`, `cia.wizard-shell`, `cia.sidebar`, `cia.toolbar`, `cia.stack`, `cia.cluster`, `cia.switcher`, `cia.cover`, `cia.frame`, `cia.media`, `cia.contain`, `cia.focus-ring`, `cia.sr-only`, `cia.print`, `cia.print-base`, `cia.print-hidden`, `cia.print-only`, `cia.color`, `cia.space`, `cia.radius`, `cia.shadow`, `cia.font`, `cia.transition`, `cia.animate`, plus many more.
+- **24 themes / 8 families** — boilerplate, sketchbook, press, prism, cupertino, glass, graphite, terminal. Each family ships three files: an unsuffixed dual-mode base (both modes via `light-dark()`) plus pinned `-light` and `-dark` single-mode variants for `<link media>` pairing. Every one has exactly one SCSS source under `scss/themes/`; `public/themes/<name>/theme.css` is BUILD OUTPUT and is gated against its source by `npm run check:theme-drift` — never hand-edit it. MCP `list_themes` returns **24**. Say **24 themes across 8 families** when you need one number.
+- **6 zero-JS interactive components** — accordion (`<details name>`), modal (`<dialog>`), tooltip (`popover="hint"`), dropdown (`[popover]`), tabs (radio + `:has()`), copy-button (Clipboard API via consumer-wired JS).
+- **163 contract tokens — 127 required + 36 optional** — surfaces, ink, lines, colors, type, radius, shadow, blur, glow, motion, z-index, spacing, semantic aliases.
+- **Spacing is themeable, and the numbered scale is the knob.** Themes declare `--space-0` … `--space-9` (contract-required). The t-shirt names (`--space-md`, `--space-lg` …) are contract-OPTIONAL and emitted by the library as `var()` aliases onto the numbered steps. `space(4)` compiles to `var(--space-4)`, so **theme the numbered step, never the alias** — setting `--space-md` alone leaves every component untouched. Library defaults emit under `:where(:root)` (specificity 0,0,0) so any theme declaration outranks them regardless of load order.
+- **Per-component shape knobs are `--btn-radius`, `--card-radius`, `--input-radius`, `--modal-radius`, `--badge-radius`, `--tag-radius`** — they cascade from the generic radii (`--btn-radius: var(--radius-md, 0.25rem)`). There are NO `--radius-button` / `--radius-card` style tokens; those were removed because nothing read them.
+- **Icons — two systems.** `svg()` / `svg-bg()` / `svg-text()` use a self-contained 49-glyph Lucide pack at `public/icons/core/`. Adding a glyph is drop-in: put `star.svg` in the folder and `cia.icon-svg(star)` works, no registration. Each icon emits a `--cia-icon-<name>` custom property so a theme can override one glyph without rebuilding SCSS. **`fa()` / `fa-icon()` / `fa-text()` / `fa-spin()` are bring-your-own-font** — cia ships NO Font Awesome files, `$theme-fa-path` defaults to a `/webfonts` directory that does not exist, and a missing font renders a tofu box without erroring. Default to `svg()` unless the user says they use Font Awesome.
+
+## Hard rules (do not violate)
+
+1. **No JavaScript in the cia npm package.** Zero `.js`/`.mjs` files ship. JS-augmented features (CopyButton handler, future force-mode) ship as separate add-on packages. **This binds the package, not the consumer:** apps built ON cia should write JS/framework components freely (React, SVG charts, interactivity) and use cia only for styling — mixins + tokens. Don't over-apply "zero-JS" to your own app code.
+2. **No `@layer`.** Tier 3 bare-tags use `:where()` (specificity 0,0,0). Cascade pollution kills the consumer experience. Corollary: **the `!important` in the print mixins is load-bearing — do not remove it.** `@media` contributes no specificity, so `print-hidden` only carries the specificity of the selector it is included in, and a later equal-specificity `display` wins in print. `@layer` would make this worse, not better: layered CSS always loses to unlayered CSS, so a layered print rule loses to any unlayered consumer stylesheet. Scope is 8 declarations, all inside `@media print`, all variable-driven (`--print-hide` / `--print-show`).
+3. **No BEM.** No `__element` / `--modifier` chains in cia source. Consumers pick their own selector names — cia has no opinion.
+4. **No Storybook.** Docs site + the `css-is-awesome-mcp` server cover both human and AI audiences.
+5. **One theme = one file.** Both light + dark inside via `light-dark()`.
+6. **`cia-` prefix is library-owned.** Consumer classes use their own naming.
+
+## Themes are open — consumers CAN edit and create their own
+
+This is the most-missed piece. **Consumers CAN:**
+
+1. **Edit any shipped theme** — open `scss/themes/<name>.scss`, change tokens, `npm run build:css:themes`. Done.
+2. **Make a brand-new theme** — copy any theme as starting point, rename, edit, build, validate.
+3. **Override tokens at consumer level** — `:root[data-theme="boilerplate"] { --action-primary-default: #ff0066; }` in their own SCSS. No fork needed.
+
+```scss
+// new theme template (a global stylesheet — emits :root)
+@use 'css-is-awesome/api' as cia;
+@include cia.theme('mybrand') {
+  --background-default: light-dark(#fff, #0a0a0e);
+  --action-primary-default: light-dark(#3A5FCD, #60a5fa);
+  @include cia.states(action-primary);
+  /* + 120 more tokens — full list in scripts/theme-contract.json */
+}
+```
+
+The validator (`node scripts/theme-validator.js`) is the gate — 127 required tokens + WCAG 2.2 AA contrast across 22 audited pairs per theme. It accepts quoted AND unquoted `[data-theme=x]` selectors, and refuses to grade rather than fall back if it sees `data-theme` but parses no block.
+
+## Paired themes (two brand identities by mode)
+
+Native HTML, no cia API:
+```html
+<link rel="stylesheet" href="/themes/sketchbook.css" media="(prefers-color-scheme: light)">
+<link rel="stylesheet" href="/themes/terminal.css"   media="(prefers-color-scheme: dark)">
+```
+Newspaper by day, hacker terminal by night. Most design systems give you dark mode; cia lets you ship a second brand at night.
+
+## Where to read next (by intent)
+
+| If you need... | Read |
+|---|---|
+| Install steps + every consumption path | `README.md` |
+| Mixin reference (every public mixin) | `src/app/docs/mixins/page.tsx` |
+| Component examples | `src/app/docs/components/*/page.tsx` (6 components) |
+| Theme authoring (full walkthrough) | `src/app/docs/authoring/themes/page.tsx` |
+| Theme contract (127 required + 36 optional, machine-readable) | `scripts/theme-contract.json` |
+| Theme pairing (`<link media>` recipe) | `src/app/docs/themes/pairing/page.tsx` |
+| CopyButton JS recipe | `src/app/docs/recipes/copy-button/page.tsx` |
+| Anchor positioning recipe | `src/app/docs/recipes/anchor-positioning/page.tsx` |
+| Tabs ARIA shim recipe | `src/app/docs/recipes/tabs-aria/page.tsx` |
+| v0.7 → v0.8 migration | `MIGRATION.md` |
+| Full breaking-change history | `CHANGELOG.md` |
+| Deeper architecture rules | `AGENTS.md` |
+
+## Common AI agent traps
+
+- **Don't write BEM.** No `cia-card__title--large`.
+- **Don't hardcode breakpoints/colors/spacing.** Use `cia.media(md)`, `cia.color(primary)`, `cia.space(4)`.
+- **Don't suggest a JS dependency for components.** The native primitive does the work.
+- **Style semantic state off ARIA, not a parallel `data-*`.** `[aria-selected]`, `[aria-expanded]`, `[aria-invalid]`, `:disabled/[aria-disabled]`, `[aria-pressed]`, `[aria-checked]`, `[aria-current]`, `[role="tab"]` are the styling hooks for stateful components — accessible-by-construction (can't style the state without setting the ARIA a screen reader needs). Reserve `data-*` for cosmetic-only variants (`data-size`, `data-variant`).
+- **Don't assume utility classes are emitted by default in Sass.** They opt in via `@use cia with ($utilities: true)`.
+- **v0.8 rename traps:** `cia.bp` → `cia.media`, `cia.cq` → `cia.contain`, `cia.inset` → `cia.pad`, `cia.squish` → `cia.pad-asym`, `cia.font-load` → `cia.font-face`, `cia.color-raw` → `cia.color-static`, layout `cia.container` → `cia.wrap`. No aliases.
+- **v0.8 theme rename:** `data-theme="press-light"` → `data-theme="press"`. Both modes are inside the single theme file now.
+- **v0.8.1 progress rename:** `cia.progress-track` → `cia.progress-track-base`; `cia.progress-fill` → `cia.progress-fill-base`. New `cia.progress` composer wraps both via `[data-slot="fill"]` markup.
+- **v0.8.1 animations split:** When @use'ing animations from a `.module.scss`, use `scss/animations` (mixin-only, safe). The keyframes + utility classes + global safety net now live in `scss/animations-utilities` — load that once globally (via `main.scss` or your app's global SCSS).
+- **v0.8.1 file move:** `badge-base` / `badge` moved from `_feedback.scss` to `_data.scss`. Use the cia barrel (`@use 'css-is-awesome/api' as cia; cia.badge-base;`) instead of path-specific imports.
+
+## MCP server (shipped 2026-05-22)
+
+cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome` (version read from package.json), protocol `2024-11-05`) at `mcp/server.cjs`, exposed as the `css-is-awesome-mcp` bin and included in the `files` manifest — so it lands in every consumer's `node_modules`. **30 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 36 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling and `resolve_size` for snapping design px values to cia's 4px geometric grid (AI agents: call this whenever you receive a px value from a design tool). Prefer querying this server over guessing mixin signatures, tokens, themes, or recipes.
+
+Add to your MCP client's `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "node",
+      "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
+    }
+  }
+}
+```
+**Two dependencies are required and npm will NOT install them for you.** They are
+declared as OPTIONAL peer dependencies, so `npm install css-is-awesome` skips
+them silently and the server exits with:
+
+```
+css-is-awesome MCP server: @modelcontextprotocol/sdk is not installed.
+```
+
+Fix, in the client project:
+
+```bash
+npm install -D @modelcontextprotocol/sdk zod
+```
+
+Do NOT suggest `npx css-is-awesome-mcp` as a shortcut. `npx` fetches the package
+but not its optional peers, so it hits the same error. Run it from an install
+that has both, using the config above.
+
+## Recipes (v1.0 preview — landing in 1.0.0)
+
+cia v1.0 ships a **recipes book**: portable patterns for building accessible components in any framework. Each recipe is a markdown file at `scss/recipes/<name>.md` with:
+
+- raw HTML structure
+- `cia.X` mixin calls for styling
+- a11y checklist (WCAG 2.2 AA grade)
+- code samples in React + Vue + Svelte + vanilla
+
+AI agents read recipes via MCP `list_recipes` / `get_recipe(name)` and generate consumer components in any framework. Humans read them at `/docs/recipes` and copy patterns directly.
+
+**Shipped today: dialog, combobox, print-to-pdf.** Still queued for 1.0.0: datepicker, data-table, command-palette. **No component library** — recipes are the deliverable. See `roadmap/epics/v1-0/EPIC-01-recipes-book.md` for the schema + roadmap.
+
+## Priority ladder (the v1.0 pitch order)
+
+1. **Users first** — easy to learn, no framework lock-in, no maintenance treadmill
+2. **Tokens** — one source of truth, swap one value = whole app shifts
+3. **Theme editor on website** — visual customization for all 127 required tokens at `/themes`
+4. **Mixin-first speed** — `@include cia.btn(primary)` on any selector
+5. **AI second (huge bonus)** — recipes book + MCP make cia uniquely AI-composable
+
+Humans first. AI's role is to compose, not to lead the pitch.
+
+---
+
+*Generated 2026-05-21 for cia v0.8. Updated 2026-05-23 for the v1.0 architecture lock, and 2026-08-30 for the theme single-source rework (24 themes, 127+36 contract, themeable spacing, `:root, :root[data-theme]` selector). Update when the API surface changes.*