@cognite/aura 0.1.6 → 0.1.7

package/DESIGN.md

@@ -0,0 +1,1269 @@
+## 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://cognitedata.github.io/aura/storybook)) 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://cognitedata.github.io/aura/storybook) 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))]`. See [Grids and layouts](#grids-and-layouts) and [Storybook grid patterns](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference).
+- [ ] **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://cognitedata.github.io/aura/storybook)). **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.
+
+---
+
+### 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.
+
+#### 3.2 Multi-step flows
+
+**Applies when:** Three or more steps or grouped data entry.
+
+**Aura components:** `Dialog`, `Progress`, `Button`, `Separator`
+
+**Rules**
+
+- **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.
+
+#### 3.3 Contextual menus and secondary actions
+
+**Applies when:** Per-row or per-object actions should stay out of the default chrome.
+
+**Aura components:** `DropdownMenu`, `Button` (kebab trigger), `ButtonGroup`  
+**App:** `ContextMenu` — same grouping and token rules
+
+**Rules**
+
+- **Must** use **DropdownMenu** for action lists anchored to a trigger (e.g. “More”).
+- **Must** scope menu items to the entity they affect — do not mix unrelated global actions into an item menu.
+- **Should** use **ButtonGroup** for a small persistent contextual action cluster.
+- **Avoid** long flat menus of **more than ~7** items without **DropdownMenuGroup** / separators / submenus.
+
+---
+
+### 4. Error handling and prevention
+
+Errors **should** be prevented; when they happen, users **must** understand cause and recovery.
+
+#### 4.1 Destructive action prevention
+
+**Applies when:** Delete, archive, reset, overwrite, disconnect, or other irreversible commits.
+
+**Aura components:** `Dialog`, `Alert`, `Banner`, `Button` (`destructive`)  
+**App:** `AlertDialog` / confirm flow where supplied by shell
+
+**Rules**
+
+- **Must** confirm high-impact destructive actions in a **Dialog** (or **AlertDialog**) **before** execution.
+- **Must** name what will be destroyed — not generic “Are you sure?”.
+- **Must** label the confirm action with a **specific verb** (“Delete report”), not “OK”.
+- **Should** use **Button** `variant="destructive"` for the confirming destructive action.
+- **Avoid** toast as the **only** safety net for irreversible work.
+
+#### 4.2 Form validation
+
+**Applies when:** Any `Input`, `Textarea`, `Select`, or similar field.
+
+**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
+
+**Rules**
+
+- **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.
+
+#### 4.4 Recovery and undo
+
+**Applies when:** User mutates or removes content.
+
+**Aura components:** `Dialog`  
+**App:** Sonner with undo
+
+**Rules**
+
+- **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).
+
+---
+
+### 5. Enabling power users
+
+Experts **should** move faster without harming first-time clarity.
+
+#### 5.1 Keyboard shortcuts
+
+**Applies when:** High-frequency actions (save, search, command palette, AI trigger).
+
+**Aura components:** `Command`, `CommandShortcut`, `DropdownMenuShortcut`, `Tooltip`
+
+**Rules**
+
+- **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.
+
+#### 5.2 Bulk actions
+
+**Applies when:** Lists or tables with repeated items.
+
+**Aura components:** `DropdownMenuCheckboxItem`, `Button`, `ButtonGroup`, `Badge`, `Banner`  
+**App:** table selection, **ActionToolbar** pattern
+
+**Rules**
+
+- **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).
+
+#### 5.3 Onboarding and learnability
+
+**Applies when:** First-use, empty data, or role-gated features.
+
+**Aura components:** `Card`, `Button`, `Tooltip`, `HelperText`, `Banner`, `Message`
+
+**Rules**
+
+- **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.
+
+---
+
+### 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
+
+**Applies when:** Viewport spans tablet / desktop / embedded shell widths.
+
+**Aura components:** `Card`, `Dialog`, `DropdownMenu`  
+**Fusion shell:** `Topbar` overflow behavior
+
+**Rules**
+
+- **Should** verify layouts at common widths (e.g. 768 / 1024 / 1440px) when shipping responsive surfaces (see **[Grids and layouts](#grids-and-layouts)**).
+- **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.
+
+---
+
+### 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
+
+**Applies when:** Text, icons, or controls on colored surfaces.
+
+**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**
+
+- **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.
+
+### Common pitfalls (agent guidance)
+
+These are the most frequent mistakes when generating or modifying Aura-based UI. Avoid all of them.
+
+**Raw hex or hardcoded colors**
+
+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.
+
+**Overriding style tokens or component styles**
+
+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.
+
+**Duplicate or parallel navigation**
+
+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.
+
+**Overly dense card layouts**
+
+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.
+
+**Mixing chart, decorative, and semantic color tokens**
+
+`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.
+
+**Icon-only controls without accessible names**
+
+Every icon-only Button must have `aria-label` and a `Tooltip`. Do not rely on visual context alone.
+
+**Disabled primary CTA with no resolution path**
+
+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.
+
+---
+
+### For `llms.txt` / agent exports
+
+When splitting or stripping this doc for agents:
+
+- 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://cognitedata.github.io/aura/storybook). 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**.
+
+---
+
+## 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-solid`, `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` | `rgba(2, 6, 23, 0.2)` | `rgba(226, 232, 240, 0.2)` | 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` | `#BBC0C4` | `#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-critical`, `ring-critical-shadow` 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` | `#E19E00` | `#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-{ramp}-background`, `decorative-{ramp}-background-hover`, `decorative-{ramp}-foreground`.
+
+**Preference order for new work:**
+
+| Priority | Ramp | Background | Foreground |
+| :---: | :--- | :--- | :--- |
+| 1 | Fjord | `decorative-fjord-background` | `decorative-fjord-foreground` |
+| 2 | Nordic | `decorative-nordic-background` | `decorative-nordic-foreground` |
+| 3 | Aurora | `decorative-aurora-background` | `decorative-aurora-foreground` |
+| 4 | Dusk | `decorative-dusk-background` | `decorative-dusk-foreground` |
+| 5 | Orange | `decorative-orange-background` | `decorative-orange-foreground` |
+| 6 | Sky | `decorative-sky-background` | `decorative-sky-foreground` |
+| 7 | Mountain | `decorative-mountain-background` | `decorative-mountain-foreground` |
+
+Example (fjord ramp): light `decorative-fjord-background` → `#CCD5FA` (fjord-200), `decorative-fjord-foreground` → `#1234B6` (fjord-700); dark → `#AEBDF7` / `#0D2582` (fjord-300 / fjord-800). Every ramp resolves in [`src/colors.css`](./src/colors.css).
+
+#### Chart tokens
+
+**Priority rule:** use `chart-*` for any data plotted on axes or series; use `decorative-*` for non-data visual differentiation (tiles, avatars, accents); use semantic tokens (`info-*`, `success-*`, `warning-*`, `destructive-*`) for operational status and feedback only. Never swap between these groups.
+
+| Token | Use |
+| :--- | :--- |
+| `chart-fjord-solid` … `chart-orange-solid` | Solid series stroke / marker color |
+| `chart-{ramp}-opacity-1` … `chart-{ramp}-opacity-5` | Area-fill opacity steps (lightest → strongest) |
+| `chart-gridlines` | Grid lines |
+
+Default series order: **fjord → nordic → aurora → dusk → orange**.
+
+---
+
+### Typography
+
+Aura uses three **font families** (loaded in [`src/styles.source.css`](./src/styles.source.css)):
+
+| 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 |
+
+**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):
+
+| 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 |
+
+---
+
+### 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.
+
+---
+
+### 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 |
+
+---
+
+### Border
+
+Aura is visually **flat**; surfaces, spacing, and typography do most structure. Add borders only when separation or affordance needs extra clarity.
+
+**Rules**
+
+- **Must** treat borders/strokes as structural signals (inputs, table boundaries, critical separators), not decoration.
+- **Should** distinguish line items inside cards with spacing, alignment, and type hierarchy before adding dividers.
+- **Should** prefer one outer container boundary over many nested per-row outlines in the same card.
+- **Avoid** drawing borders around every item in a list/card just to create visual rhythm.
+- **Avoid** decorative outline stacks (`border` + `ring` + inset strokes) when no state or interaction meaning is conveyed.
+
+| Concept | Value | Use |
+| :--- | :--- | :--- |
+| Default width | **1px** | Tailwind `border` — tables, inputs, and occasional structural dividers |
+| Emphasized width | **2px** | Stronger separation or invalid/critical state emphasis |
+| Border color | `border`, `border-emphasized`, … | See **Base — Borders and focus** |
+| Style | solid | Default |
+
+---
+
+### Effects
+
+#### Shadows
+
+`--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:
+
+| 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.3 + 0.2 | Menus, popovers, hover cards |
+| `shadow-md` | md + sm layers | 0.05 + 0.04 | 0.3 + 0.2 | Sonner toasts, temporary elevated elements |
+| `shadow-lg` | lg + sm layers | 0.06 + 0.04 | 0.4 + 0.2 | 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 2px var(--ring), 0 0 0 4px var(--ring-muted)` | Default focus on interactive controls |
+| `--shadow-focus-ring-destructive` | `0 0 0 2px var(--ring-critical), 0 0 0 4px var(--ring-critical-shadow)` | 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-*-opacity-*` | See **Chart tokens** |
+
+#### 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.
+
+---
+
+## Grids and layouts
+
+**What this section is:** How to think about **width**, **reading measure**, **vertical rhythm**, and **responsive composition** when building with Aura’s Tailwind v4 theme. Visual grids, column spans, and compositions are maintained in Storybook; this section captures the **rules and links** agents and engineers should follow first.
+
+### Storybook layout reference
+
+| Topic | Storybook |
+| :--- | :--- |
+| Layout overview (docs) | [Foundations / Layout — Docs](https://cognitedata.github.io/aura/storybook/?path=/docs/foundations-layout--docs) |
+| **Column spans** | [Column spans](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--column-spans) |
+| **Layout compositions** | [Compositions](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--compositions) |
+| **Grid patterns** | [Grid patterns reference](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference) |
+| **Container queries** | [Container queries](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--container-queries) |
+| **Breakpoints** | [Breakpoints](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--breakpoints) |
+
+### Copy-paste patterns (Tailwind)
+
+Abbreviated recipes for local iteration when Storybook is not open — **[Grid patterns reference](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference)** and related stories remain the source of truth; tune spans and gaps to match product templates.
+
+**Dashboard main frame** (wide upper bound from **Width and max content**):
+
+```html
+<div class="mx-auto w-full max-w-[min(100%,var(--container-8xl))] px-4 md:px-6">
+  <!-- page content -->
+</div>
+```
+
+**12-column metric row** (example tile shrinks from full width to quarter width at large breakpoints):
+
+```html
+<div class="grid grid-cols-12 gap-4">
+  <section class="col-span-12 sm:col-span-6 lg:col-span-3">…</section>
+  <!-- repeat tiles -->
+</div>
+```
+
+**12-column dashboard tile row** (copy-pasteable baseline):
+
+```html
+<div class="mx-auto w-full max-w-[min(100%,var(--container-8xl))] px-4 md:px-6">
+  <div class="grid grid-cols-12 gap-4 lg:gap-6">
+    <section class="col-span-12 sm:col-span-6 lg:col-span-3">…</section>
+    <section class="col-span-12 sm:col-span-6 lg:col-span-3">…</section>
+    <section class="col-span-12 sm:col-span-6 lg:col-span-3">…</section>
+    <section class="col-span-12 sm:col-span-6 lg:col-span-3">…</section>
+  </div>
+</div>
+```
+
+Adjust `col-span-*` values to match your content hierarchy. Always verify against [Storybook grid patterns](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference).
+
+**Numbers** in the tables below come from [`src/styles.source.css`](./src/styles.source.css) (`@theme inline` and `:root`) where applicable. **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 |
+
+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.
+
+### Column spans, compositions, and grids
+
+- **Must** follow the **column span** and **composition** patterns from Storybook when laying out multi-column app and marketing surfaces — see [Column spans](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--column-spans) and [Compositions](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--compositions).
+- **Must** align card grids, lists, and dashboard tiles to the **grid pattern** reference — see [Grid patterns reference](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference).
+- **Should** use **container queries** where a component’s layout should react to its **parent** width, not only the viewport — see [Container queries](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--container-queries).
+- **Should** use the canonical **viewport breakpoints** for page-level reflow — see [Breakpoints](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--breakpoints).
+
+### Specialized layout 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** grid so titles and descriptions align |
+
+### Grid and spacing usage
+
+- **Must** use the **spacing scale** for padding, margin, and `gap` between layout 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.
+
+### Responsive behavior
+
+- **Should** treat viewport breakpoints as defined in Storybook — [Breakpoints](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--breakpoints) — and still sanity-check primary templates at about **768px**, **1024px**, and **1440px** in the Fusion shell or embedded contexts.
+- **Should** use **container queries** for component-local layout where the preview shows it — [Container queries](https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--container-queries).
+- **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, **container queries**, wrapping, and CSS grid `minmax` / `fr` 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.
+
+---
+
+## Assets
+
+**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.
+
+### Illustrations
+
+Illustrations add a human, expressive layer for **meaningful moments** — not general decoration. An illustration without a clear message is a distraction.
+
+**Use for**
+
+- Empty states — no content yet; user needs context or a clear next action
+- Onboarding modals and product tours — first-use moments that should feel approachable
+- Announcements — system-level messages that need more presence than copy alone
+- Card visuals when photography or live data is not appropriate
+
+**Do not use for**
+
+- Decorative filler where the layout is already sufficient
+- Stacking multiple illustrations in one context — **one illustration per context**
+- Replacing copy — they **support** a message; they do not carry it alone
+
+**Guidance**
+
+- **Must** pair every illustration with supporting copy.
+- **Must** use the asset variant that matches the active workspace theme (**light** or **dark**).
+- **Must** preserve original aspect ratio — no non-uniform scaling or distortion.
+- **Must** leave enough surrounding space so the asset reads clearly.
+- **Must not** alter illustration artwork (cropping beyond safe bounds, filters, overlays, recolor).
+- **Avoid** illustrations in dense data views or anywhere the primary task is scanning or acting on structured information.
+
+**Accessibility**
+
+- **Must** provide descriptive `alt` text on informative illustrations — describe the message, not every visual detail.
+- Decorative illustrations that convey no extra information **should** use `alt=""` so assistive tech skips them.
+
+### Document icons
+
+Document icons signal **file type** so users can scan lists, tables, uploads, and attachments quickly.
+
+**Use for**
+
+- File-type identification in lists, tables, and previews
+- Upload flows and pickers where type recognition matters
+
+**Guidance**
+
+- **Must** use only approved sizes: **36px**, **40px**, or **44px** — no other sizes.
+- **Must** center and vertically middle-align icons with adjacent text.
+- **Must** keep shipped colors — do not recolor or theme-swizzle document icons outside the provided set.
+- **Must not** edit artwork (shapes, backgrounds, proportions).
+
+**Accessibility**
+
+- **Must** use `alt` text that names the file type (e.g. `alt="PDF"`).
+
+### App icons
+
+App icons identify **products, workspaces, or integrations** (launcher tiles, chrome, marketing surfaces). They are identity marks, not UI chrome.
+
+**Guidance**
+
+- **Must** use **official** Cognite or product marks from the brand system — no unofficial redraws.
+- **Must** preserve clear space and minimum sizes defined by brand guidelines for each context (favicon, tile, splash).
+- **Must not** distort, rotate for effect, add badges, or combine marks with decorative illustrations in the same glyph.
+
+**Accessibility**
+
+- Treat launcher and header marks as **informative** where they disambiguate apps; use `alt` or adjacent text consistent with the surface (e.g. app name next to the tile).
+
+### System icons
+
+System icons are **functional** shorthand for actions, state, and navigation. Aura standardizes on **Tabler Icons** (`@tabler/icons-react` in the library). Names describe intent — **do not repurpose** an icon for an unrelated meaning.
+
+**Sizes**
+
+- **Default / recommended:** 16×16px
+- **Accepted in UI components:** 12×12px, 14×14px, 16×16px (match the component’s density; Aura primitives often default to **16px** via `size-4` classes on icons)
+
+**Guidance**
+
+- **Must** use **filled** variants where brand or application chrome calls for weight (e.g. persistent app strip); use **outlined** variants for in-product actions and navigation unless a specific Aura component specifies otherwise.
+- **Must not** edit, merge, or warp glyphs; icons stay **single-color** (typically `currentColor` so **Tokens** foreground colors apply). Exceptions: **branded** marks supplied as dedicated assets (see below).
+- **Must not** hang hover, active, or focus styling on the raw icon — those states belong on the **control** (button, link, menu item).
+- **Should** limit how many distinct icons compete on one view so each stays recognizable.
+- **Avoid** icon-only interactive targets without a **Tooltip** or visible label (see accessibility).
+
+**Branded icons**
+
+Rare exceptions (third-party or Cognite logos inside a cell) use **provided SVGs only** — same rules as app icons for distortion and clear space; color may be multi-hue **only** when the asset is the official brand mark.
+
+**Accessibility**
+
+- **Must** meet **4.5:1** contrast against the icon’s background (same bar as body text when the icon communicates meaning).
+- **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"`.
+
+---
+
+## 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.
+
+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). |
+
+Aura primitives ship these states by default; the rules below describe the **design contract** and apply when extending Aura or building one-off interactives.
+
+### Default (enabled)
+
+The **resting** state: the element is available without shouting over neighboring content. Weight follows importance — a **primary** action reads stronger than a **table row** or **list item**. Match prominence to the action’s priority (see **Tokens** for `primary-background`, `muted-background`, `accent-background`, etc.).
+
+### Hover
+
+The pointer is over the element; hover confirms interactivity before commitment.
+
+**Guidance**
+
+- **Must** change visibly from default — usually a background shift (`accent-background`, `primary-background-hover`, `secondary-background-hover`) or stroke emphasis (`border-emphasized` on outlines).
+- **Should** feel immediate (no intentional lag on hover feedback).
+- **Must not** be the **only** cue for something critical — hover is absent on many touch and reduced-motion contexts.
+- **May** add elevation (`shadow-*`) on hover for objects that already read as “cards” or panels — **sparingly**, only where elevation matches the metaphor.
+
+### Pressed
+
+Pointer or finger is **down** on the control; confirms input was received.
+
+**Guidance**
+
+- **Must** read clearly **stronger or “deeper”** than hover (darker/lighter fill step, or subtle scale / inset — within the same token family, not a new ad-hoc color).
+- **Should** appear within about **one frame** of the gesture; duration is short and ends on release.
+
+### Focused
+
+Keyboard or assistive tech has moved focus to the element. This is the main non-pointer signal for “where am I?” and is required for accessibility.
+
+**Guidance**
+
+- **Must** show a **visible** focus indicator on every interactive control. Do not remove focus styling without replacing it with an equivalent that meets contrast rules.
+- **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**).
+
+### Disabled
+
+The control is present but **not** actionable in the current context; it does not respond to hover, press, or activation.
+
+**Guidance**
+
+- **Must** use **`disabled-background`** and **`disabled-foreground`** — not generic opacity on top of default colors unless a component API explicitly documents that pattern.
+- **Must not** show hover, pressed, or focus styling that implies activation (disabled is inert).
+- **Should** pair unexplained disabled controls with a **Tooltip** or inline hint (“Complete required fields to continue”) so users know how to re-enable.
+- **Avoid** using disabled as the main pattern for “not yet allowed” flows — prefer hiding the action, an inline message, or a clear path to fix the blocker.
+- **Avoid** disabling the **primary** CTA without a visible way to resolve the blocking condition.
+
+### Selected (toggled)
+
+Persistent **on/off**, **selected**, **active filter**, or **applied setting** until the user changes it.
+
+**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 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.
+
+### Loading
+
+Work is **in progress**; the control or region may be temporarily inert or show progress.
+
+**Guidance**
+
+- **Must** expose busy state accessibly where appropriate (`aria-busy`, progress semantics, or an accessible name that includes “Loading”).
+- **Should** use Aura **Loader** / **Skeleton** / **Shimmer** (or documented equivalents) instead of ad-hoc spinners that ignore motion and contrast tokens.
+- **Should** read differently from **disabled** when the user can still cancel, navigate away, or understand wait time — disabled means “you cannot act here”; loading means “wait or observe progress.”
+
+---
+
+## 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.
+
+**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).
+
+**Time**
+
+- **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.
+
+**Dates and combined date-time**
+
+- **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.
+
+**Ranges**
+
+- **Time range:** same style at start and end; on 12-hour clocks, repeat **AM**/**PM** only when needed for clarity (single meridiem can use one suffix; cross-midnight or long ranges may need both date and meridiem on each end).
+- **Date range:** consistent formatting; **avoid** dense numeric ranges that are hard to parse.
+- **Date-time range:** date first, then time; include year unless context suffices; for 12-hour + range, **must** label **AM**/**PM** clearly on both ends when ambiguity is likely.
+
+**Duration** (elapsed length, not a clock range)
+
+- **Should** express duration when elapsed length matters more than endpoints.
+- No “relative” phrasing for duration lists.
+- **Should** use a **space** between number and unit in body text and tables (`3 seconds`); compact controls may omit the space per component spec.
+- **Should** avoid commas between compound units (`10 minutes 3 seconds` not `10 minutes, 3 seconds`).
+- For sub-second precision, **should** use decimals (`2.5 seconds`) or round to a meaningful whole unit to reduce noise.
+
+**Abbreviations** (lowercase units except proper nouns like **Jan**, **Mon**; no periods on abbreviations)
+
+| Full (examples) | Abbreviated |
+| :--- | :--- |
+| millisecond(s), second(s), minute(s), hour(s) | ms, s, min, hr |
+| day(s), week(s), month(s), year(s) | d, wk, mo, yr |
+
+Days and months: **Monday** → **Mon**, **January** → **Jan**, etc.; capitalize; allow width for **four-letter** abbreviations where internationalization may need it.
+
+**Scheduled automation:** use **cron** expressions where users define recurring runs.
+
+---
+
+### Grammar and style
+
+**Must** use **American English** in UI (`color`, `center`, `organization`, …). **Must** use **sentence case** for UI phrases; **must not** use **ALL CAPS** for body labels.
+
+**Should** prefer **active voice**; use passive only for objectivity or legal emphasis.
+
+**Numbers:** use **numerals** for all magnitudes in UI (`6 queries per second`, `50 Mbps`). **Should** use a **non-breaking space** between a number and its unit where line breaks would confuse.
+
+**Abbreviations:** spell out when possible; **avoid** Latin shortcuts (“e.g.”, “etc.”) — use “for example”, “and more”, or recast the sentence.
+
+**Punctuation**
+
+- **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**.
+
+**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).
+
+**Plural forms:** **avoid** “(s)” or “(es)” in labels — use separate strings or unambiguous copy per locale.
+
+---
+
+### Localization
+
+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.
+
+---
+
+### 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**.
+
+---
+
+### Writing for accessibility
+
+Structural accessibility (focus, contrast, semantics, targets) lives in **Heuristics §7** and **Interaction states**. This subsection is **copy-specific**.
+
+**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.
+
+**Must** make **link text** describe the destination or outcome (“Learn about pricing”), not “click here” or bare “read more”.
+
+**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.
+
+**Should** avoid **this** / **that** without a clear noun referent.
+
+**Should** describe **data trends** in words when the UI relies on charts or color alone.
+
+**Must** use **Select** (or “choose”, “turn on”) rather than **Click** in instructions — not all users use a pointer.
+
+---