@cognite/aura 0.2.0 → 0.3.1

package/DESIGN.md

@@ -1,742 +1,575 @@
-## 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.
-
-**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.
-
-**Where the CSS sources live**
-
-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.
-
-**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)**.
-
-## Dashboard quick start (agent checklist)
-
-For pages with data-heavy layouts — cards, charts, metric tiles — work through these steps before writing component code.
-
-- [ ] **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).
-
 ---
-
-## Heuristics
-
-**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**).
-
-**Who:** Designers reviewing UI, engineers implementing features, agents generating or auditing code.
-
-**Scope — two layers**
-
-- **`@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.
-
+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}'
 ---
 
-### 1. Feedback and system status
-
-Users **must** always know what changed: loading, success, failure, or background work needs a visible signal.
-
-#### 1.1 Loading states
-
-**Applies when:** Data fetch, async work, route transition, or slow AI step blocks meaningful UI.
-
-**Aura components:** `Shimmer`, `Loader`, `Progress`, `Skeleton`
-
-**Rules**
-
-- **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**.
-
-#### 1.2 Action confirmation
-
-**Applies when:** User actions mutate state (save, submit, delete, copy, send).
-
-**Aura components:** `Dialog` (+ destructive **Button**), `Alert`, `Tooltip`, `Banner`  
-**App / shell:** Sonner (or equivalent toast), dedicated confirm **AlertDialog** where the shell provides it
-
-**Rules**
-
-- **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.
-
-#### 1.3 System status visibility
-
-**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.
-
-**Aura components:** `Alert`, `Badge`, `Banner`, `Loader` (see §1.1)  
-**App:** `Sonner` for ephemeral global notices
-
-**Rules**
-
-- **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.
-
-### 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, or editable.
-
-#### 2.1 Interactive signifiers
-
-**Applies when:** Click, drag, expand, or edit.
-
-**Aura components:** `Button`, `DropdownMenu`, `Collapsible`, `Accordion`, `Select`, `Command`
-
-**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.
-
-#### 2.2 Labels and recognizable patterns
-
-**Applies when:** Forms, navigation, empty views, search.
-
-**Aura components:** `Label`, `Input`, `Textarea`, `Select`, `Card`, `Command` / `CommandInput`
-
-**Rules**
-
-- **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).
-
-#### 2.3 Contextual help
-
-**Applies when:** Non-obvious behavior, format rules, or icon-only controls.
-
-**Aura components:** `Tooltip`, `Popover`, `HelperText`, `HoverCard`
-
-**Rules**
-
-- **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.
-
----
-
-### 3. Progressive disclosure
-
-Introduce complexity only when needed; default views **should** stay scannable.
-
-#### 3.1 Collapsible content
-
-**Applies when:** Secondary detail, advanced settings, or optional blocks.
-
-**Aura components:** `Accordion`, `Collapsible`, `Dialog`, `Popover`  
-**App:** `Sheet`, `Drawer` where the shell provides them — still use Aura tokens
-
-**Rules**
-
-- **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.
+## Overview
 
-#### 3.2 Multi-step flows
+Aura is the official design system for Cognite experiences: composable UI primitives for data-heavy industrial software.
 
-**Applies when:** Three or more steps or grouped data entry.
+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.
 
-**Aura components:** `Dialog`, `Progress`, `Button`, `Separator`
+Light and dark themes share the same semantic roles; fixed tokens support persistent shell chrome.
 
-**Rules**
+**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>}`.
 
-- **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.
+**Implementation:** Package imports, component APIs, and host-shell integration live in the Aura [README](./README.md) — not in this file.
 
-#### 3.3 Contextual menus and secondary actions
+### For agents: how to read this file
 
-**Applies when:** Per-row or per-object actions should stay out of the default chrome.
+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:
 
-**Aura components:** `DropdownMenu`, `Button` (kebab trigger), `ButtonGroup`  
-**App:** `ContextMenu` — same grouping and token rules
+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.
 
-**Rules**
+### Alignment with Google design.md
 
-- **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.
+| 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 |
 
 ---
 
-### 4. Error handling and prevention
+## Colors
 
-Errors **should** be prevented; when they happen, users **must** understand cause and recovery.
+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.
 
-#### 4.1 Destructive action prevention
+Use **Base** color for the operating surface: page backgrounds, cards, text, borders, focus, and persistent chrome. This is ~80–90% of the UI.
 
-**Applies when:** Delete, archive, reset, overwrite, disconnect, or other irreversible commits.
+Use **Semantic** color only for status and feedback: info, success, warning, destructive, validation, and operational state. This is ~5–10% of the UI.
 
