css-is-awesome 1.16.1 → 1.17.0

package/AGENTS.md

@@ -338,7 +338,7 @@ Or run this in-repo copy directly — needs its SDK peer deps installed manually
 }
 ```
 
-Either way it exposes **31 tools** across 8 families:
+Either way it exposes **32 tools** across 8 families:
 
 - **Themes** — `list_themes`, `get_theme`, `search_themes`
 - **Mixins** — `list_mixins`, `get_mixin`, `search_mixins` (real signatures — don't guess)
@@ -348,11 +348,11 @@ Either way it exposes **31 tools** across 8 families:
 - **Components** — `list_components`, `get_component`, `search_components`
 - **Recipes** — `list_recipes`, `get_recipe`
 - **Doc readers** — `read_llm_txt`, `read_changelog`, `read_migration`, `read_theming`, `read_agents`, `read_contract`, `read_three_tiers`, `read_readme`, `read_versioning`
-- **Helpers** — `assemble_prompt` (bundle context), `resolve_size` (snap a design px value to cia's 4px grid — call this whenever a design tool hands you a raw px value), `validate_theme` (run the real theme validator — contract + contrast — on a CSS string before you ship it)
+- **Helpers** — `assemble_prompt` (bundle context), `resolve_size` (snap a design px value to cia's 4px grid — call this whenever a design tool hands you a raw px value), `validate_theme` (run the real theme validator — contract + contrast — on a CSS string before you ship it), `theme_from_tokens` (DTCG / Tokens Studio / flat token JSON → a complete theme.css, base-inherited and validated; same function as `cia theme from-tokens`)
 
 ## Other tooling (shipped)
 
-- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. Three verbs:
+- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. Four 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]`
@@ -360,9 +360,14 @@ Either way it exposes **31 tools** across 8 families:
   the `space()` 1–9 scale trap, off-contract tokens (near-miss typos only), hard-coded
   hex colors, BEM chains — with a health score and CI-ready exit codes. Low-noise on
   color: a hex in a `var(--token, #hex)` fallback is token-driven, and a literal inside
-  `@media print` is an intentional paper colour — neither is flagged. Run any verb with `--help`. (`cia init` remains
+  `@media print` is an intentional paper colour — neither is flagged; `npx cia theme from-tokens <tokens.json> --name <slug>`
+  turns a design-tokens file (DTCG v2025.10, Tokens Studio for Figma, or a flat `--token` map; format auto-detected)
+  into a complete theme.css — every required token the file lacks inherits from a shipped base theme (`--base`,
+  default boilerplate), unmapped paths pass through verbatim and are reported, a `--dark` file or paired
+  `color-light`/`color-dark` groups become `light-dark()`, and the validator + WCAG audit run before anything is
+  written. Same function as the MCP `theme_from_tokens` tool. Run any verb with `--help`. (`cia init` remains
   planned.)
-- **JSON token export** — DTCG-format token list in `figma-tokens/`.
+- **JSON token export** — Tokens Studio-format sample in `figma-tokens/tokens.json`; it round-trips through `cia theme from-tokens` (paired light/dark groups → one `light-dark()` theme).
 - **`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,5 +1,13 @@
 # Changelog
 
+# [1.17.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.16.1...v1.17.0) (2026-09-19)
+
+
+### Features
+
+* **cli:** cia theme from-tokens — design-tokens JSON → validated theme.css ([066b484](https://github.com/Jerry2d3d/css-is-awesome/commit/066b4849d2e937f0362e8f21cb212f3fcc144c5f))
+* **mcp:** theme_from_tokens tool + in-process handler (32 tools) ([9dc90c4](https://github.com/Jerry2d3d/css-is-awesome/commit/9dc90c40574a5e21b7b724f97792b0fd9c4182b0))
+
 ## [1.16.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.16.0...v1.16.1) (2026-09-18)
 
 

package/README.md

@@ -14,7 +14,7 @@
 
 **Read [`llm.txt`](./llm.txt) first.** One file, the whole system: install path, hard rules, the mixin vocabulary, and the traps that make agents write wrong cia code. It ships in the npm package, so it's at `node_modules/css-is-awesome/llm.txt` in any project that has cia.
 
-**Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 31 tools covering themes, mixins, functions, tokens, recipes, components and theme validation.
+**Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 32 tools covering themes, mixins, functions, tokens, recipes, components, theme validation and theme generation from design tokens.
 
 ```json
 {
@@ -226,6 +226,10 @@ npx cia analyze src/styles  # design-system health: dead cia.* symbols, the
                             # space() scale trap, off-contract tokens (typos),
                             # off-scale lengths, hard-coded colors, BEM creep,
                             # missing focus-visible styling
+npx cia theme from-tokens tokens.json --name acme --out src/styles/acme.css
+                            # design tokens (DTCG v2025.10, Tokens Studio, or a
+                            # flat --token map) → a complete, validated theme.css;
+                            # missing required tokens inherit from a shipped base
 ```
 
 `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/).
@@ -294,7 +298,7 @@ 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`) exposing **31 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) , `resolve_size` (snap design px values to cia's 4px grid) and `validate_theme` (run the real theme validator on CSS you just wrote). 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/).
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **32 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) , `resolve_size` (snap design px values to cia's 4px grid) `validate_theme` (run the real theme validator on CSS you just wrote) and `theme_from_tokens` (design-tokens JSON → a complete, validated theme.css). 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/).
 
 **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.
 
@@ -410,7 +414,7 @@ Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 
 **Stable, [published on npm](https://www.npmjs.com/package/css-is-awesome)** (first published 2026-09-01). The mixin API, functions, token contract, and theme architecture are stable and under strict SemVer — breaking changes require a major bump. See [`VERSIONING.md`](./VERSIONING.md) for the policy.
 
-The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, and the 31-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO JavaScript by hard rule.
+The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, and the 32-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO JavaScript by hard rule.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full history and [MIGRATION.md](./MIGRATION.md) for the v0.7 → v0.8 and v0.8 → v1.0 upgrade paths.
 

package/bin/cia.cjs

@@ -11,6 +11,7 @@
  *   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
+ *   theme from-tokens — design-tokens JSON (DTCG / Tokens Studio) → validated theme.css
  *
  * cia core ships ZERO JavaScript in the `files` manifest. The CLI lives in
  * `bin/` which is explicitly allowed per the architecture lock — same path
@@ -36,11 +37,15 @@ Commands:
   analyze [path]          Design-system health check: dead cia.* symbols,
                           the space() scale trap, hard-coded colors, BEM,
                           hand-written area maps.
+  theme from-tokens <f>   Design-tokens JSON (DTCG v2025.10, Tokens Studio,
+                          or flat --token map) → a complete, validated
+                          theme.css. \`cia theme from-tokens --help\`.
 
 Examples:
   cia migrate tailwind ./tailwind.config.js
   cia add bottom-nav
   cia analyze src/styles
+  cia theme from-tokens tokens.json --name acme --out src/styles/acme.css
 
 Run \`cia <command> --help\` for command-specific help.
 `;
@@ -149,6 +154,20 @@ async function main() {
     return;
   }
 
+  if (command === 'theme') {
+    const [sub, ...themeArgs] = rest;
+    if (!sub || sub === '-h' || sub === '--help' || sub === 'help') {
+      process.stdout.write(require('./theme-from-tokens.cjs').HELP);
+      return;
+    }
+    if (sub === 'from-tokens') {
+      const { run } = require('./theme-from-tokens.cjs');
+      await run(themeArgs);
+      return;
+    }
+    fail(`unknown theme subcommand '${sub}'. Available: from-tokens.`);
+  }
+
   fail(`unknown command '${command}'. Run \`cia --help\` for usage.`);
 }
 

