@cognite/aura 0.3.5 → 1.46105.0

package/DESIGN.md

@@ -228,7 +228,7 @@ Aura color behaves like instrumentation in a control room. Most of the interface
 
 Use **Base** color for the operating surface: page backgrounds, cards, text, borders, focus, and persistent chrome. This is ~80–90% of the UI.
 
-Use **Semantic** color only for status and feedback: info, success, warning, destructive, validation, and operational state. This is ~5–10% of the UI.
+Use **Semantic** color only for status and feedback: info, success, warning, critical, validation, and operational state. This is ~5–10% of the UI.
 
 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.
 
@@ -236,179 +236,302 @@ Light-theme reference values for key roles are defined as `colors.*` tokens in t
 
 Do not hardcode hex, font sizes, or shadow strings in product UI when a token exists.
 
-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.
+Aura supports **light** (`:root`) and **dark** (`.dark` / `prefers-color-scheme: dark` per library setup). Theme tokens **resolve to different ramp steps** per theme. **`*-fixed-dark`** tokens keep the same appearance in both themes (persistent dark chrome such as sidebars). Always verify contrast in both themes before shipping.
 
-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.
+Reference tokens by **full CSS name** or Tailwind utility (`bg-base-background`, `text-critical-foreground-strong`, `border-default`, …). Never use raw `hex` / `rgb` / `hsl` in product code. Use **step colors** on ramps (`mountain-*`, `fjord-*`, …) only for custom, branding, or marketing surfaces where no theme token exists yet.
 
 ### Common Tailwind mappings
 
-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                       |
-
-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`         | `{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**
-
-| 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` |
-
-**Warning**
-
-| 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                 |
-
-**Destructive**
-
-| 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`            |
-
-**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.
+Theme tables below use **CSS token names** from Figma Reflect. Each maps to `--color-{name}` and Tailwind v4 utilities (`text-{name}`, `bg-{name}`, `border-{name}`, `ring-{name}`). Prefer utilities over raw `var(--…)`.
+
+| Pattern                     | Example utilities                                                                                          | Notes                                          |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `base-*`                    | `bg-base-background`, `text-base-foreground`                                                               | Page surface and primary text                  |
+| `medium-*`                  | `bg-medium-background`, `text-medium-foreground`                                                           | Inputs, fields, subtle elevation               |
+| `muted-*`                   | `bg-muted-background`, `text-muted-foreground`                                                             | Secondary chrome, segmented tracks             |
+| `primary-*` / `secondary-*` | `bg-primary-background`, `text-primary-foreground`                                                         | Brand actions                                  |
+| `popover-*` / `card-*`      | `bg-popover-background`, `bg-card-background`                                                              | Elevated surfaces                              |
+| `critical-*`                | `bg-critical-background` + `text-critical-foreground`; flat status text: `text-critical-foreground-strong` | Errors / critical status (not `destructive-*`) |
+| `border-*`                  | `border-default`, `border-emphasized`, `border-disabled`                                                   | Strokes (`default` → `--default` in CSS)       |
+| `ring-*`                    | `ring-ring-default`, shadow focus utilities                                                                | Focus rings                                    |
+| `decorative-{n}-*`          | `bg-decorative-1-background`                                                                               | Non-status accents (slot `n` = ramp in table)  |
+| `chart-*`                   | `bg-chart-1-200`, `bg-chart-gridlines`                                                                     | Plotted data only                              |
+
+Light and dark columns in the tables show the **ramp step** each token resolves to in `colors.css` (e.g. `mountain-50`, `fjord-500`).
+
+### Base
+
+| Token                                 | Light (ramp)                | Dark (ramp)    | Use                             |
+| ------------------------------------- | --------------------------- | -------------- | ------------------------------- |
+| `base-background`                     | `mountain-white`            | `mountain-950` | Primary page surface            |
+| `base-background-hover`               | `mountain-50`               | `mountain-800` | Hover on base surface           |
+| `base-background-hover-fixed-dark`    | `mountain-700`              | `mountain-700` | Hover on persistent dark chrome |
+| `base-background-disabled`            | `mountain-50`               | `mountain-800` | Disabled control fill           |
+| `base-background-disabled-fixed-dark` | `mountain-700`              | `mountain-700` | Disabled on dark chrome         |
+| `base-background-overlay`             | `rgba(124, 134, 142, 0.55)` | same           | Modal scrim                     |
+| `base-foreground`                     | `mountain-950`              | `mountain-10`  | Primary text and icons          |
+| `base-foreground-disabled`            | `mountain-300`              | `mountain-600` | Disabled text                   |
+| `base-foreground-disabled-fixed-dark` | `mountain-600`              | `mountain-600` | Disabled text on dark chrome    |
+
+### Medium
+
+| Token                          | Light (ramp)   | Dark (ramp)    | Use                              |
+| ------------------------------ | -------------- | -------------- | -------------------------------- |
+| `medium-background`            | `mountain-50`  | `mountain-800` | Inputs, comboboxes, subtle fills |
+| `medium-background-hover`      | `mountain-100` | `mountain-700` | Hover on medium surfaces         |
+| `medium-foreground`            | `mountain-700` | `mountain-300` | Text on medium surfaces          |
+| `medium-foreground-hover`      | `mountain-500` | `mountain-500` | Hover text on medium             |
+| `medium-foreground-fixed-dark` | `mountain-300` | `mountain-300` | Medium text on dark chrome       |
+
+### Muted
+
+| Token                         | Light (ramp)   | Dark (ramp)    | Use                             |
+| ----------------------------- | -------------- | -------------- | ------------------------------- |
+| `muted-background`            | `mountain-10`  | `mountain-900` | Secondary chrome, switch tracks |
+| `muted-background-hover`      | `mountain-50`  | `mountain-800` | Hover on muted surfaces         |
+| `muted-foreground`            | `mountain-550` | `mountain-400` | Tertiary text                   |
+| `muted-foreground-hover`      | `mountain-700` | `mountain-100` | Hover tertiary text             |
+| `muted-foreground-fixed-dark` | `mountain-400` | `mountain-400` | Muted text on dark chrome       |
+
+### Primary (brand)
+
+| Token                                 | Light (ramp)   | Dark (ramp)    | Use                              |
+| ------------------------------------- | -------------- | -------------- | -------------------------------- |
+| `primary-background`                  | `mountain-900` | `mountain-10`  | Primary actions (default button) |
+| `primary-background-hover`            | `mountain-650` | `mountain-100` | Hover on primary                 |
+| `primary-background-fixed-dark`       | `mountain-10`  | `mountain-10`  | Primary fill on dark chrome      |
+| `primary-background-hover-fixed-dark` | `mountain-100` | `mountain-100` | Hover primary on dark chrome     |
+| `primary-foreground`                  | `mountain-50`  | `mountain-950` | Text on `primary-background`     |
+| `primary-foreground-fixed-dark`       | `mountain-950` | `mountain-950` | Text on primary on dark chrome   |
+
+### Secondary (brand)
+
+| Token                                   | Light (ramp)   | Dark (ramp)    | Use                            |
+| --------------------------------------- | -------------- | -------------- | ------------------------------ |
+| `secondary-background`                  | `mountain-100` | `mountain-700` | Secondary actions, quiet fills |
+| `secondary-background-hover`            | `mountain-50`  | `mountain-600` | Hover on secondary             |
+| `secondary-background-fixed-dark`       | `mountain-700` | `mountain-700` | Secondary on dark chrome       |
+| `secondary-background-hover-fixed-dark` | `mountain-600` | `mountain-600` | Hover secondary on dark chrome |
+| `secondary-foreground`                  | `mountain-700` | `mountain-200` | Text on secondary              |
+| `secondary-foreground-fixed-dark`       | `mountain-200` | `mountain-200` | Secondary text on dark chrome  |
+
+### Popover
+
+| Token                           | Light (ramp)     | Dark (ramp)      | Use                               |
+| ------------------------------- | ---------------- | ---------------- | --------------------------------- |
+| `popover-background`            | `mountain-white` | `mountain-900`   | Dialogs, menus, shadowed surfaces |
+| `popover-background-hover`      | `mountain-50`    | `mountain-800`   | Hover on popover surface          |
+| `popover-background-fixed-dark` | `mountain-800`   | `mountain-800`   | Popover on dark chrome            |
+| `popover-foreground`            | `mountain-950`   | `mountain-50`    | Text on popover                   |
+| `popover-foreground-fixed-dark` | `mountain-white` | `mountain-white` | Text on popover on dark chrome    |
+
+### Card
+
+| Token                   | Light (ramp)   | Dark (ramp)    | Use                  |
+| ----------------------- | -------------- | -------------- | -------------------- |
+| `card-background`       | `mountain-10`  | `mountain-800` | Card surface on base |
+| `card-background-hover` | `mountain-50`  | `mountain-700` | Hover on card        |
+| `card-foreground`       | `mountain-950` | `mountain-50`  | Card text            |
+
+### Link
+
+| Token                   | Light (ramp) | Dark (ramp) | Use        |
+| ----------------------- | ------------ | ----------- | ---------- |
+| `link-foreground`       | `fjord-600`  | `fjord-450` | Text links |
+| `link-foreground-hover` | `fjord-700`  | `fjord-200` | Link hover |
+
+### Border
+
+| Token        | Light (ramp)   | Dark (ramp)    | Use                                       |
+| ------------ | -------------- | -------------- | ----------------------------------------- |
+| `default`    | `mountain-100` | `mountain-700` | Default strokes (`border-default`)        |
+| `emphasized` | `mountain-200` | `mountain-600` | Stronger separation (`border-emphasized`) |
+| `disabled`   | `mountain-50`  | `mountain-800` | Disabled outlines (`border-disabled`)     |
+
+### Ring (focus)
+
+| Token                 | Light (ramp) | Dark (ramp) | Use                         |
+| --------------------- | ------------ | ----------- | --------------------------- |
+| `ring-default`        | `fjord-500`  | `fjord-400` | Default focus ring          |
+| `ring-muted`          | `gray-200`   | `gray-800`  | Focus ring inner / muted    |
+| `ring-critical`       | `red-600`    | `red-450`   | Invalid / destructive focus |
+| `ring-critical-muted` | `red-100`    | `red-900`   | Destructive focus companion |
+
+Each **status family** (success, warning, critical, info, neutral) shares the same foreground pairing pattern:
+
+| Suffix                | Use                                                                                                                     |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `*-foreground`        | Text and icons **on** `*-background` (Alert fills, filled Badge, status chips with a tint)                              |
+| `*-foreground-strong` | Status text and icons **without** a tinted background — on `base-background`, `card-background`, or inline in body copy |
+
+Example: `bg-critical-background` + `text-critical-foreground` for a filled error badge; `text-critical-foreground-strong` for a red error label on a plain card.
+
+### Success
+
+| Token                       | Light (ramp) | Dark (ramp) | Use                                                        |
+| --------------------------- | ------------ | ----------- | ---------------------------------------------------------- |
+| `success-background`        | `green-100`  | `green-900` | Success surface                                            |
+| `success-background-hover`  | `green-200`  | `green-800` | Hover on success                                           |
+| `success-foreground`        | `green-650`  | `green-400` | Text and icons **on** `success-background`                 |
+| `success-foreground-strong` | `green-500`  | `green-400` | Success status text/icons **without** `success-background` |
+
+### Warning
+
+| Token                       | Light (ramp) | Dark (ramp)  | Use                                                        |
+| --------------------------- | ------------ | ------------ | ---------------------------------------------------------- |
+| `warning-background`        | `orange-100` | `orange-900` | Warning surface                                            |
+| `warning-background-hover`  | `orange-200` | `orange-800` | Hover on warning                                           |
+| `warning-foreground`        | `orange-650` | `orange-400` | Text and icons **on** `warning-background`                 |
+| `warning-foreground-strong` | `orange-500` | `orange-400` | Warning status text/icons **without** `warning-background` |
+
+### Critical
+
+| Token                        | Light (ramp) | Dark (ramp) | Use                                                          |
+| ---------------------------- | ------------ | ----------- | ------------------------------------------------------------ |
+| `critical-background`        | `red-100`    | `red-900`   | Error / critical surface                                     |
+| `critical-background-hover`  | `red-200`    | `red-800`   | Hover on critical                                            |
+| `critical-foreground`        | `red-650`    | `red-400`   | Text and icons **on** `critical-background`                  |
+| `critical-foreground-strong` | `red-500`    | `red-400`   | Critical status text/icons **without** `critical-background` |
+
+### Info
+
+| Token                    | Light (ramp) | Dark (ramp) | Use                                                  |
+| ------------------------ | ------------ | ----------- | ---------------------------------------------------- |
+| `info-background`        | `blue-100`   | `blue-900`  | Info surface                                         |
+| `info-background-hover`  | `blue-200`   | `blue-800`  | Hover on info                                        |
+| `info-foreground`        | `blue-650`   | `blue-400`  | Text and icons **on** `info-background`              |
+| `info-foreground-strong` | `blue-500`   | `blue-400`  | Info status text/icons **without** `info-background` |
+
+### Neutral (status)
 
-### Decorative colors
+| Token                       | Light (ramp)   | Dark (ramp)    | Use                                                        |
+| --------------------------- | -------------- | -------------- | ---------------------------------------------------------- |
+| `neutral-background`        | `mountain-100` | `mountain-900` | Draft / archived status                                    |
+| `neutral-background-hover`  | `mountain-200` | `mountain-800` | Hover on neutral status                                    |
+| `neutral-foreground`        | `mountain-650` | `mountain-400` | Text and icons **on** `neutral-background`                 |
+| `neutral-foreground-strong` | `mountain-550` | `mountain-400` | Neutral status text/icons **without** `neutral-background` |
+
+**Naming:** `*-foreground` replaces legacy `*-foreground-on-*` (copy on tinted status surfaces). `*-foreground-strong` is the flat-surface status color (replaces legacy bare `*-foreground` / `destructive-foreground` used near status on standard surfaces). Critical replaces legacy `destructive-*` in theme tokens.
 
-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}`.
+### Decorative colors
 
-**Preference order for new work:**
+For **small accents** (badges, avatars, empty states) where color differentiates but does **not** signal status — use **decorative-{1..7}-\*** semantic slots, not chart series colors, unless a design explicitly maps a tile to a plot series. Pattern: `decorative-{n}-background`, `decorative-{n}-background-hover`, `decorative-{n}-foreground` (slot `n` matches the ramp in the table below).
 
-| 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` |
+**CSS token slots** (Figma Reflect naming):
 
