@actioneer/ads 1.0.8 → 1.0.10

package/llms.txt

@@ -5,7 +5,7 @@
 ## Setup
 
 1. Install: `npm install @actioneer/ads` (or run `npx @actioneer/ads init`).
-2. In your global stylesheet, after `@import "tailwindcss";`, add `@import "@actioneer/ads/styles.css";` — it carries the `@theme` tokens, the Aribau `@font-face`, and the `@source` that makes Tailwind scan ADS classes. Imported standalone (not into the tailwindcss graph) its `@theme` is inert and no tokens emit.
+2. In your global stylesheet, after `@import "tailwindcss";`, add `@import "@actioneer/ads/styles.css";` — it carries the `@theme` tokens, the Geist `@font-face`, and the `@source` that makes Tailwind scan ADS classes. Imported standalone (not into the tailwindcss graph) its `@theme` is inert and no tokens emit.
 3. Wrap the app root with the required providers:
    - `TooltipProvider` (from `@actioneer/ads`) — wrap the app; the vendored tooltip/attachment chips crash without an ancestor provider
    - `ToastProvider` (from `@actioneer/ads`) — required to render toasts
@@ -79,26 +79,32 @@ The house rules for every ADS UI. `[lint]` = `@actioneer/ads-lint` auto-checks i
 
 ### 1. Prefer fills & elevation over strokes — but keep a balance (~75/25) [judgment]
 
-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.
+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.
 
 - Do: Establish hierarchy with at most two persistent layers: bg-background for the screen ground and bg-card/bg-elevated for the primary surface.
 - 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.
 - 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).
-- Do: Keep strokes on focus rings, the outline Button/Badge/Chip variants, Kbd, Divider, the Tree connector rail, and functional color swatches.
+- 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.
+- 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.
+- Do: Inset row dividers: put the padding on the container and border-b on each row, so the line stops at the content edge.
 - Don't: Add a border to a surface to separate or group it — use fill/elevation/spacing instead.
 - 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.
 - Don't: Give a filled control no stroke on the tinted canvas — it disappears; it needs a crisp edge.
+- 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-*).
 
-### 2. Five shadows, floating layers only [judgment]
+### 2. Eight shadows: floating layers, resting cards, the app window, the active nav item [judgment]
 
-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.
+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.
 
-- Do: Keep cards, panels, chips, buttons, tabs, fields, thumbs, and other in-page surfaces at shadow-0; separate them with fill, border, or spacing.
+- 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.
+- Do: Give resting cards rounded-card + border border-border + shadow-card, and the app window rounded-window + border border-border + shadow-window.
+- Do: Lift the active sidebar item (its White fill) with shadow-nav-active; keep hover flat.
 - 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.
 - Do: Use shadow-overlay for modals, dialogs, and overlay drawers, so a dialog always reads above a menu.
 - Don't: Put a shadow on an in-page surface for decoration or to signal that it is clickable.
 - Don't: Use raw shadow values, inset glows, or the removed numbered levels and elevation hook.
 - Don't: Invent a third floating level; stack order comes from float vs overlay.
+- 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.
 
 ### 3. Motion follows the interaction [lint: unbounded-transition, sluggish-easing, zero-scale-entrance, undersized-zoom-entrance, raw-spring-config]
 
@@ -123,14 +129,18 @@ All icons come from Phosphor Icons at the regular weight — the stroke-led icon
 - Do: Render weight='fill' for the active or selected state, and weight='bold' for the rare heavier stroke.
 - Don't: Import from an icon package directly, or install a second icon set.
 - Don't: Leave an active nav item's icon at the regular stroke weight.
+- 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).
 
-### 5. Demo screens: the shell owns the frame [judgment]
+### 5. Demo screens: the shell owns the app window [judgment]
 
-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 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.
 
