@yahoo/uds-v5-wip 1.4.0 → 1.5.0

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

@@ -1,4 +1,5 @@
-import { BaseModifierProp, ComponentsConfig, ConfigurableProp, MacroConfig, ModifierProp, MotionPreset, RemotionComponentDef, RemotionConfig, RemotionTransitionDef } from "@uds/types";
+import { UtilitiesConfig, UtilityDef, VarsConfig } from "./types.js";
+import { BaseModifierProp, ComponentsConfig, ConfigurableProp, MacroConfig, ModifierProp, MotionPreset, RemotionComponentDef, RemotionConfig, RemotionTransitionDef, StyleProp } from "@uds/types";
 
 //#region ../config/dist/createConfig.d.ts
 //#region src/createConfig.d.ts
@@ -72,22 +73,30 @@ interface AtomicToken<M extends ModifierNameShape = ModifierNameShape> {
    */
   cssPrefix?: string;
 }
-/** Helper to extract all modifier keys from AtomicToken array */
-type ExtractModifierKeys<T> = T extends readonly AtomicToken<infer M>[] ? M : never;
-/** Helper to check if all modifiers in the tokens are valid */
-type ValidateModifiers<Tokens extends readonly AtomicToken<any>[], ValidModifiers extends ModifierNameShape> = ExtractModifierKeys<Tokens> extends ValidModifiers ? Tokens : never;
-/** Extract property keys from atomic tokens */
-type ExtractProperties<T extends readonly AtomicToken<any>[]> = T[number]['properties'][number];
-/** Distributive helper: for each token group U, yield its token names if P is one of its properties */
-type TokenNamesForProperty<U, P extends ConfigurableProp> = U extends AtomicToken<any> ? P extends U['properties'][number] ? U['tokens'][number]['name'] : never : never;
-/** Build token structure for a specific property */
-type BuildTokensForProperty<T extends readonly AtomicToken<any>[], P extends ConfigurableProp> = { [K in TokenNamesForProperty<T[number], P>]: string };
-/** Extract token names from atomic tokens array */
-type ExtractTokenNames<T extends readonly AtomicToken<any>[]> = { [P in ExtractProperties<T>]: BuildTokensForProperty<T, P> };
 /** Merge two token structures */
 type MergeTokens<A, B> = { [K in keyof A | keyof B]: K extends keyof B ? K extends keyof A ? A[K] & B[K] : B[K] : K extends keyof A ? A[K] : never };
+/**
+ * Given a VarsConfig and a single utility `values` string (e.g. `'{fontWeight}'`),
+ * extract the token-name keys from the referenced namespace.
+ */
+type ExtractNsTokens<TVars extends VarsConfig, Ref extends string> = Ref extends `{${infer NS}}` ? NS extends keyof TVars ? { [K in keyof TVars[NS]]: string } : Record<string, string> : Record<string, string>;
+/** Collapse a union into an intersection so multi-namespace token maps are merged. */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/**
+ * Derive the token map shape (`{ propName: { tokenName: string } }`) that
+ * `defineUtilities` adds to `TTokens`, based on the accumulated `TVars` and the
+ * concrete utilities config type.
+ *
+ * Only `values: '{namespace}'` references produce typed tokens; literal-values
+ * and boolean utilities fall through to `Record<string, string>`.
+ */
+type ExtractVarsTokens<TVars extends VarsConfig, TUtils extends Record<string, unknown>> = { [P in keyof TUtils]: TUtils[P] extends {
+  values: infer V;
+} ? V extends string ? ExtractNsTokens<TVars, V> : V extends readonly string[] ? UnionToIntersection<ExtractNsTokens<TVars, V[number]>> : Record<string, string> : Record<string, string> };
 /** Empty tokens type for initial state */
 type EmptyTokens = {};
+/** Empty vars type for initial state */
+type EmptyVars = {};
 /** Build a structured token reference object from atomic tokens */
 declare function buildTokenReference(atomic: AtomicToken<ModifierNameShape>[], configPrefix: string): Record<ConfigurableProp, Record<string, string>>;
 /** Build a structured macro reference object for use in defineModifiers context */
