@actioneer/ads 0.7.0 → 1.0.0

package/DESIGN.md

@@ -0,0 +1,597 @@
+---
+name: Actioneer Design System
+description: ADS 1.0 — the React 19 + Tailwind v4 library every Actioneer product builds from
+colors:
+  action-primary: "#398457"
+  action-primary-hover: "#2b7348"
+  action-primary-text: "#1f623b"
+  action-primary-soft: "#e2efe5"
+  action-primary-foreground: "#ffffff"
+  field-focus: "#5c9c73"
+  brand: "#20201e"
+  brand-hover: "#4b4b47"
+  brand-text: "#20201e"
+  brand-foreground: "#ffffff"
+  success: "#516923"
+  success-foreground: "#ffffff"
+  warning: "#f79009"
+  warning-foreground: "#20201e"
+  danger: "#d92d20"
+  danger-foreground: "#ffffff"
+  info: "#1570ef"
+  info-foreground: "#ffffff"
+  background: "#f1f1ef"
+  foreground: "#20201e"
+  surface: "#ececea"
+  surface-foreground: "#20201e"
+  elevated: "#ffffff"
+  card: "#ffffff"
+  card-foreground: "#20201e"
+  muted: "#e5e5e2"
+  muted-foreground: "#4b4b47"
+  fill: "#ececea"
+  fill-foreground: "#20201e"
+  accent: "#dcdcd8"
+  accent-foreground: "#20201e"
+  on-white-primary: "#20201e"
+  on-white-secondary: "#4b4b47"
+  on-white-tertiary: "#777771"
+  on-warm-grey-primary: "#20201e"
+  on-warm-grey-secondary: "#4b4b47"
+  on-warm-grey-tertiary: "#777771"
+  primary: "#20201e"
+  secondary: "#4b4b47"
+  tertiary: "color-mix(in srgb, var(--color-wg10) 80%, var(--color-wg11))"
+  border: "#e5e5e2"
+  border-primary: "#dcdcd8"
+  border-secondary: "#e5e5e2"
+  border-tertiary: "#ececea"
+  border-strong: "#dcdcd8"
+  input: "#e5e5e2"
+  menu-stroke: "#e5e5e2"
+  toast-stroke: "#e5e5e2"
+  tree-stroke: "#e5e5e2"
+  specimen-stroke: "#ececea"
+  table-shell: "#ffffff"
+  table-stroke: "#ececea"
+  table-header-foreground: "color-mix(in srgb, var(--color-wg10) 80%, var(--color-wg11))"
+  artifact-canvas: "color-mix(in srgb, var(--color-brand-mark) 7%, var(--color-white))"
+  ring: "color-mix(in srgb, var(--color-wg12) 50%, transparent)"
+  overlay: "color-mix(in srgb, var(--color-wg12) 50%, transparent)"
+typography:
+  display:
+    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+    fontSize: "24px"
+    fontWeight: 500
+    lineHeight: "32px"
+  title:
+    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+    fontSize: "18px"
+    fontWeight: 500
+    lineHeight: "24px"
+  headline:
+    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+    fontSize: "16px"
+    fontWeight: 500
+    lineHeight: "22px"
+  body:
+    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+    fontSize: "14px"
+    fontWeight: 400
+    lineHeight: "20px"
+  label:
+    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+    fontSize: "12px"
+    fontWeight: 400
+    lineHeight: "16px"
+  mono:
+    fontFamily: "\"JetBrains Mono Variable\", ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", \"Courier New\", monospace"
+    fontSize: "12px"
+    fontWeight: 400
+    lineHeight: "16px"
+rounded:
+  xs: "2px"
+  sm: "4px"
+  md: "6px"
+  lg: "8px"
+  xl: "8px"
+  full: "9999px"
+spacing:
+  xs: "4px"
+  sm: "8px"
+  md: "12px"
+  lg: "16px"
+  xl: "20px"
+  2xl: "24px"
+components:
+  button-primary:
+    backgroundColor: "{colors.action-primary}"
+    textColor: "{colors.action-primary-foreground}"
+    rounded: "{rounded.md}"
+    height: "32px"
+    padding: "0 14px"
+    typography: "{typography.body}"
+  button-primary-hover:
+    backgroundColor: "{colors.action-primary-hover}"
+    textColor: "{colors.action-primary-foreground}"
+  button-outline:
+    backgroundColor: "transparent"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.md}"
+    height: "32px"
+    padding: "0 14px"
+  button-ghost:
+    backgroundColor: "transparent"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.md}"
+    height: "32px"
+    padding: "0 14px"
+  input:
+    backgroundColor: "{colors.elevated}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.md}"
+    height: "32px"
+    padding: "0 12px"
+    typography: "{typography.label}"
+  input-lg:
+    backgroundColor: "{colors.elevated}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.md}"
+    height: "44px"
+    padding: "0 12px"
+    typography: "{typography.body}"
+  card:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.card-foreground}"
+    rounded: "{rounded.xl}"
+    padding: "20px"
+  chip-solid:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.muted-foreground}"
+    rounded: "{rounded.sm}"
+    height: "24px"
+    padding: "0 8px"
+    typography: "{typography.label}"
+  sidebar-item:
+    backgroundColor: "transparent"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.md}"
+    height: "36px"
+    padding: "0 12px"
+    typography: "{typography.body}"
+  sidebar-item-active:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.foreground}"
+  panel:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.card-foreground}"
+    rounded: "{rounded.lg}"
+    padding: "16px"
+---
+
+# Design System: Actioneer Design System
+
+<!-- Generated by `npm run design` from ads-manifest.json + src/styles/theme.css + TASTE.md. Do not edit by hand: edit the token, the principle, or TASTE.md and regenerate. -->
+
+## Overview
+
+**Creative North Star: "Colour and motion are spent like money"**
+
+TASTE.md puts it in one line: On a quiet, neutral ground, colour and motion are spent like money — rarely, deliberately, and only where the eye should go.
+
+ADS 1.0.0 is a library first and a look second. 323 components across 10 families (Primitives / utilities, Foundations, Form controls, Overlays, Data display, Feedback, Navigation, Layout, AI Elements, Chat) ship from one barrel, and every product that consumes them inherits the judgment encoded in 56 semantic tokens and 11 principles rather than re-deciding it per screen.
+
+The ground is warm grey and the ink is warm near-black. One hue is spent by default, the Studio green CTA family, and four more carry semantic status. Everything else stays neutral. A consumer product may narrow that further, and one already does: Baby Sentinel drops the green and runs every action on ink.
+
+**Key characteristics:**
+- Warm-grey canvas, white sheet, quiet tiles. Every surface belongs to exactly one plane
+- One typeface at two real weights on a 5-step ladder (24px / 18px / 16px / 14px / 12px), with mono reserved for literal code
+- Fills and elevation separate surfaces roughly 75/25 against strokes
+- Every surface defaults to `shadow-0`; elevation means "you can act on this"
+- Radius runs 2px / 4px / 6px / 8px / 8px, with a pill reserved for chips and avatars
+
+## Colors
+
+A warm neutral ground with one CTA hue and four semantic signals. Every value below is the resolved token from `src/styles/theme.css`.
+
+### Primary
+
+The one place a hue is spent by default: the Studio green CTA family.
+
+**Primary CTA role — restrained Studio green, used sparingly.**
+
+- **action-primary** (`--color-action-primary`, #398457) `bg-action-primary`
+- **action-primary-hover** (`--color-action-primary-hover`, #2b7348) `bg-action-primary-hover`
+- **action-primary-text** (`--color-action-primary-text`, #1f623b) `text-action-primary-text`
+- **action-primary-soft** (`--color-action-primary-soft`, #e2efe5) `bg-action-primary-soft`
+- **action-primary-foreground** (`--color-action-primary-foreground`, #ffffff) `text-action-primary-foreground`
+- **field-focus** (`--color-field-focus`, #5c9c73) `bg-field-focus`
+
+### Secondary
+
+The neutral-ink action role kept as a compatibility API.
+
+**Compatibility action role — neutral ink, never a colored primary hue.**
+
+- **brand** (`--color-brand`, #20201e) `bg-brand`
+- **brand-hover** (`--color-brand-hover`, #4b4b47) `bg-brand-hover`
+- **brand-text** (`--color-brand-text`, #20201e) `text-brand-text`
+- **brand-foreground** (`--color-brand-foreground`, #ffffff) `text-brand-foreground`
+
+### Tertiary
+
+Semantic status. These four carry meaning and are never identity.
+
+**Lichen success-700 clears AA on White and both success soft fills; success-600 is reserved for non-text marks because its 3.73:1 contrast on White does not clear body-text AA.**
+
+- **success** (`--color-success`, #516923) `bg-success`
+- **success-foreground** (`--color-success-foreground`, #ffffff) `text-success-foreground`
+
+**Amber-500 fill kept (it IS the caution signal); dark ink foreground instead of white = 6.94:1 (white on amber was 2.35:1, failed even 3:1).**
+
+- **warning** (`--color-warning`, #f79009) `bg-warning`
+- **warning-foreground** (`--color-warning-foreground`, #20201e) `text-warning-foreground`
+
+**Danger and info: solid semantic fills carrying white foregrounds.**
+
+- **danger** (`--color-danger`, #d92d20) `bg-danger`
+- **danger-foreground** (`--color-danger-foreground`, #ffffff) `text-danger-foreground`
+- **info** (`--color-info`, #1570ef) `bg-info`
+- **info-foreground** (`--color-info-foreground`, #ffffff) `text-info-foreground`
+
+### Neutral
+
+The warm-grey ground everything else stands on.
+
+**The shell canvas and its ink: the ground between top-level panels.**
+
+- **background** (`--color-background`, #f1f1ef) `bg-background`
+- **foreground** (`--color-foreground`, #20201e) `text-foreground`
+
+**One continuous recess inside a white surface, never a screen-level ground.**
+
+- **surface** (`--color-surface`, #ececea) `bg-surface`
+- **surface-foreground** (`--color-surface-foreground`, #20201e) `text-surface-foreground`
+- **elevated** (`--color-elevated`, #ffffff) `bg-elevated`
+
+**The white working plane that sits on the canvas, and the specimen hairline.**
+
+- **card** (`--color-card`, #ffffff) `bg-card`
+- **card-foreground** (`--color-card-foreground`, #20201e) `text-card-foreground`
+
+**The hover and row-state wash: interaction, not a default item background.**
+
+- **muted** (`--color-muted`, #e5e5e2) `bg-muted`
+- **muted-foreground** (`--color-muted-foreground`, #4b4b47) `text-muted-foreground`
+
+**Quiet fill — avatars, chips, and disabled controls.**
+
+- **fill** (`--color-fill`, #ececea) `bg-fill`
+- **fill-foreground** (`--color-fill-foreground`, #20201e) `text-fill-foreground`
+
+**The active and selected wash, one step above hover.**
+
+- **accent** (`--color-accent`, #dcdcd8) `bg-accent`
+- **accent-foreground** (`--color-accent-foreground`, #20201e) `text-accent-foreground`
+
+**Contextual text hierarchies — three accessible levels per surface.**
+
+- **on-white-primary** (`--color-on-white-primary`, #20201e) `bg-on-white-primary`
+- **on-white-secondary** (`--color-on-white-secondary`, #4b4b47) `bg-on-white-secondary`
+- **on-white-tertiary** (`--color-on-white-tertiary`, #777771) `bg-on-white-tertiary`
+- **on-warm-grey-primary** (`--color-on-warm-grey-primary`, #20201e) `bg-on-warm-grey-primary`
+- **on-warm-grey-secondary** (`--color-on-warm-grey-secondary`, #4b4b47) `bg-on-warm-grey-secondary`
+- **on-warm-grey-tertiary** (`--color-on-warm-grey-tertiary`, #777771) `bg-on-warm-grey-tertiary`
+
+**Context-free compatibility aliases remain conservative.**
+
+- **primary** (`--color-primary`, #20201e) `bg-primary`
+- **secondary** (`--color-secondary`, #4b4b47) `bg-secondary`
+- **tertiary** (`--color-tertiary`, color-mix(in srgb, var(--color-wg10) 80%, var(--color-wg11))) `bg-tertiary`
+
+**The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.**
+
+- **border** (`--color-border`, #e5e5e2) `bg-border`
+- **border-primary** (`--color-border-primary`, #dcdcd8) `bg-border-primary`
+- **border-secondary** (`--color-border-secondary`, #e5e5e2) `bg-border-secondary`
+- **border-tertiary** (`--color-border-tertiary`, #ececea) `bg-border-tertiary`
+- **border-strong** (`--color-border-strong`, #dcdcd8) `bg-border-strong`
+- **input** (`--color-input`, #e5e5e2) `bg-input`
+- **menu-stroke** (`--color-menu-stroke`, #e5e5e2) `bg-menu-stroke`
+- **toast-stroke** (`--color-toast-stroke`, #e5e5e2) `bg-toast-stroke`
+- **tree-stroke** (`--color-tree-stroke`, #e5e5e2) `bg-tree-stroke`
+
+**The white working plane that sits on the canvas, and the specimen hairline.**
+
+- **specimen-stroke** (`--color-specimen-stroke`, #ececea) `bg-specimen-stroke`
+
+**Table surfaces: the white tray, its hairlines, and header ink.**
+
+- **table-shell** (`--color-table-shell`, #ffffff) `bg-table-shell`
+- **table-stroke** (`--color-table-stroke`, #ececea) `bg-table-stroke`
+- **table-header-foreground** (`--color-table-header-foreground`, color-mix(in srgb, var(--color-wg10) 80%, var(--color-wg11))) `text-table-header-foreground`
+
+**The artifact sheet: white warmed by a trace of the brand mark.**
+
+- **artifact-canvas** (`--color-artifact-canvas`, color-mix(in srgb, var(--color-brand-mark) 7%, var(--color-white))) `bg-artifact-canvas`
+
+**Focus ring and scrim, both translucent warm ink.**
+
+- **ring** (`--color-ring`, color-mix(in srgb, var(--color-wg12) 50%, transparent)) `ring-ring`
+- **overlay** (`--color-overlay`, color-mix(in srgb, var(--color-wg12) 50%, transparent)) `bg-overlay`
+
+### Named rules
+
+**The Fills Over Strokes Rule.** Delineate SURFACES (cards, panels, sidebars, page regions) with color contrast, elevation, and spacing — not borders. Keep no more than two persistent neutral layers in one composition: panels establish hierarchy; embedded items express state. Aim for ~75% shadow/fill, 25% strokes: form controls and floating menus keep a subtle border so they read as interactive; surfaces do not.
+
+## Typography
+
+**Display font:** Aribau Grotesk
+**Body font:** Aribau Grotesk
+**Mono font:** JetBrains Mono Variable
+
+**Character:** one grotesk doing everything at two real weights. Hierarchy comes from size, ink strength and spacing. There is no second family and no heavy weight to reach for.
+
+### Hierarchy
+
+- **Display** (500, 24px / 32px): page-level moments only.
+- **Title** (500, 18px / 24px): page titles.
+- **Headline** (500, 16px / 22px): emphasized body and section headings.
+- **Body** (400, 14px / 20px): the default, all reading text and control labels.
+- **Label** (400, 12px / 16px): the floor: captions, secondary text, table cells.
+- **Mono** (400, 12px / 16px): literal source code, and nothing else.
+
+### Named rules
+
+**The One Face Rule.** One face (Aribau Grotesk), two real weights, a five-step ladder.
+
+**The 12px Floor Rule.** Nothing renders below `--text-s` (12px). Density comes from spacing and layout, never from shrinking type.
+
+## Layout
+
+The shell owns the frame and screens own their content. ADS targets landscape tablet (1024), laptop (1440) and wide display (1920+); phone and portrait are out of scope. Components adapt to their container, not to the viewport, so the same component works in a 320px panel and a 1200px sheet.
+
+### Named rules
+
+**The Shell Owns the Frame Rule.** The demo shell applies the screen frame (inset on top/right/bottom, flush-left against the sidebar). Screens never add their own outer padding — a screen's root is flex h-full flex-col and fills the frame with Panel(s).
+
+**The One Thing Per Screen Rule.** A screen carries ONLY what the user needs to move forward: one title, the inputs, one primary action. Page, section, panel, modal, dialog, drawer, and popover headers are title-only by default; add a description only when the user explicitly asks for one. Never maximalist.
+
+**The Container, Not Viewport Rule.** ADS targets landscape tablet (1024) → laptop (1440) → wide display (1920+); phone/portrait is out of scope. Components adapt to their CONTAINER via container queries; shells and pages decide pane widths through width tokens. Design against under-utilization, not cramping.
+
+## Elevation & Depth
+
+Flat by default with tonal layering. Depth comes from the plane system, warm grey behind and white in front. `--shadow-elevation` aliases `--shadow-0`, which is `none`: a surface earns a shadow only when someone asks for one by name.
+
+### Shadow vocabulary
+
+- **0** (`--shadow-0`): `none`
+- **100** (`--shadow-100`): `0 1px 0 0 rgb(32 32 32 / 0.07)`
+- **200** (`--shadow-200`): `0 3px 1px -1px rgb(32 32 32 / 0.07)`
+- **300** (`--shadow-300`): `0 4px 6px -2px rgb(32 32 32 / 0.2)`
+- **400** (`--shadow-400`): `0 8px 16px -4px rgb(32 32 32 / 0.22)`
+- **500** (`--shadow-500`): `0 12px 20px -8px rgb(32 32 32 / 0.24)`
+- **600** (`--shadow-600`): `0 20px 20px -8px rgb(32 32 32 / 0.28)`
+- **elevation** (`--shadow-elevation`): `none`
+- **table-smudge-left** (`--shadow-table-smudge-left`): `8px 0 24px -14px rgb(32 32 32 / 0.05)`
+- **table-smudge-right** (`--shadow-table-smudge-right`): `-8px 0 24px -14px rgb(32 32 32 / 0.05)`
+
+### Named rules
+
+**The Elevation Is Actionability Rule.** Every surface defaults to shadow-0. Use the numbered elevation ladder only when the user explicitly requests a shadow for the named surface; the legacy shadow-elevation hook remains flat.
+
+## Shapes
+
+Soft geometry on a 5-step ladder: `xs` 2px, `sm` 4px, `md` 6px, `lg` 8px, `xl` 8px, plus a pill at `full` (9999px) for chips and avatars. Tailwind's larger aliases (`2xl`, `3xl`) collapse onto the top step, so a stray `rounded-3xl` cannot exceed it.
+
+### Named rules
+
+**The Square Status Dots Rule.** Indicator/status dots (Badge & Chip dot variants, ConnectionStatus, chart legend swatches, presence/pulse dots) are square — rounded-dot (2px), echoing the growth-mark's square cells — never round.
+
+## Components
+
+The catalog is the contract: 323 components, 10 hooks and 98 utilities behind one barrel (`@actioneer/ads`). Import exact, unaliased names. Native elements are for semantic structure only: `<div>`, `<form>`, `<main>`, `<section>`. Never recreate a visual control.
+
+### Sourcing a component
+
+The components documented below are specimens chosen to show how tokens land on real controls. They are not the inventory. Walk this ladder in order and stop at the first step that answers.
+
+1. **Use the ADS export.** Import the exact, unaliased name from the barrel. Enumerate the catalog before deciding something is missing: the `ads` MCP server (`search_components`, `get_component`) and `ads-manifest.json` both list every export with its family and props.
+2. **Compose ADS exports.** If the pattern is only layout or content arrangement, build it from components that already ship rather than adding a primitive.
+3. **Fall back to shadcn/ui.** When the barrel genuinely has no primitive, vendor one with `npx shadcn add` using the repo's `components.json` (style `new-york`, Radix base, `cssVariables: true`). It lands in `src/components/ui`, imports `cn` from `@/lib/utils`, and its lucide icons are swapped for aliased `@/lib/icons` imports. The shadcn-compat aliases in `theme.css` already map shadcn's colour roles onto ADS tokens, so a vendored Sidebar or Popover inherits the palette instead of shadcn's greys — do not restyle it by hand.
+4. **Promote it, only when asked.** Moving a vendored component into the public barrel is library work: it needs an explicit request, the right family, an exact exported name, and documentation.
+
+Hand-rolling a visual control, or importing a UI library at a call site, is never a step on this ladder.
+
+### Primary Button
+
+- **Export:** `Button`
+- **Character:** variant="solid". The one action a screen wants, in Studio green.
+- **Background:** {colors.action-primary}
+- **Text:** {colors.action-primary-foreground}
+- **Radius:** {rounded.md}
+- **Height:** 32px
+- **Padding:** 0 14px
+- **Type:** {typography.body}
+
+### Primary Button (hover)
+
+- **Export:** `Button`
+- **Character:** Hover and active share one deeper green. No separate active shade.
+- **Background:** {colors.action-primary-hover}
+- **Text:** {colors.action-primary-foreground}
+
+### Outline Button
+
+- **Export:** `Button`
+- **Character:** variant="outline". A hairline at rest; hover borrows the green tint rather than filling.
+- **Background:** transparent
+- **Text:** {colors.foreground}
+- **Radius:** {rounded.md}
+- **Height:** 32px
+- **Padding:** 0 14px
+
+### Ghost Button
+
+- **Export:** `Button`
+- **Character:** variant="ghost". No chrome until a pointer arrives, then the soft green wash.
+- **Background:** transparent
+- **Text:** {colors.foreground}
+- **Radius:** {rounded.md}
+- **Height:** 32px
+- **Padding:** 0 14px
+
+### Text Input
+
+- **Export:** `Input`
+- **Character:** size="md". Elevated fill, one subtle stroke so it reads as interactive, recessed inner glow.
+- **Background:** {colors.elevated}
+- **Text:** {colors.foreground}
+- **Radius:** {rounded.md}
+- **Height:** 32px
+- **Padding:** 0 12px
+- **Type:** {typography.label}
+
+### Text Input (lg)
+
+- **Export:** `Input`
+- **Character:** size="lg". The 44px register for standalone forms.
+- **Background:** {colors.elevated}
+- **Text:** {colors.foreground}
+- **Radius:** {rounded.md}
+- **Height:** 44px
+- **Padding:** 0 12px
+- **Type:** {typography.body}
+
+### Card
+
+- **Export:** `Card`
+- **Character:** A working plane on the warm-grey ground. No border, radius at the 12px step.
+- **Background:** {colors.card}
+- **Text:** {colors.card-foreground}
+- **Radius:** {rounded.xl}
+- **Padding:** 20px
+
+### Chip
+
+- **Export:** `Chip`
+- **Character:** The quiet register. Colour variants swap the fill through the semantic ramp and are the only routine colour outside charts.
+- **Background:** {colors.background}
+- **Text:** {colors.muted-foreground}
+- **Radius:** {rounded.sm}
+- **Height:** 24px
+- **Padding:** 0 8px
+- **Type:** {typography.label}
+
+### Sidebar Item
+
+- **Export:** `SidebarItem`
+- **Character:** The rail's navigation row. Active takes the white card fill and a WG4 edge, and its icon switches to the filled weight.
+- **Background:** transparent
+- **Text:** {colors.foreground}
+- **Radius:** {rounded.md}
+- **Height:** 36px
+- **Padding:** 0 12px
+- **Type:** {typography.body}
+
+### Sidebar Item (active)
+
+- **Export:** `SidebarItem`
+- **Character:** isActive. The row lifts onto the white plane; the icon renders at weight="fill".
+- **Background:** {colors.card}
+- **Text:** {colors.foreground}
+
+### Panel
+
+- **Export:** `Panel`
+- **Character:** The editor plane: header with title and toolbar, scrolling body, footer on a translucent recess.
+- **Background:** {colors.card}
+- **Text:** {colors.card-foreground}
+- **Radius:** {rounded.lg}
+- **Padding:** 16px
+
+### Named rules
+
+**The Motion Follows the Interaction Rule.** Component motion follows the closest Animate UI interaction pattern, using role-specific presets defined in src/lib/motion.ts and exported from the ADS root barrel. Direct manipulation stays immediate, small CSS feedback stays local, and reduced motion is respected everywhere. Enforced by `npm run lint:ads`.
+
+**The One Icon Language Rule.** All icons come from Phosphor Icons at the regular weight — the stroke-led icon language of ADS. Components import named icons from the @/lib/icons registry — never from an icon package directly — so swapping the underlying set touches one file. Enforced by `npm run lint:ads`.
+
+**The ADS First Rule.** Every UI decision stays synchronized with ADS. Search the full catalog before deciding a component is missing, and use the exact exported name from the public barrel. When the barrel genuinely has no primitive, the sanctioned fallback is a shadcn/ui component vendored into src/components/ui through the repo's components.json recipe — never a hand-rolled control and never a UI library imported at a call site. Enforced by `npm run lint:ads`.
+
+**The Back Leads Rule.** A page-level Back control sits immediately before the page title in the leading header cluster. It is icon-only with an accessible label and never appears on the right with forward/page actions.
+
+**The Tabs Lead, Search Trails Rule.** When tabs and a search field control the same content, they share one responsive control row: the tab track hugs its labels at the leading edge and search sits at the trailing edge. Stack only when the container cannot fit both.
+
+## Do's and Don'ts
+
+Every line below is a `do` or `dont` recorded on a principle in `ads-manifest.json`.
+
+### Do:
+
+- **Do** establish hierarchy with at most two persistent layers: bg-background for the screen ground and bg-card/bg-elevated for the primary surface. *(fills-over-strokes)*
+- **Do** inside a white Panel or Card, keep rows and items transparent at rest; group them with spacing or inset dividers, use bg-muted for hover/selection, and reserve bg-surface for one continuous semantic recess such as an editor or table tray. *(fills-over-strokes)*
+- **Do** use border-border for outline buttons and lightweight action rows; reserve border-input for form controls (input, select, textarea, checkbox, radio, segmented-control track) and floating menus (dropdown, popover, listboxes). *(fills-over-strokes)*
+- **Do** keep strokes on focus rings, the outline Button/Badge/Chip variants, Kbd, Divider, the Tree connector rail, and functional color swatches. *(fills-over-strokes)*
+- **Do** keep controls, cards, menus, overlays, panels, and other surfaces at shadow-0 unless the user specifically requests elevation. *(elevation-is-actionability)*
+- **Do** when requested, use shadow-100 for controls, shadow-200 for raised surfaces and pressable cards, shadow-300 for menus, popovers, listboxes, and toasts, and shadow-400 for dialogs and overlay drawers. *(elevation-is-actionability)*
+- **Do** reserve shadow-500 and shadow-600 for rare higher stacked layers; the legacy shadow-elevation hook resolves to shadow-0. *(elevation-is-actionability)*
+- **Do** treat motion as part of every ADS component import: preserve the component's built-in motion, and import any composition-level preset from the ADS root barrel. *(motion-follows-guide)*
+- **Do** map the component family before choosing motion: tabs/segments use control; checkbox/radio/switch use selection; menus use highlight; popovers/tooltips use overlay; modal/drawer use dialog/sheet; accordion/collapsible use disclosure; progress, carousel, and sidebar use their matching presets. *(motion-follows-guide)*
+- **Do** keep sliders, drag-resize, scrolling, and other pointer-following interactions immediate; motion begins after the committed value or destination changes. *(motion-follows-guide)*
+- **Do** give pressable elements local active feedback (text/link exempt); start entrances ≥ scale 0.95 with opacity. *(motion-follows-guide)*
+- **Do** wrap Motion components in MotionConfig reducedMotion='user'; keep useful opacity/color feedback and drop spatial movement. *(motion-follows-guide)*
+- **Do** import icons from the @/lib/icons registry; wrap a new Phosphor component with createIcon there before using it. *(icons-phosphor-regular)*
+- **Do** let icons default to size='1em' so they scale with text; size with a size prop or size-* class. *(icons-phosphor-regular)*
+- **Do** render weight='fill' for the active or selected state, and weight='bold' for the rare heavier stroke. *(icons-phosphor-regular)*
+- **Do** make a screen root flex h-full flex-col and fill the frame with Panel(s). *(shell-owns-the-frame)*
+- **Do** let one place (the shell) own the inset so every screen aligns to the rail. *(shell-owns-the-frame)*
+- **Do** use rounded-dot for every indicator/status dot. *(square-status-dots)*
+- **Do** use an existing ADS component by its exact exported name from the package barrel; compose existing components for layout-only patterns. *(ads-first)*
+- **Do** search the whole catalog before concluding a component is missing — the documented specimens are a sample, not the inventory. *(ads-first)*
+- **Do** fall back to shadcn/ui when the barrel has no primitive: vendor it with npx shadcn add into src/components/ui, import cn from @/lib/utils, and swap its lucide icons for @/lib/icons. *(ads-first)*
+- **Do** let a vendored shadcn component inherit the ADS palette through the shadcn-compat aliases in theme.css rather than restyling it by hand. *(ads-first)*
+- **Do** ask the user before promoting a vendored component into the public barrel; only an explicit request authorizes new library work. *(ads-first)*
+- **Do** when authorized, add the component to the right family, export its exact name through the barrel, and document it. *(ads-first)*
+- **Do** prefer more, smaller steps over dense ones; ask one thing at a time. *(minimal-information)*
+- **Do** derive instead of asking whenever possible (a name from a work email, the company from its domain). *(minimal-information)*
+- **Do** prefer clear text-only buttons; add an icon only when it communicates essential meaning the label cannot carry alone, or for a compact conventional icon-only control. *(minimal-information)*
+- **Do** render multi-step flows full-screen — a single content container that holds the inputs and its own Back/Continue is fine. *(minimal-information)*
+- **Do** use @container on the pane and @lg:/@xl: variants on children inside components. *(responsive-container-fluid)*
+- **Do** set pane widths in shells/pages through width tokens (thread-max-width, sidebar-width, aside-width, connector-card-min/-max). *(responsive-container-fluid)*
+- **Do** cap prose at its measure; let tables/charts/tool cards break out wider. Use auto-fill + minmax(min, 1fr) for grids. *(responsive-container-fluid)*
+- **Do** use PageHeader with onBack so the left arrow is anchored directly before the title. *(leading-back-navigation)*
+- **Do** reserve the trailing header area for forward or page-level actions such as Add, Save, or Share. *(leading-back-navigation)*
+- **Do** keep the horizontal TabList content-width, then place the scoped search field opposite it in the same toolbar. *(tabs-search-opposed)*
+- **Do** on constrained containers, stack tabs first and search second while preserving their relationship. *(tabs-search-opposed)*
+
+### Don't:
+
+- **Don't** add a border to a surface to separate or group it — use fill/elevation/spacing instead. *(fills-over-strokes)*
+- **Don't** alternate persistent neutral fills inside one panel (for example white Panel → grey item → white child); flatten the item or promote the recess to the container. *(fills-over-strokes)*
+- **Don't** give a filled control no stroke on the tinted canvas — it disappears; it needs a crisp edge. *(fills-over-strokes)*
+- **Don't** infer permission to use a shadow from actionability, floating placement, or component type. *(elevation-is-actionability)*
+- **Don't** use raw shadow values or legacy named shadow utilities. *(elevation-is-actionability)*
+- **Don't** put a shadow on a non-interactive surface for decoration. *(elevation-is-actionability)*
+- **Don't** use shadow-500 or shadow-600 as a routine default. *(elevation-is-actionability)*
+- **Don't** invent raw spring values inside a component, recreate a global duration/easing token scale, use an unbounded all-property transition, or start an entrance at scale zero. *(motion-follows-guide)*
+- **Don't** override or duplicate the motion already shipped inside an imported ADS component. *(motion-follows-guide)*
+- **Don't** animate keyboard-initiated or 100×/day actions (e.g. a command-palette toggle). *(motion-follows-guide)*
+- **Don't** add motion to a component only because it is visible; static structure and decorative chrome stay still. *(motion-follows-guide)*
+- **Don't** import from an icon package directly, or install a second icon set. *(icons-phosphor-regular)*
+- **Don't** leave an active nav item's icon at the regular stroke weight. *(icons-phosphor-regular)*
+- **Don't** add outer padding on a screen, leaving a tinted-canvas gap on the left. *(shell-owns-the-frame)*
+- **Don't** use rounded-full on an indicator dot (the one exception is a Radio control's inner dot). *(square-status-dots)*
+- **Don't** deep-import, alias, default/namespace-import, or hand-roll a local copy of a component. *(ads-first)*
+- **Don't** import a visual component directly from the web or an npm UI library at a call site. *(ads-first)*
+- **Don't** reach for the shadcn fallback before searching the catalog, or install a second component library beside it. *(ads-first)*
+- **Don't** add section eyebrows above a title that already names the screen, or helper text that restates the obvious / duplicates a disabled button's meaning. *(minimal-information)*
+- **Don't** add any header description unless the user explicitly requested supporting copy for that page, section, panel, modal, dialog, drawer, or popover. *(minimal-information)*
+- **Don't** decorate a labeled button with a redundant leading or trailing icon. *(minimal-information)*
+- **Don't** nest panel/step-rail chrome inside a multi-step flow. *(minimal-information)*
+- **Don't** use sm:/md: viewport variants inside src/components, or hardcode a pane width there. *(responsive-container-fluid)*
+- **Don't** cap a grid at a hard column count so it stops growing on wide displays. *(responsive-container-fluid)*
+- **Don't** place Back on the right side of a page header. *(leading-back-navigation)*
+- **Don't** render a redundant visible Back label when the standard left arrow and accessible label are sufficient. *(leading-back-navigation)*
+- **Don't** stretch the tab track to fill the space between its labels and the search field. *(tabs-search-opposed)*
+- **Don't** put a scoped search field on a separate row above its tabs when both controls fit side by side. *(tabs-search-opposed)*
+- **Don't** place search before tabs in the reading or keyboard order. *(tabs-search-opposed)*

package/components/ai-elements/agent-trace.js

@@ -278,7 +278,7 @@ const $e = ({
               O.title,
               " —",
               " ",
-              /* @__PURE__ */ t("span", { className: "tabular-nums text-tertiary", children: k(n) })
+              /* @__PURE__ */ t("span", { className: "tabular-nums text-muted-foreground", children: k(n) })
             ] }),
             /* @__PURE__ */ t(re, { className: "text-base leading-6", children: O.detail })
           ] }),

package/components/alert.js

@@ -7,7 +7,7 @@ import { Info as p, WarningCircle as C, Warning as I, CheckCircle as R, Close as
 import { cn as d } from "../lib/cn.js";
 import { springOverlay as z } from "../lib/motion.js";
 const D = A(
-  "relative flex w-full items-start gap-4 overflow-hidden rounded-2xl border border-border bg-white p-4 shadow-[var(--shadow-200)]",
+  "relative flex w-full items-start gap-4 overflow-hidden rounded-2xl border border-border bg-card p-4 shadow-[var(--shadow-200)]",
   {
     variants: {
       variant: {
@@ -47,7 +47,7 @@ const D = A(
     return o ? null : /* @__PURE__ */ e(E, { reducedMotion: "user", children: /* @__PURE__ */ e(
       g.div,
       {
-        initial: { opacity: 0, x: 32 },
+        initial: { opacity: 1, x: 32 },
         animate: i ? { opacity: 0, x: -32 } : { opacity: 1, x: 0 },
         transition: i ? { duration: 0.18, ease: "easeIn" } : z,
         onAnimationComplete: y,
@@ -76,7 +76,7 @@ const D = A(
                   children: /* @__PURE__ */ e(j, { "aria-hidden": !0 })
                 }
               ),
-              a > 0 && /* @__PURE__ */ e("span", { "aria-hidden": !0, className: "absolute inset-x-0 bottom-0 h-0.5 bg-ng3", children: /* @__PURE__ */ e(
+              a > 0 && /* @__PURE__ */ e("span", { "aria-hidden": !0, className: "absolute inset-x-0 bottom-0 h-0.5 bg-wg3", children: /* @__PURE__ */ e(
                 g.span,
                 {
                   className: "block size-full origin-left bg-(--alert-accent)",

package/components/answer.js

@@ -531,7 +531,7 @@ function k({ signal: a }) {
     T,
     {
       variant: J(a.tone),
-      className: "border border-ng3 bg-card",
+      className: "border border-wg3 bg-card",
       children: [
         /* @__PURE__ */ t(O, { children: a.label ?? "Takeaway" }),
         /* @__PURE__ */ t(L, { className: "text-base leading-6", children: a.text })
@@ -873,7 +873,7 @@ const re = p.forwardRef(({ spec: a, onFollowUp: l, onOptionSelect: c, onSourceSe
         ] }) }),
         /* @__PURE__ */ t("tbody", { children: a.rows.map((r) => {
           const i = r.values[0].detail === r.values[1].detail ? r.values[0].detail : void 0, s = r.description ?? i;
-          return /* @__PURE__ */ n("tr", { className: "[&>*]:bg-ng2", children: [
+          return /* @__PURE__ */ n("tr", { className: "[&>*]:bg-wg2", children: [
             /* @__PURE__ */ n(
               "th",
               {

package/components/assistant-ui/action-bar.js

@@ -56,7 +56,7 @@ const z = ({ open: s, onOpenChange: i }) => {
                 side: "bottom",
                 align: "start",
                 sideOffset: 6,
-                className: "aui-action-bar-more-content bg-popover/95 text-popover-foreground data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=open]:animate-in data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=closed]:animate-out data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-[8rem] overflow-hidden rounded-xl border p-1.5 shadow-lg backdrop-blur-sm",
+                className: "aui-action-bar-more-content bg-popover/95 text-popover-foreground data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=open]:animate-in data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=closed]:animate-out data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-[8rem] overflow-hidden rounded-xl border p-1.5 shadow-300 backdrop-blur-sm",
                 children: [
                   /* @__PURE__ */ t(
                     n.Item,