-- Do: Make a screen root flex h-full flex-col and fill the frame with Panel(s).
-- Do: Let one place (the shell) own the inset so every screen aligns to the rail.
-- Don't: Add outer padding on a screen, leaving a tinted-canvas gap on the left.
+- Do: Make a screen root flex h-full flex-col and fill the page with Panel(s); the shell renders them flush.
+- Do: Let one place (the shell) own the window, its radius, edge and shadow.
+- Do: Open record details in an attached Drawer beside the list, inside the same white page.
+- Don't: Add outer padding, a radius or a shadow on a screen, or wrap a screen in its own card.
+- Don't: Float a detail panel as a separate card with a strip of canvas between it and the list.
+- Don't: Put the sidebar outside the window, directly on the backdrop.
 
 ### 6. Status dots are square [judgment]
 
@@ -160,7 +170,7 @@ A screen carries ONLY what the user needs to move forward: one title, the inputs
 - Do: Prefer more, smaller steps over dense ones; ask one thing at a time.
 - Do: Derive instead of asking whenever possible (a name from a work email, the company from its domain).
 - 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.
-- Do: Render multi-step flows full-screen — a single content container that holds the inputs and its own Back/Continue is fine.
+- 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.
 - 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.
 - Don't: Add any header description unless the user explicitly requested supporting copy for that page, section, panel, modal, dialog, drawer, or popover.
 - Don't: Decorate a labeled button with a redundant leading or trailing icon.
@@ -176,24 +186,114 @@ ADS targets landscape tablet (1024) → laptop (1440) → wide display (1920+);
 - Don't: Use sm:/md: viewport variants inside src/components, or hardcode a pane width there.
 - Don't: Cap a grid at a hard column count so it stops growing on wide displays.
 
-### 10. Back navigation is leading [judgment]
+### 10. Back navigation is leading; drill-downs use the breadcrumb [judgment]
 
-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.
+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.
 
-- Do: Use PageHeader with onBack so the left arrow is anchored directly before the title.
-- Do: Reserve the trailing header area for forward or page-level actions such as Add, Save, or Share.
+- 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.
+- Do: Use PageHeader with onBack only for a standalone page that has no parent hierarchy to show.
+- Do: Reserve the trailing header area for forward or page-level actions such as Add, Save, Pause, or Share.
+- Don't: Stack a back arrow and a large H1 above a page whose parent is already known — the breadcrumb says both.
 - Don't: Place Back on the right side of a page header.
 - Don't: Render a redundant visible Back label when the standard left arrow and accessible label are sufficient.
 
 ### 11. Tabs lead; scoped search trails [judgment]
 
-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.
+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: Keep tab triggers left-aligned at their natural width, then place the scoped search field opposite them in the same toolbar.
+- Do: Keep tab triggers left-aligned at their natural width, then place the scoped search opposite them in the same toolbar.
+- 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.
+- 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.
 - Do: On constrained containers, stack tabs first and search second while preserving their relationship.
 - Don't: Stretch the tab track to fill the space between its labels and the search field.
 - Don't: Put a scoped search field on a separate row above its tabs when both controls fit side by side.
 - Don't: Place search before tabs in the reading or keyboard order.
