An open source design system that's fully customizable and agent ready
TypeScript
feat(theme): component-scoped container padding tokens (#1235)
Cindy Zhangfc745b9c9a59
diff --git a/apps/storybook/.storybook/main.ts b/apps/storybook/.storybook/main.tsindex 23cafa180e..cd2888c46c 100644--- a/apps/storybook/.storybook/main.ts+++ b/apps/storybook/.storybook/main.ts@@ -76,7 +76,7 @@ const config: StorybookConfig = {{tag: 'style',children:- '@layer reset, priority1, priority2, priority3, priority4, priority5, priority6, priority7, priority8, priority9;',+ '@layer reset, priority1, priority2, priority3, priority4, priority5, priority6, priority7, priority8, priority9, xds-theme;',injectTo: 'head-prepend',},{diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjsindex a9559f1bdb..22cf96836b 100644--- a/packages/cli/src/commands/build-theme.mjs+++ b/packages/cli/src/commands/build-theme.mjs@@ -265,6 +265,118 @@ function resolveTokenValue(value) {* <!-- SYNC: packages/core/src/utils/xdsClassName.ts -->* The digit-prefix and value-to-class logic must match across all three files.*/++// =============================================================================+// Container padding mapping+// =============================================================================++const CONTAINER_COMPONENTS = new Set(['card', 'section', 'dialog']);+const PADDING_PROPS = new Set([+ 'padding', 'paddingBlock', 'paddingInline',+ 'paddingBlockStart', 'paddingBlockEnd',+ 'paddingInlineStart', 'paddingInlineEnd',+]);++function parsePadding(props) {+ const result = {};+ 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;+}++function expandContainerPadding(component, parsed) {+ const prefix = `--xds-${component}-padding`;+ const tokens = [];++ // 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 parseStyleKey(key) {if (key === 'base') return '';return key@@ -364,9 +476,21 @@ function generateCSS(themeDef, {prose = true} = {}) {}}+ // Container padding mapping+ let finalProps = props;+ if (CONTAINER_COMPONENTS.has(component)) {+ const paddingProps = props.filter(([p]) => PADDING_PROPS.has(p));+ if (paddingProps.length > 0) {+ const nonPaddingProps = props.filter(([p]) => !PADDING_PROPS.has(p));+ const parsed = parsePadding(paddingProps);+ const containerTokens = expandContainerPadding(component, parsed);+ finalProps = [...nonPaddingProps, ...containerTokens];+ }+ }+// Emit base rule- if (props.length > 0) {- const declarations = props+ if (finalProps.length > 0) {+ const declarations = finalProps.map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`).join('\n');parts.push(`${baseSelector} {\n${declarations}\n }`);diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex 027b7b81be..216fdeaae4 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -108,6 +108,7 @@ export const docs = {},],theming: {+ container: true,targets: [{className: 'xds-card'},],@@ -116,9 +117,9 @@ export const docs = {],cssProperties: [{- name: '--xds-card-padding',+ name: 'padding',description:- "Controls Card container padding. Set in theme component overrides via `card: { base: { '--xds-card-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",+ "Controls Card container padding. Accepts standard CSS padding shorthand (e.g. '16px 20px'). Automatically mapped to container tokens for layout integration. Supports paddingBlock/paddingInline for axis-specific control.",default: 'var(--spacing-4)',},],@@ -234,6 +235,7 @@ export const docsZh = {},],theming: {+ container: true,targets: [{className: 'xds-card'},],@@ -242,9 +244,9 @@ export const docsZh = {],cssProperties: [{- name: '--xds-card-padding',+ name: 'padding',description:- "Controls Card container padding. Set in theme component overrides via `card: { base: { '--xds-card-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",+ "Controls Card container padding. Accepts standard CSS padding shorthand (e.g. '16px 20px'). Automatically mapped to container tokens for layout integration. Supports paddingBlock/paddingInline for axis-specific control.",default: 'var(--spacing-4)',},],diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsxindex 3c39da9384..767990321d 100644--- a/packages/core/src/Card/XDSCard.tsx+++ b/packages/core/src/Card/XDSCard.tsx@@ -60,23 +60,17 @@ export type XDSCardVariant =// =============================================================================const styles = stylex.create({- // Outer wrapper: visual styling with clip for border-radius- cardOuter: {+ card: {'--card-radius': radiusVars['--radius-container'],borderRadius: 'var(--card-radius)',overflow: 'clip',},- // Border only for the default variantwithBorder: {borderWidth: borderVars['--border-width'],borderStyle: 'solid',borderColor: colorVars['--color-border-emphasized'],},- // Inner wrapper: container padding and overflow handling- cardInner: {- height: '100%',- },- // Only enable scrolling when card has fixed height+ // Fixed-height cards scroll content; overflow: auto also clips to border-radiusscrollable: {overflow: 'auto',},@@ -247,7 +241,7 @@ export function XDSCard({// Only enable scrolling when card has a fixed height (not null/undefined and not "auto")const hasFixedHeight = height != null && height !== 'auto';- // When no explicit padding prop, use theme default (--xds-card-padding)+ // When no explicit padding prop, use theme default (set via container tokens)const useThemeDefault = padding == null;const effectivePadding = padding ?? 4;const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;@@ -258,25 +252,16 @@ export function XDSCard({{...mergeProps(xdsClassName('card', {variant}),stylex.props(- styles.cardOuter,+ styles.card,variantStyles[variant],variant === 'default' && styles.withBorder,+ hasFixedHeight && styles.scrollable,dynamicStyles.sizing(width ?? null,height ?? null,maxWidth ?? null,minHeight ?? null,),- xstyle,- ),- className,- style,- )}- {...props}>- <div- {...stylex.props(- styles.cardInner,- hasFixedHeight && styles.scrollable,...container(useThemeDefault? {useThemeDefault: 'card'}@@ -299,9 +284,13 @@ export function XDSCard({!useThemeDefault &&effectivePadding !== 4 &&containerPaddingBlockEndVarStyles[effectivePadding],- )}>- {children}- </div>+ xstyle,+ ),+ className,+ style,+ )}+ {...props}>+ {children}</div>);}diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex d9553f2a6d..3d0f56c014 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -103,12 +103,21 @@ function Example() {},],theming: {+ container: true,targets: [{className: 'xds-dialog', visualProps: ['variant']},],vars: [{name: '--dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)'},],+ cssProperties: [+ {+ name: 'padding',+ description:+ "Controls Dialog container padding. Accepts standard CSS padding shorthand (e.g. '16px 20px'). Automatically mapped to container tokens for layout integration.",+ default: 'var(--spacing-4)',+ },+ ],},keyboard:'Escape closes the dialog (unless purpose="required"); focus is trapped inside the dialog while open.',@@ -388,12 +397,21 @@ function Example() {},],theming: {+ container: true,targets: [{className: 'xds-dialog', visualProps: ['variant']},],vars: [{name: '--dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)'},],+ cssProperties: [+ {+ name: 'padding',+ description:+ "Controls Dialog container padding. Accepts standard CSS padding shorthand (e.g. '16px 20px'). Automatically mapped to container tokens for layout integration.",+ default: 'var(--spacing-4)',+ },+ ],},keyboard:'Escape 关闭对话框(purpose="required" 时除外);对话框打开时焦点被限制在内部。',diff --git a/packages/core/src/Layout/XDSLayout.tsx b/packages/core/src/Layout/XDSLayout.tsxindex 5ec0a34139..1266435dfe 100644--- a/packages/core/src/Layout/XDSLayout.tsx+++ b/packages/core/src/Layout/XDSLayout.tsx@@ -40,12 +40,17 @@ export type XDSLayoutHeight = 'fill' | 'auto';const styles = stylex.create({// Outer wrapper uses negative margin to escape container paddinglayoutOuter: {- marginInline: 'calc(-1 * var(--container-padding-inline, 0px))',+ marginInlineStart:+ 'calc(-1 * var(--container-padding-inline-start, var(--container-padding-inline, 0px)))',+ marginInlineEnd:+ 'calc(-1 * var(--container-padding-inline-end, var(--container-padding-inline, 0px)))',marginBlockStart: 'calc(-1 * var(--container-padding-block-start, 0px))',marginBlockEnd: 'calc(-1 * var(--container-padding-block-end, 0px))',},// Inner wrapper resets container padding vars for descendantslayoutInner: {+ '--container-padding-inline-start': '0px',+ '--container-padding-inline-end': '0px','--container-padding-inline': '0px','--container-padding-block-start': '0px','--container-padding-block-end': '0px',diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.tsindex 34e15bfe6a..dca6d0044c 100644--- a/packages/core/src/Layout/container.stylex.ts+++ b/packages/core/src/Layout/container.stylex.ts@@ -6,20 +6,27 @@** ## Public API for themes*- * Themes can override container padding via component-specific CSS custom- * properties following the `--xds-{component}-padding` naming convention:+ * Themes set `padding` on container component overrides. The theme build+ * pipeline expands this to component-scoped CSS custom properties:+ *+ * --xds-card-padding (shorthand — all sides)+ * --xds-card-padding-inline (horizontal)+ * --xds-card-padding-block-start+ * --xds-card-padding-block-end+ *+ * Same pattern for section (--xds-section-padding-*) and dialog+ * (--xds-dialog-padding-*).** ```ts* components: {- * card: { base: { '--xds-card-padding': 'var(--spacing-3)' } },- * section: { base: { '--xds-section-padding': 'var(--spacing-3)' } },- * dialog: { base: { '--xds-dialog-padding': 'var(--spacing-3)' } },+ * card: { base: { padding: '20px' } }, // → --xds-card-padding: 20px+ * section: { base: { padding: '12px 20px' } }, // → directional tokens+ * dialog: { base: { padding: '16px' } },* }* ```*- * This is the **only** supported way for themes to adjust container padding.- * Internal variables (`--layout-padding-inner-x`, etc.) are implementation- * details and must not be referenced by themes.+ * Internal variables (`--layout-padding-inner-x`, `--container-padding-*`)+ * are implementation details and must not be referenced by themes.** SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs*/@@ -50,102 +57,115 @@ export type SpacingToken =const baseStyles = stylex.create({container: {boxSizing: 'border-box',- paddingInline: 'var(--container-padding-inline)',+ paddingInlineStart:+ 'var(--container-padding-inline-start, var(--container-padding-inline))',+ paddingInlineEnd:+ 'var(--container-padding-inline-end, var(--container-padding-inline))',paddingBlockStart: 'var(--container-padding-block-start)',paddingBlockEnd: 'var(--container-padding-block-end)',},});/**- * Card default padding styles that cascade from --xds-card-padding.+ * Component-scoped padding tokens.+ *+ * Each container component (card, section, dialog) has public CSS custom+ * properties that themes can set:+ *+ * --xds-card-padding (shorthand — all sides)+ * --xds-card-padding-inline+ * --xds-card-padding-inline-start+ * --xds-card-padding-inline-end+ * --xds-card-padding-block-start+ * --xds-card-padding-block-end*- * When no explicit padding prop is set on Card, the internal- * layout padding variables read from --xds-card-padding (set by theme)- * with a fallback to --spacing-4 (the default).+ * The theme build pipeline maps `padding: '20px'` on a container component+ * to these tokens. The component reads them with var() fallbacks to --spacing-4.+ *+ * This indirection exists because StyleX's useCSSLayers emits priority-0+ * custom property assignments outside any @layer, making them impossible+ * to override from @layer xds-theme. By reading from a higher-level token,+ * the theme CSS sets the token value and the component picks it up via+ * CSS custom property cascade — no layer competition.*/const cardDefaultPaddingStyles = stylex.create({- containerPaddingInline: {- '--container-padding-inline': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,+ containerPaddingInlineStart: {+ '--container-padding-inline-start': `var(--xds-card-padding-inline-start, var(--xds-card-padding-inline, var(--xds-card-padding, ${spacingVars['--spacing-4']})))`,+ },+ containerPaddingInlineEnd: {+ '--container-padding-inline-end': `var(--xds-card-padding-inline-end, var(--xds-card-padding-inline, var(--xds-card-padding, ${spacingVars['--spacing-4']})))`,},containerPaddingBlockStart: {- '--container-padding-block-start': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,+ '--container-padding-block-start': `var(--xds-card-padding-block-start, var(--xds-card-padding, ${spacingVars['--spacing-4']}))`,},containerPaddingBlockEnd: {- '--container-padding-block-end': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,+ '--container-padding-block-end': `var(--xds-card-padding-block-end, var(--xds-card-padding, ${spacingVars['--spacing-4']}))`,},layoutPaddingOuterX: {- '--layout-padding-outer-x': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-outer-x': `var(--xds-card-padding-inline-start, var(--xds-card-padding-inline, var(--xds-card-padding, ${spacingVars['--spacing-4']})))`,},layoutPaddingOuterY: {- '--layout-padding-outer-y': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-outer-y': `var(--xds-card-padding-block-start, var(--xds-card-padding, ${spacingVars['--spacing-4']}))`,},layoutPaddingInnerX: {- '--layout-padding-inner-x': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-inner-x': `var(--xds-card-padding-inline-start, var(--xds-card-padding-inline, var(--xds-card-padding, ${spacingVars['--spacing-4']})))`,},layoutPaddingInnerY: {- '--layout-padding-inner-y': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-inner-y': `var(--xds-card-padding-block-start, var(--xds-card-padding, ${spacingVars['--spacing-4']}))`,},});-/**- * Section default padding styles that cascade from --xds-section-padding.- *- * When no explicit padding prop is set on Section, the internal- * layout padding variables read from --xds-section-padding (set by theme)- * with a fallback to --spacing-4 (the default).- */const sectionDefaultPaddingStyles = stylex.create({- containerPaddingInline: {- '--container-padding-inline': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,+ containerPaddingInlineStart: {+ '--container-padding-inline-start': `var(--xds-section-padding-inline-start, var(--xds-section-padding-inline, var(--xds-section-padding, ${spacingVars['--spacing-4']})))`,+ },+ containerPaddingInlineEnd: {+ '--container-padding-inline-end': `var(--xds-section-padding-inline-end, var(--xds-section-padding-inline, var(--xds-section-padding, ${spacingVars['--spacing-4']})))`,},containerPaddingBlockStart: {- '--container-padding-block-start': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,+ '--container-padding-block-start': `var(--xds-section-padding-block-start, var(--xds-section-padding, ${spacingVars['--spacing-4']}))`,},containerPaddingBlockEnd: {- '--container-padding-block-end': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,+ '--container-padding-block-end': `var(--xds-section-padding-block-end, var(--xds-section-padding, ${spacingVars['--spacing-4']}))`,},layoutPaddingOuterX: {- '--layout-padding-outer-x': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-outer-x': `var(--xds-section-padding-inline-start, var(--xds-section-padding-inline, var(--xds-section-padding, ${spacingVars['--spacing-4']})))`,},layoutPaddingOuterY: {- '--layout-padding-outer-y': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-outer-y': `var(--xds-section-padding-block-start, var(--xds-section-padding, ${spacingVars['--spacing-4']}))`,},layoutPaddingInnerX: {- '--layout-padding-inner-x': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-inner-x': `var(--xds-section-padding-inline-start, var(--xds-section-padding-inline, var(--xds-section-padding, ${spacingVars['--spacing-4']})))`,},layoutPaddingInnerY: {- '--layout-padding-inner-y': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-inner-y': `var(--xds-section-padding-block-start, var(--xds-section-padding, ${spacingVars['--spacing-4']}))`,},});-/**- * Dialog default padding styles that cascade from --xds-dialog-padding.- *- * When no explicit padding prop is set on Dialog, the internal- * layout padding variables read from --xds-dialog-padding (set by theme)- * with a fallback to --spacing-4 (the default).- */const dialogDefaultPaddingStyles = stylex.create({- containerPaddingInline: {- '--container-padding-inline': `var(--xds-dialog-padding, ${spacingVars['--spacing-4']})`,+ containerPaddingInlineStart: {+ '--container-padding-inline-start': `var(--xds-dialog-padding-inline-start, var(--xds-dialog-padding-inline, var(--xds-dialog-padding, ${spacingVars['--spacing-4']})))`,+ },+ containerPaddingInlineEnd: {+ '--container-padding-inline-end': `var(--xds-dialog-padding-inline-end, var(--xds-dialog-padding-inline, var(--xds-dialog-padding, ${spacingVars['--spacing-4']})))`,},containerPaddingBlockStart: {- '--container-padding-block-start': `var(--xds-dialog-padding, ${spacingVars['--spacing-4']})`,+ '--container-padding-block-start': `var(--xds-dialog-padding-block-start, var(--xds-dialog-padding, ${spacingVars['--spacing-4']}))`,},containerPaddingBlockEnd: {- '--container-padding-block-end': `var(--xds-dialog-padding, ${spacingVars['--spacing-4']})`,+ '--container-padding-block-end': `var(--xds-dialog-padding-block-end, var(--xds-dialog-padding, ${spacingVars['--spacing-4']}))`,},layoutPaddingOuterX: {- '--layout-padding-outer-x': `var(--xds-dialog-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-outer-x': `var(--xds-dialog-padding-inline-start, var(--xds-dialog-padding-inline, var(--xds-dialog-padding, ${spacingVars['--spacing-4']})))`,},layoutPaddingOuterY: {- '--layout-padding-outer-y': `var(--xds-dialog-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-outer-y': `var(--xds-dialog-padding-block-start, var(--xds-dialog-padding, ${spacingVars['--spacing-4']}))`,},layoutPaddingInnerX: {- '--layout-padding-inner-x': `var(--xds-dialog-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-inner-x': `var(--xds-dialog-padding-inline-start, var(--xds-dialog-padding-inline, var(--xds-dialog-padding, ${spacingVars['--spacing-4']})))`,},layoutPaddingInnerY: {- '--layout-padding-inner-y': `var(--xds-dialog-padding, ${spacingVars['--spacing-4']})`,+ '--layout-padding-inner-y': `var(--xds-dialog-padding-block-start, var(--xds-dialog-padding, ${spacingVars['--spacing-4']}))`,},});@@ -343,7 +363,7 @@ export interface ContainerOptions {/*** When set to a component name ('card' | 'section'), internal layout* padding variables cascade from the component-specific public CSS- * custom property (e.g. --xds-card-padding, --xds-section-padding)+ * container tokens (set by theme pipeline from `padding` shorthand)* instead of being set to explicit spacing token values.** This allows themes to override container padding via component-specific@@ -372,7 +392,7 @@ export interface ContainerOptions {* - `--layout-padding-outer-x`, `--layout-padding-outer-y` (internal)* - `--layout-padding-inner-x`, `--layout-padding-inner-y` (internal)*- * Themes should use `--xds-card-padding` or `--xds-section-padding` in+ * Themes should use `padding` (or `paddingBlock`/`paddingInline`) in* component overrides to adjust padding. Do not reference* `--layout-padding-*` variables directly.*@@ -381,7 +401,7 @@ export interface ContainerOptions {* import { container } from '@xds/core/Layout';* import * as stylex from '@stylexjs/stylex';*- * // Card container with default padding (theme-overridable via --xds-card-padding)+ * // Card container with default padding (theme-overridable via padding shorthand)* <div {...stylex.props(...container({ useThemeDefault: 'card' }))}>* <XDSLayout ... />* </div>@@ -419,13 +439,14 @@ export function container({: null;// When useThemeDefault is a component name, cascade from the component's- // public CSS custom property (e.g. --xds-card-padding, --xds-section-padding)+ // public CSS container tokens (set by theme pipeline from `padding` shorthand)// so themes can override each component's padding independently.if (useThemeDefault) {const defaults = themeDefaultStyles[useThemeDefault];return [baseStyles.container,- defaults.containerPaddingInline,+ defaults.containerPaddingInlineStart,+ defaults.containerPaddingInlineEnd,defaults.containerPaddingBlockStart,defaults.containerPaddingBlockEnd,defaults.layoutPaddingOuterX,diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjsindex 5952e825f2..ac36fb5812 100644--- a/packages/core/src/Section/Section.doc.mjs+++ b/packages/core/src/Section/Section.doc.mjs@@ -98,14 +98,15 @@ export const docs = {},],theming: {+ container: true,targets: [{className: 'xds-section', visualProps: ['variant']},],cssProperties: [{- name: '--xds-section-padding',+ name: 'padding',description:- "Controls Section container padding. Set in theme component overrides via `section: { base: { '--xds-section-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",+ "Controls Section container padding. Accepts standard CSS padding shorthand (e.g. '16px 20px'). Automatically mapped to container tokens for layout integration. Supports paddingBlock/paddingInline for axis-specific control.",default: 'var(--spacing-4)',},],@@ -217,14 +218,15 @@ export const docsZh = {},],theming: {+ container: true,targets: [{className: 'xds-section', visualProps: ['variant']},],cssProperties: [{- name: '--xds-section-padding',+ name: 'padding',description:- "Controls Section container padding. Set in theme component overrides via `section: { base: { '--xds-section-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",+ "Controls Section container padding. Accepts standard CSS padding shorthand (e.g. '16px 20px'). Automatically mapped to container tokens for layout integration. Supports paddingBlock/paddingInline for axis-specific control.",default: 'var(--spacing-4)',},],diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsxindex 6ec0a7f380..defd562637 100644--- a/packages/core/src/Section/XDSSection.tsx+++ b/packages/core/src/Section/XDSSection.tsx@@ -222,7 +222,7 @@ export function XDSSection({ref,...props}: XDSSectionProps) {- // When no explicit padding prop, use theme default (--xds-section-padding)+ // When no explicit padding prop, use theme default (set via container tokens)const useThemeDefault = padding == null;const effectivePadding = padding ?? 4;const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex e45c432d6e..18dc5a1b35 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -105,7 +105,7 @@ export interface ThemingTarget {** @example* ```- * {name: '--xds-card-padding', description: 'Controls Card container padding. Cascades to internal layout vars.', default: 'var(--spacing-4)'}+ * {name: 'padding', description: 'Controls Card container padding. Mapped to container tokens automatically.', default: 'var(--spacing-4)'}* ```*/export interface CSSPropertyDoc {@@ -248,6 +248,12 @@ interface BaseDoc {* rendered by this component that themes can target via `@scope`* selectors in `defineTheme`. */theming?: {+ /** Whether this component is a container whose `padding` properties+ * should be mapped to container tokens by the theme pipeline.+ * When true, `padding`, `paddingBlock`, `paddingInline` etc. in+ * component overrides are expanded to `--container-padding-*` and+ * `--layout-padding-*` tokens instead of emitting raw CSS. */+ container?: boolean;/** CSS class targets rendered by this component.* Each entry corresponds to an `xdsClassName()` call in the source. */targets: ThemingTarget[];diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.tsindex ba77f538e5..7b761e0539 100644--- a/packages/core/src/theme/defineTheme.test.ts+++ b/packages/core/src/theme/defineTheme.test.ts@@ -863,3 +863,185 @@ describe('pseudo-class overrides in components', () => {expect(css).not.toContain('.xds-card:');});});++describe('container padding mapping', () => {+ it('maps uniform padding to shorthand token on card', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {padding: '20px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ // Should NOT emit raw padding property (only the scoped token)+ expect(css).not.toMatch(/[^-]padding: 20px/);+ // Should emit component-scoped shorthand token+ expect(css).toContain('--xds-card-padding: 20px');+ // Should NOT emit directional tokens (shorthand covers all sides)+ expect(css).not.toContain('--xds-card-padding-inline');+ expect(css).not.toContain('--xds-card-padding-block-start');+ });++ it('maps asymmetric padding to directional tokens', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {padding: '16px 20px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ expect(css).toContain('--xds-card-padding-inline: 20px');+ expect(css).toContain('--xds-card-padding-block-start: 16px');+ expect(css).toContain('--xds-card-padding-block-end: 16px');+ // Should NOT emit shorthand (sides differ)+ expect(css).not.toMatch(/--xds-card-padding:[^-]/);+ });++ it('maps paddingBlock and paddingInline separately', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {paddingBlock: '24px', paddingInline: '16px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ expect(css).toContain('--xds-card-padding-inline: 16px');+ expect(css).toContain('--xds-card-padding-block-start: 24px');+ expect(css).toContain('--xds-card-padding-block-end: 24px');+ });++ it('works for section and dialog too', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ section: {+ base: {padding: '12px'},+ },+ dialog: {+ base: {padding: '24px 32px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ // Section — uniform → shorthand+ expect(css).toContain('--xds-section-padding: 12px');+ // Dialog — asymmetric → directional+ expect(css).toContain('--xds-dialog-padding-inline: 32px');+ expect(css).toContain('--xds-dialog-padding-block-start: 24px');+ });++ it('does NOT map padding on non-container components', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ button: {+ base: {padding: '8px 16px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ // Button is not a container — padding passes through as-is+ expect(css).toContain('padding: 8px 16px');+ expect(css).not.toContain('--xds-button-padding');+ });++ it('preserves non-padding properties alongside padding mapping', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {+ padding: '20px',+ '--card-radius': '16px',+ backgroundColor: 'white',+ },+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ // Non-padding props pass through+ expect(css).toContain('--card-radius: 16px');+ expect(css).toContain('background-color: white');+ // Padding is mapped to component-scoped token+ expect(css).toContain('--xds-card-padding: 20px');+ expect(css).not.toMatch(/[^-]padding: 20px/);+ });++ it('maps 3-value padding shorthand', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {padding: '16px 20px 12px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ expect(css).toContain('--xds-card-padding-block-start: 16px');+ expect(css).toContain('--xds-card-padding-block-end: 12px');+ expect(css).toContain('--xds-card-padding-inline: 20px');+ });++ it('maps paddingBlock shorthand with two values', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {paddingBlock: '16px 24px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ expect(css).toContain('--xds-card-padding-block-start: 16px');+ expect(css).toContain('--xds-card-padding-block-end: 24px');+ });++ it('maps paddingInline shorthand with two values', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {paddingInline: '12px 20px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ expect(css).toContain('--xds-card-padding-inline-start: 12px');+ expect(css).toContain('--xds-card-padding-inline-end: 20px');+ });++ it('maps paddingBlockStart alone', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {paddingBlockStart: '32px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ expect(css).toContain('--xds-card-padding-block-start: 32px');+ expect(css).not.toContain('--xds-card-padding-block-end');+ expect(css).not.toContain('--xds-card-padding-inline');+ });++ it('maps paddingInlineStart and paddingInlineEnd separately', () => {+ const theme = defineTheme({+ name: 'test',+ components: {+ card: {+ base: {paddingInlineStart: '8px', paddingInlineEnd: '24px'},+ },+ },+ });+ const css = generateThemeCSSFlat(theme);+ expect(css).toContain('--xds-card-padding-inline-start: 8px');+ expect(css).toContain('--xds-card-padding-inline-end: 24px');+ });+});diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.tsindex 9b24f442fa..6a638c022c 100644--- a/packages/core/src/theme/defineTheme.ts+++ b/packages/core/src/theme/defineTheme.ts@@ -584,6 +584,160 @@ export function defineTheme(input: XDSDefineThemeInput): XDSDefinedTheme {* Convert camelCase to kebab-case for CSS property names.* e.g. borderRadius → border-radius, backgroundColor → background-color*/++// =============================================================================+// Container padding mapping+// =============================================================================++/**+ * Components whose padding properties should be mapped to container tokens.+ * When a theme sets `padding` on these components, the pipeline intercepts it+ * and emits container token declarations instead.+ */+const CONTAINER_COMPONENTS = new Set(['card', 'section', 'dialog']);++/** 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()}`);}@@ -647,9 +801,24 @@ export function generateThemeRules(theme: XDSDefinedTheme): string[] {}}+ // Container padding mapping: intercept padding on container+ // components and emit container token declarations instead+ let finalProps = props;+ if (CONTAINER_COMPONENTS.has(component)) {+ const paddingProps = props.filter(([p]) => PADDING_PROPS.has(p));+ if (paddingProps.length > 0) {+ const nonPaddingProps = props.filter(+ ([p]) => !PADDING_PROPS.has(p),+ );+ const parsed = parsePadding(paddingProps);+ const containerTokens = expandContainerPadding(component, parsed);+ finalProps = [...nonPaddingProps, ...containerTokens];+ }+ }+// Emit base rule- if (props.length > 0) {- const declarations = props+ if (finalProps.length > 0) {+ const declarations = finalProps.map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`).join('\n');parts.push(` ${baseSelector} {\n${declarations}\n }`);diff --git a/packages/themes/meta/src/metaTheme.ts b/packages/themes/meta/src/metaTheme.tsindex 53e74d55e1..c1a8201a92 100644--- a/packages/themes/meta/src/metaTheme.ts+++ b/packages/themes/meta/src/metaTheme.ts@@ -328,13 +328,13 @@ export const metaTheme = defineTheme({// =========================================================================card: {base: {+ padding: '20px','--card-radius': '32px',- '--xds-card-padding': '20px',},},// =========================================================================- // Section — 20px padding+ // Section// =========================================================================// =========================================================================@@ -517,7 +517,6 @@ export const metaTheme = defineTheme({base: {backgroundColor: 'light-dark(var(--color-background-surface), #1F1F20)','--dialog-radius': '32px',- '--xds-card-padding': '20px',},},diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.tsindex a3b6617ddf..ca557d8112 100644--- a/packages/themes/neutral/src/neutralTheme.ts+++ b/packages/themes/neutral/src/neutralTheme.ts@@ -319,7 +319,7 @@ export const neutralTheme = defineTheme({// =========================================================================card: {base: {- '--xds-card-padding': 'var(--spacing-3)',+ padding: 'var(--spacing-3)',},},@@ -328,7 +328,7 @@ export const neutralTheme = defineTheme({// =========================================================================section: {base: {- '--xds-section-padding': 'var(--spacing-3)',+ padding: 'var(--spacing-3)',},},