@getvitops/generator 8.2.0-alpha.0 → 8.3.0-alpha.0

package/dist/tokens-CaIGQQLk.mjs

@@ -0,0 +1,740 @@
+import { LIGHTNESS_LADDER, contrastLc, generateOklchPalette, hexToOklch, oklchStringToHex, pickOn, tintedEndpoints } from "@getvitops/utils/color";
+
+// src/shared.ts
+/**
+* Data shared between the generator (`generate.ts`) and the docs bundle
+* (`docs.ts`). Lives in its own module because `generate.ts` imports `docs.ts` —
+* importing back the other way would be a cycle.
+*/
+/**
+* Selector the dark functional-token flip hangs off.
+*
+* `data-brx-theme` is Bricks' own attribute — Bricks sets it, so it's what the
+* WordPress target needs. Nothing sets it anywhere else, which meant the dark
+* flip was unreachable outside Bricks: the shipped `<wc-color-scheme-toggle>` web
+* component writes `documentElement.dataset.theme` (i.e. `data-theme`), so
+* clicking "Dark" changed an attribute no rule matched. Matching both makes the
+* component work on every target without changing what Bricks already does.
+*
+* This covers the EXPLICIT choice. The OS preference is a second, opt-in block —
+* see `SYSTEM_DARK_SEL` — because turning it on flips a site dark for dark-OS
+* users, which is the site's decision rather than the design system's.
+*
+* Shared so the docs quote the selector the generator actually emits.
+*/
+const DARK_SEL = ":root[data-brx-theme=\"dark\"], :root[data-theme=\"dark\"]";
+/**
+* Selector for the OS-preference dark block, emitted inside
+* `@media (prefers-color-scheme: dark)` when a site opts in.
+*
+* Derived from `DARK_SEL`'s attributes rather than written out a third time, and
+* inverted: this must apply when NO explicit choice has been made. That is
+* exactly what `<wc-color-scheme-toggle>`'s "System" position produces — it removes
+* `data-theme` entirely — so with this block present System resolves to the OS
+* instead of silently falling through to light, and needs no JS to do it.
+*
+* The `:not()`s are what keep an explicit *light* choice winning over a dark OS.
+*/
+const SYSTEM_DARK_SEL = `:root${DARK_SEL.split(", ").map((s) => s.replace(/^:root\[([\w-]+)="dark"\]$/, "[$1=\"light\"]")).map((attr) => `:not(${attr})`).join("")}`;
+/**
+* Roles the shipped CSS partials reference with NO fallback, so a config that
+* omits one leaves those rules resolving to nothing — an invalid declaration,
+* not a graceful degrade.
+*
+* `colors.roles` is an open record: any name works and generates a full token
+* set, utilities and dark flip. But the framework's own component CSS is
+* written against these six, so "roles are arbitrary" is only half true — they
+* are *extensible*, over a required core. `validate()` warns when one is
+* missing; `required-roles.test.ts` re-derives this list from the partials so
+* it cannot drift as components are added.
+*
+* Kept as a constant rather than scanned at call time because `validate()` is
+* a pure function — the CLI, the Vite plugin and `toJSONSchema` all import it,
+* and none of them should touch the filesystem to answer "is this config ok?".
+*/
+const REQUIRED_ROLES = [
+	"brand-primary",
+	"danger",
+	"neutral",
+	"surface",
+	"ui-primary",
+	"warning"
+];
+/**
+* Every token key a role can resolve to, across both role kinds. Shared so the
+* required-roles drift test greps for exactly what the generator emits.
+*
+* These are *keys*, not var names: the role sits in the middle of the property
+* (`--color-bg-danger-muted`), so compose them with `tokenVar()` from `tokens.ts`
+* rather than concatenating by hand.
+*/
+const ROLE_TOKEN_KEYS = [
+	"bg",
+	"bg-muted",
+	"bg-x-muted",
+	"bg-bold",
+	"bg-x-bold",
+	"bg-solid",
+	"bg-solid-bold",
+	"bg-solid-x-bold",
+	"text",
+	"text-bold",
+	"text-muted",
+	"text-x-muted",
+	"text-xx-muted",
+	"text-on",
+	"text-on-bold",
+	"icon",
+	"icon-muted",
+	"border",
+	"border-muted",
+	"border-bold"
+];
+/** The solid step / foreground polarity a role asked for (both optional). */
+const roleSolidOptions = (spec) => typeof spec === "string" ? {} : {
+	...spec.solid != null ? { solid: String(spec.solid) } : {},
+	...spec.foreground ? { foreground: spec.foreground } : {}
+};
+/** The palette hue a role points at, through either authoring form. */
+const roleHue = (spec) => typeof spec === "string" ? spec : spec.hue;
+/**
+* A role's kind. The bare-string shorthand means `chromatic`, because signal
+* colours are the common case and surfaces are the two or three you name once.
+*/
+const roleKind = (spec) => typeof spec === "string" ? "chromatic" : spec.kind ?? "chromatic";
+/**
+* Pattern base geometry props → per-pattern override-hook shorthand. Each hook
+* wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
+* consumer restyles one pattern by setting one variable. The hook is named after
+* the pattern's key, not its class.
+*/
+const BASE_HOOK = {
+	padding: "p",
+	"border-radius": "br",
+	border: "b",
+	"box-shadow": "ds",
+	"font-size": "fs",
+	background: "bg",
+	"background-color": "bg"
+};
+/**
+* A typography role's declared key → [CSS property, var-name suffix]. The
+* recognised key set is CLOSED (an unrecognised key is a config error, see
+* `generate.ts`'s `ALSO_MEANT`) — shared here (rather than living only in
+* `generate.ts`) because `tokens.ts`'s `buildReverseIndex` needs the exact
+* same key → suffix mapping to stay in step with what `generate()` itself
+* builds, and `tokens.ts` can't import from `generate.ts` (the CSS-bundling
+* half, which needs lightningcss/node:fs) without losing its own
+* Worker-safety.
+*/
+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"]
+};
+/**
+* Framework utility classes whose names collide with Tailwind's own defaults.
+* The `tailwind` format strips any rule targeting these — Tailwind provides
+* them, so consumers use Tailwind's utilities for these names instead.
+*/
+const TW_CLASH = /* @__PURE__ */ 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",
+	"text-wrap",
+	"text-nowrap",
+	"text-balance",
+	"text-pretty",
+	"rounded-none",
+	"rounded-full"
+]);
+/**
+* `layout` config key → the custom property it sets. The one table both the
+* emitters (css/bricks/tailwind) and the live-editor manifest's `reverseIndex`
+* read, so a token that is emitted is always one the editor can write back.
+*/
+const LAYOUT_TOKENS = {
+	"widths.measure": "--width-measure",
+	"widths.breakout": "--width-breakout",
+	"widths.spotlight": "--width-spotlight",
+	"widths.nav": "--width-nav",
+	"regionSpace.min": "--region-space-min",
+	"regionSpace.preferred": "--region-space",
+	"regionSpace.max": "--region-space-max"
+};
+/**
+* The `:root` declarations for an authored `layout` block (only what was set —
+* an absent key leaves the framework's own default in force), keyed by the
+* custom property.
+*/
+function layoutDecls(layout) {
+	const out = {};
+	for (const [path, token] of Object.entries(LAYOUT_TOKENS)) {
+		const [group, key] = path.split(".");
+		const value = layout?.[group]?.[key];
+		if (value != null) out[token] = value;
+	}
+	return out;
+}
+
+// src/tokens.ts
+/**
+* Palette expansion + semantic colour 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 comes from the shared
+*     `LIGHTNESS_LADDER`; the seed (and any anchors) are reproduced verbatim at
+*     their steps.
+*   • `{ tones }` — a fixed brand kit: authored tones placed verbatim at their
+*     nearest steps + tinted endpoints; nothing else is invented (strict kits).
+*
+* **The grammar.** Every role gets tokens named `--color-<target>-<role>[-<variant>]`,
+* where target ∈ bg | text | icon | border. Putting the target *inside* the name is
+* the point: `--color-bg-danger-muted` and `--color-text-danger-muted` are distinct
+* tokens, so the two axes that used to collide over one `<family>-<role>-<modifier>
+* ` namespace cannot any more. The utility class is the token name minus `--color-`.
+*
+* Variants are ordinal — xx-muted < x-muted < muted < (bare) < bold < x-bold —
+* and the tables are **sparse**: a target only emits the cells that are actually
+* viable. `bold` means "more emphatic than the role's default in the current
+* appearance", not "darker"; the appearance decides polarity.
+*
+* Roles come in two kinds (declared in `colors.roles`):
+*   • `surface` — a page/panel colour. Has a bare `bg-<role>` plus the full
+*     emphasis range and the complete text scale.
+*   • `chromatic` (default) — a signal colour. Backgrounds split into *tints*
+*     (`bg-<role>-x-muted` / `-muted`) and *solids* (`bg-<role>-solid[-bold|-x-bold]`);
+*     there is deliberately **no bare `bg-<role>`**, because "how loud?" is a
+*     question the author has to answer.
+*
+* Dark mode re-points which step each token reads; the solid family and the
+* `text-on-<role>` foreground computed against it stay mode-stable, so a filled
+* button keeps its identity across appearances.
+*/
+const NUMERIC_STEPS = [
+	"50",
+	"100",
+	"200",
+	"300",
+	"400",
+	"500",
+	"600",
+	"700",
+	"800",
+	"900",
+	"950"
+];
+/**
+* Lightness of each numeric step. Re-exported from the engine's ladder rather
+* than restated — there used to be three copies of this curve (here, the engine,
+* and the linter) and they were free to drift.
+*/
+const STEP_L = Object.fromEntries(NUMERIC_STEPS.map((s) => [s, LIGHTNESS_LADDER[Number(s)]]));
+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);
+/**
+* Claim `step` for `value`, refusing to overwrite a step another colour already
+* took.
+*
+* Silently dropping one of two colliding tones is the worst outcome: the palette
+* still builds, and the tone the author cared about is simply gone. The record
+* form (`tones: { "600": "#…", "700": "#…" }`) is the escape hatch, so the error
+* points at it.
+*/
+function claim(into, step, value, hueLabel, what) {
+	const taken = into[step];
+	if (taken != null && taken !== value) throw new Error(`palette hue "${hueLabel}": ${what} ${value} and ${taken} both map to step ${step}. Key them explicitly, e.g. { "${step}": "${taken}", "${Number(step) + 100}": "${value}" }.`);
+	into[step] = value;
+}
+function expandSeeded(input, hueLabel) {
+	const anchors = {};
+	for (const [key, value] of Object.entries(input.anchors ?? {})) claim(anchors, NUMERIC_STEPS.includes(key) ? key : nearestStep(hexToOklch(value).l), toOklchStr(value), hueLabel, "anchors");
+	const seedStep = nearestStep(hexToOklch(input.seed).l);
+	anchors[seedStep] ??= toOklchStr(input.seed);
+	const scale = generateOklchPalette(anchors);
+	const numeric = {};
+	for (const s of NUMERIC_STEPS) if (scale[s] != null) numeric[s] = oklchStringToHex(scale[s]);
+	return {
+		numeric,
+		deviations: deviationsFor(anchors)
+	};
+}
+function expandTones(input, hueLabel) {
+	const entries = Array.isArray(input.tones) ? input.tones.map((hex) => [null, hex]) : Object.entries(input.tones).map(([k, hex]) => [k, hex]);
+	const placed = {};
+	for (const [key, hex] of entries) claim(placed, key != null && NUMERIC_STEPS.includes(key) ? key : nearestStep(hexToOklch(hex).l), hex, hueLabel, "tones");
+	const numeric = {};
+	for (const [step, hex] of Object.entries(placed)) numeric[step] = hex;
+	const firstTone = entries[0]?.[1] ?? "#808080";
+	const ends = tintedEndpoints(hexToOklch(firstTone).h);
+	numeric["50"] ??= ends.light;
+	numeric["950"] ??= ends.dark;
+	return {
+		numeric,
+		sparse: true,
+		deviations: deviationsFor(placed)
+	};
+}
+/** How far each pinned colour sits from its step's ladder lightness. */
+function deviationsFor(pinned) {
+	const out = {};
+	for (const [step, value] of Object.entries(pinned)) out[step] = (isHex(value) ? hexToOklch(value).l : hexToOklch(oklchStringToHex(value)).l) - STEP_L[step];
+	return out;
+}
+/** 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, name);
+		else if (e?.tones != null) out[name] = expandTones(e, name);
+		else throw new Error(`palette hue "${name}" must have a "seed" or "tones"`);
+	}
+	return out;
+}
+/**
+* Warn about pinned colours that sit noticeably off the ladder. Not an error:
+* the author asked for that exact colour and gets it. But at ~0.03 L the hue
+* starts reading visibly heavier or lighter than its siblings at that step, and
+* that is the class of drift the fixed ladder exists to prevent.
+*/
+const LADDER_TOLERANCE = .03;
+function ladderWarnings(palette, authored = {}) {
+	const warnings = [];
+	for (const [hue, expanded] of Object.entries(palette)) {
+		if (authored[hue]?.acknowledgeOffLadder) continue;
+		for (const [step, deviation] of Object.entries(expanded.deviations ?? {})) {
+			if (Math.abs(deviation) <= LADDER_TOLERANCE) continue;
+			const dir = deviation > 0 ? "lighter" : "darker";
+			warnings.push(`colors.palette.${hue}: the colour pinned at step ${step} is ${Math.abs(deviation).toFixed(3)} ${dir} than the shared lightness ladder — this hue will read ${dir} than others at ${step}. Legal, but move it to a neighbouring step if that wasn't intended (or set \`acknowledgeOffLadder: true\` on the hue to silence this).`);
+		}
+	}
+	return warnings;
+}
+/**
+* Gamut mapping nudges lightness by a hair, so an exact `<` comparison would
+* report rounding as an inversion. Well below any deviation a person could see.
+*/
+const MONOTONIC_EPSILON = .001;
+/**
+* Ramps whose lightness does not fall monotonically from 50 to 950.
+*
+* A ramp built from the ladder alone cannot invert — only pinned colours (a seed,
+* an `anchor`, a `tones` entry) can, because they are the one thing allowed off
+* it. `ladderWarnings` will not catch it: it compares each pinned step against
+* *its own* ladder rung, never against its neighbours, so it reports the wrong
+* defect ("reads darker than others at 600") while the real problem is that 600
+* is darker than 700. And since `LADDER_TOLERANCE` is 0.03 — the same size as the
+* ladder's own 50→100 gap — two anchors can each sit within tolerance and still
+* invert, with no warning at all.
+*
+* This is an error rather than a warning because the rest of the system assumes
+* the order: `snap` picks the nearest step by ladder lightness, the mode-stable
+* solid family hard-codes 600/700/800 as increasingly dark, and both dark tables
+* re-point steps on the same assumption. An inverted ramp therefore runs hover
+* states backwards — the failure the fixed ladder was introduced to eliminate.
+*/
+function monotonicityErrors(palette) {
+	const errors = [];
+	for (const [hue, expanded] of Object.entries(palette)) {
+		const numeric = expanded.numeric ?? {};
+		const steps = NUMERIC_STEPS.filter((s) => numeric[s] != null);
+		for (let i = 1; i < steps.length; i++) {
+			const [prev, step] = [steps[i - 1], steps[i]];
+			const lPrev = hexToOklch(numeric[prev]).l;
+			const lStep = hexToOklch(numeric[step]).l;
+			if (lStep < lPrev + MONOTONIC_EPSILON) continue;
+			const pinned = expanded.deviations ?? {};
+			const culprits = [prev, step].filter((s) => pinned[s] != null);
+			const fix = culprits.length ? culprits.map((s) => {
+				const l = hexToOklch(numeric[s]).l;
+				return `${numeric[s]} (pinned at ${s}) sits at L ${l.toFixed(3)}, nearest step ${nearestStep(l)}`;
+			}).join("; ") : `no step here is pinned, so this is a bug in the generator rather than in your config`;
+			errors.push(`colors.palette.${hue}: step ${step} (${numeric[step]}, L ${lStep.toFixed(3)}) is LIGHTER than step ${prev} (${numeric[prev]}, L ${lPrev.toFixed(3)}). A ramp must darken from 50 to 950 — inverted, a hover from \`bg-<role>-solid\` to \`-solid-bold\` gets lighter, and the dark-mode tables re-point steps assuming the order. ${fix}.`);
+		}
+	}
+	return errors;
+}
+/**
+* Surface roles: a bare `bg` (cards, panels, inputs), `bg-muted` for the page
+* behind them, `bg-x-muted` for wells, and `bg-bold`/`-x-bold` for the inverse
+* surface a tooltip sits on. Elevation is expressed by *which* token you reach
+* for — page `bg-muted`, card `bg` — rather than by a raised/sunken pair. That
+* is what lets a future `data-surfaces` axis flatten it without touching markup.
+*/
+const SURFACE_LIGHT = {
+	bg: "50",
+	"bg-muted": "100",
+	"bg-x-muted": "200",
+	"bg-bold": "800",
+	"bg-x-bold": "950",
+	text: "900",
+	"text-bold": "950",
+	"text-muted": "700",
+	"text-x-muted": "500",
+	"text-xx-muted": "400",
+	"text-on-bold": "50",
+	icon: "600",
+	"icon-muted": "500",
+	"border-muted": "200",
+	border: "300",
+	"border-bold": "600"
+};
+const SURFACE_DARK = {
+	bg: "900",
+	"bg-muted": "950",
+	"bg-x-muted": "950",
+	"bg-bold": "200",
+	"bg-x-bold": "50",
+	text: "100",
+	"text-bold": "50",
+	"text-muted": "300",
+	"text-x-muted": "500",
+	"text-xx-muted": "600",
+	"text-on-bold": "950",
+	icon: "400",
+	"icon-muted": "500",
+	"border-muted": "800",
+	border: "700",
+	"border-bold": "400"
+};
+/**
+* Chromatic roles: tints for alert/badge backgrounds, solids for fills. No bare
+* `bg` — see the module docblock. No `text-muted` either: a de-emphasised
+* coloured text could not hold its contrast target off a white surface, so the
+* way to soften coloured text is weight/size, not another colour.
+*/
+const CHROMATIC_LIGHT = {
+	"bg-x-muted": "50",
+	"bg-muted": "100",
+	text: "700",
+	"text-bold": "900",
+	icon: "600",
+	border: "200",
+	"border-bold": "300"
+};
+const CHROMATIC_DARK = {
+	"bg-x-muted": "950",
+	"bg-muted": "900",
+	text: "300",
+	"text-bold": "200",
+	icon: "400",
+	border: "800",
+	"border-bold": "700"
+};
+/**
+* The solid family — mode-stable, so a filled button keeps its identity when the
+* appearance flips. Fixed steps rather than the old scan-and-clamp: with a shared
+* lightness ladder every hue's 600 already sits at the same lightness, so there
+* is nothing left to search for. `text-on-<role>` is computed against `bg-solid`.
+*/
+const SOLID = {
+	"bg-solid": "600",
+	"bg-solid-bold": "700",
+	"bg-solid-x-bold": "800"
+};
+/**
+* Map a token key to its CSS custom property for a given role.
+*
+* `on` is the one irregular case: the foreground for a filled surface reads
+* `--color-text-on-<role>`, with the role *after* `on`, because it names what it
+* sits on rather than what it is.
+*
+* The utility class name is this minus the `--color-` prefix, which is why the
+* emitter and the linter can both derive their vocabulary from one function.
+*/
+function tokenVar(role, key) {
+	const dash = key.indexOf("-");
+	const target = dash === -1 ? key : key.slice(0, dash);
+	const variant = dash === -1 ? "" : key.slice(dash + 1);
+	if (variant === "on") return `--color-${target}-on-${role}`;
+	if (variant.startsWith("on-")) return `--color-${target}-on-${role}-${variant.slice(3)}`;
+	return variant ? `--color-${target}-${role}-${variant}` : `--color-${target}-${role}`;
+}
+/** The class name a token key produces for a role (`bg-danger-solid`, …). */
+const tokenClass = (role, key) => tokenVar(role, key).slice(8);
+/** Resolve the token set for one role over its hue. */
+function functionalRole(role, hueName, hue, kind = "chromatic", opts = {}) {
+	const numeric = hue.numeric;
+	const v = (n) => `var(--color-${hueName}-${snap(numeric, n)})`;
+	const hex = (n) => numeric[snap(numeric, n)];
+	const map = (table) => {
+		const out = {};
+		for (const [token, step] of Object.entries(table)) out[token] = v(step);
+		return out;
+	};
+	const solidStep = opts.solid ?? SOLID["bg-solid"];
+	const at = NUMERIC_STEPS.indexOf(solidStep);
+	const stepAt = (i) => NUMERIC_STEPS[Math.min(i, NUMERIC_STEPS.length - 1)];
+	const solids = map({
+		"bg-solid": solidStep,
+		"bg-solid-bold": stepAt(at + 1),
+		"bg-solid-x-bold": stepAt(at + 2)
+	});
+	const onSolid = pickOn(hex(solidStep), void 0, opts.foreground);
+	return {
+		role,
+		hue: hueName,
+		kind,
+		light: {
+			...map(kind === "surface" ? SURFACE_LIGHT : CHROMATIC_LIGHT),
+			...solids,
+			"text-on": onSolid
+		},
+		dark: {
+			...map(kind === "surface" ? SURFACE_DARK : CHROMATIC_DARK),
+			...solids,
+			"text-on": onSolid
+		}
+	};
+}
+/**
+* APCA targets. `TEXT` is the body-text bar; `SECONDARY` covers text on a
+* non-primary surface and de-emphasised text. `NON_TEXT` is the icon/boundary
+* tier — the APCA analogue of WCAG's 3:1, where a glyph may run more vivid than
+* text because shape carries meaning alongside contrast.
+*/
+const CONTRAST = {
+	TEXT: 75,
+	SECONDARY: 60,
+	NON_TEXT: 45
+};
+/**
+* Text tokens deliberately exempt from the contract. Placeholders and disabled
+* text are required to look unavailable; holding them to the body-text bar would
+* defeat the affordance. Nothing else may be exempt.
+*/
+const EXEMPT_TEXT = /* @__PURE__ */ new Set(["text-x-muted", "text-xx-muted"]);
+/**
+* Verify a role's contrast targets. Returns human-readable failures.
+*
+* Chromatic roles are checked against the surface planes they actually sit on
+* (`surfaceBg`) as well as their own tints — coloured text almost never appears
+* over its own solid, it appears over the page. Checking only within the role
+* would have missed the pairing that matters most.
+*/
+function checkContrast(fr, numericOf, surfaceBg, appearances = ["light", "dark"]) {
+	const failures = [];
+	const resolve = (val) => {
+		const m = /^var\(--color-([a-z0-9-]+)-(\d+)\)$/.exec(val);
+		if (!m) return val;
+		return numericOf(m[1])[m[2]] ?? val;
+	};
+	const fail = (appearance, msg) => failures.push(`${fr.role}/${appearance}: ${msg}`);
+	for (const [appearance, tokens] of [["light", fr.light], ["dark", fr.dark]]) {
+		if (!appearances.includes(appearance)) continue;
+		const ownBg = Object.keys(tokens).filter((k) => k === "bg" || k.startsWith("bg-")).filter((k) => !k.startsWith("bg-solid")).filter((k) => !k.startsWith("bg-bold") && !k.startsWith("bg-x-bold"));
+		const planes = fr.kind === "surface" ? ownBg.map((k) => [k, resolve(tokens[k])]) : [...(surfaceBg?.[appearance] ?? []).map((h, i) => [`surface#${i}`, h]), ...ownBg.map((k) => [k, resolve(tokens[k])])];
+		for (const [planeName, bg] of planes) {
+			const textMin = planeName === "bg" ? CONTRAST.TEXT : CONTRAST.SECONDARY;
+			for (const key of [
+				"text",
+				"text-bold",
+				"text-muted"
+			]) {
+				if (tokens[key] == null || EXEMPT_TEXT.has(key)) continue;
+				const min = key === "text-muted" ? CONTRAST.SECONDARY : textMin;
+				const lc = contrastLc(resolve(tokens[key]), bg);
+				if (lc < min) fail(appearance, `${key} Lc ${lc.toFixed(1)} < ${min} on ${planeName} ${bg}`);
+			}
+			const nonText = fr.kind === "surface" ? ["icon", "border-bold"] : ["icon"];
+			for (const key of nonText) {
+				if (tokens[key] == null) continue;
+				const lc = contrastLc(resolve(tokens[key]), bg);
+				if (lc < CONTRAST.NON_TEXT) fail(appearance, `${key} Lc ${lc.toFixed(1)} < ${CONTRAST.NON_TEXT} on ${planeName} ${bg}`);
+			}
+		}
+		const solid = resolve(tokens["bg-solid"]);
+		const onLc = contrastLc(tokens["text-on"], solid);
+		if (onLc < CONTRAST.SECONDARY) fail(appearance, `text-on Lc ${onLc.toFixed(1)} < ${CONTRAST.SECONDARY} on bg-solid`);
+		if (tokens["bg-bold"] != null && tokens["text-on-bold"] != null) {
+			const lc = contrastLc(resolve(tokens["text-on-bold"]), resolve(tokens["bg-bold"]));
+			if (lc < CONTRAST.TEXT) fail(appearance, `text-on-bold Lc ${lc.toFixed(1)} < ${CONTRAST.TEXT} on bg-bold`);
+		}
+	}
+	return failures;
+}
+/**
+* Runs the same monotonicity + contrast contract `generate()`'s `build()`
+* enforces at build time (by throwing), standalone and non-throwing — for a
+* caller that needs to validate a `colors` subtree *before* handing it to
+* `generate()`, most notably the EmDash design-system-editor's save route
+* (see AGENTS.md's "live theme editor" section): a client's edit gets the
+* exact same accessibility gate a real build would apply, synchronously, at
+* save time, rather than only discovering a violation at the next deploy.
+*
+* Deliberately re-derives `expandPalette`/`functionalRole` independently
+* rather than sharing state with `build()` — both are cheap, pure
+* computations, and keeping this standalone means it has no dependency on
+* `generate.ts`'s CSS-bundling half (which needs lightningcss/node:fs) and so
+* stays reachable from a Worker.
+*/
+function validateColorContract(colors) {
+	const expandedPalette = expandPalette(colors.palette);
+	const scaleRoles = [];
+	for (const [role, spec] of Object.entries(colors.roles)) {
+		const hueName = roleHue(spec);
+		const hue = expandedPalette[hueName];
+		if (hue == null) return [`role "${role}" references unknown palette hue "${hueName}"`];
+		scaleRoles.push(functionalRole(role, hueName, hue, roleKind(spec)));
+	}
+	const monotonicity = monotonicityErrors(expandedPalette);
+	if (monotonicity.length) return monotonicity;
+	const surfaceRole = scaleRoles.find((r) => r.role === "surface" && "bg" in r.light);
+	const numericOf = (hueName) => expandedPalette[hueName]?.numeric ?? {};
+	const resolve = (val) => {
+		const m = /^var\(--color-([a-z0-9-]+)-(\d+)\)$/.exec(val);
+		return m ? numericOf(m[1])[m[2]] ?? val : val;
+	};
+	const planeKeys = [
+		"bg",
+		"bg-muted",
+		"bg-x-muted"
+	];
+	const surfaceBg = surfaceRole ? {
+		light: planeKeys.flatMap((k) => surfaceRole.light[k] ? [resolve(surfaceRole.light[k])] : []),
+		dark: planeKeys.flatMap((k) => surfaceRole.dark[k] ? [resolve(surfaceRole.dark[k])] : [])
+	} : void 0;
+	return scaleRoles.flatMap((fr) => checkContrast(fr, numericOf, surfaceBg));
+}
+/**
+* The `reverseIndex` half of `generate()`'s `design-manifest.json` (css
+* format), standalone — a CSS var name → the config path that produced it
+* (e.g. `--color-navy-500` → `colors.palette.navy.anchors.500`). Kept in exact
+* step with the block inside `generate.ts`'s `build()` that builds the same
+* map (both read `TYPO_KEYMAP`/`BASE_HOOK` from `shared.ts`, never duplicated
+* inline) — this is the standalone half for a caller that has a
+* `DesignSystem` but no built `design-manifest.json` to fetch, most notably
+* the EmDash design-system-editor plugin route: a deployed Worker has no
+* filesystem to read a manifest asset from over HTTP without adding a
+* `network:request` capability + a hostname declared in `allowedHosts` for
+* *the site's own, deployment-specific* origin — recomputing this from the
+* `DesignSystem` the site's own build already bundles avoids that entirely.
+*/
+function buildReverseIndex(ds) {
+	const expandedPalette = expandPalette(ds.colors.palette);
+	const reverseIndex = {};
+	for (const [name, hue] of Object.entries(expandedPalette)) for (const n of Object.keys(hue.numeric)) reverseIndex[`--color-${name}-${n}`] = `colors.palette.${name}.anchors.${n}`;
+	const typoRoles = ds.typography?.roles ?? {};
+	for (const role of Object.keys(typoRoles)) for (const [key, [, sfx]] of Object.entries(TYPO_KEYMAP)) reverseIndex[`--${role}-${sfx}`] = `typography.roles.${role}.${key}`;
+	for (const [path, token] of Object.entries(LAYOUT_TOKENS)) reverseIndex[token] = `layout.${path}`;
+	const pDefaults = ds.patterns?.defaults ?? {};
+	const pRadii = ds.patterns?.radii ?? {};
+	const pGroups = ds.patterns?.groups ?? {};
+	const pItems = ds.patterns?.items ?? {};
+	for (const prop of Object.keys(pDefaults)) reverseIndex[`--${prop}-default`] = `patterns.defaults.${prop}`;
+	for (const [group, props] of Object.entries(pGroups)) for (const prop of Object.keys(props)) reverseIndex[`--${prop}-${group}`] = `patterns.groups.${group}.${prop}`;
+	for (const [name, item] of Object.entries(pItems)) {
+		const base = item.base ?? {};
+		for (const prop of Object.keys(base)) if (prop in BASE_HOOK) reverseIndex[`--${BASE_HOOK[prop]}-${name}`] = `patterns.items.${name}.base.${prop}`;
+	}
+	for (const name of Object.keys(pRadii)) if (!(`--br-${name}` in reverseIndex)) reverseIndex[`--br-${name}`] = `patterns.radii.${name}`;
+	return reverseIndex;
+}
+/**
+* Turns a design-system PATCH (paths matching `manifest.reverseIndex`'s own
+* config-path values, e.g. `colors.palette.navy.anchors.500`) into the runtime
+* `:root` override `<wc-theme-editor>` already injects client-side for its own
+* live preview — server-rendered instead, for the EmDash design-system-editor
+* plugin route to serve site-wide via a `page:fragments` `html` contribution
+* (see AGENTS.md's "live theme editor" + "EmDash plugin as the design-system
+* editing surface" sections). `''` (no matching var, or an empty patch) means
+* "nothing to override" — the caller should serve no fragment at all rather
+* than an empty `<style>` tag.
+*
+* Inverts `reverseIndex` (`cssVar → configPath`) once into `configPath →
+* cssVar`, so it costs one pass regardless of how deep the patch nests. A
+* patched leaf with no matching var (a `reverseIndex` miss — the same case
+* `<wc-theme-editor>`'s own `buildPatch()` calls "skipped") is silently
+* omitted here too, for the same reason: a value with nothing to preview is
+* not an error, just nothing to show yet.
+*/
+function patchToOverrideCss(patch, reverseIndex) {
+	const byPath = /* @__PURE__ */ new Map();
+	for (const [cssVar, path] of Object.entries(reverseIndex)) byPath.set(path, cssVar);
+	const lines = [];
+	const walk = (node, path) => {
+		if (node == null || typeof node !== "object") {
+			const cssVar = byPath.get(path);
+			if (cssVar && (typeof node === "string" || typeof node === "number")) lines.push(`  ${cssVar}: ${node};`);
+			return;
+		}
+		for (const [key, value] of Object.entries(node)) walk(value, path ? `${path}.${key}` : key);
+	};
+	walk(patch, "");
+	return lines.length ? `:root {\n${lines.join("\n")}\n}` : "";
+}
+
+export { roleKind as C, roleHue as S, ROLE_TOKEN_KEYS as _, expandPalette as a, TYPO_KEYMAP as b, monotonicityErrors as c, tokenVar as d, validateColorContract as f, REQUIRED_ROLES as g, LAYOUT_TOKENS as h, checkContrast as i, patchToOverrideCss as l, DARK_SEL as m, NUMERIC_STEPS as n, functionalRole as o, BASE_HOOK as p, buildReverseIndex as r, ladderWarnings as s, CONTRAST as t, tokenClass as u, SYSTEM_DARK_SEL as v, roleSolidOptions as w, layoutDecls as x, TW_CLASH as y };
+//# sourceMappingURL=tokens-CaIGQQLk.mjs.map