+- Don't: Put a Search button or a full-width search field in the page header of a collection screen.
+
+### 12. Collection screens fill the panel [judgment]
+
+A collection screen (campaigns, call logs, leads) is one white page in the app window: BodyPageHeader (the 64px header bar — title + one primary action, full-width hairline), the tab/search/filter row, then a Table whose rows fill the panel's height with Pagination pinned to its bottom edge. Rows open details in a Drawer attached beside the list by one full-height hairline; the list stays visible.
+
+- 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.
+- Do: Show row checkboxes only on hover/focus (and while checked or mixed); keep the header select-all checkbox always visible.
+- 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.
+- Do: Put status in a Chip using business language (see status-language) and keep cell values at text-m.
+- 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.
+- Do: Show the owner as plain text — no avatar in the cell.
+- Do: Show the customer's workspace logo in the Sidebar brand slot (SidebarWorkspace) when the product runs inside a customer workspace.
+- Don't: Leave an empty band under a short table, or float Pagination mid-panel.
+- Don't: Use single-selection radios to mean 'this row is open'.
+- Don't: Show a checkbox on every resting row of a multi-select table.
+- 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.
+- Don't: Open record details in a modal over the list you are scanning.
+
+### 13. Record detail panels are grouped by question [judgment]
+
+A selection-driven detail panel (a campaign, a call) has three regions. DrawerHeader never scrolls: DrawerKicker (the KIND of record), DrawerTitle, then DrawerMeta — the status Chip and its one-line 16px context ("12 Sep, 3:41 PM · 4s") 8px under the title — closed by a full-width WG4 hairline. DrawerBody is the only scrolling region: DrawerSections 32px apart, each a 16px Medium title (with an optional Regular secondary count — "Transcript · 1 turn", "Captured fields · 0 of 10"). Attributes are a DetailList. A DrawerFooter exists only when an action leads somewhere real, and opens with a full-width hairline. The panel is attached to the page: one full-height WG4 hairline on its leading edge, no gap, radius or shadow.
+
+- Do: Compose DrawerHeader → DrawerKicker + DrawerTitle + DrawerMeta so status never floats on its own; the header's full-width hairline grounds it.
+- Do: Let DrawerBody scroll (it is overflow-y-auto) — never clip the panel with overflow hidden.
+- 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.
+- 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).
+- Do: Count what a section holds in its title ("0 of 10") instead of a separate summary line.
+- Do: Put rarely-needed data (call metadata) in a Collapsible at the end of the body, collapsed.
+- Do: Add a DrawerFooter only when its action exists — Open full view only when the dedicated page exists.
+- Don't: Mix attributes (owner) into the metric grid.
+- Don't: Repeat a fact: what the header says (status, time, length) never appears again in stat cards or write-back rows.
+- Don't: Add placeholder footer buttons (Open full view, Call again) for a record that has no page or action behind them.
+- Don't: Show raw field keys, monospace labels, or a dash pattern like "— not stated" for empty values.
+
+### 14. Stats and charts sit in their own containers, values visible [judgment]
+
+On analytics/record pages every stat and every chart is its own resting card (1px WG4 border, rounded-card 14px, shadow-card, 20px padding, white) on the white page, 16px apart. Values are printed on the chart by default — never hover-only — and the legend sits at the right end of the chart's title row.
+
+- 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.
+- 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.
+- 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.
+- 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).
+- 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).
+- Do: Size charts so the cards end on the panel's 24px bottom inset.
+- Don't: Separate stats with vertical hairlines while their bars run into the next stat — proximity breaks.
+- Don't: Hide numbers behind a hover tooltip.
+- Don't: Give a legend its own row under the subtitle when it fits beside the title.
+- Don't: Put the same spacing between a label and its value as between two separate cards.
+
+### 15. Status speaks the business, with one tone per meaning [judgment]
+
+Status labels name the business state, not the machine's activity, and tabs use the same words. Campaign statuses: Active and Scheduled (info blue), Paused (warning amber), Completed (success green), Draft (default grey), Failed (danger red). Call statuses: Completed (success), No answer and Busy (warning), Failed (danger); a call's outcome ("Customer did not speak") is a separate column that exists only once the call connected — show an em dash otherwise. Teal is reserved for actions and selection, not for a status.
+
+- Do: Say Active, not Dialing; name the tab Active too (All · Draft · Active · Paused · Completed).
+- Do: Use Chip tones consistently for the same status everywhere (table cell, detail header, filters).
+- Do: Use the plain Chip appearance (square dot + 16px text) where a column of filled chips would shout louder than the record names.
+- Do: Keep Chip labels Regular weight — 14px (text-s) in solid and outline chips, 16px (text-m) in plain ones.
+- Don't: Set a Chip label in Medium; the tone, dot and edge already carry the emphasis.
+- Don't: Colour a status with the primary teal — it competes with the primary action and the selected-row fade.
+- Don't: Use different words for the same state in the tab, the chip and the filter.
+
+### 16. Create modals: fixed frame, quiet guidance, compact inputs [judgment]
+
+Every Modal has a fixed height — sm confirmations 320px (--modal-height-sm), md/lg/xl dialogs 640px (--modal-height) — and never grows or shrinks with its content: the header and footer stay put and ModalBody scrolls. Inside a create form, each field is a Field: optional guidance sits behind a bare info icon after the label (Field info), a control that picks the field's source sits at the right end of the label row (Field actions), an upload is the 64px inline FileDropzone, and choosing one saved record is a single-select Table with a search above it. Icons sit bare: no tile, circle, or fill behind a glyph.
+
+- Do: Use the Modal default height; pick size by width only (sm confirmation, md form, lg/xl dense content).
+- Do: Put 'optional / you can change this later' notes in Field info, not in a helper line under the control.
+- Do: Put a source switch (SegmentedControl size=sm, e.g. CSV upload | Empty audience) in Field actions on the label row.
+- Do: Use FileDropzone layout='inline' (bare icon · label + hint · Browse) when the upload shares the form with other fields.
+- 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.
+- Do: Render icons bare in muted grey: in upload strips, empty states, labels and list rows.
+- Don't: Pass height='content' or let a modal resize as sections appear or disappear.
+- Don't: Stack a tall drop target, a search, and an unlabeled list one after another inside a fixed-height form.
+- Don't: Hand-roll a pick-one list with justify-between rows or an 'or' divider between alternatives.
+- Don't: Put an icon on a grey tile, a circle, or an outlined square that adds nothing but a background.
+
+### 17. Settings screens fill the panel [judgment]
+
+A settings screen is one white page: BodyPageHeader (the header bar — title + the one save action), then setting groups 32px apart. Every group fills the panel's width between its 24px side insets — no fixed reading-width column — so each row's control lines up on the panel's right edge under the save action. A group is an 18px Medium title over a SettingList of SettingRows: bare glyph, label + one-line description, and the control that changes it.
+
+- Do: Give each group w-full; let SettingRow stretch to the panel width.
+- 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.
+- Do: Keep the leading glyph bare and muted; rows separate with inset hairlines.
+- Don't: Cap a settings group at a fixed width (720px) and leave the right half of the panel empty.
+- Don't: Put a save button per group, or icons on tiles.
 
 ## UI grammar
 
