@yahoo/uds-v5-wip 1.24.0 → 1.25.0

package/dist/config/dist/component-resolution.d.ts

@@ -1 +1 @@
-import { ComponentsConfig } from "@uds/types";
+export { };

package/dist/config/dist/consts/defaultColors.d.ts

@@ -1,4 +1,5 @@
 //#region ../config/dist/consts/defaultColors.d.ts
+//#region src/consts/defaultColors.d.ts
 declare const defaultColors: {
   inherit: string;
   current: string;
@@ -247,6 +248,6 @@ declare const defaultColors: {
   'rose-800': string;
   'rose-900': string;
   'rose-950': string;
-};
+}; //#endregion
 //#endregion
 export { defaultColors };

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

@@ -1,16 +1,23 @@
 import { PropertyGroupId } from "./propertyGroups.js";
 import { TokenType, VarsConfig } from "./types.js";
-import { BaseModifierProp, ComponentsConfig, ConfigurableProp, MacroConfig, ModifierProp, MotionPreset, RemotionComponentDef, RemotionConfig, RemotionTransitionDef, StyleProp } from "@uds/types";
+import { BaseModifierProp, ComponentsConfig, CompositeStylesConfig, ConfigurableProp, ModifierProp, MotionPreset, RemotionComponentDef, RemotionConfig, RemotionTransitionDef, StyleProp } from "@uds/types";
 
 //#region ../config/dist/createConfig.d.ts
+//#region src/createConfig.d.ts
 type MotionPresetsDef = Record<string, MotionPreset>;
 type MotionAliasValue<TMotion> = TMotion extends Record<string, infer V> ? Extract<V, string> : never;
 type EmptyMotion = {};
-type EmptyMacros = {};
-/** Transform macro config type into the reference shape passed to defineModifiers */
-type MacroReference<T> = { [K in keyof T]: { [V in keyof T[K]]: {
+type EmptyCompositeStyles = {};
+/**
+ * Transform composite-styles config type into the reference shape passed to
+ * defineModifiers. Walks `T[K]['styles'][V]` so the modifier callback can
+ * write `compositeStyles.elevation['1'].className` (flat for ergonomics).
+ */
+type CompositeStylesReference<T> = { [K in keyof T]: T[K] extends {
+  styles: infer S;
+} ? { [V in keyof S]: {
   className: string;
-} } };
+} } : never };
 type ModifierNameShape = `_${string}`;
 /**
  * Check if a modifier overlaps with base reserved modifiers (not including custom ones)
@@ -70,6 +77,18 @@ interface AtomicToken<M extends ModifierNameShape = ModifierNameShape> {
    * generator.
    */
   description?: string;
+  /**
+   * Original `defineVars` namespace key, verbatim — e.g. `borderColor`,
+   * `spectrum`, `fontSize`. Distinct from {@link cssPrefix}, which is
+   * the kebab-cased form used in CSS-variable names. The Studio uses
+   * this to label tokens with the same identifier the author wrote in
+   * their config (`borderColor/accent`, not `border-color/accent`).
+   *
+   * Optional for backwards compatibility — older serialized configs
+   * predate the field; consumers should fall back to {@link cssPrefix}
+   * (kebab-cased) when this is absent.
+   */
+  namespace?: string;
   /**
    * Optional CSS variable prefix override
    *
@@ -113,6 +132,7 @@ type EmptyTokens = {};
 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 */
