Design

Role

Use Aura as the default UI system for customer-facing product work. Prefer decision-level guidance over exhaustive rules:

• choose the right primitive first,
• apply semantic tokens (no raw values),
• keep layouts and UX states consistent,
• write concise, action-oriented copy.

Use Storybook for component APIs and exact props. Use this skill for "what to choose and when."

Aura Design Guidlines can be found at: ./node_modules/@cognite/aura/DESIGN.md

<when-to-reference>

Consult this skill whenever you are:

• Creating or migrating interactive UI, forms, tables, navigation, or data display
• Writing or modifying styles, colors, spacing, or typography
• Choosing components, tokens, or layout patterns
• Creating or restructuring pages and responsive layouts
• Writing or editing any user-facing text
• Building forms, handling API responses, async actions, confirmations, or dynamic content
• Implementing accessibility (keyboard, focus, headings, ARIA, alt text)
• Applying Aura correctly in a Flows or React app

</when-to-reference>

<file-routing>

</file-routing>

Operating principles

1. Use Aura primitives before custom UI. 2. Follow foundations through semantic tokens and Aura defaults; do not hardcode raw values. 3. If a primitive almost fits, do not override visuals to force it; check variants/props first, then document the gap. 4. Keep behavior predictable and accessible: keyboard support, visible focus, and clear feedback for loading/success/error. 5. Use storybook-links.md for canonical component/foundation URLs. 6. Use publicly reachable links — Aura design system docs (Mintlify), Fusion preview Storybook, and Figma as documented in primitive-usage.md and picking-components.md.

Building pages and layouts

Role

You are structuring pages for a customer-facing application. Consistent layouts across apps are essential. Every page must use an approved pattern.

The Aura system uses Tailwind CSS for layout. All layouts use Tailwind flex/grid utilities with Aura spacing tokens. The sidebar component uses Aura's sidebar tokens (bg-sidebar, text-sidebar-foreground, etc.).

For all Storybook URLs, see ./storybook-links.md.

<storybook-foundation> Source of truth for layout foundations: https://cognitedata.github.io/aura/storybook/?path=/docs/foundations-layout--docs

Cross-reference these Storybook stories when implementing any layout pattern (full URLs):

Base: https://cognitedata.github.io/aura/storybook/ </storybook-foundation>

<foundations> Standard layout primitives used across all patterns:

CONTENT MAX-WIDTHS:

• max-w-7xl — dashboards, full-width layouts
• max-w-4xl — detail pages
• max-w-2xl — forms, wizard step content
• max-w-sm — search inputs, narrow controls

SECTION SPACING:

• space-y-8 — between major page sections (e.g. form groups)
• space-y-6 — between sections within a page
• space-y-4 — between items within a section
• space-y-2 — between label and field, tight groupings

GRID GAPS:

• gap-6 — dashboard grids, chart grids, panel gaps
• gap-4 — card grids, metric grids
• gap-3 — toolbar items, button groups

PAGE PADDING:

• px-6 py-8 — standard content area (desktop)
• px-4 py-6 — mobile content area
• p-4 — card/panel internal padding
• p-6 — larger card internal padding

</foundations>

<sidebar-tokens> The Aura system has dedicated sidebar tokens that differ from the main content area:

Note: The sidebar is ALWAYS dark-themed, even in light mode. </sidebar-tokens>

<patterns>

<pattern name="sidebar-content"> <use-when> 3+ top-level sections. Persistent navigation needed. Most common for multi-page apps. </use-when>

<structure> ┌──────────┬─────────────────────────────┐ │ │ Page Header / Breadcrumb │ │ Sidebar │─────────────────────────────│ │ Nav │ │ │ (dark) │ Main Content Area │ │ │ (bg-background) │ │ │ │ └──────────┴─────────────────────────────┘ </structure>

<responsive-behavior> Desktop (1440px+): Sidebar 240px, content fills rest. Tablet (768px-1439px): Sidebar collapsible via hamburger. Mobile (below 768px): Sidebar hidden. Hamburger menu. Consider bottom nav for 3-5 primary sections. </responsive-behavior>

