@actioneer/ads 1.0.8 → 1.0.10

package/DESIGN.md

@@ -60,41 +60,43 @@ colors:
   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"
+    fontFamily: "\"Season Mix\", serif"
     fontSize: "24px"
-    fontWeight: 500
-    lineHeight: "32px"
+    fontWeight: 400
+    lineHeight: "30px"
   title:
-    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
-    fontSize: "18px"
-    fontWeight: 500
-    lineHeight: "24px"
+    fontFamily: "\"Season Mix\", serif"
+    fontSize: "20px"
+    fontWeight: 400
+    lineHeight: "28px"
   headline:
-    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
-    fontSize: "16px"
-    fontWeight: 500
-    lineHeight: "22px"
+    fontFamily: "\"Season Mix\", serif"
+    fontSize: "18px"
+    fontWeight: 400
+    lineHeight: "26px"
   body:
-    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
-    fontSize: "14px"
+    fontFamily: "\"Geist\", system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+    fontSize: "16px"
     fontWeight: 400
-    lineHeight: "20px"
+    lineHeight: "24px"
   label:
-    fontFamily: "\"Aribau Grotesk\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
-    fontSize: "12px"
+    fontFamily: "\"Geist\", system-ui, -apple-system, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+    fontSize: "14px"
     fontWeight: 400
-    lineHeight: "16px"
+    lineHeight: "20px"
   mono:
     fontFamily: "\"JetBrains Mono Variable\", ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", \"Courier New\", monospace"
-    fontSize: "12px"
+    fontSize: "14px"
     fontWeight: 400
-    lineHeight: "16px"
+    lineHeight: "20px"
 rounded:
   xs: "2px"
   sm: "4px"
   md: "6px"
   lg: "8px"
   xl: "8px"
+  card: "14px"
+  window: "18px"
   full: "9999px"
 spacing:
   xs: "4px"
@@ -179,16 +181,16 @@ 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.8 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.10 is a library first and a look second. 335 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 17 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.
 
 **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
+- One typeface at two real weights on a 5-step ladder (24px / 20px / 18px / 16px / 14px), 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
+- Radius runs 2px / 4px / 6px / 8px / 8px / 14px / 18px, with a pill reserved for chips and avatars
 
 ## Colors
 
@@ -322,30 +324,30 @@ The warm-grey ground everything else stands on.
 
 ### 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.
+**The Fills Over Strokes Rule.** Delineate SURFACES (cards, panels, sidebars, page regions) with color contrast, elevation, and spacing — not decorative 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. Two kinds of 1px WG4 line follow opposite rules (the window panel style, user-mandated 2026-11-12): STRUCTURAL hairlines that split the page into its parts — under a header bar, under a DrawerHeader and above a DrawerFooter, between the page and an attached Drawer, between the sidebar and the page — run full width, wall to wall; ROW dividers between items inside one region stay inset to the content.
 
 ## Typography
 
-**Display font:** Aribau Grotesk
-**Body font:** Aribau Grotesk
+**Display font:** Season Mix
+**Body font:** Geist
 **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.
+**Character:** Season Mix sets heading roles (page, drawer, modal, section and chart titles); Geist carries body, labels, controls, rows and data values. Two real weights; hierarchy comes from size, ink strength and spacing, never a heavy weight.
 
 ### 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.
+- **Display** (400, 24px / 30px): page-level moments only.
+- **Title** (400, 20px / 28px): page titles.
+- **Headline** (400, 18px / 26px): emphasized body and section headings.
+- **Body** (400, 16px / 24px): the default, all reading text and control labels.
+- **Label** (400, 14px / 20px): the floor: captions, secondary text, table cells.
+- **Mono** (400, 14px / 20px): literal source code, and nothing else.
 
 ### Named rules
 
-**The One Face Rule.** One face (Aribau Grotesk), two real weights, a five-step ladder.
+**The Two Face Rule.** Two faces with fixed jobs (Season Mix for headings, Geist for everything else), two real weights, one scale.
 
