init

2026-05-31 20:25:41 +00:00
commit 0a07ab8593
275 changed files with 52660 additions and 0 deletions
@@ -0,0 +1,52 @@
+---
+name: design
+description: Simplified Aura guidance for selecting primitives, keeping token usage consistent, and applying reliable layout/copy/state patterns in Flows and Fusion apps.
+allowed-tools: Read, Glob, Grep, Edit, Write
+---
+
+## 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."
+
+<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>
+
+| If you are… | Open |
+|-------------|------|
+| Choosing primitives and deciding what to use when | `primitive-usage.md` |
+| Where to look for Storybook, docs, and Figma (router) | `picking-components.md` |
+| Structuring a page or choosing a layout pattern | `building-pages.md` |
+| Writing any user-facing text | `writing-copy.md` |
+| Forms, loading, errors, confirmations, or page-level accessibility | `handling-states.md` |
+| Looking up Storybook URLs for foundations or components | `storybook-links.md` |
+
+</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`.
@@ -0,0 +1,354 @@
+# 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):
+
+| Story | URL | Use for |
+|-------|-----|---------|
+| Breakpoints | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--breakpoints | Official breakpoint values |
+| Container Queries | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--container-queries | Responsive within components |
+| Column Spans | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--column-spans | 2-col, 3-col, asymmetric splits |
+| Layout Compositions | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--compositions | Combining layout parts |
+| Sidebar Left | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--sidebar-left-layout | Sidebar implementation |
+| Card Grid | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--card-grid-layout | Card grid layout |
+| Dashboard | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--dashboard-layout | Dashboard with metrics |
+| Comprehensive Dashboard | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--comprehensive-dashboard | Full dashboard |
+| Grid Patterns | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference | Grid configuration catalog |
+| Code Examples | https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--code-examples | Copy-paste Tailwind code |
+
+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:
+
+| Token | Purpose | Light value | Dark value |
+|-------|---------|-------------|------------|
+| bg-sidebar | Sidebar background | mountain-900 | mountain-900 |
+| text-sidebar-foreground | Sidebar text | mountain-100 | mountain-100 |
+| text-sidebar-primary | Sidebar primary | mountain-600 | mountain-600 |
+| text-sidebar-primary-foreground | Active item text | white | white |
+| bg-sidebar-accent | Active/hover bg | mountain-700 | mountain-700 |
+| text-sidebar-accent-foreground | Active text | white | white |
+| border-sidebar-border | Sidebar borders | mountain-800 | mountain-800 |
+
+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>
@@ -0,0 +1,426 @@
+# 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 `writing-copy.md`.
+
+For all Storybook URLs, see `./storybook-links.md`.
+
+<aura-coverage priority="high">
+What Aura components handle automatically:
+
+| Concern | Aura handles | You verify |
+|---------|-------------|-----------|
+| Focus indicators | shadow-focus-ring on interactive elements | Not hidden by overflow or z-index |
+| Keyboard activation | Button: Enter/Space. Input: standard keys | Custom elements also respond |
+| ARIA roles | Correct roles on Dialog, Segmented Control (Tabs ARIA pattern), etc. | Custom components have roles |
+| Color contrast | Token pairs designed for AA compliance | Page backgrounds don't reduce contrast |
+| Dark mode | Semantic tokens adapt automatically | Custom colors also work in dark mode |
+| Disabled states | Communicated via aria-disabled | Reason for disabled is accessible |
+| Focus trapping | Dialog traps focus when open | You return focus to trigger on close |
+</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>
+| State | Background | Text | Border |
+|-------|-----------|------|--------|
+| Error | bg-destructive | text-destructive-foreground | border-destructive |
+| Warning | bg-warning | text-warning-foreground | — |
+| Success | bg-success | text-success-foreground | — |
+| Disabled | bg-disabled | text-disabled-foreground | — |
+</status-token-mapping>
+
+<message-patterns>
+| Field type | Correct message | Incorrect message |
+|-----------|----------------|-------------------|
+| Required | "Report name is required." | "Required" |
+| Email | "Email must include an @ symbol." | "Invalid" |
+| Password | "At least 8 characters." | "Too short" |
+| Number | "Value must be between 1 and 100." | "Invalid" |
+| Date | "End date must be after start date." | "Invalid date" |
+
+See `writing-copy.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:
+
+| Field type | required | format | length | range | uniqueness |
+|-----------|----------|--------|--------|-------|------------|
+| Text Input | yes | — | optional | — | optional |
+| Email Input | yes | yes | — | — | optional |
+| Password | yes | yes | yes | — | — |
+| Number Input | yes | — | — | yes | — |
+| Date Picker | yes | — | — | yes | — |
+| Textarea | yes | — | yes | — | — |
+| Select | yes | — | — | — | — |
+| Combobox | yes | — | — | — | — |
+| Checkbox | — | — | — | — | — |
+| File Upload | yes | yes | — | yes (size) | — |
+
+"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>
+| Context | Pattern | Aura component |
+|---------|---------|---------------|
+| Page load | Skeleton screen | Skeleton |
+| Button action | Button disabled + spinner | Button loading state |
+| Data refresh | Overlay spinner | Spinner on existing content |
+| Long operation | Progress bar + message | Progress |
+</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 `writing-copy.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 `writing-copy.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>
+| Type | Approach | Example |
+|------|----------|---------|
+| Informational | Describe content | alt="Chart: output up 20%" |
+| Decorative | Empty | alt="" |
+| Icon button | aria-label on parent | aria-label="Delete report" |
+| Icon with label | Hide icon | aria-hidden="true" on icon |
+</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>
+| Scenario | Method |
+|----------|--------|
+| Search results update | aria-live="polite" |
+| Form error | aria-live="assertive" |
+| Toast | Sonner handles this |
+| Dialog opens | Focus moves to dialog (Aura handles) |
+| Dialog closes | Return focus to trigger |
+</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>
@@ -0,0 +1,18 @@
+# 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](https://cognite-dune-docs.mintlify.app/aura-design-system/index), [Aura Storybook (Fusion preview)](https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/), [Figma library](https://www.figma.com/design/pMnMQvfErZDJzWgrcWCIwZ/WIP---Aura-library).
+
+## When to open what
+
+| Need | File |
+|------|------|
+| Which primitive, when to use it, dos and don'ts | `primitive-usage.md` |
+| Page layouts and approved patterns | `building-pages.md` |
+| Interface copy | `writing-copy.md` |
+| Forms, loading, errors, confirmations, page a11y | `handling-states.md` |
+| Storybook URLs for foundations and components | `storybook-links.md` |
+| Component props, variants, and foundation token reference | Storybook and [Aura design system docs](https://cognite-dune-docs.mintlify.app/aura-design-system/index) (this file does not duplicate them) |
+
+Use Storybook and [Aura design system docs](https://cognite-dune-docs.mintlify.app/aura-design-system/index) for props, variants, and examples; use this skill for composition choices and consistency with Fusion and Flows apps.
@@ -0,0 +1,343 @@
+# 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 `writing-copy.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](https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-dialog--docs) · [Alert Dialog](https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-alert-dialog--docs)
+
+**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](https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-tooltip--docs) · [Popover](https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-popover--docs) · [Hover Card](https://storybook-aura-22829.fusion-preview.preview.cogniteapp.com/?path=/docs/primitives-hover-card--docs)
+
+**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.
@@ -0,0 +1,133 @@
+# 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
+
+| Foundation | URL |
+|-----------|-----|
+| Colors | https://cognitedata.github.io/aura/storybook/?path=/docs/foundations-colors--docs |
+| Effects | https://cognitedata.github.io/aura/storybook/?path=/docs/foundations-effects--docs |
+| Layout | https://cognitedata.github.io/aura/storybook/?path=/docs/foundations-layout--docs |
+| Typography | https://cognitedata.github.io/aura/storybook/?path=/docs/foundations-typography--docs |
+
+## Components — Actions and Inputs
+
+| Component | URL |
+|-----------|-----|
+| Button | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-button--docs |
+| Button Group | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-button-group--docs |
+| Input | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-input--docs |
+| Input Group | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-input-group--docs |
+| Textarea | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-textarea--docs |
+| Select | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-select--docs |
+| Combobox | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-combobox--docs |
+| Checkbox | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-checkbox--docs |
+| Radio Group | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-radio-group--docs |
+| Switch | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-switch--docs |
+| Toggle | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-toggle--docs |
+| Slider | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-slider--docs |
+| Date Picker | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-date-picker--docs |
+| Time Input | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-time-input--docs |
+| Calendar | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-calendar--docs |
+
+## Components — Form Support
+
+| Component | URL |
+|-----------|-----|
+| Label | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-label--docs |
+| Helper Text | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-helper-text--docs |
+
+## Components — Layout and Containers
+
+| Component | URL |
+|-----------|-----|
+| Card | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-card--docs |
+| Accordion | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-accordion--docs |
+| Collapsible | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-collapsible--docs |
+| Separator | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-separator--docs |
+| Swap Slot | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-swap-slot--docs |
+| Empty State | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-empty-state--docs |
+
+## Components — Navigation
+
+| Component | URL |
+|-----------|-----|
+| Sidebar | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-sidebar--docs |
+| Topbar | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-topbar--docs |
+| Breadcrumb | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-breadcrumb--docs |
+| Segmented Control | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-segmented-control--docs |
+| Menubar | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-menubar--docs |
+| Pagination | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-pagination--docs |
+| Toolbar | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-toolbar--docs |
+
+## Components — Data Display
+
+| Component | URL |
+|-----------|-----|
+| Table | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-table--docs |
+| List | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-list--docs |
+| Badge | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-badge--docs |
+| Avatar | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-avatar--docs |
+| Progress | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-progress--docs |
+| Skeleton | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-skeleton--docs |
+| Kbd | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-kbd--docs |
+| TreeView | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-treeview--docs |
+
+## 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.
+
+| Component | Sub-variant | URL |
+|-----------|-------------|-----|
+| Artifact (Count) | Metric/count display inside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-artifact--docs |
+| Artifact (List) | List display inside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-artifact--docs |
+| Artifact (Progress) | Progress tracking inside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-artifact--docs |
+| Artifact (Alert) | Alert/status inside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-artifact--docs |
+| Artifact (Tree View) | Hierarchical data inside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-artifact--docs |
+| Artifact (Chart) | Data visualization inside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-artifact--docs |
+| Chart (standalone) | Data visualization outside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-chart--docs |
+| Count (standalone) | Metric/count display outside an Artifact | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-count--docs |
+
+## Components — Feedback and Overlays
+
+| Component | URL |
+|-----------|-----|
+| Alert | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-alert--docs |
+| Alert Dialog | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-alert-dialog--docs |
+| Banner | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-banner--docs |
+| Dialog | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-dialog--docs |
+| Drawer | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-drawer--docs |
+| Sonner Toast | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-sonner-toast--docs |
+| Tooltip | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-tooltip--docs |
+| Popover | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-popover--docs |
+| Hover Card | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-hover-card--docs |
+| Context Menu | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-context-menu--docs |
+| Dropdown Menu | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-dropdown-menu--docs |
+| Command | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-command--docs |
+| Page Loader | https://cognitedata.github.io/aura/storybook/?path=/docs/primitives-page-loader--docs |
+
+## Components — AI
+
+| Component | URL |
+|-----------|-----|
+| Chain of Thought | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-chain-of-thought--docs |
+| Code Block | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-code-block--docs |
+| Confirmation | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-confirmation--docs |
+| Conversation | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-conversation--docs |
+| Inline Citation | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-inline-citation--docs |
+| Loader | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-loader--docs |
+| Message | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-message--docs |
+| Prompt Input | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-prompt-input--docs |
+| Reasoning | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-reasoning--docs |
+| Shimmer | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-shimmer--docs |
+| Sources | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-sources--docs |
+| Suggestion | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-suggestion--docs |
+| Tool | https://cognitedata.github.io/aura/storybook/?path=/docs/ai-tool--docs |
@@ -0,0 +1,233 @@
+# Writing copy
+
+## Role
+
+You are writing interface copy for Cognite customer-facing applications. Every piece of UX text must be purposeful, concise, conversational, and clear. Always identify the target audience persona before writing — the persona determines reading level, technical vocabulary, and tone.
+
+For code-level accessibility (keyboard navigation, ARIA, focus, headings, live regions), see `handling-states.md`.
+
+## Audience personas
+
+Canonical persona definitions live in the cogdocs repository (`cogdocs/cogdocs-metadata.mdx`, **Audience** section). This summary covers what matters for microcopy decisions.
+
+| Persona | Technical level | UX copy implication |
+|---|---|---|
+| `businessUser` | Low | Plain language; outcomes over features; domain terms OK, avoid platform jargon |
+| `businessDecisionMaker` | Low | Plain language; ROI, business value, strategic impact; minimal technical detail |
+| `appMaker` | Mid | Configuration, automation, outcomes; avoid deep code/API detail |
+| `dataAnalyst` | Mid | Analytics, insights, dashboards; data terms OK, keep explanations clear |
+| `partner` | Mid–high | Precise; balance technical accuracy with clarity |
+| `administrator` | High | Technical terms OK; reliability, security, compliance, access; be precise |
+| `dataEngineer` | High | Technical terms OK; pipelines, ingestion, transformation |
+| `developer` | High | Technical terms OK; APIs, SDKs, integrations; precise and concise |
+| `aiEngineer` | High | Technical terms OK; ML/AI, models, automation |
+| `dataScientist` | High | Technical terms OK; experiments, models, analytics |
+| `securityEngineer` | High | Technical terms OK; IAM, threats, compliance |
+| `solutionArchitect` | High | Technical terms OK; integration, strategy, best practices |
+| `internal` | Varies | Can use Cognite-internal jargon; match internal conventions |
+
+**Reading level:** Low = 7th–8th grade; Mid = 9th–10th grade; High = 10th–11th grade.
+
+When the persona is unknown, default to plain language and outcomes.
+
+## Voice and tone
+
+Voice is consistent; tone adapts to the user's emotional state.
+
+| Scenario | Tone | Example |
+|---|---|---|
+| First-time onboarding | Friendly, welcoming | "Let's get started — Cognite Data Fusion is ready when you are." |
+| Technical documentation | Clear, direct, supportive | "Configure your endpoint and authenticate using your API key." |
+| Error messages | Empathetic, constructive | "Something went wrong. Try refreshing, or check your connection." |
+| Success states | Encouraging, concise | "Your data is now flowing." |
+| Product tours / help | Conversational, helpful | "Want a quick tour? We'll walk you through the essentials in under 2 minutes." |
+| High-stakes actions | Serious, transparent | "Delete pipeline? All history will be permanently removed." |
+
+## Grammar and style
+
+### Language and capitalization
+
+- **American English**: color, center, organization, modeling
+- **Sentence case everywhere**: "Create data model" — not "Create Data Model". No exceptions for UI text. Only proper nouns and product names are capitalized: Cognite Data Fusion, OPC-UA, Aura.
+- **No all-caps**
+- **No "CDF" in UI copy** — customers may white-label the platform; use product or feature names instead
+
+### Numbers and units
+
+- **Numerals for all numbers**, including those under 10: "6 queries", "3 items", "1 result"
+- Non-breaking space between number and unit: "50 Mbps"
+- Don't use "(s)" or "(es)" — choose singular or plural based on context
+
+### Abbreviations and punctuation
+
+- No Latin abbreviations: use "for example" not "e.g.", "and more" not "etc."
+- Define acronyms and technical terms when first used (unless writing for technical personas)
+- No ampersands (&): use "and" — including in headings
+- **Oxford comma**: "apples, oranges, and pears"
+- No exclamation marks in UI copy
+- No period after labels, tooltip text, or single-sentence bulleted list items; use periods for multiple/complex sentences
+- Ellipsis (…): only for ongoing processes or truncated text — use sparingly
+
+### Pronouns
+
+- Don't mix "my" and "your" in the same context
+- **"My [resource]"** for app-owned items: "My data", "My assets"
+- Minimize "I" and "we" representing the application; focus on the user's perspective
+- Avoid ambiguous pronouns ("this", "that") without an explicit referent — name the thing
+
+## Action labels
+
+Use sentence case with an object: "Edit model", "Delete asset".
+
+### Approved labels
+
+| Label | Use when |
+|---|---|
+| Add | Taking an existing object into a new context ("Add to canvas") |
+| Apply | Setting filtered values that affect subsequent system behavior |
+| Approve | User agrees; initiates next step in a business process |
+| Back | Returning to the previous step in a sequence or hierarchy |
+| Cancel | Stopping the current action or closing a modal — warn of data loss |
+| Clear | Clearing all fields/selections; restores defaults |
+| Close | Closing a page, panel, or secondary window — often icon-only |
+| Copy | Copying an object to the clipboard |
+| Create | Making a new object from scratch |
+| Delete | Permanently destroying an object |
+| Discard | Discarding unsaved changes during create/edit |
+| Download | Transferring a file from remote to local |
+| Duplicate | Creating a copy in the same location as the original |
+| Edit | Changing data/values of an existing object |
+| Export | Saving data in an external format; typically opens a dialog |
+| Import | Bringing data from an external source; typically opens a dialog |
+| Next | Advancing to the next step in a wizard |
+| Finish | Completing a multi-step wizard |
+| Open | Opening a drawer, modal, or new page within current context |
+| Publish | Making content available to intended users |
+| Refresh | Reloading a view that is out of sync with the source |
+| Register | Creating a new user account |
+| Remove | Removing an object from the current context without destroying it |
+| Reset | Reverting to last saved or default state |
+| Save | Saving pending changes without closing the window/panel |
+| Search | Goal-oriented action to find precise information |
+| Select | Choosing one or more options from a list |
+| Show / Hide | Revealing or removing an element from view without deleting — use as a pair |
+| Sign in / Sign out | Entering or exiting the application |
+| Undo / Redo | Reversing or re-applying the most recent action |
+| Upload | Transferring a file from local to remote |
+| View | Presenting additional information or properties for an object |
+
+### Labels to avoid
+
+| Avoid | Use instead | Reason |
+|---|---|---|
+| Confirm | The specific action verb ("Delete", "Send") | Too vague |
+| Log in / Log out | Sign in / Sign out | "Log" is technical jargon |
+| Sign up | Register | Avoids confusion with "Sign in" |
+| Submit, OK, Yes | The specific outcome verb | Generic; tell users what happens |
+| Click here, Read more | Descriptive link text | Inaccessible; not input-agnostic |
+
+## UI text patterns
+
+### Titles
+Noun phrases, sentence case. Examples: "Asset overview", "Pipeline runs", "Configure integration"
+
+### Buttons and CTAs
+Active imperative verb + object. 2–4 words target, 6 max. Examples: "Save changes", "Delete pipeline", "View details"
+
+### Error messages
+Pattern: `[What failed]. [Why/context if known]. [What to do].`
+Examples:
+- "Ingestion failed. Check your extractor configuration and try again."
+- "Couldn't save changes. Connection lost. Reconnect and retry."
+Avoid: blame language, dead ends with no recovery path
+
+### Success messages
+Past tense, specific, brief. Pattern: `[Action] [result]`
+Avoid "successfully"; that's implied in the pattern
+Examples: "Changes saved", "Pipeline started", "Integration configured"
+
+### Empty states
+Explanation + CTA. Example: "No assets yet. Connect a data source to start exploring."
+
+### Tooltips
+One to two sentences, present tense. Pattern: `[What it is]. [What it does or why it matters].`
+Examples:
+- "Asset ID. The unique identifier for this asset in Cognite Data Fusion."
+- "Time granularity. Controls how data points are aggregated in the chart."
+Never repeat the label. Never write more than 2 sentences.
+
+### Confirmation dialogs
+State the consequence, not just the action. Pattern: `[What will be lost or affected]. [Reversibility]. [Specific action].`
+- Primary CTA: match the specific action ("Delete pipeline", not "Confirm")
+- Secondary CTA: always provide a clear exit ("Cancel")
+Examples:
+- "Delete pipeline? All runs and history will be permanently removed. This can't be undone."
+- "Remove team member? They'll lose access to all shared resources immediately."
+Avoid: "Are you sure?", manipulative phrasing
+
+### Form fields
+- **Labels**: Clear noun phrases ("Time series ID", "Email address")
+- **Placeholder text**: Use sparingly, only for standard formats like "name@example.com"
+- **Helper text**: Verb-first; explain why the information is needed
+
+### Notifications
+Verb-first title + contextual description. 10–15 words total.
+Example: "Extractor disconnected. Check your network and reconnect."
+
+## Accessibility
+
+- Use **"Select"** not "Click" — input-agnostic: mouse, keyboard, touch, voice
+- Avoid ambiguous pronouns — screen readers lose surrounding context
+- Write descriptive link text: "Read pricing details" not "Click here"
+- Alt text by image type:
+  - Icon → describes function: "Download PDF" not "download icon"
+  - Link image → describes destination: "Contact support" not "question mark"
+  - Chart/diagram → summarizes meaning: "Bar chart showing pipeline throughput declining 20% in Q3"
+  - Decorative image → empty alt text (`alt=""`)
+  - Never write "image of" or "photo of"
+- For charts and metrics, describe key trends or values in adjacent text — don't rely on visual encoding alone
+- Target 8–14 words per sentence (8 = 100% comprehension, 14 = 90%)
+- Pair visual indicators with text: "Error: field required" alongside a red icon
+
+## Date and time formatting
+
+- **Prefer written dates**: "2 January 2023" not "02/01/2023"
+- **Relative vs absolute**: ≤24 h from now → relative ("32 min ago"); >24 h → absolute ("2 Jan 2023")
+- Always include the year unless obvious from context
+- No ordinal numbers: "2 January" not "2nd January"
+- Separate date and time with "at": "2 Jan 2023 at 10:00 AM" — no comma
+- **12-hour time**: uppercase AM/PM, no periods, space before: "10:00 AM"
+- **Time zone**: UTC only; spell out "UTC" in text-only contexts
+- Never make the user convert time zones — handle in code
+- Ranges: consistent format across start and end; for ongoing processes use absolute start + "ongoing" until complete
+- Duration: no comma between units ("10 minutes 3 seconds"); space between number and unit in running text ("3 min"); no space in controls ("3min")
+
+**Time unit abbreviations** (no periods; same form singular/plural):
+ms, s, min, hr, d, wk, mo, yr
+
+**Day abbreviations** (3 chars for i18n):
+Mon, Tue, Wed, Thu, Fri, Sat, Sun
+
+**Month abbreviations** (4 chars for i18n):
+Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
+
+## Localization
+
+- Keep sentences short with the subject near the start — compound clauses increase translation cost
+- Maintain consistent terminology and capitalization across strings (critical for translation memory)
+- No Latin abbreviations in translatable strings: "for example" not "e.g.", "and more" not "etc."
+- Avoid idioms and cultural references
+- No ampersands: use "and"
+- Small words (a, the, that, is): include in prose; may omit only in space-constrained labels and CTAs
+
+## Benchmarks
+
+| Element | Target | Maximum |
+|---|---|---|
+| Buttons / CTAs | 2–4 words | 6 words |
+| Titles | 3–6 words, 40 characters | — |
+| Tooltips | 10–20 words | 2 sentences |
+| Error messages | 12–18 words | — |
+| Instructions | 14 words | 20 words |
+| Notifications | 10–15 words total | — |
+| Line length | 40–60 characters | 70 characters |