-Example (fjord ramp): light `decorative-background-fjord` → `#CCD5FA` (fjord-200), `decorative-foreground-fjord` → `#1234B6` (fjord-700); dark → `#AEBDF7` / `#0D2582` (fjord-300 / fjord-800).
+| Slot | Ramp     | Background                                                 | Foreground                |
+| ---- | -------- | ---------------------------------------------------------- | ------------------------- |
+| 1    | Mountain | `decorative-1-background`, `decorative-1-background-hover` | `decorative-1-foreground` |
+| 2    | Fjord    | `decorative-2-background`, `decorative-2-background-hover` | `decorative-2-foreground` |
+| 3    | Nordic   | `decorative-3-background`, `decorative-3-background-hover` | `decorative-3-foreground` |
+| 4    | Aurora   | `decorative-4-background`, `decorative-4-background-hover` | `decorative-4-foreground` |
+| 5    | Dusk     | `decorative-5-background`, `decorative-5-background-hover` | `decorative-5-foreground` |
+| 6    | Amber    | `decorative-6-background`, `decorative-6-background-hover` | `decorative-6-foreground` |
+| 7    | Pink     | `decorative-7-background`, `decorative-7-background-hover` | `decorative-7-foreground` |
 
-### Chart tokens
+**Avatar and Badge** expose a unified `decorative-1` … `decorative-7` **variant prop** (labels “Decorative 1” … “Decorative 7” in Storybook). Default is `decorative-1` (Mountain). Each prop maps to the matching CSS slot (e.g. prop `decorative-2` → `decorative-2-*` tokens / Fjord).
 
-**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.
+Example (Fjord slot 2): light `decorative-2-background` → `fjord-200`, hover → `fjord-300`, `decorative-2-foreground` → `fjord-800`; dark → `fjord-300` / `fjord-200` / `fjord-900`.
 
-| Token                                           | Use                                                         |
-| ----------------------------------------------- | ----------------------------------------------------------- |
-| `chart-{ramp}-color-1` … `chart-{ramp}-color-6` | Alpha-based series / area-fill steps (strongest → lightest) |
-| `chart-gridlines`                               | Grid lines                                                  |
+### Chart tokens
 
-Default series order: **fjord → nordic → aurora → dusk → orange**.
+**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-*`, `critical-*`) for operational status and feedback only. Never swap between these groups.
+
+| Token                              | Underlying ramp (light)              | Use                                                                    |
+| ---------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- |
+| `chart-gridlines`                  | `mountain-100` (`mountain-800` dark) | Axis grid lines                                                        |
+| `chart-1-{50,100,200,300,400,450}` | `fjord-alpha-*`                      | Default series 1 — line/area alpha steps (50 lightest → 450 strongest) |
+| `chart-2-{50…450}`                 | `nordic-alpha-*`                     | Series 2                                                               |
+| `chart-3-{50…450}`                 | `aurora-alpha-*`                     | Series 3                                                               |
+| `chart-4-{50…450}`                 | `dusk-alpha-*`                       | Series 4                                                               |
+| `chart-5-{50…450}`                 | `amber-alpha-*`                      | Series 5                                                               |
+| `chart-success-{50…450}`           | `green-alpha-*`                      | Status-colored series (success)                                        |
+| `chart-warning-{50…450}`           | `orange-alpha-*`                     | Status-colored series (warning)                                        |
+| `chart-critical-{50…450}`          | `red-alpha-*`                        | Status-colored series (critical)                                       |
+| `chart-info-{50…450}`              | `blue-alpha-*`                       | Status-colored series (info)                                           |
+| `chart-neutral-{50…450}`           | `mountain-alpha-*`                   | Neutral / baseline series                                              |
+
+Default multi-series order: **chart-1 (Fjord) → chart-2 (Nordic) → chart-3 (Aurora) → chart-4 (Dusk) → chart-5 (Amber)**.
+
+Utilities: `bg-chart-1-200`, `fill-chart-3-450`, `stroke-chart-gridlines`, etc.
+
+### Heat map
+
+| Token               | Light (ramp) | Dark (ramp) | Use             |
+| ------------------- | ------------ | ----------- | --------------- |
+| `heat-map-intense`  | `fjord-600`  | `fjord-300` | Highest density |
+| `heat-map-strong`   | `fjord-450`  | `fjord-450` | Strong density  |
+| `heat-map-moderate` | `fjord-300`  | `fjord-650` | Mid density     |
+| `heat-map-mild`     | `fjord-100`  | `fjord-800` | Lowest density  |
+
+### Shadow (elevation overlays)
+
+| Token       | Light              | Dark               | Use               |
+| ----------- | ------------------ | ------------------ | ----------------- |
+| `shadow-sm` | `rgba(0,0,0,0.04)` | `rgba(0,0,0,0.2)`  | Subtle elevation  |
+| `shadow-md` | `rgba(0,0,0,0.05)` | `rgba(0,0,0,0.3)`  | Cards, popovers   |
+| `shadow-lg` | `rgba(0,0,0,0.06)` | `opacity-black-40` | Modals            |
+| `shadow-xl` | `rgba(0,0,0,0.1)`  | `opacity-black-60` | Highest elevation |
+
+Focus rings compose `ring-default` + `ring-muted` (or `ring-critical` + `ring-critical-muted` for invalid fields). See [Focus rings](#focus-rings).
+
+### Color ramps (step tokens)
+
+Raw ramp steps live in `colors.css` and appear in Storybook **Color ramps**. Figma uses slash paths (`mountain/500`); CSS/Tailwind use hyphen steps (`mountain-500`, `bg-fjord-200`).
+
+| Ramp                | Role                                                   | Typical steps                                                                            |
+| ------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| **Mountain**        | Primary neutral (base, card, neutral status)           | `10`, `50`–`950`, `550` (mid-gray), `white`, `black`, `alpha-10`, `alpha-50`–`alpha-450` |
+| **Fjord**           | Brand blue; chart series 1; links; heat map            | `50`–`950`, `alpha-50`–`alpha-450`                                                       |
+| **Nordic**          | Brand teal; chart series 2; decorative slot 3          | same                                                                                     |
+| **Aurora**          | Brand green; chart series 3; decorative slot 4         | same                                                                                     |
+| **Dusk**            | Brand purple; chart series 4; decorative slot 5        | same                                                                                     |
+| **Amber**           | Brand yellow-orange; chart series 5; decorative slot 6 | same                                                                                     |
+| **Pink**            | Brand pink; decorative slot 7                          | same                                                                                     |
+| **Blue**            | Info status + `chart-info-*`                           | same                                                                                     |
+| **Green**           | Success status + `chart-success-*`                     | same                                                                                     |
+| **Red**             | Critical status + `chart-critical-*`                   | same                                                                                     |
+| **Orange**          | Warning status + `chart-warning-*`                     | same                                                                                     |
+| **Gray**            | Ring muted, secondary neutrals                         | same                                                                                     |
+| **Sky**, **Yellow** | Extended palette (rare in theme tokens)                | same                                                                                     |
+| **Opacity**         | `opacity-black-*`, `opacity-white-*`                   | Overlay and shadow building blocks                                                       |
+
+Use ramp steps only when no theme token covers the surface. Prefer theme tokens for all product UI.
+
+### Figma ↔ implementation discrepancies
+
+Compared to [Figma Reflect theme tokens](https://www.figma.com/design/pMnMQvfErZDJzWgrcWCIwZ/Aura-Design-System?node-id=18097-28085) and `colors.css` (runtime source of truth):
+
+| Item                                                                 | Figma                                        | `colors.css` / Storybook                                                  | Notes                                                                                                                                           |
+| -------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `base-foreground-contrast`                                           | Present (`base/foreground-contrast`)         | **Missing**                                                               | Not wired in CSS or `colors.stories.tsx` `THEME_TOKEN_ORDER`                                                                                    |
+| `*-muted-background` (semantic)                                      | Removed in Reflect                           | **Removed**                                                               | Legacy `info-muted-background`, `destructive-muted-background`, etc. — use `*-background` on dark chrome or `medium-*` / `popover-*-fixed-dark` |
+| `destructive-*` theme names                                          | Renamed to `critical-*`                      | `critical-*`                                                              | Deprecated aliases may remain in `colors-deprecated.css` until 1.0.0                                                                            |
+| `*-foreground-on-*`                                                  | `*-foreground`                               | e.g. `info-foreground-on-info` → `info-foreground` (on `info-background`) |
+| `destructive-foreground`, `info-foreground`, … (flat status on base) | `*-foreground-strong`                        | e.g. `destructive-foreground` → `critical-foreground-strong`              |
+| Path vs name                                                         | Slash paths (`border/default`, `chart/1/50`) | Hyphen tokens (`border-default`, `chart-1-50`)                            | Same tokens; naming convention only                                                                                                             |
+| Chart series 5 ramp                                                  | Amber in Figma/CSS                           | Amber (not orange)                                                        | Default series 5 maps to `amber-alpha-*`, not `orange-*`                                                                                        |
+
+If you need a token that exists in Figma but not in CSS, treat it as a **design–engineering gap** until added to `colors.css`.
+
+### Deprecated color tokens (removed in 1.0.0)
+
+Legacy names remain in `colors-deprecated.css` until Aura **1.0.0**. Migrate direct Tailwind usage to Reflect names:
+
+| Pattern (deprecated)                                                      | Migrate to                                                                                                     |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `text-foreground`, `bg-background`, `border-border`                       | `text-base-foreground`, `bg-base-background`, `border-default`                                                 |
+| `destructive-background`, `destructive-foreground-on-critical`            | `critical-background`, `critical-foreground`                                                                   |
+| `ring-destructive`, `ring-destructive-muted`                              | `ring-critical`, `ring-critical-muted`                                                                         |
+| `bg-accent-background`, `bg-highlight-background`, `bg-active-background` | `bg-base-background-hover`, `bg-medium-background`, `bg-primary-background` (context-dependent)                |
+| `bg-muted-background` (legacy page fill)                                  | `bg-muted-background` (Reflect) or `bg-medium-background`                                                      |
+| `text-disabled-foreground`, `bg-disabled-background`                      | `text-base-foreground-disabled`, transparent + `border-disabled`                                               |
+| `bg-background-fixed-dark`, `text-foreground-fixed-dark`                  | `bg-popover-background-fixed-dark`, `text-popover-foreground-fixed-dark` (or category-specific `*-fixed-dark`) |
+| `decorative-background-{ramp}`, `decorative-foreground-{ramp}`            | `decorative-{1..7}-background`, `decorative-{1..7}-foreground` (see slot table above)                          |
+| `chart-{ramp}-color-{n}`                                                  | `chart-{series}-{step}` (e.g. `chart-fjord-color-1` → `chart-1-50` … `chart-1-450`)                            |
+| `opacity-{10,20,…}` utilities                                             | Use semantic surfaces or ramp alpha steps                                                                      |
+
+Full per-token list: `colors-deprecated.css`. Badge/Avatar variant props `mountain`, `fjord`, `gray` are removed — use `decorative-1` … `decorative-7`.
 
 ---
 
@@ -444,7 +567,7 @@ Aura uses **Inter** for product UI, **Space Grotesk** for marketing display, and
 
 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 [Colors](#colors).
+- [ ] **Tokens** — confirm all colors use semantic or chart tokens, no raw hex. Metric tiles: `decorative-*`. Data series: `chart-*`. Status: `info-*`, `success-*`, `warning-*`, `critical-*`. 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).
@@ -465,23 +588,27 @@ Width and spacing values in this subsection follow the **`{spacing.base}`-based*
 Standard layout primitives used across all patterns:
 
 **Content max widths**
+
 - max-w-7xl — dashboards, full-width layouts
 - max-w-4xl — detail pages
 - max-w-2xl — forms, wizard step content
 - max-w-sm — search inputs, narrow controls
 
 **Section spacing**
+
 - space-y-8 — between major page sections (e.g. form groups)
 - space-y-6 — between sections within a page
 - space-y-4 — between items within a section
 - space-y-2 — between label and field, tight groupings
 
 **Grid gaps**
+
 - gap-6 — dashboard grids, chart grids, panel gaps
 - gap-4 — card grids, metric grids
 - gap-3 — toolbar items, button groups
 
 **Page padding**
+
 - px-6 py-8 — standard content area (desktop)
 - px-4 py-6 — mobile content area
 - p-4 — card/panel internal padding
@@ -490,6 +617,7 @@ Standard layout primitives used across all patterns:
 ### Layout patterns
 
 #### Sidebar content
+
 3+ top-level sections. Persistent navigation needed.
 Most common for multi-page apps.
 
@@ -510,9 +638,10 @@ Most common for multi-page apps.
 Desktop (1440px+): Sidebar 240px, content fills rest.
 Tablet (768px-1439px): Sidebar collapsible via hamburger.
 Mobile (below 768px): Sidebar hidden. Hamburger menu.
-  Consider bottom nav for 3-5 primary sections.
+Consider bottom nav for 3-5 primary sections.
 
 #### Full-width dashboard
+
 Data visualizations, metrics, monitoring. Maximum horizontal space needed.
 
 **Structure**
@@ -539,6 +668,7 @@ Tablet: 2-column grid. Charts stack.
 Mobile: Single column. Metrics as horizontal scroll.
 
 #### Form page
+
 Data entry, creation flows, configuration, settings with form fields.
 
 **Structure**
@@ -588,8 +718,8 @@ Desktop: Two-column (grid-cols-3, main span-2, sidebar span-1).
 Tablet: Sidebar below main content.
 Mobile: Single column. Sidebar collapses.
 
-
 #### Settings page
+
 App preferences, account settings, notification config.
 
 **Structure**
@@ -609,6 +739,7 @@ Tablet: Top tabs replacing left nav.
 Mobile: Category list → tap opens section full-screen.
 
 #### Split screen
+
 Comparison views, editor + preview, master-detail with equal emphasis on both sides.
 
 **Structure**
@@ -627,8 +758,8 @@ Desktop: grid-cols-2, equal columns.
 Tablet: grid-cols-2 with narrower gap.
 Mobile: Stack vertically (grid-cols-1), or use Segmented Control to switch between panels.
 
-
 #### Three panel
+
 Navigation + content + properties panel. IDE-style layouts. Complex editing workflows with context panels.
 
 **Structure**
@@ -649,8 +780,8 @@ Tablet (768-1439px): Hide right panel, toggle via button.
 Mobile (below 768px): Single panel with navigation as Drawer, right panel as bottom sheet or separate route.
 
 #### List page
-Browsing collections — reports, users, assets, items. The most common page type in data-heavy applications.
 
+Browsing collections — reports, users, assets, items. The most common page type in data-heavy applications.
 
 **Structure**
 
@@ -673,8 +804,8 @@ Tablet: Hide non-essential columns, allow horizontal scroll.
 Mobile: Switch to card/list view with stackable filters.
 
 #### Wizard
-Multi-step creation flows, onboarding, configuration wizards, setup processes.
 
+Multi-step creation flows, onboarding, configuration wizards, setup processes.
 
 **Structure**
 
@@ -716,10 +847,10 @@ Layout helpers in theme: `--container-2xl` (`{spacing.container-2xl}`), `--conta
 
 Aura adjusts Tailwind **container** breakpoints where the default scale is too wide or too narrow for data-dense product surfaces:
 
