@yahoo/uds-v5-wip 1.35.0 → 1.36.0

package/dist/config/dist/createConfig.d.ts

@@ -1,5 +1,7 @@
+import { AnyStyleProp } from "./defineStyleProp.js";
 import { PropertyGroupId } from "./propertyGroups.js";
 import { TokenType, VarsConfig } from "./types.js";
+import { ResolvedStyleProp } from "./resolveStyleProp.js";
 import { BaseModifierProp, ComponentsConfig, CompositeStylesConfig, ConfigurableProp, ModifierProp, MotionPreset, RemotionComponentDef, RemotionConfig, RemotionTransitionDef, StyleProp } from "@uds/types";
 
 //#region ../config/dist/createConfig.d.ts
@@ -232,6 +234,23 @@ interface UdsConfigData {
    * perspective.
    */
   presetTokenNames?: Record<string, string[]>;
+  /**
+   * Style props registered via `.registerStyleProps([...])`. Authored
+   * elsewhere via `defineStyleProp(...)` and imported into the config.
+   * The canonical input for codegen + runtime in the new architecture.
+   *
+   * Map keyed by JSX prop name (e.g. `bg`, `padding`); each value is the
+   * style-prop record carrying `cssProperty`, `classPrefix`, `values`, etc.
+   */
+  styleProps?: Record<string, AnyStyleProp>;
+  /**
+   * Resolved style props — every registered style prop run through
+   * `resolveStyleProp(propName, prop, config)` at `resolveConfig` time.
+   * Each entry carries the prop's filtered token list, literal keywords,
+   * arbitrary spec, and metadata. Codegen + runtime consume this instead
+   * of walking the raw style-prop records.
+   */
+  resolvedStyleProps?: ResolvedStyleProp[];
 }
 interface ComponentConfig<TComponents extends ComponentsConfig<string> = ComponentsConfig<string>, TMotion extends MotionPresetsDef | undefined = MotionPresetsDef | undefined> {
   name?: string;
@@ -274,6 +293,31 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
     tokens: TTokens;
   }) => M)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles & M, TModeModifiers, TVars>;
   defineArbitraryTokens(params: ArbitraryTokenGroup[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  /**
+   * Register style props, keyed by the JSX prop name consumers will use.
+   * Calls accumulate — later `.registerStyleProps({...})` calls merge into
+   * the existing map (later keys overwrite earlier ones with the same name).
+   *
+   * @example
+   * ```ts
+   * uds.registerStyleProps({
+   *   bg: {
+   *     cssProperty: 'background-color',
+   *     classPrefix: 'bg',
+   *     values: ['{global}', '{spectrum}', '{bg}'],
+   *     label: 'Background',
+   *   },
+   *   padding: {
+   *     cssProperty: 'padding',
+   *     classPrefix: 'p',
+   *     arbitrary: 'length-percentage',
+   *     values: ['{spacing}'],
+   *     label: 'Padding',
+   *   },
+   * });
+   * ```
+   */
+  registerStyleProps<const Props extends Record<string, AnyStyleProp>>(props: Props): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
   defineMotion<const M extends MotionPresetsDef>(presets: M | ((tokens: TTokens) => M)): ConfigResult<TModifier, TTokens, { [K in keyof M]: string }, TExt, TCompositeStyles, TModeModifiers, TVars>;
   defineComponents(params: ComponentsConfig<MotionAliasValue<TMotion> | string> | ((ctx: {
     tokens: TTokens;

package/dist/config/dist/createConfig.js

@@ -4,9 +4,10 @@ import "../../utils/dist/index.js";
 import { getConfigurablePropMapping } from "../../core/dist/propMappings.js";
 import "../../core/dist/index.js";
 import { buildMotionReference, resolveComponentMotionAliases, validateComponentVariants } from "./component-resolution.js";
+import { applyPresetToData, deepMerge, mergeAtomic } from "./preset-merge.js";
 import { expandPropertyGroups } from "./propertyGroups.js";
 import { resolveTokenType, sniffTokenTypeFromValue } from "./resolveTokenTypes.js";
-import { applyPresetToData, deepMerge, mergeAtomic } from "./preset-merge.js";
+import { resolveStyleProp } from "./resolveStyleProp.js";
 //#region ../config/dist/createConfig.js
 /** biome-ignore-all lint/suspicious/noExplicitAny: necessary for dynamic builder to work correctly */
 /**
@@ -266,7 +267,8 @@ function resolveConfig(config) {
 		vars: config.vars,
 		classNames: config.classNames,
 		scopes: config.scopes,
-		presetTokenNames: config.presetTokenNames
+		presetTokenNames: config.presetTokenNames,
+		styleProps: config.styleProps
 	};
 	if (configData.vars && configData.scopes) {
 		const synthesized = synthesizeAtomicFromScopesAndVars(configData.vars, configData.scopes, configData.modes);
@@ -276,6 +278,16 @@ function resolveConfig(config) {
 			atomic
 		};
 	}
+	if (configData.styleProps) {
+		const entries = Object.entries(configData.styleProps);
+		if (entries.length > 0) {
+			const resolved = entries.map(([propName, prop]) => resolveStyleProp(propName, prop, configData));
+			configData = {
+				...configData,
+				resolvedStyleProps: resolved
+			};
+		}
+	}
 	return configData;
 }
 function mergeRemotionConfig(existing, incoming) {
@@ -480,6 +492,12 @@ function createConfigBuilder(data, extensions) {
 		defineArbitraryTokens(params) {
 			return next({ arbitraryTokens: [...data.arbitraryTokens ?? [], ...params] });
 		},
+		registerStyleProps(props) {
+			return next({ styleProps: {
+				...data.styleProps ?? {},
+				...props
+			} });
+		},
 		defineMotion(presets) {
 			const tokenReference = buildTokenReference(data.atomic, data.prefix);
 			const resolved = typeof presets === "function" ? presets(tokenReference) : presets;

package/dist/config/dist/defineStyleProp.d.ts

@@ -0,0 +1,56 @@
+import { CssValueTypeName } from "./types/css-values.js";
+
+//#region ../config/dist/defineStyleProp.d.ts
+/** Runtime input type for `toCss` based on the entry's `type`. */
+type ArbitraryRuntimeValue<T extends CssValueTypeName> = T extends 'integer' | 'number' ? number : string;
+/**
+ * One entry in a multi-shape `arbitrary` array. The first entry whose `type`
+ * (or `pattern`, for `'regex'`) matches the runtime value wins.
+ */
+type ArbitraryEntry = { [T in CssValueTypeName]: {
+  type: T;
+  toCss?: (value: ArbitraryRuntimeValue<T>) => string;
+} }[CssValueTypeName] | {
+  type: 'regex';
+  pattern: RegExp;
+  toCss?: (value: string) => string;
+};
+/**
+ * Shape of the `arbitrary` field on a style prop:
+ *  - A bare value-type name (`'length-percentage'`, `'color'`, etc.) for the
+ *    single-shape case.
+ *  - An array of {@link ArbitraryEntry} for multi-shape acceptance.
+ */
+type ArbitrarySpec = CssValueTypeName | readonly ArbitraryEntry[];
+/**
+ * The literal-keyword subset of values a property accepts, derived from
+ * {@link CssPropertyValues}[P]. For custom CSS properties (`--*`) the value
+ * type is governed by the required `cssType` field instead, so any string
+ * is accepted at the type level.
+ */
+type StylePropMetadata = {
+  label?: string;
+  description?: string;
+};
+/**
+ * A finalized style prop. Returned by `defineStyleProp(spec).metadata(meta)`.
+ * Consumers wrap these in `uds.registerStyleProps({ <propName>: ... })`.
+ */
+/**
+ * Structurally-loose form of {@link StyleProp}. Any concrete `StyleProp<P>`
+ * is assignable to this. Used at registration / resolution boundaries where
+ * the generic `P` would otherwise cause TS2590 by re-expanding
+ * `ValuesEntry<P>` across the full property union.
+ */
+interface AnyStyleProp {
+  readonly kind: 'styleProp';
+  readonly cssProperty: string;
+  readonly classPrefix: string;
+  readonly values: readonly unknown[];
+  readonly arbitrary?: ArbitrarySpec;
+  readonly cssType?: CssValueTypeName;
+  readonly metadata: StylePropMetadata;
+}
+/** Intermediate builder — the only callable method is `.metadata()`. */
+//#endregion
+export { AnyStyleProp, ArbitraryEntry, ArbitrarySpec, StylePropMetadata };

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

@@ -1,7 +1,10 @@
 import { defaultColors } from "./consts/defaultColors.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 { PropertyGroupId } from "./propertyGroups.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 { ResolvedStyleProp, ResolvedToken } from "./resolveStyleProp.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,8 @@
 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 "./serialize.js";

package/dist/config/dist/propertyAcceptedTypes.js

@@ -12,11 +12,53 @@ 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"
+]);
 const LENGTH_PCT_PROPS = [
 	"gap",
 	"column-gap",
@@ -72,14 +114,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 +167,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]),
@@ -145,4 +190,18 @@ new Map([
 	["aspect-ratio", { types: ["ratio", "number"] }],
 	["opacity", { types: ["number", "percentage"] }]
 ]);
+/**
+* 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/resolveStyleProp.d.ts

@@ -1 +1,62 @@
-export { };
+import { CssValueTypeName } from "./types/css-values.js";
+import { ArbitrarySpec, StylePropMetadata } from "./defineStyleProp.js";
+//#region ../config/dist/resolveStyleProp.d.ts
+//#region src/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;
+}
+/**
+ * Structurally-loose input shape for the resolver. Any `StyleProp<P>` from
+ * `defineStyleProp` is assignable to this. Defined locally so the
+ * resolver's signature doesn't expand `ValuesEntry<P>` over the full CSS
+ * property union (TS2590).
+ */
+//#endregion
+export { ResolvedStyleProp, ResolvedToken };

package/dist/config/dist/resolveStyleProp.js

@@ -1,2 +1,188 @@
-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") return token.value.trim().endsWith("%") ? "percentage" : "length";
+	if (resolved === "string" && looksLikeShadow(token.value)) return "shadow";
+	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/types/css-values.d.ts

@@ -0,0 +1,61 @@
+//#region ../config/dist/types/css-values.d.ts
+//#region src/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
+//#endregion
+export { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor };

package/dist/core/dist/compositeStyles.d.ts

@@ -1,7 +1,6 @@
 import { CompositeStylesConfig } from "@uds/types";
 
 //#region ../core/dist/compositeStyles.d.ts
-//#region src/compositeStyles.d.ts
 /** Set the composite-styles config (called by loader at build time) */
 declare function setCompositeStylesConfig(config: CompositeStylesConfig): void;
 /** Get the current composite-styles config */
@@ -17,6 +16,6 @@ declare function getCompositeStylesConfig(): CompositeStylesConfig;
 declare function expandCompositeStyles(props: Record<string, unknown>, config?: CompositeStylesConfig): {
   expanded: Record<string, unknown>;
   markerClasses: string[];
-}; //#endregion
+};
 //#endregion
 export { expandCompositeStyles, getCompositeStylesConfig, setCompositeStylesConfig };

package/dist/core/dist/createComponent.d.ts

@@ -1,7 +1,6 @@
 import { CreateComponentConfig, CreateComponentProps, CreateComponentRenderFn, CreateComponentSlotTagConfig, CreateComponentTypeInput } from "@uds/types";
 
 //#region ../core/dist/createComponent.d.ts
-//#region src/createComponent.d.ts
 type PrimitiveTag = keyof React.JSX.IntrinsicElements;
 type SpecConfig<TSpec> = TSpec extends {
   config: infer TConfig extends CreateComponentTypeInput;
@@ -52,6 +51,6 @@ declare function createComponent<TSpecOrProps = {}>(tag: PrimitiveTag): React.FC
   props: infer TOwnProps;
 } ? CreateComponentProps<TConfig, TOwnProps, PrimitiveTag> : PrimitiveOwnProps<TSpecOrProps>>;
 declare function createComponent<TSpec>(renderFn: CreateComponentRenderFn<SpecConfig<TSpec>, SpecOwnProps<TSpec>, SpecSlotConfig<TSpec>>): React.FC<CreateComponentProps<SpecConfig<TSpec>, SpecOwnProps<TSpec>, SpecSlotConfig<TSpec>>>;
-declare function createComponent(config: CreateComponentConfig<string>, renderFn: CreateComponentRenderFn<any, any, any>): React.FC<any>; //#endregion
+declare function createComponent(config: CreateComponentConfig<string>, renderFn: CreateComponentRenderFn<any, any, any>): React.FC<any>;
 //#endregion
 export { createComponent };

package/dist/core/dist/createComponentExample.d.ts

@@ -1,7 +1,6 @@
 import { ComponentProps, ComponentType } from "react";
 
 //#region ../core/dist/createComponentExample.d.ts
-//#region src/createComponentExample.d.ts
 /**
  * Extracts variant fixtures from a Component's props type.
  * If Button has `variant?: 'brand' | 'outline'` and `size?: 'sm' | 'md'`,
@@ -37,6 +36,6 @@ type ExamplesResult<TComponent extends ComponentType<any>> = {
  * }));
  * ```
  */
-declare function createComponentExample<TComponent extends ComponentType<any>, T extends Record<string, ExampleFn<TComponent>>>(Component: TComponent, examplesFn: (fixtures: VariantFixtures<TComponent>) => ExamplesResult<TComponent>): ComponentExample<T>; //#endregion
+declare function createComponentExample<TComponent extends ComponentType<any>, T extends Record<string, ExampleFn<TComponent>>>(Component: TComponent, examplesFn: (fixtures: VariantFixtures<TComponent>) => ExamplesResult<TComponent>): ComponentExample<T>;
 //#endregion
 export { ComponentExample, createComponentExample };