@stridge/noctis-design-tokens 1.0.0-beta.0

package/dist/graph/index.d.ts

@@ -0,0 +1,11 @@
+import { ROLE_VAR_PREFIX } from "./registry.js";
+import { DesignToken } from "./model.js";
+import { SEMANTIC_IDS } from "./roles.js";
+import { COMPONENT_DECLARATIONS } from "./components.js";
+//#region src/graph/index.d.ts
+/** Every authored token — semantics, statics, foundations, and seeds — in tier order. */
+declare const DESIGN_TOKENS: readonly DesignToken[];
+/** A semantic-role id from the engine-backed semantic set. */
+type SemanticRoleId = (typeof SEMANTIC_IDS)[number];
+//#endregion
+export { DESIGN_TOKENS, SemanticRoleId };

package/dist/graph/index.js

@@ -0,0 +1,26 @@
+import { COMPONENT_DECLARATIONS } from "./components.js";
+import { SEED_TOKENS } from "./inputs.js";
+import "./registry.js";
+import { validateGraph } from "./model.js";
+import { SEMANTIC_TOKENS } from "./roles.js";
+import { FOUNDATION_TOKENS } from "./scales.js";
+import { STATIC_SEMANTIC_TOKENS } from "./statics.js";
+//#region src/graph/index.ts
+/**
+* The assembled token graph: the single source the views, generators, and exports derive from.
+*
+* Concatenates the authored semantic, static-semantic, foundation, and seed tokens, holds the
+* component tier, and runs {@link validateGraph} at module load — a malformed graph is a
+* load-time failure, which is the point. {@link ROLE_VAR_PREFIX} is the namespace every
+* canonical token serializes under; the slot-internal `--_` namespace is fixed.
+*/
+/** Every authored token — semantics, statics, foundations, and seeds — in tier order. */
+const DESIGN_TOKENS = [
+	...SEMANTIC_TOKENS,
+	...STATIC_SEMANTIC_TOKENS,
+	...FOUNDATION_TOKENS,
+	...SEED_TOKENS
+];
+validateGraph(DESIGN_TOKENS, COMPONENT_DECLARATIONS);
+//#endregion
+export { DESIGN_TOKENS };

package/dist/graph/inputs.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/graph/inputs.js

@@ -0,0 +1,23 @@
+//#region src/graph/inputs.ts
+function seed(uuid, id, raw, description, usage) {
+	return {
+		uuid,
+		tier: "seed",
+		name: {
+			kind: "flat",
+			id
+		},
+		value: { raw },
+		description,
+		usage,
+		introduced: "0.0.0"
+	};
+}
+/** Seed input knobs — the foundations derive from these. */
+const SEED_TOKENS = [
+	seed("d8dec6e4-07ff-403d-ad16-b072a39d36f7", "font-scale", "1", "Type-scale multiplier applied to every named text size.", "The --noctis-seed-font-scale knob the System Controls type-size slider drives."),
+	seed("1cb82eee-e029-4538-9817-b0e533570797", "radius", "9999px", "Corner-radius knob the whole rounded scale derives from.", "The --noctis-seed-radius knob; 9999px is the pill Noctis default — controls go fully round while surfaces stay capped."),
+	seed("bcb4c342-6046-417d-953c-54aaf3fdf50e", "density", "1", "Density multiplier applied to every spacing step, control height, and region padding.", "The --noctis-seed-density knob the System Controls density picker drives; 1 is the default scale.")
+];
+//#endregion
+export { SEED_TOKENS };

package/dist/graph/model.d.ts

