Color

Color comes in four groups: surfaces (what things sit on), text, edges, and the eight color roles used for actions and status. Every value below is checked for contrast in all three themes.

Contrast guarantees

• Text roles reach 4.5:1 against the surfaces they're meant for, in every theme: the default, muted and glass text roles on the page, raised, sunken and overlay surfaces, and --apui-text-inverse on --apui-surface-inverse. --apui-text-default reaches 12:1. Don't put a regular text role on the inverse surface, or inverse text on a regular one.
• Control edges and the focus ring reach 3:1 (WCAG 1.4.11).
• Glass text is checked over black, white, saturated red and saturated blue backdrops.
• Status is never shown by color alone. Components pair it with a label or an icon, and so should you.

Surfaces

From lowest to highest:

Text

• --apui-text-default for body text.
• --apui-text-muted for hints, captions and placeholders.
• --apui-text-subtle for non-text icons only: it reaches 3:1, not 4.5:1.
• --apui-text-disabled, --apui-text-inverse and --apui-text-muted-glass (muted text on glass).

Don't lower text contrast with opacity. An opacity isn't checked against the surface behind it; --apui-text-muted is.

Edges

• --apui-border-muted: the hairline around containers. Set it to a transparent color for pure tonal layering.
• --apui-border-default: control outlines, 3:1 or better.
• --apui-border-strong: hover and selected edges.

Color roles

Eight colors share the same seven roles, so every variant of every component is a fixed recipe:

The variants use them like this:

Solid accent and warning carry an edge because, in light mode, their fills sit below 3:1 against the page.

All color tokens

States and focus

Charts and code

--apui-chart-1 to --apui-chart-6 are a categorical palette for data series, assigned in order and never cycled. They were checked for colorblind separation between neighbors. Some chart colors sit under 3:1 against the surface in light mode, so every chart ships hover and focus tooltips, direct labels and a table view. The syntax colors are checked at 4.5:1 on --apui-surface-sunken, where code sits.

Using color well

• One solid primary button per view. Use soft, outline or ghost for the rest.
• Keep navigation, panels and labels neutral.
• Use the accent role for the one thing that should stand out, not a new variant.
• Pair every status color with a label or an icon.