Scale Composer documentation

Scale Composer derives a complete design system — type scale, color ramps, spacing, layout grid, and system effects — from three numbers: a base, a ratio, and a note count. Change any of the three and everything downstream recalculates together. This page explains the theory and the reasoning; the rest of the docs walk through the tool view by view.

A little scale theory

A modular scale is a fixed set of values where each value is the previous one multiplied by a constant ratio:

size(i) = base × ratio^i

With a base of 16 and a ratio of 1.5, the scale runs 16 · 24 · 36 · 54 … The idea is old — it comes from print typography and, before that, from music. The ratios themselves are borrowed from musical intervals: 1.5 is a perfect fifth (the frequency ratio 3:2), 1.333 a perfect fourth (4:3), 1.618 the golden section. That is not numerology — it reflects how perception works. We judge sizes (and sound intervals) proportionally: the jump from 16 to 24 feels like the jump from 24 to 36, because both are ×1.5. A scale built on multiplication produces steps that feel even, where hand-picked pixel values rarely do.

The pure formula has a practical flaw: the gaps grow too fast exactly where interfaces need precision. With base 16 and ratio 1.333 there is nothing between 16 and 21 — but real UI constantly needs an 18. Scale Composer therefore subdivides each ratio jump into notes, the way an octave divides into tones:

size(i) = base × ratio^(i/notes)

With two notes per interval the in-between sizes still live on the scale — they are half-steps, not exceptions — so the proportional consistency survives while the scale becomes dense enough to actually use. This is the tool’s central control: preset or custom ratio, note count, and base, always visible in the topbar.

The four views: Color, Typography, Grid, and System

Why one scale for everything

Most design systems are assembled from separate tools — a type scale calculator, a palette generator, spacing by convention. Every part can be individually reasonable and the whole still feels disjointed, because nothing ties the parts to each other.

Scale Composer’s premise is that the relationships are the system. The same three numbers drive:

  • Typography — every font size is a scale step; line heights sit on a baseline grid derived from the base (baseline = base ÷ 2).
  • Color — the ratio shapes the lightness curve of every ramp, so the distance between color steps follows the same progression as the distance between type sizes.
  • Spacing and grid — margins, gutters, and spacing steps are scale values; nudging a gutter lands on the next scale value, never an arbitrary pixel.
  • System effects — corner radii, border widths, elevation, and motion durations are derived from the same base and ratio (a duration is base × ratio^n milliseconds).

Coherence stops being a matter of discipline and becomes a property of the system: it is not that someone remembered to align the parts — they cannot drift apart.

Derived semantics, not picked colors

You do not pick seventeen colors; you pick one (or a few) and the rest is derived. From each seed the tool generates a full OKLCH ramp, and from the ramps it derives semantic roles — text on background, muted text, borders, button states, focus ring, the four functional colors — with WCAG contrast floors enforced and APCA shown alongside. Dark mode is generated as its own derivation with its own lightness curve, not as an inversion of the light theme. The color docs cover the mechanics; the theory lives in the learn section.

How the tool is built, and why

Two decisions shape everything else:

The scale is primary. The scale controls sit in the topbar, above all four views, because they are not a typography setting — they are the setting. Everything else edits interpretations of the scale.

The client presents; the server computes. Every ramp, every semantic derivation, every export is calculated server-side from your session state. Your browser receives finished values. This keeps one source of truth for the math — the numbers in the tool, in the exports, and in the docs screenshots can never disagree, because they all come from the same engine. Your work never leaves your browser except as computation requests: sessions are saved and shared as links, with the whole state encoded in the URL itself (see sharing).

A convention worth knowing from the start: almost everything steps with the arrow keys, and stepping always moves along the scale. Select a text block and press ↑/↓ — the size moves to the next scale value. Select a gutter — same thing. The keyboard reference lives under the ? button in the topbar.

Where to go next