Skip to content

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

TypeScript

fix(theme): formalize container padding tokens, prevent internal var access (#847)

Cindy Zhang255519e3b9be
diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsx
index a0a1d4c2fc..c4ef163bcb 100644
--- a/packages/core/src/Card/XDSCard.tsx
+++ b/packages/core/src/Card/XDSCard.tsx
@@ -12,7 +12,6 @@
* - /apps/storybook/stories/Card.stories.tsx (storybook stories)
*/
-
import {type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {colorVars, radiusVars, shadowVars} from '../theme/tokens.stylex';
@@ -151,6 +150,8 @@ 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)
+ const useThemeDefault = padding == null;
const effectivePadding = padding ?? 4;
const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
@@ -177,14 +178,21 @@ export function XDSCard({
{...stylex.props(
styles.cardInner,
hasFixedHeight && styles.scrollable,
- ...container({
- paddingInnerX: paddingToken,
- paddingInnerY: paddingToken,
- paddingOuterX: paddingToken,
- paddingOuterY: paddingToken,
- }),
- effectivePadding !== 4 && paddingStyles[effectivePadding],
- effectivePadding !== 4 &&
+ ...container(
+ useThemeDefault
+ ? {useThemeDefault: true}
+ : {
+ paddingInnerX: paddingToken,
+ paddingInnerY: paddingToken,
+ paddingOuterX: paddingToken,
+ paddingOuterY: paddingToken,
+ },
+ ),
+ !useThemeDefault &&
+ effectivePadding !== 4 &&
+ paddingStyles[effectivePadding],
+ !useThemeDefault &&
+ effectivePadding !== 4 &&
containerPaddingInlineVarStyles[effectivePadding],
)}>
{children}
diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.ts
index a7e0c76d85..a02aaaa6fc 100644
--- a/packages/core/src/Layout/container.stylex.ts
+++ b/packages/core/src/Layout/container.stylex.ts
@@ -4,6 +4,22 @@
* @output StyleX utility for layout container styling
* @position Layout utility; used by XDSCard, XDSSection components
*
+ * ## Public API for themes
+ *
+ * Themes can override container padding via the `--xds-container-padding`
+ * CSS custom property in component style overrides:
+ *
+ * ```ts
+ * components: {
+ * card: { base: { '--xds-container-padding': 'var(--spacing-3)' } },
+ * section: { base: { '--xds-container-padding': 'var(--spacing-3)' } },
+ * }
+ * ```
+ *
+ * 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.
+ *
* SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs
*/
@@ -37,6 +53,34 @@ const baseStyles = stylex.create({
},
});
+/**
+ * Default container padding styles that cascade from --xds-container-padding.
+ *
+ * When no explicit padding prop is set on Card/Section, the internal
+ * layout padding variables read from --xds-container-padding (set by theme)
+ * with a fallback to --spacing-4 (the default).
+ */
+const defaultContainerPaddingStyles = stylex.create({
+ containerPadding: {
+ '--container-padding': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ },
+ containerPaddingInline: {
+ '--container-padding-inline': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingOuterX: {
+ '--layout-padding-outer-x': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingOuterY: {
+ '--layout-padding-outer-y': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingInnerX: {
+ '--layout-padding-inner-x': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ },
+ layoutPaddingInnerY: {
+ '--layout-padding-inner-y': `var(--xds-container-padding, ${spacingVars['--spacing-4']})`,
+ },
+});
+
/**
* Container padding styles.
* Sets --container-padding CSS variable for simple content padding.
@@ -193,6 +237,19 @@ export interface ContainerOptions {
* @default 'spacing4'
*/
paddingInnerY?: SpacingToken;
+
+ /**
+ * When true, internal layout padding variables cascade from
+ * --xds-container-padding (set by theme component overrides)
+ * 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.
+ *
+ * Used by Card and Section when no explicit padding prop is provided.
+ * @default false
+ */
+ useThemeDefault?: boolean;
}
/**
@@ -201,20 +258,23 @@ export interface ContainerOptions {
* Sets CSS variables for padding that child layout components read:
* - `--container-padding` — Default padding for simple content
* - `--container-padding-inline` — Inline padding for edge compensation
- * - `--layout-padding-outer-x`, `--layout-padding-outer-y`
- * - `--layout-padding-inner-x`, `--layout-padding-inner-y`
+ * - `--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.
*
* @example
* ```
* import { container } from '@xds/core/Layout';
* import * as stylex from '@stylexjs/stylex';
*
- * // Basic container with default padding
- * <div {...stylex.props(...container({}))}>
+ * // Basic container with default padding (theme-overridable)
+ * <div {...stylex.props(...container({ useThemeDefault: true }))}>
* <XDSLayout ... />
* </div>
*
- * // Custom padding values
+ * // Explicit padding values (not theme-overridable)
* <div {...stylex.props(
* ...container({ padding: 'spacing3', paddingOuterY: 'spacing2', paddingInnerX: 'spacing3' }),
* customStyles.card
@@ -229,7 +289,22 @@ export function container({
paddingOuterY = 'spacing4',
paddingInnerX = 'spacing4',
paddingInnerY = 'spacing4',
+ useThemeDefault = false,
}: ContainerOptions) {
+ // When useThemeDefault is true, cascade from --xds-container-padding
+ // so themes can override via a single public custom property.
+ if (useThemeDefault) {
+ return [
+ baseStyles.container,
+ defaultContainerPaddingStyles.containerPadding,
+ defaultContainerPaddingStyles.containerPaddingInline,
+ defaultContainerPaddingStyles.layoutPaddingOuterX,
+ defaultContainerPaddingStyles.layoutPaddingOuterY,
+ defaultContainerPaddingStyles.layoutPaddingInnerX,
+ defaultContainerPaddingStyles.layoutPaddingInnerY,
+ ] as const;
+ }
+
return [
baseStyles.container,
containerPaddingStyles[padding],
diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsx
index 6660ea7383..ab07808e27 100644
--- a/packages/core/src/Section/XDSSection.tsx
+++ b/packages/core/src/Section/XDSSection.tsx
@@ -237,6 +237,8 @@ export function XDSSection({
ref,
...props
}: XDSSectionProps) {
+ // When no explicit padding prop, use theme default (--xds-container-padding)
+ const useThemeDefault = padding == null;
const effectivePadding = padding ?? 4;
const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
const outerStylex = stylex.props(
@@ -268,14 +270,21 @@ export function XDSSection({
xdsClassName('section', {variant}),
stylex.props(
nestedStyles.inner,
- ...container({
- paddingInnerX: paddingToken,
- paddingInnerY: paddingToken,
- paddingOuterX: paddingToken,
- paddingOuterY: paddingToken,
- }),
- effectivePadding !== 4 && paddingStyles[effectivePadding],
- effectivePadding !== 4 &&
+ ...container(
+ useThemeDefault
+ ? {useThemeDefault: true}
+ : {
+ paddingInnerX: paddingToken,
+ paddingInnerY: paddingToken,
+ paddingOuterX: paddingToken,
+ paddingOuterY: paddingToken,
+ },
+ ),
+ !useThemeDefault &&
+ effectivePadding !== 4 &&
+ paddingStyles[effectivePadding],
+ !useThemeDefault &&
+ effectivePadding !== 4 &&
containerPaddingInlineVarStyles[effectivePadding],
variantStyles[variant],
dividers?.includes('top') && dividerStyles.top,
diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.ts
index 74d7a89d7a..ff153eb8be 100644
--- a/packages/themes/neutral/src/neutralTheme.ts
+++ b/packages/themes/neutral/src/neutralTheme.ts
@@ -304,26 +304,20 @@ export const neutralTheme = defineTheme({
},
// =========================================================================
- // Card — tighter padding
+ // Card — tighter padding via public container padding token
// =========================================================================
card: {
base: {
- '--layout-padding-inner-x': 'var(--spacing-3)',
- '--layout-padding-inner-y': 'var(--spacing-3)',
- '--layout-padding-outer-x': 'var(--spacing-3)',
- '--layout-padding-outer-y': 'var(--spacing-3)',
+ '--xds-container-padding': 'var(--spacing-3)',
},
},
// =========================================================================
- // Section — tighter padding
+ // Section — tighter padding via public container padding token
// =========================================================================
section: {
base: {
- '--layout-padding-inner-x': 'var(--spacing-3)',
- '--layout-padding-inner-y': 'var(--spacing-3)',
- '--layout-padding-outer-x': 'var(--spacing-3)',
- '--layout-padding-outer-y': 'var(--spacing-3)',
+ '--xds-container-padding': 'var(--spacing-3)',
},
},