Spacing

Spacing scale tokens for padding, gap, and margin: the rhythmic foundation of design system layouts.

Overview

The design system 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

Token	Value
--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

Usage

Most 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)
<Stack gap={4}>{/* 16px gap */}</Stack>
// Via StyleX tokens (custom layouts)
import {spacingVars} from '@astryxdesign/core';
const styles = stylex.create({
  custom: {
    padding: spacingVars['--spacing-4'],
    gap: spacingVars['--spacing-3'],
  },
});

Best Practices

Guidance	Practices
Do	Use component gap props when available; they handle automatic spacing compensation.
Do	Stick to the scale for consistency. If a value isn't on the scale, reconsider the design.
Do	Use smaller steps (0.5–2) for tight internal spacing and larger steps (4–8) for section gaps.
Don't	Use arbitrary pixel values outside the scale.
Don't	Mix spacing tokens with raw px/rem values in the same component.