@actioneer/ads 1.0.7 → 1.0.9

package/DESIGN.md

@@ -15,46 +15,46 @@ colors:
   success: "#2d6b22"
   success-foreground: "#ffffff"
   warning: "#f79009"
-  warning-foreground: "#21201d"
+  warning-foreground: "#202020"
   danger: "#d92d20"
   danger-foreground: "#ffffff"
   info: "#1570ef"
   info-foreground: "#ffffff"
-  background: "#f3f1e9"
-  foreground: "#21201d"
-  surface: "#efece3"
-  surface-foreground: "#21201d"
+  background: "#f6f6f6"
+  foreground: "#202020"
+  surface: "#f1f1f1"
+  surface-foreground: "#202020"
   elevated: "#ffffff"
   card: "#ffffff"
-  card-foreground: "#21201d"
-  muted: "#e8e5db"
-  muted-foreground: "#4d4b44"
-  fill: "#efece3"
-  fill-foreground: "#21201d"
-  accent: "#dfdcd0"
-  accent-foreground: "#21201d"
-  on-white-primary: "#21201d"
-  on-white-secondary: "#4d4b44"
-  on-white-tertiary: "#79766a"
-  on-warm-grey-primary: "#21201d"
-  on-warm-grey-secondary: "#4d4b44"
-  on-warm-grey-tertiary: "#79766a"
-  primary: "#21201d"
-  secondary: "#4d4b44"
-  tertiary: "color-mix(in srgb, var(--color-wg10) 80%, var(--color-wg11))"
-  border: "#e8e5db"
-  border-primary: "#dfdcd0"
-  border-secondary: "#e8e5db"
-  border-tertiary: "#efece3"
-  border-strong: "#dfdcd0"
-  input: "#e8e5db"
-  menu-stroke: "#e8e5db"
-  toast-stroke: "#e8e5db"
-  tree-stroke: "#e8e5db"
-  specimen-stroke: "#efece3"
+  card-foreground: "#202020"
+  muted: "#ececec"
+  muted-foreground: "#5e5d5d"
+  fill: "#f1f1f1"
+  fill-foreground: "#202020"
+  accent: "#e6e6e6"
+  accent-foreground: "#202020"
+  on-white-primary: "#202020"
+  on-white-secondary: "#5e5d5d"
+  on-white-tertiary: "#868686"
+  on-warm-grey-primary: "#202020"
+  on-warm-grey-secondary: "#5e5d5d"
+  on-warm-grey-tertiary: "#868686"
+  primary: "#202020"
+  secondary: "#5e5d5d"
+  tertiary: "color-mix(in srgb, var(--color-wg10) 40%, var(--color-wg11))"
+  border: "#ececec"
+  border-primary: "#e6e6e6"
+  border-secondary: "#ececec"
+  border-tertiary: "#f1f1f1"
+  border-strong: "#e6e6e6"
+  input: "#ececec"
+  menu-stroke: "#ececec"
+  toast-stroke: "#ececec"
+  tree-stroke: "#ececec"
+  specimen-stroke: "#f1f1f1"
   table-shell: "#ffffff"
-  table-stroke: "#efece3"
-  table-header-foreground: "color-mix(in srgb, var(--color-wg10) 80%, var(--color-wg11))"
+  table-stroke: "#f1f1f1"
+  table-header-foreground: "color-mix(in srgb, var(--color-wg10) 40%, var(--color-wg11))"
   artifact-canvas: "color-mix(in srgb, var(--color-brand-mark) 7%, var(--color-white))"
   ring: "#1c8379"
   overlay: "color-mix(in srgb, var(--color-wg12) 50%, transparent)"
@@ -179,7 +179,7 @@ components:
 
 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.7 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.
+ADS 1.0.9 is a library first and a look second. 325 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 15 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 teal 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 teal and runs every action on ink.
 
@@ -230,7 +230,7 @@ Semantic status. These four carry meaning and are never identity.
 **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`, #21201d) `text-warning-foreground`
+- **warning-foreground** (`--color-warning-foreground`, #202020) `text-warning-foreground`
 
 **Danger and info: solid semantic fills carrying white foregrounds.**
 
@@ -245,77 +245,77 @@ The warm-grey ground everything else stands on.
 
 **The shell canvas and its ink: the ground between top-level panels.**
 
-- **background** (`--color-background`, #f3f1e9) `bg-background`
-- **foreground** (`--color-foreground`, #21201d) `text-foreground`
+- **background** (`--color-background`, #f6f6f6) `bg-background`
+- **foreground** (`--color-foreground`, #202020) `text-foreground`
 
 **One continuous recess inside a white surface, never a screen-level ground.**
 
-- **surface** (`--color-surface`, #efece3) `bg-surface`
-- **surface-foreground** (`--color-surface-foreground`, #21201d) `text-surface-foreground`
+- **surface** (`--color-surface`, #f1f1f1) `bg-surface`
+- **surface-foreground** (`--color-surface-foreground`, #202020) `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`, #21201d) `text-card-foreground`
+- **card-foreground** (`--color-card-foreground`, #202020) `text-card-foreground`
 
 **The hover and row-state wash: interaction, not a default item background.**
 
-- **muted** (`--color-muted`, #e8e5db) `bg-muted`
-- **muted-foreground** (`--color-muted-foreground`, #4d4b44) `text-muted-foreground`
+- **muted** (`--color-muted`, #ececec) `bg-muted`
+- **muted-foreground** (`--color-muted-foreground`, #5e5d5d) `text-muted-foreground`
 
 **Quiet fill — avatars, chips, and disabled controls.**
 
-- **fill** (`--color-fill`, #efece3) `bg-fill`
-- **fill-foreground** (`--color-fill-foreground`, #21201d) `text-fill-foreground`
+- **fill** (`--color-fill`, #f1f1f1) `bg-fill`
+- **fill-foreground** (`--color-fill-foreground`, #202020) `text-fill-foreground`
 
 **The active and selected wash, one step above hover.**
 
-- **accent** (`--color-accent`, #dfdcd0) `bg-accent`
-- **accent-foreground** (`--color-accent-foreground`, #21201d) `text-accent-foreground`
+- **accent** (`--color-accent`, #e6e6e6) `bg-accent`
+- **accent-foreground** (`--color-accent-foreground`, #202020) `text-accent-foreground`
 
 **Contextual text hierarchies — three accessible levels per surface.**
 
-- **on-white-primary** (`--color-on-white-primary`, #21201d) `bg-on-white-primary`
-- **on-white-secondary** (`--color-on-white-secondary`, #4d4b44) `bg-on-white-secondary`
-- **on-white-tertiary** (`--color-on-white-tertiary`, #79766a) `bg-on-white-tertiary`
-- **on-warm-grey-primary** (`--color-on-warm-grey-primary`, #21201d) `bg-on-warm-grey-primary`
-- **on-warm-grey-secondary** (`--color-on-warm-grey-secondary`, #4d4b44) `bg-on-warm-grey-secondary`
-- **on-warm-grey-tertiary** (`--color-on-warm-grey-tertiary`, #79766a) `bg-on-warm-grey-tertiary`
+- **on-white-primary** (`--color-on-white-primary`, #202020) `bg-on-white-primary`
+- **on-white-secondary** (`--color-on-white-secondary`, #5e5d5d) `bg-on-white-secondary`
+- **on-white-tertiary** (`--color-on-white-tertiary`, #868686) `bg-on-white-tertiary`
+- **on-warm-grey-primary** (`--color-on-warm-grey-primary`, #202020) `bg-on-warm-grey-primary`
+- **on-warm-grey-secondary** (`--color-on-warm-grey-secondary`, #5e5d5d) `bg-on-warm-grey-secondary`
+- **on-warm-grey-tertiary** (`--color-on-warm-grey-tertiary`, #868686) `bg-on-warm-grey-tertiary`
 
 **Context-free compatibility aliases remain conservative.**
 
-- **primary** (`--color-primary`, #21201d) `bg-primary`
-- **secondary** (`--color-secondary`, #4d4b44) `bg-secondary`
-- **tertiary** (`--color-tertiary`, color-mix(in srgb, var(--color-wg10) 80%, var(--color-wg11))) `bg-tertiary`
+- **primary** (`--color-primary`, #202020) `bg-primary`
+- **secondary** (`--color-secondary`, #5e5d5d) `bg-secondary`
+- **tertiary** (`--color-tertiary`, color-mix(in srgb, var(--color-wg10) 40%, var(--color-wg11))) `bg-tertiary`
 
 **The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.**
 
-- **border** (`--color-border`, #e8e5db) `bg-border`
-- **border-primary** (`--color-border-primary`, #dfdcd0) `bg-border-primary`
-- **border-secondary** (`--color-border-secondary`, #e8e5db) `bg-border-secondary`
-- **border-tertiary** (`--color-border-tertiary`, #efece3) `bg-border-tertiary`
-- **border-strong** (`--color-border-strong`, #dfdcd0) `bg-border-strong`
-- **input** (`--color-input`, #e8e5db) `bg-input`
-- **menu-stroke** (`--color-menu-stroke`, #e8e5db) `bg-menu-stroke`
-- **toast-stroke** (`--color-toast-stroke`, #e8e5db) `bg-toast-stroke`
-- **tree-stroke** (`--color-tree-stroke`, #e8e5db) `bg-tree-stroke`
+- **border** (`--color-border`, #ececec) `bg-border`
+- **border-primary** (`--color-border-primary`, #e6e6e6) `bg-border-primary`
+- **border-secondary** (`--color-border-secondary`, #ececec) `bg-border-secondary`
+- **border-tertiary** (`--color-border-tertiary`, #f1f1f1) `bg-border-tertiary`
+- **border-strong** (`--color-border-strong`, #e6e6e6) `bg-border-strong`
+- **input** (`--color-input`, #ececec) `bg-input`
+- **menu-stroke** (`--color-menu-stroke`, #ececec) `bg-menu-stroke`
+- **toast-stroke** (`--color-toast-stroke`, #ececec) `bg-toast-stroke`
+- **tree-stroke** (`--color-tree-stroke`, #ececec) `bg-tree-stroke`
 
 **The white working plane that sits on the canvas, and the specimen hairline.**
 
-- **specimen-stroke** (`--color-specimen-stroke`, #efece3) `bg-specimen-stroke`
+- **specimen-stroke** (`--color-specimen-stroke`, #f1f1f1) `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`, #efece3) `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`
+- **table-stroke** (`--color-table-stroke`, #f1f1f1) `bg-table-stroke`
+- **table-header-foreground** (`--color-table-header-foreground`, color-mix(in srgb, var(--color-wg10) 40%, 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.**
+**Focus ring and scrim, both translucent neutral ink.**
 
 - **ring** (`--color-ring`, #1c8379) `ring-ring`
 - **overlay** (`--color-overlay`, color-mix(in srgb, var(--color-wg12) 50%, transparent)) `bg-overlay`
@@ -361,24 +361,19 @@ The shell owns the frame and screens own their content. ADS targets landscape ta
 
 ## 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.
+Flat by default with tonal layering. Depth comes from the plane system, warm grey behind and white in front. Five shadows only: `--shadow-0` (flat, every in-page surface), `--shadow-float` (toasts, toolbars, composer dock), `--shadow-overlay` (modals, dialogs, overlay drawers), and the two table scroll-hint smudges.
 
 ### 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`
