@yahoo/uds-v5-wip 1.13.0 → 1.15.0

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

@@ -1,4 +1,5 @@
-import { UtilitiesConfig, UtilityDef, VarsConfig } from "./types.js";
+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";
 
 //#region ../config/dist/createConfig.d.ts
@@ -47,11 +48,23 @@ interface ArbitraryTokenGroup {
 type AtomicTokenValue<M extends ModifierNameShape> = {
   name: string;
   value: string;
+  /**
+   * Resolved DTCG-aligned token type. Populated per-token only when the
+   * token overrides the group-level `type` (e.g. a `'string'`-typed
+   * `transparent` sitting inside a `'color'` namespace).
+   */
+  type?: TokenType;
   modifiers?: Partial<Record<M, string>>;
 };
 interface AtomicToken<M extends ModifierNameShape = ModifierNameShape> {
   properties: ConfigurableProp[];
   tokens: AtomicTokenValue<M>[];
+  /**
+   * Resolved DTCG-aligned token type for the whole group. Set from
+   * `$type` on `defineVars`, or inferred from `defineScopes` / value sniff
+   * during config resolution.
+   */
+  type?: TokenType;
   /**
    * Optional CSS variable prefix override
    *
@@ -76,29 +89,19 @@ interface AtomicToken<M extends ModifierNameShape = ModifierNameShape> {
 /** 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>`.
+ * Derive token types directly from defineVars namespaces.
+ * Each var namespace key becomes a token property with the namespace's token names.
+ * An index signature allows property-name access (e.g., `tokens.borderRadius`)
+ * in addition to var-namespace access (e.g., `tokens.radius`).
+ * Used by `defineScopes` to populate tokens without an explicit utility mapping.
  */
-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> };
+type VarsToTokens<TVars extends VarsConfig> = { [K in keyof TVars]: { [T in Exclude<keyof TVars[K], '$type'>]: string } } & Record<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>>;
+declare function buildTokenReference(atomic: AtomicToken<ModifierNameShape>[], configPrefix: string): Record<string, Record<string, string>>;
 /** Build a structured macro 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;
@@ -136,7 +139,18 @@ interface UdsConfigData {
   examples?: Record<string, ExampleDef>;
   designPrinciples?: string[];
   vars?: VarsConfig;
-  utilities?: UtilitiesConfig;
+  /**
+   * Map each ConfigurableProp to its generated CSS class prefix.
+   * Set via `defineClassNames()`. Falls back to kebab-case of the property name.
+   */
+  classNames?: Record<string, string>;
+  /**
+   * Map each var namespace to the property group IDs it feeds.
+   * Set via `defineScopes()`. This is the canonical source for
+   * "which tokens can this property use" — the Studio UI reads and
+   * edits this via draft patches.
+   */
+  scopes?: Record<string, string[]>;
 }
 interface ComponentConfig<TComponents extends ComponentsConfig<string> = ComponentsConfig<string>, TMotion extends MotionPresetsDef | undefined = MotionPresetsDef | undefined> {
   name?: string;
@@ -205,7 +219,43 @@ interface UdsConfig<TModifier extends ModifierNameShape = ModifierProp, TTokens
     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>;
-  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>;
+  /**
+   * Map each ConfigurableProp to a CSS class prefix.
+   * Falls back to kebab-case of the property name when not specified.
+   * Typically called once by the foundational preset — consumers rarely touch this.
+   *
+   * @example
+   * ```ts
+   * uds.defineClassNames({
+   *   color: 'text',
+   *   bg: 'bg',
+   *   borderColor: 'border-color',
+   *   spacing: 'p',
+   *   gap: 'gap',
+   *   borderRadius: 'rounded',
+   * })
+   * ```
+   */
+  defineClassNames(classNames: { [K in StyleProp]?: string }): ConfigResult<TModifier, TTokens, TMotion, TExt, TMacros, 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
+   * renders it as checkboxes per token group.
+   *
+   * @example
+   * ```ts
+   * uds
+   *   .defineVars({
+   *     color: { brand: { value: '#1167f4' } },
+   *     spacing: { sm: { value: '4px' } },
+   *   })
+   *   .defineScopes({
+   *     color: ['textColor', 'background', 'borderColor', 'ringColor'],
+   *     spacing: ['padding', 'gap', 'margin'],
+   *   })
+   * ```
+   */
+  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>;
 }
 type AnyUdsConfig = UdsConfig<ModifierNameShape, any, any, any, any, any, any>;
 /** Extract the raw config data from a builder instance */

package/dist/config/dist/createConfig.js

