@yahoo/uds-create-config 4.15.1 → 4.17.0

package/dist/configs/react-native-system.d.ts

@@ -15,7 +15,8 @@ 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 { DerivedColor, Gradient } from "../entities/system/color.js";
+import { ComposedValue } from "../entities/system/composed-values.js";
+import { DerivedColor } from "../entities/system/color.js";
 import { StyleValue } from "../entities/system/style-bag.js";
 import { ComponentElementBody, ComponentReference, ComponentStyleBody } from "../entities/system/Component.js";
 import { OverrideCondition } from "../entities/system/Token.js";
@@ -62,11 +63,11 @@ declare const ReactNativeSystem: ConfigClass<{
     }, _$zod_v4_core0.$strict>>;
   }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Omit<Record<never, never>, never> & {}, _$zod_v4_core0.$strip>, "settings", Record<never, never>, Record<never, never>, true, Record<never, never>, Record<never, never>>;
   tokens: EntityClass<_$zod.ZodObject<Omit<{
-    value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+    value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
     type: _$zod.ZodOptional<_$zod.ZodString>;
     overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
       on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
-      value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+      value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
     }, _$zod_v4_core0.$strip>>>;
   }, "value" | "overrides"> & {
     value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
@@ -2216,11 +2217,11 @@ declare const ReactNativeSystem: ConfigClass<{
       }, _$zod_v4_core0.$strict>>;
     }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Omit<Record<never, never>, never> & {}, _$zod_v4_core0.$strip>, "settings", Record<never, never>, Record<never, never>, true, Record<never, never>, Record<never, never>>;
     tokens: EntityClass<_$zod.ZodObject<Omit<{
-      value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+      value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
       type: _$zod.ZodOptional<_$zod.ZodString>;
       overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
         on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
-        value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+        value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
       }, _$zod_v4_core0.$strip>>>;
     }, "value" | "overrides"> & {
       value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;

package/dist/configs/system.d.ts

@@ -15,7 +15,7 @@ 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 { DerivedColor, Gradient } from "../entities/system/color.js";
+import { ComposedValue } from "../entities/system/composed-values.js";
 import { StyleValue } from "../entities/system/style-bag.js";
 import { ComponentElementBody, ComponentReference, ComponentStyleBody } from "../entities/system/Component.js";
 import { OverrideCondition } from "../entities/system/Token.js";
@@ -56,11 +56,11 @@ declare const System: ConfigClass<{
     }, _$zod_v4_core0.$strict>>;
   }, _$zod_v4_core0.$strict>, _$zod.ZodObject<Record<never, never>, _$zod_v4_core0.$strip>, "settings", Record<never, never>, Record<never, never>, true, Record<never, never>, Record<never, never>>;
   tokens: EntityClass<_$zod.ZodObject<{
-    value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+    value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
     type: _$zod.ZodOptional<_$zod.ZodString>;
     overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
       on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
-      value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+      value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
     }, _$zod_v4_core0.$strip>>>;
   }, _$zod_v4_core0.$strip>, _$zod.ZodObject<{
     cssPrefix: _$zod.ZodOptional<_$zod.ZodString>;
@@ -2082,11 +2082,11 @@ declare const System: ConfigClass<{
       }, _$zod_v4_core0.$strict>>;
     }, _$zod_v4_core0.$strict>, _$zod.ZodObject<Record<never, never>, _$zod_v4_core0.$strip>, "settings", Record<never, never>, Record<never, never>, true, Record<never, never>, Record<never, never>>;
     tokens: EntityClass<_$zod.ZodObject<{
-      value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+      value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
       type: _$zod.ZodOptional<_$zod.ZodString>;
       overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
         on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
-        value: _$zod.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+        value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
       }, _$zod_v4_core0.$strip>>>;
     }, _$zod_v4_core0.$strip>, _$zod.ZodObject<{
       cssPrefix: _$zod.ZodOptional<_$zod.ZodString>;

package/dist/configs/system.js

@@ -37,6 +37,7 @@ import { iconLibraryWithoutComponentMigration } from "../migrations/202609210440
 import { iconLibrariesMigration } from "../migrations/20260922013625_icon_libraries.js";
 import { iconCanvasToolMigration } from "../migrations/20260923005318_icon_canvas_tool.js";
 import { computedValuesAndRepeatedNodesMigration } from "../migrations/20260923112910_computed_values_and_repeated_nodes.js";
+import { transitionTokenValueMigration } from "../migrations/20260923144958_transition_token_value.js";
 //#region src/configs/system.ts
 /**
 * `System` — the design-system config TYPE. Declares the exact kinds a design system owns (tokens,
@@ -94,5 +95,6 @@ if (!registeredSchemaMigrations().has(20260921044042)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20260922013625)) registerSchemaMigrations(iconLibrariesMigration);
 if (!registeredSchemaMigrations().has(20260923005318)) registerSchemaMigrations(iconCanvasToolMigration);
 if (!registeredSchemaMigrations().has(20260923112910)) registerSchemaMigrations(computedValuesAndRepeatedNodesMigration);
+if (!registeredSchemaMigrations().has(20260923144958)) registerSchemaMigrations(transitionTokenValueMigration);
 //#endregion
 export { System };

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/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/Token.d.ts

@@ -2,7 +2,7 @@ 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 { ComposedValue } from "./composed-values.js";
 import { z } from "zod";
 
 //#region src/entities/system/Token.d.ts
@@ -40,22 +40,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>>;
+  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>;

package/dist/entities/system/Token.js

@@ -1,7 +1,7 @@
 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 { z } from "zod";
@@ -28,9 +28,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

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 };

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

@@ -0,0 +1,36 @@
+import { Transition } from "./transition.js";
+import { DerivedColor, Gradient } from "./color.js";
+import { z } from "zod";
+
+//#region src/entities/system/composed-values.d.ts
+type ComposedValue = DerivedColor | Gradient | Transition;
+/** How the write engine spells a stored value: the helper's name and its positional arguments. */
+interface ComposedValueAuthoring {
+  readonly helper: string;
+  readonly args: readonly unknown[];
+}
+interface ComposedValueForm<T extends ComposedValue = ComposedValue> {
+  readonly schema: z.ZodType<T>;
+  readonly is: (value: unknown) => value is T;
+  /** The value as CSS, with `render` resolving each part it holds. */
+  readonly render: (value: T, render: (part: unknown) => string) => string;
+  /**
+   * The helper call that builds this value, or `undefined` for a value no helper produces (a radial
+   * gradient, a `darken` in an unexpected space). Such a value is written as the object it is.
+   */
+  readonly authoring: (value: T) => ComposedValueAuthoring | undefined;
+}
+declare const composedValueForms: readonly ComposedValueForm[];
+/** The forms' schemas, in registry order, for a value union to spread. */
+declare const composedValueSchemas: readonly z.ZodType<ComposedValue>[];
+/** The form a value takes, or `undefined` for anything that is not composed. A string or a number
+ *  answers before the forms are asked, since every form is an object. */
+declare function composedValueFormOf(value: unknown): ComposedValueForm | undefined;
+/** Whether a value is one of the composed forms. */
+declare function isComposedValue(value: unknown): value is ComposedValue;
+/** A composed value as CSS, with `render` resolving each part it holds. */
+declare function renderComposedValue(value: ComposedValue, render: (part: unknown) => string): string;
+/** The helper call that authors a composed value, or `undefined` when none does. */
+declare function composedValueAuthoring(value: unknown): ComposedValueAuthoring | undefined;
+//#endregion
+export { ComposedValue, ComposedValueAuthoring, ComposedValueForm, composedValueAuthoring, composedValueFormOf, composedValueForms, composedValueSchemas, isComposedValue, renderComposedValue };

package/dist/entities/system/composed-values.js

@@ -0,0 +1,52 @@
+import { derivedColor, derivedColorAuthoring, gradient, gradientAuthoring, isDerivedColor, isGradient, renderDerivedColor, renderGradient } from "./color.js";
+import { isTransition, renderTransition, transitionAuthoring, transitionValue } from "./transition.js";
+//#region src/entities/system/composed-values.ts
+/** A form written against its own type, widened to the union the registry holds. `render` and
+*  `authoring` take the narrower type, which the union's signature cannot express without this. */
+function form(spec) {
+	return spec;
+}
+const composedValueForms = [
+	form({
+		schema: derivedColor,
+		is: isDerivedColor,
+		render: renderDerivedColor,
+		authoring: derivedColorAuthoring
+	}),
+	form({
+		schema: gradient,
+		is: isGradient,
+		render: renderGradient,
+		authoring: gradientAuthoring
+	}),
+	form({
+		schema: transitionValue,
+		is: isTransition,
+		render: renderTransition,
+		authoring: transitionAuthoring
+	})
+];
+/** The forms' schemas, in registry order, for a value union to spread. */
+const composedValueSchemas = composedValueForms.map((entry) => entry.schema);
+/** The form a value takes, or `undefined` for anything that is not composed. A string or a number
+*  answers before the forms are asked, since every form is an object. */
+function composedValueFormOf(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	return composedValueForms.find((entry) => entry.is(value));
+}
+/** Whether a value is one of the composed forms. */
+function isComposedValue(value) {
+	return composedValueFormOf(value) !== void 0;
+}
+/** A composed value as CSS, with `render` resolving each part it holds. */
+function renderComposedValue(value, render) {
+	const entry = composedValueFormOf(value);
+	if (!entry) throw new Error("not a composed value");
+	return entry.render(value, render);
+}
+/** The helper call that authors a composed value, or `undefined` when none does. */
+function composedValueAuthoring(value) {
+	return composedValueFormOf(value)?.authoring(value);
+}
+//#endregion
+export { composedValueAuthoring, composedValueFormOf, composedValueForms, composedValueSchemas, isComposedValue, renderComposedValue };

package/dist/entities/system/style-bag.d.ts

@@ -1,4 +1,4 @@
-import { DerivedColor, Gradient } from "./color.js";
+import { ComposedValue } from "./composed-values.js";
 import { z } from "zod";
 
 //#region src/entities/system/style-bag.d.ts
@@ -13,7 +13,7 @@ import { z } from "zod";
  */
 type StyleValue = string | number | boolean | {
   readonly __ref: string;
-} | DerivedColor | Gradient | {
+} | ComposedValue | {
   readonly [key: string]: StyleValue;
 };
 //#endregion

package/dist/entities/system/style-bag.js

@@ -1,6 +1,6 @@
 import { isExtendedRef, isRef, ref, refSchema, splitRef } from "../../framework/utils/refs.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
-import { derivedColor, gradient } from "./color.js";
+import { composedValueSchemas } from "./composed-values.js";
 import { isCssProperty, kebabCase } from "../../css/values.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
 import { glyphLeafOf, glyphPackageRef } from "./glyph-identity.js";
@@ -14,8 +14,7 @@ const styleValue = z.lazy(() => z.union([
 	z.number(),
 	z.boolean(),
 	refSchema,
-	derivedColor,
-	gradient,
+	...composedValueSchemas,
 	glyphPackageRef,
 	z.record(z.string(), styleValue)
 ]));
@@ -25,8 +24,7 @@ const anatomyPropValue = z.lazy(() => z.union([
 	z.boolean(),
 	z.null(),
 	refSchema,
-	derivedColor,
-	gradient,
+	...composedValueSchemas,
 	z.array(z.union([
 		z.string(),
 		z.number(),

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

@@ -0,0 +1,35 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { z } from "zod";
+
+//#region src/entities/system/transition.d.ts
+/** A timing part of a transition: a literal (`'150ms ease-out'`) or a ref to the entity that names it,
+ *  a token or a motion role. */
+type TimingValue = string | Ref;
+interface TransitionSegment {
+  /** The CSS properties this segment animates. Each renders as its own `<property> <timing>` entry. */
+  readonly properties: readonly string[];
+  /** The duration and easing, together, as a ref to the entity that names them or a literal. */
+  readonly timing: TimingValue;
+  readonly delay?: TimingValue;
+}
+interface Transition {
+  readonly transition: readonly TransitionSegment[];
+}
+/** Whether a value is a composed transition — the test the renderers branch on. Every segment must
+ *  carry its properties and timing, so a record that merely holds a list under `transition` is not
+ *  one. */
+declare function isTransition(value: unknown): value is Transition;
+/**
+ * `transition({ properties: ['translate', 'scale'], timing: Token.ref('motion/expressive') })`.
+ * Several segments compose one transition whose properties run on different roles.
+ */
+declare function transition(...segments: readonly TransitionSegment[]): Transition;
+/**
+ * A transition as CSS — `background-color var(--uds-motion-color), box-shadow var(--uds-motion-color)`.
+ *
+ * `render` resolves the timing parts. It is passed in rather than imported because resolving a ref
+ * to a `var()` is the projection layer's job and this module is the value's shape.
+ */
+declare function renderTransition(value: Transition, render: (part: TimingValue) => string): string;
+//#endregion
+export { TimingValue, Transition, TransitionSegment, isTransition, renderTransition, transition };

package/dist/entities/system/transition.js

@@ -0,0 +1,57 @@
+import { refSchema } from "../../framework/utils/refs.js";
+import { z } from "zod";
+//#region src/entities/system/transition.ts
+/**
+* A CSS transition composed from the properties it animates and the timing they run on —
+* `transition({ properties: ['background-color', 'box-shadow'], timing: Token.ref('motion/color') })`.
+*
+* A design system names its timing once, as a motion role (`motion/color` is "150ms linear"), and a
+* transition is that role applied to some properties. Spelled as one string the role is copied into
+* the transition and stops following the token: retune the duration and the transition keeps the old
+* one. Held as parts, the role is a ref, so it renders as a `var()` and the dependency graph sees it.
+*
+* Usable wherever a style value is — a token's value, a style bag — for the same reason a gradient
+* is: it is a value, not its own kind.
+*/
+const timingValue = z.union([z.string(), refSchema]);
+const transitionValue = z.strictObject({ transition: z.array(z.strictObject({
+	properties: z.array(z.string()).min(1),
+	timing: timingValue,
+	delay: timingValue.optional()
+})).min(1) });
+/** Whether a value is a composed transition — the test the renderers branch on. Every segment must
+*  carry its properties and timing, so a record that merely holds a list under `transition` is not
+*  one. */
+function isTransition(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const segments = value.transition;
+	return Array.isArray(segments) && segments.every((segment) => typeof segment === "object" && segment !== null && Array.isArray(segment.properties) && "timing" in segment);
+}
+/**
+* `transition({ properties: ['translate', 'scale'], timing: Token.ref('motion/expressive') })`.
+* Several segments compose one transition whose properties run on different roles.
+*/
+function transition(...segments) {
+	return { transition: segments };
+}
+/** The `transition(...)` call that authors a stored value: its segments are the arguments. */
+function transitionAuthoring(value) {
+	return {
+		helper: "transition",
+		args: value.transition
+	};
+}
+/**
+* A transition as CSS — `background-color var(--uds-motion-color), box-shadow var(--uds-motion-color)`.
+*
+* `render` resolves the timing parts. It is passed in rather than imported because resolving a ref
+* to a `var()` is the projection layer's job and this module is the value's shape.
+*/
+function renderTransition(value, render) {
+	return value.transition.flatMap((segment) => {
+		const timing = [segment.timing, segment.delay].filter((part) => part !== void 0).map(render);
+		return segment.properties.map((property) => [property, ...timing].join(" "));
+	}).join(", ");
+}
+//#endregion
+export { isTransition, renderTransition, transition, transitionAuthoring, transitionValue };

package/dist/framework/Config.d.ts

@@ -72,7 +72,7 @@ interface RecordedSource {
  * The dense-counter `2` a short-lived scheme stamped before the chain existed reads as the mint
  * that replaced it (see `detectedWireVersion`).
  */
-declare const SERIALIZED_CONFIG_VERSION = 20260923112910;
+declare const SERIALIZED_CONFIG_VERSION = 20260923144958;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -4836,7 +4836,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20260923112910) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20260923144958) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;

package/dist/framework/defineEntity.js

@@ -1,4 +1,4 @@
-import { isRef, kindOf, pathOf, ref, refSchema, sourceOf } from "./utils/refs.js";
+import { isRef, kindOf, pathOf, ref, refSchema, refTo, sourceOf } from "./utils/refs.js";
 import { CONFIG_OPERATION_KIND } from "./config-operation-kind.js";
 import { resolveFields } from "./schemas.js";
 import { buildKind } from "./registry.js";
@@ -129,10 +129,7 @@ function defineEntity(spec) {
 		authoredValue: spec.authoredValue,
 		invariants: spec.invariants
 	});
-	const schema = z.object({ __ref: z.string().refine((raw) => kindOf(raw) === spec.kind) }).meta({
-		ref: true,
-		refKind: spec.kind
-	});
+	const schema = refTo(spec.kind);
 	/**
 	* The path a caller named — from a path, a ref object, or a ref string (`component:Box`, which is
 	* what a spec element's `type` is, so a caller reading one needn't take it apart first).

package/dist/framework/projections.js

@@ -1,7 +1,7 @@
 import { isRef, kindOf, memberOf, pathOf, ref, refLeaf, sourceOf, splitRef } from "./utils/refs.js";
 import { forwardedPropName, forwardsOf } from "../entities/system/element.js";
 import { classPrefixOf, varPrefixOf } from "../entities/system/Settings.js";
-import { isDerivedColor, isGradient, renderDerivedColor, renderGradient } from "../entities/system/color.js";
+import { isComposedValue, renderComposedValue } from "../entities/system/composed-values.js";
 import { fontFamilyStack } from "../entities/system/Font.js";
 import { listedIn } from "./utils/enumerated.js";
 import { modifierCategory } from "../entities/system/Modifier.js";
@@ -488,8 +488,7 @@ function resolveTokenValueUnder(config, path, condition, seen = /* @__PURE__ */
 *  ordinary call — it is `config`'s own prefix. */
 function renderStyleValue(config, value, varPrefix) {
 	if (Array.isArray(value)) return value.map((part) => renderStyleValue(config, part, varPrefix)).join(" ");
-	if (isDerivedColor(value)) return renderDerivedColor(value, (color) => renderStyleValue(config, color, varPrefix));
-	if (isGradient(value)) return renderGradient(value, (color) => renderStyleValue(config, color, varPrefix));
+	if (isComposedValue(value)) return renderComposedValue(value, (part) => renderStyleValue(config, part, varPrefix));
 	if (isRef(value)) {
 		const source = config.configFor(value);
 		if (!source) return "";

package/dist/framework/schema-version.d.ts

@@ -15,7 +15,7 @@ import { Patch, SerializedConfig } from "./Config.js";
  * sets this constant to its own older timestamp; the merge ref then carries a registered migration
  * newer than the constant, and the assertion fails until the author re-mints.
  */
-declare const CURRENT_SCHEMA_VERSION = 20260923112910;
+declare const CURRENT_SCHEMA_VERSION = 20260923144958;
 /** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
  *  and a raw old-shape record both flow in without casts. */
 interface VersionStamped {