css-is-awesome 1.8.2 → 1.9.1

package/AGENTS.md

@@ -337,10 +337,14 @@ The SDK is an optional peer dep — `npm install -D @modelcontextprotocol/sdk zo
 
 ## Other tooling (shipped)
 
-- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. The migration
-  on-ramp is live: `npx cia migrate tailwind [path]` and `npx cia migrate bootstrap [path]`
-  parse another system's config and dump a cia theme. Run either with `--help` for
-  full options. (`cia init` / `cia add` remain post-1.0.)
+- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. Three verbs:
+  `npx cia migrate tailwind|bootstrap [path]` parses another system's config and
+  dumps a cia theme; `npx cia add <recipe>` (`--list` to browse) copies a recipe
+  from the book into the project — own the pattern; `npx cia analyze [path]`
+  audits a project's stylesheets against the installed API — dead `cia.*` symbols,
+  the `space()` 1–9 scale trap, hard-coded hex colors, BEM chains — with a health
+  score and CI-ready exit codes. Run any verb with `--help`. (`cia init` remains
+  planned.)
 - **JSON token export** — DTCG-format token list in `figma-tokens/`.
 - **`llm.txt`** — at the repo root and served from the docs site; single-fetch
   summary for any AI agent. Also readable over MCP via `read_llm_txt`.

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [1.9.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.9.0...v1.9.1) (2026-09-06)
+
+
+### Features
+
+* **site:** the blog becomes two tracks - engineering + CSS discoveries (EPIC-06) ([dc4319f](https://github.com/Jerry2d3d/css-is-awesome/commit/dc4319ff106b6885247a67c738752a79d7228022))
+
+# [1.9.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.8.2...v1.9.0) (2026-09-05)
+
+
+### Features
+
+* **cli:** cia add (recipe registry) + cia analyze (design-system health) ([194c253](https://github.com/Jerry2d3d/css-is-awesome/commit/194c253a35eec68c68e2f2ca7402fd4e72a4d6ad))
+* **site:** /docs/browser-support - the dated two-tier support matrix ([d2e4604](https://github.com/Jerry2d3d/css-is-awesome/commit/d2e4604c6a331b467bdcd71b30ba2b7f7fe90f68))
+
 ## [1.8.2](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.8.1...v1.8.2) (2026-09-05)
 
 

package/README.md

@@ -221,6 +221,17 @@ npx cia migrate bootstrap ./scss/_variables.scss
 
 Both accept `--help` for the full option list. Prose walkthroughs live at [`/docs/migration-tailwind`](https://cssisawesome.com/docs/migration-tailwind/) and [`/docs/migration-bootstrap`](https://cssisawesome.com/docs/migration-bootstrap/).
 
+The CLI also carries the registry and the health check:
+
+```bash
+npx cia add --list          # browse the recipe book
+npx cia add bottom-nav      # copy a recipe into your project — you own the pattern
+npx cia analyze src/styles  # design-system health: dead cia.* symbols, the
+                            # space() scale trap, hard-coded colors, BEM creep
+```
+
+`cia analyze` reads the real API surface from the installed package and exits non-zero on errors, so it slots straight into CI.
+
 ## Print / PDF (zero JS)
 
 Print support is a pure-CSS layer — the browser's native **Print → Save as PDF** is the generator, and cia ships no JavaScript for it:

package/bin/README.md

@@ -7,7 +7,7 @@ cia's CLI entry points. **These are the only JavaScript files cia ships** — th
 | Bin | File | What it does |
 |---|---|---|
 | `css-is-awesome-mcp` | `../mcp/server.cjs` | MCP stdio server for AI agents (themes, mixins, recipes, etc.) |
-| `cia` | `./cia.cjs` | The CLI — currently supports `migrate tailwind`; more subcommands planned |
+| `cia` | `./cia.cjs` | The CLI router — `migrate` (tailwind/bootstrap), `add` (recipe registry), `analyze` (design-system health) |
 
 Invoke either via `npx` from a consumer project that has cia installed:
 
@@ -15,6 +15,8 @@ Invoke either via `npx` from a consumer project that has cia installed:
 npx css-is-awesome-mcp        # MCP server (stdio; configure via .mcp.json)
 npx cia --help                # CLI help
 npx cia migrate tailwind ./tailwind.config.js
+npx cia add bottom-nav        # copy a recipe into the project — own the pattern
+npx cia analyze src/styles    # health check: dead symbols, space() trap, hex, BEM
 ```
 
 ## Subcommand files

