@getvitops/generator 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { transform } from "lightningcss";
 import * as z from "zod/mini";
+import { generateOklchPalette, hexToOklch, oklchStringToHex, pickOn } from "@getvitops/utils/color";
 
 //#region src/schema.ts
 /**
@@ -17,26 +18,12 @@ import * as z from "zod/mini";
 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 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 UtilityName = z.enum([
 	"bg",
 	"text",
@@ -47,8 +34,8 @@ const UtilityName = z.enum([
 ]);
 const Colors = z.object({
 	palette: z.record(z.string(), Ramp),
-	utilities: z.optional(z.array(UtilityName)),
-	schemes: z.record(z.string(), Scheme)
+	roles: z.record(z.string(), z.string()),
+	utilities: z.optional(z.array(UtilityName))
 });
 const Scale = z.object({
 	base: z.string(),
@@ -111,11 +98,8 @@ const DesignSystemSchema = z.object({
 });
 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))
-	})))
+	roles: z.optional(z.record(z.string(), z.string())),
+	utilities: z.optional(z.array(UtilityName))
 });
 const DesignSystemPatchSchema = z.extend(z.partial(DesignSystemSchema), { colors: z.optional(ColorsPatch) });
 /**
@@ -137,17 +121,18 @@ function validate(input) {
 		data: void 0,
 		errors: result.error.issues
 	};
-	if (result.data.colors.schemes.default == null) return {
+	const { palette, roles } = result.data.colors;
+	for (const [role, hue] of Object.entries(roles)) if (palette[hue] == null) return {
 		ok: false,
 		data: void 0,
 		errors: [{
 			code: "custom",
 			path: [
 				"colors",
-				"schemes",
-				"default"
+				"roles",
+				role
 			],
-			message: "colors.schemes must include a \"default\" (base) scheme"
+			message: `role "${role}" references unknown palette hue "${hue}"`
 		}]
 	};
 	return {
@@ -157,6 +142,185 @@ function validate(input) {
 	};
 }
 
+//#endregion
+//#region src/tokens.ts
+/**
+* Palette expansion + semantic functional tokens.
+*
+* A palette hue is authored one of two ways:
+*   • `{ seed, anchors? }` — an 11-step numeric scale (50…950) generated in
+*     OKLCH via @getvitops/utils/color (lightness transposed toward tinted
+*     near-white/near-black, chroma dampened at the extremes),
+*   • `{ tones }` — a fixed brand kit: authored tones placed verbatim at their
+*     nearest steps + tinted endpoints; nothing else is invented (strict kits).
+*
+* Every role (from `colors.roles`) gets FUNCTIONAL tokens — the public API:
+*   --<role>-bg / -bg-muted / -border / -border-bold / -solid / -solid-bold /
+*   -on-solid / -text / -text-muted / -text-x-muted
+* plus the appearance-relative emphasis stops (x-muted · muted · bold · x-bold)
+* and, for `surface`, the translucent `--surface-glass` + `--overlay` scrim.
+* Dark mode flips the mapping automatically (solid stays mode-stable).
+*/
+const NUMERIC_STEPS = [
+	"50",
+	"100",
+	"200",
+	"300",
+	"400",
+	"500",
+	"600",
+	"700",
+	"800",
+	"900",
+	"950"
+];
+const STEP_L = {
+	"50": .95,
+	"100": .9,
+	"200": .8,
+	"300": .7,
+	"400": .6,
+	"500": .5,
+	"600": .4,
+	"700": .3,
+	"800": .2,
+	"900": .1,
+	"950": .05
+};
+const isHex = (v) => v.startsWith("#");
+const toOklchStr = (v) => {
+	if (!isHex(v)) return v;
+	const { l, c, h } = hexToOklch(v);
+	return `oklch(${(l * 100).toFixed(2)}% ${c.toFixed(4)} ${h.toFixed(2)})`;
+};
+const nearestStep = (l) => NUMERIC_STEPS.reduce((best, s) => Math.abs(l - STEP_L[s]) < Math.abs(l - STEP_L[best]) ? s : best);
+function expandSeeded(input) {
+	const anchors = {};
+	const seedStep = nearestStep(hexToOklch(input.seed).l);
+	anchors[seedStep] = toOklchStr(input.seed);
+	for (const [key, value] of Object.entries(input.anchors ?? {})) {
+		const step = NUMERIC_STEPS.includes(key) ? key : nearestStep(hexToOklch(value).l);
+		anchors[step] = toOklchStr(value);
+	}
+	const hue = hexToOklch(input.seed).h;
+	anchors["50"] ??= `oklch(97% 0.008 ${hue.toFixed(2)})`;
+	anchors["950"] ??= `oklch(13% 0.015 ${hue.toFixed(2)})`;
+	const scale = generateOklchPalette(anchors);
+	const numeric = {};
+	for (const s of NUMERIC_STEPS) if (scale[s] != null) numeric[s] = oklchStringToHex(scale[s]);
+	return { numeric };
+}
+function expandTones(input) {
+	const tones = Array.isArray(input.tones) ? input.tones : Object.values(input.tones);
+	const numeric = {};
+	for (const hex of tones) numeric[nearestStep(hexToOklch(hex).l)] = hex;
+	const hue = hexToOklch(tones[0] ?? "#808080").h;
+	numeric["50"] ??= oklchStringToHex(`oklch(97% 0.010 ${hue.toFixed(2)})`);
+	numeric["950"] ??= oklchStringToHex(`oklch(15% 0.015 ${hue.toFixed(2)})`);
+	return {
+		numeric,
+		sparse: true
+	};
+}
+/** Snap to the nearest AVAILABLE numeric step (sparse kits). */
+function snap(numeric, want) {
+	if (numeric[want] != null) return want;
+	return NUMERIC_STEPS.filter((s) => numeric[s] != null).reduce((best, s) => Math.abs(STEP_L[s] - STEP_L[want]) < Math.abs(STEP_L[best] - STEP_L[want]) ? s : best);
+}
+/** Expand every palette hue into its numeric scale. */
+function expandPalette(raw) {
+	const out = {};
+	for (const [name, entry] of Object.entries(raw)) {
+		const e = entry;
+		if (typeof e?.seed === "string") out[name] = expandSeeded(e);
+		else if (e?.tones != null) out[name] = expandTones(e);
+		else throw new Error(`palette hue "${name}" must have a "seed" or "tones"`);
+	}
+	return out;
+}
+const LIGHT = {
+	bg: "50",
+	"bg-muted": "100",
+	border: "200",
+	"border-bold": "300",
+	text: "950",
+	"text-muted": "800",
+	"text-x-muted": "600"
+};
+const DARK = {
+	bg: "950",
+	"bg-muted": "900",
+	border: "800",
+	"border-bold": "700",
+	text: "50",
+	"text-muted": "200",
+	"text-x-muted": "400"
+};
+const SURFACE_LIGHT = {
+	...LIGHT,
+	bg: "100",
+	"bg-muted": "200",
+	"bg-bold": "50"
+};
+const SURFACE_DARK = {
+	...DARK,
+	bg: "900",
+	"bg-muted": "950",
+	"bg-bold": "800"
+};
+const EMPHASIS_LIGHT = {
+	"x-muted": "100",
+	muted: "300",
+	bold: "700",
+	"x-bold": "900"
+};
+const EMPHASIS_DARK = {
+	"x-muted": "900",
+	muted: "700",
+	bold: "300",
+	"x-bold": "100"
+};
+/** Resolve the functional token set for one role over its hue. */
+function functionalRole(role, hueName, hue) {
+	const numeric = hue.numeric;
+	const v = (n) => `var(--color-${hueName}-${snap(numeric, n)})`;
+	const hex = (n) => numeric[snap(numeric, n)];
+	const naturalRaw = NUMERIC_STEPS.find((s) => numeric[s] === hex("500")) ?? "500";
+	const natural = Number(snap(numeric, naturalRaw));
+	const solidStep = snap(numeric, String(Math.min(Math.max(natural, 500), 700)));
+	const solidBold = snap(numeric, String(Math.min(Number(solidStep) + 100, 950)));
+	const onSolid = pickOn(numeric[solidStep]);
+	const isSurface = role === "surface";
+	const map = (table) => {
+		const out = {};
+		for (const [token, step] of Object.entries(table)) out[token] = v(step);
+		return out;
+	};
+	const emphasis = (table, prefix) => {
+		const out = {};
+		for (const [stop, step] of Object.entries(table)) out[`${prefix}-${stop}`] = v(step);
+		return out;
+	};
+	return {
+		role,
+		hue: hueName,
+		light: {
+			...map(isSurface ? SURFACE_LIGHT : LIGHT),
+			solid: v(solidStep),
+			"solid-bold": v(solidBold),
+			"on-solid": onSolid,
+			...emphasis(EMPHASIS_LIGHT, "stop")
+		},
+		dark: {
+			...map(isSurface ? SURFACE_DARK : DARK),
+			solid: v(solidStep),
+			"solid-bold": v(solidBold),
+			"on-solid": onSolid,
+			...emphasis(EMPHASIS_DARK, "stop")
+		}
+	};
+}
+
 //#endregion
 //#region src/docs.ts
 /**
@@ -326,7 +490,8 @@ var Parser = class {
 			const first = this.parseValue();
 			if (this.peek()?.t === "arrow") {
 				this.next();
-				map[String(first)] = this.parseValue();
+				const val = this.parseValue();
+				map[typeof first === "object" && first !== null ? JSON.stringify(first) : String(first)] = val;
 				keyed = true;
 			} else list.push(first);
 			if (this.peek()?.t === "punc" && this.peek()?.v === ",") this.next();
@@ -467,9 +632,11 @@ function parseElement(src) {
 		keywords: extractKeywords(src)
 	};
 }
+/** Stringify a parsed-PHP Json value for prose (objects → JSON, not [object Object]). */
+const asText = (v) => v == null ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
 function controlLine(c) {
 	const def = c.def;
-	if (def.type === "info") return `- _Note:_ ${def.content ?? ""}`;
+	if (def.type === "info") return `- _Note:_ ${asText(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 = [];
@@ -477,21 +644,21 @@ function controlLine(c) {
 	if (def.units === true) type += "+units";
 	meta.push(type);
 	if (def.default !== void 0) {
-		const raw = String(def.default);
+		const raw = asText(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 ?? "∞"}`);
+	if (def.placeholder !== void 0 && def.placeholder !== "") meta.push(`placeholder \`${asText(def.placeholder)}\``);
+	if (def.min !== void 0 || def.max !== void 0) meta.push(`range ${def.min != null ? asText(def.min) : "–"}–${def.max != null ? asText(def.max) : "∞"}`);
 	const tail = [];
