Colors

Choose palette steps, preset color roles, and mode-aware hue aliases for light and dark UI.

Overview

Master CSS color tokens cover fixed palette steps, preset UI roles, and mode-aware hue aliases. Use palette steps when you need an exact swatch. Use preset roles for the repeated color decisions that define application structure, text hierarchy, and light or dark mode behavior.

Default color palette

The preset palette is a P3-compatible set of fixed color families. Each family ranges from 0, 5, 10, and then by tens through 100.

Choose palette steps directly for swatches, illustrations, brand accents, and status-color foundations. For page backgrounds, surfaces, lines, and text hierarchy, use preset roles so the same markup can adapt across modes.

<div class="bg:blue-5 fg:blue-60">…</div>

Choose a color token

Start with the kind of decision you are making. Most app chrome should use roles first, then reach for palette steps or hue aliases when the color itself is the point.

<main class="bg:surface-base text:body">    <section class="surface:raised b:1px|solid|base">        <h2 class="text:strong">Project updates</h2>        <p class="text:muted">Three milestones changed this week.</p>        <a class="text:link" href="#">Continue</a>    </section></main>

Namespaces for color

Color utilities use focused namespaces so role names stay short in markup. A key such as muted can mean a line role in b:muted, a surface role in surface:muted, or a text role in text:muted.

Use the narrow role namespace first when the color describes structure, line work, or text hierarchy. Use the general color namespace when the hue or swatch itself is the decision.

Preset color roles

Preset roles describe the job a color performs in the interface. Their values are mode-aware, so bg:surface-base, surface:raised, b:base, and text:body can stay stable while light and dark modes choose different underlying colors.

Surfaces

Surface tokens are for the page background, raised panels, floating layers, and inverse blocks. Use bg:surface-base for the root canvas and the dedicated surface:* shorthand for surface roles.

<section class="surface:base"></section>

Line roles

Line tokens are for borders, dividers, outlines, and strokes. base is the default line role. Border, outline, and stroke utilities search line roles before the general color palette.

<div class="b:5x|solid|base"></div>

Text roles

Text roles are for foreground hierarchy and interaction states. Prefer these roles for body copy, emphasis, disabled content, links, and inverse surfaces instead of using hue aliases as text hierarchy.

<article class="text:body">    <h2 class="text:strong">Quarterly report</h2>    <p class="text:muted">Updated 12 minutes ago</p>    <button class="text:disabled" disabled>Archive</button>    <a class="text:link text:link-hover:hover" href="#">Open report</a>    <span class="surface:inverse text:inverse">Private</span></article>

Mode-aware hue aliases

Hue aliases are shortcuts for choosing a color family while still letting the preset select a light or dark value. Use them when the hue itself matters; use roles when the color is describing structure or text hierarchy.

Base hue aliases

Base hue aliases work for backgrounds and foregrounds when you want a named hue that adapts across modes. Use palette steps when you need a fixed swatch instead.

<div class="bg:yellow"></div>

Use base hue aliases for foreground when you want a mode-aware color choice.

<div class="fg:yellow">Aa</div>

Text hue aliases

Text hue aliases choose foreground-oriented palette steps for light and dark modes. They are useful for colored text, but they do not replace semantic text roles such as text:body, text:muted, or text:link.

<div class="text:yellow">M</div>

Customize color roles

Override preset role tokens when a repeated UI decision needs product-specific colors. Keep markup semantic so components do not need separate light and dark color classes.

@theme light {    --color-surface-base: $color-white;    --color-surface-raised: $color-white;    --color-line-base: oklch(0% 0 none / 0.12);    --color-text-body: $color-neutral-70;    --color-text-muted: $color-neutral-60;}@theme dark {    --color-surface-base: $color-gray-95;    --color-surface-raised: $color-gray-90;    --color-line-base: oklch(100% 0 none / 0.12);    --color-text-body: $color-gray-30;    --color-text-muted: $color-gray-40;}

<main class="bg:surface-base text:body">    <section class="surface:raised b:1px|solid|base">        <p class="text:muted">The classes stay the same in every mode.</p>    </section></main>

Use @theme {} when a preset role should keep the same value in every mode. Use @theme light and @theme dark when the same role needs mode-specific values.