<storybook-reference> Implement using Storybook Example: Sidebar Left: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--sidebar-left-layout </storybook-reference> </pattern>

<pattern name="full-width-dashboard"> <use-when> Data visualizations, metrics, monitoring. Maximum horizontal space needed. </use-when>

<structure> ┌─────────────────────────────────────────┐ │ Top Navigation Bar │ ├─────────────────────────────────────────┤ │ Page Header + Filters │ ├─────────────────────────────────────────┤ │ ┌───────┐ ┌───────┐ ┌───────┐ │ │ │Metric │ │Metric │ │Metric │ │ │ └───────┘ └───────┘ └───────┘ │ ├─────────────────────────────────────────┤ │ Charts / Visualizations │ ├─────────────────────────────────────────┤ │ Data Table │ └─────────────────────────────────────────┘ </structure>

<responsive-behavior> Desktop: Multi-column grid (grid-cols-3 or grid-cols-4). Tablet: 2-column grid. Charts stack. Mobile: Single column. Metrics as horizontal scroll. </responsive-behavior>

<storybook-reference> Implement using Storybook Example: Dashboard and Example: Comprehensive Dashboard:

• https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--dashboard-layout
• https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--comprehensive-dashboard

</storybook-reference> </pattern>

<pattern name="form-page"> <use-when> Data entry, creation flows, configuration, settings with form fields. </use-when>

<structure> ┌─────────────────────────────────────────┐ │ Page Header + Back navigation │ ├─────────────────────────────────────────┤ │ ┌───────────────────────────────┐ │ │ │ Form Section 1 (heading) │ │ │ │ [fields] │ │ │ ├───────────────────────────────┤ │ │ │ Form Section 2 (heading) │ │ │ │ [fields] │ │ │ └───────────────────────────────┘ │ ├─────────────────────────────────────────┤ │ Sticky footer: [Cancel] [Save action] │ └─────────────────────────────────────────┘ </structure>

<responsive-behavior> Desktop: Form centered, max-w-2xl (672px) or max-w-3xl. Tablet: Form fills width with px-6 padding. Mobile: Full width. Sticky footer stays. Fields stack. </responsive-behavior>

<storybook-reference> Use centered content (max-w-2xl) and Tailwind patterns from Storybook Code Examples: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--code-examples </storybook-reference> </pattern>

<pattern name="detail-page"> <use-when> Viewing a single record: report details, user profile, item information with related data. </use-when>

<structure> ┌─────────────────────────────────────────┐ │ Breadcrumb: Reports > Q2 Summary │ ├─────────────────────────────────────────┤ │ Record Header [Title, status, actions] │ ├─────────────────────────────────────────┤ │ ┌─────────────────┬───────────────┐ │ │ │ Main Content │ Sidebar │ │ │ │ (2/3 width) │ (1/3 width) │ │ │ └─────────────────┴───────────────┘ │ └─────────────────────────────────────────┘ </structure>

<responsive-behavior> Desktop: Two-column (grid-cols-3, main span-2, sidebar span-1). Tablet: Sidebar below main content. Mobile: Single column. Sidebar collapses. </responsive-behavior>

<storybook-reference> Use asymmetric columns from Storybook Pattern: Column Spans and composition patterns from Code Examples:

• https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--column-spans
• https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--code-examples

</storybook-reference> </pattern>

<pattern name="settings-page"> <use-when> App preferences, account settings, notification config. </use-when>

<structure> ┌─────────────────────────────────────────┐ │ Page Header: Settings │ ├───────────┬─────────────────────────────┤ │ Settings │ Section Content │ │ Nav │ [Form fields / toggles] │ └───────────┴─────────────────────────────┘ </structure>

<responsive-behavior> Desktop: Left nav + content area. Tablet: Top tabs replacing left nav. Mobile: Category list → tap opens section full-screen. </responsive-behavior>

<storybook-reference> Implement using Storybook Pattern: Layout Compositions: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--compositions </storybook-reference> </pattern>

<pattern name="split-screen"> <use-when> Comparison views, editor + preview, master-detail with equal emphasis on both sides. </use-when>

<structure> ┌─────────────────────┬─────────────────────┐ │ │ │ │ Panel Left │ Panel Right │ │ (1/2 width) │ (1/2 width) │ │ │ │ └─────────────────────┴─────────────────────┘ </structure>

<responsive-behavior> Desktop: grid-cols-2, equal columns. Tablet: grid-cols-2 with narrower gap. Mobile: Stack vertically (grid-cols-1), or use Segmented Control to switch between panels. </responsive-behavior>

<storybook-reference> Implement using Storybook Pattern: Column Spans: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--column-spans </storybook-reference> </pattern>

<pattern name="three-panel"> <use-when> Navigation + content + properties panel. IDE-style layouts. Complex editing workflows with context panels. </use-when>

<structure> ┌──────────┬───────────────────┬──────────┐ │ │ │ │ │ Nav/ │ Main Content │ Props/ │ │ Tree │ (flexible) │ Detail │ │ (fixed) │ │ (fixed) │ │ │ │ │ └──────────┴───────────────────┴──────────┘ </structure>

<responsive-behavior> Desktop (1440px+): All 3 panels visible. Tablet (768-1439px): Hide right panel, toggle via button. Mobile (below 768px): Single panel with navigation as Drawer, right panel as bottom sheet or separate route. </responsive-behavior>

<storybook-reference> Implement using Storybook Pattern: Layout Compositions: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--compositions </storybook-reference> </pattern>

<pattern name="list-page"> <use-when> Browsing collections — reports, users, assets, items. The most common page type in data-heavy applications. </use-when>

<structure> ┌──────────────────────────────────────────┐ │ Page Header [Title] [Create button] │ ├──────────────────────────────────────────┤ │ Filters toolbar [Search] [Filters] │ ├──────────────────────────────────────────┤ │ Table / List │ │ (with empty state when no data) │ ├──────────────────────────────────────────┤ │ Pagination │ └──────────────────────────────────────────┘ </structure>

<responsive-behavior> Desktop: Full table with all columns visible. Tablet: Hide non-essential columns, allow horizontal scroll. Mobile: Switch to card/list view with stackable filters. </responsive-behavior>

<storybook-reference> Use Storybook Example: Card Grid for card-style list variants and Grid Patterns for table/grid configuration:

• https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--card-grid-layout
• https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference

</storybook-reference> </pattern>

<pattern name="wizard"> <use-when> Multi-step creation flows, onboarding, configuration wizards, setup processes. </use-when>

<structure> ┌──────────────────────────────────────────┐ │ Step indicator (1 — 2 — 3 — 4) │ ├──────────────────────────────────────────┤ │ │ │ Step Content Area │ │ (centered, max-w-2xl) │ │ │ ├──────────────────────────────────────────┤ │ [Back] [Next/Submit] │ └──────────────────────────────────────────┘ </structure>

<responsive-behavior> Desktop: Centered content, horizontal numbered step indicator. Tablet: Same layout with px-6 padding. Mobile: Step indicator becomes compact ("Step 2 of 4"), content fills width. </responsive-behavior>

<storybook-reference> Center step content with max-w-2xl; use Storybook Code Examples for step and footer patterns: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--code-examples </storybook-reference> </pattern>

</patterns>

<edge-cases> 1. Only 1-2 pages? — Sidebar still works, or use top nav. 2. Layout not listed? — Compose from these patterns. Add a short code comment if the composition is genuinely new. 3. Both data display and entry? — Choose by primary purpose. 4. Need resizable panels? — Start with split-screen or three-panel, add resize handles as needed. 5. Very wide content (data tables)? — Use full-width-dashboard without max-w constraint, or list-page with horizontal scroll. </edge-cases>

Handling states, validation, and accessibility

Role

You are implementing how the application responds to user actions and ensuring page-level accessibility. These patterns determine whether users trust the application. Follow them for every form, API call, and user action.

