Project Arceus

Spacing Scale

--sds-size-space-0

0px

No spacing, used for removing default margins or padding.

--sds-size-space-025

1px

Hair-thin spacing for borders and fine details.

--sds-size-space-050

2px

Micro spacing for tight UI elements.

--sds-size-space-075

3px

Tiny spacing for compact components like small tags.

--sds-size-space-100

4px

Extra small spacing for compact layouts.

--sds-size-space-150

6px

Small spacing step for fine-tuned layouts.

--sds-size-space-200

8px

Small spacing for related elements.

--sds-size-space-250

10px

Medium-small spacing for component internals.

--sds-size-space-300

12px

Base spacing for general content.

--sds-size-space-400

16px

Medium spacing for content sections.

--sds-size-space-500

20px

Medium-large spacing for content blocks.

--sds-size-space-600

24px

Large spacing for major sections.

--sds-size-space-700

28px

Large spacing for component separation.

--sds-size-space-800

32px

Extra large spacing for page sections.

--sds-size-space-1000

40px

Extra large spacing for major content blocks.

--sds-size-space-1200

48px

Double extra large spacing for major layout blocks.

--sds-size-space-1600

64px

Triple extra large spacing for hero sections.

--sds-size-space-2000

80px

Huge spacing for major page divisions.

--sds-size-space-2400

96px

Massive spacing for dramatic layout effects.

--sds-size-space-3200

128px

Maximum spacing for hero sections.

--sds-size-space-4000

160px

Ultimate spacing for dramatic page breaks.

Usage Examples

CSS Variables

Use spacing tokens directly in your CSS to maintain consistent spacing throughout your application.

Content with margin-bottom: 16px (var(--sds-size-space-400)) and padding: 24px (var(--sds-size-space-600))

.element {
  margin-bottom: var(--sds-size-space-400);
  padding: var(--sds-size-space-600);
}

Utility Classes (Conceptual)

Apply spacing using utility classes for quick layout adjustments without writing custom CSS. (Note: Actual utility classes need to be defined separately if not already present).

Content with conceptual class `mb-400` and `p-600`.

Actual implementation of these utility classes is pending.

<div class="mb-400 p-600">
  Content with margin-bottom: 16px and padding: 24px
</div>

Component Spacing Guidelines

Different components use specific spacing tokens for optimal visual hierarchy and usability:

Tag Components

Small tags: --sds-size-space-075 × --sds-size-space-200 (3px × 8px)
Medium tags: --sds-size-space-100 × --sds-size-space-250 (4px × 10px)

Button Components

Small buttons: --sds-size-space-200 × --sds-size-space-300 (8px × 12px)
Medium buttons: --sds-size-space-300 × --sds-size-space-400 (12px × 16px)
Large buttons: --sds-size-space-400 × --sds-size-space-500 (16px × 20px)

Layout Spacing

Component gaps: --sds-size-space-200 to --sds-size-space-400
Section spacing: --sds-size-space-600 to --sds-size-space-800
Page-level spacing: --sds-size-space-1200 and above

Dimension Tokens vs. Spacing Tokens

While spacing tokens govern rhythm (margins, paddings, gaps), some fixed-width requirements are not about rhythm at all. We capture those in a companion set ofdimension tokens (e.g. --sds-size-width-sidebar). Use them whenever a component or layout needs a hard-coded width/height that shouldn't scale with the spacing steps.

--sds-size-width-sidebar ⟶ 280 px – standard sidebar width.
--sds-size-width-card-min ⟶ 280 px – minimum width for cards in responsive grids.
--sds-size-width-metric-card ⟶ 140 px – minimum width for metric cards.
--sds-size-height-* ⟶ component heights (32–52 px) tokenised in circuit.css.

If you find yourself typing raw px values for size constraints, consider whether a dimension token would make it reusable and easier to theme. When in doubt, prefer a token – consistency first!