Via brand (locked)

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

Brand as text — the -ink tokens

A brand FILL and brand TEXT are different jobs with different floors. Neither new brand value clears 4.5:1 as text (#F72684 is 3.77:1 on surface, #026FFF is 4.45:1), so text uses the darkened -ink token instead. The ink is DERIVED from the Client value with color-mix, not replaced by a Via literal, so it still follows a whitelabel override. Primary needs no ink in light — #1C0B41 is 17.89:1 as text.

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. All three published ratios below were wrong (recomputed 2026-08-20, sRGB relative luminance) — Global was wrong in the DANGEROUS direction, claiming 4.65:1 (a pass) for a real 3.56:1 (a fail); Travel and Courses were wrong the safe way, claiming 4.55:1 / 5.40:1 for real 5.47:1 / 5.70:1. Global renders fill only, with no text drawn on the raw hue, until the product-accent display/text-safe pairing exists (a later Global Design Convergence slice — see unsafe-token-pairings.test.ts); Travel and Courses keep their white-text pairing because it genuinely clears AA today.

Semantic (locked to Via)

Status meaning is consistent across all Clients — not whitelabeled. The 2026-08-11 design supplies a Foreground and a Background per meaning, and both halves are tokens now. Each foreground does double duty: it is the solid fill (carrying white) AND the ink on its own background.

Naming: the design calls the amber meaning “Attention”. The token family stays warning (Gary’s ruling, 2026-08-11) — renaming a family used across five packages is churn with no user-visible payoff. Read the design’s Attention row as this page’s warning row.

Semantic — foreground / solid fill

The design's Foreground column. Also the -ink token: --color-danger-ink and friends now resolve to these same values, replacing the stepped-down amber-800 / green-800 the old saturated fills needed.

Semantic — background (new)

The design's Background column, as real tokens (bg-success-surface, …). These REPLACE the /10 and /15 opacity tints Phoenix synthesised: an opacity tint composites over whatever sits behind it, so the same class produced a different colour on canvas, on surface-2 and inside a dialog — and none of them was the colour the design specified. Each card below is the surface carrying its own ink.

Why two values

Product named two blues, and they are a fill / ink pair — the same split the severity roles already use (--color-warning vs --color-warning-ink). The lighter value measures 4.45:1 on white: above the 3:1 floor for non-text, below the 4.5:1 floor for text. So it is the non-text value, and the darker 5.12:1 value is the text value. Getting this backwards is what shipped a serious axe violation on every validation message in the product (§15).

Measured contrast

Measured in Chromium against the surfaces each value actually sits on — not computed from a unit test, which cannot see Tailwind.

Measured contrast

A stage dot is a non-text indicator, so the floor is WCAG 2.2 SC 1.4.11’s 3:1 against the adjacent surface — not 4.5:1. Measured in Chromium against --color-surface: light 5.70 / 3.56 / 5.02 / 4.60 / 4.01, dark 5.56 / 6.69 / 8.68 / 5.71 / 7.11. These lighten on dark unlike the severity fills, because they sit on a surface rather than carrying their own foreground — #15803D on #17151E is ~2.2:1. (That green is --via-color-lifecycle-active, which the 2026-08-11 palette did not touch — lifecycle identity is its own namespace, deliberately not the severity roles.)

Turned off keeps its identity

A turned-off Stage keeps its hue and changes shape — filled becomes a ring (the second dot in each row above). Dropping it to a neutral grey would make its identity ambiguous with closed, whose identity grey genuinely is; and subduing it with opacity-* multiplies contrast against whatever is behind it, so a compliant token stops being compliant the moment it is applied (§8.1 / SC 1.4.3).

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. Every tone now takes its own tinted fill (Global Design Convergence ruling D2, Krystle 2026-08-20 — activated 2026-08-21 once the tone-mapping audit the ruling made a precondition was complete). Colour is always a redundant signal: the text label carries the meaning in every tone, which is what keeps the badge usable for colour-blind readers, in monochrome print, and in forced-colors mode. The design (Global Component library.pdf, p1) organizes Badge into five tiers, shown below in the design's own order and using its own captions.

ProgressBar

A status output (role="progressbar"), never a control. Determinate reports known progress (0–100, clamped) and exposes aria-valuenow. Indeterminate reports work of unknown duration and omits aria-valuenow — no fabricated percentage. First consumer: the ImageField upload lifecycle.

ImageDropzone

A domain-blind image acquisition surface. One real <button> — click, Enter/Space, drag & drop, or paste (while focused) — that emits a candidate File and typed validation outcomes (unsupported-type, file-too-large, multiple-files, empty-file). It owns no preview, upload, or persistence — those belong to ImageField later. Supported formats and the size cap come from the shared ingest policy (PNG, JPEG, or WebP · up to 10 MB) and are shown in the surface. Try the live examples below; nothing uploads.

ImageEditor

A domain-blind crop / zoom / rotate / reframe editor wrapping react-easy-crop (6.x, MIT) behind the Phoenix API. Desktop in a Dialog, mobile in a full-height Drawer (fixed header, scrollable body, sticky footer); presentation="auto" picks by viewport. It returns edit instructions on Apply — no canvas runs during interaction; the consumer prepares the Blob later via prepareEditedImage.

ImagePreserveEditor

The "preserve" sibling to ImageEditor above: where ImageEditor frames an image (crop/zoom/aspect to a target shape), this surface preserves it — the whole asset stays at its natural geometry, and the job is confidence, not composition. Preview the original on a transparency checkerboard (so alpha is visible), rotate if it isn't upright, and commit. There's deliberately no crop, no zoom, and no aspect selector. It is domain-blind and returns the same ImageEdit contract ImageEditor does. In the real product it never mounts standalone — ImageField mounts it internally for a preserve-intent ImagePurpose (see the "Preserve surface" example under ImageField below, which exercises the full upload path). The demos here open the editor directly against a fixed demo asset instead, so the surface is reviewable without an upload step.

ImagePreview

A domain-blind, non-interactive image preview — managed, external, or blob: URLs — that preserves aspect ratio and degrades gracefully when an image is broken. A pure renderer: it owns no object URLs (ImageField does) and knows nothing about storage.

Image

Renders any URL with its alt text.

Aspect-ratio frame

Constrain the frame to a consumer-defined ratio; the image fits inside.

Broken-image fallback

On load failure it shows a placeholder and keeps the accessible name — never a broken-image glyph.

ImageField — the One Media Experience

The domain-blind composition of the image primitives — the full lifecycle: acquire → edit → prepare → upload → process → commit → change → remove → undo. Optimistic presentation, conservative persistence: the edited image appears immediately marked “Saving…”, and is only “Saved” once the backend confirms. Normal product code passes an ImagePurpose (Avatar / Preserve below) so the consumer declares an image’s role and ImageField resolves the editing surface, geometry, output, and destination preview — it does not hand-wire aspect ratios. The raw primitives example is retained only for platform work. The transports below are fakes — nothing is persisted.

The demos below cover the complete workflow end to end: one Add entry + source chooser, Image URL staged review (nothing commits until “Use image”), a committed managed image that is itself the Edit affordance (Edit primary · Change · quiet destructive Remove — never three equal peers), a committed external image that explains why Edit is unavailable, loading / pending and error → retry states, deliberate Remove (confirmation, never a one-click delete), and Frame / Preserve purposes. On narrow screens the secondary Change + Remove fold into a “More actions” menu while Edit stays visible — resize this page below 768px to see it. Verbs are consistent throughout: Add image · Edit image · Change image · Remove · Use image.

Deliberate removal — confirmation

Remove never happens from one click: it opens a confirmation (Cancel returns the current image unchanged; the destructive action runs the existing remove transport, shows a pending state, and clears the image only on success). Undo appears afterwards when the consumer supplies restore.

Brand image

Remove asks for confirmation first.

Edit

Edit brand imageChange brand imageRemove brand image

Uploaded · PNG

Remove brand image?

This removes the current image. You can add another image at any time.

Removal failure → retry (external image)

On an externally hosted image (same confirmation as a managed one): the first confirmation fails, keeping the image visible with an actionable error; retry succeeds. No Undo — the confirmation is the protection.

Linked image

First removal fails; retry succeeds.

External URL

This image is hosted elsewhere. Change it to an uploaded image to edit it in Phoenix.

Change linked imageRemove linked image

Add image

Image URL

Enter a link to an image online.

Remove linked image?

This removes the current image. You can add another image at any time.

ChooseImageDialog — the unified image picker

The one source-neutral picker, built to the frozen Design Lab prototype (docs/product/image-platform/design-lab-prototype.md). Four sources in a deliberate hierarchy: Your media and Stock photos are places you browse, so they are tabs; Upload is an action, so it is a button; Image URL is the rarest and weakest path, so it is a quiet link to its own focused step. A four-item rail gave a once-a-quarter task the same weight as the library you open daily.

Choosing never commits. Clicking a result — or pressing Enter on it — opens a staged review; only Apply commits, and that guarantee is structural rather than remembered: no source panel is given onApply, so there is no path from a panel to a commit. The component fetches nothing — the consumer supplies loadLibrary and searchStock, the same seam SubjectPicker's onSearch uses, so no shared component acquires a tenant-scoped read of its own. Stock searches only on an explicit search: the provider quota is small and a search-on-open burned it before the author had typed.

Upload is now offered by every image slot, and the dialog owns the transport (uploadImage, 2026-08-04). Bytes go up when the file is chosen — not at Apply — so the review step shows what was actually stored, an uploaded picture reaches the consumer already shaped like a library pick, and GalleryComposer's toItemImage stays synchronous. One consequence worth knowing: cancelling after choosing a file discards the choice, but the bytes are already stored as an unreferenced object, which is exactly what the Asset Platform's reaper collects. Without an uploadImage the Upload control is not rendered at all, even for a slot whose profile offers the source — a control that provably does nothing is worse than an absent one.

Nothing applied yet. Choosing a result opens review; only Apply commits.

GalleryComposer — membership, order and primary

The one gallery surface, built to the frozen design (docs/product/image-platform/gallery-decisions.md). It owns the collection — membership, order, an explicit primary, capacity, per-item description and per-item removal. It opens ChooseImageDialog's multi-select mode to add and AdjustImageDialog to frame, and owns neither. Production fuses all three into one ~400-line component, duplicated for Experience and Activity.

It never interprets custody. The origin word is a lookup shared with the editor, credit renders because the item carries credit rather than because of what kind of image it is, and the picker's source list comes straight off the placement profile — so there is no if (custody === …) here and a fourth custody is not a change to this component.

No changes yet. Every change reports WHAT changed, so a consumer can persist one row rather than diffing two collections.

Image framing — FocalPointField + AdjustImageDialog

“Choose what stays in frame.” The author marks a point on the picture; every surface that crops the image honours it as CSS object-position over object-fit: cover. That is the whole mechanism — one declaration, no pixels, nothing decoded or re-encoded — which is exactly why it works for a stock photo Phoenix must never touch, and why one value survives every breakpoint. The derivation is focalPointObjectPosition in @viatrm/validation, shared by the brochure hero, the marketplace card, the admin thumbnails and the previews below.

The control set is derived, never chosen. presentationControlsFor(profile, custody) intersects what the placement can use with what the custody permits. A provider or external image therefore gets a shorter editor, not a disabled one: no greyed-out control advertises something that will never happen, and one sentence says why the set is short. Byte adjustments (crop / zoom / rotate / straighten) need re-encoding and are absent here for every custody until the ingest path exists.

Accessibility, stated honestly. Three routes reach the same value: click or drag, arrow keys (2%, 10% with Shift, Home to centre), and nine named presets. A 2D value has no correct ARIA role — slider is one-dimensional and application suppresses the reading cursor — so the marker is a real <button> whose accessible name carries the live position in words as well as percentages, with one polite live region on the dialog. Placing a point on a photograph is a visual judgement; the presets are the route that works without sight, and we do not claim parity.

FocalPointField, with the derived CSS beside it

Move the marker by pointer, arrow keys or preset. The two frames to the right are the same image at the widest and tallest crops the cover actually ships in — they are the outcome, not a drawing of it.

Click the picture, drag the marker, or use the arrow keys. Whatever you mark here stays in view as the image is cropped for different screens.

Or choose a position

Top left•Top•Top right•Left•Centre•Right•Bottom left•Bottom•Bottom right•

21:9 — the widest crop

4:3 — the tallest crop

object-position: 50.0% 50.0%

Last announcement: —

The crop guides, and saying when framing cannot reach. object-position only moves a picture on an axis where the picture overflows the frame, so a destination sharing the photo’s proportions cannot move at all. Measured in Chromium against a 3:2 source — which is every photo in the curated stock set (1200×800) — the 21:9 hero responds vertically, the 4:3 phone hero horizontally, and the 3:2 Browse card not at all. Each destination’s crop is now outlined on the photograph itself, so a move changes something under the cursor rather than in a list below the fold, and one sentence names the destinations the photo already fills exactly. Nothing is disabled: an axis inert at one destination is frequently live at another. The outlines are aria-hidden decoration — every fact they carry is repeated as words in the legend beneath them, which is not.

ImageAttribution

The ONE renderer for Unsplash-style "Photo by X on Unsplash" credit — Unsplash's guidelines require it wherever a credited photo is displayed. Renders a real <a href> for the photographer's name only when creditUrl parses as an absolute http(s) URL; any other scheme (or a missing value) renders the name as plain text instead — the render-side half of the write-side scheme defence. The "on Unsplash" link is a fixed Phoenix constant and always renders. Never truncates — the text wraps rather than clipping the provider half of the credit.

Notice

The shared inline message. StatusCard is a metric tile and ConsequenceCard states the consequence of a pending destructive action — neither is an inline message, and that absence is why production hand-rolls bordered alert blocks with raw amber-* / bg-danger/5 literals in a dozen places. Tone is reinforcement only: every notice carries a title in words, and there is no icon-only form.

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.

PhoenixSelect

Phoenix's canonical dropdown — everywhere else in this file, and everywhere in Admin and Portal, a select control should be this, not a native <select>. A WAI-ARIA select-only combobox styled to match TextInput exactly (same border, surface, height, focus ring), because the browser's native option-list chrome doesn't follow the product's dark mode.

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.

RichText

The single read-only renderer for sanitized rich-text HTML — used by the Experience brochure fields and Activity descriptions so the admin preview and the participant view share one content path. Content is authored with the TipTap editor (Activities + Studio). RichText sanitizes on render against the shared allowlist (@viatrm/validation — bold, italic, links, lists, H2/H3, blockquote only), and the API sanitizes again on write. Inherits font size and color from the wrapper, so each field keeps its own typography via className.

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.

ShortTextQuestion

The short_text question type. Composes FormField + TextInput — single-line, value_type: text.

ParagraphQuestion

The paragraph question type. Composes FormField + Textarea — multi-line, same value_type: text as short_text.

QuestionFieldset

The shared <fieldset><legend> layout behind every GROUP-style question widget below (MultipleChoiceQuestion, CheckboxQuestion, RatingQuestion, FileUploadQuestion, SignatureQuestion) — the group counterpart to FormField's single-<label htmlFor> wiring. It owns the legend, the required marker, and help/error text wired via aria-describedby on the fieldset itself — announced once per group rather than once per option. It takes a render prop and is deliberately option-row-agnostic; every widget below supplies its own row visuals (radios, checkboxes, a disabled card). This section demos the primitive alone, with plain rows, so the disabled/read-only distinction below isn't tangled up with any one consumer's styling.

MultipleChoiceQuestion

The multiple_choice question type — single-select. value_type: single_option_ref; the answer stores the option id, never its label, so relabeling an option never rewrites history. A <fieldset><legend> groups native radios — the same pattern already used by the login role picker — rather than FormField's single-<label htmlFor> wiring, which fits one control, not a group.

CheckboxQuestion

The checkbox question type — multi-select. value_type: multi_option_ref, modelled as one answer with N selected option ids. Composes the Checkbox primitive per option inside the same fieldset/legend group as MultipleChoiceQuestion. Not to be confused with the single Checkbox primitive above (a yes/no control) — this is a group of checkboxes answering one question.

DropdownQuestion

The dropdown question type — same value_type: single_option_ref shape as multiple_choice, different widget. Composes PhoenixSelect (CLAUDE.md §7.10) — never a native <select>.

RatingQuestion

The rating question type — value_type: number, a numeric-scale variant. Two display variants, both a fieldset/legend group of native radios (min/max inclusive, defaults to 1–5): Stars (the default — a visually-hidden radio per star, filled 1..value, each with its own "N star(s)" accessible name) and Numbers, which keeps the radio control visible rather than hiding it behind a custom "button" skin — same rationale as Checkbox: the native control is accessible by default.

DateQuestion

The date question type — value_type: date. Composes FormField + TextInput type="date" — the platform-native date picker, keyboard-operable and screen-reader-supported without a custom calendar widget.

FileUploadQuestion Authoring stub

The file_upload question type — value_type: asset_ref. Studio-only: a disabled, non-interactive "available soon" card via QuestionFieldset. Real participant upload is DEFERRED/escalation-gated (Governed-tier threat-model G-4, CLAUDE.md §15) — this component must never grow a value/onChange/upload prop.

SignatureQuestion Authoring stub

The signature question type — value_type: signature_ref. Same Studio-only inert-card posture as FileUploadQuestion above. Real signature capture — and storing the drawn signature's content at all — is DEFERRED/escalation-gated (Governed-tier threat-model G-3: biometric-in-immutable-plane, Product ruling owed).

Uncontrolled preview (Form Studio's mode)

No values/onChange passed — every widget is genuinely interactive against local, uncommitted state. applyConditionalVisibility={false} mirrors Studio's own posture: it never live-hides a question.

Disabled (the participant fill surface's mode)

Bound to saved values but read-only — nothing is editable yet (autosave is a later slice). Conditional visibility is ON by default: the follow-up question shows because the bound campus answer is 'rome'.

Read-only (admin's response review mode)

Genuinely non-interactive, like Disabled above — but each widget renders at full contrast instead of the dimmed disabled look (a11y contrast fix). Admin's Forms response drawer uses this mode; the unanswered 'Rome trip plans' question shows a muted 'Not answered' line instead of a blank box.

Conditional visibility

Toggling the campus answer re-runs the shared evaluateConditional (@viatrm/validation) — the follow-up placement appears only once 'Rome' is chosen, matching the participant runtime's real behavior.

Every block kind (desktop)

Heading, rich text, the two-up Experience card grid (one with a cover image, one without — no placeholder block, just a tighter card), an Activities list drawn as rows with a calendar mark, a divider, and a button. The undated activity renders no date line at all rather than a 'Dates TBD' placeholder, and the unpublished one is marked in words — a recipient could not open it. 'Learn more →' is styled TEXT, not a link: there is no public marketplace, and the portal is behind auth, so a real href would send a student to a login wall.

Via University

Applications for spring are open Two weeks to apply — here is what is on offer Somewhere new next spring Applications for spring placements are open until 15 August. Pick a destination, talk to an advisor, and get your paperwork started. Featured experiences Rome Study Abroad 2 Sep 2026 – 12 Dec 2026 Learn more → Tokyo Design Intensive 11 Jan 2027 – 19 Mar 2027 Learn more → Come and ask questions 📅 Study abroad fair 14 Aug 2026 10:00 · Student Union, Main Hall 📅 Advisor drop-in (not yet published) Not visible to participants — a recipient could not open this. Start an application

Via University You are receiving this because you have an account. Every message will include a way to unsubscribe.

Mobile width

The same content in the narrow single-column reading. Narrower, never lossier: a device toggle must not become a second, more forgetful renderer.

Via University

Applications for spring are open Two weeks to apply — here is what is on offer Somewhere new next spring Applications for spring placements are open until 15 August. Pick a destination, talk to an advisor, and get your paperwork started. Featured experiences Rome Study Abroad 2 Sep 2026 – 12 Dec 2026 Learn more → Tokyo Design Intensive 11 Jan 2027 – 19 Mar 2027 Learn more → Come and ask questions 📅 Study abroad fair 14 Aug 2026 10:00 · Student Union, Main Hall 📅 Advisor drop-in (not yet published) Not visible to participants — a recipient could not open this. Start an application

Via University You are receiving this because you have an account. Every message will include a way to unsubscribe.

A brand-new campaign

No subject and no blocks yet. The subject slot says 'No subject line yet' as an explicit placeholder rather than rendering an empty heading, and the empty-body copy is supplied by the CONSUMER — what to do next differs between the builder (which points at its own block picker) and the send path (which would never render an empty body at all).

With the consumer's device toggle

The chrome the Campaign builder's preview pane wraps the renderer in — a radiogroup, because these are two mutually exclusive readings of one thing. The toggle lives in the consumer, not the package.

Preview width

desktopmobile

Via University

Applications for spring are open Two weeks to apply — here is what is on offer Somewhere new next spring Applications for spring placements are open until 15 August. Pick a destination, talk to an advisor, and get your paperwork started. Featured experiences Rome Study Abroad 2 Sep 2026 – 12 Dec 2026 Learn more → Tokyo Design Intensive 11 Jan 2027 – 19 Mar 2027 Learn more → Come and ask questions 📅 Study abroad fair 14 Aug 2026 10:00 · Student Union, Main Hall 📅 Advisor drop-in (not yet published) Not visible to participants — a recipient could not open this. Start an application

Via University You are receiving this because you have an account. Every message will include a way to unsubscribe.

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.

Browse filtering (SearchField · PhoenixSelect · ClearFiltersButton)

The canonical filtering row for browse/discovery surfaces — card grids the user scans and explores, as opposed to the dense data tables above. One wrapping row: SearchField, one PhoenixSelect per filter dimension, a ClearFiltersButton when anything's active, then Sort + a result count pushed right via ml-auto. Active filters (when tracked as removable, as opposed to the toggles shown here) surface below via FilterBar/FilterChip. This is the same row every browse page should use — Admin Activities' Browse view and Portal's Experiences marketplace both compose it this way.

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”.

Card — a discrete bounded content object

One spec (24px padding, 16px radius, subtle hairline, ink-tinted shadow) plus one compact role. Is the thing inside the box the point? That is a Card. A neutral Card is valid — an accent is never what qualifies something as one.

Container — structural grouping chrome

Is the box the point — it groups, it lays out, it is chrome? That is a Container. Elevation and padding are now orthogonal props; the old variant still works unchanged and is deprecated.

ContainerHeader / ContainerFooter

Extracted from 12 bespoke implementations. The footer's contract: the hint takes the flexible space and wraps to its own line, and the actions hold the trailing edge at every width. Neither owns a heading level or any domain copy.

Row / List / ListFoot

Selection, unread, hover and activation are four separate concerns, never one boolean — the selection prop names the ARIA claim it makes, and an inert row cannot take an onClick at the type level. Dividers sit on the top of every item after the first, which is what lets the disclosure footer never leave a dangling rule.

Tabs — in-page view switching only

Peer views of one section, exactly one selected. No href and panels are required, so navigation and wizard progress are inexpressible rather than merely discouraged.

Avatar

Identity presentation, and no identity semantics — the accent is a boolean precisely so it can never encode a role or a permission.

Skeleton

Product's artifact specifies no loading state at all; Phoenix stays the authority. Shapes are aria-hidden scaffolding and the announcement lives on SkeletonGroup, whose label is required — a skeleton must never invent what is loading.

StatTile — a measured zero is not an unmeasurable metric

The figure is a discriminated union, so the confident zero Phoenix has shipped twice is unrepresentable rather than discouraged. Unavailable renders no 0 and no bare dash — it renders a marker and the reason, in words.

Button — asChild

Added before any Button restyle, so the 14 files that hand-copy the primary-button class string onto a link have somewhere to go instead of drifting.

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

DeviceToggle + PreviewThemeToggle

Desktop is fluid; Tablet/Mobile frame the canvas to a fixed max-width (DEVICE_W). The theme toggle re-resolves every --color-* token inside the framed canvas via a nested data-theme island, independent of this page's own theme or the Studio chrome's theme.