-| Token             | Value                     | Role                                                                                                                                                                        |
-| ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--container-2xl` | `{spacing.container-2xl}` | Narrower than Tailwind’s default `2xl` container — useful outer bound for regions; **body copy** inside can still follow the **`{spacing.prose-max}`** reading rule above   |
-| `--container-8xl` | `{spacing.container-8xl}` | Wide upper bound for dashboards and full-bleed marketing rows                                                                                                               |
+| Token             | Value                     | Role                                                                                                                                                                      |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--container-2xl` | `{spacing.container-2xl}` | Narrower than Tailwind’s default `2xl` container — useful outer bound for regions; **body copy** inside can still follow the **`{spacing.prose-max}`** reading rule above |
+| `--container-8xl` | `{spacing.container-8xl}` | Wide upper bound for dashboards and full-bleed marketing rows                                                                                                             |
 
 Prefer **`max-w-*`** (and other width utilities) tied to the theme over ad-hoc pixel `max-width` on wrappers. **Global frame** width (host chrome) is defined by the **host application**; **inside** the frame, combine these tokens with responsive utilities so regions reflow predictably.
 
@@ -840,8 +971,6 @@ Heights are **not** always single CSS variables; primitives use Tailwind height
 
 **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.
 
-
-
 ### Global primitive rules
 
 1. Prefer primitives over custom components.
@@ -855,9 +984,11 @@ Heights are **not** always single CSS variables; primitives use Tailwind height
 Sections are in alphabetical order. For each component, the Storybook link is the primary reference for variants and props; the docs link is the primary reference for usage and design guidance.
 
 #### Storybook reference
+
 Anytime you need to reference a component in Storybook, use the following URL and replace the slug with the component's Storybook slug: https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-{storybook-slug}--docs
 
-#### Docs reference 
+#### Docs reference
+
 Anytime you need to reference a component in docs, use the following URL and replace the slug with the component's doc slug: https://docs.cognite.com/aura-design-system/primitives/{docs-slug}
 
 #### Accordion
@@ -869,28 +1000,33 @@ Anytime you need to reference a component in docs, use the following URL and rep
 Accordion reveals and hides grouped content sections to reduce cognitive load and page density.
 
 **Use when**
+
 - Grouping settings in side/config panels.
 - Breaking long forms into manageable sections.
 - Organizing docs/FAQ/help content.
 - Showing nested information hierarchies.
 
 **Use something else when**
+
 - All content must stay visible for comparison/scanning.
 - Content is short and easy to read without progressive disclosure.
 - Users are making high-stakes or multi-step decisions where hidden content can cause errors.
 
 **Dos and don'ts**
+
 - Do use clear, specific section titles.
 - Do keep icon and heading behavior consistent.
 - Do not use for very short/simple content.
 - Do not nest accordions.
 
 **Behavior**
+
 - Header controls expand/collapse via click/tap/Enter/Space.
 - Support multi-expand unless product pattern requires single-expand.
 - Keep expanded content available to assistive tech.
 
 **Often used with**
+
 - `Separator`, section headings, and form controls inside panel content.
 
 #### Action Toolbar
@@ -902,25 +1038,30 @@ Accordion reveals and hides grouped content sections to reduce cognitive load an
 Action toolbar is a transient bottom-aligned action row that appears when users select items (for example in data-heavy views).
 
 **Use when**
+
 - Actions apply only to selected items.
 - You need to reduce persistent toolbar clutter in tables/lists/cards.
 - The workflow depends on selected state before next actions are valid.
 
 **Use something else when**
+
 - Actions are page-level and do not require selection first (use a standard toolbar/page actions).
 
 **Dos and don'ts**
+
 - Do keep actions contextual to the current selection.
 - Do keep the set focused (use overflow when needed).
 - Do center it in the container/page scope.
 - Do not make it draggable.
 
 **Behavior**
+
 - Hidden by default; appears after selection.
 - Anchored to bottom area; remains until selection clears, action completes, or user navigates away.
 - If no reload occurs, it exits after action completion.
 
 **Often used with**
+
 - Selection patterns in data views, `Checkbox`, `Button`, `Menu`, and `Tooltip` for icon-only actions.
 
 #### Alert
@@ -932,26 +1073,31 @@ Action toolbar is a transient bottom-aligned action row that appears when users
 Alert communicates contextual, medium-emphasis information inside page/task flow. It is not a blocking modal.
 
 **Use when**
+
 - Providing inline guidance/recommendations in the current task.
 - Calling attention to warnings/issues that need awareness but are not blocking.
 - Offering direct actions that resolve the issue in context.
 
 **Dos and don'ts**
+
 - Do include action buttons only when actions are directly related to resolving/dismissing the alert.
 - Do evaluate simpler feedback methods first (for example field-level validation).
 - Do not attach unrelated actions.
 
 **Placement**
+
 - Align with surrounding content; do not pin flush against dividers.
 - Use card style for wrapped content in constrained areas.
 - Use strip style for short messages in wider areas.
 
 **Behavior**
+
 - Inline with page flow (not full-screen blocking).
 - Dismissal removes/hides alert per variant.
 - Action path should be clear and minimal.
 
 **Often used with**
+
 - `Button` for direct resolution actions.
 
 #### Alert Dialog
@@ -962,15 +1108,18 @@ Alert communicates contextual, medium-emphasis information inside page/task flow
 Short, focused confirmation or acknowledgment that interrupts the user for a clear binary or limited choice.
 
 **Use when**
+
 - Confirming destructive or irreversible actions.
 - Blocking until the user chooses from a small set of options.
 
 **Use something else when**
+
 - Inline persistence is enough (`Alert`).
 - The flow requires a form or multi-field input (`Dialog`).
 - A quick acknowledgment is sufficient (`Sonner Toast`).
 
 **Often used with**
+
 - `Button` (destructive variant) as the trigger.
 
 #### Avatar
@@ -982,17 +1131,20 @@ Short, focused confirmation or acknowledgment that interrupts the user for a cle
 Avatar visually represents a user, team, or concept and helps recognition in collaborative UI.
 
 **Use when**
+
 - Showing people in comments, chat, sharing, or collaborators.
 - Representing accounts, teams, or organizations.
 - Displaying AI/agent identities in conversational interfaces.
 
 **Behavior**
+
 - Choose size based on context density.
 - Use overflow patterns for constrained spaces (for example +N with menu).
 - Can be informational or interactive based on context.
 - Can include status badges/dots.
 
 **Often used with**
+
 - `Badge`, `Tooltip`, `Menu`.
 
 #### Badge
@@ -1004,14 +1156,17 @@ Avatar visually represents a user, team, or concept and helps recognition in col
 Compact label for status, category, or metadata.
 
 **Use when**
+
 - Surfacing state at a glance (for example active, draft, error).
 - Tagging items without taking primary focus from the page.
 
 **Use something else when**
+
 - The message needs explanation or recovery steps (consider `Alert` or inline text).
 - You need a primary action (use `Button`).
 
 **Often used with**
+
 - `Avatar`, tables and lists, filter chips.
 
 #### Banner
@@ -1023,10 +1178,12 @@ Compact label for status, category, or metadata.
 Persistent or dismissible message scoped at page or section level — stronger than inline helper text, broader than a single-field `Alert` in some layouts.
 
 **Use when**
+
 - Announcing environment or product state (maintenance, trial, feature preview).
 - Page-wide outcomes that should stay visible while the user continues.
 
 **Use something else when**
+
 - Task-specific guidance inside a flow (`Alert`).
 - Brief confirmation after an action (`Sonner Toast`).
 
@@ -1039,26 +1196,31 @@ Persistent or dismissible message scoped at page or section level — stronger t
 Hierarchical navigation aid that shows users their current location within the product's structure. Location-based, not path-based.
 
 **Use when**
+
 - Users need to return to a parent page.
 - Users need clarity on their current position in the product hierarchy.
 - Quick access to ancestor pages is useful.
 
 **Use something else when**
+
 - The page structure is flat — there is no hierarchy to show.
 - Users are switching between same-level content (use `Tabs` or `Segmented Control`).
 
 **Dos and don'ts**