-**Aura components:** `Dialog`, `Alert`, `Banner`, `Button` (`destructive`)  
-**App:** `AlertDialog` / confirm flow where supplied by shell
+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.
 
-**Rules**
+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.
 
-- **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.
+Do not hardcode hex, font sizes, or shadow strings in product UI when a token exists.
 
-#### 4.2 Form validation
+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.
 
-**Applies when:** Any `Input`, `Textarea`, `Select`, or similar field.
+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.
 
-**Aura components:** `Input`, `Textarea`, `Select`, `InputGroup`, `HelperText`, `Label`
-
-**Rules**
-
-- **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.
-
-#### 4.3 Auto-save and data loss prevention
-
-**Applies when:** Edits would be lost on navigation or timeout.
-
-**Aura components:** `Banner`, `Badge`, `Dialog`  
-**App:** Sonner for “Saved” pulse
+### Common Tailwind mappings
 
-**Rules**
+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                       |
 
-- **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.
+Also generated: `ring-destructive`, `ring-destructive-muted` for destructive / invalid focus (see **Effects — Focus rings**).
 
-#### 4.4 Recovery and undo
+### Semantic colors
 
-**Applies when:** User mutates or removes content.
+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.
 
-**Aura components:** `Dialog`  
-**App:** Sonner with undo
+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.
 
-**Rules**
+**Info**
 
-- **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).
+| 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 |
 
----
+**Success**
 
-### 5. Enabling power users
+| 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` |
 
-Experts **should** move faster without harming first-time clarity.
+**Warning**
 
-#### 5.1 Keyboard shortcuts
+| 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                 |
 
-**Applies when:** High-frequency actions (save, search, command palette, AI trigger).
+**Destructive**
 
-**Aura components:** `Command`, `CommandShortcut`, `DropdownMenuShortcut`, `Tooltip`
+| 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`            |
 
-**Rules**
+**Neutral** (status: draft, archived — not “semantic calm” in the same sense as info/success)
 
-- **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.
+| 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           |
 
-#### 5.2 Bulk actions
+**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.
 
-**Applies when:** Lists or tables with repeated items.
+### Decorative colors
 
-**Aura components:** `DropdownMenuCheckboxItem`, `Button`, `ButtonGroup`, `Badge`, `Banner`  
-**App:** table selection, **ActionToolbar** pattern
+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}`.
 
-**Rules**
+**Preference order for new work:**
 
-- **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).
+| 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` |
 
-#### 5.3 Onboarding and learnability
+Example (fjord ramp): light `decorative-background-fjord` → `#CCD5FA` (fjord-200), `decorative-foreground-fjord` → `#1234B6` (fjord-700); dark → `#AEBDF7` / `#0D2582` (fjord-300 / fjord-800).
 
-**Applies when:** First-use, empty data, or role-gated features.
+### Chart tokens
 
-**Aura components:** `Card`, `Button`, `Tooltip`, `HelperText`, `Banner`, `Message`
+**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.
 
-**Rules**
+| Token                                           | Use                                                         |
+| ----------------------------------------------- | ----------------------------------------------------------- |
+| `chart-{ramp}-color-1` … `chart-{ramp}-color-6` | Alpha-based series / area-fill steps (strongest → lightest) |
+| `chart-gridlines`                               | Grid lines                                                  |
 
-- **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.
+Default series order: **fjord → nordic → aurora → dusk → orange**.
 
 ---
 
-### 6. Layout and hierarchy
-
-Information **must** be scannable and oriented before action.
-
-#### 6.1 Grouping and proximity
-
-**Applies when:** Forms, settings, detail layouts.
-
-**Aura components:** `Card`, `InputGroup`, `Accordion`, `Separator`, `Label`
-
-**Rules**
-
-- **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.
-
-#### 6.2 Persistent actions and navigation
-
-**Applies when:** Global vs page-local actions.
-
-**Aura components:** `Button`, `DropdownMenu`  
-**Fusion shell:** `Topbar`, `Tabs`, `SegmentedControl` — follow shell **SKILL** / **RULES** where your repo defines them
-
-**Rules**
-
-- **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.
-
-#### 6.3 Visual hierarchy
-
-**Applies when:** Any view with competing focal points.
-
-**Aura components:** `Button`, `Badge`, `Alert`, `Label`
-
-**Rules**
-
-- **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.
-
-#### 6.4 Responsive behaviour
+## Typography
 
