Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(theme): rename --xds-container-padding to --xds-card-padding / --xds-section-padding (#858)

Cindy Zhang4c836c708e13
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index c3ac33a1c2..805c744d04 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -95,9 +95,9 @@ export const docs = {
],
cssProperties: [
{
- name: '--xds-container-padding',
+ name: '--xds-card-padding',
description:
- "Controls Card container padding. Set in theme component overrides via `card: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ "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.",
default: 'var(--spacing-4)',
},
],
@@ -200,9 +200,9 @@ export const docsZh = {
],
cssProperties: [
{
- name: '--xds-container-padding',
+ name: '--xds-card-padding',
description:
- "Controls Card container padding. Set in theme component overrides via `card: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ "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.",
default: 'var(--spacing-4)',
},
],
diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsx
index c4ef163bcb..49afe8025c 100644
--- a/packages/core/src/Card/XDSCard.tsx
+++ b/packages/core/src/Card/XDSCard.tsx
@@ -150,7 +150,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-container-padding)
+ // When no explicit padding prop, use theme default (--xds-card-padding)
const useThemeDefault = padding == null;
const effectivePadding = padding ?? 4;
const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
@@ -180,7 +180,7 @@ export function XDSCard({
hasFixedHeight && styles.scrollable,
...container(
useThemeDefault
- ? {useThemeDefault: true}
+ ? {useThemeDefault: 'card'}
: {
paddingInnerX: paddingToken,
paddingInnerY: paddingToken,
diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.ts
index a02aaaa6fc..7707956925 100644
--- a/packages/core/src/Layout/container.stylex.ts
+++ b/packages/core/src/Layout/container.stylex.ts
@@ -6,13 +6,13 @@
*
* ## Public API for themes
*
- * Themes can override container padding via the `--xds-container-padding`
- * CSS custom property in component style overrides:
+ * Themes can override container padding via component-specific CSS custom
+ * properties following the `--xds-{component}-padding` naming convention:
*
* ```ts
* components: {
- * card: { base: { '--xds-container-padding': 'var(--spacing-3)' } },
- * section: { base: { '--xds-container-padding': 'var(--spacing-3)' } },
+ * card: { base: { '--xds-card-padding': 'var(--spacing-3)' } },
+ * section: { base: { '--xds-section-padding': 'var(--spacing-3)' } },
* }
* ```
*
@@ -54,33 +54,72 @@ const baseStyles = stylex.create({
});
/**
- * Default container padding styles that cascade from --xds-container-padding.
+ * Card default padding styles that cascade from --xds-card-padding.
*
- * When no explicit padding prop is set on Card/Section, the internal
- * layout padding variables read from --xds-container-padding (set by theme)
+ * 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).
*/
-const defaultContainerPaddingStyles = stylex.create({
+const cardDefaultPaddingStyles = stylex.create({
containerPadding: {
- '--container-padding': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ '--container-padding': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,
},
containerPaddingInline: {
- '--container-padding-inline': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ '--container-padding-inline': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,
},
layoutPaddingOuterX: {
- '--layout-padding-outer-x': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ '--layout-padding-outer-x': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,
},
layoutPaddingOuterY: {
- '--layout-padding-outer-y': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ '--layout-padding-outer-y': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,
},
layoutPaddingInnerX: {
- '--layout-padding-inner-x': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ '--layout-padding-inner-x': `var(--xds-card-padding, ${spacingVars['--spacing-4']})`,
},
layoutPaddingInnerY: {
- '--layout-padding-inner-y': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ '--layout-padding-inner-y': `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({
+ containerPadding: {
+ '--container-padding': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,
+ },
+ containerPaddingInline: {
+ '--container-padding-inline': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingOuterX: {
+ '--layout-padding-outer-x': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingOuterY: {
+ '--layout-padding-outer-y': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingInnerX: {
+ '--layout-padding-inner-x': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingInnerY: {
+ '--layout-padding-inner-y': `var(--xds-section-padding, ${spacingVars['--spacing-4']})`,
+ },
+});
+
+/**
+ * Map from component name to its theme default padding styles.
+ * Each component reads from its own public CSS custom property.
+ */
+const themeDefaultStyles = {
+ card: cardDefaultPaddingStyles,
+ section: sectionDefaultPaddingStyles,
+};
+
+export type ContainerComponent = keyof typeof themeDefaultStyles;
+
/**
* Container padding styles.
* Sets --container-padding CSS variable for simple content padding.
@@ -239,17 +278,18 @@ export interface ContainerOptions {
paddingInnerY?: SpacingToken;
/**
- * When true, internal layout padding variables cascade from
- * --xds-container-padding (set by theme component overrides)
+ * 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)
* instead of being set to explicit spacing token values.
*
- * This allows themes to override container padding via a single
- * public CSS custom property without touching internal vars.
+ * This allows themes to override container padding via component-specific
+ * public CSS custom properties without touching internal vars.
*
* Used by Card and Section when no explicit padding prop is provided.
- * @default false
+ * @default undefined (uses explicit spacing token values)
*/
- useThemeDefault?: boolean;
+ useThemeDefault?: ContainerComponent;
}
/**
@@ -261,16 +301,17 @@ 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-container-padding` in component overrides to
- * adjust padding. Do not reference `--layout-padding-*` variables directly.
+ * Themes should use `--xds-card-padding` or `--xds-section-padding` in
+ * component overrides to adjust padding. Do not reference
+ * `--layout-padding-*` variables directly.
*
* @example
* ```
* import { container } from '@xds/core/Layout';
* import * as stylex from '@stylexjs/stylex';
*
- * // Basic container with default padding (theme-overridable)
- * <div {...stylex.props(...container({ useThemeDefault: true }))}>
+ * // Card container with default padding (theme-overridable via --xds-card-padding)
+ * <div {...stylex.props(...container({ useThemeDefault: 'card' }))}>
* <XDSLayout ... />
* </div>
*
@@ -289,19 +330,21 @@ export function container({
paddingOuterY = 'spacing4',
paddingInnerX = 'spacing4',
paddingInnerY = 'spacing4',
- useThemeDefault = false,
+ useThemeDefault,
}: ContainerOptions) {
- // When useThemeDefault is true, cascade from --xds-container-padding
- // so themes can override via a single public custom property.
+ // When useThemeDefault is a component name, cascade from the component's
+ // public CSS custom property (e.g. --xds-card-padding, --xds-section-padding)
+ // so themes can override each component's padding independently.
if (useThemeDefault) {
+ const defaults = themeDefaultStyles[useThemeDefault];
return [
baseStyles.container,
- defaultContainerPaddingStyles.containerPadding,
- defaultContainerPaddingStyles.containerPaddingInline,
- defaultContainerPaddingStyles.layoutPaddingOuterX,
- defaultContainerPaddingStyles.layoutPaddingOuterY,
- defaultContainerPaddingStyles.layoutPaddingInnerX,
- defaultContainerPaddingStyles.layoutPaddingInnerY,
+ defaults.containerPadding,
+ defaults.containerPaddingInline,
+ defaults.layoutPaddingOuterX,
+ defaults.layoutPaddingOuterY,
+ defaults.layoutPaddingInnerX,
+ defaults.layoutPaddingInnerY,
] as const;
}
diff --git a/packages/core/src/Layout/index.ts b/packages/core/src/Layout/index.ts
index ce746486c3..7636053936 100644
--- a/packages/core/src/Layout/index.ts
+++ b/packages/core/src/Layout/index.ts
@@ -11,7 +11,11 @@
// Container utility
export {container} from './container.stylex';
-export type {ContainerOptions, SpacingToken} from './container.stylex';
+export type {
+ ContainerComponent,
+ ContainerOptions,
+ SpacingToken,
+} from './container.stylex';
// Edge compensation utility
export {edgeSignals, edgeCompensation} from './edgeCompensation.stylex';
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index 1b41777512..ee0ea24ac4 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -102,9 +102,9 @@ export const docs = {
],
cssProperties: [
{
- name: '--xds-container-padding',
+ name: '--xds-section-padding',
description:
- "Controls Section container padding. Set in theme component overrides via `section: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ "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.",
default: 'var(--spacing-4)',
},
],
@@ -214,9 +214,9 @@ export const docsZh = {
],
cssProperties: [
{
- name: '--xds-container-padding',
+ name: '--xds-section-padding',
description:
- "Controls Section container padding. Set in theme component overrides via `section: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ "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.",
default: 'var(--spacing-4)',
},
],
diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsx
index b2b6971cfa..01d1f077d7 100644
--- a/packages/core/src/Section/XDSSection.tsx
+++ b/packages/core/src/Section/XDSSection.tsx
@@ -237,7 +237,7 @@ export function XDSSection({
ref,
...props
}: XDSSectionProps) {
- // When no explicit padding prop, use theme default (--xds-container-padding)
+ // When no explicit padding prop, use theme default (--xds-section-padding)
const useThemeDefault = padding == null;
const effectivePadding = padding ?? 4;
const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
@@ -272,7 +272,7 @@ export function XDSSection({
nestedStyles.inner,
...container(
useThemeDefault
- ? {useThemeDefault: true}
+ ? {useThemeDefault: 'section'}
: {
paddingInnerX: paddingToken,
paddingInnerY: paddingToken,
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index d57d166fa4..ac4c6e928a 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-container-padding', description: 'Controls container padding. Cascades to internal layout vars.', default: 'var(--spacing-4)'}
+ * {name: '--xds-card-padding', description: 'Controls Card container padding. Cascades to internal layout vars.', default: 'var(--spacing-4)'}
* ```
*/
export interface CSSPropertyDoc {
diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.ts
index ff153eb8be..dd05c5620c 100644
--- a/packages/themes/neutral/src/neutralTheme.ts
+++ b/packages/themes/neutral/src/neutralTheme.ts
@@ -304,20 +304,20 @@ export const neutralTheme = defineTheme({
},
// =========================================================================
- // Card — tighter padding via public container padding token
+ // Card — tighter padding via public card padding token
// =========================================================================
card: {
base: {
- '--xds-container-padding': 'var(--spacing-3)',
+ '--xds-card-padding': 'var(--spacing-3)',
},
},
// =========================================================================
- // Section — tighter padding via public container padding token
+ // Section — tighter padding via public section padding token
// =========================================================================
section: {
base: {
- '--xds-container-padding': 'var(--spacing-3)',
+ '--xds-section-padding': 'var(--spacing-3)',
},
},