@@ -203,8 +303,13 @@ Before composing a screen, match its intent to one production below, preserve th
 - `browse-with-detail` — Browse with selection-driven detail: A primary browse Panel and an inline Drawer mounted as shell-level siblings. (intents: browse, records, list detail, inspector, audit log; Storybook: ADS/Components/Navigation/Sidebar)
 - `data-table` — Structured data table: Semantic table anatomy with matching header and body rows. (intents: table, records, comparison, sorting, selection; Storybook: ADS/Components/Data display/Table)
 - `tabbed-results` — Tabbed results with scoped search: Tabs lead and a scoped search trails in one responsive control row. (intents: tabs, filter, search, results, segmented views; Storybook: ADS/Components/Data display/Tabs)
+- `collection-screen` — Collection screen with record detail: BodyPageHeader (title + one primary action), a control row with counted Tabs leading and SearchDisclosure + Filters trailing, a Table whose rows fill the panel with Pagination at its bottom edge, a shell-level Drawer for the open record, and a fixed-height Modal for the create task. (intents: campaigns, call logs, leads, records list, collection, list page, new campaign; Storybook: ADS/Components/Table)
+- `record-analytics` — Record analytics page: A drill-down page titled by its Breadcrumbs (parent / record) with the primary action on the same row, record Tabs, a FilterBar scope row, then resting stat cards and chart cards whose legends sit in their title row and whose values are printed. (intents: analysis, analytics tab, record page, campaign analysis, metrics, dashboard tab; Storybook: ADS/Components/Chart)
 - `modal-task` — Blocking modal task: A focused interruption with one title, body, and decisive footer. (intents: modal, confirmation, short form, blocking task, destructive action; Storybook: ADS/Components/Overlays/Modal)
