Token customization - Cognite Docs

Aura’s token system is designed to be used as-is for the vast majority of use cases. Tokens are centrally maintained and contrast-tested across themes. By using the defaults, consuming applications automatically receive proper theming, accessibility compliance, and future design updates. Some scenarios still require extending or overriding these defaults — typically when building a Flows custom app that needs a customer-facing brand on top of Aura defaults.

Do not customize styling for Cognite Data Fusion (CDF) native apps. Cognite is developing a solution that will enable global theming across all of CDF.

Customization priorities

Builders can customize every color token, but not every group needs to change for a successful rebrand. Work through these priorities in order.

Priority	Token groups	Guidance
Recommended	`primary-`, `secondary-`, `ring-`, `link-`	Brand colors — highest impact for CTAs, selected states, and toggled UI
Recommended	`decorative-1`–`decorative-7`	Accent colors for tags, avatars, and badges — override background, hover, and foreground together
Optional	`chart-`, `heatmap-`	Data visualizations
Optional	`success-`, `warning-`, `critical-`, `info-`, `destructive-`, `neutral-`	Status colors — not required for rebrand; stay within each hue family if changed
Rarely needed	`base-`, `muted-`, `medium-`, `popover-`, `card-`, `border-`	Neutral tuning — shift the UI warmer or cooler using gray ramps

For resolved values and usage notes for every token, see Color.

For designers

Before you override anything

Ask these questions first:

Does an existing token cover this use case? Check Color.
Is this a product-specific need or a system gap? If it feels like a system gap, raise it with Cognite.
Will this hold up in both light and dark mode? Overrides that only work in one theme are a red flag.

Aura’s color system has two tiers:

Ramps — raw hue scales (for example fjord-500, mountain-950) that progress evenly in lightness.
Semantic tokens — named roles (for example primary/background, base/foreground) that map to ramp steps and swap between light and dark mode automatically.

When customizing for a customer brand:

Apply tokens as sets. Most groups include matching background, background-hover, and foreground tokens — override them together so contrast stays intact.
Never put raw hex on semantic tokens. Alias each semantic token to a step on your local brand ramp in Figma.
Keep Cognite Light and Dark modes as reference. Add separate brand modes (for example your-org-Light and your-org-Dark) in a local variable collection rather than editing the published Aura library.
Work in this order: Primary and Secondary → Decorative → Feedback and status → Neutrals.

Figma workflow

Enable the Aura community file as a library in your project.
Create a local variable collection for brand ramps (primary, secondary, optional decorative and neutral hues). Match Aura’s step naming — 10, 50, 100 … 950.
Add brand Light and Dark modes alongside the Cognite reference modes.
In your brand modes only, re-alias semantic tokens to your ramp steps — starting with primary/* and secondary/*.

Code implementation uses CSS variable overrides in src/styles.css. A skill is in development to help translate Figma customizations to code automatically. Until then, share aliased token names with developers so they can add matching overrides.

For developers

Follow these rules for safe overrides:

Scope to your app’s root element or a specific component — never override globally outside your app.
Override both light (:root) and dark (.dark) values for theme-sensitive tokens.
Test contrast in both themes before shipping.
Document the override and the reason in your codebase.

Applying a custom theme

Define token overrides centrally in src/styles.css so they cascade to all Aura components.

@import '@cognite/aura/styles.source.css';

@source '../node_modules/@cognite/aura/dist/components';

:root {
  --font-inter: "Roboto", ui-sans-serif, system-ui, sans-serif;
  --font-source-code-pro: "Source Code Pro", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
    "Liberation Mono", "Courier New", monospace;

  /* Custom brand tokens — light mode */
  --primary-background: #5B4FD9;
  --primary-background-hover: #4338CA;
  --primary-foreground: #FFFFFF;
  --secondary-background: #E2E4E6;
  --secondary-background-hover: #D5D8DB;
  --secondary-foreground: #33373A;
}

.dark {
  /* Custom brand tokens — dark mode */
  --primary-background: #8B7CF8;
  --primary-background-hover: #5B4FD9;
  --primary-foreground: #FFFFFF;
  --secondary-background: #33373A;
  --secondary-background-hover: #5C6369;
  --secondary-foreground: #D5D8DB;
}

@import '@cognite/aura/styles.source.css';

@source '../node_modules/@cognite/aura/dist/components';

