@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/entities/system/StyleProperty.js

@@ -0,0 +1,438 @@
+import { isRef, kindOf, pathOf, ref, refSchema, sourceOf, splitRef } from "../../framework/utils/refs.js";
+import { defineEntity } from "../../framework/defineEntity.js";
+import { cssValueIssue, isCssProperty } from "../../css/values.js";
+import { camelCase } from "./style-bag.js";
+import { z } from "zod";
+//#region src/entities/system/StyleProperty.ts
+/**
+* A style property: a prop a component can expose, mapped to CSS properties with an allowed value set.
+* The forms a `values` entry takes come first, each a zod schema built from its context, and the
+* entity's fields read them.
+*/
+/** A style property's path is the JSX prop a component exposes, so each segment is an identifier. */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** A token group's ref. Through the framework helper rather than `Token.ref`: `Token` reaches this
+*  module through `Modifier` and `Composite`, so importing it here is a cycle. */
+const tokenGroup = (group) => ref("token", group);
+/** A token ref as a model writes it, spelled from the ref itself so the prose can't drift. */
+const spelled = (path) => JSON.stringify(tokenGroup(path));
+const stylePropertyPath = z.string().check((ctx) => {
+	const bad = ctx.value.split("/").find((segment) => !IDENTIFIER.test(segment));
+	if (bad === void 0) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		message: `a style property's name is the JSX prop a component exposes (\`<Box ${camelCase(bad)}="…" />\`), and \`${bad}\` is not a valid prop name. Write it camelCase — \`${camelCase(bad)}\` — and put the CSS property in \`properties\`.`
+	});
+});
+/** A number alias is a number whose CSS form is not the number: `6` resolves to
+*  `repeat(6, minmax(0, 1fr))`. */
+const aliasName = z.union([z.string(), z.number()]);
+/** The first property among `properties` that refuses `text`, as the refusal. A property the table
+*  can't judge says nothing. */
+function cssIssue(properties, text, grammar) {
+	for (const property of properties ?? []) {
+		const issue = cssValueIssue({
+			property,
+			value: text,
+			grammar
+		});
+		if (issue !== void 0 && issue !== "unknown") return issue;
+	}
+}
+/** A check refusing CSS text no property takes, on the schema whose value is that text. A value the
+*  table can't judge goes to the grammar the config carries, when a write lane armed it with one. */
+const cssText = ({ properties, config }, textOf) => (ctx) => {
+	const issue = cssIssue(properties, textOf(ctx.value), config?.cssGrammar);
+	if (issue === void 0) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		message: issue
+	});
+};
+/** Whether a ref addresses one item, asked of the config that holds it. */
+function refNamesItem(config, target) {
+	const { kind, path, source, member } = splitRef(target);
+	if (member !== void 0 || path === "") return false;
+	return (source === void 0 ? config : config.configFor(target))?.resolve(kind, path) !== void 0;
+}
+/** A check on a ref schema that admits only one of the two things a token ref can name. */
+const namesItem = (config, wanted) => (ctx) => {
+	if (config === void 0 || refNamesItem(config, ctx.value) === wanted) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		message: wanted ? "names a group, not one token" : "names one token, not a group"
+	});
+};
+/**
+* Every form, keyed by kind, in the order a stored entry is matched against them. A ref is a record
+* of one string too, so `aliasToken` comes before `aliasDeclarations`; a boolean alias is a flag
+* whatever its value holds, so `flag` comes before the named aliases. `token` and `tokenGroup` are
+* one stored shape; with a config each refuses what the other admits, and without one a ref reads
+* as `token`.
+*/
+/** A declaration bag's key. A ref is a record of one string too, so the ref marker is not a key here,
+*  or a ref no ref form admits would read as a bag. */
+const declarationKey = z.string().regex(/^(?!__ref$)/);
+const STYLE_PROP_VALUE_FORMS = {
+	keyword: (ctx = {}) => z.string().meta({
+		title: "Keyword",
+		description: "A literal whose authored form is its resolved form: `row`, `flex`."
+	}).check(cssText(ctx, (value) => value)),
+	number: (_ctx = {}) => z.number().meta({
+		title: "Number",
+		description: "A scale whose values are numbers (`gridTemplateColumns: [1, …, 12]`), stored as authored."
+	}),
+	token: ({ config } = {}) => refSchema.meta({
+		title: "Token",
+		description: "A ref to one token, emitted as its `var()`."
+	}).check(namesItem(config, true)),
+	tokenGroup: ({ config } = {}) => refSchema.meta({
+		title: "Token group",
+		description: "A ref to a token group, which offers every token in it and follows the group as it changes."
+	}).check(namesItem(config, false)),
+	flag: (_ctx = {}) => z.strictObject({
+		alias: z.boolean(),
+		value: z.union([
+			z.string(),
+			refSchema,
+			z.record(z.string(), z.string())
+		])
+	}).meta({
+		title: "Flag",
+		description: "A boolean alias for a boolean-shaped prop: `<Box border />` sets `border-width: 1px`."
+	}),
+	aliasToken: ({ config } = {}) => z.strictObject({
+		alias: aliasName,
+		value: refSchema.check(namesItem(config, true))
+	}).meta({
+		title: "Token alias",
+		description: "One token under a name of the prop's own, still emitted as its `var()`."
+	}),
+	aliasLiteral: (ctx = {}) => z.strictObject({
+		alias: aliasName,
+		value: z.string()
+	}).meta({
+		title: "Alias",
+		description: "The authored key and the CSS value it resolves to: `{ alias: \"col\", value: \"column\" }`."
+	}).check(cssText(ctx, (value) => value.value)),
+	aliasDeclarations: (_ctx = {}) => z.strictObject({
+		alias: aliasName,
+		value: z.record(declarationKey, z.string())
+	}).meta({
+		title: "Declarations",
+		description: "A leaf that stands for a whole declaration bag: `truncate` sets `overflow`, `text-overflow` and `white-space`."
+	})
+};
+const KINDS = Object.keys(STYLE_PROP_VALUE_FORMS);
+/** The value half of a flag as leaves carry it. */
+function flagValue(value, members) {
+	if (typeof value === "string") return [{ value }];
+	if ("__ref" in value && typeof value.__ref === "string") return members(value).map(({ path }) => ({ value: path }));
+	return [{
+		value: "",
+		declarations: value
+	}];
+}
+/**
+* What each form's stored entry stands for as leaves. `members` expands a ref to what it names, one
+* entry for an item and one per member for a folder, since that walk is the config's. A flag's
+* `true` is the bare prop, an empty leaf so the class is its prefix; `false` is its absence and
+* authors nothing. A numeric alias is a leaf once it is a string: `6` names `.uds-grid-cols-6`.
+*/
+const STYLE_PROP_VALUE_LEAVES = {
+	keyword: (entry) => [{
+		leaf: entry,
+		value: entry
+	}],
+	number: (entry) => [{
+		leaf: String(entry),
+		value: String(entry)
+	}],
+	token: (entry, members) => members(entry).map(({ leaf, path }) => ({
+		leaf,
+		value: path
+	})),
+	tokenGroup: (entry, members) => members(entry).map(({ leaf, path }) => ({
+		leaf,
+		value: path
+	})),
+	flag: (entry, members) => entry.alias ? flagValue(entry.value, members).map((rest) => ({
+		leaf: "",
+		...rest
+	})) : [],
+	aliasToken: (entry, members) => members(entry.value).map(({ path }) => ({
+		leaf: String(entry.alias),
+		value: path
+	})),
+	aliasLiteral: (entry) => [{
+		leaf: String(entry.alias),
+		value: entry.value
+	}],
+	aliasDeclarations: (entry) => [{
+		leaf: String(entry.alias),
+		value: "",
+		declarations: entry.value
+	}]
+};
+/** The leaves one stored entry stands for; none for a value no form admits. */
+function leavesOfStylePropValue(entry, members) {
+	const kind = stylePropValueFormOf(entry);
+	if (kind === void 0) return [];
+	const leaves = STYLE_PROP_VALUE_LEAVES[kind];
+	return leaves(entry, members);
+}
+/** Every form built against `ctx`, in matching order. */
+function formsFor(ctx) {
+	return KINDS.map((kind) => STYLE_PROP_VALUE_FORMS[kind](ctx));
+}
+/** The `values` field's member schema against `ctx`: the union of every form. With no context it is
+*  the storage shape; with a config and the owner's properties it is also the judge. */
+function stylePropValueSchema(ctx = {}) {
+	return z.union(formsFor(ctx));
+}
+/** The form a stored entry is, or `undefined` for a value no form admits. With a config, a ref is
+*  `token` or `tokenGroup` as the config says; without one it reads as `token`. */
+function stylePropValueFormOf(entry, ctx = {}) {
+	return KINDS.find((kind) => STYLE_PROP_VALUE_FORMS[kind](ctx).safeParse(entry).success);
+}
+/** Which form a stored entry is, asked of the config that holds it. */
+function classifyStylePropValue({ config, entry }) {
+	const kind = stylePropValueFormOf(entry, { config });
+	if (kind === void 0) throw new Error(`A style property value fits no form: ${JSON.stringify(entry)}`);
+	return kind;
+}
+/**
+* A CSS property name in CSS spelling. A leading dash is a vendor or custom property, written as
+* authored. `custom`, so a stored artifact written before the check hydrates.
+*/
+const cssPropertyName = z.string().check((ctx) => {
+	const name = ctx.value;
+	if (name.startsWith("-")) return;
+	if (/[A-Z]/.test(name)) {
+		const css = name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+		ctx.issues.push({
+			code: "custom",
+			input: name,
+			message: `\`${name}\` is JSX spelling; a style property's \`properties\` are CSS names, written into the stylesheet as-is, so write \`"properties": ["${css}"]\` — and keep the camelCase name as the \`path\` (\`${name}\`), which is the prop a component exposes.`
+		});
+		return;
+	}
+	if (isCssProperty(name)) return;
+	ctx.issues.push({
+		code: "custom",
+		input: name,
+		message: `\`${name}\` is not a CSS property, so the declaration would paint nothing. \`properties\` are CSS property names in CSS spelling (\`background-color\`).`
+	});
+});
+/** A stored value's identity, with object keys in one order so two spellings of one alias compare equal. */
+function valueKey(entry) {
+	if (typeof entry !== "object" || entry === null) return JSON.stringify(entry);
+	const sorted = Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, typeof value === "object" && value !== null ? JSON.parse(valueKey(value)) : value]));
+	return JSON.stringify(sorted);
+}
+/** A value listed twice paints the same rule twice; the second is refused where it sits. */
+function eachValueOnce(ctx) {
+	const seen = /* @__PURE__ */ new Set();
+	ctx.value.forEach((entry, index) => {
+		const key = valueKey(entry);
+		if (!seen.has(key)) {
+			seen.add(key);
+			return;
+		}
+		ctx.issues.push({
+			code: "custom",
+			input: entry,
+			path: [index],
+			message: `\`values\` lists ${key} twice. Each value once.`
+		});
+	});
+}
+/** One comparable form for a CSS value, so `#FFFFFF` and `#ffffff ` read as the same value. */
+const comparable = (value) => typeof value === "string" || typeof value === "number" ? String(value).trim().toLowerCase() : void 0;
+/** Whether `values` reaches the token at `path` — through the token itself, an alias naming it, or
+*  a group above it. */
+function reaches(values, path) {
+	return values.some((entry) => {
+		const target = isRef(entry) ? entry : entry?.value;
+		if (!isRef(target) || kindOf(target) !== "token") return false;
+		const named = pathOf(target);
+		return named === path || path.startsWith(`${named}/`);
+	});
+}
+/** The token ref an entry carries, itself or as an alias's value. */
+function tokenRefOf(entry) {
+	if (isRef(entry)) return entry;
+	const value = entry?.value;
+	return isRef(value) ? value : void 0;
+}
+/**
+* A check refusing an entry that copies a token the prop doesn't reference.
+*
+* `{ alias: 'white', value: '#FFFFFF' }` on a prop that never names the `color` group is the token
+* `color/white` written out by hand: the class emits the literal, so a mode override or an edit to the
+* token never reaches it, and the system now says the same colour twice. The group ref is the form
+* that stays connected, and a model writing a system from scratch reaches for the copy unless the
+* schema says no. A prop that already reaches the token may alias it under another name — `sm` for
+* `spacing/2` — since that is one value with two spellings, not two values.
+*/
+const copiesNoToken = (config) => (ctx) => {
+	const tokens = /* @__PURE__ */ new Map();
+	for (const token of config.list("token")) {
+		const value = comparable(token.body.value);
+		if (value !== void 0 && !tokens.has(value)) tokens.set(value, token.path);
+	}
+	ctx.value.forEach((entry, index) => {
+		if (typeof entry !== "object" || entry === null || !("value" in entry)) return;
+		const value = comparable(entry.value);
+		const token = value === void 0 ? void 0 : tokens.get(value);
+		if (!token || reaches(ctx.value, token)) return;
+		const group = token.slice(0, token.lastIndexOf("/"));
+		ctx.issues.push({
+			code: "custom",
+			input: entry,
+			path: [index],
+			message: `copies \`${entry.value}\`, which is the token \`${token}\`, and this prop doesn't reference it. Reference the token — \`${spelled(token)}\` — or its whole group, \`${spelled(group)}\`, to offer every token in it; either follows the token and its mode overrides, where a restated value never does.`
+		});
+	});
+};
+/** A check refusing a ref to a token or group nothing declares: it offers no values, and the prop
+*  paints nothing. */
+const namesDeclaredTokens = (config) => (ctx) => {
+	ctx.value.forEach((entry, index) => {
+		const target = tokenRefOf(entry);
+		if (!target || kindOf(target) !== "token" || sourceOf(target) !== void 0 || pathOf(target) === "" || config.resolve("token", pathOf(target)) || config.members("token", pathOf(target)).length > 0) return;
+		const groups = config.groups("token").map((group) => `\`${group.path}\``).join(", ");
+		ctx.issues.push({
+			code: "custom",
+			input: entry,
+			path: [index],
+			message: `\`${target.__ref}\` names no token or token group this system has, so the prop would offer no values. Create its tokens first (\`token/create ${pathOf(target)}/<name>\`), or point at a group that exists${groups ? `: ${groups}` : ""}.`
+		});
+	});
+};
+/** The CSS properties a body writes, which its value forms judge their text against. */
+function cssPropertiesOf(body) {
+	const properties = body?.properties;
+	if (!Array.isArray(properties)) return [];
+	return properties.filter((name) => typeof name === "string" && !name.startsWith("-") && isCssProperty(name));
+}
+/** The `values` array for the write `ctx` describes: every form, and the checks that lane carries. */
+function valuesField({ config, body, linked }) {
+	if (!config) return z.array(stylePropValueSchema());
+	const declared = z.array(stylePropValueSchema({
+		config,
+		properties: linked ? void 0 : cssPropertiesOf(body)
+	})).check(eachValueOnce).check(namesDeclaredTokens(config));
+	return linked ? declared : declared.check(copiesNoToken(config));
+}
+/**
+* The fields, built for the write. With a config in hand a style property is held to painting: its
+* `properties` are CSS properties, and each value form judges itself against them, since a bare
+* string in `values` is written into the stylesheet as-is and `borderRadius: ['sm']` paints
+* `border-radius: sm`. Without one (`register`, hydration, tool derivation) this is the storage
+* shape, and stores what it is given. A variant with a vocabulary of its own swaps `properties` and
+* `values` (`NativeStyleProperty`).
+*
+* A body that arrived through a link is held to the forms alone. The CSS-text and token-copy checks
+* are guidance for a write made here, and the source already emits this body as it stands.
+*/
+const styleFields = ({ config, body, linked } = {}) => z.object({
+	properties: z.array(config ? cssPropertyName : z.string()).describe("The CSS properties this prop sets, all to the same value, in CSS spelling (`background-color`, never `backgroundColor`): the name is written into the stylesheet as-is."),
+	values: valuesField({
+		config,
+		body,
+		linked
+	}).optional().describe("What the prop accepts. A ref to a token GROUP (`{ \"__ref\": \"token:color\" }`) makes every member a value, named by its path under the group, and is how a prop takes tokens; a string or number is a keyword; `{ \"alias\": \"full\", \"value\": \"9999px\" }` names a literal; `{ \"alias\": \"brand\", \"value\": { \"__ref\": \"token:color/green\" } }` names one token under another name. One group ref usually replaces listing tokens one by one."),
+	responsive: z.boolean().default(false),
+	/**
+	* The class-name segment this prop contributes — `borderStyle` emits `.uds-border-style-solid`,
+	* and a prop whose values are already self-describing sets `''` so `position: absolute` emits
+	* `.uds-absolute` rather than `.uds-position-absolute`.
+	*
+	* Not derivable: whether a value needs its prop's name to be unambiguous is an authoring
+	* decision, and the same decision decides the class a consumer's markup already ships. Defaults
+	* to the prop's own path, which is the common case.
+	*/
+	classPrefix: z.string().optional(),
+	arbitrary: z.boolean().default(false),
+	/**
+	* The prop applies the NEGATION of its value — `offsetX="3"` paints `margin-inline: calc(var(…) *
+	* -1)`.
+	*
+	* It exists so one scale can be used in both directions. A system that wants to pull an element
+	* out of its container's padding needs the same steps it padded with, negated; without this it
+	* would need a parallel set of negative tokens that could drift from the positive ones, or every
+	* call site would write an off-scale literal and leave the scale behind. So the values stay
+	* positive and the PROP carries the direction.
+	*
+	* Not derivable from anything else, which is why it's a field: the negation is invisible in the
+	* values (a positive spacing token) and in the properties (`margin-inline` either way). A class
+	* name conventionally spells it (`-mx`), but a name is not a rule — reading the leading dash as
+	* one would make a rename silently change what a prop paints.
+	*/
+	negates: z.boolean().default(false),
+	/**
+	* The style prop whose alpha this one controls — `bgOpacity` is the opacity of `bg`.
+	*
+	* The pairing is modelled from the SIBLING's side, and the sibling is a real entity. The old model
+	* did neither: an opacity prop existed only as a field on its parent (`bg.opacityPair.as`), never
+	* registered, so a component exposing `bgOpacity` referenced something that wasn't there. Every
+	* config converted to v2 carries three of those dangling refs today.
+	*
+	* As an entity it resolves, the dep graph sees the relationship (so renaming `bg` cascades), and
+	* an emitter builds its parent→sibling map in the same one pass as before — just reading a ref
+	* instead of an implied name. Such a prop sets no CSS property of its own, hence an empty
+	* `properties`: it modulates its target rather than declaring anything.
+	*/
+	opacityOf: z.lazy(() => StyleProperty).optional()
+});
+/** `path` if no style property holds it, else the first free numbered variant of it. */
+function freePath(config, path) {
+	let candidate = path;
+	for (let n = 2; config.resolve("style-property", candidate); n += 1) candidate = `${path}${n}`;
+	return candidate;
+}
+/** StyleProperty (`flex/direction`) — a prop a component can expose, mapped to a CSS
+*  property with an allowed value set. Grouping (`flex`) is emergent from the path. */
+const StyleProperty = defineEntity({
+	kind: "style-property",
+	label: "Style property",
+	labelPlural: "Style properties",
+	fields: styleFields,
+	schemas: {
+		rename: { to: stylePropertyPath },
+		create: {
+			path: stylePropertyPath,
+			description: `Create a style property — the prop a component exposes for one CSS effect. \`path\` is the prop's JSX name, camelCase (\`borderRadius\`), never a CSS name; the CSS goes in \`properties\`. \`values\` is a ref to a token GROUP (\`${spelled("<group>")}\`), which offers every token in it and keeps the prop in step with modes and edits; \`{ "alias": "brand", "value": ${spelled("<group>/<name>")} }\` offers one token under a name of the prop's own; a literal (\`"row"\`, \`{ "alias": "full", "value": "9999px" }\`) is for a keyword the system has no token for. Restating a token's value as a literal instead of referencing it is refused.`,
+			example: ({ config }) => {
+				const existing = config.list("style-property").find((entry) => entry.borrowedFrom === void 0);
+				if (!existing) return void 0;
+				return {
+					path: freePath(config, existing.path),
+					data: existing.toJSON()
+				};
+			}
+		}
+	}
+});
+/** `flexDirection` → `flex-direction`. A name already spelled as CSS comes back unchanged. */
+function toCssPropertyName(property) {
+	return property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+/**
+* The CSS property names a style property governs, as the spec spells them.
+*
+* A web style property stores CSS names. A native one stores React Native style keys
+* (`flexDirection`), so a surface keyed on CSS names, the designer panel's controls or a Figma
+* paste's promotion, compares through this rather than against `properties` directly. A key only
+* React Native defines (`paddingHorizontal`) comes back hyphenated and matches no CSS-keyed control,
+* which is the right answer.
+*/
+function cssPropertyNames(styleProp) {
+	return styleProp.properties.map(toCssPropertyName);
+}
+//#endregion
+export { STYLE_PROP_VALUE_FORMS, STYLE_PROP_VALUE_LEAVES, StyleProperty, classifyStylePropValue, cssPropertyNames, leavesOfStylePropValue, stylePropValueFormOf, stylePropValueSchema, toCssPropertyName };

package/dist/entities/system/Token.d.ts

@@ -0,0 +1,67 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { DerivedColor, Gradient } from "./color.js";
+import { z } from "zod";
+
+//#region src/entities/system/Token.d.ts
+/** An override's `on`: a modifier ref, or a list of them that all hold at once. */
+type OverrideCondition = Ref | Ref[];
+/** The modifier paths an override's `on` names, in the order written. */
+declare function overrideModifiers(on: unknown): string[];
+/**
+ * An override's key, derived from its condition: the modifier's leaf, or for several modifiers
+ * their leaves sorted and joined with `&` (`dark&lg`), so one set of conditions has one key however
+ * the caller listed them. The leaf, because a modifier's leaf names it on its own (`uniqueLeaves`)
+ * and a key is what a bag's `_dark` and a force attribute spell too.
+ */
+declare function overrideKey(on: unknown): string;
+/** The modifier leaves an override key names — the inverse of {@link overrideKey}. Each resolves
+ *  through `config.resolve('modifier', leaf)`. */
+declare function overrideKeyModifiers(key: string): string[];
+/**
+ * The `on` an override key stands for: one modifier ref, or the list a compound key names. Spelled
+ * by leaf; the write canonicalizes each to the modifier's path ({@link declaredCondition}).
+ */
+declare function overrideCondition(key: string): OverrideCondition;
+/**
+ * One conditional value — what a token becomes when `on` holds. The value domain is the caller's,
+ * since a native token takes values a web token does not; everything else about an override is the
+ * same for both.
+ *
+ * Its key is DERIVED from `on`, so a token can't hold two overrides for one condition and the key
+ * can't drift from the refs it names (the framework recomputes it on every write, and on a
+ * cascading rename). A write may leave the key out; the framework computes it. A write is checked
+ * against the config's modifiers; a load is not, since the stored data is what it is.
+ */
+declare function defineOverride<TValue extends z.ZodTypeAny>(value: TValue): SubEntityClass<z.ZodObject<{
+  on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+  value: TValue;
+}, z.core.$strip>>;
+declare const tokenFields: z.ZodObject<{
+  value: z.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, z.core.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+  type: z.ZodOptional<z.ZodString>;
+  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, z.core.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** A token's stored body — what a `create` writes and what `Token.get` hands back typed. Exported
+ *  so a consumer building one names the entity's own shape instead of restating it. */
+type TokenBody = z.infer<typeof tokenFields>;
+declare const Token: EntityClass<z.ZodObject<{
+  value: z.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, z.core.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+  type: z.ZodOptional<z.ZodString>;
+  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, z.core.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+  cssPrefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, "token", {
+  readonly create: {
+    readonly description: `Create a token at \`<group>/<name>\` \u2014 \`data.value\` is the CSS value. The first path segment is its group, and a style property takes a whole group as one ref (\`${string}\`), so put the tokens one prop should offer in one group rather than listing values on the prop.`;
+  };
+}, Record<never, never>, false>;
+//#endregion
+export { OverrideCondition, Token, TokenBody, defineOverride, overrideCondition, overrideKey, overrideKeyModifiers, overrideModifiers };

package/dist/entities/system/Token.js

@@ -0,0 +1,129 @@
+import { isRef, pathOf, ref, sourceOf } from "../../framework/utils/refs.js";
+import { defineEntity } from "../../framework/defineEntity.js";
+import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { derivedColor, gradient } from "./color.js";
+import { Modifier } from "./Modifier.js";
+import { Font } from "./Font.js";
+import { z } from "zod";
+//#region src/entities/system/Token.ts
+/**
+* A demo entity — note what's here: ONLY its fields, as a plain `z.object`. No ctor, no
+* toJSON, no createSchema, no register method, no group class. `defineEntity` derives the
+* whole typed toolkit (`Token.item`/`Token.group`/`Token.ref`, validation, serialization,
+* grouping) from it.
+*/
+/** A token's value slot — a literal, a ref to ANOTHER token (a `token(...)` alias), or a ref to a
+*  `Font` — reused for the base value and every per-mode override. Both refs are typed to their
+*  kind rather than being a generic ref: a token value aliases a token or names a font family, and
+*  nothing else. `z.lazy` on `Token` because it's a SELF-reference — `Token` isn't defined until the
+*  `defineEntity` call below returns; the explicit annotation breaks the circular type inference
+*  (same pattern as any recursive zod schema).
+*
+*  A `font:` value is what makes "which fonts do I use, and where" an ordinary reverse-graph
+*  question: the family a `font-family` token resolves to is an EDGE, so renaming a font cascades
+*  and deleting one reports what breaks. Spelling it as the family's literal name instead would
+*  leave both to a string match. */
+const tokenValue = z.union([
+	z.string(),
+	z.number(),
+	z.lazy(() => Token),
+	Font,
+	derivedColor,
+	gradient
+], { error: "a token's `value` is one CSS value as a string (`#1DB954`, `4px`, `\"Circular\", sans-serif`), a number, a ref to another token or to a font (`{ \"__ref\": \"font:<name>\" }`), a derived color (`{ \"op\": \"darken\", \"color\": { \"__ref\": \"token:color/brand\" }, \"amount\": 10 }`) or a gradient. It is required; a font family is a string value or a `font` entity, never a field of its own." });
+/**
+* What an override applies under: one modifier, or several that all hold at once (`dark` and `lg`
+* together). Each is a ref, so the override is an ordinary edge: the dependency graph sees every
+* modifier it names, and renaming one cascades like anywhere else. Nothing here says what kind of
+* condition a modifier is, because the `Modifier` carries that in its `type` and its group.
+*/
+const overrideConditionSchema = z.union([Modifier, z.array(Modifier).min(1)], { error: "an override applies under a modifier: `\"on\": { \"__ref\": \"modifier:<name>\" }`, or a list of them that all hold at once." });
+/** The modifier paths an override's `on` names, in the order written. */
+function overrideModifiers(on) {
+	return (Array.isArray(on) ? on : [on]).filter(isRef).map(pathOf);
+}
+/**
+* An override's key, derived from its condition: the modifier's leaf, or for several modifiers
+* their leaves sorted and joined with `&` (`dark&lg`), so one set of conditions has one key however
+* the caller listed them. The leaf, because a modifier's leaf names it on its own (`uniqueLeaves`)
+* and a key is what a bag's `_dark` and a force attribute spell too.
+*/
+function overrideKey(on) {
+	return overrideModifiers(on).map(leafOf).sort((a, b) => a.localeCompare(b)).join("&");
+}
+/** The modifier leaves an override key names — the inverse of {@link overrideKey}. Each resolves
+*  through `config.resolve('modifier', leaf)`. */
+function overrideKeyModifiers(key) {
+	return key.split("&");
+}
+/**
+* The `on` an override key stands for: one modifier ref, or the list a compound key names. Spelled
+* by leaf; the write canonicalizes each to the modifier's path ({@link declaredCondition}).
+*/
+function overrideCondition(key) {
+	const refs = overrideKeyModifiers(key).map((leaf) => ({ __ref: `modifier:${leaf}` }));
+	return refs.length === 1 ? refs[0] : refs;
+}
+const leafOf = (path) => path.slice(path.lastIndexOf("/") + 1);
+/**
+* The condition, narrowed to modifiers `config` declares and spelled by their paths. A write naming
+* a modifier this config does not have would store a condition nothing can activate, and the emitter
+* would drop the override with nothing said. A ref written by leaf (`modifier:dark`) is stored as
+* the path (`modifier:colorMode/dark`), so the graph holds one spelling and a rename cascade finds it.
+* A ref through a link is the source's to answer for and is not judged here.
+*/
+function declaredCondition(config) {
+	const canonical = (ref) => {
+		if (sourceOf(ref) !== void 0) return ref;
+		const path = config.resolve("modifier", pathOf(ref))?.path;
+		return path === void 0 || path === pathOf(ref) ? ref : { __ref: `modifier:${path}` };
+	};
+	return overrideConditionSchema.superRefine((on, ctx) => {
+		const refs = Array.isArray(on) ? on : [on];
+		for (const ref of refs) {
+			if (sourceOf(ref) !== void 0) continue;
+			const path = pathOf(ref);
+			if (config.resolve("modifier", path)) continue;
+			ctx.addIssue({
+				code: "custom",
+				message: `names modifier "${path}", which this config does not declare`
+			});
+		}
+	}).transform((on) => Array.isArray(on) ? on.map(canonical) : canonical(on));
+}
+/**
+* One conditional value — what a token becomes when `on` holds. The value domain is the caller's,
+* since a native token takes values a web token does not; everything else about an override is the
+* same for both.
+*
+* Its key is DERIVED from `on`, so a token can't hold two overrides for one condition and the key
+* can't drift from the refs it names (the framework recomputes it on every write, and on a
+* cascading rename). A write may leave the key out; the framework computes it. A write is checked
+* against the config's modifiers; a load is not, since the stored data is what it is.
+*/
+function defineOverride(value) {
+	return defineSubEntity({
+		name: "override",
+		label: "Override",
+		fields: ({ config }) => z.object({
+			on: config ? declaredCondition(config) : overrideConditionSchema,
+			value
+		}),
+		key: (override) => overrideKey(override.on)
+	});
+}
+const Override = defineOverride(tokenValue);
+const Token = defineEntity({
+	kind: "token",
+	fields: z.object({
+		value: tokenValue,
+		type: z.string().optional(),
+		overrides: Override.optional()
+	}),
+	groupFields: z.object({ cssPrefix: z.string().optional() }),
+	localGroupFields: ["cssPrefix"],
+	subEntities: { overrides: Override },
+	schemas: { create: { description: `Create a token at \`<group>/<name>\` — \`data.value\` is the CSS value. The first path segment is its group, and a style property takes a whole group as one ref (\`${JSON.stringify(ref("token", "<group>"))}\`), so put the tokens one prop should offer in one group rather than listing values on the prop.` } }
+});
+//#endregion
+export { Token, defineOverride, overrideCondition, overrideKey, overrideKeyModifiers, overrideModifiers };