@yahoo/uds-v5-wip 1.34.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
@@ -28,6 +30,8 @@ type IsReservedModifier<T> = T extends BaseModifierProp ? true : false;
 type HasReservedModifier<T> = T extends any ? IsReservedModifier<T> extends true ? true : never : never;
 interface ModeOption {
   name: string;
+  /** Optional human-readable label for Studio. Falls back to `name`. */
+  label?: string;
   modifier: ModifierNameShape;
   /** Description for AI prompt generation (e.g. "Apply styles in dark mode") */
   description?: string;
@@ -37,16 +41,55 @@ interface ModeOption {
 }
 interface ModeGroup {
   name: string;
+  /** Optional human-readable label for Studio. Falls back to `name`. */
+  label?: string;
   options: ModeOption[];
 }
+/** Single option within a mode set, as authored. */
+interface ModeOptionInput {
+  /** Optional human-readable label for Studio. Falls back to the option key. */
+  label?: string;
+  /**
+   * Optional explicit modifier string. When omitted, derived as `_${optionKey}`.
+   * Use this when the option key and modifier must differ (e.g. `xxl` → `_2xl`).
+   */
+  modifier?: ModifierNameShape;
+  /** CSS selector applied when this option is active (e.g. `.dark`). */
+  css?: string;
+  /** Media query applied when this option is active. */
+  media?: string;
+}
+/** Single mode set, as authored. */
+interface ModeSetInput {
+  /** Optional human-readable label for Studio. Falls back to the set key. */
+  label?: string;
+  options: Record<string, ModeOptionInput>;
+}
+/** Object-keyed input shape accepted by `defineModes`. */
+type ModesInput = Record<string, ModeSetInput>;
+/**
+ * Extract the union of modifier strings produced by an authored `ModesInput`.
+ * Uses an explicit `modifier` when present; otherwise derives `_${optionKey}`.
+ * Drives both the reserved-modifier guard and the modifier types that flow
+ * through subsequent builder calls.
+ */
+type GetModifierFromInput<I extends ModesInput> = { [SetKey in keyof I]: { [OptKey in keyof I[SetKey]['options']]: I[SetKey]['options'][OptKey] extends {
+  modifier: infer M;
+} ? M extends ModifierNameShape ? M : never : OptKey extends string ? `_${OptKey}` : never }[keyof I[SetKey]['options']] }[keyof I];
+/** Reject any input whose derived/explicit modifiers collide with reserved names. */
+type CheckForReservedModifiersInput<I extends ModesInput> = true extends HasReservedModifier<GetModifierFromInput<I>> ? 'ERROR: Cannot use reserved modifier names from ModifierProp. Please use a different modifier name.' : I;
+/**
+ * Convert the authored object-keyed input into the internal `ModeGroup[]` shape.
+ * Derives `_${optionKey}` modifiers when no explicit `modifier` is provided.
+ * Never sets `default: true` — the new API has no concept of a default option;
+ * downstream consumers treat "no option active" as the implicit default.
+ */
 interface ModifierDef {
   modifier: ModifierNameShape;
   selector: string;
   /** Description for AI prompt generation (e.g. "Apply styles on elevation-1 surfaces") */
   description?: string;
 }
-/** Extract modifier union from all mode groups */
-type GetModifierName<M extends readonly ModeGroup[]> = M[number]['options'][number]['modifier'];
 interface ArbitraryTokenGroup {
   properties: string[];
   pattern: string | string[];
@@ -133,8 +176,6 @@ type EmptyVars = {};
 /** Build a structured token reference object from atomic tokens */
 declare function buildTokenReference(atomic: AtomicToken<ModifierNameShape>[], configPrefix: string): Record<string, Record<string, string>>;
 /** Build a structured composite-styles reference object for use in defineModifiers context */
-/** Extract all modifiers from mode groups and check if any are reserved */
-type CheckForReservedModifiers<T extends readonly ModeGroup[]> = true extends HasReservedModifier<GetModifierName<T>> ? 'ERROR: Cannot use reserved modifier names from ModifierProp. Please use a different modifier name.' : T;
 /** Global styles definition — CSS selector → style props */
 type GlobalStylesDef = Record<string, Record<string, any>>;
 /** CSS properties for the example wrapper element */
@@ -193,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;
@@ -226,7 +284,7 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
   preflight(enabled?: boolean): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
   prefix(value: string): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
   buildOptions(options: BuildOptions): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
-  defineModes<const NewModes extends readonly ModeGroup[]>(params: CheckForReservedModifiers<NewModes>): ConfigResult<TModifier | GetModifierName<NewModes>, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers | GetModifierName<NewModes>, TVars>;
+  defineModes<const NewModes extends ModesInput>(params: CheckForReservedModifiersInput<NewModes>): ConfigResult<TModifier | GetModifierFromInput<NewModes>, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers | GetModifierFromInput<NewModes>, TVars>;
   defineModifiers<const Defs extends readonly ModifierDef[]>(params: Defs | ((ctx: {
     tokens: TTokens;
     compositeStyles: CompositeStylesReference<TCompositeStyles>;
@@ -235,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;
@@ -315,4 +398,4 @@ interface InterpolateMarker {
 declare function darker(color: string, amount: number): string;
 declare function lighter(color: string, amount: number): string;
 //#endregion
-export { ArbitraryTokenGroup, AtomicToken, BuildOptions, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GlobalStylesDef, InterpolateMarker, ModeGroup, ModifierDef, MotionPresetsDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig };
+export { 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 };

package/dist/config/dist/createConfig.js

@@ -4,11 +4,41 @@ 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 */
+/**
+* Convert the authored object-keyed input into the internal `ModeGroup[]` shape.
+* Derives `_${optionKey}` modifiers when no explicit `modifier` is provided.
+* Never sets `default: true` — the new API has no concept of a default option;
+* downstream consumers treat "no option active" as the implicit default.
+*/
+function convertModesInputToGroups(input) {
+	const groups = [];
+	for (const [setKey, setValue] of Object.entries(input)) {
+		const options = [];
+		for (const [optionKey, optionValue] of Object.entries(setValue.options)) {
+			const option = {
+				name: optionKey,
+				modifier: optionValue.modifier ?? `_${optionKey}`
+			};
+			if (optionValue.label !== void 0) option.label = optionValue.label;
+			if (optionValue.css !== void 0) option.css = optionValue.css;
+			if (optionValue.media !== void 0) option.media = optionValue.media;
+			options.push(option);
+		}
+		const group = {
+			name: setKey,
+			options
+		};
+		if (setValue.label !== void 0) group.label = setValue.label;
+		groups.push(group);
+	}
+	return groups;
+}
 /** Build a structured token reference object from atomic tokens */
 function buildTokenReference(atomic, configPrefix) {
 	const result = Object.create(null);
@@ -237,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);
@@ -247,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) {
@@ -391,9 +432,10 @@ function createConfigBuilder(data, extensions) {
 			return next({ buildOptions: options });
 		},
 		defineModes(params) {
+			const newGroups = convertModesInputToGroups(params);
 			return createConfigBuilder({
 				...data,
-				modes: [...data.modes, ...params]
+				modes: [...data.modes, ...newGroups]
 			}, extensions);
 		},
 		defineModifiers(params) {
@@ -450,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;
@@ -692,4 +740,4 @@ const uds = createConfigBuilder({
 	remotion: void 0
 });
 //#endregion
-export { buildCompositeStylesReference, buildTokenReference, createConfigBuilder, darker, interpolate, lighter, rem, resolveConfig, uds };
+export { buildCompositeStylesReference, buildTokenReference, convertModesInputToGroups, createConfigBuilder, darker, interpolate, lighter, rem, resolveConfig, uds };

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, ComponentConfig, DefineComponentInput, DefineComponentMotionInput, ExampleDef, ExampleEntryDef, ExampleLayoutStyles, GlobalStylesDef, InterpolateMarker, ModeGroup, ModifierDef, MotionPresetsDef, UdsConfig, UdsConfigData, buildTokenReference, createConfigBuilder, darker, lighter, resolveConfig } from "./createConfig.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 };