-**Applies when:** Viewport spans tablet / desktop / embedded shell widths.
+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}`.
 
-**Aura components:** `Card`, `Dialog`, `DropdownMenu`  
-**Fusion shell:** `Topbar` overflow behavior
+| 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             |
 
-**Rules**
+**Type scale** — values live in the YAML `typography` tokens. Typical **semantic styles** map as follows:
 
-- **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.
+| 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        |
 
 ---
 
-### 7. Accessibility and inclusive design
-
-Aura targets **WCAG AA** for primitives — usage must preserve that.
-
-#### 7.1 Keyboard accessibility
-
-**Applies when:** Any interactive **Aura** component or custom control.
-
-**Rules**
-
-- **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.
-
-#### 7.2 Color contrast and readability
+## Layout
 
-**Applies when:** Text, icons, or controls on colored surfaces.
+### Dashboard quick start (agent checklist)
 
-**Rules**
-
-- **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.
-
-#### 7.3 ARIA and semantic markup
-
-**Applies when:** Composing Aura primitives or wrapping native elements.
-
-**Rules**
-
-- **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.
-
-#### 7.4 Touch and click targets
-
-**Applies when:** Touch or motor accessibility matters.
-
-**Rules**
+For pages with data-heavy layouts — cards, charts, metric tiles — work through these steps before writing component code.
 
-- **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.
+- [ ] **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).
 
-### Common pitfalls (agent guidance)
+### Layout and spacing
 
-These are the most frequent mistakes when generating or modifying Aura-based UI. Avoid all of them.
+Width and spacing values in this subsection follow the **`{spacing.base}`-based** spacing scale in **[Layout → Size and dimensions](#size-and-dimensions)**.
 
-**Raw hex or hardcoded colors**
+**Body text reading width**
 
-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.
+- **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.
 
-**Overriding style tokens or component styles**
+### Size and dimensions
 
-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.
+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:
 
-**Duplicate or parallel navigation**
+| 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                |
 
-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.
+Layout helpers in theme: `--container-2xl` (`{spacing.container-2xl}`), `--container-8xl` (`{spacing.container-8xl}`), `--message-content-max-width` (80% for chat content).
 
-**Overly dense card layouts**
+### Width and max content
 
-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.
+Aura adjusts Tailwind **container** breakpoints where the default scale is too wide or too narrow for data-dense product surfaces:
 
-**Mixing chart, decorative, and semantic color tokens**
+| 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                                                                                                               |
 
-`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.
+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.
 
-**Icon-only controls without accessible names**
+### Specialized variables
 
-Every icon-only Button must have `aria-label` and a `Tooltip`. Do not rely on visual context alone.
+| 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      |
 
-**Disabled primary CTA with no resolution path**
+### Regional spacing
 
-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.
+- **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
 
-### For `llms.txt` / agent exports
+- **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.
 
-When splitting or stripping this doc for agents:
+### Shell vs content
 
-- 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**.
+**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.
 
 ---
 
-## Tokens
-
-**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.
-
-**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.
-
-**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.
-
-### Common Tailwind mappings
-
-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 |
-
-Also generated: `ring-destructive`, `ring-destructive-muted` for destructive / invalid focus (see **Effects — Focus rings**).
-
-#### Semantic colors
-
-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.
-
-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.
-
-**Info**
-
-| 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 |
-
-**Success**
-
-| 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` |
-
-**Warning**
-
-| 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 |
-
-**Destructive**
-
-| 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` |
-
-**Neutral** (status: draft, archived — not “semantic calm” in the same sense as info/success)
-
-| 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 |
-
-**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.
-
-#### Decorative colors
-
-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}`.
-
-**Preference order for new work:**
-
-| 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). Every ramp resolves in [`src/colors.css`](./src/colors.css).
-
-#### Chart tokens
+## Elevation & Depth
 
-**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.
+### Shadows
 
-| Token | Use |
-| :--- | :--- |
-| `chart-{ramp}-color-1` … `chart-{ramp}-color-6` | Alpha-based series / area-fill steps (strongest → lightest) |
-| `chart-gridlines` | Grid lines |
+`--effect-shadow-sm` through `--effect-shadow-xl` are **alpha blacks** tuned per theme. Tailwind shadow utilities compose layered stacks from these tokens:
 
-Default series order: **fjord → nordic → aurora → dusk → orange**.
+| 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         |
 
----
+Exact pixel stacks are defined in the theme CSS alongside `--shadow-sm` … `--shadow-xl`.
 
-### Typography
+### Focus rings
 
-Aura uses three **font families** (loaded in [`src/styles.source.css`](./src/styles.source.css)):
+Shadow-based (not `outline`) for consistent rendering:
 
-| 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 |
+| 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           |
 
-**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):
+### Opacity
 
-| 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 |
+| 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**              |
 
 ---
 
-### Size and dimensions
-
-Aura aligns to a **4px base grid**. Spacing in components follows **Tailwind spacing** (`p-*`, `gap-*`, `m-*`): one unit = **4px** unless overridden. Common steps:
-
-| 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 |
-
-Layout helpers in theme: `--container-2xl` (40rem), `--container-8xl` (96rem), `--message-content-max-width` (80% for chat content).
-
-#### Component heights
-
-Heights are **not** always single CSS variables; primitives use Tailwind height utilities. Representative values from core components:
-
-| 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`) |
-
-**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.
-
----
+## Shapes
 
 ### Corner radius
 
