To extend or customize color tokens in a consuming app, see Token customization.
The two layers
Layer 1 — Color ramps
Ramps are the source material. Each hue has a sequential scale (for example--fjord-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 like--background 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 background.Dos 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 organized by semantic role. Each token uses a--group-property naming convention and resolves to different values in light and dark mode automatically.
Base
The default neutral layer. Used for page backgrounds, primary text, disabled states, and overlays. Start here for any neutral UI.- Light
- Dark
Muted
One step of contrast from Base — slightly darker in light mode, slightly lighter in dark mode. Used for subtle containers, sidebars, and shell elements that need separation from the page. For text, used for the lowest-priority content: metadata, captions, timestamps.- Light
- Dark
Medium
A further step of contrast from Muted. Used for inputs, fields, and interactive surfaces that need to read clearly on top of the page. For text, used for secondary content such as descriptions and long-form body copy.- Light
- Dark
Primary (brand)
The primary brand color (black for Cognite). Reserved for emphasis and interaction — main CTAs, and selected/active states in components like checkboxes, tabs, radio buttons, and switches. Do not use for general neutral UI. If you need black or dark gray structurally, use Base, not Primary.- Light
- Dark
Secondary (brand)
The secondary brand color (gray for Cognite). Use for secondary CTAs and toggled/selected states — toggle buttons, selected list items, selected cards. Same rule as Primary: don’t use it for general layout grays; use Muted or Medium for that.- Light
- Dark
Popover
Surface and foreground tokens for contained content in popovers, which are floating, elevated layers (menus, tooltips, dialogs). Highest in the stack; pair with shadow tokens.- Light
- Dark
Card
Surface and foreground tokens for contained content in cards, which are a distinct surface, but not floating on the page.- Light
- Dark
Destructive
Used for irreversible or destructive actions.- Light
- Dark
Link
Used for hyperlinks that link to external pages.- Light
- Dark
Border
Dividers and outlines used for page content separation, containers and inputs.- Light
- Dark
Ring
Focus indicators for keyboard navigation, including validation states.- Light
- Dark
Success
Indicates a positive, stable, or successful state.- Light
- Dark
Warning
Indicates an abnormal or warning state.- Light
- Dark
Critical
Indicates a negative, urgent, or critical state.- Light
- Dark
Info
Indicates a benign informational state such as running, active, published, or in progress.- Light
- Dark
Neutral
Indicates a neutral or archived state.- Light
- Dark
Decorative
Decorative colors are primarily used for badges, alerts, and other decorative visual elements. They do not convey semantic meaning, so semantic status colors should be avoided in these contexts. To support easy re-theming, decorative colors are named 1–7 rather than being tied to specific color names such as Blue or Orange. This naming convention keeps them independent of their visual appearance and makes it easier to update themes without renaming tokens.- Light
- Dark
Chart
Chart colors are for data visualizations and should be used in numerical order, starting with--chart-1, then --chart-2, and so on.
- Light
- Dark
Heat map
Heat map colors communicate intensity, magnitude, or density. They use a sequential progression from lower to higher values, helping users quickly identify patterns, concentrations, and outliers in data visualizations.- Light
- Dark
Shadow
Shadow colors define the tint and opacity used to create depth and elevation. They provide consistent visual separation between surfaces while maintaining a cohesive appearance across themes.- 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