@@ -4,19 +4,29 @@ 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 { 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 */
 function buildTokenReference(atomic, configPrefix) {
 	const result = Object.create(null);
-	for (const token of atomic) for (const prop of token.properties) {
-		if (!result[prop]) result[prop] = Object.create(null);
+	for (const token of atomic) {
+		const varPrefix = token.cssPrefix ?? getConfigurablePropMapping(token.properties[0])?.defaultVarPrefix;
+		const tokenEntries = Object.create(null);
 		for (const t of token.tokens) {
-			const varPrefix = token.cssPrefix ?? getConfigurablePropMapping(prop)?.defaultVarPrefix;
 			const safeName = safeTokenName(t.name);
 			const cssVarName = configPrefix ? `--${configPrefix}-${varPrefix}-${safeName}` : `--${varPrefix}-${safeName}`;
-			result[prop][t.name] = `var(${cssVarName})`;
+			tokenEntries[t.name] = `var(${cssVarName})`;
+		}
+		for (const prop of token.properties) {
+			if (!result[prop]) result[prop] = Object.create(null);
+			Object.assign(result[prop], tokenEntries);
+		}
+		if (varPrefix) {
+			if (!result[varPrefix]) result[varPrefix] = Object.create(null);
+			Object.assign(result[varPrefix], tokenEntries);
 		}
 	}
 	return result;
@@ -31,84 +41,142 @@ function buildMacroReference(macros) {
 	return result;
 }
 /**
-* Parse a `'{namespace}'` reference string, returning the namespace name
-* or `undefined` if the string is not a valid reference.
+* Convert a VarGroupDef into AtomicToken tokens, extracting modifier overrides.
+*
+* Also extracts `$type` metadata:
+* - A top-level `$type` on the group → `groupType`
+* - A `$type` on an individual token → `type` on that token (overrides group)
+*
+* `$type` is filtered out of the emitted tokens; it is metadata only.
 */
-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) {
+	let groupType;
 	const tokens = [];
-	for (const [tokenName, tokenDef] of Object.entries(varGroup)) {
+	for (const [tokenName, rawDef] of Object.entries(varGroup)) {
+		if (tokenName === "$type") {
+			if (typeof rawDef === "string") groupType = rawDef;
+			continue;
+		}
+		if (rawDef == null || typeof rawDef !== "object") continue;
+		const tokenDef = rawDef;
 		const modifiers = {};
 		for (const [key, val] of Object.entries(tokenDef)) {
-			if (key === "value" || val === void 0) continue;
+			if (key === "value" || key === "$type" || val === void 0) continue;
 			if (key.startsWith("_") && knownModifiers.has(key)) modifiers[key] = val;
 		}
 		tokens.push({
 			name: tokenName,
 			value: tokenDef.value,
+			...tokenDef.$type ? { type: tokenDef.$type } : {},
 			...Object.keys(modifiers).length > 0 ? { modifiers } : {}
 		});
 	}
-	return tokens;
+	return {
+		tokens,
+		groupType
+	};
 }
 /**
-* 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.
+* Sort properties so the one matching the cssPrefix comes last.
+* `buildVarToTokenMap` uses "last wins", so this ensures e.g. `color.brand`
+* beats `shadowColor.brand` when both reference `var(--uds-color-brand)`.
+*/
+function sortPropertiesByPrefixMatch(properties, namespace, cssPfx) {
+	return properties.slice().sort((a, b) => {
+		return (a === namespace || kebabCase(a) === cssPfx ? 1 : 0) - (b === namespace || kebabCase(b) === cssPfx ? 1 : 0);
+	});
+}
+/**
+* Synthesize AtomicToken[] from defineScopes + defineVars data.
 *
-* 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).
+* For each namespace in `scopes`, expands property group IDs into
+* ConfigurableProps, extracts tokens from the matching var namespace,
+* and produces an AtomicToken group.
 */
-function synthesizeAtomicFromVarsAndUtilities(vars, utilities, modes) {
+function synthesizeAtomicFromScopesAndVars(vars, scopes, 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) {
+	for (const [namespace, groupIds] of Object.entries(scopes)) {
 		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);
+		const properties = expandPropertyGroups(groupIds);
+		if (properties.length === 0) continue;
+		const { tokens, groupType } = varGroupToTokens(varGroup, knownModifiers);
+		const cssPfx = (properties.includes(namespace) ? getConfigurablePropMapping(namespace) : void 0)?.defaultVarPrefix ?? kebabCase(namespace);
+		const sorted = sortPropertiesByPrefixMatch(properties, namespace, cssPfx);
+		const resolvedGroupType = resolveTokenType({
+			explicit: groupType,
+			scopes: groupIds
 		});
+		if (resolvedGroupType && resolvedGroupType !== "string") for (const token of tokens) {
+			if (token.type) continue;
+			if (sniffTokenTypeFromValue(token.value) === "string") token.type = "string";
+		}
 		result.push({
-			properties,
+			properties: sorted,
 			tokens,
-			cssPrefix: cssPfx
+			cssPrefix: cssPfx,
+			...resolvedGroupType ? { type: resolvedGroupType } : {}
+		});
+	}
+	return disambiguateOverlappingProperties(result, scopes);
+}
+/**
+* When multiple scope namespaces reference the **same** property group
+* (e.g. `rotate`, `scale`, `skew`, `translate` all mapping to `['transform']`),
+* each namespace's AtomicToken gets ALL properties from that group, causing
+* last-write-wins collisions in CSS generation.
+*
+* This function partitions those shared-group properties among namespaces
+* using longest camelCase prefix matching. Cross-group overlaps (e.g.
+* `color` and `bg` both including the `bg` property via different groups)
+* are intentional cascading and left untouched.
+*/
+function disambiguateOverlappingProperties(tokens, scopes) {
+	const groupToNamespaces = /* @__PURE__ */ new Map();
+	for (const [ns, groupIds] of Object.entries(scopes)) for (const gid of groupIds) {
+		const list = groupToNamespaces.get(gid) ?? [];
+		list.push(ns);
+		groupToNamespaces.set(gid, list);
+	}
+	const contestedGroups = /* @__PURE__ */ new Map();
+	for (const [gid, nsList] of groupToNamespaces) if (nsList.length > 1) contestedGroups.set(gid, nsList);
+	if (contestedGroups.size === 0) return tokens;
+	const propOwner = /* @__PURE__ */ new Map();
+	for (const [gid, nsList] of contestedGroups) {
+		const groupProps = expandPropertyGroups([gid]);
+		const assignments = /* @__PURE__ */ new Map();
+		const nsWithMatch = /* @__PURE__ */ new Set();
+		for (const prop of groupProps) {
+			let bestNs = "";
+			let bestLen = 0;
+			for (const ns of nsList) if (prop === ns || prop.startsWith(ns) && prop.length > ns.length) {
+				if (ns.length > bestLen) {
+					bestNs = ns;
+					bestLen = ns.length;
+				}
+			}
+			if (bestNs) {
+				assignments.set(prop, bestNs);
+				nsWithMatch.add(bestNs);
+			}
+		}
+		if (nsWithMatch.size < 2) continue;
+		for (const [prop, ns] of assignments) propOwner.set(prop, ns);
+	}
+	if (propOwner.size === 0) return tokens;
+	const namespaces = Object.keys(scopes);
+	const result = [];
+	for (const token of tokens) {
+		const ns = namespaces.find((n) => token.cssPrefix === kebabCase(n)) ?? "";
+		const filtered = token.properties.filter((prop) => {
+			const owner = propOwner.get(prop);
+			return !owner || owner === ns;
+		});
+		if (filtered.length > 0) result.push({
+			...token,
+			properties: filtered
 		});
 	}
 	return result;
@@ -133,13 +201,15 @@ function resolveConfig(config) {
 		examples: config.examples,
 		designPrinciples: config.designPrinciples,
 		vars: config.vars,
-		utilities: config.utilities
+		classNames: config.classNames,
+		scopes: config.scopes
 	};
-	if (configData.vars && configData.utilities) {
-		const synthesized = synthesizeAtomicFromVarsAndUtilities(configData.vars, configData.utilities, configData.modes);
+	if (configData.vars && configData.scopes) {
+		const synthesized = synthesizeAtomicFromScopesAndVars(configData.vars, configData.scopes, configData.modes);
+		const atomic = mergeAtomic(configData.atomic, synthesized, "merge");
 		configData = {
 			...configData,
-			atomic: mergeAtomic(configData.atomic, synthesized, "merge")
+			atomic
 		};
 	}
 	return configData;
@@ -192,7 +262,8 @@ function resolvePresetData(input) {
 		examples: input.examples,
 		designPrinciples: input.designPrinciples,
 		vars: input.vars,
-		utilities: input.utilities
+		classNames: input.classNames,
+		scopes: input.scopes
 	};
 }
 function extractVarReferences(value) {
@@ -230,7 +301,10 @@ function collectRequiredTokens(sourceData, components, motion) {
 }
 function availableTokenNames(data) {
 	const names = /* @__PURE__ */ new Set();
-	for (const group of data.atomic) for (const prop of group.properties) for (const token of group.tokens) names.add(`${prop}.${token.name}`);
+	for (const group of data.atomic) for (const token of group.tokens) {
+		for (const prop of group.properties) names.add(`${prop}.${token.name}`);
+		if (group.cssPrefix) names.add(`${group.cssPrefix}.${token.name}`);
+	}
 	return names;
 }
 function validatePresetRequiredTokens(base, preset) {
@@ -434,8 +508,7 @@ function createConfigBuilder(data, extensions) {
 				arbitraryTokens: input.arbitraryTokens ?? data.arbitraryTokens,
 				examples: input.examples ?? data.examples,
 				designPrinciples: input.designPrinciples ?? data.designPrinciples,
-				vars: input.vars ?? data.vars,
-				utilities: input.utilities ?? data.utilities
+				vars: input.vars ?? data.vars
 			}, extensions);
 		},
 		extend(ext) {
@@ -515,8 +588,8 @@ function createConfigBuilder(data, extensions) {
 				...group
 			};
 			const updates = { vars: merged };
-			if (data.utilities && Object.keys(data.utilities).length > 0) {
-				const synthesized = synthesizeAtomicFromVarsAndUtilities(merged, data.utilities, data.modes ?? []);
+			if (data.scopes && Object.keys(data.scopes).length > 0) {
+				const synthesized = synthesizeAtomicFromScopesAndVars(merged, data.scopes, data.modes ?? []);
 				updates.atomic = mergeAtomic(data.atomic, synthesized, "merge");
 			}
 			return createConfigBuilder({
@@ -524,14 +597,20 @@ function createConfigBuilder(data, extensions) {
 				...updates
 			}, extensions);
 		},
-		defineUtilities(utilities) {
-			const merged = {
-				...data.utilities,
-				...utilities
+		defineClassNames(classNames) {
+			return next({ classNames: {
+				...data.classNames,
+				...classNames
+			} });
+		},
+		defineScopes(scopes) {
+			const mergedScopes = {
+				...data.scopes,
+				...scopes
 			};
-			const updates = { utilities: merged };
+			const updates = { scopes: mergedScopes };
 			if (data.vars && Object.keys(data.vars).length > 0) {
-				const synthesized = synthesizeAtomicFromVarsAndUtilities(data.vars, merged, data.modes ?? []);
+				const synthesized = synthesizeAtomicFromScopesAndVars(data.vars, mergedScopes, data.modes ?? []);
 				updates.atomic = mergeAtomic(data.atomic ?? [], synthesized, "merge");
 			}
 			return createConfigBuilder({

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

@@ -1,7 +1,7 @@
 import { defaultColors } from "./consts/defaultColors.js";
-import { UtilitiesConfig, UtilityDef, VarGroupDef, VarTokenDef, VarsConfig } from "./types.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 { 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,5 +1,6 @@
 import "./consts/defaultColors.js";
 import "./component-resolution.js";
+import "./propertyGroups.js";
+import "./resolveTokenTypes.js";
 import "./createConfig.js";
-import "./resolvedMappings.js";
 import "./serialize.js";

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,
+		groupType: group.type,
 		token
 	});
 	return entries;
@@ -39,11 +40,13 @@ function mergeAtomic(base, incoming, mode) {
 		const existing = regrouped.get(groupKey);
 		if (existing) {
 			existing.tokens.push(entry.token);
+			if (entry.groupType) existing.type = entry.groupType;
 			continue;
 		}
 		regrouped.set(groupKey, {
 			properties: [entry.property],
 			...entry.cssPrefix ? { cssPrefix: entry.cssPrefix } : {},
+			...entry.groupType ? { type: entry.groupType } : {},
 			tokens: [entry.token]
 		});
 	}
@@ -142,9 +145,13 @@ function applyPresetToData(base, preset, strategy) {
 	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
+	const mergedClassNames = base.classNames || preset.classNames ? {
+		...base.classNames,
+		...preset.classNames
+	} : void 0;
+	const mergedScopes = base.scopes || preset.scopes ? {
+		...base.scopes,
+		...preset.scopes
 	} : void 0;
 	const merged = {
 		...base,
@@ -163,7 +170,8 @@ function applyPresetToData(base, preset, strategy) {
 		examples: mergedExamples,
 		designPrinciples: mergedPrinciples,
 		vars: mergedVars,
-		utilities: mergedUtilities
+		classNames: mergedClassNames,
+		scopes: mergedScopes
 	};
 	validateComponentVariants(merged.components);
 	return merged;

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

@@ -0,0 +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 };