---
name: design-tokens-and-visual-scales
description: "Named colour, type, spacing and elevation tokens with one scale, accent and grid. Use when choosing a visual value for a UI surface."
---

# Design Tokens And Visual Scales

**Scope.** Every visual value on a UI surface: colour, type, spacing,
elevation, radius, border width, grid. Contrast ratios and focus
appearance belong to `ui-accessibility`. Voice belongs to `ui-text`.

**Two token layers.** Produce primitive tokens that name a raw value
(`color-neutral-700`, `space-4`) and semantic tokens that name a use
(`color-text-muted`, `space-inset-card`). Components reference semantic
tokens only. A reviewer greps the component tree for `#`, `rgb(`, `hsl(`
and numeric lengths: hits outside the token file and outside media
queries are defects.

**Type scale.** Produce one scale: base 16px, ratio 1.25, seven steps —
13, 16, 20, 25, 31, 39, 49px `[ASSUMPTION]`. State the ratio in the token
file. A reviewer names the ratio and finds no font size off the scale.

**Line height.** Produce line height as a unitless ratio per step: 1.5
for body text, 1.25 at 31px and above `[ASSUMPTION]`. A reviewer checks
every text token carries a line height.

**Font weights.** Produce at most three weights — 400, 500, 700
`[ASSUMPTION]`. A reviewer counts the weights in use and finds three or
fewer.

**Spacing scale.** Produce one 4px-based scale: 4, 8, 12, 16, 24, 32, 48,
64, 96px `[ASSUMPTION]`. Every margin, padding and gap is one of them. A
reviewer lists the distinct spacing values in the diff and finds every
one on the scale.

**Colour.** Produce one accent hue, one neutral ramp of nine steps, and
four semantic families — success, warning, danger, info. A reviewer
counts the accent hues and finds one. A second accent needs a written
reason in the token file.

**Elevation.** Produce a closed set of four levels: 0 flat, 1 raised
card, 2 sticky bar, 3 overlay `[ASSUMPTION]`. Each level is one shadow
token. A reviewer finds no shadow declared outside the set, and no two
levels used for the same kind of surface.

**Radius.** Produce a closed set: 0, 4, 8, 999px `[ASSUMPTION]`. A
reviewer checks each set member maps to one component class.

**Border width.** Produce a closed set: 1px hairline, 2px emphasis
`[ASSUMPTION]`. A reviewer finds no third width.

**Grid.** Produce one alignment grid per surface: column count, gutter
token and page-margin token, all drawn from the spacing scale. A reviewer
overlays the grid on the rendered surface and finds every block edge on a
column edge or a gutter edge.

**Token naming.** Produce names in `category-role-variant-state` order,
lower case, hyphen separated. A reviewer predicts an unseen token's name
from the pattern and is right.

**Change rule.** Produce a token edit, never a component-local value.
Adding a scale step needs a written reason naming the surface that cannot
be built from the existing steps. A reviewer checks every new token in
the diff against that reason.