Via brand (locked)

Cascade source. Override at the Client layer; never edit directly.

Client overrides (default to Via)

Per-Client whitelabel surface — primary, secondary, tertiary, and their foregrounds. Currently rendering the Via fallback because no Client overrides are loaded. Per-tenant inline <style> at runtime is Phase 2.

Product accents (brand-locked)

Per-product-line accent for visual identity inside a Client-themed shell. International and Contracts are out of scope per §3.5.4.

Semantic (locked to Via)

Status meaning is consistent across all Clients — not whitelabeled.

Font families

Type scale

Tailwind v4 defaults applied to font-display for headings and font-sans for body. Final scale is for UI/UX to refine.

Page

Outermost wrapper for every route. Renders as <main> so each page has exactly one main landmark. Four widths gate the readable-line-length problem on wide screens while still letting dense surfaces own the viewport.

PageHeader

The top of an index/list page. Always carries the page's single h1. The actions cluster reflows below the title on narrow viewports — the title is never truncated to make room for buttons.

Section

Labelled region inside a Page. Always renders <section aria-labelledby>; the heading level is configurable so nested sections build a meaningful h1 → h2 → h3 outline.

Stack

Vertical flex with a discrete spacing scale. Use Stack instead of ad-hoc space-y-* — the scale is the rhythm of the product.

Inline

Horizontal flex with the same spacing scale as Stack. Wraps by default so dense rows of chips, metadata, and actions reflow gracefully at 320px.

Container

A bordered surface for grouping operational content. Deliberately not called "Card" — operational UI uses surfaces for structure, not for marketing-style content cards.

EmptyState

What fills a list, table, or section when there is no data yet. Operational empty states describe the gap and offer the next step — they are not marketing slots.

SplitLayout

Main working surface + secondary <aside> for status, metadata, owners. Stacks below the main column on viewports under lg (1024px). DOM order is always main → aside, so the working content reads first.

SidebarLayout

App-shell layout with a persistent left navigation. Desktop (lg+) shows the sidebar inline; mobile collapses it behind a toggle that opens an overlay drawer scoped to the layout's bounds.

DetailHeader

Top of an entity detail page (one Experience, one Session, one Participant). Sibling to PageHeader; a page uses exactly one of the two.

Composition: Experience detail page

How the primitives compose into a realistic Phoenix workflow screen. Page → DetailHeader → SplitLayout → Section / Container / Stack / Inline.

Button

Primary action element. Real <button>; never <div onClick>. Defaults to type="button" so it doesn't accidentally submit a form.

Badge

Inline label for status, category, or count. One subtle pill style — color is always a redundant signal alongside the label, so the badge stays usable for color-blind readers and in forced-colors mode. Use a leading dot for at-a-glance scanning in lists.

FormField · FieldLabel · FieldDescription · FieldError

The unit of one labelled control. FormField generates stable IDs and exposes them through context; FieldLabel, FieldDescription, FieldError, and the inputs all read from it. Two layouts: stack (default — label above input) and inline (Checkbox / Switch).

TextInput

Single-line input. Native type is honored — text, email, number, tel, url, password, date — so the browser keyboard and validation behave correctly per-platform.

Textarea

Multi-line input. Same border, focus, and state styling as TextInput. Vertical-only resize so users can grow the field for long content (advisor notes, submission review). rows controls the initial height.

Checkbox

Native <input type="checkbox"> with accent-primary styling — fully accessible by default (keyboard, screen reader, magnifier, forced-colors). Always compose with FormField layout="inline" so the FieldLabel wraps the touch zone via htmlFor.

Switch

Binary on/off control. Implemented as a native checkbox with role="switch" — modern screen readers announce it as a switch (on/off) rather than checked/unchecked. Use a Switch for instant-effect settings (toggle a feature); use a Checkbox for choices that are committed on form submit.

Composition: Create Session

A realistic admin workflow composed from the existing layout primitives plus the new form primitives. PageHeader → SplitLayout → Section / Container / Stack → FormField + inputs. Form actions sit in a sticky footer-style row at the bottom of the form column.

