@getvitops/generator 0.8.0 → 0.9.0

package/dist/index.mjs

@@ -6,6 +6,149 @@ import { transform } from "lightningcss";
 import * as z from "zod/mini";
 import { generateOklchPalette, hexToOklch, oklchStringToHex, pickOn } from "@getvitops/utils/color";
 
+//#region src/shared.ts
+/**
+* Data shared between the generator (`generate.ts`) and the docs bundle
+* (`docs.ts`). Lives in its own module because `generate.ts` imports `docs.ts` —
+* importing back the other way would be a cycle.
+*/
+/**
+* Selector the dark functional-token flip hangs off.
+*
+* `data-brx-theme` is Bricks' own attribute — Bricks sets it, so it's what the
+* WordPress target needs. Nothing sets it anywhere else, which meant the dark
+* flip was unreachable outside Bricks: the shipped `<color-scheme-toggle>` web
+* component writes `documentElement.dataset.theme` (i.e. `data-theme`), so
+* clicking "Dark" changed an attribute no rule matched. Matching both makes the
+* component work on every target without changing what Bricks already does.
+*
+* Note this covers the explicit choice only — there is deliberately no
+* `prefers-color-scheme` block, so the toggle's "System" position currently
+* resolves to light. Adding one would flip every existing consumer site dark for
+* dark-OS users, which is a product decision, not a bug fix.
+*
+* Shared so the docs quote the selector the generator actually emits.
+*/
+const DARK_SEL = ":root[data-brx-theme=\"dark\"], :root[data-theme=\"dark\"]";
+/**
+* Roles the shipped CSS partials reference with NO fallback, so a config that
+* omits one leaves those rules resolving to nothing — an invalid declaration,
+* not a graceful degrade.
+*
+* `colors.roles` is an open record: any name works and generates a full token
+* set, utilities and dark flip. But the framework's own component CSS is
+* written against these six, so "roles are arbitrary" is only half true — they
+* are *extensible*, over a required core. `validate()` warns when one is
+* missing; `required-roles.test.ts` re-derives this list from the partials so
+* it cannot drift as components are added.
+*
+* Kept as a constant rather than scanned at call time because `validate()` is
+* a pure function — the CLI, the Vite plugin and `toJSONSchema` all import it,
+* and none of them should touch the filesystem to answer "is this config ok?".
+*/
+const REQUIRED_ROLES = [
+	"brand-primary",
+	"danger",
+	"neutral",
+	"surface",
+	"ui-primary",
+	"warning"
+];
+/**
+* The functional-token and emphasis-stop suffixes a role resolves to. Shared so
+* the required-roles drift test greps for exactly what the generator emits.
+*/
+const ROLE_TOKEN_SUFFIXES = [
+	"bg",
+	"bg-muted",
+	"bg-bold",
+	"border",
+	"border-bold",
+	"solid",
+	"solid-bold",
+	"on-solid",
+	"text",
+	"text-muted",
+	"text-x-muted"
+];
+/**
+* Pattern base geometry props → per-pattern override-hook shorthand. Each hook
+* wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
+* consumer restyles one pattern by setting one variable. The hook is named after
+* the pattern's key, not its class.
+*/
+const BASE_HOOK = {
+	padding: "p",
+	"border-radius": "br",
+	border: "b",
+	"box-shadow": "ds",
+	"font-size": "fs"
+};
+/**
+* Framework utility classes whose names collide with Tailwind's own defaults.
+* The `tailwind` format strips any rule targeting these — Tailwind provides
+* them, so consumers use Tailwind's utilities for these names instead.
+*/
+const TW_CLASH = new Set([
+	"block",
+	"inline",
+	"inline-block",
+	"flow-root",
+	"flex",
+	"inline-flex",
+	"grid",
+	"inline-grid",
+	"table",
+	"inline-table",
+	"table-caption",
+	"table-cell",
+	"table-row",
+	"contents",
+	"hidden",
+	"list-item",
+	"static",
+	"fixed",
+	"absolute",
+	"relative",
+	"sticky",
+	"isolate",
+	"visible",
+	"invisible",
+	"collapse",
+	"sr-only",
+	"not-sr-only",
+	"flex-row",
+	"flex-row-reverse",
+	"flex-col",
+	"flex-col-reverse",
+	"flex-wrap",
+	"flex-nowrap",
+	"items-start",
+	"items-end",
+	"items-center",
+	"items-baseline",
+	"items-stretch",
+	"justify-start",
+	"justify-end",
+	"justify-center",
+	"justify-between",
+	"justify-around",
+	"justify-evenly",
+	"content-start",
+	"content-end",
+	"content-center",
+	"content-between",
+	"content-around",
+	"content-evenly",
+	"text-left",
+	"text-center",
+	"text-right",
+	"text-justify",
+	"text-start",
+	"text-end"
+]);
+
+//#endregion
 //#region src/schema.ts
 /**
 * Canonical `design-system.json` schema — the single source of truth.
@@ -42,7 +185,7 @@ const UtilityName = z.enum([
 ]);
 const Colors = desc(z.object({
 	palette: desc(z.record(z.string(), Ramp), "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`)."),
-	roles: desc(z.record(z.string(), z.string()), "Maps each semantic role (neutral, surface, ui-primary/secondary/accent, brand-primary/secondary, info, success, warning, danger) to the palette hue backing it. The generator derives every role's FUNCTIONAL tokens (`--<role>-{bg,bg-muted,border,border-bold,solid,solid-bold,on-solid,text,text-muted,text-x-muted}`) plus emphasis stops from the hue's scale, and dark mode flips automatically — there is no per-appearance scheme grammar."),
+	roles: desc(z.record(z.string(), z.string()), `Maps semantic role names onto palette hues. Role names are ARBITRARY — add a key and the generator emits that role's full FUNCTIONAL token set (\`--<role>-{bg,bg-muted,border,border-bold,solid,solid-bold,on-solid,text,text-muted,text-x-muted}\`), its emphasis stops, its dark-mode flip and its utility classes. Dark mode flips automatically; there is no per-appearance scheme grammar. Six roles are a required core, because the shipped framework CSS references them with no fallback: ${REQUIRED_ROLES.join(", ")}. Conventional additions are ui-secondary/accent, brand-secondary, info and success.`),
 	utilities: z.optional(desc(z.array(UtilityName), "Which colour utility-class families to emit (`bg-*`, `text-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, border."))
 }), "The colour system (the only required section): `palette` hues become generated OKLCH scales; `roles` map semantic roles onto those hues, from which all functional tokens and dark mode derive.");
 const Scale = z.object({
@@ -153,6 +296,8 @@ function validate(input) {
 		warnings: []
 	};
 	const warnings = [];
+	const missing = REQUIRED_ROLES.filter((r) => roles[r] == null);
+	if (missing.length) warnings.push(`colors.roles is missing ${missing.map((r) => `"${r}"`).join(", ")} — the framework's own component CSS references ${missing.length === 1 ? "it" : "them"} with no fallback, so those components will render uncoloured. Add any role you like, but keep these defined.`);
 	const radii = Object.keys(result.data.patterns?.radii ?? {});
 	const items = new Set(Object.keys(result.data.patterns?.items ?? {}));
 	for (const name of radii) if (items.has(name)) warnings.push(`patterns.radii.${name} collides with the "${name}" pattern on --br-${name}; the pattern's override hook wins — rename the radius`);
@@ -164,90 +309,6 @@ function validate(input) {
 	};
 }
 
-//#endregion
-//#region src/shared.ts
-/**
-* Data shared between the generator (`generate.ts`) and the docs bundle
-* (`docs.ts`). Lives in its own module because `generate.ts` imports `docs.ts` —
-* importing back the other way would be a cycle.
-*/
-/**
-* Pattern base geometry props → per-pattern override-hook shorthand. Each hook
-* wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
-* consumer restyles one pattern by setting one variable. The hook is named after
-* the pattern's key, not its class.
-*/
-const BASE_HOOK = {
-	padding: "p",
-	"border-radius": "br",
-	border: "b",
-	"box-shadow": "ds",
-	"font-size": "fs"
-};
-/**
-* Framework utility classes whose names collide with Tailwind's own defaults.
-* The `tailwind` format strips any rule targeting these — Tailwind provides
-* them, so consumers use Tailwind's utilities for these names instead.
-*/
-const TW_CLASH = new Set([
-	"block",
-	"inline",
-	"inline-block",
-	"flow-root",
-	"flex",
-	"inline-flex",
-	"grid",
-	"inline-grid",
-	"table",
-	"inline-table",
-	"table-caption",
-	"table-cell",
-	"table-row",
-	"contents",
-	"hidden",
-	"list-item",
-	"static",
-	"fixed",
-	"absolute",
-	"relative",
-	"sticky",
-	"isolate",
-	"visible",
-	"invisible",
-	"collapse",
-	"sr-only",
-	"not-sr-only",
-	"flex-row",
-	"flex-row-reverse",
-	"flex-col",
-	"flex-col-reverse",
-	"flex-wrap",
-	"flex-nowrap",
-	"items-start",
-	"items-end",
-	"items-center",
-	"items-baseline",
-	"items-stretch",
-	"justify-start",
-	"justify-end",
-	"justify-center",
-	"justify-between",
-	"justify-around",
-	"justify-evenly",
-	"content-start",
-	"content-end",
-	"content-center",
-	"content-between",
-	"content-around",
-	"content-evenly",
-	"text-left",
-	"text-center",
-	"text-right",
-	"text-justify",
-	"text-start",
-	"text-end"
-]);
-
 //#endregion
 //#region src/tokens.ts
 /**
@@ -386,6 +447,11 @@ const EMPHASIS_DARK = {
 	bold: "300",
 	"x-bold": "100"
 };
+/**
+* The emphasis-stop names, derived from the table rather than re-listed, so the
+* utility emitter in `generate.ts` cannot drift from the tokens it emits.
+*/
+const EMPHASIS_STOPS = Object.keys(EMPHASIS_LIGHT);
 /** Resolve the functional token set for one role over its hue. */
 function functionalRole(role, hueName, hue) {
 	const numeric = hue.numeric;
@@ -981,9 +1047,17 @@ Families: ${code(families)} (\`--font-*\`).
 ## Colour
 
 **Functional tokens are the primary vocabulary** — classes name the *job*, not the tone, and
-every one remaps automatically under \`:root[data-brx-theme="dark"]\` (background/text ends
+every one remaps automatically under \`${DARK_SEL}\` (background/text ends
 swap; \`solid\` fills stay mode-stable with a computed \`on-\` foreground). Prefer these over
-raw steps. Rules (role ∈ ${code(roles)}):
+raw steps.
+
+**Role names are yours.** \`colors.roles\` is an open map: add a key, and the generator emits
+that role's full functional token set, its dark flip and every utility below. Your config
+currently defines ${code(roles)}. Six of those are a **required core** — the framework's own
+component CSS references \`${REQUIRED_ROLES.join("`, `")}\` with no fallback, so removing one
+leaves those components uncoloured (\`vitops validate\` warns). Everything beyond them is free.
+
+Rules (role ∈ ${code(roles)}, or whatever you add):
 
 - **Surfaces** — \`bg-<role>\` (the role's background wash; for \`surface\` this is the
   card/panel plane), \`bg-<role>-muted\` (subtle / sunken), \`bg-surface-bold\` (raised plane).
@@ -997,9 +1071,10 @@ raw steps. Rules (role ∈ ${code(roles)}):
   \`--color-<role>-{x-muted,muted,bold,x-bold}\` — \`muted\` recedes toward the background
   extreme, \`bold\` advances toward the foreground, in *either* appearance.
 
-Everyday pairings: page \`bg-neutral\` + \`text-neutral\`; cards \`bg-surface\`; captions
-\`text-neutral-muted\`; buttons \`bg-ui-primary-solid text-on-ui-primary\`; status text
-\`text-danger\` / \`text-success\` / \`text-warning\` / \`text-info\`.
+Everyday pairings, using the roles this config defines: page
+\`bg-${roles[0] ?? "neutral"}\` + \`text-${roles[0] ?? "neutral"}\`; captions
+\`text-${roles[0] ?? "neutral"}-muted\`; buttons
+\`bg-${roles[2] ?? roles[0] ?? "ui-primary"}-solid text-on-${roles[2] ?? roles[0] ?? "ui-primary"}\`.
 
 **Raw scale** (secondary / fine control) — rule \`<util>-<hue>-<step>\` with util ∈
 ${code(utils)}: every hue is an 11-step OKLCH scale generated from its seed (or fixed brand
@@ -1007,6 +1082,28 @@ tones), numeric steps \`50\` … \`950\` (tinted near-white → tinted near-blac
 \`bg-${ramps[0] ?? "brand"}-100\`, \`text-${ramps[0] ?? "brand"}-800\`. Hues: ${code(ramps)}.
 The **bare** role name (\`bg-<role>\`, \`text-<role>\`) is always the functional token.
 
+> **Raw scale classes are frozen — they do NOT remap in dark mode.**
+> \`bg-${ramps[0] ?? "brand"}-800\` is that exact colour in every appearance. The automatic
+> dark flip described above applies **only** to the functional role tokens, because
+> \`--color-<hue>-<step>\` is emitted once and never re-pointed under \`${DARK_SEL}\`.
+> A raw step on a page that can switch appearance is a latent bug: it looks correct in
+> whichever mode you built it in and inverts in the other.
+>
+> If you are reaching for a raw step, you usually want a **role** instead — and roles are
+> extensible, so adding one is a two-line config change:
+>
+> | instead of | use | why |
+> | --- | --- | --- |
+> | \`bg-<hue>-50\` / \`-950\` | \`bg-<role>\` | the page/backdrop plane, flips automatically |
+> | \`bg-<hue>-100\` / \`-900\` | \`bg-<role>-muted\` | one plane in from the page |
+> | \`bg-<hue>-500\`…\`-700\` | \`bg-<role>-solid\` | vivid fill, mode-stable, pairs with \`text-on-<role>\` |
+> | \`text-<hue>-950\` / \`-50\` | \`text-<role>\` | contrast-guaranteed body text |
+> | \`text-<hue>-800\` / \`-200\` | \`text-<role>-muted\` | secondary text |
+> | \`border-<hue>-200\` / \`-800\` | \`border-<role>\` | |
+>
+> Raw steps stay the right tool for genuinely fixed colours — a brand mark, a chart series,
+> an illustration — where the value must not move between appearances.
+
 ## Shadows
 
 Rule: **\`drop-shadow-<size>\`** — size ∈ ${code(shadows)} (applied as a \`filter\`, so it
@@ -1168,9 +1265,27 @@ ${clashList.map((c) => `\`${c}\``).join(", ")}
 Other Tailwind-specific behaviour:
 
 - **Variants are Tailwind's job.** No pre-expanded breakpoint/state classes are emitted
