Colors
Components use semantic tokens named by role, never raw palette steps. Every token carries its light and dark value, so the same class is right in both themes.
Neutral temperature
An experiment: lean the neutrals warm or cold and the whole site follows. The middle is pure grey; Shipped is what palette.css has now. Copy the CSS when a pair feels right.
Layers
What a region sits on. Pick by role, not by how gray it looks.
canvas App background and page contentchrome Sidebar and app headersurface Cards, tables and panels on the canvasoverlay Menus, popovers and dialogsControls
Inputs and secondary buttons share one fill, so a field and a button read as the same kind of thing.
control Inputs, selects, secondary buttonscontrol-hover Their hover stateFills
Translucent neutral fills that work on any layer.
fill Table headers, quiet badges, tracksfill-hover Hover on rows, nav items, ghost buttonsfill-active Pressed and selectedText
Most text is fg. Muted for secondary text, subtle for hints.
fg Body text, labels, headingsfg-muted Descriptions, secondary text, iconsfg-subtle Placeholders, hints, group labelsLines
Layout dividers use border-subtle. Control edges use border.
border-subtle Layout dividers, rows, card edgesborder Inputs and secondary buttonsborder-strong Hover edges and emphasisring Focus ringIntents
Each intent has the same six tokens: a solid fill, its hover, text on the fill (-fg), colored text (-text), a tinted background (-subtle) and its edge (-border).
Palette
The raw ramps behind the tokens. Use them only to define a token.