To extend or customize color tokens in a consuming app, see Token customization reference.
The two layers
Layer 1 — Color ramps
Ramps are the source material. Each hue has a sequential scale (for examplefjord-50 through fjord-950) covering the full range of tints and shades. Alpha variants (fjord-alpha-50, fjord-alpha-200) are semi-transparent overlays built from the ramp’s base color, primarily intended for charts and data visualization.
Ramps exist so tokens have something to point to. You should rarely reference ramp values directly in product UI. The only valid exceptions are:
- A color must stay visually constant across both themes (use a fixed token instead if one exists)
- You are building a custom marketing or illustration surface where no semantic token fits and theming is not a concern
Layer 2 — Tokens
Tokens are named CSS custom properties that resolve to a ramp step. They are the vocabulary product UI speaks. A token likebackground points to mountain-white in light mode and mountain-950 in dark mode — the name stays the same, the value changes with the theme.
Light and dark theming
Every token has a light mode value and a dark mode value. The token name never changes — only what it resolves to. This means:- Product code never needs
dark:overrides for tokens - Switching themes is handled entirely by the system
- Contrast has been verified for both themes for every token
How ramp steps map across themes
As a general pattern, light mode uses lighter ramp steps for surfaces and darker steps for text. Dark mode inverts this:Fixed tokens
Fixed tokens are the deliberate exception to the theming rule. They resolve to the same value in both light and dark mode — they do not flip with the theme. Unlike theme-adaptive surfaces, fixed colors stay consistent across light and dark mode — keeping these elements from becoming too stark against an inverted backgroundDos and don’ts
Do use tokens as named
Do use tokens as named
Token names reflect their intended use and have been contrast-tested in both themes. Using
destructive-foreground for something that isn’t destructive, or info-background as a decorative accent, undermines both the visual language and accessibility guarantees.Don't use raw hex values
Don't use raw hex values
Raw hex values don’t respond to theme changes. A hardcoded
#FFFFFF looks correct in light mode and breaks in dark mode. Always use a token.Don't adjust opacity manually
Don't adjust opacity manually
Manual opacity adjustments (
opacity: 0.5, custom rgba() values) bypass the token system and produce colors that aren’t theme-tested. Use alpha tokens from the ramp instead.Don't use semantic tokens decoratively
Don't use semantic tokens decoratively
Semantic tokens — info, success, warning, destructive — exist to communicate system states. Using a green semantic background as a decorative accent trains users to ignore real success states. Use decorative tokens for visual differentiation that carries no status meaning.
Theme tokens
Theme tokens are the vocabulary product UI speaks. They are organized into four families — base, semantic, decorative, and chart — each with a distinct job. Tokens resolve to different ramp values in light and dark mode automatically; product code never needs to writedark: overrides for tokens.
Base tokens cover the vast majority of UI and are organized into background, foreground, and border and ring subfamilies. Semantic tokens should only appear in components that carry a status signal. Decorative tokens add color where it carries no status meaning. Chart tokens are semi-transparent colors derived from the alpha ramps — use default series colors in sequence, and semantic chart colors only when the data itself carries that meaning.
Base
Base tokens cover most interactive elements and surfaces — backgrounds, text, borders, and interactive states.Background
Surface, action, and interactive state color tokens.- Light
- Dark
Fixed tokens in this table resolve to the same value in both themes. See Fixed tokens for when to use them.
Foreground
Text, icon, and link color tokens.- Light
- Dark
Border and ring
Border and focus ring color tokens.- Light
- Dark
Semantic
Semantic tokens communicate status and meaning. They account for 5–10% of the UI and should only appear in components that carry a status signal — Alert, Banner, Sonner toasts, status Badge variants, and form validation. Do not use them as general fills or decorative accents. Each family has a default background/foreground pair for theme-switching surfaces, a*-muted-background for use on persistent dark chrome, and a *-foreground-on-* token for text rendered directly on the colored surface.
Background
- Light
- Dark
Foreground
- Light
- Dark
Decorative
Decorative tokens add color for visual differentiation — for avatars, badges, and illustrations — where color has no status meaning. Do not use them to imply health, errors, or validation state. Preference order for layering in colors: fjord → nordic → aurora → dusk → orange → sky → mountain.Background
- Light
- Dark
Foreground
- Light
- Dark
Data visualizations
Chart tokens are semi-transparent colors derived from the alpha ramps and are intended for charts and data visualizations. They are organized into default series colors and semantic status colors. Choosing colors for data visualization- Single color, varying opacity works best for magnitude or intensity within one category — like a heatmap or density chart. Use levels 1–6 in order from most to least opaque.
- Multiple colors are for distinguishing unrelated categories — like separate series in a line chart. Limit to what’s necessary; more colors add noise.
- Semantic colors (error, warning, success, info) should only appear when the data carries that meaning. Do not repurpose them for neutral categories just for variety.
- Highlighting uses color to direct attention — keep most data in a neutral or muted state and use a prominent color only on the value that matters. If everything is highlighted, nothing is.
Default
Default chart colors ordered 1–6 from most opaque to most transparent. Use them in sequence, starting with fjord.Fjord
Fjord is the default series color for data visualization.- Light
- Dark
Nordic
Nordic is the secondary series color for data visualization.- Light
- Dark
Dusk
Dusk is the tertiary series color for data visualization.- Light
- Dark
Aurora
Aurora is the quaternary series color for data visualization.- Light
- Dark
Orange
Orange is the quinary series color for data visualization.- Light
- Dark
Semantic
Semantic chart colors communicate status within data visualizations. Only use them when the data itself carries that meaning — not for neutral series variety.Informational
- Light
- Dark
Success
- Light
- Dark
Warning
- Light
- Dark
Error
- Light
- Dark
Neutral
- Light
- Dark
Gridlines
- Light
- Dark
Color ramps
Color ramps are sequential scales of tints and shades for a single hue (for example,mountain-50 through mountain-950). Themed tokens map to specific steps on these ramps and swap their values between light and dark mode — so background points to mountain-white in light mode and mountain-950 in dark mode.
Use themed tokens, not raw ramp values — unless a color must stay constant across both themes, or you are building a custom marketing or illustration surface where no semantic token fits.
Alpha values (mountain/50, fjord/200, etc.) are semi-transparent overlays built from the ramp’s base color. They are primarily intended for charts and data visualizations and are intentionally more muted. Light theme alphas map from 50–450 with 500 as the base; dark theme alphas map from 600–950 with 550 as the base.
Mountain
Neutral base palette for text, surfaces, and borders.- Default
- Alpha
Fjord
Primary decorative color used for charts.- Default
- Alpha
Nordic
Primary decorative color used for charts and Atlas AI.- Default
- Alpha
Aurora
Primary decorative color used for charts and decorative elements.- Default
- Alpha
Dusk
Primary decorative color used for charts and decorative elements.- Default
- Alpha
Sky
Secondary decorative color used for badges, avatars, and illustrations.- Default
- Alpha
Orange
Secondary decorative color used for badges, avatars, and illustrations.- Default
- Alpha
Yellow
Secondary decorative color used for badges, avatars, and illustrations.- Default
- Alpha
Pink
Secondary decorative color used for badges, avatars, and illustrations.- Default
- Alpha
Gray
Used for focus states and secondary decorative elements.- Default
- Alpha
Red
Maps to semantic status colors for destructive actions and critical alerts.- Default
- Alpha
Amber
Maps to semantic status colors for warnings.- Default
- Alpha
Green
Maps to semantic status colors for success.- Default
- Alpha
Blue
Maps to semantic status colors for information.- Default
- Alpha