@yahoo/uds-v5-wip 1.59.0 → 1.61.0

package/dist/config/dist/style-prop-runtime.js

@@ -0,0 +1,390 @@
+//#region ../config/dist/style-prop-runtime.js
+function resolveTokenMarker(marker, configPrefix) {
+	const ref = marker.ref;
+	const slashIdx = ref.indexOf("/");
+	if (slashIdx <= 0 || slashIdx >= ref.length - 1) return ref;
+	const ns = ref.slice(0, slashIdx);
+	const name = ref.slice(slashIdx + 1);
+	const cssPrefix = ns.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+	const cssName = name.replace(/\./g, "_").replace(/\//g, "-");
+	return `var(${configPrefix ? `--${configPrefix}-${cssPrefix}-${cssName}` : `--${cssPrefix}-${cssName}`})`;
+}
+const BUILT_IN_PSEUDO = {
+	_after: "after:",
+	_hover: "hover:",
+	_focus: "focus:",
+	_focusWithin: "focus-within:",
+	_focusVisible: "focus-visible:",
+	_active: "active:",
+	_visited: "visited:",
+	_target: "target:",
+	_first: "first:",
+	_last: "last:",
+	_only: "only:",
+	_odd: "odd:",
+	_even: "even:",
+	_firstOfType: "first-of-type:",
+	_lastOfType: "last-of-type:",
+	_onlyOfType: "only-of-type:",
+	_empty: "empty:",
+	_disabled: "disabled:",
+	_enabled: "enabled:",
+	_checked: "checked:",
+	_indeterminate: "indeterminate:",
+	_default: "default:",
+	_required: "required:",
+	_valid: "valid:",
+	_invalid: "invalid:",
+	_inRange: "in-range:",
+	_outOfRange: "out-of-range:",
+	_placeholderShown: "placeholder-shown:",
+	_autofill: "autofill:",
+	_readonly: "read-only:",
+	_file: "file:",
+	_selection: "selection:",
+	_backdrop: "backdrop:",
+	_motionReduce: "motion-reduce:",
+	_motionSafe: "motion-safe:",
+	_contrastMore: "contrast-more:",
+	_contrastLess: "contrast-less:",
+	_forcedColors: "forced-colors:",
+	_placeholder: "placeholder:",
+	_ariaBusy: "aria-busy:",
+	_ariaChecked: "aria-checked:",
+	_ariaHidden: "aria-hidden:",
+	_ariaPressed: "aria-pressed:",
+	_ariaReadonly: "aria-readonly:",
+	_ariaRequired: "aria-required:",
+	_ariaSelected: "aria-selected:",
+	_ariaCurrent: "aria-[current]:",
+	_ariaDisabled: "aria-disabled:",
+	_ariaExpanded: "aria-expanded:",
+	_dataDisabled: "data-[disabled=true]:",
+	_dataStateOpen: "data-[state=open]:",
+	_dataStateClosed: "data-[state=closed]:",
+	_startingStyle: "starting-style:",
+	_scrollbar: "*::-webkit-scrollbar:",
+	_scrollbarThumb: "*::-webkit-scrollbar-thumb:",
+	_scrollbarTrack: "*::-webkit-scrollbar-track:"
+};
+/** Pseudo-suffix derived from a built-in tailwind prefix (`hover:` → `:hover`).
+*  Returns null for prefixes that aren't simple pseudo-classes (data-, aria-,
+*  pseudo-element ::, at-rules). */
+function pseudoSuffixForBuiltIn(prefix) {
+	if (prefix.includes("::") || prefix.startsWith("*")) return null;
+	if (prefix.startsWith("data-[") || prefix.startsWith("aria-")) return null;
+	return `:${prefix.slice(0, -1)}`;
+}
+function kebabCase(s) {
+	return s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function buildStylePropRuntime(config) {
+	return {
+		styleProps: buildStylePropsMap(config.resolvedStyleProps ?? []),
+		modifiers: buildModifiersMap(config),
+		composites: buildCompositesMap(config)
+	};
+}
+function buildStylePropsMap(resolved) {
+	const out = {};
+	for (const entry of resolved) {
+		if (!entry.classPrefix && !entry.pairedWith) continue;
+		const cssProperty = Array.isArray(entry.cssProperty) ? entry.cssProperty[0] : entry.cssProperty;
+		if (typeof cssProperty !== "string" || cssProperty.length === 0) continue;
+		const firstToken = entry.tokens[0];
+		let varPrefix;
+		if (firstToken?.cssVar) {
+			const stripped = firstToken.cssVar.startsWith("--") ? firstToken.cssVar.slice(2) : firstToken.cssVar;
+			const suffix = `-${firstToken.safeName}`;
+			varPrefix = stripped.endsWith(suffix) ? stripped.slice(0, -suffix.length) : stripped;
+		}
+		const literalAliases = {};
+		let hasAliases = false;
+		if (entry.literalAliases) {
+			for (const [key, value] of Object.entries(entry.literalAliases)) if (typeof value === "string") {
+				literalAliases[key] = value;
+				hasAliases = true;
+			}
+		}
+		const styleEntry = {
+			classPrefix: entry.classPrefix,
+			cssProperty,
+			...varPrefix ? { varPrefix } : {},
+			...entry.pairedWith ? { pairedWith: entry.pairedWith } : {},
+			...entry.separator ? { separator: entry.separator } : {},
+			...hasAliases ? { literalAliases } : {}
+		};
+		out[entry.propName] = styleEntry;
+	}
+	return out;
+}
+function buildModifiersMap(config) {
+	const out = {};
+	for (const [propName, prefix] of Object.entries(BUILT_IN_PSEUDO)) {
+		const suffix = pseudoSuffixForBuiltIn(prefix);
+		out[propName] = suffix ? {
+			tailwindPrefix: prefix,
+			kind: "pseudo",
+			selector: suffix
+		} : {
+			tailwindPrefix: prefix,
+			kind: "ancestor",
+			selector: complexBuiltInSelector(prefix)
+		};
+	}
+	for (const group of config.modes ?? []) for (const option of group.options) {
+		if (option.default) continue;
+		const propName = option.modifier;
+		const tailwindPrefix = `${propName.slice(1)}:`;
+		if (option.css) out[propName] = {
+			tailwindPrefix,
+			kind: "ancestor",
+			selector: option.css
+		};
+		else if (option.media) out[propName] = {
+			tailwindPrefix,
+			kind: "at-rule",
+			selector: `@media ${option.media}`
+		};
+	}
+	for (const def of config.modifiers ?? []) {
+		const propName = def.modifier;
+		out[propName] = {
+			tailwindPrefix: `${propName.slice(1)}:`,
+			kind: def.selector.trimStart().startsWith("@") ? "at-rule" : "ancestor",
+			selector: def.selector
+		};
+	}
+	return out;
+}
+/** Convert a complex built-in tailwind prefix to a CSS selector fragment. */
+function complexBuiltInSelector(prefix) {
+	const dataMatch = prefix.match(/^data-\[([^=]+)=([^\]]+)\]:$/);
+	if (dataMatch) return `[data-${dataMatch[1]}="${dataMatch[2]}"]`;
+	const ariaMatch = prefix.match(/^aria-([a-z-]+):$/);
+	if (ariaMatch) return `[aria-${ariaMatch[1]}="true"]`;
+	const ariaBracket = prefix.match(/^aria-\[([^\]]+)\]:$/);
+	if (ariaBracket) return `[aria-${ariaBracket[1]}]`;
+	if (prefix.startsWith("*")) return prefix.slice(1, -1);
+	return prefix.slice(0, -1);
+}
+function buildCompositesMap(config) {
+	const out = {};
+	const composites = config.compositeStyles;
+	if (!composites) return out;
+	for (const [groupName, group] of Object.entries(composites)) {
+		const styles = group.styles;
+		if (!styles) continue;
+		out[groupName] = { ...styles };
+	}
+	return out;
+}
+/** Detect arbitrary `[value]` syntax. */
+const ARBITRARY_RE = /^\[(.+)\]$/;
+function processStyleProps(props, runtime, opts = {}) {
+	const classes = [];
+	const dynamicRules = [];
+	let effectiveProps = props;
+	let markerClasses;
+	let compositeMarkers;
+	const expansion = expandComposites(props, runtime.composites);
+	if (expansion) {
+		effectiveProps = expansion.expanded;
+		markerClasses = expansion.markers;
+		compositeMarkers = expansion.compositeMarkers;
+	}
+	if (markerClasses) for (const marker of markerClasses) classes.push(applyModifierPrefix(marker, opts.modifier));
+	if (compositeMarkers && compositeMarkers.length > 0) for (const { group, value } of compositeMarkers) {
+		const containerRule = buildCompositeContainerRule(group, value, opts.modifier);
+		if (containerRule) dynamicRules.push(containerRule);
+		const propRule = buildCompositeMarkerRule(group, value, opts.modifier, runtime.modifiers);
+		if (propRule) dynamicRules.push(propRule);
+	}
+	for (const key in effectiveProps) {
+		if (!Object.hasOwn(effectiveProps, key)) continue;
+		const value = effectiveProps[key];
+		if (value === void 0 || value === null || value === false) continue;
+		if (key.startsWith("_")) {
+			const modifier = runtime.modifiers[key];
+			if (!modifier || !isStyleObject(value)) continue;
+			const inner = processStyleProps(value, runtime, { modifier: opts.modifier ? `${opts.modifier}${modifier.tailwindPrefix}` : modifier.tailwindPrefix });
+			if (inner.className) classes.push(inner.className);
+			dynamicRules.push(...inner.dynamicRules);
+			continue;
+		}
+		const entry = runtime.styleProps[key];
+		if (!entry) continue;
+		if (entry.pairedWith) continue;
+		const opacityProp = findOpacitySibling(key, runtime.styleProps);
+		const opacityValue = opacityProp !== void 0 ? effectiveProps[opacityProp] : void 0;
+		if (typeof value === "string" && ARBITRARY_RE.test(value)) {
+			const fullClass = applyModifierPrefix(buildArbitraryClass(entry, value, opacityValue), opts.modifier);
+			classes.push(fullClass);
+			const arbitraryRule = buildArbitraryRule(fullClass, entry, value, opacityValue, opts.modifier, runtime.modifiers);
+			if (arbitraryRule) dynamicRules.push(arbitraryRule);
+			continue;
+		}
+		if (value === true) {
+			classes.push(applyModifierPrefix(entry.classPrefix, opts.modifier));
+			continue;
+		}
+		let effectiveValue = String(value);
+		if (entry.literalAliases && effectiveValue in entry.literalAliases) {
+			const aliased = entry.literalAliases[effectiveValue];
+			if (aliased !== void 0) effectiveValue = aliased;
+		}
+		if (opacityValue !== void 0 && opacityProp !== void 0) {
+			const sep = runtime.styleProps[opacityProp]?.separator ?? entry.separator ?? "_";
+			const cls = applyModifierPrefix(buildTokenClass(entry, `${effectiveValue}${sep}${opacityValue}`), opts.modifier);
+			classes.push(cls);
+			if (entry.varPrefix) {
+				const rule = buildOpacityMixRule(cls, entry, effectiveValue, String(opacityValue), opts.modifier, runtime.modifiers);
+				if (rule) dynamicRules.push(rule);
+			}
+			continue;
+		}
+		classes.push(applyModifierPrefix(buildTokenClass(entry, effectiveValue), opts.modifier));
+	}
+	return {
+		className: classes.filter(Boolean).join(" "),
+		dynamicRules
+	};
+}
+function isStyleObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function findOpacitySibling(parentProp, styleProps) {
+	for (const candidateName in styleProps) if (styleProps[candidateName]?.pairedWith === parentProp) return candidateName;
+}
+/** Build a token-value class, e.g. `bg-brand` or `bg-elevation-1`. Applies the
+*  same safe-token-name normalization codegen uses (`.` → `_`, `/` → `-`). */
+function buildTokenClass(entry, value) {
+	if (entry.classPrefix === "") return value;
+	if (value === "") return entry.classPrefix;
+	const safe = value.replace(/\./g, "_").replace(/\//g, "-");
+	return entry.classPrefix === value ? safe : `${entry.classPrefix}-${safe}`;
+}
+/** Build the arbitrary-value class, e.g. `bg-[#ef4444]` or `bg-[#ef4444]/60`. */
+function buildArbitraryClass(entry, value, opacityValue) {
+	const base = `${entry.classPrefix}-${value}`;
+	if (opacityValue === void 0 || opacityValue === null) return base;
+	return `${base}/${opacityValue}`;
+}
+function applyModifierPrefix(cls, modifier) {
+	return modifier ? `${modifier}${cls}` : cls;
+}
+/** Build the runtime CSS rule for an arbitrary-value class. */
+function buildArbitraryRule(fullClass, entry, rawValue, opacityValue, modifier, modifiers) {
+	const match = rawValue.match(ARBITRARY_RE);
+	if (!match) return null;
+	const inside = match[1];
+	let cssValue = inside;
+	if (opacityValue !== void 0 && opacityValue !== null) cssValue = `color-mix(in srgb, ${inside} ${opacityValue}%, transparent)`;
+	return buildDynamicRule(fullClass, entry.cssProperty, cssValue, modifier, modifiers);
+}
+/** Build the runtime CSS rule for a color/opacity token-pair fallback. */
+function buildOpacityMixRule(fullClass, entry, baseValue, opacityValue, modifier, modifiers) {
+	if (!entry.varPrefix) return null;
+	const cssValue = `color-mix(in srgb, var(${`--${entry.varPrefix}-${baseValue.replace(/[./]/g, "_")}`}) ${opacityValue}%, transparent)`;
+	return buildDynamicRule(fullClass, entry.cssProperty, cssValue, modifier, modifiers);
+}
+/** Assemble a {@link DynamicRule} from a class + value + accumulated modifier prefix. */
+function buildDynamicRule(fullClass, cssProperty, cssValue, modifier, modifiers) {
+	const cssProp = kebabCase(cssProperty);
+	let ancestorParts = "";
+	let pseudoParts = "";
+	let atRule;
+	if (modifier) {
+		const parts = modifier.split(":").filter(Boolean).map((p) => `${p}:`);
+		for (const part of parts) {
+			const resolved = modifiers[`_${part.slice(0, -1)}`];
+			if (!resolved) continue;
+			if (resolved.kind === "pseudo") pseudoParts += resolved.selector;
+			else if (resolved.kind === "ancestor") ancestorParts += `${resolved.selector} `;
+			else if (resolved.kind === "at-rule") atRule = resolved.selector;
+		}
+	}
+	const escaped = escapeClassName(fullClass);
+	const selector = `${ancestorParts}.${escaped}${pseudoParts}`;
+	return atRule ? {
+		className: fullClass,
+		selector,
+		cssProperty: cssProp,
+		cssValue,
+		atRule
+	} : {
+		className: fullClass,
+		selector,
+		cssProperty: cssProp,
+		cssValue
+	};
+}
+/** CSS class-name escape — matches `CSS.escape` semantics enough for runtime use. */
+function escapeClassName(name) {
+	return name.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
+}
+/**
+* Build a dynamic CSS rule that sets `--uds-composite-<group>: <value>` on
+* the host element. The host selector is the composite marker class (which
+* also gets pushed onto the className), so the rule reads:
+*
+*   - Unconditional: `.elevation-1 { --uds-composite-elevation: 1 }`
+*   - Modifier-conditional: `.hover\:elevation-1:hover { ... }`
+*
+* Descendants react via `@container style(--uds-composite-elevation: 1) &`
+* — see `buildCompositeStylesReference` and the auto-registered
+* `_on<Group><Value>` modifiers for the descendant selector form.
+*/
+function buildCompositeMarkerRule(group, value, modifier, modifiers) {
+	const groupSafe = group.replace(/[./]/g, "-");
+	const valueSafe = value.replace(/[./]/g, "-");
+	return buildDynamicRule(applyModifierPrefix(`${groupSafe}-${valueSafe}`, modifier), `--uds-composite-${groupSafe}`, valueSafe, modifier, modifiers);
+}
+/**
+* Build an unconditional `container-type: style` rule targeting the
+* composite marker class. Required for descendant `@container style()`
+* queries to match against this host — without it the queries have no
+* container to anchor on. The rule is unconditional (no modifier scope)
+* because we want descendants to be able to query the host's state at
+* any time, including under modifier branches.
+*/
+function buildCompositeContainerRule(group, value, modifier) {
+	const fullClass = applyModifierPrefix(`${group.replace(/[./]/g, "-")}-${value.replace(/[./]/g, "-")}`, modifier);
+	return {
+		className: fullClass,
+		selector: `.${escapeClassName(fullClass)}`,
+		cssProperty: "container-type",
+		cssValue: "style"
+	};
+}
+function expandComposites(props, composites) {
+	let result = null;
+	const markers = [];
+	const compositeMarkers = [];
+	for (const groupName in composites) {
+		if (!Object.hasOwn(composites, groupName)) continue;
+		const propValue = props[groupName];
+		if (propValue === void 0 || propValue === null) continue;
+		const variants = composites[groupName];
+		if (!variants) continue;
+		const variantStyles = variants[String(propValue)];
+		if (!variantStyles) continue;
+		if (!result) result = { ...props };
+		delete result[groupName];
+		compositeMarkers.push({
+			group: groupName,
+			value: String(propValue)
+		});
+		for (const [propName, value] of Object.entries(variantStyles)) if (value !== null && typeof value === "object" && value.__kind === "token" && typeof value.ref === "string") result[propName] = resolveTokenMarker(value, void 0);
+		else result[propName] = value;
+		markers.push(`${groupName}-${String(propValue).replace(/[./]/g, "-")}`);
+	}
+	if (!result) return null;
+	return {
+		expanded: result,
+		markers,
+		compositeMarkers
+	};
+}
+//#endregion
+export { BUILT_IN_PSEUDO, buildStylePropRuntime, processStyleProps };

package/dist/config/dist/types/css-properties.d.ts

@@ -0,0 +1,223 @@
+import { CssValue, CssVarRef } from "./css-values.js";
+
+//#region ../config/dist/types/css-properties.d.ts
+//#region src/types/css-properties.d.ts
+type LengthPercentageOrVar = CssValue['length-percentage'] | CssVarRef;
+type LengthOrVar = CssValue['length'] | CssVarRef;
+type ColorOrVar = CssValue['color'] | CssVarRef;
+type NumberOrVar = CssValue['number'] | CssVarRef;
+type IntegerOrVar = CssValue['integer'] | CssVarRef;
+type TimeOrVar = CssValue['time'] | CssVarRef;
+type AngleOrVar = CssValue['angle'] | CssVarRef;
+type IntrinsicSize = 'auto' | 'min-content' | 'max-content' | 'fit-content';
+type GlobalKeyword = 'inherit' | 'initial' | 'unset' | 'revert';
+type BorderStyleKeyword = 'none' | 'hidden' | 'dotted' | 'dashed' | 'solid' | 'double' | 'groove' | 'ridge' | 'inset' | 'outset';
+type CssPropertyValues = {
+  gap: LengthPercentageOrVar;
+  'column-gap': LengthPercentageOrVar;
+  'row-gap': LengthPercentageOrVar;
+  padding: LengthPercentageOrVar;
+  'padding-top': LengthPercentageOrVar;
+  'padding-right': LengthPercentageOrVar;
+  'padding-bottom': LengthPercentageOrVar;
+  'padding-left': LengthPercentageOrVar;
+  'padding-block': LengthPercentageOrVar;
+  'padding-inline': LengthPercentageOrVar;
+  'padding-inline-start': LengthPercentageOrVar;
+  'padding-inline-end': LengthPercentageOrVar;
+  margin: LengthPercentageOrVar | 'auto';
+  'margin-top': LengthPercentageOrVar | 'auto';
+  'margin-right': LengthPercentageOrVar | 'auto';
+  'margin-bottom': LengthPercentageOrVar | 'auto';
+  'margin-left': LengthPercentageOrVar | 'auto';
+  'margin-block': LengthPercentageOrVar | 'auto';
+  'margin-inline': LengthPercentageOrVar | 'auto';
+  'margin-inline-start': LengthPercentageOrVar | 'auto';
+  'margin-inline-end': LengthPercentageOrVar | 'auto';
+  top: LengthPercentageOrVar | 'auto';
+  right: LengthPercentageOrVar | 'auto';
+  bottom: LengthPercentageOrVar | 'auto';
+  left: LengthPercentageOrVar | 'auto';
+  inset: LengthPercentageOrVar | 'auto';
+  'inset-block': LengthPercentageOrVar | 'auto';
+  'inset-inline': LengthPercentageOrVar | 'auto';
+  'scroll-margin': LengthPercentageOrVar;
+  'scroll-margin-top': LengthPercentageOrVar;
+  'scroll-margin-bottom': LengthPercentageOrVar;
+  'scroll-margin-block': LengthPercentageOrVar;
+  'scroll-margin-inline': LengthPercentageOrVar;
+  'scroll-margin-inline-start': LengthPercentageOrVar;
+  'scroll-margin-inline-end': LengthPercentageOrVar;
+  'scroll-padding': LengthPercentageOrVar;
+  'scroll-padding-top': LengthPercentageOrVar;
+  'scroll-padding-bottom': LengthPercentageOrVar;
+  'scroll-padding-block': LengthPercentageOrVar;
+  'scroll-padding-inline': LengthPercentageOrVar;
+  'scroll-padding-inline-start': LengthPercentageOrVar;
+  'scroll-padding-inline-end': LengthPercentageOrVar;
+  width: LengthPercentageOrVar | IntrinsicSize;
+  height: LengthPercentageOrVar | IntrinsicSize;
+  'min-width': LengthPercentageOrVar | IntrinsicSize;
+  'max-width': LengthPercentageOrVar | IntrinsicSize | 'none';
+  'min-height': LengthPercentageOrVar | IntrinsicSize;
+  'max-height': LengthPercentageOrVar | IntrinsicSize | 'none';
+  'border-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-top-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-right-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-bottom-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-left-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-block-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-inline-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-inline-start-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'border-inline-end-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'outline-width': LengthOrVar | 'thin' | 'medium' | 'thick';
+  'outline-offset': LengthOrVar;
+  'border-spacing': LengthOrVar;
+  'border-radius': LengthPercentageOrVar;
+  'border-top-left-radius': LengthPercentageOrVar;
+  'border-top-right-radius': LengthPercentageOrVar;
+  'border-bottom-left-radius': LengthPercentageOrVar;
+  'border-bottom-right-radius': LengthPercentageOrVar;
+  'border-start-start-radius': LengthPercentageOrVar;
+  'border-start-end-radius': LengthPercentageOrVar;
+  'border-end-start-radius': LengthPercentageOrVar;
+  'border-end-end-radius': LengthPercentageOrVar;
+  'border-style': BorderStyleKeyword | CssVarRef;
+  'outline-style': BorderStyleKeyword | 'auto' | CssVarRef;
+  'text-decoration-style': 'solid' | 'double' | 'dotted' | 'dashed' | 'wavy' | CssVarRef;
+  'text-decoration-thickness': LengthPercentageOrVar | 'auto' | 'from-font';
+  'text-underline-offset': LengthOrVar | 'auto';
+  color: ColorOrVar;
+  'background-color': ColorOrVar;
+  'border-color': ColorOrVar;
+  'border-top-color': ColorOrVar;
+  'border-right-color': ColorOrVar;
+  'border-bottom-color': ColorOrVar;
+  'border-left-color': ColorOrVar;
+  'border-block-color': ColorOrVar;
+  'border-inline-color': ColorOrVar;
+  'border-inline-start-color': ColorOrVar;
+  'border-inline-end-color': ColorOrVar;
+  'outline-color': ColorOrVar | 'invert';
+  'text-decoration-color': ColorOrVar;
+  'caret-color': ColorOrVar | 'auto';
+  fill: ColorOrVar | 'none' | 'context-fill' | 'context-stroke';
+  stroke: ColorOrVar | 'none' | 'context-fill' | 'context-stroke';
+  'stroke-width': LengthPercentageOrVar | CssValue['number'];
+  'scrollbar-color': ColorOrVar | 'auto' | `${string} ${string}`;
+  'font-size': LengthPercentageOrVar | 'xx-small' | 'x-small' | 'small' | 'medium' | 'large' | 'x-large' | 'xx-large' | 'smaller' | 'larger';
+  'font-weight': CssValue['font-weight'] | CssVarRef;
+  'font-family': CssValue['font-family'] | CssVarRef;
+  'font-style': 'normal' | 'italic' | 'oblique' | `oblique ${string}` | CssVarRef;
+  'font-stretch': CssValue['percentage'] | 'normal' | 'ultra-condensed' | 'extra-condensed' | 'condensed' | 'semi-condensed' | 'semi-expanded' | 'expanded' | 'extra-expanded' | 'ultra-expanded' | CssVarRef;
+  'font-variant-numeric': string | CssVarRef;
+  'line-height': LengthPercentageOrVar | NumberOrVar | 'normal';
+  'letter-spacing': LengthOrVar | 'normal';
+  'text-align': 'left' | 'right' | 'center' | 'justify' | 'start' | 'end' | CssVarRef;
+  'text-transform': 'none' | 'capitalize' | 'uppercase' | 'lowercase' | 'full-width' | 'full-size-kana' | CssVarRef;
+  'text-indent': LengthPercentageOrVar;
+  'text-wrap': 'wrap' | 'nowrap' | 'balance' | 'pretty' | 'stable' | CssVarRef;
+  'text-overflow': 'clip' | 'ellipsis' | string;
+  'text-decoration-line': 'none' | 'underline' | 'overline' | 'line-through' | 'blink' | string | CssVarRef;
+  'text-shadow': CssValue['shadow'] | 'none' | CssVarRef;
+  'white-space': 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | 'break-spaces' | CssVarRef;
+  'word-break': 'normal' | 'break-all' | 'keep-all' | 'break-word' | CssVarRef;
+  'overflow-wrap': 'normal' | 'break-word' | 'anywhere' | CssVarRef;
+  hyphens: 'none' | 'manual' | 'auto' | CssVarRef;
+  'list-style-type': string | CssVarRef;
+  'list-style-image': CssValue['url'] | 'none' | CssVarRef;
+  'list-style-position': 'inside' | 'outside' | CssVarRef;
+  'vertical-align': LengthPercentageOrVar | 'baseline' | 'sub' | 'super' | 'text-top' | 'text-bottom' | 'middle' | 'top' | 'bottom';
+  '-webkit-font-smoothing': 'auto' | 'none' | 'antialiased' | 'subpixel-antialiased';
+  '-webkit-line-clamp': IntegerOrVar | 'none';
+  display: 'block' | 'inline' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'inline-grid' | 'flow-root' | 'none' | 'contents' | 'table' | 'inline-table' | 'table-row-group' | 'table-header-group' | 'table-footer-group' | 'table-row' | 'table-cell' | 'table-column-group' | 'table-column' | 'table-caption' | 'list-item' | CssVarRef;
+  visibility: 'visible' | 'hidden' | 'collapse' | CssVarRef;
+  isolation: 'auto' | 'isolate' | CssVarRef;
+  position: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky' | CssVarRef;
+  'box-sizing': 'content-box' | 'border-box' | CssVarRef;
+  'container-type': 'normal' | 'size' | 'inline-size' | CssVarRef;
+  columns: IntegerOrVar | LengthOrVar | 'auto' | `${number} ${string}`;
+  flex: string | NumberOrVar | 'none' | 'auto' | 'initial';
+  'flex-direction': 'row' | 'row-reverse' | 'column' | 'column-reverse' | CssVarRef;
+  'flex-wrap': 'nowrap' | 'wrap' | 'wrap-reverse' | CssVarRef;
+  'flex-grow': NumberOrVar;
+  'flex-shrink': NumberOrVar;
+  'justify-content': 'flex-start' | 'flex-end' | 'start' | 'end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'normal' | 'left' | 'right' | CssVarRef;
+  'align-items': 'normal' | 'stretch' | 'center' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'baseline' | `first baseline` | `last baseline` | CssVarRef;
+  'align-content': 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'baseline' | CssVarRef;
+  'align-self': 'auto' | 'normal' | 'stretch' | 'center' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'baseline' | CssVarRef;
+  'place-content': string | CssVarRef;
+  'place-items': string | CssVarRef;
+  'place-self': string | CssVarRef;
+  order: IntegerOrVar;
+  'grid-template-columns': string | 'none' | CssVarRef;
+  'grid-template-rows': string | 'none' | CssVarRef;
+  'grid-column': string | 'auto' | CssVarRef;
+  'grid-column-start': string | 'auto' | CssVarRef;
+  'grid-column-end': string | 'auto' | CssVarRef;
+  'grid-row': string | 'auto' | CssVarRef;
+  'grid-row-start': string | 'auto' | CssVarRef;
+  'grid-row-end': string | 'auto' | CssVarRef;
+  transform: string | 'none' | CssVarRef;
+  'transform-origin': string | CssVarRef;
+  rotate: AngleOrVar | 'none' | `${number}` | `${string} ${string}`;
+  scale: NumberOrVar | 'none' | `${number} ${number}` | `${number} ${number} ${number}`;
+  translate: LengthPercentageOrVar | 'none' | `${string} ${string}` | `${string} ${string} ${string}`;
+  transition: string | 'none' | CssVarRef;
+  'transition-property': string | 'none' | 'all' | CssVarRef;
+  'transition-duration': TimeOrVar;
+  'transition-delay': TimeOrVar;
+  'transition-timing-function': CssValue['easing-function'] | CssVarRef;
+  'transition-behavior': 'normal' | 'allow-discrete' | CssVarRef;
+  animation: string | 'none' | CssVarRef;
+  opacity: CssValue['percentage'] | NumberOrVar;
+  'box-shadow': CssValue['shadow'] | 'none' | CssVarRef;
+  filter: string | 'none' | CssVarRef;
+  'backdrop-filter': string | 'none' | CssVarRef;
+  'mix-blend-mode': 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'plus-darker' | 'plus-lighter' | CssVarRef;
+  'background-blend-mode': 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' | CssVarRef;
+  overflow: 'visible' | 'hidden' | 'clip' | 'scroll' | 'auto' | CssVarRef;
+  'overflow-x': 'visible' | 'hidden' | 'clip' | 'scroll' | 'auto' | CssVarRef;
+  'overflow-y': 'visible' | 'hidden' | 'clip' | 'scroll' | 'auto' | CssVarRef;
+  'overscroll-behavior': 'auto' | 'contain' | 'none' | CssVarRef;
+  'scroll-behavior': 'auto' | 'smooth' | CssVarRef;
+  'scroll-snap-align': 'none' | 'start' | 'end' | 'center' | CssVarRef;
+  'scroll-snap-stop': 'normal' | 'always' | CssVarRef;
+  'scroll-snap-type': string | 'none' | CssVarRef;
+  'scrollbar-width': 'auto' | 'thin' | 'none' | CssVarRef;
+  cursor: 'auto' | 'default' | 'none' | 'context-menu' | 'help' | 'pointer' | 'progress' | 'wait' | 'cell' | 'crosshair' | 'text' | 'vertical-text' | 'alias' | 'copy' | 'move' | 'no-drop' | 'not-allowed' | 'grab' | 'grabbing' | 'all-scroll' | 'col-resize' | 'row-resize' | 'n-resize' | 'e-resize' | 's-resize' | 'w-resize' | 'ne-resize' | 'nw-resize' | 'se-resize' | 'sw-resize' | 'ew-resize' | 'ns-resize' | 'nesw-resize' | 'nwse-resize' | 'zoom-in' | 'zoom-out' | CssValue['url'] | CssVarRef;
+  'pointer-events': 'auto' | 'none' | 'visiblePainted' | 'visibleFill' | 'visibleStroke' | 'visible' | 'painted' | 'fill' | 'stroke' | 'all' | CssVarRef;
+  'user-select': 'none' | 'auto' | 'text' | 'contain' | 'all' | CssVarRef;
+  resize: 'none' | 'both' | 'horizontal' | 'vertical' | 'block' | 'inline' | CssVarRef;
+  appearance: 'none' | 'auto' | 'menulist-button' | 'textfield' | CssVarRef;
+  'touch-action': string | 'auto' | 'none' | 'manipulation' | CssVarRef;
+  'will-change': 'auto' | 'scroll-position' | 'contents' | string | CssVarRef;
+  'z-index': IntegerOrVar | 'auto';
+  'aspect-ratio': CssValue['ratio'] | NumberOrVar | 'auto';
+  'object-fit': 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | CssVarRef;
+  'object-position': string | CssVarRef;
+  'caption-side': 'top' | 'bottom' | 'inline-start' | 'inline-end' | CssVarRef;
+  'border-collapse': 'collapse' | 'separate' | CssVarRef;
+  'table-layout': 'auto' | 'fixed' | CssVarRef;
+};
+type CssPropertyName = keyof CssPropertyValues;
+/**
+ * Standard CSS properties that accept a `<color>` value. Used to gate
+ * the `.withOpacity({...})` builder on `defineStyleProp` — only
+ * color-typed props can pair with an opacity sibling (`bg` +
+ * `bgOpacity` → class `bg-primary_75` etc.).
+ *
+ * Custom CSS properties (`--foo`) authored with `cssType: 'color'` are
+ * also eligible for `.withOpacity()`; that check happens via the
+ * `cssType` generic on `defineStyleProp`, not in this union.
+ */
+type ColorCssProperty = 'background-color' | 'color' | 'text-decoration-color' | 'border-color' | 'border-top-color' | 'border-right-color' | 'border-bottom-color' | 'border-left-color' | 'border-block-color' | 'border-block-start-color' | 'border-block-end-color' | 'border-inline-color' | 'border-inline-start-color' | 'border-inline-end-color' | 'outline-color' | 'caret-color' | 'fill' | 'stroke';
+/**
+ * Re-exported for use in callers that need the CSS-wide keyword union
+ * (`inherit | initial | unset | revert`) on a non-color-typed property.
+ * Not added to {@link CssPropertyValues} entries by default — list locally
+ * if you want them.
+ */
+type CssGlobalKeyword = GlobalKeyword; //#endregion
+//#endregion
+export { ColorCssProperty, CssGlobalKeyword, CssPropertyName, CssPropertyValues };

package/dist/config/dist/types/css-values.d.ts

@@ -25,6 +25,7 @@ type CssPercentage = `${number}%`;
 type CssAngle = `${number}deg` | `${number}rad` | `${number}grad` | `${number}turn`;
 type CssTime = `${number}ms` | `${number}s`;
 type CssRatio = `${number}/${number}`;
+type CssVarRef = `var(--${string})` | `var(--${string}, ${string})`;
 /**
  * Registry of CSS value types, keyed by their spec-defined names.
  *
@@ -58,4 +59,4 @@ type CssValue = {
 };
 type CssValueTypeName = keyof CssValue; //#endregion
 //#endregion
-export { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, HexColor, HslColor, RgbColor };
+export { ColorFn, ColorKeyword, CssAngle, CssColor, CssLength, CssPercentage, CssRatio, CssTime, CssValue, CssValueTypeName, CssVarRef, HexColor, HslColor, RgbColor };

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

@@ -27,15 +27,26 @@ type TokenType = 'color' | 'dimension' | 'number' | 'fontFamily' | 'fontWeight'
  * The optional `$type` annotation lets individual tokens override the group-level
  * type (e.g. a `keyword`-valued token inside a `color` namespace).
  *
+ * `value` accepts a CSS literal (`'#1167f4'`, `'1rem'`, `'transparent'`)
+ * or a `token('namespace/name')` marker pointing at another token —
+ * codegen resolves the marker to `var(--<prefix>-<ns>-<name>)` for the
+ * alias.
+ *
  * @example
  * { value: '#1167f4', _dark: '#88bcfb' }
  * { value: 'transparent', $type: 'string' }
- * { value: '#1167f4', _slate: { value: '#1167f4', _dark: '#88bcfb' } }
+ * { value: token('spectrum/blue-500') }
  */
 type VarTokenDef<M extends `_${string}` = `_${string}`> = {
-  value: string;
+  value: string | {
+    readonly __kind: 'token';
+    readonly ref: string;
+  };
   $type?: TokenType;
-} & { [K in M]?: string | VarTokenDef<M> };
+} & { [K in M]?: string | {
+  readonly __kind: 'token';
+  readonly ref: string;
+} | VarTokenDef<M> };
 /**
  * A group of named tokens within a var namespace.
  *