Tokens
Semantic tokens, and why there are no raw colours in a component.
There are two layers. Primitives are the raw ramps — blue/600,
gray/200 — and no component ever references one. Tokens are semantic:
bg/raised, text/muted, border/hairline. Every token has a light value and
a dark value, which is what lets a component stay theme-agnostic.
Surfaces
Four surfaces, and the distance between them is what makes a card read as a card.
| Token | Class | Use |
|---|---|---|
bg/canvas | bg-canvas | The page, when cards need an outline to separate them |
bg/subtle | bg-subtle | The page, when cards should separate by tone instead |
bg/raised | bg-raised | Cards, menus, anything lifted off the page |
bg/sunken | bg-sunken | Recesses — segmented tracks, progress rails |
bg/sunken exists because a segmented control on a bg/subtle page was
invisible: its track and the page were the same colour. A recess needs to be
darker than every surface it can sit on, not merely different from white.
Ink
| Token | Class |
|---|---|
text/primary | text-fg |
text/secondary | text-fg-muted |
text/placeholder | text-fg-placeholder |
text/brand | text-fg-brand |
text/success · text/error | text-fg-success · text-fg-error |
Type
Type is a set of utilities rather than a set of props, so a heading is
t-heading and not <Text size="xl" weight="600">.
What colour is allowed to mean
Green and red mean gain and loss. Brand blue means you can act on this.
Identity hues — the tag/* family — separate one category from another and
carry no judgement.
This is why a falling number is sometimes green: a sales cycle shortening from
21 days to 19 is a down arrow with positive sentiment. Direction and
sentiment are separate props on <Delta> precisely because they disagree often
enough to matter.