@getvitops/generator 0.3.0 → 0.5.0

package/dist/index.mjs

@@ -13,17 +13,25 @@ import { generateOklchPalette, hexToOklch, oklchStringToHex, pickOn } from "@get
 * Authored with `zod/mini` (tree-shakeable Zod v4). Everything else derives from it:
 *   • the `DesignSystem` TS type (`z.infer`), used throughout the generator,
 *   • the published JSON Schema (`toJSONSchema`), emitted to `schema.json` for `$schema` refs,
-*   • runtime validation (`validate`) for the CLI and to gate `generate`.
+*   • runtime validation (`validate`) for the CLI and to gate `generate`,
+*   • the generated `authoring.md` reference doc (walks `jsonSchema`'s descriptions).
 */
-const CssDecls = z.record(z.string(), z.string());
+/**
+* Attach a JSON-Schema `description`. zod/mini has no `.describe()` method; the
+* mini-API equivalent is `.check(z.describe(…))`, and `.check()` clones — so a
+* shared sub-schema (`Scale`, `CssDecls`, …) can carry a different description
+* per use-site without mutating the original.
+*/
+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 = z.object({
-	seed: z.string(),
-	anchors: z.optional(z.record(z.string(), z.string()))
-});
-const FixedRamp = z.object({ tones: z.union([z.array(z.string()), z.record(z.string(), z.string())]) });
-const Ramp = z.union([SeededRamp, FixedRamp]);
+const SeededRamp = desc(z.object({
+	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()) that pin specific steps of the generated scale; the remaining steps interpolate around them."))
+}), "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 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.");
 const UtilityName = z.enum([
 	"bg",
 	"text",
@@ -32,66 +40,66 @@ const UtilityName = z.enum([
 	"fill",
 	"stroke"
 ]);
-const Colors = z.object({
-	palette: z.record(z.string(), Ramp),
-	roles: z.record(z.string(), z.string()),
-	utilities: z.optional(z.array(UtilityName))
-});
+const Colors = desc(z.object({
+	palette: desc(z.record(z.string(), Ramp), "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`)."),
+	roles: desc(z.record(z.string(), z.string()), "Maps each semantic role (neutral, surface, ui-primary/secondary/accent, brand-primary/secondary, info, success, warning, danger) to the palette hue backing it. The generator derives every role's FUNCTIONAL tokens (`--<role>-{bg,bg-muted,border,border-bold,solid,solid-bold,on-solid,text,text-muted,text-x-muted}`) plus emphasis stops from the hue's scale, and dark mode flips automatically — there is no per-appearance scheme grammar."),
+	utilities: z.optional(desc(z.array(UtilityName), "Which colour utility-class families to emit (`bg-*`, `text-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, border."))
+}), "The colour system (the only required section): `palette` hues become generated OKLCH scales; `roles` map semantic roles onto those hues, from which all functional tokens and dark mode derive.");
 const Scale = z.object({
-	base: z.string(),
-	ratio: z.number(),
-	steps: z.optional(z.number()),
-	names: z.optional(z.array(z.string())),
-	baseStep: z.optional(z.number()),
-	baseline: z.optional(z.string()),
-	fluid: z.optional(z.object({
-		minVw: z.string(),
-		maxVw: z.string(),
-		minRatio: z.number()
-	}))
-});
-const Pattern = z.object({
-	group: z.optional(z.string()),
-	overrides: z.optional(CssDecls),
-	element: z.optional(z.string()),
-	class: z.optional(z.string()),
-	default_role: z.optional(z.string()),
-	base: z.optional(CssDecls),
-	states: z.optional(z.record(z.string(), z.record(z.string(), z.unknown()))),
-	roles: z.optional(z.array(z.string()))
-});
-const Patterns = z.object({
-	defaults: z.optional(CssDecls),
-	radii: z.optional(CssDecls),
-	groups: z.optional(z.record(z.string(), CssDecls)),
-	z: z.optional(z.record(z.string(), z.number())),
-	items: z.optional(z.record(z.string(), Pattern))
-});
-const TypographyRole = z.record(z.string(), Scalar);
-const Typography = z.object({
-	families: z.optional(z.record(z.string(), z.string())),
-	roles: z.optional(z.record(z.string(), TypographyRole)),
-	headings: z.optional(z.record(z.string(), z.string()))
-});
-const AnimEffect = z.object({
-	kf: z.string(),
-	css: z.optional(VarMap),
-	vars: z.optional(VarMap)
-});
-const Animations = z.object({
-	effects: z.optional(z.record(z.string(), AnimEffect)),
-	journeys: z.optional(z.object({
-		base: z.optional(z.record(z.string(), VarMap)),
-		compose: z.optional(z.array(z.array(z.string())))
-	}))
+	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({
+		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({
+	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)."),
+	class: desc(z.optional(z.string()), "Class name to emit (defaults to the pattern's key)."),
+	default_role: desc(z.optional(z.string()), "Semantic colour role applied to the bare/default variant."),
+	base: z.optional(desc(CssDecls, "Base CSS declarations. Geometry properties (padding, border-radius, border, box-shadow, font-size) are wrapped in per-pattern override hooks (`--p-<name>`, `--br-<name>`, `--b-<name>`, `--ds-<name>`, `--fs-<name>`) so consumers can restyle one pattern by setting one variable.")),
+	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 fills/text by n emphasis stops), `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({
+	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({
+	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 heading elements (h1…h6) to type roles so bare headings pick up role styling.")
+}), "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the heading-element → role mapping.");
+const AnimEffect = desc(z.object({
+	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({
+	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({
+		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({
-	$schema: z.optional(z.string()),
+	$schema: desc(z.optional(z.string()), "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation."),
 	colors: Colors,
-	shadows: z.optional(z.record(z.string(), z.string())),
-	fonts: z.optional(z.record(z.string(), z.string())),
-	typeScale: z.optional(Scale),
-	spaceScale: z.optional(Scale),
+	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), applied via `filter: drop-shadow(…)`."),
+	fonts: desc(z.optional(z.record(z.string(), z.string())), "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`)."),
+	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)
@@ -142,6 +150,89 @@ function validate(input) {
 	};
 }
 
+//#endregion
+//#region src/shared.ts
+/**
+* Data shared between the generator (`generate.ts`) and the docs bundle
+* (`docs.ts`). Lives in its own module because `generate.ts` imports `docs.ts` —
+* importing back the other way would be a cycle.
+*/
+/**
+* Pattern base geometry props → per-pattern override-hook shorthand. Each hook
+* wraps the authored value (`padding: var(--p-button, 0.6em 1.2em)`) so a
+* consumer restyles one pattern by setting one variable.
+*/
+const BASE_HOOK = {
+	padding: "p",
+	"border-radius": "br",
+	border: "b",
+	"box-shadow": "ds",
+	"font-size": "fs"
+};
+/**
+* Framework utility classes whose names collide with Tailwind's own defaults.
+* The `tailwind` format strips any rule targeting these — Tailwind provides
+* them, so consumers use Tailwind's utilities for these names instead.
+*/
+const TW_CLASH = new Set([
+	"block",
+	"inline",
+	"inline-block",
+	"flow-root",
+	"flex",
+	"inline-flex",
+	"grid",
+	"inline-grid",
+	"table",
+	"inline-table",
+	"table-caption",
+	"table-cell",
+	"table-row",
+	"contents",
+	"hidden",
+	"list-item",
+	"static",
+	"fixed",
+	"absolute",
+	"relative",
+	"sticky",
+	"isolate",
+	"visible",
+	"invisible",
+	"collapse",
+	"sr-only",
+	"not-sr-only",
+	"flex-row",
+	"flex-row-reverse",
+	"flex-col",
+	"flex-col-reverse",
+	"flex-wrap",
+	"flex-nowrap",
+	"items-start",
+	"items-end",
+	"items-center",
+	"items-baseline",
+	"items-stretch",
+	"justify-start",
+	"justify-end",
+	"justify-center",
+	"justify-between",
+	"justify-around",
+	"justify-evenly",
+	"content-start",
+	"content-end",
+	"content-center",
+	"content-between",
+	"content-around",
+	"content-evenly",
+	"text-left",
+	"text-center",
+	"text-right",
+	"text-justify",
+	"text-start",
+	"text-end"
+]);
+
 //#endregion
 //#region src/tokens.ts
 /**
@@ -822,6 +913,11 @@ This is a **rule reference**, not an exhaustive list: each family below is a nam
 plus the set of tokens it expands over. Applying a rule to any listed token yields a valid
 class (e.g. rule \`bg-<color>\` + colour \`pine-xl\` → \`bg-pine-xl\`).
 
+The tokens themselves are authored in \`design-system.json\` — see
+[/authoring.md](../authoring.md); the systems behind them are explained in
+[/concepts/](../concepts/index.md); per-format output differences (including which of
+these utilities Tailwind provides natively) in [/formats.md](../formats.md).
+
 ## Responsive & state variant grammar
 
 Every utility accepts a **container-breakpoint prefix**; animation utilities also accept a
@@ -911,7 +1007,9 @@ element; scroll-linked entrances resolve within the first portion of the element
 ## Component patterns
 
 Each pattern is a base class \`<pattern>\` with interaction states (hover/active/focus-visible)
-baked in; coloured patterns add role variants via rule **\`<pattern>-<role>\`**.
+baked in; coloured patterns add role variants via rule **\`<pattern>-<role>\`**. (How the
+pattern CSS is assembled — token cascade, \`--p-<pattern>\`-style override hooks, state
+shortcuts — is explained in [/concepts/patterns.md](../concepts/patterns.md).)
 
 - Patterns: ${code(patterns)}.
 - Roles (for coloured patterns like \`badge\`, \`tag\`, \`status\`, \`button\`):
@@ -920,6 +1018,368 @@ baked in; coloured patterns add role variants via rule **\`<pattern>-<role>\`**.
 - Shape primitives: \`--br-<name>\` radii — ${code(radii)}.
 `;
 }
+const isPrimitive = (n) => !n.properties && !n.anyOf && n.type != null && n.type !== "object" && n.type !== "array";
+function typeLabel(node) {
+	if (node.enum) return node.enum.map(String).join(" | ");
+	if (node.anyOf) return node.anyOf.every(isPrimitive) ? node.anyOf.map((v) => v.type).join(" | ") : "one of";
+	if (node.type === "array") {
+		const it = node.items;
+		if (it?.enum) return `array of ${it.enum.map(String).join(" | ")}`;
+		return it?.type && it.type !== "object" ? `array of ${it.type}` : "array";
+	}
+	if (node.type === "object") {
+		const ap = node.additionalProperties;
+		return ap && typeof ap === "object" ? "map" : "object";
+	}
+	return node.type ?? "value";
+}
+/** A node's documentable children: object properties, map values, or array items. */
+function childEntries(node) {
+	if (node.properties) {
+		const req = node.required ?? [];
+		return Object.entries(node.properties).map(([k, v]) => ({
+			label: k,
+			node: v,
+			required: req.includes(k)
+		}));
+	}
+	const ap = node.additionalProperties;
+	if (ap && typeof ap === "object" && (ap.description || ap.properties || ap.anyOf)) return [{
+		label: "<name>",
+		node: ap,
+		required: false
+	}];
+	if (node.items && (node.items.description || node.items.properties || node.items.anyOf)) return [{
+		label: "[items]",
+		node: node.items,
+		required: false
+	}];
+	return [];
+}
+function renderSchemaNode(label, node, required, depth, out) {
+	const indent = "  ".repeat(depth);
+	const meta = `(${typeLabel(node)}${required ? ", required" : ""})`;
+	out.push(`${indent}- \`${label}\` ${meta}${node.description ? ` — ${node.description}` : ""}`);
+	if (depth >= 3) return;
+	if (node.anyOf && !node.anyOf.every(isPrimitive)) {
+		for (const variant of node.anyOf) {
+			out.push(`${indent}  - *one of*${variant.description ? ` — ${variant.description}` : ""}`);
+			for (const c of childEntries(variant)) renderSchemaNode(c.label, c.node, c.required, depth + 2, out);
+		}
+		return;
+	}
+	for (const c of childEntries(node)) renderSchemaNode(c.label, c.node, c.required, depth + 1, out);
+}
+function renderAuthoring() {
+	const schema = jsonSchema;
+	const required = schema.required ?? [];
+	const sections = [];
+	for (const [key, node] of Object.entries(schema.properties ?? {})) {
+		if (key === "$schema") continue;
+		const parts = [`## \`${key}\`${required.includes(key) ? "" : " *(optional)*"}`];
+		if (node.description) parts.push("", node.description);
+		const bullets = [];
+		for (const c of childEntries(node)) renderSchemaNode(c.label, c.node, c.required, 0, bullets);
+		if (bullets.length) parts.push("", ...bullets);
+		sections.push(parts.join("\n"));
+	}
+	return `${frontmatter({
+		type: "Config Reference",
+		title: "Vitops — design-system.json authoring reference",
+		description: "Every field of the design-system.json config, generated from the published JSON Schema so it always matches validation.",
+		resource: DS_PATH,
+		tags: [
+			"config",
+			"schema",
+			"authoring",
+			"design-system"
+		]
+	})}
+
+# \`design-system.json\` authoring reference
+
+The single source of truth every output format is generated from. Each consumer authors
+their own config — there is no shared canonical token set. The field docs below are
+rendered from the published JSON Schema, so they always match what \`vitops validate\`
+enforces.
+
+- Set \`"$schema": "${SCHEMA_URL}"\` in the config for editor autocomplete + validation.
+- Scaffold a starter config with \`vitops init\`; check one with \`vitops validate\`.
+- 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).
+
+${sections.join("\n\n")}
+`;
+}
+function renderFormats(ds) {
+	const clashList = Array.from(TW_CLASH).sort();
+	const spaceName = ds.spaceScale?.baseline ?? ds.spaceScale?.names?.[0] ?? "m";
+	return `${frontmatter({
+		type: "Formats Reference",
+		title: "Vitops — output formats (tailwind vs css vs bricks)",
+		description: "What each vitops generate format emits, what the target platform provides instead, and the Tailwind-specific rules (which framework utilities are stripped in favour of Tailwind defaults).",
+		resource: DS_PATH,
+		tags: [
+			"formats",
+			"tailwind",
+			"bricks",
+			"css",
+			"design-system"
+		]
+	})}
+
+# Output formats — \`tailwind\` vs \`css\` vs \`bricks\`
+
+One config, three targets: \`vitops generate --format <tailwind|css|bricks>\`. The **class
+vocabulary is the same** everywhere (see [css/classes.md](css/classes.md)); what differs is
+which layers the generator emits versus which the platform provides, and the variant
+separator (\`-\` in CSS/Bricks, \`:\` / \`@\` in Tailwind).
+
+## \`tailwind\` — single-file Tailwind v4 layer
+
+Emits one self-contained \`tailwind.css\` (plus \`tokens.json\`): \`@import "tailwindcss"\`,
+\`@theme\` tokens, the framework's structural CSS + component patterns inlined, and
+\`@utility\` definitions for the bespoke families (type roles, animation effects,
+split ratios, track placement).
+
+**Use Tailwind's own utilities for these class names.** The framework's rules for them are
+deliberately stripped from the bundle because Tailwind provides them natively — writing
+them still works, but they are Tailwind's, not the framework's:
+
+${clashList.map((c) => `\`${c}\``).join(", ")}
+
+Other Tailwind-specific behaviour:
+
+- **Variants are Tailwind's job.** No pre-expanded breakpoint/state classes are emitted
+  (the framework's \`@container (min-width: …)\` variant blocks are dropped); use Tailwind
+  syntax — \`@md:split-1-2\`, \`hover:flip-fade-in\`. Container breakpoints are registered as
+  \`--container-{sm,md,lg,xl}\` = 30/48/64/80rem, backing the \`@sm:\`…\`@xl:\` variants.
+- **The space scale is NOT mapped into Tailwind's \`--spacing-*\` namespace** (that would
+  corrupt Tailwind's numeric multipliers and \`max-w-*\` sizes). Numeric utilities like
+  \`p-4\` keep Tailwind's 0.25rem meaning; use the design-system scale via arbitrary
+  values — \`p-(--space-${spaceName})\`, \`gap-(--space-${spaceName})\`.
+- **Functional colour roles are plain \`:root\` variables, not \`@theme\` colours**, so
+  Tailwind doesn't auto-derive utilities from them; the emitted \`@utility\` set
+  (\`bg-<role>\`, \`text-<role>-muted\`, …) is the public API. The raw hue scales ARE
+  \`@theme\` colours, so native \`bg-<hue>-500\`-style utilities work.
+
+## \`css\` — standalone bundle
+
+Emits a bundled, self-contained \`styles.css\` + \`tokens.json\` + \`design-manifest.json\`.
+The colour and font/scale layers are fully included, and every utility family is
+pre-expanded — including breakpoint/state variants with \`-\` separators
+(\`md-split-1-2\`, \`hover-fade-in\`). For non-Bricks, non-Tailwind consumers and the
+docs build.
+
+## \`bricks\` — WordPress / Bricks Builder payload
+
+Emits the full deployable theme payload: \`styles.min.css\`, the Bricks import JSONs
+(\`bricks-colors-{named,semantic}.json\`, \`bricks-variables.json\`), \`tokens.json\`, the JS
+bundles (polyfills / elements / deferred), the Bricks element PHP under \`bricks/\`, and
+this docs bundle under \`docs/\`.
+
+- **Bricks provides the token layer.** \`color.css\` and \`type-tokens.css\` are one-line
+  stubs: the colour \`:root\` tokens, dark-mode overrides, colour utility classes, fonts,
+  and type/space scales are generated live by Bricks' Color / Font / Variables Managers
+  from the imported JSONs. Semantic palette entries carry \`darkEnabled\` + a \`dark\` ref so
+  Bricks emits the dark-mode overrides on import.
+- Everything else (patterns, shadows, typography roles, animation effects, structural
+  framework CSS) ships in \`styles.min.css\` as in the other formats.
+- Pattern states reference shadows by name, compiled to
+  \`filter: drop-shadow(var(--shadow-<name>))\`.
+`;
+}
+function renderColorConcept(ds) {
+	const hues = Object.keys(ds.colors.palette ?? {});
+	const roles = Object.keys(ds.colors.roles ?? {});
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops colour system — seeded scales, functional tokens, automatic dark mode",
+		description: "How palette hues become 11-step OKLCH scales, how semantic roles derive functional tokens from them, and how dark mode flips automatically.",
+		resource: DS_PATH,
+		tags: [
+			"color",
+			"oklch",
+			"dark-mode",
+			"design-system"
+		]
+	})}
+
+# Colour system
+
+Authoring is two maps in \`design-system.json\` (see [authoring.md](../authoring.md)):
+\`colors.palette\` (hues) and \`colors.roles\` (semantic role → hue). Everything else —
+scales, functional tokens, utilities, dark mode — is derived.
+
+## From seed to scale
+
+Each palette hue becomes an **11-step numeric OKLCH scale**, \`--color-<hue>-50…950\`,
+running tinted near-white → tinted near-black. Two authoring modes:
+
+- **Seeded** (\`{ seed, anchors? }\`): the scale is generated from one colour. The seed is
+  preserved at its natural lightness step; \`anchors\` pin specific steps and the rest
+  interpolate around them.
+- **Fixed** (\`{ tones }\`): a brand kit used verbatim — each authored tone lands at its
+  nearest step, endpoints are tinted off-white/off-black, no interpolation.
+
+Current hues: ${code(hues)}.
+
+## Functional tokens (the public vocabulary)
+
+Each role in \`colors.roles\` (currently ${code(roles)}) derives a family of
+**job-named** tokens from its hue's scale:
+
+- \`--<role>-bg\`, \`--<role>-bg-muted\` — background washes.
+- \`--<role>-border\`, \`--<role>-border-bold\` — borders.
+- \`--<role>-solid\`, \`--<role>-solid-bold\` — opaque fills (buttons, badges), paired with
+  \`--<role>-on-solid\` for a guaranteed-contrast foreground.
+- \`--<role>-text\`, \`--<role>-text-muted\`, \`--<role>-text-x-muted\` — content colours.
+- **Emphasis stops** \`--color-<role>-{x-muted,muted,bold,x-bold}\` — appearance-relative:
+  \`muted\` recedes toward the background extreme and \`bold\` advances toward the
+  foreground, in *either* light or dark.
+- Plus \`--surface-glass\` (translucent surface) and \`--overlay\` (scrim).
+
+Classes name the token, not the tone: \`bg-<role>\`, \`text-<role>-muted\`, \`text-on-<role>\`,
+\`border-<role>\` (see [css/classes.md](../css/classes.md)).
+
+## Automatic dark mode
+
+Dark mode is a **functional flip** under \`:root[data-brx-theme="dark"]\`: background and
+text ends of each scale swap, while \`solid\` fills stay mode-stable with a recomputed
+\`on-solid\` foreground. There is no per-appearance scheme grammar to author and no named
+steps — a role token means the same *job* in both appearances.
+
+## Contrast guarantees
+
+Text tokens target APCA Lc ≥ 75 and muted text Lc ≥ 60, in **both** appearances —
+enforced by the generator's unit tests, not left to the author.
+`;
+}
+function renderScalesConcept(ds) {
+	const t = ds.typeScale;
+	const s = ds.spaceScale;
+	const scaleLine = (label, sc) => sc ? `- **${label}**: base \`${sc.base}\` at step \`${sc.names?.[(sc.baseStep ?? 1) - 1] ?? sc.baseStep}\`, ratio ${sc.ratio}${sc.fluid ? ` (${sc.fluid.minRatio} below ${sc.fluid.minVw})` : ""}; steps ${code(sc.names ?? [])}.` : `- **${label}**: not configured.`;
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops type & space scales — fluid modular scales",
+		description: "How typeScale and spaceScale compile to clamp()-based fluid modular scales, and which utilities consume the resulting tokens.",
+		resource: DS_PATH,
+		tags: [
+			"typography",
+			"spacing",
+			"fluid",
+			"modular-scale",
+			"design-system"
+		]
+	})}
+
+# Type & space scales
+
+Both scales share one model (authored in \`design-system.json\` as \`typeScale\` /
+\`spaceScale\` — see [authoring.md](../authoring.md)): a **fluid modular scale**.
+
+## The model
+
+- \`base\` anchors the value at \`baseStep\`; every other step is a power of the \`ratio\`
+  away (step n = base × ratio^(n − baseStep)).
+- With \`fluid\`, each step compiles to a **\`clamp()\`**: the scale uses \`fluid.minRatio\`
+  at/below \`fluid.minVw\` and grows to \`ratio\` at \`fluid.maxVw\`, interpolating between —
+  so large steps spread apart on wide viewports and compress on phones, with no
+  breakpoint jumps. \`baseline\` names the pivot step that stays closest to \`base\`.
+- \`names\` become the token suffixes.
+
+${scaleLine("Type", t)}
+${scaleLine("Space", s)}
+
+## What consumes them
+
+- **Type**: \`--text-<name>\` tokens → typography role sizes (\`font-<role>\` classes,
+  heading defaults) and text-size utilities.
+- **Space**: \`--space-<name>\` tokens → gap (\`g\`), spacing utilities, and \`rhythm\`
+  (relationship-based vertical margins between headings, paragraphs, lists, media).
+  Prefer \`rhythm\` for vertical flow over per-element margins.
+- In the \`tailwind\` format these stay in their own namespaces (\`--text-*\` via \`@theme\`,
+  \`--space-*\` as plain vars) — see [formats.md](../formats.md) for why \`--spacing-*\` is
+  deliberately not used.
+`;
+}
+function renderPatternsConcept(ds) {
+	const items = ds.patterns?.items ?? {};
+	const groups = Object.keys(ds.patterns?.groups ?? {});
+	const patternNames = Object.keys(items);
+	const hookTable = Object.entries(BASE_HOOK).map(([prop, sfx]) => `| \`${prop}\` | \`--${sfx}-<pattern>\` |`).join("\n");
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops component patterns — token cascade, override hooks, states",
+		description: "How pattern CSS is assembled: the token cascade (defaults → groups → per-pattern overrides), per-pattern override-hook variables, state shortcuts, and role variants.",
+		resource: DS_PATH,
+		tags: [
+			"patterns",
+			"components",
+			"cascade",
+			"css",
+			"design-system"
+		]
+	})}
+
+# Component patterns — the CSS chain
+
+Patterns (currently ${code(patternNames)}) are authored declaratively under \`patterns\` in
+\`design-system.json\` (see [authoring.md](../authoring.md)) and compiled to CSS in the
+**\`components\` cascade layer** — so utility classes (declared in a later layer) always win
+over pattern styling without specificity fights.
+
+## 1 — Token cascade
+
+Shared geometry resolves through a variable chain, most-specific first:
+
+- \`patterns.defaults\` → \`--<prop>-default\` (cascade-wide fallbacks).
+- \`patterns.groups.<group>\` → \`--<prop>-<group>\` (e.g. groups ${code(groups)}); a pattern
+  opts in via its \`group\` key.
+- Per-pattern: each grouped pattern gets aliases \`--<prop>-<name>-group\` →
+  \`var(--<prop>-<group>)\`, and \`overrides\` replace individual aliases with literal values.
+- \`patterns.radii\` → \`--br-<name>\` shape primitives; \`patterns.z\` → \`--z-tier-<name>\`.
+
+## 2 — Base declarations & override hooks
+
+Each pattern's \`base\` block is emitted on its selector — a class (\`.<class ?? name>\`) or,
+with \`element\`, a **zero-specificity** \`:where(<element>)\` rule so author CSS can always
+override it. Geometry properties are wrapped in a **per-pattern override hook**:
+
+| base property | hook variable |
+| --- | --- |
+${hookTable}
+
+e.g. \`padding: var(--p-button, 0.6em 1.2em)\` — a consumer restyles every button by setting
+\`--p-button\` on \`:root\`, without touching the pattern.
+
+## 3 — States
+
+\`states\` (hover / active / focus-visible) compile from shortcuts:
+
+- \`step: n\` — intensify the pattern's colour one emphasis stop: fills swap
+  \`--<role>-solid\` → \`--<role>-solid-bold\`; text patterns swap the \`bold\` emphasis stop →
+  \`x-bold\`.
+- \`scale: 0.97\` — transform scale; \`lift: "<length>"\` — \`translate: 0 calc(-1 * <length>)\`.
+- \`shadow: "<name>"\` — \`filter: drop-shadow(var(--shadow-<name>))\`; \`shadow: true\` — the
+  generic lift box-shadow.
+- \`ring: true\` — focus ring (\`box-shadow\` in the role's \`muted\` stop, outline removed).
+- \`css: { … }\` — raw declarations escape hatch.
+
+Any pattern with states also gets a composed transition block (translate / scale / filter /
+box-shadow / colours, \`--interact-duration\` / \`--interact-easing\` overridable). Hover
+rules are wrapped in \`@media (hover: hover)\` so touch devices never stick.
+
+## 4 — Role variants
+
+\`roles\` lists semantic colour variants: class patterns emit \`.<pattern>-<role>\`
+(\`.badge-success\`), element patterns emit \`<element>.<role>\` (\`button.danger\`). Fill
+patterns set \`background-color: var(--<role>-solid)\` + \`color: var(--<role>-on-solid)\`;
+text patterns use the role's \`bold\` emphasis stop. \`default_role\` colours the bare,
+unsuffixed pattern. States re-apply per variant with the variant's role.
+`;
+}
 function renderTopIndex() {
 	return `${INDEX_NOTE}
 
@@ -931,10 +1391,25 @@ variable-driven CSS framework plus progressively-enhanced web components, genera
 
 # Contents
 
+* [Authoring reference](authoring.md) - every design-system.json field, generated from the JSON Schema
+* [Output formats](formats.md) - tailwind vs css vs bricks: what's emitted, what the platform provides, which utilities Tailwind owns
+* [Concepts](concepts/) - the colour system, type/space scales, and pattern CSS architecture
 * [CSS framework](css/) - the class vocabulary (colour, type, space, layout, animation, component patterns), stated as naming rules
 * [Bricks Builder](bricks/) - custom elements and how to style them
 `;
 }