DataTable · TableHeader · TableRow · TableCell

Native semantics first. Header cells use scope="col"; cells inherit text-sm with neutral-700 body text; the scrollable container is the only wrapper DataTable adds.

Selection · Indeterminate · BulkActionBar

Selection is a composition of an existing primitive (Checkbox) inside the leftmost cell of each row plus a "select all" checkbox in the header. The header checkbox supports indeterminate when some rows are selected. The BulkActionBar appears between the toolbar and the table once at least one row is selected.

SortableHeader

A <th> with a button inside. The button is the keyboard target; the <th> carries aria-sort (ascending / descending / none) so AT users can detect the sort direction without seeing the chevron.

ActionsMenu

The kebab-button popover used for per-row actions. Always provide a per-row accessible label ("Actions for {row name}") so AT users can disambiguate identical triggers across rows.

TableToolbar · TableSearch

The toolbar slot above the table. Left cluster typically holds search and filter triggers; right cluster holds the primary action. Wraps below 640px so all controls stay reachable at 320px.

FilterBar · FilterChip

The row of active filters between the toolbar and the table. Each chip is one applied filter; clicking the chip removes the filter. The whole chip is the click target — there is no separate × tap zone.

Pagination

Operational prev/next pattern with a position indicator ("Showing 1–25 of 184"). Page-number lists are deferred until a real Phoenix workflow needs them (deep links, saved views).

EmptyState · LoadingState

Empty states reuse the existing EmptyState primitive inside a single <td colSpan> row. Loading states render skeleton bars in place of cell content via LoadingRow, with aria-busy="true" on the DataTable so AT users know the data is refreshing.

Responsive · narrow · stacked alternative

At 320px, the table's scrollable container keeps it usable as a horizontal-scroll surface. For lists that are mobile-critical (participant's own dashboard, traveler portal), render a stacked Container list at narrow widths instead. Same data, different affordance.

Composition: Experiences management

Toolbar with search + add filter + new experience; one active filter chip; selection with bulk archive/export; sortable Name and Updated; per-row actions; pagination. Column priorities reduce density from lg to sm.

Composition: Submission review queue

The reviewer's daily working surface. Same primitives, different shape — a single status filter is pre-applied; bulk actions are approve / request changes / assign reviewer; the "all caught up" empty state replaces the row list when no rows match.

Dialog

Surface 4. Modal blocking dialog built on the native <dialog> element. The browser handles focus trap, Esc-to-close, focus return, and inert background. Backdrop click closes via the click-on-dialog-element pattern. Use for decisions that must be answered before continuing — confirmations, short forms, important questions.

Drawer

Surface 4. Same native <dialog> foundation as Dialog, anchored to the right (or left) viewport edge. Use a Drawer when the user needs to inspect or edit something without losing context — the Submission review queue + its detail view is the canonical case.

DropdownMenu

Surface 3. Labelled menu button — for toolbar menus, view-options, bulk-action groupings. Pair with ActionsMenu when you need a kebab affordance (row-level actions), and with Popover when the content is richer than a list of items.

Popover

Surface 3. Non-modal floating surface for richer content — filter builders, inline edits, picker-style choices. For action lists prefer DropdownMenu; for ephemeral hints prefer Tooltip.

Tooltip

Surface 3. Ephemeral hint that appears on hover and on focus — CLAUDE.md §8 forbids hover-only reveals. Use Tooltip only for short, non-essential clarification; never put critical information here.

Toast

Surface 3 (z-50). Transient confirmation anchored to the bottom-right of the viewport. Wrap your app shell in <ToastProvider> and call useToast().push(...) from anywhere downstream.

CommandPalette

Surface 4. Keyboard-first quick launcher — minimal v1. Substring search, grouped listing, arrow-key navigation, Enter to activate. Open with Cmd/Ctrl+K via the useCommandShortcut hook in your app shell.

Composition: Experience management workflow

