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

> Complete reference for extending or overriding Aura style tokens in a Flows custom app, including when scoped overrides are appropriate and which tokens to change.

Aura's token system is designed to be used as-is for the vast majority of use cases. The tokens are centrally maintained and contrast-tested across themes. By using the default tokens, consuming applications automatically receive proper theming, accessibility compliance, and future design updates.

Some scenarios still require extending or overriding these defaults. The sections below explain when scoped overrides are appropriate and how to implement them safely.

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

## Before you override anything

Ask these questions first:

1. **Does an existing token cover this use case?** Check [Color](/aura-design-system/foundations/color) — there are tokens for most surfaces, text roles, borders, semantic states, and decorative colors.
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) — the right fix is a new token, not a one-off override.
3. **Will this hold up in both light and dark mode?** Overrides that only work in one theme are a red flag.

Overrides are appropriate when:

* You are building a Flows custom app that needs to apply a customer-facing theme on top of Aura defaults.
* You need a one-off illustration or marketing surface that no semantic token covers.

## Applying custom theme

If you are applying a customer's brand to an app, override the smallest possible subset of base tokens.

While you can update decorative tokens to heavily express a customer's brand identity, avoid overriding semantic tokens (success, warning, error, info) unless strictly necessary. Semantic tokens carry meaning and are pre-tested for accessibility, so altering them can compromise legibility.

If you must override them, follow this guidance for safe overrides:

* Always scope to your app's root element or a specific component — never override globally.
* Override both light and dark values if the token is theme-sensitive.
* Test contrast in both themes before shipping.
* Document the override and the reason in your codebase.

### Defining custom tokens

When you need to override style tokens for a Flows custom app, define them centrally in your application's global stylesheet. This ensures your custom variables cascade down to all Aura components consistently.

Place your token overrides in the `src/styles.css` file in the root directory of your Flows custom app.

The following diff demonstrates how to apply customer brand colors to the primary and active token slots. Ensure you provide values for both the default (`:root`) light theme and the `.dark` theme context.

<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;
    --active-background: #DDD6FE;
    --active-background-hover: #A78BFA;
    --foreground-on-primary: #ffffff;
    --foreground-on-active: #1E1642;
    --background-fixed-dark: #1E1642;
  }

  .dark {
    /* Custom Brand Tokens - Dark Mode */
    --primary-background: #8B7CF8;
    --primary-background-hover: #5B4FD9;
    --active-background: #312E81;
    --active-background-hover: #1E1642;
    --foreground-on-primary: #ffffff;
    --foreground-on-active: #DDD6FE;
    --background-fixed-dark: #1E1642;
  }
  ```

  ```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 the styles are specific to a certain area in your application, use a scoped selector (for example, `[data-app="my-app"]`) instead of `:root` to avoid polluting the global namespace.

```css theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
/* Scope overrides to your app's root element */
[data-app="my-app"] {
  --background: #f5f5f5;
  --primary-background: #1a1a2e;
}
```

### Color tokens to override

Tokens are grouped by usage context. Related background, hover, foreground, and border tokens live together — so you can see how interactive states and layered tokens relate at a glance. For full resolved values, see [Color](/aura-design-system/foundations/color).

#### Primary

Primary is used on the default primary button, which is your main CTA for the page.

| Role               | Token                      | Override when                                |
| :----------------- | :------------------------- | :------------------------------------------- |
| Default fill       | `primary-background`       | Setting the default primary action surface   |
| Hover fill         | `primary-background-hover` | Matching hover on primary buttons and CTAs   |
| Foreground on fill | `foreground-on-primary`    | Text and icons rendered on a primary surface |

#### Active

Active is used on selected or active items in controls such as [Checkbox](/aura-design-system/primitives/checkbox), [Radio](/aura-design-system/primitives/radio), [Segmented control](/aura-design-system/primitives/segmented-control), [Switch](/aura-design-system/primitives/switch), [Progress](/aura-design-system/primitives/progress), [Pagination](/aura-design-system/primitives/pagination), and [Tabs](/aura-design-system/primitives/tabs).

| Role               | Token                           | Override when                                                                              |
| :----------------- | :------------------------------ | :----------------------------------------------------------------------------------------- |
| Default fill       | `active-background`             | Selected items in navigation and lists to indicate exclusive selection                     |
| Hover fill         | `active-background-hover`       | Hover on selected navigation items to indicate exclusive selection                         |
| Muted fill         | `active-muted-background`       | Subtle selected state in secondary navigation to indicate alternative, multiple selections |
| Muted hover fill   | `active-muted-background-hover` | Hover on muted active elements to indicate alternative, multiple selections                |
| Foreground on fill | `foreground-on-active`          | Text and icons on an active surface                                                        |
| Border             | `border-active`                 | Border on active or selected elements                                                      |

#### Link

Inline interactive text — hyperlinks and tappable text outside of button surfaces.

| Role    | Token             | Override when                          |
| :------ | :---------------- | :------------------------------------- |
| Default | `link-foreground` | Hyperlinks and interactive inline text |

#### Ring

Keyboard focus indicators. Override `ring` for brand-aligned focus; leave destructive variants unless you are theming error-state focus specifically.

| Role    | Token        | Override when                      |
| :------ | :----------- | :--------------------------------- |
| Default | `ring`       | Focus ring on interactive elements |
| Muted   | `ring-muted` | Subtle focus ring variant          |

#### Decorative

Visual differentiation for Avatar, Badge, and illustrations — color with no status meaning. Each hue is a self-contained group: override background, hover, and foreground together so text stays legible on the fill.