Aura components handle many accessibility concerns automatically; you are responsible for composition, copy, focus, and page structure. Aura's focus system uses shadow-focus-ring (custom shadow token). Never remove or override it.

All UI elements use Aura components and tokens. Error states use the destructive token family, warnings use warning tokens, success uses success tokens.

For message wording patterns, see Content guidelines in ./node_modules/@cognite/aura/DESIGN.md.

For all Storybook URLs, see ./storybook-links.md.

<aura-coverage priority="high"> What Aura components handle automatically:

</aura-coverage>

<patterns>

<pattern name="form-validation" priority="critical"> <instruction>

• Validate on blur, not on every keystroke
• Show errors inline, adjacent to the field
• Preserve user input on failure (never clear the form)
• Move focus to first error field on submission failure
• Announce errors to screen readers via aria-live

</instruction>

<status-token-mapping>

</status-token-mapping>

<message-patterns>

See Content guidelines in ./node_modules/@cognite/aura/DESIGN.md for full message patterns. </message-patterns>

<field-validation-states> Every form field must support the validation states applicable to its type. Use this table to determine which states to implement:

"yes" = must implement. "optional" = implement if relevant. </field-validation-states>

<complete-field-example> A complete form field with all states (default, focused, error, success, disabled):

import { Input } from '@/components/ui/input'; import { Label } from '@/components/ui/label'; import { HelperText } from '@/components/ui/helper-text';

{/ Default / Focused state /} <div className="space-y-2"> <Label htmlFor="report-name"> Report name <span className="text-destructive">*</span> </Label> <Input id="report-name" value={name} onChange={(e) => setName(e.target.value)} onBlur={validateName} aria-describedby="report-name-helper" aria-invalid={!!nameError} disabled={isSubmitting} /> {nameError ? ( <HelperText id="report-name-helper" variant="error"> {nameError} </HelperText> ) : ( <HelperText id="report-name-helper"> A descriptive name for your report. </HelperText> )} </div>

Key implementation details:

• Label with required indicator (asterisk in text-destructive)
• Input with aria-describedby linking to HelperText
• Input with aria-invalid reflecting error state
• Validation on blur via onBlur handler
• HelperText swaps between hint (default) and error message
• Disabled state during form submission

</complete-field-example> </pattern>

<pattern name="loading-states" priority="critical"> <instruction> Any action taking more than 300ms must show a loading indicator using Aura components. </instruction>

<variants>

</variants>

<example type="correct"> {/ Button loading during async action /} <Button variant="default" onClick={handleSave} disabled={isSaving} > {isSaving ? ( <> <Loader2 className="mr-2 h-4 w-4 animate-spin" /> Saving... </> ) : ( 'Save changes' )} </Button>

{/ Skeleton while page loads /} {isLoading ? ( <div className="space-y-4"> <Skeleton className="h-8 w-48" /> <Skeleton className="h-4 w-full" /> <Skeleton className="h-4 w-3/4" /> </div> ) : ( <DataTable data={reports} columns={columns} /> )} </example>

<example type="incorrect"> {/ No loading state /} <Button onClick={handleSave}>Save changes</Button>

{/ Blank screen while loading /} {isLoading ? null : <DataTable data={reports} />} </example> </pattern>

<pattern name="error-states" priority="critical"> <instruction> Every API failure must show a user-facing message using Aura Alert component. Never fail silently. See Content guidelines in ./node_modules/@cognite/aura/DESIGN.md for message wording. </instruction>

<full-example> import { Alert, AlertDescription } from '@/components/ui/alert'; import { AlertCircle } from 'lucide-react';

{error && ( <Alert variant="destructive"> <AlertCircle className="h-4 w-4" /> <AlertDescription> {error} </AlertDescription> <Button variant="secondary" size="sm" onClick={retry} className="ml-auto" > Try again </Button> </Alert> )} </full-example> </pattern>

<pattern name="success-feedback" priority="high"> <instruction> Use Sonner toast for brief confirmations. </instruction>

<example type="correct"> import { toast } from 'sonner';

// After save toast.success('Report saved successfully.');

// After delete toast.success('Report deleted.');

// After bulk action toast.success(${count} items archived.); </example>

<example type="incorrect"> // No feedback await saveReport(data); navigate('/reports');

// Vague toast.success('Done!'); </example> </pattern>

<pattern name="confirmation-dialogs" priority="critical"> <instruction> Destructive actions must show Dialog with specific action verb. See Content guidelines in ./node_modules/@cognite/aura/DESIGN.md for copy. </instruction>

<full-example> import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, } from '@/components/ui/dialog';

<Dialog open={showDelete} onOpenChange={setShowDelete}> <DialogContent> <DialogHeader> <DialogTitle>Delete this report?</DialogTitle> <DialogDescription> This will permanently remove "{report.name}" and all associated data. This cannot be undone. </DialogDescription> </DialogHeader> <DialogFooter> <Button variant="secondary" onClick={() => setShowDelete(false)} > Cancel </Button> <Button variant="destructive" onClick={handleDelete} > Delete report </Button> </DialogFooter> </DialogContent> </Dialog> </full-example>

<example type="incorrect"> {/ Yes/No, no description, wrong variant /} <Dialog open={show}> <DialogContent> <DialogTitle>Confirm</DialogTitle> <DialogDescription>Are you sure?</DialogDescription> <DialogFooter> <Button variant="secondary">No</Button> <Button variant="default">Yes</Button> </DialogFooter> </DialogContent> </Dialog> </example> </pattern>

</patterns>

<page-accessibility priority="critical">

<responsibility name="keyboard-navigation"> <instruction>

• Tab order follows visual reading order
• Every interactive element reachable via Tab
• No keyboard traps
• Skip-to-content link on pages with complex nav

</instruction>

<example type="correct"> <a href="#main-content" className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:bg-background focus:px-4 focus:py-2 focus:rounded-md focus:shadow-focus-ring"> Skip to main content </a> <Sidebar /> <main id="main-content"> <h1>Reports</h1> {/ Content in logical tab order /} </main> </example> </responsibility>

<responsibility name="heading-hierarchy"> <instruction> Use heading levels (H1–H6) in strict sequential order.

• One H1 per page (the page title)
• Never skip levels (H1 directly to H3)
• Never use heading tags for visual sizing — use text-*

classes from the Typography foundation instead

Aura applies text-undefined-foreground to headings by default. </instruction> </responsibility>

<responsibility name="image-alt-text"> <instruction> Every image needs alt. Icons in buttons need aria-label. </instruction>

<examples>

</examples>

<example type="correct"> {/ Icon + text: hide icon from screen reader /} <Button variant="destructive"> <TrashIcon className="h-4 w-4 mr-2" aria-hidden="true" /> Delete report </Button>

{/ Icon only: label on button /} <Button variant="ghost" size="icon" aria-label="Delete report"> <TrashIcon className="h-4 w-4" /> </Button> </example> </responsibility>

<responsibility name="dynamic-content"> <examples>

</examples>

<example type="correct"> {/ Screen reader announcement for filtered results /} <div aria-live="polite" className="sr-only"> {results.length} results found for "{query}" </div> <DataTable data={results} columns={columns} /> </example> </responsibility>

<responsibility name="color-independence"> <instruction> Never use color alone to convey meaning. </instruction>

<example type="correct"> {/ Status with text + color /} <span className="inline-flex items-center gap-1.5 bg-success text-success-foreground text-xs px-2.5 py-0.5 rounded-full"> <CheckCircle className="h-3 w-3" aria-hidden="true" /> Active </span> </example>

<example type="incorrect"> {/ Color only — invisible to colorblind users /} <span className="h-2 w-2 rounded-full bg-success" /> </example> </responsibility>

</page-accessibility>

<translation-and-testing priority="medium"> Short sentences and simple grammar translate more reliably. Plan for text expansion in localized UIs (e.g. German often adds 30–40% length); allow flexible button and title widths.

For automated checks, use WAVE, axe DevTools, or Lighthouse in Chrome DevTools. For manual verification, unplug the mouse and complete primary tasks with keyboard only; spot-check with VoiceOver (Mac) or NVDA (Windows) for critical flows. </translation-and-testing>

<self-check> Before submitting any page:

• [ ] Tab through all elements in logical order?
• [ ] Every button/link works with Enter/Space?
• [ ] Every dialog opens/closes with keyboard?
• [ ] Escape closes dialogs, popovers, dropdowns?
• [ ] Every image has appropriate alt text?
• [ ] Every form field has a visible label?
• [ ] Non-color indicator for every status?
• [ ] Headings follow H1 → H2 → H3?
• [ ] Dynamic updates announced to screen readers?
• [ ] Focus ring (shadow-focus-ring) visible on all elements?

</self-check>

<edge-cases> Forms and async 1. Destructive action with undo? — Still confirm. Mention undo in body: "You can undo within 30 seconds." 2. Bulk delete? — One confirmation: "Delete 12 reports?" 3. Auto-save? — Subtle "Saved" indicator, not toast each time. 4. Error in multi-step flow? — Don't lose progress. Show error on current step. Let user retry.

Accessibility 1. Complex data viz? — Text summary via alt or sr-only text. 2. Drag-and-drop? — Keyboard alternative required. 3. Real-time dashboard? — aria-live="polite", not "assertive". 4. Third-party embed? — iframe with descriptive title. </edge-cases>

Picking components and applying tokens

This file is a pointer. Day-to-day primitive decisions live in `primitive-usage.md`. Canonical Storybook URLs in this repo live in `storybook-links.md`.

Published Aura resources (outside this repo): Aura design system docs, Aura Storybook (Fusion preview), Figma library.

When to open what

Use Storybook and Aura design system docs for props, variants, and examples; use this skill for composition choices and consistency with Fusion and Flows apps.

Aura primitive usage guidance (simplified)

Purpose

Use this file for primitive-level decisions when building Flows and Fusion apps. It captures usage guidance that is typically missing from component specs and prop tables.

Resources

Links below must stay usable without Cognite VPN or internal auth. Do not use Cognite-internal short URL domains in this skill.

• Figma library: https://www.figma.com/design/pMnMQvfErZDJzWgrcWCIwZ/WIP---Aura-library
• Aura design system docs: https://cognite-dune-docs.mintlify.app/aura-design-system/index
• Aura Storybook (Fusion preview): https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/
• Storybook path index in this repo (same /docs/... paths; hosts may differ): ./storybook-links.md

What Aura is

Aura is Cognite's AI-native design system. It provides:

• visual language,
• primitive library,
• usage conventions for app UX.

Always prefer an Aura primitive before building custom UI.

Guidance tiers

• Foundations: non-negotiable style decisions; use tokens and do not override with raw values.
• Primitives: default building blocks; use these unless there is a clear product reason not to.
• Patterns: repeatable workflows and compositions; use established patterns for consistency across apps.

Global primitive rules

1. Prefer primitives over custom components. 2. Keep behavior accessible (keyboard activation, focus visibility, and clear state changes). 3. Do not hide critical information if users need fast comparison or repeated switching. 4. When selection is required before action, prefer contextual actions tied to that selection. 5. Use Storybook for exact variants, props, and implementation details.

Primitive guidance

Storybook links below use the Fusion preview host; paths match ./storybook-links.md.

Accordion

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-accordion--docs

Definition Accordion reveals and hides grouped content sections to reduce cognitive load and page density.

Use when

• Grouping settings in side/config panels.
• Breaking long forms into manageable sections.
• Organizing docs/FAQ/help content.
• Showing nested information hierarchies.

Use something else when

• All content must stay visible for comparison/scanning.
• Content is short and easy to read without progressive disclosure.
• Users are making high-stakes or multi-step decisions where hidden content can cause errors.

Dos and don'ts

• Do use clear, specific section titles.
• Do keep icon and heading behavior consistent.
• Do not use for very short/simple content.
• Do not nest accordions.