-**The 12px Floor Rule.** Nothing renders below `--text-s` (12px). Density comes from spacing and layout, never from shrinking type.
+**The 14px Floor Rule.** Nothing renders below `--text-s` (14px). Density comes from spacing and layout, never from shrinking type.
 
 ## Layout
 
@@ -353,7 +355,7 @@ The shell owns the frame and screens own their content. ADS targets landscape ta
 
 ### 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 Shell Owns the Frame Rule.** The shell renders one app window (user-mandated 2026-11-12): a rounded-window (18px) surface with a 1px WG4 edge and shadow-window, inset 12px on the bg-surface (WG3) backdrop. The sidebar (bg-background) and the White PageBody sit inside it, split by one full-height WG4 hairline. Page headers are BodyPageHeader bars — 64px, 20px (text-xl) Medium title, actions trailing, full-width hairline below. A record's detail panel is an inline Drawer attached to the page: flush beside the content, one full-height hairline, no gap, radius or shadow. Screens never add their own outer padding, radius, card or shadow — a screen's root is flex h-full flex-col and fills the page.
 
 **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.
 
@@ -361,23 +363,26 @@ 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. 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.
+Flat by default with tonal layering. Depth comes from the plane system: a grey backdrop, one app window resting on it, white page inside. Eight shadows only: `--shadow-0` (flat — panels, rows, controls, the attached Drawer), `--shadow-float` (toasts, toolbars, composer dock), `--shadow-overlay` (modals, dialogs, overlay drawers), the two table scroll-hint smudges, `--shadow-card` (resting cards), `--shadow-window` (the app window) and `--shadow-nav-active` (the active sidebar item).
 
 ### Shadow vocabulary
 
 - **0** (`--shadow-0`): `none`
+- **card** (`--shadow-card`): `0 1px 2px rgb(32 32 32 / 0.04), 0 8px 24px -12px rgb(32 32 32 / 0.10)`
 - **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)`
+- **nav-active** (`--shadow-nav-active`): `0 1px 2px rgb(32 32 32 / 0.08), 0 4px 12px -4px rgb(32 32 32 / 0.14)`
 - **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)`
+- **window** (`--shadow-window`): `0 1px 2px rgb(32 32 32 / 0.05), 0 24px 48px -24px rgb(32 32 32 / 0.18)`
 
 ### Named rules
 
-**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.
+**The Elevation Is Actionability Rule.** ADS has eight shadow tokens: shadow-0 (flat, the default), shadow-float, shadow-overlay, the two table scroll-hint smudges, the two resting-surface lifts shadow-card and shadow-window, and shadow-nav-active for the active sidebar item (user-mandated 2026-11-12). Only a layer that floats above the page may carry float or overlay; resting cards (Card, stat/chart cards, ConnectorCard) carry shadow-card with rounded-card (14px) and a 1px WG4 edge; the app window carries shadow-window with rounded-window (18px); everything else in the page is 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.
+Soft geometry on a 7-step ladder: `xs` 2px, `sm` 4px, `md` 6px, `lg` 8px, `xl` 8px, `card` 14px, `window` 18px, plus a pill at `full` (9999px) for chips and avatars. `card` and `window` are surface radii for resting cards and the app window only. Tailwind's larger aliases (`2xl`, `3xl`) collapse onto the `lg` control step, so a stray `rounded-3xl` cannot exceed it.
 
 ### Named rules
 
@@ -385,7 +390,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: 335 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
 
@@ -513,9 +518,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 18px, the header-bar title size, in the 64px header bar — 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 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. 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 16px with a quieter count after each label.
 
 ## Do's and Don'ts
 