+
 - Do not make the current breadcrumb clickable.
 - Do not pair with a back button.
 - Do not wrap breadcrumb labels to multiple lines; truncate and use `Tooltip` for full text.
 - Show only one breadcrumb trail per page.
 
 **Behavior**
+
 - All links except the current page are interactive (Tab, Shift+Tab, Enter).
 - When space is limited, condense middle items into an overflow menu showing the first and last two links.
 - The active page link always remains visible.
 
 **Often used with**
+
 - `Tooltip` for truncated labels, `Menu` for overflow segments, `Topbar`.
 
 #### Button
@@ -1070,15 +1232,18 @@ Hierarchical navigation aid that shows users their current location within the p
 Primary control for discrete actions.
 
 **Use when**
+
 - Committing, navigating a clear next step, or triggering destructive work (with confirmation pattern).
 
 **Dos and don'ts**
+
 - One primary action per logical section when possible.
 - Match variant to risk: destructive actions use destructive variant and confirmation.
 - Label with verb + object (see Content guidelines in `./DESIGN.md`).
 - Icon-only actions need an accessible name (`aria-label`).
 
 **Often used with**
+
 - `Button Group`, `Dialog`, forms.
 
 #### Button Group
@@ -1089,14 +1254,17 @@ Primary control for discrete actions.
 Visually joins related buttons into a connected row, clarifying that the actions belong to the same context.
 
 **Use when**
+
 - Two or more actions are closely related and operate on the same target (for example, a split-button or segmented action row).
 - Conserving horizontal space compared to individually spaced buttons.
 
 **Use something else when**
+
 - Actions are unrelated and should not appear grouped.
 - You need more than a small set of actions (consider `Toolbar` or `Dropdown Menu`).
 
 **Often used with**
+
 - `Button`, `Tooltip` for icon-only variants.
 
 #### Card
@@ -1108,19 +1276,23 @@ Visually joins related buttons into a connected row, clarifying that the actions
 A structural container with optional header, body, and footer slots for displaying data artifacts, widgets, or media. The Card with Count variant adds a numeric indicator to the header.
 
 **Use when**
+
 - Presenting charts, visualizations, or data widgets.
 - Building grids of comparable items where list/grid view toggling is needed.
 - Displaying media content (images, videos).
 
 **Use something else when**
+
 - You just need visual separation between sections — use `Separator` and spacing instead.
 - You are comparing dense metadata across rows — use `Table` or a data grid instead.
 
 **Dos and don'ts**
+
 - Cards are structural containers only; interactive elements (`Button`, `Checkbox`) go inside the body or actions area.
 - Exception: the entire card can serve as a single focusable target when it acts as a link or selection item.
 
 **Often used with**
+
 - `Button`, `Badge`, `Avatar`, `Separator`, charts, lists, or form fields in the body.
 
 #### Checkbox
@@ -1132,16 +1304,19 @@ A structural container with optional header, body, and footer slots for displayi
 Enables users to independently select one or multiple options. Can appear standalone or within menus, tree views, tables, or cards.
 
 **Use when**
+
 - Multiple independent selections are required (for example, column visibility in a table).
 - Enabling or disabling settings where changes do not take immediate effect.
 - Confirming agreement before an action (for example, delete verification).
 
 **Use something else when**
+
 - Only one option can be selected at a time (use `Radio`).
 - Options are not displayed simultaneously (use `Select`).
 - You need an immediate on/off toggle (use `Switch`).
 
 **Dos and don'ts**
+
 - Do provide a label for every checkbox.
 - Do implement indeterminate states for partial group selection.
 - Do not pre-select checkboxes automatically.
@@ -1149,11 +1324,13 @@ Enables users to independently select one or multiple options. Can appear standa
 - Do not use card variants for long option lists.
 
 **Behavior**
+
 - Space key toggles focused checkboxes.
 - Indeterminate state is set programmatically, not by user interaction.
 - Parent-child relationships follow selection cascading rules.
 
 **Often used with**
+
 - `Label`, helper text for groups, `Card` variant for options needing descriptions.
 
 #### Collapsible
@@ -1165,25 +1342,30 @@ Enables users to independently select one or multiple options. Can appear standa
 A single inline expandable block that toggles content visibility. Designed for one independent optional section, not multiple stacked areas.
 
 **Use when**
+
 - Showing one optional or secondary block of content (for example, AI reasoning, advanced settings, a preview).
 - Content is useful but not essential to the primary task.
 
 **Use something else when**
+
 - You have multiple expandable sections (use `Accordion`).
 - Content is essential — show it by default.
 - Users are navigating or filtering (use `Tabs` or filter controls).
 
 **Dos and don'ts**
+
 - Do default to collapsed unless the collapsible content is the main purpose of the view.
 - Do keep the trigger label descriptive — it should communicate what's inside.
 - Do not nest collapsibles; use `Accordion` for layered disclosure.
 - Do not hide errors or required information.
 
 **Behavior**
+
 - One trigger controls one associated region with optional animation.
 - State changes must be exposed to assistive technology.
 
 **Often used with**
+
 - `Separator` when stacking multiple collapsible regions on a page.
 
 #### Combobox
@@ -1195,27 +1377,32 @@ A single inline expandable block that toggles content visibility. Designed for o
 A searchable select input that filters options as users type. Supports single and multi-select modes with optional ability to add new items.
 
 **Use when**
+
 - More than approximately 12 options where search efficiency beats scrolling.
 - Users have a general sense of what they're looking for (country, asset name, tag).
 - Users need to add new options not in the predefined list.
 
 **Use something else when**
+
 - Fewer than ~12 options: prefer `Select`, `Radio`, or `Checkbox`.
 - Users are unfamiliar with available options and need a visible list.
 - Very large datasets risk performance lag: use a data grid with filtering.
 - Pure text entry without selection (use `Input` or `Textarea`).
 
 **Dos and don'ts**
+
 - Do group related options into categories.
 - Do position checkmarks right-aligned in menus.
 - Do not use for simple binary choices or small option sets.
 - Do not place icons or badges on the left side of menu items.
 
 **Behavior**
+
 - Single-select closes immediately on selection.
 - Multi-select stays open until the user clicks outside, presses Escape, or Enter.
 
 **Often used with**
+
 - `Label`, helper text, `Badge`.
 
 #### Command
@@ -1227,16 +1414,19 @@ A searchable select input that filters options as users type. Supports single an
 A keyboard-first search interface for discovering and executing actions, navigating pages, or looking up content application-wide. Typically activated via ⌘K / Ctrl+K and displayed inside a `Dialog` or `Popover`.
 
 **Use when**
+
 - Enabling keyboard-driven workflows across an entire application.
 - Providing power-user shortcuts to actions and destinations.
 - The application has too many actions or pages to surface in a standard nav.
 
 **Use something else when**
+
 - Filtering a specific list or dataset (use `Search`).
 - Selecting from known form options (use `Combobox` or `Select`).
 - Navigating between a small number of pages (use `Tabs` or nav links).
 
 **Dos and don'ts**
+
 - Do organize results into logical categories.
 - Do use action-oriented labels ("Create asset," "Switch to dark mode").
 - Do display the keyboard shortcut on triggering elements.
@@ -1245,10 +1435,12 @@ A keyboard-first search interface for discovering and executing actions, navigat
 - Do require confirmation steps for destructive actions.
 
 **Behavior**
+
 - Keyboard-first interface presenting categorized, scannable action lists.
 - Shows loading indicators for async results and meaningful empty states.
 
 **Often used with**
+
 - `Dialog`, `Popover`, `Search`, `Empty State`.
 
 #### Count
@@ -1259,13 +1451,16 @@ A keyboard-first search interface for discovering and executing actions, navigat
 A compact numeric indicator used to surface quantities inline — for example, unread messages, selected items, or totals attached to labels or tabs.
 
 **Use when**
+
 - Showing a quantity associated with a label, tab, or list item.
 - Surfacing unread counts or selection totals without taking primary focus.
 
 **Use something else when**
+
 - The value represents status or category rather than a quantity (use `Badge`).
 
 **Often used with**
+
 - `Tabs`, `Badge`, `Label`, list items.
 
 #### Date Picker
@@ -1277,20 +1472,24 @@ A compact numeric indicator used to surface quantities inline — for example, u
 Allows users to select a single date through a calendar interface, ensuring proper formatting and avoiding input errors.
 
 **Use when**
+
 - Users need to select an exact date.
 - Preventing manual date-formatting errors is important.
 
 **Use something else when**
+
 - Relative dates are more appropriate ("Last week") — add shortcut options instead.
 - The date is fixed or recurring (consider a cron expression or plain `Input`).
 - Exact timing is not critical (use basic `Input`).
 
 **Behavior**
+
 - Opens a calendar anchored to the input field.
 - Keyboard users can type valid values directly without using the picker.
 - Values commit in the configured locale format.
 
 **Often used with**
+
 - `Label`, helper text, `Date Range Picker`.
 
 #### Date Range Picker
@@ -1302,18 +1501,22 @@ Allows users to select a single date through a calendar interface, ensuring prop
 Allows users to select a start and end date from a calendar interface. Used for filtering by date ranges, comparing periods, or scheduling.
 
 **Use when**
+
 - Users need to specify a date range for filtering or reporting.
 - Comparing data across a period.
 
 **Use something else when**
+
 - Only a single date is needed (use `Date Picker`).
 - Relative ranges like "Last 7 days" cover most use cases — add shortcut options.
 
 **Behavior**
+
 - Enforces start/end ordering with validation messages.
 - Keyboard users can type valid values directly.
 
 **Often used with**
+
 - `Label`, helper text, `Date Picker`.
 
 #### Date Time Range Picker
@@ -1325,17 +1528,21 @@ Allows users to select a start and end date from a calendar interface. Used for
 Allows users to select start and end date and time values. Used when precise time boundaries matter, for example scheduling or time-series filtering.
 
 **Use when**
+
 - Users must specify both a date and time for a range (scheduling, time-series queries).
 
 **Use something else when**
+
 - Time precision is not required (use `Date Range Picker`).
 - Only a single point in time is needed (use `Date Picker` or `Time Picker`).
 
 **Behavior**
+
 - Enforces start/end ordering; validates that end is after start.
 - Keyboard users can type valid values directly.
 
 **Often used with**
+
 - `Label`, helper text, `Date Range Picker`.
 
 #### Dialog
@@ -1347,14 +1554,17 @@ Allows users to select start and end date and time values. Used when precise tim
 Richer content surface: forms, multi-field flows, or explanations that do not fit a strip or inline pattern.
 
 **Use when**
+
 - Collecting input or showing structured content that needs focus without leaving the page.
 
 **Use something else when**
+
 - Inline persistence is enough (`Alert`).
 - Only a quick acknowledgement is needed (`Sonner Toast`).
 - The action is binary and destructive (use `Alert Dialog`).
 
 **Often used with**
+
 - `Button`, `Form`, `Alert Dialog` for confirmation steps.
 
 #### Drawer
@@ -1365,9 +1575,11 @@ Richer content surface: forms, multi-field flows, or explanations that do not fi
 Secondary surface that slides in for filters, detail, or medium-length tasks without a full page change.
 
 **Use when**
+
 - Supporting the main view (filters, record details, auxiliary forms).
 
 **Use something else when**
+
 - The task needs full attention or multi-step wizard treatment (full page or `Dialog`).
 - Content is very short (consider `Popover` or inline).
 
@@ -1379,20 +1591,24 @@ Secondary surface that slides in for filters, detail, or medium-length tasks wit
 A button-triggered overlay listing a set of related actions or options. One of the two menu variants (the other being a context menu, which is right-click triggered). See also: `Menu`.
 
 **Use when**
+
 - A button needs to reveal secondary or overflow actions without persistent UI.
 - Grouping related actions behind a single trigger to reduce visual clutter.
 
 **Use something else when**
+
 - Options require complex selection or rich descriptions (use `Select Panel`).
 - Actions need user confirmation (use `Dialog` or `Alert Dialog`).
 - The action set is always visible and primary (use `Toolbar`).
 
 **Behavior**
+
 - Closes after selection by default.
 - Positions above, below, or beside the trigger depending on viewport space.
 - Submenus open on hover.
 
 **Often used with**
+
 - `Button`, `Separator`, `Badge`, checkbox toggles.
 
 #### Empty State
@@ -1404,9 +1620,11 @@ A button-triggered overlay listing a set of related actions or options. One of t
 Placeholder when there is no data yet or results are empty.
 
 **Use when**
+
 - Lists, tables, charts, or artifacts have zero rows/points.
 
 **Dos and don'ts**