-- `settings-card` — Settings card: A compact settings surface with grouped SettingRows and one save action. (intents: settings, preferences, configuration, toggles; Storybook: ADS/Recipes/Settings panel)
+- `create-modal` — Create modal over a collection: A fixed-height Modal opened from a collection's primary action: title-only header, one scrolling form of Fields (optional guidance in an info icon, a source switch in the label row, an inline upload strip, a single-select Table to reuse a saved record), and Cancel + Create in the footer. (intents: new campaign, create, new record, create form, setup modal, add audience, upload list; Storybook: ADS/Components/Modal)
+- `record-call-logs` — Record call logs with a call panel: A record tab (Call logs) titled by Breadcrumbs with the record status beside it and the record actions on the right, a Table of calls (Number · Status · Outcome · Duration) filling the panel, and a shell-level call panel: grounded header, scrolling sections, no footer. (intents: call logs, call review, calls, call detail, call panel, recordings, transcript, crm write-back, captured fields; Storybook: ADS/Components/Drawer)
+- `settings-screen` — Settings screen: One white page: the BodyPageHeader bar with the save action, then full-width setting groups (18px title over a SettingList) 32px apart. (intents: settings, guardrails, preferences, configuration page, compliance settings; Storybook: ADS/Components/SettingRow)
+- `settings-card` — Settings card: A compact settings surface with grouped SettingRows and one save action. (intents: settings, preferences, configuration, toggles; Storybook: ADS/Components/Under review/SettingList / SettingRow)
 - `research-trace` — Inspectable research trace: ResearchActivity owns the run summary and contains the canonical ChainOfThought tree. (intents: agent trace, research, tool activity, sources, long-running task; Storybook: ADS/Components/AI Elements/Research Activity)
 - `typed-answer` — Typed research answer: A request/answer turn where structured output flows through AnswerRenderer. (intents: answer, research result, citations, follow-up, assistant response; Storybook: ADS/Components/AI Elements/Message)
 - `workflow-canvas` — Workflow canvas: InfiniteCanvas owns pan, zoom, grid, edges, controls, and responsive canvas chrome. (intents: workflow, node graph, canvas, diagram, flow builder; Storybook: ADS/Components/Data display/InfiniteCanvas)
