@yahoo/uds-v5-wip 1.35.0 → 1.36.1

package/dist/config/dist/defineStyleProp.js

@@ -0,0 +1,25 @@
+//#region ../config/dist/defineStyleProp.js
+const CUSTOM_PROPERTY_PREFIX = "--";
+/**
+* Author a style prop. Returns a builder whose `.metadata({...})` finalizes
+* the {@link StyleProp} record. Pure — no global registration.
+*/
+function defineStyleProp(spec) {
+	const { cssProperty, classPrefix, values, arbitrary, cssType } = spec;
+	const isCustomProperty = cssProperty.startsWith(CUSTOM_PROPERTY_PREFIX);
+	if (isCustomProperty && cssType === void 0) throw new Error(`defineStyleProp: cssType is required for custom CSS properties (got cssProperty=${JSON.stringify(cssProperty)}).`);
+	if (!isCustomProperty && cssType !== void 0) throw new Error(`defineStyleProp: cssType is only allowed for custom CSS properties (--*). Got cssProperty=${JSON.stringify(cssProperty)} with cssType=${JSON.stringify(cssType)}.`);
+	return { metadata(meta = {}) {
+		return {
+			kind: "styleProp",
+			cssProperty,
+			classPrefix,
+			values: values ?? [],
+			arbitrary,
+			cssType,
+			metadata: meta
+		};
+	} };
+}
+//#endregion
+export { defineStyleProp };