@@ -126,6 +135,8 @@ interface UdsConfigData {
   buildOptions?: BuildOptions;
   examples?: Record<string, ExampleDef>;
   designPrinciples?: string[];
+  vars?: VarsConfig;
+  utilities?: UtilitiesConfig;
 }
 interface ComponentConfig<TComponents extends ComponentsConfig<string> = ComponentsConfig<string>, TMotion extends MotionPresetsDef | undefined = MotionPresetsDef | undefined> {
   name?: string;
@@ -151,58 +162,59 @@ type RemotionComponentInput<TTokens, TMotion> = RemotionComponentDef | ((ctx: {
   components: Record<string, any>;
 }) => RemotionComponentDef);
 /** Helper type: builder result includes both the UdsConfig interface and any extensions */
-type ConfigResult<TModifier extends ModifierNameShape, TTokens, TMotion, TExt extends Record<string, any> = {}, TMacros = EmptyMacros> = UdsConfig<TModifier, TTokens, TMotion, TExt, TMacros> & TExt;
-interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TMacros = EmptyMacros> {
+type ConfigResult<TModifier extends ModifierNameShape, TTokens, TMotion, TExt extends Record<string, any> = {}, TMacros = EmptyMacros, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars> = UdsConfig<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars> & TExt;
+interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TMacros = EmptyMacros, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars> {
   modes: ModeGroup[];
   atomic: AtomicToken<ModifierNameShape>[];
   components: ComponentsConfig;
-  preflight(enabled?: boolean): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  prefix(value: string): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  buildOptions(options: BuildOptions): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  defineModes<const NewModes extends readonly ModeGroup[]>(params: CheckForReservedModifiers<NewModes>): ConfigResult<TModifier | GetModifierName<NewModes>, TTokens, TMotion, TExt, TMacros>;
+  preflight(enabled?: boolean): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  prefix(value: string): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  buildOptions(options: BuildOptions): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineModes<const NewModes extends readonly ModeGroup[]>(params: CheckForReservedModifiers<NewModes>): ConfigResult<TModifier | GetModifierName<NewModes>, TTokens, TMotion, TExt, TMacros, TModeModifiers | GetModifierName<NewModes>, TVars>;
   defineModifiers<const Defs extends readonly ModifierDef[]>(params: Defs | ((ctx: {
     tokens: TTokens;
     macros: MacroReference<TMacros>;
-  }) => Defs)): ConfigResult<TModifier | Defs[number]['modifier'], TTokens, TMotion, TExt, TMacros>;
+  }) => Defs)): ConfigResult<TModifier | Defs[number]['modifier'], TTokens, TMotion, TExt, TMacros, TModeModifiers | Defs[number]['modifier'], TVars>;
   defineMacro<const M extends MacroConfig>(params: M | ((ctx: {
     tokens: TTokens;
-  }) => M)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros & M>;
-  defineAtomicTokens<const Tokens extends readonly AtomicToken<any>[]>(params: [TModifier] extends [ModifierProp] ? Tokens : ValidateModifiers<Tokens, TModifier>): ConfigResult<TModifier, MergeTokens<TTokens, ExtractTokenNames<Tokens>>, TMotion, TExt, TMacros>;
-  defineArbitraryTokens(params: ArbitraryTokenGroup[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  defineMotion<const M extends MotionPresetsDef>(presets: M | ((tokens: TTokens) => M)): ConfigResult<TModifier, TTokens, { [K in keyof M]: string }, TExt, TMacros>;
+  }) => M)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros & M, TModeModifiers, TVars>;
+  defineArbitraryTokens(params: ArbitraryTokenGroup[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineMotion<const M extends MotionPresetsDef>(presets: M | ((tokens: TTokens) => M)): ConfigResult<TModifier, TTokens, { [K in keyof M]: string }, TExt, TMacros, TModeModifiers, TVars>;
   defineComponents(params: ComponentsConfig<MotionAliasValue<TMotion> | string> | ((ctx: {
     tokens: TTokens;
     motion: TMotion;
     components: Record<string, any>;
-  }) => ComponentsConfig<MotionAliasValue<TMotion> | string>)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  defineGlobalStyles(params: GlobalStylesDef | ((tokens: TTokens) => GlobalStylesDef)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  defineDesignPrinciples(principles: string[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  defineExample(name: string, examples: ExampleDef): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  compose(...presets: (ComponentConfig | UdsConfig | Partial<UdsConfigData>)[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
+  }) => ComponentsConfig<MotionAliasValue<TMotion> | string>)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineGlobalStyles(params: GlobalStylesDef | ((tokens: TTokens) => GlobalStylesDef)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineDesignPrinciples(principles: string[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineExample(name: string, examples: ExampleDef): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  compose(...presets: (ComponentConfig | UdsConfig | Partial<UdsConfigData>)[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
   defineComponent<const TName extends string, const TComponent extends SingleComponentDef<MotionAliasValue<TMotion> | string>, const TPresetMotion extends MotionPresetsDef = EmptyMotionPresetsDef>(name: TName, component: DefineComponentInput<TTokens, TMotion, TComponent>, motion?: DefineComponentMotionInput<TTokens, TPresetMotion>): ComponentConfig<SingleComponentDefinitionRecord<TName, TComponent>, TPresetMotion>;
-  from(data: Partial<UdsConfigData>): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
-  extend<const NewExt extends Record<string, any>>(ext: NewExt): ConfigResult<TModifier, TTokens, TMotion, TExt & NewExt, TMacros>;
+  from(data: Partial<UdsConfigData>): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  extend<const NewExt extends Record<string, any>>(ext: NewExt): ConfigResult<TModifier, TTokens, TMotion, TExt & NewExt, TMacros, TModeModifiers, TVars>;
   defineRemotionComponents(params: RemotionConfig | ((ctx: {
     tokens: TTokens;
     motion: TMotion;
     components: Record<string, any>;
-  }) => RemotionConfig)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
+  }) => RemotionConfig)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
   defineRemotionComponent<const TName extends string, const TComponent extends SingleComponentDef<MotionAliasValue<TMotion> | string>, const TPresetMotion extends MotionPresetsDef = EmptyMotionPresetsDef>(name: TName, def: RemotionComponentInput<TTokens, TMotion>, motion?: DefineComponentMotionInput<TTokens, TPresetMotion>): ComponentConfig<SingleComponentDefinitionRecord<TName, TComponent>, TPresetMotion>;
   defineRemotionTransition(name: string, def: RemotionTransitionDef | ((ctx: {
     tokens: TTokens;
   }) => RemotionTransitionDef)): ComponentConfig;
   defineRemotionTransitions(params: Record<string, RemotionTransitionDef> | ((ctx: {
     tokens: TTokens;
-  }) => Record<string, RemotionTransitionDef>)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros>;
+  }) => Record<string, RemotionTransitionDef>)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineVars<const TVarsNew extends VarsConfig<[TModeModifiers] extends [never] ? `_${string}` : TModeModifiers>>(vars: TVarsNew): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars & TVarsNew>;
+  defineUtilities<const TUtils extends { [K in keyof TUtils]: K extends StyleProp ? UtilityDef : never }>(utilities: TUtils): ConfigResult<TModifier, MergeTokens<TTokens, ExtractVarsTokens<TVars, TUtils>>, TMotion, TExt, TMacros, TModeModifiers, TVars>;
 }
-type AnyUdsConfig = UdsConfig<ModifierNameShape, any, any, any, any>;
+type AnyUdsConfig = UdsConfig<ModifierNameShape, any, any, any, any, any, any>;
 /** Extract the raw config data from a builder instance */
 declare function resolveConfig(config: AnyUdsConfig): UdsConfigData;
 /**
  * Resolve configuration with all token references replaced by their raw values.
  * Useful for tools that need the actual values (e.g. anatomy generation).
  */
-declare function createConfigBuilder<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TMacros = EmptyMacros>(data: UdsConfigData, extensions?: TExt): UdsConfig<TModifier, TTokens, TMotion, TExt, TMacros> & TExt;
+declare function createConfigBuilder<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TMacros = EmptyMacros, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars>(data: UdsConfigData, extensions?: TExt): UdsConfig<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars> & TExt;
 interface InterpolateMarker {
   __type: 'interpolate';
   output: number[];

package/dist/config/dist/createConfig.js

@@ -1,3 +1,4 @@
+import { kebabCase } from "../../utils/dist/string-utils/kebabCase.js";
 import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
 import "../../utils/dist/index.js";
 import { getConfigurablePropMapping } from "../../core/dist/propMappings.js";
@@ -29,10 +30,94 @@ function buildMacroReference(macros) {
 	}
 	return result;
 }
+/**
+* Parse a `'{namespace}'` reference string, returning the namespace name
+* or `undefined` if the string is not a valid reference.
+*/
+function parseVarsReference(ref) {
+	return ref.match(/^\{(.+)\}$/)?.[1];
+}
+/** Normalize values to an array of string refs, filtering out non-string forms. */
+function normalizeValuesRefs(values) {
+	if (!values) return [];
+	if (typeof values === "string") return [values];
+	if (Array.isArray(values)) return values;
+	return [];
+}
+/** Convert a VarGroupDef into AtomicToken tokens, extracting modifier overrides. */
+function varGroupToTokens(varGroup, knownModifiers) {
+	const tokens = [];
+	for (const [tokenName, tokenDef] of Object.entries(varGroup)) {
+		const modifiers = {};
+		for (const [key, val] of Object.entries(tokenDef)) {
+			if (key === "value" || val === void 0) continue;
+			if (key.startsWith("_") && knownModifiers.has(key)) modifiers[key] = val;
+		}
+		tokens.push({
+			name: tokenName,
+			value: tokenDef.value,
+			...Object.keys(modifiers).length > 0 ? { modifiers } : {}
+		});
+	}
+	return tokens;
+}
+/**
+* Bridge: synthesize AtomicToken[] from defineVars + defineUtilities data.
+*
+* For each utility, resolves its `values` references (single or array) to var
+* namespaces. Each (namespace, property) pair produces a separate AtomicToken
+* group with `cssPrefix` = namespace name, so CSS custom properties land in
+* the correct `--prefix-namespace-token` space.
+*
+* When `values` is an array (`['{color}', '{bg}']`), tokens from all referenced
+* namespaces are included. Name collisions are resolved by the existing
+* `mergeAtomic` logic (last group wins within the same property+cssPrefix key).
+*/
+function synthesizeAtomicFromVarsAndUtilities(vars, utilities, modes) {
+	const knownModifiers = /* @__PURE__ */ new Set();
+	for (const mode of modes) for (const option of mode.options) knownModifiers.add(option.modifier);
+	const pairs = /* @__PURE__ */ new Map();
+	for (const [propName, utilDef] of Object.entries(utilities)) {
+		if (!utilDef) continue;
+		const refs = normalizeValuesRefs(utilDef.values);
+		for (const ref of refs) {
+			const namespace = parseVarsReference(ref);
+			if (!namespace || !vars[namespace]) continue;
+			const key = `${namespace}|${propName}`;
+			pairs.set(key, {
+				namespace,
+				property: propName
+			});
+		}
+	}
+	const namespaceGroups = /* @__PURE__ */ new Map();
+	for (const { namespace, property } of pairs.values()) {
+		const props = namespaceGroups.get(namespace) ?? /* @__PURE__ */ new Set();
+		props.add(property);
+		namespaceGroups.set(namespace, props);
+	}
+	const result = [];
+	for (const [namespace, propertySet] of namespaceGroups) {
+		const varGroup = vars[namespace];
+		if (!varGroup) continue;
+		const tokens = varGroupToTokens(varGroup, knownModifiers);
+		const cssPfx = (propertySet.has(namespace) ? getConfigurablePropMapping(namespace) : void 0)?.defaultVarPrefix ?? kebabCase(namespace);
+		const properties = Array.from(propertySet).sort((a, b) => {
+			return (a === namespace || kebabCase(a) === cssPfx ? 1 : 0) - (b === namespace || kebabCase(b) === cssPfx ? 1 : 0);
+		});
+		result.push({
+			properties,
+			tokens,
+			cssPrefix: cssPfx
+		});
+	}
+	return result;
+}
 /** Extract the raw config data from a builder instance */
 function resolveConfig(config) {
-	if (config._data) return config._data;
-	return {
+	let configData;
+	if (config._data) configData = config._data;
+	else configData = {
 		modes: config.modes ?? [],
 		modifiers: config.modifiers ?? [],
 		atomic: config.atomic ?? [],
@@ -46,8 +131,18 @@ function resolveConfig(config) {
 		remotion: config.remotion,
 		buildOptions: config.buildOptions,
 		examples: config.examples,
-		designPrinciples: config.designPrinciples
+		designPrinciples: config.designPrinciples,
+		vars: config.vars,
+		utilities: config.utilities
 	};
+	if (configData.vars && configData.utilities) {
+		const synthesized = synthesizeAtomicFromVarsAndUtilities(configData.vars, configData.utilities, configData.modes);
+		configData = {
+			...configData,
+			atomic: mergeAtomic(configData.atomic, synthesized, "merge")
+		};
+	}
+	return configData;
 }
 function mergeRemotionConfig(existing, incoming) {
 	return {
@@ -81,7 +176,7 @@ function resolvePresetData(input) {
 		prefix: "uds",
 		remotion: input.remotion
 	};
-	if ("defineAtomicTokens" in input) return resolveConfig(input);
+	if ("defineVars" in input) return resolveConfig(input);
 	return {
 		modes: input.modes ?? [],
 		modifiers: input.modifiers ?? [],
@@ -95,7 +190,9 @@ function resolvePresetData(input) {
 		arbitraryTokens: input.arbitraryTokens,
 		remotion: input.remotion,
 		examples: input.examples,
-		designPrinciples: input.designPrinciples
+		designPrinciples: input.designPrinciples,
+		vars: input.vars,
+		utilities: input.utilities
 	};
 }
 function extractVarReferences(value) {
@@ -239,12 +336,6 @@ function createConfigBuilder(data, extensions) {
 				}
 			}, extensions);
 		},
-		defineAtomicTokens(params) {
-			return createConfigBuilder({
-				...data,
-				atomic: mergeAtomic(data.atomic, params, "merge")
-			}, extensions);
-		},
 		defineArbitraryTokens(params) {
 			return next({ arbitraryTokens: [...data.arbitraryTokens ?? [], ...params] });
 		},
@@ -342,7 +433,9 @@ function createConfigBuilder(data, extensions) {
 				prefix: input.prefix ?? data.prefix,
 				arbitraryTokens: input.arbitraryTokens ?? data.arbitraryTokens,
 				examples: input.examples ?? data.examples,
-				designPrinciples: input.designPrinciples ?? data.designPrinciples
+				designPrinciples: input.designPrinciples ?? data.designPrinciples,
+				vars: input.vars ?? data.vars,
+				utilities: input.utilities ?? data.utilities
 			}, extensions);
 		},
 		extend(ext) {
@@ -414,6 +507,37 @@ function createConfigBuilder(data, extensions) {
 				components: {},
 				transitions: resolved
 			}) });
+		},
+		defineVars(vars) {
+			const merged = { ...data.vars };
+			for (const [namespace, group] of Object.entries(vars)) merged[namespace] = {
+				...merged[namespace] ?? {},
+				...group
+			};
+			const updates = { vars: merged };
+			if (data.utilities && Object.keys(data.utilities).length > 0) {
+				const synthesized = synthesizeAtomicFromVarsAndUtilities(merged, data.utilities, data.modes ?? []);
+				updates.atomic = mergeAtomic(data.atomic, synthesized, "merge");
+			}
+			return createConfigBuilder({
+				...data,
+				...updates
+			}, extensions);
+		},
+		defineUtilities(utilities) {
+			const merged = {
+				...data.utilities,
+				...utilities
+			};
+			const updates = { utilities: merged };
+			if (data.vars && Object.keys(data.vars).length > 0) {
+				const synthesized = synthesizeAtomicFromVarsAndUtilities(data.vars, merged, data.modes ?? []);
+				updates.atomic = mergeAtomic(data.atomic ?? [], synthesized, "merge");
+			}
+			return createConfigBuilder({
+				...data,
+				...updates
+			}, extensions);
 		}
 	};
 }

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