@@ -0,0 +1,205 @@
+import { ComponentCategory, STATE_REGISTRY, TOKEN_TIERS, TokenCategory } from "./registry.js";
+import { ThemeVar } from "@stridge/noctis-theme-engine";
+import { z } from "zod";
+
+//#region src/graph/model.d.ts
+/**
+ * How a token reaches Tailwind's `@theme` layer (no `bridge` = canonical-only, reached via
+ * `calc()`/`var()` or a component mint):
+ *   - `color` — `--color-{id}: var(canonical)` in `@theme inline` (the color-utility bridge);
+ *   - `utility` — reached through a dedicated `@utility` rule the generator authors;
+ *   - `theme` — a bare Tailwind name in plain `@theme`, carrying the **literal** value
+ *     duplicated from the canonical (breakpoints — `var()` is rejected in query preludes);
+ *   - `theme-inline` — a bare Tailwind name in `@theme inline` as `var(canonical)`.
+ */
+type TokenBridge = {
+  readonly kind: "color";
+} | {
+  readonly kind: "utility";
+} | {
+  readonly kind: "theme";
+  readonly name: string;
+} | {
+  readonly kind: "theme-inline";
+  readonly name: string;
+};
+/** How a token is grouped in the reference view (display metadata, not the structural category). */
+type TokenGroup = "surface" | "text" | "border" | "accent" | "control" | "status" | "utility" | "chart" | "avatar";
+/**
+ * A structured token name. The flat form carries an id verbatim (seed, foundation, and semantic
+ * tokens — the category segment comes from `tier`/`category` at serialization, never the id);
+ * the component form is `component[-anatomy]-property[-state]`.
+ */
+type TokenName = {
+  readonly kind: "flat";
+  readonly id: string;
+} | {
+  readonly kind: "component";
+  readonly component: string;
+  readonly anatomy?: string;
+  readonly property: string;
+  readonly state?: (typeof STATE_REGISTRY)[number];
+};
+/**
+ * A token's value in the alias graph: a sibling role id, another token's uuid, an engine
+ * primitive, or a raw literal. A raw value may carry a light-mode twin (`rawLight`) for the
+ * accent-independent palettes that switch on the resolved mode.
+ */
+type TokenValue = {
+  readonly role: string;
+} | {
+  readonly token: string;
+} | {
+  readonly primitive: ThemeVar;
+} | {
+  readonly raw: string;
+  readonly rawLight?: string;
+};
+/** A token's deprecation record — kept so a retired token stays in the graph as a redirect. */
+interface TokenDeprecation {
+  readonly version: string;
+  readonly comment: string;
+  readonly replacedBy: readonly string[];
+}
+/**
+ * A design token: stable identity, a structured name, an alias-graph value, and the view
+ * metadata the reference surfaces render. Semantic/foundation tokens carry `label`/`group`/
+ * `category`/`utility`/`bridge`; seed and component tokens leave them unset (the validator
+ * enforces the `category` rule).
+ */
+interface DesignToken {
+  readonly uuid: string;
+  readonly tier: (typeof TOKEN_TIERS)[number];
+  readonly name: TokenName;
+  readonly value: TokenValue;
+  readonly description: string;
+  readonly usage: string;
+  readonly introduced: string;
+  readonly deprecated?: TokenDeprecation;
+  readonly label?: string;
+  /** Reference-view grouping (display metadata) — formerly `category`; renamed to free the structural sense. */
+  readonly group?: TokenGroup;
+  /**
+   * The structural category — the `{category}` segment of the canonical
+   * `--noctis-{category}-{name}`. Required for `foundation` and `semantic` tokens, forbidden
+   * for `seed` and `component` tokens; semantic tokens are always `"color"` (all enforced by
+   * {@link validateGraph}).
+   */
+  readonly category?: TokenCategory;
+  /**
+   * The Tailwind utility (or utility prefix) that paints this token — **display metadata**
+   * for the docs/reference surfaces only. Emission is controlled exclusively by `bridge`.
+   */
+  readonly utility?: string;
+  readonly bridge?: TokenBridge;
+  /**
+   * Per-variant fallback re-points for a component mint: option axis → option value → the fallback
+   * the internal var takes under `[data-{axis}={value}]`. The public var stays at the chain head,
+   * so one consumer override still wins across every variant.
+   */
+  readonly variants?: Readonly<Record<string, Readonly<Record<string, TokenValue>>>>;
+}
+/** A primitive's token contract: its anatomy, option axes, consumed bridge utilities, and minted tokens. */
+interface ComponentDeclaration {
+  readonly component: string;
+  /**
+   * The showcase group this component belongs to, from {@link CATEGORY_REGISTRY}. Catalog
+   * components carry one; mechanisms (the polymorphic base, radius scope, visually-hidden) leave it
+   * unset and never appear in the gallery.
+   */
+  readonly category?: ComponentCategory;
+  readonly anatomy: readonly string[];
+  readonly options: Readonly<Record<string, readonly string[]>>;
+  readonly states: readonly string[];
+  /**
+   * The exact bridge utilities the recipes name directly (`"bg-surface"`, `"border-border"`,
+   * `"shadow-modal"`, …) — `minted-identity`'s per-owner allow-list. Identity values that flow
+   * through a minted internal var are NOT listed here; a role aliased by a mint is the mint's value,
+   * not a consumed utility. Validated against {@link consumableUtilities}; pinned to the recipes by
+   * the parity test.
+   */
+  readonly consumes: readonly string[];
+  readonly mints: readonly DesignToken[];
+  /**
+   * Maps a `TokenName.anatomy` key to the `data-slot`s its `--_` internals attach to, for the case
+   * where one anatomy's tokens are shared across several slots (Menu's `item` tokens span four item
+   * slots). When unset for an anatomy, its internals attach to the single `{component}-{anatomy}`
+   * slot (or the root `{component}` slot when the anatomy is omitted).
+   */
+  readonly slotGroups?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Maps an option axis to the `data-slot` that stamps its `data-{axis}` attribute, so a variant
+   * re-point keys off the right selector (Menu's `variant` stamps on `menu-item`).
+   */
+  readonly optionSlots?: Readonly<Record<string, string>>;
+  /**
+   * Set when the component ships a recipe that is applied as a bare class list — exported as a
+   * `*Variants` helper or composed into another element through Base UI's `render`, where the host's
+   * own `data-slot` replaces this component's. The root-slot internals are then *also* declared on a
+   * `.noctis-{component}` class the recipe carries, so the chain resolves on the recipe element even
+   * when its `data-slot` is not `{component}` (Button composed into a `Menu.Trigger`/`Sheet.Close`).
+   */
+  readonly recipePortable?: boolean;
+  /**
+   * Optional per-component prefix prepended to every emitted `data-slot` value (NOT the anatomy
+   * names, NOT the public `--noctis-*` var names). Set to `"noctis"` on `tabs` so its generated
+   * `@layer noctis.components` block targets `[data-slot="noctis-tabs*"]` to match the prefixed
+   * slots the migrated `tabs.tsx` stamps. Pre-1.0 alpha: no dual back-compat arm.
+   *
+   * Doubles as the **migration signal** (D4 final): a declaration carrying a `slotPrefix` has moved
+   * to the single-`data-slot` anchor model and drops the `.noctis-{component}` class arm entirely
+   * (the generator suppresses the portable hook for it), since D12's `.props()` spreads `data-slot`
+   * onto a foreign element so the escape hatch works through the attribute. Un-migrated components
+   * keep the dual `:where([data-slot="x"], .noctis-x)` arm unchanged.
+   */
+  readonly slotPrefix?: string;
+  /**
+   * A stable marker attribute the component's **root-slot** internals (and the per-`[data-{axis}]`
+   * re-points keyed off the root) are declared on instead of `[data-slot="{prefix}-{component}"]`.
+   * Set to `"button"` on `button` so its `--_button-*` chain is emitted as `[data-button]{…}` and
+   * `[data-button][data-size="sm"]{…}` — the generalization of surface's hand-authored `data-surface`.
+   *
+   * Button is a class-escape-hatch primitive: `Button.props()` styles a *foreign* element (the rail's
+   * `Collapsible.Trigger`, a docs `<a>`) and must NOT clobber that element's own `data-slot`. Keying
+   * the internals off a dedicated marker lets the escape hatch carry `data-button` (plus the variant/
+   * size axes) without overwriting the host's slot, while the component itself still stamps the catalog
+   * `data-slot="{prefix}-{component}"` for SLOTS.md / testing. Only the root-slot internals move to the
+   * marker; descendant-anatomy internals (and re-points whose token lives on a descendant) stay on
+   * their `[data-slot]`. Requires `slotPrefix` (the marker model is part of the migrated single-anchor
+   * world).
+   */
+  readonly marker?: string;
+}
+/** Structural schema for a single token (graph-level invariants are checked by {@link validateGraph}). */
+declare const designTokenSchema: z.ZodType<DesignToken>;
+/** Structural schema for a component declaration. */
+declare const componentDeclarationSchema: z.ZodType<ComponentDeclaration>;
+/**
+ * The canonical CSS custom-property name for a token. Component tokens keep the ungoverned
+ * component grammar (`--noctis-{body}`); seeds serialize as `{prefix}-seed-{id}`; foundation
+ * and semantic tokens carry their structural category (`{prefix}-{category}-{id}`). The prefix
+ * is a parameter so the same graph can serialize under an alternate namespace; the default is
+ * {@link ROLE_VAR_PREFIX}.
+ */
+declare function cssVarName(token: DesignToken, rolePrefix: string): string;
+/**
+ * The bare Tailwind `@theme` key a token's bridge declares, or `undefined` when the token has
+ * no `@theme` key (no bridge, or a `utility`-kind bridge reached via a dedicated `@utility`
+ * rule). `color`-kind bridges derive `--color-{id}`; `theme`/`theme-inline` bridges carry an
+ * explicit name. The single source of truth for bridge naming — generators must not re-derive it.
+ */
+declare function bridgeVarName(token: DesignToken): string | undefined;
+/** A graph validation failure, with the offending token/declaration named in the message. */
+declare class GraphValidationError extends Error {
+  constructor(message: string);
+}
+/**
+ * Enforce the cross-token invariants the serializers and generators depend on: structural schema
+ * conformance, the tier↔category contract, unique identity (uuid + serialized var name), the
+ * reserved engine namespace, bridge-name uniqueness, resolvable acyclic `{ token }`/`{ role }`
+ * aliases, existing `replacedBy` redirects, grammar-clean component property names, and
+ * well-formed component declarations. Throws {@link GraphValidationError} on the first violation.
+ */
+declare function validateGraph(tokens: readonly DesignToken[], components: readonly ComponentDeclaration[]): void;
+//#endregion
+export { ComponentDeclaration, DesignToken, GraphValidationError, TokenBridge, TokenDeprecation, TokenGroup, TokenName, TokenValue, bridgeVarName, componentDeclarationSchema, cssVarName, designTokenSchema, validateGraph };

package/dist/graph/model.js

@@ -0,0 +1,282 @@
+import { ABBREVIATED_PROPERTIES, CATEGORY_REGISTRY, COMPOSITE_PROPERTIES, ROLE_VAR_PREFIX, STATE_REGISTRY, TOKEN_CATEGORIES, TOKEN_TIERS } from "./registry.js";
+import { serializeTokenName } from "./serialize.js";
+import { THEME_VARS } from "@stridge/noctis-theme-engine";
+import { z } from "zod";
+//#region src/graph/model.ts
+/**
+* The token graph data model: zod-validated TypeScript as the single source of truth.
+*
+* A {@link DesignToken} carries stable UUID identity, a structured {@link TokenName}, and an
+* alias-graph {@link TokenValue} — an engine primitive, another token, a sibling role, or a raw
+* literal. {@link ComponentDeclaration} records a primitive's anatomy, option axes, consumed
+* roles, and the component tokens it mints. {@link validateGraph} enforces the cross-token
+* invariants the serializers and generators rely on (unique identity, resolvable acyclic
+* aliases, grammar-clean property names). JSON and DTCG are generated *from* this graph; nothing
+* is authored in them.
+*/
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/**
+* Flat semantic/foundation ids — leading digits (`2xl`), the Tailwind `--modifier` double dash,
+* and a fractional segment (`1.5`, the spacing-ramp half steps) permitted. The id carries the
+* bare `.`; CSS emission backslash-escapes it (`--noctis-space-1\.5`) at the generator.
+*/
+const FLAT_ID = /^[a-z0-9]+(?:\.[0-9]+)?(?:-{1,2}[a-z0-9]+(?:\.[0-9]+)?)*$/;
+/**
+* A bridge name: a bare Tailwind `@theme` key, double-dash modifier suffix
+* (`--text-regular--line-height`) and fractional segment (`--spacing-1.5`) permitted — the
+* fractional dot is stored bare and escaped at CSS emission, like {@link FLAT_ID}.
+*/
+const BRIDGE_NAME = /^--[a-z][a-z0-9]*(?:-{1,2}[a-z0-9]+(?:\.[0-9]+)?)*$/;
+const tokenNameSchema = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("flat"),
+	id: z.string().regex(FLAT_ID)
+}), z.object({
+	kind: z.literal("component"),
+	component: z.string().regex(/^[a-z][a-z0-9-]*$/),
+	anatomy: z.string().regex(KEBAB).optional(),
+	property: z.string().min(1),
+	state: z.enum(STATE_REGISTRY).optional()
+})]);
+const tokenValueSchema = z.union([
+	z.object({ role: z.string() }).strict(),
+	z.object({ token: z.string() }).strict(),
+	z.object({ primitive: z.enum(THEME_VARS) }).strict(),
+	z.object({
+		raw: z.string(),
+		rawLight: z.string().optional()
+	}).strict()
+]);
+const groupSchema = z.enum([
+	"surface",
+	"text",
+	"border",
+	"accent",
+	"control",
+	"status",
+	"utility",
+	"chart",
+	"avatar"
+]);
+const tokenBridgeSchema = z.discriminatedUnion("kind", [
+	z.object({ kind: z.literal("color") }).strict(),
+	z.object({ kind: z.literal("utility") }).strict(),
+	z.object({
+		kind: z.literal("theme"),
+		name: z.string().regex(BRIDGE_NAME)
+	}).strict(),
+	z.object({
+		kind: z.literal("theme-inline"),
+		name: z.string().regex(BRIDGE_NAME)
+	}).strict()
+]);
+/** Structural schema for a single token (graph-level invariants are checked by {@link validateGraph}). */
+const designTokenSchema = z.object({
+	uuid: z.uuid(),
+	tier: z.enum(TOKEN_TIERS),
+	name: tokenNameSchema,
+	value: tokenValueSchema,
+	description: z.string(),
+	usage: z.string(),
+	introduced: z.string(),
+	deprecated: z.object({
+		version: z.string(),
+		comment: z.string(),
+		replacedBy: z.array(z.string())
+	}).optional(),
+	label: z.string().optional(),
+	group: groupSchema.optional(),
+	category: z.enum(TOKEN_CATEGORIES).optional(),
+	utility: z.string().optional(),
+	bridge: tokenBridgeSchema.optional(),
+	variants: z.record(z.string(), z.record(z.string(), tokenValueSchema)).optional()
+});
+/** Structural schema for a component declaration. */
+const componentDeclarationSchema = z.object({
+	component: z.string().regex(/^[a-z][a-z0-9-]*$/),
+	category: z.enum(CATEGORY_REGISTRY).optional(),
+	anatomy: z.array(z.string().regex(KEBAB)),
+	options: z.record(z.string(), z.array(z.string())),
+	states: z.array(z.enum(STATE_REGISTRY)),
+	consumes: z.array(z.string()),
+	mints: z.array(designTokenSchema),
+	slotGroups: z.record(z.string(), z.array(z.string())).optional(),
+	optionSlots: z.record(z.string(), z.string()).optional(),
+	recipePortable: z.boolean().optional(),
+	slotPrefix: z.string().regex(/^[a-z][a-z0-9-]*$/).optional(),
+	marker: z.string().regex(/^[a-z][a-z0-9-]*$/).optional()
+});
+/**
+* The canonical CSS custom-property name for a token. Component tokens keep the ungoverned
+* component grammar (`--noctis-{body}`); seeds serialize as `{prefix}-seed-{id}`; foundation
+* and semantic tokens carry their structural category (`{prefix}-{category}-{id}`). The prefix
+* is a parameter so the same graph can serialize under an alternate namespace; the default is
+* {@link ROLE_VAR_PREFIX}.
+*/
+function cssVarName(token, rolePrefix) {
+	const body = serializeTokenName(token.name);
+	if (token.tier === "component") return `--noctis-${body}`;
+	if (token.tier === "seed") return `${rolePrefix}-seed-${body}`;
+	if (!token.category) throw new Error(`${token.tier} token "${body}" has no structural category — cannot derive its canonical name`);
+	return `${rolePrefix}-${token.category}-${body}`;
+}
+/**
+* The bare Tailwind `@theme` key a token's bridge declares, or `undefined` when the token has
+* no `@theme` key (no bridge, or a `utility`-kind bridge reached via a dedicated `@utility`
+* rule). `color`-kind bridges derive `--color-{id}`; `theme`/`theme-inline` bridges carry an
+* explicit name. The single source of truth for bridge naming — generators must not re-derive it.
+*/
+function bridgeVarName(token) {
+	if (!token.bridge) return void 0;
+	switch (token.bridge.kind) {
+		case "color": return `--color-${serializeTokenName(token.name)}`;
+		case "utility": return;
+		case "theme":
+		case "theme-inline": return token.bridge.name;
+	}
+}
+/**
+* The gated color-utility prefixes Tailwind generates for every `--color-{id}` (the family-table
+* paint families a recipe may consume). `outline-*` is deliberately absent — it is a *free* family
+* (the focus-ring composite's domain), so an `outline-{role}` is never a declared `consumes` entry.
+*/
+const COLOR_UTILITY_PREFIXES = [
+	"bg",
+	"from",
+	"via",
+	"to",
+	"text",
+	"placeholder",
+	"caret",
+	"accent",
+	"decoration",
+	"fill",
+	"stroke",
+	"border",
+	"divide",
+	"ring",
+	"ring-offset",
+	"inset-ring"
+];
+/**
+* Every bridge utility a component recipe may name in its `consumes` declaration: a color role's
+* full prefix expansion (`bg-`/`text-`/`border-`/… of each `color`-kind semantic token), the
+* single named utility of a `utility`-kind semantic token, and the named semantic shadows. Scale
+* steps (`rounded-*`, `text-{size}`, spacing) are excluded — identity values flow through mints,
+* not `consumes`. The single source of truth shared by {@link validateGraph} and the parity test.
+*/
+function consumableUtilities(tokens) {
+	const utilities = /* @__PURE__ */ new Set();
+	for (const token of tokens) if (token.tier === "semantic") {
+		if (token.bridge?.kind === "color") {
+			const id = serializeTokenName(token.name);
+			for (const prefix of COLOR_UTILITY_PREFIXES) utilities.add(`${prefix}-${id}`);
+		} else if (token.utility) utilities.add(token.utility);
+	} else if (token.tier === "foundation" && token.bridge?.kind === "theme-inline" && token.utility?.startsWith("shadow-")) utilities.add(token.utility);
+	return utilities;
+}
+function isCompositeProperty(property) {
+	return COMPOSITE_PROPERTIES.includes(property);
+}
+/** A graph validation failure, with the offending token/declaration named in the message. */
+var GraphValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "GraphValidationError";
+	}
+};
+/**
+* Enforce the cross-token invariants the serializers and generators depend on: structural schema
+* conformance, the tier↔category contract, unique identity (uuid + serialized var name), the
+* reserved engine namespace, bridge-name uniqueness, resolvable acyclic `{ token }`/`{ role }`
+* aliases, existing `replacedBy` redirects, grammar-clean component property names, and
+* well-formed component declarations. Throws {@link GraphValidationError} on the first violation.
+*/
+function validateGraph(tokens, components) {
+	for (const token of tokens) {
+		const parsed = designTokenSchema.safeParse(token);
+		if (!parsed.success) throw new GraphValidationError(`invalid token ${describe(token)}: ${parsed.error.issues[0]?.message}`);
+	}
+	for (const decl of components) {
+		const parsed = componentDeclarationSchema.safeParse(decl);
+		if (!parsed.success) throw new GraphValidationError(`invalid declaration "${decl.component}": ${parsed.error.issues[0]?.message}`);
+	}
+	const allTokens = [...tokens, ...components.flatMap((c) => c.mints)];
+	const byUuid = /* @__PURE__ */ new Map();
+	for (const token of allTokens) {
+		if (byUuid.has(token.uuid)) throw new GraphValidationError(`duplicate uuid ${token.uuid} (${describe(token)})`);
+		byUuid.set(token.uuid, token);
+	}
+	for (const token of allTokens) {
+		const categorized = token.tier === "foundation" || token.tier === "semantic";
+		if (categorized && !token.category) throw new GraphValidationError(`${token.tier} token ${describe(token)} is missing a structural category`);
+		if (!categorized && token.category) throw new GraphValidationError(`${token.tier} token ${describe(token)} must not carry a structural category`);
+		if (token.tier === "semantic" && token.category !== "color") throw new GraphValidationError(`semantic token ${describe(token)} must have category "color" (got "${token.category}")`);
+	}
+	const seenVars = /* @__PURE__ */ new Set();
+	for (const token of allTokens) {
+		const name = cssVarName(token, ROLE_VAR_PREFIX);
+		if (seenVars.has(name)) throw new GraphValidationError(`duplicate css variable ${name}`);
+		if (name.startsWith(`--noctis-engine-`)) throw new GraphValidationError(`token ${describe(token)} serializes into the reserved engine namespace (${name})`);
+		seenVars.add(name);
+	}
+	const seenBridges = /* @__PURE__ */ new Set();
+	for (const token of allTokens) {
+		const bridge = bridgeVarName(token);
+		if (!bridge) continue;
+		if (seenBridges.has(bridge)) throw new GraphValidationError(`duplicate bridge name ${bridge} (${describe(token)})`);
+		if (seenVars.has(bridge)) throw new GraphValidationError(`bridge name ${bridge} (${describe(token)}) collides with a canonical css variable`);
+		seenBridges.add(bridge);
+	}
+	const roleById = new Map(allTokens.filter((t) => t.tier === "semantic").map((t) => [serializeTokenName(t.name), t]));
+	for (const token of allTokens) {
+		if ("token" in token.value && !byUuid.has(token.value.token)) throw new GraphValidationError(`token ${describe(token)} aliases a missing uuid ${token.value.token}`);
+		if ("role" in token.value && !roleById.has(token.value.role)) throw new GraphValidationError(`token ${describe(token)} aliases a missing role "${token.value.role}"`);
+		if (token.deprecated) {
+			for (const uuid of token.deprecated.replacedBy) if (!byUuid.has(uuid)) throw new GraphValidationError(`token ${describe(token)} is replaced by a missing uuid ${uuid}`);
+		}
+		if (token.name.kind === "component") {
+			const { property } = token.name;
+			if (!isCompositeProperty(property) && !KEBAB.test(property)) throw new GraphValidationError(`token ${describe(token)} property "${property}" is not kebab-case`);
+			if (ABBREVIATED_PROPERTIES.includes(property)) throw new GraphValidationError(`token ${describe(token)} property "${property}" is an abbreviation — spell it out`);
+		}
+	}
+	const consumable = consumableUtilities(tokens);
+	for (const decl of components) {
+		for (const mint of decl.mints) {
+			if (mint.tier !== "component") throw new GraphValidationError(`"${decl.component}" mints a non-component token ${describe(mint)}`);
+			if (mint.name.kind !== "component" || mint.name.component !== decl.component) throw new GraphValidationError(`"${decl.component}" mints ${describe(mint)} under a foreign component`);
+		}
+		for (const utility of decl.consumes) if (!consumable.has(utility)) throw new GraphValidationError(`"${decl.component}" consumes an unknown bridge utility "${utility}"`);
+		const anatomy = new Set(decl.anatomy);
+		for (const [key, slots] of Object.entries(decl.slotGroups ?? {})) for (const slot of slots) if (!anatomy.has(slot)) throw new GraphValidationError(`"${decl.component}" slotGroup "${key}" references a missing slot "${slot}"`);
+		for (const [axis, slot] of Object.entries(decl.optionSlots ?? {})) {
+			if (!(axis in decl.options)) throw new GraphValidationError(`"${decl.component}" optionSlots axis "${axis}" is not an option`);
+			if (!anatomy.has(slot)) throw new GraphValidationError(`"${decl.component}" optionSlots axis "${axis}" stamps a missing slot "${slot}"`);
+		}
+		if (decl.marker !== void 0 && decl.slotPrefix === void 0) throw new GraphValidationError(`"${decl.component}" sets a marker "${decl.marker}" without a slotPrefix — the marker model is part of the migrated single-anchor world`);
+		for (const mint of decl.mints) for (const [axis, byValue] of Object.entries(mint.variants ?? {})) {
+			const values = decl.options[axis];
+			if (!values) throw new GraphValidationError(`${describe(mint)} re-points unknown axis "${axis}"`);
+			for (const value of Object.keys(byValue)) if (!values.includes(value)) throw new GraphValidationError(`${describe(mint)} re-points unknown "${axis}" value "${value}"`);
+		}
+	}
+	detectAliasCycles(allTokens, byUuid, roleById);
+}
+function detectAliasCycles(tokens, byUuid, roleById) {
+	const state = /* @__PURE__ */ new Map();
+	const visit = (token) => {
+		const mark = state.get(token.uuid);
+		if (mark === "done") return;
+		if (mark === "visiting") throw new GraphValidationError(`alias cycle through ${describe(token)}`);
+		state.set(token.uuid, "visiting");
+		const next = "token" in token.value ? byUuid.get(token.value.token) : "role" in token.value ? roleById.get(token.value.role) : void 0;
+		if (next) visit(next);
+		state.set(token.uuid, "done");
+	};
+	for (const token of tokens) visit(token);
+}
+function describe(token) {
+	return `"${serializeTokenName(token.name)}"`;
+}
+//#endregion
+export { GraphValidationError, bridgeVarName, componentDeclarationSchema, cssVarName, designTokenSchema, validateGraph };