-  (the framework's \`@container (min-width: …)\` variant blocks are dropped); use Tailwind
-  syntax — \`@md:split-1-2\`, \`hover:flip-fade-in\`. Container breakpoints are registered as
+  (the framework's \`@container (min-width: …)\` **variant** blocks are dropped; component
+  container queries such as the sitenav's desktop switch are kept); use Tailwind syntax —
+  \`@md:split-1-2\`, \`hover:flip-fade-in\`. Container breakpoints are registered as
   \`--container-{sm,md,lg,xl}\` = 30/48/64/80rem, backing the \`@sm:\`…\`@xl:\` variants.
+
+  > **Three spellings, and only two of them work here.**
+  >
+  > | you write | in \`tailwind\` | note |
+  > | --- | --- | --- |
+  > | \`@md:flex-row\` | ✅ container query | the framework's breakpoints (48rem) |
+  > | \`md:flex-row\` | ✅ media query | **Tailwind's** breakpoints, which differ — \`sm:\` is 40rem where \`@sm:\` is 30rem |
+  > | \`md-flex-row\` | ❌ silently nothing | the css/bricks spelling; not emitted in this format |
+  >
+  > \`md-*\` is the trap: it is a real class in \`css\`/\`bricks\` and a no-op here, and
+  > nothing errors — the element simply never changes at the breakpoint. Prefer \`@md:\`
+  > so one vocabulary of breakpoints applies throughout.
+
+- **Overriding \`--container-*\` also moves Tailwind's width scale.** Registering the
+  framework breakpoints in \`@theme\` re-points \`max-w-sm\`…\`max-w-xl\` at the same values,
+  so \`max-w-md\` is 48rem here rather than Tailwind's stock 28rem. Use
+  \`max-w-(--container-md)\` style arbitrary values if you need to be explicit.
 - **The space scale is NOT mapped into Tailwind's \`--spacing-*\` namespace** (that would
   corrupt Tailwind's numeric multipliers and \`max-w-*\` sizes). Numeric utilities like
   \`p-4\` keep Tailwind's 0.25rem meaning; use the design-system scale via arbitrary
@@ -1180,6 +1295,18 @@ Other Tailwind-specific behaviour:
   (\`bg-<role>\`, \`text-<role>-muted\`, …) is the public API. The raw hue scales ARE
   \`@theme\` colours, so native \`bg-<hue>-500\`-style utilities work.
 
+  This split is deliberate and load-bearing. When a token sits in \`@theme\` *and* an
+  \`@utility\` of the derived name exists, Tailwind merges both into one rule with the
+  \`@theme\` declaration last — regardless of source order. Promoting the role tokens
+  would therefore silently replace the functional plane with the emphasis stop on
+  \`bg-<role>-muted\`, \`text-<role>-muted\`, \`text-<role>-x-muted\`, \`border-<role>-bold\`
+  and \`bg-surface-bold\`, two of which are the contrast-guaranteed text tokens.
+- **\`colors.utilities\` is a floor here, not a ceiling.** It controls which families get
+  explicit role \`@utility\` rules, exactly as in \`css\`/\`bricks\`. But the raw hue scales
+  are \`@theme\` colours, and Tailwind derives *every* colour family from those on demand
+  (\`ring-\`, \`divide-\`, \`accent-\`, \`caret-\`, …), so hue-step utilities you did not enable
+  still resolve in this format.
+
 ## \`css\` — standalone bundle
 
 Emits a bundled, self-contained \`styles.css\` + \`tokens.json\` + \`design-manifest.json\`.
@@ -1188,6 +1315,26 @@ pre-expanded — including breakpoint/state variants with \`-\` separators
 (\`md-split-1-2\`, \`hover-fade-in\`). For non-Bricks, non-Tailwind consumers and the
 docs build.
 
+**Cascade layers.** The bundle ships three, in precedence order:
+
+\`\`\`
+@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.
+
+So a utility overrides a pattern: \`class="card bg-danger-muted"\` tints the card. Your own
+unlayered CSS beats all three — see [concepts/patterns.md](concepts/patterns.md) for the
+override story and the one gotcha (a reset must be layered and ordered first).
+
+Known gap: \`layout.css\` is a single partial mixing structural rules (\`.rhythm\`,
+\`.centered\`) with utilities (\`.m-*\`, \`.flex\`, \`.split-*\`), so it sits in
+\`vitops.components\` whole — its utility half cannot yet override a pattern. Splitting it is
+tracked separately.
+
 ## \`bricks\` — WordPress / Bricks Builder payload
 
 Emits the full deployable theme payload: \`styles.min.css\`, the Bricks import JSONs
@@ -1261,11 +1408,16 @@ Classes name the token, not the tone: \`bg-<role>\`, \`text-<role>-muted\`, \`te
 
 ## Automatic dark mode
 
-Dark mode is a **functional flip** under \`:root[data-brx-theme="dark"]\`: background and
+Dark mode is a **functional flip** under \`${DARK_SEL}\`: background and
 text ends of each scale swap, while \`solid\` fills stay mode-stable with a recomputed
 \`on-solid\` foreground. There is no per-appearance scheme grammar to author and no named
 steps — a role token means the same *job* in both appearances.
 
+Two attributes, one flip: \`data-brx-theme\` is Bricks' own (Bricks sets it on the
+WordPress target), \`data-theme\` is what the shipped \`<color-scheme-toggle>\` writes on
+\`<html>\`, so the toggle works on every other target. Set either. There is deliberately
+no \`prefers-color-scheme\` block — the flip follows an explicit choice only.
+
 ## Contrast guarantees
 
 Text tokens target APCA Lc ≥ 75 and muted text Lc ≥ 60, in **both** appearances —
@@ -1342,9 +1494,34 @@ function renderPatternsConcept(ds) {
 # Component patterns — the CSS chain
 
 Patterns (currently ${code(patternNames)}) are authored declaratively under \`patterns\` in
-\`design-system.json\` (see [authoring.md](../authoring.md)) and compiled to CSS in the
-**\`components\` cascade layer** — so utility classes (declared in a later layer) always win
-over pattern styling without specificity fights.
+\`design-system.json\` (see [authoring.md](../authoring.md)) and compiled to CSS in a
+**components cascade layer** — so utility classes, which live in a later layer, always win over
+pattern styling without specificity fights. \`class="card bg-danger-muted"\` tints the card.
+
+The layer names differ by format, because each defers to its host:
+
+| format | layer stack (last wins) |
+| --- | --- |
+| \`css\`, \`bricks\` | \`vitops.base\` → \`vitops.components\` → \`vitops.utilities\` |
+| \`tailwind\` | Tailwind's own \`theme\` → \`base\` → \`components\` → \`utilities\` |
+
+**Your own CSS beats all of it.** Unlayered styles outrank every cascade layer regardless of
+specificity, so a plain stylesheet, an Astro scoped \`<style>\`, or a Bricks-authored class
+overrides the framework with no \`!important\` and no specificity escalation. That is the
+intended override story.
+
+The one thing to watch: a **reset** must be layered too, and ordered *below* the framework —
+left unlayered it beats the very component rules it is meant to sit under (a bare
+\`p { margin: 0 }\` would defeat \`.rhythm\`). Declare the order before you load the stylesheet,
+since layer precedence is fixed by first declaration:
+
+\`\`\`html
+<style>@layer my.reset, vitops.base, vitops.components, vitops.utilities;</style>
+<link rel="stylesheet" href="/styles.css">
+\`\`\`
+
+Put it *after* the link and \`my.reset\` becomes a new name introduced later — which sorts
+**last**, i.e. highest priority, and the reset wins. That is the one non-obvious step.
 
 ## 1 — Token cascade
 
@@ -1505,22 +1682,6 @@ function generateDocs(ds, assetsDir) {
 * and the pre-built JS bundles) live under `assets/` in this package and are read /
 * copied from there — they are the same for every consumer.
 */
-/**
-* Selector the dark functional-token flip hangs off.
-*
-* `data-brx-theme` is Bricks' own attribute — Bricks sets it, so it's what the
-* WordPress target needs. Nothing sets it anywhere else, which meant the dark
-* flip was unreachable outside Bricks: the shipped `<color-scheme-toggle>` web
-* component writes `documentElement.dataset.theme` (i.e. `data-theme`), so
-* clicking "Dark" changed an attribute no rule matched. Matching both makes the
-* component work on every target without changing what Bricks already does.
-*
-* Note this covers the explicit choice only — there is deliberately no
-* `prefers-color-scheme` block, so the toggle's "System" position currently
-* resolves to light. Adding one would flip every existing consumer site dark for
-* dark-OS users, which is a product decision, not a bug fix.
-*/
-const DARK_SEL = ":root[data-brx-theme=\"dark\"], :root[data-theme=\"dark\"]";
 const DEFAULT_ASSETS = join(dirname(fileURLToPath(import.meta.url)), "..", "assets");
 const UTILITY_PROPS = {
 	bg: "background-color",
@@ -1531,24 +1692,55 @@ const UTILITY_PROPS = {
 	stroke: "stroke"
 };
 const fnVar = (role, token) => token.startsWith("stop-") ? `--color-${role}-${token.slice(5)}` : `--${role}-${token}`;
-const fnUtilities = (role, utilities, isSurface) => {
-	const rows = [];
-	if (utilities.includes("bg")) {
-		rows.push(`.bg-${role} { background-color: var(--${role}-bg); }`);
-		rows.push(`.bg-${role}-muted { background-color: var(--${role}-bg-muted); }`);
-		rows.push(`.bg-${role}-solid { background-color: var(--${role}-solid); }`);
-		rows.push(`.bg-${role}-solid-bold { background-color: var(--${role}-solid-bold); }`);
-		if (isSurface) rows.push(`.bg-${role}-bold { background-color: var(--${role}-bg-bold); }`);
+/**
+* Every role colour utility, each class name emitted EXACTLY once.
+*
+* Two axes share the `<family>-<role>-<modifier>` namespace: the functional
+* background/text/border **planes** (`--<role>-bg-muted`) and the
+* appearance-relative emphasis **stops** (`--color-<role>-muted`). Where both
+* would produce the same class the plane wins.
+*
+* That precedence used to be implicit — the css path emitted the stop matrix,
+* then the planes, and relied on the CSS minifier dropping the shadowed
+* earlier rule. The tailwind path never ran the stop half at all, so the two
+* formats shipped different vocabularies (87 role classes existed in css and
+* not in tailwind) with nothing to catch it. Deciding it here, once, is what
+* keeps all three formats in step; `format-parity.test.ts` holds them there.
+*
+* Order is stops-then-planes to match the css bundle's historical rule order.
+*/
+function roleColorUtilities(roles, utilities) {
+	const plane = (cls, prop, value) => ({
+		cls,
+		prop,
+		value,
+		axis: "plane"
+	});
+	const planes = [];
+	for (const { role } of roles) {
+		if (utilities.includes("bg")) {
+			planes.push(plane(`bg-${role}`, "background-color", `var(--${role}-bg)`), plane(`bg-${role}-muted`, "background-color", `var(--${role}-bg-muted)`), plane(`bg-${role}-solid`, "background-color", `var(--${role}-solid)`), plane(`bg-${role}-solid-bold`, "background-color", `var(--${role}-solid-bold)`));
+			if (role === "surface") planes.push(plane(`bg-${role}-bold`, "background-color", `var(--${role}-bg-bold)`));
+		}
+		if (utilities.includes("text")) planes.push(plane(`text-${role}`, "color", `var(--${role}-text)`), plane(`text-${role}-muted`, "color", `var(--${role}-text-muted)`), plane(`text-${role}-x-muted`, "color", `var(--${role}-text-x-muted)`), plane(`text-on-${role}`, "color", `var(--${role}-on-solid)`));
+		if (utilities.includes("border")) planes.push(plane(`border-${role}`, "border-color", `var(--${role}-border)`), plane(`border-${role}-bold`, "border-color", `var(--${role}-border-bold)`));
 	}
-	if (utilities.includes("text")) {
-		rows.push(`.text-${role} { color: var(--${role}-text); }`);
-		rows.push(`.text-${role}-muted { color: var(--${role}-text-muted); }`);
-		rows.push(`.text-${role}-x-muted { color: var(--${role}-text-x-muted); }`);
-		rows.push(`.text-on-${role} { color: var(--${role}-on-solid); }`);
+	const claimed = new Set(planes.map((p) => p.cls));
+	const stops = [];
+	for (const { role } of roles) for (const stop of EMPHASIS_STOPS) for (const fam of utilities) {
+		const cls = `${fam}-${role}-${stop}`;
+		if (claimed.has(cls) || !(fam in UTILITY_PROPS)) continue;
+		stops.push({
+			cls,
+			prop: UTILITY_PROPS[fam],
+			value: `var(--color-${role}-${stop})`,
+			axis: "stop"
+		});
 	}
-	if (utilities.includes("border")) rows.push(`.border-${role} { border-color: var(--${role}-border); }`, `.border-${role}-bold { border-color: var(--${role}-border-bold); }`);
-	return rows.join("\n");
-};
+	return [...stops, ...planes];
+}
+/** Render the shared set as plain rules (css/bricks formats). */
+const colorUtilityRules = (u) => u.map(({ cls, prop, value }) => `.${cls} { ${prop}: ${value}; }`).join("\n");
 const decls = (obj, indent = "  ") => Object.entries(obj).map(([k, v]) => `${indent}${k}: ${v};`).join("\n");
 const round = (n) => Number(n.toFixed(4)).toString();
 const rem = (v) => parseFloat(v);
@@ -1663,18 +1855,10 @@ function build(ds, format, assetsDir) {
 				css += `${DARK_SEL} {\n  color-scheme: dark;\n${fb}}\n\n`;
 			}
 		}
-		const allTokens = [];
-		for (const [name, hue] of Object.entries(expandedPalette)) for (const n of Object.keys(hue.numeric)) allTokens.push(`${name}-${n}`);
-		for (const fr of scaleRoles) for (const stop of [
-			"x-muted",
-			"muted",
-			"bold",
-			"x-bold"
-		]) allTokens.push(`${fr.role}-${stop}`);
 		css += `/* Colour utilities — ${UTILITIES.join(", ")} */\n`;
-		for (const token of allTokens) css += UTILITIES.map((cls) => `.${cls}-${token} { ${UTILITY_PROPS[cls]}: var(--color-${token}); }`).join("\n") + "\n";
-		css += `\n/* Functional utilities (the public API) */\n`;
-		for (const fr of scaleRoles) css += `${fnUtilities(fr.role, UTILITIES, fr.role === "surface")}\n`;
+		for (const [name, hue] of Object.entries(expandedPalette)) for (const n of Object.keys(hue.numeric)) css += UTILITIES.map((cls) => `.${cls}-${name}-${n} { ${UTILITY_PROPS[cls]}: var(--color-${name}-${n}); }`).join("\n") + "\n";
+		css += `\n/* Role utilities (the public API) */\n`;
+		css += `${colorUtilityRules(roleColorUtilities(scaleRoles, UTILITIES))}\n`;
 		if (surfaceRole) css += `.glass { background-color: var(--surface-glass); backdrop-filter: blur(12px); -webkit-backdrop-filter: blur(12px); }\n`;
 		generated["color.css"] = css;
 	}
@@ -2062,7 +2246,8 @@ function build(ds, format, assetsDir) {
 			twTypeTokensCss,
 			twPatternTokensCss,
 			patternsCss: pat,
-			assetsDir
+			assetsDir,
+			utilities: UTILITIES
 		}),
 		twTypeTokensCss,
 		twPatternTokensCss,
@@ -2070,10 +2255,10 @@ function build(ds, format, assetsDir) {
 	};
 }
 function emitTailwind(ctx) {
-	const { ds, expandedPalette, scaleRoles, shadows, typeSteps, spaceSteps, typography, roleDecls, twTypeTokensCss, twPatternTokensCss, patternsCss, assetsDir } = ctx;
+	const { ds, expandedPalette, scaleRoles, shadows, typeSteps, spaceSteps, typography, roleDecls, twTypeTokensCss, twPatternTokensCss, patternsCss, assetsDir, utilities } = ctx;
 	const cssDir = join(assetsDir, "css");
 	const nl = (arr) => arr.filter(Boolean).join("\n");
-	const parts = [`/* GENERATED for Tailwind v4 (Astro) — do not edit by hand. */`];
+	const parts = ["/* GENERATED for Tailwind v4 (Astro) — do not edit by hand.\n   Class reference: npx vitops docs classes  ·  All topics: npx vitops docs */"];
 	parts.push(`@import "tailwindcss";\n`);
 	const theme = [];
 	theme.push(`  /* Hue scales → bg-<hue>-<step> text-* border-* (numeric, 50…950) */`);
@@ -2114,15 +2299,8 @@ function emitTailwind(ctx) {
 	parts.push("/* State variant for the active flip (hover/focus-visible are built in). */\n@custom-variant is-active (&.is-active, &[data-active]);\n");
 	const util = [];
 	if (scaleRoles.length) {
-		util.push(`/* Functional colour utilities (the public API) */`);
-		for (const fr of scaleRoles) for (const row of fnUtilities(fr.role, [
-			"bg",
-			"text",
-			"border"
-		], fr.role === "surface").split("\n")) {
-			const m = /^\.([^ ]+) \{ (.*) \}$/.exec(row);
-			if (m) util.push(`@utility ${m[1]} {\n  ${m[2]}\n}`);
-		}
+		util.push(`/* Role colour utilities (the public API) */`);
+		for (const { cls, prop, value } of roleColorUtilities(scaleRoles, utilities)) util.push(`@utility ${cls} {\n  ${prop}: ${value};\n}`);
 		if (scaleRoles.some((r) => r.role === "surface")) util.push(`@utility glass {\n  background-color: var(--surface-glass);\n  backdrop-filter: blur(12px);\n  -webkit-backdrop-filter: blur(12px);\n}`);
 	}
 	util.push(`/* Typography roles */`);
@@ -2250,11 +2428,42 @@ body {
 }
 }
 `);