:root {
  --font-inter: "Roboto", ui-sans-serif, system-ui, sans-serif;
  --font-source-code-pro: "Source Code Pro", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
    "Liberation Mono", "Courier New", monospace;
}

Scoped CSS variable overrides

If overrides apply only to part of your app, use a scoped selector instead of :root:

[data-app="my-app"] {
  --primary-background: #5B4FD9;
  --secondary-background: #E2E4E6;
}

Color tokens to customize

Tokens are grouped by semantic role, matching the Color reference. Override related background, hover, and foreground tokens together.

Primary (brand) — Recommended

The primary brand color. Reserved for emphasis and interaction — main CTAs and selected states in checkboxes, tabs, radio buttons, and switches. Do not use for general neutral UI.

CSS variable	Override when
`--primary-background`	Primary action buttons and key CTAs
`--primary-background-hover`	Hover on primary actions
`--primary-foreground`	Text and icons on primary surfaces
`--primary-background-fixed-dark`	Primary surfaces locked to light in both themes
`--primary-background-hover-fixed-dark`	Hover on fixed-dark primary surfaces
`--primary-foreground-fixed-dark`	Text/icons on fixed-dark primary surfaces
`--ring-default`	Focus state for interactive elements with keyboard navigation, generally reflects brand color
`--ring-muted`	Focus state for interactive elements with keyboard navigation, generally reflects brand color
`--link-foreground`, `--link-foreground-hover`	Must be a different color from standard text color, often blue or associated with brand color

Secondary (brand) — Recommended

The secondary brand color. Used for secondary CTAs and toggled or selected states — toggle buttons, selected list items, selected cards.

CSS variable	Override when
`--secondary-background`	Secondary buttons and switch backgrounds
`--secondary-background-hover`	Hover on secondary surfaces
`--secondary-foreground`	Text and icons on secondary surfaces
`--secondary-background-fixed-dark`	Secondary surfaces locked to dark in both themes
`--secondary-background-hover-fixed-dark`	Hover on fixed-dark secondary surfaces
`--secondary-foreground-fixed-dark`	Text/icons on fixed-dark secondary surfaces

Decorative — Recommended

Accent colors for avatars, badges, and visual differentiation — no status meaning. Override each numbered group (decorative/1 through decorative/7) as a set.

CSS variable pattern	Override when
`--decorative-{n}-background`	Fill for decorative accent `n`
`--decorative-{n}-background-hover`	Hover on decorative accent `n`
`--decorative-{n}-foreground`	Text/icons on decorative accent `n`

Replace {n} with 1–7. See Decorative for default values.

Feedback and status — Optional

Semantic colors for alerts, banners, badges, and toasts. Not required for a successful rebrand. If you change them, keep each token within its intended hue family — warning should still read as warning.

Group	CSS variable examples
Success	`--success-background`, `--success-foreground`
Warning	`--warning-background`, `--warning-foreground`
Critical	`--critical-background`, `--critical-foreground`, `--ring-critical-default`, `--ring-critical-muted`
Info	`--info-background`, `--info-foreground`
Destructive	`--destructive-background`, `--destructive-foreground`
Neutral	`--neutral-background`, `--neutral-foreground`

Neutrals — Optional

Shift the UI warmer or cooler by overriding neutral layers. Use Cognite defaults as a contrast and lightness guide — your grays should follow the same relative steps on your chosen neutral ramp.

Group	CSS variable examples
Base	`--base-background`, `--base-foreground`
Muted	`--muted-background`, `--muted-foreground`
Medium	`--medium-background`, `--medium-foreground`
Border	`--border-default`, `--border-emphasized`, `--border-disabled`

Chart & heatmap — Optional

Chart and heatmap colors are only used for data visualizations. Chart colors often use an extension of the decorative brand palette. Preferred chart colors start with chart-1-450 and decrease in step as more colors in the same hue are needed.

CSS variable pattern	Override when
`--chart-{n}-50`	Fill for decorative chart color `n`
`--chart-{n}-100`	Fill for decorative chart color `n`
`--chart-{n}-200`	Fill for decorative chart color `n`
`--chart-{n}-300`	Fill for decorative chart color `n`
`--chart-{n}-400`	Fill for decorative chart color `n`
`--chart-{n}-450`	Fill for decorative chart color `n`
`--heat-map-intense`	Fill for strongest, most saturated heat map color
`--heat-map-strong`	Fill for second strongest heat map color
`--heat-map-moderate`	Fill for third strongest heat map color
`--heat-map-mild`	Fill for fourth strongest heat map color

