css-is-awesome 1.11.1 → 1.12.0

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+# [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
 
@@ -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)
 
@@ -387,11 +388,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/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') {

package/bin/migrate-chakra.cjs

@@ -0,0 +1,249 @@
+/**
+ * cia migrate chakra — parse a Chakra UI (v2) theme object + map to cia.
+ *
+ * v1.2 EPIC-05. Same shape as migrate-tailwind / migrate-bootstrap / migrate-mui.
+ * Chakra's theme object shape (colors as {shade: hex} palettes, a flat
+ * rem-keyed space/fontSizes scale, a named radii object) lines up closely
+ * enough with Tailwind's that most of this is direct reuse of the shared
+ * mapping engine, not new logic.
+ *
+ * Token-only: reads Chakra's theme VALUES. Never imports @chakra-ui/react,
+ * never translates Chakra React components — same scope boundary as the
+ * MUI migrator, for the same reason (cia has no component library to
+ * translate them to).
+ *
+ * Scoped to Chakra v2 theme shape (still dominant as of this writing); v3
+ * changed the theme shape significantly and isn't handled here.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Shared engine from the Tailwind module — no need to fork it. mapColors and
+// mapBorderRadius are reused UNMODIFIED: Chakra's {shade: hex} color-palette
+// shape and {name: length} radii shape are structurally identical to what
+// those functions already walk for Tailwind.
+const {
+  loadConfig,
+  writeThemeScss,
+  parseFlags,
+  mapColors,
+  mapFlatScale,
+  mapBorderRadius,
+  CIA_SPACING,
+  CIA_FONT_SIZES,
+} = require('./migrate-tailwind.cjs');
+
+// ─── theme object discovery ─────────────────────────────────────────────────
+
+// extendTheme({...}) already returns a fully-resolved plain object — no
+// Chakra import needed to read one.
+function findChakraTheme(mod) {
+  if (mod && typeof mod === 'object') {
+    if (mod.theme && (mod.theme.colors || mod.theme.space || mod.theme.fonts)) return mod.theme;
+    if (mod.default && (mod.default.colors || mod.default.space || mod.default.fonts)) return mod.default;
+    if (mod.colors || mod.space || mod.fonts) return mod;
+  }
+  return null;
+}
+
+// ─── font mapping (Chakra's heading/body key names don't match Tailwind's) ──
+
+function mapChakraFonts(fonts) {
+  const mappings = {};
+  if (!fonts || typeof fonts !== 'object') return mappings;
+  if (typeof fonts.heading === 'string') {
+    mappings['font-display'] = {
+      value: fonts.heading,
+      source: 'fonts.heading',
+      confidence: 'HIGH',
+      rationale: `Chakra 'fonts.heading' → cia 'font-display' (direct stack copy).`,
+    };
+  }
+  if (typeof fonts.body === 'string') {
+    mappings['font-sans'] = {
+      value: fonts.body,
+      source: 'fonts.body',
+      confidence: 'HIGH',
+      rationale: `Chakra 'fonts.body' → cia 'font-sans' (direct stack copy).`,
+    };
+  }
+  return mappings;
+}
+
+// ─── master mapping ─────────────────────────────────────────────────────────
+
+function mapChakraToCia(theme) {
+  const allMappings = {};
+  const allUnmapped = [];
+
+  const colors = mapColors(theme.colors);
+  Object.assign(allMappings, colors.mappings);
+  allUnmapped.push(...colors.unmapped);
+
+  const space = mapFlatScale(theme.space, CIA_SPACING, 'space', 'space');
+  Object.assign(allMappings, space.mappings);
+  allUnmapped.push(...space.unmapped);
+
+  const fontSizes = mapFlatScale(theme.fontSizes, CIA_FONT_SIZES, 'font-size', 'fontSizes');
+  Object.assign(allMappings, fontSizes.mappings);
+  allUnmapped.push(...fontSizes.unmapped);
+
+  const radii = mapBorderRadius(theme.radii);
+  Object.assign(allMappings, radii.mappings);
+  allUnmapped.push(...radii.unmapped);
+
+  Object.assign(allMappings, mapChakraFonts(theme.fonts));
+
+  // Deliberately not mapped — same disclosed scope cut as MUI's shadows:
+  // Chakra's shadow/breakpoint/zIndex scales don't have a clean 1:1 cia
+  // analog (cia's breakpoints and z-layers are a fixed system scale, not
+  // themed per-project — see scss/_system.scss).
+  if (theme.shadows && Object.keys(theme.shadows).length) {
+    allUnmapped.push({
+      source: 'shadows.*',
+      value: `${Object.keys(theme.shadows).length} shadow token(s)`,
+      reason: `No 1:1 cia analog (cia has 5 named steps: shadow-sm/md/lg/xl/2xl). Review and pick manually.`,
+    });
+  }
+  if (theme.breakpoints) {
+    allUnmapped.push({
+      source: 'breakpoints.*',
+      value: JSON.stringify(theme.breakpoints),
+      reason: `cia's breakpoints are a fixed system scale, not themed per-project — not migrated. Note for reference only.`,
+    });
+  }
+  if (theme.zIndices) {
+    allUnmapped.push({
+      source: 'zIndices.*',
+      value: JSON.stringify(theme.zIndices),
+      reason: `cia's z-layers are a fixed system scale (--z-dropdown/-modal/etc.), not themed per-project — not migrated. Note for reference only.`,
+    });
+  }
+
+  const counts = { HIGH: 0, MEDIUM: 0, LOW: 0, UNMAPPED: 0 };
+  for (const m of Object.values(allMappings)) {
+    if (counts[m.confidence] != null) counts[m.confidence] += 1;
+  }
+  counts.UNMAPPED = allUnmapped.length;
+  counts.total = counts.HIGH + counts.MEDIUM + counts.LOW + counts.UNMAPPED;
+
+  return { mappings: allMappings, unmapped: allUnmapped, report: counts };
+}
+
+// ─── CLI entry ────────────────────────────────────────────────────────────
+
+const HELP = `cia migrate chakra — convert a Chakra UI (v2) theme object to a cia theme.scss
+
+Usage:
+  cia migrate chakra <path> [options]
+
+Default behavior:
+  Loads a module exporting a Chakra theme (the result of extendTheme({...}),
+  as a default export, a named 'theme' export, or a plain theme-shaped
+  object), maps its colors/space/radii/fonts/fontSizes to cia contract
+  tokens with confidence scoring, and writes a cia theme.scss to
+  ./cia-themes/<name>.scss. Diagnostics print to stderr.
+
+  Token-only: never imports @chakra-ui/react, never translates Chakra React
+  components — only reads plain values off the theme object. Scoped to
+  Chakra v2 theme shape.
+
+Arguments:
+  path             Path to a .js/.ts/.mjs/.cjs module exporting a Chakra theme.
+
+Options:
+  --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).
+  -h, --help       Show this help.
+
+Examples:
+  cia migrate chakra ./src/theme.ts
+  cia migrate chakra ./src/theme.ts --name acme
+  cia migrate chakra ./src/theme.ts --json | jq '.cia.report'
+
+Notes:
+  - Chakra's 'colors' object uses the same {shade: hex} palette shape as
+    Tailwind's, so the color-mapping heuristics (a 'brand'/'primary'-named
+    scale, 'red'/'green'/'orange'/'blue' for status) apply unmodified.
+  - shadows / breakpoints / zIndices are not mapped automatically — see
+    the UNMAPPED block for why.
+`;
+
+async function run(args) {
+  const { flags, positional } = parseFlags(args);
+  if (flags.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  let themePath = positional[0];
+  if (!themePath) {
+    throw new Error(`cia migrate chakra requires a path to a module exporting a Chakra theme. Example: cia migrate chakra ./src/theme.ts`);
+  }
+  if (!path.isAbsolute(themePath)) themePath = path.resolve(process.cwd(), themePath);
+  if (!fs.existsSync(themePath)) throw new Error(`theme file not found: ${themePath}`);
+
+  process.stderr.write(`cia migrate chakra\n`);
+  process.stderr.write(`  theme: ${themePath}\n`);
+  process.stderr.write(`  loading...\n`);
+
+  const mod = loadConfig(themePath);
+  const theme = findChakraTheme(mod);
+  if (!theme) {
+    throw new Error(
+      `Could not find a Chakra theme in ${themePath}. Expected a default export, a named ` +
+        `'theme' export, or the module itself to be a theme-shaped object with a 'colors', ` +
+        `'space', or 'fonts' key (the result of extendTheme({...})).`,
+    );
+  }
+
+  process.stderr.write(`  found theme\n`);
+  process.stderr.write(`\n  mapping to cia contract tokens...\n`);
+  const cia = mapChakraToCia(theme);
+
+  process.stderr.write(`\n  ─── confidence report ─────────────────────────\n`);
+  process.stderr.write(`    HIGH     (exact match):     ${cia.report.HIGH}\n`);
+  process.stderr.write(`    MEDIUM   (close, ≤0.125rem): ${cia.report.MEDIUM}\n`);
+  process.stderr.write(`    LOW      (best guess):       ${cia.report.LOW}\n`);
+  process.stderr.write(`    UNMAPPED (no cia analog):    ${cia.report.UNMAPPED}\n`);
+  process.stderr.write(`    ─────────────────────────────────────────────\n`);
+  process.stderr.write(`    total                         ${cia.report.total}\n`);
+
+  if (flags.json) {
+    process.stderr.write(`\n  --- JSON dump on stdout below ---\n`);
+    process.stdout.write(JSON.stringify({ source: themePath, cia }, null, 2));
+    process.stdout.write('\n');
+    return;
+  }
+
+  const scss = writeThemeScss(cia, { name: flags.name, source: themePath, tool: 'chakra' });
+  let outPath = flags.out;
+  if (outPath) {
+    if (!path.isAbsolute(outPath)) outPath = path.resolve(process.cwd(), outPath);
+  } else {
+    outPath = path.join(process.cwd(), 'cia-themes', `${flags.name}.scss`);
+  }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, scss, 'utf8');
+
+  process.stderr.write(`\n  wrote ${outPath}\n`);
+  process.stderr.write(`  ${scss.split('\n').length - 1} lines, ${Object.keys(cia.mappings).length} mapped tokens\n`);
+  if (cia.report.UNMAPPED > 0) {
+    process.stderr.write(`  ${cia.report.UNMAPPED} unmapped/informational entries appended as a comment block — review\n`);
+  }
+  process.stderr.write(`\n  Next steps:\n`);
+  process.stderr.write(`    1. Review the file (MEDIUM/LOW/UNMAPPED entries are flagged)\n`);
+  process.stderr.write(`    2. @use this file from your app's SCSS entry\n`);
+  process.stderr.write(`    3. Set <html data-theme="${flags.name}"> and run npm run build:css\n`);
+  process.stderr.write(`    4. Run npm run validate-themes to confirm WCAG 2.2 AA contrast\n`);
+}
+
+module.exports = {
+  run,
+  findChakraTheme,
+  mapChakraFonts,
+  mapChakraToCia,
+};