css-is-awesome 1.17.0 → 1.19.0

package/AGENTS.md

@@ -4,7 +4,7 @@ This file is the entry point for AI coding agents (Aider, Codex, Cursor, Claude
 
 ## What this library is
 
-A token-driven SCSS design system with a **single mixin-router per component**. **Mixin-first since v0.8** — the mixin is the API; the class/tag/selector is the consumer's choice. The npm package ships **zero JavaScript** by hard rule.
+A token-driven SCSS design system with a **single mixin-router per component**. **Mixin-first since v0.8** — the mixin is the API; the class/tag/selector is the consumer's choice. The npm package ships **zero runtime JavaScript** by hard rule — nothing in it is loaded by a page; the Node tooling (`cia` CLI, MCP server, validators) never reaches the browser.
 
 **Every mixin is a knob-board.** Each look/feel dimension is an *input*, so a consumer can restyle any mixin at any time by changing an argument — row→column is just `@include cia.flex($direction: column)`, never a hand-written `flex-direction`. Customization lives in the mixin's arguments; the consumer stays one line. **If a visual dimension can only be reached by overriding in CSS, that's a missing input — add it to the mixin.** Fewer SCSS lines always wins.
 
@@ -25,7 +25,7 @@ When asked to add a UI element, follow this order:
 3. **Never invent `cia-*` class names.** That prefix is library-owned. Consumer code uses its own naming.
 4. **All values come from tokens.** Never hardcode `#3A5FCD`, `1rem`, `8px`. Use `cia.color(primary)`, `cia.space(4)`, `cia.radius(md)`.
 5. **No BEM.** No `__element` / `--modifier` chains. `cia-` is a single-class namespace prefix, not BEM.
-6. **No JavaScript.** Cia ships zero JS in the npm package. The 6 interactive components (accordion, modal, tooltip, dropdown, tabs, copy-button) use native HTML primitives — `<details name>`, `<dialog>`, `[popover]`, radio + `:has()`. Mobile navigation follows the same doctrine: the `hamburger` / `drawer` / `sheet` / `dock` mixin family rides `[popover]` + CSS Grid — see the `mobile-nav` recipe (hamburger + drawer) and the `bottom-nav` recipe (dock + sheets). **This rule binds cia, not you.** If you're *consuming* cia (building an app/component library on top of it), write JavaScript/framework components freely — React, SVG charts, interactivity, all of it — and use cia purely for styling (mixins + tokens). Compose the mixins to build any visual you want; you are not limited to cia's pre-made component mixins.
+6. **No runtime JavaScript.** Nothing in the npm package is loaded by a page — the Node tooling (`cia` CLI, MCP server, validators) never reaches the browser. The 6 interactive components (accordion, modal, tooltip, dropdown, tabs, copy-button) use native HTML primitives — `<details name>`, `<dialog>`, `[popover]`, radio + `:has()`. Mobile navigation follows the same doctrine: the `hamburger` / `drawer` / `sheet` / `dock` mixin family rides `[popover]` + CSS Grid — see the `mobile-nav` recipe (hamburger + drawer) and the `bottom-nav` recipe (dock + sheets). **This rule binds cia, not you.** If you're *consuming* cia (building an app/component library on top of it), write JavaScript/framework components freely — React, SVG charts, interactivity, all of it — and use cia purely for styling (mixins + tokens). Compose the mixins to build any visual you want; you are not limited to cia's pre-made component mixins.
 7. **Grid is the skeleton; Flex is the quick moves.** Three levels, strictly:
    - **The page shell is CSS Grid with landmark-named areas.** The body's areas ARE the document's landmarks — `nav`, `main`, `footer` — so the area map reads like the page and screen readers get the structure for free. Declared once via `cia.page-layout(default | sidebar-left | sidebar-right | holy-grail)` (100dvh, sticky footer, auto mobile collapse) or `cia.layout((sidebar content toc), $tracks: …)`; children claim slots with `cia.page-header` / `cia.page-main` / `cia.page-footer` / `cia.area(name)`. Baseline since 2020.
    - **The doctrine scales inward: any control-dense region gets its own named-area grid.** A docs article (`header / demo / usage / tabs / footer`), a selections rail (`filter / list`), a dashboard — when a region has many controls, name its rows with `cia.layout(...)` too. Nested grids all the way down where density warrants; the grid's `gap` is the region's entire vertical rhythm (children carry no rhythm margins).
@@ -338,7 +338,7 @@ Or run this in-repo copy directly — needs its SDK peer deps installed manually
 }
 ```
 
-Either way it exposes **32 tools** across 8 families:
+Either way it exposes **33 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 **32 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), `theme_from_tokens` (DTCG / Tokens Studio / flat token JSON → a complete theme.css, base-inherited and validated; same function as `cia theme from-tokens`)
+- **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`), `get_token_map` (that path → token mapping as data, or how one path resolves — read it instead of re-deriving the rules)
 
 ## Other tooling (shipped)
 
-- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. Four verbs:
+- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. Four verbs (`theme` has two subcommands: `from-tokens` and `map`, the latter printing the path → token mapping as a table, `--json`, or `--path <p>` for one name):
   `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]`

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+# [1.19.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.18.0...v1.19.0) (2026-09-19)
+
+
+### Features
+
+* **cli:** cia theme map — the design-token → cia-token mapping as data ([283db9b](https://github.com/Jerry2d3d/css-is-awesome/commit/283db9b47b2195b8d8cb3afe9bad254c88e91cab))
+* **cli:** map boilerplate's canonical DTCG layout — font.family roles, component.* overrides ([8ae71fd](https://github.com/Jerry2d3d/css-is-awesome/commit/8ae71fd55b07bbf7da6d562f5388dcc489bcffb9))
+* **mcp:** get_token_map tool + in-process handler (33 tools) ([ff5610f](https://github.com/Jerry2d3d/css-is-awesome/commit/ff5610f5409bead49fa794a8c27967f602376c77))
+
+# [1.18.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.17.0...v1.18.0) (2026-09-19)
+
+
+### Bug Fixes
+
+* **site:** playground editor no longer boots from stale text when a share link decodes early ([3f0748f](https://github.com/Jerry2d3d/css-is-awesome/commit/3f0748f28b8a70471f1f61485733872c6ccdd6a9))
+
+
+### Features
+
+* **contract:** feature groups for optional tokens — contract 1.2 ([cc98e1f](https://github.com/Jerry2d3d/css-is-awesome/commit/cc98e1f9397ae89ef65b70557a942b5b561a0f85))
+
 # [1.17.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.16.1...v1.17.0) (2026-09-19)
 
 

package/CONTRACT.md

@@ -306,6 +306,25 @@ Paper themes declare these as `none` / `transparent` so a swap to a glass or pho
 
 ---
 
+## Optional tokens by feature (contract 1.2)
+
+Every optional token belongs to exactly one **feature** in `scripts/theme-contract.json` (`features`), so a validator, installer or agent can say *"this theme is missing the tokens for print"* instead of listing all 41 optional names. The validator's info line reports counts per feature; `--show-optional` lists them grouped. `npm run check:contract` fails the build if an optional token is in no feature, in two, or if a feature names a required token.
+
+| Feature | Tokens | Enables |
+| --- | --- | --- |
+| `density` | `--space-unit` | The density knob: shipped themes derive every --space-N from this one unit via calc(); set it to tighten or open up the whole UI (theme editor slider). |
+| `spacing-aliases` | `--space-2xs`, `--space-xs`, `--space-sm`, `--space-md`, `--space-lg`, `--space-xl` | T-shirt spacing names (2xs–xl) for consumer CSS that prefers them; the library reads the numbered scale, so these are pure aliases. |
+| `print` | `--print-ink`, `--print-paper`, `--print-line`, `--print-muted` | A themed printed page: cia.print-base rebinds ink/surface/border/code tokens onto this palette inside @media print. Without them the ink-on-white default applies. |
+| `component-radius` | `--btn-radius`, `--card-radius`, `--input-radius`, `--modal-radius`, `--badge-radius`, `--tag-radius` | Per-component corner radius overrides (buttons, cards, inputs, modals, badges, tags) without rebuilding SCSS; each falls back to the generic --radius-* scale. |
+| `component-shadows` | `--shadow-button`, `--shadow-card`, `--shadow-dropdown`, `--shadow-input-focus`, `--shadow-modal`, `--shadow-popover`, `--shadow-tooltip`, `--shadow-text` | Per-component elevation overrides; each falls back to the generic --shadow-* scale. |
+| `component-motion` | `--duration-button-hover`, `--duration-modal-open`, `--duration-toast-slide` | Per-component durations for button hover, modal open and toast slide; each falls back to the generic --duration-* scale. |
+| `surfaces-extended` | `--background-elevated`, `--background-hero`, `--background-overlay`, `--background-scrim` | Extra background layers (elevated, hero, overlay, scrim) for themes that want more than the required surface set; each falls back to a required surface. |
+| `borders-extended` | `--border-card`, `--border-divider`, `--border-focus-ring`, `--border-input` | Per-context border colours (card, divider, focus ring, input); each falls back to --border-default / --border-focus. |
+| `logo` | `--logo-default`, `--logo-mark`, `--logo-monochrome`, `--logo-wordmark` | Theme-aware logo assets (default, mark, monochrome, wordmark) as url() or SVG data values for the icon/brand mixins. |
+| `touch-target` | `--touch-target-min` | Minimum interactive target size read by form and button mixins (WCAG 2.2 SC 2.5.8); the library default is 24px. |
+
+---
+
 ## 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.

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/css-is-awesome?logo=npm&color=cb3837)](https://www.npmjs.com/package/css-is-awesome) [![CI](https://github.com/Jerry2d3d/css-is-awesome/actions/workflows/ci.yml/badge.svg)](https://github.com/Jerry2d3d/css-is-awesome/actions/workflows/ci.yml) [![Node](https://img.shields.io/badge/node-%E2%89%A520-43853d?logo=node.js&logoColor=white)](./package.json) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![semantic-release](https://img.shields.io/badge/semantic--release-enabled-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
 
-**Bring your own components. Bring your own selectors. We bring the design system.** No component library to fight, in React, Vue, Angular, Svelte, Web Components, Razor, SharePoint, or plain HTML — cia styles the markup you already own. One CSS file per theme — drop it in and the page restyles, no markup change. 24 themes. Zero JavaScript in the npm package. Six browser-native interactive components. Small enough to read in an afternoon.
+**Bring your own components. Bring your own selectors. We bring the design system.** No component library to fight, in React, Vue, Angular, Svelte, Web Components, Razor, SharePoint, or plain HTML — cia styles the markup you already own. One CSS file per theme — drop it in and the page restyles, no markup change. 24 themes. Zero runtime JavaScript — nothing in the package is loaded by a page. Six browser-native interactive components. Small enough to read in an afternoon.
 
 **Docs:** [cssisawesome.com](https://cssisawesome.com/) · **Install:** `npm install css-is-awesome`
 
@@ -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 — 32 tools covering themes, mixins, functions, tokens, recipes, components, theme validation and theme generation from design tokens.
+**Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 33 tools covering themes, mixins, functions, tokens, recipes, components, theme validation, theme generation from design tokens and the token mapping itself.
 
 ```json
 {
@@ -230,6 +230,9 @@ 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
+npx cia theme map --path color.text.primary
+                            # the path → token mapping from-tokens applies, as
+                            # data: one path, or the whole table with --json
 ```
 
 `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/).
@@ -298,7 +301,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 **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/).
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **33 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) `theme_from_tokens` (design-tokens JSON → a complete, validated theme.css) and `get_token_map` (that mapping as data, or how one path resolves). 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.
 
@@ -408,13 +411,13 @@ Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 | `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. |
+| **Runtime JavaScript shipped in package** | **0 KB** | Nothing in the package is loaded by a page. The Node tooling (`cia` CLI, MCP server, validators) never reaches the browser; JS-driven UI features ship as separate add-on packages. |
 
 ## Status
 
 **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 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.
+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 33-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 runtime JavaScript by hard rule — nothing in it is loaded by a page; its Node tooling (CLI, MCP server, validators) never reaches the browser.
 
 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/VERSIONING.md

@@ -43,6 +43,7 @@ Additive, non-breaking changes.
 | New public CSS class                                         | `.cia-grid-auto-fit` added                        |
 | New public SCSS mixin                                        | `m.cluster($gap)` added                           |
 | New optional token added to contract (`"1"` → `"1.1"`)       | `--dropdown-offset-y` added to component section  |
+| Contract metadata added (e.g. the `features` map, `"1.1"` → `"1.2"`, 2026-09-18) | Additive keys — old validators ignore them |
 | Required token relaxed to optional (contract minor bump)      | `--space-unit` required → optional, contract `"1"` → `"1.1"` (2026-09-18) |
 | New theme or recipe shipped                                  | `prism` family added; `mobile-nav` recipe added   |
 | New utility class (`.cia-*`)                                 | `.cia-text-balance` added                         |

package/bin/cia.cjs

@@ -12,6 +12,7 @@
  *   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
+ *   theme map         — the design-token → cia-token mapping, as data (table / --json / --path)
  *
  * cia core ships ZERO JavaScript in the `files` manifest. The CLI lives in
  * `bin/` which is explicitly allowed per the architecture lock — same path
@@ -40,12 +41,15 @@ Commands:
   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\`.
+  theme map               The path → token mapping from-tokens applies, as
+                          data: a table, \`--json\`, or \`--path <p>\` for one.
 
 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
+  cia theme map --path color.text.primary
 
 Run \`cia <command> --help\` for command-specific help.
 `;
@@ -165,7 +169,12 @@ async function main() {
       await run(themeArgs);
       return;
     }
-    fail(`unknown theme subcommand '${sub}'. Available: from-tokens.`);
+    if (sub === 'map') {
+      const { runMap } = require('./theme-from-tokens.cjs');
+      await runMap(themeArgs);
+      return;
+    }
+    fail(`unknown theme subcommand '${sub}'. Available: from-tokens, map.`);
   }
 
   fail(`unknown command '${command}'. Run \`cia --help\` for usage.`);

package/bin/theme-from-tokens.cjs

@@ -136,4 +136,72 @@ async function run(argv) {
   }
 }
 
-module.exports = { run, parseArgs, HELP };
+const MAP_HELP = `cia theme map — the design-token → cia-token mapping, as data
+
+Usage:
+  cia theme map                 Human-readable table: explicit entries by family,
+                                the prefix rewrites, then the generic rule
+  cia theme map --json          The same mapping as JSON (stable shape — read it
+                                from a build script or another tool)
+  cia theme map --path <p>      How ONE path resolves, e.g. --path color.text.primary
+
+The JSON shape: { generatorVersion, contractVersion, explicit: { "<path>": "--token" },
+aliases: [{ pattern, replaceWith }], genericRule, targets: { required, optional } }.
+Same data the MCP tool get_token_map returns and \`cia theme from-tokens\` applies.
+`;
+
+function parseMapArgs(argv) {
+  const opts = { json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--path') { opts.path = argv[++i]; if (opts.path === undefined) throw new Error('--path needs a value'); }
+    else throw new Error(`unknown option ${a}`);
+  }
+  return opts;
+}
+
+function familyOf(tokenPath) { return tokenPath.split('.')[0]; }
+
+async function runMap(argv) {
+  let opts;
+  try { opts = parseMapArgs(argv); } catch (e) { process.stderr.write(`cia theme map: ${e.message}\n`); process.exit(2); }
+  if (opts.help) { process.stdout.write(MAP_HELP); return; }
+  const { tokenMap, resolvePath } = require('../scripts/tokens-to-theme.cjs');
+
+  if (opts.path) {
+    let r;
+    try { r = resolvePath(opts.path); } catch (e) { process.stderr.write(`cia theme map: ${e.message}\n`); process.exit(2); }
+    if (opts.json) { process.stdout.write(JSON.stringify(r, null, 2) + '\n'); return; }
+    const how = {
+      'explicit': 'explicit table entry',
+      'explicit-after-alias': 'explicit table entry, after a prefix rewrite',
+      'generic': 'generic rule (join with "-", found in the contract)',
+      'passthrough': 'NOT a contract token — emitted verbatim, reported as unmapped',
+    }[r.via];
+    process.stdout.write(`${r.path}  →  ${r.token}\n  ${r.mapped ? 'mapped' : 'unmapped'} · ${how}${r.status ? ` · contract: ${r.status}` : ''}\n`);
+    return;
+  }
+
+  const m = tokenMap();
+  if (opts.json) { process.stdout.write(JSON.stringify(m, null, 2) + '\n'); return; }
+  const out = [`cia token map — generator ${m.generatorVersion}, contract ${m.contractVersion}`, ''];
+  const byFamily = {};
+  for (const [p, t] of Object.entries(m.explicit)) (byFamily[familyOf(p)] = byFamily[familyOf(p)] || []).push([p, t]);
+  out.push(`Explicit entries (${Object.keys(m.explicit).length})`);
+  for (const fam of Object.keys(byFamily).sort()) {
+    out.push(`  ${fam}`);
+    const w = Math.max(...byFamily[fam].map(([p]) => p.length));
+    for (const [p, t] of byFamily[fam]) out.push(`    ${p.padEnd(w)}  →  ${t}`);
+  }
+  out.push('', `Prefix rewrites (${m.aliases.length}, first match wins, applied before the generic rule)`);
+  const aw = Math.max(...m.aliases.map((a) => a.pattern.length));
+  for (const a of m.aliases) out.push(`    ${a.pattern.padEnd(aw)}  →  ${JSON.stringify(a.replaceWith)}`);
+  out.push('', 'Generic rule', `  ${m.genericRule}`, '',
+    `Targets: ${m.targets.required.length} required + ${m.targets.optional.length} optional contract tokens`,
+    '', 'Try one:  cia theme map --path color.text.primary');
+  process.stdout.write(out.join('\n') + '\n');
+}
+
+module.exports = { run, runMap, parseArgs, parseMapArgs, HELP, MAP_HELP };

package/llm.txt

@@ -8,7 +8,8 @@
 
 A token-driven SCSS design system. **Mixin-first** (since v0.8) — the mixin
 is the API, the class/tag/selector is the consumer's choice. The npm package
-ships **zero JavaScript** by hard rule.
+ships **zero runtime JavaScript** by hard rule — nothing in it is loaded by a
+page; its Node tooling (`cia` CLI, MCP server, validators) never reaches the browser.
 
 ## How consumers install it (the primary path)
 
@@ -48,7 +49,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|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.
+- **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), `theme map [--json | --path <p>]` (the path → token mapping from-tokens applies, as data; same as MCP `get_token_map`), `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.
@@ -57,7 +58,7 @@ silent.
 
 ## Hard rules (do not violate)
 
-1. **No JavaScript in the cia npm package.** Zero `.js`/`.mjs` files ship. JS-augmented features (CopyButton handler, future force-mode) ship as separate add-on packages. **This binds the package, not the consumer:** apps built ON cia should write JS/framework components freely (React, SVG charts, interactivity) and use cia only for styling — mixins + tokens. Don't over-apply "zero-JS" to your own app code.
+1. **No runtime JavaScript in the cia npm package.** Nothing in it is loaded by a page — the Node tooling (`cia` CLI, MCP server, validators) never reaches the browser. JS-augmented UI features (CopyButton handler, future force-mode) ship as separate add-on packages. **This binds the package, not the consumer:** apps built ON cia should write JS/framework components freely (React, SVG charts, interactivity) and use cia only for styling — mixins + tokens. Don't over-apply "zero-JS" to your own app code.
 2. **No `@layer`.** Tier 3 bare-tags use `:where()` (specificity 0,0,0). Cascade pollution kills the consumer experience. Corollary: **the `!important` in the print mixins is load-bearing — do not remove it.** `@media` contributes no specificity, so `print-hidden` only carries the specificity of the selector it is included in, and a later equal-specificity `display` wins in print. `@layer` would make this worse, not better: layered CSS always loses to unlayered CSS, so a layered print rule loses to any unlayered consumer stylesheet. Scope is 8 declarations, all inside `@media print`, all variable-driven (`--print-hide` / `--print-show`).
 3. **No BEM.** No `__element` / `--modifier` chains in cia source. Consumers pick their own selector names — cia has no opinion.
 4. **No Storybook.** Docs site + the `css-is-awesome-mcp` server cover both human and AI audiences.
@@ -104,7 +105,7 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 | Mobile playbook (layouts, dropdown doctrine, lessons) | `src/app/docs/mobile/page.tsx` |
 | Browser support matrix (Baseline floor + progressive tiers) | `src/app/docs/browser-support/page.tsx` |
 | Theme authoring (full walkthrough) | `src/app/docs/authoring/themes/page.tsx` |
-| Theme contract (127 required + 41 optional, machine-readable) | `scripts/theme-contract.json` |
+| Theme contract (127 required + 41 optional grouped into 10 features, machine-readable) | `scripts/theme-contract.json` |
 | Theme pairing (`<link media>` recipe) | `src/app/docs/themes/pairing/page.tsx` |
 | CopyButton JS recipe | `src/app/docs/recipes/copy-button/page.tsx` |
 | Anchor positioning recipe | `src/app/docs/recipes/anchor-positioning/page.tsx` |
@@ -128,7 +129,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`. **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.
+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`. **33 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 41 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling, `validate_theme`, `theme_from_tokens`, `get_token_map` (the design-token → cia-token mapping as data) 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

@@ -20,9 +20,10 @@
  *                  read_three_tiers, read_readme, read_versioning
  *   Sizing:        resolve_size
  *   Themes (build): theme_from_tokens — design-tokens JSON → validated theme.css
+ *                   get_token_map     — the path → token mapping as data (or one path)
  *   Prompt:        assemble_prompt(intent[, args])
  *
- * 32 tools total.
+ * 33 tools total.
  *
  * Discovery model: filesystem scan, no database. Parses SCSS files with
  * focused regex (no full SCSS AST). Tokens come from the authoritative
@@ -426,6 +427,12 @@ function loadTokenContract() {
     return { required: [], optional: [], byName: {}, byCategory: {} };
   }
   const optional = Array.isArray(contract.optional) ? contract.optional : [];
+  // Contract 1.2: optional tokens are grouped by the feature they enable.
+  const features = contract.features && typeof contract.features === 'object' ? contract.features : {};
+  const featureOf = {};
+  for (const [feature, def] of Object.entries(features)) {
+    for (const t of (def && Array.isArray(def.tokens)) ? def.tokens : []) featureOf[t] = feature;
+  }
 
   const byName = {};
   const byCategory = {};
@@ -460,11 +467,11 @@ function loadTokenContract() {
   }
   for (const t of optional) {
     const category = categorize(t);
-    byName[t] = { name: t, category, required: false };
+    byName[t] = { name: t, category, required: false, feature: featureOf[t] || null };
     (byCategory[category] = byCategory[category] || []).push(t);
   }
 
-  return { required: contract.required, optional, byName, byCategory };
+  return { required: contract.required, optional, features, byName, byCategory };
 }
 
 /**
@@ -711,6 +718,25 @@ const handlers = {
     return themeFromTokens({ tokens, name, format, base, dark, mode, validate });
   },
 
+  // The design-token → cia-token mapping theme_from_tokens applies, as DATA:
+  // the explicit table, the prefix rewrites, the generic rule, and the target
+  // token lists — or, with `path`, how one path resolves plus the contract's
+  // view of the target (required/optional + contract-1.2 feature). Exists so
+  // two consumers (an inventory builder, a boilerplate registry) map the same
+  // source token the same way without re-deriving the rules.
+  get_token_map({ path: tokenPath } = {}) {
+    const { tokenMap, resolvePath } = require(path.join(SCRIPTS_DIR, 'tokens-to-theme.cjs'));
+    if (tokenPath == null || tokenPath === '') return tokenMap({ ciaRoot: PROJECT_ROOT });
+    const r = resolvePath(String(tokenPath), { ciaRoot: PROJECT_ROOT });
+    const entry = getTokens().byName[r.token] || null;
+    return {
+      ...r,
+      required: entry ? entry.required : null,
+      feature: entry && !entry.required ? (entry.feature || null) : null,
+      category: entry ? entry.category : null,
+    };
+  },
+
   // ─── Mixins ────────────────────────────────────────────────────────────
 
   list_mixins({ category, component, limit = 500, offset = 0 } = {}) {
@@ -854,6 +880,8 @@ const handlers = {
       name: entry.name,
       category: entry.category,
       required: entry.required,
+      // Contract 1.2: the feature an OPTIONAL token enables (null for required).
+      feature: entry.required ? null : (entry.feature || null),
       themeValues,
       referencedBy: referencedBy.slice(0, 20),
     };
@@ -1388,6 +1416,19 @@ async function startServer() {
     },
   }, async (a) => ok(handlers.theme_from_tokens(a || {})));
 
+  server.registerTool('get_token_map', {
+    description:
+      'The design-token → cia-token mapping that theme_from_tokens applies, as data. Without `path`: ' +
+      '{ generatorVersion, contractVersion, explicit: { "<path>": "--token" }, aliases: [{ pattern, ' +
+      'replaceWith }], genericRule, targets: { required, optional } }. With `path` (e.g. ' +
+      '"color.text.primary"): how that one path resolves — { token, mapped, via, status, required, ' +
+      'feature, category }. Use it to map a Figma / DTCG / Tokens Studio token name to the cia custom ' +
+      'property the same way the converter does, or to check a name before building a theme.',
+    inputSchema: {
+      path: z.string().optional().describe('One token path to resolve (dot-separated, e.g. spacing.4). Omit for the whole map.'),
+    },
+  }, async (a) => ok(handlers.get_token_map(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.17.0",
+  "version": "1.19.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": {

package/scripts/theme-contract.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.1",
-  "description": "Authoritative token contract for css-is-awesome themes. Every theme.css MUST declare every token in `required`. Tokens in `optional` are reported by the validator as info, never as failures \u2014 the library or the theme generator supplies a default. Source of truth is CONTRACT.md (human-readable) and public/theme.css (Sketchbook reference). Contract 1.1 (2026-09-18): --space-unit relaxed from required to optional; it had been added as required in library 1.12.0, which VERSIONING.md forbids in a MINOR.",
+  "version": "1.2",
+  "description": "Authoritative token contract for css-is-awesome themes. Every theme.css MUST declare every token in `required`. Tokens in `optional` are reported by the validator as info, never as failures \u2014 the library or the theme generator supplies a default. Source of truth is CONTRACT.md (human-readable) and public/theme.css (Sketchbook reference). Contract 1.1 (2026-09-18): --space-unit relaxed from required to optional; it had been added as required in library 1.12.0, which VERSIONING.md forbids in a MINOR. Contract 1.2 (2026-09-18): `features` groups every optional token by the capability it enables, so a validator or installer can say \"missing the tokens for print\" instead of listing all optional tokens.",
   "required": [
     "--action-primary-active",
     "--action-primary-default",
@@ -172,5 +172,98 @@
     "--space-xs",
     "--tag-radius",
     "--touch-target-min"
-  ]
+  ],
+  "features": {
+    "density": {
+      "enables": "The density knob: shipped themes derive every --space-N from this one unit via calc(); set it to tighten or open up the whole UI (theme editor slider).",
+      "tokens": [
+        "--space-unit"
+      ]
+    },
+    "spacing-aliases": {
+      "enables": "T-shirt spacing names (2xs\u2013xl) for consumer CSS that prefers them; the library reads the numbered scale, so these are pure aliases.",
+      "tokens": [
+        "--space-2xs",
+        "--space-xs",
+        "--space-sm",
+        "--space-md",
+        "--space-lg",
+        "--space-xl"
+      ]
+    },
+    "print": {
+      "enables": "A themed printed page: cia.print-base rebinds ink/surface/border/code tokens onto this palette inside @media print. Without them the ink-on-white default applies.",
+      "tokens": [
+        "--print-ink",
+        "--print-paper",
+        "--print-line",
+        "--print-muted"
+      ]
+    },
+    "component-radius": {
+      "enables": "Per-component corner radius overrides (buttons, cards, inputs, modals, badges, tags) without rebuilding SCSS; each falls back to the generic --radius-* scale.",
+      "tokens": [
+        "--btn-radius",
+        "--card-radius",
+        "--input-radius",
+        "--modal-radius",
+        "--badge-radius",
+        "--tag-radius"
+      ]
+    },
+    "component-shadows": {
+      "enables": "Per-component elevation overrides; each falls back to the generic --shadow-* scale.",
+      "tokens": [
+        "--shadow-button",
+        "--shadow-card",
+        "--shadow-dropdown",
+        "--shadow-input-focus",
+        "--shadow-modal",
+        "--shadow-popover",
+        "--shadow-tooltip",
+        "--shadow-text"
+      ]
+    },
+    "component-motion": {
+      "enables": "Per-component durations for button hover, modal open and toast slide; each falls back to the generic --duration-* scale.",
+      "tokens": [
+        "--duration-button-hover",
+        "--duration-modal-open",
+        "--duration-toast-slide"
+      ]
+    },
+    "surfaces-extended": {
+      "enables": "Extra background layers (elevated, hero, overlay, scrim) for themes that want more than the required surface set; each falls back to a required surface.",
+      "tokens": [
+        "--background-elevated",
+        "--background-hero",
+        "--background-overlay",
+        "--background-scrim"
+      ]
+    },
+    "borders-extended": {
+      "enables": "Per-context border colours (card, divider, focus ring, input); each falls back to --border-default / --border-focus.",
+      "tokens": [
+        "--border-card",
+        "--border-divider",
+        "--border-focus-ring",
+        "--border-input"
+      ]
+    },
+    "logo": {
+      "enables": "Theme-aware logo assets (default, mark, monochrome, wordmark) as url() or SVG data values for the icon/brand mixins.",
+      "tokens": [
+        "--logo-default",
+        "--logo-mark",
+        "--logo-monochrome",
+        "--logo-wordmark"
+      ]
+    },
+    "touch-target": {
+      "enables": "Minimum interactive target size read by form and button mixins (WCAG 2.2 SC 2.5.8); the library default is 24px.",
+      "tokens": [
+        "--touch-target-min"
+      ]
+    }
+  }
 }

package/scripts/theme-validator.js

@@ -342,7 +342,19 @@ function validateTokenSet(declared, contract) {
   for (const optional of Array.isArray(contract.optional) ? contract.optional : []) {
     if (!declared.has(optional)) optionalMissing.push(optional);
   }
-  return { ok: missing.length === 0, missing, optionalMissing, declaredCount: declared.size };
+  // Contract 1.2: group by the feature each optional token enables, so the
+  // report can say "missing the tokens for print" instead of listing 41 names.
+  const featureOf = {};
+  const features = contract.features && typeof contract.features === 'object' ? contract.features : {};
+  for (const [feature, def] of Object.entries(features)) {
+    for (const t of (def && Array.isArray(def.tokens)) ? def.tokens : []) featureOf[t] = feature;
+  }
+  const optionalMissingByFeature = {};
+  for (const t of optionalMissing) {
+    const f = featureOf[t] || 'other';
+    (optionalMissingByFeature[f] = optionalMissingByFeature[f] || []).push(t);
+  }
+  return { ok: missing.length === 0, missing, optionalMissing, optionalMissingByFeature, declaredCount: declared.size };
 }
 
 // -----------------------------------------------------------
@@ -367,6 +379,7 @@ function validateText(text, contract, options) {
     declaredCount: 0,
     missing: [],
     optionalMissing: [],
+    optionalMissingByFeature: {},
     themes: null,
     a11y: null,
     error: null,
@@ -389,6 +402,7 @@ function validateText(text, contract, options) {
         declaredCount: v.declaredCount,
         missing: v.missing,
         optionalMissing: v.optionalMissing,
+        optionalMissingByFeature: v.optionalMissingByFeature,
         a11y: null,
       };
       if (wantA11y) theme.a11y = a11y.auditThemeTokens({ name: b.name, values: b.values });
@@ -417,6 +431,7 @@ function validateText(text, contract, options) {
   result.declaredCount = v.declaredCount;
   result.missing = v.missing;
   result.optionalMissing = v.optionalMissing;
+  result.optionalMissingByFeature = v.optionalMissingByFeature;
   result.ok = v.ok;
   if (wantA11y) {
     const inferredName = label !== '(pasted CSS)' ? (path.basename(path.dirname(label)) || path.basename(label, '.css')) : 'theme';
@@ -456,11 +471,18 @@ function relForDisplay(p) {
 
 // Optional tokens a theme leaves to the library default. Info only — shown as
 // a count, or listed with --show-optional. Never affects the exit code.
-function optionalInfo(optionalMissing, indent) {
+function optionalInfo(optionalMissing, byFeature, indent) {
   const list = Array.isArray(optionalMissing) ? optionalMissing : [];
   if (!list.length) return;
-  console.log(`${indent}${dim(`i ${list.length} optional token(s) not declared — library default applies`)}`);
-  if (SHOW_OPTIONAL) for (const token of list) console.log(`${indent}    ${dim(token)}`);
+  const groups = byFeature && typeof byFeature === 'object' ? byFeature : {};
+  const summary = Object.entries(groups).map(([f, ts]) => `${f} ${ts.length}`).join(' · ');
+  console.log(`${indent}${dim(`i ${list.length} optional token(s) not declared — library default applies${summary ? ` (${summary})` : ''}`)}`);
+  if (SHOW_OPTIONAL) {
+    for (const [f, ts] of Object.entries(groups)) {
+      console.log(`${indent}    ${dim(f + ':')}`);
+      for (const token of ts) console.log(`${indent}      ${dim(token)}`);
+    }
+  }
 }
 
 function reportResult(result) {
@@ -483,7 +505,7 @@ function reportResult(result) {
         console.log(
           `    ${green('✓')} [data-theme="${t.name}"] ${dim(`(${t.declaredCount} tokens)`)}`
         );
-        optionalInfo(t.optionalMissing, '      ');
+        optionalInfo(t.optionalMissing, t.optionalMissingByFeature, '      ');
       } else {
         const n = t.missing.length;
         console.log(
@@ -502,7 +524,7 @@ function reportResult(result) {
     console.log(
       `${green('✓')} ${bold(rel)} ${dim(`passes (${result.declaredCount} tokens declared)`)}`
     );
-    optionalInfo(result.optionalMissing, '    ');
+    optionalInfo(result.optionalMissing, result.optionalMissingByFeature, '    ');
     return;
   }
 
@@ -583,7 +605,7 @@ function printUsage() {
     '  --all              validate every theme.css under public/ (CI mode)',
     '  --no-a11y          skip the WCAG 2.2 AA contrast audit',
     '  --allow-a11y-fail  do NOT exit non-zero on a11y FAILs (report only)',
-    '  --show-optional    list optional contract tokens a theme leaves to the library default (info only)',
+    '  --show-optional    list optional contract tokens a theme leaves to the library default, grouped by feature (info only)',
     '  --strict           accepted for backwards compatibility (no-op; FAIL is now the default)',
     '',
     'Exit codes:',

package/scripts/tokens-to-theme.cjs

@@ -201,6 +201,46 @@ const TOKEN_MAP = {
   'layer.modal':                    '--z-modal',
   'layer.popover':                  '--z-popover',
   'layer.tooltip':                  '--z-tooltip',
+  // ── Role-named font families (boilerplate / ui-ux-builder layout) ──────
+  // "primary" is the body face, "secondary" the display/heading face.
+  'font.primary':                    '--font-primary',
+  'font.secondary':                  '--font-display',
+  'font.heading':                    '--font-display',
+  'font.body':                       '--font-primary',
+  'typography.font.secondary':       '--font-display',
+  'typography.font.heading':         '--font-display',
+  'typography.family.primary':       '--font-primary',
+  'typography.family.secondary':     '--font-display',
+  'typography.family.heading':       '--font-display',
+
+  // ── component.<name>.<knob> → the contract's per-component overrides ──
+  // (optional tokens, contract 1.2 features component-radius / -shadows /
+  // -motion / borders-extended). `components.` is aliased to `component.`.
+  'component.button.radius':         '--btn-radius',
+  'component.button.shadow':         '--shadow-button',
+  'component.button.duration':       '--duration-button-hover',
+  'component.card.radius':           '--card-radius',
+  'component.card.shadow':           '--shadow-card',
+  'component.card.border':           '--border-card',
+  'component.input.radius':          '--input-radius',
+  'component.input.border':          '--border-input',
+  'component.input.shadow':          '--shadow-input-focus',
+  'component.input.focus-shadow':    '--shadow-input-focus',
+  'component.modal.radius':          '--modal-radius',
+  'component.modal.shadow':          '--shadow-modal',
+  'component.modal.duration':        '--duration-modal-open',
+  'component.badge.radius':          '--badge-radius',
+  'component.tag.radius':            '--tag-radius',
+  'component.chip.radius':           '--tag-radius',
+  'component.dropdown.shadow':       '--shadow-dropdown',
+  'component.popover.shadow':        '--shadow-popover',
+  'component.tooltip.shadow':        '--shadow-tooltip',
+  'component.toast.duration':        '--duration-toast-slide',
+  'component.divider.border':        '--border-divider',
+  'component.divider.color':         '--border-divider',
+  'component.focus.ring':            '--border-focus-ring',
+  'component.text.shadow':           '--shadow-text',
+  'component.touch-target.min':      '--touch-target-min',
 };
 
 // Group-name rewrites applied before the generic rule (rule 2). Case-insensitive
@@ -226,6 +266,9 @@ const PATH_ALIASES = [
   [/^lineHeights?\./i, 'line-height.'],
   [/^durations?\./i, 'duration.'],
   [/^motion\.duration\./i, 'duration.'],
+  [/^font\.family\./, 'font.'],        // font.family.mono → font.mono → --font-mono
+  [/^fontFamily\./, 'font.'],
+  [/^components\./, 'component.'],     // components.button.radius → component.button.radius
 ];
 
 // Token families that are unitless by contract — a bare number stays bare.
@@ -545,6 +588,45 @@ function collect(tokens, format, contract) {
 // ---------------------------------------------------------------------------
 const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 
+// ---------------------------------------------------------------------------
+// The mapping as DATA — so a second implementation (a boilerplate registry,
+// an inventory builder, another agent) can map the same source token the
+// same way this command does, without re-deriving the rules.
+// ---------------------------------------------------------------------------
+const GENERIC_RULE =
+  'If a path is not in `explicit` (checked before and after the alias rewrites), strip/rewrite the ' +
+  'prefix per `aliases` (first matching pattern wins), join the remaining segments with "-", prefix ' +
+  '"--", and lower-case it. If that name is a contract token (required or optional) it is the target. ' +
+  'One retry converts camelCase segments to kebab-case (color.text.linkHover → --text-link-hover). ' +
+  'Otherwise the path is emitted verbatim as --<joined-path> and reported as unmapped — never dropped.';
+
+/** The full path → token mapping as JSON-serialisable data. */
+function tokenMap({ ciaRoot = path.join(__dirname, '..') } = {}) {
+  const contract = loadContract(ciaRoot);
+  return {
+    generatorVersion: GENERATOR_VERSION,
+    contractVersion: contract.version,
+    explicit: { ...TOKEN_MAP },
+    aliases: PATH_ALIASES.map(([re, to]) => ({ pattern: re.source, replaceWith: to })),
+    genericRule: GENERIC_RULE,
+    targets: { required: [...contract.required], optional: [...contract.optional] },
+  };
+}
+
+/** How ONE path resolves, with the contract loaded for the caller. */
+function resolvePath(tokenPath, { ciaRoot = path.join(__dirname, '..') } = {}) {
+  if (typeof tokenPath !== 'string' || !tokenPath.trim()) throw new Error('resolvePath: path is required');
+  const contract = loadContract(ciaRoot);
+  const p = tokenPath.trim();
+  const result = mapPath(p, contract);
+  const via = TOKEN_MAP[p] ? 'explicit'
+    : TOKEN_MAP[applyPathAliases(p)] ? 'explicit-after-alias'
+    : result.mapped ? 'generic' : 'passthrough';
+  const status = contract.required.includes(result.token) ? 'required'
+    : contract.optional.includes(result.token) ? 'optional' : null;
+  return { path: p, token: result.token, mapped: result.mapped, via, status };
+}
+
 function themeFromTokens(opts = {}) {
   const ciaRoot = opts.ciaRoot || CIA_ROOT_DEFAULT;
   const name = String(opts.name || '').trim();
@@ -661,6 +743,8 @@ module.exports = {
   resolveAliases,
   normalizeValue,
   mapPath,
+  tokenMap,
+  resolvePath,
   listBases,
   TOKEN_MAP,
   PATH_ALIASES,