@yahoo/uds 3.156.2 → 3.157.1

package/dist/automated-config/dist/utils/index.js

@@ -2,21 +2,31 @@
 import { BUTTON_GAP_VAR, BUTTON_SCALE_EFFECT_HOVER, BUTTON_SCALE_EFFECT_PRESSED, BUTTON_SCALE_EFFECT_REST } from "../../../css-tokens/dist/index.js";
 import { mapTextVariantFixtureToValue } from "../mapTextVariantFixtureToValue.js";
 import { configurableProperties } from "../properties.js";
-import { filterPseudoStatesByExclusion, getExcludedPseudoStatesForComponentStateOption } from "./componentStatePseudoStates.js";
+import { INTERACTIVE_ATOMICS, MODIFIER_ATOMICS, comparePriority } from "../types/StateAxis.js";
+import { getExcludedPseudoStatesForComponentStateOption } from "./componentStatePseudoStates.js";
 import { generateSchemaKey } from "./generateSchemaKey.js";
+import "./canonicalizeStateKey.js";
+import { atomicAndCompoundStateKeys, resolvePropertyStates } from "./resolvePropertyStates.js";
 import { isVariantConfigWithComponentStates, isVariantConfigWithProperties } from "./variantConfigGuards.js";
 import { findFixtureTypeForValue } from "./buildConfigSchema.js";
 import { generateDefaultClassName } from "./generateDefaultClassName.js";
+import { applyButtonControlHeightDeclarations, applyIconButtonControlHeightDeclarations, getButtonContentLineHeight } from "./getButtonControlHeight.js";
+import "./iconButtonMatchButtonHeight.js";
+import "./getButtonControlHeightPx.js";
+import { getStateDocsClass, getStateSelector } from "./pseudoStateSelectors.js";
+import { resolveSlotByCascade } from "./resolveSlotByCascade.js";
 import "./cartesianProduct.js";
 import "./subcomponents.js";
 import "./coalesceConfigVariant.js";
 import "./defaults.js";
 import "./generateKeyFromFlatConfigPath.js";
+import "./getConfigComponentVariant.js";
 import "./getConfigVariantComponentStatesMatrix.js";
 import "./getConfigVariantProperties.js";
 import "./getConfigVariantPseudoStates.js";
 import "./getConfigVariants.js";
 import "./getPaginationControlWidthPx.js";
+import "./isConfiguratorPropertyVisible.js";
 import { isFunction, mergeWith } from "lodash-es";
 //#region ../automated-config/dist/utils/index.js
 /*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
@@ -70,47 +80,59 @@ const COMPONENTS_WITH_SHADOW_BORDERS = [
 	}
 ];
 /**
-* Map our "states" to pseudo-classes (hover => :hover, pressed => :active, etc.).
-* Adjust or extend as needed.
+* Legacy state keys still used by unmigrated component configs via per-property
+* `pseudoStates` arrays. They aren't in the new `StateAxis` taxonomy (so the
+* resolver/StateBuilder don't auto-compose them) but they must remain in
+* `KNOWN_STATE_KEYS` so the docs-mode map / configurator safelist still cover
+* configs that emit them. Drop entries from this list as components migrate.
 */
-const statePseudoMap = {
-	rest: "",
-	hover: ":hover:not(:active, :disabled, :has(:disabled))",
-	pressed: ":active:not(:disabled, :has(:disabled))",
-	disabled: ":is(:disabled, :has(:disabled))",
-	visited: ":visited",
-	focused: ":focus",
-	"focus-within": ":focus-within",
-	"focused-keyboard": ":focus-visible",
-	readonly: ":has(input:read-only)",
-	invalid: ":has(input[aria-invalid=\"true\"])",
-	"invalid&hover": ":has(input[aria-invalid=\"true\"]):hover:not(:active, :disabled, :has(:disabled))",
-	"invalid&pressed": ":has(input[aria-invalid=\"true\"]):active:not(:disabled, :has(:disabled))"
-};
-const statePseudoMapDocsMode = {
-	rest: "",
-	hover: "hover",
-	pressed: "active",
-	disabled: "has-disabled",
-	visited: "visited",
-	focused: "focus",
-	"focus-within": "focus-within",
-	"focused-keyboard": "focus-visible",
-	readonly: "input-readonly",
-	invalid: "has-input-invalid",
-	"invalid&hover": "has-input-invalid-and-hover",
-	"invalid&pressed": "has-input-invalid-and-active"
-};
+const LEGACY_STATE_KEYS = [
+	"disabled",
+	"focused",
+	"focused-keyboard"
+];
 /**
-* Generates button line-height with icon size minimum.
-* Ensures button line-height is at least as tall as the icon to prevent clipping.
-* @returns Enhanced line-height CSS value with max(), or original value if icon size unavailable
+* Enumerates every canonical state key the system supports: rest, every atom,
+* every modifier-subset (up to {@link MAX_MODIFIERS_PER_COMPOUND}) on its own
+* and combined with each interactive, plus any legacy keys still in use.
+*
+* Mirrors `resolvePropertyStates` exactly so what the resolver pre-emits in
+* the schema, what the StateBuilder lets users compose, and what the docs
+* map / configurator safelist preserve are all the same set.
 */