package/bin/add-recipe.cjs

@@ -0,0 +1,94 @@
+/**
+ * cia add — copy a recipe from the installed package into the project.
+ *
+ * The recipes book ships inside the npm package (scss/recipes/*.md). This
+ * command copies one into the consumer's tree so they OWN the pattern —
+ * the registry model: own the generated code, don't import an opaque
+ * component. Markdown pattern recipes only; the opt-in SCSS recipes
+ * (e.g. bare-tags) are `@use`d, not copied.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RECIPES_DIR = path.join(__dirname, '..', 'scss', 'recipes');
+
+const HELP = `cia add — copy a recipe into your project
+
+Usage:
+  cia add <recipe> [options]
+  cia add --list
+
+Options:
+  --list           List available recipes.
+  --out <path>     Output path. Default: ./cia-recipes/<recipe>.md
+  --force          Overwrite if the target file exists.
+
+Examples:
+  cia add --list
+  cia add bottom-nav
+  cia add mobile-nav --out docs/patterns/mobile-nav.md
+`;
+
+function fail(message) {
+  process.stderr.write(`cia add: ${message}\n`);
+  process.exit(1);
+}
+
+function listRecipes() {
+  return fs
+    .readdirSync(RECIPES_DIR)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('_') && f !== 'README.md')
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort();
+}
+
+function frontmatterDescription(raw) {
+  const m = raw.match(/^---[\s\S]*?\ndescription:\s*(.+?)\r?\n[\s\S]*?---/);
+  return m ? m[1].trim() : '';
+}
+
+async function run(args) {
+  if (!args.length || args[0] === '-h' || args[0] === '--help' || args[0] === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (args.includes('--list')) {
+    for (const slug of listRecipes()) {
+      const raw = fs.readFileSync(path.join(RECIPES_DIR, `${slug}.md`), 'utf8');
+      process.stdout.write(`${slug.padEnd(16)} ${frontmatterDescription(raw)}\n`);
+    }
+    return;
+  }
+
+  const slug = args[0];
+  const recipes = listRecipes();
+  if (!recipes.includes(slug)) {
+    fail(`unknown recipe '${slug}'. Available: ${recipes.join(', ')}.`);
+  }
+
+  const outFlag = args.indexOf('--out');
+  const outPath =
+    outFlag !== -1 && args[outFlag + 1]
+      ? path.resolve(args[outFlag + 1])
+      : path.resolve('cia-recipes', `${slug}.md`);
+
+  if (fs.existsSync(outPath) && !args.includes('--force')) {
+    fail(`${path.relative(process.cwd(), outPath)} already exists. Pass --force to overwrite.`);
+  }
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.copyFileSync(path.join(RECIPES_DIR, `${slug}.md`), outPath);
+
+  const rel = path.relative(process.cwd(), outPath);
+  process.stdout.write(
+    `✓ ${slug} → ${rel}\n\n` +
+      `The recipe is yours now — correct HTML, the cia mixin calls, and the\n` +
+      `a11y checklist. Read it, copy the pattern into your stack, keep the\n` +
+      `checklist. Docs: https://cssisawesome.com/docs/recipes/${slug}/\n`,
+  );
+}
+
+module.exports = { run };

package/bin/analyze.cjs

@@ -0,0 +1,191 @@
+/**
+ * cia analyze — design-system health check for a consumer project.
+ *
+ * Reads the REAL API surface from the installed package's SCSS sources
+ * (the same files the MCP server serves), then audits the project's
+ * stylesheets for:
+ *   - cia.* calls that don't resolve (dead symbols — typos, removals)
+ *   - the space() scale trap (numbered scale is 1–9; unknown keys pass
+ *     through raw and silently invalidate the declaration)
+ *   - hard-coded hex colors (values should come from tokens)
+ *   - BEM-style class names (__ / -- chains are forbidden in cia projects)
+ *   - hand-written grid-template-areas (the layout mixins own the maps)
+ *
+ * Zero dependencies, filesystem only — same philosophy as the MCP server.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_SCSS = path.join(__dirname, '..', 'scss');
+
+const HELP = `cia analyze — design-system health check
+
+Usage:
+  cia analyze [path] [options]
+
+Scans [path] (default: current directory) for *.scss files and audits
+them against the installed css-is-awesome API.
+
+Options:
+  --namespace <ns>   Extra namespace(s) to treat as cia (comma-separated).
+                     Auto-detected per file from @use lines; use this when
+                     imports are aliased through an intermediate file.
+  --json             Machine-readable report on stdout.
+  --strict           Exit 1 on warnings too (default: errors only).
+
+Examples:
+  cia analyze
+  cia analyze src/styles --json
+  cia analyze src --namespace m,l
+`;
+
+// ── API surface discovery ───────────────────────────────────────────────────
+
+function collectSymbols() {
+  const symbols = new Set();
+  const files = [];
+  const top = ['_mixins.scss', '_layout.scss', '_animations.scss', '_generator.scss'];
+  for (const f of top) files.push(path.join(PKG_SCSS, f));
+  const compDir = path.join(PKG_SCSS, 'components');
+  for (const f of fs.readdirSync(compDir)) {
+    if (f.endsWith('.scss')) files.push(path.join(compDir, f));
+  }
+  for (const file of files) {
+    let src = '';
+    try {
+      src = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const m of src.matchAll(/@(?:mixin|function)\s+([a-zA-Z][\w-]*)/g)) {
+      if (!m[1].startsWith('_')) symbols.add(m[1]);
+    }
+  }
+  // Icon mixins are forwarded with an icon- prefix by the /api barrel.
+  const icons = path.join(PKG_SCSS, '_icons.scss');
+  try {
+    const src = fs.readFileSync(icons, 'utf8');
+    for (const m of src.matchAll(/@(?:mixin|function)\s+([a-zA-Z][\w-]*)/g)) {
+      if (!m[1].startsWith('_')) symbols.add(`icon-${m[1]}`);
+    }
+  } catch {
+    /* icons module optional */
+  }
+  return symbols;
+}
+
+// ── project scan ────────────────────────────────────────────────────────────
+
+function walkScss(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkScss(full, out);
+    else if (entry.name.endsWith('.scss')) out.push(full);
+  }
+  return out;
+}
+
+const CIA_SOURCE = /^(?:css-is-awesome(?:\/|$)|pkg:css-is-awesome|api$|mixins$|layout$|animations$|generator$|icons$|components(?:\/|$))/;
+
+function detectNamespaces(src, extra) {
+  const ns = new Set(extra);
+  for (const m of src.matchAll(/@use\s+['"]([^'"]+)['"]\s+as\s+([a-zA-Z][\w-]*)/g)) {
+    if (CIA_SOURCE.test(m[1])) ns.add(m[2]);
+  }
+  // `@use 'css-is-awesome/api';` without `as` → namespace is the last segment.
+  for (const m of src.matchAll(/@use\s+['"]([^'"]+)['"]\s*;/g)) {
+    if (CIA_SOURCE.test(m[1])) ns.add(m[1].split('/').pop().replace(/\.scss$/, ''));
+  }
+  return ns;
+}
+
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+}
+
+function analyzeFile(file, symbols, extraNs) {
+  const raw = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+  const src = stripComments(raw);
+  const ns = detectNamespaces(src, extraNs);
+  const findings = [];
+  if (ns.size) {
+    const nsPattern = [...ns].map((n) => n.replace(/[-]/g, '\\-')).join('|');
+    const callRe = new RegExp(`\\b(?:${nsPattern})\\.([a-zA-Z][\\w-]*)`, 'g');
+    for (const m of src.matchAll(callRe)) {
+      const sym = m[1];
+      if (!symbols.has(sym)) {
+        findings.push({ level: 'error', rule: 'unknown-symbol', detail: `cia.${sym} does not exist in the installed API` });
+      }
+    }
+    // space() scale trap: numbered keys are 1–9; higher/fractional numbers
+    // pass through raw and silently invalidate the declaration.
+    const spaceRe = new RegExp(`\\b(?:${nsPattern})\\.space\\(\\s*(\\d+(?:\\.\\d+)?)\\s*\\)`, 'g');
+    for (const m of src.matchAll(spaceRe)) {
+      const n = Number(m[1]);
+      if (!Number.isInteger(n) || n > 9) {
+        findings.push({ level: 'error', rule: 'space-scale', detail: `space(${m[1]}) — the numbered scale is 1–9; this emits a unitless number and the browser drops the declaration. Use grid(n) for 4px multiples or pass an explicit unit.` });
+      }
+    }
+  }
+  for (const m of src.matchAll(/#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g)) {
+    findings.push({ level: 'warn', rule: 'hard-coded-color', detail: `${m[0]} — values should come from tokens (cia.color(...) / var(--...))` });
+  }
+  for (const m of src.matchAll(/\.[a-zA-Z][\w]*(?:__|--)[\w-]+/g)) {
+    findings.push({ level: 'warn', rule: 'bem', detail: `${m[0]} — BEM chains are forbidden; use semantic single-class names` });
+  }
+  if (/(?:^|[{;\s])grid-template-areas\s*:/m.test(src)) {
+    findings.push({ level: 'info', rule: 'hand-written-areas', detail: 'grid-template-areas written by hand — the layout mixins (page-layout / layout / area) own the maps' });
+  }
+  return { file, namespaces: [...ns], findings };
+}
+
+// ── report ──────────────────────────────────────────────────────────────────
+
+async function run(args) {
+  if (args[0] === '-h' || args[0] === '--help' || args[0] === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+  const json = args.includes('--json');
+  const strict = args.includes('--strict');
+  const nsFlag = args.indexOf('--namespace');
+  const extraNs = nsFlag !== -1 && args[nsFlag + 1] ? args[nsFlag + 1].split(',') : [];
+  const target = path.resolve(args.find((a) => !a.startsWith('--') && a !== extraNs.join(',')) || '.');
+
+  if (!fs.existsSync(target)) {
+    process.stderr.write(`cia analyze: path not found: ${target}\n`);
+    process.exit(1);
+  }
+
+  const symbols = collectSymbols();
+  const files = walkScss(target);
+  const results = files.map((f) => analyzeFile(f, symbols, extraNs)).filter((r) => r.findings.length || r.namespaces.length);
+
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const r of results) for (const f of r.findings) counts[f.level]++;
+  const ciaFiles = results.filter((r) => r.namespaces.length).length;
+  const health = Math.max(0, 100 - counts.error * 10 - counts.warn * 2 - counts.info);
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ target, files: files.length, ciaFiles, apiSymbols: symbols.size, counts, health, results }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`\ncia analyze — ${path.relative(process.cwd(), target) || '.'}\n`);
+    process.stdout.write(`${files.length} scss file(s), ${ciaFiles} using cia, ${symbols.size} API symbols known\n\n`);
+    for (const r of results) {
+      if (!r.findings.length) continue;
+      process.stdout.write(`${path.relative(process.cwd(), r.file)}\n`);
+      for (const f of r.findings) {
+        const mark = f.level === 'error' ? '✗' : f.level === 'warn' ? '⚠' : 'ℹ';
+        process.stdout.write(`  ${mark} [${f.rule}] ${f.detail}\n`);
+      }
+    }
+    process.stdout.write(`\nDesign-system health: ${health}%  (${counts.error} error, ${counts.warn} warn, ${counts.info} info)\n`);
+  }
+
+  if (counts.error > 0 || (strict && counts.warn > 0)) process.exit(1);
+}
+
+module.exports = { run };

