The authoring menu: every role you can reach for, grouped by the job it does, one line of what it
is for. This is the half a stylesheet cannot tell you, which is why it is written by hand and
checked against the other half in Primitives.
Each role maps a meaning onto a value, and the mapping is what moves. Light is the base; dark, more
contrast, and the palette an operating system forces re-point these same names. Four realities, one
contract, no new mechanism for any of them.
Semantics
The named jobs. Each maps a meaning onto a primitive, so the value can shift without the name moving.
Colour — Text
token
swatch
description
--color-text
high-contrast body text
--color-text-muted
low-contrast text: captions, small print, the h2 label
--color-on-solid
text / icon on a neutral solid fill
Colour — Surfaces
token
swatch
description
--color-background
the page canvas
--color-background-subtle
a faint step off the canvas
--color-surface
a raised element background (cards, wells)
--color-surface-hover
that element, hovered
--color-surface-active
that element, active / selected
--color-solid
a neutral solid fill
--color-solid-hover
that fill, hovered
Colour — Borders
token
swatch
description
--color-border-subtle
the faintest separator / hairline
--color-border
the standard border + focus ring
--color-border-hover
a border on hover
Colour — Accent
token
swatch
description
--color-accent-surface
tinted accent background
--color-accent-surface-hover
tinted accent background, hovered
--color-accent-border
accent border / focus ring
--color-accent-solid
brand fill: buttons, links
--color-accent-solid-hover
brand fill, hovered
--color-accent-on-solid
text / icon on the brand fill
--color-accent-text
accent-coloured text
Colour — Status
Four families, one shape. Never the sole signal — pair with an icon or word.
token
swatch
description
--color-success-surface
success — tinted status background
--color-success-border
success — status border
--color-success-text
success — status-coloured text
--color-success-solid
success — status fill
--color-success-on-solid
success — text / icon on the status fill
--color-warning-surface
warning — tinted status background
--color-warning-border
warning — status border
--color-warning-text
warning — status-coloured text
--color-warning-solid
warning — status fill
--color-warning-on-solid
warning — text / icon on the status fill
--color-danger-surface
danger — tinted status background
--color-danger-border
danger — status border
--color-danger-text
danger — status-coloured text
--color-danger-solid
danger — status fill
--color-danger-on-solid
danger — text / icon on the status fill
--color-info-surface
info — tinted status background
--color-info-border
info — status border
--color-info-text
info — status-coloured text
--color-info-solid
info — status fill
--color-info-on-solid
info — text / icon on the status fill
Type
token
description
--font-family-body
body copy face
--font-family-heading
heading face
--font-family-code
mono / code face
--text-size-body
base reading size
--text-size-secondary
one step down (captions, kbd, samp)
--text-size-muted
smallest text (small)
--text-size-lede
a lead paragraph
--text-size-title
a title
--text-size-display
the display / h1 size
--text-size-code
inline code size
--text-lineheight-body
body leading
--text-lineheight-heading
heading leading
--text-lineheight-code
code leading
--text-letterspacing-body
body tracking
--text-letterspacing-heading
heading tracking
--text-inlinesize-body
the body measure (line-length cap)
--text-inlinesize-heading
heading measure
--link-underline-thickness
link underline thickness
--link-underline-offset
link underline offset
Space
token
description
--space-inset-3xs
container padding — smallest
--space-inset-2xs
container padding
--space-inset-xs
container padding
--space-inset-s
container padding
--space-inset-m
container padding
--space-inset-l
container padding
--space-inset-xl
container padding
--space-inset-2xl
container padding — largest
--space-gap-xs
row / cluster gap (CSS gap)
--space-gap-s
row / cluster gap
--space-gap-m
row / cluster gap
--space-gap-l
row / cluster gap
--flow-space-2xs
vertical rhythm between prose — tight
--flow-space-s
vertical rhythm between prose
--flow-space-m
vertical rhythm between prose
--flow-space-xl
vertical rhythm between prose — wide
Borders
token
description
--border-width-default
standard hairline border
--border-radius-control
inline controls: code, kbd, link hover
--border-radius-card
blocks: pre, details, cards
--focus-ring-width
the focus outline width
--focus-ring-offset
the focus outline offset
Undocumented roles
These roles are declared in profile/semantic/ but have no entry above. The menu has
drifted from the stylesheet — give each one a line.