@getvitops/generator 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,464 @@
 # @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
+
+- **The `tailwind` format now emits the full role colour vocabulary.** It previously emitted only
+  the functional role utilities, so 87 classes — `bg-<role>-x-muted`, `bg-<role>-bold`,
+  `bg-<role>-x-bold`, `text-<role>-bold`, `text-<role>-x-bold`,
+  `border-<role>-{muted,x-muted,x-bold}`, for every role — existed in the `css` and `bricks`
+  outputs and silently did nothing in `tailwind`. Nothing in the test suite built the tailwind
+  format, so the divergence was invisible; it was found by a consumer who hand-forked four
+  background planes into their own stylesheet to work around the absence.
+
+  All three formats now render from one emitter (`roleColorUtilities()`), which resolves the
+  plane-vs-stop namespace collision explicitly instead of relying on the CSS minifier dropping a
+  shadowed rule. No class changes meaning, and the `css`/`bricks` output is unchanged.
+
+  Also fixed in the tailwind format:
+  - `colors.utilities` is now honoured. It was hardcoded to `bg`/`text`/`border`, so enabling
+    `outline`/`fill`/`stroke` worked in `css`/`bricks` and was ignored here. (For raw hue scales
+    it remains a floor rather than a ceiling — those are `@theme` colours, and Tailwind derives
+    every colour family from them on demand.)
+  - **Component container queries are no longer stripped.** The pass that drops the framework's
+    pre-expanded `md-*` breakpoint utilities (Tailwind regenerates those as `@md:`) matched every
+    `@container (min-width: …)` block, including component behaviour — most visibly the
+    sitenav's, so `.sitenav--bp-{sm,md,lg,xl}` were removed and the nav stayed in its mobile
+    layout at every width.
+
+  New: **`vitops lint`** reports framework classes in your source that resolve to nothing — the
+  failure mode where an unknown utility looks exactly like a working one. It is format-aware
+  (`md-flex-row` is a real class in `css`/`bricks` and inert in `tailwind`) and only judges
+  classes anchored to your own config, so it stays quiet on Tailwind's utilities and your own.
+
+  ```
+  vitops lint --format tailwind --src src
+  ```
+
+- **The `css` and `bricks` bundles now ship cascade layers, so a utility can override a pattern.**
+
+  `class="card bg-danger-muted"` previously tinted the card in the `tailwind` format and silently
+  did nothing in `css`/`bricks`: every colour utility was emitted before every pattern and both sat
+  at `0-1-0`, so the pattern won on source order. The bundle now emits
+
+  ```css
+  @layer vitops.base, vitops.components, vitops.utilities;
+  ```
+
+  - `vitops.base` — the UA reset and the pure `:root` token blocks
+  - `vitops.components` — the animation engine, structural layout, and every pattern
+  - `vitops.utilities` — `bg-*`, `text-*`, `border-*`, `drop-shadow-*`, `font-*`, animation
+    effects, and the display/`sr-only` families
+
+  No rule changed — 1482 rules before, 1482 after — only precedence.
+
+  **What this changes for you.** Unlayered CSS beats every cascade layer regardless of specificity,
+  so your own stylesheet, an Astro scoped `<style>`, or a Bricks-authored class now overrides the
+  framework with no `!important` and no specificity escalation. That is the intended override story
+  and the reason to layer at all.
+
+  **Migration — only if you ship a reset.** An unlayered reset will now beat the framework
+  component rules it used to lose to; a bare `p { margin: 0 }` defeats `.rhythm`. Put it in a layer
+  and declare the order **before** the stylesheet loads:
+
+  ```html
+  <style>
+    @layer my.reset, vitops.base, vitops.components, vitops.utilities;
+  </style>
+  <link rel="stylesheet" href="/styles.css" />
+  ```
+
+  Declaring it _after_ the link makes `my.reset` a name introduced later, which sorts **last** —
+  highest priority — and the reset wins anyway. That ordering rule is the one non-obvious step.
+
+  The `tailwind` format is byte-identical. Its utilities are `@utility` definitions, which Tailwind
+  already places in a layer above `components` and which are what make `hover:`/`@md:` variants
+  work; wrapping them ourselves would win the cascade and lose the variants.
+
+  Known gap: `layout.css` mixes structural rules (`.rhythm`, `.centered`) with utilities (`.m-*`,
+  `.flex`, `.split-*`) in one partial, so it sits in `vitops.components` whole and its utility half
+  cannot yet override a pattern. Splitting it is tracked separately.
+
+### Patch Changes
+
+- **Fixed: `vitops init` and `vp create` scaffolded configs referencing tokens that no longer
+  exist.** `defaultConfig()` and the EmDash template still pointed at `--color-surface-xl` and
+  `--color-surface-xxl`, aliases from the named-step colour scale removed in 0.6. A scaffolded
+  project therefore got a `card` with no background and an invalid default border colour, with
+  nothing reporting it. Both now use `--surface-bg` / `--surface-bg-muted`. The EmDash template
+  also dropped its `patterns.radii.card` key, which collided with the `card` pattern on
+  `--br-card` — the collision `validate()` has been warning about (the `panel` group already
+  supplies the same radius, so nothing changes visually).
+
+  **Fixed: `.text-reveal` rendered invisible text.** Its gradient consumed
+  `--text-reveal-color-from`/`-to` with no defaults, so unless a consumer set both, the `var()`
+  substitution failed, `background` became invalid at computed-value time, and the accompanying
+  `color: transparent` left the text with no way to render. Both tones now default to the
+  functional text tokens.
+
+  **Fixed: `.bordered` fell back to `currentColor`** via a reference to `--color-surface-xl`,
+  which the generator never emitted. It now resolves `--surface-border`.
+
+  **New: `validate()` warns when a required role is missing.** `colors.roles` is an open map —
+  any name works and generates a full token set — but the shipped component CSS references
+  `brand-primary`, `danger`, `neutral`, `surface`, `ui-primary` and `warning` with no fallback,
+  so omitting one leaves those components uncoloured. This is a warning, not an error; the
+  required list is re-derived from the CSS partials by a test so it cannot drift.
+
+  `vitops docs` and `vitops agents` now surface config warnings (on stderr, so piping `docs` is
+  unaffected). They previously discarded them, unlike `generate` and `validate`.
+
+  Docs corrections, all in the generated bundle:
+  - **Raw scale classes are frozen and do not remap in dark mode** — stated explicitly for the
+    first time, with a migration table to the role equivalents. The dark-mode guarantee only ever
+    applied to functional role tokens, and nothing said so.
+  - **Roles are extensible over a required core** — the schema description and class reference
+    read as a closed enumeration, which is why a consumer forked their own colour layer rather
+    than adding a role.
+  - **The `md:` / `@md:` / `md-` distinction** in the tailwind format: `@md:` uses the framework's
+    breakpoints, `md:` works but uses Tailwind's (which differ — `sm:` is 40rem, `@sm:` is 30rem),
+    and `md-` is silently inert. Plus a note that registering `--container-*` also re-points
+    Tailwind's `max-w-*` scale.
+  - The css and bricks bundles now carry a `/*!` banner pointing at `npx vitops docs classes`
+    (the previous plain comment was stripped by the minifier, so it never reached the file).
+
+  Contrast checking now covers **every** background plane a role emits (`bg`, `bg-muted`, and
+  `bg-bold`), not just `bg` — body text on a `card` was previously unguaranteed.
+
+- Docs now name both dark-mode attributes. The generated colour docs still described the
+  dark flip as hanging off `:root[data-brx-theme="dark"]` alone, from before the selector
+  also matched `:root[data-theme="dark"]` (the attribute `<color-scheme-toggle>` writes) —
+  so a non-Bricks consumer reading `vitops docs color` would wire up an attribute that
+  nothing matches. The selector moved into `shared.ts` as `DARK_SEL` (also exported from
+  the package index) and the docs interpolate it, so the two can't drift again.
+- c949cae: `vitops init` no longer scaffolds a config that warns on its own output.
+
+  `defaultConfig()` declared `patterns.radii.card`, a key named after the `card` pattern — the exact
+  collision `validate()` started reporting in 0.8.0. The primitive won `--br-card`, shadowing the
+  pattern's override hook and leaving its `--br-card-group` alias unreachable, so a scaffolded project
+  was warned about a config it had just been given.
+
+  The key is dropped. This is **value-preserving**: `card` belongs to the `panel` group, which already
+  carries the same `0.5rem`, so `--br-card-group` → `--br-panel` → `0.5rem` renders identically.
+
+  **Migration:** none for existing configs — your `design-system.json` is not touched. If you copied
+  the scaffold and reference `var(--br-card)` directly in hand-written CSS, note it is now an
+  _override hook_ (undefined until you set it) rather than a defined primitive; read `--br-card-group`
+  instead, or keep your own `radii` key under a name no pattern uses.
+
+- **The theme editor no longer dims the page it's editing.**
+
+  The panel used `.drawer`'s scrim and `popover="auto"`, which fought the whole purpose of a live
+  editor: the page you were tuning sat behind a 4px blur, and the first click on it dismissed the
+  panel. It is now modeless — no scrim, and clicking through to the page keeps it open. Escape still
+  closes it (wired explicitly, since `popover="manual"` doesn't provide it), as does the × button.
+
+  **New: `.drawer--modeless`.** The same treatment is available to any drawer — a side panel you work
+  _alongside_ rather than through (an inspector, a live editor, a filter rail). Pair it with
+  `popover="manual"`:
+
+  ```html
+  <div class="drawer drawer--right drawer--modeless" popover="manual">…</div>
+  ```
+
+  An `auto` popover light-dismisses on the first outside click, which is exactly the interaction a
+  modeless panel exists to permit — so `manual` is part of the pattern, not an afterthought. It also
+  drops Escape, so give the panel a visible close control.
+
+  **Added:** a drift guard tying `<wc-theme-editor>`'s dark-override selector to the generator's
+  `DARK_SEL`. The two must match or the editor's dark-mode edits land on a rule the page never
+  matches — a failure that is invisible in light mode, so nothing would have caught it.
+  - @getvitops/utils@0.9.0
+
 ## 0.8.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

@@ -303,6 +303,16 @@
    failure leaves readable text rather than blank space. Scroll-timeline is also
    guarded — without it the text simply shows the final (to) color, still legible. */
 .text-reveal {
+  /* Both tones MUST default, and NOT to currentColor. They are consumed by the
+     gradient below, where a var() substitution failure makes `background`
+     invalid at computed-value time — which, with the `color: transparent` in
+     that same block, renders the text completely invisible rather than
+     degrading. currentColor is unusable there for the same reason: inside the
+     @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(--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);
 }
@@ -313,8 +323,8 @@
       --text-reveal-background,
       linear-gradient(
         var(--text-reveal-slant, 90deg),
-        var(--text-reveal-color-to) 50%,
-        var(--text-reveal-color-from) 50%
+        var(--_reveal-to) 50%,
+        var(--_reveal-from) 50%
       )
     );
     background-size: 200% 100%;

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'] {