css-is-awesome 1.16.0 → 1.17.0

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-17.
+// 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. */
@@ -94,7 +94,6 @@ export type CiaToken =
   | "--shadow-xl"
   | "--shu"
   | "--shu-wash"
-  | "--space-unit"
   | "--space-0"
   | "--space-1"
   | "--space-2"
@@ -225,7 +224,6 @@ export interface CiaTokenMap {
   "--shadow-xl": string;
   "--shu": string;
   "--shu-wash": string;
-  "--space-unit": string;
   "--space-0": string;
   "--space-1": string;
   "--space-2": string;
@@ -265,4 +263,4 @@ export interface CiaTokenMap {
 }
 
 /** Count of required tokens in the current contract. */
-export declare const CIA_TOKEN_COUNT: 128;
+export declare const CIA_TOKEN_COUNT: 127;

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,9 +48,9 @@ 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`.
-- **163 contract tokens — 127 required + 36 optional** — surfaces, ink, lines, colors, type, radius, shadow, blur, glow, motion, z-index, spacing, semantic aliases.
+- **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.
 - **Per-component shape knobs are `--btn-radius`, `--card-radius`, `--input-radius`, `--modal-radius`, `--badge-radius`, `--tag-radius`** — they cascade from the generic radii (`--btn-radius: var(--radius-md, 0.25rem)`). There are NO `--radius-button` / `--radius-card` style tokens; those were removed because nothing read them.
 - **Icons — two systems.** `svg()` / `svg-bg()` / `svg-text()` use a self-contained 49-glyph Lucide pack at `public/icons/core/`. Adding a glyph is drop-in: put `star.svg` in the folder and `cia.icon-svg(star)` works, no registration. Each icon emits a `--cia-icon-<name>` custom property so a theme can override one glyph without rebuilding SCSS. **`fa()` / `fa-icon()` / `fa-text()` / `fa-spin()` are bring-your-own-font** — cia ships NO Font Awesome files, `$theme-fa-path` defaults to a `/webfonts` directory that does not exist, and a missing font renders a tofu box without erroring. Default to `svg()` unless the user says they use Font Awesome.
@@ -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 + 36 optional, machine-readable) | `scripts/theme-contract.json` |
+| Theme contract (127 required + 41 optional, 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
@@ -698,6 +699,18 @@ const handlers = {
     return validateText(css, loadContract(), { label: label || undefined });
   },
 
+  // Design-tokens JSON (DTCG v2025.10 / Tokens Studio / flat --token map) →
+  // a complete theme.css in the shipped shape, validated + contrast-audited.
+  // Same function as `cia theme from-tokens`; reachable in-process through
+  // module.exports.handlers so an inventory builder can call it without a
+  // transport. See scripts/tokens-to-theme.cjs for the input contract.
+  theme_from_tokens({ tokens, name, format, base, dark, mode, validate } = {}) {
+    if (tokens == null) throw new Error('theme_from_tokens: tokens is required (object or JSON string)');
+    if (!name) throw new Error('theme_from_tokens: name is required');
+    const { themeFromTokens } = require(path.join(SCRIPTS_DIR, 'tokens-to-theme.cjs'));
+    return themeFromTokens({ tokens, name, format, base, dark, mode, validate });
+  },
+
   // ─── Mixins ────────────────────────────────────────────────────────────
 
   list_mixins({ category, component, limit = 500, offset = 0 } = {}) {
@@ -1354,6 +1367,27 @@ async function startServer() {
     },
   }, async (a) => ok(handlers.validate_theme(a || {})));
 
+  server.registerTool('theme_from_tokens', {
+    description:
+      'Build a complete, validated cia theme.css from a design-tokens JSON — DTCG v2025.10 ({ $value, $type }, ' +
+      '{aliases} resolved), a Tokens Studio for Figma export ({ value, type }, single or multi-set), or a flat ' +
+      '{ "--token": value } map. Format is auto-detected. Every REQUIRED contract token the file does not supply ' +
+      'is inherited from a shipped base theme (default boilerplate) and listed in report.inherited, so the output ' +
+      'is always contract-complete; unmapped paths are emitted verbatim and listed in report.unmapped, never ' +
+      'dropped. Pass `dark` (same format) or a single file with paired color-light/color-dark groups to get ' +
+      'light-dark() values. Returns { css, report, validation } — validation is the same result validate_theme ' +
+      'gives, run on the CSS before you write it anywhere.',
+    inputSchema: {
+      tokens: z.union([z.record(z.any()), z.string()]).describe('The tokens JSON (object, or a JSON string).'),
+      name: z.string().describe('Theme name — kebab-case slug, becomes [data-theme="<name>"].'),
+      format: z.enum(['auto', 'dtcg', 'tokens-studio', 'cia-flat']).optional().describe('Default auto.'),
+      base: z.string().optional().describe('Shipped theme that supplies missing required tokens. Default boilerplate.'),
+      dark: z.union([z.record(z.any()), z.string()]).optional().describe('Optional dark-mode tokens (same format) → light-dark() values.'),
+      mode: z.enum(['light', 'dark']).optional().describe('Single-mode color-scheme when there is no dark side. Default light.'),
+      validate: z.boolean().optional().describe('Run the validator + WCAG audit (default true).'),
+    },
+  }, async (a) => ok(handlers.theme_from_tokens(a || {})));
+
   // Mixins
   server.registerTool('list_mixins', {
     description: `List all ${MIXIN_COUNT} public @mixins across core, layout, animation, icons, generator, per-component and recipe sources. Filter by category (core/layout/animation/icons/generator/component/recipe) or component name.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {
@@ -69,6 +69,7 @@
     "mcp",
     "scripts/theme-contract.json",
     "scripts/theme-validator.js",
+    "scripts/tokens-to-theme.cjs",
     "scripts/theme-a11y.js",
     "scripts/audit-pairs.json",
     "scripts/icon-validator.js",
@@ -90,7 +91,6 @@
     "THEMING.md",
     "MIGRATION.md",
     "CONTRACT.md",
-    "ROADMAP.md",
     "VERSIONING.md",
     "scripts/prepare-dist.mjs"
   ],
@@ -118,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",
@@ -130,8 +131,11 @@
     "prepare": "node scripts/prepare-dist.mjs",
     "prepublishOnly": "npm run build:css:all",
     "check:theme-drift": "node scripts/check-theme-drift.mjs",
+    "check:contract": "node scripts/check-contract-growth.mjs",
     "check:token-consumers": "node scripts/check-token-consumer-map.mjs",
-    "check:rtl": "node scripts/audit-logical-properties.mjs"
+    "check:rtl": "node scripts/audit-logical-properties.mjs",
+    "prebuild": "node scripts/build-playground-scss-map.mjs",
+    "verify:playground": "node scripts/build-playground-scss-map.mjs && node scripts/verify-playground-compile.mjs"
   },
   "keywords": [
     "css",
@@ -172,6 +176,12 @@
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.11.2",
+    "@codemirror/commands": "6.11.1",
+    "@codemirror/lang-html": "6.4.12",
+    "@codemirror/lang-sass": "6.0.2",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/state": "6.7.5",
+    "@codemirror/view": "6.43.12",
     "@eslint/eslintrc": "^3.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@playwright/test": "^1.59.1",

package/scripts/theme-contract.json

@@ -1,6 +1,6 @@
 {
-  "version": "1",
-  "description": "Authoritative token contract for css-is-awesome themes. Every theme.css MUST declare every token in `required`. Source of truth is CONTRACT.md (human-readable) and public/theme.css (Sketchbook reference).",
+  "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.",
   "required": [
     "--action-primary-active",
     "--action-primary-default",
@@ -93,7 +93,6 @@
     "--shadow-xl",
     "--shu",
     "--shu-wash",
-    "--space-unit",
     "--space-0",
     "--space-1",
     "--space-2",
@@ -168,6 +167,7 @@
     "--space-lg",
     "--space-md",
     "--space-sm",
+    "--space-unit",
     "--space-xl",
     "--space-xs",
     "--tag-radius",

package/scripts/theme-validator.js

@@ -334,7 +334,15 @@ function validateTokenSet(declared, contract) {
   for (const required of contract.required) {
     if (!declared.has(required)) missing.push(required);
   }
-  return { ok: missing.length === 0, missing, declaredCount: declared.size };
+  // Optional tokens (contract 1.1+) are reported as INFO, never as failures:
+  // the library or the theme generator supplies a default for each of them.
+  // `--space-unit` is the canonical case — it was wrongly listed as required
+  // in 1.12.0–1.16.0 and broke every consumer's custom theme on a MINOR.
+  const optionalMissing = [];
+  for (const optional of Array.isArray(contract.optional) ? contract.optional : []) {
+    if (!declared.has(optional)) optionalMissing.push(optional);
+  }
+  return { ok: missing.length === 0, missing, optionalMissing, declaredCount: declared.size };
 }
 
 // -----------------------------------------------------------
@@ -358,6 +366,7 @@ function validateText(text, contract, options) {
     ok: false,
     declaredCount: 0,
     missing: [],
+    optionalMissing: [],
     themes: null,
     a11y: null,
     error: null,
@@ -379,6 +388,7 @@ function validateText(text, contract, options) {
         ok: v.ok,
         declaredCount: v.declaredCount,
         missing: v.missing,
+        optionalMissing: v.optionalMissing,
         a11y: null,
       };
       if (wantA11y) theme.a11y = a11y.auditThemeTokens({ name: b.name, values: b.values });
@@ -406,6 +416,7 @@ function validateText(text, contract, options) {
   const v = validateTokenSet(root.tokens, contract);
   result.declaredCount = v.declaredCount;
   result.missing = v.missing;
+  result.optionalMissing = v.optionalMissing;
   result.ok = v.ok;
   if (wantA11y) {
     const inferredName = label !== '(pasted CSS)' ? (path.basename(path.dirname(label)) || path.basename(label, '.css')) : 'theme';
@@ -443,6 +454,15 @@ function relForDisplay(p) {
   return rel || p;
 }
 
+// Optional tokens a theme leaves to the library default. Info only — shown as
+// a count, or listed with --show-optional. Never affects the exit code.
+function optionalInfo(optionalMissing, indent) {
+  const list = Array.isArray(optionalMissing) ? optionalMissing : [];
+  if (!list.length) return;
+  console.log(`${indent}${dim(`i ${list.length} optional token(s) not declared — library default applies`)}`);
+  if (SHOW_OPTIONAL) for (const token of list) console.log(`${indent}    ${dim(token)}`);
+}
+
 function reportResult(result) {
   const rel = relForDisplay(result.file);
 
@@ -463,6 +483,7 @@ function reportResult(result) {
         console.log(
           `    ${green('✓')} [data-theme="${t.name}"] ${dim(`(${t.declaredCount} tokens)`)}`
         );
+        optionalInfo(t.optionalMissing, '      ');
       } else {
         const n = t.missing.length;
         console.log(
@@ -481,6 +502,7 @@ function reportResult(result) {
     console.log(
       `${green('✓')} ${bold(rel)} ${dim(`passes (${result.declaredCount} tokens declared)`)}`
     );
+    optionalInfo(result.optionalMissing, '    ');
     return;
   }
 
@@ -561,6 +583,7 @@ function printUsage() {
     '  --all              validate every theme.css under public/ (CI mode)',
     '  --no-a11y          skip the WCAG 2.2 AA contrast audit',
     '  --allow-a11y-fail  do NOT exit non-zero on a11y FAILs (report only)',
+    '  --show-optional    list optional contract tokens a theme leaves to the library default (info only)',
     '  --strict           accepted for backwards compatibility (no-op; FAIL is now the default)',
     '',
     'Exit codes:',
@@ -573,8 +596,11 @@ function printUsage() {
   console.log(u);
 }
 
+let SHOW_OPTIONAL = false;
+
 function main(argv) {
   const argsRaw = argv.slice(2).filter(function (a) { return a !== '--watch'; });
+  SHOW_OPTIONAL = argsRaw.includes('--show-optional');
   if (argsRaw.length === 0 || argsRaw.includes('-h') || argsRaw.includes('--help')) {
     printUsage();
     process.exit(argsRaw.length === 0 ? 2 : 0);
@@ -583,7 +609,7 @@ function main(argv) {
   const wantLenient = argsRaw.includes('--allow-a11y-fail');
   // --strict is accepted as a no-op for backwards compatibility — a11y FAIL is now the default
   const args = argsRaw.filter(function (a) {
-    return a !== '--no-a11y' && a !== '--strict' && a !== '--allow-a11y-fail';
+    return a !== '--no-a11y' && a !== '--strict' && a !== '--allow-a11y-fail' && a !== '--show-optional';
   });
 
   const contract = loadContract();
@@ -687,6 +713,10 @@ module.exports = {
   validateFile,
   validateText,
   loadContract,
+  // Reporters — reused by `cia theme from-tokens` so its output reads exactly
+  // like `npm run validate-themes`.
+  reportResult,
+  reportA11yForTheme,
   a11y: a11y,
 };