package/bin/cia.cjs

@@ -27,11 +27,17 @@ Usage:
 
 Commands:
   migrate <tool> [path]   Convert another design system's config to a cia
-                          theme. Tools: tailwind | bootstrap (planned).
+                          theme. Tools: tailwind | bootstrap.
+  add <recipe>            Copy a recipe from the book into your project
+                          (own the pattern). \`cia add --list\` to browse.
+  analyze [path]          Design-system health check: dead cia.* symbols,
+                          the space() scale trap, hard-coded colors, BEM,
+                          hand-written area maps.
 
 Examples:
   cia migrate tailwind ./tailwind.config.js
-  cia migrate tailwind                       # auto-detect tailwind.config.*
+  cia add bottom-nav
+  cia analyze src/styles
 
 Run \`cia <command> --help\` for command-specific help.
 `;
@@ -106,6 +112,18 @@ async function main() {
     fail(`unknown migrate tool '${tool}'. Available: tailwind, bootstrap.`);
   }
 
+  if (command === 'add') {
+    const { run } = require('./add-recipe.cjs');
+    await run(rest);
+    return;
+  }
+
+  if (command === 'analyze') {
+    const { run } = require('./analyze.cjs');
+    await run(rest);
+    return;
+  }
+
   fail(`unknown command '${command}'. Run \`cia --help\` for usage.`);
 }
 

