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 defines fixed color families using OKLCH. Each family has steps 0, 5, 10 through 90 in tens, 95, and 100. These are palette names, not percentages or opacity values.
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>Natural material colors
Eight material-inspired families extend the palette with warm neutrals, botanical greens, mineral blue-green, and fired earth. Each has all thirteen fixed steps, a base hue alias such as bg-petrol, and a foreground alias such as text-petrol.
| Family | Character | Pairing direction |
|---|---|---|
sand | Golden beige with warm umber shadows | Plaster, paper, and warm editorial surfaces |
taupe | Restrained red-brown gray | Quiet typography and architectural neutrals |
olive | Mature yellow-green | Botanical accents beside sand or taupe |
sage | Soft gray-green | Calm surfaces and natural lifestyle interfaces |
moss | Fuller leaf green | Plant imagery and accents beside sage |
petrol | Deep mineral blue-green | Cool backdrops beside warm materials |
copper | Golden orange-brown | Warm accents distinct from red clay |
terracotta | Muted red clay with peach tints | Ceramic, craft, and boutique compositions |
The lightest steps retain a tint; the darkest retain the material's hue. Step numbers describe an ordered palette, not equal lightness or guaranteed contrast between families. The curves are individually tuned rather than shared across every hue.
<article class="bg-sand-5 fg-taupe-80 bg-taupe-95@dark fg-sand-10@dark"> Warm materials, with explicit light and dark pairings.</article><p class="surface-raised text-petrol">A mode-aware mineral accent.</p>All eight families fit within Display P3. Petrol's 60 and 70 steps use a small extension beyond sRGB; other new steps fit sRGB. Browsers map colors to the display's available gamut. Copy the OKLCH value or CSS variable to preserve the authored color; a hex representation is an sRGB approximation.
The new text:<family> aliases meet at least 4.5:1 against the matching preset base, muted, raised, and overlay surfaces in both modes, measured after sRGB gamut mapping. Check contrast again when changing the surface, adding transparency, or choosing a fixed step or base hue alias. See WCAG's text contrast guidance.
olive now resolves to the mode-aware preset family, just as red and blue do. Existing classes such as fg-olive and bg-olive therefore change appearance. To retain the CSS named olive color, use a literal such as fg:#808000 or background-color:#808000.
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.
| Decision | Use | Examples |
|---|---|---|
| Fixed swatch | Palette steps | bg-blue-5, fg-blue-60 |
| App structure and hierarchy | Preset roles | bg-surface-base, surface-raised, b-base, text-body |
| Mode-aware hue choice | Hue aliases | bg-blue, fg-blue, text-blue |
<main class="bg-surface-base text-body"> <section class="b:1px|solid|var(--color-line-base) surface-raised"> <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.
| Group | Utility keys | Description |
|---|---|---|
| General paint | bg, background-color, fg, color, accent-color, fill, filter | Use palette steps and base hue aliases for broad paint decisions. |
| Surfaces | surface | Use surface roles for panels, cards, overlays, and inverse blocks. |
| Line roles | b, bt, br, bb, bl, bx, by, border, border-color, outline, outline-color, stroke | Use line roles for borders, dividers, outlines, and strokes before falling back to palette colors. |
| Text roles | text, fg, color, caret-color, text-fill-color, -webkit-text-fill-color, text-decoration, text-decoration-color | Use text roles for readable foreground hierarchy and interaction states. |
| Effects and strokes | shadow, box-shadow, text-shadow, text-stroke, text-stroke-color, backdrop-filter | Use color tokens where paint appears inside effects or stroke utilities. |
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.
| Token | Class | Role |
|---|---|---|
--color-surface-base | surface-base | Root page or app background. |
--color-surface-muted | surface-muted | Subdued sections and low-emphasis blocks. |
--color-surface-raised | surface-raised | Raised cards, controls, and stacked surfaces. |
--color-surface-overlay | surface-overlay | Floating layers such as dialogs, popovers, and menus. |
--color-surface-inverse | surface-inverse | High-contrast inverse surfaces. |
<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.
| Token | Class | Role |
|---|---|---|
--color-line-base | b-base | Default borders, dividers, outlines, and strokes. |
--color-line-strong | b-strong | Emphasized boundaries and selected states. |
--color-line-muted | b-muted | Quiet separators in dense interfaces. |
--color-line-subtle | b-subtle | Low-contrast hairlines and soft outlines. |
<div class="b:1.25rem|solid|var(--color-line-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.
| Token | Class | Role |
|---|---|---|
Aa--color-text-body | text-body | Default readable foreground text. |
Aa--color-text-strong | text-strong | Headings, labels, and emphasized foreground text. |
Aa--color-text-muted | text-muted | Secondary copy, metadata, and quiet navigation. |
Aa--color-text-subtle | text-subtle | Low-emphasis helper text and placeholder-adjacent content. |
Aa--color-text-disabled | text-disabled | Unavailable actions and disabled controls. |
Aa--color-text-placeholder | text-placeholder | Input placeholders. |
Aa--color-text-inverse | text-inverse | Text on inverse surfaces. |
Aa--color-text-link | text-link | Default inline links. |
Aa--color-text-link-hover | text-link-hover | Interactive link hover state. |
Revenue is on track for the current cycle.
Updated 12 minutes ago
Archived export unavailable
Open reportRevenue is on track for the current cycle.
Updated 12 minutes ago
Archived export unavailable
Open report<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.
| Token | Class | Use for |
|---|---|---|
--color-stone | bg-stonefg-stone | Mode-aware stone for backgrounds and foregrounds. |
--color-gray | bg-grayfg-gray | Mode-aware gray for backgrounds and foregrounds. |
--color-neutral | bg-neutralfg-neutral | Mode-aware neutral for backgrounds and foregrounds. |
--color-slate | bg-slatefg-slate | Mode-aware slate for backgrounds and foregrounds. |
--color-brown | bg-brownfg-brown | Mode-aware brown for backgrounds and foregrounds. |
--color-orange | bg-orangefg-orange | Mode-aware orange for backgrounds and foregrounds. |
--color-amber | bg-amberfg-amber | Mode-aware amber for backgrounds and foregrounds. |
--color-yellow | bg-yellowfg-yellow | Mode-aware yellow for backgrounds and foregrounds. |
--color-lime | bg-limefg-lime | Mode-aware lime for backgrounds and foregrounds. |
--color-green | bg-greenfg-green | Mode-aware green for backgrounds and foregrounds. |
--color-beryl | bg-berylfg-beryl | Mode-aware beryl for backgrounds and foregrounds. |
--color-teal | bg-tealfg-teal | Mode-aware teal for backgrounds and foregrounds. |
--color-cyan | bg-cyanfg-cyan | Mode-aware cyan for backgrounds and foregrounds. |
--color-sky | bg-skyfg-sky | Mode-aware sky for backgrounds and foregrounds. |
--color-blue | bg-bluefg-blue | Mode-aware blue for backgrounds and foregrounds. |
--color-indigo | bg-indigofg-indigo | Mode-aware indigo for backgrounds and foregrounds. |
--color-violet | bg-violetfg-violet | Mode-aware violet for backgrounds and foregrounds. |
--color-purple | bg-purplefg-purple | Mode-aware purple for backgrounds and foregrounds. |
--color-fuchsia | bg-fuchsiafg-fuchsia | Mode-aware fuchsia for backgrounds and foregrounds. |
--color-pink | bg-pinkfg-pink | Mode-aware pink for backgrounds and foregrounds. |
--color-crimson | bg-crimsonfg-crimson | Mode-aware crimson for backgrounds and foregrounds. |
--color-red | bg-redfg-red | Mode-aware red for backgrounds and foregrounds. |
--color-sand | bg-sandfg-sand | Mode-aware sand for backgrounds and foregrounds. |
--color-taupe | bg-taupefg-taupe | Mode-aware taupe for backgrounds and foregrounds. |
--color-olive | bg-olivefg-olive | Mode-aware olive for backgrounds and foregrounds. |
--color-sage | bg-sagefg-sage | Mode-aware sage for backgrounds and foregrounds. |
--color-moss | bg-mossfg-moss | Mode-aware moss for backgrounds and foregrounds. |
--color-petrol | bg-petrolfg-petrol | Mode-aware petrol for backgrounds and foregrounds. |
--color-copper | bg-copperfg-copper | Mode-aware copper for backgrounds and foregrounds. |
--color-terracotta | bg-terracottafg-terracotta | Mode-aware terracotta for backgrounds and foregrounds. |
<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.
| Token | Class | Use for |
|---|---|---|
Aa--color-text-stone | text-stone | Mode-aware stone foreground text. |
Aa--color-text-gray | text-gray | Mode-aware gray foreground text. |
Aa--color-text-neutral | text-neutral | Mode-aware neutral foreground text. |
Aa--color-text-slate | text-slate | Mode-aware slate foreground text. |
Aa--color-text-brown | text-brown | Mode-aware brown foreground text. |
Aa--color-text-orange | text-orange | Mode-aware orange foreground text. |
Aa--color-text-amber | text-amber | Mode-aware amber foreground text. |
Aa--color-text-yellow | text-yellow | Mode-aware yellow foreground text. |
Aa--color-text-lime | text-lime | Mode-aware lime foreground text. |
Aa--color-text-green | text-green | Mode-aware green foreground text. |
Aa--color-text-beryl | text-beryl | Mode-aware beryl foreground text. |
Aa--color-text-teal | text-teal | Mode-aware teal foreground text. |
Aa--color-text-cyan | text-cyan | Mode-aware cyan foreground text. |
Aa--color-text-sky | text-sky | Mode-aware sky foreground text. |
Aa--color-text-blue | text-blue | Mode-aware blue foreground text. |
Aa--color-text-indigo | text-indigo | Mode-aware indigo foreground text. |
Aa--color-text-violet | text-violet | Mode-aware violet foreground text. |
Aa--color-text-purple | text-purple | Mode-aware purple foreground text. |
Aa--color-text-fuchsia | text-fuchsia | Mode-aware fuchsia foreground text. |
Aa--color-text-pink | text-pink | Mode-aware pink foreground text. |
Aa--color-text-crimson | text-crimson | Mode-aware crimson foreground text. |
Aa--color-text-red | text-red | Mode-aware red foreground text. |
Aa--color-text-sand | text-sand | Mode-aware sand foreground text. |
Aa--color-text-taupe | text-taupe | Mode-aware taupe foreground text. |
Aa--color-text-olive | text-olive | Mode-aware olive foreground text. |
Aa--color-text-sage | text-sage | Mode-aware sage foreground text. |
Aa--color-text-moss | text-moss | Mode-aware moss foreground text. |
Aa--color-text-petrol | text-petrol | Mode-aware petrol foreground text. |
Aa--color-text-copper | text-copper | Mode-aware copper foreground text. |
Aa--color-text-terracotta | text-terracotta | Mode-aware terracotta foreground text. |
<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: var(--color-white); --color-surface-raised: var(--color-white); --color-line-base: oklch(0% 0 none / 0.12); --color-text-body: var(--color-neutral-70); --color-text-muted: var(--color-neutral-60);}@theme dark { --color-surface-base: var(--color-gray-95); --color-surface-raised: var(--color-gray-90); --color-line-base: oklch(100% 0 none / 0.12); --color-text-body: var(--color-gray-30); --color-text-muted: var(--color-gray-40);}<main class="bg-surface-base text-body"> <section class="b:1px|solid|var(--color-line-base) surface-raised"> <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.