@getvitops/generator 1.0.0 → 2.1.0

package/dist/index.mjs

@@ -1,11 +1,13 @@
+import { createRequire } from "node:module";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { transform } from "lightningcss";
 import * as z from "zod/mini";
 import { LIGHTNESS_LADDER, contrastLc, generateOklchPalette, hexToOklch, oklchStringToHex, pickOn, tintedEndpoints } from "@getvitops/utils/color";
-import { nodesToHtml, t } from "@getvitops/utils";
+import { generateIconInclude, nodesToHtml, resolveIcon, t } from "@getvitops/utils";
+import { getIconData, iconToSVG, replaceIDs } from "@iconify/utils";
 
 //#region src/shared.ts
 /**
@@ -23,15 +25,27 @@ import { nodesToHtml, t } from "@getvitops/utils";
 * 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.
+* This covers the EXPLICIT choice. The OS preference is a second, opt-in block —
+* see `SYSTEM_DARK_SEL` — because turning it on flips a site dark for dark-OS
+* users, which is the site's decision rather than the design system's.
 *
 * Shared so the docs quote the selector the generator actually emits.
 */
 const DARK_SEL = ":root[data-brx-theme=\"dark\"], :root[data-theme=\"dark\"]";
 /**
+* Selector for the OS-preference dark block, emitted inside
+* `@media (prefers-color-scheme: dark)` when a site opts in.
+*
+* Derived from `DARK_SEL`'s attributes rather than written out a third time, and
+* inverted: this must apply when NO explicit choice has been made. That is
+* exactly what `<color-scheme-toggle>`'s "System" position produces — it removes
+* `data-theme` entirely — so with this block present System resolves to the OS
+* instead of silently falling through to light, and needs no JS to do it.
+*
+* The `:not()`s are what keep an explicit *light* choice winning over a dark OS.
+*/
+const SYSTEM_DARK_SEL = `:root${DARK_SEL.split(", ").map((s) => s.replace(/^:root\[([\w-]+)="dark"\]$/, "[$1=\"light\"]")).map((attr) => `:not(${attr})`).join("")}`;
+/**
 * 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.
@@ -168,7 +182,11 @@ const TW_CLASH = new Set([
 	"text-right",
 	"text-justify",
 	"text-start",
-	"text-end"
+	"text-end",
+	"text-wrap",
+	"text-nowrap",
+	"text-balance",
+	"text-pretty"
 ]);
 
 //#endregion
@@ -192,18 +210,18 @@ const desc = (schema, text) => schema.check(z.describe(text));
 const CssDecls = desc(z.record(z.string(), z.string()), "A CSS declaration block: property → value. Values stay strings (they can be hex, var(), clamp(), keywords, …); the generator, not the schema, interprets them.");
 const Scalar = z.union([z.string(), z.number()]);
 const VarMap = z.record(z.string(), Scalar);
-const SeededRamp = desc(z.object({
+const SeededRamp = desc(z.strictObject({
 	seed: desc(z.string(), "Seed colour (hex or oklch()). An 11-step numeric scale (50…950, tinted near-white → tinted near-black) is generated in OKLCH from it; the seed is preserved at its natural step."),
 	anchors: z.optional(desc(z.record(z.string(), z.string()), "Step → colour overrides (hex or oklch()) pinned VERBATIM at those steps. Every other step takes its lightness from the shared ladder, with chroma and hue interpolated between the anchors — so an anchor is reproduced exactly and is the only step allowed off the ladder. An explicit anchor overrides the seed at that step; two anchors that resolve to the same step are an error."))
 }), "Seeded hue: the 11-step scale is GENERATED in OKLCH from `seed` (anchors pin specific steps).");
-const FixedRamp = desc(z.object({ tones: desc(z.union([z.array(z.string()), z.record(z.string(), z.string())]), "Fixed brand kit: authored tones placed verbatim at their nearest steps plus tinted off-white/off-black endpoints; no interpolation. Either an ordered light → dark array or a step → colour map.") }), "Fixed hue: authored brand tones used verbatim; no generation.");
+const FixedRamp = desc(z.strictObject({ tones: desc(z.union([z.array(z.string()), z.record(z.string(), z.string())]), "Fixed brand kit: authored tones placed verbatim at their nearest steps plus tinted off-white/off-black endpoints; no interpolation. Either an ordered light → dark array or a step → colour map.") }), "Fixed hue: authored brand tones used verbatim; no generation.");
 const Ramp = desc(z.union([SeededRamp, FixedRamp]), "A palette hue, authored one of two ways: `{ seed, anchors? }` generates an 11-step numeric OKLCH scale (50…950) from the seed, or `{ tones }` supplies a fixed brand kit used verbatim.");
 /**
 * A role points at a hue, and optionally declares its kind. The bare-string form
 * is the shorthand for a chromatic role — signal colours are the common case,
 * and the two or three surfaces are worth naming explicitly.
 */