-	const animEngine = readFileSync(join(cssDir, "animation.css"), "utf8");
-	parts.push(`/* ── Animation engine (animation.css) ── */\n@layer components {\n${animEngine}\n}`);
+	const animPath = join(cssDir, "animation.css");
+	const animEngine = existsSync(animPath) ? readFileSync(animPath, "utf8") : "";
+	if (animEngine) parts.push(`/* ── Animation engine (animation.css) ── */\n@layer components {\n${animEngine}\n}`);
 	parts.push(`/* ── Component patterns ── */\n@layer components {\n${patternsCss}\n}`);
 	const droppedClashes = /* @__PURE__ */ new Set();
 	let droppedVariantBlocks = 0;
+	/**
+	* Is this `@container (min-width: …)` block a PRE-EXPANDED VARIANT block —
+	* i.e. only `.sm-*`/`.md-*`/`.lg-*`/`.xl-*` utility classes, which Tailwind
+	* regenerates on demand as `@md:`?
+	*
+	* Anything else in a container query is component *behaviour*, not a variant,
+	* and dropping it breaks the component. `sitenav.css` is the case that caught
+	* this: its `@container (min-width: 48rem) { .sitenav--bp-md { … } }` is what
+	* switches the nav to its desktop layout, and blanket-dropping every
+	* container block meant the tailwind format shipped a nav stuck in mobile.
+	*/
+	const isVariantBlock = (raw) => {
+		const open = raw.indexOf("{");
+		const body = raw.slice(open + 1, raw.lastIndexOf("}"));
+		const selectors = [];
+		let depth = 0;
+		let start = 0;
+		for (let i = 0; i < body.length; i++) {
+			const ch = body[i];
+			if (ch === "{") {
+				if (depth === 0) selectors.push(body.slice(start, i));
+				depth++;
+			} else if (ch === "}") {
+				depth--;
+				if (depth === 0) start = i + 1;
+			}
+		}
+		const names = selectors.flatMap((s) => s.split(",")).map((s) => s.replace(/\/\*[\s\S]*?\*\//g, "").trim()).filter(Boolean);
+		return names.length > 0 && names.every((n) => /^\.(sm|md|lg|xl)-/.test(n));
+	};
 	const stripForTailwind = (css) => {
 		const kept = [];
 		let depth = 0;
@@ -2281,7 +2490,7 @@ body {
 					const raw = css.slice(start, i + 1).trim();
 					const prelude = css.slice(start, preludeEnd).replace(/\/\*[\s\S]*?\*\//g, "").trim();
 					const clash = /^\.([A-Za-z0-9_-]+)/.exec(prelude);
-					if (/^@container\s*\(\s*min-width:/.test(prelude)) droppedVariantBlocks++;
+					if (/^@container\s*\(\s*min-width:/.test(prelude) && isVariantBlock(raw)) droppedVariantBlocks++;
 					else if (clash && TW_CLASH.has(clash[1])) droppedClashes.add(clash[1]);
 					else if (raw) kept.push(raw);
 					start = i + 1;
@@ -2293,7 +2502,7 @@ body {
 	const componentCss = componentPartialOrder(cssDir).map((rel) => {
 		return `/* ── ${rel} ── */\n${stripForTailwind(readFileSync(join(cssDir, rel), "utf8"))}`;
 	}).join("\n\n");
-	parts.push(`/* ── Component + structural partials (Tailwind-clashing utilities dropped) ── */\n@layer components {\n${componentCss}\n}`);
+	if (componentCss) parts.push(`/* ── Component + structural partials (Tailwind-clashing utilities dropped) ── */\n/* Dropped ${droppedVariantBlocks} pre-expanded breakpoint block(s) — write @sm:/@md:/@lg:/@xl: instead.\n   Dropped ${droppedClashes.size} clashing utilit(ies) Tailwind provides itself:\n   ${[...droppedClashes].sort().join(" ") || "(none)"} */\n@layer components {\n${componentCss}\n}`);
 	return nl(parts) + "\n";
 }
 /**
@@ -2330,11 +2539,61 @@ function componentPartialOrder(cssDir) {
 	}
 	return order;
 }
+/** The bundle's cascade layers, in precedence order (last wins). */
+const CSS_LAYERS = [
+	"vitops.base",
+	"vitops.components",
+	"vitops.utilities"
+];
+/**
+* Which layer each `index.css` chunk belongs to. Anything unmapped defaults to
+* `vitops.components` — the safe default, since an unrecognised partial is far
+* more likely to be a component than a utility family.
+*
+* The split is by what the file *emits*, not what it's named:
+*   • base       — the UA reset and the pure `:root` token blocks.
+*   • components — the animation engine, structural layout, and every pattern.
+*   • utilities  — the single-purpose classes that must be able to override a
+*                  pattern (`bg-*`, `drop-shadow-*`, `font-*`, effects, …).
+*
+* `color.css` and `shadows.css` each mix a `:root` block with utility classes
+* and go to `utilities` whole. That is safe because custom-property resolution
+* is NOT source-order dependent — a `:root` block declared after a rule that
+* reads it still resolves.
+*
+* `layout.css` is genuinely mixed (structural `.rhythm`/`.centered` AND
+* `.m-*`/`.flex`/`.split-*` utilities) and stays in `components` whole, so its
+* utility half still can't override a pattern. Splitting it is a separate
+* change; see the 0.9.0 changelog.
+*/
+const CHUNK_LAYER = {
+	"global.css": "vitops.base",
+	"generated/type-tokens.css": "vitops.base",
+	"generated/tokens.css": "vitops.base",
+	"generated/color.css": "vitops.utilities",
+	"generated/shadows.css": "vitops.utilities",
+	"generated/typography.css": "vitops.utilities",
+	"generated/animation-effects.css": "vitops.utilities",
+	"utilities.css": "vitops.utilities"
+};
 /**
 * Assemble the full stylesheet by resolving index.css's @import order against the
 * static partials (from assets) and the freshly generated token partials (in
 * memory), then minify with lightningcss. No @import survives, so no disk
 * resolution / shared `generated/` dir is needed.
+*
+* Each chunk is wrapped in a cascade layer. This is what lets a single-purpose
+* utility override a component pattern — `class="card bg-danger-muted"` — which
+* previously depended on source order and so silently did nothing here while
+* working in the tailwind format, where Tailwind's own layers already ordered
+* them correctly.
+*
+* Consequence worth knowing: unlayered CSS beats ALL layered CSS regardless of
+* specificity, so a consumer's own stylesheet now wins over the framework by
+* default. That is deliberate — it is the override story every layered
+* framework ships — but it means an unlayered *reset* will beat framework
+* component rules it used to lose to. Such a reset belongs in a layer declared
+* before `vitops.base` (see the `<style>` block in this repo's index.html).
 */
 function bundleCss(generated, assetsDir, minify) {
 	const cssDir = join(assetsDir, "css");
@@ -2344,12 +2603,13 @@ function bundleCss(generated, assetsDir, minify) {
 		const m = /@import\s+['"]\.\/([^'"]+)['"]/.exec(line);
 		if (!m) continue;
 		const rel = m[1];
-		if (rel.startsWith("generated/")) {
-			const name = rel.slice(10);
-			chunks.push(generated[name] ?? "");
-		} else chunks.push(readFileSync(join(cssDir, rel), "utf8"));
+		const body = rel.startsWith("generated/") ? generated[rel.slice(10)] ?? "" : readFileSync(join(cssDir, rel), "utf8");
+		if (!body.trim()) continue;
+		chunks.push(`@layer ${CHUNK_LAYER[rel] ?? "vitops.components"} {\n${body}\n}`);
 	}
-	const merged = chunks.join("\n");
+	const merged = `/*! GENERATED by @getvitops/generator — do not edit by hand.
+    Class reference: npx vitops docs classes  ·  All topics: npx vitops docs */
+@layer ${CSS_LAYERS.join(", ")};\n` + chunks.join("\n");
 	const res = transform({
 		filename: "styles.css",
 		code: Buffer.from(merged),
@@ -3113,15 +3373,14 @@ function defaultConfig() {
 		patterns: {
 			defaults: {
 				ds: "none",
-				b: "1px solid var(--color-surface-xl)",
+				b: "1px solid var(--surface-bg-muted)",
 				br: "0.375rem",
 				p: "1rem",
 				fs: "1rem"
 			},
 			radii: {
 				pill: "999px",
-				circle: "50%",
-				card: "0.5rem"
+				circle: "50%"
 			},
 			groups: {
 				control: {
@@ -3224,7 +3483,7 @@ function defaultConfig() {
 					base: {
 						"border-radius": "var(--br-card-group)",
 						padding: "1.5rem",
-						background: "var(--color-surface-xxl)",
+						background: "var(--surface-bg)",
 						border: "var(--b-card-group)",
 						"box-shadow": "var(--ds-card-group)"
 					},
@@ -3293,5 +3552,5 @@ function defaultConfig() {
 }
 
 //#endregion
-export { BASE_HOOK, DesignSystemSchema, SCHEMA_URL, SITE_SCHEMA_URL, SiteConfigSchema, TW_CLASH, deepMerge, defaultConfig, generate, generateDocs, jsonSchema, resolveSiteConfig, resolveTheme, siteJsonSchema, stripNulls, validate, validateSite };
+export { BASE_HOOK, DARK_SEL, DesignSystemSchema, REQUIRED_ROLES, ROLE_TOKEN_SUFFIXES, SCHEMA_URL, SITE_SCHEMA_URL, SiteConfigSchema, TW_CLASH, deepMerge, defaultConfig, expandPalette, functionalRole, generate, generateDocs, jsonSchema, resolveSiteConfig, resolveTheme, roleColorUtilities, siteJsonSchema, stripNulls, validate, validateSite };
 //# sourceMappingURL=index.mjs.map