@yahoo/uds-create-config 4.16.0 → 4.18.0

package/dist/css/root-font-size.d.ts

@@ -0,0 +1,16 @@
+//#region src/css/root-font-size.d.ts
+/** A root font size that parses, and the pixels one `rem` is when the value fixes one. */
+interface RootFontSize {
+  /** As written. */
+  readonly css: string;
+  /** The pixels one `rem` is: a `px` value as is, a relative one (`%`, `em`, `rem`) against the
+   *  browser's 16px default. `undefined` for a value that fixes none — a fluid `clamp(…)`, a
+   *  viewport unit, a keyword. */
+  readonly px: number | undefined;
+}
+/**
+ * The value parsed, or `undefined` when it is not a `font-size` a stylesheet can carry.
+ */
+declare function parseRootFontSize(value: string): RootFontSize | undefined;
+//#endregion
+export { RootFontSize, parseRootFontSize };

package/dist/css/root-font-size.js

@@ -0,0 +1,97 @@
+import { isLengthUnit } from "./value-type.js";
+import parse from "css-tree/parser";
+/** The `font-size` keywords, which fix no pixel value a build can name. */
+const KEYWORDS = new Set([
+	"xx-small",
+	"x-small",
+	"small",
+	"medium",
+	"large",
+	"x-large",
+	"xx-large",
+	"xxx-large",
+	"smaller",
+	"larger",
+	"inherit",
+	"initial",
+	"unset"
+]);
+/** The functions a `font-size` may be, each of which fixes no pixel value a build can name. */
+const FUNCTIONS = new Set([
+	"calc",
+	"clamp",
+	"min",
+	"max",
+	"var",
+	"env"
+]);
+/**
+* The value parsed, or `undefined` when it is not a `font-size` a stylesheet can carry.
+*/
+function parseRootFontSize(value) {
+	const css = value.trim();
+	if (css === "") return void 0;
+	if (!balanced(css)) return void 0;
+	let malformed = false;
+	let parsed;
+	try {
+		parsed = parse(css, {
+			context: "value",
+			onParseError: () => {
+				malformed = true;
+			}
+		});
+	} catch {
+		return;
+	}
+	if (malformed || parsed.type !== "Value") return void 0;
+	const [node, ...rest] = parsed.children.toArray();
+	if (!node || rest.length > 0) return void 0;
+	switch (node.type) {
+		case "Dimension": {
+			if (!isLengthUnit(node.unit.toLowerCase())) return void 0;
+			const amount = Number(node.value);
+			const unit = node.unit.toLowerCase();
+			if (unit === "px") return {
+				css,
+				px: amount
+			};
+			if (unit === "em" || unit === "rem") return {
+				css,
+				px: amount * 16
+			};
+			return {
+				css,
+				px: void 0
+			};
+		}
+		case "Percentage": return {
+			css,
+			px: Number(node.value) / 100 * 16
+		};
+		case "Number": return Number(node.value) === 0 ? {
+			css,
+			px: 0
+		} : void 0;
+		case "Identifier": return KEYWORDS.has(node.name.toLowerCase()) ? {
+			css,
+			px: void 0
+		} : void 0;
+		case "Function": return FUNCTIONS.has(node.name.toLowerCase()) ? {
+			css,
+			px: void 0
+		} : void 0;
+		default: return;
+	}
+}
+function balanced(css) {
+	let depth = 0;
+	for (const char of css) {
+		if (char === "(") depth += 1;
+		if (char === ")") depth -= 1;
+		if (depth < 0) return false;
+	}
+	return depth === 0;
+}
+//#endregion
+export { parseRootFontSize };

package/dist/css/value-type.js

@@ -29,6 +29,10 @@ const EASING_FUNCTIONS = [
 	"linear("
 ];
 /** Absolute and relative length units, longest-first so `rem` wins over `em`. */
