An open source design system that's fully customizable and agent ready
TypeScript
refactor(theme): extract CSS generation into generateThemeRules.ts (#2498)
Cindy Zhang5cbb1597bb39
diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjsindex 77ac1075db..998e21107f 100644--- a/packages/cli/src/commands/build-theme.mjs+++ b/packages/cli/src/commands/build-theme.mjs@@ -24,6 +24,8 @@ import {ERROR_CODES} from '../lib/error-codes.mjs';// Import shared theme processing from core — ensures build and runtime// use the same logic for typography.scale expansion, prose, and component rules.+// When available, these imports supersede all local fallback implementations+// (parsePadding, expandContainerPadding, parseStyleKey, generateCSS, generateProseCSS).let _defineTheme = null;let _generateThemeRules = null;let _generateThemeRulesSplit = null;@@ -298,6 +300,18 @@ function resolveTokenValue(value) {// =============================================================================// Container padding mapping+//+// LEGACY FALLBACK: The functions below (parsePadding, expandContainerPadding,+// parseStyleKey, generateCSS, generateProseCSS) duplicate logic from+// @xds/core/theme (packages/core/src/theme/generateThemeRules.ts).+//+// When @xds/core is built, the CLI imports and uses the shared implementation+// from core (see _generateThemeRules / _generateThemeRulesSplit at top of file).+// These local copies exist only as a fallback for when core hasn't been built yet+// (e.g., first-time bootstrap or CI environments where core builds after CLI).+//+// TODO: Remove this fallback once the monorepo build order guarantees core+// is always available before CLI runs. Track in issue backlog.// =============================================================================const CONTAINER_COMPONENTS = new Set(['card', 'section', 'dialog']);@@ -457,6 +471,7 @@ const PROSE_COMPONENT_MAP = {/*** Generate CSS from a theme definition object.+ * @deprecated Legacy fallback — see generateThemeRules.ts in @xds/core.** When prose is enabled, component overrides for prose-related components* (heading, text, kbd, link, divider) co-select their HTML elementdiff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.tsindex 661e6a0938..56609bcae2 100644--- a/packages/core/src/theme/defineTheme.ts+++ b/packages/core/src/theme/defineTheme.ts@@ -37,8 +37,6 @@ import {type OnMediaOverrides,type ResolvedOnMedia,} from './onMediaTokens';-import {parseStyleKey} from '../utils/parseStyleKey';-import {getDerivedVars} from './derivedVarRegistry';import {colorDefaults,spacingDefaults,@@ -641,583 +639,18 @@ export function defineTheme(input: XDSDefineThemeInput): XDSDefinedTheme {}// =============================================================================-// CSS generation (used by XDSTheme for unbuilt themes)+// CSS generation — re-exported from ./generateThemeRules.ts// =============================================================================-/**- * Convert camelCase to kebab-case for CSS property names.- * e.g. borderRadius → border-radius, backgroundColor → background-color- */--// =============================================================================-// Container padding mapping-// =============================================================================--/** Padding properties that trigger container token mapping */-const PADDING_PROPS = new Set([- 'padding',- 'paddingBlock',- 'paddingInline',- 'paddingBlockStart',- 'paddingBlockEnd',- 'paddingInlineStart',- 'paddingInlineEnd',-]);--interface ParsedPadding {- blockStart?: string;- blockEnd?: string;- inline?: string;- inlineStart?: string;- inlineEnd?: string;-}--/**- * Parse CSS padding shorthand/longhand into block/inline values.- * Supports 1-3 value shorthands and logical properties.- */-function parsePadding(props: [string, string][]): ParsedPadding {- const result: ParsedPadding = {};-- for (const [prop, value] of props) {- switch (prop) {- case 'padding': {- const parts = value.trim().split(/\s+/);- if (parts.length === 1) {- result.blockStart = parts[0];- result.blockEnd = parts[0];- result.inline = parts[0];- } else if (parts.length === 2) {- result.blockStart = parts[0];- result.blockEnd = parts[0];- result.inline = parts[1];- } else if (parts.length >= 3) {- result.blockStart = parts[0];- result.inline = parts[1];- result.blockEnd = parts[2];- }- break;- }- case 'paddingBlock': {- const parts = value.trim().split(/\s+/);- result.blockStart = parts[0];- result.blockEnd = parts[1] ?? parts[0];- break;- }- case 'paddingInline': {- const parts = value.trim().split(/\s+/);- if (parts.length === 1) {- result.inline = parts[0];- } else {- result.inlineStart = parts[0];- result.inlineEnd = parts[1];- }- break;- }- case 'paddingBlockStart':- result.blockStart = value;- break;- case 'paddingBlockEnd':- result.blockEnd = value;- break;- case 'paddingInlineStart':- result.inlineStart = value;- break;- case 'paddingInlineEnd':- result.inlineEnd = value;- break;- }- }-- return result;-}--/**- * Expand parsed padding into component-scoped public tokens.- *- * Emits --xds-<component>-padding (shorthand) and directional overrides:- * --xds-card-padding: 20px- * --xds-card-padding-inline: 20px- * --xds-card-padding-block-start: 20px- * --xds-card-padding-block-end: 20px- *- * The container.stylex.ts default styles read these via var() fallbacks,- * so the theme CSS sets the value and the component picks it up through- * CSS custom property cascade — no layer competition with StyleX output.- */-function expandContainerPadding(- component: string,- parsed: ParsedPadding,-): [string, string][] {- const prefix = `--xds-${component}-padding`;- const tokens: [string, string][] = [];-- // Resolve effective inline values (inlineStart/End override inline)- const effectiveInlineStart = parsed.inlineStart ?? parsed.inline;- const effectiveInlineEnd = parsed.inlineEnd ?? parsed.inline;- const inlineSymmetric =- effectiveInlineStart != null &&- effectiveInlineEnd != null &&- effectiveInlineStart === effectiveInlineEnd;-- // If all sides are the same, emit the shorthand token only- const allSame =- inlineSymmetric &&- parsed.blockStart != null &&- parsed.blockEnd != null &&- effectiveInlineStart === parsed.blockStart &&- parsed.blockStart === parsed.blockEnd;-- if (allSame) {- tokens.push([prefix, effectiveInlineStart ?? '']);- return tokens;- }-- // Directional tokens- if (parsed.inlineStart != null || parsed.inlineEnd != null) {- // Asymmetric inline — emit start and end separately- if (effectiveInlineStart != null) {- tokens.push([`${prefix}-inline-start`, effectiveInlineStart]);- }- if (effectiveInlineEnd != null) {- tokens.push([`${prefix}-inline-end`, effectiveInlineEnd]);- }- } else if (parsed.inline != null) {- tokens.push([`${prefix}-inline`, parsed.inline]);- }- if (parsed.blockStart != null) {- tokens.push([`${prefix}-block-start`, parsed.blockStart]);- }- if (parsed.blockEnd != null) {- tokens.push([`${prefix}-block-end`, parsed.blockEnd]);- }-- return tokens;-}--function toKebabCase(str: string): string {- return str.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);-}--/**- * Generate CSS rules for a defined theme.- * Includes token overrides and component style overrides.- */-/**- * Generate the intermediary CSS rules for a theme.- *- * Returns an array of CSS rule strings — the shared format used by both- * the runtime path (useInsertionEffect) and the build path (xds theme build).- *- * Options:- * - computedValues: when true, prose rules use computed px values from tokens- * (for the build path where CSS must be self-contained).- * When false (default), prose rules use var() references to token custom properties- * (for the runtime path where tokens are set on :scope).- */-export function generateThemeRules(theme: XDSDefinedTheme): string[] {- const parts: string[] = [];- const tokens = theme.tokens;-- // Helper: resolve a token value — tokens always have computed values- // since defineTheme runs expandTypeScale to produce them.- const val = (key: string): string => tokens[key] || `var(${key})`;-- // 1. Token block — CSS custom properties on :scope- const tokenEntries = Object.entries(tokens);- if (tokenEntries.length > 0) {- const declarations = tokenEntries- .map(([prop, value]) => ` ${prop}: ${value};`)- .join('\n');- parts.push(` :scope {\n${declarations}\n }`);- }-- // 2. Component overrides (.xds-* class rules)- if (theme.components) {- for (const [component, rules] of Object.entries(theme.components)) {- for (const [key, styles] of Object.entries(- rules as Record<- string,- Record<string, string | Record<string, string>>- >,- )) {- const entries = Object.entries(styles);- if (entries.length > 0) {- const suffix = parseStyleKey(key);- const baseSelector = `.xds-${component}${suffix}`;-- // Separate regular properties from pseudo-class overrides- const props: [string, string][] = [];- const pseudos: [string, Record<string, string>][] = [];-- for (const [prop, value] of entries) {- if (prop.startsWith(':') && typeof value === 'object') {- pseudos.push([prop, value]);- } else {- props.push([prop, value as string]);- }- }-- // Derived var expansion: for each CSS property, check if the- // component has derived var entries and emit additional declarations.- // Entries are processed in order (priority).- // - `vars`: emit internal CSS custom property declarations- // - `expand: 'container'`: expand padding to container layout tokens- let finalProps = props;- const derivedProps: [string, string][] = [];- let containerExpanded = false;-- for (const [prop, value] of props) {- const derived = getDerivedVars(component, prop);- // Padding longhands (paddingBlock, paddingInline, etc.) also- // match the 'padding' derived entry for container expansion.- const paddingDerived =- PADDING_PROPS.has(prop) && prop !== 'padding'- ? getDerivedVars(component, 'padding')- : [];- for (const entry of [...derived, ...paddingDerived]) {- if (entry.expand === 'container' && PADDING_PROPS.has(prop)) {- containerExpanded = true;- }- if (entry.vars) {- for (const varName of entry.vars) {- derivedProps.push([varName, value]);- }- }- }- }-- // Container padding expansion: replace padding props with- // component-scoped container tokens for layout integration.- if (containerExpanded) {- const paddingProps = props.filter(([p]) => PADDING_PROPS.has(p));- const nonPaddingProps = props.filter(- ([p]) => !PADDING_PROPS.has(p),- );- const parsed = parsePadding(paddingProps);- const containerTokens = expandContainerPadding(component, parsed);- finalProps = [...nonPaddingProps, ...containerTokens];- }-- if (derivedProps.length > 0) {- finalProps = [...finalProps, ...derivedProps];- }-- // Emit base rule- if (finalProps.length > 0) {- const declarations = finalProps- .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)- .join('\n');- parts.push(` ${baseSelector} {\n${declarations}\n }`);- }-- // Emit pseudo-class rules- for (const [pseudo, pseudoStyles] of pseudos) {- const pseudoEntries = Object.entries(pseudoStyles);- if (pseudoEntries.length > 0) {- const declarations = pseudoEntries- .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)- .join('\n');- parts.push(` ${baseSelector}${pseudo} {\n${declarations}\n }`);- }- }- }- }- }- }-- // 3. Prose HTML element rules (h1-h6, p, small, code, hr)- //- // Default styles for bare HTML elements inside a themed scope.- // Wrapped in :where() for zero specificity — these are defaults that- // any class-based style (StyleX, .xds-* overrides) should beat.- // The caller places these in the reset layer (not xds-theme) so they- // sit below all component styles in the cascade.- parts.push(` :where(h1, h2, h3, h4, h5, h6) {- font-family: var(--font-family-heading);- color: var(--color-text-primary);- }`);-- for (let level = 1; level <= 6; level++) {- parts.push(` :where(h${level}) {- font-size: ${val(`--text-heading-${level}-size`)};- font-weight: ${val(`--text-heading-${level}-weight`)};- line-height: ${val(`--text-heading-${level}-leading`)};- }`);- }-- parts.push(` :where(p) {- font-family: var(--font-family-heading);- font-size: ${val('--text-body-size')};- font-weight: ${val('--text-body-weight')};- line-height: ${val('--text-body-leading')};- color: var(--color-text-primary);- }`);-- parts.push(` :where(small) {- font-size: ${val('--text-supporting-size')};- font-weight: ${val('--text-supporting-weight')};- line-height: ${val('--text-supporting-leading')};- color: var(--color-text-secondary);- }`);-- parts.push(` :where(code, pre) {- font-family: var(--font-family-code);- font-size: ${val('--text-code-size')};- line-height: ${val('--text-code-leading')};- }`);-- parts.push(` :where(hr) {- border: none;- border-top: 1px solid var(--color-border);- }`);-- // 4. Prop-level color overrides (for text/heading/link specificity)- const TEXT_COLOR_MAP: Record<string, string> = {- primary: 'var(--color-text-primary)',- secondary: 'var(--color-text-secondary)',- disabled: 'var(--color-text-disabled)',- placeholder: 'var(--color-text-secondary)',- active: 'var(--color-accent)',- };-- const components = theme.components || {};- const touchesText = 'text' in components;- const touchesHeading = 'heading' in components;- const touchesLink = 'link' in components;-- if (touchesText || touchesHeading || touchesLink) {- for (const [colorName, colorValue] of Object.entries(TEXT_COLOR_MAP)) {- if (touchesText) {- parts.push(` .xds-text.${colorName} { color: ${colorValue}; }`);- }- if (touchesHeading) {- parts.push(` .xds-heading.${colorName} { color: ${colorValue}; }`);- }- if (touchesLink) {- parts.push(` .xds-link.${colorName} { color: ${colorValue}; }`);- }- }- }-- // (on-media rules are generated separately -- see generateOnMediaCSS)-- return parts;-}--/**- * Structured output from generateThemeRulesSplit.- * Separates prose element defaults from component/token overrides- * so callers can place them in different CSS layers.- */-export interface ThemeRulesSplit {- /** Token overrides + component .xds-* overrides + prop-level color rules */- component: string[];- /** Prose element defaults (h1-h6, p, small, code, hr) — belongs in reset layer */- prose: string[];-}--/**- * Generate theme rules split into component and prose groups.- *- * Prose element rules (h1-h6, p, small, code, hr) style bare HTML elements- * as themed defaults — conceptually the same tier as the CSS reset. They- * belong in the reset layer so any class-based style wins.- *- * Component rules (tokens, .xds-* overrides) are intentional theme overrides- * that need to beat StyleX — they stay in xds-theme (above StyleX layers).- */-export function generateThemeRulesSplit(- theme: XDSDefinedTheme,-): ThemeRulesSplit {- const allRules = generateThemeRules(theme);-- const prose: string[] = [];- const component: string[] = [];-- for (const rule of allRules) {- if (rule.trimStart().startsWith(':where(')) {- prose.push(rule);- } else {- component.push(rule);- }- }-- return {component, prose};-}--/**- * Generate the full CSS string for a theme — runtime path.- *- * Produces two layer blocks:- * - `@layer reset`: Prose element defaults (p, h1-h6, small, code, hr) scoped- * to the theme. These sit at reset-layer priority so any class-based style- * (StyleX, .xds-* overrides) wins. Uses :where() for zero specificity.- * - Unlayered: Token overrides + component .xds-* overrides. The caller- * (XDSTheme.tsx) wraps this in @layer xds-theme, which sits above StyleX- * layers so theme component overrides take effect.- */-/**- * Output from generateThemeCSS — two CSS blocks for different layers.- */-export interface ThemeCSSOutput {- /**- * Prose element defaults (p, h1-h6, small, code, hr) scoped to the theme.- * Should be injected into @layer reset — lowest priority, any class wins.- * Empty string if no prose rules.- */- prose: string;- /**- * Token overrides + component .xds-* overrides scoped to the theme.- * Should be injected into @layer xds-theme — above StyleX layers so- * theme component overrides take effect. Empty string if no rules.- */- component: string;-}--/**- * Generate layered CSS for a theme — runtime path.- *- * Returns two CSS blocks for injection into different layers:- * - `prose`: @scope'd element defaults → inject into @layer reset- * - `component`: @scope'd token + .xds-* overrides → inject into @layer xds-theme- *- * This separation ensures prose defaults (what bare HTML looks like in a theme)- * sit at reset-layer priority where any class-based style wins, while component- * overrides sit above StyleX so themes can restyle components intentionally.- */--// =============================================================================-// On-media CSS generation-// =============================================================================--/**- * Generate CSS for on-media token and component overrides.- *- * Emitted in an unbounded @scope (no `to` limit) so the rules can reach- * [data-xds-media] elements. Parent theme component overrides flow through- * to media contexts -- only tokens change. Themes can further customize- * via onDark.components / onLight.components.- */-export function generateOnMediaCSS(theme: XDSDefinedTheme): string {- const parts: string[] = [];- const scopeSelector = `[data-xds-theme="${theme.name}"]`;-- for (const surface of ['dark', 'light'] as const) {- const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;- if (!onMedia) {- continue;- }-- // Token overrides- const tokenEntries = Object.entries(onMedia.tokens);- if (tokenEntries.length > 0) {- const declarations = tokenEntries- .map(([prop, value]) => ` ${prop}: ${value};`)- .join('\n');- parts.push(` [data-xds-media="${surface}"] {\n${declarations}\n }`);- }-- // Component overrides- if (onMedia.components) {- for (const [component, rules] of Object.entries(onMedia.components)) {- for (const [key, styles] of Object.entries(- rules as Record<- string,- Record<string, string | Record<string, string>>- >,- )) {- const entries = Object.entries(styles);- if (entries.length > 0) {- const suffix = parseStyleKey(key);- const baseSelector = `[data-xds-media="${surface}"] .xds-${component}${suffix}`;-- const props: [string, string][] = [];- const pseudos: [string, Record<string, string>][] = [];-- for (const [prop, value] of entries) {- if (prop.startsWith(':') && typeof value === 'object') {- pseudos.push([prop, value]);- } else {- props.push([prop, value as string]);- }- }-- if (props.length > 0) {- const declarations = props- .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)- .join('\n');- parts.push(` ${baseSelector} {\n${declarations}\n }`);- }-- for (const [pseudo, pseudoStyles] of pseudos) {- const pseudoEntries = Object.entries(pseudoStyles);- if (pseudoEntries.length > 0) {- const declarations = pseudoEntries- .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)- .join('\n');- parts.push(- ` ${baseSelector}${pseudo} {\n${declarations}\n }`,- );- }- }- }- }- }- }- }-- if (parts.length === 0) {- return '';- }-- const inner = parts.join('\n\n');- return `@scope (${scopeSelector}) to ([data-xds-theme]) {\n${inner}\n}`;-}--export function generateThemeCSS(theme: XDSDefinedTheme): ThemeCSSOutput {- const {component, prose} = generateThemeRulesSplit(theme);- const scopeSelector = `[data-xds-theme="${theme.name}"]`;- const scopeTo = `[data-xds-theme]`;-- let proseCss = '';- if (prose.length > 0) {- const proseInner = prose.join('\n\n');- proseCss = `@scope (${scopeSelector}) to (${scopeTo}) {\n${proseInner}\n}`;- }-- // Component rules: bounded scope (stops at nested themes) +- // on-media rules in unbounded scope (can reach [data-xds-media] elements)- let componentCss = '';- if (component.length > 0) {- const componentInner = component.join('\n\n');- componentCss = `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`;- }-- const onMediaCss = generateOnMediaCSS(theme);- if (onMediaCss) {- componentCss = componentCss- ? `${componentCss}\n\n${onMediaCss}`- : onMediaCss;- }-- return {prose: proseCss, component: componentCss};-}--/**- * Generate the full CSS string for a theme as a single string.- * @deprecated Use generateThemeCSS() which returns { prose, component } for proper layering.- * This flat version is kept for backwards compatibility with tests and simple cases.- */-export function generateThemeCSSFlat(theme: XDSDefinedTheme): string {- const rules = generateThemeRules(theme);- if (rules.length === 0) {- return '';- }- const scopeSelector = `[data-xds-theme="${theme.name}"]`;- const inner = rules.join('\n\n');- return `@scope (${scopeSelector}) to ([data-xds-theme]) {\n${inner}\n}`;-}+export {+ generateThemeRules,+ generateThemeRulesSplit,+ generateOnMediaCSS,+ generateThemeCSS,+ generateThemeCSSFlat,+ type ThemeRulesSplit,+ type ThemeCSSOutput,+} from './generateThemeRules';// =============================================================================// Type guarddiff --git a/packages/core/src/theme/generateThemeRules.ts b/packages/core/src/theme/generateThemeRules.tsnew file mode 100644index 0000000000..bbcee81a98--- /dev/null+++ b/packages/core/src/theme/generateThemeRules.ts@@ -0,0 +1,598 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Theme CSS generation utilities+ *+ * Shared logic for generating CSS rules from a resolved theme definition.+ * Used by both the runtime path (XDSTheme injects <style>) and the build+ * path (`xds theme build` pre-compiles to CSS files).+ *+ * Extracted from defineTheme.ts to reduce cyclomatic complexity and provide+ * a clear single-responsibility module for CSS generation.+ *+ * @input XDSDefinedTheme (resolved theme object from defineTheme)+ * @output CSS rule strings, split by layer (component vs prose)+ * @position packages/core/src/theme/generateThemeRules.ts+ */++import type {XDSDefinedTheme} from './defineTheme';+import {parseStyleKey} from '../utils/parseStyleKey';+import {getDerivedVars} from './derivedVarRegistry';++// =============================================================================+// Types+// =============================================================================++/**+ * Structured output from generateThemeRulesSplit.+ * Separates prose element defaults from component/token overrides+ * so callers can place them in different CSS layers.+ */+export interface ThemeRulesSplit {+ /** Token overrides + component .xds-* overrides + prop-level color rules */+ component: string[];+ /** Prose element defaults (h1-h6, p, small, code, hr) — belongs in reset layer */+ prose: string[];+}++/**+ * Output from generateThemeCSS — two CSS blocks for different layers.+ */+export interface ThemeCSSOutput {+ /**+ * Prose element defaults (p, h1-h6, small, code, hr) scoped to the theme.+ * Should be injected into @layer reset — lowest priority, any class wins.+ * Empty string if no prose rules.+ */+ prose: string;+ /**+ * Token overrides + component .xds-* overrides scoped to the theme.+ * Should be injected into @layer xds-theme — above StyleX layers so+ * theme component overrides take effect. Empty string if no rules.+ */+ component: string;+}++// =============================================================================+// Internal helpers+// =============================================================================++/** Convert camelCase CSS property to kebab-case */+function toKebabCase(str: string): string {+ return str.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);+}++/** Padding properties that trigger container token mapping */+const PADDING_PROPS = new Set([+ 'padding',+ 'paddingBlock',+ 'paddingInline',+ 'paddingBlockStart',+ 'paddingBlockEnd',+ 'paddingInlineStart',+ 'paddingInlineEnd',+]);++interface ParsedPadding {+ blockStart?: string;+ blockEnd?: string;+ inline?: string;+ inlineStart?: string;+ inlineEnd?: string;+}++/**+ * Parse CSS padding shorthand/longhand into block/inline values.+ * Supports 1-3 value shorthands and logical properties.+ */+function parsePadding(props: [string, string][]): ParsedPadding {+ const result: ParsedPadding = {};++ for (const [prop, value] of props) {+ switch (prop) {+ case 'padding': {+ const parts = value.trim().split(/\s+/);+ if (parts.length === 1) {+ result.blockStart = parts[0];+ result.blockEnd = parts[0];+ result.inline = parts[0];+ } else if (parts.length === 2) {+ result.blockStart = parts[0];+ result.blockEnd = parts[0];+ result.inline = parts[1];+ } else if (parts.length >= 3) {+ result.blockStart = parts[0];+ result.inline = parts[1];+ result.blockEnd = parts[2];+ }+ break;+ }+ case 'paddingBlock': {+ const parts = value.trim().split(/\s+/);+ result.blockStart = parts[0];+ result.blockEnd = parts[1] ?? parts[0];+ break;+ }+ case 'paddingInline': {+ const parts = value.trim().split(/\s+/);+ if (parts.length === 1) {+ result.inline = parts[0];+ } else {+ result.inlineStart = parts[0];+ result.inlineEnd = parts[1];+ }+ break;+ }+ case 'paddingBlockStart':+ result.blockStart = value;+ break;+ case 'paddingBlockEnd':+ result.blockEnd = value;+ break;+ case 'paddingInlineStart':+ result.inlineStart = value;+ break;+ case 'paddingInlineEnd':+ result.inlineEnd = value;+ break;+ }+ }++ return result;+}++/**+ * Expand parsed padding into component-scoped public tokens.+ *+ * Emits --xds-<component>-padding (shorthand) and directional overrides:+ * --xds-card-padding: 20px+ * --xds-card-padding-inline: 20px+ * --xds-card-padding-block-start: 20px+ * --xds-card-padding-block-end: 20px+ *+ * The container.stylex.ts default styles read these via var() fallbacks,+ * so the theme CSS sets the value and the component picks it up through+ * CSS custom property cascade — no layer competition with StyleX output.+ */+function expandContainerPadding(+ component: string,+ parsed: ParsedPadding,+): [string, string][] {+ const prefix = `--xds-${component}-padding`;+ const tokens: [string, string][] = [];++ // Resolve effective inline values (inlineStart/End override inline)+ const effectiveInlineStart = parsed.inlineStart ?? parsed.inline;+ const effectiveInlineEnd = parsed.inlineEnd ?? parsed.inline;+ const inlineSymmetric =+ effectiveInlineStart != null &&+ effectiveInlineEnd != null &&+ effectiveInlineStart === effectiveInlineEnd;++ // If all sides are the same, emit the shorthand token only+ const allSame =+ inlineSymmetric &&+ parsed.blockStart != null &&+ parsed.blockEnd != null &&+ effectiveInlineStart === parsed.blockStart &&+ parsed.blockStart === parsed.blockEnd;++ if (allSame) {+ tokens.push([prefix, effectiveInlineStart ?? '']);+ return tokens;+ }++ // Directional tokens+ if (parsed.inlineStart != null || parsed.inlineEnd != null) {+ // Asymmetric inline — emit start and end separately+ if (effectiveInlineStart != null) {+ tokens.push([`${prefix}-inline-start`, effectiveInlineStart]);+ }+ if (effectiveInlineEnd != null) {+ tokens.push([`${prefix}-inline-end`, effectiveInlineEnd]);+ }+ } else if (parsed.inline != null) {+ tokens.push([`${prefix}-inline`, parsed.inline]);+ }+ if (parsed.blockStart != null) {+ tokens.push([`${prefix}-block-start`, parsed.blockStart]);+ }+ if (parsed.blockEnd != null) {+ tokens.push([`${prefix}-block-end`, parsed.blockEnd]);+ }++ return tokens;+}++// =============================================================================+// Public API+// =============================================================================++/**+ * Generate the intermediary CSS rules for a theme.+ *+ * Returns an array of CSS rule strings — the shared format used by both+ * the runtime path (useInsertionEffect) and the build path (xds theme build).+ */+export function generateThemeRules(theme: XDSDefinedTheme): string[] {+ const parts: string[] = [];+ const tokens = theme.tokens;++ // Helper: resolve a token value — tokens always have computed values+ // since defineTheme runs expandTypeScale to produce them.+ const val = (key: string): string => tokens[key] || `var(${key})`;++ // 1. Token block — CSS custom properties on :scope+ const tokenEntries = Object.entries(tokens);+ if (tokenEntries.length > 0) {+ const declarations = tokenEntries+ .map(([prop, value]) => ` ${prop}: ${value};`)+ .join('\n');+ parts.push(` :scope {\n${declarations}\n }`);+ }++ // 2. Component overrides (.xds-* class rules)+ if (theme.components) {+ generateComponentRules(theme.components, parts);+ }++ // 3. Prose HTML element rules (h1-h6, p, small, code, hr)+ generateProseRules(val, parts);++ // 4. Prop-level color overrides (for text/heading/link specificity)+ generateColorOverrides(theme.components || {}, parts);++ // (on-media rules are generated separately — see generateOnMediaCSS)++ return parts;+}++/**+ * Generate component .xds-* class override rules.+ * Handles derived var expansion and container padding mapping.+ */+function generateComponentRules(+ components: Record<+ string,+ Record<string, Record<string, string | Record<string, string>>>+ >,+ parts: string[],+): void {+ for (const [component, rules] of Object.entries(components)) {+ for (const [key, styles] of Object.entries(+ rules,+ )) {+ const entries = Object.entries(styles);+ if (entries.length === 0) {continue;}++ const suffix = parseStyleKey(key);+ const baseSelector = `.xds-${component}${suffix}`;++ // Separate regular properties from pseudo-class overrides+ const props: [string, string][] = [];+ const pseudos: [string, Record<string, string>][] = [];++ for (const [prop, value] of entries) {+ if (prop.startsWith(':') && typeof value === 'object') {+ pseudos.push([prop, value]);+ } else {+ props.push([prop, value as string]);+ }+ }++ // Derived var expansion: for each CSS property, check if the+ // component has derived var entries and emit additional declarations.+ // Entries are processed in order (priority).+ // - `vars`: emit internal CSS custom property declarations+ // - `expand: 'container'`: expand padding to container layout tokens+ let finalProps = props;+ const derivedProps: [string, string][] = [];+ let containerExpanded = false;++ for (const [prop, value] of props) {+ const derived = getDerivedVars(component, prop);+ // Padding longhands (paddingBlock, paddingInline, etc.) also+ // match the 'padding' derived entry for container expansion.+ const paddingDerived =+ PADDING_PROPS.has(prop) && prop !== 'padding'+ ? getDerivedVars(component, 'padding')+ : [];+ for (const entry of [...derived, ...paddingDerived]) {+ if (entry.expand === 'container' && PADDING_PROPS.has(prop)) {+ containerExpanded = true;+ }+ if (entry.vars) {+ for (const varName of entry.vars) {+ derivedProps.push([varName, value]);+ }+ }+ }+ }++ // Container padding expansion: replace padding props with+ // component-scoped container tokens for layout integration.+ if (containerExpanded) {+ const paddingProps = props.filter(([p]) => PADDING_PROPS.has(p));+ const nonPaddingProps = props.filter(([p]) => !PADDING_PROPS.has(p));+ const parsed = parsePadding(paddingProps);+ const containerTokens = expandContainerPadding(component, parsed);+ finalProps = [...nonPaddingProps, ...containerTokens];+ }++ if (derivedProps.length > 0) {+ finalProps = [...finalProps, ...derivedProps];+ }++ // Emit base rule+ if (finalProps.length > 0) {+ const declarations = finalProps+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)+ .join('\n');+ parts.push(` ${baseSelector} {\n${declarations}\n }`);+ }++ // Emit pseudo-class rules+ for (const [pseudo, pseudoStyles] of pseudos) {+ const pseudoEntries = Object.entries(pseudoStyles);+ if (pseudoEntries.length > 0) {+ const declarations = pseudoEntries+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)+ .join('\n');+ parts.push(` ${baseSelector}${pseudo} {\n${declarations}\n }`);+ }+ }+ }+ }+}++/**+ * Generate prose HTML element default rules (h1-h6, p, small, code, hr).+ * Wrapped in :where() for zero specificity — these are defaults that+ * any class-based style (StyleX, .xds-* overrides) should beat.+ * The caller places these in the reset layer (not xds-theme) so they+ * sit below all component styles in the cascade.+ */+function generateProseRules(+ val: (key: string) => string,+ parts: string[],+): void {+ parts.push(` :where(h1, h2, h3, h4, h5, h6) {+ font-family: var(--font-family-heading);+ color: var(--color-text-primary);+ }`);++ for (let level = 1; level <= 6; level++) {+ parts.push(` :where(h${level}) {+ font-size: ${val(`--text-heading-${level}-size`)};+ font-weight: ${val(`--text-heading-${level}-weight`)};+ line-height: ${val(`--text-heading-${level}-leading`)};+ }`);+ }++ parts.push(` :where(p) {+ font-family: var(--font-family-heading);+ font-size: ${val('--text-body-size')};+ font-weight: ${val('--text-body-weight')};+ line-height: ${val('--text-body-leading')};+ color: var(--color-text-primary);+ }`);++ parts.push(` :where(small) {+ font-size: ${val('--text-supporting-size')};+ font-weight: ${val('--text-supporting-weight')};+ line-height: ${val('--text-supporting-leading')};+ color: var(--color-text-secondary);+ }`);++ parts.push(` :where(code, pre) {+ font-family: var(--font-family-code);+ font-size: ${val('--text-code-size')};+ line-height: ${val('--text-code-leading')};+ }`);++ parts.push(` :where(hr) {+ border: none;+ border-top: 1px solid var(--color-border);+ }`);+}++/**+ * Generate prop-level color override rules for text/heading/link components.+ * These ensure color prop classes override theme token changes.+ */+function generateColorOverrides(+ components: Record<string, unknown>,+ parts: string[],+): void {+ const TEXT_COLOR_MAP: Record<string, string> = {+ primary: 'var(--color-text-primary)',+ secondary: 'var(--color-text-secondary)',+ disabled: 'var(--color-text-disabled)',+ placeholder: 'var(--color-text-secondary)',+ active: 'var(--color-accent)',+ };++ const touchesText = 'text' in components;+ const touchesHeading = 'heading' in components;+ const touchesLink = 'link' in components;++ if (touchesText || touchesHeading || touchesLink) {+ for (const [colorName, colorValue] of Object.entries(TEXT_COLOR_MAP)) {+ if (touchesText) {+ parts.push(` .xds-text.${colorName} { color: ${colorValue}; }`);+ }+ if (touchesHeading) {+ parts.push(` .xds-heading.${colorName} { color: ${colorValue}; }`);+ }+ if (touchesLink) {+ parts.push(` .xds-link.${colorName} { color: ${colorValue}; }`);+ }+ }+ }+}++/**+ * Generate theme rules split into component and prose groups.+ *+ * Prose element rules (h1-h6, p, small, code, hr) style bare HTML elements+ * as themed defaults — conceptually the same tier as the CSS reset. They+ * belong in the reset layer so any class-based style wins.+ *+ * Component rules (tokens, .xds-* overrides) are intentional theme overrides+ * that need to beat StyleX — they stay in xds-theme (above StyleX layers).+ */+export function generateThemeRulesSplit(+ theme: XDSDefinedTheme,+): ThemeRulesSplit {+ const allRules = generateThemeRules(theme);++ const prose: string[] = [];+ const component: string[] = [];++ for (const rule of allRules) {+ if (rule.trimStart().startsWith(':where(')) {+ prose.push(rule);+ } else {+ component.push(rule);+ }+ }++ return {component, prose};+}++/**+ * Generate CSS for on-media token and component overrides.+ *+ * Emitted in an unbounded @scope (no `to` limit) so the rules can reach+ * [data-xds-media] elements. Parent theme component overrides flow through+ * to media contexts — only tokens change. Themes can further customize+ * via onDark.components / onLight.components.+ */+export function generateOnMediaCSS(theme: XDSDefinedTheme): string {+ const parts: string[] = [];+ const scopeSelector = `[data-xds-theme="${theme.name}"]`;++ for (const surface of ['dark', 'light'] as const) {+ const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;+ if (!onMedia) {+ continue;+ }++ // Token overrides+ const tokenEntries = Object.entries(onMedia.tokens);+ if (tokenEntries.length > 0) {+ const declarations = tokenEntries+ .map(([prop, value]) => ` ${prop}: ${value};`)+ .join('\n');+ parts.push(` [data-xds-media="${surface}"] {\n${declarations}\n }`);+ }++ // Component overrides+ if (onMedia.components) {+ for (const [component, rules] of Object.entries(onMedia.components)) {+ for (const [key, styles] of Object.entries(+ rules as Record<+ string,+ Record<string, string | Record<string, string>>+ >,+ )) {+ const entries = Object.entries(styles);+ if (entries.length === 0) {continue;}++ const suffix = parseStyleKey(key);+ const baseSelector = `[data-xds-media="${surface}"] .xds-${component}${suffix}`;++ const props: [string, string][] = [];+ const pseudos: [string, Record<string, string>][] = [];++ for (const [prop, value] of entries) {+ if (prop.startsWith(':') && typeof value === 'object') {+ pseudos.push([prop, value]);+ } else {+ props.push([prop, value as string]);+ }+ }++ if (props.length > 0) {+ const declarations = props+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)+ .join('\n');+ parts.push(` ${baseSelector} {\n${declarations}\n }`);+ }++ for (const [pseudo, pseudoStyles] of pseudos) {+ const pseudoEntries = Object.entries(pseudoStyles);+ if (pseudoEntries.length > 0) {+ const declarations = pseudoEntries+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)+ .join('\n');+ parts.push(` ${baseSelector}${pseudo} {\n${declarations}\n }`);+ }+ }+ }+ }+ }+ }++ if (parts.length === 0) {+ return '';+ }++ const inner = parts.join('\n\n');+ return `@scope (${scopeSelector}) to ([data-xds-theme]) {\n${inner}\n}`;+}++/**+ * Generate layered CSS for a theme — runtime path.+ *+ * Returns two CSS blocks for injection into different layers:+ * - `prose`: @scope'd element defaults → inject into @layer reset+ * - `component`: @scope'd token + .xds-* overrides → inject into @layer xds-theme+ *+ * This separation ensures prose defaults (what bare HTML looks like in a theme)+ * sit at reset-layer priority where any class-based style wins, while component+ * overrides sit above StyleX so themes can restyle components intentionally.+ */+export function generateThemeCSS(theme: XDSDefinedTheme): ThemeCSSOutput {+ const {component, prose} = generateThemeRulesSplit(theme);+ const scopeSelector = `[data-xds-theme="${theme.name}"]`;+ const scopeTo = `[data-xds-theme]`;++ let proseCss = '';+ if (prose.length > 0) {+ const proseInner = prose.join('\n\n');+ proseCss = `@scope (${scopeSelector}) to (${scopeTo}) {\n${proseInner}\n}`;+ }++ // Component rules: bounded scope (stops at nested themes) ++ // on-media rules in unbounded scope (can reach [data-xds-media] elements)+ let componentCss = '';+ if (component.length > 0) {+ const componentInner = component.join('\n\n');+ componentCss = `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`;+ }++ const onMediaCss = generateOnMediaCSS(theme);+ if (onMediaCss) {+ componentCss = componentCss+ ? `${componentCss}\n\n${onMediaCss}`+ : onMediaCss;+ }++ return {prose: proseCss, component: componentCss};+}++/**+ * Generate the full CSS string for a theme as a single string.+ * @deprecated Use generateThemeCSS() which returns { prose, component } for proper layering.+ * This flat version is kept for backwards compatibility with tests and simple cases.+ */+export function generateThemeCSSFlat(theme: XDSDefinedTheme): string {+ const rules = generateThemeRules(theme);+ if (rules.length === 0) {+ return '';+ }+ const scopeSelector = `[data-xds-theme="${theme.name}"]`;+ const inner = rules.join('\n\n');+ return `@scope (${scopeSelector}) to ([data-xds-theme]) {\n${inner}\n}`;+}