Row ActionsMenu → destructive Dialog (Surface 5) → success Toast with Undo. The whole flow stays in one keyboard journey: Tab to the row, Enter on the kebab, ↓ to Archive…, Enter to open the confirmation, Tab to Archive, Enter to confirm. Focus returns to the row when the toast appears.

Composition: Submission review workflow

Filter Popover (Surface 3) → click a row → Drawer (Surface 4) with contextual actions (Approve / Request changes / Close). Approve fires a success Toast; Request changes fires a warning. The Drawer keeps the queue in view on desktop, full-screens on mobile.

KeyboardScope + KeyboardCheatsheet

Stack-based keyboard shortcut system. Wrap the app once in <KeyboardScopeProvider>, then mount <KeyboardScope> wherever a workspace, row, or overlay needs its own keys. The deepest scope in the render tree wins for nested cases; siblings at the same depth resolve by mount order — so opening a modal automatically intercepts shared keys without explicit wiring. Drop a single <KeyboardCheatsheet /> nearby and ? becomes a self-documenting help surface.

SplitView

Resizable two-pane layout with three modes (split, primary-only, secondary-only). Slot-based — pass <SplitView.Primary> and <SplitView.Secondary> as direct children. Mode and ratio are controlled-or-uncontrolled; persistence is the consumer's responsibility (a server-backed user-preferences slice lands in Phase 2 of the Worklist plan). The drag mechanics and ARIA separator come from react-resizable-panels; the snap/reset keybindings (Enter, Esc, Home, End) and the mode wrapping are ours.

WorklistTable

Virtualized ARIA grid for high-frequency operational lists. Built as a div-based role="grid" because virtualizing native <tr> breaks the layout flow that screen readers expect; the WAI-ARIA grid pattern is the accepted accessible alternative for this case. Fully controlled — focus, selection, sort, and density flow from props; the table doesn't own workspace state and doesn't register global keyboard listeners. Wire j / k / x / etc. via a <KeyboardScope> at the consumer, and call the table's imperative scrollToRow(id) when the focused row leaves the viewport.

ConsequenceCard — hero emphasis (the lead concern)

Filled, prominent. One per severity. The action is the single interactive element.

ConsequenceCard — compact emphasis (the watch list)

A colored left accent + the severity word; neutral body. Used in “Also worth your attention”.

OutcomeGauge — the cockpit instrument

One gauge, one truth: current vs. target. Severity tints the fill, but the count is always text — colour is never the only signal. Uncapped targets show the count with no bar.

OutcomeMovement — is this getting better or worse?

A read-only instrument: a plain-language direction (word + glyph + colour, never colour alone), the net change, and a short count log — oldest→newest, current emphasised. No chart, no sparkline, no forecast.

AudienceGapSummary — who sits inside the gap

Identification only: expected / registered / missing, led by the gap, plus a representative sample of opaque (PII-free) handles and a “+N more” remainder. No table, no checkboxes, no actions. The all-registered state reads honestly.

RecommendedActionCard — what is the move?

Modeling + presentation only: the recommended move, its reason, the expected outcome impact, and the availability state. No button, no disabled button, no “Send” — when a move can’t run yet, the card says so in plain text.

OverviewBackground — atmosphere by tone

The recessive atmospheric layer behind the Home. Shown here are the gradient fallbacks (calm / active / critical) used until art-directed photographs are configured; a scrim keeps content AA over any image. Decorative, static, never competes with content.

OverviewShell — the Home scaffold

Greeting → verdict (the page’s h1) → lead concern → “also worth your attention” → calm-remainder footer. Layout only; the page fills the slots.

StatusCard — Phoenix status card

Vertical status card with a spine, origin dot, and atmospheric gradient. Color is tone-mapped to danger / warning / info / neutral — but the signal is always carried in pillLabel and statusText too (color is never the sole indicator). Cards with a count of 0 receive active=false — muted opacity, no tone color. First implementation: Activities Needs Attention.

Active state — four tones

Inactive state — count zero