css-is-awesome 1.11.1 → 1.12.1

package/AGENTS.md

@@ -308,9 +308,22 @@ Inside this package (all whitelisted in `files`):
 
 ## MCP server (SHIPPED — use it)
 
-cia ships a Model Context Protocol 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. It's in the `files` manifest, so it lands in every consumer's `node_modules`. **Prefer querying it over guessing** — it returns cia's real mixin signatures, tokens, themes, and recipes.
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`. It's in the `files` manifest, so it lands in every consumer's `node_modules`. **Prefer querying it over guessing** — it returns cia's real mixin signatures, tokens, themes, and recipes.
 
-Wire it into your MCP client's `.mcp.json`:
+Two ways to run it — prefer the dedicated `npx css-is-awesome-mcp` package (zero install, SDK is a real dependency, no separate peer-install step):
+
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "npx",
+      "args": ["css-is-awesome-mcp"]
+    }
+  }
+}
+```
+
+Or run this in-repo copy directly — needs its SDK peer deps installed manually first (`npm install -D @modelcontextprotocol/sdk zod` in the client project, since they're optional peers):
 
 ```json
 {
@@ -323,7 +336,7 @@ Wire it into your MCP client's `.mcp.json`:
 }
 ```
 
-The SDK is an optional peer dep — `npm install -D @modelcontextprotocol/sdk zod` in the client project to run it. It exposes **30 tools** across 8 families:
+Either way it exposes **30 tools** across 8 families:
 
 - **Themes** — `list_themes`, `get_theme`, `search_themes`
 - **Mixins** — `list_mixins`, `get_mixin`, `search_mixins` (real signatures — don't guess)

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## [1.12.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.12.0...v1.12.1) (2026-09-11)
+
+
+### Bug Fixes
+
+* **mcp:** remove colliding css-is-awesome-mcp bin entry, point docs at the new package ([f2ac41c](https://github.com/Jerry2d3d/css-is-awesome/commit/f2ac41c4d6056a1d13c19c5dcb48386acfb0fcda))
+
+# [1.12.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.11.1...v1.12.0) (2026-09-11)
+
+
+### Bug Fixes
+
+* **a11y:** unlabeled checklist checkboxes and non-focusable code blocks ([d98a92c](https://github.com/Jerry2d3d/css-is-awesome/commit/d98a92c549a2b74c3cff976d0fdfd61031162585))
+* **ci:** raise utilities size budget to 5.0 KB, correct stale bundle-size docs ([0e447f1](https://github.com/Jerry2d3d/css-is-awesome/commit/0e447f16e33d5a39cbcedb3b44caab79e4920f23))
+* **theme-editor:** density slider + fix override specificity bug affecting every row ([3977043](https://github.com/Jerry2d3d/css-is-awesome/commit/39770434e5f1819b57c16e502de15e252c5cf0d5))
+* **theme:** recurse into at-rules when bundling themes ([ca6397b](https://github.com/Jerry2d3d/css-is-awesome/commit/ca6397bcdcbcfc6bcb784253855b0af74d94ae74))
+
+
+### Features
+
+* **cli:** npx cia migrate chakra — Chakra UI theme object -> cia theme.scss ([2bcc95c](https://github.com/Jerry2d3d/css-is-awesome/commit/2bcc95c32058b2b1f60378e6718b772363fd77a2))
+* **cli:** npx cia migrate mui — MUI theme object -> cia theme.scss ([4f1d682](https://github.com/Jerry2d3d/css-is-awesome/commit/4f1d6828fc13fa1929f78127ab7c94503f55afb0))
+* **cli:** off-scale-length and missing-focus-visible analyzer rules ([d7bb8d9](https://github.com/Jerry2d3d/css-is-awesome/commit/d7bb8d96598b9897f130a152ad024ccc13a0cbbb))
+* **editor:** print preview persists per theme and seeds from overrides ([404e494](https://github.com/Jerry2d3d/css-is-awesome/commit/404e494051b9d3893c8ab18762da8044a389f5fd))
+* **editor:** token-consumer map, used-by list, live contrast readout ([a52f74e](https://github.com/Jerry2d3d/css-is-awesome/commit/a52f74e968f340d1c9f6b2ed8a02b8f16457432b))
+* **recipes:** admin-dashboard-layout recipe + live demo ([6e79812](https://github.com/Jerry2d3d/css-is-awesome/commit/6e79812980abbd90391507bd06db06b65820c1e2))
+* **recipes:** app-shell recipe - navbar + control panel + footer + modal ([a5abd6e](https://github.com/Jerry2d3d/css-is-awesome/commit/a5abd6e68287a1d99978e8956d601c170cbff657))
+* **recipes:** auth-flow recipe + live demo ([7e566e2](https://github.com/Jerry2d3d/css-is-awesome/commit/7e566e274fd84be8eab0ae877e3c222a1adc8c1e))
+* **recipes:** confirm-dialog recipe + live demo ([24977c2](https://github.com/Jerry2d3d/css-is-awesome/commit/24977c2214efc5588d90c601da70c2db1ed3b1f5))
+* **recipes:** data-table recipe + live demo ([cbcdbb3](https://github.com/Jerry2d3d/css-is-awesome/commit/cbcdbb384f2d44f25071d593391d0cb4a6bd5d0d))
+* **recipes:** datepicker recipe + live demo ([90ea515](https://github.com/Jerry2d3d/css-is-awesome/commit/90ea515f8c2ab044a4957be642295d188cf60cb3))
+* **recipes:** form validation recipes + live demos ([78ae02d](https://github.com/Jerry2d3d/css-is-awesome/commit/78ae02d4c29458d60feb90f0135faaedd7684b26))
+* **recipes:** i18n-date-formatting recipe + live demo ([689152a](https://github.com/Jerry2d3d/css-is-awesome/commit/689152a4ebb55b5c19285bfcd6f4c81f1a090b1d))
+* **recipes:** i18n-number-currency recipe + live demo ([a4ec9a3](https://github.com/Jerry2d3d/css-is-awesome/commit/a4ec9a35b80d9a4d6fb8f5333107694ef9e5ccf3))
+* **recipes:** i18n-pluralization recipe + live demo ([fe6a3f0](https://github.com/Jerry2d3d/css-is-awesome/commit/fe6a3f0272de3d848b5306800e3ecbca84d09e1c))
+* **recipes:** multi-step-wizard recipe + live demo ([932358e](https://github.com/Jerry2d3d/css-is-awesome/commit/932358e54d0550ecf7017d48266f833646634d58))
+* **recipes:** otp-input recipe + live demo ([af99b86](https://github.com/Jerry2d3d/css-is-awesome/commit/af99b86ab08f8357e908bd19533ea3bd55eab548))
+* **rtl:** audit + fix non-logical CSS, add a logical utility set ([35704fd](https://github.com/Jerry2d3d/css-is-awesome/commit/35704fda8941c56eea16070813845d15295f897f))
+* **rtl:** recipe + /docs/rtl live demo ([b18bc04](https://github.com/Jerry2d3d/css-is-awesome/commit/b18bc04910b9db02c0091ccaa4e93ab551d13326))
+* **themes:** --space-unit density knob — one var drives all 9 spacing steps ([a1638c7](https://github.com/Jerry2d3d/css-is-awesome/commit/a1638c72338309055f752e6940220a9a8cd6be99))
+
 ## [1.11.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.11.0...v1.11.1) (2026-09-09)
 
 

package/CONTRACT.md

@@ -305,6 +305,21 @@ Paper themes declare these as `none` / `transparent` so a swap to a glass or pho
 
 ---
 
+## Print (optional)
+
+Four tokens describing the printed page. They're **optional** — `cia.print-base` (included once, at the stylesheet root) emits every one of them on `:root` inside `@media print` with a clean ink-on-white default, and every print rule reads them via `var(--print-*)`. A theme MAY override them in its own `@media print` block for a paper identity (Press does, for a newsprint look); a theme that sets none of them prints the plain default.
+
+| Token           | Type   | Default   | Purpose                              |
+| --------------- | ------ | --------- | ------------------------------------- |
+| `--print-ink`   | color  | `#000`    | Body text, links, code text on paper  |
+| `--print-paper` | color  | `#fff`    | Backgrounds on paper                  |
+| `--print-line`  | color  | `#999`    | Borders, rules, hairlines on paper    |
+| `--print-muted` | color  | `#666`    | Printed URLs, captions, secondary text |
+
+`print-base` also rebinds the theme's own colour tokens (`--ink`, `--surface-*`, `--border-*`, `--code-*`) onto this palette inside `@media print`, so every theme — dark-only ones included — prints legible ink-on-paper with no per-theme work required. See [`/docs/print`](https://cssisawesome.com/docs/print) and the [`letterhead` recipe](./scss/recipes/letterhead.md).
+
+---
+
 ## Component overrides (optional)
 
 These are per-component tokens a theme MAY override to change how a single family of components renders (buttons, cards, inputs, etc.) without touching the library or rebuilding SCSS. They are **optional** — the library emits every one of them on `:root` with a sensible default, and every component mixin reads them via `var(--<key>, <library-default>)`. A theme that sets none of them renders exactly the same as today.

package/README.md

@@ -8,7 +8,7 @@
 
 **Docs:** [cssisawesome.com](https://cssisawesome.com/) · **Install:** `npm install css-is-awesome`
 
-> **The recipes book:** build any component in any framework using cia mixins — seven recipes today (`dialog`, `combobox`, `print-to-pdf`, `print-spec`, `letterhead`, `mobile-nav`, `bottom-nav`), with `datepicker`, `data-table` and `command-palette` queued. AI agents read recipes via MCP and generate components in your stack; humans read them at [`/docs/recipes`](https://cssisawesome.com/docs/recipes/).
+> **The recipes book:** build any component in any framework using cia mixins — 16 recipes today, including `dialog`, `combobox`, `datepicker`, `data-table`, `app-shell`, five form-validation patterns (HTML5, react-hook-form, Zod, async, success-states), `rtl-layout`, `print-to-pdf`, `print-spec`, `letterhead`, `mobile-nav` and `bottom-nav` — with `command-palette` and five more (`confirm-dialog`, `auth-flow`, `multi-step-wizard`, `otp-input`, `admin-dashboard-layout`) queued. AI agents read recipes via MCP and generate components in your stack; humans read them at [`/docs/recipes`](https://cssisawesome.com/docs/recipes/).
 
 ## For AI agents — start here
 
@@ -31,7 +31,7 @@ npm install -D @modelcontextprotocol/sdk zod   # required — npm will NOT insta
 }
 ```
 
-The SDK and `zod` are declared as *optional* peer dependencies, so a plain `npm install css-is-awesome` skips them and the server exits with `@modelcontextprotocol/sdk is not installed`. Install both. `npx css-is-awesome-mcp` does **not** work around this — npx fetches the package but not its optional peers.
+The SDK and `zod` are declared as *optional* peer dependencies, so a plain `npm install css-is-awesome` skips them and this in-repo copy exits with `@modelcontextprotocol/sdk is not installed`. Install both — or skip this entirely and run `npx css-is-awesome-mcp` instead, the dedicated zero-install package (see the MCP section below), which ships the SDK as a real dependency.
 
 Why it matters more here than for older frameworks: no model has memorised cia's API the way it has memorised Tailwind's class names. Without `llm.txt` or MCP, an agent will confidently invent a Tailwind-shaped API. With them, it reads the real thing. Details at [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
 
@@ -228,10 +228,11 @@ 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, off-contract tokens (typos),
-                            # hard-coded colors, BEM creep
+                            # off-scale lengths, hard-coded colors, BEM creep,
+                            # missing focus-visible styling
 ```
 
-`cia analyze` reads the real API surface from the installed package and exits non-zero on errors, so it slots straight into CI. It's deliberately low-noise about color: a hex used as a `var(--token, #hex)` fallback is token-driven (not flagged), and a literal inside `@media print` is an intentional paper colour (print escapes theme colours by design). Off-contract-token findings only fire on a **near-miss** of a real token — a typo like `--inkk` — never on your own custom tokens. The default output is a **graded report** — a health score, a section per concern (Contract / Spacing / Color / Naming / Layout / API) with a `✓` when clean, and a suggested fix on each finding; add `--verbose` for the flat per-file list or `--json` for the machine shape.
+`cia analyze` reads the real API surface from the installed package and exits non-zero on errors, so it slots straight into CI. It's deliberately low-noise about color: a hex used as a `var(--token, #hex)` fallback is token-driven (not flagged), and a literal inside `@media print` is an intentional paper colour (print escapes theme colours by design). Off-contract-token findings only fire on a **near-miss** of a real token — a typo like `--inkk` — never on your own custom tokens. Off-scale-length findings suggest the nearest named step (e.g. `--radius-md`) for a literal `border-radius`/`padding`/`margin`/`gap` value, as a hint toward using a token — never a claim about your active theme's exact pixel value, since themes are free to set their own numbers (Terminal sets every `--radius-*` to `0`, deliberately). The default output is a **graded report** — a health score, a section per concern (Contract / Spacing / Color / Naming / Layout / API / Accessibility) with a `✓` when clean, and a suggested fix on each finding; add `--verbose` for the flat per-file list or `--json` for the machine shape. Full rule reference: [`/docs/analyzer`](https://cssisawesome.com/docs/analyzer/).
 
 ## Print / PDF (zero JS)
 
@@ -297,30 +298,37 @@ The scope is kept narrow: 8 `!important` declarations, all inside `@media print`
 
 ## MCP server (for AI agents)
 
-cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) at [`mcp/server.cjs`](./mcp/server.cjs), exposed as the `css-is-awesome-mcp` bin. It's in the `files` manifest, so it lands in every consumer's `node_modules`. Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Exposes **30 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) and `resolve_size` (snap design px values to cia's 4px grid). Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **30 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) and `resolve_size` (snap design px values to cia's 4px grid). Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
 
-**Setup is two steps — do both, or the server won't start.**
+**Recommended — zero install:** use the dedicated [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package. It depends on `css-is-awesome` and resolves your installed version's real source, so it's never out of sync — and the MCP SDK ships as a real dependency, not an optional peer you have to remember to add.
 
-1. Install the SDK peer deps. The MCP SDK needs `@modelcontextprotocol/sdk` + `zod`; they're declared as *optional* peers so npm skips them by default. Without them the server exits and your MCP client shows only a generic "failed to connect":
-
-   ```bash
-   npm install -D @modelcontextprotocol/sdk zod
-   ```
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "npx",
+      "args": ["css-is-awesome-mcp"]
+    }
+  }
+}
+```
 
-2. Add to your client's `.mcp.json` (the `npx` form uses the shipped bin and is CWD-independent):
+**Alternative — the copy already in your `node_modules`:** cia's own `files` manifest ships [`mcp/server.cjs`](./mcp/server.cjs) too, for anyone who'd rather not add a second package. This copy needs its SDK peer deps installed manually first, since they're declared as *optional* peers (so a plain `npm install css-is-awesome` doesn't pull JS into a CSS-only install):
 
-   ```json
-   {
-     "mcpServers": {
-       "css-is-awesome": {
-         "command": "npx",
-         "args": ["css-is-awesome-mcp"]
-       }
-     }
-   }
-   ```
+```bash
+npm install -D @modelcontextprotocol/sdk zod
+```
 
-   Equivalent explicit path: `"command": "node", "args": ["node_modules/css-is-awesome/mcp/server.cjs"]`.
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "node",
+      "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
+    }
+  }
+}
+```
 
 ## Docs site
 
@@ -387,11 +395,11 @@ Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 
 | Bundle | Size | Use case |
 |---|---|---|
-| `dist/tokens.css` | 2.2 KB | Tokens only (`:where(:root)` CSS variables, no rules) — the purest mixin-first emit |
-| `dist/css-is-awesome.core.min.css` | 2.4 KB | Tokens + resets, no utilities or components |
-| `dist/css-is-awesome.utilities.min.css` | 4.1 KB | Every `cia-*` utility class, nothing else |
-| `dist/css-is-awesome.min.css` | 7.3 KB | Full bundle (everything) |
-| Per-theme `themes/<name>/theme.css` | 1.5–3.4 KB | One file per theme, both modes via `light-dark()`, drop-in with no markup change |
+| `dist/tokens.css` | 2.25 KB | Tokens only (`:where(:root)` CSS variables, no rules) — the purest mixin-first emit |
+| `dist/css-is-awesome.core.min.css` | 2.38 KB | Tokens + resets, no utilities or components |
+| `dist/css-is-awesome.utilities.min.css` | 4.75 KB | Every `cia-*` utility class, nothing else |
+| `dist/css-is-awesome.min.css` | 7.96 KB | Full bundle (everything) |
+| Per-theme `themes/<name>/theme.css` | 1.9–3.7 KB | One file per theme, both modes via `light-dark()`, drop-in with no markup change |
 | **JavaScript shipped in package** | **0 KB** | Zero. Period. JS-driven features ship as separate add-on packages. |
 
 ## Status

package/THEMING.md

@@ -163,6 +163,7 @@ those names were removed because nothing read them.)
 | `--z-*` | `hide`, `base`, `dropdown`, `sticky`, `fixed`, `backdrop`, `modal`, `popover`, `tooltip`, `toast` |
 | `--duration-*` | `instant`, `fast`, `normal`, `slow`, `slower` |
 | `--opacity-*` | `0` through `100` |
+| `--print-*` | `ink`, `paper`, `line`, `muted` — optional, override in your own `@media print` block to restyle paper (defaults to ink-on-white; see [`CONTRACT.md`](./CONTRACT.md#print-optional)) |
 
 ---
 

package/bin/README.md

@@ -6,19 +6,19 @@ 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 router — `migrate` (tailwind/bootstrap), `add` (recipe registry), `analyze` (design-system health) |
+| `cia` | `./cia.cjs` | The CLI router — `migrate` (tailwind/bootstrap/mui/chakra), `add` (recipe registry), `analyze` (design-system health) |
 
-Invoke either via `npx` from a consumer project that has cia installed:
+Invoke via `npx` from a consumer project that has cia installed:
 
 ```bash
-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
 ```
 
+**MCP server is NOT registered here** — `../mcp/server.cjs` ships in the `files` manifest but deliberately has no `bin` entry. It used to (`css-is-awesome-mcp`), but that collided with the separate [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package's own identically-named bin: since that package depends on `css-is-awesome`, npm links both packages' bins into the same `node_modules/.bin/`, and whichever wins is undefined — in practice it silently ran this repo's copy instead of the dedicated package's. Removed here so there's exactly one owner of that command name. Run this in-repo copy directly via `node mcp/server.cjs` (see the README's MCP section for both invocation paths).
+
 ## Subcommand files
 
 `cia.cjs` is the router. Each subcommand lives in its own sibling file and is loaded lazily so consumers who only use one path don't pay the require cost of the others.

package/bin/analyze.cjs

@@ -54,6 +54,10 @@ Usage:
 Scans [path] (default: current directory) for *.scss files and audits
 them against the installed css-is-awesome API.
 
+Rules: unknown-symbol, space-scale, off-contract-token, off-scale-length,
+hard-coded-color, bem, hand-written-areas, missing-focus-visible.
+Full reference: https://cssisawesome.com/docs/analyzer
+
 Options:
   --namespace <ns>   Extra namespace(s) to treat as cia (comma-separated).
                      Auto-detected per file from @use lines; use this when
@@ -173,6 +177,85 @@ function stripPrintBlocks(src) {
   return out;
 }
 
+// Reference-scale hints for the off-scale-length rule. Sourced from Sketchbook
+// (public/themes/sketchbook/theme.css) — CONTRACT.md's own designated
+// "reference implementation." These are HINTS, not a value guarantee: real
+// themes intentionally diverge (Terminal flattens every --radius-* to 0), so
+// a suggestion names the nearest named STEP, never asserts the consumer's
+// active theme actually holds this exact pixel value.
+const SCALE_HINTS = [
+  { token: '--radius-sm', px: 2 },
+  { token: '--radius-md', px: 3 },
+  { token: '--radius-lg', px: 6 },
+  { token: '--radius-xl', px: 12 },
+  { token: '--radius-full', px: 9999 },
+  { token: '--space-1', px: 8 },
+  { token: '--space-2', px: 12 },
+  { token: '--space-3', px: 14 },
+  { token: '--space-4', px: 16 },
+  { token: '--space-5', px: 24 },
+  { token: '--space-6', px: 32 },
+  { token: '--space-7', px: 48 },
+  { token: '--space-8', px: 64 },
+  { token: '--space-9', px: 96 },
+];
+const LENGTH_PROP_RE = /(?:^|[{;\s])(border-radius|padding|margin|gap)\s*:\s*([^;{}]+);/g;
+
+// "7px" / "0.75rem" -> px, or null if not a plain single-value length
+// (percentages, calc(), keywords like "auto" are left alone — out of scope).
+function parseLengthPx(raw) {
+  const m = /^(-?\d*\.?\d+)(px|rem)$/.exec(raw.trim());
+  if (!m) return null;
+  return m[2] === 'rem' ? parseFloat(m[1]) * 16 : parseFloat(m[1]);
+}
+
+// off-scale-length: a literal border-radius/padding/margin/gap value that's
+// close to a scale step — almost certainly meant to be that token. Values
+// already routed through var() (with or without a literal fallback) were
+// stripped by the caller, so only genuine literals reach here. `0` is never
+// flagged: it's unambiguous and a legitimate theme choice in its own right
+// (Terminal sets every --radius-* to 0) — flagging it would be a guaranteed
+// false positive for exactly that theme's consumers.
+function offScaleLength(varStrippedSrc) {
+  const findings = [];
+  for (const m of varStrippedSrc.matchAll(LENGTH_PROP_RE)) {
+    const prop = m[1];
+    for (const tok of m[2].trim().split(/\s+/)) {
+      if (tok === '0' || tok === '0px' || tok === '0rem') continue;
+      const px = parseLengthPx(tok);
+      if (px == null || px === 0) continue;
+      let best = null;
+      let bestDiff = Infinity;
+      for (const hint of SCALE_HINTS) {
+        const diff = Math.abs(hint.px - px);
+        if (diff < bestDiff) { bestDiff = diff; best = hint; }
+      }
+      if (best && bestDiff > 0 && bestDiff <= 2) {
+        findings.push({ level: 'warn', rule: 'off-scale-length', detail: `${prop}: ${tok} — close to the reference scale's ${best.token}; consider the token instead of a literal (exact px varies by theme)` });
+      }
+    }
+  }
+  return findings;
+}
+
+// missing-focus-visible: a file styles :hover/:active on something
+// button/link-shaped but never mentions :focus-visible or focus-ring
+// anywhere in the same file — keyboard users likely get no visible
+// feedback. File-level co-occurrence, not selector-pairing: SCSS commonly
+// nests hover/active under `&` while focus-ring is set once for the whole
+// component elsewhere in the file (see scss/components/_buttons.scss),
+// so per-selector adjacency would false-positive on that exact shape.
+const INTERACTIVE_SHAPE_RE = /(?:^|[^\w-])(?:button|a)(?:[.:#[\s{,]|$)|\[role\s*=\s*["']?button["']?\]|\.[\w-]*btn[\w-]*/i;
+const HOVER_ACTIVE_RE = /:(?:hover|active)\b/;
+const FOCUS_VISIBLE_RE = /:focus-visible\b|focus-ring/i;
+
+function missingFocusVisible(strippedSrc) {
+  if (!HOVER_ACTIVE_RE.test(strippedSrc)) return [];
+  if (!INTERACTIVE_SHAPE_RE.test(strippedSrc)) return [];
+  if (FOCUS_VISIBLE_RE.test(strippedSrc)) return [];
+  return [{ level: 'info', rule: 'missing-focus-visible', detail: 'interactive :hover/:active styling with no :focus-visible or focus-ring anywhere in this file — keyboard users may get no visible feedback' }];
+}
+
 function analyzeFile(file, symbols, contractTokens, extraNs) {
   const raw = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
   const src = stripComments(raw);
@@ -222,6 +305,8 @@ function analyzeFile(file, symbols, contractTokens, extraNs) {
   for (const m of stripVarExpr(stripPrintBlocks(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(--...))` });
   }
+  findings.push(...offScaleLength(stripVarExpr(src)));
+  findings.push(...missingFocusVisible(src));
   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` });
   }
@@ -240,13 +325,15 @@ const RULE_CATEGORY = {
   'unknown-symbol': 'API',
   'space-scale': 'Spacing',
   'off-contract-token': 'Contract',
+  'off-scale-length': 'Spacing',
   'hard-coded-color': 'Color',
   bem: 'Naming',
   'hand-written-areas': 'Layout',
+  'missing-focus-visible': 'Accessibility',
 };
 // The categories with rules implemented today — shown ✓ when clean so a passing
 // audit reads as coverage, not silence.
-const IMPLEMENTED_CATEGORIES = ['API', 'Contract', 'Spacing', 'Color', 'Naming', 'Layout'];
+const IMPLEMENTED_CATEGORIES = ['API', 'Contract', 'Spacing', 'Color', 'Naming', 'Layout', 'Accessibility'];
 
 // Details are authored as "claim — suggested fix"; split so the graded report
 // can put the fix on its own `→` line.

package/bin/cia.cjs

@@ -5,9 +5,12 @@
  * Subcommand router. Each subcommand lives in its own file under bin/ and
  * exposes a `run(args)` async function.
  *
- * Status: both converters shipped (EPIC-03 migration on-ramp, 6/6).
+ * Status: 4 converters shipped (v1.0 EPIC-03 tailwind+bootstrap; v1.2
+ *   EPIC-05 mui+chakra).
  *   migrate tailwind  — parse tailwind.config.* + dump theme JSON
  *   migrate bootstrap — parse Bootstrap SCSS/CSS vars + dump theme JSON
+ *   migrate mui       — parse a MUI createTheme() result + dump theme JSON
+ *   migrate chakra    — parse a Chakra extendTheme() result + dump theme JSON
  *
  * cia core ships ZERO JavaScript in the `files` manifest. The CLI lives in
  * `bin/` which is explicitly allowed per the architecture lock — same path
@@ -27,7 +30,7 @@ Usage:
 
 Commands:
   migrate <tool> [path]   Convert another design system's config to a cia
-                          theme. Tools: tailwind | bootstrap.
+                          theme. Tools: tailwind | bootstrap | mui | chakra.
   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,
@@ -58,7 +61,18 @@ Tools:
              via Bootstrap convention.
              Run \`cia migrate bootstrap --help\` for full options.
 
-Common options (both tools):
+  mui        Read a MUI (Material UI v5+) theme module (createTheme({...})
+             result) and write a cia theme.scss. Maps palette.primary/
+             secondary/error/warning/info/success, text, background,
+             spacing, shape.borderRadius, typography.fontFamily.
+             Run \`cia migrate mui --help\` for full options.
+
+  chakra     Read a Chakra UI (v2) theme module (extendTheme({...})
+             result) and write a cia theme.scss. Maps colors, space,
+             radii, fonts, fontSizes.
+             Run \`cia migrate chakra --help\` for full options.
+
+Common options (all tools):
   --name <name>    Theme name. Default: migrated
   --out <path>     Custom output path. Default: ./cia-themes/<name>.scss
   --json           Skip the file write and dump JSON to stdout (pipe-safe).
@@ -66,7 +80,8 @@ Common options (both tools):
 Examples:
   cia migrate tailwind ./tailwind.config.js
   cia migrate bootstrap ./scss/_variables.scss --name acme
-  cia migrate bootstrap ./scss/_variables.scss --json | jq '.cia.report'
+  cia migrate mui ./src/theme.ts --name acme
+  cia migrate chakra ./src/theme.ts --json | jq '.cia.report'
 `;
 
 function fail(message, exit = 1) {
@@ -109,7 +124,17 @@ async function main() {
       await run(migrateArgs);
       return;
     }
-    fail(`unknown migrate tool '${tool}'. Available: tailwind, bootstrap.`);
+    if (tool === 'mui') {
+      const { run } = require('./migrate-mui.cjs');
+      await run(migrateArgs);
+      return;
+    }
+    if (tool === 'chakra') {
+      const { run } = require('./migrate-chakra.cjs');
+      await run(migrateArgs);
+      return;
+    }
+    fail(`unknown migrate tool '${tool}'. Available: tailwind, bootstrap, mui, chakra.`);
   }
 
   if (command === 'add') {