@cognite/aura 0.3.0 → 0.3.2

package/DESIGN.md

@@ -1,852 +1,2072 @@
+---
+version: alpha
+name: Aura
+description: Cognite's design system for composable UI primitives in data-heavy industrial software.
+colors:
+  primary: '#212426'
+  secondary: '#E4E6E8'
+  tertiary: '#486AED'
+  neutral: '#F1F2F3'
+  background: '#FFFFFF'
+  foreground: '#191B1D'
+  alternate-background: '#F9FAFA'
+  card-background: '#F9FAFA'
+  muted-background: '#F1F2F3'
+  muted-foreground: '#6D767E'
+  primary-background-hover: '#40464A'
+  secondary-background-hover: '#D4D7D9'
+  foreground-on-primary: '#F1F2F3'
+  secondary-foreground: '#40464A'
+  link-foreground: '#486AED'
+  border: '#E4E6E8'
+  border-emphasized: '#D4D7D9'
+  ring: '#7081C7'
+  ring-muted: '#B5BEE2'
+  info-background: '#D0D6ED'
+  info-foreground-on-info: '#32417F'
+  success-background: '#BBF3D0'
+  success-foreground-on-success: '#0F5026'
+  warning-background: '#FFE3A2'
+  warning-foreground-on-warning: '#755200'
+  destructive-background: '#FCCAD2'
+  destructive-foreground-on-critical: '#8D081F'
+  overlay-background: '#7C868E80'
+typography:
+  display:
+    fontFamily: Space Grotesk
+    fontSize: 36px
+    fontWeight: 600
+    lineHeight: 44px
+    letterSpacing: -0.08px
+  h1:
+    fontFamily: Inter
+    fontSize: 32px
+    fontWeight: 600
+    lineHeight: 40px
+    letterSpacing: -0.08px
+  h2:
+    fontFamily: Inter
+    fontSize: 28px
+    fontWeight: 600
+    lineHeight: 32px
+    letterSpacing: -0.08px
+  h3:
+    fontFamily: Inter
+    fontSize: 24px
+    fontWeight: 600
+    lineHeight: 28px
+    letterSpacing: -0.04px
+  h4:
+    fontFamily: Inter
+    fontSize: 20px
+    fontWeight: 500
+    lineHeight: 24px
+    letterSpacing: -0.04px
+  body-md:
+    fontFamily: Inter
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 20px
+    letterSpacing: -0.04px
+  body-sm:
+    fontFamily: Inter
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 18px
+    letterSpacing: -0.04px
+  label:
+    fontFamily: Inter
+    fontSize: 12px
+    fontWeight: 500
+    lineHeight: 14px
+    letterSpacing: -0.04px
+  code:
+    fontFamily: Source Code Pro
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 20px
+rounded:
+  none: 0px
+  xs: 2px
+  sm: 4px
+  md: 6px
+  lg: 8px
+  xl: 12px
+  2xl: 16px
+  3xl: 24px
+  4xl: 32px
+  full: 9999px
+spacing:
+  base: 4px
+  xs: 4px
+  sm: 8px
+  md: 12px
+  lg: 16px
+  xl: 20px
+  2xl: 24px
+  3xl: 32px
+  prose-max: 600px
+  container-2xl: 640px
+  container-8xl: 1536px
+components:
+  button-primary:
+    backgroundColor: '{colors.primary}'
+    textColor: '{colors.foreground-on-primary}'
+    rounded: '{rounded.lg}'
+    padding: '{spacing.md}'
+    height: 36px
+  button-primary-hover:
+    backgroundColor: '{colors.primary-background-hover}'
+  button-secondary:
+    backgroundColor: '{colors.secondary}'
+    textColor: '{colors.foreground}'
+    rounded: '{rounded.lg}'
+    padding: '{spacing.md}'
+    height: 36px
+  button-destructive:
+    backgroundColor: '{colors.destructive-background}'
+    textColor: '{colors.destructive-foreground-on-critical}'
+    rounded: '{rounded.lg}'
+    height: 36px
+  button-sm:
+    height: 28px
+    rounded: '{rounded.lg}'
+  button-lg:
+    height: 40px
+    rounded: '{rounded.lg}'
+  button-secondary-hover:
+    backgroundColor: '{colors.secondary-background-hover}'
+  input-default:
+    backgroundColor: '{colors.background}'
+    textColor: '{colors.foreground}'
+    rounded: '{rounded.lg}'
+    height: 36px
+  input-muted:
+    backgroundColor: '{colors.muted-background}'
+    textColor: '{colors.muted-foreground}'
+    rounded: '{rounded.lg}'
+    height: 36px
+  dialog-overlay:
+    backgroundColor: '{colors.overlay-background}'
+  divider-default:
+    backgroundColor: '{colors.border}'
+  divider-emphasized:
+    backgroundColor: '{colors.border-emphasized}'
+  badge-neutral:
+    backgroundColor: '{colors.neutral}'
+    textColor: '{colors.secondary-foreground}'
+    rounded: '{rounded.sm}'
+  panel-alternate:
+    backgroundColor: '{colors.alternate-background}'
+    textColor: '{colors.foreground}'
+  card-default:
+    backgroundColor: '{colors.card-background}'
+    textColor: '{colors.foreground}'
+    rounded: '{rounded.xl}'
+    padding: '{spacing.lg}'
+  link-default:
+    textColor: '{colors.link-foreground}'
+    typography: '{typography.body-md}'
+  badge-xs:
+    height: 20px
+    rounded: '{rounded.sm}'
+  alert-info:
+    backgroundColor: '{colors.info-background}'
+    textColor: '{colors.info-foreground-on-info}'
+    rounded: '{rounded.lg}'
+  alert-success:
+    backgroundColor: '{colors.success-background}'
+    textColor: '{colors.success-foreground-on-success}'
+    rounded: '{rounded.lg}'
+  alert-warning:
+    backgroundColor: '{colors.warning-background}'
+    textColor: '{colors.warning-foreground-on-warning}'
+    rounded: '{rounded.lg}'
+  alert-destructive:
+    backgroundColor: '{colors.destructive-background}'
+    textColor: '{colors.destructive-foreground-on-critical}'
+    rounded: '{rounded.lg}'
+---
+
 ## Overview
 
-Aura is the design system for Cognite Data Fusion experiences: composable UI primitives (buttons, inputs, overlays, AI/chat surfaces), Tailwind v4 theme extensions, and **Base**, **Decorative**, and **Semantic** tokens. Interfaces should feel **clear, layered without clutter, and trustworthy** — mountain neutrals for structure, fjord for links and focus, and restrained decorative ramps for accents, charts, and status.
+Aura is the official design system for Cognite experiences: composable UI primitives for data-heavy industrial software.
 