-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 |
+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}`).
 
----
+| 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                                                 |
 
-### Border
+### Borders
 
 Aura is visually **flat**; surfaces, spacing, and typography do most structure. Add borders only when separation or affordance needs extra clarity.
 
@@ -748,105 +581,65 @@ Aura is visually **flat**; surfaces, spacing, and typography do most structure.
 - **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 |
+| 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                                                                |
 
 ---
 
-### Effects
-
-#### Shadows
+## Components
 
-`--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:
+### Component heights
 
-| 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 |
-
-Exact pixel stacks: `--shadow-sm` … `--shadow-xl` in [`src/styles.source.css`](./src/styles.source.css).
-
-#### Focus rings
-
-Shadow-based (not `outline`) for consistent rendering:
-
-| 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 |
-
-#### Opacity
-
-| 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** |
+Heights are **not** always single CSS variables; primitives use Tailwind height utilities. Representative values from core components:
 
-#### Motion (reference)
+| 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`               |
 
-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.
+**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.
 
 ---
 
-### Layout and spacing
-
-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)**.
-
-**Body text reading width**
-
-- **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.
-
-### Width and max content
-
-Aura adjusts Tailwind **container** breakpoints where the default scale is too wide or too narrow for Fusion-style surfaces:
-
-| 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 |
+## Do's and Don'ts
 
-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.
+Practical guardrails for Aura-based UI. For full rationale, see [Heuristics](#heuristics), [Interaction states](#interaction-states), and [Content](#content).
 
+### Do
 
-### 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
+- 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.
 
-- **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.
+### Don't
 
-### 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
-
-**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.
+- 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 +733,156 @@ 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.
+
+---
+
+### 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.
+- **Avoid** using toast as the only safety net for irreversible work or revealing every validation error only on final submit.
+
+---
+
+### 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.
+- **Avoid** pointer-only behavior, unreadable `muted-foreground` copy for required tasks, and sub-24px icon hit zones without expansion.
+
+### 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.
+
 ---
 
 ## 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 +920,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 +940,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 +959,252 @@ 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
-
-**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.
-
-**Dimensions**
-
-| 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”. |
-
-**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).
+**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.
 
-**Time**
+### Role
 
-- **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.
+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.
 
-**Dates and combined date-time**
+For code-level accessibility (keyboard navigation, ARIA, focus, headings, live regions), see `handling-states.md`.
 
-- **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.
+### Audience personas
 
-**Ranges**
+Canonical persona definitions live in the cogdocs repository (`cogdocs/cogdocs-metadata.mdx`, **Audience** section). This summary covers what matters for microcopy decisions.
 
-- **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.
+| 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                     |
 
-**Duration** (elapsed length, not a clock range)
+**Reading level:** Low = 7th–8th grade; Mid = 9th–10th grade; High = 10th–11th grade.
 
-- **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.
+When the persona is unknown, default to plain language and outcomes.
 
-**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.
+#### Language and capitalization
 
-**Abbreviations:** spell out when possible; **avoid** Latin shortcuts (“e.g.”, “etc.”) — use “for example”, “and more”, or recast the sentence.
+- **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.
 
-**Punctuation**
+#### Numbers and units
 
-- **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**.
+- **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
 
-**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).
+#### Abbreviations and punctuation
 
-**Plural forms:** **avoid** “(s)” or “(es)” in labels — use separate strings or unambiguous copy per locale.
+- 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
 
----
-
-### Localization
+#### Pronouns
 
-Strings ship through translation workflows (e.g. **Locize**); follow platform developer documentation for keys and context.
-
-**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
+
+### 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 |