Skip to content

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.ts
index 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.mjs
index 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.mjs
index 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.tsx
index 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 variant
withBorder: {
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-radius
scrollable: {
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.mjs
index 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.tsx
index 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 padding
layoutOuter: {
- 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 descendants
layoutInner: {
+ '--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.ts
index 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.mjs
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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)',
},
},