@@ -137,7 +157,7 @@ interface UdsConfigData {
   modes: ModeGroup[];
   modifiers: ModifierDef[];
   atomic: AtomicToken<ModifierNameShape>[];
-  macros: MacroConfig;
+  compositeStyles: CompositeStylesConfig;
   motion: MotionPresetsDef;
   components: ComponentsConfig<string>;
   globalStyles: GlobalStylesDef;
@@ -198,49 +218,49 @@ 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, 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> {
+type ConfigResult<TModifier extends ModifierNameShape, TTokens, TMotion, TExt extends Record<string, any> = {}, TCompositeStyles = EmptyCompositeStyles, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars> = UdsConfig<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars> & TExt;
+interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens = EmptyTokens, TMotion = EmptyMotion, TExt extends Record<string, any> = {}, TCompositeStyles = EmptyCompositeStyles, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars> {
   modes: ModeGroup[];
   atomic: AtomicToken<ModifierNameShape>[];
   components: ComponentsConfig;
-  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>;
+  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>;
   defineModifiers<const Defs extends readonly ModifierDef[]>(params: Defs | ((ctx: {
     tokens: TTokens;
-    macros: MacroReference<TMacros>;
-  }) => Defs)): ConfigResult<TModifier | Defs[number]['modifier'], TTokens, TMotion, TExt, TMacros, TModeModifiers | Defs[number]['modifier'], TVars>;
-  defineMacro<const M extends MacroConfig>(params: M | ((ctx: {
+    compositeStyles: CompositeStylesReference<TCompositeStyles>;
+  }) => Defs)): ConfigResult<TModifier | Defs[number]['modifier'], TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers | Defs[number]['modifier'], TVars>;
+  defineCompositeStyles<const M extends CompositeStylesConfig>(params: M | ((ctx: {
     tokens: TTokens;
-  }) => 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>;
+  }) => M)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles & M, TModeModifiers, TVars>;
+  defineArbitraryTokens(params: ArbitraryTokenGroup[]): 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;
     motion: TMotion;
     components: Record<string, any>;
-  }) => 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>;
+  }) => ComponentsConfig<MotionAliasValue<TMotion> | string>)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  defineGlobalStyles(params: GlobalStylesDef | ((tokens: TTokens) => GlobalStylesDef)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  defineDesignPrinciples(principles: string[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  defineExample(name: string, examples: ExampleDef): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  compose(...presets: (ComponentConfig | UdsConfig | Partial<UdsConfigData>)[]): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, 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, TModeModifiers, TVars>;
-  extend<const NewExt extends Record<string, any>>(ext: NewExt): ConfigResult<TModifier, TTokens, TMotion, TExt & NewExt, TMacros, TModeModifiers, TVars>;
+  from(data: Partial<UdsConfigData>): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  extend<const NewExt extends Record<string, any>>(ext: NewExt): ConfigResult<TModifier, TTokens, TMotion, TExt & NewExt, TCompositeStyles, TModeModifiers, TVars>;
   defineRemotionComponents(params: RemotionConfig | ((ctx: {
     tokens: TTokens;
     motion: TMotion;
     components: Record<string, any>;
-  }) => RemotionConfig)): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  }) => RemotionConfig)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, 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, TModeModifiers, TVars>;
-  defineVars<const TVarsNew extends VarsConfig<[TModeModifiers] extends [never] ? `_${string}` : TModeModifiers>>(vars: TVarsNew): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars & TVarsNew>;
+  }) => Record<string, RemotionTransitionDef>)): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
+  defineVars<const TVarsNew extends VarsConfig<[TModeModifiers] extends [never] ? `_${string}` : TModeModifiers>>(vars: TVarsNew): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars & TVarsNew>;
   /**
    * Map each ConfigurableProp to a CSS class prefix.
    * Falls back to kebab-case of the property name when not specified.
@@ -258,7 +278,7 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
    * })
    * ```
    */
-  defineClassNames(classNames: { [K in StyleProp]?: string }): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineClassNames(classNames: { [K in StyleProp]?: string }): ConfigResult<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
   /**
    * Map var namespaces to property groups, defining which tokens each property
    * group can reference. This is the canonical scope definition — the Studio UI
@@ -277,12 +297,16 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
    *   })
    * ```
    */
-  defineScopes(scopes: [keyof TVars] extends [never] ? Record<string, PropertyGroupId[]> : { [K in keyof TVars]?: PropertyGroupId[] }): ConfigResult<TModifier, MergeTokens<TTokens, VarsToTokens<TVars>>, TMotion, TExt, TMacros, TModeModifiers, TVars>;
+  defineScopes(scopes: [keyof TVars] extends [never] ? Record<string, PropertyGroupId[]> : { [K in keyof TVars]?: PropertyGroupId[] }): ConfigResult<TModifier, MergeTokens<TTokens, VarsToTokens<TVars>>, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars>;
 }
 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;