+function renderConceptsIndex() {
+	return `${INDEX_NOTE}
+
+# Design-system concepts
+
+# Contents
+
+* [Colour system](color.md) - seeded OKLCH scales, functional 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
+`;
+}
 function renderCssIndex() {
 	return `${INDEX_NOTE}
 
@@ -974,12 +1449,66 @@ function generateDocs(ds, assetsDir) {
 	const elementsDir = join(assetsDir, "bricks", "elements");
 	return {
 		"index.md": renderTopIndex(),
+		"authoring.md": renderAuthoring(),
+		"formats.md": renderFormats(ds),
+		"concepts/index.md": renderConceptsIndex(),
+		"concepts/color.md": renderColorConcept(ds),
+		"concepts/scales.md": renderScalesConcept(ds),
+		"concepts/patterns.md": renderPatternsConcept(ds),
 		"css/index.md": renderCssIndex(),
 		"css/classes.md": renderCssClasses(ds),
 		"bricks/index.md": renderBricksIndex(),
 		"bricks/elements.md": renderElementsDoc(elementsDir)
 	};
 }
+/**
+* Render the generated agent skill (`SKILL.md`) that fronts the docs bundle.
+* The bundle is expected to live beside it under `references/` (the layout
+* `vitops agents` writes); paths in the body are relative to the skill dir.
+*/
+function renderSkill(ds) {
+	const patternNames = Object.keys(ds.patterns?.items ?? {});
+	return `---
+name: vitops-design-system
+description: >-
+  Work with this project's Vitops design system. Use when styling or authoring
+  pages or components (choosing utility/pattern classes, colours, spacing,
+  typography), when editing design-system.json (tokens, palette, patterns,
+  scales, animations), when generating output (vitops generate --format
+  tailwind|css|bricks), or when asking what the design system provides on a
+  given platform (Tailwind vs Bricks vs standalone CSS).
+---
+
+<!-- GENERATED by @getvitops/cli — do not hand-edit; regenerate with \`vitops agents\`. -->
+
+# Vitops design system
+
+This project is styled with the Vitops design system (\`@getvitops/*\`): a variable-driven
+CSS framework generated from \`design-system.json\` (single source of truth — semantic
+colour roles ${code(Object.keys(ds.colors.roles ?? {}))}, fluid type/space scales, component patterns
+${code(patternNames)}, animation effects).
+
+**Core rule:** prefer the framework's utility + component classes over hand-written CSS or
+ad-hoc values — they encode the tokens, respond to dark mode, and update with the system.
+
+## Which reference to read when
+
+- Choosing classes (layout, colour, type, spacing, animation, patterns) →
+  [references/css/classes.md](references/css/classes.md)
+- Editing \`design-system.json\` (what a field means / what's valid) →
+  [references/authoring.md](references/authoring.md)
+- Output questions per platform — what Tailwind provides natively (and which framework
+  utilities are deliberately NOT emitted for it), what Bricks' managers own, what the
+  standalone CSS bundle contains → [references/formats.md](references/formats.md)
+- Understanding the systems (seeded OKLCH colour + automatic dark mode, fluid modular
+  scales, pattern CSS cascade/override hooks) → [references/concepts/](references/concepts/index.md)
+- Building in Bricks Builder (custom elements + controls) →
+  [references/bricks/elements.md](references/bricks/elements.md)
+
+Regenerate this skill and its references after changing \`design-system.json\`:
+\`vitops agents\`.
+`;
+}
 
 //#endregion
 //#region src/generate.ts