-const RoleSpecSchema = z.union([desc(z.string(), "A palette hue name. Shorthand for `{ hue, kind: \"chromatic\" }`."), z.object({
+const RoleSpecSchema = z.union([desc(z.string(), "A palette hue name. Shorthand for `{ hue, kind: \"chromatic\" }`."), z.strictObject({
 	hue: desc(z.string(), "The palette hue this role resolves to."),
 	kind: z.optional(desc(z.enum(["surface", "chromatic"]), "`surface` — a page/panel colour: gets a bare `bg-<role>` plus the full emphasis range and text scale. `chromatic` (default) — a signal colour: tints and solids only, no bare `bg-<role>`."))
 })]);
@@ -216,25 +234,25 @@ const UtilityName = z.enum([
 	"fill",
 	"stroke"
 ]);
-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`)."),
+const Colors = desc(z.strictObject({
+	palette: desc(z.record(z.string(), Ramp), "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`). Every ramp shares one fixed lightness ladder, so a step means the same lightness in every hue; only chroma and hue vary. Beyond the outermost authored colour the chroma decays towards a small endpoint value (0.008 light / 0.015 dark) so the near-white and near-black ends keep a whisper of the hue — but that is a **ceiling**, not a target, so a low-chroma seed stays low and **a chroma-0 seed gives a true neutral** rather than a tinted one. The ladder is also enforced: if pinned colours leave a ramp non-monotonic (some step darker than the one below it), the build fails rather than shipping a scale whose hover states run backwards."),
 	roles: desc(z.record(z.string(), RoleSpecSchema), `Maps semantic role names onto palette hues. Role names are ARBITRARY — add a key and the generator emits that role's token set (\`--color-<target>-<role>[-<variant>]\` for target bg/text/icon/border), its dark-mode flip and its utility classes.\n\nA value is either a hue name (\`"danger": "rust"\`) or \`{ "hue": …, "kind": "surface" | "chromatic" }\`. **The kind decides the shape of the token set.** \`chromatic\` (the default, and what the bare-string form means) is a signal colour: its backgrounds split into tints (\`bg-<role>-x-muted\`/\`-muted\`) and solids (\`bg-<role>-solid[-bold|-x-bold]\`), with deliberately **no bare \`bg-<role>\`** — "how loud?" is a question the author answers. \`surface\` is a page/panel colour: it has a bare \`bg-<role>\` plus the full emphasis range and text scale.\n\nDark mode flips automatically; there is no per-appearance scheme grammar. The solid family and its computed \`text-on-<role>\` foreground stay mode-stable so a filled button keeps its identity. 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-*`, `icon-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, icon, border. `icon` is a separate non-text tier (a glyph may run more vivid than text); `outline`/`fill`/`stroke` have no tokens of their own and alias the border and icon tiers."))
 }), "The colour system (the only required section): `palette` hues become generated OKLCH scales; `roles` map semantic roles onto those hues, from which all role tokens and dark mode derive.");
-const Scale = z.object({
+const Scale = z.strictObject({
 	base: desc(z.string(), "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."),
 	ratio: desc(z.number(), "Modular ratio between adjacent steps at large viewports."),
 	steps: desc(z.optional(z.number()), "Token count when `names` is absent (steps are then named 1..steps)."),
 	names: desc(z.optional(z.array(z.string())), "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix."),
 	baseStep: desc(z.optional(z.number()), "1-based index of the step whose value is `base`."),
 	baseline: desc(z.optional(z.string()), "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`)."),
-	fluid: desc(z.optional(z.object({
+	fluid: desc(z.optional(z.strictObject({
 		minVw: desc(z.string(), "Viewport width (CSS length) where fluid scaling bottoms out."),
 		maxVw: desc(z.string(), "Viewport width (CSS length) where fluid scaling tops out."),
 		minRatio: desc(z.number(), "Modular ratio at/below `minVw` (usually < `ratio`).")
 	})), "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.")
 });
-const Pattern = desc(z.object({
+const Pattern = desc(z.strictObject({
 	group: desc(z.optional(z.string()), "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`."),
 	overrides: z.optional(desc(CssDecls, "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values.")),
 	element: desc(z.optional(z.string()), "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class)."),
@@ -245,47 +263,47 @@ const Pattern = desc(z.object({
 	states: desc(z.optional(z.record(z.string(), z.record(z.string(), z.unknown()))), "Interaction states (hover / active / focus-visible), each a map of shortcuts: `step` (intensify the fill or text by n rungs — `bg-<role>-solid` → `-solid-bold`, `text-<role>` → `-bold`), `scale` (transform scale), `lift` (translateY + shadow), `shadow` (a shadow name → drop-shadow(var(--shadow-<name>)), or true → lift shadow), `ring` (focus ring), or raw `css` declarations. Hover rules are wrapped in `@media (hover: hover)`."),
 	roles: desc(z.optional(z.array(z.string())), "Semantic colour role variants to emit as `<pattern>-<role>` classes (fills use the role solid / on-solid tokens).")
 }), "One component pattern (button, link, badge, card, …): base declarations + interaction states + semantic role variants, resolved through the pattern token cascade.");
-const Patterns = desc(z.object({
+const Patterns = desc(z.strictObject({
 	defaults: z.optional(desc(CssDecls, "Cascade-wide fallback tokens, emitted as `--<prop>-default`.")),
 	radii: z.optional(desc(CssDecls, "Shape primitives, emitted as `--br-<name>` (referenced by pattern bases).")),
 	groups: desc(z.optional(z.record(z.string(), CssDecls)), "Group-level tokens, emitted as `--<prop>-<group>`; patterns opt in via their `group` key."),
 	z: desc(z.optional(z.record(z.string(), z.number())), "Z-index tiers → `--z-tier-<name>`."),
 	items: desc(z.optional(z.record(z.string(), Pattern)), "The component patterns to emit, keyed by name.")
 }), "Component patterns and their token cascade: `defaults` → `groups` → per-pattern `overrides`, plus shape (`radii`) and z-index primitives.");
-const TypographyRole = desc(z.record(z.string(), Scalar), "An open bag of CSS-ish keys (family / size / weight / line-height / tracking / transform / decoration / text-wrap / …); the generator maps known keys and passes the rest through.");
-const Typography = desc(z.object({
+const TypographyRole = desc(z.record(z.string(), Scalar), "A bag of CSS-ish keys, each mapped to a declaration plus a `--<role>-<sfx>` override hook. The recognised set is **closed**: `family`, `size`, `weight`, `style`, `line-height`, `tracking` (→ `letter-spacing`), `text-transform`, `text-decoration`, `text-wrap`, `color`. Note the last four are spelled with their full CSS property names — `transform` and `decoration` are NOT accepted. Anything unrecognised is **ignored**, not passed through, so the generator warns rather than emitting it: a silently-dropped `transform: uppercase` is how title-case navigation reaches production. Note also that `style`, `text-transform`, `text-decoration` and `text-wrap` are emitted on **every** role at their identity value (`normal`/`none`/`none`/`wrap`) whether declared or not, so applying one role class over another fully resets it — which means **omitting `text-wrap` is not \"inherit\"**: it emits `text-wrap: wrap` and cancels the `pretty` the role would otherwise inherit from a `pretty` ancestor such as a `body`-mapped role. Declare it on every role — `balance` for heading-like roles, `pretty` for copy, `wrap` for short single-line labels.");
+const Typography = desc(z.strictObject({
 	families: desc(z.optional(z.record(z.string(), z.string())), "Role-facing family aliases → CSS font values, usually referencing the top-level `fonts` tokens (e.g. \"var(--font-display)\")."),
 	roles: desc(z.optional(z.record(z.string(), TypographyRole)), "Semantic type roles (display, title, heading, body, quote, caption, eyebrow, code, lead, footnote, tag, …), each emitted as a `font-<role>` class."),
 	headings: desc(z.optional(z.record(z.string(), z.string())), "Maps bare elements to type roles so unclassed markup picks up role styling — `{ \"h1\": \"display\", \"h2\": \"heading\" }`. The key is used verbatim as a selector, so it is not limited to h1…h6: **map `\"body\"` to your prose role** to bind base page typography to the role rather than hand-writing it. That binding is what makes the role editable — a stylesheet that re-states `font-family`/`line-height` as literals on `body` shadows `--<role>-ff`/`--<role>-lh`, and the live theme editor then appears to do nothing.")
 }), "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the bare-element → role mapping.");
-const AnimEffect = desc(z.object({
+const AnimEffect = desc(z.strictObject({
 	kf: desc(z.string(), "Keyframe family driving the effect: composite (transform/opacity), paint, or layout."),
 	css: z.optional(desc(VarMap, "Extra literal declarations merged into the effect class as-is.")),
 	vars: z.optional(desc(VarMap, "Effect endpoint variables (`--<key>: <value>`, e.g. opacity-from, translate-y-to) that override the keyframe defaults."))
 }), "A named animation effect class — a pure value layer (`--_anim` + `--<prop>-from/-to`) over the static keyframe engine.");
-const Animations = desc(z.object({
+const Animations = desc(z.strictObject({
 	effects: desc(z.optional(z.record(z.string(), AnimEffect)), "Effect classes to emit (`.fade-in`, `.reveal-left`, …), keyed by class name."),
-	journeys: desc(z.optional(z.object({
+	journeys: desc(z.optional(z.strictObject({
 		base: desc(z.optional(z.record(z.string(), VarMap)), "Named journey building blocks: part name → var map."),
 		compose: desc(z.optional(z.array(z.array(z.string()))), "Combinations of base parts, each emitted as a `.<parts>-journey` class.")
 	})), "Multi-part journey classes composed from `base` building blocks.")
 }), "Animation effect + journey classes (pure value layers). The animation engine itself — keyframes, drivers, floats, utilities — is static framework CSS, not configured here.");
-const DesignSystemSchema = z.object({
+const DesignSystemSchema = z.strictObject({
 	$schema: desc(z.optional(z.string()), "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation."),
-	meta: desc(z.optional(z.object({
+	meta: desc(z.optional(z.strictObject({
 		name: desc(z.optional(z.string()), "Brand/system name. Used as the `name` field and `<h1>` of the `design` format's `DESIGN.md`. Defaults to \"Design System\"."),
 		description: desc(z.optional(z.string()), "One or two sentences on the brand personality and the feeling the UI should evoke — what an agent needs when no token answers the question. Becomes the DESIGN.md `description` field and opens its Overview section; if omitted, a generic description of the system's mechanics is used instead.")
 	})), "Brand identity for agent-facing output. Consumed only by the `design` format (`DESIGN.md`); it emits no CSS and no tokens."),
 	colors: Colors,
 	shadows: desc(z.optional(z.record(z.string(), z.string())), "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. Values are shadow parameter lists (offset/blur/colour). Each token feeds two consumers with different grammars — `box-shadow` (pattern geometry, via the `--ds-*` group aliases) and `filter: drop-shadow(…)` (the utilities and the `shadow:` state shortcut) — so values must stay in the intersection: **one layer, no spread radius, no `inset`**. `drop-shadow()` rejects all three, and rejecting them invalidates the whole filter, so the shadow vanishes rather than degrading."),
-	fonts: desc(z.optional(z.record(z.string(), z.string())), "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`)."),
+	fonts: desc(z.optional(z.record(z.string(), z.string())), "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`). **Stacks only — vitops does not load webfonts.** A value here is a `font-family` list and nothing more: it emits no `@font-face`, no preload, and no metrics-matched fallback. If a family needs loading, declare it in Astro's `fonts:` config (`astro.config`, or the site config's `fonts` array) and point the token at the family's `cssVariable` — `\"display\": \"var(--font-league-spartan), sans-serif\"`. Installing a `@fontsource*` package and importing its CSS also works but gives up subsetting, preload and `size-adjust`/`ascent-override` fallbacks, so it regresses CLS."),
 	typeScale: desc(z.optional(Scale), "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities."),
 	spaceScale: desc(z.optional(Scale), "Fluid modular SPACE scale → `--space-<name>` tokens, consumed by spacing/gap utilities and vertical rhythm."),
 	patterns: z.optional(Patterns),
 	typography: z.optional(Typography),
 	animations: z.optional(Animations)
 });
-const ColorsPatch = z.object({
+const ColorsPatch = z.strictObject({
 	palette: z.optional(z.record(z.string(), Ramp)),
 	roles: z.optional(z.record(z.string(), RoleSpecSchema)),
 	utilities: z.optional(z.array(UtilityName))
@@ -338,6 +356,39 @@ const dropShadowIssue = (value) => {
 	const lengths = layer.replaceAll(/[\w-]*\([^()]*\)/g, " ").split(/\s+/).filter((t) => LENGTH.test(t));
 	if (lengths.length > 3) return `a spread radius (${lengths.length} lengths)`;
 };
+const RAMP_KEYS = new Set([
+	"seed",
+	"anchors",
+	"tones"
+]);
+/**
+* Replace the bare "Invalid input" a failed union produces with the reason.
+*
+* `Ramp` is `SeededRamp | FixedRamp`, and both branches are closed — so `{ seed,
+* tones }` or a stray key fails *both* and zod reports only that the union didn't
+* match. That message sends you reading the schema rather than looking at the two
+* keys in front of you, and the config that produced it is one whose `tones` were
+* being silently discarded at generate time.
+*/
+const explainRamp = (input) => (issue) => {
+	if (issue.code === "unrecognized_keys") {
+		const keys = issue.keys ?? [];
+		if (keys.length) return {
+			...issue,
+			message: `unknown key${keys.length > 1 ? "s" : ""} ${keys.map((k) => `"${k}"`).join(", ")} — not part of the schema, so ignored at generate time.`
+		};
+	}
+	if (issue.path.length !== 3 || issue.path[0] !== "colors" || issue.path[1] !== "palette") return issue;
+	const hue = input?.colors?.palette?.[String(issue.path[2])];
+	if (hue == null || typeof hue !== "object") return issue;
+	const keys = Object.keys(hue);
+	const unknown = keys.filter((k) => !RAMP_KEYS.has(k));
+	const message = "seed" in hue && "tones" in hue ? "a hue is either seeded (`seed`, with optional `anchors`) or fixed (`tones`) — not both. Drop one: with both present the `tones` are ignored at generate time." : unknown.length ? `unknown key${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}. A hue takes \`seed\` + optional \`anchors\`, or \`tones\`.` : keys.length === 0 ? "a hue needs `seed` (+ optional `anchors`) or `tones`." : null;
+	return message ? {
+		...issue,
+		message
+	} : issue;
+};
 /**
 * Validate an unknown value against the design-system schema.
 *
@@ -350,7 +401,7 @@ function validate(input) {
 	if (!result.success) return {
 		ok: false,
 		data: void 0,
-		errors: result.error.issues,
+		errors: result.error.issues.map(explainRamp(input)),
 		warnings: []
 	};
 	const { palette, roles } = result.data.colors;
@@ -532,6 +583,50 @@ function ladderWarnings(palette) {
 	return warnings;
 }
 /**
+* Gamut mapping nudges lightness by a hair, so an exact `<` comparison would
+* report rounding as an inversion. Well below any deviation a person could see.
+*/
+const MONOTONIC_EPSILON = .001;
+/**
+* Ramps whose lightness does not fall monotonically from 50 to 950.
+*
+* A ramp built from the ladder alone cannot invert — only pinned colours (a seed,
+* an `anchor`, a `tones` entry) can, because they are the one thing allowed off
+* it. `ladderWarnings` will not catch it: it compares each pinned step against
+* *its own* ladder rung, never against its neighbours, so it reports the wrong
+* defect ("reads darker than others at 600") while the real problem is that 600
+* is darker than 700. And since `LADDER_TOLERANCE` is 0.03 — the same size as the
+* ladder's own 50→100 gap — two anchors can each sit within tolerance and still
+* invert, with no warning at all.
+*
+* This is an error rather than a warning because the rest of the system assumes
+* the order: `snap` picks the nearest step by ladder lightness, the mode-stable
+* solid family hard-codes 600/700/800 as increasingly dark, and both dark tables
+* re-point steps on the same assumption. An inverted ramp therefore runs hover
+* states backwards — the failure the fixed ladder was introduced to eliminate.
+*/
+function monotonicityErrors(palette) {
+	const errors = [];
+	for (const [hue, expanded] of Object.entries(palette)) {
+		const numeric = expanded.numeric ?? {};
+		const steps = NUMERIC_STEPS.filter((s) => numeric[s] != null);
+		for (let i = 1; i < steps.length; i++) {
+			const [prev, step] = [steps[i - 1], steps[i]];
+			const lPrev = hexToOklch(numeric[prev]).l;
+			const lStep = hexToOklch(numeric[step]).l;
+			if (lStep < lPrev + MONOTONIC_EPSILON) continue;
+			const pinned = expanded.deviations ?? {};
+			const culprits = [prev, step].filter((s) => pinned[s] != null);
+			const fix = culprits.length ? culprits.map((s) => {
+				const l = hexToOklch(numeric[s]).l;
+				return `${numeric[s]} (pinned at ${s}) sits at L ${l.toFixed(3)}, nearest step ${nearestStep(l)}`;
+			}).join("; ") : `no step here is pinned, so this is a bug in the generator rather than in your config`;
+			errors.push(`colors.palette.${hue}: step ${step} (${numeric[step]}, L ${lStep.toFixed(3)}) is LIGHTER than step ${prev} (${numeric[prev]}, L ${lPrev.toFixed(3)}). A ramp must darken from 50 to 950 — inverted, a hover from \`bg-<role>-solid\` to \`-solid-bold\` gets lighter, and the dark-mode tables re-point steps assuming the order. ${fix}.`);
+		}
+	}
+	return errors;
+}
+/**
 * Surface roles: a bare `bg` (cards, panels, inputs), `bg-muted` for the page
 * behind them, `bg-x-muted` for wells, and `bg-bold`/`-x-bold` for the inverse
 * surface a tooltip sits on. Elevation is expressed by *which* token you reach
@@ -1194,6 +1289,8 @@ function renderCssClasses(ds) {
 	const typeRoles = Object.keys(ds.typography?.roles ?? {});
 	const shadows = Object.keys(ds.shadows ?? {});
 	const effects = Object.keys(ds.animations?.effects ?? {});
+	const stateful = Object.entries(ds.animations?.effects ?? {}).filter(([, e]) => e.kf === "composite" || e.kf === "paint").map(([name]) => name);
+	const keyframeOnly = effects.filter((name) => !stateful.includes(name));
 	const items = ds.patterns?.items ?? {};
 	const patterns = Object.keys(items);
 	const patternRoles = Array.from(new Set(Object.values(items).flatMap((p) => [p.default_role, ...p.roles ?? []].filter(Boolean))));
@@ -1253,9 +1350,29 @@ Every utility accepts a **container-breakpoint prefix**; animation utilities als
   \`--width-breakout\` / \`--width-spotlight\` and \`--gutter\`.
 - **\`rhythm\`** — relationship-based vertical spacing (margins between headings, paragraphs,
   lists, media) driven by the space scale. Usually paired with \`centered\`.
-- **\`split\`** — equal flex columns. Ratio rule: **\`split-<a>-<b>\`** where \`<a>-<b>\` ∈
-  \`1-2\`, \`2-1\`, \`1-3\`, \`3-1\`, \`1-4\`, \`4-1\`, \`2-3\`, \`3-2\` (breakpoint-prefixable).
-- **Flex** — \`flex\`, \`flex-row\`, \`flex-col\`; \`g\` for gap (space-scale token).
+- **\`split\`** — a two-column pair. Ratio rule: **\`split-<a>-<b>\`** where \`<a>-<b>\` ∈
+  \`1-2\`, \`2-1\`, \`1-3\`, \`3-1\`, \`1-4\`, \`4-1\`, \`2-3\`, \`3-2\` (breakpoint-prefixable); equal
+  columns without one. The ratio is a flex **basis**, so a column's padding counts
+  inside its share, and \`min-inline-size: 0\` is built in so long unbreakable content
+  can't stretch a column past it.
+  - **Stacking is \`flex-col\`** — there is no split-specific class for it:
+    \`class="split flex-col md-split-1-2"\` is stacked below 48rem and 1:2 above,
+    because the \`<bp>-\` ratio classes assert the row. While stacked the ratio goes
+    inert on its own (a percentage basis against an auto-height column resolves as
+    \`content\`), unless you give the split a definite \`block-size\`.
+  - **\`split-reverse\`** — swaps the two panels (breakpoint-prefixable). Implemented
+    as \`order\` on the first child, so it reverses on whichever axis the split is
+    currently on: bare, it swaps the columns in a row AND the rows in a stack;
+    scoped (\`md-split-reverse\`) it swaps only once there are two columns — media
+    first in source so it leads on mobile, on the right at width. The ratio stays
+    with the source-first child, not with the visual position.
+    - **Accessibility:** reversing makes visual order disagree with DOM order, and
+      focus order follows the DOM (WCAG 2.4.3 Focus Order). Put focusable content in
+      **only one** of the two panels, or the tab order will not be linear. The
+      pattern declares \`reading-flow: flex-visual\`, which fixes this properly where
+      it is supported; support is not yet broad enough to rely on.
+- **Flex** — \`flex\`, \`flex-row\`, \`flex-col\`, \`flex-row-reverse\`, \`flex-col-reverse\`
+  (all breakpoint-prefixable).
 - **Alignment** — \`items-{start,center,end,stretch}\`, \`justify-{start,center,end,between}\`,
   text align \`text-{start,center,end}\` (all breakpoint-prefixable).
 - **Display** — \`block\`, \`inline\`, \`inline-block\`, \`flex\`, \`grid\`, \`hidden\`
@@ -1266,15 +1383,27 @@ Every utility accepts a **container-breakpoint prefix**; animation utilities als
 ## Spacing
 
 The space scale is ${code(spaceNames)} exposed as \`--space-<name>\` tokens.
-Gap (\`g\`) and \`rhythm\` margins consume these tokens; prefer \`rhythm\` for vertical flow
-rather than per-element margins.
+\`rhythm\` margins consume these tokens; prefer \`rhythm\` for vertical flow rather than
+per-element margins.
+
+Rule: **\`gap-<name>\`**, **\`gap-x-<name>\`** (column) and **\`gap-y-<name>\`** (row), name ∈
+${code(spaceNames)} — all breakpoint-prefixable (\`md-gap-l\`, \`@md:gap-l\`). These are the
+framework's own utilities in every format: the fluid steps are deliberately kept out of
+Tailwind's \`--spacing-*\` namespace (named keys there shadow the size scales, so
+\`max-w-7xl\` would resolve to \`var(--spacing-7xl)\`), which means Tailwind's numeric
+\`gap-4\` still uses its own multiplier and coexists with these.
 
 ## Typography
 
 Rule: **\`font-<role>\`** — role ∈ ${code(typeRoles)}. Each role carries its own family,
-size (from the type scale ${code(typeNames)}), tracking, transform, and weight.
+size (from the type scale ${code(typeNames)}), tracking, transform, weight and \`text-wrap\`.
 Families: ${code(families)} (\`--font-*\`).
 
+Because the role owns \`text-wrap\`, a heading is balanced and copy is \`pretty\` with **no
+class at all** wherever \`typography.headings\` maps the bare element to a role. Override one
+element with \`text-{wrap,nowrap,balance,pretty}\` — the per-element escape hatch, for markup
+that carries no role class. (These four are Tailwind's own in the tailwind format.)
+
 ## Colour
 
 **Functional tokens are the primary vocabulary** — classes name the *job*, not the tone, and
@@ -1360,10 +1489,41 @@ follows non-rectangular shapes).
 
 ## Animation
 
-Rule: **\`<effect>\`** (with the state/flip prefixes above) — effect ∈ ${code(effects)}.
+An effect carries no motion of its own — it sets \`--<prop>-from\`/\`-to\` and picks a keyframe.
+A **driver** supplies the motion, and you always compose one of each:
+
+- \`animate-view\` — plays as the element crosses the viewport
+- \`animate-scroll\` — scrubs against page scroll
+- \`animate-trigger\` — time-based; plays once when \`.is-active\` / \`[data-active]\` is set
+- \`transition\` — transitions the same from/to vars, so it reverses on a state flip
+
+Rule: **\`<effect>\`** — effect ∈ ${code(effects)}. The state/flip prefixes above pair with
+\`transition\` and apply to every one of them.
+
+Each state matches the element **or its direct parent** (\`.hover-<fx>:hover, :hover > .hover-<fx>\`),
+which is what makes \`reveal-*\` usable: it rests at a zero-area \`clip-path\`, and \`clip-path\` clips
+hit-testing as well as painting, so the element itself can never be hovered.${keyframeOnly.length ? `
+
+${code(keyframeOnly)} animate \`height\`, the only stage that reflows and the only one behind a
+feature gate: \`0 → auto\` is not interpolable without \`interpolate-size: allow-keywords\`, so
+\`transition\` declares \`height\` only inside an \`@supports\` for it. The \`layout\` **keyframe**
+has the same dependency — this is not a limit of the transition driver.` : ""}
+
+**When it plays.** \`animate-view\` and \`.is-active\` are both timed off the element's **midpoint**:
+motion starts once that midpoint is 10% of the viewport in, and a one-shot entrance completes at
+25%. Both stops are the element's position on screen rather than a fraction of its own height, so a
+small card and a full-bleed section behave alike. Shift the window with \`--anim-start\` /
+\`--anim-end\`, or replace it outright with \`--anim-range\`.
+
 Composed **journeys** chain multiple effects into one entrance: rule \`<parts>-journey\`
-(e.g. \`fade-slide-journey\`, \`fade-scale-blur-journey\`). All require \`transition\` on the
-element; scroll-linked entrances resolve within the first portion of the element's scroll.
+(e.g. \`fade-slide-journey\`, \`fade-scale-blur-journey\`). They need a **keyframe** driver, not
+\`transition\`. A journey is entry → hold → exit, so it starts on that same 10% pivot but runs to the
+end of the exit phase — the hold occupies the middle of the crossing instead of the bottom edge of
+the screen.
+
+**\`stagger\`** on a parent offsets each child by \`--stagger-amount\` (time-based drivers) and by
+\`--stagger-range-step\` (scroll-driven ones — \`animation-delay\` is ignored on a progress-based
+timeline). Journeys set an explicit range and opt out.
 
 ## Component patterns
 
@@ -1467,6 +1627,13 @@ enforces.
 
 - Set \`"$schema": "${SCHEMA_URL}"\` in the config for editor autocomplete + validation.
 - Scaffold a starter config with \`vitops init\`; check one with \`vitops validate\`.
+- **This can be a standalone file, or live inside a site config.** Anywhere the
+  toolchain takes a config — \`--input\`, the Vite plugin, the Astro integration's
+  \`css.input\` — that file may be a \`design-system.json\` or the larger site config
+  that embeds one under \`designSystem.themes.<name>\`. They are told apart by shape,
+  and the fields below are the same either way. A site config additionally supplies
+  the site-level facts generation reads (its default colour scheme, legal documents,
+  icon sprite), so the path is declared once rather than per option.
 - The *why* behind each section: [colour system](concepts/color.md),
   [type & space scales](concepts/scales.md), [component patterns](concepts/patterns.md).
 - What each output format does with these tokens: [formats.md](formats.md).
@@ -1575,19 +1742,31 @@ docs build.
 @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.base\` — the reset (\`box-sizing: border-box\` on every element and pseudo-element,
+  a 16px root, no body margin) and the pure \`:root\` token blocks. Lowest of the three, so
+  your own reset overrides it — unlayered, or from a layer you declare before \`vitops.base\`.
+- \`vitops.components\` — the animation engine, the structural patterns (\`.rhythm\`,
+  \`.centered\`, \`.region\`, \`.split\`, \`.reveal\`) and every UI 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.
+  \`gap-*\`, animation effects, the layout utilities (\`.m-*\`, \`.flex-*\`, \`.items-*\`,
+  \`.split-<a>-<b>\`, track placement) and the display/\`sr-only\` families.
+
+So a utility overrides a pattern: \`class="card bg-danger-muted"\` tints the card,
+\`class="split flex-col"\` stacks the split, \`class="table text-center"\` centres the table.
+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).
+
+The classification is by RULE, not by file: a partial that mixes patterns and utilities is
+split in two rather than shelved whole. \`layout.css\` (patterns) and \`layout-utilities.css\`
+(utilities) are the same family in two files for exactly this reason, and the \`tailwind\`
+format reaches the same arrangement by its own route — patterns in \`@layer components\`,
+utilities as \`@utility\`.
+
+Known gap: the \`typography.headings\` bare-element bindings (\`h1\`, \`h2\`, \`body\`) are
+emitted alongside \`.font-<role>\` and so sit in \`vitops.utilities\`, where a tag rule
+outranks every pattern — \`<h2 class="pull-quote">\` keeps the heading's font-size in
+\`css\`/\`bricks\` and the pattern's in \`tailwind\`, which puts the bindings in \`@layer base\`.
+Give the element a \`.font-<role>\` class to pin it either way.
 
 ## \`bricks\` — WordPress / Bricks Builder payload
 
@@ -1723,8 +1902,18 @@ ignores the appearance.
 
 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.
+\`<html>\`, so the toggle works on every other target. Set either.
+
+The OS preference is a **second, opt-in block**. Set
+\`designSystem.defaultColorScheme: "system"\` in your site config and the same delta is emitted again inside
+\`@media (prefers-color-scheme: dark)\`, under
+\`${SYSTEM_DARK_SEL}\` — i.e. whenever no explicit choice has been made. That is what makes
+\`<color-scheme-toggle>\`'s "System" position resolve to the OS (it *removes* the attribute,
+so without this block it fell through to light), and it gives a no-JS page the OS
+appearance, which the toggle alone never could. An explicit light choice still wins.
+
+It is opt-in rather than default because turning it on flips a site dark for dark-OS
+visitors, which is the site's decision and not the design system's.
 
 ## Contrast guarantees
 
@@ -1947,6 +2136,118 @@ variable-driven CSS framework plus progressively-enhanced web components, genera
 * [Bricks Builder](bricks/) - custom elements and how to style them
 `;
 }
+function renderIconsConcept() {
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops icons — one semantic vocabulary across icon sets",
+		description: "Semantic icon names that resolve per configured set, how the bundle is derived on a server build, and the three delivery paths (astro-icon, astro-iconset, SVG sprite).",
+		resource: DS_PATH,
+		tags: [
+			"icons",
+			"svg",
+			"sprite",
+			"astro-icon",
+			"design-system"
+		]
+	})}
+
+# Icons
+
+Icons are named by **meaning**, not by set. \`menu\` resolves to \`fa7-solid:bars\`,
+\`lucide:menu\` or \`ph:list\` depending on which set the site configures, so changing
+sets is a config edit rather than a find-and-replace across templates.
+
+The escape hatch is deliberate and always available: **a name containing \`:\` passes
+through untouched**. \`<Icon name="simple-icons:zoho" />\` renders that exact glyph
+whether or not the semantic map knows it.
+
+## Declaring them
+
+The \`icons\` block lives in the **site config**, not \`design-system.json\` — it
+describes what a site uses, not what the design system defines.
+
+\`\`\`json
+{
+  "icons": {
+    "ui": "ph",
+    "brand": "simple-icons",
+    "weight": "bold",
+    "semantic": ["menu", "close", "arrow-right"],
+    "simple-icons": ["zoho", "cloudflare"],
+    "sprite": true
+  }
+}
+\`\`\`
+
+\`ui\` and \`brand\` pick which set a semantic name resolves against. Any other key is
+an iconify collection name with an explicit list, passed through verbatim.
+
+**\`weight\` is only meaningful for sets that encode weight in the icon NAME.**
+Phosphor does (\`list\`, \`list-bold\`, \`list-fill\`), so \`ph\` accepts it; Font Awesome
+splits weights across collections instead (\`fa7-solid\` vs \`fa7-regular\`), so there
+the weight is part of the prefix and this key is ignored.
+
+## Why the bundle list exists
+
+astro-icon is **zero-config on a static build**. Under \`output: 'server'\` it bundles
+*every icon in a set* unless given an \`include\` map — which is why projects end up
+hand-maintaining one.
+
+The \`icons\` option on \`getvitops()\` derives it by scanning your source, merged with
+whatever you declare. On a static build **no include is passed at all**: there is
+nothing to trim there, and a list could only drop a glyph the scan couldn't see.
+
+Two failure modes, treated differently on purpose:
+
+- A name you **declared** that doesn't resolve is a config error and **throws**.
+- A name only the **scan** found and can't resolve just **warns** — a bare unmapped
+  name is more often a local \`src/icons/*.svg\` than a mistake, and a dev server
+  that dies on a template typo is worse than one that tells you.
+
+Names computed at runtime (\`<Icon name={expr} />\`) can't be read statically. They are
+reported with file and line, never guessed at — declare them in \`semantic\` or a
+per-set list. Run \`vitops icons\` to see the whole report.
+
+## Delivery
+
+| Path | Used by | Needs |
+| --- | --- | --- |
+| \`astro-icon\` / \`astro-iconset\` | Astro sites | the integration, an optional peer |
+| **SVG sprite** (\`icons.svg\`) | Bricks/WordPress, EmDash renderers, plain HTML | \`icons.sprite: true\` |
+
+The sprite is the no-JavaScript path: \`<svg><use href="/vitops/icons.svg#ph--list"></svg>\`.
+Ids are the qualified name with \`:\` replaced by \`--\` (\`:\` is not valid in a fragment
+identifier), **plus a set-independent \`icon-<name>\` alias for every semantic name** —
+so sprite markup survives an icon-set change the same way \`resolveIcon\` protects Astro
+call sites.
+
+In WordPress, \`vitops_icon('menu')\` and \`[vitops_icon name="menu"]\` emit that markup,
+and a **Vitops → Icon** Bricks element wraps the same helper.
+
+⚠️ An external-file \`<use>\` is **same-origin only** and dead under \`file://\`. Serving
+\`dist/\` from a different origin makes every icon vanish with no console error.
+
+## Markup
+
+Always the framework's \`.icon\` box:
+
+\`\`\`html
+<span class="icon" aria-hidden="true"><svg>…</svg></span>
+\`\`\`
+
+\`.icon\` sizes in \`em\` via \`--icon-size\` (default \`1.25em\`) and sets \`fill: currentColor\`,
+so an icon inherits the colour of whatever it sits in. Because \`.cta\` and
+\`:where(button, .btn)\` are already \`inline-flex\` with a \`gap\`, **a start or end icon is
+child order — not a modifier class**.
+
+Icons are \`aria-hidden\` by default. Pass a label only when the icon carries meaning on
+its own; beside a text label it would be announced twice.
+
+Note \`.icon-mask\` is a different thing: the CSS-only adornment path used by
+\`.link--icon::before\`, where the glyph is a \`mask-image\` on a pseudo-element and there
+is no markup to hang an \`<svg>\` on.
+`;
+}
 function renderConceptsIndex() {
 	return `${INDEX_NOTE}
 
@@ -1957,6 +2258,7 @@ function renderConceptsIndex() {
 * [Colour system](color.md) - seeded OKLCH scales on a shared lightness ladder, target-prefixed tokens, automatic dark mode
 * [Type & space scales](scales.md) - fluid modular scales and the tokens they emit
 * [Component patterns](patterns.md) - token cascade, override hooks, states, role variants
+* [Icons](icons.md) - semantic names across icon sets, bundle derivation, sprite delivery
 `;
 }
 function renderCssIndex() {
@@ -2004,6 +2306,7 @@ function generateDocs(ds, assetsDir) {
 		"concepts/color.md": renderColorConcept(ds),
 		"concepts/scales.md": renderScalesConcept(ds),
 		"concepts/patterns.md": renderPatternsConcept(ds),
+		"concepts/icons.md": renderIconsConcept(),
 		"css/index.md": renderCssIndex(),
 		"css/classes.md": renderCssClasses(ds),
 		"bricks/index.md": renderBricksIndex(),
@@ -2362,6 +2665,10 @@ Layout is composed from utilities rather than bespoke CSS:
   decision rather than per-element margins.
 - \`.flex\` / \`.split-<a>-<b>\` / \`.grid\` — the structural families, with container-query
   variants prefixed \`sm-\` / \`md-\` / \`lg-\` / \`xl-\` (30 / 48 / 64 / 80rem).
+  \`.split\` is a two-column pair. Stack it with \`.flex-col\` and let a
+  breakpoint-prefixed ratio un-stack it (\`split flex-col md-split-1-2\`);
+  \`.split-reverse\` swaps the two panels. Reversing puts visual order out of step
+  with DOM order, so keep focusable content in only one panel.
 
 Breakpoints are **container** queries, not viewport media queries: a component
 responds to the space it is given, so the same markup works in a sidebar and a full-width
@@ -2442,7 +2749,7 @@ across every pattern. Focus rings are never removed, only restyled.
 * `design-system.json`-compliant `designSystem`.
 *
 * Authored with `zod/mini` (same instance the design-system schema uses), so the
-* two compose: `DesignSystemSchema` is embedded as `designSystem.<theme>` and the
+* two compose: `DesignSystemSchema` is embedded as `designSystem.themes.<theme>` and the
 * whole thing serialises to one JSON Schema via `z.toJSONSchema`. Everything a
 * generator needs derives from here: the `SiteConfig` type (`z.infer`), the
 * published JSON Schema (`siteJsonSchema`), and runtime validation (`validateSite`).
@@ -2475,9 +2782,32 @@ const DayOfWeek = z.enum([
 	"Sunday"
 ]);
 const DesignSystemEntry = z.extend(DesignSystemPatchSchema, {
-	displayName: desc(z.optional(LocalizableSchema), "Human-readable theme name (localisable)."),
-	extends: desc(z.optional(z.string()), "Another `designSystem` key to inherit from; this entry then only supplies what it overrides.")
+	displayName: desc(z.optional(LocalizableSchema), "Human-readable theme name (localisable). The label a theme picker would show — nothing reads it yet, because nothing builds more than one theme (see `themes`)."),
+	extends: desc(z.optional(z.string()), "Another `themes` key to inherit from; this entry then only supplies what it overrides.")
 });
+/**
+* The design system as a whole: the named themes plus the facts that describe the
+* system rather than any one theme.
+*
+* `themes` is nested rather than being the block itself because the block used to
+* BE the map — every key was a theme name, so there was nowhere to put
+* system-wide metadata without it colliding with a theme of that name.
+*
+* Note the two axes here are independent, and deliberately so. `defaultTheme`
+* picks a *theme* (an authored design system); `defaultColorScheme` picks an
+* *appearance* (light/dark), which every theme already has because the flip is
+* derived from one ramp rather than authored. "Theme `elegant`, appearance
+* follows the OS" has to be sayable, and a single union could not express it.
+*/
+const DesignSystemBlock = desc(z.strictObject({
+	themes: desc(z.record(z.string(), DesignSystemEntry), "Named themes. `default` is the base; others may `extends` another and supply a partial patch. Light/dark is NOT a theme — the functional tokens flip per appearance within each one, so `default` already has both. Only the default theme is built today; multi-theme output and a picker are not wired yet."),
+	defaultTheme: desc(z.optional(z.string()), "Which `themes` entry to use (convention: \"default\"). Validated against the map; selecting a non-default theme is not wired yet."),
+	defaultColorScheme: desc(z.optional(z.enum([
+		"light",
+		"dark",
+		"system"
+	])), "Initial appearance. `\"system\"` follows the OS via `prefers-color-scheme` and is what makes `<color-scheme-toggle>`'s \"System\" position resolve to anything — it removes the theme attribute, so without this the page falls through to light. It also gives a no-JS page the OS appearance. Defaults to `\"light\"`, because switching an existing site to `\"system\"` visibly flips it dark for dark-OS visitors.")
+}), "The design system: named themes plus the system-wide facts (which theme, which appearance). A bare design system, or a bare theme map, is accepted as shorthand for `{ themes: … }`.");
 const LocaleSchema = z.object({
 	name: desc(z.string(), "Display name of the locale (e.g. \"English\")."),
 	tagline: desc(z.optional(z.string()), "Site tagline in this locale."),
@@ -2626,7 +2956,7 @@ const FontVariantSchema = z.object({
 	unicodeRange: z.optional(z.array(z.string())),
 	display: z.optional(FontDisplay)
 });
-const FontSchema = z.object({
+const SiteFontSchema = z.object({
 	name: z.string(),
 	provider: FontProvider,
 	cssVariable: z.string().check(z.regex(/^--/)),
@@ -2775,6 +3105,35 @@ const TwitterSchema = z.object({
 	image: z.optional(ImageRefSchema)
 });
 /**
+* What `vitops notify` needs to tell search engines a deploy happened.
+*
+* Scoped by what search engines actually accept, which is narrower than it looks:
+* Google exposes **no** "request indexing" API (the Search Console button is not in
+* its API, and URL Inspection is read-only), and it removed the sitemap ping
+* endpoint in 2023. So the sanctioned set is: an accurate sitemap, a Search Console
+* sitemap resubmit, an IndexNow ping — which Google does *not* honour but Bing,
+* Yandex, Naver, Seznam and Yep do — and a read-only inspection pass to find out
+* what Google actually did.
+*
+* Facts only, the same rule the legal block follows: this records what the site has
+* (a key, a property, which pages matter), never what to say about it.
+*/
+const IndexNowSchema = z.object({
+	key: desc(z.string().check(z.regex(/^[a-zA-Z0-9-]{8,128}$/)), "IndexNow key (8–128 chars, hex is conventional). NOT a secret — it is served publicly at `keyLocation` so the engine can verify you own the host. Generate one with `vitops notify --new-key`."),
+	keyLocation: desc(z.optional(z.url()), "Absolute URL of the key file. Defaults to `<canonical>/<key>.txt`; set it only when the file lives elsewhere."),
+	endpoint: desc(z.optional(z.url()), "IndexNow endpoint (default `https://api.indexnow.org/indexnow`). Any participating engine shares submissions with the rest, so one is normally enough.")
+});
+const SearchConsoleSchema = z.object({
+	siteUrl: desc(z.string(), "The property exactly as Search Console identifies it — `sc-domain:acme.ca` for a domain property, or the URL-prefix form `https://acme.ca/`. A mismatch here is a 403, not a \"not found\"."),
+	resubmitSitemap: desc(z.optional(z.boolean()), "Re-submit the sitemap through the Search Console API on each notify (default true when `searchConsole` is set). This is the automated equivalent of the manual resubmit in the UI.")
+});
+const IndexingSchema = z.object({
+	sitemapUrl: desc(z.optional(z.url()), "The sitemap to submit and to diff for changed URLs. Defaults to `<canonical>/sitemap-index.xml`."),
+	indexNow: desc(z.optional(IndexNowSchema), "IndexNow submission (Bing, Yandex, Naver, Seznam, Yep — not Google). Omit to skip the channel."),
+	searchConsole: desc(z.optional(SearchConsoleSchema), "Google Search Console property. Needs a service-account credential in `VITOPS_GSC_SERVICE_ACCOUNT` or `GOOGLE_APPLICATION_CREDENTIALS` at run time — never put the key in this file."),
+	priorityUrls: desc(z.optional(z.array(z.url())), "The pages whose indexing actually matters. `vitops notify --check` inspects these and exits non-zero if Google has not indexed one. Kept explicit because URL Inspection is quota-bound (2000/day), so checking every page is neither affordable nor informative.")
+});
+/**
 * Which template set the generated legal documents are written against. This is
 * a closed enum rather than a free string because an unrecognised value would
 * otherwise silently fall back to the wrong body of law; `validateSite` rejects
@@ -2828,11 +3187,8 @@ const SiteConfigSchema = z.object({
 		splitRatio: desc(z.optional(z.number().check(z.gte(0), z.lte(1))), "Fraction of traffic sent to the variant (0–1)."),
 		variants: desc(z.optional(z.record(z.string(), AbVariantSchema)), "Named variants; each targets an environment and may deep-merge config `overrides`.")
 	})), "A/B testing: cookie-based split plus named variants whose `overrides` patch the config per environment."),
-	designSystem: desc(z.record(z.string(), DesignSystemEntry), "Named-theme map of design systems. `default` is the base; other entries may `extends` another and supply a partial patch. Light/dark is automatic (functional tokens flip per appearance), not a separate theme entry. A bare design system (with `colors`) is shorthand for `{ default: … }`."),
-	defaultTheme: desc(z.optional(z.string()), "Which `designSystem` entry to use by default (convention: \"default\")."),
-	defaultColorScheme: desc(z.optional(z.enum(["light", "dark"])), "Initial appearance to render before any user/system preference applies."),
-	respectSystemPreference: desc(z.optional(z.boolean()), "Follow the user's OS light/dark preference."),
-	fonts: desc(z.optional(z.array(FontSchema)), "Font LOADING (a serialisable projection of the Astro Fonts API: provider, weights, subsets, preload). Font TOKENS live in `designSystem.<theme>.fonts` and reference the same `cssVariable`."),
+	designSystem: DesignSystemBlock,
+	fonts: desc(z.optional(z.array(SiteFontSchema)), "Font LOADING (a serialisable projection of the Astro Fonts API: provider, weights, subsets, preload). Font TOKENS live in `designSystem.themes.<theme>.fonts` and reference the same `cssVariable`."),
 	tags: desc(z.optional(z.record(z.string(), z.unknown())), "Free-form content-tag taxonomy (site-specific; not interpreted by the generator)."),
 	postTypes: desc(z.optional(z.record(z.string(), z.unknown())), "Free-form content-type definitions (site-specific; not interpreted by the generator)."),
 	galleries: desc(z.optional(z.record(z.string(), GallerySchema)), "Named image galleries (title, tags, images with localisable alt/caption)."),
@@ -2849,13 +3205,20 @@ const SiteConfigSchema = z.object({
 		googleSiteVerification: z.optional(z.string()),
 		bingSiteVerification: z.optional(z.string()),
 		openGraph: z.optional(OpenGraphSchema),
-		twitter: z.optional(TwitterSchema)
-	})), "SEO defaults: title/description templates, robots policy, verification tokens, Open Graph + Twitter cards."),
+		twitter: z.optional(TwitterSchema),
+		indexing: desc(z.optional(IndexingSchema), "How `vitops notify` tells search engines about a deploy: which sitemap, IndexNow key, Search Console property, and which pages to verify afterwards.")
+	})), "SEO defaults: title/description templates, robots policy, verification tokens, Open Graph + Twitter cards, and post-deploy indexing notification."),
 	analytics: desc(z.optional(z.object({
 		googleAnalyticsId: z.optional(z.string()),
 		plausibleDomain: z.optional(z.string()),
-		googleTagManagerId: z.optional(z.string())
-	})), "Analytics provider IDs (gated per environment via `environments.<env>.analytics`)."),
+		googleTagManagerId: z.optional(z.string()),
+		clarityId: desc(z.optional(z.string()), "Microsoft Clarity project ID."),
+		matomo: desc(z.optional(z.object({
+			url: desc(z.string(), "Instance base URL (self-hosted, or `*.matomo.cloud`)."),
+			siteId: desc(z.string(), "Site ID within that instance."),
+			cookies: desc(z.optional(z.boolean()), "Default false — Matomo runs cookieless (`disableCookies`), which is what lets the cookie notice state positively that it sets none.")
+		})), "Matomo instance.")
+	})), "Analytics provider IDs (gated per environment via `environments.<env>.analytics`). Which provider is set is also what the generated privacy policy and cookie notice disclose — see `legal`."),
 	notifications: desc(z.optional(z.object({ email: z.optional(z.email()) })), "Where site notifications (e.g. form submissions) are sent."),
 	tracking: desc(z.optional(z.object({
 		enabled: z.optional(z.boolean()),
@@ -2889,9 +3252,11 @@ const SiteConfigSchema = z.object({
 			categories: z.optional(z.array(z.string()))
 		}))
 	})), "Legal pages: which documents exist, where they live, and the facts the generated prose asserts."),
-	icons: desc(z.optional(z.object({
-		ui: desc(z.optional(z.string()), "Icon set used for UI chrome (e.g. \"lucide\")."),
+	icons: desc(z.optional(z.looseObject({
+		ui: desc(z.optional(z.string()), "Icon set used for UI chrome (e.g. \"lucide\", \"ph\")."),
 		brand: desc(z.optional(z.string()), "Icon set used for brand marks."),
+		weight: desc(z.optional(z.string()), "Weight for suffix-weighted sets like Phosphor (\"regular\" | \"bold\" | \"duotone\" | \"fill\" | \"light\" | \"thin\"). Ignored by sets that split weights across collections, e.g. Font Awesome."),
+		sprite: desc(z.optional(z.boolean()), "Emit an SVG sprite (icons.svg) alongside the stylesheet, for consumers that cannot run an icon integration (Bricks/WordPress, EmDash renderers)."),
 		semantic: desc(z.optional(z.array(z.string())), "Named semantic icons to include."),
 		"fa7-solid": z.optional(z.array(z.string())),
 		"fa7-regular": z.optional(z.array(z.string())),
@@ -2900,7 +3265,8 @@ const SiteConfigSchema = z.object({
 		"fa7-brands": z.optional(z.array(z.string())),
 		"simple-icons": z.optional(z.array(z.string())),
 		"material-symbols": z.optional(z.array(z.string())),
-		lucide: z.optional(z.array(z.string()))
+		lucide: z.optional(z.array(z.string())),
+		ph: z.optional(z.array(z.string()))
 	})), "Icon sets and the specific icons to bundle from each (keys are iconify collection names)."),
 	favicon: desc(z.optional(z.object({
 		source: desc(z.string(), "Source image (SVG/PNG) the favicon set is generated from."),
@@ -2944,17 +3310,24 @@ function validateSite(input) {
 	const errors = [];
 	const has = (m, k) => !!m && k in m;
 	if (!has(cfg.locales, cfg.defaultLocale)) errors.push(issue(["defaultLocale"], `defaultLocale "${cfg.defaultLocale}" is not in locales`));
-	if (!has(cfg.designSystem, "default") && cfg.defaultTheme == null) errors.push(issue(["designSystem"], "designSystem must include a \"default\" theme"));
-	if (cfg.defaultTheme != null && !has(cfg.designSystem, cfg.defaultTheme)) errors.push(issue(["defaultTheme"], `defaultTheme "${cfg.defaultTheme}" is not in designSystem`));
-	for (const [key, entry] of Object.entries(cfg.designSystem)) if (entry.extends != null && !has(cfg.designSystem, entry.extends)) errors.push(issue([
+	const themes = cfg.designSystem?.themes ?? {};
+	const defaultTheme = cfg.designSystem?.defaultTheme;
+	if (!has(themes, "default") && defaultTheme == null) errors.push(issue(["designSystem", "themes"], "themes must include a \"default\" entry"));
+	if (defaultTheme != null && !has(themes, defaultTheme)) errors.push(issue(["designSystem", "defaultTheme"], `defaultTheme "${defaultTheme}" is not in designSystem.themes`));
+	for (const [key, entry] of Object.entries(themes)) if (entry.extends != null && !has(themes, entry.extends)) errors.push(issue([
 		"designSystem",
+		"themes",
 		key,
 		"extends"
-	], `extends "${entry.extends}" is not a designSystem key`));
-	for (const key of Object.keys(cfg.designSystem)) try {
-		resolveTheme(cfg.designSystem, key);
+	], `extends "${entry.extends}" is not a themes key`));
+	for (const key of Object.keys(themes)) try {
+		resolveTheme(themes, key);
 	} catch (e) {
-		errors.push(issue(["designSystem", key], e.message));
+		errors.push(issue([
+			"designSystem",
+			"themes",
+			key
+		], e.message));
 	}
 	if (cfg.primaryLocation != null && !has(cfg.locations, cfg.primaryLocation)) errors.push(issue(["primaryLocation"], `primaryLocation "${cfg.primaryLocation}" is not in locations`));
 	if (typeof cfg.contact === "string" && !has(cfg.locations, cfg.contact)) errors.push(issue(["contact"], `contact "${cfg.contact}" is not a locations key`));
@@ -2993,6 +3366,20 @@ function validateSite(input) {
 		if (resolvePrivacyContact(cfg) == null) errors.push(issue(["legal", "privacyPolicy"], "privacyPolicy.enabled requires a contact for privacy requests — set legal.privacyPolicy.privacyOfficer, contact, or organization.email/address"));
 		if (cfg.domains?.canonical == null) errors.push(issue(["legal", "privacyPolicy"], "privacyPolicy.enabled requires domains.canonical — the policy states where information is held"));
 	}
+	const indexing = cfg.seo?.indexing;
+	if (indexing != null && cfg.domains?.canonical == null) {
+		if (indexing.sitemapUrl == null) errors.push(issue([
+			"seo",
+			"indexing",
+			"sitemapUrl"
+		], "seo.indexing needs domains.canonical to derive the sitemap URL — set one, or state sitemapUrl explicitly"));
+		if (indexing.indexNow != null && indexing.indexNow.keyLocation == null) errors.push(issue([
+			"seo",
+			"indexing",
+			"indexNow",
+			"keyLocation"
+		], "seo.indexing.indexNow needs domains.canonical to derive the key location — set one, or state keyLocation explicitly"));
+	}
 	if (errors.length) return {
 		ok: false,
 		data: void 0,
@@ -3061,22 +3448,49 @@ function resolveTheme(designSystem, key) {
 	return out;
 }
 /**
+* Normalise the two `designSystem` shorthands to the canonical
+* `{ themes: { … } }` shape.
+*
+* Both are keyed off what CANNOT be a theme name in the other reading:
+*  - `colors` → a bare `DesignSystem` was written inline.
+*  - `themes` → already canonical.
+*  - neither → the legacy bare theme map, from before the block gained
+*    system-wide fields. Every config authored against the old schema takes this
+*    branch, which is what keeps the change forgiving at runtime even though the
+*    published JSON Schema moved.
+*/
+function normaliseDesignSystem(raw) {
+	const ds = raw.designSystem;
+	if (ds == null || typeof ds !== "object") return;
+	if ("themes" in ds) return;
+	raw.designSystem = "colors" in ds ? { themes: { default: ds } } : { themes: ds };
+}
+/**
 * Resolve a raw (already-parsed) config into a validated `SiteConfig`:
 *  1. strip YAML nulls,
-*  2. apply the active A/B variant's `overrides` (by `siteEnv`),
-*  3. normalise a bare-`DesignSystem` `designSystem` shorthand to `{ default: … }`,
+*  2. normalise the `designSystem` shorthands to `{ themes: … }`,
+*  3. apply the active A/B variant's `overrides` (by `siteEnv`),
 *  4. validate (shape + cross-field).
 * Pure — no YAML/env access. A loader supplies `siteEnv`.
+*
+* Steps 2 and 3 are in this order deliberately. Normalising first means an
+* `abTesting` override always addresses the canonical shape
+* (`designSystem.themes.<name>`), whatever shorthand the base config used. With
+* the merge first, an override's key path depended on how the base happened to be
+* written — so the same patch hit a different place in two configs that were
+* otherwise equivalent.
 */
 function resolveSiteConfig(input, siteEnv = "production") {
 	const raw = stripNulls(input);
+	normaliseDesignSystem(raw);
 	const envConfig = raw.environments?.[siteEnv];
 	if (envConfig?.variant) {
 		const overrides = raw.abTesting?.variants?.[envConfig.variant]?.overrides;
-		if (overrides) deepMerge(raw, overrides);
+		if (overrides) {
+			normaliseDesignSystem(overrides);
+			deepMerge(raw, overrides);
+		}
 	}
-	const ds = raw.designSystem;
-	if (ds != null && "colors" in ds) raw.designSystem = { default: ds };
 	const result = validateSite(raw);
 	if (!result.ok) {
 		const msg = result.errors.map((e) => `  ${e.path.join(".")}: ${e.message}`).join("\n");
@@ -3084,6 +3498,52 @@ function resolveSiteConfig(input, siteEnv = "production") {
 	}
 	return result.data;
 }
+/**
+* Is this raw config a `SiteConfig` rather than a bare `design-system.json`?
+*
+* The discriminator is **total**, not a heuristic, and both halves are load-
+* bearing: `SiteConfigSchema` cannot validate without a `designSystem` (a config
+* lacking one fails `validateSite` with `themes must include a "default" entry`),
+* and `DesignSystemSchema` is strict, so a `designSystem` key in a design system
+* is an `unrecognized_keys` error. No document can be read as both, and no
+* document that is neither reaches here without failing validation anyway.
+*
+* Deliberately shape-based rather than filename-based: consumers name this file
+* whatever suits them (`company.json`, `site.json`, `vitops.config.json`), and a
+* rule keyed to a name would silently stop working the moment someone renamed it.
+*/
+function isSiteConfig(raw) {
+	return typeof raw === "object" && raw != null && !Array.isArray(raw) && "designSystem" in raw;
+}
+/**
+* Resolve a raw config of either kind into the design system to build from.
+*
+* Every entry point that used to take a `design-system.json` goes through this,
+* so a consumer who keeps their tokens inside the larger site config points the
+* same option at that file instead of maintaining a second one. The site config
+* is handed back too, because the parts of generation that depend on site-level
+* facts (`designSystem.defaultColorScheme`, the legal documents, the icon
+* sprite) would otherwise need the same path declared a second time.
+*
+* The returned `designSystem` is **not** validated here — the caller does that,
+* so it can say which file and which theme the errors belong to. Validation of
+* the site config itself has already happened (`resolveSiteConfig` throws).
+*/
+function resolveInput(raw, opts = {}) {
+	if (!isSiteConfig(raw)) {
+		if (opts.theme != null) throw new Error(`theme "${opts.theme}" was requested, but this is a design-system.json — it holds one design system and no \`themes\` map. Point at a site config to select a theme.`);
+		return { designSystem: raw };
+	}
+	const site = resolveSiteConfig(raw, opts.siteEnv);
+	const themes = site.designSystem?.themes ?? {};
+	const theme = opts.theme ?? site.designSystem?.defaultTheme ?? "default";
+	if (!(theme in themes)) throw new Error(`designSystem.themes has no "${theme}" entry (found: ${Object.keys(themes).join(", ") || "none"})`);
+	return {
+		designSystem: resolveTheme(themes, theme),
+		site,
+		theme
+	};
+}
 /** Strip nulls (YAML `~`/`null`) → undefined so optional fields validate. */
 function stripNulls(obj) {
 	if (obj === null) return void 0;
@@ -3137,6 +3597,30 @@ const KNOWN_PROCESSORS = {
 		privacyUrl: "https://plausible.io/privacy",
 		cookies: []
 	},
+	clarity: {
+		name: "Microsoft Clarity",
+		purpose: "session replay and heatmaps",
+		country: "the United States",
+		privacyUrl: "https://privacy.microsoft.com/privacystatement",
+		cookies: [
+			"_clck",
+			"_clsk",
+			"MUID"
+		],
+		optOut: "https://privacy.microsoft.com/privacystatement"
+	},
+	matomo: {
+		name: "Matomo",
+		purpose: "website analytics",
+		privacyUrl: "https://matomo.org/privacy-policy/",
+		cookies: ["_pk_id", "_pk_ses"]
+	},
+	matomoCookieless: {
+		name: "Matomo",
+		purpose: "website analytics",
+		privacyUrl: "https://matomo.org/privacy-policy/",
+		cookies: []
+	},
 	turnstile: {
 		name: "Cloudflare Turnstile",
 		purpose: "bot protection on forms",
@@ -3185,6 +3669,8 @@ function detectProcessorKeys(site) {
 	if (analytics?.googleAnalyticsId) keys.push("googleAnalytics");
 	if (analytics?.googleTagManagerId) keys.push("googleTagManager");
 	if (analytics?.plausibleDomain) keys.push("plausible");
+	if (analytics?.clarityId) keys.push("clarity");
+	if (analytics?.matomo) keys.push(analytics.matomo.cookies ? "matomo" : "matomoCookieless");
 	if (site.security?.turnstile?.siteKey) keys.push("turnstile");
 	const platform = site.deployment?.platform;
 	const hosting = platform && HOSTING_PATTERNS.find(([re]) => re.test(platform))?.[1];
@@ -3199,10 +3685,27 @@ function detectProcessorKeys(site) {
 * an explicit declaration is a statement of fact we have no grounds to drop.
 */
 function resolveProcessors(site) {
-	const detected = detectProcessorKeys(site).map((k) => KNOWN_PROCESSORS[k]);
+	const detected = detectProcessorKeys(site).map((k) => matomoCountry(KNOWN_PROCESSORS[k], site));
 	const declared = site.legal?.privacyPolicy?.processors ?? [];
 	return [...detected, ...declared];
 }
+/**
+* Matomo is the one provider whose location the config actually knows.
+*
+* Matomo Cloud is hosted in the EU; a self-hosted instance is wherever the
+* consumer put it, which is very often their own infrastructure in their own
+* country. So the cross-border transfer sentence is asserted only for the case we
+* can see. Naming a transfer that isn't happening is the same class of error as
+* omitting one that is — the config records facts, and "we don't know" is a fact.
+*/
+function matomoCountry(processor, site) {
+	if (processor.name !== "Matomo") return processor;
+	const url = site.analytics?.matomo?.url ?? "";
+	return /\.matomo\.cloud/i.test(url) ? {
+		...processor,
+		country: "the European Union"
+	} : processor;
+}
 
 //#endregion
 //#region src/legal/derive.ts
@@ -3321,7 +3824,7 @@ function derivePolicyVars(site) {
 	const processors = resolveProcessors(site);
 	const fields = formFields(site);
 	const hasForms = fields.length > 0;
-	const hasAnalytics = !!site.analytics && Object.values(site.analytics).some((v) => typeof v === "string" && v.length > 0);
+	const hasAnalytics = Object.values(site.analytics ?? {}).some((v) => typeof v === "string" ? v.length > 0 : !!v);
 	processors.filter((p) => p.cookies?.length);
 	const consent = legal?.cookieConsent;
 	const contact = resolvePrivacyContact(site);
@@ -3333,15 +3836,18 @@ function derivePolicyVars(site) {
 		fields.some((f) => /newsletter|subscribe|mailing/i.test(f.name)) ? "register to receive our newsletter" : void 0
 	]);
 	const piiCollected = uniq([...hasForms ? fields.map((f) => fieldPhrase(f.name, f.type)) : ["your full name", "contact information, such as your address, telephone number, or e-mail address"], "any other personal information that you choose to submit to us"]);
+	const hasSessionReplay = !!site.analytics?.clarityId;
 	const techInfo = uniq([
 		"your domain name",
 		"your numerical IP address",
 		hasAnalytics ? "the pages you view and the files you request" : void 0,
 		hasAnalytics ? "the type of browser and operating system you use" : void 0,
-		hasAnalytics ? "the address of the site that referred you" : void 0
+		hasAnalytics ? "the address of the site that referred you" : void 0,
+		hasSessionReplay ? "a recording of how you interacted with a page, including mouse movement, scrolling and clicks" : void 0
 	]);
 	const techInfoPurposes = uniq([
 		hasAnalytics ? "measure the performance of our Site" : void 0,
+		hasSessionReplay ? "see where visitors encounter difficulty using our Site" : void 0,
 		site.security?.turnstile?.siteKey ? "protect our Site and its forms from automated abuse" : void 0,
 		"better understand how visitors use our Site",
 		"improve our Site to better meet your needs"
@@ -3351,11 +3857,13 @@ function derivePolicyVars(site) {
 		"your IP address",
 		"the type of web browser and operating system used",
 		"the pages of the Site visited",
-		ab?.enabled ? "which version of a page you were shown" : void 0
+		ab?.enabled ? "which version of a page you were shown" : void 0,
+		hasSessionReplay ? "how you moved through and interacted with a page" : void 0
 	]);
 	const cookiePurposes = uniq([
 		"keep the Site functioning as you move between pages",
 		hasAnalytics ? "understand how our Site is used, in aggregate" : void 0,
+		hasSessionReplay ? "recognise a returning visit as part of the same session" : void 0,
 		ab?.enabled ? "keep you on a consistent version of the Site between visits" : void 0,
 		site.security?.turnstile?.siteKey ? "distinguish visitors from automated traffic" : void 0
 	]);
@@ -3980,6 +4488,118 @@ function generateLegal(site, opts = {}) {
 	return out;
 }
 
+//#endregion
+//#region src/icons-sprite.ts
+/**
+* Build an SVG sprite from an icon `include` map.
+*
+* This is the delivery path for consumers that cannot run an icon integration:
+* Bricks/WordPress, EmDash's renderers, anything rendering HTML outside an Astro
+* build. Markup is `<svg><use href="…/icons.svg#ph--caret-down"/></svg>` — no
+* runtime JS and no network call, which is what keeps it inside the tier rules
+* (a runtime-fetching element would be behaviour JS with no fallback to enhance).
+*
+* The icon DATA comes from the `@iconify-json/*` collections, which stay optional
+* peers loaded dynamically: `@iconify-json/ph` alone is ~4.5 MB and the semantic
+* map spans five sets, so depending on them directly would be indefensible for
+* every consumer who never asks for a sprite.
+*/
+/**
+* `ph:caret-down` → `ph--caret-down`.
+*
+* The one place this grammar lives. `Icon.astro` mirrors it and `icon.test.ts`
+* guards the pair, because a drift here resolves `<use>` to nothing and renders
+* as an empty box rather than an error.
+*/
+function spriteId(qualified) {
+	return qualified.replace(":", "--");
+}
+/**
+* Default loader: the collection JSON shipped by `@iconify-json/<prefix>`.
+*
+* Resolved through a `createRequire` rooted at the consumer's directory, then
+* imported by absolute path — a bare specifier would resolve against this
+* package instead, where the collections deliberately aren't installed.
+*/
+async function loadCollection(prefix, from) {
+	try {
+		const mod = await import(pathToFileURL(createRequire(pathToFileURL(join(from, "noop.js"))).resolve(`@iconify-json/${prefix}/icons.json`)).href, { with: { type: "json" } });
+		return mod.default ?? mod;
+	} catch {
+		return null;
+	}
+}
+async function buildIconSprite(o) {
+	const from = o.resolveFrom ?? process.cwd();
+	const load = o.loadSet ?? ((prefix) => loadCollection(prefix, from));
+	const symbols = [];
+	const ids = [];
+	const missing = [];
+	/** qualified name → its rendered body+viewBox, so an alias can reuse it. */
+	const rendered = /* @__PURE__ */ new Map();
+	for (const [prefix, names] of Object.entries(o.include)) {
+		if (!names?.length) continue;
+		const set = await load(prefix);
+		if (!set) throw new Error(`[vitops icons] Cannot build the sprite: the "${prefix}" icon set is not installed. Run \`pnpm add -D @iconify-json/${prefix}\`, or drop it from your icons config.`);
+		for (const name of names) {
+			const data = getIconData(set, name);
+			if (!data) {
+				missing.push(`${prefix}:${name}`);
+				continue;
+			}
+			const built = iconToSVG(data, { height: "none" });
+			const body = replaceIDs(built.body);
+			const id = spriteId(`${prefix}:${name}`);
+			rendered.set(`${prefix}:${name}`, {
+				viewBox: built.attributes.viewBox,
+				body
+			});
+			ids.push(id);
+			symbols.push(`<symbol id="${id}" viewBox="${built.attributes.viewBox}">${body}</symbol>`);
+		}
+	}
+	for (const [alias, target] of Object.entries(o.aliases ?? {})) {
+		const hit = rendered.get(target);
+		if (!hit) {
+			missing.push(`${target} (aliased as ${alias})`);
+			continue;
+		}
+		ids.push(alias);
+		symbols.push(`<symbol id="${alias}" viewBox="${hit.viewBox}">${hit.body}</symbol>`);
+	}
+	return {
+		svg: `<svg xmlns="http://www.w3.org/2000/svg" style="display:none" aria-hidden="true">` + symbols.join("") + `</svg>\n`,
+		ids,
+		missing
+	};
+}
+/**
+* One icon's renderable parts, for inlining into markup.
+*
+* Exists because `<Icon />` cannot go through astro-icon: its `./components`
+* entry is a TypeScript file that Vite must transform, so it can only be
+* reached by a statically-analysable import — and a static import is exactly
+* what made the optional peer mandatory for anyone rendering Popover, Details
+* or Drawer. Reading the collection directly sidesteps the peer entirely and
+* shares this file's loader with the sprite, so both paths draw the same glyph.
+*/
+async function loadIconSvg(qualified, opts) {
+	const i = qualified.indexOf(":");
+	if (i <= 0) return null;
+	const prefix = qualified.slice(0, i);
+	const name = qualified.slice(i + 1);
+	const from = opts?.resolveFrom ?? process.cwd();
+	const set = await (opts?.loadSet ?? ((p) => loadCollection(p, from)))(prefix);
+	if (!set) return null;
+	const data = getIconData(set, name);
+	if (!data) return null;
+	const built = iconToSVG(data, { height: "none" });
+	return {
+		viewBox: built.attributes.viewBox,
+		body: replaceIDs(built.body)
+	};
+}
+
 //#endregion
 //#region src/generate.ts
 /**
@@ -4026,6 +4646,47 @@ const targetOf = (key) => {
 	return i === -1 ? key : key.slice(0, i);
 };
 /**
+* The framework's container breakpoints. `sm-`/`md-`/`lg-`/`xl-` prefixes in the
+* css/bricks formats; `@sm:`/`@md:`/… in tailwind, where they are registered as
+* `--container-*` in `@theme` and Tailwind expands the variants itself.
+*/
+const BREAKPOINTS = [
+	["sm", "30rem"],
+	["md", "48rem"],
+	["lg", "64rem"],
+	["xl", "80rem"]
+];
+/**
+* Gap utilities over the space scale, emitted from one list into all three
+* formats — same arrangement as `roleColorUtilities`, for the same reason.
+*
+* These did not exist. `vitops docs css` advertised a `g` class that was never
+* emitted, so the honest answer for a css/bricks consumer was an inline
+* `style="gap: …"`, which is what this repo's own `index.html` does throughout.
+* Tailwind does not fill the hole either: the fluid space steps are deliberately
+* kept OUT of Tailwind's `--spacing-*` namespace (named keys there shadow the
+* size scales — `max-w-7xl` would resolve to `var(--spacing-7xl)`), so `gap-md`
+* is not something Tailwind can derive on its own. Measured against
+* tailwindcss@4.3.3: an explicit `@utility gap-md` is honoured, coexists with
+* the built-in numeric `gap-4`, and picks up variants (`@md:gap-md`).
+*
+* The whole matrix is emitted rather than a useful-looking subset: an undefined
+* step produces no rule and no error in either format, so a missing
+* `md-gap-x-2xl` would be indistinguishable from a working one.
+*/
+function gapUtilities(steps) {
+	const FAMILIES = [
+		["gap", "gap"],
+		["gap-x", "column-gap"],
+		["gap-y", "row-gap"]
+	];
+	return steps.flatMap(({ name }) => FAMILIES.map(([prefix, prop]) => ({
+		cls: `${prefix}-${name}`,
+		prop,
+		value: `var(--space-${name})`
+	})));
+}
+/**
 * Every role colour utility, each class name emitted EXACTLY once.
 *
 * There is now a single axis. The target lives *inside* the token name, so
@@ -4104,6 +4765,23 @@ const TYPO_KEYMAP = {
 	"text-wrap": ["text-wrap", "tw"],
 	color: ["color", "color"]
 };
+/**
+* Wrong spellings worth naming explicitly, because each is a plausible reading of
+* the key it isn't. `transform`/`decoration` were documented in the schema for a
+* while and shipped title-case navigation to production; `letter-spacing` and
+* `font-*` are the natural guesses for keys we chose to shorten.
+*/
+const ALSO_MEANT = {
+	transform: "text-transform",
+	decoration: "text-decoration",
+	"letter-spacing": "tracking",
+	wrap: "text-wrap",
+	"font-family": "family",
+	"font-size": "size",
+	"font-weight": "weight",
+	"font-style": "style",
+	lineHeight: "line-height"
+};
 const TYPO_IDENTITY = {
 	"font-style": "normal",
 	"letter-spacing": "normal",
@@ -4126,10 +4804,11 @@ const STATE_DEFAULT = {
 	saturate: "1",
 	sepia: "0",
 	"hue-rotate": "0deg",
-	clip: "none"
+	clip: "none",
+	height: "auto"
 };
 const id = (key) => createHash("sha256").update(key).digest("hex").slice(0, 6);
-function build(ds, format, assetsDir) {
+function build(ds, format, assetsDir, buildOpts = {}) {
 	const BRICKS = format === "bricks";
 	const expandedPalette = expandPalette(ds.colors.palette);
 	const roleMap = ds.colors.roles;
@@ -4143,6 +4822,10 @@ function build(ds, format, assetsDir) {
 	const surfaceRole = scaleRoles.find((r) => r.role === "surface");
 	const focusRole = scaleRoles.find((r) => r.role === "ui-primary") ?? scaleRoles[0];
 	for (const w of ladderWarnings(expandedPalette)) console.warn(`[vitops] ${w}`);
+	{
+		const errors = monotonicityErrors(expandedPalette);
+		if (errors.length) throw new Error(errors.join("\n"));
+	}
 	{
 		const numericOf = (hueName) => expandedPalette[hueName]?.numeric ?? {};
 		const resolve = (val) => {
@@ -4206,6 +4889,9 @@ function build(ds, format, assetsDir) {
 			if (fb) {
 				css += `/* Functional role tokens (dark) */\n`;
 				css += `${DARK_SEL} {\n  color-scheme: dark;\n${fb}}\n\n`;
+				if (buildOpts.systemColorScheme) css += `/* Functional role tokens (dark) — OS preference, no explicit choice */
+@media (prefers-color-scheme: dark) {
+  ${SYSTEM_DARK_SEL} {\n    color-scheme: dark;\n${fb.replace(/^ {2}/gm, "    ")}  }\n}\n\n`;
 			}
 		}
 		css += `/* Colour utilities — ${UTILITIES.join(", ")} */\n`;
@@ -4231,6 +4917,14 @@ function build(ds, format, assetsDir) {
 	const spaceSteps = ds.spaceScale ? buildScale(ds.spaceScale) : [];
 	const textMax = Object.fromEntries(typeSteps.map((s) => [`text-${s.name}`, s.max]));
 	const typographyFamilies = typography?.families ?? {};
+	{
+		const known = new Set(Object.keys(TYPO_KEYMAP));
+		for (const [role, spec] of Object.entries(typography?.roles ?? {})) for (const key of Object.keys(spec)) {
+			if (known.has(key)) continue;
+			const near = ALSO_MEANT[key];
+			console.warn(`[vitops] typography.roles.${role}: unknown key "${key}" — ignored` + (near ? `. Did you mean "${near}"?` : `. Recognised: ${[...known].join(", ")}.`));
+		}
+	}
 	const withScaleFallback = (v) => v.replace(/var\(\s*(--text-[\w-]+)\s*\)/g, (m, name) => textMax[name.slice(2)] ? `var(${name}, ${textMax[name.slice(2)]})` : m);
 	const roleDecls = (role, spec) => {
 		const out = {};
@@ -4248,10 +4942,26 @@ function build(ds, format, assetsDir) {
 		for (const [name, stack] of Object.entries(ds.fonts ?? {})) root[`--font-${name}`] = stack;
 		for (const s of typeSteps) root[`--text-${s.name}`] = s.value;
 		for (const s of spaceSteps) root[`--space-${s.name}`] = s.value;
-		const css = `/* GENERATED font families + fluid type/space scales — do not edit by hand. */\n:root {\n${decls(root)}\n}\n`;
+		const css = `/* GENERATED font families + fluid type/space scales — do not edit by hand.
+   --font-* are STACKS ONLY; no @font-face is emitted here. Load webfonts with
+   Astro's fonts: config and point the token at the family's cssVariable. */
+:root {\n${decls(root)}\n}\n`;
 		twTypeTokensCss = css;
 		generated["type-tokens.css"] = css;
 	}
+	{
+		const gaps = gapUtilities(spaceSteps);
+		let sp = `/* GENERATED gap utilities — do not edit by hand. */\n`;
+		if (gaps.length) {
+			for (const { cls, prop, value } of gaps) sp += `.${cls} { ${prop}: ${value}; }\n`;
+			for (const [bp, width] of BREAKPOINTS) {
+				sp += `\n@container (min-width: ${width}) {\n`;
+				for (const { cls, prop, value } of gaps) sp += `  .${bp}-${cls} { ${prop}: ${value}; }\n`;
+				sp += `}\n`;
+			}
+		}
+		generated["spacing.css"] = sp;
+	}
 	let twPatternTokensCss = "";
 	{
 		const tDefaults = patterns?.defaults ?? {};
@@ -4286,7 +4996,6 @@ function build(ds, format, assetsDir) {
 		generated["typography.css"] = typo;
 	}
 	const stateRules = (sel, role, states, colorProp = "background-color") => {
-		const sels = Array.isArray(sel) ? sel : [sel];
 		let out = "";
 		for (const [state, spec] of Object.entries(states)) {
 			const body = [];
@@ -4304,8 +5013,7 @@ function build(ds, format, assetsDir) {
 			}
 			if (spec.css && typeof spec.css === "object") for (const [k, v] of Object.entries(spec.css)) body.push(`${k}: ${v};`);
 			if (!body.length) continue;
-			const pseudo = state === "hover" ? ":hover" : state === "active" ? ":active" : state === "focus-visible" ? ":focus-visible" : `:${state}`;
-			const rule = `${sels.map((s) => `${s}${pseudo}`).join(",\n")} {\n  ${body.join("\n  ")}\n}\n`;
+			const rule = `${sel(state === "hover" ? ":hover" : state === "active" ? ":active" : state === "focus-visible" ? ":focus-visible" : `:${state}`).join(",\n")} {\n  ${body.join("\n  ")}\n}\n`;
 			out += state === "hover" ? `@media (hover: hover) {\n${rule}}\n` : rule;
 		}
 		return out;
@@ -4316,8 +5024,9 @@ function build(ds, format, assetsDir) {
 		if (!p.base) continue;
 		const states = p.states ?? {};
 		const cls = p.class ?? (p.element ? void 0 : pname);
-		const elementSel = (extra = "") => `:where(${[p.element, cls && `.${cls}`].filter(Boolean).join(", ")})${extra}`;
+		const elementSel = (extra = "", pseudo = "") => `:where(${[p.element, cls && `.${cls}`].filter(Boolean).map((s) => `${s}${pseudo}`).join(", ")})${extra}`;
 		const defaultSel = p.element ? elementSel() : `.${cls}`;
+		const defaultSelFor = (pseudo) => p.element ? [elementSel("", pseudo)] : [`.${cls}${pseudo}`];
 		const defaultRole = p.default_role ?? null;
 		const base = { ...p.base };
 		const fills = p.fill ?? (pname === "button" || pname === "badge" || base["background-color"] != null || base["background"] != null);
@@ -4336,12 +5045,13 @@ function build(ds, format, assetsDir) {
 			wrappedBase[prop] = sfx ? `var(--${sfx}-${pname}, ${val})` : String(val);
 		}
 		pat += decls(wrappedBase) + "\n}\n";
-		pat += stateRules(defaultSel, defaultRole, states, colorProp);
+		pat += stateRules(defaultSelFor, defaultRole, states, colorProp);
 		for (const role of p.roles ?? []) {
-			const variantSels = p.element ? [elementSel(`.${role}`), ...cls ? [`.${cls}-${role}`] : []] : [`.${cls}-${role}`];
+			const variantSelsFor = (pseudo) => p.element ? [elementSel(`.${role}`, pseudo), ...cls ? [`.${cls}-${role}${pseudo}`] : []] : [`.${cls}-${role}${pseudo}`];
+			const variantSels = variantSelsFor("");
 			const variantColorDecl = fills ? `background-color: var(--color-bg-${role}-solid); color: var(--color-text-on-${role})` : `color: var(--color-text-${role})`;
 			pat += `${variantSels.join(",\n")} { ${variantColorDecl}; }\n`;
-			pat += stateRules(variantSels, role, states, colorProp);
+			pat += stateRules(variantSelsFor, role, states, colorProp);
 		}
 		pat += "\n";
 	}
@@ -4361,25 +5071,25 @@ function build(ds, format, assetsDir) {
 		for (const parts of anim.journeys?.compose ?? []) {
 			const d = {
 				"--_anim": parts.map((p) => `${p}-journey`).join(", "),
-				"animation-range": "entry exit"
+				"animation-range": "entry calc(50% + 10vh) exit 100%"
 			};
 			for (const p of parts) for (const [k, v] of Object.entries(base[p] ?? {})) d[`--${k}`] = asStr(v);
 			out += block(`${parts.join("-")}-journey`, d);
 		}
 		const STATES = [
-			["hover", (s) => `.${s}:hover`],
-			["focus", (s) => `.${s}:focus-visible`],
+			["hover", (s) => `.${s}:hover, :hover > .${s}`],
+			["focus", (s) => `.${s}:focus-visible, :focus-within > .${s}`],
 			["active", (s) => `.${s}.is-active, .${s}[data-active]`]
 		];
 		out += `\n/* State-flip variants — compose with .transition (hover-/focus-/active-<fx>). */\n`;
 		for (const [name, e] of Object.entries(anim.effects ?? {})) {
-			if (e.kf !== "composite" && e.kf !== "paint") continue;
 			const props = {};
 			for (const [k, v] of Object.entries(e.vars ?? {})) {
 				const m = /^(.*)-(from|to)$/.exec(k);
 				if (m) (props[m[1]] ??= {})[m[2]] = asStr(v);
 			}
 			const rest = {};
+			for (const [k, v] of Object.entries(e.css ?? {})) rest[k] = asStr(v);
 			for (const [p, ft] of Object.entries(props)) {
 				if (ft.from != null && ft.from !== STATE_DEFAULT[p]) rest[`--${p}-from`] = ft.from;
 				if (ft.to != null && ft.to !== STATE_DEFAULT[p]) rest[`--${p}-to`] = ft.to;
@@ -4602,7 +5312,8 @@ function build(ds, format, assetsDir) {
 			twPatternTokensCss,
 			patternsCss: pat,
 			assetsDir,
-			utilities: UTILITIES
+			utilities: UTILITIES,
+			systemColorScheme: buildOpts.systemColorScheme === true
 		}),
 		designMd: format !== "design" ? "" : emitDesignMd({
 			ds,
@@ -4621,24 +5332,19 @@ function emitTailwind(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.\n   Class reference: npx vitops docs classes  ·  All topics: npx vitops docs */"];
+	const parts = ["/* GENERATED for Tailwind v4 (Astro) — do not edit by hand.\n   Class reference: npx vitops docs classes  ·  All topics: npx vitops docs\n   Fonts below are STACKS ONLY — this file loads no webfonts. Load them with\n   Astro's fonts: config and point the token at the family's cssVariable. */"];
 	parts.push(`@import "tailwindcss";\n`);
 	const theme = [];
 	theme.push(`  /* Hue scales → bg-<hue>-<step> text-* border-* (numeric, 50…950) */`);
 	for (const [name, hue] of Object.entries(expandedPalette)) for (const [n, hex] of Object.entries(hue.numeric)) theme.push(`  --color-${name}-${n}: ${hex};`);
-	theme.push(`\n  /* Fonts → font-* */`);
+	theme.push(`\n  /* Fonts → font-* (stacks only; no @font-face is emitted — see header) */`);
 	for (const [name, stack] of Object.entries(ds.fonts ?? {})) theme.push(`  --font-${name}: ${stack};`);
 	theme.push(`\n  /* Fluid type scale → text-* */`);
 	for (const s of typeSteps) theme.push(`  --text-${s.name}: ${s.value};`);
 	theme.push(`\n  /* Drop-shadows → shadow-* */`);
 	for (const [name, value] of Object.entries(shadows ?? {})) theme.push(`  --shadow-${name}: ${value};`);
 	theme.push(`\n  /* Container breakpoints → @sm:/@md:/@lg:/@xl: */`);
-	for (const [name, val] of [
-		["sm", "30rem"],
-		["md", "48rem"],
-		["lg", "64rem"],
-		["xl", "80rem"]
-	]) theme.push(`  --container-${name}: ${val};`);
+	for (const [name, val] of BREAKPOINTS) theme.push(`  --container-${name}: ${val};`);
 	parts.push(`@theme {\n${theme.join("\n")}\n}\n`);
 	if (spaceSteps.length) parts.push(`/* Fluid space scale — var(--space-<name>) or p-(--space-<name>) */\n:root {\n` + spaceSteps.map((s) => `  --space-${s.name}: ${s.value};`).join("\n") + `\n}\n`);
 	if (scaleRoles.length) {
@@ -4660,8 +5366,16 @@ function emitTailwind(ctx) {
 		const surface = scaleRoles.find((r) => r.role === "surface");
 		if (surface) darkBlock += `  --overlay: color-mix(in oklch, var(--color-${surface.hue}-950) 60%, transparent);\n`;
 	}
-	if (darkBlock) parts.push(`/* Functional role tokens (dark) */\n${DARK_SEL} {\n  color-scheme: dark;\n${darkBlock}}\n`);
+	if (darkBlock) {
+		parts.push(`/* Functional role tokens (dark) */\n${DARK_SEL} {\n  color-scheme: dark;\n${darkBlock}}\n`);
+		if (ctx.systemColorScheme) parts.push(`/* Functional role tokens (dark) — OS preference, no explicit choice */\n@media (prefers-color-scheme: dark) {\n  ${SYSTEM_DARK_SEL} {\n    color-scheme: dark;\n${darkBlock.replace(/^ {2}/gm, "    ")}  }\n}\n`);
+	}
 	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 roles = typography?.roles ?? {};
+		const bindings = Object.entries(typography?.headings ?? {}).filter(([, r]) => roles[r]);
+		if (bindings.length) parts.push(`/* Bare-element type roles (typography.headings) */\n@layer base {\n` + bindings.map(([tag, role]) => `  ${tag} {\n${decls(roleDecls(role, roles[role]), "    ")}\n  }`).join("\n") + `\n}\n`);
+	}
 	const util = [];
 	if (scaleRoles.length) {
 		util.push(`/* Role colour utilities (the public API) */`);
@@ -4677,7 +5391,6 @@ function emitTailwind(ctx) {
 		for (const [k, v] of Object.entries(e.css ?? {})) d[k] = asStr(v);
 		for (const [k, v] of Object.entries(e.vars ?? {})) d[`--${k}`] = asStr(v);
 		util.push(`@utility ${name} {\n${decls(d)}\n}`);
-		if (e.kf !== "composite" && e.kf !== "paint") continue;
 		const props = /* @__PURE__ */ new Set();
 		for (const k of Object.keys(e.vars ?? {})) {
 			const m = /^(.*)-(from|to)$/.exec(k);
@@ -4687,7 +5400,7 @@ function emitTailwind(ctx) {
 		util.push(`@utility flip-${name} {\n${decls(flip)}\n}`);
 	}
 	util.push(`\n/* Split — internal fractions (pair split with a ratio) */`);
-	util.push("@utility split {\n  display: flex;\n  & > * { flex: 1; }\n  & > :first-child { flex: var(--_split-a, 1); }\n  & > :last-child { flex: var(--_split-b, 1); }\n}");
+	util.push(`@utility split-reverse {\n  reading-flow: flex-visual;\n  & > :first-child { order: 1; }\n}`);
 	for (const [a, b] of [
 		[1, 2],
 		[2, 1],
@@ -4697,7 +5410,12 @@ function emitTailwind(ctx) {
 		[4, 1],
 		[2, 3],
 		[3, 2]
-	]) util.push(`@utility split-${a}-${b} {\n  --_split-a: ${a};\n  --_split-b: ${b};\n}`);
+	]) util.push(`@utility split-${a}-${b} {\n  flex-direction: row;\n  --_split-a: ${a};\n  --_split-b: ${b};\n}`);
+	const gaps = gapUtilities(spaceSteps);
+	if (gaps.length) {
+		util.push(`\n/* Gap — the fluid space scale (var(--space-<name>)) */`);
+		for (const { cls, prop, value } of gaps) util.push(`@utility ${cls} {\n  ${prop}: ${value};\n}`);
+	}
 	util.push(`\n/* Track placement (inside .centered) */`);
 	for (const track of [
 		"measure",
@@ -4705,6 +5423,28 @@ function emitTailwind(ctx) {
 		"spotlight",
 		"fullbleed"
 	]) util.push(`@utility ${track} {\n  grid-column: ${track};\n}`);
+	util.push(`\n/* Auto-fit grid — column count is content-driven, unlike .split */`);
+	util.push("@utility grid-auto {\n  display: grid;\n  gap: var(--grid-gap, 1rem);\n  grid-template-columns: repeat(auto-fit, minmax(var(--grid-min, 13rem), 1fr));\n  &:is(ul, ol) > li + li { margin-block-start: 0; }\n}");
+	util.push(`\n/* Vertical-rhythm overrides (mirrors layout.css) */`);
+	for (const pair of [
+		"h-p",
+		"p-p",
+		"p-h",
+		"h-h",
+		"p-list",
+		"list-p",
+		"li-li",
+		"text-media",
+		"media-text"
+	]) util.push(`@utility m-${pair} {\n  margin-top: calc(var(--rhythm-base) * var(--rhythm-${pair}));\n}`);
+	for (const [name, mult] of [
+		["0", null],
+		["xs", "0.25"],
+		["s", "0.5"],
+		["m", "1"],
+		["l", "1.5"],
+		["xl", "2"]
+	]) util.push(`@utility m-${name} {\n  margin-top: ${mult == null ? "0" : `calc(var(--rhythm-base) * ${mult})`};\n}`);
 	parts.push(util.join("\n") + "\n");
 	parts.push(`/* ── Structure (mirrors src/css/layout.css) ── */
 :root {
@@ -4727,6 +5467,11 @@ function emitTailwind(ctx) {
 
 body {
   container-type: inline-size;
+  /* Named so \`patterns/scroll-target.css\`'s \`@container body (…)\` queries
+     resolve — .toc-layout/.toc-sidebar/.toc-inline. Those partials are inlined
+     into this bundle verbatim, so dropping the name (as this literal did) left
+     the TOC permanently in its narrow layout in the tailwind format only. */
+  container-name: body;
 }
 
 /* Class-level structure rules live in \`components\` so track/spacing utilities
@@ -4791,6 +5536,39 @@ body {
     var(--region-space-max, 8rem)
   );
 }
+
+/* \`.split\` is a PATTERN, so it belongs here rather than in an \`@utility\` — that
+   is what makes \`flex-col\` beat it by layer instead of by a source-order race
+   whose winner depends on Tailwind's property-based sort of custom utilities.
+   Its ratio/reversal modifiers stay utilities. Mirrors layout.css, where each
+   rule's rationale is written out; in short: \`min-inline-size: 0\` because a flex
+   item's automatic minimum is its min-content size; the ratio as a flex BASIS
+   rather than a grow factor, because grow shares out only the free space and a
+   child's padding is not part of it; scoped to a two-child split because a ratio
+   is a pair contract and a middle child with no basis would collapse to zero;
+   \`box-sizing: border-box\` because a basis only sizes the border box on a
+   border-box item (Tailwind's preflight sets it, the other formats' reset does). */
+.split {
+  display: flex;
+  flex-direction: row;
+}
+.split > * {
+  flex: 1;
+  box-sizing: border-box;
+  min-inline-size: 0;
+}
+.split > :first-child {
+  flex-grow: var(--_split-a, 1);
+}
+.split > :last-child {
+  flex-grow: var(--_split-b, 1);
+}
+.split > :first-child:nth-last-child(2) {
+  flex-basis: ${splitBasis("--_split-a")};
+}
+.split > :nth-child(2):last-child {
+  flex-basis: ${splitBasis("--_split-b")};
+}
 }
 `);
 	const animPath = join(cssDir, "animation.css");
@@ -4854,9 +5632,9 @@ body {
 				if (depth === 0) {
 					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);
+					const name = /^\.([A-Za-z0-9_-]+)/.exec(prelude)?.[1];
 					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 (name && TW_CLASH.has(name) && !CLASH_KEEP.has(name)) droppedClashes.add(name);
 					else if (raw) kept.push(raw);
 					start = i + 1;
 				}
@@ -4871,25 +5649,60 @@ body {
 	return nl(parts) + "\n";
 }
 /**
+* Partials the tailwind format does NOT inline, because it re-creates them by
+* hand: the engine (`global.css` — Tailwind's preflight covers the reset;
+* `animation.css` — read directly and wrapped in `@layer components`), and the
+* two layout partials, whose utilities are re-emitted as `@utility` and whose
+* structure is re-emitted in the `@layer components` literal.
+*
+* **Every partial mapped to `vitops.utilities` must be listed here.** Inlining a
+* utility family lands it in tailwind's `@layer components`, the exact inversion
+* the layer split exists to remove — and it fails SILENTLY, because each of those
+* classes already exists as an `@utility` that wins on layer anyway. You would get
+* ~30 dead rules and no test failure. `format-parity.test.ts` asserts the
+* implication structurally rather than spot-checking the output.
+*
+* The implication is one-way: `layout.css` is skipped while sitting in
+* `vitops.components`, because its structure is re-emitted by hand.
+*/
+/**
+* Framework COMPONENTS whose class name collides with a Tailwind utility, and
+* which must therefore survive the `TW_CLASH` strip.
+*
+* The clash test matches a rule's leading `.<name>`, which is right for a
+* single-purpose utility (Tailwind ships its own) and wrong for a pattern that
+* merely shares the name. `patterns/sticky.css` opens `.sticky { … }` and was
+* being deleted from the tailwind bundle WHOLESALE — the `--_sticky-offset`
+* wiring, the z-index, and every `&.sticky--bottom`/`--inline-start` variant —
+* so a consumer writing `class="sticky sticky--bottom"` got bare
+* `position: sticky` and nothing else.
+*
+* `table` is here for the same reason but was never actually hit: `table.css`'s
+* prelude is `table,\n.table`, which doesn't start with `.`, so the regex missed
+* it by luck. Listing it makes that explicit rather than accidental.
+*/
+const CLASH_KEEP = new Set(["sticky", "table"]);
+const TAILWIND_SKIP = new Set([
+	"global.css",
+	"animation.css",
+	"layout.css",
+	"layout-utilities.css",
+	"utilities.css"
+]);
+/**
 * The component/structural CSS partials to inline into the Tailwind bundle, in
-* index.css cascade order. Everything the aggregator imports EXCEPT the engine
-* (global/animation), the layout utilities (Tailwind owns them), and the generated
-* token layer (Tailwind builds its own via @theme).
+* index.css cascade order. Everything the aggregator imports EXCEPT `TAILWIND_SKIP`
+* and the generated token layer (Tailwind builds its own via @theme).
 */
 function componentPartialOrder(cssDir) {
 	const indexPath = join(cssDir, "index.css");
-	const skip = new Set([
-		"global.css",
-		"animation.css",
-		"layout.css"
-	]);
 	const order = [];
 	const seen = /* @__PURE__ */ new Set();
 	const text = existsSync(indexPath) ? readFileSync(indexPath, "utf8") : "";
 	for (const m of text.matchAll(/@import\s+['"]\.\/([^'"]+)['"]/g)) {
 		const rel = m[1];
 		if (rel.startsWith("generated/")) continue;
-		if (skip.has(rel)) continue;
+		if (TAILWIND_SKIP.has(rel)) continue;
 		if (!seen.has(rel) && existsSync(join(cssDir, rel))) {
 			seen.add(rel);
 			order.push(rel);
@@ -4939,9 +5752,21 @@ const CHUNK_LAYER = {
 	"generated/shadows.css": "vitops.utilities",
 	"generated/typography.css": "vitops.utilities",
 	"generated/animation-effects.css": "vitops.utilities",
+	"generated/spacing.css": "vitops.utilities",
+	"layout-utilities.css": "vitops.utilities",
 	"utilities.css": "vitops.utilities"
 };
 /**
+* A `.split` child's flex basis. The ratio is a BASIS rather than a grow factor
+* because grow shares out only the FREE space, which a child's padding is not
+* part of — so a padded column came out wider than its sibling by exactly its
+* horizontal padding. Must stay character-identical to layout.css; the parity
+* suite matches this expression against both.
+*/
+const splitBasis = (v) => `calc(var(${v}, 1) / (var(--_split-a, 1) + var(--_split-b, 1)) * 100%)`;
+/** The layer a partial's rules are wrapped in; unmapped partials are components. */
+const layerForPartial = (rel) => CHUNK_LAYER[rel] ?? "vitops.components";
+/**
 * 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
@@ -4970,7 +5795,7 @@ function bundleCss(generated, assetsDir, minify) {
 		const rel = m[1];
 		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}`);
+		chunks.push(`@layer ${layerForPartial(rel)} {\n${body}\n}`);
 	}
 	const merged = `/*! GENERATED by @getvitops/generator — do not edit by hand.
     Class reference: npx vitops docs classes  ·  All topics: npx vitops docs */
@@ -4986,21 +5811,39 @@ function bundleCss(generated, assetsDir, minify) {
 		map: res.map ? res.map.toString() : void 0
 	};
 }
-function loadConfig(input) {
-	const result = validate(typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input);
+/**
+* Read `input` as whichever config kind it is, and return the design system to
+* build from plus the site config if that is what it was.
+*
+* The design system is validated here rather than in `resolveInput` so the error
+* can name where it came from: a theme inside a site config reports its `themes`
+* path, which is the difference between "your config is wrong" and "your config
+* is wrong *here*" when the file is a few hundred lines of company facts.
+*/
+function loadInput(input, opts) {
+	const resolved = resolveInput(typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input, opts);
+	const result = validate(resolved.designSystem);
 	if (!result.ok) {
+		const where = resolved.theme != null ? `design system at designSystem.themes.${resolved.theme}` : "design-system.json";
 		const lines = result.errors.slice(0, 12).map((e) => `  • ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
-		throw new Error(`Invalid design-system.json:\n${lines}`);
+		throw new Error(`Invalid ${where}:\n${lines}`);
 	}
 	for (const w of result.warnings) console.warn(`[vitops] ${w}`);
-	return result.data;
+	return {
+		ds: result.data,
+		...resolved.site ? { site: resolved.site } : {}
+	};
 }
 async function generate(options) {
 	const format = options.format ?? "bricks";
 	const outDir = options.outDir ?? "dist";
 	const assetsDir = options.assetsDir ?? DEFAULT_ASSETS;
-	const ds = loadConfig(options.input);
-	const built = build(ds, format, assetsDir);
+	const { ds, site: embedded } = loadInput(options.input, {
+		...options.theme != null ? { theme: options.theme } : {},
+		...options.siteEnv != null ? { siteEnv: options.siteEnv } : {}
+	});
+	const site = options.site != null ? loadSiteConfigFile(options.site, options.siteEnv) : embedded;
+	const built = build(ds, format, assetsDir, { systemColorScheme: options.systemColorScheme ?? site?.designSystem?.defaultColorScheme === "system" });
 	mkdirSync(outDir, { recursive: true });
 	const written = [];
 	const put = (rel, content) => {
@@ -5039,9 +5882,30 @@ async function generate(options) {
 		const docs = generateDocs(ds, assetsDir);
 		for (const [rel, content] of Object.entries(docs)) put(join("docs", rel), content);
 	}
-	if (options.site != null && format !== "design") {
-		const legal = generateLegal(loadSiteConfigFile(options.site), { output: "html" });
+	if (site != null && format !== "design") {
+		const legal = generateLegal(site, { output: "html" });
 		for (const [name, content] of Object.entries(legal)) put(join("legal", name), content);
+		const icons = site.icons;
+		if (icons?.sprite) {
+			const { ui, brand, weight, semantic, sprite: _sprite, ...sets } = icons;
+			const include = generateIconInclude({
+				...ui ? { ui } : {},
+				...brand ? { brand } : {},
+				...weight ? { weight } : {},
+				...semantic ? { semantic } : {},
+				...sets
+			});
+			const aliases = {};
+			for (const name of semantic ?? []) try {
+				aliases[`icon-${name}`] = resolveIcon(name, ui ?? "fa7-solid", weight ? { weight } : {});
+			} catch {}
+			const built = await buildIconSprite({
+				include,
+				aliases
+			});
+			put("icons.svg", built.svg);
+			if (built.missing.length) console.warn(`[vitops] icons.sprite: ${built.missing.length} icon(s) were not found and are absent from the sprite: ${built.missing.join(", ")}.`);
+		}
 	}
 	return {
 		format,
@@ -5049,8 +5913,8 @@ async function generate(options) {
 		written
 	};
 }
-function loadSiteConfigFile(input) {
-	return resolveSiteConfig(typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input);
+function loadSiteConfigFile(input, siteEnv) {
+	return resolveSiteConfig(typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input, siteEnv);
 }
 
 //#endregion
@@ -5280,19 +6144,22 @@ function defaultConfig() {
 					size: "var(--text-3xl)",
 					weight: 700,
 					"line-height": "1.05",
-					tracking: "-0.03em"
+					tracking: "-0.03em",
+					"text-wrap": "balance"
 				},
 				heading: {
 					family: "display",
 					size: "var(--text-xl)",
 					weight: 600,
-					"line-height": "1.3"
+					"line-height": "1.3",
+					"text-wrap": "balance"
 				},
 				body: {
 					family: "sans",
 					size: "var(--text-m)",
 					weight: 400,
-					"line-height": "1.55"
+					"line-height": "1.55",
+					"text-wrap": "pretty"
 				}
 			},
 			headings: {
@@ -5316,7 +6183,7 @@ function defaultConfig() {
 			journeys: {
 				base: {
 					fade: { "opacity-from": 0 },
-					slide: {}
+					slide: { "translate-y-from": "var(--slide-distance, 2rem)" }
 				},
 				compose: [
 					["fade"],
@@ -5329,5 +6196,5 @@ function defaultConfig() {
 }
 
 //#endregion
-export { BASE_HOOK, CONTRAST, DARK_SEL, DOC_ORDER, DOC_SLUGS, DesignSystemSchema, JURISDICTIONS, KNOWN_PROCESSORS, NUMERIC_STEPS, REQUIRED_ROLES, ROLE_TOKEN_KEYS, SCHEMA_URL, SITE_SCHEMA_URL, SiteConfigSchema, TEMPLATES, TW_CLASH, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, jsonSchema, parseMarkdown, renderMarkdown, renderNodes, resolvePrivacyContact, resolveProcessors, resolveSiteConfig, resolveTheme, roleColorUtilities, roleHue, roleKind, siteJsonSchema, stripNulls, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateSite };
+export { BASE_HOOK, CONTRAST, DARK_SEL, DOC_ORDER, DOC_SLUGS, DesignSystemSchema, JURISDICTIONS, KNOWN_PROCESSORS, NUMERIC_STEPS, REQUIRED_ROLES, ROLE_TOKEN_KEYS, SCHEMA_URL, SITE_SCHEMA_URL, SiteConfigSchema, SiteFontSchema, TEMPLATES, TW_CLASH, buildIconSprite, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isSiteConfig, jsonSchema, loadIconSvg, parseMarkdown, renderMarkdown, renderNodes, resolveInput, resolvePrivacyContact, resolveProcessors, resolveSiteConfig, resolveTheme, roleColorUtilities, roleHue, roleKind, siteJsonSchema, spriteId, stripNulls, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateSite };
 //# sourceMappingURL=index.mjs.map