package/dist/tokens.d.ts

@@ -1,4 +1,4 @@
-// Generated from scripts/theme-contract.json on 2026-09-05.
+// Generated from scripts/theme-contract.json on 2026-09-06.
 // Do not edit by hand. Run `npm run build:token-types` to regenerate.
 
 /** Every CSS custom property cia themes are required to declare. */

package/llm.txt

@@ -48,6 +48,7 @@ silent.
 - **Mixins** — `cia.btn`, `cia.card`, `cia.accordion`, `cia.modal`, `cia.tooltip`, `cia.dropdown`, `cia.tabs`, `cia.copy-button`, `cia.hamburger`, `cia.drawer`, `cia.sheet`, `cia.dock`, `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]` — the mixin re-asserts the UA's closed state and restores `display: flex` only under `:popover-open`, so menus never render permanently open on popover markup), tabs (radio + `:has()`), copy-button (Clipboard API via consumer-wired JS).
+- **CLI** (`npx cia`) — `migrate tailwind|bootstrap` (config → cia theme), `add <recipe>` (copy a recipe from the book into the project), `analyze [path]` (audit stylesheets against the installed API: dead `cia.*` symbols, the `space()` 1–9 trap, hard-coded hex, BEM; health score, CI exit codes).
 - **Mobile navigation family** — `cia.hamburger` / `cia.drawer` / `cia.sheet` / `cia.dock` ride `[popover]` + CSS Grid, zero JS; recipes `mobile-nav` (hamburger + drawer) and `bottom-nav` (dock + sheets). House rule: **on phones things take the space they're in** — a `cia.dropdown` menu opens 1px under its full-width trigger at the trigger's exact width via CSS anchor positioning (`position-try-fallbacks: flip-block` flips it above at the screen bottom; set `width: auto` at `&[popover]` specificity or the UA's `[popover] { width: fit-content }` and the mixin's inset reset win). Full spec: AGENTS.md quick decision #8 and `/docs/mobile`.
 - **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.
@@ -101,6 +102,7 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 | Mixin reference (every public mixin) | `src/app/docs/mixins/page.tsx` |
 | Component examples | `src/app/docs/components/*/page.tsx` (6 components) |
 | Mobile playbook (layouts, dropdown doctrine, lessons) | `src/app/docs/mobile/page.tsx` |
+| Browser support matrix (Baseline floor + progressive tiers) | `src/app/docs/browser-support/page.tsx` |
 | 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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.8.2",
+  "version": "1.9.1",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {