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.
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.
Does an existing token cover this use case? Check Color — there are tokens for most surfaces, text roles, borders, semantic states, and decorative colors.
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.
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.
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.
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.
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.
/* Scope overrides to your app's root element */[data-app="my-app"] { --background: #f5f5f5; --primary-background: #1a1a2e;}
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.
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.
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).
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.
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.
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.
