Once UI colour is four pairings, not a palette you pick from: background with onBackground, solid with onSolid, alpha over whatever sits behind, and surface when you want the theme to decide. Use the pairs; leave sand-700 alone.
Once UI colour is not a palette you pick from. It is four pairings. Reach for the pair that matches the job, and leave base tokens like sand-700 alone — they are the foundation layer, not something a product page should name.Colour arrives on the container. Set the fill and the text that sits on it once, and every label inside inherits it. That is why the props come in pairs rather than as a freestyle colour picker on every child.
background and onBackground
Use this for a panel, a section, a page area — anything that is a surface, not a control.background also accepts page, surface, overlay, and transparent. Those follow the theme without naming a scheme. The main site background is usually page; raised layout chrome such as a header or sidebar is usually surface.
solid and onSolid
Use this when the fill has to read as pressable — a button, a checkbox, a filled badge. solid is the high-contrast fill; onSolid is the only safe text colour on top of it.Putting onBackground on a solid fill is the usual contrast bug. The pair names exist so you do not have to remember which weight clears a brand fill in light mode and again in dark mode.
Alpha over whatever sits behind
Alpha weights (brand-alpha-medium, neutral-alpha-weak) tint whatever is behind them instead of replacing it. That is what keeps a glow, a soft highlight, or a scrim working over both an image and a plain surface.Do not stack a low opacity on top of an already-weak colour. Prefer the alpha token. And do not use *-background-weak as an accent: it is nearly the page colour, so it disappears.
surface when you do not want to pick a side
background="surface" is the neutral raised panel. It follows the theme without naming neutral, brand, or anything else. Pair it with a quiet border and you have the static panel recipe most product UIs live on:
<Column
background="neutral-medium"
onBackground="neutral-strong"
padding="24"
radius="l"
gap="8"
>
<Heading variant="heading-strong-m">Panel title</Heading>
<Text variant="body-default-s" onBackground="neutral-weak">
Supporting copy stays on the same surface.
</Text>
</Column>