package/dist/graph/registry.d.ts

@@ -0,0 +1,67 @@
+//#region src/graph/registry.d.ts
+/**
+ * Closed vocabularies the token grammar is built from.
+ *
+ * These are the controlled sets a structured token name draws on: the interaction states a
+ * token may key off, the composite pseudo-properties that stand in where no single real CSS
+ * property names an anatomy-level seam, and the abbreviation denylist that keeps property
+ * names spelled out. Extending any of them is a deliberate schema change here — never an
+ * ad-hoc string at a call site.
+ */
+/**
+ * Interaction states a component token may carry, as the final name segment. The default
+ * (rest) state is the absence of a segment, so there is no `default` member. Order is the
+ * serialization tie-break only; names never combine two states.
+ */
+declare const STATE_REGISTRY: readonly ["hover", "active", "focus", "disabled", "selected", "highlighted", "open", "checked"];
+/** A sanctioned interaction state. */
+type TokenState = (typeof STATE_REGISTRY)[number];
+/**
+ * Composite pseudo-properties: names admitted as a token `property` where no single real CSS
+ * property names the seam a consumer would override. Each expands to real CSS properties at the
+ * recipe — `size` is width + height (Tailwind's `size-*`). The seam vocabulary grows only by
+ * adding a member here.
+ */
+declare const COMPOSITE_PROPERTIES: readonly ["size"];
+/** A sanctioned composite pseudo-property. */
+type CompositeProperty = (typeof COMPOSITE_PROPERTIES)[number];
+/**
+ * The token tiers. `seed` is the knob stratum (the System Controls inputs the foundations
+ * derive from); `foundation` is the authored non-color scale stratum (type, radius, motion,
+ * z, …); `semantic` is the intent-named color stratum over the engine; `component` is the
+ * minted per-component seam stratum. The engine stratum is not a graph tier — it is the
+ * engine's own `--noctis-engine-*` namespace.
+ */
+declare const TOKEN_TIERS: readonly ["seed", "foundation", "semantic", "component"];
+/** A token tier. */
+type TokenTier = (typeof TOKEN_TIERS)[number];
+/**
+ * The closed structural-category vocabulary — the `{category}` segment of a canonical
+ * `--noctis-{category}-{name}` CSS variable. Required on `foundation` and
+ * `semantic` tokens, forbidden on `seed` and `component` tokens (the validator enforces
+ * both). Distinct from {@link TokenGroup} (the reference-view grouping) and from
+ * {@link ComponentCategory} (the showcase groups) — do not conflate the three. Growing the
+ * vocabulary is a deliberate schema change here, never an ad-hoc string in a data file.
+ */
+declare const TOKEN_CATEGORIES: readonly ["color", "space", "size", "text", "leading", "radius", "shadow", "duration", "ease", "z", "font", "tracking", "breakpoint", "container", "border", "opacity", "blur", "animate"];
+/** A sanctioned structural category — the category segment of a canonical CSS variable name. */
+type TokenCategory = (typeof TOKEN_CATEGORIES)[number];
+/**
+ * The namespace every canonical token serializes under. A parameter on the serializers so the
+ * same graph can emit under an alternate namespace; this constant is the single source of truth
+ * for the default. `--noctis-engine-*` is the engine's reserved private namespace — the
+ * validator rejects any graph token that serializes into it.
+ */
+declare const ROLE_VAR_PREFIX: "--noctis";
+/**
+ * The closed component-category vocabulary the showcase groups primitives by. A
+ * {@link ComponentDeclaration} draws its optional `category` from this set, and the gallery renders
+ * one localized group per member in this order. Mechanisms (the polymorphic base, the radius scope,
+ * the visually-hidden helper) carry no category — they are never showcased. Growing the vocabulary
+ * is a deliberate schema change here, never an ad-hoc string in the docs app.
+ */
+declare const CATEGORY_REGISTRY: readonly ["actions", "fields", "navigation", "overlays", "surfaces", "data", "typography", "system"];
+/** A sanctioned component category. */
+type ComponentCategory = (typeof CATEGORY_REGISTRY)[number];
+//#endregion
+export { CATEGORY_REGISTRY, COMPOSITE_PROPERTIES, ComponentCategory, CompositeProperty, ROLE_VAR_PREFIX, STATE_REGISTRY, TOKEN_CATEGORIES, TOKEN_TIERS, TokenCategory, TokenState, TokenTier };