+- **float** (`--shadow-float`): `0 0 0 1px rgb(32 32 32 / 0.04), 0 2px 4px rgb(32 32 32 / 0.04), 0 8px 20px -4px rgb(32 32 32 / 0.10)`
+- **overlay** (`--shadow-overlay`): `0 0 0 1px rgb(32 32 32 / 0.04), 0 4px 8px rgb(32 32 32 / 0.04), 0 16px 36px -8px rgb(32 32 32 / 0.14)`
 - **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.
+**The Elevation Is Actionability Rule.** ADS has five shadow tokens: shadow-0 (flat, the default), shadow-float, shadow-overlay, and the two table scroll-hint smudges. Only a layer that floats above the page may carry float or overlay; everything in the page is flat.
 
 ## Shapes
 
@@ -390,7 +385,7 @@ Soft geometry on a 5-step ladder: `xs` 2px, `sm` 4px, `md` 6px, `lg` 8px, `xl` 8
 
 ## 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.
+The catalog is the contract: 325 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
 
@@ -518,9 +513,9 @@ Hand-rolling a visual control, or importing a UI library at a call site, is neve
 
 **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 Back Leads Rule.** A record or drill-down page (a campaign inside Voice campaigns, a connector inside Data Integrations) is titled by its Breadcrumbs trail — parent / record at 16px — with no back arrow and no repeated H1; the page's one primary action sits at the right end of the same row. A standalone page-level Back control, when one is needed outside a hierarchy, sits immediately before the title and never on the right.
 