-	if (def.description) tail.push(String(def.description));
+	if (def.description) tail.push(asText(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 (first && typeof first === "object" && !Array.isArray(first) && "property" in first) tail.push(`Bound to \`${asText(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);
+		const fields = Object.values(def.fields).map((f) => f && typeof f === "object" && !Array.isArray(f) ? asText(f.label) : null).filter(Boolean);
 		if (fields.length) tail.push(`Fields: ${fields.join(", ")}.`);
 	}
 	const head = `- **${label}** (${meta.join(", ")})`;
@@ -613,11 +780,9 @@ function renderElementsDoc(elementsDir) {
 }
 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 expanded = expandPalette(ds.colors.palette);
+	const ramps = Object.keys(expanded);
+	const roles = Object.keys(ds.colors.roles ?? {});
 	const utils = ds.colors.utilities ?? [
 		"bg",
 		"text",
@@ -704,13 +869,32 @@ Families: ${code(families)} (\`--font-*\`).
 
 ## Colour
 
-Rule: **\`<util>-<color>\`** — util ∈ ${code(utils)}; \`<color>\` is either a **named ramp**
-step or a **semantic role**.
+**Functional tokens are the primary vocabulary** — classes name the *job*, not the tone, and
+every one remaps automatically under \`:root[data-brx-theme="dark"]\` (background/text ends
+swap; \`solid\` fills stay mode-stable with a computed \`on-\` foreground). Prefer these over
+raw steps. Rules (role ∈ ${code(roles)}):
+
+- **Surfaces** — \`bg-<role>\` (the role's background wash; for \`surface\` this is the
+  card/panel plane), \`bg-<role>-muted\` (subtle / sunken), \`bg-surface-bold\` (raised plane).
+- **Solid fills** — \`bg-<role>-solid\`, \`bg-<role>-solid-bold\` (hover / emphasis), paired
+  with \`text-on-<role>\` for guaranteed-contrast foreground.
+- **Content** — \`text-<role>\` (primary, contrast-guaranteed in both appearances),
+  \`text-<role>-muted\` (secondary), \`text-<role>-x-muted\` (tertiary / disabled).
+- **Borders** — \`border-<role>\`, \`border-<role>-bold\`.
+- **Translucency** — \`glass\` (translucent surface + backdrop blur); \`--overlay\` scrim var.
+- **Emphasis stops** (appearance-relative vars for power use):
+  \`--color-<role>-{x-muted,muted,bold,x-bold}\` — \`muted\` recedes toward the background
+  extreme, \`bold\` advances toward the foreground, in *either* appearance.
+
+Everyday pairings: page \`bg-neutral\` + \`text-neutral\`; cards \`bg-surface\`; captions
+\`text-neutral-muted\`; buttons \`bg-ui-primary-solid text-on-ui-primary\`; status text
+\`text-danger\` / \`text-success\` / \`text-warning\` / \`text-info\`.
 
-- 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"]\`.
+**Raw scale** (secondary / fine control) — rule \`<util>-<hue>-<step>\` with util ∈
+${code(utils)}: every hue is an 11-step OKLCH scale generated from its seed (or fixed brand
+tones), numeric steps \`50\` … \`950\` (tinted near-white → tinted near-black) — e.g.
+\`bg-${ramps[0] ?? "brand"}-100\`, \`text-${ramps[0] ?? "brand"}-800\`. Hues: ${code(ramps)}.
+The **bare** role name (\`bg-<role>\`, \`text-<role>\`) is always the functional token.
 
 ## Shadows
 
@@ -813,31 +997,6 @@ function generateDocs(ds, assetsDir) {
 * 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",
@@ -846,20 +1005,25 @@ const UTILITY_PROPS = {
 	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 fnVar = (role, token) => token.startsWith("stop-") ? `--color-${role}-${token.slice(5)}` : `--${role}-${token}`;
+const fnUtilities = (role, utilities, isSurface) => {
+	const rows = [];
+	if (utilities.includes("bg")) {
+		rows.push(`.bg-${role} { background-color: var(--${role}-bg); }`);
+		rows.push(`.bg-${role}-muted { background-color: var(--${role}-bg-muted); }`);
+		rows.push(`.bg-${role}-solid { background-color: var(--${role}-solid); }`);
+		rows.push(`.bg-${role}-solid-bold { background-color: var(--${role}-solid-bold); }`);
+		if (isSurface) rows.push(`.bg-${role}-bold { background-color: var(--${role}-bg-bold); }`);
+	}
+	if (utilities.includes("text")) {
+		rows.push(`.text-${role} { color: var(--${role}-text); }`);
+		rows.push(`.text-${role}-muted { color: var(--${role}-text-muted); }`);
+		rows.push(`.text-${role}-x-muted { color: var(--${role}-text-x-muted); }`);
+		rows.push(`.text-on-${role} { color: var(--${role}-on-solid); }`);
+	}
+	if (utilities.includes("border")) rows.push(`.border-${role} { border-color: var(--${role}-border); }`, `.border-${role}-bold { border-color: var(--${role}-border-bold); }`);
+	return rows.join("\n");
 };
-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);
@@ -940,13 +1104,15 @@ const BASE_HOOK = {
 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 expandedPalette = expandPalette(ds.colors.palette);
+	const roleMap = ds.colors.roles;
+	const scaleRoles = [];
+	for (const [role, hueName] of Object.entries(roleMap)) {
+		const hue = expandedPalette[hueName];
+		if (hue == null) throw new Error(`role "${role}" references unknown palette hue "${hueName}"`);
+		scaleRoles.push(functionalRole(role, hueName, hue));
+	}
+	const surfaceRole = scaleRoles.find((r) => r.role === "surface");
 	const patterns = ds.patterns;
 	const shadows = ds.shadows;
 	const typography = ds.typography;
@@ -959,41 +1125,39 @@ function build(ds, format, assetsDir) {
 	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 += `  color-scheme: light;\n`;
+		css += `  /* Hue scales (numeric steps, 50 = tinted near-white … 950 = tinted near-black) */\n`;
+		for (const [name, hue] of Object.entries(expandedPalette)) for (const [n, hex] of Object.entries(hue.numeric)) css += `  --color-${name}-${n}: ${hex};\n`;
+		css += `\n  /* Functional role tokens (the public API) */\n`;
+		for (const fr of scaleRoles) for (const [t, val] of Object.entries(fr.light)) css += `  ${fnVar(fr.role, t)}: ${val};\n`;
+		if (surfaceRole) {
+			css += `\n  /* Translucent surface + scrim */\n`;
+			css += `  --surface-glass: color-mix(in oklch, var(--surface-bg) 72%, transparent);\n`;
+			css += `  --overlay: color-mix(in oklch, var(--color-${surfaceRole.hue}-950) 45%, transparent);\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`;
+		{
+			let fb = "";
+			for (const fr of scaleRoles) for (const [t, val] of Object.entries(fr.dark)) if (fr.light[t] !== val) fb += `  ${fnVar(fr.role, t)}: ${val};\n`;
+			if (surfaceRole) fb += `  --overlay: color-mix(in oklch, var(--color-${surfaceRole.hue}-950) 60%, transparent);\n`;
+			if (fb) {
+				css += `/* Functional role tokens (dark) */\n`;
+				css += `:root[data-brx-theme="dark"] {\n  color-scheme: dark;\n${fb}}\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)}`);
-		}
+		for (const [name, hue] of Object.entries(expandedPalette)) for (const n of Object.keys(hue.numeric)) allTokens.push(`${name}-${n}`);
+		for (const fr of scaleRoles) for (const stop of [
+			"x-muted",
+			"muted",
+			"bold",
+			"x-bold"
+		]) allTokens.push(`${fr.role}-${stop}`);
 		css += `/* Colour utilities — ${UTILITIES.join(", ")} */\n`;
 		for (const token of allTokens) css += UTILITIES.map((cls) => `.${cls}-${token} { ${UTILITY_PROPS[cls]}: var(--color-${token}); }`).join("\n") + "\n";
+		css += `\n/* Functional utilities (the public API) */\n`;
+		for (const fr of scaleRoles) css += `${fnUtilities(fr.role, UTILITIES, fr.role === "surface")}\n`;
+		if (surfaceRole) css += `.glass { background-color: var(--surface-glass); backdrop-filter: blur(12px); -webkit-backdrop-filter: blur(12px); }\n`;
 		generated["color.css"] = css;
 	}
 	{
@@ -1067,16 +1231,18 @@ function build(ds, format, assetsDir) {
 	}
 	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.step === "number" && role) {
+				const stateVar = colorProp === "background-color" ? `var(--${role}-${spec.step >= 1 ? "solid-bold" : "solid"})` : `var(--color-${role}-${spec.step >= 1 ? "x-bold" : "bold"})`;
+				body.push(`${colorProp}: ${stateVar};`);
+			}
 			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)`;
+				const ringColor = role ? `var(--color-${role}-muted)` : `var(--color-ui-primary-muted)`;
 				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};`);
@@ -1104,7 +1270,7 @@ function build(ds, format, assetsDir) {
 			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})`;
