@getvitops/generator 0.1.0

package/dist/index.mjs

@@ -0,0 +1,2611 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { transform } from "lightningcss";
+import * as z from "zod/mini";
+
+//#region src/schema.ts
+/**
+* Canonical `design-system.json` schema — the single source of truth.
+*
+* 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`.
+*/
+const CssDecls = z.record(z.string(), z.string());
+const Scalar = z.union([z.string(), z.number()]);
+const VarMap = z.record(z.string(), Scalar);
+const Ramp = z.object({
+	xxd: z.optional(z.string()),
+	xd: z.optional(z.string()),
+	d: z.optional(z.string()),
+	base: z.optional(z.string()),
+	l: z.optional(z.string()),
+	xl: z.optional(z.string()),
+	xxl: z.optional(z.string())
+});
+const RoleSpec = z.union([z.string(), z.object({
+	ramp: z.optional(z.string()),
+	invert: z.optional(z.boolean()),
+	shift: z.optional(z.number()),
+	steps: z.optional(z.record(z.string(), z.string())),
+	value: z.optional(z.record(z.string(), z.string()))
+})]);
+const Scheme = z.object({
+	appearance: z.enum(["light", "dark"]),
+	semantic: z.record(z.string(), RoleSpec)
+});
+const UtilityName = z.enum([
+	"bg",
+	"text",
+	"border",
+	"outline",
+	"fill",
+	"stroke"
+]);
+const Colors = z.object({
+	palette: z.record(z.string(), Ramp),
+	utilities: z.optional(z.array(UtilityName)),
+	schemes: z.record(z.string(), Scheme)
+});
+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())))
+	}))
+});
+const DesignSystemSchema = z.object({
+	$schema: z.optional(z.string()),
+	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),
+	patterns: z.optional(Patterns),
+	typography: z.optional(Typography),
+	animations: z.optional(Animations)
+});
+const ColorsPatch = z.object({
+	palette: z.optional(z.record(z.string(), Ramp)),
+	utilities: z.optional(z.array(UtilityName)),
+	schemes: z.optional(z.record(z.string(), z.object({
+		appearance: z.optional(z.enum(["light", "dark"])),
+		semantic: z.optional(z.record(z.string(), RoleSpec))
+	})))
+});
+const DesignSystemPatchSchema = z.extend(z.partial(DesignSystemSchema), { colors: z.optional(ColorsPatch) });
+/**
+* Stable URL of the published JSON Schema. Resolves once `@getvitops/generator` is on
+* npm (unpkg serves the packaged `schema.json`); `vitops init` stamps this into a
+* scaffolded config's `$schema` so editors light up autocomplete + validation.
+*/
+const SCHEMA_URL = "https://unpkg.com/@getvitops/generator/schema.json";
+/** The published JSON Schema (draft-2020-12), derived from the zod schema. */
+const jsonSchema = {
+	$id: SCHEMA_URL,
+	...z.toJSONSchema(DesignSystemSchema, { target: "draft-2020-12" })
+};
+/** Validate an unknown value against the design-system schema. */
+function validate(input) {
+	const result = z.safeParse(DesignSystemSchema, input);
+	if (!result.success) return {
+		ok: false,
+		data: void 0,
+		errors: result.error.issues
+	};
+	if (result.data.colors.schemes.default == null) return {
+		ok: false,
+		data: void 0,
+		errors: [{
+			code: "custom",
+			path: [
+				"colors",
+				"schemes",
+				"default"
+			],
+			message: "colors.schemes must include a \"default\" (base) scheme"
+		}]
+	};
+	return {
+		ok: true,
+		data: result.data,
+		errors: []
+	};
+}
+
+//#endregion
+//#region src/docs.ts
+/**
+* OKF documentation bundle generator (ported from the repo's `generate-docs.ts`).
+*
+* Pure: `generateDocs(ds, assetsDir)` returns a `{ relPath: markdown }` map for the
+* Open Knowledge Format tree (top index, css/, bricks/), reading the Bricks element
+* PHP from `<assetsDir>/bricks/elements`. No filesystem writes — the caller decides
+* where the bundle lands (e.g. `<outDir>/docs`).
+*/
+const DS_PATH = "design-system.json";
+const ORDER = [
+	"split",
+	"centered",
+	"carousel",
+	"color-scheme-toggle",
+	"copy-button",
+	"dismissable",
+	"entries",
+	"image-compare",
+	"sitenav",
+	"multi-field",
+	"split-link",
+	"split-panel"
+];
+function tokenize(src) {
+	const toks = [];
+	let i = 0;
+	const n = src.length;
+	while (i < n) {
+		const c = src[i];
+		if (c === " " || c === "	" || c === "\n" || c === "\r") {
+			i++;
+			continue;
+		}
+		if (c === "/" && src[i + 1] === "/") {
+			while (i < n && src[i] !== "\n") i++;
+			continue;
+		}
+		if (c === "#") {
+			while (i < n && src[i] !== "\n") i++;
+			continue;
+		}
+		if (c === "/" && src[i + 1] === "*") {
+			i += 2;
+			while (i < n && !(src[i] === "*" && src[i + 1] === "/")) i++;
+			i += 2;
+			continue;
+		}
+		if (c === "'" || c === "\"") {
+			const quote = c;
+			i++;
+			let s = "";
+			while (i < n && src[i] !== quote) if (src[i] === "\\" && i + 1 < n) {
+				const next = src[i + 1];
+				s += next === "n" ? "\n" : next === "t" ? "	" : next;
+				i += 2;
+			} else s += src[i++];
+			i++;
+			toks.push({
+				t: "str",
+				v: s
+			});
+			continue;
+		}
+		if (c === "=" && src[i + 1] === ">") {
+			toks.push({
+				t: "arrow",
+				v: "=>"
+			});
+			i += 2;
+			continue;
+		}
+		if ("[](){},".includes(c)) {
+			toks.push({
+				t: "punc",
+				v: c
+			});
+			i++;
+			continue;
+		}
+		if (c >= "0" && c <= "9" || c === "-" && src[i + 1] >= "0" && src[i + 1] <= "9") {
+			let s = c;
+			i++;
+			while (i < n && src[i] >= "0" && src[i] <= "9") s += src[i++];
+			toks.push({
+				t: "num",
+				v: s
+			});
+			continue;
+		}
+		if (/[A-Za-z_\\]/.test(c)) {
+			let s = c;
+			i++;
+			while (i < n && /[A-Za-z0-9_\\]/.test(src[i])) s += src[i++];
+			toks.push({
+				t: "id",
+				v: s
+			});
+			continue;
+		}
+		i++;
+	}
+	return toks;
+}
+var Parser = class {
+	p = 0;
+	toks;
+	constructor(toks) {
+		this.toks = toks;
+	}
+	peek() {
+		return this.toks[this.p];
+	}
+	next() {
+		return this.toks[this.p++];
+	}
+	parseValue() {
+		const t = this.peek();
+		if (!t) return null;
+		if (t.t === "str") {
+			this.next();
+			return t.v;
+		}
+		if (t.t === "num") {
+			this.next();
+			return Number(t.v);
+		}
+		if (t.t === "id") {
+			this.next();
+			if (t.v === "true") return true;
+			if (t.v === "false") return false;
+			if (t.v === "null") return null;
+			if (this.peek()?.t === "punc" && this.peek()?.v === "(") {
+				this.next();
+				if (t.v === "array") return this.parseBody(")");
+				const args = this.parseCallArgs();
+				return args.find((a) => typeof a === "string") ?? args[0] ?? "";
+			}
+			return t.v;
+		}
+		if (t.t === "punc" && t.v === "[") {
+			this.next();
+			return this.parseBody("]");
+		}
+		if (t.t === "punc" && t.v === "(") {
+			this.next();
+			return this.parseBody(")");
+		}
+		this.next();
+		return null;
+	}
+	parseCallArgs() {
+		const args = [];
+		while (this.peek() && !(this.peek().t === "punc" && this.peek().v === ")")) {
+			args.push(this.parseValue());
+			if (this.peek()?.t === "punc" && this.peek()?.v === ",") this.next();
+		}
+		this.next();
+		return args;
+	}
+	parseBody(close) {
+		const list = [];
+		const map = {};
+		let keyed = false;
+		while (this.peek() && !(this.peek().t === "punc" && this.peek().v === close)) {
+			const first = this.parseValue();
+			if (this.peek()?.t === "arrow") {
+				this.next();
+				map[String(first)] = this.parseValue();
+				keyed = true;
+			} else list.push(first);
+			if (this.peek()?.t === "punc" && this.peek()?.v === ",") this.next();
+		}
+		this.next();
+		return keyed ? map : list;
+	}
+};
+function parsePhpLiteral(text) {
+	return new Parser(tokenize(text)).parseValue();
+}
+function matchBalanced(src, open) {
+	const pairs = {
+		"(": ")",
+		"[": "]",
+		"{": "}"
+	};
+	const stack = [];
+	let i = open;
+	const n = src.length;
+	while (i < n) {
+		const c = src[i];
+		if (c === "/" && src[i + 1] === "/") {
+			while (i < n && src[i] !== "\n") i++;
+			continue;
+		}
+		if (c === "/" && src[i + 1] === "*") {
+			i += 2;
+			while (i < n && !(src[i] === "*" && src[i + 1] === "/")) i++;
+			i += 2;
+			continue;
+		}
+		if (c === "'" || c === "\"") {
+			i++;
+			while (i < n && src[i] !== c) {
+				if (src[i] === "\\") i++;
+				i++;
+			}
+			i++;
+			continue;
+		}
+		if (c in pairs) stack.push(pairs[c]);
+		else if (c === ")" || c === "]" || c === "}") {
+			if (stack.pop() !== c) {}
+			if (stack.length === 0) return i + 1;
+		}
+		i++;
+	}
+	return n;
+}
+function methodBody(src, name) {
+	const m = new RegExp(`function\\s+${name}\\s*\\([^)]*\\)`).exec(src);
+	if (!m) return null;
+	const brace = src.indexOf("{", m.index + m[0].length);
+	if (brace < 0) return null;
+	const end = matchBalanced(src, brace);
+	return src.slice(brace + 1, end - 1);
+}
+function literalAt(src, fromIdx) {
+	let i = fromIdx;
+	while (i < src.length && /\s/.test(src[i])) i++;
+	let open;
+	if (src[i] === "[") open = i;
+	else if (src.startsWith("array", i)) open = src.indexOf("(", i);
+	else return null;
+	const end = matchBalanced(src, open);
+	return {
+		text: src.slice(i, end),
+		end
+	};
+}
+function firstString(re, src) {
+	const m = re.exec(src);
+	return m ? m[1] ?? null : null;
+}
+function extractDocblock(src) {
+	const m = /\/\*\*([\s\S]*?)\*\//.exec(src);
+	if (!m) return "";
+	const lines = m[1].split("\n").map((l) => l.replace(/^\s*\*?\s?/, "").replace(/\s+$/, ""));
+	while (lines.length && lines[0] === "") lines.shift();
+	if (lines.length && /Bricks Builder\)\./.test(lines[0])) lines.shift();
+	const owned = lines.findIndex((l) => l.startsWith("Owned by the framework repo"));
+	const kept = (owned >= 0 ? lines.slice(0, owned) : lines).map((l) => l.replace(/^•\s*/, "- "));
+	while (kept.length && kept[kept.length - 1] === "") kept.pop();
+	while (kept.length && kept[0] === "") kept.shift();
+	return kept.join("\n");
+}
+function extractControls(src) {
+	const body = methodBody(src, "set_controls");
+	if (!body) return [];
+	const controls = [];
+	const re = /\$this->controls\[\s*'([^']+)'\s*\](\[\s*'([^']+)'\s*\])?\s*=\s*/g;
+	let m;
+	while (m = re.exec(body)) {
+		const key = m[1];
+		if (m[2]) continue;
+		const lit = literalAt(body, m.index + m[0].length);
+		if (!lit) continue;
+		const def = parsePhpLiteral(lit.text);
+		if (def && typeof def === "object" && !Array.isArray(def)) controls.push({
+			key,
+			def
+		});
+		re.lastIndex = lit.end;
+	}
+	return controls;
+}
+function extractChildren(src) {
+	const body = methodBody(src, "get_nestable_children");
+	if (!body) return [];
+	const labels = [];
+	const re = /'label'\s*=>\s*esc_html__\(\s*'([^']*)'/g;
+	let m;
+	while (m = re.exec(body)) labels.push(m[1]);
+	return labels;
+}
+function extractKeywords(src) {
+	const body = methodBody(src, "get_keywords");
+	if (!body) return [];
+	const ret = /return\s+/.exec(body);
+	if (!ret) return [];
+	const lit = literalAt(body, ret.index + ret[0].length);
+	if (!lit) return [];
+	const arr = parsePhpLiteral(lit.text);
+	return Array.isArray(arr) ? arr.filter((x) => typeof x === "string") : [];
+}
+function parseElement(src) {
+	const name = firstString(/public\s+\$name\s*=\s*'vitops-([^']+)'/, src);
+	if (!name) return null;
+	return {
+		name,
+		label: firstString(/function get_label\(\)[\s\S]*?return\s+esc_html__\(\s*'([^']*)'/, src) ?? name,
+		nestable: /public\s+\$nestable\s*=\s*true/.test(src),
+		docblock: extractDocblock(src),
+		controls: extractControls(src),
+		cssClass: firstString(/\$this->controls\[\s*'_cssClasses'\s*\]\[\s*'default'\s*\]\s*=\s*'([^']*)'/, src),
+		children: extractChildren(src),
+		keywords: extractKeywords(src)
+	};
+}
+function controlLine(c) {
+	const def = c.def;
+	if (def.type === "info") return `- _Note:_ ${def.content ?? ""}`;
+	const label = def.label || c.key;
+	const options = def.options && typeof def.options === "object" && !Array.isArray(def.options) ? def.options : null;
+	const meta = [];
+	let type = def.type || "text";
+	if (def.units === true) type += "+units";
+	meta.push(type);
+	if (def.default !== void 0) {
+		const raw = String(def.default);
+		const shown = options && options[raw] ? options[raw] : raw;
+		meta.push(`default \`${shown}\``);
+	}
+	if (def.placeholder !== void 0 && def.placeholder !== "") meta.push(`placeholder \`${def.placeholder}\``);
+	if (def.min !== void 0 || def.max !== void 0) meta.push(`range ${def.min ?? "–"}–${def.max ?? "∞"}`);
+	const tail = [];
+	if (def.description) tail.push(String(def.description));
+	if (options) tail.push(`Options: ${Object.values(options).map((o) => `\`${o}\``).join(", ")}.`);
+	if (Array.isArray(def.css) && def.css.length) {
+		const first = def.css[0];
+		if (first && typeof first === "object" && !Array.isArray(first) && "property" in first) tail.push(`Bound to \`${first.property}\`.`);
+	}
+	if (def.type === "repeater" && def.fields && typeof def.fields === "object") {
+		const fields = Object.values(def.fields).map((f) => f && typeof f === "object" && !Array.isArray(f) ? f.label : null).filter(Boolean);
+		if (fields.length) tail.push(`Fields: ${fields.join(", ")}.`);
+	}
+	const head = `- **${label}** (${meta.join(", ")})`;
+	return tail.length ? `${head} — ${tail.join(" ")}` : head;
+}
+function renderElement(el) {
+	const out = [];
+	const nest = el.nestable ? "nestable" : "not nestable";
+	out.push(`## ${el.label} — \`vitops-${el.name}\` · ${nest}`);
+	out.push("");
+	if (el.docblock) {
+		out.push(el.docblock);
+		out.push("");
+	}
+	if (el.controls.filter((c) => c.def.type !== "info").length) {
+		out.push("**Controls**");
+		out.push("");
+		for (const c of el.controls) out.push(controlLine(c));
+		out.push("");
+	} else {
+		const notes = el.controls.filter((c) => c.def.type === "info");
+		if (notes.length) {
+			for (const c of notes) out.push(controlLine(c));
+			out.push("");
+		}
+	}
+	if (el.cssClass) {
+		out.push(`**Base CSS class:** \`${el.cssClass}\` (applied automatically; add ratio/modifier classes alongside it in the element's "CSS classes" field).`);
+		out.push("");
+	}
+	if (el.children.length) {
+		out.push(`**Seeded children:** ${el.children.join(", ")}.`);
+		out.push("");
+	}
+	if (el.keywords.length) {
+		out.push(`**Keywords:** ${el.keywords.filter((k) => k !== "vitops").join(", ")}.`);
+		out.push("");
+	}
+	return out.join("\n");
+}
+function frontmatter(fm) {
+	const q = (s) => `"${s.replace(/"/g, "\\\"")}"`;
+	const lines = [
+		`type: ${q(fm.type)}`,
+		`title: ${q(fm.title)}`,
+		`description: ${q(fm.description)}`
+	];
+	if (fm.resource) lines.push(`resource: ${q(fm.resource)}`);
+	if (fm.tags) lines.push(`tags: [${fm.tags.join(", ")}]`);
+	lines.push("generator: \"@getvitops/generator\"");
+	return `---\n${lines.join("\n")}\n---`;
+}
+const INDEX_NOTE = `<!-- GENERATED by @getvitops/generator — do not edit; regenerate with \`vitops generate\`. -->`;
+const ELEMENTS_PREAMBLE = `${frontmatter({
+	type: "Bricks Elements Reference",
+	title: "Vitops — Bricks Builder elements reference",
+	description: "Every repo-owned Bricks element, its controls, defaults, seeded children and keywords, for driving the Bricks Builder UI.",
+	resource: "bricks/elements",
+	tags: [
+		"bricks",
+		"wordpress",
+		"elements",
+		"design-system"
+	]
+})}
+
+# Vitops — Bricks Builder elements reference
+
+Context for driving the Bricks Builder UI (e.g. Claude for Chrome). Every section below
+is generated from the element's own source, so this reference always matches the elements
+currently deployed. See also the CSS class vocabulary in [/css/classes.md](../css/classes.md)
+and the integration guidance in [/bricks/index.md](index.md).
+
+## How they appear in the builder
+
+- The elements register from \`dist/bricks/load.php\` and group under a **"Vitops"** category
+  pinned to the **top** of the element panel. Insert one by searching its **label** (e.g.
+  "Split", "Carousel") or any of its **keywords** (listed per element).
+- Two rendering families:
+  - **Web-component elements** render a Lit custom element (\`<wc-*>\`, \`<copy-button>\`, …)
+    from \`dist/elements.js\` and progressively enhance. A few (Image Compare, Split Panel)
+    show their children stacked in the builder canvas until the client-side upgrade runs —
+    that is expected, not broken.
+  - **CSS-pattern elements** (Split, Centered, Menu, Split Link) render plain markup styled
+    by the framework CSS — no JS dependency.
+- **Nestable** elements accept child elements dropped into them; some seed starter children
+  (listed as "Seeded children"). **Non-nestable** elements are configured entirely through
+  their controls.
+
+## Configuring layout
+
+Some layout is set through **controls**; some through **CSS classes typed into the element's
+built-in "CSS classes" field** (called out per element as modifier classes). Responsive
+suffixes on those classes engage from a container breakpoint: \`-sm\` = 30rem, \`-md\` = 48rem,
+\`-lg\` = 64rem, \`-xl\` = 80rem.
+
+Each control below lists its type, default/placeholder, any select options, and the CSS
+custom property it writes (when it drives one). Info notes flagged _Note:_ carry the
+modifier-class and structural guidance from the element itself.
+
+---
+`;
+function renderElementsDoc(elementsDir) {
+	const files = existsSync(elementsDir) ? readdirSync(elementsDir).filter((f) => f.endsWith(".php")) : [];
+	const elements = [];
+	for (const f of files) try {
+		const el = parseElement(readFileSync(join(elementsDir, f), "utf8"));
+		if (el) elements.push(el);
+	} catch {}
+	elements.sort((a, b) => {
+		const ia = ORDER.indexOf(a.name);
+		const ib = ORDER.indexOf(b.name);
+		if (ia >= 0 && ib >= 0) return ia - ib;
+		if (ia >= 0) return -1;
+		if (ib >= 0) return 1;
+		return a.name.localeCompare(b.name);
+	});
+	return `${ELEMENTS_PREAMBLE}\n${elements.map(renderElement).join("\n---\n\n")}`;
+}
+const code = (xs) => xs.map((x) => `\`${x}\``).join(", ");
+function renderCssClasses(ds) {
+	const palette = ds.colors.palette;
+	const ramps = Object.keys(palette);
+	const firstRamp = ramps[0];
+	const nonBase = (firstRamp ? Object.keys(palette[firstRamp] ?? {}) : []).filter((s) => s !== "base");
+	const roles = Object.keys(ds.colors.schemes.default?.semantic ?? {});
+	const utils = ds.colors.utilities ?? [
+		"bg",
+		"text",
+		"border"
+	];
+	const typeRoles = Object.keys(ds.typography?.roles ?? {});
+	const shadows = Object.keys(ds.shadows ?? {});
+	const effects = Object.keys(ds.animations?.effects ?? {});
+	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))));
+	const spaceNames = ds.spaceScale?.names ?? [];
+	const typeNames = ds.typeScale?.names ?? [];
+	const families = Object.keys(ds.typography?.families ?? {});
+	const radii = Object.keys(ds.patterns?.radii ?? {});
+	return `${frontmatter({
+		type: "CSS Framework Reference",
+		title: "Vitops CSS framework — class vocabulary",
+		description: "Every utility and component class in the Vitops CSS framework, stated as a naming rule over the design tokens it expands.",
+		resource: DS_PATH,
+		tags: [
+			"css",
+			"utilities",
+			"patterns",
+			"design-system"
+		]
+	})}
+
+# Vitops CSS framework — class vocabulary (LLM reference)
+
+A variable-driven CSS framework. Classes encode the design system's **tokens** (colour,
+type, space, shadow), **responsive grammar**, and **interaction states** — so styling with
+these classes stays consistent and theme-/dark-mode-aware. Prefer them over hand-written
+CSS or ad-hoc property values.
+
+This is a **rule reference**, not an exhaustive list: each family below is a naming rule
+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\`).
+
+## Responsive & state variant grammar
+
+Every utility accepts a **container-breakpoint prefix**; animation utilities also accept a
+**state prefix**. In CSS/Bricks the separator is \`-\`; in Tailwind it is \`:\` / \`@\`.
+
+| Intent            | CSS / Bricks               | Tailwind                                  |
+| ----------------- | -------------------------- | ----------------------------------------- |
+| responsive split  | \`md-split-1-2\`             | \`@md:split-1-2\`                           |
+| responsive align  | \`md-items-center\`         | \`@md:items-center\`                        |
+| hover effect      | \`transition hover-fade-in\` | \`transition fade-in hover:flip-fade-in\`   |
+
+- Breakpoint prefixes (bare): \`sm-\` = 30rem, \`md-\` = 48rem, \`lg-\` = 64rem, \`xl-\` = 80rem.
+- State prefixes (animation effects only): \`hover-\`, \`active-\`, \`focus-\`, and \`flip-<effect>\`
+  (plays the effect in reverse on toggle). Effects require \`transition\` on the element.
+
+## Layout & structure
+
+- **\`centered\`** — named-track grid centering content in the reading \`measure\` track.
+  Widen a **direct child** by adding \`breakout\`, \`spotlight\`, or \`fullbleed\` (each
+  breakpoint-prefixable) to that child. Track widths are set via \`--width-measure\` /
+  \`--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).
+- **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\`
+  (breakpoint-prefixable, e.g. \`md-hidden\`).
+- **Accessibility** — \`sr-only\` / \`not-sr-only\` (breakpoint-prefixable).
+- **State hooks** — \`is-active\`, \`is-open\` (styling flags toggled by JS / native state).
+
+## 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.
+
+## Typography
+
+Rule: **\`font-<role>\`** — role ∈ ${code(typeRoles)}. Each role carries its own family,
+size (from the type scale ${code(typeNames)}), tracking, transform, and weight.
+Families: ${code(families)} (\`--font-*\`).
+
+## Colour
+
+Rule: **\`<util>-<color>\`** — util ∈ ${code(utils)}; \`<color>\` is either a **named ramp**
+step or a **semantic role**.
+
+- Named ramps: ${code(ramps)}. Steps: base (no suffix) + ${code(nonBase)} — e.g. \`bg-pine\`
+  (base), \`text-navy-xl\`, \`border-grey-d\`.
+- Semantic roles: ${code(roles)} — e.g. \`bg-brand-primary\`, \`text-danger\`. Roles remap
+  automatically under \`:root[data-brx-theme="dark"]\`.
+
+## Shadows
+
+Rule: **\`drop-shadow-<size>\`** — size ∈ ${code(shadows)} (applied as a \`filter\`, so it
+follows non-rectangular shapes).
+
+## Animation
+
+Rule: **\`<effect>\`** (with the state/flip prefixes above) — effect ∈ ${code(effects)}.
+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.
+
+## 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>\`**.
+
+- Patterns: ${code(patterns)}.
+- Roles (for coloured patterns like \`badge\`, \`tag\`, \`status\`, \`button\`):
+  ${code(patternRoles)} — e.g. \`badge-success\`, \`button-danger\`. The default (unsuffixed)
+  variant uses the brand-primary role.
+- Shape primitives: \`--br-<name>\` radii — ${code(radii)}.
+`;
+}
+function renderTopIndex() {
+	return `${INDEX_NOTE}
+
+# Vitops design system
+
+LLM-oriented documentation bundle (Open Knowledge Format) for the Vitops design system — a
+variable-driven CSS framework plus progressively-enhanced web components, generated from
+\`design-system.json\` and published alongside the deployed theme.
+
+# Contents
+
+* [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 renderCssIndex() {
+	return `${INDEX_NOTE}
+
+# CSS framework
+
+# Contents
+
+* [Class vocabulary](classes.md) - every utility and component class, summarized by naming rule
+`;
+}
+function renderBricksIndex() {
+	return `${INDEX_NOTE}
+
+# Bricks Builder integration
+
+# Styling
+
+Prefer adding the framework **CSS classes** — see [/css/classes.md](../css/classes.md) — in a
+Bricks element's "CSS classes" field over hand-setting spacing, colour, or typography through
+the Bricks Builder property panels. The classes encode the design system's tokens, responsive
+grammar, and interaction states, so they stay consistent, respond to theme / dark mode, and
+update with the system. Values typed directly into Bricks' property controls are one-off,
+drift from the system, and don't react to theme changes — reserve them for genuinely bespoke,
+one-element cases.
+
+# Contents
+
+* [Elements reference](elements.md) - every custom Vitops element, its controls, defaults, seeded children and keywords
+* [Class vocabulary](../css/classes.md) - the framework CSS classes to apply to elements
+`;
+}
+/**
+* Build the OKF docs bundle for a config. Returns a `{ relPath: content }` map;
+* the caller writes it wherever the bundle should live (e.g. `<outDir>/docs`).
+*/
+function generateDocs(ds, assetsDir) {
+	const elementsDir = join(assetsDir, "bricks", "elements");
+	return {
+		"index.md": renderTopIndex(),
+		"css/index.md": renderCssIndex(),
+		"css/classes.md": renderCssClasses(ds),
+		"bricks/index.md": renderBricksIndex(),
+		"bricks/elements.md": renderElementsDoc(elementsDir)
+	};
+}
+
+//#endregion
+//#region src/generate.ts
+/**
+* Pure, parameterized port of the Vitops design-system generator.
+*
+* `generate({ input, format, outDir })` reads a consumer's `design-system.json`,
+* validates it, and emits consumer-ready output for the chosen format into
+* `outDir`. Unlike the original CWD-bound script it mutates no shared state: every
+* generated token layer is built in memory and either bundled (css/bricks) or
+* inlined (tailwind) before writing.
+*
+* Framework-static assets (the hand-written CSS partials, the Bricks PHP + loader,
+* and the pre-built JS bundles) live under `assets/` in this package and are read /
+* copied from there — they are the same for every consumer.
+*/
+const DEFAULT_ASSETS = join(dirname(fileURLToPath(import.meta.url)), "..", "assets");
+const STEP_ORDER = [
+	"xxd",
+	"xd",
+	"d",
+	"base",
+	"l",
+	"xl",
+	"xxl"
+];
+const suffix = (step) => step === "base" ? "" : `-${step}`;
+const MIRROR = {
+	xxd: "xxl",
+	xd: "xl",
+	d: "l",
+	base: "base",
+	l: "d",
+	xl: "xd",
+	xxl: "xxd"
+};
+const STEP_INDEX = Object.fromEntries(STEP_ORDER.map((s, i) => [s, i]));
+const shiftStep = (step, by) => {
+	const i = STEP_INDEX[step] ?? STEP_ORDER.indexOf("base");
+	return STEP_ORDER[Math.max(0, Math.min(STEP_ORDER.length - 1, i - by))];
+};
+const BASE_STEP = "d";
+const UTILITY_PROPS = {
+	bg: "background-color",
+	text: "color",
+	border: "border-color",
+	outline: "outline-color",
+	fill: "fill",
+	stroke: "stroke"
+};
+const roleRamp = (spec, inherited = "") => typeof spec === "string" ? spec : spec.ramp ?? inherited;
+const resolveSlot = (spec, step, inherited) => {
+	if (typeof spec === "string") return {
+		ramp: spec,
+		step
+	};
+	if (spec.value?.[step] != null) return { value: spec.value[step] };
+	return {
+		ramp: spec.ramp ?? inherited,
+		step: spec.steps?.[step] ?? shiftStep(spec.invert ? MIRROR[step] : step, spec.shift ?? 0)
+	};
+};
+const srcVar = (s) => "value" in s ? s.value : `var(--color-${s.ramp}${suffix(s.step)})`;
+const srcEq = (a, b) => "value" in a || "value" in b ? "value" in a && "value" in b && a.value === b.value : a.ramp === b.ramp && a.step === b.step;
+const decls = (obj, indent = "  ") => Object.entries(obj).map(([k, v]) => `${indent}${k}: ${v};`).join("\n");
+const round = (n) => Number(n.toFixed(4)).toString();
+const rem = (v) => parseFloat(v);
+const buildScale = (s) => {
+	const names = s.names ?? Array.from({ length: s.steps ?? 0 }, (_, i) => String(i + 1));
+	const base = rem(s.base);
+	const baseStep = s.baseStep ?? Math.ceil(names.length / 2);
+	const baselineIdx = s.baseline ? names.indexOf(s.baseline) : baseStep - 1;
+	return names.map((name, i) => {
+		const k = i - (baseStep - 1);
+		const vMax = base * Math.pow(s.ratio, k);
+		const max = `${round(vMax)}rem`;
+		let value = max;
+		if (s.fluid) {
+			const { minVw, maxVw, minRatio } = s.fluid;
+			const vMin = base * Math.pow(minRatio, k);
+			const lo = Math.min(vMin, vMax);
+			const hi = Math.max(vMin, vMax);
+			if (lo !== hi) {
+				const slope = (vMax - vMin) / (rem(maxVw) - rem(minVw));
+				const intercept = vMin - slope * rem(minVw);
+				const sign = slope < 0 ? "-" : "+";
+				const pref = `calc(${round(intercept)}rem ${sign} ${round(Math.abs(slope * 100))}vw)`;
+				value = `clamp(${round(lo)}rem, ${pref}, ${round(hi)}rem)`;
+			}
+		}
+		return {
+			name,
+			value,
+			max,
+			offset: i - baselineIdx
+		};
+	});
+};
+const TYPO_KEYMAP = {
+	family: ["font-family", "ff"],
+	size: ["font-size", "fs"],
+	weight: ["font-weight", "fw"],
+	style: ["font-style", "fst"],
+	"line-height": ["line-height", "lh"],
+	tracking: ["letter-spacing", "ls"],
+	"text-decoration": ["text-decoration", "td"],
+	"text-transform": ["text-transform", "tt"],
+	"text-wrap": ["text-wrap", "tw"],
+	color: ["color", "color"]
+};
+const TYPO_IDENTITY = {
+	"font-style": "normal",
+	"letter-spacing": "normal",
+	"text-decoration": "none",
+	"text-transform": "none",
+	"text-wrap": "wrap"
+};
+const STATE_DEFAULT = {
+	opacity: "1",
+	"translate-x": "0",
+	"translate-y": "0",
+	"scale-x": "1",
+	"scale-y": "1",
+	rotate: "0deg",
+	blur: "0px",
+	shadow: "0 0 0 transparent",
+	brightness: "1",
+	grayscale: "0",
+	contrast: "1",
+	saturate: "1",
+	sepia: "0",
+	"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";
+	const palette = ds.colors.palette;
+	const schemes = ds.colors.schemes;
+	const base = schemes.default;
+	if (base == null) throw new Error("colors.schemes must include a \"default\" scheme");
+	const defaultSemantic = base.semantic;
+	const altSchemes = Object.entries(schemes).filter(([k]) => k !== "default");
+	const darkScheme = altSchemes.map(([, s]) => s).find((s) => s.appearance === "dark");
+	const patterns = ds.patterns;
+	const shadows = ds.shadows;
+	const typography = ds.typography;
+	const UTILITIES = (ds.colors.utilities ?? [
+		"bg",
+		"text",
+		"border"
+	]).filter((u) => u in UTILITY_PROPS);
+	const generated = {};
+	if (BRICKS) generated["color.css"] = "/* Colours provided by Bricks (palette import generates tokens + utilities). */\n";
+	else {
+		let css = `/* GENERATED from design-system.json — do not edit by hand. */\n:root {\n`;
+		css += `  color-scheme: ${base.appearance};\n`;
+		css += `  /* Palette ramps */\n`;
+		for (const [name, steps] of Object.entries(palette)) for (const step of STEP_ORDER) if (steps[step] != null) css += `  --color-${name}${suffix(step)}: ${steps[step]};\n`;
+		css += `\n  /* Semantic roles → ramps (default: ${base.appearance}) */\n`;
+		for (const [role, spec] of Object.entries(defaultSemantic)) {
+			const ramp = roleRamp(spec);
+			for (const step of STEP_ORDER) if (palette[ramp]?.[step] != null) css += `  --color-${role}${suffix(step)}: ${srcVar(resolveSlot(spec, step, ramp))};\n`;
+		}
+		css += `}\n\n`;
+		for (const [key, scheme] of altSchemes) {
+			let block = "";
+			for (const [role, spec] of Object.entries(scheme.semantic)) {
+				const baseSpec = defaultSemantic[role];
+				if (baseSpec == null) continue;
+				const ramp = roleRamp(baseSpec);
+				for (const step of STEP_ORDER) {
+					if (palette[ramp]?.[step] == null) continue;
+					const alt = resolveSlot(spec, step, ramp);
+					if (srcEq(alt, resolveSlot(baseSpec, step, ramp))) continue;
+					block += `  --color-${role}${suffix(step)}: ${srcVar(alt)};\n`;
+				}
+			}
+			if (block) {
+				css += `/* Semantic roles → ramps (${key}: ${scheme.appearance}) */\n`;
+				css += `:root[data-brx-theme="${scheme.appearance}"] {\n  color-scheme: ${scheme.appearance};\n${block}}\n\n`;
+			}
+		}
+		const allTokens = [];
+		for (const [name, steps] of Object.entries(palette)) for (const step of STEP_ORDER) if (steps[step] != null) allTokens.push(`${name}${suffix(step)}`);
+		for (const [role, spec] of Object.entries(defaultSemantic)) {
+			const ramp = roleRamp(spec);
+			for (const step of STEP_ORDER) if (palette[ramp]?.[step] != null) allTokens.push(`${role}${suffix(step)}`);
+		}
+		css += `/* Colour utilities — ${UTILITIES.join(", ")} */\n`;
+		for (const token of allTokens) css += UTILITIES.map((cls) => `.${cls}-${token} { ${UTILITY_PROPS[cls]}: var(--color-${token}); }`).join("\n") + "\n";
+		generated["color.css"] = css;
+	}
+	{
+		const entries = Object.entries(shadows ?? {});
+		let sh = `/* GENERATED drop-shadow tokens + utilities — do not edit by hand. */\n`;
+		if (entries.length) {
+			sh += `:root {\n`;
+			for (const [name, value] of entries) sh += `  --shadow-${name}: ${value};\n`;
+			sh += `}\n\n`;
+			for (const [name] of entries) sh += `.drop-shadow-${name} { filter: drop-shadow(var(--shadow-${name})); }\n`;
+		}
+		generated["shadows.css"] = sh;
+	}
+	const typeSteps = ds.typeScale ? buildScale(ds.typeScale) : [];
+	const spaceSteps = ds.spaceScale ? buildScale(ds.spaceScale) : [];
+	const textMax = Object.fromEntries(typeSteps.map((s) => [`text-${s.name}`, s.max]));
+	const typographyFamilies = typography?.families ?? {};
+	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 = {};
+		for (const [key, [prop, sfx]] of Object.entries(TYPO_KEYMAP)) {
+			const identity = TYPO_IDENTITY[prop];
+			if (spec[key] == null && identity == null) continue;
+			out[prop] = `var(--${role}-${sfx}, ${spec[key] == null ? identity : key === "family" ? typographyFamilies[spec.family] ?? String(spec.family) : key === "size" ? withScaleFallback(String(spec[key])) : String(spec[key])})`;
+		}
+		return out;
+	};
+	let twTypeTokensCss = "";
+	if (BRICKS) generated["type-tokens.css"] = "/* Fonts + type/space scales provided by Bricks (Font + Variables managers). */\n";
+	else {
+		const root = {};
+		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`;
+		twTypeTokensCss = css;
+		generated["type-tokens.css"] = css;
+	}
+	let twPatternTokensCss = "";
+	{
+		const tDefaults = patterns?.defaults ?? {};
+		const tRadii = patterns?.radii ?? {};
+		const tGroups = patterns?.groups ?? {};
+		const tZ = patterns?.z ?? {};
+		const tItems = patterns?.items ?? {};
+		const root = {};
+		for (const [prop, val] of Object.entries(tDefaults)) root[`--${prop}-default`] = val;
+		if (!BRICKS) for (const [name, val] of Object.entries(tRadii)) root[`--br-${name}`] = val;
+		for (const [group, props] of Object.entries(tGroups)) for (const [prop, val] of Object.entries(props)) root[`--${prop}-${group}`] = val;
+		for (const [name, n] of Object.entries(tZ)) root[`--z-tier-${name}`] = String(n);
+		const aliases = {};
+		for (const [name, p] of Object.entries(tItems)) {
+			if (!p.group) continue;
+			for (const prop of Object.keys(tGroups[p.group] ?? {})) aliases[`--${prop}-${name}-group`] = `var(--${prop}-${p.group})`;
+			for (const [prop, val] of Object.entries(p.overrides ?? {})) aliases[`--${prop}-${name}-group`] = val;
+		}
+		let tok = `/* GENERATED pattern token cascade — do not edit by hand. */\n:root {\n`;
+		tok += decls(root) + "\n";
+		if (Object.keys(aliases).length) tok += "\n" + decls(aliases) + "\n";
+		tok += `}\n`;
+		twPatternTokensCss = tok;
+		generated["tokens.css"] = tok;
+	}
+	{
+		const roles = typography?.roles ?? {};
+		const headings = typography?.headings ?? {};
+		let typo = `/* GENERATED typography roles — do not edit by hand. */\n`;
+		for (const [role, spec] of Object.entries(roles)) typo += `.font-${role} {\n${decls(roleDecls(role, spec))}\n}\n`;
+		for (const [tag, role] of Object.entries(headings)) if (roles[role]) typo += `${tag} {\n${decls(roleDecls(role, roles[role]))}\n}\n`;
+		generated["typography.css"] = typo;
+	}
+	const stateRules = (sel, role, states, colorProp = "background-color") => {
+		let out = "";
+		const roleVar = (step) => role ? `var(--color-${role}-${step})` : "";
+		for (const [state, spec] of Object.entries(states)) {
+			const body = [];
+			if (typeof spec.step === "number" && role) body.push(`${colorProp}: ${roleVar(shiftStep(BASE_STEP, spec.step))};`);
+			if (typeof spec.scale === "number") body.push(`scale: ${spec.scale};`);
+			if (typeof spec.lift === "string") body.push(`translate: 0 calc(-1 * ${spec.lift});`);
+			if (typeof spec.shadow === "string" && shadows?.[spec.shadow]) body.push(`filter: drop-shadow(var(--shadow-${spec.shadow}));`);
+			else if (spec.shadow === true) body.push(`box-shadow: var(--lift-shadow, 0 8px 20px -6px rgb(0 0 0 / 0.25));`);
+			if (spec.ring === true) {
+				const ringColor = role ? `var(--color-${role}-l)` : `var(--color-brand-primary-l)`;
+				body.push(`outline: none;`, `box-shadow: 0 0 0 3px ${ringColor};`);
+			}
+			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 rule = `${sel}${state === "hover" ? ":hover" : state === "active" ? ":active" : state === "focus-visible" ? ":focus-visible" : `:${state}`} {\n  ${body.join("\n  ")}\n}\n`;
+			out += state === "hover" ? `@media (hover: hover) {\n${rule}}\n` : rule;
+		}
+		return out;
+	};
+	let pat = `/* GENERATED component patterns — do not edit by hand. */\n`;
+	pat += `/* Interaction transitions for patterned elements (independent props compose). */\n`;
+	for (const [pname, p] of Object.entries(patterns?.items ?? {})) {
+		if (!p.base) continue;
+		const states = p.states ?? {};
+		const isElement = !!p.element;
+		const defaultSel = isElement ? `:where(${p.element})` : `.${p.class ?? pname}`;
+		const defaultRole = p.default_role ?? null;
+		const base = { ...p.base };
+		const fills = pname === "button" || pname === "badge" || base["background-color"] != null || base["background"] != null;
+		const colorProp = fills ? "background-color" : "color";
+		pat += `${defaultSel} {\n`;
+		if (Object.keys(states).length > 0) {
+			pat += `  transition-property: translate, scale, rotate, filter, box-shadow, background-color, color;\n`;
+			pat += `  transition-duration: var(--interact-duration, 200ms);\n`;
+			pat += `  transition-timing-function: var(--interact-easing, ease);\n`;
+			pat += `  translate: 0 0; scale: 1; rotate: 0deg;\n`;
+		}
+		if (defaultRole && fills && base["background-color"] == null && base["background"] == null) base["background-color"] = `var(--color-${defaultRole}-${BASE_STEP})`;
+		const wrappedBase = {};
+		for (const [prop, val] of Object.entries(base)) {
+			const sfx = BASE_HOOK[prop];
+			wrappedBase[prop] = sfx ? `var(--${sfx}-${pname}, ${val})` : String(val);
+		}
+		pat += decls(wrappedBase) + "\n}\n";
+		pat += stateRules(defaultSel, defaultRole, states, colorProp);
+		for (const role of p.roles ?? []) {
+			const variantSel = isElement ? `${p.element}.${role}` : `.${p.class ?? pname}-${role}`;
+			const variantColorDecl = fills ? `background-color: var(--color-${role}-${BASE_STEP})` : `color: var(--color-${role}-${BASE_STEP})`;
+			pat += `${variantSel} { ${variantColorDecl}; }\n`;
+			pat += stateRules(variantSel, role, states, colorProp);
+		}
+		pat += "\n";
+	}
+	generated["patterns.css"] = pat;
+	{
+		const anim = ds.animations ?? {};
+		const asStr = (v) => String(v);
+		const block = (sel, d) => `.${sel} {\n${decls(d)}\n}\n`;
+		let out = `/* GENERATED animation effects + journeys — do not edit by hand. */\n`;
+		for (const [name, e] of Object.entries(anim.effects ?? {})) {
+			const d = { "--_anim": e.kf };
+			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);
+			out += block(name, d);
+		}
+		const base = anim.journeys?.base ?? {};
+		for (const parts of anim.journeys?.compose ?? []) {
+			const d = {
+				"--_anim": parts.map((p) => `${p}-journey`).join(", "),
+				"animation-range": "entry exit"
+			};
+			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`],
+			["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 [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;
+			}
+			const flip = Object.fromEntries(Object.keys(props).map((p) => [`--t-${p}`, `var(--${p}-to, ${STATE_DEFAULT[p]})`]));
+			if (Object.keys(rest).length) out += `${STATES.map(([s]) => `.${s}-${name}`).join(", ")} {\n${decls(rest)}\n}\n`;
+			for (const [s, sel] of STATES) out += `${sel(`${s}-${name}`)} {\n${decls(flip)}\n}\n`;
+		}
+		generated["animation-effects.css"] = out;
+	}
+	const namedColors = [];
+	for (const [name, steps] of Object.entries(palette)) for (const step of STEP_ORDER) {
+		const hex = steps[step];
+		if (hex == null) continue;
+		const token = `${name}${suffix(step)}`;
+		namedColors.push({
+			raw: `var(--color-${token})`,
+			light: hex,
+			id: id(`named:${token}`),
+			utilityClasses: UTILITIES
+		});
+	}
+	const semanticColors = [];
+	for (const [role, spec] of Object.entries(defaultSemantic)) {
+		const ramp = roleRamp(spec);
+		const altSpec = darkScheme?.semantic[role];
+		for (const step of STEP_ORDER) {
+			if (palette[ramp]?.[step] == null) continue;
+			const lightSrc = resolveSlot(spec, step, ramp);
+			const darkSrc = altSpec != null ? resolveSlot(altSpec, step, ramp) : lightSrc;
+			const hasDark = !srcEq(darkSrc, lightSrc);
+			semanticColors.push({
+				raw: `var(--color-${role}${suffix(step)})`,
+				light: srcVar(lightSrc),
+				darkModeEnabled: hasDark,
+				dark: srcVar(darkSrc),
+				id: id(`semantic:${role}${suffix(step)}`),
+				utilityClasses: UTILITIES
+			});
+		}
+	}
+	return {
+		generated,
+		bricksColorsNamed: JSON.stringify({
+			id: id("palette:named"),
+			name: "Named",
+			colors: namedColors
+		}, null, 2),
+		bricksColorsSemantic: JSON.stringify({
+			id: id("palette:semantic"),
+			name: "Semantic",
+			colors: semanticColors
+		}, null, 2),
+		bricksVariables: (() => {
+			const scaleMeta = (scope, prefix, s, names) => {
+				const px = Math.round(rem(s.base) * 16);
+				const lo = s.fluid?.minRatio ?? s.ratio;
+				return {
+					scaleScope: scope,
+					scaleType: "tshirt",
+					scaleNames: names,
+					prefix,
+					minFontSize: px,
+					minScaleRatio: lo,
+					minScaleRatioSelect: lo,
+					maxFontSize: px,
+					maxScaleRatio: s.ratio,
+					maxScaleRatioSelect: s.ratio,
+					baseline: s.baseline ?? names[Math.floor((names.length - 1) / 2)]
+				};
+			};
+			const categories = [];
+			const variables = [];
+			const addScale = (label, scope, prefix, cfg, steps) => {
+				if (!cfg || !steps.length) return;
+				const names = steps.map((s) => s.name);
+				const catId = id(`varcat:${scope}`);
+				categories.push({
+					id: catId,
+					name: label,
+					scale: scaleMeta(scope, prefix, cfg, names),
+					utilityClasses: []
+				});
+				for (const st of steps) variables.push({
+					id: id(`var:${prefix}${st.name}`),
+					name: `${prefix}${st.name}`,
+					value: st.value,
+					category: catId,
+					scale: {
+						scale: st.offset,
+						scaleName: st.name
+					}
+				});
+			};
+			addScale("Typography", "typography", "text-", ds.typeScale, typeSteps);
+			addScale("Spacing", "spacing", "space-", ds.spaceScale, spaceSteps);
+			for (const [name, stack] of Object.entries(ds.fonts ?? {})) variables.push({
+				id: id(`var:font-${name}`),
+				name: `font-${name}`,
+				value: stack
+			});
+			for (const [name, val] of Object.entries(ds.patterns?.radii ?? {})) variables.push({
+				id: id(`var:br-${name}`),
+				name: `br-${name}`,
+				value: val
+			});
+			return JSON.stringify({
+				variables,
+				categories
+			}, null, 2);
+		})(),
+		tokensJson: JSON.stringify({
+			colors: {
+				palette,
+				semantic: Object.fromEntries(Object.entries(defaultSemantic).map(([role, spec]) => [role, roleRamp(spec)]))
+			},
+			fonts: ds.fonts ?? {},
+			text: Object.fromEntries(typeSteps.map((s) => [s.name, s.value])),
+			spacing: Object.fromEntries(spaceSteps.map((s) => [s.name, s.value])),
+			shadows: shadows ?? {},
+			radii: ds.patterns?.radii ?? {}
+		}, null, 2),
+		designManifest: (() => {
+			const reverseIndex = {};
+			for (const [name, steps] of Object.entries(palette)) for (const step of STEP_ORDER) if (steps[step] != null) reverseIndex[`--color-${name}${suffix(step)}`] = `colors.palette.${name}.${step}`;
+			const colorRoles = Object.entries(defaultSemantic).map(([name, spec]) => ({
+				name,
+				ramp: roleRamp(spec)
+			}));
+			const typoRoles = typography?.roles ?? {};
+			const hooks = {};
+			for (const [key, [prop, sfx]] of Object.entries(TYPO_KEYMAP)) hooks[sfx] = {
+				prop,
+				key
+			};
+			for (const [role, spec] of Object.entries(typoRoles)) for (const [key, [, sfx]] of Object.entries(TYPO_KEYMAP)) if (spec[key] != null) reverseIndex[`--${role}-${sfx}`] = `typography.roles.${role}.${key}`;
+			const pDefaults = patterns?.defaults ?? {};
+			const pRadii = patterns?.radii ?? {};
+			const pGroups = patterns?.groups ?? {};
+			const pItems = patterns?.items ?? {};
+			for (const prop of Object.keys(pDefaults)) reverseIndex[`--${prop}-default`] = `patterns.defaults.${prop}`;
+			for (const name of Object.keys(pRadii)) reverseIndex[`--br-${name}`] = `patterns.radii.${name}`;
+			for (const [group, props] of Object.entries(pGroups)) for (const prop of Object.keys(props)) reverseIndex[`--${prop}-${group}`] = `patterns.groups.${group}.${prop}`;
+			const items = Object.entries(pItems).map(([name, p]) => {
+				const base = p.base ?? {};
+				const wrappable = Object.keys(base).filter((prop) => prop in BASE_HOOK).map((prop) => ({
+					sfx: BASE_HOOK[prop],
+					prop
+				}));
+				for (const { sfx, prop } of wrappable) reverseIndex[`--${sfx}-${name}`] = `patterns.items.${name}.base.${prop}`;
+				return {
+					name,
+					group: p.group ?? null,
+					base,
+					wrappable,
+					roles: p.roles ?? []
+				};
+			});
+			return JSON.stringify({
+				colors: {
+					ramps: Object.keys(palette),
+					steps: STEP_ORDER,
+					palette,
+					roles: colorRoles
+				},
+				typography: {
+					roles: Object.keys(typoRoles),
+					hooks,
+					families: typographyFamilies,
+					specs: typoRoles
+				},
+				scales: {
+					text: typeSteps.map((s) => ({
+						name: s.name,
+						value: s.value,
+						max: s.max
+					})),
+					space: spaceSteps.map((s) => ({
+						name: s.name,
+						value: s.value,
+						max: s.max
+					}))
+				},
+				fonts: ds.fonts ?? {},
+				patterns: {
+					defaults: pDefaults,
+					radii: pRadii,
+					groups: pGroups,
+					items
+				},
+				shadows: shadows ?? {},
+				interaction: {
+					duration: "200ms",
+					easing: "ease"
+				},
+				reverseIndex
+			}, null, 2);
+		})(),
+		tailwind: emitTailwind({
+			ds,
+			palette,
+			defaultSemantic,
+			darkScheme,
+			shadows,
+			typeSteps,
+			spaceSteps,
+			typography,
+			roleDecls,
+			twTypeTokensCss,
+			twPatternTokensCss,
+			patternsCss: pat,
+			assetsDir
+		}),
+		twTypeTokensCss,
+		twPatternTokensCss,
+		patternsCss: pat
+	};
+}
+function emitTailwind(ctx) {
+	const { ds, palette, defaultSemantic, darkScheme, shadows, typeSteps, spaceSteps, typography, roleDecls, twTypeTokensCss, twPatternTokensCss, patternsCss, assetsDir } = 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. */`];
+	parts.push(`@import "tailwindcss";\n`);
+	const theme = [];
+	theme.push(`  /* Colour ramps → bg-* text-* border-* */`);
+	for (const [name, steps] of Object.entries(palette)) for (const step of STEP_ORDER) if (steps[step] != null) theme.push(`  --color-${name}${suffix(step)}: ${steps[step]};`);
+	theme.push(`\n  /* Semantic roles → ramps (default scheme) */`);
+	for (const [role, spec] of Object.entries(defaultSemantic)) {
+		const ramp = roleRamp(spec);
+		for (const step of STEP_ORDER) if (palette[ramp]?.[step] != null) theme.push(`  --color-${role}${suffix(step)}: ${srcVar(resolveSlot(spec, step, ramp))};`);
+	}
+	theme.push(`\n  /* Fonts → font-* */`);
+	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  /* Fluid spacing scale → p-* m-* gap-* */`);
+	for (const s of spaceSteps) theme.push(`  --spacing-${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};`);
+	parts.push(`@theme {\n${theme.join("\n")}\n}\n`);
+	parts.push(`/* ── Framework tokens (consumed by the inlined components) ── */\n${twTypeTokensCss}\n${twPatternTokensCss}`);
+	let darkBlock = "";
+	if (darkScheme) for (const [role, spec] of Object.entries(darkScheme.semantic)) {
+		const baseSpec = defaultSemantic[role];
+		if (baseSpec == null) continue;
+		const ramp = roleRamp(baseSpec);
+		for (const step of STEP_ORDER) {
+			if (palette[ramp]?.[step] == null) continue;
+			const alt = resolveSlot(spec, step, ramp);
+			if (srcEq(alt, resolveSlot(baseSpec, step, ramp))) continue;
+			darkBlock += `  --color-${role}${suffix(step)}: ${srcVar(alt)};\n`;
+		}
+	}
+	if (darkBlock && darkScheme) parts.push(`/* Dark-mode semantic overrides */\n:root[data-brx-theme="${darkScheme.appearance}"] {\n${darkBlock}}\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 util = [];
+	util.push(`/* Typography roles */`);
+	for (const [role, spec] of Object.entries(typography?.roles ?? {})) util.push(`@utility font-${role} {\n${decls(roleDecls(role, spec))}\n}`);
+	util.push(`\n/* Animation effects (pair with .transition or a driver) */`);
+	const asStr = (v) => String(v);
+	for (const [name, e] of Object.entries(ds.animations?.effects ?? {})) {
+		const d = { "--_anim": e.kf };
+		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);
+			if (m) props.add(m[1]);
+		}
+		const flip = Object.fromEntries([...props].map((p) => [`--t-${p}`, `var(--${p}-to, ${STATE_DEFAULT[p]})`]));
+		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}");
+	for (const [a, b] of [
+		[1, 2],
+		[2, 1],
+		[1, 3],
+		[3, 1],
+		[1, 4],
+		[4, 1],
+		[2, 3],
+		[3, 2]
+	]) util.push(`@utility split-${a}-${b} {\n  --_split-a: ${a};\n  --_split-b: ${b};\n}`);
+	util.push(`\n/* Track placement (inside .centered) */`);
+	for (const track of [
+		"measure",
+		"breakout",
+		"spotlight",
+		"fullbleed"
+	]) util.push(`@utility ${track} {\n  grid-column: ${track};\n}`);
+	parts.push(util.join("\n") + "\n");
+	parts.push(`/* ── Structure (mirrors src/css/layout.css) ── */
+:root {
+  --rhythm-scale: 1;
+  --rhythm-base: calc(1rlh * var(--rhythm-scale));
+  --rhythm-h-p: 0.4;
+  --rhythm-p-p: 0.9;
+  --rhythm-p-h: 1.6;
+  --rhythm-h-h: 0.6;
+  --rhythm-p-list: 0.5;
+  --rhythm-list-p: 0.9;
+  --rhythm-li-li: 0.3;
+  --rhythm-text-media: 1.2;
+  --rhythm-media-text: 1.2;
+  --width-measure: 65ch;
+  --width-breakout: 90ch;
+  --width-spotlight: 120ch;
+  --gutter: clamp(1rem, 4cqi, 3rem);
+}
+
+body {
+  container-type: inline-size;
+}
+
+.rhythm {
+  display: flow-root;
+}
+.rhythm > * + * {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-p-p));
+}
+.rhythm > :where(h1, h2, h3, h4, h5, h6) + p {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-h-p));
+}
+.rhythm > p + :where(h1, h2, h3, h4, h5, h6) {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-p-h));
+}
+.rhythm > :where(h1, h2, h3, h4, h5, h6) + :where(h1, h2, h3, h4, h5, h6) {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-h-h));
+}
+.rhythm > p + :where(ul, ol) {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-p-list));
+}
+.rhythm > :where(ul, ol) + p {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-list-p));
+}
+.rhythm :where(ul, ol) > li + li {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-li-li));
+}
+.rhythm > :where(p, h1, h2, h3, h4, h5, h6, ul, ol) + :where(figure, img, picture, video) {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-text-media));
+}
+.rhythm > :where(figure, img, picture, video) + :where(p, h1, h2, h3, h4, h5, h6, ul, ol) {
+  margin-top: calc(var(--rhythm-base) * var(--rhythm-media-text));
+}
+
+.centered {
+  --_measure: min(var(--width-measure), 100% - var(--gutter) * 2);
+  --_breakout: minmax(0, calc((var(--width-breakout) - var(--width-measure)) / 2));
+  --_spotlight: minmax(0, calc((var(--width-spotlight) - var(--width-breakout)) / 2));
+  position: relative;
+  display: grid;
+  grid-template-columns:
+    [fullbleed-start] minmax(var(--gutter), 1fr)
+    [spotlight-start] var(--_spotlight)
+    [breakout-start] var(--_breakout)
+    [measure-start] var(--_measure) [measure-end]
+    var(--_breakout) [breakout-end]
+    var(--_spotlight) [spotlight-end]
+    minmax(var(--gutter), 1fr) [fullbleed-end];
+}
+.centered > * {
+  grid-column: measure;
+}
+
+.region {
+  padding-block: clamp(
+    var(--region-space-min, 3rem),
+    var(--region-space, 8vh),
+    var(--region-space-max, 8rem)
+  );
+}
+`);
+	const animEngine = readFileSync(join(cssDir, "animation.css"), "utf8");
+	parts.push(`/* ── Animation engine (animation.css) ── */\n${animEngine}`);
+	parts.push(`/* ── Component patterns ── */\n${patternsCss}`);
+	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) => {
+		const kept = [];
+		let depth = 0;
+		let start = 0;
+		let preludeEnd = -1;
+		for (let i = 0; i < css.length; i++) {
+			const ch = css[i];
+			if (ch === "/" && css[i + 1] === "*") {
+				const end = css.indexOf("*/", i + 2);
+				i = end === -1 ? css.length : end + 1;
+				continue;
+			}
+			if (ch === "\"" || ch === "'") {
+				i += 1;
+				while (i < css.length && css[i] !== ch) i += css[i] === "\\" ? 2 : 1;
+				continue;
+			}
+			if (ch === "{") {
+				if (depth === 0) preludeEnd = i;
+				depth++;
+			} else if (ch === "}") {
+				depth--;
+				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);
+					if (/^@container\s*\(\s*min-width:/.test(prelude)) droppedVariantBlocks++;
+					else if (clash && TW_CLASH.has(clash[1])) droppedClashes.add(clash[1]);
+					else if (raw) kept.push(raw);
+					start = i + 1;
+				}
+			}
+		}
+		return kept.join("\n\n");
+	};
+	const componentCss = componentPartialOrder(cssDir).map((rel) => {
+		return `/* ── ${rel} ── */\n${stripForTailwind(readFileSync(join(cssDir, rel), "utf8"))}`;
+	}).join("\n\n");
+	parts.push(`/* ── Component + structural partials (Tailwind-clashing utilities dropped) ── */\n${componentCss}`);
+	return nl(parts) + "\n";
+}
+/**
+* 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).
+*/
+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 (!seen.has(rel) && existsSync(join(cssDir, rel))) {
+			seen.add(rel);
+			order.push(rel);
+		}
+	}
+	if (!order.length) {
+		if (existsSync(join(cssDir, "utilities.css"))) order.push("utilities.css");
+		const pdir = join(cssDir, "patterns");
+		if (existsSync(pdir)) {
+			for (const f of readdirSync(pdir).sort()) if (f.endsWith(".css")) order.push(`patterns/${f}`);
+		}
+	}
+	return order;
+}
+/**
+* Assemble the full stylesheet by resolving index.css's @import order against the
+* static partials (from assets) and the freshly generated token partials (in
+* memory), then minify with lightningcss. No @import survives, so no disk
+* resolution / shared `generated/` dir is needed.
+*/
+function bundleCss(generated, assetsDir, minify) {
+	const cssDir = join(assetsDir, "css");
+	const index = readFileSync(join(cssDir, "index.css"), "utf8");
+	const chunks = [];
+	for (const line of index.split("\n")) {
+		const m = /@import\s+['"]\.\/([^'"]+)['"]/.exec(line);
+		if (!m) continue;
+		const rel = m[1];
+		if (rel.startsWith("generated/")) {
+			const name = rel.slice(10);
+			chunks.push(generated[name] ?? "");
+		} else chunks.push(readFileSync(join(cssDir, rel), "utf8"));
+	}
+	const merged = chunks.join("\n");
+	const res = transform({
+		filename: "styles.css",
+		code: Buffer.from(merged),
+		minify,
+		sourceMap: minify
+	});
+	return {
+		code: res.code.toString(),
+		map: res.map ? res.map.toString() : void 0
+	};
+}
+function loadConfig(input) {
+	const result = validate(typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input);
+	if (!result.ok) {
+		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}`);
+	}
+	return result.data;
+}
+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);
+	mkdirSync(outDir, { recursive: true });
+	const written = [];
+	const put = (rel, content) => {
+		const p = join(outDir, rel);
+		mkdirSync(dirname(p), { recursive: true });
+		writeFileSync(p, content);
+		written.push(p);
+	};
+	if (format === "tailwind") {
+		put("tailwind.css", built.tailwind);
+		put("tokens.json", built.tokensJson);
+	} else if (format === "css") {
+		const { code } = bundleCss(built.generated, assetsDir, true);
+		put("styles.css", code);
+		put("tokens.json", built.tokensJson);
+		put("design-manifest.json", built.designManifest);
+	} else {
+		const { code, map } = bundleCss(built.generated, assetsDir, true);
+		put("styles.min.css", map ? code + `\n/*# sourceMappingURL=styles.min.css.map */` : code);
+		if (map) put("styles.min.css.map", map);
+		put("bricks-colors-named.json", built.bricksColorsNamed);
+		put("bricks-colors-semantic.json", built.bricksColorsSemantic);
+		put("bricks-variables.json", built.bricksVariables);
+		put("tokens.json", built.tokensJson);
+		const jsDir = join(assetsDir, "js");
+		if (existsSync(jsDir)) {
+			cpSync(jsDir, outDir, { recursive: true });
+			for (const f of readdirSync(jsDir)) written.push(join(outDir, f));
+		}
+		const bricksSrc = join(assetsDir, "bricks");
+		if (existsSync(bricksSrc)) {
+			cpSync(bricksSrc, join(outDir, "bricks"), { recursive: true });
+			written.push(join(outDir, "bricks"));
+		}
+		const docs = generateDocs(ds, assetsDir);
+		for (const [rel, content] of Object.entries(docs)) put(join("docs", rel), content);
+	}
+	return {
+		format,
+		outDir,
+		written
+	};
+}
+
+//#endregion
+//#region src/site.ts
+/**
+* Company / site-level configuration schema — the umbrella around a
+* `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
+* 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`).
+*
+* 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 ImageRefSchema = z.union([z.string(), z.object({
+	src: z.string(),
+	alt: z.string(),
+	width: z.optional(z.number()),
+	height: z.optional(z.number())
+})]);
+const AttrValue = z.union([
+	z.string(),
+	z.number(),
+	z.boolean()
+]);
+const AttrsSchema = z.optional(z.record(z.string(), AttrValue));
+const IsoDate = z.string().check(z.regex(/^\d{4}-\d{2}-\d{2}$/));
+const Iso4217 = z.string().check(z.regex(/^[A-Z]{3}$/));
+const DayOfWeek = z.enum([
+	"Monday",
+	"Tuesday",
+	"Wednesday",
+	"Thursday",
+	"Friday",
+	"Saturday",
+	"Sunday"
+]);
+const DesignSystemEntry = z.extend(DesignSystemPatchSchema, {
+	displayName: z.optional(LocalizableSchema),
+	extends: z.optional(z.string())
+});
+const LocaleSchema = z.object({
+	name: z.string(),
+	tagline: z.optional(z.string()),
+	basePath: z.optional(z.string())
+});
+const HttpRedirect = z.union([
+	z.literal(301),
+	z.literal(302),
+	z.literal(307),
+	z.literal(308)
+]);
+const DomainAliasSchema = z.object({
+	domain: z.string(),
+	redirectType: HttpRedirect,
+	redirectTo: z.string(),
+	environment: z.optional(z.string())
+});
+/** schema.org `PostalAddress` field names, so JSON-LD generation is lossless. */
+const PostalAddressSchema = z.object({
+	streetAddress: z.string(),
+	addressLocality: z.string(),
+	addressRegion: z.optional(z.string()),
+	postalCode: z.optional(z.string()),
+	addressCountry: z.string()
+});
+const ContactObjectSchema = z.object({
+	name: z.optional(z.string()),
+	email: z.optional(z.email()),
+	phone: z.optional(z.string()),
+	address: z.optional(PostalAddressSchema)
+});
+const ContactConfigSchema = z.union([z.string(), ContactObjectSchema]);
+const GeoSchema = z.object({
+	latitude: z.number().check(z.gte(-90), z.lte(90)),
+	longitude: z.number().check(z.gte(-180), z.lte(180))
+});
+/** schema.org `OpeningHoursSpecification` — per-day open/close (24h `HH:MM`). */
+const OpeningHoursSchema = z.object({
+	dayOfWeek: z.array(DayOfWeek),
+	opens: z.string().check(z.regex(/^\d{2}:\d{2}$/)),
+	closes: z.string().check(z.regex(/^\d{2}:\d{2}$/))
+});
+const LocalBusinessType = z.enum([
+	"LocalBusiness",
+	"Store",
+	"Restaurant",
+	"CafeOrCoffeeShop",
+	"ProfessionalService",
+	"MedicalBusiness",
+	"HealthAndBeautyBusiness",
+	"HomeAndConstructionBusiness",
+	"AutomotiveBusiness",
+	"FinancialService",
+	"LegalService",
+	"RealEstateAgent",
+	"Organization"
+]);
+const LocationSchema = z.object({
+	slug: z.optional(LocalizableSchema),
+	name: LocalizableSchema,
+	email: z.optional(z.email()),
+	phone: z.optional(z.string()),
+	address: z.optional(PostalAddressSchema),
+	geo: z.optional(GeoSchema),
+	hours: z.optional(z.array(OpeningHoursSchema)),
+	type: z.optional(LocalBusinessType),
+	description: z.optional(LocalizableSchema),
+	areaServed: z.optional(z.array(z.string())),
+	priceRange: z.optional(z.string()),
+	paymentAccepted: z.optional(z.array(z.string())),
+	currenciesAccepted: z.optional(Iso4217),
+	knowsLanguage: z.optional(z.array(z.string()))
+});
+const OrganizationSchema = z.object({
+	name: z.optional(LocalizableSchema),
+	legalName: z.optional(z.string()),
+	foundingDate: z.optional(IsoDate),
+	logo: z.optional(ImageRefSchema),
+	email: z.optional(z.email()),
+	phone: z.optional(z.string()),
+	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()))
+});
+const DnsRecordType = z.enum([
+	"A",
+	"AAAA",
+	"CNAME",
+	"TXT",
+	"MX",
+	"NS",
+	"SRV",
+	"CAA",
+	"PTR",
+	"SOA"
+]);
+const DnsRecordSchema = z.object({
+	type: DnsRecordType,
+	name: z.optional(z.string()),
+	value: z.string(),
+	ttl: z.optional(z.number().check(z.int(), z.positive())),
+	proxied: z.optional(z.boolean())
+});
+const DnsDomainSchema = z.object({
+	provider: z.optional(z.string()),
+	nameservers: z.optional(z.array(z.string())),
+	records: z.optional(z.array(DnsRecordSchema))
+});
+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())
+});
+const AbVariantSchema = z.object({
+	environment: z.string(),
+	description: z.optional(z.string()),
+	overrides: z.optional(z.record(z.string(), z.unknown()))
+});
+const FontProvider = z.enum([
+	"google",
+	"fontsource",
+	"adobe",
+	"bunny",
+	"fontshare",
+	"googleicons",
+	"npm",
+	"local"
+]);
+const FontStyle = z.enum(["normal", "italic"]);
+const FontDisplay = z.enum([
+	"auto",
+	"block",
+	"swap",
+	"fallback",
+	"optional"
+]);
+const FontWeight = z.union([z.number(), z.string()]);
+/** A local-font face (`provider: 'local'`). */
+const FontVariantSchema = z.object({
+	src: z.array(z.string()),
+	weight: z.optional(FontWeight),
+	style: z.optional(FontStyle),
+	unicodeRange: z.optional(z.array(z.string())),
+	display: z.optional(FontDisplay)
+});
+const FontSchema = z.object({
+	name: z.string(),
+	provider: FontProvider,
+	cssVariable: z.string().check(z.regex(/^--/)),
+	weights: z.optional(z.array(FontWeight)),
+	styles: z.optional(z.array(FontStyle)),
+	subsets: z.optional(z.array(z.string())),
+	fallbacks: z.optional(z.array(z.string())),
+	optimizedFallbacks: z.optional(z.boolean()),
+	display: z.optional(FontDisplay),
+	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({
+		weight: FontWeight,
+		style: z.optional(FontStyle)
+	}))]))
+});
+const PresentSchema = z.optional(z.record(z.string(), z.unknown()));
+const NavItemSchema = z.object({
+	label: z.optional(LocalizableSchema),
+	image: z.optional(ImageRefSchema),
+	href: z.optional(z.string()),
+	icon: z.optional(z.string()),
+	attrs: AttrsSchema,
+	itemAttrs: AttrsSchema,
+	submenu: z.optional(z.object({
+		present: PresentSchema,
+		get items() {
+			return z.optional(z.array(NavItemSchema));
+		}
+	}))
+});
+const FormFieldType = z.enum([
+	"text",
+	"email",
+	"tel",
+	"url",
+	"number",
+	"password",
+	"textarea",
+	"select",
+	"checkbox",
+	"radio",
+	"date",
+	"file",
+	"hidden"
+]);
+const FormFieldSchema = z.object({
+	name: z.string(),
+	type: FormFieldType,
+	label: z.optional(LocalizableSchema),
+	required: z.optional(z.boolean()),
+	validation: z.optional(z.string()),
+	options: z.optional(z.union([z.string(), z.array(z.object({
+		label: z.string(),
+		value: z.string()
+	}))])),
+	attrs: AttrsSchema
+});
+const ContentNodeSchema = z.object({
+	tag: z.string(),
+	attrs: AttrsSchema,
+	text: z.optional(z.string()),
+	get children() {
+		return z.optional(z.array(ContentNodeSchema));
+	}
+});
+const TemplateSchema = z.union([
+	z.object({
+		type: z.literal("nav"),
+		tags: z.optional(z.array(z.string())),
+		present: PresentSchema,
+		items: z.optional(z.array(NavItemSchema))
+	}),
+	z.object({
+		type: z.literal("form"),
+		tags: z.optional(z.array(z.string())),
+		present: PresentSchema,
+		action: z.optional(z.string()),
+		method: z.optional(z.enum(["get", "post"])),
+		fields: z.optional(z.array(FormFieldSchema)),
+		submit: z.optional(z.record(z.string(), AttrValue)),
+		honeypot: z.optional(z.boolean())
+	}),
+	z.object({
+		type: z.literal("nodes"),
+		tags: z.optional(z.array(z.string())),
+		nodes: z.optional(z.array(ContentNodeSchema))
+	})
+]);
+const GalleryImageSchema = z.object({
+	src: z.string(),
+	alt: LocalizableSchema,
+	caption: z.optional(LocalizableSchema)
+});
+const GallerySchema = z.object({
+	title: z.optional(LocalizableSchema),
+	tags: z.optional(z.array(z.string())),
+	images: z.array(GalleryImageSchema)
+});
+const TestimonialItemSchema = z.object({
+	quote: LocalizableSchema,
+	name: z.string(),
+	role: z.optional(z.string()),
+	rating: z.optional(z.number().check(z.gte(0), z.lte(5))),
+	date: z.optional(IsoDate)
+});
+const TestimonialGroupSchema = z.object({
+	title: z.optional(LocalizableSchema),
+	items: z.array(TestimonialItemSchema)
+});
+const OfferSchema = z.object({
+	name: z.optional(LocalizableSchema),
+	price: z.optional(z.union([z.string(), z.number()])),
+	priceCurrency: z.optional(Iso4217),
+	availability: z.optional(z.string()),
+	url: z.optional(z.url()),
+	validFrom: z.optional(IsoDate),
+	priceValidUntil: z.optional(IsoDate)
+});
+const ServiceSchema = z.object({
+	name: LocalizableSchema,
+	description: z.optional(LocalizableSchema),
+	slug: z.optional(LocalizableSchema),
+	offers: z.optional(z.array(OfferSchema))
+});
+const OpenGraphSchema = z.object({
+	type: z.optional(z.string()),
+	siteName: z.optional(z.string()),
+	title: z.optional(LocalizableSchema),
+	description: z.optional(LocalizableSchema),
+	image: z.optional(ImageRefSchema),
+	locale: z.optional(z.string())
+});
+const TwitterSchema = z.object({
+	card: z.optional(z.enum([
+		"summary",
+		"summary_large_image",
+		"app",
+		"player"
+	])),
+	site: z.optional(z.string()),
+	creator: z.optional(z.string()),
+	title: z.optional(LocalizableSchema),
+	description: z.optional(LocalizableSchema),
+	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({
+		googleMaps: z.optional(z.url()),
+		instagram: z.optional(z.url()),
+		facebook: z.optional(z.url()),
+		x: z.optional(z.url()),
+		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({
+		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()),
+		descriptionTemplate: z.optional(z.string()),
+		robots: z.optional(RobotsSchema),
+		googleSiteVerification: z.optional(z.string()),
+		bingSiteVerification: z.optional(z.string()),
+		openGraph: z.optional(OpenGraphSchema),
+		twitter: z.optional(TwitterSchema)
+	})),
+	analytics: 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({
+		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({
+		privacyPolicy: z.optional(z.object({
+			enabled: z.boolean(),
+			url: z.optional(z.url()),
+			lastUpdated: z.optional(IsoDate)
+		})),
+		termsOfService: z.optional(z.object({
+			enabled: z.boolean(),
+			url: z.optional(z.url()),
+			lastUpdated: z.optional(z.nullable(IsoDate))
+		})),
+		cookieConsent: z.optional(z.object({
+			enabled: z.boolean(),
+			type: z.optional(z.enum(["opt-in", "opt-out"])),
+			position: z.optional(z.enum([
+				"top",
+				"bottom",
+				"center"
+			])),
+			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())),
+		"fa7-solid": z.optional(z.array(z.string())),
+		"fa7-regular": z.optional(z.array(z.string())),
+		"fa7-light": z.optional(z.array(z.string())),
+		"fa7-thin": z.optional(z.array(z.string())),
+		"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()))
+	})),
+	favicon: z.optional(z.object({
+		source: z.string(),
+		lowResSource: z.optional(z.string())
+	})),
+	deployment: 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())
+	}))
+});
+const SITE_SCHEMA_URL = "https://unpkg.com/@getvitops/generator/site.schema.json";
+/** The published JSON Schema (draft-2020-12), derived from the zod schema. */
+const siteJsonSchema = {
+	$id: SITE_SCHEMA_URL,
+	...z.toJSONSchema(SiteConfigSchema, { target: "draft-2020-12" })
+};
+const issue = (path, message) => ({
+	code: "custom",
+	path,
+	message
+});
+/**
+* Validate a raw (already parsed) config: shape via zod, then the cross-field
+* integrity that JSON Schema can't express (referential keys, extends acyclicity).
+* These live only here — the published JSON Schema enforces shape, not integrity.
+*/
+function validateSite(input) {
+	const parsed = z.safeParse(SiteConfigSchema, input);
+	if (!parsed.success) return {
+		ok: false,
+		data: void 0,
+		errors: parsed.error.issues
+	};
+	const cfg = parsed.data;
+	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([
+		"designSystem",
+		key,
+		"extends"
+	], `extends "${entry.extends}" is not a designSystem key`));
+	for (const key of Object.keys(cfg.designSystem)) try {
+		resolveTheme(cfg.designSystem, key);
+	} catch (e) {
+		errors.push(issue(["designSystem", 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`));
+	for (const [name, v] of Object.entries(cfg.abTesting?.variants ?? {})) if (!has(cfg.environments, v.environment)) errors.push(issue([
+		"abTesting",
+		"variants",
+		name,
+		"environment"
+	], `environment "${v.environment}" is not in environments`));
+	for (const [i, a] of (cfg.domains?.aliases ?? []).entries()) if (a.environment != null && !has(cfg.environments, a.environment)) errors.push(issue([
+		"domains",
+		"aliases",
+		i,
+		"environment"
+	], `environment "${a.environment}" is not in environments`));
+	const templates = cfg.templates;
+	const at = cfg.navigation?.activeTemplate;
+	if (at?.default != null && !has(templates, at.default)) errors.push(issue([
+		"navigation",
+		"activeTemplate",
+		"default"
+	], `template "${at.default}" is not in templates`));
+	for (const [bp, tpl] of Object.entries(at?.breakpoints ?? {})) if (!has(templates, tpl)) errors.push(issue([
+		"navigation",
+		"activeTemplate",
+		"breakpoints",
+		bp
+	], `template "${tpl}" is not in templates`));
+	if (errors.length) return {
+		ok: false,
+		data: void 0,
+		errors
+	};
+	return {
+		ok: true,
+		data: cfg,
+		errors: []
+	};
+}
+/**
+* Resolve a design-system theme by following its `extends` chain and deep-merging
+* base → child (child wins; arrays replace wholesale, correct for token overrides).
+* Throws on unknown keys or an `extends` cycle. The result is a plain
+* `DesignSystem` (validate it against `DesignSystemSchema` for completeness).
+*/
+function resolveTheme(designSystem, key) {
+	const chain = [];
+	const seen = /* @__PURE__ */ new Set();
+	let cur = key;
+	while (cur != null) {
+		if (seen.has(cur)) throw new Error(`extends cycle in designSystem at "${cur}"`);
+		seen.add(cur);
+		const entry = designSystem[cur];
+		if (entry == null) throw new Error(`designSystem theme "${cur}" not found`);
+		chain.unshift(entry);
+		cur = entry.extends;
+	}
+	const out = {};
+	for (const entry of chain) {
+		const { extends: _e, displayName: _d, ...ds } = entry;
+		deepMerge(out, ds);
+	}
+	return out;
+}
+/**
+* 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: … }`,
+*  4. validate (shape + cross-field).
+* Pure — no YAML/env access. A loader supplies `siteEnv`.
+*/
+function resolveSiteConfig(input, siteEnv = "production") {
+	const raw = stripNulls(input);
+	const envConfig = raw.environments?.[siteEnv];
+	if (envConfig?.variant) {
+		const overrides = raw.abTesting?.variants?.[envConfig.variant]?.overrides;
+		if (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");
+		throw new Error(`Invalid site config:\n${msg}`);
+	}
+	return result.data;
+}
+/** Strip nulls (YAML `~`/`null`) → undefined so optional fields validate. */
+function stripNulls(obj) {
+	if (obj === null) return void 0;
+	if (Array.isArray(obj)) return obj.map(stripNulls);
+	if (obj && typeof obj === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) {
+			const stripped = stripNulls(value);
+			if (stripped !== void 0) result[key] = stripped;
+		}
+		return result;
+	}
+	return obj;
+}
+/** Deep-merge `source` into `target` (in place). Arrays replace wholesale. */
+function deepMerge(target, source) {
+	for (const key of Object.keys(source)) {
+		const s = source[key];
+		const t = target[key];
+		if (s && typeof s === "object" && !Array.isArray(s) && t && typeof t === "object" && !Array.isArray(t)) deepMerge(t, s);
+		else target[key] = s;
+	}
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* A minimal but complete starter design system, used by `vitops init`. It
+* validates against the schema and generates real output in every format, so a
+* new project can `vitops generate` immediately and then tune from here.
+*/
+function defaultConfig() {
+	return {
+		$schema: SCHEMA_URL,
+		colors: {
+			palette: {
+				brand: {
+					xxd: "#0a1f17",
+					xd: "#123a2b",
+					d: "#1f6b4f",
+					base: "#2e9b73",
+					l: "#5cbf9a",
+					xl: "#93dcc0",
+					xxl: "#c8f0e2"
+				},
+				ink: {
+					xxd: "#0b0e13",
+					xd: "#151a22",
+					d: "#2a323f",
+					base: "#3f4a5c",
+					l: "#6b7688",
+					xl: "#a3abb8",
+					xxl: "#d7dbe2"
+				}
+			},
+			utilities: [
+				"bg",
+				"text",
+				"border"
+			],
+			schemes: {
+				default: {
+					appearance: "light",
+					semantic: {
+						"brand-primary": "brand",
+						surface: "ink",
+						neutral: "ink"
+					}
+				},
+				alternate: {
+					appearance: "dark",
+					semantic: {
+						surface: { invert: true },
+						neutral: { invert: true }
+					}
+				}
+			}
+		},
+		shadows: {
+			sm: "0 1px 2px rgb(0 0 0 / 0.08)",
+			md: "0 4px 6px rgb(0 0 0 / 0.12)",
+			lg: "0 10px 15px rgb(0 0 0 / 0.18)"
+		},
+		fonts: {
+			display: "system-ui, -apple-system, \"Segoe UI\", sans-serif",
+			sans: "system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif",
+			mono: "ui-monospace, \"SF Mono\", Menlo, monospace"
+		},
+		typeScale: {
+			base: "1rem",
+			names: [
+				"2xs",
+				"xs",
+				"s",
+				"m",
+				"l",
+				"xl",
+				"2xl",
+				"3xl"
+			],
+			baseStep: 4,
+			baseline: "m",
+			ratio: 1.2,
+			fluid: {
+				minVw: "22.5rem",
+				maxVw: "80rem",
+				minRatio: 1.12
+			}
+		},
+		spaceScale: {
+			base: "1rem",
+			names: [
+				"2xs",
+				"xs",
+				"s",
+				"m",
+				"l",
+				"xl",
+				"2xl",
+				"3xl"
+			],
+			baseStep: 4,
+			baseline: "m",
+			ratio: 1.25,
+			fluid: {
+				minVw: "22.5rem",
+				maxVw: "80rem",
+				minRatio: 1.2
+			}
+		},
+		patterns: {
+			defaults: {
+				ds: "none",
+				b: "1px solid var(--color-surface-xl)",
+				br: "0.375rem",
+				p: "1rem",
+				fs: "1rem"
+			},
+			radii: {
+				pill: "999px",
+				circle: "50%",
+				card: "0.5rem"
+			},
+			groups: {
+				control: {
+					ds: "var(--ds-default)",
+					b: "var(--b-default)",
+					br: "var(--br-default)",
+					p: "0.5em 1em",
+					fs: "var(--fs-default)"
+				},
+				panel: {
+					ds: "var(--shadow-md)",
+					b: "var(--b-default)",
+					br: "0.5rem",
+					p: "1rem",
+					fs: "var(--fs-default)"
+				}
+			},
+			z: {
+				raised: 1,
+				sticky: 100,
+				overlay: 200,
+				top: 1e3
+			},
+			items: {
+				button: {
+					group: "control",
+					element: "button",
+					default_role: "brand-primary",
+					base: {
+						padding: "0.6em 1.2em",
+						"border-radius": "var(--br-control, 0.25rem)",
+						border: "none",
+						"font-weight": "600",
+						color: "#fff",
+						cursor: "pointer",
+						"box-shadow": "var(--shadow-sm)"
+					},
+					states: {
+						hover: { step: 1 },
+						active: { scale: .97 },
+						"focus-visible": { ring: true }
+					},
+					roles: []
+				},
+				card: {
+					group: "panel",
+					class: "card",
+					base: {
+						"border-radius": "var(--br-card-group)",
+						padding: "1.5rem",
+						background: "var(--color-surface-xxl)",
+						border: "var(--b-card-group)",
+						"box-shadow": "var(--ds-card-group)"
+					},
+					states: {},
+					roles: []
+				}
+			}
+		},
+		typography: {
+			families: {
+				display: "var(--font-display)",
+				sans: "var(--font-sans)",
+				code: "var(--font-mono, ui-monospace, monospace)"
+			},
+			roles: {
+				display: {
+					family: "display",
+					size: "var(--text-3xl)",
+					weight: 700,
+					"line-height": "1.05",
+					tracking: "-0.03em"
+				},
+				heading: {
+					family: "display",
+					size: "var(--text-xl)",
+					weight: 600,
+					"line-height": "1.3"
+				},
+				body: {
+					family: "sans",
+					size: "var(--text-m)",
+					weight: 400,
+					"line-height": "1.55"
+				}
+			},
+			headings: {
+				h1: "display",
+				h2: "heading",
+				h3: "heading"
+			}
+		},
+		animations: {
+			effects: {
+				"fade-in": {
+					kf: "composite",
+					vars: { "opacity-from": 0 }
+				},
+				"slide-up": {
+					kf: "composite",
+					vars: { "translate-y-from": "var(--slide-distance, 2rem)" }
+				}
+			},
+			journeys: {
+				base: {
+					fade: { "opacity-from": 0 },
+					slide: {}
+				},
+				compose: [
+					["fade"],
+					["slide"],
+					["fade", "slide"]
+				]
+			}
+		}
+	};
+}
+
+//#endregion
+export { DesignSystemSchema, SCHEMA_URL, SITE_SCHEMA_URL, SiteConfigSchema, deepMerge, defaultConfig, generate, generateDocs, jsonSchema, resolveSiteConfig, resolveTheme, siteJsonSchema, stripNulls, validate, validateSite };
+//# sourceMappingURL=index.mjs.map