css-is-awesome 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,1036 @@
+# [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-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).
+
+**See also:** [`VERSIONING.md`](./VERSIONING.md) — version policy, deprecation
+lifecycle, and the Conventional Commits → changelog section mapping that drives
+automated releases.
+
+## [Unreleased]
+
+> 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
+> the Conventional Commit history; nothing here hand-edits `package.json`.
+
+### Fixed
+
+- **Both documented SCSS imports failed on a clean install.** `@use 'css-is-awesome'`
+  (the README's primary example) and `@use 'css-is-awesome/api'` (the two-import
+  model) both errored with *"Can't find stylesheet to import"* for anyone who
+  installed the package. Sass does not read `package.json` `"exports"` — it
+  resolves a bare specifier against a load path on disk, so `css-is-awesome/api`
+  looked for `node_modules/css-is-awesome/api.scss` while the real barrel sits at
+  `scss/api.scss`. The `"./api"` exports entry only ever served bundlers that
+  honour exports.
+
+  Fixed by shipping two forwarding shims at the package root: `api.scss`
+  (zero-emit) and `_index.scss` (kitchen sink). Only the deep paths
+  (`css-is-awesome/scss/api`) worked before, which is why in-repo checks and the
+  Boiler showcase both stayed green.
+
+### Added
+
+- **`npm run validate-package`** — packs, installs into a temp project, and
+  compiles all ten documented `@use` specifiers, asserting the `/api` forms stay
+  zero-emit. `validate-api` only ever compiled the barrel from inside this repo
+  with `scss/` on the load path, so it could not see the packaging break. Wired
+  into CI.
+- **`npm run pack:consumer`** — packs and installs the current build into a local
+  consumer project in one step, replacing a three-step manual dance whose middle
+  step (hand-editing the versioned tarball filename) failed silently when skipped.
+- CI now also gates `validate-icons` and `validate-api`, which existed but were
+  never executed by the workflow.
+
+### Changed — themes own the spacing rhythm (**action required for custom themes**)
+
+- **`--space-0` … `--space-9` are now contract-required; the six t-shirt names
+  are now optional.** Components call `space(4)`, which reads `var(--space-4)` —
+  but a theme could only declare the six t-shirt names, and those were emitted
+  as *independent literals* that happened to hold the same values. The token a
+  theme set and the token a component read were different variables, so spacing
+  was untouchable from a theme. The proof shipped in the box: all 21 themes
+  carried byte-identical spacing under a comment reading "Library scales —
+  identical". The t-shirt aliases now emit as `var()` **references**
+  (`--space-md: var(--space-4)`), so retuning a numbered step moves both.
+
+  **If you maintain a custom theme, `npm run validate-themes` will now fail it
+  until you declare `--space-0` through `--space-9`.** The six t-shirt names
+  (`--space-2xs`, `--space-xs`, `--space-sm`, `--space-md`, `--space-lg`,
+  `--space-xl`) moved to optional, so keeping or dropping them is your call.
+  Contract totals: **123 required + 30 optional → 127 required + 36 optional.**
+
+- **Library defaults now emit under `:where(:root)` instead of `:root`.**
+  Required by the change above: a dropped-in theme file emits a bare `:root`
+  block, which **tied** the library's own `:root` at (0,1,0) — and the
+  documented load order is theme first, library second, so the *library* won
+  every tie. `:where()` drops the library block to (0,0,0), so a theme's plain
+  `:root` always wins. Specificity only *decreases* here, so nothing that used
+  to win can start losing. `:where()`, not `@layer` — cia does not use cascade
+  layers.
+
+- **`theme()` now emits `:root, :root[data-theme="<name>"]`, so a drop-in theme
+  file needs no markup change.** Shipped themes disagreed three ways about
+  their own selector: 9 emitted `:root[data-theme="x"]`, 7 emitted
+  `[data-theme="x"]`, and 5 emitted a bare `:root`. Only that last group worked
+  when dropped into a page on its own — the other 16 silently rendered an
+  untokenised page unless the consumer *also* set `<html data-theme>` to a value
+  matching the file. Both halves now ship, so a single-file drop-in themes the
+  page immediately and `data-theme` switching still works. New `$standalone`
+  parameter (default `true`) suppresses the bare `:root` half; the multi-theme
+  bundle sets it to `false` so 24 blocks don't all claim `:root`.
+
+### Added — theme build + drift gates
+
+- **`npm run check:theme-drift`** (`scripts/check-theme-drift.mjs`) — rebuilds
+  every theme into a scratch copy and diffs the result against the committed CSS
+  declaration by declaration, then restores (the check is read-only).
+  `validate-themes` reads the **committed** CSS under `public/`, not the SCSS
+  sources, and theme building was in no CI step at all — so a fix could land in
+  `scss/themes/*.scss`, never be rebuilt, and CI would happily validate the
+  stale artifact and report success. Now wired into CI ahead of
+  `validate-themes`.
+- **`scripts/build-theme-bundle.mjs`** — regenerates the whole of
+  `public/theme.css` on every build.
+- `build:css:themes` now builds the bundle as well as the per-theme files, and
+  is finally part of `build:css:all` (it never was).
+- The a11y audit gained five `--code-*` pairs (`--code-ink`, `--code-muted`,
+  `--code-accent`, `--code-blue`, `--code-green`, each against `--code-bg`),
+  taking it from **17 to 22 audited pairs per theme**.
+
+### Fixed — a11y validator, theme sources, theme bundle
+
+- **The contrast validator silently passed themes it had never read.** Its
+  block-matching regex required quotes, so `[data-theme=dark]` — valid CSS —
+  matched nothing. The file then fell through to a legacy `:root`-only path in
+  which every theme block is invisible, audited `:root` alone, found it fine and
+  exited 0, reporting "1 theme block(s)" while passing a theme with near-black
+  text on near-black paper. Reproduced both ways: the quoted form failed with 9
+  bad pairs, the unquoted form passed. Both now fail. A guard was added on top:
+  if a file mentions `data-theme` but no block parses, the validator **refuses to
+  grade** rather than fall back and report a meaningless pass.
+- **33 real contrast failures across 9 themes**, worst 3.02:1, surfaced by the
+  newly-audited `--code-*` pairs and all fixed by holding hue and saturation and
+  moving only lightness. Prism's `--code-muted` needed a structural fix: it was a
+  single value sitting against a `light-dark(#fafafa, #0a0a0a)` surface, and no
+  single grey clears even 4.5:1 on both (it would need L ≤ 0.174 *and* L ≥ 0.189
+  — disjoint). It is now `light-dark()` too.
+- **13 `-light` / `-dark` theme files were hand-authored CSS with no SCSS
+  source.** Nothing could rebuild them and they had drifted **31 declarations**
+  from their namesakes. They were **ported, not derived** — checked first: 3 were
+  exact derivations, 9 were not. `glass-light` carries `blur(30px)` where its
+  parent has `blur(20px)`, and a `.70` white glow where the parent has `.16` —
+  deliberate tuning that deriving would have silently restyled away. Values were
+  copied byte-for-byte; 2,647 declarations across 21 files verified with zero
+  value differences.
+- **Three themes existed only inside `public/theme.css`** — `sketchbook-light`
+  (the docs site's *default* theme), `boilerplate-light` and `boilerplate-dark`
+  were blocks with no SCSS source and no theme directory, invisible to the
+  contract gate and unrebuildable. All three were promoted to real sources with
+  values copied verbatim (checked first: two are exact derivations,
+  `boilerplate-dark` is not — its `--shadow-md/lg/xl` are two-part shadows where
+  the parent's dark branch is single-part). **24 themes now ship, all passing the
+  contract check and the a11y audit.**
+
+### Removed
+
+- **Six dead contract tokens:** `--radius-button`, `--radius-card`,
+  `--radius-input`, `--radius-modal`, `--radius-badge`, `--radius-avatar`. They
+  were required of every theme and had **zero consumers** anywhere in the
+  library. The live knobs are `--btn-radius`, `--card-radius`, `--input-radius`,
+  `--modal-radius`, `--badge-radius` and `--tag-radius`, which already cascade
+  from the generic `--radius-*` scale; those six are now listed in the contract
+  as **optional**, so overriding one is documented rather than folklore.
+- **`scripts/bundle-companion-themes.mjs`** — a one-shot appender that only
+  added a theme to `public/theme.css` if its block was *missing*, and never
+  updated an existing one, so the bundle silently fell 8 commits behind.
+  Replaced by `scripts/build-theme-bundle.mjs`, which regenerates the file.
+
+## [1.0.0] — 2026-08-17 — Mixin-first, stable
+
+First 1.0. The API surface (mixins, functions, token contract, theme
+architecture) is now under strict SemVer — breaking changes require a major
+bump. See [`VERSIONING.md`](./VERSIONING.md) for the policy.
+
+Nothing in the library changed in this release; 1.0.0 marks the point at which
+the 0.8 mixin-first surface is treated as stable. Everything below shipped
+during the 0.9/1.0 development window.
+
+### Added
+
+- **`css-is-awesome/api` — zero-emit authoring barrel for per-component styles.**
+  New `scss/api.scss` + package export `"css-is-awesome/api"` forwards the full
+  mixin/function/token-map API but emits **zero CSS** until a mixin is actually
+  called. This is the correct entry point for a component stylesheet
+  (`Card.module.scss`), because it prints no `:root` block and is therefore safe
+  under Next.js CSS Modules "pure" mode:
+
+  ```scss
+  @use 'css-is-awesome/api' as cia;
+  .card { @include cia.card-base($shadow: 2); background: cia.color(surface-default); }
+  ```
+
+  Tokens + keyframes still live at the app root (emitted once by the CSS bundle
+  or a theme stylesheet); components only pull in the mixins. `scss/_index.scss`
+  is now the "kitchen-sink" barrel (`api` + the global `.cia-anim-*` utilities)
+  and derives its API surface from `api.scss`, so the two can't drift. Guarded by
+  `npm run validate-api` (a Sass compile-assertion test).
+
+  Fixes a latent consume-time bug: `spinner()` and `skeleton()` previously
+  defined their `@keyframes` at module top level, which leaked CSS on import and
+  would be renamed by CSS Modules (breaking the animation reference). Their
+  keyframes now emit via `@at-root` inside the mixin — only when called, and
+  co-emitted with the reference so CSS Modules renames both together (matching
+  the existing `_overlay.scss` pattern).
+
+- **Print / PDF — pure-CSS, zero-JS.** "The page IS the PDF source." Four
+  new mixins in `scss/_mixins.scss` (namespaced `cia.` / `m.`): `print`
+  (bare `@media print { @content }` wrapper, co-locate inside a selector to
+  override on paper), `print-base($freeze-animations, $size, $margin)`
+  (root-only page defaults — emits `@page`, freezes animations so nothing
+  prints invisible, and emits the print variable control plane),
+  `print-hidden` (hide chrome on paper), and `print-only` (show an element
+  only on paper, hidden on screen). Three custom properties from
+  `print-base`: `--is-print` (`0` on screen, `1` on paper; readable in
+  `calc()` / `opacity` / `@container style(--is-print: 1)`), `--print-hide`
+  (display for `print-hidden`, default `none`), and `--print-show` (display
+  for `print-only`, default `revert`) — override either locally to keep or
+  lay out an element with no rule rewrite. New recipe at
+  `scss/recipes/print-to-pdf.md` (layout, simple) with framework examples,
+  read by humans at `/docs/recipes/print-to-pdf`. No Puppeteer, no server —
+  the browser's native Print → Save as PDF is the generator. Pulled forward
+  from v1.2 into v1.0.
+
+### Changed
+
+- **Docs now teach the two-import model with the `cia.` namespace consistently.**
+  AGENTS.md, `llm.txt`, `css-is-awesome.instructions.md`, THREE-TIERS.md,
+  MIGRATION.md, the `/docs/install` page, and the MCP server (`assemble_prompt`
+  usage blocks + `resolve_size` suggestions) now show component styles importing
+  `@use 'css-is-awesome/api' as cia;` (zero-emit) and reference every mixin as
+  `cia.*` instead of the inconsistent `m.*`. The root/global bundle
+  (`@use 'css-is-awesome'`, optionally `with (...)`) stays the token-emitting
+  entry. The MCP theme-name parser now matches any namespace (`m.theme`,
+  `cia.theme`, …).
+
+### Fixed
+
+- **Docs no longer show imports/mixins that don't compile.** The previously
+  documented `@use 'css-is-awesome' as cia;` for component styles resolved to the
+  CSS-emitting bundle (no mixin API, and it emitted `:root` — rejected by CSS
+  Modules pure mode); it now points at `css-is-awesome/api`. Icon examples used
+  `m.svg(...)` (never defined — icons are `cia.icon-svg` via the barrel, or
+  `i.svg` via `css-is-awesome/scss/icons`), and the font examples referenced the
+  removed `font-load` / `font-load-local` names (now `cia.font-face` /
+  `cia.font-face-local`). All doc snippets are verified to compile through `/api`.
+
+## [0.8.2] — 2026-05-21 — Panel R7 bug-fix patch
+
+Hotfix responding to the css-scss-master panel audit of v0.8.1. Two real
+build/render bugs caught + four behavior fixes. All compile-verified.
+
+### Fixed
+
+- **Bare-tags recipe `<dialog>` block** — `@include m.modal-base` was failing
+  with "Undefined mixin" because `_bare-tags.scss` `@use`'s `mixins as m` but
+  `modal-base` lives in `_overlay.scss`. Added `@use '../components/overlay' as o;`
+  and switched the call to `o.modal-base`. (Same "didn't grep callers" miss as
+  Badge in `c06324d` — feedback memory `grep-callers-before-rename-or-move`
+  is now in place.)
+- **Stepper composed router selectors** — `[data-status='upcoming'] > &`
+  inside `stepper-circle` was compiling to the wrong selector when used via
+  `stepper()` (the nested selector resolved with `&` AFTER the parent,
+  inverting the intent). Rewritten: status palette now lives at the composer
+  level via `> li[data-status='...'] > [data-slot='circle']` selectors.
+  Standalone `stepper-circle` retained as the "upcoming default" primitive.
+- **Stepper connector over-painted** — `[data-status='completed'] ~ * > &`
+  matched every trailing connector after the first completed step. Switched
+  to `+ li` (adjacent sibling only).
+- **`progress-fill-base` transitions `width`** — animated `width` skipped the
+  transition when consumer used `inline-size` (RTL-correct logical property).
+  Switched to `inline-size`.
+- **`wizard-shell` / `sidebar` / `toolbar` bypassed `m.space()`** — using raw
+  `map.get(t.$space, …)` meant runtime `--space-*` overrides had no effect on
+  the new mixins. Added `@use './mixins' as m;` to `_layout.scss` and switched
+  the new mixins to `m.space()`. Token-theming parity restored.
+- **`_index.scss` barrel now forwards `./animations-utilities`** — survived
+  v0.8.1 only because `main.scss` loaded both halves. Bare `@use 'css-is-awesome' as cia`
+  now correctly exposes the keyframes + utility classes too.
+- **Dead `$variant` param in `stepper()` removed.**
+
+### Investigated, no change
+
+- `if(sass($cond): a; else: b)` syntax in `_layout.scss:46`, `_data.scss:45`,
+  `_mixins.scss:630` was flagged as "not valid Dart Sass" by the audit.
+  Compile test passes cleanly with no deprecation warning. The form is
+  Sass's actively-recommended replacement for the deprecated `if($c, a, b)`
+  short form. No change required.
+
+## [0.8.1] — 2026-05-21 — Animations split + 5 new mixins (dogfood patch)
+
+Patch release responding to boiler-project-ai dogfood feedback. One real bug
+(animations partial breaking Next.js CSS Modules), five new mixin primitives
+the consumer was hand-rolling.
+
+### BREAKING (small) — `_animations.scss` split + `progress-track`/`progress-fill` rename
+
+- **`_animations.scss` split into two files.**
+  - `scss/_animations.scss` keeps the mixins (`animate`, `animate-on`,
+    `$_anims`/`$_speeds` maps) — safe to `@use` from `.module.scss`
+    in Next.js / Vite / Parcel CSS-Modules pipelines.
+  - `scss/_animations-utilities.scss` (NEW) holds keyframes, `.cia-anim-*`
+    classes, `.cia-hover-*` classes, and the global `*, *::before, *::after`
+    reduced-motion safety net. Load ONCE globally.
+  - `main.scss` already loads both — full-bundle consumers unaffected.
+  - Why: top-level `*, *::before, *::after` in the same file as the mixin
+    surface caused `Selector "*, *::before, *::after" is not pure` build
+    errors when a `.module.scss` did `@use 'css-is-awesome/scss/animations' as anim`.
+- **`progress-track` / `progress-fill` renamed to `-base` suffix.**
+  - `m.progress-track` → `m.progress-track-base`
+  - `m.progress-fill` → `m.progress-fill-base`
+  - Signals "compose me" intent and unblocks the new `progress()` router name.
+- **`badge-base` / `badge` moved from `_feedback.scss` to `_data.scss`.**
+  - Lives next to `card-base` / `table-base` where consumers expect it.
+  - Path-specific imports (`@use 'css-is-awesome/scss/components/feedback' as f; f.badge-base;`)
+    will break — switch to the cia barrel (`@use 'css-is-awesome' as cia; cia.badge-base;`)
+    or import from `data` instead. The cia barrel re-exports all components.
+
+### Added — 5 new mixins (boiler-driven additions)
+
+- **`m.wizard-shell($min-height, $gutter, $body-padding, $rail-padding, $max-width, $footer-border)`** — 3-row grid layout with shared horizontal rhythm. Header + scrollable body + footer; all three rows share `padding-inline` so stepper above + controls below align with the body. `<div data-slot="header|body|footer">…</div>` markup.
+- **`m.stepper($orientation, $variant, $size)` + `m.stepper-circle($size, $r)` + `m.stepper-connector($thickness)`** — status-driven progress indicator. `[data-status="upcoming|active|completed|warning|error"]` parent attribute drives the palette. Composable: use just the circle, or the full strip.
+- **`m.progress($height, $r, $bg, $fill)`** — composed router over `progress-track-base` + `progress-fill-base`. Consumer markup: `<div role="progressbar"><span data-slot="fill" style="inline-size: 60%"></span></div>`.
+- **`m.sidebar($side, $side-width, $content-min, $gap)`** — Every-Layout sidebar primitive. Fixed-width nav + flexible content, gracefully stacks when content falls below `$content-min`. `[data-slot="side|content"]` markup.
+- **`m.toolbar($gap, $align)`** — cluster with auto-margin trailing slot. Left group + right group via `[data-slot="trailing"]`.
+
+### Added — Tier 3 bare-tags additions
+
+- `:where(dialog)` — wraps `m.modal-base` + `::backdrop` blur for a sensible default `<dialog>` look.
+- `:where(progress)` — themed `<progress>` element using cia tokens.
+- Both still ship at specificity (0,0,0) via the existing `:where()` wrap.
+
+### Locked architectural rule
+
+- **No top-level rules in mixin-surface partials.** Any cia partial whose
+  public surface is mixins MUST NOT emit CSS rules at file scope. Rule-emitting
+  code lives in dedicated `*-utilities.scss` files or entry points. Enforced
+  via convention; future CI test planned.
+
+## [0.8.0] — 2026-05-21 — Mixin-first reframe
+
+The big one. cia is now **mixin-first** end-to-end: the mixin is the API, the
+class/tag/selector is the consumer's choice. The npm package ships **zero
+JavaScript** by hard rule.
+
+### BREAKING — Mixin renames (no aliases, hard cut)
+
+| Old | New | Why |
+|---|---|---|
+| `m.bp` | `m.media` | Matches CSS `@media` |
+| `m.bp-down` | `m.media-down` | Same family |
+| `m.bp-between` | `m.media-between` | Same family |
+| `m.cq` | `m.contain` | Matches `container-type` mental model |
+| `m.cq-down` | `m.contain-down` | Same |
+| `m.cq-between` | `m.contain-between` | Same |
+| `m.color-raw` | `m.color-static` | "static" makes runtime-vs-compile clearer |
+| `m.inset` | `m.pad` | `inset` collides with CSS property |
+| `m.inset-x` | `m.pad-x` | Same family |
+| `m.inset-y` | `m.pad-y` | Same family |
+| `m.squish` | `m.pad-asym` | Cute → ambiguous; `pad-asym` is descriptive |
+| `m.font-load` | `m.font-face` | Matches `@font-face` at-rule emitted |
+| `m.font-load-local` | `m.font-face-local` | Same |
+| Layout `m.container` | `m.wrap` | Resolves collision with the CSS-containment `m.container` |
+
+### BREAKING — Theme system collapsed
+
+- 14 hand-authored `public/themes/<name-mode>/theme.css` files → 9 single-file
+  themes generated from `scss/themes/<name>.scss` sources via `light-dark()`.
+- New selector: `:root[data-theme="press"]` instead of
+  `[data-theme="press-light"]` / `[data-theme="press-dark"]`. **Consumers must
+  rename `data-theme` attribute values** — drop the `-light`/`-dark` suffix.
+- Glass uses Pattern C (nested `@media` block for blur/glow that differs per
+  mode); all other themes use Pattern B (one block, `light-dark()` per token).
+- Terminal + Terminal-light are two separate themes, not a paired family —
+  intentional. Different brand identities.
+
+### BREAKING — Responsive `:` utilities killed
+
+- `.cia-sm:flex`, `.cia-md:hidden`, etc. — gone. They were generating ~85
+  lines of cartesian-product responsive utility classes that almost nobody
+  was opting in to.
+- `main.scss` compiled bundle dropped from 16.6 KB gz → 8.2 KB gz (50%).
+- Consumers needing responsive utilities: opt back in via `@use cia with
+  ($responsive-spacing: true)` once the opt-in API ships.
+
+### BREAKING — Utility classes opt-in (Sass path)
+
+- Default for Sass-authoring consumers: zero `.cia-*` rules emitted.
+- Opt in via `@use 'css-is-awesome' as cia with ($utilities: true)`.
+- Pre-built `dist/css-is-awesome.utilities.css` still ships every utility for
+  CDN drop-in consumers — unchanged. Opt-in governs the Sass compile path only.
+
+### BREAKING — Zero JavaScript in npm package
+
+- New hard rule. Audit-able: `find node_modules/css-is-awesome -name "*.mjs"
+  -o -name "*.js" -o -name "*.cjs"` returns nothing.
+- The optional `copy-button` JS shim moved to `public/copy-button.mjs`
+  (website-only, not in the published `files` manifest).
+- A future `@cia/copy-button` add-on package will be the canonical opt-in path
+  for JS-augmented features (v1.x).
+
+### Added — Zero-JS interactive component slate
+
+- `cia.accordion` — native `<details name="...">` mutual exclusion
+- `cia.modal` — native `<dialog>` + `::backdrop` + `@starting-style`
+- `cia.tooltip` — native `popover="hint"`
+- `cia.dropdown` — native `[popover]` + auto-dismiss + animation
+- `cia.tabs` — radio + `:has()` + `:nth-of-type()` panel switching
+- `cia.copy-button` + `cia.copy-toast` — styled button (JS handler is a
+  documented recipe at `/docs/recipes/copy-button`, NOT shipped)
+
+### Added — Intrinsic layout vocabulary
+
+- `m.stack` — vertical rhythm via flex column + gap
+- `m.cluster` — wrapping inline group (pills/tags/buttons)
+- `m.switcher` — auto row↔column based on container width
+- `m.cover` — hero with vertically-centered child
+- `m.frame` — aspect-ratio wrapper for media
+
+### Added — Foundation mixins
+
+- `m.theme($name, $scheme)` — wraps a theme's `:root[data-theme=…]` block
+- `m.states($group)` — derives hover/active via `color-mix(in oklch, ..., light-dark(black, white), N%)`
+- `m.theme-properties($tokens)` — emits `@property` registrations for animated theme swaps
+- `m.focus-ring` — centralized; all interactive components route through it
+- `m.sr-only` mixin + opt-in `.cia-sr-only` utility
+
+### Added — Tokens-only micro-bundle
+
+- New `scss/tokens.scss` → `dist/tokens.css` (2.3 KB gz). Pure `:root` CSS
+  variables, no rules, no resets. The purest mixin-first emit.
+- New `dist/tokens.d.ts` — TypeScript declarations for 123 tokens, IDE
+  autocomplete + AI tooling readiness.
+
+### Added — DTCG ingestion
+
+- New `scripts/dtcg-to-scss.mjs` — converts DTCG v2025.10 JSON tokens into
+  a cia theme SCSS source. Built-in mapping table for color/surface/text/
+  action/status/border/type/shape/space paths.
+
+### Added — Docs site refresh
+
+- Homepage hero: "Bring your own selectors. We bring the design system." +
+  moat comparison section (cia 12 LOC vs Tailwind+HUI 70 LOC accordion).
+- 6 component pages at `/docs/components/{accordion,modal,tooltip,dropdown,tabs,copy-button}`.
+- 3 recipe pages at `/docs/recipes/{anchor-positioning,copy-button,tabs-aria}`.
+- `/docs/themes/pairing` — the `<link media>` two-brand-by-mode recipe.
+- `/compare` refreshed with v0.8 stats + new rows.
+- `/docs/install` mixin-first lead (instead of CDN-first).
+- `/docs/utilities` opt-in callout.
+
+### Fixed — 5-bug cleanup punch list
+
+- `scss/_index.scss:12` invalid `@forward 'mixins' as *` syntax (file
+  previously failed to compile).
+- `scss/_mixins.scss` `btn-base` calling removed `inline()` mixin → now
+  `m.flex($inline: true, $gap: 2)`.
+- 267 lines of dead duplicate mixins removed from `_mixins.scss` (lines 754-1020).
+- Layout `m.container` → `m.wrap` resolves duplicate-mixin collision.
+- `theme/_index.scss` spacing maps now defer to `_system.scss` (single source).
+
+### Locked — Architectural rules (memory)
+
+- Mixin-first: cia is the mixin; class/tag is the consumer's choice.
+- No `@layer` — use `:where()` for the Tier 3 bare-tag fix.
+- No JavaScript in the npm package — period.
+- One theme = one file.
+- No Storybook — docs site + `@cia/mcp-server` cover both audiences.
+- No BEM — `__` and `--` modifier patterns forbidden in cia source.
+
+---
+
+## [Unreleased — pre-v0.8]
+
+### Changed — Flex layout API consolidated to `m.flex` (BREAKING)
+
+- New `m.flex($direction, $gap, $align, $justify, $wrap, $inline)`
+  replaces the six legacy flex helpers. Shorthand value names
+  (`start`/`end`/`center`/`between`/`around`/`evenly`) match the
+  `cia-*` utility-class vocabulary; full CSS values still pass
+  through.
+- **Removed** (no aliases): `m.flex-center`, `m.flex-between`,
+  `m.stack`, `m.inline` (from `_mixins.scss`), `m.row`, `m.col`
+  (from `_layout.scss`). All internal callsites migrated in this
+  pass. Consumers must replace, e.g.:
+  ```scss
+  @include m.flex-center        →  @include m.flex($justify: center)
+  @include m.flex-between       →  @include m.flex($justify: between)
+  @include m.stack(md)          →  @include m.flex($direction: column, $gap: md)
+  @include m.inline(2)          →  @include m.flex($gap: 2)
+  ```
+- The `cia-flex-center` / `cia-flex-between` utility *classes* in
+  `dist/css-is-awesome.utilities.css` are unchanged; only the SCSS
+  mixin surface was consolidated.
+
+### Added — Live theme editor (docs site)
+
+- New `<ThemeEditorDock>` on `/themes` lets visitors tweak the active
+  theme's tokens in-place: category tab strip, paginated sub-pages for
+  groups with >4 controls, round color swatches, contrast hints, and a
+  lint pass against the 123-token contract. Per-family persistence
+  keeps a separate edit set for each theme family.
+- "Download" emits a validator-conformant `theme.css` so an edit can
+  drop straight back into `public/themes/<name>/`.
+- **In progress (uncommitted at time of writing):** an "Import" affordance
+  that accepts an existing `theme.css` upload and re-hydrates the editor
+  with its declared tokens so a partially-edited theme can be picked
+  back up later. Will land before the v0.7 tag cuts.
+
+### Changed — npm publish gate (v0.7.0 prep)
+
+- `package.json` `files` array now explicitly includes `public/icons` and
+  `LICENSE-third-party` so the new Lucide `core` icon pack (49 SVGs) and
+  the third-party attribution license ship in the tarball. Verified via
+  `npm pack --dry-run` and a real `npm pack` extract: 125 files, 162 kB
+  packed / 1.0 MB unpacked, no `dist/components/`, no `src/`, no tests,
+  no `.next/` or `out/`. Top-level layout: `dist/`, `scss/`, `public/`,
+  `figma-tokens/`, both `LICENSE` files, and the four reference markdown
+  docs (`README`, `CHANGELOG`, `AGENTS`, `CLAUDE`, `GEMINI`,
+  `css-is-awesome.instructions`).
+- Confirmed `scss/main.scss` no longer `@use`s `_app-styles` (already
+  fixed in `d986ea7`). Spot-checked all four `dist/*.css` builds for
+  docs-only selectors (`.site-header`, `.docs-*`, `.draft-stamp`,
+  `APP STYLES`, `next-`, `launch-gate`) — none present. Build sizes:
+  core 18.2 kB / 16.4 kB min, utilities 112.4 kB / 81.9 kB min, full
+  161.5 kB / 115.6 kB min (uncompressed; gzip ≈ 2.4 / 11.5 / 15.2 kB
+  per the previously recorded baselines).
+- `_app-styles.scss` itself remains in `scss/` as a project-owned
+  template for consuming boilerplates — not imported by any library
+  entry, but shipped so a downstream copy-step can pick it up if a
+  consumer wants the boilerplate template.
+
+### Added — Docs content refresh + live token visualizers
+
+- `/docs` intro now ships a real Quick Start: CDN one-`<link>` snippet, the
+  three bundle tiers (`core` 2.4 KB / `utilities` 11.5 KB / `full` 15.2 KB
+  gzipped), a side-by-side utility-class vs. SCSS-mixin example, and an
+  expanded "What next" with links out to `/docs/tokens`, `/docs/animation`,
+  `/themes`, `/docs/authoring/themes`, and `/compare`.
+- `/docs/tokens` swatches now read live values via
+  `getComputedStyle(document.documentElement)` and re-resolve whenever the
+  active theme changes — color chips, hex/rgb values and the type-scale
+  preview all reskin without a reload. Added an `Action (semantic primary)`
+  group covering the four `--action-primary-*` slots, an extended radii
+  preview that renders `--r-sm/md/lg` next to the `--radius-*` aliases, and
+  a Type scale section with sample lines at the resolved sizes.
+- `<Example.Code>` snippets across every docs page now have a
+  copy-to-clipboard button. Reads `pre.textContent` (so syntax-highlight
+  spans are stripped automatically), shows `Copied` for ~1.5 s, and falls
+  back to a hidden-textarea + `execCommand('copy')` when the Async
+  Clipboard API is unavailable. Hover-to-reveal on pointer devices,
+  always-visible on touch and on focus, with `aria-label` swapping
+  between "Copy code to clipboard" and "Copied to clipboard".
+### Added — A11y contrast linter (Phase 7 differentiator)
+
+- New `scripts/theme-a11y.js` (zero deps) implements the WCAG 2.2
+  §1.4.3 / §1.4.11 contrast-ratio formulas and is wired into
+  `scripts/theme-validator.js`. Every `npm run validate-themes` run now
+  audits 17 key token pairs per theme (text on `--paper`, status text
+  on subtle status surfaces, inverse text on action primary / `--ai`,
+  borders + focus rings + `--shu` against `--paper`). PASS/WARN/FAIL
+  with required-vs-actual ratios.
+- **A11y FAILs fail the build by default (as of v0.7).** Every shipped
+  theme passes WCAG 2.2 AA across all 17 audited pairs after the v0.7
+  triage. `--border-default` is reclassified as decorative
+  (informational only) per WCAG 2.2 SC 1.4.11. Pass `--allow-a11y-fail`
+  to downgrade contrast FAILs to warnings (useful while authoring a new
+  theme); `--strict` is still accepted as a no-op for backwards compat.
+- Translucent foregrounds are alpha-composited onto their background
+  before the ratio is computed; translucent backgrounds composite onto
+  `--paper` first, so the audited number matches what users see.
+- New `--no-a11y` CLI flag on `theme-validator.js` to skip the audit
+  entirely; the contract check still runs.
+- Color formats handled with no dependencies: hex (3/4/6/8 digit), `rgb()`,
+  `rgba()`, `hsl()`, `hsla()` (comma + space + slash-alpha syntaxes), 148
+  named colors, `transparent`. Modern spaces (`oklch`, `oklab`, `lab`,
+  `lch`, `hwb`, `color()`, `color-mix()`) report as **SKIP** with a reason.
+- `var(--token)` references are resolved transitively against the theme's
+  own declarations (with `var(--x, fallback)` fallback support).
+- Documented in [`CONTRACT.md`](./CONTRACT.md#a11y-contrast-wcag-22-aa)
+  including the audited pairs and the WARN buffer for tertiary / faint
+  ink. Source: WCAG 2.2 §1.4.3 / §1.4.11 — relative-luminance formula
+  with the standard `(L1+0.05)/(L2+0.05)` ratio.
+
+### Added — Boilerplate theme (recommended starter)
+
+- New theme **Boilerplate** (`boilerplate-light` + `boilerplate-dark`) at
+  `public/themes/boilerplate/theme.css`. Both modes ship in a single file
+  and each declares the full 123-token contract.
+- Design intent: a neutral, low-flourish, easy-to-override starter.
+  Slate-leaning grays + one clean blue accent (`#2563eb` / `#3b82f6`),
+  system UI sans-serif by default (no web fonts, no `@import` — fastest
+  possible first paint), `ui-monospace` code stack, subtle shadows,
+  standard 4 / 6 / 8 px radii. Goal: drop it in, accept defaults, get
+  something that looks "modern, clean, professional, and unsurprising."
+- Bundled into the consolidated `public/theme.css` via
+  `scripts/bundle-companion-themes.mjs` (script extended to support
+  multiple `[data-theme]` blocks per source folder).
+- Selectable in the docs UI: added to `<ThemeSelect>` (header dropdown),
+  `<ThemePicker>` (docs row), and the `/themes/gallery` page as the
+  first tile.
+- Gates the v0.7 npm publish (per ROADMAP.md).
+
+### BREAKING CHANGES — Theme naming convention (Feature 2.14)
+
+Every built-in theme name now carries a `-light` / `-dark` mode suffix.
+Five of the six original themes are renamed; `terminal` stays
+single-mode by design (CRT phosphor only — a "terminal-light" is no
+longer terminal).
+
+| v0.6 name      | v0.7 name           |
+|----------------|---------------------|
+| `sketchbook`   | `sketchbook-light`  |
+| `press`        | `press-light`       |
+| `graphite`     | `graphite-dark`     |
+| `glass`        | `glass-light`       |
+| `cupertino`    | `cupertino-light`   |
+
+**Backward-compat aliases** ship in `public/theme.css` for the entire
+0.7.x line: `<html data-theme="sketchbook">` keeps resolving to the
+sketchbook-light tokens, etc. The aliases are **removed in v0.8**
+(US-2.14.3). Migration steps are in [`MIGRATION.md`](./MIGRATION.md).
+
+The default attribute on `<html>` and the default cookie value both
+become `sketchbook-light`. The `:root:not([data-theme])` fallback in
+the consolidated bundle still selects sketchbook so a no-attribute
+drop-in still works.
+
+### Changed — Theme system
+
+- `public/theme.css` selectors renamed (with the v0.6 names retained as
+  comma-grouped alias selectors on each block).
+- `public/themes/{press,graphite,glass,cupertino}/` folders renamed to
+  `{press-light,graphite-dark,glass-light,cupertino-light}/`. Per-theme
+  banner comments updated.
+- `<ThemePicker>` and the `/themes` gallery emit suffixed IDs.
+- Pre-hydration script in `app/layout.tsx` accepts both old and new
+  cookie values (old maps to alias selectors).
+- Visual-regression baselines under `tests/__screenshots__/` renamed to
+  match the new theme IDs.
+
+### Added — Documentation
+
+- [`MIGRATION.md`](./MIGRATION.md) — v0.7 migration steps for consumers
+  (theme renames, removal timeline, per-tier impact).
+- [`THREE-TIERS.md`](./THREE-TIERS.md) — top-level doc for the canonical
+  three-tier authoring story (drop-in classes, SCSS mixins, bare tags),
+  same-button-three-ways demo, router architecture, and a picking-a-tier
+  table.
+- New docs route `/docs/three-tiers` dogfoods the same story with live
+  Button previews next to each tier's code. Sidebar nav: "Three tiers"
+  sits between Introduction and Install under Getting started.
+- `/docs/animation` rewritten as a live preview page: every keyframe in
+  `_animations.scss` rendered as a card in a responsive grid, with
+  hover/click/keyboard-driven replay for one-shot animations and
+  always-on previews for loopers. Cards show the `cia-anim-*` utility
+  class so readers can copy the trigger directly. Page reads from the
+  same motion tokens (`--duration-*`, `--ease`) so swapping themes via
+  the header dropdown or floating ThemePicker retimes every preview in
+  place. Reduced-motion safety net documented inline.
+
+### Changed — Documentation
+
+- README "Two ways to use it" → "Three ways to use it" with a Tier 3
+  bare-tags section and a link to `THREE-TIERS.md`.
+
+### Added — Icons (Lucide `core` pack + per-theme override)
+
+- **Default `core` icon pack** vendored from Lucide, shipping at
+  `public/icons/core/<name>.svg` — 49 glyphs (8 already shipped + 41
+  new) covering navigation, actions, status, communication, user /
+  security, and media. Source list and per-glyph mapping documented in
+  `roadmap/icons-proposal.md` and `scripts/icon-contract.json`.
+- **Per-theme override mechanism** in `scss/_icons.scss`. The `m.svg`,
+  `m.svg-bg`, and `m.svg-text` mixins now emit
+  `var(--cia-icon-<name>, url('/icons/core/<name>.svg'))` as the icon
+  URL, so a theme overrides one glyph by declaring
+  `--cia-icon-<name>: url('/themes/<theme>/icons/core/<name>.svg')` on
+  `:root`. Resolution order: per-theme override → core pack → 404.
+  Mixin call signatures are unchanged (`m.svg(check)` still works).
+- New SCSS variable `$icon-pack` (default `'core'`, re-exported as
+  `$theme-icon-pack`) decouples the pack folder from `$icon-path`.
+- New machine-readable contract at `scripts/icon-contract.json` and a
+  validator at `scripts/icon-validator.js` (`npm run validate-icons`)
+  that mirror the theme-validator. The validator fails if a pack omits
+  any contract glyph.
+- New script `scripts/vendor-lucide-core.mjs` (idempotent) regenerates
+  `public/icons/core/` from `lucide-static`.
+- New `LICENSE-third-party` at the repo root attributing Lucide
+  (ISC + Feather-derived MIT subset).
+- `CONTRACT.md` gains an "Icons contract" section covering the
+  resolution order, the canonical 49-glyph list, naming conventions,
+  and SVG file-format expectations.
+- `AGENTS.md` gains a short "Icons" subsection pointing at
+  `CONTRACT.md` for the full spec.
+
+The legacy flat-layout files at `public/icons/<name>.svg` (the original
+8 glyphs) remain on disk as a backward-compat copy; the mixin output now
+resolves against `/icons/core/<name>.svg`.
+
+## [0.6.0] - 2026-04-25
+
+First public release — the npm + CDN cut. The library, its docs, the
+theme system, the React component layer, the test pipeline, and the
+release/CDN automation all land together — designed as one system,
+shipped as one cake. v1.0.0 is reserved for after the CDN smoke is
+verified live and the API has stabilised in production usage.
+
+### Added — Library
+
+- Six built-in themes: **Sketchbook** (default), **Press**, **Graphite**,
+  **Glass**, **Cupertino**, **Terminal**. All ship as `[data-theme="..."]`
+  blocks in a single consolidated `public/theme.css`; per-theme files
+  remain at `public/themes/<name>/theme.css` for external download.
+- 123-token theme contract (`scripts/theme-contract.json`) + validator
+  (`scripts/theme-validator.js`) that gate every theme, consolidated or
+  standalone.
+- ~120 SCSS mixins across `_mixins.scss`, `_layout.scss`, `_animations.scss`,
+  `_icons.scss`, and the `components/*.scss` partials. Mixin-first API.
+- Token-driven runtime theming via `<html data-theme="...">` attribute +
+  cookie persistence. No FOUC, no `<link href>` mutation, no hydration
+  mismatch.
+- Animation system: 12 named keyframes, motion tokens
+  (`--duration-fast/normal/slow`, `--ease`), `.cia-anim-*` and
+  `.cia-hover-*` utility classes, all respecting `prefers-reduced-motion`.
+- Utility class set (`.cia-*` namespace) for spacing, flex, grid, text,
+  color, display, position, sizing — covered in
+  [`/docs/utilities`](./src/app/docs/utilities/page.tsx).
+- Icon system in `scss/_icons.scss` with SVG and Font Awesome tracks; eight
+  starter SVGs in `public/icons/`.
+
+### Added — React component library
+
+- 45 React components built on `forwardRef` + CSS Modules: Accordion,
+  Alert, Avatar, Badge, Breadcrumb, Button, Card, Checkbox, DataTable,
+  Divider, DocsSidebar, DraftStamp, Dropdown, Example, FormField, Input,
+  Label, LaunchGate, List, Logo, LogoMark, MenuItem, Modal, Pagination,
+  Popover, Post, Principle, Progress, Radio, Seal, SearchBar, Select,
+  SiteHeader, Skeleton, Slider, Spinner, StatChip, Switch, Tabs, Tag,
+  Textarea, ThemePicker, ThemeTile, TimelineItem, Toast, Tooltip.
+
+### Added — Documentation site
+
+- Nested-route docs at `/docs` with shared shell (sidebar + on-this-page
+  TOC + prev/next footer + cookie-driven theme picker).
+- 24 static-export pages including: getting started, install (CDN /
+  npm-SCSS / React-Next / download), tokens reference, mixin API, utility
+  class reference, animation reference, accessibility reference, recipes
+  (10 composed patterns), Bootstrap migration, Tailwind migration, theme
+  authoring guide, icon authoring guide, FAQ.
+- LaunchGate component + `public/flags.json` for coming-soon and
+  announcement banner modes.
+
+### Added — Quality, CI, and release
+
+- GitHub Actions CI workflow (`.github/workflows/ci.yml`): lint, SCSS
+  lint, theme validator, library bundle build, Next static export, docs
+  artifact upload.
+- Playwright suite (`tests/`): 16 smoke tests, 5 axe-core a11y scans, 18
+  visual-regression baselines (6 themes × 3 routes). Parallel CI job.
+- `semantic-release` pipeline (`.releaserc.json` +
+  `.github/workflows/release.yml`) gated on CI success — Conventional
+  Commits drive `CHANGELOG.md`, version bumps, GitHub releases, and npm
+  publish.
+- CDN publish workflow (`.github/workflows/cdn-publish.yml`): on every
+  release, attaches `.tar.gz` + `.zip` bundles to the GitHub Release and
+  smoke-checks five jsDelivr URLs.
+- Package shaped for distribution: `exports` map (CSS bundles + SCSS
+  source + per-theme files + figma tokens), `peerDependencies` (sass
+  optional), `engines.node >= 20`, `prepublishOnly` builds bundles.
+
+### Added — Community meta
+
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1
+  adoption), `SECURITY.md` (90-day coordinated disclosure),
+  `VERSIONING.md` (SemVer + deprecation lifecycle + Conventional Commits
+  mapping).
+- Issue templates: bug report, feature request, theme submission,
+  question; pull-request template.
+- README badges (CI status + Node 20 + MIT + semantic-release).
+
+### Changed — Mixin API consolidation
+
+- **Buttons**: `btn-primary`, `btn-secondary`, `btn-outline`, `btn-ghost`,
+  and `btn-preset` are replaced by a single `btn($variant)` router. Status
+  variants (info / success / warning / error) are FREE via token
+  interpolation (`#{$variant}-default`, `#{$variant}-subtle`,
+  `#{$variant}-text`). The previous mixin names are gone — call sites
+  update to `@include btn(primary)`.
+- **Tag**: `tag-base` + `tag-removable` are replaced by
+  `tag($removable: false)`.
+- **List item**: `list-item` + `list-item-interactive` are replaced by
+  `list-item($interactive: false)`.
+- **`nav-link`** removed — was an alias for `navbar-link`. Use
+  `navbar-link` directly.
+
+### Changed — Theme system
+
+- Theme dispatch moved from runtime `<link href>` mutation to
+  `<html data-theme="...">` attribute + cookie. Eliminates Next 15 / React
+  19 hydration warnings on docs routes. The previous `cia-theme-file`
+  localStorage key is replaced by a `cia-theme` cookie.
+- **Numbered sizing scale migration (non-breaking refactor).** Numeric
+  keys (`1..N`) are now the authoritative source of truth for the internal
+  scale maps; t-shirt keys (`xs/sm/md/…`) layer on top as aliases that
+  resolve to the same values. Aligns with Radix, Open Props, IBM Carbon
+  conventions; unblocks numeric tokens (`--space-1..9`,
+  `--font-size-1..10`, …).
+
+  Both call styles continue to produce identical visual output —
+  `m.space(4)` and `m.space(md)` both resolve to `1rem`. The generator
+  emits both `--space-4` *and* `--space-md` at `:root` so themes can
+  declare either.
+
+  Mixin defaults flipped from t-shirt to numeric across `_mixins.scss`,
+  `_layout.scss`, and `components/*.scss` (~60 defaults). Theme
+  component tokens in `scss/theme/_components.scss` flipped too; radius
+  component tokens stayed t-shirt because the radius scale is
+  anchor-named (`sm/md/lg/xl/full`).
+
+  `$radius`, `$z-layers`, `$letter-spacings`, `$breakpoints`, and
+  container width aliases stay keyed by name (semantic anchor maps).
+
+- Standardized dark/light theme selector on `[data-theme="..."]`. The
+  `.theme-dark` / `.theme-light` class selectors are removed from the
+  generator and documentation. For component-scoped theming, use the
+  `generate-scoped` mixin under your own selector.
+
+### Fixed
+
+- Real fixes (not allowlist) for 7 axe-core serious violations:
+  color-contrast on home/footer; in-prose link contrast on
+  `/docs/install` + `/docs/tokens`; aria-prohibited-attr on token
+  swatches; aria-hidden-focus on the recipes-page modal demo;
+  scrollable-region-focusable on `<pre>` code samples.
+- React 19 hydration mismatch on `/docs/*` routes — root cause was
+  `usePathname()` in `DocsNav` + `DocsPrevNext` resolving differently
+  between static-export build time and client hydration. Fixed with a
+  `mounted` gate in both components.
+- 4 ESLint warnings: Popover useEffect deps, Avatar `<img>` →
+  `next/image`, Dropdown unused `_ref`, Radio unsupported
+  `aria-invalid`.
+- Eliminated Sass "unquoted color-name in interpolation" warning by
+  quoting the `black` key in `$font-weights` (`scss/_system.scss`).
+- Doc typo in `scss/README.md`: import example referenced a nonexistent
+  `primitives` module; corrected to `system`.
+
+### Removed
+
+- Hex-coded `buttonold` scratch mixin (replaced by token-driven
+  `btn-preset`, then absorbed into `btn($variant)`).
+
+### Sizing scale alias tables
+
+For reference — both call styles produce identical output. T-shirt aliases
+remain available for legacy code; numbered keys are recommended for new code.
+
+Space (`$spacing`, `$space`):
+| t-shirt | numeric | value    |
+| ------- | ------- | -------- |
+| xs      | 1       | 0.5rem   |
+| sm      | 2       | 0.75rem  |
+| —       | 3       | 0.875rem |
+| md      | 4       | 1rem     |
+| lg      | 5       | 1.5rem   |
+| xl      | 6       | 2rem     |
+| 2xl     | 7       | 3rem     |
+| 3xl     | 8       | 4rem     |
+| 4xl     | 9       | 6rem     |
+
+Extras outside the numbered scale: `0` / `none` (0), `2xs` (0.25rem).
+
+Font size (`$font-sizes`):
+| t-shirt | numeric | value    |
+| ------- | ------- | -------- |
+| xs      | 1       | 0.75rem  |
+| sm      | 2       | 0.875rem |
+| base    | 3       | 1rem     |
+| lg      | 4       | 1.125rem |
+| xl      | 5       | 1.25rem  |
+| 2xl     | 6       | 1.5rem   |
+| 3xl     | 7       | 1.875rem |
+| 4xl     | 8       | 2.25rem  |
+| 5xl     | 9       | 3rem     |
+| 6xl     | 10      | 3.75rem  |
+
+Line height (`$line-heights`):
+| named   | numeric | value |
+| ------- | ------- | ----- |
+| none    | 1       | 1     |
+| tight   | 2       | 1.25  |
+| snug    | 3       | 1.375 |
+| normal  | 4       | 1.5   |
+| relaxed | 5       | 1.625 |
+| loose   | 6       | 2     |
+
+Shadow (`$shadows-light` / `$shadows-dark`):
+| t-shirt | numeric |
+| ------- | ------- |
+| sm      | 1       |
+| md      | 2       |
+| lg      | 3       |
+| xl      | 4       |
+| 2xl     | 5       |
+
+Semantic shadow keys (`inner`, `none`) remain named.
+
+## [0.1.0] - 2026-04-15
+
+### Added
+- Initial extraction of the SCSS design system from `boiler-project-ai`.
+- `package.json` with `build`, `build:min`, and `watch` scripts.
+- Top-level `README.md` with install and usage instructions.
+- `ROADMAP.md` outlining phases through v1.0.