@yahoo/uds-create-config 4.17.0 → 4.18.0

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/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/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 { 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
@@ -50,7 +52,7 @@ declare const tokenFields: z.ZodObject<{
 /** 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<{
+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<{
@@ -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

@@ -4,6 +4,7 @@ import { defineSubEntity } from "../../framework/defineSubEntity.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
 /**
@@ -112,7 +113,7 @@ function defineOverride(value) {
 	});
 }
 const Override = defineOverride(tokenValue);
-const Token = defineEntity({
+const TokenEntity = defineEntity({
 	kind: "token",
 	fields: z.object({
 		value: tokenValue,
@@ -124,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/token-index.js

@@ -1,6 +1,6 @@
 import { isRef, splitRef } from "../../framework/utils/refs.js";
-import { resolveTokenValueUnder } from "../../framework/projections.js";
 import { resolveValueType } from "../../css/value-type.js";
+import { resolveTokenValueUnder } from "../../framework/projections.js";
 import { matchEntities, searchEntities } from "../../framework/entity-search.js";
 //#region src/entities/system/token-index.ts
 /**

package/dist/entities/system/token-values.d.ts

@@ -0,0 +1,138 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { Config } from "../../framework/Config.js";
+import { RootFontSize } from "../../css/root-font-size.js";
+
+//#region src/entities/system/token-values.d.ts
+/**
+ * A resolved value and the numbers a JS caller reads off it. `px` is present for a length in `px`,
+ * for a unitless number, and for a length in `rem` when the page's root font size fixes one; `ms` for
+ * a time in `s` or `ms`. Anything else — a color, a font stack, a percentage — is its CSS string only.
+ */
+interface TokenValueEntry {
+  readonly css: string;
+  readonly px?: number;
+  readonly ms?: number;
+}
+/** What a token resolved to, or why it did not. */
+type TokenValueState = /** One value, the same under every mode and state. */{
+  readonly kind: 'value';
+  readonly value: TokenValueEntry;
+}
+/** A modifier decides it — an override on the token or on one it aliases — so it is only ever a
+ *  `var()` on the page. */
+| {
+  readonly kind: 'conditional';
+}
+/** Nothing to resolve to: an alias chain that never ends, a linked source this config did not
+ *  reach, or a value that is not one scalar. */
+| {
+  readonly kind: 'unresolved';
+};
+/** One token as the runtime module carries it. */
+interface TokenValueRow {
+  readonly path: string;
+  /** The first path segment, which is the group a reader is addressed by. */
+  readonly group: string;
+  /** The rest of the path — `2.5` for `spacing/2.5`, `blue/3` for `spectrum/blue/3`. A path with no
+   *  slash is its own group and alias. */
+  readonly alias: string;
+  /** The custom property the stylesheet declares it as, spelled by the config that owns it. */
+  readonly variable: string;
+  readonly state: TokenValueState;
+}
+/** The root font size of the page this config's sheet is for, as stated or the browser's own. A
+ *  stored value already passed the setting's own check, so it parses. */
+declare function rootFontSize(config: Config): RootFontSize;
+/**
+ * Every token this config lists, in list order, as {@link TokenValueRow}s.
+ *
+ * Keyed on the token and settings slices, plus the attached sources every memo keys on: a token edit
+ * or a `rem` change recomputes, a component edit does not. A source's values reach here through the
+ * closure the artifact recorded whether or not the source is attached, so the two answer the same.
+ */
+declare const tokenValueRows: (config: Config) => readonly TokenValueRow[];
+/**
+ * One token's row by ref or path, qualified or not. A qualified target is read in the source it
+ * names, so the row spells that source's variable and value; an unqualified one is this config's,
+ * including a row this config derived from a link.
+ */
+declare function tokenValueRow({
+  config,
+  target
+}: {
+  config: Config;
+  target: string | Ref;
+}): TokenValueRow | undefined;
+/**
+ * Whether a `token:` target names something this config can answer for — an item, qualified or not,
+ * or a group. A group is what a read whose path a prop completes is an edge to.
+ */
+declare function tokenExists({
+  config,
+  target
+}: {
+  config: Config;
+  target: string | Ref;
+}): boolean;
+/**
+ * Token path → what the build resolved it to, the augmentation the emitted `uds-env.d.ts` fills:
+ *
+ * ```ts
+ * declare module '@yahoo/uds-create-config' {
+ *   interface RegisteredTokenValues {
+ *     'spacing/1': { css: '0.25rem'; px: 4 };
+ *     'motion/fast': { css: '200ms'; ms: 200 };
+ *     'color/brand': {};
+ *   }
+ * }
+ * ```
+ *
+ * Every token is a key, so `var()` types against all of them; `css`, `px` and `ms` are present only
+ * where the token resolves to one value, which is what makes `px('brand')` on a colour an error.
+ */
+interface RegisteredTokenValues {}
+/**
+ * One token group's readers. `var` is available for every token; the others only for the tokens the
+ * build resolved to one value, so a mode-dependent token is a type error everywhere but `var`.
+ */
+interface TokenGroupReader<All extends string = string, Static extends string = string, Px extends string = string, Ms extends string = string> {
+  /** `var(--uds-spacing-2_5)` — the reference the stylesheet's own rules use, so it follows modes. */
+  var(alias: All): string;
+  /** The resolved CSS value, `'0.625rem'`. */
+  value(alias: Static): string;
+  /** The value as CSS pixels: `rem` against the page's root font size (`settings.css.rem`), `px`
+   *  as written, a unitless number as itself. */
+  px(alias: Px): number;
+  /** The value in milliseconds, for a duration or a delay. */
+  ms(alias: Ms): number;
+}
+/**
+ * The readers a token ref offers, by what the build resolved that path to. A path the augmentation
+ * knows narrows to the readers its value supports, so `.px()` on a colour is a compile error; a path it
+ * does not know — before a build, or a template a prop fills in — keeps all four.
+ */
+type TokenReaders<P extends string> = P extends keyof RegisteredTokenValues ? ReadersOf<RegisteredTokenValues[P]> : ReadersOf<{
+  css: string;
+  px: number;
+  ms: number;
+}>;
+type ReadersOf<V> = {
+  /** `var(--uds-spacing-2_5)` — the reference the stylesheet's own rules use, so it follows modes. */var(): string;
+} & (V extends {
+  css: string;
+} ? {
+  value(): string;
+} : unknown) & (V extends {
+  px: number;
+} ? {
+  px(): number;
+} : unknown) & (V extends {
+  ms: number;
+} ? {
+  ms(): number;
+} : unknown);
+/** The reader names, which is what the build recognizes on a `Token.ref(…)`. */
+declare const TOKEN_READERS: readonly ["var", "value", "px", "ms"];
+type TokenReader = (typeof TOKEN_READERS)[number];
+//#endregion
+export { RegisteredTokenValues, TOKEN_READERS, TokenGroupReader, TokenReader, TokenReaders, TokenValueEntry, TokenValueRow, TokenValueState, rootFontSize, tokenExists, tokenValueRow, tokenValueRows };