package/bin/theme-from-tokens.cjs

@@ -0,0 +1,139 @@
+/**
+ * cia theme from-tokens — design-tokens JSON → validated cia theme.css.
+ *
+ * The CLI face of scripts/tokens-to-theme.cjs (the MCP tool
+ * `theme_from_tokens` and the in-process `handlers.theme_from_tokens` are the
+ * same function). Zero dependencies, no Sass: the theme is emitted as CSS in
+ * the exact shape the shipped themes use, then the shipped validator + WCAG
+ * audit run on it before anything is written.
+ *
+ * Exit codes: 0 valid (or --no-validate), 1 contract/a11y failure (a11y only
+ * unless --allow-a11y-fail), 2 usage / input error.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const HELP = `cia theme from-tokens — design-tokens JSON → validated cia theme.css
+
+Usage:
+  cia theme from-tokens <tokens.json> --name <slug> [options]
+
+Options:
+  --name <slug>        Theme name (kebab-case). Required.
+  --format <f>         auto | dtcg | tokens-studio | cia-flat   (default: auto)
+  --base <theme>       Shipped theme that supplies every REQUIRED token the file
+                       does not (default: boilerplate). \`--base list\` prints them.
+  --dark <dark.json>   Second tokens file for dark mode → light-dark() values.
+  --mode light|dark    Single-mode color-scheme when no dark side (default: light).
+  --out <theme.css>    Write the CSS here (default: stdout).
+  --json               Print { report, validation } as JSON to stdout
+                       (CSS goes to --out only).
+  --no-validate        Skip the validator + WCAG audit.
+  --allow-a11y-fail    Do not exit non-zero on a11y FAILs (report only).
+
+Formats:
+  dtcg           DTCG v2025.10 — leaves carry $value (+ $type); {aliases} resolve.
+  tokens-studio  Tokens Studio for Figma — leaves carry value + type; single set
+                 or multi-set export ($metadata.tokenSetOrder); {aliases} resolve.
+                 Paired top-level groups (color-light + color-dark, or
+                 light + dark) become light-dark() automatically.
+  cia-flat       { "--brand-primary": "#3A5FCD", ... } passthrough.
+
+Minimum content: none. Whatever the file does not supply is inherited from the
+base theme and listed in the report, so the output is always contract-complete.
+
+Examples:
+  cia theme from-tokens tokens.json --name acme --out src/styles/acme.css
+  cia theme from-tokens light.json --dark dark.json --name acme --json
+  cia theme from-tokens brand.json --name acme --base press --format dtcg
+`;
+
+function parseArgs(argv) {
+  const opts = { format: 'auto', base: 'boilerplate', mode: 'light', validate: true, allowA11yFail: false, json: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) throw new Error(`${a} needs a value`); return v; };
+    if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '--name') opts.name = next();
+    else if (a === '--format') opts.format = next();
+    else if (a === '--base') opts.base = next();
+    else if (a === '--dark') opts.dark = next();
+    else if (a === '--mode') opts.mode = next();
+    else if (a === '--out') opts.out = next();
+    else if (a === '--json') opts.json = true;
+    else if (a === '--no-validate') opts.validate = false;
+    else if (a === '--allow-a11y-fail') opts.allowA11yFail = true;
+    else if (a.startsWith('-')) throw new Error(`unknown option ${a}`);
+    else positional.push(a);
+  }
+  opts.input = positional[0];
+  return opts;
+}
+
+function readJson(file) {
+  const abs = path.resolve(file);
+  let text;
+  try { text = fs.readFileSync(abs, 'utf8'); } catch (e) { throw new Error(`cannot read ${file}: ${e.message}`); }
+  try { return JSON.parse(text); } catch (e) { throw new Error(`${file} is not valid JSON: ${e.message}`); }
+}
+
+async function run(argv) {
+  let opts;
+  try { opts = parseArgs(argv); } catch (e) { process.stderr.write(`cia theme: ${e.message}\n`); process.exit(2); }
+  if (opts.help || !opts.input && opts.base !== 'list') { process.stdout.write(HELP); return; }
+
+  const { themeFromTokens, listBases } = require('../scripts/tokens-to-theme.cjs');
+  if (opts.base === 'list') { process.stdout.write(listBases(path.join(__dirname, '..')).join('\n') + '\n'); return; }
+  if (!opts.name) { process.stderr.write('cia theme: --name <slug> is required\n'); process.exit(2); }
+
+  let result;
+  try {
+    result = themeFromTokens({
+      tokens: readJson(opts.input),
+      dark: opts.dark ? readJson(opts.dark) : undefined,
+      name: opts.name,
+      format: opts.format,
+      base: opts.base,
+      mode: opts.mode,
+      validate: opts.validate,
+    });
+  } catch (e) {
+    process.stderr.write(`cia theme: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  const { css, report, validation } = result;
+  if (opts.out) fs.writeFileSync(path.resolve(opts.out), css, 'utf8');
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ report, validation, out: opts.out || null }, null, 2) + '\n');
+  } else {
+    if (!opts.out) process.stdout.write(css);
+    const c = report.counts;
+    const lines = [
+      `theme "${report.name}" — ${report.format}${report.darkMode ? ' (light + dark)' : ''} · base ${report.base}`,
+      `  from tokens   ${c.fromTokens}`,
+      `  inherited     ${c.inherited}   (required tokens the file did not supply)`,
+      `  passthrough   ${c.unmapped}   (not contract tokens — emitted verbatim)`,
+      c.skipped ? `  skipped       ${c.skipped}   (composite values with no single-token home)` : null,
+      opts.out ? `  written       ${opts.out}` : null,
+    ].filter(Boolean);
+    process.stderr.write(lines.join('\n') + '\n');
+    if (validation) {
+      const { reportResult, reportA11yForTheme } = require('../scripts/theme-validator.js');
+      reportResult(validation);
+      const themes = validation.mode === 'consolidated' ? validation.themes : [{ name: report.name, a11y: validation.a11y }];
+      for (const t of themes) if (t.a11y) reportA11yForTheme(t.name, t.a11y, '    ');
+    }
+  }
+
+  if (validation) {
+    const a11yFail = validation.a11ySummary ? validation.a11ySummary.fail : 0;
+    if (!validation.ok) process.exit(1);
+    if (a11yFail && !opts.allowA11yFail) process.exit(1);
+  }
+}
+
+module.exports = { run, parseArgs, HELP };

package/dist/tokens.d.ts

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

package/figma-tokens/README.md

@@ -22,6 +22,21 @@ The `.scss` siblings exist for consumers who want to `@import` Figma-exported
 tokens directly without going through `tokens.json`. They are not consumed by
 the main `scss/` build — `scss/main.scss` pulls from `scss/theme/`.
 
+## Round trip: `tokens.json` → a theme
+
+`tokens.json` is a Tokens Studio export and is consumed by the design-tokens
+on-ramp shipped since 1.17.0:
+
+```bash
+npx cia theme from-tokens node_modules/css-is-awesome/figma-tokens/tokens.json --name figma-demo --out figma-demo.css
+```
+
+Its paired `color-light` / `color-dark` groups become one `light-dark()` theme;
+`brand`, `spacing`, `font-*`, `line-height`, `border-radius` and `shadow` map by
+the generic path rule; anything without a contract home (e.g. `brand.accent`)
+is emitted verbatim and listed in the report. The same function is the MCP
+`theme_from_tokens` tool. Input contract: `/docs/authoring/themes#from-design-tokens`.
+
 ## Direction of truth
 
 **Hand-maintained.** Keep in sync with `scss/theme/` when tokens change.

package/llm.txt

@@ -48,7 +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. **`cia.print-base` always forces `color-scheme: light` in print (paired `light-dark()` themes print their light branch), defines a themeable print palette (`--print-ink` / `--print-paper` / `--print-line` / `--print-muted`, default ink-on-white with grays) and rebinds the theme's own colour tokens (`--ink`, `--surface-*`, `--border-*`, `--code-*`) onto it — so every theme, dark-only (Terminal) included, prints legible ink-on-paper, and overriding a `--print-*` token restyles paper (a letterhead) without touching a component. Three opt-in flags, all default OFF:** `$link-urls` + `$link-origin` (print each link's full destination via `attr(href)`), `$page-numbers` (sheet numbers in the `@page` footer). `$legible` is a DEPRECATED no-op — the token rebind supersedes it and passing it warns.
 - **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, off-contract tokens (near-miss typos of real tokens only, never your own custom tokens), hard-coded hex, BEM; health score, CI exit codes). Low-noise on color: a hex in a `var(--token, #hex)` fallback is token-driven and a literal inside `@media print` is an intentional paper colour — neither is flagged.
+- **CLI** (`npx cia`) — `migrate tailwind|bootstrap|mui|chakra` (config → cia theme), `theme from-tokens <tokens.json> --name <slug>` (DTCG v2025.10 / Tokens Studio / flat `--token` JSON → a complete theme.css: required tokens the file lacks inherit from a shipped base, unmapped paths pass through and are reported, light/dark pairs become `light-dark()`, validator + WCAG audit run first; same function as the MCP `theme_from_tokens` tool), `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, off-contract tokens (near-miss typos of real tokens only, never your own custom tokens), hard-coded hex, BEM; health score, CI exit codes). Low-noise on color: a hex in a `var(--token, #hex)` fallback is token-driven and a literal inside `@media print` is an intentional paper colour — neither is flagged.
 - **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`.
 - **168 contract tokens — 127 required + 41 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.
@@ -128,7 +128,7 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 
 ## MCP server (shipped 2026-05-22)
 
-cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`, 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.
+cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`, included in the `files` manifest — so it lands in every consumer's `node_modules`. **32 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.
 
 **Recommended: suggest the dedicated `css-is-awesome-mcp` package** — zero install,
 SDK ships as a real dependency, no separate peer-install step:

package/mcp/server.cjs

@@ -19,9 +19,10 @@
  *                  read_theming, read_agents, read_contract,
  *                  read_three_tiers, read_readme, read_versioning
  *   Sizing:        resolve_size
+ *   Themes (build): theme_from_tokens — design-tokens JSON → validated theme.css
  *   Prompt:        assemble_prompt(intent[, args])
  *
- * 31 tools total.
+ * 32 tools total.
  *
  * Discovery model: filesystem scan, no database. Parses SCSS files with
  * focused regex (no full SCSS AST). Tokens come from the authoritative
@@ -698,6 +699,18 @@ const handlers = {
     return validateText(css, loadContract(), { label: label || undefined });
   },
 
+  // Design-tokens JSON (DTCG v2025.10 / Tokens Studio / flat --token map) →
+  // a complete theme.css in the shipped shape, validated + contrast-audited.
+  // Same function as `cia theme from-tokens`; reachable in-process through
+  // module.exports.handlers so an inventory builder can call it without a
+  // transport. See scripts/tokens-to-theme.cjs for the input contract.
+  theme_from_tokens({ tokens, name, format, base, dark, mode, validate } = {}) {
+    if (tokens == null) throw new Error('theme_from_tokens: tokens is required (object or JSON string)');
+    if (!name) throw new Error('theme_from_tokens: name is required');
+    const { themeFromTokens } = require(path.join(SCRIPTS_DIR, 'tokens-to-theme.cjs'));
+    return themeFromTokens({ tokens, name, format, base, dark, mode, validate });
+  },
+
   // ─── Mixins ────────────────────────────────────────────────────────────
 
   list_mixins({ category, component, limit = 500, offset = 0 } = {}) {
@@ -1354,6 +1367,27 @@ async function startServer() {
     },
   }, async (a) => ok(handlers.validate_theme(a || {})));
 
+  server.registerTool('theme_from_tokens', {
+    description:
+      'Build a complete, validated cia theme.css from a design-tokens JSON — DTCG v2025.10 ({ $value, $type }, ' +
+      '{aliases} resolved), a Tokens Studio for Figma export ({ value, type }, single or multi-set), or a flat ' +
+      '{ "--token": value } map. Format is auto-detected. Every REQUIRED contract token the file does not supply ' +
+      'is inherited from a shipped base theme (default boilerplate) and listed in report.inherited, so the output ' +
+      'is always contract-complete; unmapped paths are emitted verbatim and listed in report.unmapped, never ' +
+      'dropped. Pass `dark` (same format) or a single file with paired color-light/color-dark groups to get ' +
+      'light-dark() values. Returns { css, report, validation } — validation is the same result validate_theme ' +
+      'gives, run on the CSS before you write it anywhere.',
+    inputSchema: {
+      tokens: z.union([z.record(z.any()), z.string()]).describe('The tokens JSON (object, or a JSON string).'),
+      name: z.string().describe('Theme name — kebab-case slug, becomes [data-theme="<name>"].'),
+      format: z.enum(['auto', 'dtcg', 'tokens-studio', 'cia-flat']).optional().describe('Default auto.'),
+      base: z.string().optional().describe('Shipped theme that supplies missing required tokens. Default boilerplate.'),
+      dark: z.union([z.record(z.any()), z.string()]).optional().describe('Optional dark-mode tokens (same format) → light-dark() values.'),
+      mode: z.enum(['light', 'dark']).optional().describe('Single-mode color-scheme when there is no dark side. Default light.'),
+      validate: z.boolean().optional().describe('Run the validator + WCAG audit (default true).'),
+    },
+  }, async (a) => ok(handlers.theme_from_tokens(a || {})));
+
   // Mixins
   server.registerTool('list_mixins', {
     description: `List all ${MIXIN_COUNT} public @mixins across core, layout, animation, icons, generator, per-component and recipe sources. Filter by category (core/layout/animation/icons/generator/component/recipe) or component name.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.16.1",
+  "version": "1.17.0",
   "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": {
@@ -69,6 +69,7 @@
     "mcp",
     "scripts/theme-contract.json",
     "scripts/theme-validator.js",
+    "scripts/tokens-to-theme.cjs",
     "scripts/theme-a11y.js",
     "scripts/audit-pairs.json",
     "scripts/icon-validator.js",
@@ -117,6 +118,7 @@
     "validate-api": "node scripts/validate-api.mjs",
     "validate-package": "node scripts/validate-package.mjs",
     "validate-recipes": "node scripts/validate-recipes.mjs",
+    "test:tokens": "node --test scripts/test-tokens-to-theme.mjs",
     "size-budget": "node scripts/size-budget.mjs",
     "size-report": "node scripts/size-budget.mjs --report",
     "coverage:api": "node scripts/api-coverage.mjs",

package/scripts/theme-validator.js

@@ -713,6 +713,10 @@ module.exports = {
   validateFile,
   validateText,
   loadContract,
+  // Reporters — reused by `cia theme from-tokens` so its output reads exactly
+  // like `npm run validate-themes`.
+  reportResult,
+  reportA11yForTheme,
   a11y: a11y,
 };
 

package/scripts/tokens-to-theme.cjs

@@ -0,0 +1,668 @@
+#!/usr/bin/env node
+// ============================================================================
+// tokens-to-theme.cjs — design-tokens JSON → validated cia theme.css
+// ============================================================================
+// The supported path from a design tool to a cia theme. Ships in the npm
+// package (see `files`), zero dependencies, Node ≥ 20. Three front doors share
+// this one module:
+//
+//   CLI     npx cia theme from-tokens tokens.json --name acme        (bin/theme-from-tokens.cjs)
+//   MCP     theme_from_tokens({ tokens, name })                       (mcp/server.cjs)
+//   In-proc require('css-is-awesome/mcp/server.cjs').handlers.theme_from_tokens(...)
+//
+// INPUT FORMATS (`format`)
+//   auto           detect: keys starting with `--` → cia-flat; any `$value` → dtcg;
+//                  otherwise tokens-studio.
+//   dtcg           DTCG v2025.10 — nested groups, leaves carry `$value` (+ `$type`).
+//                  Aliases `{group.path}` resolve recursively (cycle-safe; an
+//                  unresolved alias is an error, never a silent drop). `$extensions`
+//                  and other `$`-keys are ignored. 2025.10 composite values are
+//                  understood: color objects ({hex} or {colorSpace, components}),
+//                  dimension/duration objects ({value, unit}), shadow objects/arrays,
+//                  fontFamily arrays, cubicBezier arrays.
+//   tokens-studio  Tokens Studio for Figma export — leaves carry `value` + `type`.
+//                  Either a single set (like figma-tokens/tokens.json here) or the
+//                  multi-set export with top-level `$themes` / `$metadata`; sets merge
+//                  in `$metadata.tokenSetOrder` (later sets win). Aliases `{path}`
+//                  (and legacy `$path`) resolve the same way.
+//   cia-flat       `{ "--brand-primary": "#3A5FCD", ... }` — passthrough.
+//
+// PATH → TOKEN RESOLUTION (in order; first hit wins)
+//   1. TOKEN_MAP — the explicit table below for Figma-style paths that don't
+//      spell the cia name (typography.font.body → --font-sans, …).
+//   2. Generic rule — strip a leading `color.`/`colors.`, rewrite a few common
+//      group names (PATH_ALIASES: spacing.→space., border-radius.→radius., …),
+//      then join the segments with `-`, prefix `--`, and accept the name if it
+//      is in the contract (required or optional). So `space.4` → `--space-4`,
+//      `brand.primary` → `--brand-primary`, `text.primary` → `--text-primary`.
+//   3. Anything else is emitted VERBATIM as `--<joined-path>` and listed in
+//      report.unmapped — never dropped silently.
+//
+// MINIMUM CONTENT
+//   None beyond what you have. Every REQUIRED token the file does not supply is
+//   inherited from a shipped base theme (`base`, default boilerplate) and listed
+//   in report.inherited; optional tokens are never inherited (the library
+//   default applies). The output is always a complete, contract-valid theme —
+//   the validator + WCAG audit run on it and come back as `validation`.
+//
+// LIGHT + DARK
+//   Pass `dark` (a second tokens object, same format) and every colour token
+//   that differs becomes `light-dark(light, dark)` with `color-scheme: light dark`.
+//   A single Tokens Studio file with paired top-level groups (`color-light` +
+//   `color-dark`, or `light` + `dark`) is split the same way automatically.
+//   Without a dark side the block is single-mode: `color-scheme: <mode>`
+//   (`mode`, default light).
+// ============================================================================
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CIA_ROOT_DEFAULT = path.resolve(__dirname, '..');
+const GENERATOR_VERSION = (() => {
+  try { return require(path.join(CIA_ROOT_DEFAULT, 'package.json')).version; } catch { return 'unknown'; }
+})();
+
+// ---------------------------------------------------------------------------
+// 1. Explicit table — Figma-style paths whose cia name is not the joined path.
+//    (Everything that IS the joined path — brand.primary, space.4, shadow.md,
+//    duration.fast, z.modal, code.bg, … — needs no entry: rule 2 covers it.)
+// ---------------------------------------------------------------------------
+const TOKEN_MAP = {
+  // Surfaces / backgrounds — original table (kept verbatim)
+  'color.background.default':       '--background-default',
+  'color.background.subtle':        '--background-subtle',
+  'color.background.elevated':      '--background-elevated',
+  'color.background.overlay':       '--background-overlay',
+  'color.background.hero':          '--background-hero',
+  'color.background.scrim':         '--background-scrim',
+  'color.surface.default':          '--surface-default',
+  'color.surface.raised':           '--surface-raised',
+  'color.surface.muted':            '--surface-muted',
+  // Text
+  'color.text.primary':             '--text-primary',
+  'color.text.secondary':           '--text-secondary',
+  'color.text.muted':               '--text-muted',
+  'color.text.inverse':             '--text-inverse',
+  'color.text.link':                '--text-link',
+  // Action
+  'color.action.primary.default':   '--action-primary-default',
+  'color.action.primary.hover':     '--action-primary-hover',
+  'color.action.primary.active':    '--action-primary-active',
+  'color.action.secondary.default': '--action-secondary-default',
+  'color.action.secondary.hover':   '--action-secondary-hover',
+  'color.action.secondary.active':  '--action-secondary-active',
+  // Status
+  'color.success.default':          '--success-default',
+  'color.success.subtle':           '--success-subtle',
+  'color.warning.default':          '--warning-default',
+  'color.warning.subtle':           '--warning-subtle',
+  'color.error.default':            '--error-default',
+  'color.error.subtle':             '--error-subtle',
+  // Border
+  'color.border.default':           '--border-default',
+  'color.border.subtle':            '--border-subtle',
+  'color.border.focus':             '--border-focus',
+  // Type
+  'typography.font.display':        '--font-display',
+  'typography.font.body':           '--font-sans',
+  'typography.font.mono':           '--font-mono',
+  'typography.font.serif':          '--font-serif',
+  // Shape
+  'shape.radius.sm':                '--radius-sm',
+  'shape.radius.md':                '--radius-md',
+  'shape.radius.lg':                '--radius-lg',
+  'shape.radius.full':              '--radius-full',
+  // Spacing aliases
+  'space.xs':                       '--space-xs',
+  'space.sm':                       '--space-sm',
+  'space.md':                       '--space-md',
+  'space.lg':                       '--space-lg',
+  'space.xl':                       '--space-xl',
+
+  // ── Additions 2026-09-18 (Gremlin Forge item 1) — every REQUIRED token
+  //    whose natural Figma path does not spell the cia name ─────────────
+  // Type — Figma tools group families/sizes/weights under typography.*
+  'typography.font.primary':        '--font-primary',
+  'typography.font.sans':           '--font-sans',
+  'typography.font.script':         '--font-script',
+  'typography.family.display':      '--font-display',
+  'typography.family.body':         '--font-sans',
+  'typography.family.sans':         '--font-sans',
+  'typography.family.serif':        '--font-serif',
+  'typography.family.mono':         '--font-mono',
+  'typography.family.script':       '--font-script',
+  'typography.family.primary':      '--font-primary',
+  'typography.size.base':           '--font-size-base',
+  'typography.fontSize.base':       '--font-size-base',
+  'typography.weight.medium':       '--font-weight-medium',
+  'typography.fontWeight.medium':   '--font-weight-medium',
+  'typography.lineHeight.normal':   '--line-height-normal',
+  'typography.line-height.normal':  '--line-height-normal',
+  // Shape — the fifth radius step + the short r-* aliases some kits export
+  'shape.radius.xl':                '--radius-xl',
+  'shape.radius.r-sm':              '--r-sm',
+  'shape.radius.r-md':              '--r-md',
+  'shape.radius.r-lg':              '--r-lg',
+  // Colour ramps — the tertiary action, washes, interactive states
+  'color.action.tertiary.default':  '--action-tertiary-default',
+  'color.action.tertiary.hover':    '--action-tertiary-hover',
+  'color.action.tertiary.active':   '--action-tertiary-active',
+  'color.action.primary.wash':      '--action-primary-wash',
+  'color.action.secondary.wash':    '--action-secondary-wash',
+  'color.action.tertiary.wash':     '--action-tertiary-wash',
+  'color.interactive.hover':        '--interactive-hover',
+  'color.interactive.active':       '--interactive-active',
+  'color.text.tertiary':            '--text-tertiary',
+  'color.text.link.hover':          '--text-link-hover',
+  'color.text.linkHover':           '--text-link-hover',
+  'color.border.emphasis':          '--border-emphasis',
+  'color.surface.subtle':           '--surface-subtle',
+  'color.surface.emphasis':         '--surface-emphasis',
+  'color.surface.glass':            '--surface-glass',
+  'color.surface.sunk':             '--surface-sunk',
+  'color.background.navbar':        '--background-navbar',
+  'color.success.text':             '--success-text',
+  'color.warning.text':             '--warning-text',
+  'color.error.text':               '--error-text',
+  'color.info.default':             '--info-default',
+  'color.info.subtle':              '--info-subtle',
+  'color.info.text':                '--info-text',
+  'color.feedback.success':         '--feedback-success',
+  'color.feedback.warning':         '--feedback-warning',
+  'color.feedback.error':           '--feedback-error',
+  'color.feedback.info':            '--feedback-info',
+  'color.brand.primary':            '--brand-primary',
+  'color.brand.primary.hover':      '--brand-primary-hover',
+  'color.brand.primaryHover':       '--brand-primary-hover',
+  // Motion
+  'motion.duration.fast':           '--duration-fast',
+  'motion.duration.normal':         '--duration-normal',
+  'motion.duration.slow':           '--duration-slow',
+  'motion.easing':                  '--ease',
+  'motion.ease':                    '--ease',
+  'motion.easing.default':          '--ease',
+  // Effects
+  'effect.shadow.sm':               '--shadow-sm',
+  'effect.shadow.md':               '--shadow-md',
+  'effect.shadow.lg':               '--shadow-lg',
+  'effect.shadow.xl':               '--shadow-xl',
+  'effect.shadow.2xl':              '--shadow-2xl',
+  'effect.blur.sm':                 '--blur-sm',
+  'effect.blur.md':                 '--blur-md',
+  'effect.blur.lg':                 '--blur-lg',
+  'effect.glow.sm':                 '--glow-sm',
+  'effect.glow.md':                 '--glow-md',
+  'effect.glow.lg':                 '--glow-lg',
+  // Layering
+  'layer.dropdown':                 '--z-dropdown',
+  'layer.sticky':                   '--z-sticky',
+  'layer.backdrop':                 '--z-backdrop',
+  'layer.modal':                    '--z-modal',
+  'layer.popover':                  '--z-popover',
+  'layer.tooltip':                  '--z-tooltip',
+};
+
+// Group-name rewrites applied before the generic rule (rule 2). Case-insensitive
+// on the first segment only; the rest of the path is joined verbatim.
+const PATH_ALIASES = [
+  [/^colors?\./i, ''],
+  [/^spacing\./i, 'space.'],
+  [/^border-?radius\./i, 'radius.'],
+  [/^radii\./i, 'radius.'],
+  [/^elevation\./i, 'shadow.'],
+  [/^shadows\./i, 'shadow.'],
+  [/^z-?index\./i, 'z.'],
+  [/^zindex\./i, 'z.'],
+  [/^layer\./i, 'z.'],
+  [/^font-?family\./i, 'font.'],
+  [/^fontFamilies\./i, 'font.'],
+  [/^fonts\./i, 'font.'],
+  [/^font-?size\./i, 'font-size.'],
+  [/^fontSizes?\./i, 'font-size.'],
+  [/^font-?weight\./i, 'font-weight.'],
+  [/^fontWeights?\./i, 'font-weight.'],
+  [/^line-?height\./i, 'line-height.'],
+  [/^lineHeights?\./i, 'line-height.'],
+  [/^durations?\./i, 'duration.'],
+  [/^motion\.duration\./i, 'duration.'],
+];
+
+// Token families that are unitless by contract — a bare number stays bare.
+const UNITLESS_RE = /^--(line-height|font-weight|z-|opacity)/;
+
+// ---------------------------------------------------------------------------
+// Format detection + flattening
+// ---------------------------------------------------------------------------
+function isPlainObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+
+function detectFormat(tokens) {
+  if (!isPlainObject(tokens)) throw new Error('tokens must be a JSON object');
+  const keys = Object.keys(tokens);
+  if (keys.length && keys.every((k) => k.startsWith('--'))) return 'cia-flat';
+  if (hasKeyDeep(tokens, '$value')) return 'dtcg';
+  return 'tokens-studio';
+}
+
+function hasKeyDeep(obj, key, depth = 0) {
+  if (!isPlainObject(obj) || depth > 12) return false;
+  if (Object.prototype.hasOwnProperty.call(obj, key)) return true;
+  return Object.values(obj).some((v) => hasKeyDeep(v, key, depth + 1));
+}
+
+/** DTCG: leaves are objects carrying `$value`; `$`-prefixed keys are metadata. */
+function flattenDtcg(obj, prefix = '', out = []) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    const p = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(val)) {
+      if ('$value' in val) out.push({ path: p, value: val.$value, type: val.$type ? String(val.$type).toLowerCase() : undefined });
+      else flattenDtcg(val, p, out);
+    }
+  }
+  return out;
+}
+
+/** Tokens Studio: leaves are objects carrying `value` (+ `type`). */
+function flattenTokensStudio(obj, prefix = '', out = []) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    const p = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(val)) {
+      if ('value' in val && !isPlainObject(val.value) || ('value' in val && 'type' in val)) {
+        out.push({ path: p, value: val.value, type: val.type ? String(val.type).toLowerCase() : undefined });
+      } else {
+        flattenTokensStudio(val, p, out);
+      }
+    }
+  }
+  return out;
+}
+
+/** Tokens Studio multi-set export → one merged set (later sets override). */
+function mergeTokensStudioSets(root) {
+  const meta = root.$metadata;
+  const setNames = Object.keys(root).filter((k) => !k.startsWith('$'));
+  const looksMultiSet = isPlainObject(meta) && Array.isArray(meta.tokenSetOrder) || Array.isArray(root.$themes);
+  if (!looksMultiSet) return { set: root, sets: null };
+  const order = isPlainObject(meta) && Array.isArray(meta.tokenSetOrder) ? meta.tokenSetOrder.filter((n) => setNames.includes(n)) : setNames;
+  const missing = setNames.filter((n) => !order.includes(n));
+  const merged = {};
+  for (const name of [...order, ...missing]) deepMerge(merged, root[name]);
+  return { set: merged, sets: [...order, ...missing] };
+}
+
+function deepMerge(target, src) {
+  if (!isPlainObject(src)) return target;
+  for (const [k, v] of Object.entries(src)) {
+    if (isPlainObject(v) && isPlainObject(target[k]) && !('value' in v) && !('$value' in v)) deepMerge(target[k], v);
+    else target[k] = v;
+  }
+  return target;
+}
+
+// ---------------------------------------------------------------------------
+// Alias resolution — `{group.path}` anywhere in a string, or a whole-value
+// legacy `$group.path`. Recursive, cycle-safe, loud on failure.
+// ---------------------------------------------------------------------------
+function resolveAliases(entries) {
+  const byPath = new Map(entries.map((e) => [e.path, e]));
+  const resolved = new Map();
+
+  function resolveValue(value, stack) {
+    if (typeof value === 'string') {
+      const whole = value.match(/^\$([A-Za-z0-9_.-]+)$/);
+      if (whole) return resolvePath(whole[1], stack);
+      return value.replace(/\{([^{}]+)\}/g, (_m, ref) => {
+        const v = resolvePath(ref.trim(), stack);
+        return typeof v === 'string' || typeof v === 'number' ? String(v) : JSON.stringify(v);
+      });
+    }
+    if (Array.isArray(value)) return value.map((v) => resolveValue(v, stack));
+    if (isPlainObject(value)) {
+      const out = {};
+      for (const [k, v] of Object.entries(value)) out[k] = resolveValue(v, stack);
+      return out;
+    }
+    return value;
+  }
+
+  function resolvePath(ref, stack) {
+    if (resolved.has(ref)) return resolved.get(ref);
+    if (stack.includes(ref)) throw new Error(`alias cycle: ${[...stack, ref].join(' → ')}`);
+    const target = byPath.get(ref);
+    if (!target) throw new Error(`unresolved alias {${ref}} (referenced from ${stack[stack.length - 1] || 'top level'})`);
+    const v = resolveValue(target.value, [...stack, ref]);
+    resolved.set(ref, v);
+    return v;
+  }
+
+  return entries.map((e) => ({ ...e, value: resolveValue(e.value, [e.path]) }));
+}
+
+// ---------------------------------------------------------------------------
+// Value normalisation — every leaf becomes one CSS value string, or is skipped
+// with a reason (composites such as `typography` have no single-token home).
+// ---------------------------------------------------------------------------
+function unitOf(type) {
+  const t = (type || '').toLowerCase();
+  if (['duration', 'durations'].includes(t)) return 'ms';
+  if (['dimension', 'spacing', 'sizing', 'borderradius', 'borderwidth', 'fontsize', 'fontsizes', 'letterspacing', 'paragraphspacing', 'space', 'radius'].includes(t)) return 'px';
+  return null;
+}
+
+function dimToString(v, fallbackUnit) {
+  if (isPlainObject(v) && 'value' in v) return `${v.value}${v.unit || fallbackUnit || ''}`;
+  if (typeof v === 'number') return `${v}${fallbackUnit || ''}`;
+  // Tokens Studio exports numbers as strings ("4"); a bare numeric string takes the unit too.
+  if (typeof v === 'string' && /^-?\d+(\.\d+)?$/.test(v.trim())) return `${v.trim()}${fallbackUnit || ''}`;
+  return String(v);
+}
+
+function colorToString(v) {
+  if (typeof v === 'string') return v.trim();
+  if (isPlainObject(v)) {
+    if (v.hex) return String(v.hex);
+    const space = String(v.colorSpace || 'srgb').toLowerCase();
+    const c = Array.isArray(v.components) ? v.components : [];
+    const a = v.alpha == null ? 1 : Number(v.alpha);
+    if (space === 'srgb' && c.length >= 3) {
+      const [r, g, b] = c.map((x) => Math.round(Number(x) * 255));
+      return a < 1 ? `rgba(${r}, ${g}, ${b}, ${a})` : `rgb(${r}, ${g}, ${b})`;
+    }
+    return `color(${space} ${c.join(' ')}${a < 1 ? ` / ${a}` : ''})`;
+  }
+  return String(v);
+}
+
+function shadowToString(v) {
+  const one = (s) => {
+    if (typeof s === 'string') return s;
+    if (!isPlainObject(s)) return String(s);
+    const x = dimToString(s.offsetX ?? s.x ?? 0, 'px');
+    const y = dimToString(s.offsetY ?? s.y ?? 0, 'px');
+    const blur = dimToString(s.blur ?? 0, 'px');
+    const spread = dimToString(s.spread ?? 0, 'px');
+    const color = colorToString(s.color ?? 'rgba(0,0,0,0.2)');
+    const inset = s.inset || String(s.type || '').toLowerCase() === 'innershadow' ? 'inset ' : '';
+    return `${inset}${x} ${y} ${blur} ${spread} ${color}`;
+  };
+  return (Array.isArray(v) ? v : [v]).map(one).join(', ');
+}
+
+function fontFamilyToString(v) {
+  const list = Array.isArray(v) ? v : String(v).split(',').map((s) => s.trim());
+  return list.map((f) => (/[\s]/.test(f) && !/^["']/.test(f) ? `"${f}"` : f)).join(', ');
+}
+
+/** Returns { value } or { skip: reason }. */
+function normalizeValue(entry, tokenName) {
+  const { value, type } = entry;
+  const t = (type || '').toLowerCase();
+  if (value == null) return { skip: 'empty value' };
+  if (['typography', 'border', 'composition', 'strokestyle', 'transition', 'gradient'].includes(t)) return { skip: `composite type "${t}" has no single-token home` };
+  if (t === 'color') return { value: colorToString(value) };
+  if (t === 'shadow' || t === 'boxshadow') return { value: shadowToString(value) };
+  if (t === 'fontfamily' || t === 'fontfamilies') return { value: fontFamilyToString(value) };
+  if (t === 'cubicbezier' && Array.isArray(value)) return { value: `cubic-bezier(${value.join(', ')})` };
+  const unit = unitOf(t);
+  if (unit) {
+    if (isPlainObject(value)) return { value: dimToString(value, unit) };
+    if (typeof value === 'number' || /^-?\d+(\.\d+)?$/.test(String(value).trim())) {
+      const n = Number(value);
+      return { value: n === 0 ? '0' : `${n}${UNITLESS_RE.test(tokenName) ? '' : unit}` };
+    }
+    return { value: String(value).trim() };
+  }
+  if (isPlainObject(value)) {
+    if ('hex' in value || 'colorSpace' in value) return { value: colorToString(value) };
+    if ('value' in value && 'unit' in value) return { value: dimToString(value) };
+    return { skip: 'object value of unknown shape' };
+  }
+  if (Array.isArray(value)) return { value: value.map(String).join(', ') };
+  return { value: String(value).trim() };
+}
+
+// ---------------------------------------------------------------------------
+// Path → cia token name
+// ---------------------------------------------------------------------------
+function loadContract(ciaRoot) {
+  const p = path.join(ciaRoot, 'scripts', 'theme-contract.json');
+  const c = JSON.parse(fs.readFileSync(p, 'utf8'));
+  return {
+    version: c.version,
+    required: c.required || [],
+    optional: c.optional || [],
+    all: new Set([...(c.required || []), ...(c.optional || [])]),
+  };
+}
+
+function applyPathAliases(p) {
+  let out = p;
+  for (const [re, to] of PATH_ALIASES) {
+    if (re.test(out)) { out = out.replace(re, to); break; }
+  }
+  return out;
+}
+
+/** Returns { token, mapped: true } or { token, mapped: false } (verbatim fallback). */
+function mapPath(tokenPath, contract) {
+  if (TOKEN_MAP[tokenPath]) return { token: TOKEN_MAP[tokenPath], mapped: true };
+  const aliased = applyPathAliases(tokenPath);
+  if (TOKEN_MAP[aliased]) return { token: TOKEN_MAP[aliased], mapped: true };
+  const generic = `--${aliased.replace(/\./g, '-').toLowerCase()}`;
+  if (contract.all.has(generic)) return { token: generic, mapped: true };
+  // camelCase segments → kebab (linkHover → link-hover), one more try.
+  const kebab = `--${aliased.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/\./g, '-').toLowerCase()}`;
+  if (contract.all.has(kebab)) return { token: kebab, mapped: true };
+  return { token: generic, mapped: false };
+}
+
+// ---------------------------------------------------------------------------
+// Base theme — the shipped theme.css a partial file inherits from
+// ---------------------------------------------------------------------------
+function listBases(ciaRoot) {
+  const dir = path.join(ciaRoot, 'public', 'themes');
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && fs.existsSync(path.join(dir, d.name, 'theme.css')))
+      .map((d) => d.name)
+      .sort();
+  } catch { return []; }
+}
+
+function loadBase(ciaRoot, base) {
+  const file = path.join(ciaRoot, 'public', 'themes', base, 'theme.css');
+  if (!fs.existsSync(file)) {
+    const bases = listBases(ciaRoot);
+    throw new Error(`unknown base theme "${base}". Available: ${bases.join(', ') || '(none found under public/themes)'}`);
+  }
+  const validator = require(path.join(ciaRoot, 'scripts', 'theme-validator.js'));
+  const text = fs.readFileSync(file, 'utf8');
+  const blocks = validator.extractDataThemeBlocks(text);
+  const values = blocks.length ? blocks[0].values : validator.extractRootBlock(text).values;
+  return { name: base, file, values }; // Map<token, rawValue>
+}
+
+// ---------------------------------------------------------------------------
+// Paired-mode detection for a single Tokens Studio / DTCG file
+// ---------------------------------------------------------------------------
+const PAIRS = [['color-light', 'color-dark'], ['light', 'dark'], ['colors-light', 'colors-dark']];
+
+function splitPairedModes(tokens) {
+  if (!isPlainObject(tokens)) return null;
+  for (const [l, d] of PAIRS) {
+    if (isPlainObject(tokens[l]) && isPlainObject(tokens[d])) {
+      const rest = {};
+      for (const [k, v] of Object.entries(tokens)) if (k !== l && k !== d) rest[k] = v;
+      const light = { ...rest, color: tokens[l] };
+      const dark = { ...rest, color: tokens[d] };
+      return { light, dark, groups: [l, d] };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// One tokens object → Map<token, value> (+ bookkeeping)
+// ---------------------------------------------------------------------------
+function collect(tokens, format, contract) {
+  const declared = new Map();     // token → value
+  const unmapped = [];            // { path, emittedAs }
+  const skipped = [];             // { path, reason }
+  const fromPaths = new Map();    // token → path
+
+  if (format === 'cia-flat') {
+    for (const [k, v] of Object.entries(tokens)) {
+      if (!k.startsWith('--')) throw new Error(`cia-flat: key "${k}" is not a custom property`);
+      declared.set(k, String(v));
+      if (!contract.all.has(k)) unmapped.push({ path: k, emittedAs: k });
+    }
+    return { declared, unmapped, skipped, fromPaths };
+  }
+
+  let entries;
+  if (format === 'dtcg') entries = flattenDtcg(tokens);
+  else {
+    const { set } = mergeTokensStudioSets(tokens);
+    entries = flattenTokensStudio(set);
+  }
+  entries = resolveAliases(entries);
+
+  for (const e of entries) {
+    const { token, mapped } = mapPath(e.path, contract);
+    const norm = normalizeValue(e, token);
+    if (norm.skip) { skipped.push({ path: e.path, reason: norm.skip }); continue; }
+    declared.set(token, norm.value);
+    fromPaths.set(token, e.path);
+    if (!mapped) unmapped.push({ path: e.path, emittedAs: token });
+  }
+  return { declared, unmapped, skipped, fromPaths };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function themeFromTokens(opts = {}) {
+  const ciaRoot = opts.ciaRoot || CIA_ROOT_DEFAULT;
+  const name = String(opts.name || '').trim();
+  if (!NAME_RE.test(name)) throw new Error(`name must be a kebab-case slug (got "${opts.name}")`);
+  let tokens = typeof opts.tokens === 'string' ? JSON.parse(opts.tokens) : opts.tokens;
+  let dark = typeof opts.dark === 'string' ? JSON.parse(opts.dark) : opts.dark || null;
+  if (!isPlainObject(tokens)) throw new Error('tokens must be a JSON object (or a JSON string)');
+
+  const contract = loadContract(ciaRoot);
+  const base = loadBase(ciaRoot, opts.base || 'boilerplate');
+  const mode = opts.mode === 'dark' ? 'dark' : 'light';
+
+  let format = opts.format && opts.format !== 'auto' ? String(opts.format) : detectFormat(tokens);
+  if (!['dtcg', 'tokens-studio', 'cia-flat'].includes(format)) throw new Error(`format must be auto | dtcg | tokens-studio | cia-flat (got "${format}")`);
+
+  // A single file with paired light/dark groups is split automatically.
+  let pairedGroups = null;
+  if (!dark && format !== 'cia-flat') {
+    const pair = splitPairedModes(tokens);
+    if (pair) { tokens = pair.light; dark = pair.dark; pairedGroups = pair.groups; }
+  }
+  if (dark && !isPlainObject(dark)) throw new Error('dark must be a JSON object (or a JSON string)');
+  const darkFormat = dark ? (opts.format && opts.format !== 'auto' ? format : detectFormat(dark)) : null;
+
+  const light = collect(tokens, format, contract);
+  const darkSide = dark ? collect(dark, darkFormat, contract) : null;
+  const darkMode = Boolean(darkSide);
+
+  const isColorish = (v) => /^(#|rgb|hsl|hwb|lab|lch|oklab|oklch|color\(|light-dark\()/i.test(String(v).trim()) || /^[a-z]+$/i.test(String(v).trim());
+  const valueFor = (token) => {
+    const l = light.declared.get(token);
+    const d = darkSide ? darkSide.declared.get(token) : undefined;
+    if (l == null && d == null) return undefined;
+    if (d != null && l != null && d !== l && (isColorish(l) || isColorish(d))) return `light-dark(${l}, ${d})`;
+    if (l == null) return darkMode ? `light-dark(${d}, ${d})` : d;
+    return l;
+  };
+
+  const lines = [];
+  const fromTokens = [];
+  const inherited = [];
+  const optionalDeclared = [];
+
+  for (const token of contract.required) {
+    const v = valueFor(token);
+    if (v !== undefined) { lines.push([token, v]); fromTokens.push(token); continue; }
+    const b = base.values.get(token);
+    if (b === undefined) throw new Error(`base theme "${base.name}" does not declare required token ${token}; refusing to emit an incomplete theme`);
+    lines.push([token, b]);
+    inherited.push(token);
+  }
+  for (const token of contract.optional) {
+    const v = valueFor(token);
+    if (v !== undefined) { lines.push([token, v]); fromTokens.push(token); optionalDeclared.push(token); }
+  }
+  const seen = new Set(lines.map(([t]) => t));
+  const extras = [];
+  for (const [token, v] of light.declared) if (!seen.has(token)) { extras.push([token, valueFor(token)]); seen.add(token); }
+  if (darkSide) for (const [token] of darkSide.declared) if (!seen.has(token)) { extras.push([token, valueFor(token)]); seen.add(token); }
+  extras.sort((a, b) => a[0].localeCompare(b[0]));
+
+  const scheme = darkMode ? 'light dark' : mode;
+  const header =
+    `/* css-is-awesome theme "${name}" — generated by tokens-to-theme ${GENERATOR_VERSION}\n` +
+    `   source: ${format}${darkSide ? ` (+ dark side${pairedGroups ? `, paired groups ${pairedGroups.join('/')}` : ''})` : ''} · base: ${base.name} · contract ${contract.version}\n` +
+    `   ${fromTokens.length} token(s) from the design file, ${inherited.length} inherited from the base, ${extras.length} passed through verbatim */\n`;
+  const body =
+    `:root, :root[data-theme="${name}"] {\n` +
+    `  color-scheme: ${scheme};\n` +
+    [...lines, ...extras].map(([t, v]) => `  ${t}: ${v};`).join('\n') +
+    `\n}\n`;
+  const css = header + body;
+
+  const optionalMissing = contract.optional.filter((t) => !seen.has(t));
+  const report = {
+    name,
+    format,
+    base: base.name,
+    darkMode,
+    pairedGroups,
+    fromTokens,
+    inherited,
+    unmapped: [...light.unmapped, ...(darkSide ? darkSide.unmapped.filter((u) => !light.unmapped.some((x) => x.emittedAs === u.emittedAs)) : [])],
+    skipped: [...light.skipped, ...(darkSide ? darkSide.skipped : [])],
+    optionalDeclared,
+    optionalMissing,
+    counts: { fromTokens: fromTokens.length, inherited: inherited.length, unmapped: light.unmapped.length, skipped: light.skipped.length },
+  };
+
+  let validation = null;
+  if (opts.validate !== false) {
+    const validator = require(path.join(ciaRoot, 'scripts', 'theme-validator.js'));
+    validation = validator.validateText(css, validator.loadContract(), { label: name });
+    validation.a11ySummary = summarizeA11y(validation);
+  }
+  return { css, report, validation };
+}
+
+function summarizeA11y(validation) {
+  const audits = validation.mode === 'consolidated'
+    ? (validation.themes || []).flatMap((t) => t.a11y || [])
+    : validation.a11y || [];
+  const s = { fail: 0, warn: 0, pass: 0, info: 0, skip: 0 };
+  for (const r of audits) if (s[r.status] != null) s[r.status]++;
+  return s;
+}
+
+module.exports = {
+  themeFromTokens,
+  detectFormat,
+  flattenDtcg,
+  flattenTokensStudio,
+  mergeTokensStudioSets,
+  resolveAliases,
+  normalizeValue,
+  mapPath,
+  listBases,
+  TOKEN_MAP,
+  PATH_ALIASES,
+  GENERATOR_VERSION,
+};