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.tsxindex 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.tsindex 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.tsxindex 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.tsindex 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)',},},