Replace {n} with 1–5. Chart tokens use semi-transparent ramp values for data visualization series. Override only when remapping chart colors to a customer palette. See Chart for the full series list. See Color theme tokens for the full list per group.

Typography tokens to override

Typefaces

Token	Font	Use
`--font-sans` / `--font-inter`	Inter	Main product copy — UI text, labels, and dense interfaces
`--font-mono`	Source Code Pro	Code blocks, technical strings, terminal output
`--font-display`	Space Grotesk	Display fonts for splash screens, onboarding, or marketing

Text (Inter)

Token	Description	Size	Line height	Weight
`xxs/normal`	Metadata; short labels	10px	12px	Regular
`xxs/medium`	Metadata; short labels; emphasized	10px	12px	Medium
`xs/normal`	Small captions and chart labels	12px	14px	Regular
`xs/medium`	Small captions and chart labels; emphasized	12px	14px	Medium
`sm/normal`	Secondary text, small labels	14px	18px	Regular
`sm/medium`	Secondary text, small labels; emphasized	14px	18px	Medium
`base/normal`	Default body text	16px	20px	Regular
`base/medium`	Default body text; emphasized	16px	20px	Medium
`lg/normal`	Large text, sub-headlines	18px	24px	Regular
`lg/medium`	Large text, sub-headlines; emphasized	18px	24px	Medium
`xl/normal`	Headlines, small titles	20px	24px	Regular
`xl/medium`	Headlines, small titles; emphasized	20px	24px	Medium
`2xl/normal`	Page headers, titles	24px	28px	Regular
`2xl/medium`	Page headers, titles; emphasized	24px	28px	Medium
`3xl/normal`	Splash screens, onboarding, or login	30px	32px	Regular
`3xl/medium`	Splash screens, onboarding, or login; emphasized	30px	32px	Medium
`4xl/normal`	Splash screens, onboarding, or login	36px	40px	Regular
`4xl/medium`	Splash screens, onboarding, or login; emphasized	36px	40px	Medium
`5xl/normal`	Splash screens, onboarding, or login	48px	44px	Regular
`5xl/medium`	Splash screens, onboarding, or login; emphasized	48px	44px	Medium

Code (Source Code Pro)

Token	Description	Size	Line height	Weight
`sm`	Code blocks, snippets, and technical strings	14px	18px	Regular
`md`	Code blocks, snippets, and technical strings	16px	20px	Regular
`lg`	Code blocks, snippets, and technical strings	18px	24px	Regular

Building custom components

When your requirements fall outside the scope of existing Aura components, you may need to build custom UI elements. To maintain system stability and visual consistency, follow these guidelines.

File structure

Custom components: Place in src/components/common/.
Static assets (images, icons): Place in src/assets/.

Extend Aura primitives

Whenever possible, build custom components by composing Aura primitives (such as Button, Card, and Input) rather than writing raw HTML and custom CSS from scratch. Benefits of extending Aura primitives:

Automatic theming — Components built with Aura primitives inherit your custom design tokens. Updates to src/styles.css apply automatically.
Built-in accessibility — Primitives include baseline ARIA roles and keyboard navigation.
Upgrade compatibility — Custom components inherit updates to the Aura design system, reducing maintenance overhead.

​Customization priorities

​For designers

​Before you override anything

​Figma workflow

​For developers

​Applying a custom theme

​Scoped CSS variable overrides

​Color tokens to customize

​Primary (brand) — Recommended

​Secondary (brand) — Recommended

​Decorative — Recommended

​Feedback and status — Optional

​Neutrals — Optional

​Chart & heatmap — Optional

​Typography tokens to override

​Typefaces

​Text (Inter)

​Code (Source Code Pro)

​Building custom components

​File structure

​Extend Aura primitives

​Related resources

Customization priorities

For designers

Before you override anything

Figma workflow

For developers

Applying a custom theme

Scoped CSS variable overrides

Color tokens to customize

Primary (brand) — Recommended

Secondary (brand) — Recommended

Decorative — Recommended

Feedback and status — Optional

Neutrals — Optional

Chart & heatmap — Optional

Typography tokens to override

Typefaces

Text (Inter)

Code (Source Code Pro)

Building custom components

File structure

Extend Aura primitives

Related resources