+		if (defaultRole && fills && base["background-color"] == null && base["background"] == null) base["background-color"] = `var(--${defaultRole}-solid)`;
 		const wrappedBase = {};
 		for (const [prop, val] of Object.entries(base)) {
 			const sfx = BASE_HOOK[prop];
@@ -1114,7 +1280,7 @@ function build(ds, format, assetsDir) {
 		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})`;
+			const variantColorDecl = fills ? `background-color: var(--${role}-solid); color: var(--${role}-on-solid)` : `color: var(--color-${role}-bold)`;
 			pat += `${variantSel} { ${variantColorDecl}; }\n`;
 			pat += stateRules(variantSel, role, states, colorProp);
 		}
@@ -1166,10 +1332,8 @@ function build(ds, format, assetsDir) {
 		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)}`;
+	for (const [name, hue] of Object.entries(expandedPalette)) for (const [n, hex] of Object.entries(hue.numeric)) {
+		const token = `${name}-${n}`;
 		namedColors.push({
 			raw: `var(--color-${token})`,
 			light: hex,
@@ -1178,98 +1342,99 @@ function build(ds, format, assetsDir) {
 		});
 	}
 	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
-			});
-		}
+	for (const fr of scaleRoles) for (const [t, light] of Object.entries(fr.light)) {
+		const dark = fr.dark[t];
+		semanticColors.push({
+			raw: `var(${fnVar(fr.role, t)})`,
+			light,
+			darkModeEnabled: light !== dark,
+			dark,
+			id: id(`semantic:${fr.role}-${t}`),
+			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
-					}
-				});
+	const bricksColorsNamed = JSON.stringify({
+		id: id("palette:named"),
+		name: "Named",
+		colors: namedColors
+	}, null, 2);
+	const bricksColorsSemantic = JSON.stringify({
+		id: id("palette:semantic"),
+		name: "Semantic",
+		colors: semanticColors
+	}, null, 2);
+	const 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)]
 			};