-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;
+/**
+ * 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> = {}, TCompositeStyles = EmptyCompositeStyles, TModeModifiers extends ModifierNameShape = never, TVars extends VarsConfig = EmptyVars>(data: UdsConfigData, extensions?: TExt): UdsConfig<TModifier, TTokens, TMotion, TExt, TCompositeStyles, TModeModifiers, TVars> & TExt;
 interface InterpolateMarker {
   __type: 'interpolate';
   output: number[];

package/dist/config/dist/createConfig.js

@@ -4,9 +4,9 @@ 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";
 //#region ../config/dist/createConfig.js
 /** biome-ignore-all lint/suspicious/noExplicitAny: necessary for dynamic builder to work correctly */
 /** Build a structured token reference object from atomic tokens */
@@ -31,16 +31,37 @@ function buildTokenReference(atomic, configPrefix) {
 	}
 	return result;
 }
-/** Build a structured macro reference object for use in defineModifiers context */
-function buildMacroReference(macros) {
+/** Build a structured composite-styles reference object for use in defineModifiers context */
+function buildCompositeStylesReference(compositeStyles) {
 	const result = {};
-	for (const [macroName, def] of Object.entries(macros)) {
-		result[macroName] = {};
-		for (const valueName of Object.keys(def)) result[macroName][valueName] = { className: `${macroName}-${safeTokenName(valueName)}` };
+	for (const [groupName, def] of Object.entries(compositeStyles)) {
+		result[groupName] = {};
+		for (const valueName of Object.keys(def.styles)) result[groupName][valueName] = { className: `${groupName}-${safeTokenName(valueName)}` };
 	}
 	return result;
 }
 /**
+* Migrate legacy `macros` JSON (the pre-rename shape) into the new
+* `compositeStyles` shape. Each old key (`elevation`) becomes a `{ label,
+* styles }` def so older serialized configs (in `uds.config.json`,
+* `draft_base_configs.baseConfig`) keep loading until they're rewritten.
+*
+* Returns `undefined` when no legacy data is present so callers can chain
+* a fallback (`?? {}`).
+*/
+function upgradeLegacyMacros(legacy) {
+	if (!legacy || typeof legacy !== "object") return void 0;
+	const out = {};
+	for (const [name, variants] of Object.entries(legacy)) {
+		if (!variants || typeof variants !== "object") continue;
+		out[name] = {
+			label: name,
+			styles: variants
+		};
+	}
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/**
 * Convert a VarGroupDef into AtomicToken tokens, extracting modifier overrides.
 *
 * Also extracts group-level metadata:
@@ -123,6 +144,7 @@ function synthesizeAtomicFromScopesAndVars(vars, scopes, modes) {
 		result.push({
 			properties: sorted,
 			tokens,
+			namespace,
 			cssPrefix: cssPfx,
 			...resolvedGroupType ? { type: resolvedGroupType } : {},
 			...groupDescription ? { description: groupDescription } : {}
@@ -197,7 +219,7 @@ function resolveConfig(config) {
 		modes: config.modes ?? [],
 		modifiers: config.modifiers ?? [],
 		atomic: config.atomic ?? [],
-		macros: config.macros ?? {},
+		compositeStyles: config.compositeStyles ?? upgradeLegacyMacros(config.macros) ?? {},
 		motion: config.motion ?? {},
 		components: config.components ?? {},
 		globalStyles: config.globalStyles ?? {},
@@ -247,7 +269,7 @@ function resolvePresetData(input) {
 		modes: [],
 		modifiers: [],
 		atomic: [],
-		macros: {},
+		compositeStyles: {},
 		motion: input.motion ?? {},
 		components: input.components,
 		globalStyles: {},
@@ -260,7 +282,7 @@ function resolvePresetData(input) {
 		modes: input.modes ?? [],
 		modifiers: input.modifiers ?? [],
 		atomic: input.atomic ?? [],
-		macros: input.macros ?? {},
+		compositeStyles: input.compositeStyles ?? {},
 		motion: input.motion ?? {},
 		components: input.components ?? {},
 		globalStyles: input.globalStyles ?? {},
@@ -372,27 +394,27 @@ function createConfigBuilder(data, extensions) {
 		defineModifiers(params) {
 			const resolved = typeof params === "function" ? params({
 				tokens: buildTokenReference(data.atomic, data.prefix),
-				macros: buildMacroReference(data.macros)
+				compositeStyles: buildCompositeStylesReference(data.compositeStyles)
 			}) : params;
 			return createConfigBuilder({
 				...data,
 				modifiers: [...data.modifiers, ...resolved]
 			}, extensions);
 		},
-		defineMacro(params) {
+		defineCompositeStyles(params) {
 			const tokenReference = buildTokenReference(data.atomic, data.prefix);
 			const resolved = typeof params === "function" ? params({ tokens: tokenReference }) : params;
-			const allMacros = {
-				...data.macros,
+			const allCompositeStyles = {
+				...data.compositeStyles,
 				...resolved
 			};
 			const edges = /* @__PURE__ */ new Map();
-			for (const [macroName, macroDef] of Object.entries(allMacros)) {
+			for (const [groupName, def] of Object.entries(allCompositeStyles)) {
 				const targets = /* @__PURE__ */ new Set();
-				for (const bag of Object.values(macroDef)) if (bag && typeof bag === "object") {
-					for (const key of Object.keys(bag)) if (key in allMacros) targets.add(key);
+				for (const bag of Object.values(def.styles)) if (bag && typeof bag === "object") {
+					for (const key of Object.keys(bag)) if (key in allCompositeStyles) targets.add(key);
 				}
-				if (targets.size > 0) edges.set(macroName, targets);
+				if (targets.size > 0) edges.set(groupName, targets);
 			}
 			const visited = /* @__PURE__ */ new Set();
 			const stack = /* @__PURE__ */ new Set();
@@ -400,7 +422,7 @@ function createConfigBuilder(data, extensions) {
 			function dfs(node) {
 				if (stack.has(node)) {
 					const cycleStart = path.indexOf(node);
-					throw new Error(`Circular macro reference: ${[...path.slice(cycleStart), node].join(" → ")}`);
+					throw new Error(`Circular composite style reference: ${[...path.slice(cycleStart), node].join(" → ")}`);
 				}
 				if (visited.has(node)) return;
 				visited.add(node);
@@ -414,8 +436,8 @@ function createConfigBuilder(data, extensions) {
 			for (const node of edges.keys()) dfs(node);
 			return createConfigBuilder({
 				...data,
-				macros: {
-					...data.macros,
+				compositeStyles: {
+					...data.compositeStyles,
 					...resolved
 				}
 			}, extensions);
@@ -509,7 +531,7 @@ function createConfigBuilder(data, extensions) {
 				modes: input.modes ?? data.modes,
 				modifiers: input.modifiers ?? data.modifiers,
 				atomic: input.atomic ?? data.atomic,
-				macros: input.macros ?? data.macros,
+				compositeStyles: input.compositeStyles ?? data.compositeStyles,
 				motion: input.motion ?? data.motion,
 				components: input.components ?? data.components,
 				globalStyles: input.globalStyles ?? data.globalStyles,
@@ -656,7 +678,7 @@ const uds = createConfigBuilder({
 	atomic: [],
 	modes: [],
 	modifiers: [],
-	macros: {},
+	compositeStyles: {},
 	motion: {},
 	components: {},
 	globalStyles: {},
@@ -665,4 +687,4 @@ const uds = createConfigBuilder({
 	remotion: void 0
 });
 //#endregion
-export { buildMacroReference, buildTokenReference, createConfigBuilder, darker, interpolate, lighter, rem, resolveConfig, uds };
+export { buildCompositeStylesReference, buildTokenReference, createConfigBuilder, darker, interpolate, lighter, rem, resolveConfig, uds };

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

@@ -14,6 +14,7 @@ function flattenAtomic(atomic) {
 	for (const group of atomic) for (const property of group.properties) for (const token of group.tokens) entries.push({
 		property,
 		cssPrefix: group.cssPrefix,
+		namespace: group.namespace,
 		groupType: group.type,
 		groupDescription: group.description,
 		token
@@ -47,6 +48,7 @@ function mergeAtomic(base, incoming, mode) {
 		}
 		regrouped.set(groupKey, {
 			properties: [entry.property],
+			...entry.namespace ? { namespace: entry.namespace } : {},
 			...entry.cssPrefix ? { cssPrefix: entry.cssPrefix } : {},
 			...entry.groupType ? { type: entry.groupType } : {},
 			...entry.groupDescription ? { description: entry.groupDescription } : {},
@@ -161,9 +163,9 @@ function applyPresetToData(base, preset, strategy) {
 		modes: mergeModes(base.modes, preset.modes, s.modes),
 		modifiers: mergeModifiers(base.modifiers, preset.modifiers, s.modifiers),
 		atomic: mergeAtomic(base.atomic, preset.atomic, s.tokens),
-		macros: {
-			...base.macros,
-			...preset.macros
+		compositeStyles: {
+			...base.compositeStyles,
+			...preset.compositeStyles
 		},
 		motion: mergeRecordByKey(base.motion, preset.motion, s.motion),
 		components: mergeRecordByKey(base.components, preset.components, s.components),

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

@@ -1,6 +1,11 @@
 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 };

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

@@ -1,6 +1,8 @@
 import { ArbitraryTokenGroup, 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;
@@ -9,6 +11,12 @@ interface SerializedConfig {
   modes: ModeGroup[];
   modifiers?: ModifierDef[];
   atomic: AtomicToken<ModifierNameShape>[];
+  compositeStyles?: CompositeStylesConfig;
+  /**
+   * Legacy field name. Kept on the wire format so older serialized configs
+   * (and `draft_base_configs.baseConfig` blobs) continue to deserialize
+   * until they're rewritten. New code should populate `compositeStyles`.
+   */
   macros?: Record<string, Record<string, Record<string, unknown>>>;
   arbitraryTokens?: ArbitraryTokenGroup[];
   motion?: MotionPresetsDef;
@@ -52,6 +60,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;
+declare function deserializeConfig(data: SerializedConfig): UdsConfig; //#endregion
 //#endregion
 export { SerializedConfig, TokenRef, buildReverseMap, deserializeConfig, serializeConfig };

package/dist/config/dist/serialize.js

@@ -10,6 +10,21 @@ import { buildTokenReference, createConfigBuilder, resolveConfig } from "./creat
 * serializeConfig:   UdsConfig → SerializedConfig  (var() → $ref markers)
 * deserializeConfig: SerializedConfig → UdsConfig   ($ref markers → var())
 */
+/**
+* Migrate the legacy serialized `macros` field into the new
+* `compositeStyles` shape. Each old key (`elevation`) becomes a
+* `{ label, styles }` def. Returns an empty object when there's
+* nothing to migrate so the field is always populated.
+*/
+function upgradeLegacyMacros(legacy) {
+	if (!legacy) return {};
+	const out = {};
+	for (const [name, variants] of Object.entries(legacy)) out[name] = {
+		label: name,
+		styles: variants
+	};
+	return out;
+}
 function isTokenRef(val) {
 	return typeof val === "object" && val !== null && "$ref" in val && typeof val.$ref === "string";
 }
@@ -93,7 +108,7 @@ function serializeConfig(config) {
 		modes: data.modes,
 		modifiers: data.modifiers.length > 0 ? data.modifiers : void 0,
 		atomic: data.atomic,
-		macros: Object.keys(data.macros).length > 0 ? data.macros : void 0,
+		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,
@@ -136,7 +151,7 @@ function deserializeConfig(data) {
 		modes: data.modes,
 		modifiers: data.modifiers ?? [],
 		atomic: data.atomic,
-		macros: data.macros ?? {},
+		compositeStyles: data.compositeStyles ?? upgradeLegacyMacros(data.macros),
 		motion: data.motion ?? {},
 		components,
 		preflight: data.preflight,

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

@@ -1,4 +1,5 @@
 //#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
@@ -59,6 +60,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>>;
+type VarsConfig<M extends `_${string}` = `_${string}`> = Record<string, VarGroupDef<M>>; //#endregion
 //#endregion
 export { TokenType, VarGroupDef, VarTokenDef, VarsConfig };