Color

• Text is text-foreground, then text-foreground-secondary (step 11) for captions and secondary rows. text-foreground-placeholder and text-foreground-disabled sit below 4.5:1 on purpose and never carry content. No text-foreground/70: an opacity is a guess that drifts per background.
• Backgrounds are bg-background (the page), bg-background-raised (content on it), bg-background-subtle (one step off, like a code block head) and bg-background-overlay (popups, menus, dialogs). A control's own fill is not a background: it is bg-element.
• Borders are a bare border, whose colour is already an alpha step, so no opacity. Never border-foreground. The Border page has the rest.
• Brand is loud. One primary action per view, and selection. Never as body text.
• System steps (bg-blue-9, text-orange-11) are for hues no semantic token covers: status, avatars, illustration. Pick the step by its role, not by eye.
• black and white are alpha ramps that do not flip with the theme. Use them over photos and solid fills; elsewhere use the semantic tokens.

These sit between the ramps and the components. A ramp step has no meaning on its own; a token gives one step a job, and components read only the job. That is what lets hover:bg-element-hover be one rule that holds in light and dark, for every tone, where hover:bg-foreground/15 is an opacity guess that has to be retuned per backdrop.

• Fills climb element → element-hover, with element-active for selected or open. There is no pressed fill: the press is the scale.
• Edges are a border at rest (a bare border) and a 3:1 boundary under the pointer (border-hover). border-strong is the hairline an outline button carries.
• Marks: text-indicator is a checked control's check, a step darker than the focus blue so a hairline glyph still clears contrast.

Every tone carries the same parts, named by the property that reads them: bg-danger (the solid, with -hover and -active), bg-danger-subtle (the quiet fill, likewise), text-danger (step-12 text) and text-danger-subtle (step 11), border-danger (the edge) and text-on-danger (the text on the solid). Because the shape repeats, a component takes emphasis and intent as two props rather than one flat list, and a destructive action can sit quietly in a menu row or loudly in a dialog without changing component.

• A solid is a fill that carries text, so it comes off the ramp rather than from step 9. Danger and info darken so white holds; brand, success and warning stay light and take dark text.
• A subtle fill is steps 3 to 5, the same climb the elements make. Step-12 text always clears AA on it.
• The ring is an outline in --focus-ring-color, 3px wide and offset 1px, drawn on every focusable element by the base layer. The offset is an empty gap, so it holds on any background, and as an outline it never touches the element's own shadow. Most controls need nothing; a toned one takes focus-ring-danger or focus-ring-success.
• Fixed backgrounds (on-light, on-dark) are built from the alpha ramps and never swap with the theme, and take the tone's shape: bg-on-light, bg-on-light-subtle, text-on-light, border-on-light, and text-on-light-inverse on the solid. Use them over a photo or a brand fill; where the system owns the background, .dark on an ancestor is the better tool.