package/dist/config/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { defaultColors } from "./consts/defaultColors.js";
-import { PropertyGroupId } from "./propertyGroups.js";
+import { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor } from "./types/css-values.js";
+import { AnyStyleProp, ArbitraryEntry, ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
+import { ResolvedStyleProp, ResolvedToken } from "./resolveStyleProp.js";
 import { TokenType, VarGroupDef, VarTokenDef, VarsConfig } from "./types.js";
-import { ArbitraryTokenGroup, AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig } from "./createConfig.js";
+import { AtomicToken, BuildOptions, CheckForReservedModifiersInput, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GetModifierFromInput, GlobalStylesDef, InterpolateMarker, ModeGroup, ModeOption, ModeOptionInput, ModeSetInput, ModesInput, ModifierDef, MotionPresetsDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig } from "./createConfig.js";
 import { SerializedConfig, TokenRef, buildReverseMap, deserializeConfig, serializeConfig } from "./serialize.js";
 import { ComponentsConfig as ComponentsConfig$1 } from "@uds/types";
 export { type ComponentsConfig$1 as ComponentsConfig };

package/dist/config/dist/index.js

@@ -1,8 +1,9 @@
 import "./consts/defaultColors.js";
 import "./component-resolution.js";
-import "./propertyGroups.js";
-import "./resolveTokenTypes.js";
-import "./createConfig.js";
 import "./propertyAcceptedTypes.js";
+import "./resolveTokenTypes.js";
 import "./resolveStyleProp.js";
+import "./createConfig.js";
+import "./defineStyleProp.js";
+import "./propertyGroups.js";
 import "./serialize.js";

package/dist/config/dist/preset-merge.js

@@ -148,16 +148,7 @@ function applyPresetToData(base, preset, strategy) {
 	};
 	const mergedExamples = base.examples || preset.examples ? mergeRecordByKey(base.examples ?? {}, preset.examples ?? {}, s.examples) : void 0;
 	const mergedPrinciples = base.designPrinciples || preset.designPrinciples ? [...base.designPrinciples ?? [], ...preset.designPrinciples ?? []] : void 0;
-	const mergedArbitraryTokens = base.arbitraryTokens || preset.arbitraryTokens ? [...base.arbitraryTokens ?? [], ...preset.arbitraryTokens ?? []] : void 0;
 	const mergedVars = base.vars || preset.vars ? mergeRecordByKey(base.vars ?? {}, preset.vars ?? {}, "merge") : void 0;
-	const mergedClassNames = base.classNames || preset.classNames ? {
-		...base.classNames,
-		...preset.classNames
-	} : void 0;
-	const mergedScopes = base.scopes || preset.scopes ? {
-		...base.scopes,
-		...preset.scopes
-	} : void 0;
 	const merged = {
 		...base,
 		modes: mergeModes(base.modes, preset.modes, s.modes),
@@ -171,12 +162,9 @@ function applyPresetToData(base, preset, strategy) {
 		components: mergeRecordByKey(base.components, preset.components, s.components),
 		globalStyles: mergeRecordByKey(base.globalStyles, preset.globalStyles, s.globalStyles),
 		remotion: mergeRemotionConfig(base.remotion, preset.remotion),
-		arbitraryTokens: mergedArbitraryTokens,
 		examples: mergedExamples,
 		designPrinciples: mergedPrinciples,
 		vars: mergedVars,
-		classNames: mergedClassNames,
-		scopes: mergedScopes,
 		presetTokenNames: mergePresetTokenNames(base, preset)
 	};
 	validateComponentVariants(merged.components);

package/dist/config/dist/propertyAcceptedTypes.js

@@ -12,11 +12,56 @@ const LENGTH_PCT_AUTO = {
 	],
 	literals: ["auto"]
 };
+const SIZING = {
+	types: [
+		"length",
+		"percentage",
+		"length-percentage"
+	],
+	literals: [
+		"auto",
+		"min-content",
+		"max-content",
+		"fit-content"
+	]
+};
+const SIZING_WITH_NONE = {
+	types: [
+		"length",
+		"percentage",
+		"length-percentage"
+	],
+	literals: [
+		"auto",
+		"min-content",
+		"max-content",
+		"fit-content",
+		"none"
+	]
+};
 const LENGTH_ONLY = { types: ["length"] };
-const COLOR_ONLY = { types: ["color"] };
+const COLOR_ONLY = {
+	types: ["color"],
+	literals: ["transparent", "currentColor"]
+};
 const TIME_ONLY = { types: ["time"] };
 const NUMBER_ONLY = { types: ["number", "integer"] };
 const ANGLE_ONLY = { types: ["angle"] };
+/**
+* CSS-wide keywords — accepted on every CSS property per the CSS spec.
+* Synthesizer marks these as `$type: 'string'` so they don't match the
+* property's type-based accept rule; they pass via this set instead.
+*/
+const CSS_WIDE_KEYWORDS = new Set([
+	"inherit",
+	"initial",
+	"unset",
+	"revert",
+	"revert-layer",
+	"transparent",
+	"currentColor",
+	"currentcolor"
+]);
 const LENGTH_PCT_PROPS = [
 	"gap",
 	"column-gap",
@@ -72,14 +117,15 @@ const LENGTH_PCT_AUTO_PROPS = [
 	"left",
 	"inset",
 	"inset-block",
-	"inset-inline",
+	"inset-inline"
+];
+const SIZING_PROPS = [
 	"width",
 	"height",
 	"min-width",
-	"min-height",
-	"max-width",
-	"max-height"
+	"min-height"
 ];
+const SIZING_WITH_NONE_PROPS = ["max-width", "max-height"];
 const LENGTH_ONLY_PROPS = [
 	"border-width",
 	"border-top-width",
@@ -124,9 +170,11 @@ const NUMBER_PROPS = [
 	"-webkit-line-clamp"
 ];
 const ANGLE_PROPS = ["rotate"];
-new Map([
+const PROPERTY_ACCEPTED_TYPES = new Map([
 	...LENGTH_PCT_PROPS.map((p) => [p, LENGTH_PCT]),
 	...LENGTH_PCT_AUTO_PROPS.map((p) => [p, LENGTH_PCT_AUTO]),
+	...SIZING_PROPS.map((p) => [p, SIZING]),
+	...SIZING_WITH_NONE_PROPS.map((p) => [p, SIZING_WITH_NONE]),
 	...LENGTH_ONLY_PROPS.map((p) => [p, LENGTH_ONLY]),
 	...COLOR_PROPS.map((p) => [p, COLOR_ONLY]),
 	...TIME_PROPS.map((p) => [p, TIME_ONLY]),
@@ -139,10 +187,34 @@ new Map([
 	] }],
 	["font-family", { types: ["font-family"] }],
 	["transition-timing-function", { types: ["easing-function"] }],
-	["box-shadow", { types: ["shadow"] }],
-	["text-shadow", { types: ["shadow"] }],
+	["box-shadow", {
+		types: ["shadow"],
+		literals: ["none"]
+	}],
+	["text-shadow", {
+		types: ["shadow"],
+		literals: ["none"]
+	}],
 	["list-style-image", { types: ["url", "image"] }],
 	["aspect-ratio", { types: ["ratio", "number"] }],
-	["opacity", { types: ["number", "percentage"] }]
+	["opacity", { types: ["number", "percentage"] }],
+	["z-index", {
+		types: ["integer", "number"],
+		literals: ["auto"]
+	}]
 ]);
+/**
+* Whether a token with the given detected value type AND raw string value
+* is accepted by the CSS property. Returns `true` for any property not in
+* the table.
+*/
+function isTokenAcceptedByProperty(cssProperty, valueType, rawValue) {
+	if (CSS_WIDE_KEYWORDS.has(rawValue)) return true;
+	const entry = PROPERTY_ACCEPTED_TYPES.get(cssProperty);
+	if (!entry) return true;
+	if (valueType && entry.types?.includes(valueType)) return true;
+	if (entry.literals?.includes(rawValue)) return true;
+	return false;
+}
 //#endregion
+export { PROPERTY_ACCEPTED_TYPES, isTokenAcceptedByProperty };

package/dist/config/dist/propertyGroups.d.ts

@@ -1,11 +1 @@
-import { ConfigurableProp } from "@uds/types";
-
-//#region ../config/dist/propertyGroups.d.ts
-//#region src/propertyGroups.d.ts
-type PropertyGroupId = 'textColor' | 'background' | 'borderColor' | 'outlineColor' | 'ringColor' | 'divideColor' | 'shadowColor' | 'svgFill' | 'svgStroke' | 'caretColor' | 'textDecorationColor' | 'opacity' | 'colorOpacity' | 'bgOpacity' | 'borderColorOpacity' | 'divideColorOpacity' | 'outlineColorOpacity' | 'ringColorOpacity' | 'textDecorationColorOpacity' | 'svgFillOpacity' | 'svgStrokeOpacity' | 'shadowColorOpacity' | 'caretColorOpacity' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'lineHeight' | 'letterSpacing' | 'blur' | 'backdropBlur' | 'animation' | 'shadow' | 'textShadow' | 'zIndex' | 'borderWidth' | 'borderRadius' | 'outlineWidth' | 'divideWidth' | 'ringWidth' | 'padding' | 'margin' | 'offset' | 'gap' | 'indent' | 'scrollSnapGap' | 'scrollSnapSpacing' | 'tableBorderSpacing' | 'width' | 'height' | 'aspectRatio' | 'positionPlacement' | 'flex' | 'transform' | 'strokeWidth';
-/**
- * A logical grouping of ConfigurableProps with a human-readable label.
- * Used by the Studio UI to let users scope token groups to specific properties.
- */
-//#endregion
-export { PropertyGroupId };
+import { ConfigurableProp } from "@uds/types";

package/dist/config/dist/propertyGroups.js

@@ -394,7 +394,7 @@ const ALL_PROPERTY_GROUPS = [
 		properties: ["strokeWidth"]
 	}
 ];
-const groupById = new Map(ALL_PROPERTY_GROUPS.map((g) => [g.id, g]));
+new Map(ALL_PROPERTY_GROUPS.map((g) => [g.id, g]));
 const propToGroupId = /* @__PURE__ */ new Map();
 for (const group of ALL_PROPERTY_GROUPS) for (const prop of group.properties) propToGroupId.set(prop, group.id);
 const COLOR_GROUPS = [
@@ -411,22 +411,4 @@ const COLOR_GROUPS = [
 	"textDecorationColor"
 ];
 [...COLOR_GROUPS], [...COLOR_GROUPS], [...COLOR_GROUPS];
-/**
-* Given an array of group IDs, returns the flat union of all their
-* member ConfigurableProps (deduplicated).
-*/
-function expandPropertyGroups(groupIds) {
-	const seen = /* @__PURE__ */ new Set();
-	const result = [];
-	for (const id of groupIds) {
-		const group = groupById.get(id);
-		if (!group) continue;
-		for (const prop of group.properties) if (!seen.has(prop)) {
-			seen.add(prop);
-			result.push(prop);
-		}
-	}
-	return result;
-}
 //#endregion
-export { expandPropertyGroups };

package/dist/config/dist/resolveStyleProp.d.ts

@@ -1 +1,55 @@
-export { };
+import { CssValueTypeName } from "./types/css-values.js";
+import { ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
+//#region ../config/dist/resolveStyleProp.d.ts
+interface ResolvedToken {
+  /** The token's raw key, e.g. `'brand'`. */
+  readonly name: string;
+  /** Resolved CSS value, e.g. `'#1167f4'` or `'1rem'`. */
+  readonly value: string;
+  /** Detected CSS value type, used for filtering. `undefined` if not detectable. */
+  readonly valueType: CssValueTypeName | undefined;
+  /** The token group's namespace (or cssPrefix fallback) the token came from. */
+  readonly group: string;
+  /**
+   * Style-prop-local namespace, set only when the token was sourced via a
+   * {@link NamespacedGroupRef}. Used to disambiguate when two groups feed
+   * the same prop and share keys.
+   */
+  readonly namespace?: string;
+  /**
+   * The user-facing key the consumer writes in JSX. For un-namespaced
+   * groups this is just `name`; for namespaced groups, `'${namespace}.${name}'`.
+   */
+  readonly qualifiedName: string;
+  /**
+   * The token name with characters that aren't class-name-safe replaced
+   * (e.g. `/` → `_`, `.` → `_`). Used as the trailing segment of generated
+   * `@utility` class names and CSS variable names. Mirrors
+   * `safeTokenName` from `@uds/utils`.
+   */
+  readonly safeName: string;
+  /**
+   * Full CSS variable reference for this token at config-build time, e.g.
+   * `'--uds-bg-brand'`. Built as `--{config.prefix}-{group.cssPrefix}-{safeName}`,
+   * falling back to omit the config prefix when it's empty.
+   */
+  readonly cssVar: string;
+  /**
+   * Per-modifier value overrides carried verbatim from the source
+   * `AtomicTokenValue`. Used by CSS-gen to emit mode override blocks
+   * (e.g. `.dark { --uds-bg-brand: ... }`).
+   */
+  readonly modifiers?: Record<string, string>;
+}
+interface ResolvedStyleProp {
+  /** The JSX prop name — the map key from `registerStyleProps({...})`. */
+  readonly propName: string;
+  readonly cssProperty: string;
+  readonly classPrefix: string;
+  readonly tokens: readonly ResolvedToken[];
+  readonly literals: readonly string[];
+  readonly arbitrary: ArbitrarySpec | undefined;
+  readonly metadata: StylePropMetadata;
+}
+//#endregion
+export { ResolvedStyleProp, ResolvedToken };

package/dist/config/dist/resolveStyleProp.js

@@ -1,2 +1,197 @@
-import "./resolveTokenTypes.js";
-import "./propertyAcceptedTypes.js";
+import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
+import "../../utils/dist/index.js";
+import { isTokenAcceptedByProperty } from "./propertyAcceptedTypes.js";
+import { sniffTokenTypeFromValue } from "./resolveTokenTypes.js";
+//#region ../config/dist/resolveStyleProp.js
+/**
+* Resolve a {@link StyleProp} authored via `defineStyleProp` against the
+* active UDS config, producing a flat list of accepted tokens, literal
+* keywords, and the arbitrary spec — the data that downstream codegen
+* consumes to populate `Custom*` interfaces and emit utility CSS.
+*
+* Filtering invariant: a token is exposed in the resolved pool only when
+* its detected CSS value type is accepted by the prop's `cssProperty`,
+* per {@link PROPERTY_ACCEPTED_TYPES}. Properties absent from that table
+* accept every token.
+*
+* The resolver is pure — given the same `(StyleProp, UdsConfigData)` input
+* it returns the same output. Group lookups are by `namespace` (with a
+* fallback to `cssPrefix`) on the resolved config's `atomic` array.
+*/
+/**
+* Map the legacy 8-entry `TokenType` enum to a {@link CssValueTypeName}.
+* The `'dimension'` case is ambiguous (length vs. percentage); callers
+* disambiguate by sniffing the value string.
+*/
+function tokenTypeToValueType(t) {
+	switch (t) {
+		case "color": return "color";
+		case "dimension": return "length-percentage";
+		case "number": return "number";
+		case "fontFamily": return "font-family";
+		case "fontWeight": return "font-weight";
+		case "duration": return "time";
+		case "strokeStyle": return "string";
+		case "string": return "string";
+		default: return;
+	}
+}
+/**
+* A value looks like a CSS shadow when it combines at least one length
+* (offset/blur/spread) with a color reference. Catches both single-shadow
+* (`'0 1px 2px rgba(...)'`) and multi-shadow (`'..., ...'`) forms, plus
+* inset shadows. Used to refine `'string'`-typed tokens to the more precise
+* `'shadow'` value type so they pass the runtime filter on `box-shadow` /
+* `text-shadow` props.
+*/
+const SHADOW_LENGTH_RE = /(?:^|[\s,])-?\d+(?:\.\d+)?(?:px|rem|em|ch|ex)/i;
+const SHADOW_COLOR_RE = /(?:rgba?|hsla?|color|oklch|oklab|lch|lab|hwb)\(|#[0-9a-fA-F]{3,8}\b/;
+function looksLikeShadow(value) {
+	const trimmed = value.trim();
+	return SHADOW_LENGTH_RE.test(trimmed) && SHADOW_COLOR_RE.test(trimmed);
+}
+/**
+* Detect a token's CSS value type. Resolution order:
+*  1. Per-token `type` override.
+*  2. Group-level `type`.
+*  3. Value sniff via {@link sniffTokenTypeFromValue}.
+*
+* When the resolved type is `'length-percentage'` and the raw value ends in
+* `%`, narrow to `'percentage'`; otherwise narrow to `'length'`. When the
+* resolved type is `'string'` but the value looks like a shadow expression,
+* narrow to `'shadow'`.
+*/
+function detectTokenValueType(token, group) {
+	const explicit = token.type ?? group.type;
+	let resolved;
+	if (explicit) resolved = tokenTypeToValueType(explicit);
+	else {
+		const sniffed = sniffTokenTypeFromValue(token.value);
+		resolved = sniffed ? tokenTypeToValueType(sniffed) : void 0;
+	}
+	if (resolved === "length-percentage") {
+		const trimmed = token.value.trim();
+		if (trimmed.endsWith("%")) return "percentage";
+		if (/(deg|rad|grad|turn)$/.test(trimmed)) return "angle";
+		if (/(ms|s)$/.test(trimmed)) return "time";
+		return "length";
+	}
+	if (resolved === "string") {
+		if (looksLikeShadow(token.value)) return "shadow";
+		if (/^\d+(?:\.\d+)?\s*\/\s*\d+(?:\.\d+)?$/.test(token.value.trim())) return "ratio";
+	}
+	return resolved;
+}
+const REF_RE = /^\{([^.{}]+)(?:\.([^.{}]+))?\}$/;
+/**
+* Parse a string ref like `'{palette}'` or `'{spacing.4}'`. Returns
+* `undefined` for any string that isn't a brace ref (so the caller can
+* treat it as a literal keyword).
+*/
+function parseGroupRef(raw) {
+	const m = REF_RE.exec(raw);
+	if (!m) return void 0;
+	const [, group, key] = m;
+	if (!group) return void 0;
+	return key !== void 0 ? {
+		group,
+		key
+	} : { group };
+}
+function findGroup(atomic, name) {
+	return atomic.find((g) => g.namespace === name || g.cssPrefix === name);
+}
+function isNamespacedRef(entry) {
+	return typeof entry === "object" && entry !== null && "ref" in entry && "namespace" in entry;
+}
+/**
+* Build `--{configPrefix}-{varPrefix}-{safeName}` (or omit the configPrefix
+* when empty). Mirrors `buildTokenVarName` in `@uds/codegen/css/prepareCss`.
+*/
+function buildCssVar(configPrefix, varPrefix, safeName) {
+	return configPrefix ? `--${configPrefix}-${varPrefix}-${safeName}` : `--${varPrefix}-${safeName}`;
+}
+function resolveGroupTokens(group, cssProperty, configPrefix, namespace) {
+	const groupName = group.namespace ?? group.cssPrefix ?? "";
+	const varPrefix = group.cssPrefix ?? group.namespace ?? "";
+	const out = [];
+	for (const token of group.tokens) {
+		const valueType = detectTokenValueType(token, group);
+		if (!isTokenAcceptedByProperty(cssProperty, valueType, token.value)) continue;
+		const safeName = safeTokenName(token.name);
+		out.push({
+			name: token.name,
+			value: token.value,
+			valueType,
+			group: groupName,
+			namespace,
+			qualifiedName: namespace !== void 0 ? `${namespace}.${token.name}` : token.name,
+			safeName,
+			cssVar: buildCssVar(configPrefix, varPrefix, safeName),
+			modifiers: token.modifiers
+		});
+	}
+	return out;
+}
+/**
+* Resolve a style prop against the given resolved UDS config. Unknown group
+* refs are silently dropped from `tokens` (callers can detect this by
+* comparing input refs vs. resolved tokens if they need to surface a
+* config-build warning).
+*
+* @param propName - The JSX prop name (the map key from `registerStyleProps`).
+*/
+function resolveStyleProp(propName, styleProp, config) {
+	const { cssProperty, classPrefix, values, arbitrary, metadata } = styleProp;
+	const configPrefix = config.prefix;
+	const tokens = [];
+	const literals = [];
+	for (const entry of values ?? []) {
+		if (typeof entry === "string") {
+			const parsed = parseGroupRef(entry);
+			if (!parsed) {
+				literals.push(entry);
+				continue;
+			}
+			const group = findGroup(config.atomic, parsed.group);
+			if (!group) continue;
+			if (parsed.key !== void 0) {
+				const token = group.tokens.find((t) => t.name === parsed.key);
+				if (!token) continue;
+				const valueType = detectTokenValueType(token, group);
+				if (!isTokenAcceptedByProperty(cssProperty, valueType, token.value)) continue;
+				const safeName = safeTokenName(token.name);
+				const varPrefix = group.cssPrefix ?? group.namespace ?? parsed.group;
+				tokens.push({
+					name: token.name,
+					value: token.value,
+					valueType,
+					group: group.namespace ?? group.cssPrefix ?? parsed.group,
+					qualifiedName: token.name,
+					safeName,
+					cssVar: buildCssVar(configPrefix, varPrefix, safeName),
+					modifiers: token.modifiers
+				});
+			} else tokens.push(...resolveGroupTokens(group, cssProperty, configPrefix));
+			continue;
+		}
+		if (isNamespacedRef(entry)) {
+			const parsed = parseGroupRef(entry.ref);
+			if (!parsed || parsed.key !== void 0) continue;
+			const group = findGroup(config.atomic, parsed.group);
+			if (!group) continue;
+			tokens.push(...resolveGroupTokens(group, cssProperty, configPrefix, entry.namespace));
+		}
+	}
+	return {
+		propName,
+		cssProperty,
+		classPrefix,
+		tokens,
+		literals,
+		arbitrary,
+		metadata: metadata ?? {}
+	};
+}
+//#endregion
+export { resolveStyleProp };

package/dist/config/dist/serialize.d.ts

@@ -1,8 +1,8 @@
-import { ArbitraryTokenGroup, AtomicToken, ExampleDef, ModeGroup, ModifierDef, MotionPresetsDef, UdsConfig } from "./createConfig.js";
+import { VarsConfig } from "./types.js";
+import { AtomicToken, ExampleDef, ModeGroup, ModifierDef, MotionPresetsDef, UdsConfig } from "./createConfig.js";
 import { CompositeStylesConfig } from "@uds/types";
 
 //#region ../config/dist/serialize.d.ts
-//#region src/serialize.d.ts
 type ModifierNameShape = `_${string}`;
 type TokenRef = {
   $ref: string;
@@ -10,6 +10,14 @@ type TokenRef = {
 interface SerializedConfig {
   modes: ModeGroup[];
   modifiers?: ModifierDef[];
+  /**
+   * Verbatim `defineVars` input. Authoritative source for CSS variable
+   * declarations downstream. `atomic` carries derived (property × token)
+   * data for utility-class generation; `vars` carries the original
+   * namespace-keyed input. New code should rely on `vars`; `atomic` is
+   * still emitted for legacy consumers.
+   */
+  vars?: VarsConfig;
   atomic: AtomicToken<ModifierNameShape>[];
   compositeStyles?: CompositeStylesConfig;
   /**
@@ -18,7 +26,6 @@ interface SerializedConfig {
    * until they're rewritten. New code should populate `compositeStyles`.
    */
   macros?: Record<string, Record<string, Record<string, unknown>>>;
-  arbitraryTokens?: ArbitraryTokenGroup[];
   motion?: MotionPresetsDef;
   components: SerializedComponentsDef;
   globalStyles?: Record<string, Record<string, SerializedValue>>;
@@ -60,6 +67,6 @@ declare function serializeConfig(config: UdsConfig): SerializedConfig;
  * Resolves `$ref` markers back to `var()` strings using the atomic token
  * definitions, then reconstructs the builder chain.
  */
-declare function deserializeConfig(data: SerializedConfig): UdsConfig; //#endregion
+declare function deserializeConfig(data: SerializedConfig): UdsConfig;
 //#endregion
 export { SerializedConfig, TokenRef, buildReverseMap, deserializeConfig, serializeConfig };

package/dist/config/dist/serialize.js

@@ -1,6 +1,6 @@
 import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
 import "../../utils/dist/index.js";
-import { getConfigurablePropMapping } from "../../core/dist/propMappings.js";
+import { getConfigurablePropMapping } from "../../core/dist/configurable-prop-helpers.js";
 import "../../core/dist/index.js";
 import { buildTokenReference, createConfigBuilder, resolveConfig } from "./createConfig.js";
 //#region ../config/dist/serialize.js
@@ -107,9 +107,9 @@ function serializeConfig(config) {
 	return {
 		modes: data.modes,
 		modifiers: data.modifiers.length > 0 ? data.modifiers : void 0,
+		vars: data.vars && Object.keys(data.vars).length > 0 ? data.vars : void 0,
 		atomic: data.atomic,
 		compositeStyles: Object.keys(data.compositeStyles).length > 0 ? data.compositeStyles : void 0,
-		arbitraryTokens: data.arbitraryTokens && data.arbitraryTokens.length > 0 ? data.arbitraryTokens : void 0,
 		motion: Object.keys(data.motion).length > 0 ? data.motion : void 0,
 		components,
 		globalStyles: Object.keys(globalStyles).length > 0 ? globalStyles : void 0,
@@ -150,13 +150,13 @@ function deserializeConfig(data) {
 	let config = createConfigBuilder({
 		modes: data.modes,
 		modifiers: data.modifiers ?? [],
+		vars: data.vars,
 		atomic: data.atomic,
 		compositeStyles: data.compositeStyles ?? upgradeLegacyMacros(data.macros),
 		motion: data.motion ?? {},
 		components,
 		preflight: data.preflight,
 		prefix: data.prefix ?? "uds",
-		arbitraryTokens: data.arbitraryTokens,
 		remotion: void 0,
 		globalStyles: {},
 		presetTokenNames: data.presetTokenNames

package/dist/config/dist/types/css-values.d.ts

@@ -0,0 +1,60 @@
+//#region ../config/dist/types/css-values.d.ts
+/**
+ * CSS value-type primitives — building blocks used by {@link CssPropertyValues}
+ * in `./css-properties` and by `defineStyleProp` to constrain authored values.
+ *
+ * Each entry in {@link CssValue} corresponds to a CSS value type name from the
+ * CSS specs (length, percentage, color, time, etc.). The CSS-wide keywords
+ * (`inherit`, `initial`, `unset`, `revert`) are bundled into {@link ColorKeyword}
+ * because color is the most common channel for them; properties that accept
+ * those keywords on non-color value types are expected to list them locally.
+ *
+ * Note: named colors (`red`, `blue`, etc.) are intentionally NOT in the union —
+ * authors should use a token, a hex code, or a function form (`rgb(...)`, etc.).
+ */
+/** CSS-wide keywords accepted on color-valued properties. */
+type ColorKeyword = 'transparent' | 'currentColor' | 'inherit' | 'initial' | 'unset' | 'revert';
+type HexColor = `#${string}`;
+type RgbColor = `rgb(${string})` | `rgba(${string})`;
+type HslColor = `hsl(${string})` | `hsla(${string})`;
+type ColorFn = `color(${string})` | `lab(${string})` | `lch(${string})` | `oklab(${string})` | `oklch(${string})`;
+type CssColor = HexColor | RgbColor | HslColor | ColorFn | ColorKeyword;
+type CssLength = `${number}px` | `${number}rem` | `${number}em` | `${number}ch` | `${number}ex` | `${number}vh` | `${number}vw` | `${number}vmin` | `${number}vmax` | 0;
+type CssPercentage = `${number}%`;
+type CssAngle = `${number}deg` | `${number}rad` | `${number}grad` | `${number}turn`;
+type CssTime = `${number}ms` | `${number}s`;
+type CssRatio = `${number}/${number}`;
+/**
+ * Registry of CSS value types, keyed by their spec-defined names.
+ *
+ * Used in two places:
+ *  1. As the source of truth for what shapes count as e.g. a "length" or a
+ *     "color" when validating token values and `defineStyleProp` `arbitrary`
+ *     specs.
+ *  2. By {@link import('./css-properties').CssPropertyValues}, which composes
+ *     these entries (plus per-property keywords) into the union accepted by
+ *     each CSS property.
+ */
+type CssValue = {
+  color: CssColor;
+  length: CssLength;
+  percentage: CssPercentage;
+  'length-percentage': CssLength | CssPercentage;
+  number: number;
+  integer: number;
+  angle: CssAngle;
+  time: CssTime;
+  ratio: CssRatio;
+  image: string;
+  url: `url(${string})`;
+  'font-weight': number | 'normal' | 'bold' | 'lighter' | 'bolder';
+  'font-family': string;
+  'easing-function': 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'step-start' | 'step-end' | `cubic-bezier(${string})` | `steps(${string})`;
+  shadow: string;
+  gradient: string;
+  ident: string;
+  string: string;
+};
+type CssValueTypeName = keyof CssValue;
+//#endregion
+export { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor };

package/dist/config/dist/types.d.ts

@@ -1,5 +1,4 @@
 //#region ../config/dist/types.d.ts
-//#region src/types.d.ts
 /**
  * Scalar DTCG-aligned token types. Composite types (shadow, gradient,
  * typography, border, transition, cubicBezier) are intentionally deferred
@@ -60,6 +59,6 @@ type VarGroupDef<M extends `_${string}` = `_${string}`> = {
  *   spacing: { $type: 'dimension', 1: { value: '0.25rem' }, 2: { value: '0.5rem' } },
  * }
  */
-type VarsConfig<M extends `_${string}` = `_${string}`> = Record<string, VarGroupDef<M>>; //#endregion
+type VarsConfig<M extends `_${string}` = `_${string}`> = Record<string, VarGroupDef<M>>;
 //#endregion
 export { TokenType, VarGroupDef, VarTokenDef, VarsConfig };