-			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
+		};
+		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 [name, val] of Object.entries(ds.patterns?.radii ?? {})) variables.push({
-				id: id(`var:br-${name}`),
-				name: `br-${name}`,
-				value: val
+			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
+				}
 			});
-			return JSON.stringify({
-				variables,
-				categories
-			}, null, 2);
-		})(),
+		};
+		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);
+	})();
+	const numericPalette = Object.fromEntries(Object.entries(expandedPalette).map(([k, v]) => [k, v.numeric]));
+	return {
+		generated,
+		bricksColorsNamed,
+		bricksColorsSemantic,
+		bricksVariables,
 		tokensJson: JSON.stringify({
 			colors: {
-				palette,
-				semantic: Object.fromEntries(Object.entries(defaultSemantic).map(([role, spec]) => [role, roleRamp(spec)]))
+				palette: numericPalette,
+				roles: roleMap,
+				functional: Object.fromEntries(scaleRoles.map((fr) => [fr.role, {
+					light: fr.light,
+					dark: fr.dark
+				}]))
 			},
 			fonts: ds.fonts ?? {},
 			text: Object.fromEntries(typeSteps.map((s) => [s.name, s.value])),
@@ -1279,10 +1444,10 @@ function build(ds, format, assetsDir) {
 		}, 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]) => ({
+			for (const [name, hue] of Object.entries(expandedPalette)) for (const n of Object.keys(hue.numeric)) reverseIndex[`--color-${name}-${n}`] = `colors.palette.${name}.seed`;
+			const colorRoles = Object.entries(roleMap).map(([name, ramp]) => ({
 				name,
-				ramp: roleRamp(spec)
+				ramp
 			}));
 			const typoRoles = typography?.roles ?? {};
 			const hooks = {};
@@ -1315,9 +1480,9 @@ function build(ds, format, assetsDir) {
 			});
 			return JSON.stringify({
 				colors: {
-					ramps: Object.keys(palette),
-					steps: STEP_ORDER,
-					palette,
+					ramps: Object.keys(expandedPalette),
+					steps: NUMERIC_STEPS,
+					palette: numericPalette,
 					roles: colorRoles
 				},
 				typography: {
@@ -1355,9 +1520,8 @@ function build(ds, format, assetsDir) {
 		})(),
 		tailwind: emitTailwind({
 			ds,
-			palette,
-			defaultSemantic,
-			darkScheme,
+			expandedPalette,
+			scaleRoles,
 			shadows,
 			typeSteps,
 			spaceSteps,
@@ -1374,25 +1538,18 @@ function build(ds, format, assetsDir) {
 	};
 }
 function emitTailwind(ctx) {
-	const { ds, palette, defaultSemantic, darkScheme, shadows, typeSteps, spaceSteps, typography, roleDecls, twTypeTokensCss, twPatternTokensCss, patternsCss, assetsDir } = ctx;
+	const { ds, expandedPalette, scaleRoles, 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(`  /* Hue scales → bg-<hue>-<step> text-* border-* (numeric, 50…950) */`);
+	for (const [name, hue] of Object.entries(expandedPalette)) for (const [n, hex] of Object.entries(hue.numeric)) theme.push(`  --color-${name}-${n}: ${hex};`);
 	theme.push(`\n  /* Fonts → font-* */`);
 	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: */`);
@@ -1403,22 +1560,39 @@ function emitTailwind(ctx) {
 		["xl", "80rem"]
 	]) theme.push(`  --container-${name}: ${val};`);
 	parts.push(`@theme {\n${theme.join("\n")}\n}\n`);
+	if (spaceSteps.length) parts.push(`/* Fluid space scale — var(--space-<name>) or p-(--space-<name>) */\n:root {\n` + spaceSteps.map((s) => `  --space-${s.name}: ${s.value};`).join("\n") + `\n}\n`);
+	if (scaleRoles.length) {
+		let fn = "";
+		for (const fr of scaleRoles) for (const [t, val] of Object.entries(fr.light)) fn += `  ${fnVar(fr.role, t)}: ${val};\n`;
+		const surface = scaleRoles.find((r) => r.role === "surface");
+		if (surface) {
+			fn += `  --surface-glass: color-mix(in oklch, var(--surface-bg) 72%, transparent);\n`;
+			fn += `  --overlay: color-mix(in oklch, var(--color-${surface.hue}-950) 45%, transparent);\n`;
+		}
+		parts.push(`/* Functional role tokens (the public API) */\n:root {\n${fn}}\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`;
-		}
+	for (const fr of scaleRoles) for (const [t, val] of Object.entries(fr.dark)) if (fr.light[t] !== val) darkBlock += `  ${fnVar(fr.role, t)}: ${val};\n`;
+	{
+		const surface = scaleRoles.find((r) => r.role === "surface");
+		if (surface) darkBlock += `  --overlay: color-mix(in oklch, var(--color-${surface.hue}-950) 60%, transparent);\n`;
 	}
-	if (darkBlock && darkScheme) parts.push(`/* Dark-mode semantic overrides */\n:root[data-brx-theme="${darkScheme.appearance}"] {\n${darkBlock}}\n`);
+	if (darkBlock) parts.push(`/* Functional role tokens (dark) */\n:root[data-brx-theme="dark"] {\n  color-scheme: dark;\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 = [];
+	if (scaleRoles.length) {
+		util.push(`/* Functional colour utilities (the public API) */`);
+		for (const fr of scaleRoles) for (const row of fnUtilities(fr.role, [
+			"bg",
+			"text",
+			"border"
+		], fr.role === "surface").split("\n")) {
+			const m = /^\.([^ ]+) \{ (.*) \}$/.exec(row);
+			if (m) util.push(`@utility ${m[1]} {\n  ${m[2]}\n}`);
+		}
+		if (scaleRoles.some((r) => r.role === "surface")) util.push(`@utility glass {\n  background-color: var(--surface-glass);\n  backdrop-filter: blur(12px);\n  -webkit-backdrop-filter: blur(12px);\n}`);
+	}
 	util.push(`/* Typography roles */`);
 	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) */`);
@@ -1540,7 +1714,7 @@ body {
 `);
 	const animEngine = readFileSync(join(cssDir, "animation.css"), "utf8");
 	parts.push(`/* ── Animation engine (animation.css) ── */\n${animEngine}`);
-	parts.push(`/* ── Component patterns ── */\n${patternsCss}`);
+	parts.push(`/* ── Component patterns ── */\n@layer components {\n${patternsCss}\n}`);
 	const TW_CLASH = new Set([
 		"block",
 		"inline",
@@ -1639,7 +1813,7 @@ body {
 	const componentCss = componentPartialOrder(cssDir).map((rel) => {
 		return `/* ── ${rel} ── */\n${stripForTailwind(readFileSync(join(cssDir, rel), "utf8"))}`;
 	}).join("\n\n");
-	parts.push(`/* ── Component + structural partials (Tailwind-clashing utilities dropped) ── */\n${componentCss}`);
+	parts.push(`/* ── Component + structural partials (Tailwind-clashing utilities dropped) ── */\n@layer components {\n${componentCss}\n}`);
 	return nl(parts) + "\n";
 }
 /**
@@ -2210,7 +2384,13 @@ const SiteConfigSchema = z.object({
 	})),
 	favicon: z.optional(z.object({
 		source: z.string(),
-		lowResSource: z.optional(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({
 		platform: z.optional(z.string()),
@@ -2382,47 +2562,27 @@ function defaultConfig() {
 		$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"
-				}
+				brand: { seed: "#2e9b73" },
+				ink: { seed: "#3f4a5c" },
+				sky: { seed: "#2f7bc0" },
+				sun: { seed: "#d08a1f" },
+				rose: { seed: "#c74a42" }
+			},
+			roles: {
+				neutral: "ink",
+				surface: "ink",
+				"ui-primary": "brand",
+				"brand-primary": "brand",
+				info: "sky",
+				success: "brand",
+				warning: "sun",
+				danger: "rose"
 			},
 			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)",