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. The base reality is Windows
10; Aero, Luna and Classic re-point these same names, and so do dark, more contrast, and the
palette an operating system forces. Six 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
the standard ink — control labels, body text
--color-text-muted
low-contrast text: column headers, status strings
--color-text-disabled
greyed-out text
--color-on-solid
text / icon on a neutral solid fill
Colour — Surfaces
token
swatch
description
--color-background
the client area — what a window is made of
--color-background-subtle
a faint step off the client area
--color-surface
what a control is made of
--color-surface-hover
that control, hovered
--color-surface-active
that control, pressed / 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 — panels, rules, group boxes
--color-border-hover
a border on hover
Colour — Field
Distinct from surface: surface is what a control is made of, field is what you type into.
token
swatch
description
--color-field
the editable well — what you type into
--color-field-text
ink inside the well
--color-field-border
the well’s edge
--color-field-border-top
its darker top edge — light falls from above
--color-field-border-focus
the well’s edge, focused
--color-field-border-top-focus
its top edge, focused
Colour — Selection
token
swatch
description
--color-selection
the selection fill — the one role that is never subtle
--color-selection-text
ink on the selection
Colour — Control
A control border is not a separator border. Aero draws separators at steel-200 and control edges at steel-500.
token
swatch
description
--color-control-text
ink on a thing you press
--color-control-text-disabled
that ink, disabled
--color-control-border
a control’s edge — not a separator’s
--color-control-border-hover
that edge, hovered
--color-control-border-active
that edge, pressed
--color-control-border-default
the default button’s ring — the one Enter presses
--color-control-border-disabled
that edge, disabled
--color-control-face-disabled
a disabled control’s fill
Colour — Window furniture
Title bar, menu bar and status bar are not "surface" — they are a window’s furniture, and Windows named them separately for thirty years.
token
swatch
description
--color-titlebar
the title bar, active
--color-titlebar-gradient
its second stop
--color-titlebar-text
the caption
--color-titlebar-inactive
the title bar, inactive
--color-titlebar-inactive-gradient
its second stop — every era gradated the inactive bar too
--color-titlebar-inactive-text
the caption, inactive
--color-window-border
the window’s outer edge
--color-caption-close-text
the glyph on the close button
--color-caption-close-border
its edge — furniture, not a status colour
--color-menubar
the menu bar strip
--color-menu
a dropped menu’s surface
--color-menu-text
menu ink
--color-menu-selection
the highlighted menu item
--color-menu-selection-text
ink on it
--color-statusbar
the status strip
--color-statusbar-text
status ink
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
the accent fill: links, emphasis
--color-accent-solid-hover
that fill, hovered
--color-accent-on-solid
text / icon on the accent fill
--color-accent-text
accent-coloured text
Colour — Status
Held back until a page needed one, on this file’s own terms. Windows put these in the message-box icons rather than the palette, so the fill moves per era — and the glyph does not. White on red, black on yellow, white on blue, unchanged while the disc under it was redrawn three times. The matched values are in the primitives, labelled as matched rather than published.
token
swatch
description
--color-error-solid
the error red — the message box disc, not a palette entry
--color-error-solid-lit
its lighter stop
--color-error-on-solid
the glyph on it: white, in every era
--color-warning-solid
the warning yellow
--color-warning-solid-lit
its lighter stop
--color-warning-on-solid
the glyph on it: black, in every era
--color-info-solid
the information blue
--color-info-solid-lit
its lighter stop
--color-info-on-solid
the glyph on it: white, in every era
Colour — Tooltip
token
swatch
description
--color-tooltip
the tip surface — its own colour since 1995
--color-tooltip-text
tip ink
--color-tooltip-border
the tip’s edge
Colour — Rows
token
swatch
description
--color-row-text
ink in a list row
--color-row-text-selected
ink in a selected row — inverts where the fill is solid
--color-row-border-hover
a hovered row’s edge
--color-row-border-selected
a selected row’s edge
Surfaces
The fifth axis. These ask what a thing is made of and what gives it relief — named for the job, not the method, which is why a flat grey and a bevel can answer where a gradient and a gloss did before.
token
swatch
description
--surface-control
what a control is filled with — a gradient, or a flat grey
--surface-control-hover
that fill, hovered
--surface-control-active
that fill, pressed
--surface-control-disabled
that fill, disabled
--surface-caption-close
what the close button is filled with — bare until hover in Win10, red in Aero and Luna, ordinary grey in Classic
--surface-caption-close-hover
that fill, hovered
--bevel-control
what gives a control relief — a gloss, or a two-ring bevel
--bevel-control-active
that relief, pressed
--surface-well-block
a horizontal trough: slider groove, scrollbar track
--surface-well-inline
the vertical trough
--bevel-well
the trough’s inset edge
--bevel-field-inset
the soft recess inside an editable well
--surface-row-hover
a hovered list row
--surface-row-selected
a selected list row
--shadow-window
the drop shadow under a window
--shadow-artwork
the drop shadow under album art / thumbnails
Type
These ship bound to the point scale, because that is what Windows specifies. Re-point them at --font-size-rem-* and every control on the page starts answering the reader’s browser setting — the roles do not move, only what they resolve to. That swap is the one this profile is built to make cheap. Note that an era outranks a presentation: Luna and Classic re-point --text-size-body from :root[data-era], which beats the plain :root in document/tokens.css, so this site’s reading column narrows when you switch era. That is the era mechanism working — an appearance scheme changed everything downstream of it, and no role here is exempt.
token
description
--font-family-ui
the chrome face — every control, menu and label
--font-family-body
running text
--font-family-caption
the title bar face
--font-family-code
mono / code face
--text-size-ui
the chrome size — what a control, a menu item and a label all take
--text-size-body
base reading size
--text-size-status
status bars, tooltips
--text-size-caption
the title bar
--text-size-heading
a heading
--text-size-display
the display / h1 size
--text-size-code
inline code size
--text-weight-caption
title bar weight — bold in Luna and Classic, regular from Aero on
--text-weight-heading
heading weight
--text-lineheight-ui
chrome leading — flush, because a menu item is one line
--text-lineheight-body
body leading
--text-lineheight-heading
heading leading
--text-letterspacing-ui
chrome tracking
--text-letterspacing-body
body tracking
--text-inlinesize-body
the body measure (line-length cap)
--link-underline-thickness
link underline thickness
--link-underline-offset
link underline offset
Space
Inset and gap are sibling axes on one shared t-shirt scale — the same name is the same size on both, which is the only thing that makes two scales navigable. They ship bound to --space-pixel-*; the rem steps mirror them exactly if you want them to scale. Anything larger than 24px is page rhythm, not chrome, and lives in document/tokens.css.
token
description
--space-inset-2xs
padding inside a container — 4px
--space-inset-xs
padding inside a container — 8px
--space-inset-s
padding inside a container — 12px
--space-inset-m
padding inside a container — 16px
--space-inset-l
padding inside a container — 24px, the widest chrome pads
--space-gap-2xs
gap between items in a row — 4px
--space-gap-xs
gap between items in a row — 8px
--space-gap-s
gap between items in a row — 12px
--flow-space-2xs
vertical rhythm between prose — tight
--flow-space-s
vertical rhythm between prose
--flow-space-m
vertical rhythm between prose
--flow-space-l
vertical rhythm between prose — wide
Metrics
Declared directly: nothing in the 4px rhythm maps to 23px, and inventing a primitive to point at would be indirection, not a layer.
token
description
--size-control-block
buttons, selects, text boxes (23px)
--size-toolbar-block
toolbar buttons — two shorter than a control (21px)
--size-menubar-block
the menu bar (SM_CYMENU)
--size-titlebar-block
the title bar
--size-statusbar-block
the status strip
--size-scrollbar
scrollbar thickness (SM_CXVSCROLL)
--size-checkbox
the check / radio box
--size-slider-thumb-inline
slider thumb width
--size-slider-thumb-block
slider thumb height
--size-slider-track
slider groove thickness
--size-button-min-inline
the minimum dialog button width (75px, since 1992)