Design System Utility Tokens

A design system gives the developer sheet music to play from, complete with tempo, scores, and notation. Without it, every component improvises.

Design tokens are the score that keeps everything in rhythm, playing in time, and creating harmony across spacing, type, and layout.

Spacing is the beat that holds a UI together. Every component — every padding, gap, and margin decision — reaches for spacing tokens.

Without a defined scale, the beat breaks down. A button gets 0.5rem padding, while a card gets an off-beat 14px. Each decision seems locally reasonable, but is globally inconsistent.

This system introduces a shared scale that covers the full range of layout needs.

:root {
    --spacing-xs:   0.25rem;    /*  4px */
    --spacing-sm:   0.5rem;     /*  8px */
    --spacing-md:   0.75rem;    /* 12px */
    --spacing-lg:   1rem;       /* 16px */
    --spacing-xl:   1.5rem;     /* 24px */
    --spacing-xxl:  2rem;       /* 32px */
    --spacing-3xl:  4rem;       /* 64px */
}

Why these values?

The scale is built on increments of 0.25rem (4px) — small enough to be precise, large enough to be meaningful.

Each step is named using t-shirt sizing ( sm, md, lg etc. ) rather than numeric values, so names communicate scale at a glance rather than requiring mental conversion.

Where spacing tokens live in the system

Spacing tokens are consumed at every layer:

• Primitives use them for gap values between children
• Components use them for internal spacing ( margins, padding, gaps, and offsets )

From there, utility classes expose the same scale as composable helpers for one-off spacing needs.

The utility layer uses the same t-shirt sizing as the tokens - .gap-lg and --spacing-lg are clearly the same step in that scale.

/* gap.css */
.gap-sm { gap: var(--spacing-sm); }

/* padding.css */
.p-sm { padding: var(--spacing-sm); }

/* margin.css */
.m-sm { margin: var(--spacing-sm); }

/* ...full reference in resources */

Breakpoints are the dynamic markings — they tell the layout when to shift register. Like a musical arrangement that changes feel at the chorus, a layout should also adapt at deliberate, shared moments.

If one component shifts at 768px and another at 769px, the result is a layout that feels unpolished. Shared breakpoints ensure every adaptation happens in step.

:root {
    --bp-xs:         18.75rem;  /*  300px */
    --bp-sm:         35rem;     /*  560px */
    --bp-md:         48rem;     /*  768px */
    --bp-lg:         75rem;     /* 1200px */
    --bp-xl:         90rem;     /* 1440px */
    --bp-characters: 80ch;      /* Maximum content line length */
}

Why rem?

Breakpoints defined in rem stay proportional to the type scale. When a user's font size increases, text takes up more space — a rem-based breakpoint shifts the layout at the right moment relative to that text.

The character width breakpoint

--bp-characters is different from the others — it is not a viewport breakpoint but a content constraint. Setting max-width: var(--bp-characters) on text content keeps line lengths within a readable range, regardless of the viewport width.

This is applied to <p> elements throughout the system.

Using breakpoints in CSS

CSS custom properties cannot be used directly inside @media queries — media queries do not inherit from :root. Instead, breakpoint tokens define shared values that are referenced consistently:

/* Use the raw value inside media queries */
@media screen and (min-width: 35rem) {
    .nav__wrapper {
        flex-direction: row;
    }
}

/* Use the token for max-width constraints in layout */
.layout-wrapper {
    max-width: var(--bp-lg);
}

The tokens remain the single source of truth.

These three token categories form the remaining foundation of the system.

• Spacing ensures the beat holds — every gap, padding, and margin comes from a shared scale.
• Typography ensures the composition is intentional — font sizes and line heights communicate hierarchy, not guesswork.
• Breakpoints ensure the arrangement shifts in step — layout boundaries are shared contracts, not scattered magic numbers.

Together with the color and theme tokens from the theming post, the token layer is now complete. Every value the system needs — colors, spacing, typography, and layout have defined homes.

At this point, the system is no longer a collection of components — it is a score that every component plays from.

This is the last post in the design system series for now. The next series covers individual components — starting with the Button.