+
 - Explain what will appear and how to get started.
 - Include a single clear CTA when creation/import applies.
 
@@ -1418,15 +1636,18 @@ Placeholder when there is no data yet or results are empty.
 A structural wrapper for form fields that manages layout, spacing, validation state propagation, and submission handling.
 
 **Use when**
+
 - Collecting structured user input across one or more fields.
 - Grouping related fields with shared validation and submission logic.
 
 **Dos and don'ts**
+
 - Do group semantically related fields together.
 - Do associate every field with a `Label`.
 - Do not use `Form` as a generic container when no submission or validation is needed.
 
 **Often used with**
+
 - `Input`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Label`, `Button` (submit), `Dialog`.
 
 #### Input
@@ -1438,28 +1659,72 @@ A structural wrapper for form fields that manages layout, spacing, validation st
 Single-line text field for capturing short text-based information in forms and toolbars.
 
 **Use when**
+
 - Collecting specific text data (names, credentials, asset identifiers).
 - A form field requires free text that doesn't fit a structured picker.
 
 **Use something else when**
+
 - Selecting from predefined options (use `Select`, `Combobox`, `Checkbox`, or `Radio`).
 - Suggestions as the user types are needed (use `Combobox`).
 - Selecting dates or times (use `Date Picker` / `Time Picker`).
 - Multi-line text is expected (use `Textarea`).
 
 **Dos and don'ts**
+
 - Do not use long placeholder text that duplicates the label.
 - Do not mimic pre-filled content with placeholder text.
 - Do not wrap text in an input; truncate or switch to `Textarea`.
 
 **Behavior**
+
 - Single-line only; updates as the user types.
 - Validation messages associate with the field for accessibility.
 - Supports leading (icon, prefix) and trailing (button, suffix, stepper) slots.
 
 **Often used with**
+
 - `Label`, helper text, `Button`, `Tooltip`.
 
+#### Item
+
+**Storybook-slug:** item
+**Docs-slug:** item
+
+**Definition**
+A flexible list-row primitive for displaying a title, optional description, leading media, and trailing actions. Composes into groups for lists, trees, cards, and popovers.
+
+**Use when**
+
+- Building selectable or navigable rows in lists and tree views.
+- Showing a compact row with icon or avatar, title, and optional description.
+- Revealing row actions on hover or keyboard focus.
+
+**Use something else when**
+
+- Selecting from predefined options in a dropdown (use `Select` or `Dropdown Menu`).
+- Displaying form inputs inline (use `Field` patterns with `Checkbox`, `Radio`, or `Switch`).
+- Presenting dense tabular data across many columns (use `Table` or `DataGrid`).
+
+**Dos and don'ts**
+
+- Compose rows with `ItemGroup`, `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, and `ItemDescription`.
+- Use `ItemActions` for hover-revealed icon buttons.
+- Place `ItemSectionHeader` as a sibling of `ItemGroup`, not inside it — `ItemGroup` renders a `<ul>`, which only accepts `<li>` children.
+- Do not use `Item` as a generic card container (use `Card`).
+
+**Behavior**
+
+- `ItemGroup` renders a `<ul>` and `Item` a `<li>`; place interactive elements (links, buttons) inside the row rather than replacing it.
+- Hover and keyboard focus-within apply `accent-background` unless the row is disabled; selected rows use the stronger `secondary-background`.
+- Disabled rows use `base-foreground-disabled` without opacity reduction. `disabled` is presentational — disable interactive children (buttons, links, checkboxes) yourself when the row is unavailable.
+- Row actions appear on hover and when the row receives keyboard focus.
+- Set `Avatar` `sizes` on the `Avatar` itself; `Item` and `ItemMedia` do not size media from description presence.
+
+**Often used with**
+
+- `Button`, `Avatar`, `Checkbox`, `Separator`, `List`, `Tree`.
+
 #### Label
 
 **Storybook-slug:** label
@@ -1469,20 +1734,24 @@ Single-line text field for capturing short text-based information in forms and t
 A form label that identifies and is programmatically associated with an input field. Not intended as general-purpose text.
 
 **Use when**
+
 - Every `Input`, `Select`, `Combobox`, `Textarea`, `Checkbox` group, `Radio` group, `Switch`, `Slider`, or `Date Picker` needs one.
 
 **Use something else when**
+
 - You need a heading or section title (use appropriate heading levels).
 - You need descriptive text below a field (use helper text).
 - You are labeling a non-interactive element like a status indicator (use plain text or `Badge`).
 
 **Dos and don'ts**
+
 - Do associate labels with fields via `htmlFor`/`id` for accessibility.
 - Do mark required fields consistently (asterisk or explicit text).
 - Do not replace labels with placeholder text — placeholders disappear and are inaccessible.
 - Do not hide labels for visual cleanliness; use `Tooltip` to supplement shortened labels.
 
 **Often used with**
