css-is-awesome 1.16.1 → 1.18.0

package/AGENTS.md

@@ -338,7 +338,7 @@ Or run this in-repo copy directly — needs its SDK peer deps installed manually
 }
 ```
 
-Either way it exposes **31 tools** across 8 families:
+Either way it exposes **32 tools** across 8 families:
 
 - **Themes** — `list_themes`, `get_theme`, `search_themes`
 - **Mixins** — `list_mixins`, `get_mixin`, `search_mixins` (real signatures — don't guess)
@@ -348,11 +348,11 @@ Either way it exposes **31 tools** across 8 families:
 - **Components** — `list_components`, `get_component`, `search_components`
 - **Recipes** — `list_recipes`, `get_recipe`
 - **Doc readers** — `read_llm_txt`, `read_changelog`, `read_migration`, `read_theming`, `read_agents`, `read_contract`, `read_three_tiers`, `read_readme`, `read_versioning`
-- **Helpers** — `assemble_prompt` (bundle context), `resolve_size` (snap a design px value to cia's 4px grid — call this whenever a design tool hands you a raw px value), `validate_theme` (run the real theme validator — contract + contrast — on a CSS string before you ship it)
+- **Helpers** — `assemble_prompt` (bundle context), `resolve_size` (snap a design px value to cia's 4px grid — call this whenever a design tool hands you a raw px value), `validate_theme` (run the real theme validator — contract + contrast — on a CSS string before you ship it), `theme_from_tokens` (DTCG / Tokens Studio / flat token JSON → a complete theme.css, base-inherited and validated; same function as `cia theme from-tokens`)
 
 ## Other tooling (shipped)
 
-- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. Three verbs:
+- **`cia` CLI** — ships as `bin/cia.cjs`, exposed as the `cia` bin. Four verbs:
   `npx cia migrate tailwind|bootstrap [path]` parses another system's config and
   dumps a cia theme; `npx cia add <recipe>` (`--list` to browse) copies a recipe
   from the book into the project — own the pattern; `npx cia analyze [path]`
@@ -360,9 +360,14 @@ Either way it exposes **31 tools** across 8 families:
   the `space()` 1–9 scale trap, off-contract tokens (near-miss typos only), hard-coded
   hex colors, BEM chains — with a health score and CI-ready exit codes. Low-noise on
   color: a hex in a `var(--token, #hex)` fallback is token-driven, and a literal inside
-  `@media print` is an intentional paper colour — neither is flagged. Run any verb with `--help`. (`cia init` remains
+  `@media print` is an intentional paper colour — neither is flagged; `npx cia theme from-tokens <tokens.json> --name <slug>`
+  turns a design-tokens file (DTCG v2025.10, Tokens Studio for Figma, or a flat `--token` map; format auto-detected)
+  into a complete theme.css — every required token the file lacks inherits from a shipped base theme (`--base`,
+  default boilerplate), unmapped paths pass through verbatim and are reported, a `--dark` file or paired
+  `color-light`/`color-dark` groups become `light-dark()`, and the validator + WCAG audit run before anything is
+  written. Same function as the MCP `theme_from_tokens` tool. Run any verb with `--help`. (`cia init` remains
   planned.)
-- **JSON token export** — DTCG-format token list in `figma-tokens/`.
+- **JSON token export** — Tokens Studio-format sample in `figma-tokens/tokens.json`; it round-trips through `cia theme from-tokens` (paired light/dark groups → one `light-dark()` theme).
 - **`llm.txt`** — at the repo root and served from the docs site; single-fetch
   summary for any AI agent. Also readable over MCP via `read_llm_txt`.
 

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+# [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)
+
+
+### Features
+
+* **cli:** cia theme from-tokens — design-tokens JSON → validated theme.css ([066b484](https://github.com/Jerry2d3d/css-is-awesome/commit/066b4849d2e937f0362e8f21cb212f3fcc144c5f))
+* **mcp:** theme_from_tokens tool + in-process handler (32 tools) ([9dc90c4](https://github.com/Jerry2d3d/css-is-awesome/commit/9dc90c40574a5e21b7b724f97792b0fd9c4182b0))
+
 ## [1.16.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.16.0...v1.16.1) (2026-09-18)
 
 

package/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

@@ -14,7 +14,7 @@
 
 **Read [`llm.txt`](./llm.txt) first.** One file, the whole system: install path, hard rules, the mixin vocabulary, and the traps that make agents write wrong cia code. It ships in the npm package, so it's at `node_modules/css-is-awesome/llm.txt` in any project that has cia.
 
-**Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 31 tools covering themes, mixins, functions, tokens, recipes, components and theme validation.
+**Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 32 tools covering themes, mixins, functions, tokens, recipes, components, theme validation and theme generation from design tokens.
 
 ```json
 {
@@ -226,6 +226,10 @@ npx cia analyze src/styles  # design-system health: dead cia.* symbols, the
                             # space() scale trap, off-contract tokens (typos),
                             # off-scale lengths, hard-coded colors, BEM creep,
                             # missing focus-visible styling
+npx cia theme from-tokens tokens.json --name acme --out src/styles/acme.css
+                            # design tokens (DTCG v2025.10, Tokens Studio, or a
+                            # flat --token map) → a complete, validated theme.css;
+                            # missing required tokens inherit from a shipped base
 ```
 
 `cia analyze` reads the real API surface from the installed package and exits non-zero on errors, so it slots straight into CI. It's deliberately low-noise about color: a hex used as a `var(--token, #hex)` fallback is token-driven (not flagged), and a literal inside `@media print` is an intentional paper colour (print escapes theme colours by design). Off-contract-token findings only fire on a **near-miss** of a real token — a typo like `--inkk` — never on your own custom tokens. Off-scale-length findings suggest the nearest named step (e.g. `--radius-md`) for a literal `border-radius`/`padding`/`margin`/`gap` value, as a hint toward using a token — never a claim about your active theme's exact pixel value, since themes are free to set their own numbers (Terminal sets every `--radius-*` to `0`, deliberately). The default output is a **graded report** — a health score, a section per concern (Contract / Spacing / Color / Naming / Layout / API / Accessibility) with a `✓` when clean, and a suggested fix on each finding; add `--verbose` for the flat per-file list or `--json` for the machine shape. Full rule reference: [`/docs/analyzer`](https://cssisawesome.com/docs/analyzer/).
@@ -294,7 +298,7 @@ The scope is kept narrow: 8 `!important` declarations, all inside `@media print`
 
 ## MCP server (for AI agents)
 
-cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **31 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) , `resolve_size` (snap design px values to cia's 4px grid) and `validate_theme` (run the real theme validator on CSS you just wrote). Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **32 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) , `resolve_size` (snap design px values to cia's 4px grid) `validate_theme` (run the real theme validator on CSS you just wrote) and `theme_from_tokens` (design-tokens JSON → a complete, validated theme.css). Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
 
 **Recommended — zero install:** use the dedicated [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package. It depends on `css-is-awesome` and resolves your installed version's real source, so it's never out of sync — and the MCP SDK ships as a real dependency, not an optional peer you have to remember to add.
 
@@ -410,7 +414,7 @@ Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 
 **Stable, [published on npm](https://www.npmjs.com/package/css-is-awesome)** (first published 2026-09-01). The mixin API, functions, token contract, and theme architecture are stable and under strict SemVer — breaking changes require a major bump. See [`VERSIONING.md`](./VERSIONING.md) for the policy.
 
-The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, and the 31-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO JavaScript by hard rule.
+The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, and the 32-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO JavaScript by hard rule.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full history and [MIGRATION.md](./MIGRATION.md) for the v0.7 → v0.8 and v0.8 → v1.0 upgrade paths.
 

package/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

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

package/bin/theme-from-tokens.cjs

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

package/dist/tokens.d.ts

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

package/figma-tokens/README.md

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

package/llm.txt

@@ -48,7 +48,7 @@ silent.
 - **Mixins** — `cia.btn`, `cia.card`, `cia.accordion`, `cia.modal`, `cia.tooltip`, `cia.dropdown`, `cia.tabs`, `cia.copy-button`, `cia.hamburger`, `cia.drawer`, `cia.sheet`, `cia.dock`, `cia.stepper`, `cia.progress`, `cia.wizard-shell`, `cia.sidebar`, `cia.toolbar`, `cia.stack`, `cia.cluster`, `cia.switcher`, `cia.cover`, `cia.frame`, `cia.media`, `cia.contain`, `cia.focus-ring`, `cia.sr-only`, `cia.print`, `cia.print-base`, `cia.print-hidden`, `cia.print-only`, `cia.color`, `cia.space`, `cia.radius`, `cia.shadow`, `cia.font`, `cia.transition`, `cia.animate`, plus many more. **`cia.print-base` always forces `color-scheme: light` in print (paired `light-dark()` themes print their light branch), defines a themeable print palette (`--print-ink` / `--print-paper` / `--print-line` / `--print-muted`, default ink-on-white with grays) and rebinds the theme's own colour tokens (`--ink`, `--surface-*`, `--border-*`, `--code-*`) onto it — so every theme, dark-only (Terminal) included, prints legible ink-on-paper, and overriding a `--print-*` token restyles paper (a letterhead) without touching a component. Three opt-in flags, all default OFF:** `$link-urls` + `$link-origin` (print each link's full destination via `attr(href)`), `$page-numbers` (sheet numbers in the `@page` footer). `$legible` is a DEPRECATED no-op — the token rebind supersedes it and passing it warns.
 - **24 themes / 8 families** — boilerplate, sketchbook, press, prism, cupertino, glass, graphite, terminal. Each family ships three files: an unsuffixed dual-mode base (both modes via `light-dark()`) plus pinned `-light` and `-dark` single-mode variants for `<link media>` pairing. Every one has exactly one SCSS source under `scss/themes/`; `public/themes/<name>/theme.css` is BUILD OUTPUT and is gated against its source by `npm run check:theme-drift` — never hand-edit it. MCP `list_themes` returns **24**. Say **24 themes across 8 families** when you need one number.
 - **6 zero-JS interactive components** — accordion (`<details name>`), modal (`<dialog>`), tooltip (`popover="hint"`), dropdown (`[popover]` — the mixin re-asserts the UA's closed state and restores `display: flex` only under `:popover-open`, so menus never render permanently open on popover markup), tabs (radio + `:has()`), copy-button (Clipboard API via consumer-wired JS).
-- **CLI** (`npx cia`) — `migrate tailwind|bootstrap` (config → cia theme), `add <recipe>` (copy a recipe from the book into the project), `analyze [path]` (audit stylesheets against the installed API: dead `cia.*` symbols, the `space()` 1–9 trap, off-contract tokens (near-miss typos of real tokens only, never your own custom tokens), hard-coded hex, BEM; health score, CI exit codes). Low-noise on color: a hex in a `var(--token, #hex)` fallback is token-driven and a literal inside `@media print` is an intentional paper colour — neither is flagged.
+- **CLI** (`npx cia`) — `migrate tailwind|bootstrap|mui|chakra` (config → cia theme), `theme from-tokens <tokens.json> --name <slug>` (DTCG v2025.10 / Tokens Studio / flat `--token` JSON → a complete theme.css: required tokens the file lacks inherit from a shipped base, unmapped paths pass through and are reported, light/dark pairs become `light-dark()`, validator + WCAG audit run first; same function as the MCP `theme_from_tokens` tool), `add <recipe>` (copy a recipe from the book into the project), `analyze [path]` (audit stylesheets against the installed API: dead `cia.*` symbols, the `space()` 1–9 trap, off-contract tokens (near-miss typos of real tokens only, never your own custom tokens), hard-coded hex, BEM; health score, CI exit codes). Low-noise on color: a hex in a `var(--token, #hex)` fallback is token-driven and a literal inside `@media print` is an intentional paper colour — neither is flagged.
 - **Mobile navigation family** — `cia.hamburger` / `cia.drawer` / `cia.sheet` / `cia.dock` ride `[popover]` + CSS Grid, zero JS; recipes `mobile-nav` (hamburger + drawer) and `bottom-nav` (dock + sheets). House rule: **on phones things take the space they're in** — a `cia.dropdown` menu opens 1px under its full-width trigger at the trigger's exact width via CSS anchor positioning (`position-try-fallbacks: flip-block` flips it above at the screen bottom; set `width: auto` at `&[popover]` specificity or the UA's `[popover] { width: fit-content }` and the mixin's inset reset win). Full spec: AGENTS.md quick decision #8 and `/docs/mobile`.
 - **168 contract tokens — 127 required + 41 optional** — surfaces, ink, lines, colors, type, radius, shadow, blur, glow, motion, z-index, spacing, semantic aliases.
 - **Spacing is themeable, and the numbered scale is the knob.** Themes declare `--space-0` … `--space-9` (contract-required). The t-shirt names (`--space-md`, `--space-lg` …) are contract-OPTIONAL and emitted by the library as `var()` aliases onto the numbered steps. `space(4)` compiles to `var(--space-4)`, so **theme the numbered step, never the alias** — setting `--space-md` alone leaves every component untouched. Library defaults emit under `:where(:root)` (specificity 0,0,0) so any theme declaration outranks them regardless of load order.
@@ -104,7 +104,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 +128,7 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 
 ## MCP server (shipped 2026-05-22)
 
-cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`, included in the `files` manifest — so it lands in every consumer's `node_modules`. **30 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 36 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling and `resolve_size` for snapping design px values to cia's 4px geometric grid (AI agents: call this whenever you receive a px value from a design tool). Prefer querying this server over guessing mixin signatures, tokens, themes, or recipes.
+cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`, included in the `files` manifest — so it lands in every consumer's `node_modules`. **32 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 36 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling and `resolve_size` for snapping design px values to cia's 4px geometric grid (AI agents: call this whenever you receive a px value from a design tool). Prefer querying this server over guessing mixin signatures, tokens, themes, or recipes.
 
 **Recommended: suggest the dedicated `css-is-awesome-mcp` package** — zero install,
 SDK ships as a real dependency, no separate peer-install step:

package/mcp/server.cjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {
@@ -69,6 +69,7 @@
     "mcp",
     "scripts/theme-contract.json",
     "scripts/theme-validator.js",
+    "scripts/tokens-to-theme.cjs",
     "scripts/theme-a11y.js",
     "scripts/audit-pairs.json",
     "scripts/icon-validator.js",
@@ -117,6 +118,7 @@
     "validate-api": "node scripts/validate-api.mjs",
     "validate-package": "node scripts/validate-package.mjs",
     "validate-recipes": "node scripts/validate-recipes.mjs",
+    "test:tokens": "node --test scripts/test-tokens-to-theme.mjs",
     "size-budget": "node scripts/size-budget.mjs",
     "size-report": "node scripts/size-budget.mjs --report",
     "coverage:api": "node scripts/api-coverage.mjs",

package/scripts/theme-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"
+      ]
+    }
+  }
 }