| Hue      | Background                       | Background hover                       | Foreground                       |
| :------- | :------------------------------- | :------------------------------------- | :------------------------------- |
| Fjord    | `decorative-background-fjord`    | `decorative-background-hover-fjord`    | `decorative-foreground-fjord`    |
| Nordic   | `decorative-background-nordic`   | `decorative-background-hover-nordic`   | `decorative-foreground-nordic`   |
| Aurora   | `decorative-background-aurora`   | `decorative-background-hover-aurora`   | `decorative-foreground-aurora`   |
| Dusk     | `decorative-background-dusk`     | `decorative-background-hover-dusk`     | `decorative-foreground-dusk`     |
| Orange   | `decorative-background-orange`   | `decorative-background-hover-orange`   | `decorative-foreground-orange`   |
| Sky      | `decorative-background-sky`      | `decorative-background-hover-sky`      | `decorative-foreground-sky`      |
| Mountain | `decorative-background-mountain` | `decorative-background-hover-mountain` | `decorative-foreground-mountain` |

#### Chart

Semi-transparent series colors for data visualization. Each series has six levels ordered from most opaque (`-color-1`) to most transparent (`-color-6`). Override the full level set for a hue when remapping that series to the customer palette.

**Default series** — use in sequence for unrelated categories (start with fjord).

| Series | Level 1 (strongest)    | Level 2                | Level 3                | Level 4                | Level 5                | Level 6 (lightest)     |
| :----- | :--------------------- | :--------------------- | :--------------------- | :--------------------- | :--------------------- | :--------------------- |
| Fjord  | `chart-fjord-color-1`  | `chart-fjord-color-2`  | `chart-fjord-color-3`  | `chart-fjord-color-4`  | `chart-fjord-color-5`  | `chart-fjord-color-6`  |
| Nordic | `chart-nordic-color-1` | `chart-nordic-color-2` | `chart-nordic-color-3` | `chart-nordic-color-4` | `chart-nordic-color-5` | `chart-nordic-color-6` |
| Dusk   | `chart-dusk-color-1`   | `chart-dusk-color-2`   | `chart-dusk-color-3`   | `chart-dusk-color-4`   | `chart-dusk-color-5`   | `chart-dusk-color-6`   |
| Aurora | `chart-aurora-color-1` | `chart-aurora-color-2` | `chart-aurora-color-3` | `chart-aurora-color-4` | `chart-aurora-color-5` | `chart-aurora-color-6` |
| Orange | `chart-orange-color-1` | `chart-orange-color-2` | `chart-orange-color-3` | `chart-orange-color-4` | `chart-orange-color-5` | `chart-orange-color-6` |

**Semantic series** — use only when the data carries that meaning (status, feedback, validation).

| Series  | Level 1 (strongest)     | Level 2                 | Level 3                 | Level 4                 | Level 5                 | Level 6 (lightest)      |
| :------ | :---------------------- | :---------------------- | :---------------------- | :---------------------- | :---------------------- | :---------------------- |
| Info    | `chart-info-color-1`    | `chart-info-color-2`    | `chart-info-color-3`    | `chart-info-color-4`    | `chart-info-color-5`    | `chart-info-color-6`    |
| Success | `chart-success-color-1` | `chart-success-color-2` | `chart-success-color-3` | `chart-success-color-4` | `chart-success-color-5` | `chart-success-color-6` |
| Warning | `chart-warning-color-1` | `chart-warning-color-2` | `chart-warning-color-3` | `chart-warning-color-4` | `chart-warning-color-5` | `chart-warning-color-6` |
| Error   | `chart-error-color-1`   | `chart-error-color-2`   | `chart-error-color-3`   | `chart-error-color-4`   | `chart-error-color-5`   | `chart-error-color-6`   |
| Neutral | `chart-neutral-color-1` | `chart-neutral-color-2` | `chart-neutral-color-3` | `chart-neutral-color-4` | `chart-neutral-color-5` | `chart-neutral-color-6` |

#### Semantic

Semantic colors indicate status or meaning and are used in Badge, Alert, Banner, and Sonner toasts. Use the pre-defined Aura tokens when possible because they are tested for accessibility. If you need to override them, use the tokens in the following tables.

The following tokens are paired together in semantic roles with a semantic foreground and background.

| Series  | Background           | Background muted           | Background hover           | Foreground on fill   |
| :------ | :------------------- | :------------------------- | :------------------------- | :------------------- |
| Info    | `info-background`    | `info-muted-background`    | `info-background-hover`    | `info-foreground`    |
| Success | `success-background` | `success-muted-background` | `success-background-hover` | `success-foreground` |
| Warning | `warning-background` | `warning-muted-background` | `warning-background-hover` | `warning-foreground` |
| Error   | `error-background`   | `error-muted-background`   | `error-background-hover`   | `error-foreground`   |
| Neutral | `neutral-background` | `neutral-muted-background` | `neutral-background-hover` | `neutral-foreground` |

The following tokens are for semantic foreground only and do not have a semantic background.

| Series  | Foreground                      |
| :------ | :------------------------------ |
| Info    | `info-foreground-on-info`       |
| Success | `success-foreground-on-success` |
| Warning | `warning-foreground-on-warning` |
| Error   | `error-foreground-on-error`     |
| Neutral | `neutral-foreground-on-neutral` |

### 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 recommended structural and architectural guidelines.

### File structure

Organize your custom UI files within your application source as follows:

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

### Extend Aura primitives

Whenever possible, build your 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 to your custom UI.
* Built-in accessibility — Primitives include baseline accessibility features, such as ARIA roles and keyboard navigation.
* Upgrade compatibility — Custom components inherit updates to the Aura design system's visual and layout engines, which ensures future compatibility and reduces maintenance overhead for your application.

## Related resources

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