@getvitops/generator 0.9.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,293 @@
 # @getvitops/generator
 
+## 1.0.0
+
+### Major Changes
+
+- bb92a14: **The colour system is rebuilt on a target-prefixed grammar and a shared lightness ladder.**
+  This is a breaking change to every colour token and utility class.
+
+  ## Why
+
+  Two axes shared one class namespace — functional _planes_ (`--<role>-bg-muted`) and
+  appearance-relative _stops_ (`--color-<role>-muted`) — arbitrated by a "plane wins" rule. The
+  result was not a scale. On the shipped palette, light mode:
+
+  | class                              | resolved to  | step                                          |
+  | ---------------------------------- | ------------ | --------------------------------------------- |
+  | `bg-ui-accent-x-muted`             | stop         | 100                                           |
+  | `bg-ui-accent-muted`               | plane        | 100 — identical, so `x-muted` was a dead rung |
+  | `bg-ui-accent`                     | plane        | 50 — _lighter_ than both its "muted" rungs    |
+  | `border-ui-accent-muted` / `-bold` | stop / plane | 300 / 300 — identical                         |
+  | `text-ui-accent-bold`              | stop         | 700 — _lighter_ than `text-…-muted` (800)     |
+
+  Every family was non-monotonic, two had duplicate rungs, and `--color-<role>-muted` was
+  unreachable through any `bg-` class.
+
+  ## The new grammar
+
+  ```
+  --color-<target>-<role>[-<variant>]        target ∈ bg | text | icon | border
+  ```
+
+  The target is **inside** the name, so `bg-danger-muted` and `text-danger-muted` are different
+  tokens and there is nothing left to arbitrate. **The class name is the token name minus
+  `--color-`** — one vocabulary instead of two.
+
+  Variants are ordinal (`xx-muted` < `x-muted` < `muted` < bare < `bold` < `x-bold`) and the
+  tables are sparse: only cells that hold their contrast target exist.
+
+  ## Role kinds
+
+  `colors.roles` values may now be `{ hue, kind }` as well as a bare hue string:
+
+  ```jsonc
+  "roles": {
+    "danger":  "rust",                             // shorthand => chromatic
+    "surface": { "hue": "navy", "kind": "surface" }
+  }
+  ```
+
+  - **`surface`** — a page/panel colour: `bg-<role>` is the card, `bg-<role>-muted` the page
+    behind it, `bg-<role>-x-muted` a well, `bg-<role>-bold` the inverse surface. Full text scale.
+  - **`chromatic`** (default) — a signal colour: tints (`bg-<role>-x-muted`/`-muted`) and solids
+    (`bg-<role>-solid[-bold|-x-bold]`), with **no bare `bg-<role>`** — say how loud you mean.
+    `text-on-<role>` is the guaranteed foreground for the solid family.
+
+  ## Palette generation
+
+  Every ramp now sits on one **fixed lightness ladder** (50 → L 0.98 … 950 → L 0.21); only chroma
+  and hue vary. That is what makes a step mean the same lightness in every hue. Previously each
+  seed transposed the curve, so relative luminance at step 300 ranged from 0.253 to 0.384 across
+  the shipped palette — the same variant read differently depending on the role.
+
+  Authored colours are still reproduced **exactly**. A `seed`, an `anchors` entry or a `tones`
+  value is pinned verbatim at its nearest step; every other step takes the ladder. Snapping brand
+  colours to the ladder was measured and rejected: 11 of 18 real brand hexes moved beyond a
+  just-noticeable difference (worst ΔE-OK 0.050 — Facebook's `#1877F2` → `#0067e1`) and six left
+  sRGB gamut. Deviation is now bounded and local to pinned steps, and warns past ~0.03 L.
+
+  Two tones that claim the same step now **error** instead of one silently overwriting the other;
+  the record form (`tones: { "600": "…", "700": "…" }`) is how you resolve it.
+
+  ## New
+  - **`icon-<role>`** — a non-text tier, so a glyph may run more vivid than text. `icon` is now a
+    default utility family alongside `bg`/`text`/`border`.
+  - **`--color-border-focus`** — the focus-ring tone, taken from `ui-primary`'s solid.
+  - **Contrast is enforced at build time**, not only in tests: text ≥ APCA Lc 75 on its primary
+    background, ≥ 60 on secondary planes, icons and surface boundaries ≥ 45, both appearances.
+    A violation now fails `generate`. Chromatic text is checked against the _surface_ planes it
+    actually sits on, not only its own tints. `text-<role>-x-muted` (placeholder) and `-xx-muted`
+    (disabled) are explicitly exempt; nothing else is.
+
+  ## Migrating
+
+  Rename `--<role>-<suffix>` → `--color-<target>-<role>[-<variant>]`, and the same for classes:
+
+  | before                                  | after                                                            |
+  | --------------------------------------- | ---------------------------------------------------------------- |
+  | `--<role>-bg` / `bg-<role>` (chromatic) | `--color-bg-<role>-x-muted` / `bg-<role>-x-muted`                |
+  | `--<role>-bg-muted`                     | `--color-bg-<role>-muted`                                        |
+  | `--<role>-solid` / `-solid-bold`        | `--color-bg-<role>-solid` / `-solid-bold`                        |
+  | `--<role>-on-solid` / `text-on-<role>`  | `--color-text-on-<role>` (class unchanged)                       |
+  | `--<role>-text` / `-text-muted`         | `--color-text-<role>` / `-muted`                                 |
+  | `--<role>-border` / `-border-bold`      | `--color-border-<role>` / `-bold`                                |
+  | `--color-<role>-muted` (stop)           | judge by use: `--color-bg-<role>-muted` or `--color-text-<role>` |
+
+  **`surface` background names rotate**, value-preserving: what was `--surface-bg` (the page) is
+  now `--color-bg-surface-muted`; what was `--surface-bg-bold` (raised) is now
+  `--color-bg-surface`. Elevation is expressed by which token you reach for — page `bg-muted`,
+  card `bg` — rather than a raised/sunken pair, which is what lets a future surfaces axis flatten
+  it without touching markup.
+
+  `vitops lint` reports role classes that no longer resolve, and now derives its suggestions from
+  what the generator actually emits rather than a hand-maintained list.
+
+### Minor Changes
+
+- bb92a14: **Base page typography can now be bound to a type role, and the live editor's Body controls work.**
+
+  `typography.headings` was documented as an h1…h6 map, but the key has always been used verbatim as
+  a selector. Mapping `"body"` to your prose role now binds base page typography to that role:
+
+  ```jsonc
+  "typography": {
+    "headings": { "body": "body", "h1": "display", "h2": "heading" }
+  }
+  ```
+
+  The generator emits `body { font-family: var(--body-ff, …); line-height: var(--body-lh, …); … }`,
+  so prose inherits the role and the role's tokens become the single place it is edited.
+  `defaultConfig()` includes the binding; existing configs are unaffected until they add it.
+
+  This is what made `<wc-theme-editor>`'s **Typography → Body** controls appear dead. They set
+  `--body-lh` and friends on `:root`, but only `.font-body` read them — page prose was styled by
+  hand-written `body { line-height: 1.55 }` rules that consumers had to write precisely _because_ the
+  framework offered no binding. If you keep such a block, drop the properties the role now owns:
+  restating them shadows the role's tokens, and because that CSS is typically unlayered it wins.
+
+  **Fixed: typography edits that previewed live and were dropped on save.** The design manifest's
+  `reverseIndex` only mapped hooks a role explicitly declared, while the editor renders a control for
+  every hook. Editing a property the role omitted (`--body-ls`, `--body-tt`, …) updated the page and
+  then silently vanished from the `design-system.json` patch. Every hook of every role is now indexed.
+
+  **Added: `validate()` warns when a shadow value can't survive `drop-shadow()`.** A `--shadow-<name>`
+  token feeds both `box-shadow` (pattern geometry) and `filter: drop-shadow(…)` (the
+  `.drop-shadow-<name>` utilities and the `shadow:` state shortcut). `drop-shadow()` accepts a single
+  layer of at most three lengths — a spread radius, a second comma-separated layer or `inset`
+  invalidates the whole `filter`, so the utility renders **no** shadow while the token still looks
+  correct everywhere it is authored. Keep shadow values in that intersection.
+
+- bb92a14: Add a fourth output format, `design`, that emits `DESIGN.md` — the agent-facing brief in
+  [google-labs-code/design.md](https://github.com/google-labs-code/design.md) format.
+
+  ```sh
+  vitops generate --format design --out .     # DESIGN.md, and nothing else
+  vitops generate --format css,design         # compose it with a stylesheet
+  ```
+
+  The file is YAML front matter carrying the tokens (`colors`, `typography`, `rounded`,
+  `spacing`, `components`, cross-referenced with `{group.token}`) followed by a prose body
+  carrying the rationale — colour model, fluid scales, layout vocabulary, elevation, shape
+  cascade, component tiers, do's and don'ts. Every section is rendered from your config, so
+  it cannot describe a system the other formats don't build. Point a coding agent, a Figma
+  import, or a designer at this one file when they don't have the toolchain; `vitops docs`
+  remains the richer reference for those who do.
+
+  It is emitted with `--out .` in mind: DESIGN.md conventionally lives at a repo root beside
+  `AGENTS.md`, not in a build directory.
+
+  Three things the spec cannot express, handled the same way every time and explained in the
+  emitted prose so the file is self-describing:
+  - **Fluid `clamp()` sizes** → the maximum (desktop) value, since a spec `Dimension` is a
+    bare number plus px/em/rem.
+  - **Dark mode** → light values only, with the automatic functional flip explained. Role
+    tokens are emitted as `{colors.<hue>-<step>}` references into the raw ramps rather than
+    flattened hexes, so the role → ramp lineage survives the export — flattening them is
+    exactly what breaks dark mode downstream.
+  - **A `50%` radius** → dropped from `rounded` (it is not a `Dimension`) and named in the
+    Shapes prose instead, so nothing is silently lost.
+
+  **New:** an optional `meta` key in `design-system.json` (`{ name, description }`) supplies
+  the brand name and the Overview paragraph. It affects no other format.
+
+  **New:** `StylesheetFormat` (`Exclude<Format, 'design'>`), exported from
+  `@getvitops/generator`. `@getvitops/astro`'s `css.format` now takes that narrower type —
+  `design` produces no stylesheet to inject, so passing it there is a type error rather than
+  a missing-file failure at build time. `vitops lint --format` is likewise restricted to the
+  three CSS formats. No change for anyone already passing `tailwind`, `css` or `bricks`.
+
+- bb92a14: Generate legal documents from your site config
+
+  `vitops legal` renders a privacy policy, terms of service and cookie notice from a site
+  config, in markdown, HTML or EmDash Portable Text:
+
+  ```sh
+  vitops legal --out ./content                 # every enabled document, as markdown
+  vitops legal --doc privacy --format html     # one document, as an HTML fragment
+  ```
+
+  The documents are **derived from your config**, not filled into a form. The analytics
+  provider they name is the one whose ID you set; the personal information they list is what
+  your configured forms actually collect; the countries they name come from the providers you
+  use. So a provider swap updates the policy on the next build, and the fix for a wrong policy
+  is a corrected config — hand-editing the output is overwritten.
+
+  Enable documents under `legal`, which gains the facts the prose asserts:
+
+  ```jsonc
+  {
+    "legal": {
+      "jurisdiction": "ca", // only 'ca' (PIPEDA) ships today
+      "privacyPolicy": {
+        "enabled": true,
+        "lastUpdated": "2026-08-01",
+        "retention": "24 months after our last contact with you",
+        // Third parties the config cannot imply. Analytics, Turnstile and your
+        // deploy platform are detected automatically — list only the rest.
+        "processors": [
+          {
+            "name": "Stripe",
+            "purpose": "payment processing",
+            "country": "the United States",
+          },
+        ],
+      },
+      "termsOfService": { "enabled": true },
+      "cookieConsent": {
+        "enabled": true,
+        "type": "opt-in",
+        "categories": ["Essential", "Analytics"],
+      },
+    },
+  }
+  ```
+
+  Delivery, by stack:
+  - **Any stack** — `vitops legal`. No integration code; prints to stdout without `--out`.
+  - **WordPress/Bricks** — `vitops generate --site <path>` also writes `dist/legal/*.html`, and
+    the theme loader now registers `[vitops_legal doc="privacy"]` to render one in a page. The
+    document updates on the next deploy with no action in WordPress.
+  - **Astro** — `getvitops({ legal: { input: 'site.json', out: 'src/content/legal' } })` writes
+    markdown into a content collection and re-renders when the site config changes. It needs a
+    `css` config (that is what registers the Vite plugin); without one, use the CLI.
+  - **EmDash** — `--format portable-text`, pasted into the admin.
+
+  Also new on the public API: `generateLegal()`, `renderMarkdown()`, `renderNodes()`,
+  `derivePolicyVars()`, `parseMarkdown()` / `toHtmlFragment()` / `toPortableText()`, and
+  `resolvePrivacyContact()`.
+
+  Two things to know before you publish anything this produces:
+  - **It is not legal advice.** Every document opens with a review banner saying so. The
+    bundled terms-of-service prose in particular is generic website boilerplate and
+    deliberately does not cover sales, refunds, subscriptions, accounts or user-generated
+    content — a site doing any of those needs clauses drafted for it.
+  - **It is only as true as your config.** A policy asserting things your site does not do is
+    worse than no policy. Check that the config describes reality before you ship the output.
+
+  `validateSite` now rejects a config that enables a privacy policy without a contact for
+  privacy requests or a `domains.canonical`, since both are interpolated into sentences that
+  would otherwise render blank.
+
+- eeb059f: **A pattern's fill can now be undone — flat, border-only cards.**
+
+  `background` was the only `base` property with no per-pattern override hook. Every other one had
+  `--p-card`, `--br-card`, `--b-card`, `--ds-card`; the background was hard-wired, so a flat card
+  meant an inline `style="background: transparent"` rather than the documented mechanism.
+
+  Two additions:
+  - **`background` and `background-color` join `BASE_HOOK`**, both mapping to `bg`, since patterns
+    author either spelling. `.card` now emits
+    `background: var(--bg-card, var(--surface-bg))`. This also covers the fill the generator
+    _injects_ for a `default_role` pattern, so `.cta` gets `--bg-cta`.
+
+    Role variants (`.card-danger`) are emitted as separate rules and stay unwrapped, so tuning
+    `--bg-card` adjusts the default fill without silently defeating them.
+
+  - **`bg-transparent` and `bg-inherit` utilities** in the `css` and `bricks` formats. Neither is
+    derived from the palette, so neither the generated scale nor Bricks' palette import produced
+    them. The `tailwind` format deliberately emits neither — Tailwind ships both as built-ins, the
+    same deferral it makes for the `TW_CLASH` names.
+
+  ```html
+  <!-- via the hook — set it anywhere, including :root for every card -->
+  <div class="card" style="--bg-card: transparent; --ds-card: none">…</div>
+
+  <!-- or compose the utility, which is what most authors will reach for -->
+  <div class="card bg-transparent" style="--ds-card: none">…</div>
+  ```
+
+  There is no utility for the shadow, so `--ds-card: none` is how you drop it in every format.
+
+  These hooks also reach the live theme editor: `--bg-card`, `--bg-btn` and `--bg-status` now
+  appear in `design-manifest.json`'s reverse index, so pattern backgrounds are tunable in the
+  browser alongside their geometry.
+
+### Patch Changes
+
+- Updated dependencies [bb92a14]
+  - @getvitops/utils@1.0.0
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,8 @@
 # @getvitops/generator
 
-Generate design-system outputs — **Bricks** (WordPress), standalone **CSS**, and **Tailwind
-v4** (Astro/EmDash) — from a single `design-system.json`. This is the library that powers
+Generate design-system outputs — **Tailwind v4** (Astro/EmDash), **Bricks** (WordPress), an
+agent-facing **`DESIGN.md`** brief, and standalone **CSS** — from a single `design-system.json`.
+This is the library that powers
 [`@getvitops/cli`](https://www.npmjs.com/package/@getvitops/cli) and
 [`@getvitops/vite`](https://www.npmjs.com/package/@getvitops/vite).
 
@@ -10,7 +11,7 @@ import { generate, validate, defaultConfig } from '@getvitops/generator';
 
 await generate({
   input: './design-system.json', // path or a config object
-  format: 'tailwind', // 'bricks' | 'css' | 'tailwind'
+  format: 'tailwind', // 'tailwind' | 'bricks' | 'design' | 'css'
   outDir: './src/styles',
 });
 ```
@@ -29,8 +30,19 @@ await generate({
 | format     | writes                                                                                                   |
 | ---------- | -------------------------------------------------------------------------------------------------------- |
 | `tailwind` | `tailwind.css` (self-contained, `@import "tailwindcss"`) + `tokens.json`                                 |
-| `css`      | `styles.css` (bundled, standalone) + `tokens.json` + `design-manifest.json`                              |
 | `bricks`   | `styles.min.css`, `bricks-colors-*.json`, `bricks-variables.json`, `tokens.json`, JS, `bricks/`, `docs/` |
+| `design`   | `DESIGN.md` — and nothing else                                                                           |
+| `css`      | `styles.css` (bundled, standalone) + `tokens.json` + `design-manifest.json`                              |
+
+`design` is the odd one out: it emits **no CSS**, just the agent-facing brief in
+[design.md](https://github.com/google-labs-code/design.md) format — YAML token front matter plus a
+prose body, meant to sit at a repo root beside `AGENTS.md` (so run it with `outDir: '.'`). It's what
+you hand to a tool that has never heard of Vitops; the stylesheet formats are what the browser gets.
+`Format` covers all four, and `StylesheetFormat` (`Exclude<Format, 'design'>`) is the narrower type
+anything expecting an importable stylesheet uses.
+
+`generate()` takes one format per call, so pair the brief with a stylesheet by calling it twice
+(`@getvitops/cli`'s `--format` accepts a comma-separated list and does exactly that).
 
 See the [`design-system.json` schema](./schema.json) for the config shape.
 

package/assets/bricks/load.php

@@ -6,13 +6,15 @@
  *
  *   require_once get_stylesheet_directory() . '/dist/bricks/load.php';
  *
- * It does three things:
+ * It does the following:
  *   1. Registers every repo-owned Bricks element under dist/bricks/elements/.
  *   2. Enqueues the framework CSS + JS bundles — polyfills.js and elements.js as
  *      ES modules (so the Lit custom elements upgrade), deferred.js with `defer`.
  *      The enqueue runs on `wp_enqueue_scripts`, which the Bricks builder canvas
  *      iframe also fires, so the elements upgrade while editing too.
  *   3. Registers a "Vitops" builder category so the elements group together.
+ *   4. Defaults the design system to dark mode.
+ *   5. Registers [vitops_legal] for the generated legal documents.
  *
  * Owned by the framework repo (vitops: bricks/); copied into the theme's
  * dist/bricks/ on build — do not hand-edit in the theme.
@@ -127,3 +129,46 @@ add_filter(
 	},
 	99
 );
+
+/**
+ * 5. [vitops_legal doc="privacy"] — render a generated legal document.
+ *
+ * The build emits dist/legal/*.html from the site config, so the document updates
+ * on the next deploy with no action in WordPress. Drop this shortcode into a
+ * Bricks page (or any content) and the fragment renders there, styled by the
+ * framework CSS the theme already loads.
+ *
+ * `doc` is matched against a fixed allowlist rather than interpolated into the
+ * path. The attribute is author-supplied and lands in a filesystem read, so
+ * anything less would be a traversal waiting to happen — an unknown value
+ * renders nothing.
+ *
+ * The fragment is generated by our own build from a closed markdown subset, and
+ * is already HTML-escaped at render time. It is echoed as-is deliberately:
+ * running it through wp_kses would strip the markup the document depends on.
+ */
+add_shortcode(
+	'vitops_legal',
+	function ( $atts ) {
+		$allowed = array(
+			'privacy' => 'privacy-policy',
+			'terms'   => 'terms-of-service',
+			'cookies' => 'cookie-notice',
+		);
+
+		$atts = shortcode_atts( array( 'doc' => 'privacy' ), $atts, 'vitops_legal' );
+		$key  = is_string( $atts['doc'] ) ? strtolower( trim( $atts['doc'] ) ) : '';
+
+		if ( ! isset( $allowed[ $key ] ) ) {
+			return '';
+		}
+
+		$path = get_stylesheet_directory() . '/dist/legal/' . $allowed[ $key ] . '.html';
+
+		if ( ! file_exists( $path ) ) {
+			return '';
+		}
+
+		return file_get_contents( $path );
+	}
+);

package/assets/css/animation.css

@@ -311,8 +311,8 @@
      @supports block it resolves to that transparent value. So default to the
      functional text tokens (they flip with the appearance) with a literal
      backstop, since this is precisely the declaration that must never fail. */
-  --_reveal-from: var(--text-reveal-color-from, var(--neutral-text-x-muted, #9099a8));
-  --_reveal-to: var(--text-reveal-color-to, var(--neutral-text, #05070d));
+  --_reveal-from: var(--text-reveal-color-from, var(--color-text-neutral-x-muted, #9099a8));
+  --_reveal-to: var(--text-reveal-color-to, var(--color-text-neutral, #05070d));
   /* Fallback baseline: ordinary visible text in the start color. */
   color: var(--text-reveal-color-from, currentColor);
 }

package/assets/css/patterns/carousel.css

@@ -64,7 +64,7 @@
       border: none;
       border-radius: 50%;
       color: var(--carousel-button-color, currentColor);
-      background: var(--surface-bg-muted);
+      background: var(--color-bg-surface-muted);
       opacity: 0.9;
       transition:
         opacity 0.2s ease,
@@ -73,7 +73,7 @@
 
     &::scroll-button(*):hover {
       opacity: 1;
-      background: var(--color-surface-muted);
+      background: var(--color-bg-surface-muted);
     }
 
     &::scroll-button(*):focus-visible {
@@ -211,7 +211,7 @@
     block-size: 2rem;
     border: none;
     border-radius: 50%;
-    background: var(--surface-bg-muted);
+    background: var(--color-bg-surface-muted);
     color: var(--carousel-button-color, currentColor);
     opacity: 0.7;
     cursor: pointer;

package/assets/css/patterns/code.css

@@ -10,8 +10,8 @@
 :where(:not(pre) > code) {
   font-family: var(--font-mono);
   font-size: 0.85em;
-  background: var(--neutral-border);
-  color: var(--neutral-text);
+  background: var(--color-border-neutral);
+  color: var(--color-text-neutral);
   padding: 0.1em 0.4em;
   border-radius: var(--br-default);
 }

package/assets/css/patterns/combobox.css

@@ -20,7 +20,7 @@
     border-radius: var(--_br);
 
     &:focus {
-      outline: 2px solid var(--combobox-focus-color, var(--color-brand-primary-muted));
+      outline: 2px solid var(--combobox-focus-color, var(--color-border-focus));
       outline-offset: 2px;
     }
   }
@@ -35,7 +35,7 @@
     border: var(--_b);
     border-radius: var(--_br);
     box-shadow: var(--_ds);
-    background: var(--surface-bg);
+    background: var(--color-bg-surface);
     max-block-size: 15rem;
     overflow-y: auto;
     list-style: none;
@@ -55,7 +55,7 @@
 
     &:hover,
     &[aria-selected='true'] {
-      background: var(--color-surface-muted);
+      background: var(--color-bg-surface-muted);
     }
 
     &[aria-disabled='true'] {

package/assets/css/patterns/comment.css

@@ -62,7 +62,7 @@
     grid-column: 1 / -1;
     margin-inline-start: var(--comment-indent, 2rem);
     padding-inline-start: var(--comment-indent, 2rem);
-    border-inline-start: 2px solid var(--color-surface-muted);
+    border-inline-start: 2px solid var(--color-bg-surface-muted);
     display: flex;
     flex-direction: column;
     gap: 1rem;

package/assets/css/patterns/copy.css

@@ -38,7 +38,7 @@
     }
 
     &:focus-visible {
-      outline: 2px solid var(--copy-focus-color, var(--color-brand-primary-muted));
+      outline: 2px solid var(--copy-focus-color, var(--color-border-focus));
       outline-offset: 2px;
     }
   }
@@ -66,8 +66,8 @@
     font-size: 0.75rem;
     border-radius: 0.25rem;
     white-space: nowrap;
-    background: var(--surface-text);
-    color: var(--surface-bg);
+    background: var(--color-text-surface);
+    color: var(--color-bg-surface);
     opacity: 0;
     visibility: hidden;
     transition:

package/assets/css/patterns/dialog.css

@@ -25,8 +25,8 @@ dialog.dialog {
   border: var(--_b);
   border-radius: var(--_br);
   box-shadow: var(--_ds);
-  background: var(--surface-bg);
-  color: var(--surface-text);
+  background: var(--color-bg-surface);
+  color: var(--color-text-surface);
   max-block-size: calc(100vh - 2rem);
 
   &::backdrop {

package/assets/css/patterns/drawer.css

@@ -15,8 +15,8 @@
   padding: var(--_p);
   border: var(--_b);
   box-shadow: var(--_ds);
-  background: var(--surface-bg);
-  color: var(--surface-text);
+  background: var(--color-bg-surface);
+  color: var(--color-text-surface);
   max-inline-size: none;
   max-block-size: none;
 

package/assets/css/patterns/forms.css

@@ -32,7 +32,7 @@
 
   .form-group__error {
     font-size: var(--form-error-size, 0.75rem);
-    color: var(--color-danger-bold);
+    color: var(--color-text-danger);
     display: flex;
     align-items: center;
     gap: 0.25rem;
@@ -87,7 +87,7 @@ fieldset.fieldset,
   border: var(--_b);
   border-radius: var(--_br);
   padding: var(--_p);
-  background: var(--surface-bg);
+  background: var(--color-bg-surface);
 }
 
 /* ── Range + colour controls ───────────────────────────────────────────────── */
@@ -95,7 +95,7 @@ fieldset.fieldset,
  * natively, in both appearances, with no pseudo-element rewriting. The colour
  * swatch only needs its chrome removed so the well fills the control box. */
 input[type='range'] {
-  accent-color: var(--range-accent, var(--ui-primary-solid));
+  accent-color: var(--range-accent, var(--color-bg-ui-primary-solid));
   inline-size: 100%;
   min-inline-size: 0;
 }
@@ -202,7 +202,7 @@ input[type='color'] {
     block-size: var(--_check-size);
     border: var(--_b);
     border-radius: var(--_br);
-    background: var(--surface-bg);
+    background: var(--color-bg-surface);
     color: #fff;
     display: flex;
     align-items: center;
@@ -225,8 +225,8 @@ input[type='color'] {
   }
 
   input:checked + .custom-check__box {
-    background: var(--brand-primary-solid);
-    border-color: var(--brand-primary-solid);
+    background: var(--color-bg-brand-primary-solid);
+    border-color: var(--color-bg-brand-primary-solid);
 
     .custom-check__indicator {
       opacity: 1;
@@ -235,7 +235,7 @@ input[type='color'] {
   }
 
   input:focus-visible + .custom-check__box {
-    outline: 2px solid var(--check-focus-color, var(--color-brand-primary-muted));
+    outline: 2px solid var(--check-focus-color, var(--color-border-focus));
     outline-offset: 2px;
   }
 
@@ -288,7 +288,7 @@ input[type='color'] {
     inline-size: var(--_switch-width);
     block-size: var(--_switch-height);
     border-radius: var(--br-switch-track, var(--br-pill, 999px));
-    background: var(--color-surface-muted);
+    background: var(--color-bg-surface-muted);
     transition: background-color 0.2s ease;
   }
 
@@ -306,7 +306,7 @@ input[type='color'] {
   }
 
   input:checked + .switch__track {
-    background: var(--brand-primary-solid);
+    background: var(--color-bg-brand-primary-solid);
 
     .switch__thumb {
       inset-inline-start: calc(100% - var(--_switch-thumb-size) - 2px);
@@ -314,7 +314,7 @@ input[type='color'] {
   }
 
   input:focus-visible + .switch__track {
-    outline: 2px solid var(--switch-focus-color, var(--color-brand-primary-muted));
+    outline: 2px solid var(--switch-focus-color, var(--color-border-focus));
     outline-offset: 2px;
   }
 
@@ -360,7 +360,7 @@ select.custom-select {
   cursor: pointer;
 
   &:focus-visible {
-    outline: 2px solid var(--select-focus-color, var(--color-brand-primary-muted));
+    outline: 2px solid var(--select-focus-color, var(--color-border-focus));
     outline-offset: 2px;
   }
 }

package/assets/css/patterns/grouped.css

@@ -9,7 +9,7 @@
   --_bs: var(--bs, solid);
   border-width: var(--_bw);
   border-style: var(--_bs);
-  border-color: var(--bc, var(--surface-border, currentColor));
+  border-color: var(--bc, var(--color-border-surface, currentColor));
 }
 
 /* ── Group — collapse border-radius (+ shared borders) across direct children ─

package/assets/css/patterns/icon.css

@@ -57,11 +57,11 @@
   transition: background-color 0.15s ease;
 
   &:hover {
-    background: var(--color-surface-muted);
+    background: var(--color-bg-surface-muted);
   }
 
   &:focus-visible {
-    outline: 2px solid var(--icon-button-focus-color, var(--color-brand-primary-muted));
+    outline: 2px solid var(--icon-button-focus-color, var(--color-border-focus));
     outline-offset: 2px;
   }