css-is-awesome 1.18.0 → 1.19.1

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]`
@@ -365,7 +365,7 @@ Either way it exposes **32 tools** across 8 families:
   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
+  written. Same function as the MCP `theme_from_tokens` tool; `npx cia theme map [--json] [--path <token.path>]` prints the design-token → cia-token mapping that verb applies (same data as the MCP `get_token_map` tool), for anyone who needs to map one token name the way the converter would. Run any verb with `--help`. (`cia init` remains
   planned.)
 - **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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.19.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.19.0...v1.19.1) (2026-09-23)
+
+
+### Bug Fixes
+
+* **cli:** paired light/dark modes carried only colours; export the in-process entry point ([f1fe71f](https://github.com/Jerry2d3d/css-is-awesome/commit/f1fe71f8a91a8e7bf59e0b9e830585701beb9160))
+
+
+### Features
+
+* **site:** cross-link the posts that explain a browser-support row (B6.4) ([44f40d8](https://github.com/Jerry2d3d/css-is-awesome/commit/44f40d8bf278113a81f7f2b643ad52390fb1af25))
+
+# [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)
 
 

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, the in-browser [Playground](https://cssisawesome.com/playground/), the design-tokens on-ramp (`npx cia theme from-tokens` / `theme map`), 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/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/dist/tokens.d.ts

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

package/llm.txt

@@ -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.
@@ -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:
@@ -197,4 +198,4 @@ Humans first. AI's role is to compose, not to lead the pitch.
 
 ---
 
-*Generated 2026-05-21 for cia v0.8. Updated 2026-05-23 for the v1.0 architecture lock, 2026-08-30 for the theme single-source rework (24 themes, 127+36 contract, themeable spacing, `:root, :root[data-theme]` selector), and 2026-09-04 for the shipped recipes count (5), the mobile-nav mixin family, and the dropdown popover guard. Update when the API surface changes.*
+*Generated 2026-05-21 for cia v0.8. Updated 2026-05-23 for the v1.0 architecture lock, 2026-08-30 for the theme single-source rework (24 themes, 127+36 contract, themeable spacing, `:root, :root[data-theme]` selector), 2026-09-04 for the shipped recipes count (5), the mobile-nav mixin family, and the dropdown popover guard, and 2026-09-19 for the 32-recipe book, 33-tool MCP, contract 1.2 (127 + 41 in 10 features), the playground and the design-tokens on-ramp. Update when the API surface changes.*

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
@@ -33,13 +34,13 @@
  *     "mcpServers": {
  *       "css-is-awesome": {
  *         "command": "node",
- *         "args": ["K:/Repo/css-is-awesome/mcp/server.cjs"]
+ *         "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
  *       }
  *     }
  *   }
  *
- * Aligned with the canonical sibling MCP shape: ui-ux-builder, ideas-master,
- * video-maker. Response envelope is `{ total, items }` for list/search;
+ * Aligned with the canonical sibling MCP shape used across our other servers.
+ * Response envelope is `{ total, items }` for list/search;
  * get_* tools return the full record.
  */
 
@@ -717,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 } = {}) {
@@ -1382,7 +1402,8 @@ async function startServer() {
       '{ "--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 ' +
+      'dropped. Pass `dark` (same format), or one file with paired top-level groups — `light`/`dark` (each a full '
+      + 'token set) or `color-light`/`color-dark` (each a colour set) — 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: {
@@ -1396,6 +1417,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.18.0",
+  "version": "1.19.1",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {
@@ -41,6 +41,10 @@
     "./scss/main": "./scss/main.scss",
     "./scss/tokens": "./scss/tokens.scss",
     "./scss/mixins": "./scss/_mixins.scss",
+    "./scripts/tokens-to-theme.cjs": "./scripts/tokens-to-theme.cjs",
+    "./scripts/tokens-to-theme": "./scripts/tokens-to-theme.cjs",
+    "./scripts/theme-validator.js": "./scripts/theme-validator.js",
+    "./mcp/server.cjs": "./mcp/server.cjs",
     "./scss/generator": "./scss/_generator.scss",
     "./scss/utilities": "./scss/_utilities.scss",
     "./scss/animations": "./scss/_animations.scss",

package/scripts/tokens-to-theme.cjs

@@ -48,8 +48,11 @@
 // 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.
+//   A single file with paired top-level groups is split automatically, and the
+//   two conventions mean different things: `color-light`/`color-dark` name a
+//   COLOUR SET (children are colours), while `light`/`dark` name a MODE whose
+//   group holds a FULL token set — colours, spacing, fonts, component
+//   overrides — which merges beside any groups shared outside the pair.
 //   Without a dark side the block is single-mode: `color-scheme: <mode>`
 //   (`mode`, default light).
 // ============================================================================
@@ -201,6 +204,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 +269,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.
@@ -447,6 +493,17 @@ function applyPathAliases(p) {
 
 /** Returns { token, mapped: true } or { token, mapped: false } (verbatim fallback). */
 function mapPath(tokenPath, contract) {
+  if (typeof tokenPath !== 'string' || !tokenPath.trim()) {
+    throw new Error('mapPath: first argument must be a non-empty token path, e.g. "color.text.primary"');
+  }
+  // The contract is optional: omit it and the installed one is loaded. It used
+  // to be required, but only the generic-rule branch touched it — so a path in
+  // the explicit table appeared to work and the mistake surfaced later as a
+  // TypeError on some other path. Fail clearly or not at all.
+  if (contract == null) contract = loadContract(path.join(__dirname, '..'));
+  else if (!contract.all || typeof contract.all.has !== 'function') {
+    throw new Error('mapPath: second argument must be a contract from loadContract(); omit it to load the installed contract automatically');
+  }
   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 };
@@ -455,6 +512,26 @@ function mapPath(tokenPath, contract) {
   // 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 };
+  // Flat per-component form: `component.btn-radius` → `--btn-radius`. The
+  // explicit table carries the nested shape (`component.button.radius`), and
+  // it is tried first; this catches exporters that flatten the group instead.
+  // Generic-rule first means this can never shadow a real `--component-*`.
+  const flat = aliased.replace(/^components?\./, '');
+  if (flat !== aliased) {
+    const body = flat.replace(/\./g, '-').toLowerCase();
+    // `component.btn-radius` → `--btn-radius`.
+    if (contract.all.has(`--${body}`)) return { token: `--${body}`, mapped: true };
+    // The contract names per-component overrides two ways: radius trails the
+    // component (`--card-radius`) but shadow, border and duration lead it
+    // (`--shadow-card`). A flat exporter cannot know which, so try the swap:
+    // `card-shadow` → `--shadow-card`, `button-hover-duration` →
+    // `--duration-button-hover`. Only accepted if it is a real token.
+    const cut = body.lastIndexOf('-');
+    if (cut > 0) {
+      const swapped = `--${body.slice(cut + 1)}-${body.slice(0, cut)}`;
+      if (contract.all.has(swapped)) return { token: swapped, mapped: true };
+    }
+  }
   return { token: generic, mapped: false };
 }
 
@@ -487,16 +564,35 @@ function loadBase(ciaRoot, base) {
 // ---------------------------------------------------------------------------
 // Paired-mode detection for a single Tokens Studio / DTCG file
 // ---------------------------------------------------------------------------
-const PAIRS = [['color-light', 'color-dark'], ['light', 'dark'], ['colors-light', 'colors-dark']];
+// Two different conventions look alike and must NOT be treated alike:
+//
+//   `color-light` / `color-dark`  name a COLOUR SET. The group's children are
+//        colours (`color-light.brand.primary`), so they nest under `color.`.
+//   `light` / `dark`              name a MODE. The group holds a FULL token
+//        set — `color.*`, `spacing.*`, `font.*`, `component.*` — so its
+//        children merge at the TOP level, beside any shared groups.
+//
+// Wrapping a mode group in `color.` (which this did for every pair until
+// 2026-09-19) silently mis-routed every non-colour group: `spacing.unit`
+// became `color.spacing.unit` → `--spacing-unit`, so the theme lost its
+// density knob while `validation.ok` stayed true, because the required token
+// was quietly inherited from the base theme instead. Reported by a consumer
+// against boilerplate's canonical DTCG layout.
+const PAIRS = [
+  { light: 'color-light', dark: 'color-dark', wrap: 'color' },
+  { light: 'colors-light', dark: 'colors-dark', wrap: 'color' },
+  { light: 'light', dark: 'dark', wrap: null },
+];
 
 function splitPairedModes(tokens) {
   if (!isPlainObject(tokens)) return null;
-  for (const [l, d] of PAIRS) {
+  for (const { light: l, dark: d, wrap } 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] };
+      // Mode-specific groups win over shared ones on a key collision.
+      const light = wrap ? { ...rest, [wrap]: tokens[l] } : { ...rest, ...tokens[l] };
+      const dark = wrap ? { ...rest, [wrap]: tokens[d] } : { ...rest, ...tokens[d] };
       return { light, dark, groups: [l, d] };
     }
   }
@@ -545,6 +641,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 +796,8 @@ module.exports = {
   resolveAliases,
   normalizeValue,
   mapPath,
+  tokenMap,
+  resolvePath,
   listBases,
   TOKEN_MAP,
   PATH_ALIASES,