@@ -253,7 +358,8 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [Field] — Wrap any form control (Input, Select, NumberField, Textarea, etc.) with a label plus optional description or error footer. [docs](https://ads.actioneer.dev/#/field)
 - [FieldDescription] — component [docs](https://ads.actioneer.dev/#/field)
 - [FieldError] — component [docs](https://ads.actioneer.dev/#/field)
-- [FileDropzone] — component (variants: hasFiles: true|false; isDragging: true|false; isDisabled: true|false) [docs](https://ads.actioneer.dev/#/review/file-dropzone)
+- [FieldInfo] — component [docs](https://ads.actioneer.dev/#/field)
+- [FileDropzone] — component (variants: hasFiles: true|false; layout: stacked|inline; isDragging: true|false; isDisabled: true|false) [docs](https://ads.actioneer.dev/#/review/file-dropzone)
 - [Heading] — Use Heading for semantic h1–h4 titles above a page, section, or card, sized by document level via `level` (never a `size` prop). [docs](https://ads.actioneer.dev/#/typography)
 - [Kbd] — Use to display a keyboard shortcut or key name, inline in text or trailing a label in a shortcut list. [docs](https://ads.actioneer.dev/#/kbd)
 - [Label] — component [docs](https://ads.actioneer.dev/#/field)
@@ -271,6 +377,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [AudioWaveformLook] — TypeScript type
 - [AudioWaveformProps] — TypeScript type
 - [ButtonProps] — TypeScript type
+- [ButtonSize] — TypeScript type
 - [CodeBlockProps] — TypeScript type
 - [DividerProps] — TypeScript type
 - [FieldProps] — TypeScript type
@@ -306,6 +413,10 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [Checkbox] — Use for a standalone boolean toggle or a multi-select list item — including a tri-state "select all" via `indeterminate`. [docs](https://ads.actioneer.dev/#/checkbox)
 - [CheckboxGroup] — component [docs](https://ads.actioneer.dev/#/checkbox)
 - [DateRangePicker] — component [docs](https://ads.actioneer.dev/#/date-range-picker)
+- [FilterBar] — component [docs](https://ads.actioneer.dev/#/filter-bar)
+- [FilterBarSelect] — component [docs](https://ads.actioneer.dev/#/filter-bar)
+- [FilterBarValue] — component [docs](https://ads.actioneer.dev/#/filter-bar)
+- [Filters] — component [docs](https://ads.actioneer.dev/#/filters)
 - [Input] — Use for any single-line text value, wrapped in `Field` for label/description/error and `startContent`/`endContent` for icons or inline actions. [docs](https://ads.actioneer.dev/#/input)
 - [InputField] — component [docs](https://ads.actioneer.dev/#/input-field)
 - [NumberField] — Use for a bounded numeric quantity (e.g. seats, width, count) that benefits from stepper buttons and min/max clamping, not free-form numeric text entry. [docs](https://ads.actioneer.dev/#/number-field)
@@ -324,6 +435,13 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [DateRangePickerProps] — TypeScript type
 - [DateRangeValue] — TypeScript type
 - [DropdownOptionsProps] — TypeScript type
+- [FilterBarOption] — TypeScript type
+- [FilterBarProps] — TypeScript type
+- [FilterBarSelectProps] — TypeScript type
+- [FilterBarValueProps] — TypeScript type
+- [FilterGroup] — TypeScript type
+- [FilterOption] — TypeScript type
+- [FiltersProps] — TypeScript type
 - [InputFieldProps] — TypeScript type
 - [InputProps] — TypeScript type
 - [NumberFieldProps] — TypeScript type
@@ -342,10 +460,13 @@ Before using any component below, preserve its built-in motion and apply the mot
 ### Overlays
 
 - [CommandPalette] — component [docs](https://ads.actioneer.dev/#/command-palette)
-- [Drawer] — Use the portaled Drawer for a focused, blocking task (form, details, settings) that slides in over the page with a backdrop and focus trap; use InlineDrawer instead for a contextual panel that must stay in-flow beside content the user still needs. The inline Drawer is a flat white panel (bg-card, no shadow, no border) that reads ONLY by fill contrast, so it MUST sit as a sibling of its content inside a bg-surface flex row — on a white (bg-background) parent it is invisible. If it doesn't read, tint the ground; never add a border or shadow to force it. SELECTION-DRIVEN DETAIL RAILS (inspector/detail panels tied to a selected row, node, or category) are CLOSED BY DEFAULT: the slot mounts only while a selection exists and unmounts on deselect. Never render a placeholder rail ('Select a row to see details') — an empty rail is chrome that claims space and implies a selection the user hasn't made. Header anatomy when open: uppercase kicker (what kind of thing is selected) + title + close affordance, then a scrollable body. Never hand-roll the panel with translate-x + backdrop — that's this component. (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
+- [Drawer] — Use the portaled Drawer for a focused, blocking task (form, details, settings) that slides in over the page with a backdrop and focus trap; use InlineDrawer instead for a contextual panel that must stay in-flow beside content the user still needs. The inline Drawer is attached to the page: a flat white panel (bg-card, no radius, no shadow) that sits flush beside its content inside the white page and draws one full-height WG4 hairline on its leading edge; its header and footer close with full-width hairlines. Never float it as a separate card with a strip of canvas between, and never give it a shadow. SELECTION-DRIVEN DETAIL RAILS (inspector/detail panels tied to a selected row, node, or category) are CLOSED BY DEFAULT: the slot mounts only while a selection exists and unmounts on deselect. Never render a placeholder rail ('Select a row to see details') — an empty rail is chrome that claims space and implies a selection the user hasn't made. Header anatomy when open: uppercase kicker (what kind of thing is selected) + title + close affordance, then a scrollable body. Never hand-roll the panel with translate-x + backdrop — that's this component. (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
 - [DrawerBody] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
 - [DrawerFooter] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
 - [DrawerHeader] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
+- [DrawerKicker] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
+- [DrawerMeta] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
+- [DrawerSection] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
 - [DrawerTitle] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
 - [Dropdown] — Use a portaled, keyboard-navigable menu anchored to a trigger for row actions, account menus, or any list of commands revealed by a click. [docs](https://ads.actioneer.dev/#/dropdown)
 - [DropdownContent] — component [docs](https://ads.actioneer.dev/#/dropdown)
@@ -354,15 +475,15 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [DropdownSeparator] — component [docs](https://ads.actioneer.dev/#/dropdown)
 - [DropdownTrigger] — component [docs](https://ads.actioneer.dev/#/dropdown)
 - [InlineDrawer] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
-- [Modal] — Use for a blocking, focused task or confirmation that must interrupt the page until resolved (portaled, focus-trapped, Escape/backdrop dismissible). (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
-- [ModalBody] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
-- [ModalClose] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
-- [ModalDescription] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
+- [Modal] — Use for a blocking, focused task or confirmation that must interrupt the page until resolved (portaled, focus-trapped, Escape/backdrop dismissible). (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
+- [ModalBody] — component (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
+- [ModalClose] — component (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
+- [ModalDescription] — component (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
 - [ModalDrawer] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
-- [ModalFooter] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
-- [ModalHeader] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
-- [ModalSection] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
-- [ModalTitle] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
+- [ModalFooter] — component (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
+- [ModalHeader] — component (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
+- [ModalSection] — component (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
+- [ModalTitle] — component (variants: size: sm|md|lg|xl|full; position: center|top; height: fixed|content) [docs](https://ads.actioneer.dev/#/modal)
 - [Popover] — Use Popover for a portaled, dismissible panel anchored to a trigger — quick settings, a profile card, or a short inline form — that closes on outside click or Escape. [docs](https://ads.actioneer.dev/#/popover)
 - [PopoverContent] — component [docs](https://ads.actioneer.dev/#/popover)
 - [PopoverTrigger] — component [docs](https://ads.actioneer.dev/#/popover)
@@ -370,6 +491,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [CommandPaletteItem] — TypeScript type
 - [CommandPaletteProps] — TypeScript type
 - [DrawerProps] — TypeScript type
+- [DrawerSectionProps] — TypeScript type
 - [DropdownContentProps] — TypeScript type
 - [DropdownItemProps] — TypeScript type
 - [DropdownProps] — TypeScript type
@@ -418,7 +540,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [CarouselItem] — component [docs](https://ads.actioneer.dev/#/carousel)
 - [CarouselNext] — component [docs](https://ads.actioneer.dev/#/carousel)
 - [CarouselPrevious] — component [docs](https://ads.actioneer.dev/#/carousel)
-- [Chip] — A compact pill for statuses, tags, or metadata, with an optional leading icon/avatar or a dismiss control. (variants: variant: solid|outline; color: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/chip)
+- [Chip] — A compact pill for statuses, tags, or metadata, with an optional leading icon/avatar or a dismiss control. (variants: variant: solid|outline|plain; color: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/chip)
 - [ClarificationAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
 - [ComboChart] — component [docs](https://ads.actioneer.dev/#/ai/chart)
 - [ComparisonAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
@@ -427,6 +549,8 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [ConnectionStatus] — component [docs](https://ads.actioneer.dev/#/connector-card)
 - [ConnectorCard] — Use ConnectorCard to represent one data source/destination on an integrations screen — identity, connection status, health strip, and a usage/action footer. [docs](https://ads.actioneer.dev/#/connector-card)
 - [DecisionAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
+- [DetailItem] — component [docs](https://ads.actioneer.dev/#/detail-list)
+- [DetailList] — component [docs](https://ads.actioneer.dev/#/detail-list)
 - [EdgeLabelRenderer] — component [docs](https://ads.actioneer.dev/#/infinite-canvas)
 - [EmptyAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
 - [ErrorAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
@@ -454,6 +578,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [RetentionGrid] — component [docs](https://ads.actioneer.dev/#/viz-charts)
 - [ScatterChart] — component [docs](https://ads.actioneer.dev/#/ai/chart)
 - [SeriesChart] — component [docs](https://ads.actioneer.dev/#/viz-charts)
+- [Sparkline] — component [docs](https://ads.actioneer.dev/#/sparkline)
 - [StatusAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
 - [Tab] — component (variants: orientation: horizontal|vertical; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
 - [Table] — Use Table for structured tabular data that may need row selection, column sorting, sticky columns, or a paginated footer — not for simple key-value lists. Every primary body-cell value defaults to text-m (14px / 20px); only clearly secondary metadata inside a cell may opt down to text-s. Give a whole-row action an onClick and aria-label: TableRow then adds hover/focus feedback, a pointer cursor, and Enter/Space activation. The consumer decides whether that action navigates or opens a panel; TableRow owns neither destination. Display-only rows stay static. Single selection uses grouped radio buttons and keeps the chosen row selected; multiple selection uses checkboxes. Selecting or clearing a parent cascades through all descendants, including collapsed rows; partial groups show a mixed checkbox. Selection callbacks include the complete selected key set. Selected row fills fade from full soft-teal tint at the visible left edge to no tint at the right edge, including pinned cells. Use TableRow.childRows for collapsible hierarchies, expanded/defaultExpanded and onExpandedChange for disclosure, and stable rowKey values. Child rows open below their parent without shifting columns; the caret and parent label share one transparent disclosure button, separate from selection, and both turn the primary-action text color on hover. Sorting keeps child rows with their parent. Keep normal row geometry without a brand tint or hover-only corner rounding. Nested controls keep their own actions. Primary record links stay text-only in every state: never reveal an arrow, chevron, or other directional icon only on hover. Persistent row actions use a final sticky-right column plus elevatedActionColumn so one body-column shadow lifts the action surface instead of repeating on individual cells. The empty matching header cell remains transparent and non-sticky. [docs](https://ads.actioneer.dev/#/table)
@@ -510,6 +635,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [ChartAxisDomain] — TypeScript type
 - [ChartColor] — TypeScript type
 - [ChartDatum] — TypeScript type
+- [ChartLegendPlacement] — TypeScript type
 - [ChartTickFormatter] — TypeScript type
 - [ChartTooltipContext] — TypeScript type
 - [ChartTooltipItem] — TypeScript type
@@ -535,6 +661,8 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [ConnectorTint] — TypeScript type
 - [DecisionAnswerProps] — TypeScript type
 - [DecisionAnswerSpec] — TypeScript type
+- [DetailItemProps] — TypeScript type
+- [DetailListProps] — TypeScript type
 - [Edge] — TypeScript type
 - [EdgeProps] — TypeScript type
 - [EdgeTypes] — TypeScript type
@@ -584,6 +712,8 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [SeriesChartProps] — TypeScript type
 - [SortDescriptor] — TypeScript type
 - [SortDirection] — TypeScript type
+- [SparklineColor] — TypeScript type
+- [SparklineProps] — TypeScript type
 - [StatusAnswerProps] — TypeScript type
 - [StatusAnswerSpec] — TypeScript type
 - [TableAnswerProps] — TypeScript type
@@ -698,6 +828,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [SidebarNav] — component [docs](https://ads.actioneer.dev/#/sidebar)
 - [SidebarSection] — component [docs](https://ads.actioneer.dev/#/sidebar)
 - [SidebarTrigger] — component [docs](https://ads.actioneer.dev/#/sidebar)
+- [SidebarWorkspace] — component [docs](https://ads.actioneer.dev/#/sidebar)
 - [BodyPageHeaderProps] — TypeScript type
 - [BreadcrumbItemProps] — TypeScript type
 - [BreadcrumbsProps] — TypeScript type
@@ -712,6 +843,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [SidebarItemProps] — TypeScript type
 - [SidebarProps] — TypeScript type
 - [SidebarSectionProps] — TypeScript type
+- [SidebarWorkspaceProps] — TypeScript type
 - [useSidebar] — React hook
 
 ### Layout