Styles

Spacing

Draft

Arch UI leverages standard sizes and spacing created from increments of 4. This provides consistent sizing and components that snap into place.

Usage

16

24

36

48

64

Common alternative names

Spacers, sizing units

---

Anatomy

Spacing interval

We use an incremental spacing scale with a root of 4 based on a modular scale with a major second ratio (1.125).

All grids, typography, and component constructions leverage this scale to produce a pixel-fitted and harmonious structure. Use this scale to create space between objects in product layouts.

16Core sizes

4

8

12

16

20

24

28

32

36

40

48

56

64

96

128

Units1   2   3   4   5x   6x   7x   8x   9x   10x   12x   14x   16x   24x   32x

---

Baseline grid

Built off the 4 spacing scale, the vertical grid provides a flexible structure that allows text to flow vertically along its baseline. This creates a consistent vertical rhythm across all product screens. Use multiples of 4 when defining measurements, spacing, and positioning elements.

---

Core sizes

While all increments of 4 are available, designers will use a set of five archetype sizes that will cover 90% of their layouts.

Note that not every asset should be displayed in all sizes. We don't show an xsmall avatar in this example, as its readability would be compromised.

64

48

36

24

16

---

Usage

Padding vs margin

Use padding to create space inside a container — the breathing room around content. Use margin (or gap) to create space between sibling elements. In Arch UI components, prefer CSS gap on flex and grid containers over margin; it avoids collapsed-margin surprises and is easier to override with a single token.

---

Component spacing

Semantic component tokens (--spacing-component-*) control the internal padding and gaps of individual components — buttons, inputs, cards, and dialogs. They follow a t-shirt size progression:

Token	Value	Typical use
--spacing-component-xs	4 px	Tight icon padding, badge insets
--spacing-component-sm	8 px	Compact button padding, input padding-inline
--spacing-component-md	12 px	Default internal padding
--spacing-component-lg	16 px	Card body padding, dialog content area
--spacing-component-xl	24 px	Large cards, hero sections inside components

---

Inline spacing

Inline tokens (--spacing-inline-*) handle the horizontal gaps between elements that sit on the same line — icon + label, avatar + name, tag + tag.

Token	Value	Typical use
--spacing-inline-xs	2 px	Sub-pixel optical gaps
--spacing-inline-sm	4 px	Icon-to-label gap (small)
--spacing-inline-md	8 px	Icon-to-label gap (default), chip gap
--spacing-inline-lg	12 px	Adjacent buttons, wider inline groups

---

Layout spacing

Layout tokens control page-level structure — the gutter around content, the gap between major sections, and the gap between content blocks within a section.

Token	Value	Typical use
--spacing-layout-page-gutter	16 px	Left/right page margin on mobile-first layouts
--spacing-layout-content-gap	24 px	Gap between content blocks within a section
--spacing-layout-section-gap	48 px	Gap between major page sections

---

Phone layout

All mobile devices, both Android and iOS, follow the same grid system. The only variable height will be the status bar, which changes depending on OS and device.

	iOS	Android
Status bar height	Variable by device	Variable by device
Nav bar height	44	48
Left & right margin	16	16
Artwork column (centered in)	64	64

---

Do / Don't

padding: var(--spacing-component-md);

✓ Do

Use semantic tokens for component and layout spacing. They communicate intent and can be changed globally.

padding: 12px;

✕ Don't

Hardcoded pixel values bypass the system and won't respond to future density changes.

gap: var(--spacing-inline-md);

✓ Do

Use CSS gap with a spacing token on flex or grid parents to space children evenly.

.child { margin-right: 8px; }

✕ Don't

Adding margin to individual children creates inconsistencies and requires overrides on first or last child.

/* optical alignment override */ margin-top: var(--spacing-2);

✓ Do

Reach for primitive tokens only when no semantic token fits. Document why in a comment.

padding: var(--spacing-12);

✕ Don't

Don't use primitives for common patterns that already have semantic tokens. It hides the purpose of the value.

Tokens

Primitive tokens

Primitive spacing tokens map directly to fixed pixel values. They form the raw scale that semantic tokens reference. Use primitives only when no semantic token matches your use case.

Token	Value	Preview
--spacing-0	0 px
--spacing-1	1 px
--spacing-2	2 px
--spacing-4	4 px
--spacing-6	6 px
--spacing-8	8 px
--spacing-10	10 px
--spacing-12	12 px
--spacing-14	14 px
--spacing-16	16 px
--spacing-18	18 px
--spacing-20	20 px
--spacing-22	22 px
--spacing-24	24 px
--spacing-28	28 px
--spacing-32	32 px
--spacing-36	36 px
--spacing-40	40 px
--spacing-48	48 px
--spacing-56	56 px
--spacing-64	64 px
--spacing-80	80 px
--spacing-96	96 px
--spacing-112	112 px
--spacing-128	128 px

Semantic tokens — Component

Component tokens define the internal spacing of UI elements. They alias to primitives so a global density change only requires updating these mappings.

Token	Value	Resolves to	Preview
--spacing-component-xs	4 px	--spacing-4
--spacing-component-sm	8 px	--spacing-8
--spacing-component-md	12 px	--spacing-12
--spacing-component-lg	16 px	--spacing-16
--spacing-component-xl	24 px	--spacing-24

Semantic tokens — Inline

Inline tokens control horizontal gaps between adjacent elements on the same line.

Token	Value	Resolves to	Preview
--spacing-inline-xs	2 px	--spacing-2
--spacing-inline-sm	4 px	--spacing-4
--spacing-inline-md	8 px	--spacing-8
--spacing-inline-lg	12 px	--spacing-12

Semantic tokens — Layout

Layout tokens govern page-level structure: gutters, section gaps, and content gaps.

Token	Value	Resolves to	Preview
--spacing-layout-page-gutter	16 px	--spacing-16
--spacing-layout-content-gap	24 px	--spacing-24
--spacing-layout-section-gap	48 px	--spacing-48

Alias chain

Spacing tokens follow the same two-tier alias pattern as all Arch UI tokens:

--spacing-component-md

--spacing-inline-md

--spacing-layout-content-gap

→

--spacing-12 12 px

--spacing-8 8 px

--spacing-24 24 px

semanticprimitive

To change the density of every component in the system, update the semantic-to-primitive mapping — no component CSS needs to change.

Code

Padding vs margin

/* Padding inside a card */
.card {
  padding: var(--spacing-component-lg);          /* 16px */
}

/* Gap between stacked cards */
.card-list {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-layout-content-gap);         /* 24px */
}

Layout spacing

.page {
  padding-inline: var(--spacing-layout-page-gutter);
}

.page__sections {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-layout-section-gap);
}

.section__content {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-layout-content-gap);
}

Status & changelog

Status & changelog coming soon.