Behavior

• Header controls expand/collapse via click/tap/Enter/Space.
• Support multi-expand unless product pattern requires single-expand.
• Keep expanded content available to assistive tech.

Often used with

• Separator, section headings, and form controls inside panel content.

Action toolbar

Storybook: coming soon

Definition Action toolbar is a transient bottom-aligned action row that appears when users select items (for example in data-heavy views).

Use when

• Actions apply only to selected items.
• You need to reduce persistent toolbar clutter in tables/lists/cards.
• The workflow depends on selected state before next actions are valid.

Use something else when

• Actions are page-level and do not require selection first (use a standard toolbar/page actions).

Dos and don'ts

• Do keep actions contextual to the current selection.
• Do keep the set focused (use overflow when needed).
• Do center it in the container/page scope.
• Do not make it draggable.

Behavior

• Hidden by default; appears after selection.
• Anchored to bottom area; remains until selection clears, action completes, or user navigates away.
• If no reload occurs, it exits after action completion.

Often used with

• Selection patterns in data views, Checkbox, Button, Menu, and Tooltip for icon-only actions.

Avatar

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-avatar--docs

Definition Avatar visually represents a user, team, or concept and helps recognition in collaborative UI.

Use when

• Showing people in comments, chat, sharing, or collaborators.
• Representing accounts, teams, or organizations.
• Displaying AI/agent identities in conversational interfaces.

Behavior

• Choose size based on context density.
• Use overflow patterns for constrained spaces (for example +N with menu).
• Can be informational or interactive based on context.
• Can include status badges/dots.

Often used with

• Badge, Tooltip, Menu.

Alert

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-alert--docs

Definition Alert communicates contextual, medium-emphasis information inside page/task flow. It is not a blocking modal.

Use when

• Providing inline guidance/recommendations in the current task.
• Calling attention to warnings/issues that need awareness but are not blocking.
• Offering direct actions that resolve the issue in context.

Dos and don'ts

• Do include action buttons only when actions are directly related to resolving/dismissing the alert.
• Do evaluate simpler feedback methods first (for example field-level validation).
• Do not attach unrelated actions.

Placement

• Align with surrounding content; do not pin flush against dividers.
• Use card style for wrapped content in constrained areas.
• Use strip style for short messages in wider areas.

Behavior

• Inline with page flow (not full-screen blocking).
• Dismissal removes/hides alert per variant.
• Action path should be clear and minimal.

Often used with

• Button for direct resolution actions.

Badge

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-badge--docs

Definition Compact label for status, category, or metadata.

Use when

• Surfacing state at a glance (for example active, draft, error).
• Tagging items without taking primary focus from the page.

Use something else when

• The message needs explanation or recovery steps (consider Alert or inline text).
• You need a primary action (use Button).

Often used with

• Avatar, tables and lists, filter chips.

Banner

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-banner--docs

Definition Persistent or dismissible message scoped at page or section level — stronger than inline helper text, broader than a single-field Alert in some layouts.

Use when

• Announcing environment or product state (maintenance, trial, feature preview).
• Page-wide outcomes that should stay visible while the user continues.

Use something else when

• Task-specific guidance inside a flow (Alert).
• Brief confirmation after an action (Sonner Toast).

Button

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-button--docs

Definition Primary control for discrete actions.

Use when

• Committing, navigating a clear next step, or triggering destructive work (with confirmation pattern).

Dos and don'ts

• One primary action per logical section when possible.
• Match variant to risk: destructive actions use destructive variant and confirmation.
• Label with verb + object (see Content guidelines in ./node_modules/@cognite/aura/DESIGN.md).
• Icon-only actions need an accessible name (aria-label).

Often used with

• Button Group, Dialog / Alert Dialog, forms.

Dialog and Alert Dialog

Storybook: Dialog · Alert Dialog

Definition

• Alert Dialog — short, focused confirmation or acknowledgment; interrupts for a clear binary or limited choice.
• Dialog — richer content: forms, multi-field flows, or explanations that do not fit a strip or inline pattern.

