Design Tokens — spacing and layout

Spacing is the “invisible glue” of an interface. Colors and fonts can partly be forgiven by the eye; chaotic spacing immediately reveals the lack of a system: 10px next to 12px, “almost like the mock,” different gutters on neighboring pages.

Spacing principles

1. Consistent scale — values from one scale.
2. Hierarchy — more air between sections, less between related elements.
3. Proximity — related items closer, unrelated farther.

// Good: multiples of 4
[4, 8, 12, 16, 24, 32, 48, 64]

// Bad: random exceptions
[4, 8, 10, 16, 22, 30]

4px base scale

A 4px base (often felt as an 8pt grid) is an industry standard:

• flexible enough for dense UI;
• pairs well with typography and 16/20/24 icons;
• easy to document and verify.

export const spacing = {
  0: '0',
  1: '0.25rem', // 4px
  2: '0.5rem',  // 8px
  3: '0.75rem', // 12px
  4: '1rem',    // 16px
  6: '1.5rem',  // 24px
  8: '2rem',    // 32px
  12: '3rem',   // 48px
  16: '4rem'    // 64px
};

A semantic layer on top of the scale:

export const space = {
  element: { tight: 1, normal: 2, relaxed: 4 },
  component: { sm: 3, md: 4, lg: 6 },
  section: { sm: 8, md: 12, lg: 16 }
};

Then intent shows up in code: section.md, not “yet another 48px.”

Grid and layout

Column grid

Classic responsive layout: 4 columns on mobile, 8 on tablet, 12 on desktop + gutter from the spacing scale.

export const grid = {
  columns: { mobile: 4, tablet: 8, desktop: 12 },
  gutter: { mobile: 2, tablet: 3, desktop: 4 },
  container: {
    sm: '640px',
    md: '768px',
    lg: '1024px',
    xl: '1280px'
  }
};

CSS Grid / Flexbox

For cards and toolbars, flex/grid with a tokenized gap is often enough. You do not need a 12-column grid in every micro-block.

.card-grid {
  display: grid;
  grid-template-columns: repeat(12, minmax(0, 1fr));
  gap: var(--space-4);
}

Breakpoints

A practical set:

export const breakpoints = {
  sm: '640px',
  md: '768px',
  lg: '1024px',
  xl: '1280px',
  '2xl': '1536px'
};

Prefer mobile-first: base styles for a narrow screen, then min-width enhancements for tablet/desktop.

Semantic names (tablet, desktop) help in docs, but code often keeps sm/md/lg like Tailwind — the main rule is not to mix two incompatible scales.

Layout patterns worth tokenizing

1. Container — max-width + horizontal padding.
2. Section — vertical rhythm between page blocks.
3. Stack — vertical rhythm inside a form/card.
4. Card grid — columns and gap by breakpoints.

.container {
  width: min(100% - 2 * var(--space-4), 80rem);
  margin-inline: auto;
}

@media (min-width: 768px) {
  .container {
    width: min(100% - 2 * var(--space-6), 80rem);
  }
}

Common mistakes

• define a scale and keep writing arbitrary 13px / 18px;
• use huge section gaps in dense admin UIs without adaptation;
• change gutter “by eye” on every page;
• forget that spacing is also part of a11y: too-tight hit areas and cramped form fields hurt UX.

Module 2 takeaway

By now you have the system skeleton:

• package/folder structure;
• color tokens + semantic mapping;
• typography scale and roles;
• spacing/grid/breakpoints.

Next, components are built on this foundation — without magic numbers in every file.