+
 - `Input`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Switch`, `Slider`, `Textarea`, `Date Picker`.
 
 #### Menu
@@ -1494,24 +1763,29 @@ A form label that identifies and is programmatically associated with an input fi
 Presents a list of actions, options, or states for the current selection or context. Two variants: context menu (right-click/long-press trigger) and dropdown menu (button trigger). See also: `Dropdown Menu`.
 
 **Use when**
+
 - Offering action choices from a button, select, or combobox when space is constrained.
 - Exposing contextual actions via right-click without dedicated trigger UI.
 
 **Use something else when**
+
 - Options require reordering or rich descriptions (use `Select Panel`).
 - Actions need user confirmation before executing (use `Dialog`, `Alert Dialog`, or `Popover`).
 
 **Dos and don'ts**
+
 - Do keep items left-aligned and styled consistently within sections.
 - Do separate actions into labeled sections using `Separator`.
 - Do not mix items with and without leading content (icons/toggles) in the same section.
 
 **Behavior**
+
 - Closes after selection unless multi-select is enabled.
 - Positions above, below, left, or right of the trigger with a 4px gap, adapting to viewport space.
 - Submenus open on hover.
 
 **Often used with**
+
 - `Button`, `Select`, `Combobox`, `Separator`, `Badge`, checkbox toggles.
 
 #### Pagination
@@ -1523,28 +1797,33 @@ Presents a list of actions, options, or states for the current selection or cont
 Divides large datasets into pages, giving users control over navigation and improving load performance.
 
 **Use when**
+
 - Datasets are large (tables, search results, galleries).
 - Performance concerns rule out infinite scroll.
 - Users need to bookmark or return to a specific page position.
 
 **Use something else when**
+
 - The context is a discovery feed (use infinite scroll or "Load more").
 - Users are completing a sequential task (use a wizard/stepper).
 - You need to switch between unrelated modes (use `Segmented Control` or `Tabs`).
 
 **Dos and don'ts**
+
 - Do place pagination below content, left-aligned.
 - Do provide "Next" and "Previous" buttons, disabled when irrelevant.
 - Do include "Results per page" options for large datasets.
 - Do not use pagination when fewer than ~20 items per page exist.
 
 **Behavior**
+
 - Each page should have its own shareable URL.
 - Content loads without full page reloads; use loaders and skeletons while data fetches.
 - Teleport variant allows direct page number entry.
 - Filters, searches, and selections persist across pages.
 
 **Often used with**
+
 - `Table`, data grids, `Search`, `Skeleton`.
 
 #### Popover
@@ -1556,13 +1835,16 @@ Divides large datasets into pages, giving users control over navigation and impr
 A click-triggered panel for interactive or structured supplemental content. Stays open until dismissed.
 
 **Use when**
+
 - User needs to pick options, fill short fields, or read formatted content on demand without leaving the page.
 
 **Use something else when**
+
 - Content is essential to the task — surface it inline or in `Dialog` / `Drawer`.
 - A brief, non-interactive hint is needed (use `Tooltip`).
 
 **Often used with**
+
 - `Button` or icon as trigger, `Command`, form controls inside the panel.
 
 #### Radio
@@ -1574,23 +1856,28 @@ A click-triggered panel for interactive or structured supplemental content. Stay
 Allows users to select exactly one option from a small set of mutually exclusive choices.
 
 **Use when**
+
 - Single selection from a small, visible set of predefined options.
 - All options should be visible side by side for comparison.
 
 **Use something else when**
+
 - Multiple selections are needed (use `Checkbox`).
 - There are more than ~5 options or space is limited (use `Select` or `Combobox`).
 - The choice is binary and takes immediate effect (use `Switch`).
 
 **Dos and don'ts**
+
 - Do pair each radio with a descriptive label.
 - Do not group unrelated options.
 - Do not exceed 5 options.
 
 **Behavior**
+
 - Clicking or pressing Space selects the focused option and deselects others in the group.
 
 **Often used with**
+
 - `Label`, helper text, `Card` variant for options needing supporting descriptions.
 
 #### Search
@@ -1602,16 +1889,19 @@ Allows users to select exactly one option from a small set of mutually exclusive
 A specialized input for locating and filtering content, with built-in search and clear affordances.
 
 **Use when**
+
 - Lists, tables, or datasets need quick item location.
 - Content-heavy pages where scrolling is impractical.
 - Application-wide search (in conjunction with `Command`).
 
 **Use something else when**
+
 - Selecting from predefined options (use `Combobox` or `Select`).
 - Multi-attribute filtering requires dedicated filter controls.
 - General text input unrelated to content discovery (use `Input`).
 
 **Dos and don'ts**
+
 - Do make it clear whether search covers the current list, the page, or the whole app.
 - Do display a no-results state when queries return nothing.
 - Do debounce live search to avoid excessive requests.
@@ -1619,6 +1909,7 @@ A specialized input for locating and filtering content, with built-in search and
 - Do not leave empty results without explanation.
 
 **Often used with**
+
 - `Table`, data grids, `Command`, adjacent filter controls (`Select`, `Combobox`).
 
 #### Segmented Control
@@ -1630,13 +1921,16 @@ A specialized input for locating and filtering content, with built-in search and
 Switches between a small number of peer views or modes on the same page.
 
 **Use when**
+
 - Two to several comparable sections (for example overview vs details vs activity).
 
 **Use something else when**
+
 - Content is hierarchical or lengthy and users must open multiple sections at once (consider `Accordion` or visible sections).
 - Navigating separate routes (tabs/sidebar patterns — see `building-pages.md`).
 
 **Relationship to Accordion**
+
 - Segmented control swaps visibility of peer panels; accordion stacks expandable sections. Prefer segmented control when users switch modes frequently; accordion when progressive disclosure matters.
 
 #### Select
@@ -1648,11 +1942,13 @@ Switches between a small number of peer views or modes on the same page.
 Enables users to choose one or more predefined options from a dropdown list. Used in forms and filtering when space is constrained.
 
 **Use when**
+
 - Multiple predefined options exist and space prevents showing them all at once.
 - Options are familiar and don't require explanation.
 - A single or multi-select form input is needed.
 
 **Use something else when**
+
 - 12+ options or search is needed (use `Combobox`).
 - Few options or a binary choice (use `Checkbox`, `Radio`, or `Switch`).
 - User-created values are needed (use `Combobox`).
@@ -1660,15 +1956,18 @@ Enables users to choose one or more predefined options from a dropdown list. Use
 - Selection triggers immediate mode-switch (use `Segmented Control` or `Tabs`).
 
 **Dos and don'ts**
+
 - Do provide a clear label and placeholder.
 - Do use helper text when clarification is needed.
 - Exercise caution with default selections — users may overlook them.
 
 **Behavior**
+
 - Single-select closes after selection; multi-select may remain open.
 - Checkmarks appear right-aligned in the list.
 
 **Often used with**
+
 - `Label`, helper text, `Button`.
 
 #### Separator
@@ -1680,20 +1979,24 @@ Enables users to choose one or more predefined options from a dropdown list. Use
 A 1px visual divider between distinct content sections. Improves readability while remaining visually subtle.
 
 **Use when**
+
 - Creating visual relief between related groups of content.
 - Dividing sections within toolbars, menus, cards, or forms.
 
 **Use something else when**
+
 - The layout is sparse — whitespace alone is sufficient.
 - Sections need semantic grouping (use headings, `Card`, or background regions instead).
 
 **Dos and don'ts**
+
 - Do use 16px vertical separators for button or horizontal form element separation.
 - Do not place separators between every element.
 - Do not use bold or colorful separators — keep them subtle.
 - Do not replace semantic headings or landmarks with separators.
 
 **Often used with**
+
 - `Toolbar`, `Card` headers/footers, `Accordion`, menus, dense form sections.
 
 #### Skeleton
@@ -1704,18 +2007,22 @@ A 1px visual divider between distinct content sections. Improves readability whi
 A loading placeholder that mimics the shape of incoming content, reducing perceived wait time and preventing layout shift.
 
 **Use when**
+
 - Content is loading and the shape of the result is predictable (cards, lists, table rows).
 - Reducing layout shift while data fetches in the background.
 
 **Use something else when**
+
 - The loading duration is very short (<300ms) — no loader is needed.
 - The content shape is unpredictable (use a spinner or progress indicator).
 
 **Dos and don'ts**
+
 - Do match skeleton shapes to the actual content layout.
 - Do not animate excessively — subtle pulse is sufficient.
 
 **Often used with**
+
 - `Card`, `Table`, `Pagination`, lists.
 
 #### Slider
@@ -1727,19 +2034,23 @@ A loading placeholder that mimics the shape of incoming content, reducing percei
 An interactive control for selecting a single value or a range from a continuous scale. Provides visual feedback and quick approximate value selection.
 
 **Use when**
+
 - Adjusting continuous values where precision is less important than visual feedback (volume, brightness, pricing filter).
 - Providing immediate visual feedback (media scrubbing, live previews).
 - Selecting a minimum and maximum range.
 
 **Use something else when**
+
 - Precise numeric entry is required (use `Input` or `Select`).
 - The choice is categorical, not continuous (use `Radio` or `Select`).
 
 **Behavior**
+
 - Supports immediate feedback (changes apply as the user drags) and deferred feedback (changes apply on submit).
 - Use deferred feedback when slider adjustments trigger screen reloads or visual disruptions; pair with helper text explaining that the user must submit to apply.
 
 **Often used with**
+
 - `Label`, helper text, optional adjacent `Input` for precise numeric entry.
 
 #### Sonner Toast
@@ -1751,10 +2062,12 @@ An interactive control for selecting a single value or a range from a continuous
 Lightweight, auto-dismiss feedback for outcomes that do not need a blocking surface.
 
 **Use when**
+
 - Confirming save, delete, or background completion.
 - Non-critical notices the user can miss without breaking a workflow.
 
 **Use something else when**
+
 - User must read and act before continuing (`Alert Dialog`, `Dialog`, or persistent `Alert` / `Banner`).
 
 #### Switch
@@ -1766,22 +2079,27 @@ Lightweight, auto-dismiss feedback for outcomes that do not need a blocking surf
 A binary toggle control that turns a setting on or off, with changes taking effect immediately.
 
 **Use when**
+
 - Toggling a setting that takes immediate effect (for example, dark mode, notifications).
 
 **Use something else when**
+
 - The change is form-dependent and deferred (use `Checkbox` or `Button`).
 - The action is one-time or destructive (use `Button`).
 - Multiple related toggles need grouping (use `Toggle Group`, `Checkbox`, or `Select`).
 
 **Dos and don'ts**
+
 - Do apply a clear, descriptive label explaining the switch's function.
 - Do not embed switches inside `Menu` components — use menu checkmarks instead.
 - Do not use for destructive actions.
 
 **Behavior**
+
 - Responds instantly to user interaction without requiring separate form submission.
 
 **Often used with**
+
 - `Label`, helper text.
 
 #### Table
@@ -1792,13 +2110,16 @@ A binary toggle control that turns a setting on or off, with changes taking effe
 Dense, scannable display of rows and columns with optional selection and actions.
 
 **Use when**
+
 - Comparing rows, scanning many attributes, or operating on multiple items.
 
 **Use something else when**
+
 - A simple fixed list of links or single-column items (`List`).
 - A primary chart or narrative view (`Card`, charts — see Storybook).
 
 **Often used with**
+
 - Selection + `Action Toolbar` (when selection-gated actions apply), `Pagination`, `Empty State`, row `Checkbox`, `Dropdown Menu` for row actions.
 
 #### Tabs
@@ -1810,16 +2131,19 @@ Dense, scannable display of rows and columns with optional selection and actions
 Organizes related content into switchable sections, allowing users to navigate between different views without leaving the page.
 
 **Use when**
+
 - Organizing content into sections users switch between frequently.
 - Displaying related, mutually exclusive content.
 - Navigation within pages, dashboards, settings, or data views.
 
 **Use something else when**
+
 - Filtering a list or dataset (use `Segmented Control`, `Button`, or `Menu`).
 - Multiple sections must be visible simultaneously (use `Accordion` or filters).
 - The choice is a binary toggle (use `Switch`).
 
 **Dos and don'ts**
+
 - Do use a minimum of two tabs.
 - Do keep content above tabs stable across all tab states.
 - Do use leading icons consistently across all tabs or not at all.
@@ -1827,11 +2151,13 @@ Organizes related content into switchable sections, allowing users to navigate b
 - Do not apply to binary options.
 
 **Behavior**
+
 - Exactly one tab panel is visible at a time.
 - Tab buttons manage selection state and keyboard focus.
 - Supports default, vertical, and full-width alignment options.
 
 **Often used with**
+
 - `Table`, `Form`, `Card`, `Empty State`. Keep global page actions outside tab panels.
 
 #### Textarea
@@ -1843,25 +2169,30 @@ Organizes related content into switchable sections, allowing users to navigate b
 A multi-line text field for extended free-form input such as comments, feedback, messages, descriptions, or notes.
 
 **Use when**
+
 - Multi-line text is expected (comments, notes, bios, explanations).
 - Editing large chunks of existing text.
 
 **Use something else when**
+
 - A single line of text is all that is needed (use `Input`).
 - Structured data is expected (use masked `Input`, `Date Picker`, `Select`, or `Combobox`).
 - Rich formatting is needed (use a rich-text editor).
 
 **Dos and don'ts**
+
 - Do use concise labels and placeholder text.
 - Do allow scroll when content exceeds the maximum height.
 - Do not set a small fixed height for expected lengthy input.
 - Do not pre-fill with default text users might overlook.
 
 **Behavior**
+
 - Supports optional user resizing via a drag handle.
 - Restrict resizing when layout integrity is critical (forms in modals or sidebars) or when the textarea auto-expands programmatically.
 
 **Often used with**
+
 - `Label`, helper text (optionally with character count).
 
 #### Time Picker
@@ -1873,18 +2204,22 @@ A multi-line text field for extended free-form input such as comments, feedback,
 Allows users to select a time value through a clock interface.
 
 **Use when**
+
 - Users need to select a precise time without a date.
 - Scheduling tasks, alarms, or time-of-day settings.
 
 **Use something else when**
+
 - Both date and time are required (use `Date Picker` or `Date Time Range Picker`).
 - Exact timing is not important (use basic `Input`).
 
 **Behavior**
+
 - Keyboard users can type valid values directly.
 - Values commit in the configured locale format.
 
 **Often used with**
+
 - `Label`, helper text, `Date Picker`.
 
 #### Toggle
@@ -1895,14 +2230,17 @@ Allows users to select a time value through a clock interface.
 A single pressable button with active/inactive state, used to toggle one option or formatting command on or off.
 
 **Use when**
+
 - A single binary option needs a visible pressed/unpressed state (for example, bold text, mute).
 
 **Use something else when**
+
 - Two or more related toggles should be grouped (use `Toggle Group`).
 - The change takes immediate app-level effect (use `Switch`).
 - The action is a one-time command (use `Button`).
 
 **Often used with**
+
 - `Toolbar`, `Tooltip` for icon-only variants, `Toggle Group`.
 
 #### Toggle Group
@@ -1913,10 +2251,12 @@ A single pressable button with active/inactive state, used to toggle one option
 A set of 2–4 related toggle options for mutually exclusive or multi-select settings that are always visible.
 
 **Use when**
+
 - Toggling between 2–4 always-visible, mutually exclusive modes (for example, grid lines, text alignment, ruler visibility).
 - The current selection must always be immediately clear.
 
 **Use something else when**
+
 - More than ~4–5 options exist (use `Select` or `Menu`).
 - Options execute one-time commands (use `Button`).
 - Multi-select filtering across a larger set (use `Checkbox` or filter chips).
@@ -1924,14 +2264,17 @@ A set of 2–4 related toggle options for mutually exclusive or multi-select set
 - The context is page navigation (use `Tabs` or routing).
 
 **Dos and don'ts**
+
 - Do keep labels concise — one or two words or icons only.
 - Do not mix icons and text labels within the same group.
 
 **Behavior**
+
 - Selection updates instantly.
 - Supports single-select and multi-select configurations.
 
 **Often used with**
+
 - `Toolbar`, `Tooltip` for icon-only variants.
 
 #### Toolbar
@@ -1942,10 +2285,12 @@ A set of 2–4 related toggle options for mutually exclusive or multi-select set
 Persistent strip of primary tools or filters for a page or region — available without selecting rows first.
 
 **Use when**
+
 - Page-level create/filter/export actions.
 - Tools that apply to the whole view or the current query.
 
 **Use something else when**
+
 - Actions apply only after row/item selection (use `Action Toolbar`).
 
 #### Topbar
@@ -1957,15 +2302,18 @@ Persistent strip of primary tools or filters for a page or region — available
 The single, persistent navigation bar at the top of every authenticated CDF and Flows custom app. Provides the primary orientation layer across three fixed regions: left (identity/breadcrumbs), middle (optional global navigation), and right (system controls).
 
 **Use when**
+
 - Every authenticated screen in a CDF or Flows app — this component is mandatory.
 - The app has two or more top-level views requiring global switching.
 - Actions apply consistently across all app pages (for example, a persistent "Add data" button).
 
 **Use something else when**
+
 - Login or authentication-only screens.
 - Full-screen flows or modals that intentionally hide global chrome.
 
 **Dos and don'ts**
+
 - Do use the middle section for primary global app navigation.
 - Do use `Tabs` for distinct pages, `Segmented Control` for mode switching in the middle section.
 - Do not place page-specific actions in the action slot.
@@ -1973,11 +2321,13 @@ The single, persistent navigation bar at the top of every authenticated CDF and
 - Do not use multiple topbars per page.
 
 **Behavior**
+
 - Left: app mark (small `Avatar`), breadcrumbs, optional inline metadata.
 - Middle: optional; omit for single-view apps.
 - Right (fixed order): Share → Notifications → Theme → Atlas.
 
 **Often used with**
+
 - `Breadcrumb`, `Tabs`, `Segmented Control`, `Avatar`.
 
 #### Tooltip
@@ -1989,14 +2339,17 @@ The single, persistent navigation bar at the top of every authenticated CDF and
 A short hint that appears on hover or focus. No heavy interaction inside.
 
 **Use when**
+
 - Clarifying a control or icon in one line or sentence.
 - Providing the full text of a truncated label (for example in `Breadcrumb`).
 
 **Use something else when**
+
 - Content is essential to the task — surface it inline or in `Dialog` / `Drawer`.
 - Users need to interact with the content (use `Popover`).
 
 **Often used with**
+
 - Icon-only `Button`, `Toggle`, `Breadcrumb`, `Label`.
 
 #### Tree
@@ -2005,30 +2358,34 @@ A short hint that appears on hover or focus. No heavy interaction inside.
 **Docs-slug:** tree-view
 
 **Definition**
-Displays hierarchical data in a nested structure with expandable/collapsible rows. Supports optional selection and drag-and-drop.
+Displays hierarchical data in a nested structure with expandable/collapsible rows. Supports optional cascading checkboxes.
 
 **Use when**
+
 - Presenting large structures with multiple nesting levels (folders, files, organizational hierarchies).
 - Progressive disclosure of complex hierarchical relationships.
 
 **Use something else when**
+
 - Data is not hierarchical (use lists or `Table`).
 - A sortable, tabular layout with multiple columns is needed (use `Table`).
 - Non-hierarchical filtering is the goal (use `Tabs` or `Segmented Control`).
 - Showing location in site hierarchy (use `Breadcrumb`).
 
 **Behavior**
-- Nodes expand and collapse independently.
+
+- Nodes expand and collapse independently via chevron; row click focuses only.
 - Keyboard navigation follows tree semantics (arrow keys, Home/End).
-- Supports single and multi-selection.
-- Optional drag-and-drop reordering (must maintain accessibility).
+- Optional checkboxes cascade to descendants; checked and indeterminate rows receive row fill.
 
 **Often used with**
-- Row checkboxes, row menus, `Badge` for status, drag handles, selection highlights connecting to a side panel or `Table` in split-view layouts.
+
+- Row checkboxes, row menus, `Badge` for status, checkbox highlights connecting to a side panel or `Table` in split-view layouts.
 
 ## Escalation guidance
 
 If a primitive does not fit:
+
 1. Check Storybook variants/props first.
 2. Compose with existing primitives.
 3. If still blocked, note the gap and keep implementation consistent with Aura foundations.
@@ -2154,53 +2511,53 @@ System icons are **functional** shorthand for actions, state, and navigation. Au
 
 Action icons represent operations a user can perform that trigger a change in state, content, or system behavior. They typically appear in interactive, contextual components like buttons, toolbars, context menus, dropdown menus, and inline controls.
 
-| Concept | Icon name | Source | Keywords / aliases | Accepted labels |
-|---|---|---|---|---|
-| Add / New | `plus` | [Tabler](https://tabler.io/icons?icon=plus) | create, add, new, insert | Add, Create |
-| Cancel | `cancel` | [Tabler](https://tabler.io/icons?icon=cancel) | abort, stop | Cancel |
-| Collapse (window) | `arrows-diagonal-minimize-2` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal-minimize-2) | exit fullscreen, collapse, minimize | Collapse |
-| Copy | `copy` | [Tabler](https://tabler.io/icons?icon=copy) | duplicate, clone | Copy |
-| Delete | `trash` | [Tabler](https://tabler.io/icons?icon=trash) | delete, destroy | Delete |
-| Download | `download` | [Tabler](https://tabler.io/icons?icon=download) | save to file, export file | Download |
-| Edit | `pencil` | [Tabler](https://tabler.io/icons?icon=pencil) | modify, rename, update | Edit |
-| Expand (window) | `arrows-diagonal` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal) | fullscreen, expand, maximize | Expand |
-| Filter | `filter` | [Tabler](https://tabler.io/icons?icon=filter) | narrow, refine, search filters | Filter |
-| Hide | `eye-off` | [Tabler](https://tabler.io/icons?icon=eye-off) | hide; conceal, invisible, toggle visibility | Hide |
-| Link | `link` | [Tabler](https://tabler.io/icons?icon=link) | hyperlink, relationship, connected | — |
-| More options (menu opens above or below) | `dots-vertical` | [Tabler](https://tabler.io/icons?icon=dots-vertical) | overflow, actions, kebab menu | — |
-| Notifications | `bell` | [Tabler](https://tabler.io/icons?icon=bell) | alerts, notification center | Notifications |
-| Open external link | `external-link` | [Tabler](https://tabler.io/icons?icon=external-link) | open in new tab, link out | Open |
-| Publish | `rocket` | [Tabler](https://tabler.io/icons?icon=rocket) | deploy, release, go live, launch | Publish |
-| Redo | `arrow-forward-up` | [Tabler](https://tabler.io/icons?icon=arrow-forward-up) | step forward, redo | Redo |
-| Refresh | `reload` | [Tabler](https://tabler.io/icons?icon=reload) | reload page, refresh view | Refresh |
-| Remove / Close | `x` | [Tabler](https://tabler.io/icons?icon=x) | close, dismiss, remove, exit | Close, Remove |
-| Save | `check` | [Tabler](https://tabler.io/icons?icon=check) | save changes, confirm, persist, write | Save |
-| Search | `search` | [Tabler](https://tabler.io/icons?icon=search) | find, look up, query | Search |
-| Settings | `settings` | [Tabler](https://tabler.io/icons?icon=settings) | configure, preferences, gear | Settings |
-| Share | `share` | [Tabler](https://tabler.io/icons?icon=share) | send, distribute, invite | Share |
-| Show | `eye` | [Tabler](https://tabler.io/icons?icon=eye) | show; reveal, visible, unhide | Show |
-| Sync | `refresh` | [Tabler](https://tabler.io/icons?icon=refresh) | synchronize, pull latest, update data | Sync |
-| Undo | `arrow-back-up` | [Tabler](https://tabler.io/icons?icon=arrow-back-up) | revert, undo, step back | Undo |
-| Upload | `upload` | [Tabler](https://tabler.io/icons?icon=upload) | import from file, attach | Upload |
+| Concept                                  | Icon name                    | Source                                                            | Keywords / aliases                          | Accepted labels |
+| ---------------------------------------- | ---------------------------- | ----------------------------------------------------------------- | ------------------------------------------- | --------------- |
+| Add / New                                | `plus`                       | [Tabler](https://tabler.io/icons?icon=plus)                       | create, add, new, insert                    | Add, Create     |
+| Cancel                                   | `cancel`                     | [Tabler](https://tabler.io/icons?icon=cancel)                     | abort, stop                                 | Cancel          |
+| Collapse (window)                        | `arrows-diagonal-minimize-2` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal-minimize-2) | exit fullscreen, collapse, minimize         | Collapse        |
+| Copy                                     | `copy`                       | [Tabler](https://tabler.io/icons?icon=copy)                       | duplicate, clone                            | Copy            |
+| Delete                                   | `trash`                      | [Tabler](https://tabler.io/icons?icon=trash)                      | delete, destroy                             | Delete          |
+| Download                                 | `download`                   | [Tabler](https://tabler.io/icons?icon=download)                   | save to file, export file                   | Download        |
+| Edit                                     | `pencil`                     | [Tabler](https://tabler.io/icons?icon=pencil)                     | modify, rename, update                      | Edit            |
+| Expand (window)                          | `arrows-diagonal`            | [Tabler](https://tabler.io/icons?icon=arrows-diagonal)            | fullscreen, expand, maximize                | Expand          |
+| Filter                                   | `filter`                     | [Tabler](https://tabler.io/icons?icon=filter)                     | narrow, refine, search filters              | Filter          |
+| Hide                                     | `eye-off`                    | [Tabler](https://tabler.io/icons?icon=eye-off)                    | hide; conceal, invisible, toggle visibility | Hide            |
+| Link                                     | `link`                       | [Tabler](https://tabler.io/icons?icon=link)                       | hyperlink, relationship, connected          | —               |
+| More options (menu opens above or below) | `dots-vertical`              | [Tabler](https://tabler.io/icons?icon=dots-vertical)              | overflow, actions, kebab menu               | —               |
+| Notifications                            | `bell`                       | [Tabler](https://tabler.io/icons?icon=bell)                       | alerts, notification center                 | Notifications   |
+| Open external link                       | `external-link`              | [Tabler](https://tabler.io/icons?icon=external-link)              | open in new tab, link out                   | Open            |
+| Publish                                  | `rocket`                     | [Tabler](https://tabler.io/icons?icon=rocket)                     | deploy, release, go live, launch            | Publish         |
+| Redo                                     | `arrow-forward-up`           | [Tabler](https://tabler.io/icons?icon=arrow-forward-up)           | step forward, redo                          | Redo            |
+| Refresh                                  | `reload`                     | [Tabler](https://tabler.io/icons?icon=reload)                     | reload page, refresh view                   | Refresh         |
+| Remove / Close                           | `x`                          | [Tabler](https://tabler.io/icons?icon=x)                          | close, dismiss, remove, exit                | Close, Remove   |
+| Save                                     | `check`                      | [Tabler](https://tabler.io/icons?icon=check)                      | save changes, confirm, persist, write       | Save            |
+| Search                                   | `search`                     | [Tabler](https://tabler.io/icons?icon=search)                     | find, look up, query                        | Search          |
+| Settings                                 | `settings`                   | [Tabler](https://tabler.io/icons?icon=settings)                   | configure, preferences, gear                | Settings        |
+| Share                                    | `share`                      | [Tabler](https://tabler.io/icons?icon=share)                      | send, distribute, invite                    | Share           |
+| Show                                     | `eye`                        | [Tabler](https://tabler.io/icons?icon=eye)                        | show; reveal, visible, unhide               | Show            |
+| Sync                                     | `refresh`                    | [Tabler](https://tabler.io/icons?icon=refresh)                    | synchronize, pull latest, update data       | Sync            |
+| Undo                                     | `arrow-back-up`              | [Tabler](https://tabler.io/icons?icon=arrow-back-up)              | revert, undo, step back                     | Undo            |
+| Upload                                   | `upload`                     | [Tabler](https://tabler.io/icons?icon=upload)                     | import from file, attach                    | Upload          |
 
 **Navigation icons**
 
 Navigation icons represent spatial or positional concepts that help users understand where they are, where they can go, or how to move through an interface. They typically appear in structural, persistent components like sidebars, top bars, breadcrumbs, tabs, and pagination controls.
 
-| Concept | Icon name | Source | Keywords / aliases | Accepted labels |
-|---|---|---|---|---|
-| App switcher | `grid-dots` | [Tabler](https://tabler.io/icons?icon=grid-dots) | apps, modules, switcher, launcher | — |
-| Back | `arrow-left` | [Tabler](https://tabler.io/icons?icon=arrow-left) | back, go back, previous, navigate back | Back |
-| Home | `home` | [Tabler](https://tabler.io/icons?icon=home) | root, dashboard, start, homepage | Home |
-| Open | `chevron-down` | [Tabler](https://tabler.io/icons?icon=chevron-down) | expand, open, closed or opened state | — |
-| Close | `chevron-up` | [Tabler](https://tabler.io/icons?icon=chevron-up) | collapse, close, opened state | — |
-| Open, Next page | `chevron-right` | [Tabler](https://tabler.io/icons?icon=chevron-right) | expand, open, closed state, next, right | — |
-| Last page, skip | `chevrons-right` | [Tabler](https://tabler.io/icons?icon=chevrons-right) | last page, pagination, skip to end | — |
-| Previous page | `chevron-left` | [Tabler](https://tabler.io/icons?icon=chevron-left) | previous, left | — |
-| First page, skip | `chevrons-left` | [Tabler](https://tabler.io/icons?icon=chevrons-left) | first page, pagination, skip to start | — |
-| Location | `map-pin` | [Tabler](https://tabler.io/icons?icon=map-pin) | place, geographic, anchor, location, plant, site, rig, factory, warehouse | — |
-| Sign in | `login-2` | [Tabler](https://tabler.io/icons?icon=login-2) | log in, authenticate, sign in | Sign in |
-| Sign out | `login` | [Tabler](https://tabler.io/icons?icon=login) | log out, sign out, exit session | Sign out |
+| Concept          | Icon name        | Source                                                | Keywords / aliases                                                        | Accepted labels |
+| ---------------- | ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------- |
+| App switcher     | `grid-dots`      | [Tabler](https://tabler.io/icons?icon=grid-dots)      | apps, modules, switcher, launcher                                         | —               |
+| Back             | `arrow-left`     | [Tabler](https://tabler.io/icons?icon=arrow-left)     | back, go back, previous, navigate back                                    | Back            |
+| Home             | `home`           | [Tabler](https://tabler.io/icons?icon=home)           | root, dashboard, start, homepage                                          | Home            |
+| Open             | `chevron-down`   | [Tabler](https://tabler.io/icons?icon=chevron-down)   | expand, open, closed or opened state                                      | —               |
+| Close            | `chevron-up`     | [Tabler](https://tabler.io/icons?icon=chevron-up)     | collapse, close, opened state                                             | —               |
+| Open, Next page  | `chevron-right`  | [Tabler](https://tabler.io/icons?icon=chevron-right)  | expand, open, closed state, next, right                                   | —               |
+| Last page, skip  | `chevrons-right` | [Tabler](https://tabler.io/icons?icon=chevrons-right) | last page, pagination, skip to end                                        | —               |
+| Previous page    | `chevron-left`   | [Tabler](https://tabler.io/icons?icon=chevron-left)   | previous, left                                                            | —               |
+| First page, skip | `chevrons-left`  | [Tabler](https://tabler.io/icons?icon=chevrons-left)  | first page, pagination, skip to start                                     | —               |
+| Location         | `map-pin`        | [Tabler](https://tabler.io/icons?icon=map-pin)        | place, geographic, anchor, location, plant, site, rig, factory, warehouse | —               |
+| Sign in          | `login-2`        | [Tabler](https://tabler.io/icons?icon=login-2)        | log in, authenticate, sign in                                             | Sign in         |
+| Sign out         | `login`          | [Tabler](https://tabler.io/icons?icon=login)          | log out, sign out, exit session                                           | Sign out        |
 
 **Branded icons**
 
@@ -2210,14 +2567,14 @@ Rare exceptions (third-party or Cognite logos inside a cell) use **provided SVGs
 
 - **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.
+  **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)
 
 #### Motion
 
-**What this is:** the rules for **when**, **how fast**, and **how** something should move in Aura-based UIs — durations, easing curves, and which properties to animate — so engineers and agents pick consistent motion instead of inventing values per component. 
+**What this is:** the rules for **when**, **how fast**, and **how** something should move in Aura-based UIs — durations, easing curves, and which properties to animate — so engineers and agents pick consistent motion instead of inventing values per component.
 
 **Motion roles**
 
@@ -2239,12 +2596,12 @@ Every animation plays one of two roles. Role determines how visible, fast, and e
 
 Easing is the rate of speed change — it makes motion feel physical rather than mechanical. Use `cubic-bezier` curves, not linear or default browser easing.
 
-| Curve | cubic-bezier | Use |
-| :--- | :--- | :--- |
-| Standard | `(0.40, 0.00, 0.15, 1.00)` | Motion between two states — most repositioning and in-view transitions |
-| Entrance | `(0.00, 0.00, 0.15, 1.00)` | Elements appearing — decelerates into place, arrives with momentum and lands softly |
-| Exit | `(0.67, 0.00, 0.83, 0.83)` | Elements leaving — accelerates away, lifts off and clears the view decisively |
-| Sine | `(0.33, 0.00, 0.67, 1.00)` | Near-linear; opacity fades and subtle color shifts where a strong ease would distract |
+| Curve    | cubic-bezier               | Use                                                                                   |
+| :------- | :------------------------- | :------------------------------------------------------------------------------------ |
+| Standard | `(0.40, 0.00, 0.15, 1.00)` | Motion between two states — most repositioning and in-view transitions                |
+| Entrance | `(0.00, 0.00, 0.15, 1.00)` | Elements appearing — decelerates into place, arrives with momentum and lands softly   |
+| Exit     | `(0.67, 0.00, 0.83, 0.83)` | Elements leaving — accelerates away, lifts off and clears the view decisively         |
+| Sine     | `(0.33, 0.00, 0.67, 1.00)` | Near-linear; opacity fades and subtle color shifts where a strong ease would distract |
 
 - **Should** treat heavier or larger elements as slower to start and more settled on arrival; lighter, smaller elements can respond and land more quickly.
 - **Must not** let easings overshoot or bounce — restraint is part of the Aura feel (see **Animation anchors**, Calm).
@@ -2253,25 +2610,25 @@ Easing is the rate of speed change — it makes motion feel physical rather than
 
 Aura has no custom `duration-*`/`ease-*` theme tokens — use [Tailwind's transition utilities](https://tailwindcss.com/docs/transition-duration) directly, matching existing components (`accordion.tsx`, `tabs.tsx`, `segmented-control.tsx`):
 
-| Concept | Tailwind utility |
-| :--- | :--- |
-| Duration | `duration-150` / `duration-200` / `duration-300`, or an arbitrary value like `duration-[233ms]` for values off the default scale |
-| Standard / Entrance / Exit / Sine easing | Tailwind's built-in `ease-*` keywords don't match Aura's curves — use an arbitrary value, e.g. `ease-[cubic-bezier(0.40,0.00,0.15,1.00)]` |
-| Which properties animate | `transition-[property-list]`, e.g. `transition-[top,left,width,height]` (see `tabs.tsx`), rather than the broader `transition-all` |
-| Stagger | `delay-[Nms]` per item (arbitrary value, since Tailwind has no stagger primitive), or `[animation-delay:Nms]` when using `@keyframes` |
-| Respect reduced motion | Prefix with `motion-safe:` (already used in `tabs.tsx`, `segmented-control.tsx`) so the transition is skipped for users with reduced-motion enabled |
+| Concept                                  | Tailwind utility                                                                                                                                    |
+| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Duration                                 | `duration-150` / `duration-200` / `duration-300`, or an arbitrary value like `duration-[233ms]` for values off the default scale                    |
+| Standard / Entrance / Exit / Sine easing | Tailwind's built-in `ease-*` keywords don't match Aura's curves — use an arbitrary value, e.g. `ease-[cubic-bezier(0.40,0.00,0.15,1.00)]`           |
+| Which properties animate                 | `transition-[property-list]`, e.g. `transition-[top,left,width,height]` (see `tabs.tsx`), rather than the broader `transition-all`                  |
+| Stagger                                  | `delay-[Nms]` per item (arbitrary value, since Tailwind has no stagger primitive), or `[animation-delay:Nms]` when using `@keyframes`               |
+| Respect reduced motion                   | Prefix with `motion-safe:` (already used in `tabs.tsx`, `segmented-control.tsx`) so the transition is skipped for users with reduced-motion enabled |
 
 **What to animate**
 
 Every animation is built from a combination of these properties:
 
-| Property | Use |
-| :--- | :--- |
-| Position | Moving elements on screen — the most common property for entrances, exits, and layout transitions |
-| Scale | Growing or shrinking — drawing attention or showing hierarchy |
-| Rotation | Less common in UI; adds dynamism when used with restraint |
-| Opacity | Fading in/out — often paired with position or scale for softer transitions |
-| Color | Shifting an element's color — state changes, hover feedback, the aurora accent language |
+| Property     | Use                                                                                                          |
+| :----------- | :----------------------------------------------------------------------------------------------------------- |
+| Position     | Moving elements on screen — the most common property for entrances, exits, and layout transitions            |
+| Scale        | Growing or shrinking — drawing attention or showing hierarchy                                                |
+| Rotation     | Less common in UI; adds dynamism when used with restraint                                                    |
+| Opacity      | Fading in/out — often paired with position or scale for softer transitions                                   |
+| Color        | Shifting an element's color — state changes, hover feedback, the aurora accent language                      |
 | Mask / morph | Revealing through a mask or transforming one shape into another — expressive moments, progressive disclosure |
 
 - **Should** combine 2–3 properties per transition (e.g. position + opacity) rather than relying on one alone.
@@ -2281,9 +2638,9 @@ Every animation is built from a combination of these properties:
 
 Three qualities every Aura animation should reinforce. Use them to test a motion design, not as literal component names.
 
-- **Flow** — continuity. Elements arrive and leave with direction and connection; nothing jumps or teleports. Groups reveal with a natural stagger. *Test: can I follow the motion with my eyes without losing my place?*
-- **Calm** — confidence in restraint. Motion never competes with the industrial data it's presenting. Easings don't overshoot, staggers don't drag, nothing bounces when it should settle. Calm does not mean slow — most motion is quiet **and** fast. *Test: does this still feel good after 8 hours of use?*
-- **Tactile** — motion builds intuition. Buttons snap, panels slide from the edge they belong to, cards lift when selected — the way something moves signals what's possible before the user thinks about it. *Test: can I tell what's interactive just by how it moves?*
+- **Flow** — continuity. Elements arrive and leave with direction and connection; nothing jumps or teleports. Groups reveal with a natural stagger. _Test: can I follow the motion with my eyes without losing my place?_
+- **Calm** — confidence in restraint. Motion never competes with the industrial data it's presenting. Easings don't overshoot, staggers don't drag, nothing bounces when it should settle. Calm does not mean slow — most motion is quiet **and** fast. _Test: does this still feel good after 8 hours of use?_
+- **Tactile** — motion builds intuition. Buttons snap, panels slide from the edge they belong to, cards lift when selected — the way something moves signals what's possible before the user thinks about it. _Test: can I tell what's interactive just by how it moves?_
 
 **Reference example — anatomy of a transition**
 
@@ -2307,15 +2664,15 @@ These rules apply to Aura primitives, host-shell components themed with Aura tok
 
 Aura components handle many accessibility concerns automatically. Composition, copy, focus management, and page structure remain the implementer's job.
 
-| Concern              | Aura handles                                       | You verify                                   |
-| --------------------- | --------------------------------------------------- | --------------------------------------------- |
-| Focus indicators      | `shadow-focus-ring` on interactive elements         | Not hidden by `overflow` or `z-index`        |
-| Keyboard activation    | Button: Enter/Space. Input: standard keys           | Custom elements also respond                  |
-| ARIA roles             | Correct roles on Dialog, SegmentedControl, etc.     | Custom components declare correct roles       |
-| Color contrast         | Token pairs designed for AA compliance              | Page backgrounds don't reduce contrast        |
-| Dark mode              | Semantic tokens adapt automatically                 | Custom colors also work in dark mode          |
-| Disabled states        | Communicated via `aria-disabled`                    | Reason for disabled is accessible             |
-| Focus trapping         | Dialog traps focus while open                       | Focus returns to the trigger element on close |
+| Concern             | Aura handles                                    | You verify                                    |
+| ------------------- | ----------------------------------------------- | --------------------------------------------- |
+| Focus indicators    | `shadow-focus-ring` on interactive elements     | Not hidden by `overflow` or `z-index`         |
+| Keyboard activation | Button: Enter/Space. Input: standard keys       | Custom elements also respond                  |
+| ARIA roles          | Correct roles on Dialog, SegmentedControl, etc. | Custom components declare correct roles       |
+| Color contrast      | Token pairs designed for AA compliance          | Page backgrounds don't reduce contrast        |
+| Dark mode           | Semantic tokens adapt automatically             | Custom colors also work in dark mode          |
+| Disabled states     | Communicated via `aria-disabled`                | Reason for disabled is accessible             |
+| Focus trapping      | Dialog traps focus while open                   | Focus returns to the trigger element on close |
 
 ---
 
@@ -2396,18 +2753,18 @@ Prevent errors where possible. When errors happen, users must understand what fa
 
 Not every field type needs every validation kind. Use this to scope what to implement:
 
-| Field type    | Required | Format | Length   | Range        | Uniqueness |
-| ------------- | -------- | ------ | -------- | ------------ | ---------- |
-| Text input    | Yes      | —      | Optional | —            | Optional   |
-| Email input   | Yes      | Yes    | —        | —            | Optional   |
-| Password      | Yes      | Yes    | Yes      | —            | —          |
-| Number input  | Yes      | —      | —        | Yes          | —          |
-| Date picker   | Yes      | —      | —        | Yes          | —          |
-| Textarea      | Yes      | —      | Yes      | —            | —          |
-| Select        | Yes      | —      | —        | —            | —          |
-| Combobox      | Yes      | —      | —        | —            | —          |
-| Checkbox      | —        | —      | —        | —            | —          |
-| File upload   | Yes      | Yes    | —        | Yes (size)   | —          |
+| Field type   | Required | Format | Length   | Range      | Uniqueness |
+| ------------ | -------- | ------ | -------- | ---------- | ---------- |
+| Text input   | Yes      | —      | Optional | —          | Optional   |
+| Email input  | Yes      | Yes    | —        | —          | Optional   |
+| Password     | Yes      | Yes    | Yes      | —          | —          |
+| Number input | Yes      | —      | —        | Yes        | —          |
+| Date picker  | Yes      | —      | —        | Yes        | —          |
+| Textarea     | Yes      | —      | Yes      | —          | —          |
+| Select       | Yes      | —      | —        | —          | —          |
+| Combobox     | Yes      | —      | —        | —          | —          |
+| Checkbox     | —        | —      | —        | —          | —          |
+| File upload  | Yes      | Yes    | —        | Yes (size) | —          |
 
 **Edge cases**
 
@@ -2460,22 +2817,22 @@ Aura targets **WCAG AA** for primitives — usage must preserve that.
 
 **Alt text and icon naming**
 
-| Type                    | Approach                    | Example                              |
-| ------------------------ | ---------------------------- | ------------------------------------- |
-| Informational image      | Describe the content         | `alt="Chart: output up 20%"`         |
-| Decorative image         | Empty                        | `alt=""`                              |
-| Icon-only control        | `aria-label` on the control  | `aria-label="Delete report"`         |
-| Icon paired with a label  | Hide the icon                | `aria-hidden="true"` on the icon      |
+| Type                     | Approach                    | Example                          |
+| ------------------------ | --------------------------- | -------------------------------- |
+| Informational image      | Describe the content        | `alt="Chart: output up 20%"`     |
+| Decorative image         | Empty                       | `alt=""`                         |
+| Icon-only control        | `aria-label` on the control | `aria-label="Delete report"`     |
+| Icon paired with a label | Hide the icon               | `aria-hidden="true"` on the icon |
 
 **Announcing dynamic content**
 
-| Scenario              | Method                                       |
-| ---------------------- | --------------------------------------------- |
-| Search/list results update | `aria-live="polite"`                     |
-| Form error              | `aria-live="assertive"`                     |
-| Toast                   | Handled by the toast component               |
-| Dialog opens            | Focus moves into the dialog (Aura handles)   |
-| Dialog closes           | Return focus to the trigger element          |
+| Scenario                   | Method                                     |
+| -------------------------- | ------------------------------------------ |
+| Search/list results update | `aria-live="polite"`                       |
+| Form error                 | `aria-live="assertive"`                    |
+| Toast                      | Handled by the toast component             |
+| Dialog opens               | Focus moves into the dialog (Aura handles) |
+| Dialog closes              | Return focus to the trigger element        |
 
 ### Common pitfalls (agent guidance)
 
@@ -2583,7 +2940,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.