Use Alert Dialog when

• Confirming destructive or irreversible actions.
• Blocking until the user chooses a small set of options.

Use Dialog when

• Collecting input or showing structured content that needs focus without leaving the page.

Use something else when

• Inline persistence is enough (Alert).
• Only a quick acknowledgement is needed (Sonner Toast).

Drawer

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-drawer--docs

Definition Secondary surface that slides in for filters, detail, or medium-length tasks without a full page change.

Use when

• Supporting the main view (filters, record details, auxiliary forms).

Use something else when

• The task needs full attention or multi-step wizard treatment (full page or Dialog).
• Content is very short (consider Popover or inline).

Empty State

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-empty-state--docs

Definition Placeholder when there is no data yet or results are empty.

Use when

• Lists, tables, charts, or artifacts have zero rows/points.

Dos and don'ts

• Explain what will appear and how to get started.
• Include a single clear CTA when creation/import applies.

Segmented Control

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-segmented-control--docs

Definition Switches between a small number of peer views or modes on the same page.

Use when

• Two to several comparable sections (for example overview vs details vs activity).

Use something else when

• Content is hierarchical or lengthy and users must open multiple sections at once (consider Accordion or visible sections).
• Navigating separate routes (tabs/sidebar patterns — see building-pages.md).

Relationship to Accordion

• Segmented control swaps visibility of peer panels; accordion stacks expandable sections. Prefer segmented control when users switch modes frequently; accordion when progressive disclosure matters.

Sonner Toast

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-sonner-toast--docs

Definition Lightweight, auto-dismiss feedback for outcomes that do not need a blocking surface.

Use when

• Confirming save, delete, or background completion.
• Non-critical notices the user can miss without breaking a workflow.

Use something else when

• User must read and act before continuing (Alert Dialog, Dialog, or persistent Alert / Banner).

Table

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-table--docs

Definition Dense, scannable display of rows and columns with optional selection and actions.

Use when

• Comparing rows, scanning many attributes, or operating on multiple items.

Use something else when

• A simple fixed list of links or single-column items (List).
• A primary chart or narrative view (Card, charts — see Storybook).

Often used with

• Selection + Action toolbar (when selection-gated actions apply), Pagination, Empty State, row Checkbox, Dropdown Menu for row actions.

Toolbar

Storybook: https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-toolbar--docs

Definition Persistent strip of primary tools or filters for a page or region — available without selecting rows first.

Use when

• Page-level create/filter/export actions.
• Tools that apply to the whole view or the current query.

Use something else when

• Actions apply only after row/item selection (use Action toolbar pattern).

Tooltip, Popover, and Hover Card

Storybook: Tooltip · Popover · Hover Card

Definition

• Tooltip — short hint on hover/focus; no heavy interaction inside.
• Popover — click-triggered panel for interactive or structured supplemental content.
• Hover Card — richer preview on hover for entities (profiles, references).

Use Tooltip when

• Clarifying a control or icon in one line or sentence.

Use Popover when

• User picks options, fills short fields, or reads formatted content on demand.

Use Hover Card when

• Previewing related metadata without leaving context.

Use something else when

• Content is essential to the task — surface it inline or in Dialog / Drawer.

Escalation guidance

If a primitive does not fit: 1. Check Storybook variants/props first. 2. Compose with existing primitives. 3. If still blocked, note the gap and keep implementation consistent with Aura foundations.

Aura Storybook Links

Canonical reference for all Aura Storybook URLs. If the Storybook domain or path structure changes, update this file and propagate to individual skills.

Base URL: https://cognitedata.github.io/aura/storybook/

Last verified against Storybook: 2026-03-13

Foundations

Components — Actions and Inputs

Components — Form Support

Components — Layout and Containers

Components — Navigation

Components — Data Display

Components — Artifact (Domain-Specific)

All Artifact sub-variants live on the same docs page (primitives-artifact--docs). Chart and Count are also available as standalone components with their own docs pages.

Components — Feedback and Overlays

Components — AI