-**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.
+**The Tabs Lead, Search Trails Rule.** When tabs and a search field control the same content, they share one responsive control row: the tab list leads with its triggers left-aligned at their natural width over a baseline that fades from WG3 to transparent, and search sits at the trailing edge. On collection screens the trailing controls are icon triggers — SearchDisclosure (expands into the field) then Filters — and tab labels are 14px with a quieter count after each label.
 
 ## Do's and Don'ts
 
@@ -532,9 +527,9 @@ Every line below is a `do` or `dont` recorded on a principle in `ads-manifest.js
 - **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** keep cards, panels, chips, buttons, tabs, fields, thumbs, and other in-page surfaces at shadow-0; separate them with fill, border, or spacing. *(elevation-is-actionability)*
+- **Do** use shadow-float for floating layers that sit over content: toasts, toolbars, the chat composer dock, and any menu or popover that needs lift beyond its border. *(elevation-is-actionability)*
+- **Do** use shadow-overlay for modals, dialogs, and overlay drawers, so a dialog always reads above a menu. *(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)*
@@ -555,24 +550,42 @@ Every line below is a `do` or `dont` recorded on a principle in `ads-manifest.js
 - **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** open a multi-step create task launched from a collection (New campaign) as a Modal over that list: title-only header, one scrolling form (for New campaign: Campaign name, Caller numbers, Audience), and Cancel + Create together in the footer — the user never loses their place. Add a Stepper only when the task truly has separate steps. Form modals use a fixed height (Modal height="fixed", 640px) so the frame never resizes: the header and footer stay put and ModalBody scrolls. Standalone onboarding flows render full-screen with a single content container holding the inputs and its own Back/Continue. *(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** title a drill-down with Breadcrumbs (16px trail: muted parent links, Medium current item) and put its primary action (e.g. Pause campaign) right-aligned on the same row. *(leading-back-navigation)*
+- **Do** use PageHeader with onBack only for a standalone page that has no parent hierarchy to show. *(leading-back-navigation)*
+- **Do** reserve the trailing header area for forward or page-level actions such as Add, Save, Pause, or Share. *(leading-back-navigation)*
+- **Do** keep tab triggers left-aligned at their natural width, then place the scoped search opposite them in the same toolbar. *(tabs-search-opposed)*
+- **Do** on collection screens use SearchDisclosure followed by Filters as 32px icon triggers at the trailing edge; keep the page header for the title and one primary action only. *(tabs-search-opposed)*
+- **Do** give each status tab its count (All 42 · Active 14 · Paused 4); the count renders Regular in tertiary grey, teal on the active tab. *(tabs-search-opposed)*
 - **Do** on constrained containers, stack tabs first and search second while preserving their relationship. *(tabs-search-opposed)*
+- **Do** size the page so the rows fill the panel to its 24px bottom inset and Pagination sits at the bottom; let only the rows scroll. *(collection-screens)*
+- **Do** show row checkboxes only on hover/focus (and while checked or mixed); keep the header select-all checkbox always visible. *(collection-screens)*
+- **Do** when a row's details are open, mark it with TableRow isActive (the soft-teal fade) — no radio and no selection column for that purpose. *(collection-screens)*
+- **Do** put status in a Chip using business language (see status-language) and keep cell values at text-m. *(collection-screens)*
+- **Do** show the customer's workspace logo in the Sidebar brand slot (SidebarWorkspace) when the product runs inside a customer workspace. *(collection-screens)*
+- **Do** put the status Chip and its context ("Finished Oct 21") in the header, 4px under the title, so status never floats on its own. *(record-detail-panels)*
+- **Do** group numbers in small outlined stat cards (WG3 edge, radius-l, 12px padding, 8px apart) and the trend in its own chart card. *(record-detail-panels)*
+- **Do** list attributes (owner, started, calling windows) as label–value rows: label secondary left, value primary right, inset WG3 dividers. *(record-detail-panels)*
+- **Do** separate sections with 32px and keep items inside a section ≤16px apart; give each section a 14px Medium title. *(record-detail-panels)*
+- **Do** stat card: label (14px secondary) → number (32px) with its scope ("of 4,800 calls") 4px apart, then a Progress bar 12px below that fills the card width. *(analytics-surfaces)*
+- **Do** chart card: title (16px Medium) + scope subtitle (12px secondary) on the left, the legend right-aligned on the same row, ~40px from the title block to the plot. *(analytics-surfaces)*
+- **Do** bar charts print each bar's value; stacked bars print each segment that fits plus the stack total. Line charts print every point's value in the series colour (secondary grey for light amber/grey series). *(analytics-surfaces)*
+- **Do** size charts so the cards end on the panel's 24px bottom inset. *(analytics-surfaces)*
+- **Do** say Active, not Dialing; name the tab Active too (All · Draft · Active · Paused · Completed). *(status-language)*
+- **Do** use Chip tones consistently for the same status everywhere (table cell, detail header, filters). *(status-language)*
+- **Do** use the plain Chip appearance (square dot + 14px text) where a column of filled chips would shout louder than the record names. *(status-language)*
 
 ### 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** put a shadow on an in-page surface for decoration or to signal that it is clickable. *(elevation-is-actionability)*
+- **Don't** use raw shadow values, inset glows, or the removed numbered levels and elevation hook. *(elevation-is-actionability)*
+- **Don't** invent a third floating level; stack order comes from float vs overlay. *(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)*
@@ -590,8 +603,23 @@ Every line below is a `do` or `dont` recorded on a principle in `ads-manifest.js
 - **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** stack a back arrow and a large H1 above a page whose parent is already known — the breadcrumb says both. *(leading-back-navigation)*
 - **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)*
+- **Don't** put a Search button or a full-width search field in the page header of a collection screen. *(tabs-search-opposed)*
+- **Don't** leave an empty band under a short table, or float Pagination mid-panel. *(collection-screens)*
+- **Don't** use single-selection radios to mean 'this row is open'. *(collection-screens)*
+- **Don't** show a checkbox on every resting row of a multi-select table. *(collection-screens)*
+- **Don't** open record details in a modal over the list you are scanning. *(collection-screens)*
+- **Don't** mix attributes (owner) into the metric grid. *(record-detail-panels)*
+- **Don't** leave a lone chip or line of metadata between the title and the first section. *(record-detail-panels)*
+- **Don't** repeat the same fact (finish date) in the header and in Details. *(record-detail-panels)*
+- **Don't** separate stats with vertical hairlines while their bars run into the next stat — proximity breaks. *(analytics-surfaces)*
+- **Don't** hide numbers behind a hover tooltip. *(analytics-surfaces)*
+- **Don't** give a legend its own row under the subtitle when it fits beside the title. *(analytics-surfaces)*
+- **Don't** put the same spacing between a label and its value as between two separate cards. *(analytics-surfaces)*
+- **Don't** colour a status with the primary teal — it competes with the primary action and the selected-row fade. *(status-language)*
+- **Don't** use different words for the same state in the tab, the chip and the filter. *(status-language)*

package/README.md

@@ -156,6 +156,24 @@ Reference the semantic tokens (e.g. `bg-brand`, `text-muted-foreground`,
 `border-input`, `ring-ring`) rather than raw values; the full token list is in
 `manifest.json` under `tokens`.
 
+**Sample screens:** full screens built only from ADS exports ship as readable
+source in `node_modules/@actioneer/ads/examples/` (`AgentsScreen`,
+`SettingsScreen`, `WorkspaceHeaderScreen`, `CampaignsScreen`,
+`CampaignAnalysisScreen`). Open them to see how components are meant to be
+composed, or copy one into your app and swap in your own data; the folder's
+`README.md` lists what each one shows.
+
+**Screen recipes:** when you build a screen CLOSE to a collection (a list of
+records with a detail panel and a create modal) or a record's analytics page,
+start from `CampaignsScreen` / `CampaignAnalysisScreen` and follow the
+`collection-screens`, `record-detail-panels`, `analytics-surfaces` and
+`status-language` principles (`get_principles`) and the `collection-screen` /
+`record-analytics` productions (`get_ui_grammar`). In short: rows fill the panel
+with pagination at the bottom, row checkboxes on hover, `TableRow isActive` for
+the open row, status under the detail title, outlined stat and chart cards with
+legends in the title row and printed values, a 16px breadcrumb titling
+drill-downs, business-language statuses, and fixed-height form modals.
+
 Shared motion presets are named exports from `@actioneer/ads`. Components already
 include their own interaction motion; use the exported presets for additional
 application state changes.
@@ -197,7 +215,7 @@ every consuming repo honest.
 
 ## Documentation and license
 
-- [Storybook: components and recipes](https://actioneer-ads-storybook.himanshu-563.workers.dev)
+- [Storybook: components](https://actioneer-ads-storybook.himanshu-563.workers.dev)
 - [ADS MCP: component discovery for coding agents](https://www.npmjs.com/package/@actioneer/ads-mcp)
 - Bundled references: `@actioneer/ads/manifest.json`, `@actioneer/ads/llms.txt`,
   and `@actioneer/ads/DESIGN.md`.

package/components/ai-elements/chart.js

@@ -8,7 +8,7 @@ import { Collapsible as V, CollapsibleTrigger as W, CollapsibleContent as E } fr
 import { Skeleton as x } from "../skeleton.js";
 import { Spinner as v } from "../spinner.js";
 import { Database as O, ChevronDown as P, WarningCircle as S, Refresh as F, CloseCircle as G } from "../../lib/icons.js";
-import { cn as l } from "../../lib/cn.js";
+import { cn as s } from "../../lib/cn.js";
 const H = M(
   // An ARTIFACT card, not a work-trace row: the chart is a produced object,
   // so it reads like an attachment (contained hairline card + filled icon
@@ -91,7 +91,7 @@ function Z({
   progress: r,
   errorContent: i,
   onRetry: o,
-  children: s
+  children: l
 }) {
   return t === "error" ? /* @__PURE__ */ a(
     "div",
@@ -138,11 +138,11 @@ function Z({
       ),
       /* @__PURE__ */ e("span", { children: U(r) ?? "Receiving chart data" })
     ] }),
-    /* @__PURE__ */ e("div", { className: "min-h-40", children: s ?? /* @__PURE__ */ e(x, { className: "h-40 w-full" }) })
+    /* @__PURE__ */ e("div", { className: "min-h-40", children: l ?? /* @__PURE__ */ e(x, { className: "h-40 w-full" }) })
   ] }) : t !== "ready" ? /* @__PURE__ */ e(Y, { status: t }) : (
     // The ready chart draws itself in left→right (the reveal wipe) instead of
     // popping after the loading state — data entrance, not chrome.
-    /* @__PURE__ */ e("div", { className: "ads-reveal ads-reveal-wipe min-h-40", "data-slot": "ai-chart-visual", children: s })
+    /* @__PURE__ */ e("div", { className: "ads-reveal ads-reveal-wipe min-h-40", "data-slot": "ai-chart-visual", children: l })
   );
 }
 const ee = g.forwardRef(
@@ -151,7 +151,7 @@ const ee = g.forwardRef(
     status: r,
     title: i,
     tag: o,
-    source: s,
+    source: l,
     progress: c,
     elapsed: y,
     meta: d,
@@ -164,13 +164,13 @@ const ee = g.forwardRef(
     onRetry: w,
     children: k,
     role: A = "group",
-    "aria-label": z,
-    "aria-describedby": R,
-    "aria-busy": j,
+    "aria-label": R,
+    "aria-describedby": j,
+    "aria-busy": z,
     ...I
   }, $) => {
     const n = r ?? "ready", B = n === "querying" || n === "partial" || n === "rendering", m = d !== void 0 ? d : X(n, c, y), q = K[n], f = g.useId(), p = n === "ready" && u != null, D = [
-      R,
+      j,
       p ? f : void 0
     ].filter(Boolean).join(" ") || void 0;
     return /* @__PURE__ */ a(
@@ -181,11 +181,11 @@ const ee = g.forwardRef(
         defaultOpen: N,
         onOpenChange: C,
         role: A,
-        "aria-label": z ?? (typeof i == "string" ? i : "AI chart evidence"),
+        "aria-label": R ?? (typeof i == "string" ? i : "AI chart evidence"),
         "aria-describedby": D,
         "data-slot": "ai-chart",
         "data-status": n,
-        className: l(H({ status: n }), t),
+        className: s(H({ status: n }), t),
         ...I,
         children: [
           /* @__PURE__ */ e(
@@ -203,7 +203,7 @@ const ee = g.forwardRef(
             "button",
             {
               type: "button",
-              className: l(
+              className: s(
                 "group/ai-chart-trigger flex w-full items-center gap-2.5 px-2.5 py-2 text-left",
                 "outline-none transition-[background,color,transform] duration-150 ease-out hover:bg-fill active:scale-[0.97] motion-reduce:active:scale-100",
                 "focus-visible:ring-3 focus-visible:ring-inset focus-visible:ring-ring motion-reduce:transition-none"
@@ -213,7 +213,7 @@ const ee = g.forwardRef(
                   "span",
                   {
                     "aria-hidden": !0,
-                    className: "grid size-8 shrink-0 place-items-center rounded-md bg-surface",
+                    className: "grid h-8 w-5 shrink-0 place-items-center",
                     children: /* @__PURE__ */ e(O, { "data-slot": "ai-chart-icon", className: "size-4" })
                   }
                 ),
@@ -248,7 +248,7 @@ const ee = g.forwardRef(
           /* @__PURE__ */ a(
             E,
             {
-              className: l(
+              className: s(
                 "overflow-hidden px-2.5 pb-2.5 outline-none",
                 "data-[state=closed]:pointer-events-none"
               ),
@@ -257,7 +257,7 @@ const ee = g.forwardRef(
                   "div",
                   {
                     "data-slot": "ai-chart-body",
-                    "aria-busy": j ?? (B || void 0),
+                    "aria-busy": z ?? (B || void 0),
                     children: /* @__PURE__ */ e(
                       Z,
                       {
@@ -270,7 +270,7 @@ const ee = g.forwardRef(
                     )
                   }
                 ),
-                s && /* @__PURE__ */ e(
+                l && /* @__PURE__ */ e(
                   "div",
                   {
                     className: "mt-2 text-xs text-tertiary",
@@ -280,16 +280,16 @@ const ee = g.forwardRef(
                       {
                         type: "button",
                         className: "rounded-sm text-left text-s outline-none transition-colors duration-150 ease-out hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring motion-reduce:transition-none",
-                        "aria-label": `Open source ${s}`,
-                        onClick: () => h(s),
+                        "aria-label": `Open source ${l}`,
+                        onClick: () => h(l),
                         children: [
                           "from ",
-                          /* @__PURE__ */ e("span", { className: "font-normal tabular-nums", children: s })
+                          /* @__PURE__ */ e("span", { className: "font-normal tabular-nums", children: l })
                         ]
                       }
                     ) : /* @__PURE__ */ a("p", { children: [
                       "from ",
-                      /* @__PURE__ */ e("span", { className: "font-normal tabular-nums", children: s })
+                      /* @__PURE__ */ e("span", { className: "font-normal tabular-nums", children: l })
                     ] })
                   }
                 )