css-is-awesome 1.16.0 → 1.17.0

package/AGENTS.md

@@ -148,7 +148,7 @@ Authoring template (in your own project — a theme file is a global stylesheet,
 
 `$standalone` defaults to `true` (emit `:root, :root[data-theme="<name>"]`). Pass `$standalone: false` only when your block is going into a multi-theme bundle where the bare `:root` would collide.
 
-The validator (`node scripts/theme-validator.js`) enforces the token contract — **127 required + 36 optional = 163 slots** — plus WCAG 2.2 AA contrast (**22 audited pairs per theme**, including five `--code-*` pairs). Themes that miss required tokens or fail contrast cannot ship without `--allow-a11y-fail`.
+The validator (`node scripts/theme-validator.js`) enforces the token contract — **127 required + 41 optional = 168 slots** — plus WCAG 2.2 AA contrast (**22 audited pairs per theme**, including five `--code-*` pairs). Themes that miss required tokens or fail contrast cannot ship without `--allow-a11y-fail`.
 
 ### Theming spacing (new — read this before you set a size token)
 
@@ -168,7 +168,7 @@ Why it matters: components call `cia.space(4)`, which resolves to `var(--space-4
 
 Two `<link media>` themes still work under the new selector model: a stylesheet whose `media` doesn't match is loaded but never applied, so only the matching file's `:root` block lands.
 
-Validator: `node scripts/theme-validator.js path/to/theme.css` (or `--all` for every shipped theme). Every theme must declare every required contract token (127 required in v1; missing tokens always fail). The audit also runs a WCAG 2.2 AA contrast check over 22 pairs; **a11y FAILs are fatal by default** as of v0.7. Pass `--allow-a11y-fail` to downgrade contrast failures to a report-only warning (the older `--strict` flag is accepted as a no-op alias). `--border-default` is treated as decorative per WCAG 2.2 SC 1.4.11 and reports as info, not FAIL.
+Validator: `node scripts/theme-validator.js path/to/theme.css` (or `--all` for every shipped theme). Every theme must declare every required contract token (127 required in contract 1.1; missing required tokens always fail, missing optional ones are reported as info). The audit also runs a WCAG 2.2 AA contrast check over 22 pairs; **a11y FAILs are fatal by default** as of v0.7. Pass `--allow-a11y-fail` to downgrade contrast failures to a report-only warning (the older `--strict` flag is accepted as a no-op alias). `--border-default` is treated as decorative per WCAG 2.2 SC 1.4.11 and reports as info, not FAIL.
 
 ### Theme init (Next.js / SSR consumers)
 
@@ -338,21 +338,21 @@ 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)
 - **Functions** — `list_functions`, `get_function`, `search_functions`
-- **Tokens** — `list_tokens`, `get_token`, `search_tokens` (127 required + 36 optional contract tokens)
+- **Tokens** — `list_tokens`, `get_token`, `search_tokens` (127 required + 41 optional contract tokens)
 - **Animations** — `list_animations`, `get_animation`
 - **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,3 +1,28 @@
+# Changelog
+
+# [1.17.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.16.1...v1.17.0) (2026-09-19)
+
+
+### Features
+
+* **cli:** cia theme from-tokens — design-tokens JSON → validated theme.css ([066b484](https://github.com/Jerry2d3d/css-is-awesome/commit/066b4849d2e937f0362e8f21cb212f3fcc144c5f))
+* **mcp:** theme_from_tokens tool + in-process handler (32 tools) ([9dc90c4](https://github.com/Jerry2d3d/css-is-awesome/commit/9dc90c40574a5e21b7b724f97792b0fd9c4182b0))
+
+## [1.16.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.16.0...v1.16.1) (2026-09-18)
+
+
+### Bug Fixes
+
+* **contract:** --space-unit is optional, not required — contract 1.1 + CI growth gate ([42292ff](https://github.com/Jerry2d3d/css-is-awesome/commit/42292ff995a3e6d7fa1623404614f3519e30a284))
+
+
+### Features
+
+* **site:** "Try in playground" on every recipe page ([9d2c7cc](https://github.com/Jerry2d3d/css-is-awesome/commit/9d2c7cc18399ff0c55c5c986ed70bdd9b6e1ddb5))
+* **site:** /playground — in-browser Sass compile, CodeMirror panes, live preview ([c1474e4](https://github.com/Jerry2d3d/css-is-awesome/commit/c1474e40bfecaa7bd7b742ca545bf7f8f6756021))
+* **site:** link the playground from the nav, the docs intro and the README ([9acabcc](https://github.com/Jerry2d3d/css-is-awesome/commit/9acabcc66f84e30f83cc8a7ff01e4845635ee2c4))
+* **site:** playground groundwork — scss source map, [@use](https://github.com/use) resolver, share codec ([f5fb619](https://github.com/Jerry2d3d/css-is-awesome/commit/f5fb619d5b3d11dff9c77beeb77cd192b4b6d090))
+
 # [1.16.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.15.0...v1.16.0) (2026-09-17)
 
 
@@ -400,132 +425,17 @@
 * **site:** print the story, not the chrome — dogfoods cia's print mixins ([ece519c](https://github.com/Jerry2d3d/css-is-awesome/commit/ece519c43f62230e1b3392538dae5148fc31ddf6))
 * **themes:** themes own the spacing rhythm, not just the palette ([4bc1e24](https://github.com/Jerry2d3d/css-is-awesome/commit/4bc1e24f1b64f33cacd35f3bab12327019634fea))
 
-# [1.1.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.0.0...v1.1.0) (2026-09-01)
-
-
-### Bug Fixes
-
-* **a11y:** copy button used code-surface ink on a page-surface background ([bf84bf4](https://github.com/Jerry2d3d/css-is-awesome/commit/bf84bf4d6c23e3ebafdb5dc98a303d9961d68714))
-* **a11y:** validator ignored unquoted [data-theme]; grade the code palette ([2437f41](https://github.com/Jerry2d3d/css-is-awesome/commit/2437f4182ddccc01b372d9aacd898b6222fcabd3)), closes [#fafafa](https://github.com/Jerry2d3d/css-is-awesome/issues/fafafa) [#0a0a0a](https://github.com/Jerry2d3d/css-is-awesome/issues/0a0a0a)
-* **ci:** snapshot job installed chromium but ran all three engines ([f7b7fc9](https://github.com/Jerry2d3d/css-is-awesome/commit/f7b7fc9e29883863c6a525f44391e6eb4b4b9662))
-* **ci:** snapshot workflow silently discarded the baselines it created ([3358cac](https://github.com/Jerry2d3d/css-is-awesome/commit/3358cacb6fbf88d9dcf0109597bed301efeda483))
-* **compare:** correct every measurable claim on the comparison page ([3d1b602](https://github.com/Jerry2d3d/css-is-awesome/commit/3d1b602ff6074712a2e2d0aea5a1ad27128d2d70))
-* **pkg:** build dist/ on git installs via a prepare hook ([1a0deb1](https://github.com/Jerry2d3d/css-is-awesome/commit/1a0deb19e4fc6de15b7b3530847779920d01d784))
-* **print:** stop the freeze from flattening deliberate opacity and transform ([1af51d2](https://github.com/Jerry2d3d/css-is-awesome/commit/1af51d2e3a08cd61e51ac3b857eeaa261afd044e))
-* root barrel emitted no tokens; retract the false Turbopack claim ([d7f71e3](https://github.com/Jerry2d3d/css-is-awesome/commit/d7f71e366a1ef4b918cfcfd6dafcba8d352afcb5))
-* **sass:** stop using the deprecated if() function; sharpen the AI on-ramp ([61df05a](https://github.com/Jerry2d3d/css-is-awesome/commit/61df05a31228fce169664690c2562d128bf06958))
-* **site:** moat card uses grid; Tailwind sample updated to Headless UI v2 ([cb39e44](https://github.com/Jerry2d3d/css-is-awesome/commit/cb39e44b4eb8d7ab1a86377c1d828b1cde3ed58b))
-* **site:** moat code blocks now fill their card ([8e53d35](https://github.com/Jerry2d3d/css-is-awesome/commit/8e53d355b0f9279125b9dfd6f913851cf2ebcdc3))
-* six upstream bugs from the Boiler audit (BUG-1..7) ([84f4c4f](https://github.com/Jerry2d3d/css-is-awesome/commit/84f4c4fc6f6259bf74541a833fe0ad343821ab12))
-* **themes:** prism was missing from every theme picker ([4ce4f5f](https://github.com/Jerry2d3d/css-is-awesome/commit/4ce4f5f8a696728b513aa1adc148b33c5808e26e))
-
-
-### Features
-
-* **animate:** accept a raw duration; add letter-spacing() coverage fixture ([25b7cd6](https://github.com/Jerry2d3d/css-is-awesome/commit/25b7cd6cbc09d76b51c9dd0b74077ec1af78c327))
-* **blog:** real posts from real commits, replacing seven dead stubs ([f37c5be](https://github.com/Jerry2d3d/css-is-awesome/commit/f37c5be94cd64f99548a6a119820325d559e6920))
-* **site:** print the story, not the chrome — dogfoods cia's print mixins ([ece519c](https://github.com/Jerry2d3d/css-is-awesome/commit/ece519c43f62230e1b3392538dae5148fc31ddf6))
-* **themes:** themes own the spacing rhythm, not just the palette ([4bc1e24](https://github.com/Jerry2d3d/css-is-awesome/commit/4bc1e24f1b64f33cacd35f3bab12327019634fea))
-
-# [1.1.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.0.0...v1.1.0) (2026-09-01)
-
-
-### Bug Fixes
-
-* **a11y:** copy button used code-surface ink on a page-surface background ([bf84bf4](https://github.com/Jerry2d3d/css-is-awesome/commit/bf84bf4d6c23e3ebafdb5dc98a303d9961d68714))
-* **a11y:** validator ignored unquoted [data-theme]; grade the code palette ([2437f41](https://github.com/Jerry2d3d/css-is-awesome/commit/2437f4182ddccc01b372d9aacd898b6222fcabd3)), closes [#fafafa](https://github.com/Jerry2d3d/css-is-awesome/issues/fafafa) [#0a0a0a](https://github.com/Jerry2d3d/css-is-awesome/issues/0a0a0a)
-* **ci:** snapshot job installed chromium but ran all three engines ([f7b7fc9](https://github.com/Jerry2d3d/css-is-awesome/commit/f7b7fc9e29883863c6a525f44391e6eb4b4b9662))
-* **ci:** snapshot workflow silently discarded the baselines it created ([3358cac](https://github.com/Jerry2d3d/css-is-awesome/commit/3358cacb6fbf88d9dcf0109597bed301efeda483))
-* **compare:** correct every measurable claim on the comparison page ([3d1b602](https://github.com/Jerry2d3d/css-is-awesome/commit/3d1b602ff6074712a2e2d0aea5a1ad27128d2d70))
-* **pkg:** build dist/ on git installs via a prepare hook ([1a0deb1](https://github.com/Jerry2d3d/css-is-awesome/commit/1a0deb19e4fc6de15b7b3530847779920d01d784))
-* **print:** stop the freeze from flattening deliberate opacity and transform ([1af51d2](https://github.com/Jerry2d3d/css-is-awesome/commit/1af51d2e3a08cd61e51ac3b857eeaa261afd044e))
-* root barrel emitted no tokens; retract the false Turbopack claim ([d7f71e3](https://github.com/Jerry2d3d/css-is-awesome/commit/d7f71e366a1ef4b918cfcfd6dafcba8d352afcb5))
-* **sass:** stop using the deprecated if() function; sharpen the AI on-ramp ([61df05a](https://github.com/Jerry2d3d/css-is-awesome/commit/61df05a31228fce169664690c2562d128bf06958))
-* **site:** moat card uses grid; Tailwind sample updated to Headless UI v2 ([cb39e44](https://github.com/Jerry2d3d/css-is-awesome/commit/cb39e44b4eb8d7ab1a86377c1d828b1cde3ed58b))
-* **site:** moat code blocks now fill their card ([8e53d35](https://github.com/Jerry2d3d/css-is-awesome/commit/8e53d355b0f9279125b9dfd6f913851cf2ebcdc3))
-* six upstream bugs from the Boiler audit (BUG-1..7) ([84f4c4f](https://github.com/Jerry2d3d/css-is-awesome/commit/84f4c4fc6f6259bf74541a833fe0ad343821ab12))
-* **themes:** prism was missing from every theme picker ([4ce4f5f](https://github.com/Jerry2d3d/css-is-awesome/commit/4ce4f5f8a696728b513aa1adc148b33c5808e26e))
-
-
-### Features
-
-* **animate:** accept a raw duration; add letter-spacing() coverage fixture ([25b7cd6](https://github.com/Jerry2d3d/css-is-awesome/commit/25b7cd6cbc09d76b51c9dd0b74077ec1af78c327))
-* **blog:** real posts from real commits, replacing seven dead stubs ([f37c5be](https://github.com/Jerry2d3d/css-is-awesome/commit/f37c5be94cd64f99548a6a119820325d559e6920))
-* **site:** print the story, not the chrome — dogfoods cia's print mixins ([ece519c](https://github.com/Jerry2d3d/css-is-awesome/commit/ece519c43f62230e1b3392538dae5148fc31ddf6))
-* **themes:** themes own the spacing rhythm, not just the palette ([4bc1e24](https://github.com/Jerry2d3d/css-is-awesome/commit/4bc1e24f1b64f33cacd35f3bab12327019634fea))
-
-# [1.1.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.0.0...v1.1.0) (2026-08-30)
-
-
-### Bug Fixes
-
-* **a11y:** copy button used code-surface ink on a page-surface background ([bf84bf4](https://github.com/Jerry2d3d/css-is-awesome/commit/bf84bf4d6c23e3ebafdb5dc98a303d9961d68714))
-* **a11y:** validator ignored unquoted [data-theme]; grade the code palette ([2437f41](https://github.com/Jerry2d3d/css-is-awesome/commit/2437f4182ddccc01b372d9aacd898b6222fcabd3)), closes [#fafafa](https://github.com/Jerry2d3d/css-is-awesome/issues/fafafa) [#0a0a0a](https://github.com/Jerry2d3d/css-is-awesome/issues/0a0a0a)
-* **ci:** snapshot job installed chromium but ran all three engines ([f7b7fc9](https://github.com/Jerry2d3d/css-is-awesome/commit/f7b7fc9e29883863c6a525f44391e6eb4b4b9662))
-* **ci:** snapshot workflow silently discarded the baselines it created ([3358cac](https://github.com/Jerry2d3d/css-is-awesome/commit/3358cacb6fbf88d9dcf0109597bed301efeda483))
-* **compare:** correct every measurable claim on the comparison page ([3d1b602](https://github.com/Jerry2d3d/css-is-awesome/commit/3d1b602ff6074712a2e2d0aea5a1ad27128d2d70))
-* **pkg:** build dist/ on git installs via a prepare hook ([1a0deb1](https://github.com/Jerry2d3d/css-is-awesome/commit/1a0deb19e4fc6de15b7b3530847779920d01d784))
-* **print:** stop the freeze from flattening deliberate opacity and transform ([1af51d2](https://github.com/Jerry2d3d/css-is-awesome/commit/1af51d2e3a08cd61e51ac3b857eeaa261afd044e))
-* root barrel emitted no tokens; retract the false Turbopack claim ([d7f71e3](https://github.com/Jerry2d3d/css-is-awesome/commit/d7f71e366a1ef4b918cfcfd6dafcba8d352afcb5))
-* **sass:** stop using the deprecated if() function; sharpen the AI on-ramp ([61df05a](https://github.com/Jerry2d3d/css-is-awesome/commit/61df05a31228fce169664690c2562d128bf06958))
-* **site:** moat card uses grid; Tailwind sample updated to Headless UI v2 ([cb39e44](https://github.com/Jerry2d3d/css-is-awesome/commit/cb39e44b4eb8d7ab1a86377c1d828b1cde3ed58b))
-* **site:** moat code blocks now fill their card ([8e53d35](https://github.com/Jerry2d3d/css-is-awesome/commit/8e53d355b0f9279125b9dfd6f913851cf2ebcdc3))
-* six upstream bugs from the Boiler audit (BUG-1..7) ([84f4c4f](https://github.com/Jerry2d3d/css-is-awesome/commit/84f4c4fc6f6259bf74541a833fe0ad343821ab12))
-* **themes:** prism was missing from every theme picker ([4ce4f5f](https://github.com/Jerry2d3d/css-is-awesome/commit/4ce4f5f8a696728b513aa1adc148b33c5808e26e))
-
-
-### Features
-
-* **animate:** accept a raw duration; add letter-spacing() coverage fixture ([25b7cd6](https://github.com/Jerry2d3d/css-is-awesome/commit/25b7cd6cbc09d76b51c9dd0b74077ec1af78c327))
-* **blog:** real posts from real commits, replacing seven dead stubs ([f37c5be](https://github.com/Jerry2d3d/css-is-awesome/commit/f37c5be94cd64f99548a6a119820325d559e6920))
-* **site:** print the story, not the chrome — dogfoods cia's print mixins ([ece519c](https://github.com/Jerry2d3d/css-is-awesome/commit/ece519c43f62230e1b3392538dae5148fc31ddf6))
-* **themes:** themes own the spacing rhythm, not just the palette ([4bc1e24](https://github.com/Jerry2d3d/css-is-awesome/commit/4bc1e24f1b64f33cacd35f3bab12327019634fea))
-
-## [1.1.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.1.0...v1.1.1) (2026-08-30)
-
-
-### Bug Fixes
-
-* **sass:** stop using the deprecated if() function; sharpen the AI on-ramp ([61df05a](https://github.com/Jerry2d3d/css-is-awesome/commit/61df05a31228fce169664690c2562d128bf06958))
-
-# [1.1.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.0.0...v1.1.0) (2026-08-30)
-
-
-### Bug Fixes
-
-* **a11y:** copy button used code-surface ink on a page-surface background ([bf84bf4](https://github.com/Jerry2d3d/css-is-awesome/commit/bf84bf4d6c23e3ebafdb5dc98a303d9961d68714))
-* **a11y:** validator ignored unquoted [data-theme]; grade the code palette ([2437f41](https://github.com/Jerry2d3d/css-is-awesome/commit/2437f4182ddccc01b372d9aacd898b6222fcabd3)), closes [#fafafa](https://github.com/Jerry2d3d/css-is-awesome/issues/fafafa) [#0a0a0a](https://github.com/Jerry2d3d/css-is-awesome/issues/0a0a0a)
-* **ci:** snapshot job installed chromium but ran all three engines ([f7b7fc9](https://github.com/Jerry2d3d/css-is-awesome/commit/f7b7fc9e29883863c6a525f44391e6eb4b4b9662))
-* **ci:** snapshot workflow silently discarded the baselines it created ([3358cac](https://github.com/Jerry2d3d/css-is-awesome/commit/3358cacb6fbf88d9dcf0109597bed301efeda483))
-* **compare:** correct every measurable claim on the comparison page ([3d1b602](https://github.com/Jerry2d3d/css-is-awesome/commit/3d1b602ff6074712a2e2d0aea5a1ad27128d2d70))
-* **pkg:** build dist/ on git installs via a prepare hook ([1a0deb1](https://github.com/Jerry2d3d/css-is-awesome/commit/1a0deb19e4fc6de15b7b3530847779920d01d784))
-* **print:** stop the freeze from flattening deliberate opacity and transform ([1af51d2](https://github.com/Jerry2d3d/css-is-awesome/commit/1af51d2e3a08cd61e51ac3b857eeaa261afd044e))
-* root barrel emitted no tokens; retract the false Turbopack claim ([d7f71e3](https://github.com/Jerry2d3d/css-is-awesome/commit/d7f71e366a1ef4b918cfcfd6dafcba8d352afcb5))
-* **site:** moat card uses grid; Tailwind sample updated to Headless UI v2 ([cb39e44](https://github.com/Jerry2d3d/css-is-awesome/commit/cb39e44b4eb8d7ab1a86377c1d828b1cde3ed58b))
-* **site:** moat code blocks now fill their card ([8e53d35](https://github.com/Jerry2d3d/css-is-awesome/commit/8e53d355b0f9279125b9dfd6f913851cf2ebcdc3))
-* six upstream bugs from the Boiler audit (BUG-1..7) ([84f4c4f](https://github.com/Jerry2d3d/css-is-awesome/commit/84f4c4fc6f6259bf74541a833fe0ad343821ab12))
-* **themes:** prism was missing from every theme picker ([4ce4f5f](https://github.com/Jerry2d3d/css-is-awesome/commit/4ce4f5f8a696728b513aa1adc148b33c5808e26e))
-
-
-### Features
-
-* **animate:** accept a raw duration; add letter-spacing() coverage fixture ([25b7cd6](https://github.com/Jerry2d3d/css-is-awesome/commit/25b7cd6cbc09d76b51c9dd0b74077ec1af78c327))
-* **blog:** real posts from real commits, replacing seven dead stubs ([f37c5be](https://github.com/Jerry2d3d/css-is-awesome/commit/f37c5be94cd64f99548a6a119820325d559e6920))
-* **site:** print the story, not the chrome — dogfoods cia's print mixins ([ece519c](https://github.com/Jerry2d3d/css-is-awesome/commit/ece519c43f62230e1b3392538dae5148fc31ddf6))
-* **themes:** themes own the spacing rhythm, not just the palette ([4bc1e24](https://github.com/Jerry2d3d/css-is-awesome/commit/4bc1e24f1b64f33cacd35f3bab12327019634fea))
-
-# Changelog
-
-All notable changes to this project will be documented in this file.
+---
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## Hand-written history (before automated releases)
 
-**See also:** [`VERSIONING.md`](./VERSIONING.md) — version policy, deprecation
-lifecycle, and the Conventional Commits → changelog section mapping that drives
-automated releases.
+> Everything above this line is generated by `semantic-release`. Everything
+> below was written by hand, up to and including the launch notes for 1.1.0
+> (the first version published to npm, 2026-09-01). The generated 1.1.0 entry
+> above is the terse commit list; the section right below is the same release
+> explained.
 
-## [Unreleased]
+## [1.1.0] — 2026-09-01 — launch notes (hand-written detail for the generated entry above)
 
 > Ships as **1.1.0** — the first release actually published to npm. `1.0.0` was
 > tagged but never published. The number is computed by `semantic-release` from

package/CONTRACT.md

@@ -223,6 +223,7 @@ The **numbered scale is the source of truth and is contract-required**: a theme
 | Token                       | Type   | Example (default rhythm)          | Purpose                          |
 | --------------------------- | ------ | --------------------------------- | -------------------------------- |
 | `--space-0` … `--space-9`   | length | `0`, `0.25rem`, `0.5rem`, … `6rem` | The numbered scale — **required** |
+| `--space-unit`              | length | `0.25rem`                          | The density knob — **optional** (contract 1.1). Shipped themes derive every `--space-N` from it via `calc()`; a hand-written theme that declares absolute `--space-N` values never references it, so nothing breaks without it. It was listed as *required* by mistake in library 1.12.0–1.16.0. |
 
 The t-shirt names are **optional aliases**. The library emits `xs`–`xl` as `var()` references into the numbered scale, so they follow it automatically; `--space-2xs` sits outside the numbered scale and emits as a literal:
 

package/MIGRATION.md

@@ -2,6 +2,154 @@
 
 Breaking changes between css-is-awesome versions, and how to migrate.
 
+## v1.0 — mixin-first goes stable (published as 1.1.0)
+
+**There are no breaking changes between v0.8.1/0.8.2 and v1.0.0.** 1.0.0
+(tagged 2026-08-17) is the point at which the v0.8 mixin-first surface —
+mixins, functions, token contract, theme architecture — became stable under
+strict SemVer (see [`VERSIONING.md`](./VERSIONING.md)). Every mixin you called
+in v0.8.1 compiles unchanged in v1.x; `npm run validate-api` guards the barrel
+surface on every commit. The 67 commits between 0.8.2 and 1.0.0 carry no
+rename, removal or signature change.
+
+1.0.0 itself was never published to npm. The first published release is
+**1.1.0 (2026-09-01)**, so upgrading from v0.8 in practice means landing on
+1.1.x — and that release does carry **one action-required change for authors
+of custom themes** (section 2 below). Consumers of the shipped themes have
+nothing to do.
+
+### What changed at a glance
+
+| Area | v0.8.x | v1.x |
+|---|---|---|
+| Component stylesheet import | `@use 'css-is-awesome/scss/mixins' as m` (deep path) or the emitting bundle | **`@use 'css-is-awesome/api' as cia`** — zero-emit barrel, safe in CSS Modules (additive; the deep paths still work) |
+| Root-level `@use 'css-is-awesome'` | Worked only via the deep `scss/…` paths on a clean install | **Resolves on a clean install** — root shims `api.scss` + `_index.scss` shipped (Sass ignores `package.json` `exports`) |
+| Custom-theme contract | `--space-{2xs,xs,sm,md,lg,xl}` required | **`--space-0` … `--space-9` required**, t-shirt names optional (1.1.0 — validator fails an unconverted theme) |
+| Six `--radius-{button,card,input,modal,badge,avatar}` tokens | Required of every theme, read by nothing | **Dropped from the contract** — the live knobs are `--btn-radius`, `--card-radius`, … |
+| Library defaults selector | `:root { … }` (tied a drop-in theme at 0,1,0 — library won) | **`:where(:root) { … }`** — a theme's bare `:root` always wins |
+| `theme()` mixin output | Inconsistent (`:root`, `[data-theme]`, or `:root[data-theme]`) | **`:root, :root[data-theme="<name>"]`** — drop-in with no markup change; `$standalone: false` for bundles |
+| `spinner` / `skeleton` keyframes | Emitted at module top level on import (leaked; CSS Modules renamed them) | **Emitted via `@at-root` inside the mixin** — only when called |
+| Print / PDF | — | **New**: `print`, `print-base`, `print-hidden`, `print-only` mixins + `print-to-pdf` recipe |
+
+### 1. Adopt the two-import model (recommended, not required)
+
+v0.8 consumers typically imported the whole library into every component
+stylesheet, or reached for the deep `scss/mixins` path. Both still compile.
+The v1 shape separates the two jobs:
+
+```scss
+// app/globals.scss — loaded ONCE at the app root. Emits :root tokens + base.
+@use 'css-is-awesome';
+
+// Card.module.scss — per component. Emits NOTHING until a mixin is called,
+// so it is safe under Next.js CSS Modules "pure" mode.
+@use 'css-is-awesome/api' as cia;
+.card { @include cia.card-base($shadow: 2); background: cia.color(surface-default); }
+```
+
+If you were on the deep path, the swap is one line:
+
+```scss
+// v0.8
+@use 'css-is-awesome/scss/mixins' as m;
+.btn { @include m.btn(primary); }
+
+// v1.x — same mixins, one namespace for the whole API (layout + components too)
+@use 'css-is-awesome/api' as cia;
+.btn { @include cia.btn(primary); }
+```
+
+`m.` was only ever the `_mixins.scss` leaf; `cia.` forwards every module, so
+`cia.stack`, `cia.card-base` and `cia.print-base` are all reachable without a
+second import. Deep paths remain supported for anyone who prefers them.
+
+### 2. Custom themes: declare `--space-0` … `--space-9` (1.1.0, action required)
+
+In v0.8 a theme could satisfy the contract with the six t-shirt spacing
+names, but components read the numbered scale (`space(4)` → `var(--space-4)`),
+so a theme's spacing was never actually applied. 1.1.0 makes the numbered
+scale the required source of truth and turns the t-shirt names into optional
+aliases that reference it.
+
+```css
+/* v0.8 custom theme — passes the old validator, but components ignored it */
+:root[data-theme="brand"] {
+  --space-xs: 4px;  --space-sm: 8px;  --space-md: 16px;
+  --space-lg: 24px; --space-xl: 32px; --space-2xs: 2px;
+}
+
+/* v1.x custom theme — required. `npm run validate-themes` fails without it. */
+:root[data-theme="brand"] {
+  --space-0: 0;    --space-1: 4px;  --space-2: 8px;  --space-3: 12px;
+  --space-4: 16px; --space-5: 24px; --space-6: 32px; --space-7: 48px;
+  --space-8: 64px; --space-9: 96px;
+  /* optional aliases — keep them only if your own CSS reads them */
+  --space-md: var(--space-4);
+}
+```
+
+Shipped themes were all converted; if you copied one as a starting point,
+re-copy its spacing block. `--space-unit` (the density knob, 1.12.0) is
+**optional** — since contract 1.1 (library 1.16.1) the validator reports a
+missing optional token as info, never a failure; between 1.12.0 and 1.16.0 it
+was wrongly listed as required, which is why a custom theme could fail
+validation after a minor upgrade. (Later 1.x releases derive the whole scale from a
+single `--space-unit`; see the theme authoring docs for the current shape.)
+
+While you are in the file: the six `--radius-button` / `-card` / `-input` /
+`-modal` / `-badge` / `-avatar` tokens can be deleted. Nothing read them. The
+per-component radius knobs that do work are `--btn-radius`, `--card-radius`,
+`--input-radius`, `--modal-radius`, `--badge-radius` and `--tag-radius`.
+
+### 3. Drop-in themes need no markup (1.1.0, behaviour change, no action)
+
+Two changes make a single theme file work when dropped into any page:
+
+- Library defaults now emit under `:where(:root)` (specificity 0,0,0). In
+  v0.8 the library's own `:root` tied a theme's `:root` and, loading second,
+  won — so a drop-in theme rendered an untokenised page unless you also set
+  `<html data-theme>`. Specificity only *decreased*, so nothing that used to
+  win can start losing.
+- `cia.theme('name')` now emits `:root, :root[data-theme="name"]`. If you build
+  a multi-theme bundle yourself, pass `$standalone: false` so twenty blocks
+  don't all claim `:root`.
+
+If your app overrode a library default with a bare `:root` rule that only
+worked because of source order, it now works by specificity instead.
+
+### 4. `spinner` / `skeleton` in CSS Modules (fix, no action)
+
+v0.8 defined those mixins' `@keyframes` at module top level, so importing the
+file leaked CSS and CSS Modules renamed the keyframes away from the
+`animation-name` that referenced them. They now emit via `@at-root` inside the
+mixin, co-located with the reference, so CSS Modules renames both together.
+If you had worked around it by importing `animations-utilities` globally,
+that workaround is harmless and can stay.
+
+### New mixins/features (additive, no migration needed)
+
+- `css-is-awesome/api` — the zero-emit authoring barrel (section 1)
+- `cia.print`, `cia.print-base($freeze-animations, $size, $margin)`,
+  `cia.print-hidden`, `cia.print-only` — pure-CSS print/PDF layer;
+  `print-base` is root-only (emits `@page`) and exposes `--is-print`,
+  `--print-hide`, `--print-show`. Recipe: `scss/recipes/print-to-pdf.md`
+- The recipes book (`scss/recipes/*.md`) and the MCP server (`mcp/server.cjs`)
+  ship in the package; `npx cia add <recipe>` copies a recipe into your project
+- `npm run validate-package` — packs, installs into a temp project and compiles
+  every documented `@use` specifier, which is how the root-shim break was found
+- Theme build + drift gates (`check:theme-drift`), a corrected contrast
+  validator (it previously skipped unquoted `[data-theme=x]` blocks), and
+  24 shipped themes all passing the contract and the a11y audit
+
+### Where to read more
+
+- [`CHANGELOG.md`](./CHANGELOG.md) — `[1.0.0]` and `[1.1.0]` entries carry the
+  full detail and the reasoning behind each change
+- [`VERSIONING.md`](./VERSIONING.md) — what counts as MAJOR from 1.0 on
+- [`CONTRACT.md`](./CONTRACT.md) — the current required/optional token list
+
+---
+
 ## v0.8.1 — animations split + small renames
 
 Patch release with one real fix (animations CSS Modules bug) and two small

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
 {
@@ -145,7 +145,7 @@ node scripts/theme-validator.js public/themes/midnight/theme.css
 #    <link rel="stylesheet" href="/themes/midnight/theme.css">
 ```
 
-Full authoring walkthrough: [`/docs/authoring/themes`](https://cssisawesome.com/docs/authoring/themes/). The contract (127 required + 36 optional tokens) is at [`scripts/theme-contract.json`](./scripts/theme-contract.json).
+Full authoring walkthrough: [`/docs/authoring/themes`](https://cssisawesome.com/docs/authoring/themes/). The contract (127 required + 41 optional tokens) is at [`scripts/theme-contract.json`](./scripts/theme-contract.json).
 
 ## Token contract
 
@@ -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.
 
@@ -334,7 +338,7 @@ npm install -D @modelcontextprotocol/sdk zod
 
 ## Docs site
 
-The docs site is live at **https://cssisawesome.com** (production — Vercel, deployed from the `prod-css-is-awesome` branch), with a GitHub Pages mirror at **https://jerry2d3d.github.io/css-is-awesome/** that auto-deploys from `main`. To run it locally:
+The docs site is live at **https://cssisawesome.com** (production — Vercel, building `main` on every push), with a GitHub Pages mirror at **https://jerry2d3d.github.io/css-is-awesome/** that deploys after each release. To run it locally:
 
 ```bash
 git clone https://github.com/Jerry2d3d/css-is-awesome.git
@@ -345,6 +349,8 @@ npm run dev          # http://localhost:5173
 
 The docs site is a Next.js 16 app at `src/` that dogfoods the library — every page uses CSS Modules composed from the same tokens and mixins the library ships.
 
+It also hosts the **[playground](https://cssisawesome.com/playground/)**: write SCSS with cia mixins, see it render live against any of the 24 themes, and share the result as a link. Sass runs in your browser (dart-sass in a web worker against cia's own source), so nothing is uploaded and the site stays a static export. Every recipe page has a “Try in playground” button.
+
 ## Scripts
 
 | Script | Does |
@@ -359,7 +365,7 @@ The docs site is a Next.js 16 app at `src/` that dogfoods the library — every
 | `npm run dtcg-to-scss` | Convert DTCG-format design tokens into cia SCSS |
 | `npm run lint` | ESLint on the Next.js app |
 | `npm run lint:scss` | Stylelint on the SCSS library |
-| `npm run validate-themes` | Validate every theme against the 127-token contract + WCAG 2.2 AA contrast (FAIL-by-default since v0.7; checks both `light-dark()` branches and reports the worse) |
+| `npm run validate-themes` | Validate every theme against the 127-required-token contract + WCAG 2.2 AA contrast (FAIL-by-default since v0.7; checks both `light-dark()` branches and reports the worse) |
 | `npm run validate-icons` | Validate the `core` icon pack against the 49-glyph contract |
 | `npm run validate-api` | Assert the `css-is-awesome/api` barrel stays zero-emit |
 | `npm run validate-package` | Pack + install into a temp project and compile every documented `@use` form — catches breakage that in-repo checks can't see |
@@ -408,9 +414,9 @@ 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 upgrade path.
+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.
 
 For the deep authoring reference (tier decisions, mixin contracts, agent rules), read [`AGENTS.md`](./AGENTS.md).
 

package/VERSIONING.md

@@ -30,6 +30,7 @@ Any change that can break a consumer upgrading blindly.
 | SCSS mixin renamed, removed, or breaking signature change                 | `m.btn($variant)` now requires `$size`                 |
 | SCSS mixin default changes rendered output                                | `m.card()` default radius flips from `md` → `lg`       |
 | Contract: required token renamed or removed                               | `--surface-default` → `--surface-base`                 |
+| Contract: **new required token added** (existing custom themes stop validating) | `--space-unit` added as required in 1.12.0 — a mistake, relaxed in contract 1.1 |
 | Contract: `version` field bumps to a new major (`"1"` → `"2"`)            | Required-token removal in `scripts/theme-contract.json` |
 | Optional-peer floor rises                                                 | `@modelcontextprotocol/sdk` minimum raised             |
 
@@ -42,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  |
+| 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                         |
 
@@ -68,6 +70,8 @@ While the library was pre-1.0 (`0.x.x`), the rules above applied with one carve-
 
 **`1.0.0` locked the contract** (cut 2026-08-17). Breaking changes now require a MAJOR bump, no exceptions.
 
+`npm run check:contract` (CI-gated since 2026-09-18) diffs `scripts/theme-contract.json` against the last release tag and fails the build when the required/optional lists change without the version bump these tables demand. It exists because 1.12.0 shipped a new *required* token in a MINOR and nothing caught it until a consumer's validator broke.
+
 ---
 
 ## 3. Deprecation policy

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.`);
 }