Skip to main content
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.
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.

​
Before you override anything

Ask these questions first:
  1. Does an existing token cover this use case? Check 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 — 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.

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

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

​
Primary

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

​
Active

Active is used on selected or active items in controls such as Checkbox, Radio, Segmented control, Switch, Progress, Pagination, and Tabs. Inline interactive text — hyperlinks and tappable text outside of button surfaces.

​
Ring

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

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

​
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). Semantic series — use only when the data carries that meaning (status, feedback, validation).

​
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. The following tokens are for semantic foreground only and do not have a semantic background.

​
Typography tokens to override

​
Typefaces

​
Text (Inter)

​
Code (Source Code Pro)

​
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.
Last modified on June 12, 2026