SpacingSpacing scale tokens for padding, gap, and margin — the rhythmic foundation of XDS layouts.
OverviewXDS uses a 4px base-unit spacing scale. Component gap props accept step values that map to these tokens. The scale provides fine-grained control at the small end (2px, 4px, 6px) and consistent rhythm at larger sizes (multiples of 4px).
Scale
TokenValue
--spacing-0
0px
--spacing-0-5
2px
--spacing-1
4px
--spacing-1-5
6px
--spacing-2
8px
--spacing-3
12px
--spacing-4
16px
--spacing-5
20px
--spacing-6
24px
--spacing-7
28px
--spacing-8
32px
--spacing-9
36px
--spacing-10
40px
--spacing-11
44px
--spacing-12
48px
UsageMost components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX.
Spacing via component props vs StyleX
tsx
// Via component props (preferred)
<XDSStack gap={4}>{/* 16px gap */}</XDSStack>
​
// Via StyleX tokens (custom layouts)
import {spacingVars} from '@xds/core';
​
const styles = stylex.create({
  custom: {
    padding: spacingVars['--spacing-4'],
    gap: spacingVars['--spacing-3'],
  },
});
Best Practices
GuidancePractices
DoUse component gap props when available — they handle automatic spacing compensation.
DoStick to the scale for consistency. If a value isn't on the scale, reconsider the design.
DoUse smaller steps (0.5–2) for tight internal spacing and larger steps (4–8) for section gaps.
Don'tUse arbitrary pixel values outside the scale.
Don'tMix spacing tokens with raw px/rem values in the same component.