Layout and Spacing

A unified system for dimensions, spacing, and scale.

Overview

Dialtone uses a unified set of layout and spacing design tokens for all dimensional values. These tokens define both the intrinsic dimensions of UI surfaces (e.g. width, height) and the spatial relationships between them (e.g. padding, gap, positioning).

Layout and Spacing Tokens

Layout and spacing tokens are CSS custom properties (a.k.a. CSS variables) generated from two base units:

  • Spacing: base 8px
  • Layout: base 64px

Samples:

Token Math Value
--dt-spacing-100 1 × 8px 8px
--dt-spacing-400 4 × 8px 32px
--dt-layout-100 1 × 64px 64px
--dt-layout-400 4 × 64px 256px

Because the formula is deterministic, tools and code-generation assistants (including LLMs) can resolve any stop without needing the full reference table in context.

For the complete set, view Spacing Tokens and Layout Tokens. For the story behind why layout and spacing live in separate families, see New Layout and Spacing Token Systems.

The Primitive Triad

You rarely need these tokens directly. The primitive triad exposes them through three components:

  • DtBox: what a container is (e.g. surface, border, padding, sizing, positioning)
  • DtStack: how children are arranged (e.g. direction, gap, alignment)
  • DtText: what the content looks like (e.g. font, size, tone)

Compose the triad; reach for raw design tokens or CSS utilities as an escape hatch.

Usage

The primitive triad handles layout and spacing declaratively. For example:

  • DtBox's padding: space inside a container, uses --dt-spacing-* design tokens
  • DtBox's min-inline-size: container width, uses --dt-layout-* design tokens
  • DtBox's inset-block-start: positioned container offset, uses documented coordinate values such as --dt-spacing-*, negative spacing tokens, and side-specific percentage coordinates
  • DtStack's gap: space between boxes, uses --dt-spacing-* design tokens

Layout

Do

  • Prefer percentages, min-inline-size, or min-block-size so containers adapt to their context.
  • Use DtBox's sizing props (inline-size, min-inline-size, max-inline-size, plus their block-axis equivalents) over raw width and height.
  • Use fixed dimensions on elements that require them: avatars, icons, toggles.

Don’t

  • Avoid setting explicit dimensions (e.g. width or height) when a layout can flex.

Padding

Do

  • Use DtBox's padding prop (or its directional variants padding-inline and padding-block) for space inside a container.
  • Use DtStack's gap for space between sibling elements.

Don’t

  • Avoid using margin for layout. It lives outside the element, collapses in surprising ways, and may not scale well since it assumes a sibling element's presence. You might likely can achieve the same result with DtStack's gap or careful use of padding.

Arrangement

Do

  • Use DtStack's gap to space siblings apart, vertically or horizontally.
  • Pick smaller --dt-spacing-* values for gaps inside a container (between headings, text, buttons) and larger values for gaps between regions of a page.

Don’t

  • Avoid hand-rolling flex containers (d-d-flex + d-ai-* + d-jc-* + d-g-*) for layouts DtStack already expresses as props.

Grouping

Do

  • Group related elements tightly; separate unrelated ones widely. Proximity communicates relationship.
  • Keep spacing decisions consistent across pages. Predictability reduces cognitive load.

Don’t

  • Don't vary gap sizes within a single UI pattern. Readers interpret inconsistent spacing as noise.

Guiding the Eye

Do

  • Give prominent elements more space around them; give supporting content less.
  • Use empty space on purpose. Breathing room improves readability and contrast.
  • Keep reading order in mind when deciding what to emphasize.

Don’t

  • Don't pack elements edge-to-edge. Crowded layouts bury hierarchy and fight reading order.

Text Rhythm

Typography is the third leg of the triad.

Do

  • Use DtText for all text. Its density prop controls line-height, so it governs rhythm within text.
  • Pair DtText's density (within-text rhythm) with DtStack's gap (between-element rhythm).

Don’t

  • Avoid combining typography utility classes (d-fs-*, d-lh-*, d-fw-*) when DtText already exposes the right props.

Related CSS Utilities

The triad covers most size and space needs. These utility classes remain available for cases the components don't cover.

Purpose Utility Prefer
Padding d-p-* DtBox padding / padding-inline / padding-block
Margin d-m-* DtStack gap for between-element spacing
Flex / grid gap d-g-* DtStack gap
Width / height d-w* / d-h* DtBox inline-size / block-size
Min / max width d-wmn-* / d-wmx-* DtBox min-inline-size / max-inline-size
Position d-ps-* DtBox position
Coordinates d-ibs-* / d-iie-* DtBox inset-block-start / inset-inline-end
Z-index d-zi-* DtBox z-index
Enable flex container d-d-flex DtStack
Cross-axis alignment d-ai-* DtStack align
Main-axis distribution d-jc-* DtStack justify

For the full set, view Spacing Tokens, Layout Tokens, and CSS Utilities.

Key Takeaways

  • Let the triad do the work: DtBox for the container, DtStack for arrangement, DtText for content.
  • Reach for tokens, not magic numbers. --dt-layout-* and --dt-spacing-* keep sizing and spacing consistent without manual pixel math.
  • Use padding inside containers and gap between them. Avoid margin for layout wherever possible.
  • Avoid fixed dimensions when a layout can flex; min-* constraints respond better across screen sizes.
  • CSS utilities remain available for cases the triad doesn't cover, but start with the triad.

Layout and Spacing documentation last updated Friday, September 4, 2026

fix/popover-modal-zindex-scope