-**What belongs in this file:** identity, token *names*, *roles*, and *resolved reference values* so humans and agents choose the right variable or Tailwind color/shadow/radius utility; **[Content](#content)** for UI copy (action labels, dates, grammar, localization, voice, accessible writing). **How** to wire themes, run Figma sync, or verify in CI belongs in Aura engineering / agent skills, not here.
+Aura should feel like an **industrial control room**: quiet surfaces, stable hierarchy, immediate status signals, and controls that stay out of the operator's way until action is needed. The interface is engineered, not decorated. It gives dense operational data enough structure to scan quickly, reserves color for meaning, and makes interaction states predictable under pressure.
 
-**Where the CSS sources live**
+Light and dark themes share the same semantic roles; fixed tokens support persistent shell chrome.
 
-The canonical token files (`colors.css`, `styles.source.css`) live in the Aura library repo under `src/`. In a consuming app they are available through the published package — import from `@cognite/aura/colors.css` and `@cognite/aura/styles.css`. Do not look for `src/colors.css` next to your app code; resolve token names via your IDE's autocomplete on `@cognite/aura`, or consult the tables in [Tokens](#tokens) below.
+**Tokens:** Reference values live in the YAML front matter at the top of this file. They provide context for agents and humans — the prose sections below carry design intent, constraints, and reasoning. Reference tokens in prose as `{colors.<name>}`, `{spacing.<name>}`, `{typography.<name>}`, `{rounded.<name>}`, and `{components.<name>}`.
 
-**Code:** In Fusion / host apps (example convention), ship UI from Aura exports (`@cognite/aura/components`, [Storybook](https://storybook-aura-23638.fusion-preview.preview.cogniteapp.com)) under e.g. `src/components/ui`; prefer **CVA** variants. **[Interaction states](#interaction-states)**, **[Heuristics](#heuristics)**, and **[Content](#content)** define how to use primitives — prefer component APIs over reimplementing or overriding internals when a variant already matches intent. **Prop names, `size` values, and subcomponents** are **not** duplicated here; use [Storybook](https://storybook-aura-23638.fusion-preview.preview.cogniteapp.com), the [Aura design system documentation](https://docs.cognite.com/aura-design-system/get-started) (foundations, primitives, installation), and TypeScript types from `@cognite/aura/components` as the source of truth. For color in product UI, use tokens — not raw `hex` / `rgb` / `hsl` when a semantic or base token exists; details under **[Tokens](#tokens)**.
+**Implementation:** Package imports, component APIs, and host-shell integration live in the Aura [README](./README.md) — not in this file.
 
-## Dashboard quick start (agent checklist)
+### For agents: how to read this file
 
-For pages with data-heavy layouts — cards, charts, metric tiles — work through these steps before writing component code.
+Before editing or generating from this file, read Google's [DESIGN.md Philosophy](https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md). The philosophy applies directly to how Aura's spec should be used:
 
-- [ ] **Tokens** — confirm all colors use semantic or chart tokens, no raw hex. Metric tiles: `decorative-*`. Data series: `chart-*`. Status: `info-*`, `success-*`, `warning-*`, `destructive-*`. See [Tokens → Color](#color).
-- [ ] **Layout** — use a 12-column grid with `gap-4` or `gap-6`. Tile widths: `col-span-12 sm:col-span-6 lg:col-span-3`. Cap the page frame with `max-w-[min(100%,var(--container-8xl))]`. 
-- [ ] **Cards** — use the `Card` component with title, description, and a primary action. Do not stack unrelated actions in the same card. See [Heuristics §6.1](#61-grouping-and-proximity).
-- [ ] **Loading states** — every data region must show `Shimmer` (known layout) or `Loader` (unknown layout) while fetching. See [Heuristics §1.1](#11-loading-states).
-- [ ] **Status signals** — default to **Badge** or compact status cards for repeated states; keep **Alert** to one page-level inline instance unless multiple independent incidents each need separate action. See [Alert vs Banner vs Badge vs Sonner](#alert-vs-banner-vs-badge-vs-sonner).
-- [ ] **Navigation** — one Topbar, no sidebar. Chart sub-navigation lives in the content area. See [Heuristics §3.3](#33-contextual-menus-and-secondary-actions).
-- [ ] **Accessibility** — every chart must have a text summary of key insights. Icon-only controls must have `aria-label` and a `Tooltip`. See [Heuristics §7](#7-accessibility-and-inclusive-design).
+1. **Start with prose, not tokens.** The quality of generated UI depends more on understanding _intent_ than on copying hex values. Read **Overview**, **Do's and Don'ts**, **Heuristics**, **Interaction states**, and **Content** before implementing from the YAML block. Use **Heuristics** for detailed feedback, disclosure, error, layout, and accessibility decisions.
+2. **Tokens are context, not rendering instructions.** YAML values anchor names and approximate light-theme references. Runtime styling comes from `@cognite/aura/colors.css`, `@cognite/aura/styles.css`, and component APIs — not from reimplementing token literals in product code.
+3. **Prefer specific constraints over adjectives.** Aura targets data-heavy industrial software: flat hierarchy, semantic color only for status and feedback, predictable interaction states, and calm surfaces. When prose and a token disagree, follow the prose rationale.
+4. **Negative constraints matter.** **Do's and Don'ts** and the **Avoid** / **Must not** rules in Heuristics define character as much as the palette.
+5. **Extension sections are intentional.** Sections beyond the core design.md spec order — **Assets & Motion**, **Heuristics**, **Interaction states**, **Content** — extend the format for Aura. UX playbook guidance lives in this file.
+
+### Alignment with Google design.md
+
+| Philosophy principle                  | Aura approach                                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Prose carries design intent           | Overview, colors, interaction states, content, and do's/don'ts are the primary identity guidance         |
+| Tokens referenced in prose            | Key roles use `{colors.*}`, `{spacing.*}`, etc. inline; full ramps stay in tables and CSS                |
+| Specific reference > vague adjectives | Overview names data-heavy industrial UI; heuristic rules carry constraints                               |
+| Do's and don'ts as guardrails         | Dedicated **Do's and Don'ts** section plus compact severity-rated heuristics                             |
+| Format extends beyond the spec        | Motion, iconography, elevation, copy, accessibility, and extended UX guidance live in extension sections |
 
 ---
 
-## Heuristics
+## Colors
 
-**What this section is:** Interaction-quality, disclosure, error, power-user, layout, and accessibility heuristics for **Aura-based** UIs. **Severity:** **Must** / **must not** — breaks usability, a11y, or system conformance; **Should** — strong default, deviate only with intent; **Avoid** — known failure mode. Component **names** and composition patterns are specified here; **props and enums** live in Storybook and package types (see **Overview**).
+Aura color behaves like instrumentation in a control room. Most of the interface is neutral structure; important changes appear as clear signals; decorative color is rare and never competes with status. A screen should still make sense when color is removed, but color should make state faster to recognize.
 
-**Who:** Designers reviewing UI, engineers implementing features, agents generating or auditing code.
+Use **Base** color for the operating surface: page backgrounds, cards, text, borders, focus, and persistent chrome. This is ~80–90% of the UI.
 
-**Scope — two layers**
+Use **Semantic** color only for status and feedback: info, success, warning, destructive, validation, and operational state. This is ~5–10% of the UI.
 
-- **`@cognite/aura`:** primitives exported from this library ([Storybook](https://storybook-aura-23638.fusion-preview.preview.cogniteapp.com)). **Components:** lines below name Aura exports where they exist.
-- **Fusion / app shell:** patterns such as global **Topbar**, **Sonner** toasts, **AlertDialog**, **Sheet** / **Drawer**, **Tabs**, **SegmentedControl**, **Checkbox** / **Radio** / **Switch**, **ContextMenu**, or **EmptyState** may live **outside** this package — **Must** still follow the same **Tokens**, **Interaction states**, and severity rules using your shell’s components or Radix-style primitives themed with Aura.
-- **Minimal or standalone apps** (no Fusion shell): apply the **same tokens** and **interaction rules** with Aura primitives and your stack’s equivalents. **Must** rules that name shell-only components (**Topbar**, **Sonner**, **AlertDialog**, **Sheet**, …) apply **when that capability exists** — treat them as **Should** / **when available** and substitute with the closest Aura or Radix pattern; wire **TooltipProvider** (or your tooltip root) at app root wherever **Tooltip** is used. Do not invent a fake shell just to satisfy a checklist.
+Use **Decorative** color only for non-status differentiation: accents, avatars, illustrations, and small visual markers that do not imply system health. This is ~5–10% of the UI.
 
----
+Light-theme reference values for key roles are defined as `colors.*` tokens in the YAML front matter (referenced in tables as `{colors.<name>}`); full ramps and dark-theme values are in the tables below.
 
-### 1. Feedback and system status
+Do not hardcode hex, font sizes, or shadow strings in product UI when a token exists.
 
-Users **must** always know what changed: loading, success, failure, or background work needs a visible signal.
+Aura supports **light** (`:root`) and **dark** (`.dark` / `prefers-color-scheme: dark` per library setup). Semantic and base tokens **resolve to different ramps** per theme. **`background-fixed-dark`**, **`background-fixed-light`**, **`foreground-fixed-*`**, and related **fixed** tokens keep the same appearance in both themes (persistent chrome such as sidebars). Always verify contrast in both themes before shipping.
 
-#### 1.1 Loading states
+Reference tokens by **full CSS name** or Tailwind token. Never use raw `hex` / `rgb` / `hsl` in product code. If no semantic token fits, use a documented **base** token; **step colors** on ramps (`mountain/*`, `fjord/*`, …) are only for custom, branding, or marketing surfaces where no semantic token exists yet.
 
-**Applies when:** Data fetch, async work, route transition, or slow AI step blocks meaningful UI.
+### Common Tailwind mappings
 
-**Aura components:** `Shimmer`, `Loader`, `Progress`, `Skeleton`
+Tables in this section use **CSS role names** (e.g. `link-foreground`, `card-background`). Each role maps to a `--color-{role}` custom property and Tailwind v4 utilities (`text-{role}`, `bg-{role}`, `border-{role}`, and `ring-{role}` where applicable). Prefer these utilities over raw `var(--…)` when the theme wire-up matches.
+
+| Role (suffix after `text-` / `bg-` / `border-`) | Typical utilities                                                                   | Notes                                                 |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `background`                                    | `bg-background`                                                                     | Page base                                             |
+| `foreground`                                    | `text-foreground`                                                                   | Primary text                                          |
+| `muted-foreground`                              | `text-muted-foreground`                                                             | Tertiary copy                                         |
+| `card-background`                               | `bg-card-background`                                                                | Cards (see **Card** component)                        |
+| `muted-background`                              | `bg-muted-background`                                                               | Static fills, inputs, secondary chrome                |
+| `border`                                        | `border-border`                                                                     | Default strokes                                       |
+| `link-foreground` (`{colors.link-foreground}`)  | `text-link-foreground`                                                              | Text links — same value as `{colors.tertiary}`        |
+| `primary-background`                            | `bg-primary-background`, `text-foreground-on-primary`                               | Default **Button** (`variant="default"`) pattern      |
+| `destructive-background`                        | `bg-destructive-background`, `text-destructive-foreground-on-critical` (on surface) | Destructive actions — pairings in **Semantic colors** |
+| `info-background`, `success-background`, …      | `bg-info-background`, `text-info-foreground`, …                                     | Full names match **Semantic colors** token columns    |
+
+Semantic utilities use the **full token name** as the Tailwind segment (e.g. `bg-info-background`, not `bg-info`). For **charts**, utilities follow the **Chart tokens** names (`bg-chart-fjord-color-1`, `bg-chart-gridlines`, …).
+
+Tables below list **light-theme** values as `{colors.<name>}` token references in the YAML front matter and **dark-theme** resolved values in the second column; the published `colors.css` is the runtime source of truth (some entries are `rgba()`).
+
+### Base — Background
+
+| Token                           | Light (reference)                     | Dark (reference) | Use                                                                |
+| ------------------------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `background`                    | `{colors.background}`                 | `#191B1D`        | Primary surface — lowest layer                                     |
+| `alternate-background`          | `{colors.alternate-background}`       | `#111213`        | Distinct layer or block separate from `background`                 |
+| `card-background`               | `{colors.card-background}`            | `#212426`        | Cards without drop shadow on `background` / `alternate-background` |
+| `muted-background`              | `{colors.muted-background}`           | `#2D3134`        | Static fills for controls, rows, segmented controls                |
+| `primary-background`            | `{colors.primary}`                    | `#F9FAFA`        | Primary actions (default button); use sparingly                    |
+| `primary-background-hover`      | `{colors.primary-background-hover}`   | `#E4E6E8`        | Hover on `primary-background`                                      |
+| `secondary-background`          | `#E4E6E8`                             | `#40464A`        | Secondary actions, switch track                                    |
+| `secondary-background-hover`    | `{colors.secondary-background-hover}` | `#5E666D`        | Hover on `secondary-background`                                    |
+| `accent-background`             | `#F1F2F3`                             | `#2D3134`        | Neutral hover on `background` / `card-background` (e.g. tabs)      |
+| `accent-background-strong`      | `#E4E6E8`                             | `#40464A`        | Neutral hover on `muted-background` / `active-muted-background`    |
+| `highlight-background`          | `#F1F2F3`                             | `#2D3134`        | Focused / active fields (inputs, selects, comboboxes)              |
+| `highlight-background-strong`   | `#E4E6E8`                             | `#40464A`        | Stronger focused / active field fill                               |
+| `active-background`             | `#191B1D`                             | `#F9FAFA`        | High-contrast “on” (switch, checkbox, radio)                       |
+| `active-background-hover`       | `#2D3134`                             | `#F1F2F3`        | Hover on `active-background`                                       |
+| `active-muted-background`       | `#F1F2F3`                             | `#2D3134`        | Lower-contrast selected (e.g. tabs)                                |
+| `active-muted-background-hover` | `#E4E6E8`                             | `#40464A`        | Hover on `active-muted-background`                                 |
+| `popover-background`            | `#FFFFFF`                             | `#212426`        | Top-layer surfaces with shadow (dialogs, popovers)                 |
+| `raised-background`             | `#2D3134`                             | `#40464A`        | Tooltips, Sonner toasts — floats above page                        |
+| `disabled-background`           | `#F1F2F3`                             | `#2D3134`        | Disabled inputs and controls                                       |
+| `overlay-background`            | `{colors.overlay-background}`         | `#7C868E80`      | Scrim behind modals                                                |
+| `background-fixed-dark`         | `#212426`                             | `#212426`        | Must stay **dark** in both themes                                  |
+| `background-fixed-light`        | `#FFFFFF`                             | `#FFFFFF`        | Must stay **light** in both themes                                 |
+| `accent-background-fixed-dark`  | `#2D3134`                             | `#2D3134`        | Persistent dark accent chrome (e.g. sidebar)                       |
+
+### Base — Foreground
+
+| Token                              | Light (reference)                | Dark (reference) | Use                            |
+| ---------------------------------- | -------------------------------- | ---------------- | ------------------------------ |
+| `foreground`                       | `{colors.foreground}`            | `#F1F2F3`        | Primary text and icons         |
+| `secondary-foreground`             | `{colors.secondary-foreground}`  | `#D4D7D9`        | Supporting text and icons      |
+| `muted-foreground`                 | `{colors.muted-foreground}`      | `#A5ABB1`        | Tertiary / low emphasis        |
+| `disabled-foreground`              | `#D4D7D9`                        | `#5E666D`        | Disabled text and icons        |
+| `link-foreground`                  | `{colors.link-foreground}`       | `#1742E7`        | Text links                     |
+| `foreground-on-primary`            | `{colors.foreground-on-primary}` | `#191B1D`        | On `primary-background`        |
+| `foreground-on-active`             | `#F1F2F3`                        | `#191B1D`        | On `active-background`         |
+| `active-foreground`                | `#191B1D`                        | `#F1F2F3`        | On `active-muted-background`   |
+| `foreground-fixed-dark`            | `#191B1D`                        | `#191B1D`        | Must stay dark in both themes  |
+| `foreground-fixed-light`           | `#FFFFFF`                        | `#FFFFFF`        | Must stay light in both themes |
+| `foreground-secondary-fixed-dark`  | `#40464A`                        | `#40464A`        | Secondary copy, always dark    |
+| `secondary-foreground-fixed-light` | `#D4D7D9`                        | `#D4D7D9`        | Secondary copy, always light   |
+| `muted-foreground-fixed-light`     | `#BBC0C4`                        | `#BBC0C4`        | Muted copy, always light       |
+
+### Base — Borders and focus
+
+| Token               | Light (reference)            | Dark (reference) | Use                                              |
+| ------------------- | ---------------------------- | ---------------- | ------------------------------------------------ |
+| `border`            | `{colors.border}`            | `#2D3134`        | Default strokes                                  |
+| `border-emphasized` | `{colors.border-emphasized}` | `#40464A`        | Stronger separation                              |
+| `border-on-dark`    | `#2D3134`                    | `#2D3134`        | Strokes on dark chrome (both themes)             |
+| `border-active`     | `#191B1D`                    | `#F9FAFA`        | Active / toggled outlines                        |
+| `ring`              | `{colors.ring}`              | `#7081C7`        | Focus ring outer (maps to `--shadow-focus-ring`) |
+| `ring-muted`        | `{colors.ring-muted}`        | `#B5BEE2`        | Focus ring inner companion                       |
 
-**Rules**
+Also generated: `ring-destructive`, `ring-destructive-muted` for destructive / invalid focus (see **Effects — Focus rings**).
 
-- **Must** show loading for any wait the user is expected to sit through.
-- **Must** use **Shimmer** when the layout of incoming content is known (list rows, cards, table skeleton).
-- **Must** use **Loader** for compact inline waits (e.g. inside a **Button** or card header).
-- **Must** use a **full-surface** pattern (centered **Loader**, **Skeleton** layout, or app **PageLoader**) for full-page or high-latency transitions including long AI operations.
-- **Should** use **Progress** when completion is measurable (upload %, stepped flow).
-- **Avoid** blank content areas with no indicator.
-- **Avoid** using only a tiny spinner for large unknown layouts — prefer **Shimmer** / **Skeleton**.
+### Semantic colors
 
-#### 1.2 Action confirmation
+Semantic tokens are **only** for status and system feedback (Alert, Banner, Sonner, badge status variants, validation). Do not use them as generic fills or decoration.
 
-**Applies when:** User actions mutate state (save, submit, delete, copy, send).
+Each family has **default** pairings (theme-switching surfaces) and **muted** pairings (blocks on **persistent dark chrome**). On muted surfaces, use the same `*-foreground-on-*` token names with the muted background; verify contrast in context.
 
-**Aura components:** `Dialog` (+ destructive **Button**), `Alert`, `Tooltip`, `Banner`  
-**App / shell:** Sonner (or equivalent toast), dedicated confirm **AlertDialog** where the shell provides it
+**Info**
 
-**Rules**
+| Token                     | Light (reference)                  | Dark (reference) | Use                                                                           |
+| ------------------------- | ---------------------------------- | ---------------- | ----------------------------------------------------------------------------- |
+| `info-background`         | `{colors.info-background}`         | `#B5BEE2`        | Info surface                                                                  |
+| `info-background-hover`   | `#B5BEE2`                          | `#D0D6ED`        | Hover on `info-background`                                                    |
+| `info-foreground`         | `#4A5FB8`                          | `#9DA9D9`        | Text near info context on standard surfaces                                   |
+| `info-foreground-on-info` | `{colors.info-foreground-on-info}` | `#1A2242`        | Text **on** `info-background`                                                 |
+| `info-muted-background`   | `#F0F2F9`                          | `#2D3134`        | Info tint on dark chrome                                                      |
+| _(pairing)_               | —                                  | —                | On `info-muted-background`, use `info-foreground-on-info` for on-surface copy |
 
-- **Must** acknowledge user-triggered mutations with a visible signal.
-- **Must** use **transient toast** (e.g. Sonner, bottom-right, ~4s auto-dismiss) for low-stakes confirmations (“Saved”, “Copied”) — theme with Aura tokens.
-- **Must** use **Dialog** (or shell **AlertDialog**) with explicit copy **before** irreversible actions — not only after the fact.
-- **Should** offer **Undo** in the toast when the action is reversible and undo is cheap.
-- **Should** use **Tooltip** (“Copied!”) for copy on small icon targets.
-- **Avoid** `alert()` and other native blocking dialogs for product UX.
-- **Avoid** stacking multiple toasts for a single user gesture.
+**Success**
 
-#### 1.3 System status visibility
+| Token                           | Light (reference)                        | Dark (reference) | Use                                                                |
+| ------------------------------- | ---------------------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `success-background`            | `{colors.success-background}`            | `#8BDEAE`        | Success surface                                                    |
+| `success-background-hover`      | `#8BDEAE`                                | `#BBF3D0`        | Hover on `success-background`                                      |
+| `success-foreground`            | `#1C984A`                                | `#24C45E`        | Text near success on standard surfaces                             |
+| `success-foreground-on-success` | `{colors.success-foreground-on-success}` | `#0A381C`        | Text **on** `success-background`                                   |
+| `success-muted-background`      | `#DDF9E7`                                | `#2D3134`        | Success on dark chrome                                             |
+| _(pairing)_                     | —                                        | —                | On `success-muted-background`, use `success-foreground-on-success` |
 
-**Applies when:** **Persistent** problems with **user-visible workflow impact** — degraded mode, auth expiry, data stale beyond policy, or API health that blocks or misleads work — not routine connection handshakes or background connectivity that users do not need to monitor continuously.
+**Warning**
 
-**Aura components:** `Alert`, `Badge`, `Banner`, `Loader` (see §1.1)  
-**App:** `Sonner` for ephemeral global notices
+| Token                           | Light (reference)                        | Dark (reference) | Use                                    |
+| ------------------------------- | ---------------------------------------- | ---------------- | -------------------------------------- |
+| `warning-background`            | `{colors.warning-background}`            | `#FFE3A2`        | Warning surface                        |
+| `warning-background-hover`      | `#FFD062`                                | `#FFF1D0`        | Hover on `warning-background`          |
+| `warning-foreground`            | `#C18800`                                | `#D8BF00`        | Text near warning on standard surfaces |
+| `warning-foreground-on-warning` | `{colors.warning-foreground-on-warning}` | `#5B4000`        | Text **on** `warning-background`       |
+| `warning-muted-background`      | `#FFF1D0`                                | `#2D3134`        | Warning on dark chrome                 |
 
-**Rules**
+**Destructive**
 
-- **Must** surface problems that stay **until dismissed or resolved** and **scope to a region** with **Banner** at the top of that region — when the issue is **persistent** and **not** low-salience ambient state.
-- **Must** use **Alert** for inline, page-scoped status that needs awareness but not always immediate action, and keep it to **one page-level Alert per view** in standard dashboards.
-- **Should** use **Badge** semantic variants (`warning`, `destructive`, …) on entities carrying that state.
-- **Should** represent repeated or list-level status (many assets, tasks, signals) with **Badge**, metric/status cards, or concise icon+text rows — not repeated Alert stacks.
-- **Should** use **Loader** (inline or full-surface per §1.1) for transient waits such as host handshake or reconnect; use **Banner** only when the degraded state **remains** after loading settles.
-- **Should** use a short **Sonner** or **inline Alert** for **optional** or **intermittent** connection notices instead of permanent chrome.
-- **Avoid** hiding workflow-critical status **only** behind hover.
-- **Avoid** dedicating **Banner** or other persistent strip space to connection state when users **do not** need that signal continuously — prefer compact indicators (**Badge**, toolbar dot, footer text) or nothing until failure.
-- **Avoid** treating routine “connecting / connected” or handshake flows as the default **Banner** channel — same rationale as **Avoid** using **Banner** for long onboarding when critical alerts need that channel (§5.3).
-- **Avoid** stacking multiple Alerts inside one card or page section to enumerate line items; aggregate the message and push per-item state to badges or compact status rows.
+| Token                                | Light (reference)                             | Dark (reference) | Use                                                |
+| ------------------------------------ | --------------------------------------------- | ---------------- | -------------------------------------------------- |
+| `destructive-background`             | `{colors.destructive-background}`             | `#FAA9B7`        | Error / destructive surface                        |
+| `destructive-background-hover`       | `#FAA9B7`                                     | `#FCCAD2`        | Hover on `destructive-background`                  |
+| `destructive-foreground`             | `#CB0B2C`                                     | `#F65E78`        | Text near destructive context on standard surfaces |
+| `destructive-foreground-on-critical` | `{colors.destructive-foreground-on-critical}` | `#8D081F`        | Text **on** `destructive-background`               |
+| `destructive-muted-background`       | `#FDDEE4`                                     | `#2D3134`        | Destructive on dark chrome                         |
+| `destructive-muted-background-hover` | `#FCCAD2`                                     | `#40464A`        | Hover on `destructive-muted-background`            |
 
-### Alert vs Banner vs Badge vs Sonner
+**Neutral** (status: draft, archived — not “semantic calm” in the same sense as info/success)
 
-Use this matrix to pick the right feedback component. Priority is defined by whether the message requires immediate action and how long it needs to persist.
+| Token                           | Light (reference) | Dark (reference) | Use                              |
+| ------------------------------- | ----------------- | ---------------- | -------------------------------- |
+| `neutral-background`            | `#E4E6E8`         | `#D4D7D9`        | Neutral status surface           |
+| `neutral-background-hover`      | `#D4D7D9`         | `#E4E6E8`        | Hover on `neutral-background`    |
+| `neutral-foreground`            | `#52595F`         | `#A5ABB1`        | Text near neutral status         |
+| `neutral-foreground-on-neutral` | `#40464A`         | `#2D3134`        | Text **on** `neutral-background` |
+| `neutral-muted-background`      | `#F1F2F3`         | `#2D3134`        | Neutral on dark chrome           |
 
-| Priority | When | Components | Notes |
-| :--- | :--- | :--- | :--- |
-| **Low** | Non-disruptive updates, minor status, validation hints | `Badge`, notification dot, inline `HelperText` | Does not interrupt the user. Badge for entity state; HelperText for field-level feedback. |
-| **Medium** | Informative, occasionally actionable, not urgent | `Sonner` (toast), `Alert` | Sonner for transient confirmations (~4 s, bottom-right). Alert for inline, page-scoped status that needs awareness but not immediate action (typically one per page section/view). |
-| **High** | Requires immediate attention or action; may interrupt task flow | `Banner` (system errors), `Dialog` / `AlertDialog`, full-page error state | Banner for persistent, region-scoped degraded states. Dialog for irreversible actions. Never use Sonner as the sole safety net for destructive work. |
+**Naming:** CSS uses full role names (`info-foreground-on-info`, `neutral-foreground-on-neutral`, `destructive-foreground-on-critical`). There is no shortened alias in the theme.
 
-**Rules**
+### Decorative colors
 
-- **Must not** use Banner for low-priority or transient notices — it occupies persistent chrome and dilutes high-priority signals.
-- **Must not** use Sonner for errors that require user action — it auto-dismisses.
-- **Must not** use repeated Alerts as a list visualization pattern; one Alert communicates the grouped situation, while item-level status belongs in Badge/status-card patterns.
-- **Should** use `Badge` semantic variants (`warning`, `destructive`, `success`) on entities that carry that state, not as page-level alerts.
-- **Avoid** stacking multiple Sonner toasts for a single user gesture.
+For **small accents** (badges, avatars, empty states) where color differentiates but does **not** signal status — use **Chart tokens** for plot colors, not this ramp, unless a design explicitly maps a tile to a series color. Pattern: `decorative-background-{ramp}`, `decorative-background-{ramp}-hover`, `decorative-foreground-{ramp}`.
 
-**Industrial / operational states**
+**Preference order for new work:**
 
-The matrix above covers standard cases. For domain-specific states (e.g. sensor offline, process limit breach, control system degraded), apply the same priority logic: does the user need to act now? -> Banner or Dialog. Informational? -> Alert or Badge on the asset. Transient confirmation? -> Sonner. When many entities share similar state, summarize once (Alert/Banner) and show per-entity state with Badge or status cards.
+| Priority | Ramp     | Background                       | Foreground                       |
+| -------- | -------- | -------------------------------- | -------------------------------- |
+| 1        | Fjord    | `decorative-background-fjord`    | `decorative-foreground-fjord`    |
+| 2        | Nordic   | `decorative-background-nordic`   | `decorative-foreground-nordic`   |
+| 3        | Aurora   | `decorative-background-aurora`   | `decorative-foreground-aurora`   |
+| 4        | Dusk     | `decorative-background-dusk`     | `decorative-foreground-dusk`     |
+| 5        | Orange   | `decorative-background-orange`   | `decorative-foreground-orange`   |
+| 6        | Sky      | `decorative-background-sky`      | `decorative-foreground-sky`      |
+| 7        | Mountain | `decorative-background-mountain` | `decorative-foreground-mountain` |
+
+Example (fjord ramp): light `decorative-background-fjord` → `#CCD5FA` (fjord-200), `decorative-foreground-fjord` → `#1234B6` (fjord-700); dark → `#AEBDF7` / `#0D2582` (fjord-300 / fjord-800).
+
+### Chart tokens
+
+**Priority rule:** use `chart-*` for any data plotted on axes or series; use `decorative-*` for non-data visual differentiation (tiles, avatars, accents); use semantic tokens (`info-*`, `success-*`, `warning-*`, `destructive-*`) for operational status and feedback only. Never swap between these groups.
+
+| Token                                           | Use                                                         |
+| ----------------------------------------------- | ----------------------------------------------------------- |
+| `chart-{ramp}-color-1` … `chart-{ramp}-color-6` | Alpha-based series / area-fill steps (strongest → lightest) |
+| `chart-gridlines`                               | Grid lines                                                  |
+
+Default series order: **fjord → nordic → aurora → dusk → orange**.
 
 ---
 
-### 2. Affordance and discoverability
+## Typography
 
-Controls **must** read as interactive; users **should** not guess what is clickable, expandable, or editable.
+Aura uses **Inter** for product UI, **Space Grotesk** for marketing display, and **Source Code Pro** for monospace. The type scale balances density for data interfaces with readable body copy at `{typography.body-md.fontSize}`.
 
-#### 2.1 Interactive signifiers
+| Token                          | Font            | Use                                 |
+| ------------------------------ | --------------- | ----------------------------------- |
+| `--font-sans` / `--font-inter` | Inter           | Default UI — copy, labels, dense UI |
+| `--font-marketing`             | Space Grotesk   | Marketing / display headings only   |
+| `--font-mono`                  | Source Code Pro | Code, technical strings             |
 
-**Applies when:** Click, drag, expand, or edit.
+**Type scale** — values live in the YAML `typography` tokens. Typical **semantic styles** map as follows:
 
-**Aura components:** `Button`, `DropdownMenu`, `Collapsible`, `Accordion`, `Select`, `Command`
+| Style     | Token                  | Tailwind class | Use                      |
+| --------- | ---------------------- | -------------- | ------------------------ |
+| `display` | `{typography.display}` | `text-5xl`     | Hero / marketing display |
+| `h1`      | `{typography.h1}`      | `text-4xl`     | Page title               |
+| `h2`      | `{typography.h2}`      | `text-3xl`     | Section title            |
+| `h3`      | `{typography.h3}`      | `text-2xl`     | Subsection               |
+| `h4`      | `{typography.h4}`      | `text-xl`      | Group label              |
+| `body-md` | `{typography.body-md}` | `text-base`    | Default body             |
+| `body-sm` | `{typography.body-sm}` | `text-sm`      | Secondary body           |
+| `label`   | `{typography.label}`   | `text-xs`      | Form labels, compact UI  |
+| `code`    | `{typography.code}`    | `text-sm`      | Monospace content        |
 
-**Rules**
+---
 
-- **Must** use **Button** for discrete actions — not `div`/`span` with `onClick` styled as buttons.
-- **Must** match **Button** `variant` to prominence: `default` = primary CTA, `secondary` / `outline` / `ghost` for supporting actions, `destructive` for irreversible commit.
-- **Must** use a **chevron-down** (or equivalent) on controls that open menus or expandable regions, consistent with **DropdownMenu** / **Collapsible** / **Accordion** patterns.
-- **Should** keep **`pointer`** cursor on interactive surfaces — Aura sets this; do not override without cause.
-- **Avoid** custom “clickable text” that looks identical to body copy.
+## Layout
 
-#### 2.2 Labels and recognizable patterns
+### Dashboard quick start (agent checklist)
 
-**Applies when:** Forms, navigation, empty views, search.
+For pages with data-heavy layouts — cards, charts, metric tiles — work through these steps before writing component code.
 
-**Aura components:** `Label`, `Input`, `Textarea`, `Select`, `Card`, `Command` / `CommandInput`
+- [ ] **Tokens** — confirm all colors use semantic or chart tokens, no raw hex. Metric tiles: `decorative-*`. Data series: `chart-*`. Status: `info-*`, `success-*`, `warning-*`, `destructive-*`. See [Colors](#colors).
+- [ ] **Layout** — use a 12-column grid with `gap-4` or `gap-6`. Tile widths: `col-span-12 sm:col-span-6 lg:col-span-3`. Cap the page frame with `max-w-[min(100%,var(--container-8xl))]`.
+- [ ] **Cards** — use the `Card` component with title, description, and a primary action. Do not stack unrelated actions in the same card. See [Layout and hierarchy](#6-layout-and-hierarchy).
+- [ ] **Loading states** — every data region must show `Shimmer` (known layout) or `Loader` (unknown layout) while fetching. See [Feedback and system status](#1-feedback-and-system-status).
+- [ ] **Status signals** — default to **Badge** or compact status cards for repeated states; keep **Alert** to one page-level inline instance unless multiple independent incidents each need separate action. See [Alert vs Banner vs Badge vs Sonner](#alert-vs-banner-vs-badge-vs-sonner).
+- [ ] **Navigation** — one primary app chrome; avoid duplicating global navigation inside content. See [Layout and hierarchy](#6-layout-and-hierarchy).
+- [ ] **Accessibility** — every chart must have a text summary of key insights. Icon-only controls must have `aria-label` and a `Tooltip`. See [Accessibility and inclusive design](#7-accessibility-and-inclusive-design).
 
-**Rules**
+### Layout and spacing
 
-- **Must** pair every field with a visible **Label** — placeholders are not labels.
-- **Must** use recognizable patterns (search field + magnifier icon, menu trigger + chevron).
-- **Should** use **Card** + title/description + **Button** for first-use empty views — not a bare white panel.
-- **Avoid** ambiguous icon-only controls without **Tooltip** + accessible name (see §2.3).
+Width and spacing values in this subsection follow the **`{spacing.base}`-based** spacing scale in **[Layout → Size and dimensions](#size-and-dimensions)**.
 
-#### 2.3 Contextual help
+**Body text reading width**
 
-**Applies when:** Non-obvious behavior, format rules, or icon-only controls.
+- **Must** cap **continuous body text** (paragraphs, descriptions, long labels) at a **maximum width of `{spacing.prose-max}`** for comfortable reading.
+- **Must** apply that limit to the **text column only** — companion UI (icons, thumbnails, side metadata, charts, code blocks) **may** sit outside that `{spacing.prose-max}` band in the same row or card; do not shrink the text measure to absorb those elements.
+- **Should** implement the cap with `max-w-[{spacing.prose-max}]` / `max-w-[37.5rem]` (or an equivalent layout wrapper) on the text block, not by stretching typography alone inside an arbitrarily wide container.
+
+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
+
+### Layout patterns
+
+#### Sidebar content
+3+ top-level sections. Persistent navigation needed.
+Most common for multi-page apps.
+
+**Structure**
+
+```
+┌──────────┬─────────────────────────────┐
+│          │  Page Header / Breadcrumb   │
+│  Sidebar │─────────────────────────────│
+│   Nav    │                             │
+│  (dark)  │  Main Content Area          │
+│          │  (bg-background)            │
+│          │                             │
+└──────────┴─────────────────────────────┘
+```
+
+**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.
+
+#### Full-width dashboard
+Data visualizations, metrics, monitoring. Maximum horizontal space needed.
+
+**Structure**
+
+```
+┌─────────────────────────────────────────┐
+│  Top Navigation Bar                      │
+├─────────────────────────────────────────┤
+│  Page Header + Filters                   │
+├─────────────────────────────────────────┤
+│  ┌───────┐  ┌───────┐  ┌───────┐       │
+│  │Metric │  │Metric │  │Metric │       │
+│  └───────┘  └───────┘  └───────┘       │
+├─────────────────────────────────────────┤
+│  Charts / Visualizations                 │
+├─────────────────────────────────────────┤
+│  Data Table                              │
+└─────────────────────────────────────────┘
+```
+
+**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.
+
+#### Form page
+Data entry, creation flows, configuration, settings with form fields.
+
+**Structure**
+
+```
+┌─────────────────────────────────────────┐
+│  Page Header + Back navigation           │
+├─────────────────────────────────────────┤
+│  ┌───────────────────────────────┐      │
+│  │  Form Section 1 (heading)     │      │
+│  │  [fields]                     │      │
+│  ├───────────────────────────────┤      │
+│  │  Form Section 2 (heading)     │      │
+│  │  [fields]                     │      │
+│  └───────────────────────────────┘      │
+├─────────────────────────────────────────┤
+│  Sticky footer: [Cancel]  [Save action] │
+└─────────────────────────────────────────┘
+```
+
+**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.
+
+#### Detail page
+
+Viewing a single record: report details, user profile, item information with related data.
+
+**Structure**
+
+```
+┌─────────────────────────────────────────┐
+│  Breadcrumb: Reports > Q2 Summary        │
+├─────────────────────────────────────────┤
+│  Record Header [Title, status, actions]  │
+├─────────────────────────────────────────┤
+│  ┌─────────────────┬───────────────┐    │
+│  │  Main Content    │  Sidebar      │    │
+│  │  (2/3 width)     │  (1/3 width)  │    │
+│  └─────────────────┴───────────────┘    │
+└─────────────────────────────────────────┘
+```
+
+**Responsive behavior**
+Desktop: Two-column (grid-cols-3, main span-2, sidebar span-1).
+Tablet: Sidebar below main content.
+Mobile: Single column. Sidebar collapses.
+
+
+#### Settings page
+App preferences, account settings, notification config.
+
+**Structure**
+
+```
+┌─────────────────────────────────────────┐
+│  Page Header: Settings                   │
+├───────────┬─────────────────────────────┤
+│  Settings │  Section Content            │
+│   Nav     │  [Form fields / toggles]    │
+└───────────┴─────────────────────────────┘
+```
+
+**Responsive behavior**
+Desktop: Left nav + content area.
+Tablet: Top tabs replacing left nav.
+Mobile: Category list → tap opens section full-screen.
+
+#### Split screen
+Comparison views, editor + preview, master-detail with equal emphasis on both sides.
+
+**Structure**
+
+```
+┌─────────────────────┬─────────────────────┐
+│                     │                     │
+│   Panel Left        │   Panel Right       │
+│   (1/2 width)       │   (1/2 width)       │
+│                     │                     │
+└─────────────────────┴─────────────────────┘
+```
+
+**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.
+
+
+#### Three panel
+Navigation + content + properties panel. IDE-style layouts. Complex editing workflows with context panels.
+
+**Structure**
+
+```
+┌──────────┬───────────────────┬──────────┐
+│          │                   │          │
+│  Nav/    │   Main Content    │  Props/  │
+│  Tree    │   (flexible)      │  Detail  │
+│  (fixed) │                   │  (fixed) │
+│          │                   │          │
+└──────────┴───────────────────┴──────────┘
+```
+
+**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.
+
+#### List page
+Browsing collections — reports, users, assets, items. The most common page type in data-heavy applications.
+
+
+**Structure**
+
+```
+┌──────────────────────────────────────────┐
+│  Page Header [Title]    [Create button]  │
+├──────────────────────────────────────────┤
+│  Filters toolbar  [Search] [Filters]     │
+├──────────────────────────────────────────┤
+│  Table / List                            │
+│  (with empty state when no data)         │
+├──────────────────────────────────────────┤
+│  Pagination                              │
+└──────────────────────────────────────────┘
+```
+
+**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.
+
+#### Wizard
+Multi-step creation flows, onboarding, configuration wizards, setup processes.
+
+
+**Structure**
+
+```
+┌──────────────────────────────────────────┐
+│  Step indicator (1 — 2 — 3 — 4)         │
+├──────────────────────────────────────────┤
+│                                          │
+│   Step Content Area                      │
+│   (centered, max-w-2xl)                  │
+│                                          │
+├──────────────────────────────────────────┤
+│  [Back]                    [Next/Submit] │
+└──────────────────────────────────────────┘
+```
+
+**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.
 
-**Aura components:** `Tooltip`, `Popover`, `HelperText`, `HoverCard`
+### Size and dimensions
 
-**Rules**
+Aura aligns to a **`{spacing.base}` base grid**. Spacing in components follows **Tailwind spacing** (`p-*`, `gap-*`, `m-*`): one unit = **`{spacing.base}`** unless overridden. Common steps:
+
+| Name | Token           | Tailwind | Typical use                      |
+| ---- | --------------- | -------- | -------------------------------- |
+| xs   | `{spacing.xs}`  | `1`      | Tight gaps, icon padding         |
+| sm   | `{spacing.sm}`  | `2`      | Inline controls, compact padding |
+| md   | `{spacing.md}`  | `3`      | Card / popover internal padding  |
+| lg   | `{spacing.lg}`  | `4`      | Related groups                   |
+| xl   | `{spacing.xl}`  | `5`      | Sections                         |
+| 2xl  | `{spacing.2xl}` | `6`      | Page regions                     |
+| 3xl  | `{spacing.3xl}` | `8`      | Large layout gaps                |
+
+Layout helpers in theme: `--container-2xl` (`{spacing.container-2xl}`), `--container-8xl` (`{spacing.container-8xl}`), `--message-content-max-width` (80% for chat content).
+
+### Width and max content
+
+Aura adjusts Tailwind **container** breakpoints where the default scale is too wide or too narrow for data-dense product surfaces:
+
+| Token             | Value                     | Role                                                                                                                                                                        |
+| ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--container-2xl` | `{spacing.container-2xl}` | Narrower than Tailwind’s default `2xl` container — useful outer bound for regions; **body copy** inside can still follow the **`{spacing.prose-max}`** reading rule above   |
+| `--container-8xl` | `{spacing.container-8xl}` | Wide upper bound for dashboards and full-bleed marketing rows                                                                                                               |
+
+Prefer **`max-w-*`** (and other width utilities) tied to the theme over ad-hoc pixel `max-width` on wrappers. **Global frame** width (host chrome) is defined by the **host application**; **inside** the frame, combine these tokens with responsive utilities so regions reflow predictably.
+
+### Specialized variables
+
+| Variable                      | Value                                           | Use                                                                             |
+| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
+| `--message-content-max-width` | `80%`                                           | Primary column for chat / assistant **Message** content in wide threads         |
+| `--drawer-max-height`         | `80vh`                                          | Maximum height for top/bottom drawer-style panels when the host implements them |
+| `--alert-icon-width`          | `calc(var(--spacing) * 4)` (typically **16px**) | Fixed icon column in the **Alert** layout so titles and descriptions align      |
+
+### Regional spacing
+
+- **Must** use the **spacing scale** for padding, margin, and `gap` between regions (`gap-*`, `p-*`, `m-*`) — see **Layout → Size and dimensions**.
+- **Should** keep major block **padding** and **gap** on **`{spacing.base}`** multiples so control heights, radii, and typography line up visually.
+- **Should** group related regions in **Card** (and **Separator** when two unrelated groups share a container) before mixing unrelated actions into the same band — see [Layout and hierarchy](#6-layout-and-hierarchy).
+- **Avoid** one-off pixel gutters that ignore the scale unless matching a fixed graphic asset.
+
+### Responsive behavior
+
+- **Should** move secondary work into **Dialog** or a shell **Drawer** on narrow widths instead of compressing multi-column chrome.
+- **Avoid** single-breakpoint layouts tuned only to a static design frame — use breakpoints, wrapping, and flexible sizing utilities where content must grow and shrink.
+
+### Shell vs content
 
-- **Must** put **Tooltip** on icon-only **Button**s with no visible label.
-- **Must** use **HelperText** under fields for format and constraints **before** error.
-- **Should** use **Popover** / **HoverCard** when help needs paragraphs or links.
-- **Avoid** **Tooltip** as the **only** place for information users must have on touch-first flows.
+**Global chrome** (workspace switcher, app-level navigation) is implemented by the **host application shell**, not the Aura component library. **Must** still theme that chrome with Aura **tokens** so shell and in-app surfaces feel continuous. **In-app content** should rely on Aura primitives (**Card**, **Banner**, **Dialog**, forms) plus the width and spacing rules above.
 
 ---
 
-### 3. Progressive disclosure
+## Elevation & Depth
 
-Introduce complexity only when needed; default views **should** stay scannable.
+### Shadows
 
-#### 3.1 Collapsible content
+`--effect-shadow-sm` through `--effect-shadow-xl` are **alpha blacks** tuned per theme. Tailwind shadow utilities compose layered stacks from these tokens:
 
-**Applies when:** Secondary detail, advanced settings, or optional blocks.
+| Tailwind shadow  | Built from `--effect-shadow-*` | Light (α)   | Dark (α)    | Use (per theme comments in CSS)                    |
+| ---------------- | ------------------------------ | ----------- | ----------- | -------------------------------------------------- |
+| `shadow-sm`      | `--effect-shadow-sm`           | 0.04        | 0.2         | Tooltips, small floating containers                |
+| `shadow-default` | md + sm layers                 | 0.05 + 0.04 | 0.302 + 0.2 | Menus, popovers, hover cards                       |
+| `shadow-md`      | lg + md layers                 | 0.06 + 0.05 | 0.4 + 0.302 | Sonner toasts, temporary elevated elements         |
+| `shadow-lg`      | xl + lg layers                 | 0.10 + 0.06 | 0.6 + 0.4   | Modals / dialogs **without** full backdrop overlay |
+| `shadow-xl`      | xl + lg layers                 | 0.10 + 0.06 | 0.6 + 0.4   | Modals / dialogs **with** backdrop overlay         |
 
-**Aura components:** `Accordion`, `Collapsible`, `Dialog`, `Popover`  
-**App:** `Sheet`, `Drawer` where the shell provides them — still use Aura tokens
+Exact pixel stacks are defined in the theme CSS alongside `--shadow-sm` … `--shadow-xl`.
 
-**Rules**
+### Focus rings
+
+Shadow-based (not `outline`) for consistent rendering:
 
-- **Must** use **Accordion** for stacked, independent sections (FAQ, settings groups).
-- **Must** use **Collapsible** for a single inline expandable block.
-- **Must** use **Drawer** / **Sheet** (shell) for edge panels or lightweight overlays that should not replace the whole page; otherwise **Dialog** for modal tasks.
-- **Should** default **Accordion** / **Collapsible** to collapsed unless the section is the main purpose of the view.
-- **Avoid** nesting **Accordion** more than one level.
+| Token                             | Composition                                                                                      | Use                                   |
+| --------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------- |
+| `--shadow-focus-ring`             | `0 0 0 1px var(--ring)` (`{colors.ring}`), `0 0 0 3px var(--ring-muted)` (`{colors.ring-muted}`) | Default focus on interactive controls |
+| `--shadow-focus-ring-destructive` | `0 0 0 1px var(--ring-destructive), 0 0 0 3px var(--ring-destructive-muted)`                     | Destructive / invalid focus           |
 
-#### 3.2 Multi-step flows
+### Opacity
 
-**Applies when:** Three or more steps or grouped data entry.
+| Token / concept                                  | Value                    | Use                               |
+| ------------------------------------------------ | ------------------------ | --------------------------------- |
+| `--opacity-10` … `--opacity-80` (+ `*-inverted`) | rgba steps               | Overlays, glass effects           |
+| Overlay scrim                                    | via `overlay-background` | Modal backdrop (see color tables) |
+| Chart fills                                      | `chart-*-color-*`        | See **Chart tokens**              |
 
-**Aura components:** `Dialog`, `Progress`, `Button`, `Separator`
+---
 
-**Rules**
+## Shapes
 
-- **Must** split into discrete steps with visible progress (step label, **Progress**, or stepper UI).
-- **Must** let users return to earlier steps unless that causes data loss.
-- **Avoid** multiple irreversible **primary** decisions in one step.
+### Corner radius
 
-#### 3.3 Contextual menus and secondary actions
+Defined in the theme. Default interactive radius in components is often **`rounded-lg`** (`{rounded.lg}`) for buttons/inputs; cards and overlays use **`rounded-lg`**–**`rounded-xl`** (`{rounded.lg}`–`{rounded.xl}`).
 
-**Applies when:** Per-row or per-object actions should stay out of the default chrome.
+| CSS variable               | Token            | Use                                                            |
+| -------------------------- | ---------------- | -------------------------------------------------------------- |
+| `--radius-none`            | `{rounded.none}` | Dividers, full-bleed                                           |
+| `--radius-xs`              | `{rounded.xs}`   | Tight inner chrome                                             |
+| `--radius-sm`              | `{rounded.sm}`   | Small controls, badges                                         |
+| `--radius-md` / `--radius` | `{rounded.md}`   | Maps to `rounded-md` — shared default in theme                 |
+| `--radius-lg`              | `{rounded.lg}`   | **Default** for many controls (Button, Input) via `rounded-lg` |
+| `--radius-xl`              | `{rounded.xl}`   | Dialogs, large cards, popovers                                 |
+| `--radius-2xl`             | `{rounded.2xl}`  | Extra-large surfaces                                           |
+| `--radius-3xl`             | `{rounded.3xl}`  | Marketing / hero panels                                        |
+| `--radius-4xl`             | `{rounded.4xl}`  | Largest marketing rounding                                     |
+| `--radius-full`            | `{rounded.full}` | Pills, avatars                                                 |
 
-**Aura components:** `DropdownMenu`, `Button` (kebab trigger), `ButtonGroup`  
-**App:** `ContextMenu` — same grouping and token rules
+### Borders
+
+Aura is visually **flat**; surfaces, spacing, and typography do most structure. Add borders only when separation or affordance needs extra clarity.
 
 **Rules**
 
-- **Must** use **DropdownMenu** for action lists anchored to a trigger (e.g. “More”).
-- **Must** scope menu items to the entity they affect — do not mix unrelated global actions into an item menu.
-- **Should** use **ButtonGroup** for a small persistent contextual action cluster.
-- **Avoid** long flat menus of **more than ~7** items without **DropdownMenuGroup** / separators / submenus.
+- **Must** treat borders/strokes as structural signals (inputs, table boundaries, critical separators), not decoration.
+- **Should** distinguish line items inside cards with spacing, alignment, and type hierarchy before adding dividers.
+- **Should** prefer one outer container boundary over many nested per-row outlines in the same card.
+- **Avoid** drawing borders around every item in a list/card just to create visual rhythm.
+- **Avoid** decorative outline stacks (`border` + `ring` + inset strokes) when no state or interaction meaning is conveyed.
+
+| Concept          | Value                            | Use                                                                    |
+| ---------------- | -------------------------------- | ---------------------------------------------------------------------- |
+| Default width    | **1px**                          | Tailwind `border` — tables, inputs, and occasional structural dividers |
+| Emphasized width | **2px**                          | Stronger separation or invalid/critical state emphasis                 |
+| Border color     | `border`, `border-emphasized`, … | See **Base — Borders and focus**                                       |
+| Style            | solid                            | Default                                                                |
 
 ---
 
-### 4. Error handling and prevention
+## Primitive components
 
-Errors **should** be prevented; when they happen, users **must** understand cause and recovery.
+### Primitive component heights
 
-#### 4.1 Destructive action prevention
+Heights are **not** always single CSS variables; primitives use Tailwind height utilities. Representative values from core components:
 
-**Applies when:** Delete, archive, reset, overwrite, disconnect, or other irreversible commits.
+| Size        | Component token               | Height         | Aura usage                                    |
+| ----------- | ----------------------------- | -------------- | --------------------------------------------- |
+| xs          | `{components.badge-xs}`       | 20px (`h-5`)   | Badge (default)                               |
+| sm          | `{components.button-sm}`      | 28px (`h-7`)   | Button `sm`, compact rows                     |
+| md          | `{components.button-primary}` | 36px (`h-9`)   | Button default, Input, Select, many menu rows |
+| lg          | `{components.button-lg}`      | 40px (`h-10`)  | Button `lg`                                   |
+| Icon button | sm / md / lg tokens           | 28 / 36 / 40px | `icon-sm` / default / `icon-lg`               |
 
-**Aura components:** `Dialog`, `Alert`, `Banner`, `Button` (`destructive`)  
-**App:** `AlertDialog` / confirm flow where supplied by shell
+**Topbar** height is **application-defined** (not a single Aura token). **Table / list row** density varies by product; menu and command patterns often use **`{components.button-primary.height}`** (`h-9`) rows.
 
-**Rules**
 
-- **Must** confirm high-impact destructive actions in a **Dialog** (or **AlertDialog**) **before** execution.
-- **Must** name what will be destroyed — not generic “Are you sure?”.
-- **Must** label the confirm action with a **specific verb** (“Delete report”), not “OK”.
-- **Should** use **Button** `variant="destructive"` for the confirming destructive action.
-- **Avoid** toast as the **only** safety net for irreversible work.
 
-#### 4.2 Form validation
+### Global primitive rules
 
-**Applies when:** Any `Input`, `Textarea`, `Select`, or similar field.
+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.
 
-**Aura components:** `Input`, `Textarea`, `Select`, `InputGroup`, `HelperText`, `Label`
+### Primitive guidance
 
-**Rules**
+Sections are in alphabetical order. For each component, the Storybook link is the primary reference for variants and props; the docs link is the primary reference for usage and design guidance.
 
-- **Must** show errors inline with **HelperText** (or documented `aria-invalid` pattern) on the affected field.
-- **Must** say what is wrong and how to fix it — not only “Invalid”.
-- **Must** gate “next step” until blocking errors are resolved.
-- **Must** use component **`error`** / invalid props where **Input** / **Select** expose them — do not invent parallel red borders.
-- **Should** validate on **blur** when the value is incomplete mid-typing.
-- **Should** validate live when rules are cheap (length, pattern).
-- **Avoid** revealing every error only on final submit with no prior field feedback.
+#### Storybook reference
+Anytime you need to reference a component in Storybook, use the following URL and replace the slug with the component's Storybook slug: https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-{storybook-slug}--docs
 
-#### 4.3 Auto-save and data loss prevention
+#### Docs reference 
+Anytime you need to reference a component in docs, use the following URL and replace the slug with the component's doc slug: https://docs.cognite.com/aura-design-system/primitives/{docs-slug}
 
-**Applies when:** Edits would be lost on navigation or timeout.
+#### Accordion
 
-**Aura components:** `Banner`, `Badge`, `Dialog`  
-**App:** Sonner for “Saved” pulse
+**Storybook-slug:** accordion
+**Docs-slug:** accordion
 
-**Rules**
+**Definition**
+Accordion reveals and hides grouped content sections to reduce cognitive load and page density.
 
-- **Must** auto-save when feasible; when not, show persistent unsaved state (**Badge** / **Banner** / shell slot).
-- **Must** warn before discard navigation (**Dialog** confirm) when changes are unsaved.
-- **Should** show “Saved” / timestamp feedback (toast or inline) after auto-save.
+**Use when**
+- Grouping settings in side/config panels.
+- Breaking long forms into manageable sections.
+- Organizing docs/FAQ/help content.
+- Showing nested information hierarchies.
 
-#### 4.4 Recovery and undo
+**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.
 
-**Applies when:** User mutates or removes content.
+**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.
 
-**Aura components:** `Dialog`  
-**App:** Sonner with undo
+**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.
 
-**Rules**
+**Often used with**
+- `Separator`, section headings, and form controls inside panel content.
 
-- **Should** provide **Undo** in toast for reversible destructive actions.
-- **Must** keep undo inside the same session without deep navigation gymnastics.
-- **Avoid** relying on undo alone for high-stakes actions — still confirm where appropriate (§4.1).
+#### Action Toolbar
 
----
+**Storybook-slug:** actiontoolbar
+**Docs-slug:** action-toolbar
 
-### 5. Enabling power users
+**Definition**
+Action toolbar is a transient bottom-aligned action row that appears when users select items (for example in data-heavy views).
 
-Experts **should** move faster without harming first-time clarity.
+**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.
 
-#### 5.1 Keyboard shortcuts
+**Use something else when**
+- Actions are page-level and do not require selection first (use a standard toolbar/page actions).
 
-**Applies when:** High-frequency actions (save, search, command palette, AI trigger).
+**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.
 
-**Aura components:** `Command`, `CommandShortcut`, `DropdownMenuShortcut`, `Tooltip`
+**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.
 
-**Rules**
+**Often used with**
+- Selection patterns in data views, `Checkbox`, `Button`, `Menu`, and `Tooltip` for icon-only actions.
 
-- **Should** ship shortcuts for the top few actions per surface.
-- **Must** render shortcut glyphs with **CommandShortcut** / **DropdownMenuShortcut** — not bespoke styled `<kbd>`.
-- **Should** align with platform norms (e.g. ⌘/Ctrl+S, ⌘/Ctrl+K) where they do not fight the browser.
-- **Avoid** stealing OS or browser reserved shortcuts.
+#### Alert
 
-#### 5.2 Bulk actions
+**Storybook-slug:** alert
+**Docs-slug:** alert
 
-**Applies when:** Lists or tables with repeated items.
+**Definition**
+Alert communicates contextual, medium-emphasis information inside page/task flow. It is not a blocking modal.
 
-**Aura components:** `DropdownMenuCheckboxItem`, `Button`, `ButtonGroup`, `Badge`, `Banner`  
-**App:** table selection, **ActionToolbar** pattern
+**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.
 
-**Rules**
+**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.
 
-- **Must** support multi-select in list/table UIs that offer per-row destructive or batch actions (shell table + **DropdownMenuCheckboxItem** or equivalent).
-- **Must** show bulk **ButtonGroup** / toolbar only when selection is non-empty; show selected count.
-- **Should** support select-all for the current page or filter.
-- **Avoid** bulk destructive work without **Dialog** confirmation (§4.1).
+**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.
 
-#### 5.3 Onboarding and learnability
+**Behavior**
+- Inline with page flow (not full-screen blocking).
+- Dismissal removes/hides alert per variant.
+- Action path should be clear and minimal.
 
-**Applies when:** First-use, empty data, or role-gated features.
+**Often used with**
+- `Button` for direct resolution actions.
 
-**Aura components:** `Card`, `Button`, `Tooltip`, `HelperText`, `Banner`, `Message`
+#### Alert Dialog
 
-**Rules**
+**Docs-slug:** alert-dialog
 
-- **Must** use a structured empty pattern (**Card** + explanation + primary **Button**), not a blank canvas.
-- **Should** explain what the view is for and how to populate it.
-- **Should** use **HelperText** / **Tooltip** for compact role- or context-specific hints.
-- **Avoid** using **Banner** for long onboarding tours if **Banner** is already the channel for critical system alerts — mixed priority dilutes both.
+**Definition**
+Short, focused confirmation or acknowledgment that interrupts the user for a clear binary or limited choice.
 
----
+**Use when**
+- Confirming destructive or irreversible actions.
+- Blocking until the user chooses from a small set of options.
 
-### 6. Layout and hierarchy
+**Use something else when**
+- Inline persistence is enough (`Alert`).
+- The flow requires a form or multi-field input (`Dialog`).
+- A quick acknowledgment is sufficient (`Sonner Toast`).
 
-Information **must** be scannable and oriented before action.
+**Often used with**
+- `Button` (destructive variant) as the trigger.
 
-#### 6.1 Grouping and proximity
+#### Avatar
 
-**Applies when:** Forms, settings, detail layouts.
+**Storybook-slug:** avatar
+**Docs-slug:** avatar
 
-**Aura components:** `Card`, `InputGroup`, `Accordion`, `Separator`, `Label`
+**Definition**
+Avatar visually represents a user, team, or concept and helps recognition in collaborative UI.
 
-**Rules**
+**Use when**
+- Showing people in comments, chat, sharing, or collaborators.
+- Representing accounts, teams, or organizations.
+- Displaying AI/agent identities in conversational interfaces.
 
-- **Must** group related fields in one **Card** or labeled section.
-- **Must** use **Separator** between unrelated groups in the same container.
-- **Must** use **InputGroup** when addons and input share one logical value.
-- **Should** use **Accordion** for distinct sub-topics in long settings.
-- **Avoid** unrelated primary actions in the same **Card** as sensitive fields without hierarchy.
+**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.
 
-#### 6.2 Persistent actions and navigation
+**Often used with**
+- `Badge`, `Tooltip`, `Menu`.
 
-**Applies when:** Global vs page-local actions.
+#### Badge
 
-**Aura components:** `Button`, `DropdownMenu`  
-**Fusion shell:** `Topbar`, `Tabs`, `SegmentedControl` — follow shell **SKILL** / **RULES** where your repo defines them
+**Storybook-slug:** badge
+**Docs-slug:** badge
 
-**Rules**
+**Definition**
+Compact label for status, category, or metadata.
 
-- **Must** keep **one** clear **primary** CTA per view in content; put global-only actions in shell chrome, page actions in page header/toolbar.
-- **Must** use shell **Tabs** / **SegmentedControl** for primary view switching when the product uses that pattern — do not duplicate the same navigation inline without reason.
-- **Avoid** duplicating shell navigation inside content.
+**Use when**
+- Surfacing state at a glance (for example active, draft, error).
+- Tagging items without taking primary focus from the page.
 
-#### 6.3 Visual hierarchy
+**Use something else when**
+- The message needs explanation or recovery steps (consider `Alert` or inline text).
+- You need a primary action (use `Button`).
 
-**Applies when:** Any view with competing focal points.
+**Often used with**
+- `Avatar`, tables and lists, filter chips.
 
-**Aura components:** `Button`, `Badge`, `Alert`, `Label`
+#### Banner
 
-**Rules**
+**Storybook-slug:** banner
+**Docs-slug:** banner-alert
 
-- **Must** limit **primary** (`default` **Button**) to one obvious main action per view.
-- **Must** use **semantic tokens** for status (**Tokens** § Semantic) — no arbitrary hex.
-- **Must not** use **Button** `destructive` for non-destructive actions.
-- **Should** use type scale, weight, and spacing (**Tokens** § Typography / spacing) to lead attention.
+**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.
 
-#### 6.4 Responsive behaviour
+**Use when**
+- Announcing environment or product state (maintenance, trial, feature preview).
+- Page-wide outcomes that should stay visible while the user continues.
 
-**Applies when:** Viewport spans tablet / desktop / embedded shell widths.
+**Use something else when**
+- Task-specific guidance inside a flow (`Alert`).
+- Brief confirmation after an action (`Sonner Toast`).
 
-**Aura components:** `Card`, `Dialog`, `DropdownMenu`  
-**Fusion shell:** `Topbar` overflow behavior
+#### Breadcrumb
 
-**Rules**
+**Storybook-slug:** breadcrumb
+**Docs-slug:** breadcrumbs
 
-- **Should** verify layouts at common widths (e.g. 768 / 1024 / 1440px) when shipping responsive surfaces.
-- **Should** prefer **Dialog** / shell **Drawer** for secondary tasks on narrow viewports instead of cramming wide panels.
-- **Avoid** hard-coded pixel widths that bypass Tailwind and Aura layout tokens.
+**Definition**
+Hierarchical navigation aid that shows users their current location within the product's structure. Location-based, not path-based.
 
----
+**Use when**
+- Users need to return to a parent page.
+- Users need clarity on their current position in the product hierarchy.
+- Quick access to ancestor pages is useful.
 
-### 7. Accessibility and inclusive design
+**Use something else when**
+- The page structure is flat — there is no hierarchy to show.
+- Users are switching between same-level content (use `Tabs` or `Segmented Control`).
 
-Aura targets **WCAG AA** for primitives — usage must preserve that.
+**Dos and don'ts**
+- Do not make the current breadcrumb clickable.
+- Do not pair with a back button.
+- Do not wrap breadcrumb labels to multiple lines; truncate and use `Tooltip` for full text.
+- Show only one breadcrumb trail per page.
 
-#### 7.1 Keyboard accessibility
+**Behavior**
+- All links except the current page are interactive (Tab, Shift+Tab, Enter).
+- When space is limited, condense middle items into an overflow menu showing the first and last two links.
+- The active page link always remains visible.
 
-**Applies when:** Any interactive **Aura** component or custom control.
+**Often used with**
+- `Tooltip` for truncated labels, `Menu` for overflow segments, `Topbar`.
 
-**Rules**
+#### Button
 
-- **Must** complete every task path with keyboard alone — do not break Radix / Base focus traps or `Tab` order.
-- **Must** keep a visible **focus** treatment per **Interaction states** — never `outline-none` / `ring-0` **without** Aura’s `shadow-focus-ring` equivalent.
-- **Must** expose **DropdownMenu**, **Dialog**, and other overlays via keyboard, not pointer-only triggers.
-- **Avoid** critical behavior on `onMouseEnter` / `onMouseLeave` without a keyboard-accessible path.
+**Storybook-slug:** button
+**Docs-slug:** button
 
-#### 7.2 Color contrast and readability
+**Definition**
+Primary control for discrete actions.
 
-**Applies when:** Text, icons, or controls on colored surfaces.
+**Use when**
+- Committing, navigating a clear next step, or triggering destructive work (with confirmation pattern).
 
-**Rules**
+**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 `./DESIGN.md`).
+- Icon-only actions need an accessible name (`aria-label`).
 
-- **Must** use **Tokens** for color — no stray hex / arbitrary Tailwind color literals.
-- **Must not** override colors in ways that drop below **4.5:1** for normal text (or **3:1** for large text) against its background.
-- **Must not** encode meaning with **color alone** — pair with icon, **HelperText**, or label.
-- **Avoid** `muted-foreground` for text the user must read to complete a task.
+**Often used with**
+- `Button Group`, `Dialog`, forms.
 
-#### 7.3 ARIA and semantic markup
+#### Button Group
 
-**Applies when:** Composing Aura primitives or wrapping native elements.
+**Storybook-slug:** button-group
 
-**Rules**
+**Definition**
+Visually joins related buttons into a connected row, clarifying that the actions belong to the same context.
 
-- **Must** use each primitive for its intended role — not **Button** as navigation that should be `<a>`.
-- **Must** name icon-only controls (`aria-label` / `aria-labelledby`) and supply **Tooltip** where design hides text.
-- **Should** use landmark elements (`main`, `nav`, `header`) at page level alongside Aura layout.
-- **Avoid** stripping default ARIA from primitives without an equivalent.
+**Use when**
+- Two or more actions are closely related and operate on the same target (for example, a split-button or segmented action row).
+- Conserving horizontal space compared to individually spaced buttons.
 
-#### 7.4 Touch and click targets
+**Use something else when**
+- Actions are unrelated and should not appear grouped.
+- You need more than a small set of actions (consider `Toolbar` or `Dropdown Menu`).
 
-**Applies when:** Touch or motor accessibility matters.
+**Often used with**
+- `Button`, `Tooltip` for icon-only variants.
 
-**Rules**
+#### Card
 
-- **Must** meet **WCAG 2.5** target-size expectations — do not ship tappable UI smaller than the primitive’s documented interactive box without an invisible hit-area expansion.
-- **Should** keep comfortable spacing between adjacent tap targets (use spacing tokens, not zero gap).
-- **Avoid** sub-24px icon hit zones without expansion in dense tables.
+**Storybook-slug:** card
+**Docs-slug:** card
 
-### Common pitfalls (agent guidance)
+**Definition**
+A structural container with optional header, body, and footer slots for displaying data artifacts, widgets, or media. The Card with Count variant adds a numeric indicator to the header.
 
-These are the most frequent mistakes when generating or modifying Aura-based UI. Avoid all of them.
+**Use when**
+- Presenting charts, visualizations, or data widgets.
+- Building grids of comparable items where list/grid view toggling is needed.
+- Displaying media content (images, videos).
 
-**Raw hex or hardcoded colors**
+**Use something else when**
+- You just need visual separation between sections — use `Separator` and spacing instead.
+- You are comparing dense metadata across rows — use `Table` or a data grid instead.
 
-Do not write `#486AED`, `rgb(...)`, or arbitrary Tailwind color literals like `text-blue-600`. Always use a semantic, base, or chart token. If no token fits the intent, choose the closest documented base token. Using raw values breaks dark mode and makes token-level theming impossible.
+**Dos and don'ts**
+- Cards are structural containers only; interactive elements (`Button`, `Checkbox`) go inside the body or actions area.
+- Exception: the entire card can serve as a single focusable target when it acts as a link or selection item.
 
-**Overriding style tokens or component styles**
+**Often used with**
+- `Button`, `Badge`, `Avatar`, `Separator`, charts, lists, or form fields in the body.
 
-Do not add `style={{ color: '...' }}`, override Tailwind utilities that shadow Aura tokens, or patch component internals with ad-hoc CSS. The ESLint `className-override` rule will flag LLM-generated style overrides for this reason. If a component does not support a needed variant, raise it — do not work around it.
+#### Checkbox
 
-**Duplicate or parallel navigation**
+**Storybook-slug:** checkbox
+**Docs-slug:** checkbox
 
-Every app has exactly one Topbar. Do not render a second header, a sidebar for primary navigation, or duplicate breadcrumbs outside the Topbar. Page-specific sub-navigation belongs in the content area.
+**Definition**
+Enables users to independently select one or multiple options. Can appear standalone or within menus, tree views, tables, or cards.
 
-**Overly dense card layouts**
+**Use when**
+- Multiple independent selections are required (for example, column visibility in a table).
+- Enabling or disabling settings where changes do not take immediate effect.
+- Confirming agreement before an action (for example, delete verification).
 
-Do not stack unrelated actions or data types in a single Card, and do not reduce spacing below the 4 px grid scale. Cards should group one related concern with clear hierarchy: title, supporting content, one primary action.
+**Use something else when**
+- Only one option can be selected at a time (use `Radio`).
+- Options are not displayed simultaneously (use `Select`).
+- You need an immediate on/off toggle (use `Switch`).
 
-**Mixing chart, decorative, and semantic color tokens**
+**Dos and don'ts**
+- Do provide a label for every checkbox.
+- Do implement indeterminate states for partial group selection.
+- Do not pre-select checkboxes automatically.
+- Do not use a single checkbox unless it is confirming agreement.
+- Do not use card variants for long option lists.
 
-`chart-*` is for data series and plot areas only. `decorative-*` is for non-data differentiation (metric tile accents, avatars). `semantic-*` (`info-*`, `success-*`, etc.) is for operational status and feedback. Do not use chart or decorative tokens to imply system health or validation state.
+**Behavior**
+- Space key toggles focused checkboxes.
+- Indeterminate state is set programmatically, not by user interaction.
+- Parent-child relationships follow selection cascading rules.
 
-**Icon-only controls without accessible names**
+**Often used with**
+- `Label`, helper text for groups, `Card` variant for options needing descriptions.
 
-Every icon-only Button must have `aria-label` and a `Tooltip`. Do not rely on visual context alone.
+#### Collapsible
 
-**Disabled primary CTA with no resolution path**
+**Storybook-slug:** collapsible
+**Docs-slug:** collapsible
 
-Do not disable the main action without showing the user how to re-enable it. Pair a disabled CTA with a `HelperText` or `Tooltip` explaining the blocker.
+**Definition**
+A single inline expandable block that toggles content visibility. Designed for one independent optional section, not multiple stacked areas.
 
----
+**Use when**
+- Showing one optional or secondary block of content (for example, AI reasoning, advanced settings, a preview).
+- Content is useful but not essential to the primary task.
 
-### For `llms.txt` / agent exports
+**Use something else when**
+- You have multiple expandable sections (use `Accordion`).
+- Content is essential — show it by default.
+- Users are navigating or filtering (use `Tabs` or filter controls).
 
-When splitting or stripping this doc for agents:
+**Dos and don'ts**
+- Do default to collapsed unless the collapsible content is the main purpose of the view.
+- Do keep the trigger label descriptive — it should communicate what's inside.
+- Do not nest collapsibles; use `Accordion` for layered disclosure.
+- Do not hide errors or required information.
 
-- Drop decorative emoji or ornamental Unicode if any appear in future edits.
-- Keep **Must** / **Should** / **Avoid** / **must not** wording — severity is the routing signal.
-- Keep each **Applies when:** line — it tells the agent which subsection fires.
-- Keep **Aura components:** lines aligned with [`src/components/index.ts`](./src/components/index.ts) exports (public entry for `@cognite/aura/components`); treat **App / Fusion shell** lines as integration responsibilities, not as Aura package exports.
-- Preserve links: [Aura Storybook](https://storybook-aura-23638.fusion-preview.preview.cogniteapp.com); [Aura documentation](https://docs.cognite.com/aura-design-system/get-started) for published guides. Fetch current prop names from Storybook or source before codegen.
-- If you split by section (§1–§7), repeat the **Severity** and **Scope** bullets at the top of each file so standalone chunks stay interpretable.
-- Preserve **[Content](#content)** for action verbs, date/time rules, and tone; agents generating strings should follow it alongside **Heuristics**.
+**Behavior**
+- One trigger controls one associated region with optional animation.
+- State changes must be exposed to assistive technology.
 
----
+**Often used with**
+- `Separator` when stacking multiple collapsible regions on a page.
 
-## Tokens
+#### Combobox
 
-**What this section is:** The token reference for Aura — color (base, semantic, decorative), typography, spacing, radii, borders, and effects. Consume tokens via **CSS variables** (e.g. `var(--background)`) or **Tailwind theme** utilities (e.g. `bg-background`, `text-muted-foreground`, `shadow-default`, `rounded-lg`). Do not hardcode hex, font sizes, or shadow strings in product UI when a token exists.
+**Storybook-slug:** combobox
+**Docs-slug:** combobox
 
-**Theming:** Aura supports **light** (`:root`) and **dark** (`.dark` / `prefers-color-scheme: dark` per library setup). Semantic and base tokens **resolve to different ramps** per theme. **`background-fixed-dark`**, **`background-fixed-light`**, **`foreground-fixed-*`**, and related **fixed** tokens keep the same appearance in both themes (persistent chrome such as sidebars). Always verify contrast in both themes in Storybook or the consuming app.
+**Definition**
+A searchable select input that filters options as users type. Supports single and multi-select modes with optional ability to add new items.
 
-**Agents:** Reference tokens by **full CSS name** or Tailwind token. Never use raw `hex` / `rgb` / `hsl` in product code. If no semantic token fits, use a documented **base** token; **step colors** on ramps (`mountain/*`, `fjord/*`, …) are only for custom, branding, or marketing surfaces where no semantic token exists yet.
+**Use when**
+- More than approximately 12 options where search efficiency beats scrolling.
+- Users have a general sense of what they're looking for (country, asset name, tag).
+- Users need to add new options not in the predefined list.
 
-### Common Tailwind mappings
+**Use something else when**
+- Fewer than ~12 options: prefer `Select`, `Radio`, or `Checkbox`.
+- Users are unfamiliar with available options and need a visible list.
+- Very large datasets risk performance lag: use a data grid with filtering.
+- Pure text entry without selection (use `Input` or `Textarea`).
 
-Tables in this section use **CSS role names** (e.g. `link-foreground`, `card-background`). Aura registers each role as `--color-{role}` in `@theme inline` in [`src/colors.css`](./src/colors.css); Tailwind v4 exposes utilities **`text-{role}`**, **`bg-{role}`**, **`border-{role}`** (and **`ring-{role}`** / **`shadow-*`** where documented in **Effects**). Prefer these utilities in components over raw `var(--…)` when the theme wire-up matches.
-
-| Role (suffix after `text-` / `bg-` / `border-`) | Typical utilities | Notes |
-| :--- | :--- | :--- |
-| `background` | `bg-background` | Page base |
-| `foreground` | `text-foreground` | Primary text |
-| `muted-foreground` | `text-muted-foreground` | Tertiary copy |
-| `card-background` | `bg-card-background` | Cards (see **Card** component) |
-| `muted-background` | `bg-muted-background` | Static fills, inputs, secondary chrome |
-| `border` | `border-border` | Default strokes |
-| `link-foreground` | `text-link-foreground` | Text links |
-| `primary-background` | `bg-primary-background`, `text-foreground-on-primary` | Default **Button** (`variant="default"`) pattern |
-| `destructive-background` | `bg-destructive-background`, `text-destructive-foreground-on-critical` (on surface) | Destructive actions — pairings in **Semantic colors** |
-| `info-background`, `success-background`, … | `bg-info-background`, `text-info-foreground`, … | Full names match **Semantic colors** token columns |
-
-Semantic utilities use the **full token name** as the Tailwind segment (e.g. `bg-info-background`, not `bg-info`). For **charts**, utilities follow the **Chart tokens** names (`bg-chart-fjord-color-1`, `bg-chart-gridlines`, …). For exhaustive coverage, use [`src/colors.css`](./src/colors.css) or your IDE on `@cognite/aura`.
-
-Tables below list **approximate hex** resolved from [`src/colors.css`](./src/colors.css) at build time; the source of truth is the synced file (some entries are `rgba()`).
-
-### Color
-
-Aura groups color into **Base** (~80–90% of UI), **Semantic** (status and feedback, ~5–10%), and **Decorative** (accents and illustration, ~5–10%) so color carries **meaning** and stays calm.
-
-#### Base — Background
-
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `background` | `#FFFFFF` | `#191B1D` | Primary surface — lowest layer |
-| `alternate-background` | `#F9FAFA` | `#111213` | Distinct layer or block separate from `background` |
-| `card-background` | `#F9FAFA` | `#212426` | Cards without drop shadow on `background` / `alternate-background` |
-| `muted-background` | `#F1F2F3` | `#2D3134` | Static fills for controls, rows, segmented controls |
-| `primary-background` | `#212426` | `#F9FAFA` | Primary actions (default button); use sparingly |
-| `primary-background-hover` | `#40464A` | `#E4E6E8` | Hover on `primary-background` |
-| `secondary-background` | `#E4E6E8` | `#40464A` | Secondary actions, switch track |
-| `secondary-background-hover` | `#D4D7D9` | `#5E666D` | Hover on `secondary-background` |
-| `accent-background` | `#F1F2F3` | `#2D3134` | Neutral hover on `background` / `card-background` (e.g. tabs) |
-| `accent-background-strong` | `#E4E6E8` | `#40464A` | Neutral hover on `muted-background` / `active-muted-background` |
-| `highlight-background` | `#F1F2F3` | `#2D3134` | Focused / active fields (inputs, selects, comboboxes) |
-| `highlight-background-strong` | `#E4E6E8` | `#40464A` | Stronger focused / active field fill |
-| `active-background` | `#191B1D` | `#F9FAFA` | High-contrast “on” (switch, checkbox, radio) |
-| `active-background-hover` | `#2D3134` | `#F1F2F3` | Hover on `active-background` |
-| `active-muted-background` | `#F1F2F3` | `#2D3134` | Lower-contrast selected (e.g. tabs) |
-| `active-muted-background-hover` | `#E4E6E8` | `#40464A` | Hover on `active-muted-background` |
-| `popover-background` | `#FFFFFF` | `#212426` | Top-layer surfaces with shadow (dialogs, popovers) |
-| `raised-background` | `#2D3134` | `#40464A` | Tooltips, Sonner toasts — floats above page |
-| `disabled-background` | `#F1F2F3` | `#2D3134` | Disabled inputs and controls |
-| `overlay-background` | `#7C868E80` | `#7C868E80` | Scrim behind modals |
-| `background-fixed-dark` | `#212426` | `#212426` | Must stay **dark** in both themes |
-| `background-fixed-light` | `#FFFFFF` | `#FFFFFF` | Must stay **light** in both themes |
-| `accent-background-fixed-dark` | `#2D3134` | `#2D3134` | Persistent dark accent chrome (e.g. sidebar) |
-
-#### Base — Foreground
-
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `foreground` | `#191B1D` | `#F1F2F3` | Primary text and icons |
-| `secondary-foreground` | `#40464A` | `#D4D7D9` | Supporting text and icons |
-| `muted-foreground` | `#6D767E` | `#A5ABB1` | Tertiary / low emphasis |
-| `disabled-foreground` | `#D4D7D9` | `#5E666D` | Disabled text and icons |
-| `link-foreground` | `#486AED` | `#1742E7` | Text links |
-| `foreground-on-primary` | `#F1F2F3` | `#191B1D` | On `primary-background` |
-| `foreground-on-active` | `#F1F2F3` | `#191B1D` | On `active-background` |
-| `active-foreground` | `#191B1D` | `#F1F2F3` | On `active-muted-background` |
-| `foreground-fixed-dark` | `#191B1D` | `#191B1D` | Must stay dark in both themes |
-| `foreground-fixed-light` | `#FFFFFF` | `#FFFFFF` | Must stay light in both themes |
-| `foreground-secondary-fixed-dark` | `#40464A` | `#40464A` | Secondary copy, always dark |
-| `secondary-foreground-fixed-light` | `#D4D7D9` | `#D4D7D9` | Secondary copy, always light |
-| `muted-foreground-fixed-light` | `#BBC0C4` | `#BBC0C4` | Muted copy, always light |
-
-#### Base — Borders and focus
-
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `border` | `#E4E6E8` | `#2D3134` | Default strokes |
-| `border-emphasized` | `#D4D7D9` | `#40464A` | Stronger separation |
-| `border-on-dark` | `#2D3134` | `#2D3134` | Strokes on dark chrome (both themes) |
-| `border-active` | `#191B1D` | `#F9FAFA` | Active / toggled outlines |
-| `ring` | `#7081C7` | `#7081C7` | Focus ring outer (maps to `--shadow-focus-ring`) |
-| `ring-muted` | `#B5BEE2` | `#B5BEE2` | Focus ring inner companion |
+**Dos and don'ts**
+- Do group related options into categories.
+- Do position checkmarks right-aligned in menus.
+- Do not use for simple binary choices or small option sets.
+- Do not place icons or badges on the left side of menu items.
 
-Also generated: `ring-destructive`, `ring-destructive-muted` for destructive / invalid focus (see **Effects — Focus rings**).
+**Behavior**
+- Single-select closes immediately on selection.
+- Multi-select stays open until the user clicks outside, presses Escape, or Enter.
 
-#### Semantic colors
+**Often used with**
+- `Label`, helper text, `Badge`.
 
-Semantic tokens are **only** for status and system feedback (Alert, Banner, Sonner, badge status variants, validation). Do not use them as generic fills or decoration.
+#### Command
 
-Each family has **default** pairings (theme-switching surfaces) and **muted** pairings (blocks on **persistent dark chrome**). On muted surfaces, use the same `*-foreground-on-*` token names with the muted background; verify contrast in context.
+**Storybook-slug:** command
+**Docs-slug:** command
 
-**Info**
+**Definition**
+A keyboard-first search interface for discovering and executing actions, navigating pages, or looking up content application-wide. Typically activated via ⌘K / Ctrl+K and displayed inside a `Dialog` or `Popover`.
 
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `info-background` | `#D0D6ED` | `#B5BEE2` | Info surface |
-| `info-background-hover` | `#B5BEE2` | `#D0D6ED` | Hover on `info-background` |
-| `info-foreground` | `#4A5FB8` | `#9DA9D9` | Text near info context on standard surfaces |
-| `info-foreground-on-info` | `#32417F` | `#1A2242` | Text **on** `info-background` |
-| `info-muted-background` | `#F0F2F9` | `#2D3134` | Info tint on dark chrome |
-| *(pairing)* | — | — | On `info-muted-background`, use `info-foreground-on-info` for on-surface copy |
+**Use when**
+- Enabling keyboard-driven workflows across an entire application.
+- Providing power-user shortcuts to actions and destinations.
+- The application has too many actions or pages to surface in a standard nav.
 
-**Success**
+**Use something else when**
+- Filtering a specific list or dataset (use `Search`).
+- Selecting from known form options (use `Combobox` or `Select`).
+- Navigating between a small number of pages (use `Tabs` or nav links).
 
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `success-background` | `#BBF3D0` | `#8BDEAE` | Success surface |
-| `success-background-hover` | `#8BDEAE` | `#BBF3D0` | Hover on `success-background` |
-| `success-foreground` | `#1C984A` | `#24C45E` | Text near success on standard surfaces |
-| `success-foreground-on-success` | `#0F5026` | `#0A381C` | Text **on** `success-background` |
-| `success-muted-background` | `#DDF9E7` | `#2D3134` | Success on dark chrome |
-| *(pairing)* | — | — | On `success-muted-background`, use `success-foreground-on-success` |
+**Dos and don'ts**
+- Do organize results into logical categories.
+- Do use action-oriented labels ("Create asset," "Switch to dark mode").
+- Do display the keyboard shortcut on triggering elements.
+- Do surface frequently used items by default.
+- Do not use for general content search.
+- Do require confirmation steps for destructive actions.
 
-**Warning**
+**Behavior**
+- Keyboard-first interface presenting categorized, scannable action lists.
+- Shows loading indicators for async results and meaningful empty states.
 
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `warning-background` | `#FFE3A2` | `#FFE3A2` | Warning surface |
-| `warning-background-hover` | `#FFD062` | `#FFF1D0` | Hover on `warning-background` |
-| `warning-foreground` | `#C18800` | `#D8BF00` | Text near warning on standard surfaces |
-| `warning-foreground-on-warning` | `#755200` | `#5B4000` | Text **on** `warning-background` |
-| `warning-muted-background` | `#FFF1D0` | `#2D3134` | Warning on dark chrome |
+**Often used with**
+- `Dialog`, `Popover`, `Search`, `Empty State`.
 
-**Destructive**
+#### Count
 
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `destructive-background` | `#FCCAD2` | `#FAA9B7` | Error / destructive surface |
-| `destructive-background-hover` | `#FAA9B7` | `#FCCAD2` | Hover on `destructive-background` |
-| `destructive-foreground` | `#CB0B2C` | `#F65E78` | Text near destructive context on standard surfaces |
-| `destructive-foreground-on-critical` | `#8D081F` | `#8D081F` | Text **on** `destructive-background` |
-| `destructive-muted-background` | `#FDDEE4` | `#2D3134` | Destructive on dark chrome |
-| `destructive-muted-background-hover` | `#FCCAD2` | `#40464A` | Hover on `destructive-muted-background` |
+**Storybook-slug:** count
 
-**Neutral** (status: draft, archived — not “semantic calm” in the same sense as info/success)
+**Definition**
+A compact numeric indicator used to surface quantities inline — for example, unread messages, selected items, or totals attached to labels or tabs.
 
-| Token | Light (reference) | Dark (reference) | Use |
-| :--- | :--- | :--- | :--- |
-| `neutral-background` | `#E4E6E8` | `#D4D7D9` | Neutral status surface |
-| `neutral-background-hover` | `#D4D7D9` | `#E4E6E8` | Hover on `neutral-background` |
-| `neutral-foreground` | `#52595F` | `#A5ABB1` | Text near neutral status |
-| `neutral-foreground-on-neutral` | `#40464A` | `#2D3134` | Text **on** `neutral-background` |
-| `neutral-muted-background` | `#F1F2F3` | `#2D3134` | Neutral on dark chrome |
+**Use when**
+- Showing a quantity associated with a label, tab, or list item.
+- Surfacing unread counts or selection totals without taking primary focus.
 
-**Naming:** CSS uses full role names (`info-foreground-on-info`, `neutral-foreground-on-neutral`, `destructive-foreground-on-critical`). There is no shortened alias in the theme.
+**Use something else when**
+- The value represents status or category rather than a quantity (use `Badge`).
 
-#### Decorative colors
+**Often used with**
+- `Tabs`, `Badge`, `Label`, list items.
 
-For **small accents** (badges, avatars, empty states) where color differentiates but does **not** signal status — use **Chart tokens** for plot colors, not this ramp, unless a design explicitly maps a tile to a series color. Pattern: `decorative-background-{ramp}`, `decorative-background-{ramp}-hover`, `decorative-foreground-{ramp}`.
+#### Date Picker
 
-**Preference order for new work:**
+**Storybook-slug:** datepicker
+**Docs-slug:** date-and-time-picker
 
-| Priority | Ramp | Background | Foreground |
-| :---: | :--- | :--- | :--- |
-| 1 | Fjord | `decorative-background-fjord` | `decorative-foreground-fjord` |
-| 2 | Nordic | `decorative-background-nordic` | `decorative-foreground-nordic` |
-| 3 | Aurora | `decorative-background-aurora` | `decorative-foreground-aurora` |
-| 4 | Dusk | `decorative-background-dusk` | `decorative-foreground-dusk` |
-| 5 | Orange | `decorative-background-orange` | `decorative-foreground-orange` |
-| 6 | Sky | `decorative-background-sky` | `decorative-foreground-sky` |
-| 7 | Mountain | `decorative-background-mountain` | `decorative-foreground-mountain` |
+**Definition**
+Allows users to select a single date through a calendar interface, ensuring proper formatting and avoiding input errors.
 
-Example (fjord ramp): light `decorative-background-fjord` → `#CCD5FA` (fjord-200), `decorative-foreground-fjord` → `#1234B6` (fjord-700); dark → `#AEBDF7` / `#0D2582` (fjord-300 / fjord-800). Every ramp resolves in [`src/colors.css`](./src/colors.css).
+**Use when**
+- Users need to select an exact date.
+- Preventing manual date-formatting errors is important.
 
-#### Chart tokens
+**Use something else when**
+- Relative dates are more appropriate ("Last week") — add shortcut options instead.
+- The date is fixed or recurring (consider a cron expression or plain `Input`).
+- Exact timing is not critical (use basic `Input`).
 
-**Priority rule:** use `chart-*` for any data plotted on axes or series; use `decorative-*` for non-data visual differentiation (tiles, avatars, accents); use semantic tokens (`info-*`, `success-*`, `warning-*`, `destructive-*`) for operational status and feedback only. Never swap between these groups.
+**Behavior**
+- Opens a calendar anchored to the input field.
+- Keyboard users can type valid values directly without using the picker.
+- Values commit in the configured locale format.
 
-| Token | Use |
-| :--- | :--- |
-| `chart-{ramp}-color-1` … `chart-{ramp}-color-6` | Alpha-based series / area-fill steps (strongest → lightest) |
-| `chart-gridlines` | Grid lines |
+**Often used with**
+- `Label`, helper text, `Date Range Picker`.
 
-Default series order: **fjord → nordic → aurora → dusk → orange**.
+#### Date Range Picker
 
----
+**Storybook-slug:** daterangepicker
+**Docs-slug:** date-and-time-picker
 
-### Typography
+**Definition**
+Allows users to select a start and end date from a calendar interface. Used for filtering by date ranges, comparing periods, or scheduling.
 
-Aura uses three **font families** (loaded in [`src/styles.source.css`](./src/styles.source.css)):
+**Use when**
+- Users need to specify a date range for filtering or reporting.
+- Comparing data across a period.
 
-| Token | Font | Use |
-| :--- | :--- | :--- |
-| `--font-sans` / `--font-inter` | Inter | Default UI — copy, labels, dense UI |
-| `--font-marketing` | Space Grotesk | Marketing / display headings only |
-| `--font-mono` | Source Code Pro | Code, technical strings |
+**Use something else when**
+- Only a single date is needed (use `Date Picker`).
+- Relative ranges like "Last 7 days" cover most use cases — add shortcut options.
 
-**Type scale** — sizes and line heights are driven by Tailwind v4 theme overrides (`--text-*`, `--text-*--line-height`) and tracking tokens (`--tracking-tight`, `--tracking-tighter`, `--tracking-tightest`). Typical **semantic styles** map as follows (use Storybook / product patterns for exact classes):
+**Behavior**
+- Enforces start/end ordering with validation messages.
+- Keyboard users can type valid values directly.
 
-| Style | Font | Size | Weight | Line height | Letter spacing | Use |
-| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| `display` | Space Grotesk | 36px (`text-5xl`) | 600 | 44px | -0.08px | Hero / marketing display |
-| `h1` | Inter | 32px (`text-4xl`) | 600 | 40px | -0.08px | Page title |
-| `h2` | Inter | 28px (`text-3xl`) | 600 | 32px | -0.08px | Section title |
-| `h3` | Inter | 24px (`text-2xl`) | 600 | 28px | -0.04px | Subsection |
-| `h4` | Inter | 20px (`text-xl`) | 500 | 24px | -0.04px | Group label |
-| `body-md` | Inter | 16px (`text-base`) | 400 | 20px | -0.04px | Default body |
-| `body-sm` | Inter | 14px (`text-sm`) | 400 | 18px | -0.04px | Secondary body |
-| `label` | Inter | 12px (`text-xs`) | 500 | 14px | -0.04px | Form labels, compact UI |
-| `code` | Source Code Pro | 14px (`text-sm`) | 400 | 20px | — | Monospace content |
+**Often used with**
+- `Label`, helper text, `Date Picker`.
 
----
+#### Date Time Range Picker
 
-### Size and dimensions
+**Storybook-slug:** datetimerangepicker
+**Docs-slug:** date-and-time-picker
 
-Aura aligns to a **4px base grid**. Spacing in components follows **Tailwind spacing** (`p-*`, `gap-*`, `m-*`): one unit = **4px** unless overridden. Common steps:
+**Definition**
+Allows users to select start and end date and time values. Used when precise time boundaries matter, for example scheduling or time-series filtering.
 
-| Name | Value | Tailwind | Typical use |
-| :--- | :--- | :--- | :--- |
-| xs | 4px | `1` | Tight gaps, icon padding |
-| sm | 8px | `2` | Inline controls, compact padding |
-| md | 12px | `3` | Card / popover internal padding |
-| lg | 16px | `4` | Related groups |
-| xl | 20px | `5` | Sections |
-| 2xl | 24px | `6` | Page regions |
-| 3xl | 32px | `8` | Large layout gaps |
+**Use when**
+- Users must specify both a date and time for a range (scheduling, time-series queries).
 
-Layout helpers in theme: `--container-2xl` (40rem), `--container-8xl` (96rem), `--message-content-max-width` (80% for chat content).
+**Use something else when**
+- Time precision is not required (use `Date Range Picker`).
+- Only a single point in time is needed (use `Date Picker` or `Time Picker`).
 
-#### Component heights
+**Behavior**
+- Enforces start/end ordering; validates that end is after start.
+- Keyboard users can type valid values directly.
 
-Heights are **not** always single CSS variables; primitives use Tailwind height utilities. Representative values from core components:
+**Often used with**
+- `Label`, helper text, `Date Range Picker`.
 
-| Size | Height | Aura usage |
-| :--- | :--- | :--- |
-| xs | 20px (`h-5`) | Badge (default) |
-| sm | 28px (`h-7`) | Button `sm`, compact rows |
-| md | 36px (`h-9`) | Button default, Input, Select, many menu rows |
-| lg | 40px (`h-10`) | Button `lg` |
-| Icon button | 28 / 36 / 40px | `icon-sm` / default / `icon-lg` (`size-7`, `size-9`, `size-10`) |
+#### Dialog
 
-**Topbar** height is **application-defined** (not a single Aura token). **Table / list row** density varies by product; menu and command patterns often use **36px** (`h-9`) rows.
+**Storybook-slug:** dialog
+**Docs-slug:** dialog
 
----
+**Definition**
+Richer content surface: forms, multi-field flows, or explanations that do not fit a strip or inline pattern.
 
-### Corner radius
+**Use when**
+- Collecting input or showing structured content that needs focus without leaving the page.
 
-Defined in [`src/styles.source.css`](./src/styles.source.css). Default interactive radius in components is often **`rounded-lg` (8px)** for buttons/inputs; cards and overlays use **`rounded-lg`**–**`rounded-xl`**.
-
-| Token | Value | Use |
-| :--- | :--- | :--- |
-| `--radius-none` | 0px | Dividers, full-bleed |
-| `--radius-xs` | 2px | Tight inner chrome |
-| `--radius-sm` | 4px | Small controls, badges |
-| `--radius-md` / `--radius` | 6px | Maps to `rounded-md` — shared default in theme |
-| `--radius-lg` | 8px | **Default** for many controls (Button, Input) via `rounded-lg` |
-| `--radius-xl` | 12px | Dialogs, large cards, popovers |
-| `--radius-2xl` | 16px | Extra-large surfaces |
-| `--radius-3xl` | 24px | Marketing / hero panels |
-| `--radius-4xl` | 32px | Largest marketing rounding |
-| `--radius-full` | 9999px | Pills, avatars |
+**Use something else when**
+- Inline persistence is enough (`Alert`).
+- Only a quick acknowledgement is needed (`Sonner Toast`).
+- The action is binary and destructive (use `Alert Dialog`).
 
----
+**Often used with**
+- `Button`, `Form`, `Alert Dialog` for confirmation steps.
 
-### Border
+#### Drawer
 
-Aura is visually **flat**; surfaces, spacing, and typography do most structure. Add borders only when separation or affordance needs extra clarity.
+**Storybook-slug:** drawer
 
-**Rules**
+**Definition**
+Secondary surface that slides in for filters, detail, or medium-length tasks without a full page change.
 
-- **Must** treat borders/strokes as structural signals (inputs, table boundaries, critical separators), not decoration.
-- **Should** distinguish line items inside cards with spacing, alignment, and type hierarchy before adding dividers.
-- **Should** prefer one outer container boundary over many nested per-row outlines in the same card.
-- **Avoid** drawing borders around every item in a list/card just to create visual rhythm.
-- **Avoid** decorative outline stacks (`border` + `ring` + inset strokes) when no state or interaction meaning is conveyed.
+**Use when**
+- Supporting the main view (filters, record details, auxiliary forms).
 
-| Concept | Value | Use |
-| :--- | :--- | :--- |
-| Default width | **1px** | Tailwind `border` — tables, inputs, and occasional structural dividers |
-| Emphasized width | **2px** | Stronger separation or invalid/critical state emphasis |
-| Border color | `border`, `border-emphasized`, … | See **Base — Borders and focus** |
-| Style | solid | Default |
+**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).
 
----
+#### Dropdown Menu
 
-### Effects
+**Storybook-slug:** dropdown-menu
 
-#### Shadows
+**Definition**
+A button-triggered overlay listing a set of related actions or options. One of the two menu variants (the other being a context menu, which is right-click triggered). See also: `Menu`.
 
-`--effect-shadow-sm` through `--effect-shadow-xl` are **alpha blacks** (tuned per theme in [`src/colors.css`](./src/colors.css)). [`src/styles.source.css`](./src/styles.source.css) composes Tailwind shadows:
+**Use when**
+- A button needs to reveal secondary or overflow actions without persistent UI.
+- Grouping related actions behind a single trigger to reduce visual clutter.
 
-| Tailwind shadow | Built from `--effect-shadow-*` | Light (α) | Dark (α) | Use (per theme comments in CSS) |
-| :--- | :--- | :--- | :--- | :--- |
-| `shadow-sm` | `--effect-shadow-sm` | 0.04 | 0.2 | Tooltips, small floating containers |
-| `shadow-default` | md + sm layers | 0.05 + 0.04 | 0.302 + 0.2 | Menus, popovers, hover cards |
-| `shadow-md` | lg + md layers | 0.06 + 0.05 | 0.4 + 0.302 | Sonner toasts, temporary elevated elements |
-| `shadow-lg` | xl + lg layers | 0.10 + 0.06 | 0.6 + 0.4 | Modals / dialogs **without** full backdrop overlay |
-| `shadow-xl` | xl + lg layers | 0.10 + 0.06 | 0.6 + 0.4 | Modals / dialogs **with** backdrop overlay |
+**Use something else when**
+- Options require complex selection or rich descriptions (use `Select Panel`).
+- Actions need user confirmation (use `Dialog` or `Alert Dialog`).
+- The action set is always visible and primary (use `Toolbar`).
 
-Exact pixel stacks: `--shadow-sm` … `--shadow-xl` in [`src/styles.source.css`](./src/styles.source.css).
+**Behavior**
+- Closes after selection by default.
+- Positions above, below, or beside the trigger depending on viewport space.
+- Submenus open on hover.
 
-#### Focus rings
+**Often used with**
+- `Button`, `Separator`, `Badge`, checkbox toggles.
 
-Shadow-based (not `outline`) for consistent rendering:
+#### Empty State
 
-| Token | Composition | Use |
-| :--- | :--- | :--- |
-| `--shadow-focus-ring` | `0 0 0 1px var(--ring), 0 0 0 3px var(--ring-muted)` | Default focus on interactive controls |
-| `--shadow-focus-ring-destructive` | `0 0 0 1px var(--ring-destructive), 0 0 0 3px var(--ring-destructive-muted)` | Destructive / invalid focus |
+**Storybook-slug:** empty
+**Docs-slug:** empty-state
 
-#### Opacity
+**Definition**
+Placeholder when there is no data yet or results are empty.
 
-| Token / concept | Value | Use |
-| :--- | :--- | :--- |
-| `--opacity-10` … `--opacity-80` (+ `*-inverted`) | rgba steps | Overlays, glass effects |
-| Overlay scrim | via `overlay-background` | Modal backdrop (see color tables) |
-| Chart fills | `chart-*-color-*` | See **Chart tokens** |
+**Use when**
+- Lists, tables, charts, or artifacts have zero rows/points.
 
-#### Motion (reference)
+**Dos and don'ts**
+- Explain what will appear and how to get started.
+- Include a single clear CTA when creation/import applies.
 
-Short UI motion (e.g. accordion height) uses **~0.2s ease-out** in utilities; there is no separate “motion duration” token table in Aura today — follow component and `tw-animate-css` patterns.
+#### Form
 
----
+**Storybook-slug:** form
 
-### Layout and spacing
+**Definition**
+A structural wrapper for form fields that manages layout, spacing, validation state propagation, and submission handling.
 
-Width and spacing values in this subsection come from [`src/styles.source.css`](./src/styles.source.css) (`@theme inline` and `:root`) where noted. **Gutters and gaps** use the same **4px-based** spacing scale as **[Tokens → Size and dimensions](#size-and-dimensions)**.
+**Use when**
+- Collecting structured user input across one or more fields.
+- Grouping related fields with shared validation and submission logic.
 
-**Body text reading width**
+**Dos and don'ts**
+- Do group semantically related fields together.
+- Do associate every field with a `Label`.
+- Do not use `Form` as a generic container when no submission or validation is needed.
 
-- **Must** cap **continuous body text** (paragraphs, descriptions, long labels) at a **maximum width of 600px** for comfortable reading.
-- **Must** apply that limit to the **text column only** — companion UI (icons, thumbnails, side metadata, charts, code blocks) **may** sit outside that 600px band in the same row or card; do not shrink the text measure to absorb those elements.
-- **Should** implement the cap with `max-w-[600px]` / `max-w-[37.5rem]` (or an equivalent layout wrapper) on the text block, not by stretching typography alone inside an arbitrarily wide container.
+**Often used with**
+- `Input`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Label`, `Button` (submit), `Dialog`.
 
-### Width and max content
+#### Input
 
-Aura adjusts Tailwind **container** breakpoints where the default scale is too wide or too narrow for Fusion-style surfaces:
+**Storybook-slug:** input
+**Docs-slug:** input
 
-| Token | Value | Role |
-| :--- | :--- | :--- |
-| `--container-2xl` | 40rem (**640px**) | Narrower than Tailwind’s default `2xl` container — useful outer bound for regions; **body copy** inside can still follow the **600px** reading rule above |
-| `--container-8xl` | 96rem (**1536px**) | Wide upper bound for dashboards and full-bleed marketing rows |
+**Definition**
+Single-line text field for capturing short text-based information in forms and toolbars.
 
-Prefer **`max-w-*`** (and other width utilities) tied to the theme over ad-hoc pixel `max-width` on wrappers. **Global frame** width (shell chrome) is defined by the **Fusion / product** host; **inside** the frame, combine these tokens with responsive utilities so regions reflow predictably.
+**Use when**
+- Collecting specific text data (names, credentials, asset identifiers).
+- A form field requires free text that doesn't fit a structured picker.
 
+**Use something else when**
+- Selecting from predefined options (use `Select`, `Combobox`, `Checkbox`, or `Radio`).
+- Suggestions as the user types are needed (use `Combobox`).
+- Selecting dates or times (use `Date Picker` / `Time Picker`).
+- Multi-line text is expected (use `Textarea`).
 
-### Specialized variables
+**Dos and don'ts**
+- Do not use long placeholder text that duplicates the label.
+- Do not mimic pre-filled content with placeholder text.
+- Do not wrap text in an input; truncate or switch to `Textarea`.
 
-| Variable | Value | Use |
-| :--- | :--- | :--- |
-| `--message-content-max-width` | `80%` | Primary column for chat / assistant **Message** content in wide threads |
-| `--drawer-max-height` | `80vh` | Maximum height for top/bottom drawer-style panels when the host implements them |
-| `--alert-icon-width` | `calc(var(--spacing) * 4)` (typically **16px**) | Fixed icon column in the **Alert** layout so titles and descriptions align |
+**Behavior**
+- Single-line only; updates as the user types.
+- Validation messages associate with the field for accessibility.
+- Supports leading (icon, prefix) and trailing (button, suffix, stepper) slots.
 
-### Regional spacing
+**Often used with**
+- `Label`, helper text, `Button`, `Tooltip`.
 
-- **Must** use the **spacing scale** for padding, margin, and `gap` between regions (`gap-*`, `p-*`, `m-*`) — see **Tokens → Size and dimensions**.
-- **Should** keep major block **padding** and **gap** on **4px** multiples so control heights, radii, and typography line up visually.
-- **Should** group related regions in **Card** (and **Separator** when two unrelated groups share a container) before mixing unrelated actions into the same band — see **Heuristics §6**.
-- **Avoid** one-off pixel gutters that ignore the scale unless matching a fixed graphic asset.
+#### Label
 
-### Responsive behavior
+**Storybook-slug:** label
+**Docs-slug:** label
 
-- **Should** move secondary work into **Dialog** or a shell **Drawer** on narrow widths instead of compressing multi-column chrome.
-- **Avoid** single-breakpoint layouts tuned only to a static design frame — use breakpoints, wrapping, and flexible sizing utilities where content must grow and shrink.
+**Definition**
+A form label that identifies and is programmatically associated with an input field. Not intended as general-purpose text.
 
-### Shell vs content
+**Use when**
+- Every `Input`, `Select`, `Combobox`, `Textarea`, `Checkbox` group, `Radio` group, `Switch`, `Slider`, or `Date Picker` needs one.
+
+**Use something else when**
+- You need a heading or section title (use appropriate heading levels).
+- You need descriptive text below a field (use helper text).
+- You are labeling a non-interactive element like a status indicator (use plain text or `Badge`).
+
+**Dos and don'ts**
+- Do associate labels with fields via `htmlFor`/`id` for accessibility.
+- Do mark required fields consistently (asterisk or explicit text).
+- Do not replace labels with placeholder text — placeholders disappear and are inaccessible.
+- Do not hide labels for visual cleanliness; use `Tooltip` to supplement shortened labels.
+
+**Often used with**
+- `Input`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Switch`, `Slider`, `Textarea`, `Date Picker`.
+
+#### Menu
+
+**Storybook-slug:** menu
+**Docs-slug:** menu
+
+**Definition**
+Presents a list of actions, options, or states for the current selection or context. Two variants: context menu (right-click/long-press trigger) and dropdown menu (button trigger). See also: `Dropdown Menu`.
+
+**Use when**
+- Offering action choices from a button, select, or combobox when space is constrained.
+- Exposing contextual actions via right-click without dedicated trigger UI.
+
+**Use something else when**
+- Options require reordering or rich descriptions (use `Select Panel`).
+- Actions need user confirmation before executing (use `Dialog`, `Alert Dialog`, or `Popover`).
+
+**Dos and don'ts**
+- Do keep items left-aligned and styled consistently within sections.
+- Do separate actions into labeled sections using `Separator`.
+- Do not mix items with and without leading content (icons/toggles) in the same section.
+
+**Behavior**
+- Closes after selection unless multi-select is enabled.
+- Positions above, below, left, or right of the trigger with a 4px gap, adapting to viewport space.
+- Submenus open on hover.
+
+**Often used with**
+- `Button`, `Select`, `Combobox`, `Separator`, `Badge`, checkbox toggles.
+
+#### Pagination
+
+**Storybook-slug:** pagination
+**Docs-slug:** pagination
+
+**Definition**
+Divides large datasets into pages, giving users control over navigation and improving load performance.
+
+**Use when**
+- Datasets are large (tables, search results, galleries).
+- Performance concerns rule out infinite scroll.
+- Users need to bookmark or return to a specific page position.
+
+**Use something else when**
+- The context is a discovery feed (use infinite scroll or "Load more").
+- Users are completing a sequential task (use a wizard/stepper).
+- You need to switch between unrelated modes (use `Segmented Control` or `Tabs`).
+
+**Dos and don'ts**
+- Do place pagination below content, left-aligned.
+- Do provide "Next" and "Previous" buttons, disabled when irrelevant.
+- Do include "Results per page" options for large datasets.
+- Do not use pagination when fewer than ~20 items per page exist.
+
+**Behavior**
+- Each page should have its own shareable URL.
+- Content loads without full page reloads; use loaders and skeletons while data fetches.
+- Teleport variant allows direct page number entry.
+- Filters, searches, and selections persist across pages.
+
+**Often used with**
+- `Table`, data grids, `Search`, `Skeleton`.
+
+#### Popover
+
+**Storybook-slug:** popover
+**Docs-slug:** popover
+
+**Definition**
+A click-triggered panel for interactive or structured supplemental content. Stays open until dismissed.
+
+**Use when**
+- User needs to pick options, fill short fields, or read formatted content on demand without leaving the page.
+
+**Use something else when**
+- Content is essential to the task — surface it inline or in `Dialog` / `Drawer`.
+- A brief, non-interactive hint is needed (use `Tooltip`).
+
+**Often used with**
+- `Button` or icon as trigger, `Command`, form controls inside the panel.
+
+#### Radio
+
+**Storybook-slug:** radio
+**Docs-slug:** radio
+
+**Definition**
+Allows users to select exactly one option from a small set of mutually exclusive choices.
+
+**Use when**
+- Single selection from a small, visible set of predefined options.
+- All options should be visible side by side for comparison.
+
+**Use something else when**
+- Multiple selections are needed (use `Checkbox`).
+- There are more than ~5 options or space is limited (use `Select` or `Combobox`).
+- The choice is binary and takes immediate effect (use `Switch`).
+
+**Dos and don'ts**
+- Do pair each radio with a descriptive label.
+- Do not group unrelated options.
+- Do not exceed 5 options.
+
+**Behavior**
+- Clicking or pressing Space selects the focused option and deselects others in the group.
+
+**Often used with**
+- `Label`, helper text, `Card` variant for options needing supporting descriptions.
+
+#### Search
+
+**Storybook-slug:** search
+**Docs-slug:** search
+
+**Definition**
+A specialized input for locating and filtering content, with built-in search and clear affordances.
+
+**Use when**
+- Lists, tables, or datasets need quick item location.
+- Content-heavy pages where scrolling is impractical.
+- Application-wide search (in conjunction with `Command`).
+
+**Use something else when**
+- Selecting from predefined options (use `Combobox` or `Select`).
+- Multi-attribute filtering requires dedicated filter controls.
+- General text input unrelated to content discovery (use `Input`).
+
+**Dos and don'ts**
+- Do make it clear whether search covers the current list, the page, or the whole app.
+- Do display a no-results state when queries return nothing.
+- Do debounce live search to avoid excessive requests.
+- Do use descriptive placeholder text ("Search assets").
+- Do not leave empty results without explanation.
+
+**Often used with**
+- `Table`, data grids, `Command`, adjacent filter controls (`Select`, `Combobox`).
+
+#### Segmented Control
+
+**Storybook-slug:** segmented
+**Docs-slug:** segmented-control
+
+**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.
+
+#### Select
+
+**Storybook-slug:** select
+**Docs-slug:** select
+
+**Definition**
+Enables users to choose one or more predefined options from a dropdown list. Used in forms and filtering when space is constrained.
+
+**Use when**
+- Multiple predefined options exist and space prevents showing them all at once.
+- Options are familiar and don't require explanation.
+- A single or multi-select form input is needed.
+
+**Use something else when**
+- 12+ options or search is needed (use `Combobox`).
+- Few options or a binary choice (use `Checkbox`, `Radio`, or `Switch`).
+- User-created values are needed (use `Combobox`).
+- Options need lengthy descriptions (use `Checkbox` or `Radio`).
+- Selection triggers immediate mode-switch (use `Segmented Control` or `Tabs`).
+
+**Dos and don'ts**
+- Do provide a clear label and placeholder.
+- Do use helper text when clarification is needed.
+- Exercise caution with default selections — users may overlook them.
+
+**Behavior**
+- Single-select closes after selection; multi-select may remain open.
+- Checkmarks appear right-aligned in the list.
+
+**Often used with**
+- `Label`, helper text, `Button`.
+
+#### Separator
+
+**Storybook-slug:** separator
+**Docs-slug:** separator
+
+**Definition**
+A 1px visual divider between distinct content sections. Improves readability while remaining visually subtle.
+
+**Use when**
+- Creating visual relief between related groups of content.
+- Dividing sections within toolbars, menus, cards, or forms.
+
+**Use something else when**
+- The layout is sparse — whitespace alone is sufficient.
+- Sections need semantic grouping (use headings, `Card`, or background regions instead).
+
+**Dos and don'ts**
+- Do use 16px vertical separators for button or horizontal form element separation.
+- Do not place separators between every element.
+- Do not use bold or colorful separators — keep them subtle.
+- Do not replace semantic headings or landmarks with separators.
+
+**Often used with**
+- `Toolbar`, `Card` headers/footers, `Accordion`, menus, dense form sections.
+
+#### Skeleton
+
+**Storybook-slug:** skeleton
 
-**Global chrome** (workspace switcher, app-level navigation) is implemented by the **product shell**, not `@cognite/aura`. **Must** still theme that chrome with Aura **Tokens** so shell and in-app surfaces feel continuous. **In-app content** should rely on Aura primitives (**Card**, **Banner**, **Dialog**, forms) plus the width and spacing rules above.
+**Definition**
+A loading placeholder that mimics the shape of incoming content, reducing perceived wait time and preventing layout shift.
+
+**Use when**
+- Content is loading and the shape of the result is predictable (cards, lists, table rows).
+- Reducing layout shift while data fetches in the background.
+
+**Use something else when**
+- The loading duration is very short (<300ms) — no loader is needed.
+- The content shape is unpredictable (use a spinner or progress indicator).
+
+**Dos and don'ts**
+- Do match skeleton shapes to the actual content layout.
+- Do not animate excessively — subtle pulse is sufficient.
+
+**Often used with**
+- `Card`, `Table`, `Pagination`, lists.
+
+#### Slider
+
+**Storybook-slug:** slider
+**Docs-slug:** slider
+
+**Definition**
+An interactive control for selecting a single value or a range from a continuous scale. Provides visual feedback and quick approximate value selection.
+
+**Use when**
+- Adjusting continuous values where precision is less important than visual feedback (volume, brightness, pricing filter).
+- Providing immediate visual feedback (media scrubbing, live previews).
+- Selecting a minimum and maximum range.
+
+**Use something else when**
+- Precise numeric entry is required (use `Input` or `Select`).
+- The choice is categorical, not continuous (use `Radio` or `Select`).
+
+**Behavior**
+- Supports immediate feedback (changes apply as the user drags) and deferred feedback (changes apply on submit).
+- Use deferred feedback when slider adjustments trigger screen reloads or visual disruptions; pair with helper text explaining that the user must submit to apply.
+
+**Often used with**
+- `Label`, helper text, optional adjacent `Input` for precise numeric entry.
+
+#### Sonner Toast
+
+**Storybook-slug:** sonner
+**Docs-slug:** sonner
+
+**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`).
+
+#### Switch
+
+**Storybook-slug:** switch
+**Docs-slug:** switch
+
+**Definition**
+A binary toggle control that turns a setting on or off, with changes taking effect immediately.
+
+**Use when**
+- Toggling a setting that takes immediate effect (for example, dark mode, notifications).
+
+**Use something else when**
+- The change is form-dependent and deferred (use `Checkbox` or `Button`).
+- The action is one-time or destructive (use `Button`).
+- Multiple related toggles need grouping (use `Toggle Group`, `Checkbox`, or `Select`).
+
+**Dos and don'ts**
+- Do apply a clear, descriptive label explaining the switch's function.
+- Do not embed switches inside `Menu` components — use menu checkmarks instead.
+- Do not use for destructive actions.
+
+**Behavior**
+- Responds instantly to user interaction without requiring separate form submission.
+
+**Often used with**
+- `Label`, helper text.
+
+#### Table
+
+**Storybook-slug:** table
+
+**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.
+
+#### Tabs
+
+**Storybook-slug:** tabs
+**Docs-slug:** tabs
+
+**Definition**
+Organizes related content into switchable sections, allowing users to navigate between different views without leaving the page.
+
+**Use when**
+- Organizing content into sections users switch between frequently.
+- Displaying related, mutually exclusive content.
+- Navigation within pages, dashboards, settings, or data views.
+
+**Use something else when**
+- Filtering a list or dataset (use `Segmented Control`, `Button`, or `Menu`).
+- Multiple sections must be visible simultaneously (use `Accordion` or filters).
+- The choice is a binary toggle (use `Switch`).
+
+**Dos and don'ts**
+- Do use a minimum of two tabs.
+- Do keep content above tabs stable across all tab states.
+- Do use leading icons consistently across all tabs or not at all.
+- Do not use tabs for basic filtering.
+- Do not apply to binary options.
+
+**Behavior**
+- Exactly one tab panel is visible at a time.
+- Tab buttons manage selection state and keyboard focus.
+- Supports default, vertical, and full-width alignment options.
+
+**Often used with**
+- `Table`, `Form`, `Card`, `Empty State`. Keep global page actions outside tab panels.
+
+#### Textarea
+
+**Storybook-slug:** textarea
+**Docs-slug:** textarea
+
+**Definition**
+A multi-line text field for extended free-form input such as comments, feedback, messages, descriptions, or notes.
+
+**Use when**
+- Multi-line text is expected (comments, notes, bios, explanations).
+- Editing large chunks of existing text.
+
+**Use something else when**
+- A single line of text is all that is needed (use `Input`).
+- Structured data is expected (use masked `Input`, `Date Picker`, `Select`, or `Combobox`).
+- Rich formatting is needed (use a rich-text editor).
+
+**Dos and don'ts**
+- Do use concise labels and placeholder text.
+- Do allow scroll when content exceeds the maximum height.
+- Do not set a small fixed height for expected lengthy input.
+- Do not pre-fill with default text users might overlook.
+
+**Behavior**
+- Supports optional user resizing via a drag handle.
+- Restrict resizing when layout integrity is critical (forms in modals or sidebars) or when the textarea auto-expands programmatically.
+
+**Often used with**
+- `Label`, helper text (optionally with character count).
+
+#### Time Picker
+
+**Storybook-slug:** timepicker
+**Docs-slug:** date-and-time-picker
+
+**Definition**
+Allows users to select a time value through a clock interface.
+
+**Use when**
+- Users need to select a precise time without a date.
+- Scheduling tasks, alarms, or time-of-day settings.
+
+**Use something else when**
+- Both date and time are required (use `Date Picker` or `Date Time Range Picker`).
+- Exact timing is not important (use basic `Input`).
+
+**Behavior**
+- Keyboard users can type valid values directly.
+- Values commit in the configured locale format.
+
+**Often used with**
+- `Label`, helper text, `Date Picker`.
+
+#### Toggle
+
+**Storybook-slug:** toggle
+
+**Definition**
+A single pressable button with active/inactive state, used to toggle one option or formatting command on or off.
+
+**Use when**
+- A single binary option needs a visible pressed/unpressed state (for example, bold text, mute).
+
+**Use something else when**
+- Two or more related toggles should be grouped (use `Toggle Group`).
+- The change takes immediate app-level effect (use `Switch`).
+- The action is a one-time command (use `Button`).
+
+**Often used with**
+- `Toolbar`, `Tooltip` for icon-only variants, `Toggle Group`.
+
+#### Toggle Group
+
+**Docs-slug:** toggle-group
+
+**Definition**
+A set of 2–4 related toggle options for mutually exclusive or multi-select settings that are always visible.
+
+**Use when**
+- Toggling between 2–4 always-visible, mutually exclusive modes (for example, grid lines, text alignment, ruler visibility).
+- The current selection must always be immediately clear.
+
+**Use something else when**
+- More than ~4–5 options exist (use `Select` or `Menu`).
+- Options execute one-time commands (use `Button`).
+- Multi-select filtering across a larger set (use `Checkbox` or filter chips).
+- Single-select filtering of a small dataset (use `Segmented Control`).
+- The context is page navigation (use `Tabs` or routing).
+
+**Dos and don'ts**
+- Do keep labels concise — one or two words or icons only.
+- Do not mix icons and text labels within the same group.
+
+**Behavior**
+- Selection updates instantly.
+- Supports single-select and multi-select configurations.
+
+**Often used with**
+- `Toolbar`, `Tooltip` for icon-only variants.
+
+#### Toolbar
+
+**Docs-slug:** toolbar
+
+**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`).
+
+#### Topbar
+
+**Storybook-slug:** topbar
+**Docs-slug:** topbar
+
+**Definition**
+The single, persistent navigation bar at the top of every authenticated CDF and Flows custom app. Provides the primary orientation layer across three fixed regions: left (identity/breadcrumbs), middle (optional global navigation), and right (system controls).
+
+**Use when**
+- Every authenticated screen in a CDF or Flows app — this component is mandatory.
+- The app has two or more top-level views requiring global switching.
+- Actions apply consistently across all app pages (for example, a persistent "Add data" button).
+
+**Use something else when**
+- Login or authentication-only screens.
+- Full-screen flows or modals that intentionally hide global chrome.
+
+**Dos and don'ts**
+- Do use the middle section for primary global app navigation.
+- Do use `Tabs` for distinct pages, `Segmented Control` for mode switching in the middle section.
+- Do not place page-specific actions in the action slot.
+- Do not reorder or restyle system controls.
+- Do not use multiple topbars per page.
+
+**Behavior**
+- Left: app mark (small `Avatar`), breadcrumbs, optional inline metadata.
+- Middle: optional; omit for single-view apps.
+- Right (fixed order): Share → Notifications → Theme → Atlas.
+
+**Often used with**
+- `Breadcrumb`, `Tabs`, `Segmented Control`, `Avatar`.
+
+#### Tooltip
+
+**Storybook-slug:** tooltip
+**Docs-slug:** tooltip
+
+**Definition**
+A short hint that appears on hover or focus. No heavy interaction inside.
+
+**Use when**
+- Clarifying a control or icon in one line or sentence.
+- Providing the full text of a truncated label (for example in `Breadcrumb`).
+
+**Use something else when**
+- Content is essential to the task — surface it inline or in `Dialog` / `Drawer`.
+- Users need to interact with the content (use `Popover`).
+
+**Often used with**
+- Icon-only `Button`, `Toggle`, `Breadcrumb`, `Label`.
+
+#### Tree
+
+**Storybook-slug:** tree
+**Docs-slug:** tree-view
+
+**Definition**
+Displays hierarchical data in a nested structure with expandable/collapsible rows. Supports optional selection and drag-and-drop.
+
+**Use when**
+- Presenting large structures with multiple nesting levels (folders, files, organizational hierarchies).
+- Progressive disclosure of complex hierarchical relationships.
+
+**Use something else when**
+- Data is not hierarchical (use lists or `Table`).
+- A sortable, tabular layout with multiple columns is needed (use `Table`).
+- Non-hierarchical filtering is the goal (use `Tabs` or `Segmented Control`).
+- Showing location in site hierarchy (use `Breadcrumb`).
+
+**Behavior**
+- Nodes expand and collapse independently.
+- Keyboard navigation follows tree semantics (arrow keys, Home/End).
+- Supports single and multi-selection.
+- Optional drag-and-drop reordering (must maintain accessibility).
+
+**Often used with**
+- Row checkboxes, row menus, `Badge` for status, drag handles, selection highlights connecting to a side panel or `Table` in split-view layouts.
+
+## 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.
+
+---
+
+## Do's and Don'ts
+
+Practical guardrails for Aura-based UI. For full rationale, see [Heuristics](#heuristics), [Interaction states](#interaction-states), and [Content](#content).
+
+### Do
+
+- Use semantic or base **color tokens** — never raw hex, rgb, or hsl when a token exists.
+- Prefer Aura component **variants and APIs** over overriding styles with visual Tailwind utilities on primitives.
+- Show **loading feedback** (`Shimmer`, `Loader`, `Skeleton`) for any wait the user is expected to sit through.
+- Provide a **visible focus ring** on every interactive control (`shadow-focus-ring` / `shadow-focus-ring-destructive` on `:focus-visible`).
+- Cap continuous **body text** at `{spacing.prose-max}` width; keep companion UI outside that measure.
+- Use the **`{spacing.base}` spacing scale** for padding, margin, and gaps.
+- Pair **icon-only controls** with `aria-label` and a `Tooltip`.
+- Use **sentence case** for all UI copy; write action labels as verb + object ("Save changes", "Delete pipeline").
+- Verify **contrast in both light and dark themes** before shipping.
+
+### Don't
+
+- Don't use semantic status colors (`info-*`, `success-*`, `warning-*`, `destructive-*`) as generic decoration or toggled selection fills.
+- Don't remove focus styling or use `outline-none` / `ring-0` without an equivalent token-based focus ring.
+- Don't stack multiple **Alerts** or **toasts** for a single user gesture.
+- Don't use `alert()` or other native blocking dialogs for product UX.
+- Don't hardcode **font sizes, shadows, or border radii** when theme tokens exist.
+- Don't use icon-only targets without an accessible name and tooltip.
+- Don't mix **chart**, **decorative**, and **semantic** color groups interchangeably.
+- Don't override Aura primitive appearance with visual `className` utilities — use variants instead.
 
 ---
 
-## Assets
+## Assets & Motion
 
-**What this section is:** Rules for **illustrations**, **document icons**, **app icons**, and **system icons** in Aura-based products. Each type has a distinct job; mixing types or bending the rules adds noise and weakens trust. Visual execution (where files live, export pipelines) belongs in brand tooling and engineering skills, not here.
+**What this section is:** Rules for **illustrations**, **document icons**, **app icons**, and **system icons** in Aura-based products. It also includes rules and guidance for motion design. Each type has a distinct job; mixing types or bending the rules adds noise and weakens trust. Visual execution (where files live, export pipelines) belongs in brand tooling and engineering skills, not here.
 
 ### Illustrations
 
@@ -940,18 +2160,243 @@ Rare exceptions (third-party or Cognite logos inside a cell) use **provided SVGs
 - **Must** give icon-only controls an accessible name (`aria-label` / `aria-labelledby`) **and** a **Tooltip** on hover/focus where the design hides the text label.
 - Icons that only repeat the meaning of adjacent visible text **should** be `aria-hidden="true"`.
 
+### Motion (reference)
+
+Short UI motion (e.g. accordion height) uses **~0.2s ease-out** in utilities; there is no separate “motion duration” token table in Aura today — follow component and `tw-animate-css` patterns.
+
+---
+
+## Heuristics
+
+**What this section is:** The short interaction contract for Aura-based UIs. It keeps the design identity usable by agents and reviewers without turning this file into a full UX playbook.
+
+This section contains Aura's decision rules, component selection guidance, and common failure modes. Severity terms carry specific meaning: **Must** / **must not** breaks usability, accessibility, or system conformance; **Should** is the strong default; **Avoid** is a known failure mode.
+
+These rules apply to Aura primitives, host-shell components themed with Aura tokens, and standalone apps using Aura. Component props and enum names live in the component APIs, not in this spec.
+
+### Aura vs. your responsibility
+
+Aura components handle many accessibility concerns automatically. Composition, copy, focus management, and page structure remain the implementer's job.
+
+| 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, SegmentedControl, etc.     | Custom components declare correct 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 while open                       | Focus returns to the trigger element on close |
+
+---
+
+### 1. Feedback and system status
+
+Users must always know whether the system is waiting, succeeded, failed, or needs action.
+
+- **Must** show loading for any wait the user is expected to sit through. Use **Shimmer** or **Skeleton** when the incoming layout is known, **Loader** for compact waits, and **Progress** when completion is measurable.
+- **Must** acknowledge user-triggered mutations with visible feedback. Use a transient toast for low-stakes confirmations, inline feedback for scoped changes, and **Dialog** / shell **AlertDialog** before irreversible actions.
+- **Must** surface persistent workflow-impacting problems until dismissed or resolved. Use **Banner** for high-priority degraded states, **Alert** for page-scoped awareness, and **Badge** or compact status rows for repeated entity state.
+- **Avoid** blank loading areas, stacked toasts for one gesture, repeated Alert lists, and using **Banner** for routine connection handshakes.
+
+### Alert vs Banner vs Badge vs Sonner
+
+Use this matrix to pick the right feedback component. Priority is defined by whether the message requires immediate action and how long it needs to persist.
+
+| Priority   | When                                                            | Components                                                                | Notes                                                                                                                                                                              |
+| ---------- | --------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Low**    | Non-disruptive updates, minor status, validation hints          | `Badge`, notification dot, inline `HelperText`                            | Does not interrupt the user. Badge for entity state; HelperText for field-level feedback.                                                                                          |
+| **Medium** | Informative, occasionally actionable, not urgent                | `Sonner` (toast), `Alert`                                                 | Sonner for transient confirmations (~4 s, bottom-right). Alert for inline, page-scoped status that needs awareness but not immediate action (typically one per page section/view). |
+| **High**   | Requires immediate attention or action; may interrupt task flow | `Banner` (system errors), `Dialog` / `AlertDialog`, full-page error state | Banner for persistent, region-scoped degraded states. Dialog for irreversible actions. Never use Sonner as the sole safety net for destructive work.                               |
+
+**Rules**
+
+- **Must not** use Banner for low-priority or transient notices — it occupies persistent chrome and dilutes high-priority signals.
+- **Must not** use Sonner for errors that require user action — it auto-dismisses.
+- **Must not** use repeated Alerts as a list visualization pattern; one Alert communicates the grouped situation, while item-level status belongs in Badge/status-card patterns.
+- **Should** use `Badge` semantic variants (`warning`, `destructive`, `success`) on entities that carry that state, not as page-level alerts.
+- **Avoid** stacking multiple Sonner toasts for a single user gesture.
+
+**Industrial / operational states**
+
+The matrix above covers standard cases. For domain-specific states (e.g. sensor offline, process limit breach, control system degraded), apply the same priority logic: does the user need to act now? -> Banner or Dialog. Informational? -> Alert or Badge on the asset. Transient confirmation? -> Sonner. When many entities share similar state, summarize once (Alert/Banner) and show per-entity state with Badge or status cards.
+
+---
+
+### 2. Affordance and discoverability
+
+Controls must read as interactive; users should not guess what is clickable, expandable, editable, or destructive.
+
+- **Must** use semantic controls for actions, links, form fields, menus, and disclosure. Do not make generic elements behave like buttons.
+- **Must** match component variant to intent: primary for one main action, secondary or ghost for support, destructive only for irreversible work.
+- **Must** pair every field with a visible **Label**. Placeholder text is not a label.
+- **Must** give icon-only controls both an accessible name and a **Tooltip**.
+- **Should** use recognizable signifiers: chevrons for menus and disclosure, magnifier icons for search, helper text for constraints, and empty-state cards with an explanation plus a next action.
+- **Avoid** clickable text that looks identical to body copy or help that exists only in hover on touch-first flows.
+
+---
+
+### 3. Progressive disclosure
+
+Introduce complexity only when needed; default views should stay scannable.
+
+- **Must** use **Accordion** for stacked independent sections and **Collapsible** for one inline expandable block.
+- **Must** use **Dialog** for modal tasks and shell **Drawer** / **Sheet** for secondary edge panels where the host provides them.
+- **Must** split flows with 3 or more steps into discrete steps with visible progress.
+- **Must** scope menu items to the entity they affect. Do not mix row actions, page actions, and global actions in one menu.
+- **Should** keep advanced settings, rare metadata, and secondary actions behind disclosure when they are not needed for the main task.
+- **Avoid** deeply nested accordions, long flat menus, and multiple irreversible primary decisions in one step.
+
+---
+
+### 4. Error handling and prevention
+
+Prevent errors where possible. When errors happen, users must understand what failed, why it matters, and how to recover.
+
+- **Must** confirm high-impact destructive actions before execution. Name the object and consequence; do not ask only "Are you sure?".
+- **Must** label destructive confirmation with the specific action, such as "Delete report", not "OK" or "Confirm".
+- **Must** show form errors inline on the affected field and explain how to fix them.
+- **Must** protect unsaved work with auto-save where feasible, persistent unsaved state where not, and a discard warning before navigation.
+- **Should** offer **Undo** for reversible destructive actions when recovery is cheap and contained in the same session.
+- **Must** validate fields on blur, not on every keystroke.
+- **Must** preserve user input on a failed submission — never clear the form.
+- **Must** move focus to the first invalid field after a failed submission and announce the error via `aria-live`.
+- **Avoid** using toast as the only safety net for irreversible work or revealing every validation error only on final submit.
+
+**Field validation states**
+
+Not every field type needs every validation kind. Use this to scope what 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)   | —          |
+
+**Edge cases**
+
+- Destructive action with undo? Still confirm — mention the undo window in the dialog body ("You can undo within 30 seconds").
+- Bulk delete? One confirmation naming the count ("Delete 12 reports?"), not one per item.
+- Auto-save? Use a subtle persistent "Saved" indicator, not a toast on every save.
+- Error partway through a multi-step flow? Don't lose progress — show the error on the current step and let the user retry from there.
+
+---
+
+### 5. Enabling power users
+
+Experts should move faster without harming first-time clarity.
+
+- **Should** provide shortcuts for the top few high-frequency actions and render them with Aura shortcut components.
+- **Should** align shortcuts with platform norms where they do not fight the browser or operating system.
+- **Must** support multi-select in list or table UIs that offer per-row destructive or batch actions.
+- **Must** show bulk action controls only when selection is non-empty, with selected count.
+- **Must** use structured empty states for first use or no data: title, explanation, and one clear next action.
+- **Avoid** bulk destructive work without confirmation, stealing reserved shortcuts, or using **Banner** for long onboarding tours.
+
+---
+
+### 6. Layout and hierarchy
+
+Information must be scannable and oriented before action.
+
+- **Must** group related fields and content in one **Card** or labeled section.
+- **Must** separate unrelated groups with spacing, section labels, or **Separator** before adding nested borders.
+- **Must** keep one clear primary CTA per view. Global actions belong in shell chrome; page actions belong in the page header or toolbar.
+- **Must** use shell **Tabs** / **SegmentedControl** for primary view switching where the product uses that pattern; do not duplicate global navigation in content.
+- **Should** use type scale, weight, and spacing to lead attention before using color or elevation.
+- **Avoid** unrelated actions in the same card, hard-coded pixel widths, duplicated navigation, and destructive styling for non-destructive actions.
+
+---
+
+### 7. Accessibility and inclusive design
+
+Aura targets **WCAG AA** for primitives — usage must preserve that.
+
+- **Must** complete every task path with keyboard alone.
+- **Must** keep visible focus treatment on every interactive control. Never use `outline-none` or `ring-0` without an equivalent Aura focus ring.
+- **Must** preserve primitive roles and ARIA behavior when composing or wrapping Aura components.
+- **Must** name icon-only controls and pair them with a **Tooltip**.
+- **Must not** encode meaning with color alone. Pair color with text, icon, helper text, or label.
+- **Must** meet contrast and target-size requirements for the shipped context.
+- **Must** follow visual/reading order for tab order, with no keyboard traps; add a skip-to-content link on pages with complex navigation.
+- **Must** use heading levels in strict sequential order: one `H1` per page, never skip a level, and never use a heading tag purely for visual sizing — use the Typography scale instead.
+- **Avoid** pointer-only behavior, unreadable `muted-foreground` copy for required tasks, and sub-24px icon hit zones without expansion.
+
+**Alt text and icon naming**
+
+| Type                    | Approach                    | Example                              |
+| ------------------------ | ---------------------------- | ------------------------------------- |
+| Informational image      | Describe the content         | `alt="Chart: output up 20%"`         |
+| Decorative image         | Empty                        | `alt=""`                              |
+| Icon-only control        | `aria-label` on the control  | `aria-label="Delete report"`         |
+| Icon paired with a label  | Hide the icon                | `aria-hidden="true"` on the icon      |
+
+**Announcing dynamic content**
+
+| Scenario              | Method                                       |
+| ---------------------- | --------------------------------------------- |
+| Search/list results update | `aria-live="polite"`                     |
+| Form error              | `aria-live="assertive"`                     |
+| Toast                   | Handled by the toast component               |
+| Dialog opens            | Focus moves into the dialog (Aura handles)   |
+| Dialog closes           | Return focus to the trigger element          |
+
+### Common pitfalls (agent guidance)
+
+These are the most frequent mistakes when generating or modifying Aura-based UI. Avoid all of them.
+
+- Raw hex, `rgb(...)`, or arbitrary Tailwind colors in product UI.
+- Visual `className` overrides that bypass Aura variants, props, or tokens.
+- Duplicate shell navigation inside content.
+- Cards that mix unrelated actions, unrelated data, and dense nested borders.
+- Semantic, decorative, and chart colors used interchangeably.
+- Icon-only controls without accessible names and tooltips.
+- Disabled primary CTAs with no visible path to resolve the blocker.
+
+### Verifying accessibility
+
+**Self-check before shipping a page**
+
+- [ ] Tab through all elements in logical order
+- [ ] Every button/link works with Enter/Space
+- [ ] Every dialog opens/closes with keyboard, and Escape closes dialogs, popovers, and dropdowns
+- [ ] Every image has appropriate alt text; every form field has a visible label
+- [ ] Non-color indicator present for every status
+- [ ] Headings follow H1 → H2 → H3 with no skipped levels
+- [ ] Dynamic updates are announced to screen readers
+- [ ] Focus ring (`shadow-focus-ring`) is visible on all interactive elements
+
+**Tooling**
+
+- Automated: WAVE, axe DevTools, or Lighthouse in Chrome DevTools.
+- Manual: unplug the mouse and complete primary tasks keyboard-only; spot-check critical flows with VoiceOver (Mac) or NVDA (Windows).
+
+**Accessibility edge cases**
+
+- Complex data visualization? Provide a text summary via `alt` or screen-reader-only text.
+- Drag-and-drop? Requires a keyboard alternative.
+- Real-time dashboard? Use `aria-live="polite"`, not `"assertive"` — frequent updates should not interrupt the user.
+- Third-party embed? Give the `iframe` a descriptive `title`.
+
 ---
 
 ## Interaction states
 
-**What this section is:** What each interaction state *means* for users, which **Tokens** and patterns Aura uses, and rules for custom controls built outside the library. **How** to wire `focus-visible`, CVA variants, or component props belongs in code and engineering skills.
+**What this section is:** What each interaction state _means_ for users, which **Tokens** and patterns Aura uses, and rules for custom controls built outside the library. **How** to wire `focus-visible`, CVA variants, or component props belongs in code and engineering skills.
 
-Every interactive control signals what is possible, what is happening, and what the system registered. **States are signifiers** — visual cues for affordances (what the element *can* do). Using them consistently builds trust and keeps keyboard and assistive-tech use predictable.
+Every interactive control signals what is possible, what is happening, and what the system registered. **States are signifiers** — visual cues for affordances (what the element _can_ do). Using them consistently builds trust and keeps keyboard and assistive-tech use predictable.
 
-| Concept | Meaning |
-| :--- | :--- |
-| **Affordance** | A property that makes an action possible (e.g. a control can be activated). |
-| **Signifier** | A visible cue that communicates that affordance (shape, label, shadow, state styling). |
+| Concept        | Meaning                                                                                |
+| -------------- | -------------------------------------------------------------------------------------- |
+| **Affordance** | A property that makes an action possible (e.g. a control can be activated).            |
+| **Signifier**  | A visible cue that communicates that affordance (shape, label, shadow, state styling). |
 
 Aura primitives ship these states by default; the rules below describe the **design contract** and apply when extending Aura or building one-off interactives.
 
@@ -989,7 +2434,7 @@ Keyboard or assistive tech has moved focus to the element. This is the main non-
 - **Must** use Aura’s **token-based focus ring** — `shadow-focus-ring` (CSS variable `--shadow-focus-ring`, composed from `ring` + `ring-muted` tokens) for default controls, and **`shadow-focus-ring-destructive`** / `--shadow-focus-ring-destructive` for invalid or destructive fields. Shared utilities in the library pair `outline-none` **with** these rings on `:focus-visible` — never `outline-none` or `ring-0` **alone**.
 - **Must** meet **WCAG AA** for the focus indicator against its immediate background.
 - **Should** use **`:focus-visible`** (or library equivalents) so pointers do not get a keyboard ring on every click, while keyboard users always see one.
-- **Invalid inputs:** on focus, use the **destructive** focus ring token pair above (see **Tokens → Effects → Focus rings**).
+- **Invalid inputs:** on focus, use the **destructive** focus ring token pair above (see **Elevation & Depth → Focus rings**).
 
 ### Disabled
 
@@ -1009,7 +2454,7 @@ Persistent **on/off**, **selected**, **active filter**, or **applied setting** u
 
 **Guidance**
 
-- **Must** use **`active-background`** / **`active-background-hover`** or **`active-muted-background`** / **`active-muted-background-hover`** (and matching foreground tokens such as **`foreground-on-active`**, **`active-foreground`**) — **not** semantic status colors (`info-*`, `success-*`, …) for generic toggles.
+- **Must** use **`active-background`** / **`active-background-hover`** or **`active-muted-background`** / **`active-muted-background-hover`** (and matching foreground tokens such as **`foreground-on-active`**, **`active-foreground`**) — **not** semantic status colors (`info-`*, `success-`*, …) for generic toggles.
 - **Must not** rely on **color alone** — combine fill with icon, checkmark, label, or border treatment where the pattern is ambiguous.
 - **Must** implement **hover**, **pressed**, and **focus** for the **selected** variant as well as the default variant when both exist.
 - **Must not** show “selected” visuals for controls that are not actually in a selected state.
@@ -1028,184 +2473,253 @@ Work is **in progress**; the control or region may be temporarily inert or show
 
 ## Content
 
-**What this section is:** Conventions for **UI copy** — standardized action labels, date and time presentation, grammar and style, localization, voice and tone, and writing that supports accessibility. Use it with **Heuristics** (especially feedback, labels, and §7 accessibility) when designing or implementing strings in Aura-based surfaces.
+**What this section is:** Conventions for **Fusion monorepo UI copy** in Aura-based surfaces: action labels, date and time presentation, grammar and style, localization, voice and tone, and writing that supports accessibility. Use it with **Heuristics** and **Interaction states** when designing or implementing strings.
 
 **Who:** Designers, product writers, engineers, and agents generating microcopy.
 
-**Scope:** English product UI for Cognite Data Fusion experiences unless a feature explicitly ships localized strings; numeric date order and clocks follow user or tenant preferences via the platform **dateTime** configuration. For **customer-visible** strings, follow the approved **product terminology** glossary (do not use internal codenames in place of customer-facing names). UI microcopy should **avoid** spelling out “Cognite Data Fusion” where products may be white-labeled — use neutral terms (“the application”, feature names) when context allows.
-
----
-
-### Action labels
-
-Users predict behavior from **consistent verbs**. Action labels use **sentence case** (e.g. “Edit model”).
-
-**Must not** use **Confirm** as the primary action — name the outcome (**Delete**, **Save**, **Send**, …). **Must** use **Sign in** and **Sign out**; **must not** use “Log in” / “Log out” in UI.
-
-**Avoid** a labeled **Close** action **alongside** **Cancel** or a **Confirm**-labeled button in the same surface — use **Cancel** to abandon without applying, the **outcome verb** for commit, and/or icon-only dismiss per pattern library.
-
-| Label | Use |
-| :--- | :--- |
-| **Add** | Attach an existing object to a new context (e.g. add to canvas). |
-| **Apply** | Commit filters or settings so they drive subsequent behavior. |
-| **Approve** | User agrees; in workflows, usually advances the process. |
-| **Back** | Previous step in a sequence or hierarchy. |
-| **Browse** | Structured scanning (categories, menus, filters). |
-| **Cancel** | Stop the current action and dismiss the surface; warn if stopping risks data loss. |
-| **Clear (all)** | Clear fields or selections; restore default where a control always has a value (e.g. radio). |
-| **Close** | Close a page, pane, or window (often icon-only). |
-| **Collapse** / **Expand** | Hide or show a panel (often icon-only). |
-| **Copy** | Copy to clipboard for use elsewhere. |
-| **Create** | New object from nothing (vs **Add** / **Duplicate**). |
-| **Delete** | Permanently remove the object. |
-| **Discard** | Abandon unsaved draft or edits. |
-| **Download** / **Upload** | Transfer file remote → local / local → remote. |
-| **Duplicate** | Copy in the same location as the original. |
-| **Edit** | Change data or values. |
-| **Explore** | Open-ended discovery without a fixed goal. |
-| **Export** | Save in an external format (often via a secondary step for type and destination). |
-| **Finish** | Complete a multi-step flow (e.g. wizard). |
-| **Hide** / **Show** | Toggle visibility in the UI only (not delete). |
-| **Import** | Bring data in from an external source. |
-| **Insert** | Place at a position in an ordered structure (e.g. table row). |
-| **Next** | Advance one step in a sequence. |
-| **Open** | **Internal:** drawer, modal, or in-app route (support open-in-new-tab where appropriate). **External:** new tab/window for external URLs. |
-| **Publish** / **Unpublish** | Make content available to intended audiences / remove from public view without deleting. |
-| **Query** | Request specific data from a store or service. |
-| **Redo** / **Undo** | Redo reverses undo; undo steps back through user edits (not all actions are undoable). |
-| **Refresh** | Reload when the view may be stale. |
-| **Register** | Create an account or enroll a user (prefer over “Sign up” where it could be confused with **Sign in**). |
-| **Reject** | User does not approve; in workflows, usually blocks progression. |
-| **Remove** | Remove from current context without destroying the object. |
-| **Reset** | Revert to last saved or default values. |
-| **Restore** | Revert to last saved version. |
-| **Save** | Persist changes without closing the surface. |
-| **Search** | Goal-oriented lookup. |
-| **Select** | Pick from a set of options. |
-| **Sign in** / **Sign out** | Authenticate / end session. |
-| **View** | Show details or properties (read-heavy). |
-
----
-
-### Date and time formatting
+**Scope:** English UI strings authored in the Fusion monorepo unless a feature explicitly ships localized strings. Numeric date order and clocks follow the host platform `dateTime` configuration. Product naming, white-labeling policy, and market-facing terminology are owned by product documentation and brand guidance; this section covers in-product microcopy patterns that Aura surfaces should follow.
 
-**Defaults:** Respect user or product **dateTime** configuration (CDF preferences where applicable). **Read-only** stamps (lists, headers, audit) follow these guidelines; **input** fields and pickers follow component behavior and the same provider unless an exceptional case is documented.
+### Role
 
-**Dimensions**
+You are writing interface copy for Fusion applications. Every string must be purposeful, concise, conversational, and clear. Identify the target audience persona before writing; the persona determines reading level, technical vocabulary, and tone.
 
-| Concept | Meaning |
-| :--- | :--- |
-| **Read-only vs input** | Read-only is display-only; input uses pickers/fields — both should stay consistent within a feature. |
-| **Full vs abbreviated** | Full (“2 January 2023”, “6 hours 7 minutes”) vs short (“2 Jan 2023”, “6 hr 7 min”). Prefer abbreviated only when space is tight. |
-| **Absolute vs relative** | Absolute = calendar date/time of the event; relative = “32 min ago”. |
+For code-level accessibility (keyboard navigation, ARIA, focus, headings, live regions), see `handling-states.md`.
 
-**Must** prefer **written** month forms over numeric dates when readability matters across locales. **Must** stay consistent within the same feature for format style. **Must** use **absolute** timestamps when the event is **more than 24 hours** in the past or future; **should** use **relative** timestamps within **24 hours** before/after “now” (either can be full or abbreviated).
+### Audience personas
 
-**Time**
+Canonical persona definitions live in the cogdocs repository (`cogdocs/cogdocs-metadata.mdx`, **Audience** section). This summary covers what matters for microcopy decisions.
 
-- **Must** follow user preference for **12-** vs **24-hour** clock; 12-hour **must** include **AM** / **PM** (uppercase, no periods, space before suffix: `3:00 PM`).
-- **Must** use **UTC** (not GMT) when a zone label is required; do not spell out “UTC” unless prose clarity needs it. **Must not** ask users to hand-convert zones — the application converts.
+| 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                     |
 
-**Dates and combined date-time**
+**Reading level:** Low = 7th–8th grade; Mid = 9th–10th grade; High = 10th–11th grade.
 
-- **Must** include the **year** unless context makes it obvious (e.g. chart titled by year).
-- **Must not** use **ordinal** day forms (“1st”, “23rd”) in UI dates.
-- If numeric dates are required, **should** use **`/`** separators, zero-pad single-digit days/months, and include the year; stay consistent across the feature.
-- For combined date + time in prose, **should** separate with **“at”** or an unambiguous pattern; **must** keep date and time ordering consistent.
+When the persona is unknown, default to plain language and outcomes.
 
-**Ranges**
-
-- **Time range:** same style at start and end; on 12-hour clocks, repeat **AM**/**PM** only when needed for clarity (single meridiem can use one suffix; cross-midnight or long ranges may need both date and meridiem on each end).
-- **Date range:** consistent formatting; **avoid** dense numeric ranges that are hard to parse.
-- **Date-time range:** date first, then time; include year unless context suffices; for 12-hour + range, **must** label **AM**/**PM** clearly on both ends when ambiguity is likely.
-
-**Duration** (elapsed length, not a clock range)
-
-- **Should** express duration when elapsed length matters more than endpoints.
-- No “relative” phrasing for duration lists.
-- **Should** use a **space** between number and unit in body text and tables (`3 seconds`); compact controls may omit the space per component spec.
-- **Should** avoid commas between compound units (`10 minutes 3 seconds` not `10 minutes, 3 seconds`).
-- For sub-second precision, **should** use decimals (`2.5 seconds`) or round to a meaningful whole unit to reduce noise.
-
-**Abbreviations** (lowercase units except proper nouns like **Jan**, **Mon**; no periods on abbreviations)
-
-| Full (examples) | Abbreviated |
-| :--- | :--- |
-| millisecond(s), second(s), minute(s), hour(s) | ms, s, min, hr |
-| day(s), week(s), month(s), year(s) | d, wk, mo, yr |
-
-Days and months: **Monday** → **Mon**, **January** → **Jan**, etc.; capitalize; allow width for **four-letter** abbreviations where internationalization may need it.
+### Voice and tone
 
-**Scheduled automation:** use **cron** expressions where users define recurring runs.
+Voice is consistent; tone adapts to the user's emotional state.
 
----
+| Scenario                | Tone                      | Example                                                                        |
+| ----------------------- | ------------------------- | ------------------------------------------------------------------------------ |
+| First-time onboarding   | Friendly, welcoming       | "Let's get started. Your workspace 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
 
-**Must** use **American English** in UI (`color`, `center`, `organization`, …). **Must** use **sentence case** for UI phrases; **must not** use **ALL CAPS** for body labels.
-
-**Should** prefer **active voice**; use passive only for objectivity or legal emphasis.
-
-**Numbers:** use **numerals** for all magnitudes in UI (`6 queries per second`, `50 Mbps`). **Should** use a **non-breaking space** between a number and its unit where line breaks would confuse.
-
-**Abbreviations:** spell out when possible; **avoid** Latin shortcuts (“e.g.”, “etc.”) — use “for example”, “and more”, or recast the sentence.
+#### Language and capitalization
 
-**Punctuation**
+- **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: Fusion, OPC-UA, Aura.
+- **No all-caps**
+- **No internal codenames** in customer-facing UI copy; use the feature or resource name users recognize.
 
-- **Avoid** terminal periods on short labels, tooltips, and single-line list items.
-- **Must** use periods for **multi-sentence** blocks and dense prose.
-- **Avoid** exclamation marks in default UI; use **ellipses** sparingly for in-progress or truncated text.
-- **Should** use the **Oxford comma** in lists.
-- **Avoid** ampersands (`&`) in translatable UI — use **and**.
+#### Numbers and units
 
-**Pronouns and point of view:** **must not** mix **my** and **your** in the same flow; **should** minimize “we” / “I” for the product voice — prefer the user’s perspective and **should** align with the approved product glossary (e.g. “My data” vs neutral labels).
+- **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
 
-**Plural forms:** **avoid** “(s)” or “(es)” in labels — use separate strings or unambiguous copy per locale.
+#### Abbreviations and punctuation
 
----
-
-### Localization
+- 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
 
-Strings ship through translation workflows (e.g. **Locize**); follow platform developer documentation for keys and context.
+#### Pronouns
 
-**Must** ship source English without spelling or grammar errors. **Should** use **short**, simple sentences (one idea per sentence) and **consistent** word order and capitalization for easier translation. **Should** include “small grammar words” (**a**, **the**, **is**) in prose; labels may omit them only when space is critical.
+- 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
 
----
-
-### Voice and tone
-
-**Voice** stays consistent; **tone** shifts with context (onboarding vs error vs success).
-
-**Should** lead with the user’s **intent** and **task**; use **plain**, customer vocabulary; stay **concise** and **scannable** (headings first, steps chunked; prefer visuals over long notes).
-
-**Should** acknowledge friction honestly where UX is rough; keep disclaimers minimal.
-
-| Scenario | Tone | Example |
-| :--- | :--- | :--- |
-| First-time onboarding | Friendly, welcoming | “Let’s get started — you’re ready when you are.” |
-| Technical flows | Clear, direct | “Configure your endpoint and authenticate with your API key.” |
-| Errors | Empathetic, constructive | “Something went wrong. Try refreshing or check your connection.” |
-| Success | Brief, positive | “Your data is now flowing.” |
-| Tours / help | Conversational | “Want a quick tour? We’ll cover the essentials in under two minutes.” |
-
-Align microcopy with the same **product terminology** glossary referenced in **Grammar and style**.
+### Action labels
 
----
+Use sentence case with an object: "Edit model", "Delete asset".
 
-### Writing for accessibility
+#### Approved labels
 
-Structural accessibility (focus, contrast, semantics, targets) lives in **Heuristics §7** and **Interaction states**. This subsection is **copy-specific**.
+| 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."
+- "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](mailto: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
 
-**Must** write **icon** `alt` / accessible names that state **intent** (“Download PDF”), not appearance (“disk icon”). **Must** provide **alt text** for informative images; **must** use empty alt for **decorative** images only.
+### Date and time formatting
 
-**Must** make **link text** describe the destination or outcome (“Learn about pricing”), not “click here” or bare “read more”.
+- **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")
 
-**Should** use **headings** and **lists** so screen reader users can skim; for **charts** or complex figures, repeat key insights in adjacent text, not only in the graphic.
+**Time unit abbreviations** (no periods; same form singular/plural):
+ms, s, min, hr, d, wk, mo, yr
 
-**Should** avoid **this** / **that** without a clear noun referent.
+**Day abbreviations** (3 chars for i18n):
+Mon, Tue, Wed, Thu, Fri, Sat, Sun
 
-**Should** describe **data trends** in words when the UI relies on charts or color alone.
+**Month abbreviations** (4 chars for i18n):
+Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
 
-**Must** use **Select** (or “choose”, “turn on”) rather than **Click** in instructions — not all users use a pointer.
+### 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
+- Short sentences and simple grammar translate more reliably; plan for text expansion in localized UI (e.g. German often adds 30–40% length) with flexible button and title widths, not fixed ones
+
+### 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 |