@@ -526,8 +531,12 @@ Every line below is a `do` or `dont` recorded on a principle in `ads-manifest.js
 - **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 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** keep strokes on focus rings, the outline Button/Badge/Chip variants, Kbd, Divider, the Tree connector rail, functional color swatches, the WG4 edge of resting cards and the app window, and the structural hairlines. *(fills-over-strokes)*
+- **Do** run structural hairlines edge to edge: the 64px header bar's bottom line, the DrawerHeader/DrawerFooter lines, the full-height line on an attached Drawer's leading edge, the sidebar's edge inside the app window. *(fills-over-strokes)*
+- **Do** inset row dividers: put the padding on the container and border-b on each row, so the line stops at the content edge. *(fills-over-strokes)*
+- **Do** keep panels, rows, chips, buttons, tabs, fields, thumbs, the attached Drawer and other in-page surfaces at shadow-0; separate them with fill, hairlines, or spacing. *(elevation-is-actionability)*
+- **Do** give resting cards rounded-card + border border-border + shadow-card, and the app window rounded-window + border border-border + shadow-window. *(elevation-is-actionability)*
+- **Do** lift the active sidebar item (its White fill) with shadow-nav-active; keep hover flat. *(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)*
@@ -538,8 +547,9 @@ Every line below is a `do` or `dont` recorded on a principle in `ads-manifest.js
 - **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** make a screen root flex h-full flex-col and fill the page with Panel(s); the shell renders them flush. *(shell-owns-the-frame)*
+- **Do** let one place (the shell) own the window, its radius, edge and shadow. *(shell-owns-the-frame)*
+- **Do** open record details in an attached Drawer beside the list, inside the same white page. *(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)*
@@ -550,30 +560,71 @@ 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. Every modal is fixed-height (sm 320px, md/lg/xl 640px — the Modal default) so the frame never resizes: the header and footer stay put and ModalBody scrolls; see principle create-modals. 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 tab triggers left-aligned at their natural width, then place the scoped search field opposite them in the same toolbar. *(tabs-search-opposed)*
+- **Do** title a drill-down with Breadcrumbs (20px trail, the same size as the header-bar title: 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** give a rate column a small Progress meter (size sm, ~48px) before the right-aligned percentage, and give a record with a recent trend a "Last 7 days" column holding a dotless Sparkline (height 28, dot={false}); a record with no calls yet shows an em dash and "No calls yet" in secondary text. *(collection-screens)*
+- **Do** show the owner as plain text — no avatar in the cell. *(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** compose DrawerHeader → DrawerKicker + DrawerTitle + DrawerMeta so status never floats on its own; the header's full-width hairline grounds it. *(record-detail-panels)*
+- **Do** let DrawerBody scroll (it is overflow-y-auto) — never clip the panel with overflow hidden. *(record-detail-panels)*
+- **Do** group numbers in small flat stat tiles (WG1 fill + 1px WG4 edge, rounded-card, 12px padding, no shadow, 8px apart) and a trend in its own chart tile. *(record-detail-panels)*
+- **Do** list attributes as a DetailList: sentence-case labels ("Type of loan", never type_of_loan), values right-aligned and wrapping, Not stated in secondary grey when empty (tertiary fails AA at 16px). *(record-detail-panels)*
+- **Do** count what a section holds in its title ("0 of 10") instead of a separate summary line. *(record-detail-panels)*
+- **Do** put rarely-needed data (call metadata) in a Collapsible at the end of the body, collapsed. *(record-detail-panels)*
+- **Do** add a DrawerFooter only when its action exists — Open full view only when the dedicated page exists. *(record-detail-panels)*
+- **Do** spell out the scope under the tabs with a FilterBar: joined 32px segments showing their current values — period preset + resolved dates leading, a second filter (cohort) trailing. *(analytics-surfaces)*
+- **Do** stat card: label (16px secondary) → number (text-4xl, 35px, tightened tracking) with its scope ("of 4,800 calls", 14px secondary) 4px apart, a Sparkline of its recent trend beside the number (right ~third of the card), then a Progress bar 12px below that fills the card width. *(analytics-surfaces)*
+- **Do** chart card: title (18px Medium) + scope subtitle (14px 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** keep LineChart's default gradientFill: a wash under each observed line fading top-to-bottom from 20% of the series colour to nothing (forecasts stay unfilled). *(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 + 16px text) where a column of filled chips would shout louder than the record names. *(status-language)*
+- **Do** keep Chip labels Regular weight — 14px (text-s) in solid and outline chips, 16px (text-m) in plain ones. *(status-language)*
+- **Do** use the Modal default height; pick size by width only (sm confirmation, md form, lg/xl dense content). *(create-modals)*
+- **Do** put 'optional / you can change this later' notes in Field info, not in a helper line under the control. *(create-modals)*
+- **Do** put a source switch (SegmentedControl size=sm, e.g. CSV upload | Empty audience) in Field actions on the label row. *(create-modals)*
+- **Do** use FileDropzone layout='inline' (bare icon · label + hint · Browse) when the upload shares the form with other fields. *(create-modals)*
+- **Do** let the user pick one saved record from a Table with selectionMode='single' (radio + soft-teal fade) under a search field, with the unit named once in the column header. *(create-modals)*
+- **Do** render icons bare in muted grey: in upload strips, empty states, labels and list rows. *(create-modals)*
+- **Do** give each group w-full; let SettingRow stretch to the panel width. *(settings-screens)*
+- **Do** use the control that matches the setting: Switch for on/off, an outline Button showing the current value for pickers ("10:00 – 19:00"), a Badge for a fixed threshold. *(settings-screens)*
+- **Do** keep the leading glyph bare and muted; rows separate with inset hairlines. *(settings-screens)*
 
 ### 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** stop a structural hairline short of the walls, or run a row divider full-bleed (divide-y on a container whose rows carry their own px-*). *(fills-over-strokes)*
 - **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** put shadow-card on a panel, a row, a detail-panel stat tile or the attached Drawer; put shadow-window on anything but the app window. *(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** set a glyph on a background tile, circle, or outlined square — icons sit bare in muted grey (avatars and brand logos keep their frames). *(icons-phosphor-regular)*
+- **Don't** add outer padding, a radius or a shadow on a screen, or wrap a screen in its own card. *(shell-owns-the-frame)*
+- **Don't** float a detail panel as a separate card with a strip of canvas between it and the list. *(shell-owns-the-frame)*
+- **Don't** put the sidebar outside the window, directly on the backdrop. *(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)*
@@ -584,8 +635,32 @@ 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** put a profile image beside every owner name, or draw an empty meter or a flat sparkline for a record with no data. *(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** repeat a fact: what the header says (status, time, length) never appears again in stat cards or write-back rows. *(record-detail-panels)*
+- **Don't** add placeholder footer buttons (Open full view, Call again) for a record that has no page or action behind them. *(record-detail-panels)*
+- **Don't** show raw field keys, monospace labels, or a dash pattern like "— not stated" for empty values. *(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** set a Chip label in Medium; the tone, dot and edge already carry the emphasis. *(status-language)*
+- **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)*
+- **Don't** pass height='content' or let a modal resize as sections appear or disappear. *(create-modals)*
+- **Don't** stack a tall drop target, a search, and an unlabeled list one after another inside a fixed-height form. *(create-modals)*
+- **Don't** hand-roll a pick-one list with justify-between rows or an 'or' divider between alternatives. *(create-modals)*
+- **Don't** put an icon on a grey tile, a circle, or an outlined square that adds nothing but a background. *(create-modals)*
+- **Don't** cap a settings group at a fixed width (720px) and leave the right half of the panel empty. *(settings-screens)*
+- **Don't** put a save button per group, or icons on tiles. *(settings-screens)*

package/README.md

@@ -1,7 +1,7 @@
 # @actioneer/ads
 
 The **Actioneer Design System**: React 19 components, Tailwind CSS v4 tokens,
-bundled Aribau Grotesk fonts, and accessible interactions with built-in motion.
+bundled Geist body font, Season Mix heading tokens, and accessible interactions with built-in motion.
 
 [Browse components in Storybook](https://actioneer-ads-storybook.himanshu-563.workers.dev).
 
@@ -48,8 +48,10 @@ Tailwind:
 `tailwindcss`:
 
 - the `@theme` **design tokens** (colors, typography, spacing, and radii),
-- the **Aribau Grotesk** `@font-face` rules (served package-relative — no
-  `/public` copy needed), and
+- the **Geist** `@font-face` rule (served package-relative — no `/public` copy
+  needed). Headings use `--font-heading: "Season Mix"`; Season Mix is licensed
+  and not bundled, so declare its `@font-face` in your app from your licensed
+  file (without it, headings fall back to the platform serif), and
 - a baked `@source "./**/*.{js,mjs}"` so Tailwind scans ADS's own class usage and
   generates its utilities in your build.
 
@@ -158,9 +160,31 @@ Reference the semantic tokens (e.g. `bg-brand`, `text-muted-foreground`,
 
 **Sample screens:** full screens built only from ADS exports ship as readable
 source in `node_modules/@actioneer/ads/examples/` (`AgentsScreen`,
-`SettingsScreen`, `WorkspaceHeaderScreen`). 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.
+`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`,
+`status-language`, `create-modals` and `settings-screens` principles
+(`get_principles`) and the `collection-screen` / `record-analytics` /
+`create-modal` / `record-call-logs` / `settings-screen` productions
+(`get_ui_grammar`). A record's call logs start from `CallLogsScreen`; a
+settings page from `GuardrailsSettingsScreen`. 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 modals (sm 320px,
+md–xl 640px). Inside a create modal (`NewCampaignModal`): optional guidance in
+a `Field info` icon, a source switch in `Field actions`, an inline
+`FileDropzone`, a single-select `Table` to reuse a saved record, and bare
+icons with no tile behind them. Record panels: a grounded `DrawerHeader`
+(`DrawerKicker`, `DrawerTitle`, `DrawerMeta`), a scrolling `DrawerBody` of
+`DrawerSection`s, `DetailList` attributes with Not stated empties, each fact
+once, and no footer unless its action exists. Settings groups fill the panel.
 
 Shared motion presets are named exports from `@actioneer/ads`. Components already
 include their own interaction motion; use the exported presets for additional
@@ -203,7 +227,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/answer.js

@@ -1224,7 +1224,7 @@ const ce = p.forwardRef(
               {
                 className: g(
                   A({ tone: a.value.tone }),
-                  "mt-1 text-3xl font-normal tracking-tight"
+                  "mt-1 text-4xl font-normal"
                 ),
                 children: a.value.value
               }

package/components/assistant-ui/composer-harness.js

@@ -1,8 +1,8 @@
 "use client";
 var c = Object.defineProperty;
 var l = (r, t, o) => t in r ? c(r, t, { enumerable: !0, configurable: !0, writable: !0, value: o }) : r[t] = o;
-var p = (r, t, o) => l(r, typeof t != "symbol" ? t + "" : t, o);
-import { jsxs as n, jsx as e } from "react/jsx-runtime";
+var n = (r, t, o) => l(r, typeof t != "symbol" ? t + "" : t, o);
+import { jsxs as p, jsx as e } from "react/jsx-runtime";
 import { useComposerRuntime as d, useComposer as u } from "@assistant-ui/react";
 import "../../lib/cn.js";
 import "../../lib/interactive.js";
@@ -39,6 +39,8 @@ import "react-aria-components";
 import "../autocomplete.js";
 import "../slider.js";
 import "../segmented.js";
+import "../filters.js";
+import "../filter-bar.js";
 import "../modal.js";
 import "../drawer.js";
 import "../popover.js";
@@ -59,6 +61,8 @@ import "../avatar.js";
 import "../badge.js";
 import "../chip.js";
 import "../timeline.js";
+import "../detail-list.js";
+import "../sparkline.js";
 import "../alert.js";
 import "../surface-loader.js";
 import "../pixel-blast-svg.js";
@@ -127,7 +131,7 @@ const m = "application/x-actioneer-harness", S = [
     instructions: "Write a concise executive brief: lead with the decision or insight, use only decision-relevant evidence, and end with the recommended next action."
   }
 ];
-function wi() {
+function Di() {
   const r = d(), t = u((i) => i.attachments), o = new Set(
     t.filter((i) => i.contentType === m).map((i) => i.name)
   ), s = (i) => {
@@ -135,8 +139,8 @@ function wi() {
       new File([i.instructions], `${i.label}.harness`, { type: m })
     );
   };
-  return /* @__PURE__ */ n(b, { children: [
-    /* @__PURE__ */ e(v, { children: /* @__PURE__ */ n(
+  return /* @__PURE__ */ p(b, { children: [
+    /* @__PURE__ */ e(v, { children: /* @__PURE__ */ p(
       "button",
       {
         type: "button",
@@ -155,7 +159,7 @@ function wi() {
         ]
       }
     ) }),
-    /* @__PURE__ */ n(y, { side: "top", align: "start", className: "w-56", autoFocusFirstItem: !1, children: [
+    /* @__PURE__ */ p(y, { side: "top", align: "start", className: "w-56", autoFocusFirstItem: !1, children: [
       /* @__PURE__ */ e(x, { children: "Add a harness" }),
       S.map((i) => /* @__PURE__ */ e(
         w,
@@ -170,9 +174,9 @@ function wi() {
     ] })
   ] });
 }
-class Si {
+class Ei {
   constructor() {
-    p(this, "accept", m);
+    n(this, "accept", m);
   }
   async add(t) {
     return {
@@ -203,7 +207,7 @@ ${o}
   }
 }
 export {
-  wi as ComposerHarness,
+  Di as ComposerHarness,
   m as HARNESS_MIME,
-  Si as HarnessAttachmentAdapter
+  Ei as HarnessAttachmentAdapter
 };

package/components/body-page-header.d.ts

@@ -6,10 +6,15 @@ export interface BodyPageHeaderProps extends Omit<React.HTMLAttributes<HTMLEleme
     actions?: React.ReactNode;
 }
 /**
- * Borderless header for a PageBody destination.
+ * Header bar for a PageBody destination (the window panel style,
+ * user-mandated 2026-11-12).
  *
- * The header owns a 24px inset on every side and keeps the page title at the
- * canonical 24px title-1 step. Destination icons and compact metadata belong in the
- * sidebar or content, not beside the title.
+ * A 64px bar: the 18px page title at the leading edge, page actions (and any
+ * quiet "Updated 2m ago" meta) at the trailing edge, 24px side insets, and a
+ * full-width WG4 hairline under it that separates the bar from the page
+ * content. The hairline is structural, so it runs edge to edge; row dividers
+ * inside the content stay inset. The bar owns the 24px gap to the content
+ * below (mb-6), so content never pads its own top.
+ * Destination icons belong in the sidebar, not beside the title.
  */
 export declare const BodyPageHeader: React.ForwardRefExoticComponent<BodyPageHeaderProps & React.RefAttributes<HTMLElement>>;

package/components/body-page-header.js

@@ -1,24 +1,24 @@
 "use client";
-import { jsxs as i, jsx as r } from "react/jsx-runtime";
-import * as d from "react";
-import { cn as n } from "../lib/cn.js";
-const l = d.forwardRef(({ className: a, title: t, actions: e, ...s }, m) => /* @__PURE__ */ i(
+import { jsxs as s, jsx as r } from "react/jsx-runtime";
+import * as i from "react";
+import { cn as o } from "../lib/cn.js";
+const n = i.forwardRef(({ className: a, title: t, actions: e, ...d }, m) => /* @__PURE__ */ s(
   "header",
   {
     ref: m,
     "data-slot": "body-page-header",
-    className: n(
-      "flex shrink-0 items-center justify-between gap-4 p-6",
+    className: o(
+      "mb-6 flex h-16 shrink-0 items-center justify-between gap-4 border-b border-border px-6",
       a
     ),
-    ...s,
+    ...d,
     children: [
-      /* @__PURE__ */ r("h1", { className: "min-w-0 truncate text-2xl font-medium text-on-warm-grey-primary", children: t }),
+      /* @__PURE__ */ r("h1", { className: "m-0 min-w-0 truncate text-xl font-medium text-on-white-primary", children: t }),
       e ? /* @__PURE__ */ r("div", { className: "flex shrink-0 items-center gap-2", children: e }) : null
     ]
   }
 ));
-l.displayName = "BodyPageHeader";
+n.displayName = "BodyPageHeader";
 export {
-  l as BodyPageHeader
+  n as BodyPageHeader
 };