-function getButtonLineHeightWithIconMinimum({ lineHeight, schema, iconLayerKey, state, theme }) {
-	const iconSizeValue = schema.variables?.[iconLayerKey]?.size?.[state]?.value;
-	if (iconSizeValue) return `max(${lineHeight}, ${theme(configurableProperties.iconSize.twThemePath("iconSizes", iconSizeValue))})`;
-	return lineHeight;
+function enumerateAllStateKeys() {
+	const states = ["rest"];
+	const atoms = [...INTERACTIVE_ATOMICS, ...MODIFIER_ATOMICS].sort(comparePriority);
+	for (const stateKey of atomicAndCompoundStateKeys(atoms)) states.push(stateKey);
+	for (const legacy of LEGACY_STATE_KEYS) states.push(legacy);
+	return states;
+}
+const KNOWN_STATE_KEYS = enumerateAllStateKeys();
+/**
+* Lookup of every known state key to its index in `KNOWN_STATE_KEYS` — i.e. the
+* resolver's emission order. The CSS generator iterates property-state maps
+* in this order (instead of the alphabetical insertion order produced by
+* `syncYosConfig`'s `normalizeConfig`), so cascade tie-breaking under the
+* uniform per-atom specificity actually follows the priority chain. Unknown
+* keys sort to the end.
+*/
+const KNOWN_STATE_RANK = new Map(KNOWN_STATE_KEYS.map((key, index) => [key, index]));
+function compareStateKeys(a, b) {
+	const ra = KNOWN_STATE_RANK.get(a) ?? Number.POSITIVE_INFINITY;
+	const rb = KNOWN_STATE_RANK.get(b) ?? Number.POSITIVE_INFINITY;
+	if (ra === rb) return a < b ? -1 : a > b ? 1 : 0;
+	return ra - rb;
+}
+function buildStateRecord(transform) {
+	const record = {};
+	for (const key of KNOWN_STATE_KEYS) record[key] = transform(key);
+	return record;
 }
+const statePseudoMapDocsMode = buildStateRecord(getStateDocsClass);
+/**
+* Layout line-height for button root: icon size only (not textVariant line-height).
+* @see getButtonContentLineHeight
+*/
 /**
 * Shared pagination control content size: max(icon size, text line-height).
 * Keeps page numbers and prev/next icons vertically centered when typography exceeds icon height.
@@ -243,7 +265,65 @@ const getTheCssPropertyValue = (schema, theme, propertyName, schemaStateValue, e
 	if (propertyConfig.concatenate && existingValue) return `${existingValue}${propertyConfig.concatenationDelimiter || ", "}${newValue}`;
 	return newValue;
 };
-function generateDeclaration({ componentName, subComponentName, variantKey, variantValue, layer, layerOptionalPseudoSelector, componentStateKey, componentStateValue, schema, propertyKey, originalPropertyDefinition, theme, currentStyles, previewOptions, excludedPseudoStates = [] }) {
+/**
+* Builds the per-state resolution map for a per-componentState OVERRIDE in
+* exhaustive mode: the universal layer's state map with the override's ENABLED
+* (and `rest`) slots layered on top. An unset or disabled override slot defers
+* to the universal layer's value, so `resolveSlotByCascade` picks the
+* most-specific *enabled* slot across both layers (override winning ties) rather
+* than collapsing every unset state to the override's own `rest`.
+*/
+function mergeUniversalUnderOverride(universal, override) {
+	const merged = { ...universal };
+	const overrideRecord = override;
+	for (const state of Object.keys(overrideRecord)) {
+		const slot = overrideRecord[state];
+		if (state === "rest" && slot?.isEnabled !== false || slot?.isEnabled === true) merged[state] = slot;
+	}
+	return merged;
+}
+/**
+* Replays SELECTIVE emission for a STANDALONE atomicStates layer (no universal
+* fallback) and returns the sparse set of slots it would emit: `rest`, every
+* explicitly-enabled state, and every cascade-correction. Mirrors the inline
+* selective decision in `generateDeclaration` — keep the two in lock-step.
+*
+* The override path seeds its own correction accumulator with this for the
+* UNIVERSAL layer. Universal layers are emitted in a separate pass at the SAME
+* specificity tier as their per-option overrides (see `bumpRootSpecificity`), so
+* at runtime a universal rule wins wherever the override emits nothing. Without
+* this seed, an override that flattens a state to `rest` (e.g. a `filled` help
+* text that's `muted` everywhere) silently inherits the universal's brighter
+* rule for that state in selective mode — a divergence from exhaustive, where
+* the override emits every state explicitly. Seeding makes the override emit a
+* correction whenever the universal would otherwise render a different value.
+*/
+function selectiveEmittedStates(stateMap, orderedStateKeys, emittableStates) {
+	const emitted = { rest: stateMap.rest };
+	for (const stateKey of orderedStateKeys) {
+		if (stateKey === "rest" || !emittableStates.has(stateKey)) continue;
+		const value = resolveSlotByCascade(stateKey, stateMap);
+		if (!value) continue;
+		if (!(stateMap[stateKey]?.isEnabled === true)) {
+			if (resolveSlotByCascade(stateKey, emitted)?.value === value.value) continue;
+		}
+		emitted[stateKey] = {
+			...value,
+			isEnabled: true
+		};
+	}
+	return emitted;
+}
+function generateDeclaration({ componentName, subComponentName, variantKey, variantValue, layer, layerOptionalPseudoSelector, componentStateKey, componentStateValue, schema, propertyKey, originalPropertyDefinition, declaredStates, layerUsesAtomicStates, theme, currentStyles, previewOptions, excludedPseudoStates = [], emit, fallbackStateMap, bumpRootSpecificity, buttonHeightReferenceSchema }) {
+	const shouldUseExhaustive = (emit ?? "exhaustive") === "exhaustive" && layerUsesAtomicStates;
+	const { cssProperties: configuredCssProperties, extendedProperties: configuredExtendedGetter } = configurableProperties[originalPropertyDefinition.name];
+	const configuredExtendedProperties = isFunction(configuredExtendedGetter) ? configuredExtendedGetter({
+		componentName,
+		subComponentName,
+		layer,
+		propertyKey
+	}) : configuredExtendedGetter;
+	if (!(typeof configuredCssProperties === "string" && configuredCssProperties.length > 0 || Array.isArray(configuredCssProperties) && configuredCssProperties.length > 0 || Array.isArray(configuredExtendedProperties) && configuredExtendedProperties.length > 0)) return {};
 	const schemaKey = generateSchemaKey({
 		variantKey,
 		variantValue,
@@ -264,14 +344,29 @@ function generateDeclaration({ componentName, subComponentName, variantKey, vari
 	const propertyStateMap = schema.variables?.[schemaKey]?.[propertyKey];
 	if (!propertyStateMap) throw new Error(`Prop definition (${componentName} - ${schemaKey} - ${propertyKey}) not found, this is not expected, please report the bug to the UDS team`);
 	const styles = {};
-	const skipRestForProperty = originalPropertyDefinition.skipRestState === true;
-	const declaredPseudoStates = filterPseudoStatesByExclusion(originalPropertyDefinition.pseudoStates, excludedPseudoStates);
-	const declaredPropertyStates = new Set([...skipRestForProperty ? [] : ["rest"], ...declaredPseudoStates]);
-	for (const propStateStr in propertyStateMap) {
-		if (!declaredPropertyStates.has(propStateStr)) continue;
+	const excludedStateSet = new Set(excludedPseudoStates);
+	const emittableStates = new Set([...declaredStates].filter((state) => !excludedStateSet.has(state)));
+	const orderedStateKeys = (shouldUseExhaustive || layerUsesAtomicStates ? [...emittableStates] : Object.keys(propertyStateMap)).sort(compareStateKeys);
+	const resolutionStates = fallbackStateMap ? mergeUniversalUnderOverride(fallbackStateMap, propertyStateMap) : propertyStateMap;
+	const emittedForSelective = layerUsesAtomicStates && !shouldUseExhaustive ? fallbackStateMap ? selectiveEmittedStates(fallbackStateMap, orderedStateKeys, emittableStates) : { rest: resolutionStates.rest } : {};
+	for (const propStateStr of orderedStateKeys) {
+		if (!emittableStates.has(propStateStr)) continue;
 		const propertyState = propStateStr;
-		const propertyStateSelector = statePseudoMap[propertyState] ?? "";
-		const schemaValueForState = propertyStateMap[propertyState];
+		const propertyStateSelector = getStateSelector(propertyState);
+		const schemaValueForState = shouldUseExhaustive || layerUsesAtomicStates ? resolveSlotByCascade(propStateStr, resolutionStates) : propertyStateMap[propertyState];
+		if (!schemaValueForState) continue;
+		if (!shouldUseExhaustive) {
+			if (layerUsesAtomicStates) {
+				const isExplicitlyEnabled = propertyStateMap[propertyState]?.isEnabled === true;
+				if (propStateStr !== "rest" && !isExplicitlyEnabled) {
+					if (resolveSlotByCascade(propStateStr, emittedForSelective)?.value === schemaValueForState.value) continue;
+				}
+				emittedForSelective[propStateStr] = {
+					...schemaValueForState,
+					isEnabled: true
+				};
+			} else if (schemaValueForState.isEnabled === false) continue;
+		}
 		let fullClassName = ``;
 		if (layer === "root") if (componentStateKey && componentStateValue) {
 			const rootVariantClass = generateClassName({
@@ -290,7 +385,7 @@ function generateDeclaration({ componentName, subComponentName, variantKey, vari
 				componentStateValue
 			});
 			fullClassName = `.${rootVariantClass}${propertyStateSelector}.${className}`;
-		} else fullClassName = `.${className}${propertyStateSelector}`;
+		} else fullClassName = bumpRootSpecificity ? `.${className}.${className}${propertyStateSelector}` : `.${className}${propertyStateSelector}`;
 		else {
 			const rootVariantClassName = generateClassName({
 				componentName,
@@ -317,7 +412,17 @@ function generateDeclaration({ componentName, subComponentName, variantKey, vari
 					subComponentName
 				});
 				fullClassName = `.${rootVariantClassName}${propertyStateSelector}.${rootVariantClassNameWithComponentState} .${className}`;
-			} else fullClassName = `.${rootVariantClassName}${propertyStateSelector} .${className}`;
+			} else {
+				className = generateClassName({
+					componentName,
+					variantKey,
+					variantValue,
+					layer,
+					layerOptionalPseudoSelector,
+					subComponentName
+				});
+				fullClassName = bumpRootSpecificity ? `.${rootVariantClassName}.${rootVariantClassName}${propertyStateSelector} .${className}` : `.${rootVariantClassName}${propertyStateSelector} .${className}`;
+			}
 		}
 		const { cssProperties, extendedProperties: extendedPropertiesGetter } = configurableProperties[originalPropertyDefinition.name];
 		const cssDeclarations = {};
@@ -353,6 +458,28 @@ function generateDeclaration({ componentName, subComponentName, variantKey, vari
 		*/
 		if (componentName === "button" && layer === "root") {
 			if (propertyKey === CSS_GAP) cssDeclarations[BUTTON_GAP_VAR] = cssDeclarations[CSS_GAP];
+			if (propertyKey === "spacingVertical") {
+				const paddingVertical = cssDeclarations["padding-top"];
+				if (paddingVertical) applyButtonControlHeightDeclarations({
+					cssDeclarations,
+					paddingVertical,
+					schema,
+					rootLayerKey: generateSchemaKey({
+						variantKey,
+						variantValue,
+						layer: "root",
+						subComponentName
+					}),
+					iconLayerKey: generateSchemaKey({
+						variantKey,
+						variantValue,
+						layer: "icon",
+						subComponentName
+					}),
+					state: propertyState,
+					theme
+				});
+			}
 			if (propertyKey === "scaleEffect" && propertyState === "hover") {
 				const rootClassName = `.${className}`;
 				const renderValue = (schemaValue) => configurableProperties.scaleEffect.customValueRenderer?.(schemaValue, schema, () => "") ?? "1";
@@ -361,17 +488,39 @@ function generateDeclaration({ componentName, subComponentName, variantKey, vari
 				if (propertyStateMap.hover) styles[rootClassName][BUTTON_SCALE_EFFECT_HOVER] = renderValue(propertyStateMap.hover);
 				if (propertyStateMap.pressed) styles[rootClassName][BUTTON_SCALE_EFFECT_PRESSED] = renderValue(propertyStateMap.pressed);
 			}
-			if (cssDeclarations[CSS_LINE_HEIGHT]) {
-				const iconLayerKey = generateSchemaKey({
+			if (cssDeclarations[CSS_LINE_HEIGHT]) cssDeclarations[CSS_LINE_HEIGHT] = getButtonContentLineHeight({
+				schema,
+				rootLayerKey: generateSchemaKey({
+					variantKey,
+					variantValue,
+					layer: "root",
+					subComponentName
+				}),
+				iconLayerKey: generateSchemaKey({
 					variantKey,
 					variantValue,
 					layer: "icon",
 					subComponentName
-				});
-				cssDeclarations[CSS_LINE_HEIGHT] = getButtonLineHeightWithIconMinimum({
-					lineHeight: cssDeclarations[CSS_LINE_HEIGHT],
-					schema,
-					iconLayerKey,
+				}),
+				state: propertyState,
+				theme
+			});
+		}
+		if (componentName === "iconbutton" && layer === "root") {
+			if (propertyKey === "spacing") {
+				const paddingVertical = cssDeclarations[CSS_PADDING];
+				if (paddingVertical) applyIconButtonControlHeightDeclarations({
+					cssDeclarations,
+					paddingVertical,
+					iconButtonSchema: schema,
+					buttonHeightReferenceSchema,
+					variantValue,
+					iconLayerKey: generateSchemaKey({
+						variantKey,
+						variantValue,
+						layer: "icon",
+						subComponentName
+					}),
 					state: propertyState,
 					theme
 				});
@@ -459,7 +608,7 @@ function generateDeclaration({ componentName, subComponentName, variantKey, vari
 			...styles[fullClassName]
 		};
 		if (previewOptions?.generatePseudoStateClassModifier) {
-			const pseudoPrefixClass = statePseudoMapDocsMode[propertyState] ?? "";
+			const pseudoPrefixClass = getStateDocsClass(propertyState);
 			if (pseudoPrefixClass.length) {
 				const importantCssDeclarations = Object.fromEntries(Object.entries(cssDeclarations).map(([prop, value]) => {
 					const strValue = String(value).trimEnd().replace(/;$/, "");
@@ -475,12 +624,139 @@ function generateDeclaration({ componentName, subComponentName, variantKey, vari
 	}
 	return styles;
 }
-function generateConfigStyles(config, schema, theme, previewOptions) {
+/**
+* Emit CSS for per-state schema entries that target a variant's universal
+* layers — the "override" path. Per-state schema entries can be authored by
+* the Configurator (via `setConfigPseudoStateVariable`) or written by data
+* migrations; they aren't declared in source configs.
+*
+* Iterates the cartesian product of `componentStates.X.options × universal
+* layers × universal properties`. For each combination, calls
+* `generateDeclaration` with the universal property's metadata plus the
+* componentState key/value — the existing schema lookup inside
+* `generateDeclaration` picks up the override slot if one exists and skips
+* the property otherwise.
+*/
+function emitSchemaOverrideStyles({ componentName, subComponentName, variantKey, variantOption, variantConfig, schema, theme, previewOptions, emit, currentStyles }) {
+	let styles = currentStyles;
+	const universalLayers = variantConfig.layers;
+	const componentStates = variantConfig.componentStates;
+	if (!universalLayers || !componentStates) return styles;
+	const variables = schema.variables;
+	if (!variables) return styles;
+	for (const componentStateKey in componentStates) {
+		const componentState = componentStates[componentStateKey];
+		for (const componentStateOption of componentState.options) for (const layerKey in universalLayers) {
+			const universalLayer = universalLayers[layerKey];
+			const schemaEntry = variables[generateSchemaKey({
+				variantKey,
+				variantValue: variantOption,
+				componentStateKey,
+				componentStateValue: componentStateOption,
+				layer: layerKey,
+				subComponentName
+			})];
+			if (!schemaEntry) continue;
+			for (const propertyKey in universalLayer.properties) {
+				if (!schemaEntry[propertyKey]) continue;
+				const originalPropertyDefinition = universalLayer.properties[propertyKey];
+				const fallbackStateMap = variables[generateSchemaKey({
+					variantKey,
+					variantValue: variantOption,
+					layer: layerKey,
+					subComponentName
+				})]?.[propertyKey];
+				const declarations = generateDeclaration({
+					componentName,
+					subComponentName,
+					variantKey,
+					variantValue: variantOption,
+					componentStateKey,
+					componentStateValue: componentStateOption,
+					layer: layerKey,
+					layerOptionalPseudoSelector: universalLayer.pseudoSelector,
+					propertyKey,
+					originalPropertyDefinition,
+					declaredStates: new Set(resolvePropertyStates(universalLayer, originalPropertyDefinition)),
+					layerUsesAtomicStates: (universalLayer.atomicStates?.length ?? 0) > 0,
+					theme,
+					schema,
+					currentStyles: styles,
+					previewOptions,
+					emit,
+					fallbackStateMap
+				});
+				styles = deepMerge(styles, declarations);
+			}
+		}
+	}
+	return styles;
+}
+/**
+* Emit CSS for a set of layers without a component-state segment in the
+* selector. Used by both `VariantConfigWithProperties` (where layers are the
+* only source of styles) and `VariantConfigWithComponentStates` (where these
+* layers express the variant's universal baseline, with per-state overrides
+* winning via class-compound specificity).
+*/
+function emitUniversalLayers({ componentName, subComponentName, variantKey, variantOption, layers, schema, theme, previewOptions, emit, currentStyles, bumpRootSpecificity, buttonHeightReferenceSchema }) {
+	let styles = currentStyles;
+	const variables = schema.variables;
+	for (const layerKey in layers) {
+		const layer = layers[layerKey];
+		const schemaKey = generateSchemaKey({
+			variantKey,
+			variantValue: variantOption,
+			layer: layerKey,
+			subComponentName
+		});
+		const schemaEntry = variables?.[schemaKey];
+		for (const propertyKey in layer.properties) {
+			if (!schemaEntry || !schemaEntry[propertyKey]) continue;
+			const originalPropertyDefinition = layer.properties[propertyKey];
+			const declarations = generateDeclaration({
+				componentName,
+				subComponentName,
+				variantKey,
+				variantValue: variantOption,
+				layer: layerKey,
+				layerOptionalPseudoSelector: layer.pseudoSelector,
+				propertyKey,
+				originalPropertyDefinition,
+				declaredStates: new Set(resolvePropertyStates(layer, originalPropertyDefinition)),
+				layerUsesAtomicStates: (layer.atomicStates?.length ?? 0) > 0,
+				theme,
+				schema,
+				currentStyles: styles,
+				previewOptions,
+				emit,
+				bumpRootSpecificity,
+				buttonHeightReferenceSchema
+			});
+			styles = deepMerge(styles, declarations);
+		}
+	}
+	return styles;
+}
+function generateConfigStyles(config, schema, theme, previewOptions, emit, generateStylesContext) {
 	const componentName = config.label.toLowerCase();
 	let styles = {};
 	for (const variantKey in config.variants) {
 		const variantConfig = config.variants[variantKey];
 		for (const variantOption of variantConfig.options) if (isVariantConfigWithComponentStates(variantConfig)) {
+			if (variantConfig.layers) styles = emitUniversalLayers({
+				componentName,
+				variantKey,
+				variantOption,
+				layers: variantConfig.layers,
+				schema,
+				theme,
+				previewOptions,
+				emit,
+				currentStyles: styles,
+				bumpRootSpecificity: true,
+				buttonHeightReferenceSchema: generateStylesContext?.buttonHeightReferenceSchema
+			});
 			const componentStates = variantConfig.componentStates;
 			for (const componentStateKey in componentStates) {
 				const componentState = componentStates[componentStateKey];
@@ -500,46 +776,64 @@ function generateConfigStyles(config, schema, theme, previewOptions) {
 								layerOptionalPseudoSelector: layer.pseudoSelector,
 								propertyKey,
 								originalPropertyDefinition,
+								declaredStates: new Set(resolvePropertyStates(layer, originalPropertyDefinition)),
+								layerUsesAtomicStates: (layer.atomicStates?.length ?? 0) > 0,
 								theme,
 								schema,
 								currentStyles: styles,
 								previewOptions,
-								excludedPseudoStates
+								excludedPseudoStates,
+								emit,
+								buttonHeightReferenceSchema: generateStylesContext?.buttonHeightReferenceSchema
 							});
 							styles = deepMerge(styles, declarations);
 						}
 					}
 				}
 			}
-		} else if (isVariantConfigWithProperties(variantConfig)) {
-			const layers = variantConfig.layers;
-			for (const layerKey in layers) {
-				const layer = layers[layerKey];
-				for (const propertyKey in layer.properties) {
-					const originalPropertyDefinition = layer.properties[propertyKey];
-					const declarations = generateDeclaration({
-						componentName,
-						variantKey,
-						variantValue: variantOption,
-						layer: layerKey,
-						layerOptionalPseudoSelector: layer.pseudoSelector,
-						propertyKey,
-						originalPropertyDefinition,
-						theme,
-						schema,
-						currentStyles: styles,
-						previewOptions
-					});
-					styles = deepMerge(styles, declarations);
-				}
-			}
-		}
+			styles = emitSchemaOverrideStyles({
+				componentName,
+				variantKey,
+				variantOption,
+				variantConfig,
+				schema,
+				theme,
+				previewOptions,
+				emit,
+				currentStyles: styles
+			});
+		} else if (isVariantConfigWithProperties(variantConfig)) styles = emitUniversalLayers({
+			componentName,
+			variantKey,
+			variantOption,
+			layers: variantConfig.layers,
+			schema,
+			theme,
+			previewOptions,
+			emit,
+			currentStyles: styles,
+			buttonHeightReferenceSchema: generateStylesContext?.buttonHeightReferenceSchema
+		});
 	}
 	if (config.subComponents) {
 		const { subComponents } = config;
 		for (const subComponentKey in subComponents) for (const variantKey in subComponents[subComponentKey].variants) {
 			const variantConfig = subComponents[subComponentKey].variants[variantKey];
 			for (const variantOption of variantConfig.options) if (isVariantConfigWithComponentStates(variantConfig)) {
+				if (variantConfig.layers) styles = emitUniversalLayers({
+					componentName,
+					subComponentName: subComponentKey,
+					variantKey,
+					variantOption,
+					layers: variantConfig.layers,
+					schema,
+					theme,
+					previewOptions,
+					emit,
+					currentStyles: styles,
+					bumpRootSpecificity: true,
+					buttonHeightReferenceSchema: generateStylesContext?.buttonHeightReferenceSchema
+				});
 				const componentStates = variantConfig.componentStates;
 				for (const componentStateKey in componentStates) {
 					const componentState = componentStates[componentStateKey];
@@ -560,41 +854,46 @@ function generateConfigStyles(config, schema, theme, previewOptions) {
 									layerOptionalPseudoSelector: layer.pseudoSelector,
 									propertyKey,
 									originalPropertyDefinition,
+									declaredStates: new Set(resolvePropertyStates(layer, originalPropertyDefinition)),
+									layerUsesAtomicStates: (layer.atomicStates?.length ?? 0) > 0,
 									theme,
 									schema,
 									currentStyles: styles,
 									previewOptions,
-									excludedPseudoStates
+									excludedPseudoStates,
+									emit,
+									buttonHeightReferenceSchema: generateStylesContext?.buttonHeightReferenceSchema
 								});
 								styles = deepMerge(styles, declarations);
 							}
 						}
 					}
 				}
-			} else if (isVariantConfigWithProperties(variantConfig)) {
-				const layers = variantConfig.layers;
-				for (const layerKey in layers) {
-					const layer = layers[layerKey];
-					for (const propertyKey in layer.properties) {
-						const originalPropertyDefinition = layer.properties[propertyKey];
-						const declarations = generateDeclaration({
-							componentName,
-							subComponentName: subComponentKey,
-							variantKey,
-							variantValue: variantOption,
-							layer: layerKey,
-							layerOptionalPseudoSelector: layer.pseudoSelector,
-							propertyKey,
-							originalPropertyDefinition,
-							theme,
-							schema,
-							currentStyles: styles,
-							previewOptions
-						});
-						styles = deepMerge(styles, declarations);
-					}
-				}
-			}
+				styles = emitSchemaOverrideStyles({
+					componentName,
+					subComponentName: subComponentKey,
+					variantKey,
+					variantOption,
+					variantConfig,
+					schema,
+					theme,
+					previewOptions,
+					emit,
+					currentStyles: styles
+				});
+			} else if (isVariantConfigWithProperties(variantConfig)) styles = emitUniversalLayers({
+				componentName,
+				subComponentName: subComponentKey,
+				variantKey,
+				variantOption,
+				layers: variantConfig.layers,
+				schema,
+				theme,
+				previewOptions,
+				emit,
+				currentStyles: styles,
+				buttonHeightReferenceSchema: generateStylesContext?.buttonHeightReferenceSchema
+			});
 		}
 	}
 	/**
@@ -627,8 +926,8 @@ function generateConfigStyles(config, schema, theme, previewOptions) {
 * @param previewOptions - Options for generating preview mode class modifiers
 * @returns CSS styles object with grouped selectors for default aliases
 */
-const generateStyles = (config, schema, theme, previewOptions) => {
-	const styles = generateConfigStyles(config, schema, theme, previewOptions);
+const generateStylesInner = (config, schema, theme, previewOptions, generateStylesContext) => {
+	const styles = generateConfigStyles(config, schema, theme, previewOptions, previewOptions.emit ?? "exhaustive", generateStylesContext);
 	if (!config.variants && !config.subComponents) return styles;
 	const componentName = config.label.toLowerCase();
 	if (componentName !== "button" && componentName !== "iconbutton") return styles;
@@ -636,14 +935,15 @@ const generateStyles = (config, schema, theme, previewOptions) => {
 	/**
 	* Helper: Extract all layer keys from a variant configuration
 	* Handles both simple variants (with direct layers) and variants with component states
+	* (which may additionally declare top-level universal layers).
 	*/
 	const getLayerKeys = (variantConfig) => {
-		if (isVariantConfigWithProperties(variantConfig)) return Object.keys(variantConfig.layers);
-		else if (isVariantConfigWithComponentStates(variantConfig)) {
+		if (isVariantConfigWithComponentStates(variantConfig)) {
 			const layerKeysSet = /* @__PURE__ */ new Set();
-			for (const componentStateConfig of Object.values(variantConfig.componentStates)) Object.keys(componentStateConfig.layers).forEach((key) => layerKeysSet.add(key));
+			for (const componentStateConfig of Object.values(variantConfig.componentStates)) Object.keys(componentStateConfig.layers ?? {}).forEach((key) => layerKeysSet.add(key));
+			if (variantConfig.layers) Object.keys(variantConfig.layers).forEach((key) => layerKeysSet.add(key));
 			return Array.from(layerKeysSet);
-		}
+		} else if (isVariantConfigWithProperties(variantConfig)) return Object.keys(variantConfig.layers);
 		return [];
 	};
 	/**
@@ -693,7 +993,39 @@ const generateStyles = (config, schema, theme, previewOptions) => {
 	}
 	return finalStyles;
 };
+/**
+* Public entry point. Generates a component's CSS, emitting each declared state
+* as its own rule (one selector per rule) so the cascade is carried entirely by
+* per-rule specificity — which CSS minifiers preserve.
+*
+* An earlier optimization merged rules sharing a declaration block into a single
+* comma-separated selector list (to avoid repeating invariant declarations per
+* state). It was removed: a minifier's forgiving-`:is()` rewrite — applied to a
+* comma-separated list that contains `:has()` when targeting browsers without
+* native `:has()` support — collapses the list to its single highest
+* specificity, inflating the weakest selector (`rest`) above genuinely
+* customized states and corrupting the cascade. Separate rules never form such a
+* list, so minifiers leave their specificity intact. (gzip already collapses the
+* repeated declaration blocks, so the shipped-size cost is minimal.)
+*/
+const generateStyles = (config, schema, theme, previewOptions, generateStylesContext) => generateStylesInner(config, schema, theme, previewOptions, generateStylesContext);
+/**
+* Throws if `values` contains a duplicate entry. Runs at config-import time so
+* a typo like `atomicStates: ['hover', 'hover']` fails the UDS build instead
+* of silently degrading the configurator's sidebar (where the resolver would
+* emit two entries for the same state).
+*/
+function assertNoDuplicates(values, field, ownerLabel) {
+	if (!values) return;
+	const seen = /* @__PURE__ */ new Set();
+	for (const v of values) {
+		if (seen.has(v)) throw new Error(`Duplicate "${v}" in ${field} on ${ownerLabel}. Each entry must appear at most once.`);
+		seen.add(v);
+	}
+}
 function createConfigurableProperty(prop) {
+	assertNoDuplicates(prop.pseudoStates, "pseudoStates", `property "${prop.label}"`);
+	assertNoDuplicates(prop.excludeAtomics, "excludeAtomics", `property "${prop.label}"`);
 	return prop;
 }
 function createVariantConfig(config) {
@@ -709,10 +1041,44 @@ function createComponentStates(config) {
 	return config;
 }
 function createLayerConfig(config) {
+	assertNoDuplicates(config.atomicStates, "atomicStates", `layer "${config.label}"`);
+	assertNoSkipRestStateOnAtomicLayer(config);
 	return config;
 }
+/**
+* Disallows pairing `skipRestState: true` properties with a layer that uses
+* `atomicStates`. The combination breaks exhaustive emission's cascade
+* resolution:
+*
+* Under `atomicStates`, `generateDeclaration` emits every declared state and
+* resolves each non-customized compound through `resolveSlotByCascade`, so a
+* deliberate atom customization (e.g. `hover`) flows into every compound that
+* inherits from it (`invalid&hover`, …). That inheritance is what keeps the
+* higher-specificity compound rules from cancelling a lower-specificity atom
+* customization.
+*
+* But `buildPropertyStateMap` force-marks EVERY slot of a `skipRestState`
+* property `isEnabled: true` (there's no `rest` fall-through, so each state must
+* carry its own value). `resolveSlotByCascade` returns an enabled slot as-is,
+* so each force-enabled compound emits the property's *default* value instead of
+* inheriting a sibling atom's customization — and the compound's higher
+* specificity then silently overrides that customization (e.g. a customized
+* `hover` is cancelled by an unmodified `invalid&hover` carrying the default).
+*
+* Resolution path when this becomes a real need (currently the only
+* `skipRestState` properties are Button's `opacity` and `scaleEffect`, and
+* Button is on legacy `pseudoStates`):
+* teach `generateDeclaration` to skip compound state emission entirely for
+* `skipRestState` properties — atom rules cascade naturally, and designers
+* who want fine compound control simply drop `skipRestState` for that
+* property.
+*/
+function assertNoSkipRestStateOnAtomicLayer(config) {
+	if (!config.atomicStates || config.atomicStates.length === 0) return;
+	for (const [propertyKey, property] of Object.entries(config.properties)) if (property.skipRestState) throw new Error(`Property "${propertyKey}" on layer "${config.label}" uses skipRestState: true, but the layer declares atomicStates. This combination isn't currently supported — see the comment on assertNoSkipRestStateOnAtomicLayer for the trade-offs and resolution path. For now, either drop skipRestState on this property or keep the layer on legacy per-property pseudoStates.`);
+}
 function createSubComponentConfig(config) {
 	return config;
 }
 //#endregion
-export { applyBoxShadowBorder, createComponentStates, createConfigurableProperty, createLayerConfig, createSubComponentConfig, createVariantConfig, createVariantConfigWithComponentStates, createVariantConfigWithProperties, generateClassName, generateConfigStyles, generateDeclaration, generateStyles, statePseudoMapDocsMode };
+export { applyBoxShadowBorder, createComponentStates, createConfigurableProperty, createLayerConfig, createSubComponentConfig, createVariantConfig, createVariantConfigWithComponentStates, createVariantConfigWithProperties, generateClassName, generateConfigStyles, generateDeclaration, generateStyles, mergeUniversalUnderOverride, statePseudoMapDocsMode };