@@ -1094,13 +1623,6 @@ const STATE_DEFAULT = {
 	"hue-rotate": "0deg",
 	clip: "none"
 };
-const BASE_HOOK = {
-	padding: "p",
-	"border-radius": "br",
-	border: "b",
-	"box-shadow": "ds",
-	"font-size": "fs"
-};
 const id = (key) => createHash("sha256").update(key).digest("hex").slice(0, 6);
 function build(ds, format, assetsDir) {
 	const BRICKS = format === "bricks";
@@ -1721,64 +2243,6 @@ body {
 	const animEngine = readFileSync(join(cssDir, "animation.css"), "utf8");
 	parts.push(`/* ── Animation engine (animation.css) ── */\n@layer components {\n${animEngine}\n}`);
 	parts.push(`/* ── Component patterns ── */\n@layer components {\n${patternsCss}\n}`);
-	const TW_CLASH = new Set([
-		"block",
-		"inline",
-		"inline-block",
-		"flow-root",
-		"flex",
-		"inline-flex",
-		"grid",
-		"inline-grid",
-		"table",
-		"inline-table",
-		"table-caption",
-		"table-cell",
-		"table-row",
-		"contents",
-		"hidden",
-		"list-item",
-		"static",
-		"fixed",
-		"absolute",
-		"relative",
-		"sticky",
-		"isolate",
-		"visible",
-		"invisible",
-		"collapse",
-		"sr-only",
-		"not-sr-only",
-		"flex-row",
-		"flex-row-reverse",
-		"flex-col",
-		"flex-col-reverse",
-		"flex-wrap",
-		"flex-nowrap",
-		"items-start",
-		"items-end",
-		"items-center",
-		"items-baseline",
-		"items-stretch",
-		"justify-start",
-		"justify-end",
-		"justify-center",
-		"justify-between",
-		"justify-around",
-		"justify-evenly",
-		"content-start",
-		"content-end",
-		"content-center",
-		"content-between",
-		"content-around",
-		"content-evenly",
-		"text-left",
-		"text-center",
-		"text-right",
-		"text-justify",
-		"text-start",
-		"text-end"
-	]);
 	const droppedClashes = /* @__PURE__ */ new Set();
 	let droppedVariantBlocks = 0;
 	const stripForTailwind = (css) => {
@@ -1960,8 +2424,7 @@ async function generate(options) {
 * Pure: no YAML/env/fs. `resolveSiteConfig` takes an already-parsed object; a
 * thin loader (reading YAML, injecting `SITE_ENV`) lives outside this module.
 */
-/** A string, or a per-locale map of strings (`{ en: "…", fr: "…" }`). */
-const LocalizableSchema = z.union([z.string(), z.record(z.string(), z.string())]);
+const LocalizableSchema = desc(z.union([z.string(), z.record(z.string(), z.string())]), "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`).");
 const ImageRefSchema = z.union([z.string(), z.object({
 	src: z.string(),
 	alt: z.string(),
@@ -1986,13 +2449,13 @@ const DayOfWeek = z.enum([
 	"Sunday"
 ]);
 const DesignSystemEntry = z.extend(DesignSystemPatchSchema, {
-	displayName: z.optional(LocalizableSchema),
-	extends: z.optional(z.string())
+	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.")
 });
 const LocaleSchema = z.object({
-	name: z.string(),
-	tagline: z.optional(z.string()),
-	basePath: z.optional(z.string())
+	name: desc(z.string(), "Display name of the locale (e.g. \"English\")."),
+	tagline: desc(z.optional(z.string()), "Site tagline in this locale."),
+	basePath: desc(z.optional(z.string()), "URL prefix for this locale (e.g. \"/fr\").")
 });
 const HttpRedirect = z.union([
 	z.literal(301),
@@ -2006,14 +2469,13 @@ const DomainAliasSchema = z.object({
 	redirectTo: z.string(),
 	environment: z.optional(z.string())
 });
-/** schema.org `PostalAddress` field names, so JSON-LD generation is lossless. */
-const PostalAddressSchema = z.object({
+const PostalAddressSchema = desc(z.object({
 	streetAddress: z.string(),
-	addressLocality: z.string(),
-	addressRegion: z.optional(z.string()),
+	addressLocality: desc(z.string(), "City."),
+	addressRegion: desc(z.optional(z.string()), "State / province."),
 	postalCode: z.optional(z.string()),
-	addressCountry: z.string()
-});
+	addressCountry: desc(z.string(), "Country (ISO 3166-1 alpha-2 preferred).")
+}), "schema.org `PostalAddress` field names, so JSON-LD generation is lossless.");
 const ContactObjectSchema = z.object({
 	name: z.optional(z.string()),
 	email: z.optional(z.email()),
@@ -2072,8 +2534,7 @@ const OrganizationSchema = z.object({
 	address: z.optional(PostalAddressSchema),
 	taxID: z.optional(z.string()),
 	vatID: z.optional(z.string()),
-	/** Profile URLs → JSON-LD `sameAs` (mirrors `links`). */
-	sameAs: z.optional(z.array(z.url()))
+	sameAs: desc(z.optional(z.array(z.url())), "Profile URLs → JSON-LD `sameAs` (mirrors `links`).")
 });
 const DnsRecordType = z.enum([
 	"A",
@@ -2101,11 +2562,11 @@ const DnsDomainSchema = z.object({
 });
 const RobotsSchema = z.string();
 const EnvironmentSchema = z.object({
-	url: z.url(),
-	api: z.optional(z.url()),
-	analytics: z.optional(z.boolean()),
-	robots: z.optional(RobotsSchema),
-	variant: z.optional(z.string())
+	url: desc(z.url(), "Public origin of this environment."),
+	api: desc(z.optional(z.url()), "API origin, when different from `url`."),
+	analytics: desc(z.optional(z.boolean()), "Whether analytics fire in this environment."),
+	robots: desc(z.optional(RobotsSchema), "Robots policy (e.g. \"noindex,nofollow\" for dev)."),
+	variant: desc(z.optional(z.string()), "Active `abTesting.variants` key for this environment.")
 });
 const AbVariantSchema = z.object({
 	environment: z.string(),
@@ -2152,11 +2613,10 @@ const FontSchema = z.object({
 	formats: z.optional(z.array(z.string())),
 	unicodeRange: z.optional(z.array(z.string())),
 	variants: z.optional(z.array(FontVariantSchema)),
-	/** Emit `<Font preload />` for this family. */
-	preload: z.optional(z.union([z.boolean(), z.array(z.object({
+	preload: desc(z.optional(z.union([z.boolean(), z.array(z.object({
 		weight: FontWeight,
 		style: z.optional(FontStyle)
-	}))]))
+	}))])), "Emit `<Font preload />` for this family (true, or a list of weight/style faces).")
 });
 const PresentSchema = z.optional(z.record(z.string(), z.unknown()));
 const NavItemSchema = z.object({
@@ -2289,18 +2749,18 @@ const TwitterSchema = z.object({
 	image: z.optional(ImageRefSchema)
 });
 const SiteConfigSchema = z.object({
-	defaultLocale: z.string(),
-	locales: z.record(z.string(), LocaleSchema),
-	organization: z.optional(OrganizationSchema),
-	contact: z.optional(ContactConfigSchema),
-	domains: z.optional(z.object({
-		canonical: z.url(),
-		aliases: z.optional(z.array(DomainAliasSchema))
-	})),
-	primaryLocation: z.optional(z.string()),
-	locations: z.optional(z.record(z.string(), LocationSchema)),
-	services: z.optional(z.record(z.string(), ServiceSchema)),
-	links: z.optional(z.object({
+	defaultLocale: desc(z.string(), "The locale used when none is specified; must be a `locales` key."),
+	locales: desc(z.record(z.string(), LocaleSchema), "Locales the site is published in, keyed by BCP 47 tag (e.g. \"en\", \"fr\")."),
+	organization: desc(z.optional(OrganizationSchema), "schema.org Organization details for JSON-LD (name, legalName, logo, tax IDs, sameAs profiles)."),
+	contact: desc(z.optional(ContactConfigSchema), "Primary contact: either a `locations` key (string reference) or an inline name/email/phone/address object."),
+	domains: desc(z.optional(z.object({
+		canonical: desc(z.url(), "The canonical origin used for absolute URLs and SEO."),
+		aliases: desc(z.optional(z.array(DomainAliasSchema)), "Alias domains and how they redirect to the canonical one.")
+	})), "Canonical domain + redirecting aliases."),
+	primaryLocation: desc(z.optional(z.string()), "The main `locations` key (for JSON-LD and defaults)."),
+	locations: desc(z.optional(z.record(z.string(), LocationSchema)), "Physical locations (schema.org LocalBusiness): address, geo, opening hours, service area."),
+	services: desc(z.optional(z.record(z.string(), ServiceSchema)), "Services offered (schema.org Service/Offer): name, description, slug, price offers."),
+	links: desc(z.optional(z.object({
 		googleMaps: z.optional(z.url()),
 		instagram: z.optional(z.url()),
 		facebook: z.optional(z.url()),
@@ -2308,52 +2768,52 @@ const SiteConfigSchema = z.object({
 		linkedin: z.optional(z.url()),
 		youtube: z.optional(z.url()),
 		github: z.optional(z.url())
-	})),
-	dns: z.optional(z.record(z.string(), DnsDomainSchema)),
-	cloudflare: z.optional(z.record(z.string(), z.unknown())),
-	environments: z.record(z.string(), EnvironmentSchema),
-	abTesting: z.optional(z.object({
+	})), "Public profile URLs (also feed JSON-LD `sameAs` via `organization.sameAs`)."),
+	dns: desc(z.optional(z.record(z.string(), DnsDomainSchema)), "Desired DNS state per domain (provider, nameservers, records) — declarative reference, not applied automatically."),
+	cloudflare: desc(z.optional(z.record(z.string(), z.unknown())), "Deliberate escape hatch for provider-specific Cloudflare settings — out of scope to model here."),
+	environments: desc(z.record(z.string(), EnvironmentSchema), "Deploy environments (production, dev, …): URL, API origin, analytics toggle, robots policy, active A/B variant."),
+	abTesting: desc(z.optional(z.object({
 		enabled: z.boolean(),
 		cookieName: z.optional(z.string()),
-		cookieMaxAge: z.optional(z.number().check(z.int(), z.positive())),
-		splitRatio: z.optional(z.number().check(z.gte(0), z.lte(1))),
-		variants: z.optional(z.record(z.string(), AbVariantSchema))
-	})),
-	designSystem: z.record(z.string(), DesignSystemEntry),
-	defaultTheme: z.optional(z.string()),
-	defaultColorScheme: z.optional(z.enum(["light", "dark"])),
-	respectSystemPreference: z.optional(z.boolean()),
-	fonts: z.optional(z.array(FontSchema)),
-	tags: z.optional(z.record(z.string(), z.unknown())),
-	postTypes: z.optional(z.record(z.string(), z.unknown())),
-	galleries: z.optional(z.record(z.string(), GallerySchema)),
-	testimonials: z.optional(z.record(z.string(), TestimonialGroupSchema)),
-	templates: z.optional(z.record(z.string(), TemplateSchema)),
-	navigation: z.optional(z.object({ activeTemplate: z.optional(z.object({
-		default: z.optional(z.string()),
-		breakpoints: z.optional(z.record(z.string(), z.string()))
-	})) })),
-	seo: z.optional(z.object({
-		titleTemplate: z.optional(z.string()),
+		cookieMaxAge: desc(z.optional(z.number().check(z.int(), z.positive())), "Seconds."),
+		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`."),
+	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)."),
+	testimonials: desc(z.optional(z.record(z.string(), TestimonialGroupSchema)), "Named testimonial groups (quote, name, role, rating, date)."),
+	templates: desc(z.optional(z.record(z.string(), TemplateSchema)), "Named content templates rendered at SSR time: `nav` (menu trees), `form` (field lists + submit), or `nodes` (raw element trees)."),
+	navigation: desc(z.optional(z.object({ activeTemplate: desc(z.optional(z.object({
+		default: desc(z.optional(z.string()), "A `templates` key."),
+		breakpoints: desc(z.optional(z.record(z.string(), z.string())), "Breakpoint name → `templates` key overrides.")
+	})), "Which nav template is active, optionally per breakpoint.") })), "Site navigation settings (which nav template renders where)."),
+	seo: desc(z.optional(z.object({
+		titleTemplate: desc(z.optional(z.string()), "Page-title pattern (e.g. \"%s · Acme\")."),
 		descriptionTemplate: z.optional(z.string()),
-		robots: z.optional(RobotsSchema),
+		robots: desc(z.optional(RobotsSchema), "e.g. \"index,follow\" / \"noindex,nofollow\"."),
 		googleSiteVerification: z.optional(z.string()),
 		bingSiteVerification: z.optional(z.string()),
 		openGraph: z.optional(OpenGraphSchema),
 		twitter: z.optional(TwitterSchema)
-	})),
-	analytics: z.optional(z.object({
+	})), "SEO defaults: title/description templates, robots policy, verification tokens, Open Graph + Twitter cards."),
+	analytics: desc(z.optional(z.object({
 		googleAnalyticsId: z.optional(z.string()),
 		plausibleDomain: z.optional(z.string()),
 		googleTagManagerId: z.optional(z.string())
-	})),
-	notifications: z.optional(z.object({ email: z.optional(z.email()) })),
-	tracking: z.optional(z.object({
+	})), "Analytics provider IDs (gated per environment via `environments.<env>.analytics`)."),
+	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()),
 		platforms: z.optional(z.array(z.string()))
-	})),
-	security: z.optional(z.object({ turnstile: z.optional(z.object({ siteKey: z.optional(z.string()) })) })),
-	legal: z.optional(z.object({
+	})), "Marketing/conversion tracking toggles per platform."),
+	security: desc(z.optional(z.object({ turnstile: z.optional(z.object({ siteKey: desc(z.optional(z.string()), "Cloudflare Turnstile site key (public).") })) })), "Security integrations (bot protection)."),
+	legal: desc(z.optional(z.object({
 		privacyPolicy: z.optional(z.object({
 			enabled: z.boolean(),
 			url: z.optional(z.url()),
@@ -2366,7 +2826,7 @@ const SiteConfigSchema = z.object({
 		})),
 		cookieConsent: z.optional(z.object({
 			enabled: z.boolean(),
-			type: z.optional(z.enum(["opt-in", "opt-out"])),
+			type: desc(z.optional(z.enum(["opt-in", "opt-out"])), "Consent model."),
 			position: z.optional(z.enum([
 				"top",
 				"bottom",
@@ -2374,11 +2834,11 @@ const SiteConfigSchema = z.object({
 			])),
 			categories: z.optional(z.array(z.string()))
 		}))
-	})),
-	icons: z.optional(z.object({
-		ui: z.optional(z.string()),
-		brand: z.optional(z.string()),
-		semantic: z.optional(z.array(z.string())),
+	})), "Legal pages + cookie-consent configuration."),
+	icons: desc(z.optional(z.object({
+		ui: desc(z.optional(z.string()), "Icon set used for UI chrome (e.g. \"lucide\")."),
+		brand: desc(z.optional(z.string()), "Icon set used for brand marks."),
+		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())),
 		"fa7-light": z.optional(z.array(z.string())),
@@ -2387,24 +2847,21 @@ const SiteConfigSchema = z.object({
 		"simple-icons": z.optional(z.array(z.string())),
 		"material-symbols": z.optional(z.array(z.string())),
 		lucide: z.optional(z.array(z.string()))
-	})),
-	favicon: z.optional(z.object({
-		source: z.string(),
-		lowResSource: z.optional(z.string()),
-		/** App name for the generated web manifest / PWA. */
-		name: z.optional(z.string()),
-		/** PWA theme color (also `<meta name="theme-color">`). */
-		themeColor: z.optional(z.string()),
-		/** PWA background color. */
-		backgroundColor: z.optional(z.string())
-	})),
-	deployment: z.optional(z.object({
+	})), "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."),
+		lowResSource: desc(z.optional(z.string()), "Alternate source for small raster sizes (16/32px) when the main source scales down poorly."),
+		name: desc(z.optional(z.string()), "App name for the generated web manifest / PWA."),
+		themeColor: desc(z.optional(z.string()), "PWA theme color (also `<meta name=\"theme-color\">`)."),
+		backgroundColor: desc(z.optional(z.string()), "PWA background color.")
+	})), "Favicon/PWA asset generation (consumed by `@getvitops/utils` favicon tooling)."),
+	deployment: desc(z.optional(z.object({
 		platform: z.optional(z.string()),
 		buildCommand: z.optional(z.string()),
 		deployCommand: z.optional(z.string()),
 		outputDirectory: z.optional(z.string()),
 		type: z.optional(z.string())
-	}))
+	})), "How the site is built and deployed (platform, commands, output directory) — informational for tooling.")
 });
 const SITE_SCHEMA_URL = "https://unpkg.com/@getvitops/generator/site.schema.json";
 /** The published JSON Schema (draft-2020-12), derived from the zod schema. */
@@ -2773,5 +3230,5 @@ function defaultConfig() {
 }
 
 //#endregion
-export { DesignSystemSchema, SCHEMA_URL, SITE_SCHEMA_URL, SiteConfigSchema, deepMerge, defaultConfig, generate, generateDocs, jsonSchema, resolveSiteConfig, resolveTheme, siteJsonSchema, stripNulls, validate, validateSite };
+export { BASE_HOOK, DesignSystemSchema, SCHEMA_URL, SITE_SCHEMA_URL, SiteConfigSchema, TW_CLASH, deepMerge, defaultConfig, generate, generateDocs, jsonSchema, renderSkill, resolveSiteConfig, resolveTheme, siteJsonSchema, stripNulls, validate, validateSite };
 //# sourceMappingURL=index.mjs.map