> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token customization

> How to apply customer brand colors to Aura in Figma and code — which token groups to customize, and how to override safely in Flows custom apps.

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.

<Warning>
  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.
</Warning>

## 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](/aura-design-system/foundations/color).

## For designers

### Before you override anything

Ask these questions first:

1. **Does an existing token cover this use case?** Check [Color](/aura-design-system/foundations/color).
2. **Is this a product-specific need or a system gap?** If it feels like a system gap, [raise it with Cognite](mailto:support@cognite.com).
3. **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:

1. **Ramps** — raw hue scales (for example `fjord-500`, `mountain-950`) that progress evenly in lightness.
2. **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

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

<Note>
  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.
</Note>

## 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.

<CodeGroup>
  ```css src/styles.css (After) wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  @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;
  }
  ```

  ```css src/styles.css (Before) wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  @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;
  }
  ```
</CodeGroup>

### Scoped CSS variable overrides

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

```css theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
[data-app="my-app"] {
  --primary-background: #5B4FD9;
  --secondary-background: #E2E4E6;
}
```

## Color tokens to customize

Tokens are grouped by semantic role, matching the [Color](/aura-design-system/foundations/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](/aura-design-system/foundations/color#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](/aura-design-system/foundations/color#chart) for the full series list.

See [Color theme tokens](/aura-design-system/foundations/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.

## Related resources

* [Color](/aura-design-system/foundations/color)
* [About Aura](/aura-design-system/what-is-aura)
* [Exploring Aura foundations](/aura-design-system/foundations/index)