+/** Whether `unit` is a CSS length unit, `rem` and `vw` alike. */
+function isLengthUnit(unit) {
+	return LENGTH_UNITS.includes(unit);
+}
 const LENGTH_UNITS = [
 	"ch",
 	"cm",
@@ -128,4 +132,4 @@ function resolveValueType({ type, value }) {
 	return sniffValueType(value);
 }
 //#endregion
-export { resolveValueType, sniffValueType };
+export { isLengthUnit, resolveValueType, sniffValueType };

package/dist/entities/native/NativeModifier.d.ts

@@ -14,8 +14,8 @@ declare const NativeModifier: EntityClass<z.ZodObject<{
   value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodOptional<z.ZodEnum<{
-    state: "state";
     mode: "mode";
+    state: "state";
   }>>;
   default: z.ZodOptional<z.ZodObject<{
     __ref: z.ZodString;

package/dist/entities/native/NativeSettings.d.ts

@@ -29,6 +29,7 @@ declare const NativeSettings: EntityClass<z.ZodObject<Omit<{
     }, z.core.$strict>]>>;
     scope: z.ZodOptional<z.ZodString>;
     preflight: z.ZodOptional<z.ZodBoolean>;
+    rem: z.ZodOptional<z.ZodString>;
     safelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
   }, z.core.$strict>>;
   playground: z.ZodOptional<z.ZodObject<{

package/dist/entities/native/NativeToken.d.ts

@@ -2,18 +2,19 @@ import { Ref } from "../../framework/utils/ref-grammar.js";
 import { Ref as Ref$1 } from "../../framework/utils/refs.js";
 import { SubEntityClass } from "../../framework/defineSubEntity.js";
 import { EntityClass } from "../../framework/defineEntity.js";
-import { DerivedColor, Gradient } from "../system/color.js";
+import { ComposedValue } from "../system/composed-values.js";
+import { DerivedColor } from "../system/color.js";
 import { OverrideCondition } from "../system/Token.js";
 import { z } from "zod";
 
 //#region src/entities/native/NativeToken.d.ts
 declare const nativeTokenValue: z.ZodType<number | boolean | string | Ref$1 | DerivedColor>;
 declare const NativeToken: EntityClass<z.ZodObject<Omit<{
-  value: z.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, z.core.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+  value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   }, z.core.$strip>>>;
 }, "value" | "overrides"> & {
   value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;

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

@@ -10,7 +10,9 @@ import { StoredPreviewCondition } from "../../framework/preview-store.js";
 import { listSlots, namedSlots, slotHostedBy, slotOf } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
+import { ComposedValue } from "./composed-values.js";
 import { StyleValue } from "./style-bag.js";
+import { OverrideCondition, TokenRefPath, TokenReference } from "./Token.js";
 import { AsInput, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StyleRuleInput } from "./defineComponent.js";
 import { z } from "zod";
 
@@ -718,6 +720,22 @@ declare const componentFields: z.ZodObject<{
     __ref: z.ZodString;
   }, z.core.$strip>>;
   export: z.ZodOptional<z.ZodString>;
+  tokenRefs: z.ZodOptional<z.ZodArray<Omit<EntityClass<z.ZodObject<{
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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 | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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, Record<never, never>, Record<never, never>>, "ref"> & {
+    readonly ref: <const Path extends TokenRefPath>(path: Path) => TokenReference<Path>;
+  }>>;
 }, z.core.$strict>;
 /**
  * A component's stored body — every field, typed off the schema above.
@@ -906,6 +924,22 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
     __ref: z.ZodString;
   }, z.core.$strip>>;
   export: z.ZodOptional<z.ZodString>;
+  tokenRefs: z.ZodOptional<z.ZodArray<Omit<EntityClass<z.ZodObject<{
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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 | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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, Record<never, never>, Record<never, never>>, "ref"> & {
+    readonly ref: <const Path extends TokenRefPath>(path: Path) => TokenReference<Path>;
+  }>>;
 }, z.core.$strict>, z.ZodObject<{
   icon: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, "component", {
@@ -1078,6 +1112,22 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
         __ref: z.ZodString;
       }, z.core.$strip>>;
       export: z.ZodOptional<z.ZodString>;
+      tokenRefs: z.ZodOptional<z.ZodArray<Omit<EntityClass<z.ZodObject<{
+        value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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 | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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, Record<never, never>, Record<never, never>>, "ref"> & {
+        readonly ref: <const Path extends TokenRefPath>(path: Path) => TokenReference<Path>;
+      }>>;
     }, z.core.$strict>;
     readonly description: "Create a component at a new qualified `path`. For a component with nothing in it yet, one to design on the canvas before it has props or variants, use `create-blank` with only a `path` instead of authoring a minimal body here. When its complete body is known, include all layers, anatomy, props, defaults, and styles in this one operation. `data.layers` maps each stable layer name to the element it renders and must include `root` — a tag for a primitive (`{ \"layers\": { \"root\": \"div\" } }`), and for anything built on top, a ref to a primitive (`{ \"root\": { \"__ref\": \"component:Box\" }, \"label\": { \"__ref\": \"component:Text\" } }`), which is what lets the layer take that primitive's style props. A primitive exposes style props as `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:bg\" } }` and declares `children: { \"type\": \"slot\", \"text\": true }` when it holds content — without the slot, nothing nested inside it renders. A composed component exposes a layer's props at its own top level through `forwards`, keyed by layer: `{ \"forwards\": { \"root\": \"*\" } }` passes every prop the root's element takes (so `<Button width=\"full\">` reaches the root's `width`), and a list of member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`, each naming the component that declares the prop) passes only those. A prop a layer already exposes is forwarded, never redeclared in `props`; a `props` entry of `{ \"type\": \"forward\" }` is the reverse route, one of this component's props into a layer's. `anatomy` is the tree the build would read off a render: each node renders a layer (`{ \"__ref\": \"layer:<name>\" }`), an intrinsic tag, or `Slot` (`{ \"element\": \"Slot\", \"props\": { \"name\": \"children\" } }`, where a slot prop's content lands — but a declared slot fills `root` by default, so a primitive still declares its `children` slot prop yet needs no `Slot` node or `children` entry for it, and a `Slot` node is only for landing that content in a nested layer); `children` lists sibling node keys from the `root` node, never a prop name; `text` is a fixed string; `visible` is a condition on a prop (`{ \"$state\": \"<prop>\" }`, or with `eq`); content shown in a nested layer is a route, `children: { \"type\": \"forward\", \"target\": \"label/children\" }`. `$state` appears only in `visible` and in an `element` a prop chooses, never as a prop value. A glyph is a node of its own, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it, never a prop value. Text a prop supplies to a text layer is never a node either: declare the prop `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }` and the layer shows it; a `Slot` node goes only under a layer that takes nodes. A style rule is `\"styles\": { \"*\": { \"when\": null, \"layers\": { \"root\": { \"bg\": \"surface\" } } } }`, keyed by a name, with each layer's bag under `layers`. A composed component carries its own styles: give it an unconditional (`\"*\"`) rule that lays out and surfaces it through the system's style properties — spacing, alignment and gap on the container, a background and color where it has one — rather than leaning on the bare primitives, which paint flat. Style a layer only with the style props the primitive it renders exposes, set to the values those props accept: `component/get` on the primitive lists both, so read it and choose from that rather than reaching for a CSS name or value the system has no style property for. Set `preview` (`{ \"*\": { \"when\": null, \"props\": { \"children\": \"Example\" } } }`) or `defaultProps` so the component previews with content; a root that takes children renders empty otherwise. A style rule's layer bag is keyed by style-prop name (`fontWeight`, `color`), never by CSS property name, and each value is one of that prop's values.";
     readonly example: ({

package/dist/entities/system/Component.js

@@ -19,6 +19,7 @@ import { instanceAt } from "../../spec/instance.js";
 import { Package } from "./Package.js";
 import { File } from "./File.js";
 import { iconDomainInvariants } from "./icon-domain-invariants.js";
+import { Token } from "./Token.js";
 import { intoName, routedPropIn, routesContent } from "../../framework/prop-surface.js";
 import { z } from "zod";
 //#region src/entities/system/Component.ts
@@ -1444,7 +1445,13 @@ const componentFields = z.strictObject({
 	* two components, and a borrower registers the publisher's `Card` under its own name. Nothing
 	* recovers that binding from a path.
 	*/
-	export: z.string().optional()
+	export: z.string().optional(),
+	/**
+	* The tokens the render reads as values — `Token.ref('spacing/2.5').px()` — baked from the source
+	* like `file`. Each is an edge: a rename reaches the read, a delete names the component, and a
+	* link's closure carries the token. A read whose path a prop completes names the group.
+	*/
+	tokenRefs: z.array(Token).optional()
 }).check((ctx) => {
 	const body = ctx.value;
 	if (isPlainObject(body.props)) for (const [name, decl] of Object.entries(body.props)) {

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

@@ -27,8 +27,8 @@ type WebActivation = (typeof WEB_ACTIVATIONS)[number];
  */
 declare const modifierGroupFields: z.ZodObject<{
   type: z.ZodOptional<z.ZodEnum<{
-    state: "state";
     mode: "mode";
+    state: "state";
   }>>;
   default: z.ZodOptional<z.ZodObject<{
     __ref: z.ZodString;
@@ -49,8 +49,8 @@ declare const Modifier: EntityClass<z.ZodObject<{
   }, z.core.$strip>, z.ZodObject<Record<never, never>, z.core.$strip>, "composite", Record<never, never>, Record<never, never>, false, Record<never, never>, Record<never, never>>>]>;
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodOptional<z.ZodEnum<{
-    state: "state";
     mode: "mode";
+    state: "state";
   }>>;
   default: z.ZodOptional<z.ZodObject<{
     __ref: z.ZodString;

package/dist/entities/system/Modifier.js

@@ -1,4 +1,4 @@
-import { isRef, kindOf } from "../../framework/utils/refs.js";
+import { isRef, refTo } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { Composite } from "./Composite.js";
 import { z } from "zod";
@@ -14,10 +14,7 @@ const WEB_ACTIVATIONS = [
 	"composite"
 ];
 /** A ref to a modifier, spelled out because the kind's own class is what this is a field of. */
-const modifierRef = z.object({ __ref: z.string().refine((raw) => kindOf(raw) === "modifier") }).meta({
-	ref: true,
-	refKind: "modifier"
-});
+const modifierRef = refTo("modifier");
 /**
 * A modifier group's own fields.
 *

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

@@ -29,6 +29,7 @@ type CssPrefix = z.output<typeof prefix>;
 declare const CSS_DEFAULTS: {
   readonly prefix: "uds";
   readonly preflight: true;
+  readonly rem: "16px";
 };
 /** The `css` section — how a web system names what it emits and where its stylesheet applies. A
  *  native system declares no such section, so a native config setting one is refused. */
@@ -39,6 +40,7 @@ declare const CssSection: SubEntityClass<z.ZodObject<{
   }, z.core.$strict>]>>;
   scope: z.ZodOptional<z.ZodString>;
   preflight: z.ZodOptional<z.ZodBoolean>;
+  rem: z.ZodOptional<z.ZodString>;
   safelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>>;
 /** The two namespaces a prefix names, whichever form it was written in, defaulted when unset. */
@@ -83,6 +85,7 @@ declare const Settings: EntityClass<z.ZodObject<{
     }, z.core.$strict>]>>;
     scope: z.ZodOptional<z.ZodString>;
     preflight: z.ZodOptional<z.ZodBoolean>;
+    rem: z.ZodOptional<z.ZodString>;
     safelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
   }, z.core.$strict>>;
   playground: z.ZodOptional<z.ZodObject<{

package/dist/entities/system/Settings.js

@@ -1,4 +1,5 @@
 import { buildFields } from "../../configs/build-options.js";
+import { parseRootFontSize } from "../../css/root-font-size.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
 import { z } from "zod";
@@ -61,7 +62,8 @@ const prefix = z.union([z.string(), z.strictObject({
 /** The `css` section as a config that set nothing reads it, spelled once. */
 const CSS_DEFAULTS = {
 	prefix: "uds",
-	preflight: true
+	preflight: true,
+	rem: "16px"
 };
 const cssFields = z.strictObject({
 	prefix: prefix.meta({
@@ -81,6 +83,15 @@ const cssFields = z.strictObject({
 		description: "Start the stylesheet with the element resets, so buttons, inputs and headings begin from the same baseline in every browser. Off, the page keeps its own base styles. Unset, on.",
 		default: CSS_DEFAULTS.preflight
 	}).optional(),
+	/** The root font size of the page this sheet is for, as CSS — what one `rem` is. Stated, the app's
+	*  sheet sets it and a token's `px()` reads a `rem` value against it; a fixed size (`16px`, `62.5%`,
+	*  `1em`) folds to pixels against the browser's 16px default, a fluid one (`clamp(…)`) leaves a
+	*  rem with no pixel reading. A sheet confined to a `scope` cannot set it, and states it only. */
+	rem: z.string().refine((value) => parseRootFontSize(value) !== void 0, { error: "a root font size is one CSS `font-size` value: a length (`16px`, `1em`), a percentage (`62.5%`), a math or `var()` function (`clamp(14px, 1vw + 12px, 18px)`), or a font-size keyword." }).meta({
+		title: "Rem",
+		description: `The root font size of the page this stylesheet is for, as CSS: \`16px\`, \`62.5%\`, \`1em\`, or a fluid \`clamp(…)\`. Stated, the stylesheet sets \`html { font-size }\` to it unless it is confined to a \`scope\`, and a token's \`px()\` reads a rem value against it — a fixed size folds against the browser's 16px default, a fluid one leaves rem values with no pixel reading. Unset, ${CSS_DEFAULTS.rem} is assumed and the page's root is left alone.`,
+		default: CSS_DEFAULTS.rem
+	}).optional(),
 	/** Classes the stylesheet keeps whether or not a scanned file names them — for a class built at
 	*  runtime, or one used by a file the build does not scan. */
 	safelist: z.array(z.string().min(1)).meta({

package/dist/entities/system/StyleProperty.js

@@ -2,6 +2,7 @@ import { isRef, kindOf, pathOf, ref, refSchema, sourceOf, splitRef } from "../..
 import { defineEntity } from "../../framework/defineEntity.js";
 import { cssValueIssue, isCssProperty } from "../../css/values.js";
 import { camelCase } from "./style-bag.js";
+import { isIdentifier } from "../../framework/utils/identifier.js";
 import { z } from "zod";
 //#region src/entities/system/StyleProperty.ts
 /**
@@ -9,15 +10,13 @@ import { z } from "zod";
 * 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));
+	const bad = ctx.value.split("/").find((segment) => !isIdentifier(segment));
 	if (bad === void 0) return;
 	ctx.issues.push({
 		code: "custom",

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

@@ -1,8 +1,10 @@
 import { Ref } from "../../framework/utils/ref-grammar.js";
 import { Ref as Ref$1 } from "../../framework/utils/refs.js";
 import { SubEntityClass } from "../../framework/defineSubEntity.js";
-import { EntityClass } from "../../framework/defineEntity.js";
-import { DerivedColor, Gradient } from "./color.js";
+import { PathOf } from "../../framework/registered.js";
+import { EntityClass, KindRef } from "../../framework/defineEntity.js";
+import { ComposedValue } from "./composed-values.js";
+import { TokenReaders } from "./token-values.js";
 import { z } from "zod";
 
 //#region src/entities/system/Token.d.ts
@@ -40,22 +42,22 @@ declare function defineOverride<TValue extends z.ZodTypeAny>(value: TValue): Sub
   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>>;
+  value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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>>;
+declare const TokenEntity: EntityClass<z.ZodObject<{
+  value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, 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>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   }, z.core.$strip>>>;
 }, z.core.$strip>, z.ZodObject<{
   cssPrefix: z.ZodOptional<z.ZodString>;
@@ -64,5 +66,16 @@ declare const Token: EntityClass<z.ZodObject<{
     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, Record<never, never>, Record<never, never>>;
+/** A token ref as an authoring file holds it: the marker, `extend`, and the value readers. */
+type TokenReference<Path extends string> = KindRef<typeof tokenFields, 'token', Path> & TokenReaders<Path>;
+/**
+ * What `Token.ref` takes in an authoring file: a registered path, or a path a prop completes under a
+ * registered group — `` `spacing/${gutter}` `` — whose readers stay open since no one token is named.
+ */
+type TokenRefPath = PathOf<'token'> | `${PathOf<'token'>}/${string}`;
+declare function tokenRef<const Path extends TokenRefPath>(path: Path): TokenReference<Path>;
+declare const Token: Omit<typeof TokenEntity, "ref"> & {
+  readonly ref: typeof tokenRef;
+};
 //#endregion
-export { OverrideCondition, Token, TokenBody, defineOverride, overrideCondition, overrideKey, overrideKeyModifiers, overrideModifiers };
+export { OverrideCondition, Token, TokenBody, TokenRefPath, TokenReference, defineOverride, overrideCondition, overrideKey, overrideKeyModifiers, overrideModifiers };

package/dist/entities/system/Token.js

@@ -1,9 +1,10 @@
 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 { composedValueSchemas } from "./composed-values.js";
 import { Font } from "./Font.js";
 import { Modifier } from "./Modifier.js";
+import { TOKEN_READERS } from "./token-values.js";
 import { z } from "zod";
 //#region src/entities/system/Token.ts
 /**
@@ -28,9 +29,8 @@ const tokenValue = z.union([
 	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." });
+	...composedValueSchemas
+], { 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 }`), a gradient, or a transition (`{ \"transition\": [{ \"properties\": [\"background-color\"], \"timing\": { \"__ref\": \"token:motion/color\" } }] }`). 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
@@ -113,7 +113,7 @@ function defineOverride(value) {
 	});
 }
 const Override = defineOverride(tokenValue);
-const Token = defineEntity({
+const TokenEntity = defineEntity({
 	kind: "token",
 	fields: z.object({
 		value: tokenValue,
@@ -125,5 +125,24 @@ const Token = defineEntity({
 	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.` } }
 });
+/**
+* Token refs add the value readers a render calls — `Token.ref('spacing/2.5').px()`. Phantoms, like a
+* component ref's `render`: the build resolves each read in place and the authoring file's own call is
+* never made, so calling one anyway names what happened. Non-enumerable, so the marker a config
+* evaluates to is the same small wire form a hydrated config receives.
+*/
+const baseTokenRef = TokenEntity.ref.bind(TokenEntity);
+function tokenRef(path) {
+	const value = baseTokenRef(path);
+	for (const reader of TOKEN_READERS) Object.defineProperty(value, reader, {
+		enumerable: false,
+		configurable: false,
+		value: () => {
+			throw new Error(`[uds] Token.ref(${JSON.stringify(path)}).${reader}() was called from an authoring file. The build resolves a token read in place, and a render only ever runs from the module it emits.`);
+		}
+	});
+	return value;
+}
+const Token = Object.assign(TokenEntity, { ref: tokenRef });
 //#endregion
 export { Token, defineOverride, overrideCondition, overrideKey, overrideKeyModifiers, overrideModifiers };

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

@@ -43,6 +43,9 @@ declare function isGradient(value: unknown): value is Gradient;
 declare function linearGradient(spec: Omit<Gradient, 'gradient'>): Gradient;
 /** Whether a value is a derived colour — the test the renderers branch on. */
 declare function isDerivedColor(value: unknown): value is DerivedColor;
+/** The interpolation space each op is authored in: `oklch` for shading (perceptually even), `srgb`
+ *  for alpha. */
+declare const DERIVED_COLOR_SPACE: Record<DerivedColor['op'], string>;
 /** Blend toward black in light mode and white in dark — so a hover state darkens in both. */
 declare function darken(color: ColorValue, amount: number): DerivedColor;
 /** Mirror of {@link darken}: toward white in light mode, black in dark. */
@@ -61,4 +64,4 @@ declare function renderDerivedColor(value: DerivedColor, render: (color: ColorVa
 /** A gradient as CSS — `linear-gradient(to right, transparent 0%, var(--uds-bg-primary) 50%)`. */
 declare function renderGradient(value: Gradient, render: (color: ColorValue) => string): string;
 //#endregion
-export { ColorValue, DerivedColor, Gradient, alpha, darken, isDerivedColor, isGradient, lighten, linearGradient, mix, renderDerivedColor, renderGradient };
+export { ColorValue, DERIVED_COLOR_SPACE, DerivedColor, Gradient, alpha, darken, isDerivedColor, isGradient, lighten, linearGradient, mix, renderDerivedColor, renderGradient };

package/dist/entities/system/color.js

@@ -63,13 +63,21 @@ const derivedColor = z.lazy(() => z.strictObject({
 function isDerivedColor(value) {
 	return typeof value === "object" && value !== null && typeof value.op === "string" && "color" in value;
 }
+/** The interpolation space each op is authored in: `oklch` for shading (perceptually even), `srgb`
+*  for alpha. */
+const DERIVED_COLOR_SPACE = {
+	darken: "oklch",
+	lighten: "oklch",
+	alpha: "srgb",
+	mix: "oklch"
+};
 /** Blend toward black in light mode and white in dark — so a hover state darkens in both. */
 function darken(color, amount) {
 	return {
 		op: "darken",
 		color,
 		amount,
-		space: "oklch"
+		space: DERIVED_COLOR_SPACE.darken
 	};
 }
 /** Mirror of {@link darken}: toward white in light mode, black in dark. */
@@ -78,7 +86,7 @@ function lighten(color, amount) {
 		op: "lighten",
 		color,
 		amount,
-		space: "oklch"
+		space: DERIVED_COLOR_SPACE.lighten
 	};
 }
 /** `alpha(color, 0.2)` — the colour at 20% opacity. Takes a 0–1 opacity, like CSS. */
@@ -87,11 +95,11 @@ function alpha(color, opacity) {
 		op: "alpha",
 		color,
 		amount: Math.round(Math.max(0, Math.min(1, opacity)) * 100),
-		space: "srgb"
+		space: DERIVED_COLOR_SPACE.alpha
 	};
 }
 /** `mix(a, b, 30)` — 30% of the way from `a` to `b`. */
-function mix(color, towards, amount, space = "oklch") {
+function mix(color, towards, amount, space = DERIVED_COLOR_SPACE.mix) {
 	return {
 		op: "mix",
 		color,
@@ -101,6 +109,52 @@ function mix(color, towards, amount, space = "oklch") {
 	};
 }
 /**
+* The helper call that authors a stored derived colour, or `undefined` for one no helper produces (a
+* `darken` in another space, an `alpha` at a fractional percent). `alpha` stores a 0–100 percent and
+* takes a 0–1 opacity, so the argument is the percent scaled back. A `darken`, `lighten` or `mix`
+* with no `space` renders in `oklch`, so it is the helper's own value; an `alpha` with none renders
+* in `oklch` too, which is not what `alpha()` writes, so it stays an object.
+*/
+function derivedColorAuthoring(value) {
+	if (value.op === "darken" || value.op === "lighten") {
+		if ((value.space ?? DERIVED_COLOR_SPACE[value.op]) !== DERIVED_COLOR_SPACE[value.op] || value.with !== void 0) return;
+		return {
+			helper: value.op,
+			args: [value.color, value.amount]
+		};
+	}
+	if (value.op === "alpha") {
+		const whole = Number.isInteger(value.amount);
+		const inRange = value.amount >= 0 && value.amount <= 100;
+		if (value.space !== DERIVED_COLOR_SPACE.alpha || value.with !== void 0 || !whole || !inRange) return;
+		return {
+			helper: "alpha",
+			args: [value.color, value.amount / 100]
+		};
+	}
+	if (value.with === void 0) return void 0;
+	const args = [
+		value.color,
+		value.with,
+		value.amount
+	];
+	if (value.space !== void 0 && value.space !== DERIVED_COLOR_SPACE.mix) args.push(value.space);
+	return {
+		helper: "mix",
+		args
+	};
+}
+/** The `linearGradient({...})` call that authors a stored gradient; a radial or conic one has no
+*  helper and prints as the object it is. */
+function gradientAuthoring(value) {
+	if (value.gradient !== "linear") return void 0;
+	const { gradient: _kind, ...spec } = value;
+	return {
+		helper: "linearGradient",
+		args: [spec]
+	};
+}
+/**
 * A derived colour as CSS.
 *
 * `render` resolves the nested colours — passed in rather than imported, because resolving a token
@@ -120,4 +174,4 @@ function renderGradient(value, render) {
 	return `${value.repeating ? "repeating-" : ""}${value.gradient}-gradient(${[...head, stops].join(", ")})`;
 }
 //#endregion
-export { alpha, darken, derivedColor, gradient, isDerivedColor, isGradient, lighten, linearGradient, mix, renderDerivedColor, renderGradient };
+export { DERIVED_COLOR_SPACE, alpha, darken, derivedColor, derivedColorAuthoring, gradient, gradientAuthoring, isDerivedColor, isGradient, lighten, linearGradient, mix, renderDerivedColor, renderGradient };