@@ -1,5 +1,7 @@
 import { defaultColors } from "./consts/defaultColors.js";
+import { UtilitiesConfig, UtilityDef, 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 { ResolvedUtilityMapping, resolveUtilityMappings } from "./resolvedMappings.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,4 +1,5 @@
 import "./consts/defaultColors.js";
 import "./component-resolution.js";
 import "./createConfig.js";
+import "./resolvedMappings.js";
 import "./serialize.js";

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

@@ -141,6 +141,11 @@ 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 mergedUtilities = base.utilities || preset.utilities ? {
+		...base.utilities,
+		...preset.utilities
+	} : void 0;
 	const merged = {
 		...base,
 		modes: mergeModes(base.modes, preset.modes, s.modes),
@@ -156,7 +161,9 @@ function applyPresetToData(base, preset, strategy) {
 		remotion: mergeRemotionConfig(base.remotion, preset.remotion),
 		arbitraryTokens: mergedArbitraryTokens,
 		examples: mergedExamples,
-		designPrinciples: mergedPrinciples
+		designPrinciples: mergedPrinciples,
+		vars: mergedVars,
+		utilities: mergedUtilities
 	};
 	validateComponentVariants(merged.components);
 	return merged;

package/dist/config/dist/resolvedMappings.d.ts

@@ -0,0 +1,22 @@
+import { UtilitiesConfig } from "./types.js";
+
+//#region ../config/dist/resolvedMappings.d.ts
+//#region src/resolvedMappings.d.ts
+interface ResolvedUtilityMapping {
+  classPrefix: string;
+  cssProperty?: string;
+  defaultVarPrefix?: string;
+  literalValues?: string[];
+}
+/**
+ * Derive PropMapping-equivalent data from a defineUtilities config.
+ *
+ * For each utility:
+ * - `className` → `classPrefix`
+ * - `values: '{ns}'` → `defaultVarPrefix = ns`
+ * - `transform('__probe__')` → inspect returned CSS property keys → `cssProperty` (first key)
+ * - `literalValues` → passed through
+ */
+declare function resolveUtilityMappings(utilities: UtilitiesConfig): Record<string, ResolvedUtilityMapping>; //#endregion
+//#endregion
+export { ResolvedUtilityMapping, resolveUtilityMappings };

package/dist/config/dist/resolvedMappings.js

@@ -0,0 +1,43 @@
+import { kebabCase } from "../../utils/dist/string-utils/kebabCase.js";
+import "../../utils/dist/index.js";
+//#region ../config/dist/resolvedMappings.js
+/**
+* Resolve utility mappings from a defineUtilities config into PropMapping-equivalent data.
+*
+* When `config.utilities` is present, this derives the same shape that `propMappings`
+* provides — `classPrefix`, `cssProperty`, `defaultVarPrefix`, `literalValues` — by
+* inspecting each utility definition. Falls back to the hardcoded `propMappings` from
+* `@uds/core` when no utilities config exists.
+*/
+const PROBE_VALUE = "__probe__";
+/**
+* Derive PropMapping-equivalent data from a defineUtilities config.
+*
+* For each utility:
+* - `className` → `classPrefix`
+* - `values: '{ns}'` → `defaultVarPrefix = ns`
+* - `transform('__probe__')` → inspect returned CSS property keys → `cssProperty` (first key)
+* - `literalValues` → passed through
+*/
+function resolveUtilityMappings(utilities) {
+	const result = {};
+	for (const [propName, utilDef] of Object.entries(utilities)) {
+		const mapping = { classPrefix: utilDef.className };
+		if (utilDef.transform) try {
+			const noopToken = (ref) => `var(--${ref.replace(".", "-")})`;
+			const cssOutput = utilDef.transform(PROBE_VALUE, { token: noopToken });
+			const cssProps = Object.keys(cssOutput);
+			if (cssProps.length > 0) mapping.cssProperty = cssProps[0];
+		} catch {}
+		const valuesRef = Array.isArray(utilDef.values) ? utilDef.values[utilDef.values.length - 1] : typeof utilDef.values === "string" ? utilDef.values : void 0;
+		if (valuesRef) {
+			const match = valuesRef.match(/^\{(.+)\}$/);
+			if (match) mapping.defaultVarPrefix = kebabCase(match[1]);
+		}
+		if (utilDef.literalValues) mapping.literalValues = utilDef.literalValues;
+		result[propName] = mapping;
+	}
+	return result;
+}
+//#endregion
+export { resolveUtilityMappings };

package/dist/config/dist/serialize.js

@@ -2,7 +2,7 @@ import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
 import "../../utils/dist/index.js";
 import { getConfigurablePropMapping } from "../../core/dist/propMappings.js";
 import "../../core/dist/index.js";
-import { buildTokenReference, resolveConfig, uds } from "./createConfig.js";
+import { buildTokenReference, createConfigBuilder, resolveConfig } from "./createConfig.js";
 //#region ../config/dist/serialize.js
 /**
 * Config serialization for lossless round-tripping through a database.
@@ -131,16 +131,19 @@ function deserializeConfig(data) {
 		if (compConfig.defaultVariants) resolved.defaultVariants = compConfig.defaultVariants;
 		components[compName] = resolved;
 	}
-	let config = uds;
-	if (data.prefix) config = config.prefix(data.prefix);
-	config = config.preflight(data.preflight);
-	if (data.modes.length > 0) config = config.defineModes(data.modes);
-	if (data.modifiers && data.modifiers.length > 0) config = config.defineModifiers(data.modifiers);
-	if (data.atomic.length > 0) config = config.defineAtomicTokens(data.atomic);
-	if (data.arbitraryTokens && data.arbitraryTokens.length > 0) config = config.defineArbitraryTokens(data.arbitraryTokens);
-	if (data.macros && Object.keys(data.macros).length > 0) config = config.defineMacro(data.macros);
-	if (data.motion && Object.keys(data.motion).length > 0) config = config.defineMotion(data.motion);
-	if (Object.keys(components).length > 0) config = config.defineComponents(components);
+	let config = createConfigBuilder({
+		modes: data.modes,
+		modifiers: data.modifiers ?? [],
+		atomic: data.atomic,
+		macros: data.macros ?? {},
+		motion: data.motion ?? {},
+		components,
+		preflight: data.preflight,
+		prefix: data.prefix ?? "uds",
+		arbitraryTokens: data.arbitraryTokens,
+		remotion: void 0,
+		globalStyles: {}
+	});
 	if (data.globalStyles && Object.keys(data.globalStyles).length > 0) {
 		const globalStyles = {};
 		for (const [selector, styles] of Object.entries(data.globalStyles)) globalStyles[selector] = resolveRefs(styles, tokenRef);

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

@@ -0,0 +1,94 @@
+import { StyleProp } from "@uds/types";
+
+//#region ../config/dist/types.d.ts
+//#region src/types.d.ts
+/**
+ * A single design token definition with a base value and optional modifier overrides.
+ * Modifier keys use the `_` prefix convention (e.g., `_dark`, `_hover`).
+ *
+ * When `M` is narrowed (e.g., `'_dark' | '_light'`), only those modifier keys are
+ * accepted — TypeScript will flag unknown modifiers like `_eggs` at compile time.
+ *
+ * @example
+ * { value: '#1167f4', _dark: '#88bcfb' }
+ */
+type VarTokenDef<M extends `_${string}` = `_${string}`> = {
+  value: string;
+} & { [K in M]?: string };
+/**
+ * A group of named tokens within a var namespace.
+ *
+ * @example
+ * { brand: { value: '#1167f4', _dark: '#88bcfb' }, accent: { value: '#7c3aed' } }
+ */
+type VarGroupDef<M extends `_${string}` = `_${string}`> = Record<string, VarTokenDef<M>>;
+/**
+ * Top-level vars config — namespaces to groups of tokens.
+ *
+ * @example
+ * {
+ *   color: { brand: { value: '#1167f4', _dark: '#88bcfb' } },
+ *   spacing: { 1: { value: '0.25rem' }, 2: { value: '0.5rem' } },
+ * }
+ */
+type VarsConfig<M extends `_${string}` = `_${string}`> = Record<string, VarGroupDef<M>>;
+/**
+ * A single utility definition mapping a style prop to CSS output.
+ *
+ * @example
+ * {
+ *   className: 'bg',
+ *   values: '{bg}',
+ *   transform(value) { return { 'background-color': value } },
+ * }
+ */
+interface UtilityDef {
+  /** Class name prefix for runtime generation. Empty string means value IS the class. */
+  className: string;
+  /**
+   * Reference to defineVars namespace(s). Tokens from referenced namespaces become allowed values.
+   *
+   * - Single: `'{namespace}'` — tokens from one namespace
+   * - Array: `['{ns1}', '{ns2}']` — tokens from multiple namespaces, last entry wins on name collision
+   *
+   * The namespace name determines the CSS custom property prefix (e.g., `'{color}'` → `--uds-color-*`).
+   */
+  values?: string | string[] | {
+    type: 'boolean';
+  };
+  /** Literal enum values (e.g., `['block', 'flex', 'grid']`). */
+  literalValues?: string[];
+  /** Transform a token/literal value into CSS property declarations.
+   *  Optional for Phase 0 — only needed by resolveUtilityMappings() to derive cssProperty. */
+  transform?: (value: string, ctx: {
+    token: (ref: string) => string;
+  }) => Record<string, string>;
+}
+/**
+ * Internal utilities config — used for resolved/stored data.
+ * Keys are plain strings so internal iteration (Object.entries, etc.) stays clean.
+ *
+ * @example
+ * {
+ *   bg: { className: 'bg', values: '{bg}', transform(v) { return { 'background-color': v } } },
+ *   display: { className: '', literalValues: ['block', 'flex'], transform(v) { return { display: v } } },
+ * }
+ */
+type UtilitiesConfig = Record<string, UtilityDef>;
+/**
+ * Input type for `defineUtilities()` — keys must be valid UDS style prop names (`StyleProp`).
+ *
+ * This is the public-facing constraint used by the builder method. It ensures callers
+ * only map props that exist in the UDS component style API. Unlike `UtilitiesConfig`
+ * (which uses `Record<string, ...>` for clean internal iteration), this type enforces
+ * named keys at the call site.
+ *
+ * @example
+ * {
+ *   color: { className: 'text', values: '{color}' },
+ *   bg: { className: 'bg', values: ['{color}', '{bg}'] },
+ *   display: { className: '', literalValues: ['block', 'flex', 'grid'] },
+ * }
+ */
+//#endregion
+export { UtilitiesConfig, UtilityDef, VarGroupDef, VarTokenDef, VarsConfig };