Skip to content

Latest commit

 

History

History
1363 lines (1200 loc) · 101 KB

DESIGN.md

File metadata and controls

1363 lines (1200 loc) · 101 KB

Hub Design System

How the Hub looks and behaves, written as reusable decisions: principles, tokens, the shared components that encode them, UX patterns, and recipes for recurring page shapes.

How to use this file. Read §1 and the §5 component index, then jump to the pattern or recipe your task matches. Detail that only matters to one surface lives next to its code (§8) — follow the link when you touch that code, not before.

How to extend it. When you settle a new question (§1 "Deciding"), write the answer back as a general rule in the pattern or recipe it belongs to, in the same change. Do not add a section per feature; add a reference implementation to an existing recipe instead. Implementation detail (pixel values, retry counts, vendor quirks) goes in code comments or a README beside the component.

This is an evolving document. Every rule here records the current decision and the reason for it, not a law. When a real case shows a rule no longer fits, change the rule in the same change as the code, and keep the reason. Don't work around it locally, and don't leave the old wording behind. The new rule must still be general and keep §1's principles. Absolute wording ("never", "only") means "not without changing this file first".


1. Principles

North star — "The Digital Curator". Data is presented as curated editorial content: calm, spacious, precise. Boundaries come from tonal surfaces and white space, not lines. Built on shadcn/ui + Tailwind CSS.

  1. The page serves its reader's task. A review page optimises for scanning and comparison (values aligned in one column, keys visible, exceptions summarised at the top). An action page makes the action unmistakable.
  2. One vocabulary per concept, encoded in one component. Status, file type, table chrome, locale, copy affordance — the same idea appears in a table cell, a panel header and a review step. Three local copies drift into three shapes, so reach for the §5 component; if none exists and the idea recurs, create one and index it.
  3. Tokens, never palette steps. Everything must work in light and dark from app/globals.css.
  4. Tone carries meaning; decoration does not. Colour is reserved for status. Icons mark sections and kinds of things, not individual fields.
  5. Prefer removing over adding. Most inconsistency is accumulated decoration — an icon on one badge, a tooltip on one label. Cutting it is almost always more on-brand than harmonising it.
  6. Chrome is borrowed space. Navigation, titles and descriptions take the reader's working area on every visit. Put moving around in the header and menus, not in rows of the page; say each thing once (a title the trail already says, a description the title already says, two links to one page are all noise).

Deciding a question this file does not answer — in this order, then write it back:

  1. Does a sibling page already solve it? Match it. Cross-page consistency beats a locally nicer idea.
  2. Does a token or shared component cover it? Use it. If a semantic token lacks a Tailwind utility, register it (§2) rather than hardcoding a palette step.
  3. What is the page for? Principle 1.
  4. Can you remove something instead? Principle 5.
  5. Working from a mockup or a reference app? Adopt the idea, not the layout. Keep every rule here unless the case shows the rule no longer fits — then change the rule (top of this file). Example: the audience mockup's "Properties" button opened a panel whose rows opened panels; that stacks overlays, so properties became a view of the page instead (§6 Navigation).
  6. Look at it in the running app before calling it done (§7, last items). Screenshots catch what types and tests do not: a stray scrollbar, a row that wastes height, two buttons fighting.

2. Colour & Surfaces

  • Primary (#0053db) is reserved for high-intent actions and active states. Never spend it on read-only information (status, labels). primary_container (#dbe1ff) for subtle highlights.
  • Canvas (#f8f9ff) — a cool, bright blue-gray.
  • No-Line Rule. No 1px solid borders for sectioning or between list items. Boundaries come from background shifts (sidebar on surface_container_low against a surface main area).
  • No fixed Tailwind scales (bg-blue-50, text-blue-950, red-*) on any surface that must work in both themes. Use semantic tokens or component variants (<Alert variant="info">).

Semantic tokens (app/globals.css)

Token Usage
--success / --success-foreground / --success-background / --success-border Positive completion states
--warning / --warning-foreground Cautionary states
--info / --info-foreground / --info-background / --info-border Informational callouts, external-user badges, non-blocking guidance
--destructive / --destructive-foreground Errors and destructive confirmations

Values live under :root and .dark. Every token must also be registered in @theme inline (--color-token: var(--token)) in the same change, or the Tailwind utility silently does not compile and the class is dropped.

Surface tiers

Treat the UI as physical layers; depth comes from the tier, not from borders:

Level Token Used for
0 — Base surface Page canvas
1 — Sectioning surface_container_low / surface_container Sidebar, nested row groups
2 — Interaction surface_container_lowest (high contrast) / _highest Cards, inputs

A surface_container_lowest card on a surface_container_low background gives a "soft lift" that is felt rather than seen. Nested surface = a group of rows on bg-muted/40 or bg-surface-container-low inside a card or panel — the standard way to group dense data.


3. Typography & Spacing

Inter, chosen for precision and legibility at small sizes.

Level Size Token Usage
Display 3.5rem display-lg Hero metrics and large data visualisations
Headline 1.75rem headline-md Page titles and primary section headers
Title 1.125rem title-md Card headers and modal titles
Body 0.875rem body-md Standard UI text and data values
Label 0.75rem label-md Form labels and metadata (on_surface_variant, medium weight)

Spacing is a tight 0.2rem increment for data density, expanding for editorial breathing room: Tight (2) 0.4rem icon→text · Standard (4) 0.9rem inside components · Editorial (10) 2.25rem between sections · Hero (16) 3.5rem page margins and headers. Pair a bold headline with regular body and generous vertical padding (8–10).


4. Elevation & Depth

  • Tonal layering first (§2). A raised element never sits inside another raised element to express one boundary — no Card in an overlay, no Card around a table.
  • Ambient shadow for floating elements (command menu): shadow-[0_8px_30px_rgb(0,52,94,0.06)], tinted with on_surface. Never #000 shadows.
  • Ghost border when containment is required for accessibility: outline_variant at 15% opacity. Never a 100% opaque border.
  • Glass for floating chrome (nav bars, dropdowns, modals): bg-surface/80 backdrop-blur-xl (or surface_container_lowest at 80% + backdrop-blur-md).

5. Components

Component index

Before building a control, check whether the vocabulary already exists here.

Component Owns
components/common/status-badge.tsx — StatusBadge, StatusDot The four-tone on / off / attention / idle pill, and its dot alone for a group label
components/table/faceted-filter.tsx — FacetedFilter A facet: toolbar pill or form field; flat or grouped options (Filters, below)
components/common/file-kind-icon.tsx — FileKindIcon, FileKindLabel The file-type mark and its icon+label row (File Type Marks, below)
components/common/panel-section.tsx — PanelSection A titled concern inside an overlay, on a nested surface (§6 Create / edit overlay)
components/common/panel-form.tsx — PanelForm, PanelFormError A create/edit overlay as one form: header, failure strip, sections, Cancel or Back + submit
components/common/panel-steps.tsx — PanelSteps The progress track of a multi-step overlay, first in its body (§6 Create / edit overlay)
components/common/field-with-help.tsx — FieldWithHelp A label, its control and the one visible help line under it (§6 Displaying values)
components/common/download-menu.tsx — DownloadMenu The one Download control: a button for one format, a menu of formats with file marks (§6 Hand over a file)
components/common/pending-button.tsx — PendingButton An action button that swaps to a spinner and its running verb (Buttons, below)
components/common/summary-row.tsx — SummaryRow Label-left / value-right rows (§6 Displaying values)
components/common/locked-value.tsx — LockedValue A value an overlay can never change, with its Locked badge, as a SummaryRow value (§6 Controls)
components/common/truncated-id.tsx — TruncatedId A long id shortened to head…tail with a copy affordance
components/common/text-link.tsx — TextLink An inline link; external for one that leaves the Hub (Links, below)
components/layout-ui/navigation/nav-switcher.tsx — NavSwitcher The current choice among siblings as a menu, with icons and a check (§6 Record workspace)
components/layout-ui/navigation/nav-icons.ts — NAV_ICONS, NavIconName One icon per destination, named by server-built menus and resolved on the client (§6 Navigation)
components/common/link-tabs.tsx — LinkTabs A segmented switch between a page's views, each a URL, with counts (§6 Record workspace)
components/common/stat-card.tsx — StatCard One fact at a glance: icon tile, label, value, one sentence; a link card with href (§6 Record workspace)
features/forms/form-workspace — FormPageHeaderSlot, FormWorkspaceHeader, FormSummaryCards A form's trail, page switcher and Design in the header, its page masthead, its fact cards (§6)
components/timeline — Timeline and its parts Any sequence of steps: history, activity, progress (Timeline, below)
components/common/locale-label.tsx — LocaleLabel A survey language as name + short code (Spanish es), anywhere
components/copy-to-clipboard.tsx — CopyToClipboard The copy affordance, overlay and inline layouts (below)
components/table — DataTableSurface and friends All list-table chrome (List tables, below)
components/ui/responsive-panel.tsx — ResponsivePanel Desktop Sheet / Dialog ↔ mobile Drawer swap; dismissible lock (Overlays, below)
.grid-card-list (app/globals.css) Peer-card grids without breakpoints (below)
asset-storage/…/get-user-file/ui — SubmissionFileDialog A submission file's preview + details dialog (§6 File answers)
components/public-status — PublicStatusPage, PublicStatusReference Every status page a non-Hub reader sees: respondents, link and export recipients (§6)
components/error-handling/error-page — ErrorPage Every full-page error a Hub user sees (rules: AGENTS.md "Error page chrome")
features/about — ReleaseVersionLink A Hub or API version, linked to its tracked GitHub release notes (Links, below)

Add a row here in the same change that adds a shared component. Where it lives (components/common/, a graduated components/<domain>/, or lib/<domain>/<slice>/ui/) is decided by "Where UI for a shared concept lives" in project-structure.md.

Status vocabulary — StatusBadge

Four tones. Add a fifth only by changing this table, with a state none of the four can express.

Tone Meaning Badge variant Example labels
on Present / active / healthy / accepted success Configured, Set, On, Enabled, Active
off Absent, inactive or declined — a legitimate state secondary Not set, Off, Disabled, Rejected
attention Required and missing, or waiting — the operator must act warning Not configured, Expired, Pending
idle Exists, but nothing has happened yet — nobody to chase info Not started, Viewed
  • destructive is only for something actively failing, or confirming a destructive action. Never for "empty", never for a declined request.
  • All tones render as the same soft-tinted pill (bg-success/12 text-success) with a leading size-1.5 rounded-full bg-current dot. No solid fills (primary is for actions), no per-state icons — differing shapes read as differing kinds of information.
  • One label per concept per page ("Enabled/Disabled" or "On/Off", everywhere).
  • A lifecycle with many codes is grouped first; the tone follows the group, never the code. Collection status: not yet engaged (Not started, Viewed — the respondent has answered nothing) is idle, still collecting (In progress, Expired) is attention, Complete is on, ended without completing (Screened out, Quota full, Abandoned, Cancelled) is off — a legitimate outcome, not a failure. The group, not the code, also decides what else applies to the record. Reference: features/submissions/ui/describe-collection-status.ts.
  • A group has its own label, never a member's (Not engaged, Collecting, Complete, Ended). A group called "In progress" that holds the code "In progress" makes a chip ambiguous: the reader cannot tell one code from the whole group. A one-code group may share its code's label, because it is shown as that code. The mapping file owns the groups, their order and labels (COLLECTION_STATUS_GROUPS), so the column, the filter and any prefill agree.
  • A record's lifecycle word must not collide with the form's. "Closed" and "Open" already describe a form (accepting responses or not; a closed survey's public page), so a submission group never uses them. Name what happened to the response, not to the form.
  • idle is only the first step of a lifecycle — the record exists and nothing has happened to it. It is quieter than attention (no one has to act) and must not read as off (nothing has ended). Never use it for "informational" or "optional"; a fact with no lifecycle has no badge tone (§5 Alerts for callouts).
  • An unknown code is never shown raw. It joins the neutral group and is humanised (panel_hold → Panel hold), so a code added on the server reads like its siblings.
  • One record, several status axes: the lifecycle is "Status", every other axis names itself. A submission's collection state is its Status; what a reviewer did afterwards is "Review" (column, detail cell and filter alike). Never two columns or filters both called Status.
  • In a value column, either every row is a badge or every row is a literal. Mix only when the row kinds differ (a flag vs a URL), and then the literal is monospace.
  • A state is a badge everywhere it appears — table cell, panel header, review step. Never a bare word in one of them. If you write variant={x ? "default" : "secondary"}, use StatusBadge.
  • Alerts use the same mapping: info for a consequence or a view choice, warning for a risk the operator is choosing, success for a completed write, destructive for a failure. Never info for a security-relevant choice.
  • A batch that finished with some failures is warning, not success — title says so ("Ready, with failed submissions"), description gives the counts the reader can act on and what the failures mean for them. Leave out bookkeeping (batch counts, internal step names).

File Type Marks — FileKindIcon

A status tone answers "how is this doing?"; a file mark answers "what will I get?" — so it may carry an icon, under the same discipline.

lib/file-kinds/ is the server-safe catalog (extension, MIME, label, group); components/common/file-kind-icon.tsx renders FileKindIcon (glyph) and FileKindLabel (icon+label row for pickers, menu items, table cells).

  1. All or none. Every option in a list gets a mark, or none do.
  2. Muted and uniform — size-4 text-muted-foreground, owned by the component. Never tint by format; colour belongs to status. (A preview tile is the one place it renders larger.)
  3. Never guess. An unknown kind renders the generic file glyph; resolvers return FileKindKey | undefined, never a defaulted icon.
  4. Resolve the kind, not the icon. Feature code maps its vocabulary to a FileKindKey (features/export/utils.ts) and never returns a LucideIcon.
  5. Specific source first, coarser fallback (wire key csv-shoji before delivery enum Csv).
  6. Catalog stays server-safe. lib/file-kinds/index.ts does not re-export icons; import glyphs from @/components/common/file-kind-icon.
  7. Same format → same label on every surface (FILE_KINDS.xlsx.label = Excel (XLSX)). When a SelectItem's children are a FileKindLabel, set textValue to that label.

Copy affordance — CopyToClipboard

  • overlay (default) for a normal-width field with spare room; inline as a flex sibling of the value in table cells, tight rows, and next to any disabled input or textarea.
  • Never mix both layouts on one page for the same kind of value.
  • Give every value a reader might paste somewhere (URLs, keys, ids) a copy button — and then give it to every such value on the page. Enum-ish values (development, /api) get none.

Links — TextLink

A link goes somewhere; a button does something. An inline destination (in prose, a SummaryRow value, a section aside) is a TextLink — never a hand-styled <a> or a Button dressed as text. The reverse holds too: a quiet action inside a panel ("Rebuild reporting data…") is a ghost button, never variant="link".

  • Internal links stay in the tab. The reader keeps their place with Back (and BackToTableButton restores list state).
  • External links say they leave: TextLink external opens a new tab (rel="noopener noreferrer"), adds a trailing ExternalLink mark and an sr-only "(opens in a new tab)". Never hand-roll target="_blank".
  • Name the destination, not the data type — "Open in Tenants", "PostHog", not "Profile", "Details" or "Link". The reader decides whether to click from the text alone.
  • No configuration, no link. A link to a third-party tool renders only when the server can build a working URL; otherwise omit the row — never a disabled link or —. Build such URLs on the server so project ids and keys stay there.
  • Links to Endatix's own sites are measured in the Hub. Build the URL in one helper that adds utm_source=endatix_hub, utm_medium=<where it was clicked> and utm_campaign=<purpose> (lib/hosting/release-notes-url.ts), and send a PostHog event on click (TextLink onClick). The event is the measure: GitHub shows repo owners no UTM data, and noreferrer drops the referrer. Never link to a third party's site with our UTM tags.
  • Link only to what is known to exist. An id is not proof: a session id is issued even when recording is off, so a replay link built from it opens an empty page. Link to a resource the API has returned, or check before linking.

List tables — components/table

Every list of records uses the shared chrome — a set of primitives, so a small static list and a paged sortable grid look identical:

Export Use
DataTableSurface The rounded, softly-lifted container; dims rows during a URL transition
DataTableGrid Header + body for a TanStack table
DataTableEmpty The empty state, outside the table element
dataTableHeaderCellClassName / dataTableBodyRowClassName / dataTableBodyCellClassName Sticky header, zebra fill, cell padding for a hand-rolled <table>
dataTableColumnLabelClassName The uppercase muted column title
DATA_TABLE_SHRINK_WRAP_CLASS_NAME Shrink a column to its content
PagedTableFooter, DataTableToolbar, DataTableSkeleton Pagination, filter bar, loading state
StaticDataTable, StaticDataTableRow, dataTableCell A few known rows on the helpers above: static header, zebra rows
DataTableRowActions The trailing ghost icon actions of a row, each named for its row
  • A table is not card content. Title, description and primary action sit above DataTableSurface as plain h2 + p + Button. A Card is for controls and prose.
  • Class-name helpers before TanStack. A handful of static rows needs DataTableSurface + StaticDataTable (the helpers, assembled), not a table instance. Pass isStatic: true to the header helper when you hand-roll the header and it never scrolls under sticky positioning.
  • Zebra parity is index % 2 === 1, matching DataTableGrid.
  • Column labels name what the column holds for the reader ("Requester", "Submitted"), not the entity field (Email, Created).
  • A badge column shrink-wraps (DATA_TABLE_SHRINK_WRAP_CLASS_NAME + whitespace-nowrap), left-aligned with its header. Never a fixed narrow width: the header truncates to C… and the reader loses the one column they scan first. Icon-only columns stay w-12.
  • A per-row control that cannot apply to this row yet is — with an sr-only reason ("Not reviewable until complete"), not a control that acts on nothing. A value already recorded still shows, so nothing a user did disappears. The rule lives in the state mapping, so grid and detail agree (isReviewApplicable, features/submissions/ui/table/cell-review-status.tsx).
  • Rows are read, not edited in place. A record list never puts inputs in its cells or saves on blur: a row is edited in its own overlay and deleted through an AlertDialog (§6 Controls & consequences). The table stays a surface for scanning.
  • Row actions are ghost icon buttons in a trailing Actions column (DataTableRowActions). Each aria-label names the action and the row ("Remove ada@example.com from this form"). An action that cannot apply to a row is omitted, not disabled ("Edit" on a person when the list has no properties to edit).
  • User-defined columns (one per property, field or answer): every column gets a minimum width, values wrap, an unset cell is — with sr-only "Not set", and the table scrolls in overflow-x-auto instead of squeezing columns.
  • Wiring (URL state, paging, loading skeletons): project-structure.md "List pages and tables".

Filters — FacetedFilter. A facet speaks the vocabulary of the column it filters. Reference: the submissions Status facet, features/submissions/ui/filters/submissions-filter-toolbar.tsx.

  • A facet over states shows each option as its StatusBadge (tone on the option): the same pill, tone and label as the column, so the reader matches a row to a choice by sight. Plain options keep plain labels; never mix badges and plain labels in one facet.
  • A grouped lifecycle is filtered group first (groups). Each group is one top-level row — a tri-state checkbox, the group's StatusDot and its label — that selects or clears every code in it. Its codes sit indented beneath as badges, so a reader can still narrow to one.
  • Every top-level row has the same anatomy. A group with one code (Complete) is a top-level row like the others — checkbox, dot, label — with no child row. Shown as a lone badge it reads as a child that lost its parent.
  • The choice most readers want comes first; the rest follow the lifecycle. The submissions facet leads with Complete (the outcome people filter for), then Not engaged → Collecting → Ended. A one-code group is the natural lead: it is the only row with no children, so it sits above the nested part of the menu instead of interrupting it.
  • The trigger summarises in the same terms. A fully selected group is one chip with the group's label and tone; otherwise one chip per code, in menu order; more than two chips collapse to n selected.
  • Search finds a group by its name as well as its codes ("ended" lists every ended code).
  • The URL and the API carry codes; a group is a shorthand for its codes. When the API gains a category filter, the heading sends the category and the UI does not change. Until then a new code in a group must be added to the mapping, or the heading silently stops covering it.
  • A facet that replaces an older one keeps the old links working. Read the old URL key into the new facet (isComplete=true → collectionStatus=complete) and let the canonical redirect rewrite the URL. A bookmark that silently drops its filter shows the reader the wrong rows.
  • The same facet in a form is variant="field", not a second control. A dialog that filters the same records (export) reuses the list's facet and its groups (COLLECTION_STATUS_FACET_GROUPS), so its menu, badges and search are the list's. The list passes those groups in (statusGroups); export does not import the mapping file. As a field it sits under its own Label htmlFor, spans the width like the fields around it, names its whole selection at every width, says what an empty selection means (emptyLabel: "All statuses" — never a blank field that reads as "none"), and wires its help line through describedBy. Its clear item says "Clear selection".
  • Flows prefilled from the list take the list's values exactly. Send the same codes, not a coarser mapping onto another control; a flow that cannot express a list filter names it (Configure and run, below).

Empty states — DataTableEmpty with icon + title, description as children:

<DataTableEmpty
  icon={Inbox}
  title="No matching requests"
  onClearFilters={clearFilters}
>
  No request matches “acme”. Search looks at the email and company.
</DataTableEmpty>
The list is empty because… Title says Action
nothing was ever created "No … yet" the create button (action) if the list has one
the default view is clear what is clear ("No requests waiting…") optional ghost link to the wider view ("Show all …")
a search or a non-default filter "No matching …" / "No approved …" onClearFilters — the standard outline "Clear filters"
  • One icon for both kinds of empty: the list's entity icon, same as its sidebar item. A search or warning glyph reads as a different screen, or an error.
  • The description names what was searched or filtered, and which fields search looks at.
  • onClearFilters resets exactly what the toolbar's Reset resets — build it once in the list shell and hand it to both.
  • Compact inside the surface (py-10, text-base title, EmptyMedia variant="icon" on bg-muted); the page-level Empty is for whole-page empties such as /forms. The one-liner <DataTableEmpty>No rows.</DataTableEmpty> is only for secondary lists (a settings card, a dialog). Reference: SignupRequestsEmpty in features/platform-admin/list-signup-requests/.

Card grids — .grid-card-list

Any set of peer cards uses .grid-card-list (app/globals.css), never viewport breakpoints:

grid-template-columns: repeat(auto-fill, minmax(min(var(--grid-card-min), 100%), 1fr));
--grid-card-min: 380px;  /* per page: className="grid-card-list [--grid-card-min:360px]" */
  • Why: the collapsible sidebar changes the content width without changing the viewport, so md:/lg: breakpoints measure the wrong thing; auto-fill also scales to ultrawide screens with one knob instead of a breakpoint ladder.
  • auto-fill, not auto-fit — card width must not depend on card count.
  • Keep the min(…, 100%) guard, or narrow containers overflow.
  • Set --grid-card-min from the card's narrowest legible content (default 380px; below ~320px only for tiny tiles). Three columns need 3 × min + 48px: 1188px at the default. A card that needs more than its track holds (a footer of four links) loses an action to overflow, so move the action into the card's menu instead of raising the minimum.
  • The grid owns the card's width. A card inside it does not set its own min-w-*.
  • Give cards h-full so a row shares a bottom edge.

Fact cards — StatCard

components/common/stat-card.tsx. One fact about a record at a glance: an icon tile, a label, the value and one sentence. Reference: features/forms/form-workspace/ui/form-summary-cards.tsx.

  • A card holds a fact, never an action. Counts, states, last change. Share, Export and other actions are buttons in the masthead or header, not cards.
  • The value keeps its type (§6 Displaying values): a state is a StatusBadge, a count a number, a time a formatted date. The sentence says what it means for the reader ("Accepting submissions", "Anyone with the link can respond"), not the field name again.
  • The icon names the kind of fact in a bg-primary/10 tile — the one place a card carries an accent; the card itself stays bg-card with its ghost border.
  • A card that leads somewhere is the link, as a whole, marked by ArrowUpRight in its corner (href). No text link inside a card, and a card with nowhere to go has no arrow.
  • Peer cards share a row: .grid-card-list with a --grid-card-min chosen so the cards fill the row at the common width (no empty column after the last card); a narrow panel lowers it.
  • A count that failed to load shows no number (§6 Counts).
  • A value being read again is pending: the icon and label stay, and the value and sentence are skeleton bars (§6 Fresh facts in a preview).

Timeline — components/timeline

For one subject, in order: what already happened to it, or how far a process has got.

  • Use it for the history or activity of one record or person (a visitor's steps up to a signup, an audit trail, a submission's life), and for the progress of a process the reader is not driving (provisioning, a job, a delivery).
  • Not for a set of facts (SummaryRows — order is not the point), a state (StatusBadge or Alert), the reader's place in a form (PanelSteps — those are sections still to fill, not events that happened), or many records (a table).
  • Reach for it when the reader would otherwise scan a log to answer "what came first, and where did it end?".

Composition API adapted from ReUI's Timeline (MIT): Timeline (value, orientation, size) → TimelineItem step={n} → TimelineHeader (TimelineDate, TimelineTitle) + TimelineIndicator + TimelineSeparator, optional TimelineContent. Steps up to value are completed; the value step itself is active. Reference: features/platform-admin/review-signup-request/ui/signup-visitor-section.tsx.

  • One active step — the one the record is about (the request in a visitor's history). Steps that led to it read as completed; later steps stay muted. With nothing to single out, the last step is active.
  • Oldest first. A timeline reads as a story that ends at, or passes through, the event the reader is looking at.
  • Words, not event names ("Viewed /signup", "Requested a workspace", not $pageview). Map known events, humanise the rest. Non-active titles are font-normal.
  • Leave out bookkeeping (tool-internal events such as $set, $web_vitals) — filter at the source, not in the component.
  • Fold repeats into one step with a muted ×n; a refresh is not new information.
  • Cap it and link to the source (~15 steps; the full history is one TextLink external away).
  • Semantics: it is an ordered list — give it an aria-label. Titles are <p>, not headings, because a timeline sits under a section heading; opt into a heading (asChild) only when the timeline is the page. Dates are <time dateTime> in compact format.
  • Colour means progress, not health. Rings and connectors are primary at low opacity until completed. Never tint a step by status — say a failure in its title. An indicator icon marks only the active step. size="sm" inside panels and cards; the default on a page.

Overlays — ResponsivePanel

Operation Desktop Mobile (<768px)
Simple create/edit, 1–2 fields Dialog Drawer
Complex create/edit, 3+ fields Right Sheet Drawer
Destructive/critical confirmation AlertDialog AlertDialog
Record detail / preview Right Sheet (or Dialog for media) Full route, or Drawer
Record preview from a list (read) Right Sheet, standard width Drawer
Short reference (About, versions) Dialog Drawer, content height
  1. Use ResponsivePanel — desktopType="simple" (Dialog) or "complex" (Sheet). If a Dialog scrolls on desktop, it should be a Sheet.
  2. Never side="bottom" on a Sheet for mobile — swap to Drawer for Vaul's touch behaviour. Never a Drawer on desktop.
  3. One scrollable body; the footer stays outside it.
  4. Every overlay has an accessible title and description.
  5. Never stack overlays. A follow-up form (approve, reject) is a step inside the same panel, not a Dialog over a Sheet: the record disappears behind a scrim and Escape closes the wrong one.
  6. Widen a Dialog with an sm: prefix (sm:max-w-4xl) — DialogContent ships sm:max-w-lg and an unprefixed class loses to it.
  7. Every Hub dialog is shadcn — never a SurveyJS popup (§9).
  8. Lock the panel while its own work runs: dismissible={false} hides the close button and ignores Escape, outside clicks and drag-to-close on every mode. Also guard onOpenChange, and never leave a visible close control that silently does nothing.
  9. A short panel gets a short Drawer. ResponsivePanel sizes the Drawer at 90vh for forms; a few rows of reference pass drawerContentClassName="h-auto".
  10. An overlay opened from a menu is rendered outside the menu. Keep its open state in the component that owns the DropdownMenu, set it from the item's onSelect, and render the panel as the menu's sibling. Inside DropdownMenuContent it unmounts when the menu closes.
  11. A prefilled form opens on its primary action (onOpenAutoFocus → focus the submit button) so Enter runs it with the suggested choices. Fall back to Radix's default when the button is absent or disabled.
  12. When a follow-up would stack, link out or make it a view. From a preview panel, an action whose own UI is an overlay (the Share dialog) becomes a link to where it lives (Share link opens the public page in a new tab), or the panel's job moves to a page. A list whose rows open overlays is a view of the page (LinkTabs), not a panel. Reference: features/forms/ui/form-sheet.tsx.

Buttons, inputs, chips

  • Buttons: primary (primary / on_primary, no shadow) for the one high-intent action; secondary (secondary_container); ghost (primary text) for low emphasis; destructive only to commit something final. A trailing ellipsis (Reject…) means "asks for more before it acts". Spinners belong on action buttons, never list rows. A multi-stage action names the stage that is running (Updating submissions… → Exporting…), in a short verb phrase (PendingButton). One primary per page: when a page has several list sections, the create action of the main task is primary and the others are outline. A view (§6 Record workspace) counts as a page: Add participant is primary on a form's Participants view, Add property on its Properties view.
  • A record's main action sits in the header's action area and is always primary (Design on every form page). The page's own create action stays in the page. A button that goes to another page is a Link styled as a button (Button asChild), so it can open in a new tab and shows its URL.
  • Inputs: surface_container_low fill; on focus the ghost border goes from 15% to 100% primary. Labels label-md in on_surface_variant.
  • Typed values use the control that produces their wire format, so the API never refuses a value the form let through: a date is type="date" (YYYY-MM-DD), a date-time datetime-local, a number type="number", a yes/no a Select (Yes / No), a choice from a list a Select or checkboxes. Free text is for text only. An optional value can always be emptied: a select carries an explicit Not set first option, and emptying clears the stored value rather than saving "". A date-time is shown in the reader's time zone and sent with their offset (2026-03-01T09:00+02:00): datetime-local has no zone, and an API that reads a bare wall time as UTC would store a different instant. A choice control always offers the stored value, even one outside its list, so nothing stored is hidden or silently cleared. Reference: features/audience/ui/property-value-field.tsx.
  • Chips / tags: rounded-full to distinguish from buttons. Status tags are StatusBadge, and its dot marks a state. A role tag says what a row is, not its state (Identifier on the property that copies the match key). It is a Badge variant="secondary" with no dot, placed after the row's name, so the reader does not read it as a status. It may carry the icon of the section that owns the concept elsewhere (UserRound, the Participant section of Add and Edit participant), and its help line reuses that section's wording ("It matches … across forms"), so one idea looks and reads the same on every surface.

6. UX Patterns & Page Recipes

Cross-cutting patterns first; recipes after them only add what is specific to their shape.

Displaying values

  • Align label → value. Label left, value right-aligned into one scannable column (SummaryRow, or dt/dd with justify-end text-right). Put label/value rows in a .grid-card-list — a full-width card puts a two-word label ~1000px from its value.
  • Never truncate a value the reader came to read. Wrap it (break-all for ids/URLs/emails, break-words whitespace-normal for prose). Truncate only secondary text, with the full value in title.
  • Unset ≠ empty. Never configured → — with sr-only "Not set". Resolved to an empty string → (none). An optional field left empty → —.
  • Show the source key as text, not in a tooltip. On configuration pages the env var or setting name is a font-mono text-xs text-on-surface-variant sub-label under the human label — on every row, secrets included. A row of CircleHelp icons is noise standing in for design.
  • Help is visible text, not a tooltip. What a field means goes in one text-xs text-muted-foreground line under its label or legend, wired with aria-describedby. Siblings get one each or none (three date ranges → three lines). An Info icon on one label is decoration.
  • Literal values are monospace. Nested detail rows indent pl-4 in text-xs text-muted-foreground — no left-border rule.
  • A value keeps its type everywhere — a state is a StatusBadge, a language a LocaleLabel, a format a FileKindLabel, an id a TruncatedId, a product version a ReleaseVersionLink.
  • Omit what cannot apply rather than showing it empty.
  • Dense grids (read-only matrix answers, matrixdropdown-answer.tsx): every column gets a minimum width, cells wrap (never a single-line <Input>), padding is tightened for the density instead of inherited from page tables, header rows are h-auto, and the grid scrolls in overflow-x-auto rather than compressing columns. The PDF equivalent (PdfMatrixTable) splits width evenly and falls back to stacked rows.
  • Secrets: never render a secret value, even masked — show presence (Set / Not set) and say so in the section description. But decide what is secret by where the value already goes: if it is a ClientEndatixConfig field it is already in every page's HTML, so show it (reCAPTCHA site key, PostHog project key). Hiding a public value costs the operator the one fact they came for.

Controls & consequences

  • A control that cannot take effect is disabled, with one text-xs text-muted-foreground line saying when it applies. Not hidden (the panel jumps), not silently inert.
  • Warn only about a reachable risk. A warning that cannot come true teaches readers to ignore warnings.
  • State the consequence once, as one closing Alert — never a warning per field.
  • A consequence of one choice sits under that control, shown only while the choice is made ("Incomplete submissions are updated first, so this export takes a little longer"). It is not an Alert above the form; that is for the whole step.
  • A section that cannot apply to the current choice keeps its masthead and says why in its description, with no body ("A codebook describes the form's questions, so submission filters don't apply"). Disable single controls; drop a whole section's fields.
  • Hide what the tenant cannot reach; disable what cannot take effect now. A page, tab or link behind a feature flag the tenant does not have is not rendered at all — a disabled way to nowhere is noise. A control on a reachable page that cannot apply yet stays visible, disabled, with its reason (above).
  • A setup choice that later locks is a control while it can change and a fact once it is locked — a card with the select before anyone depends on it, then one clause with a Locked badge where the reader works (the audience match key in the Participants description).
  • Immutability belongs on the field it constrains (a Locked badge + one line), not in the panel description.
  • A value an edit can never change is a read-only row, not a disabled input. Show it as a SummaryRow whose value is wrapped in LockedValue, copyable when it is a key or an id, with one text-xs line saying why it never changes. A disabled input means "not now" (the first rule here), fades the value the reader came to check, and cannot be copied. Reference: features/audience/update-person/ui/edit-person-panel.tsx.
  • A record's key appears once, as the key. A field that copies it (a property named like the audience match key, email or external_id) is left out of the table and the add and edit overlays. Editing it could not change who the record is, so it would only be an empty second copy. Filter it once, where the list is handed to them (valueProperties). Where the fields themselves are what the page lists (the Properties view), that field is pinned first with an Identifier tag and one line saying where the key shows instead. That way, its absence from the other places is explained where the reader would look for it. Reference: features/audience/get-audience-page/ui/properties-table.tsx.
  • A key derived from a name is previewed before it is fixed. While the reader types, the field's help line shows the key it will produce ("Variable name cost_center. It never changes…"), or why none can be made, with the submit disabled. In the edit overlay the key is a read-only SummaryRow (copyable) with a Locked badge beside it.
  • A delete names its blast radius: the confirmation says what else goes, with a count when there is one ("Its values are deleted for all 1,240 participants on this form"), and what stays ("They stay on any other form they are on"). The AlertDialog stays open while it runs (spinner + verb on the destructive button) and shows a failure inside it; it never closes on click and leaves the outcome to a toast.
  • A setting wider than the page says its scope. A tenant-wide control surfaced on a record page (the match key on a form's audience) says so in its description, and its disabled line says who can change it or when it can change again.
  • State lives in the section header. An on/off section shows a StatusBadge in its aside; the switch sets it, the badge reports it.
  • Prefill what can be suggested, and say where it came from ("Suggested from the company name").
  • A required free-text reason has its API limit as maxLength, a visible n / max counter, and a description saying who will read it.
  • Errors land where they belong. Field validation under the field (aria-invalid, aria-describedby); anything else a destructive Alert at the top, with the form keeping its values — PanelForm puts that strip (PanelFormError) at the top of the body and stays open. A single control outside an overlay (a select in a card) shows its failure in its help line.
  • Back, not Cancel, on a step whose record is still open behind it.
  • Show the outcome in place; don't toast and close when the result is a record the user needs to see (a toast disappears; the updated record is the proof).

Navigation & wayfinding

Every move has one control, and each control does one kind of move. Pick by what the reader is moving between:

The reader moves between… Control Example
Areas of the Hub Sidebar Forms, Data lists, Settings
Up to a parent Header trail (breadcrumb) Forms › Flows › Cedar Grove Pulse
Siblings at one level of the trail A dropdown crumb (NavSwitcher) Flows ▾ lists the other folders
Aspects of one record NavSwitcher after the trail, past a vertical divider Cedar Grove Pulse │ Submissions ▾
Views of one page LinkTabs (segmented, ?view=) Participants / Properties
Panes that are not worth a URL Radix Tabs, inside a panel —
Into an immersive editor and back A button in, one Back out (?from=) Design
From a record back to the filtered list lib/list-page/table-return-to + BackToTableButton a submission back to its list
  • Everything a reader would share or reload is a URL — a page, a view (?view=), a filter. Only panes inside an overlay may be unaddressable.
  • The trail is location only. It starts at the area (the sidebar already leads home, so no Home crumb), its last crumb is where the reader is (plain text, never a link to the page they are on), and it folds its middle into … past three crumbs. An aspect or a view of a page is never a crumb.
  • One place per destination. Two links to the same page in one header (a record's name and its Overview) are one too many; keep the one the reader expects to use.
  • No "Back to …" buttons between siblings. Siblings are reached through their switcher; Back is for leaving a mode (an editor, a detail opened from a list).
  • One icon per destination, the same everywhere it is offered — sidebar, switcher, sheet links, card quick links. A server-built menu carries the icon's name (NavIconName) and the client resolves it from nav-icons.ts: a component cannot cross from a server component into a client one.
  • A return target from the URL is never a path. ?from= (and any "return to" value) is checked against the known destinations; anything else falls back to a safe default. Building a redirect from query text is an open redirect.
  • Navigation costs no row of the page (principle 6). A tab row on every page of a record is a row the reader pays for on every visit; a header switcher is not.

Page masthead

  • h1 names the page the reader is on; the trail carries the context (the record, the folder). A record's own home (its Overview) titles itself with the record's name.
  • A description only when it says something the title and trail cannot ("mocked data").
  • One row: title left, the page's own actions right (Participants: Add participant). Record-wide actions are not repeated here.

Reference information on demand

Facts a reader needs now and then (the Hub and API versions while reporting an issue) are one menu item away, not in the navigation. The sidebar holds places to go. A fact that costs a request or needs the space of a row of its own does not belong in it. Reference: features/about/view-versions/ (account menu → About Endatix).

  • One entry point, where people look for it — the account menu, after Settings, signed in only. Not a chevron, a footer line or a tooltip on another item.
  • A simple ResponsivePanel: title names the thing ("About Endatix"), the description says when it is useful ("Include them when you report an issue"), the body is SummaryRows on a nested surface.
  • Read on open, never on page load, and nothing reaches public HTML or the client bundle. next.config.ts resolves the build and passes it through env, which inlines it where process.env.HUB_* is read: server code only (lib/hosting/hub-version.ts), so it lands in server chunks. Never assign process.env in next.config.ts: a standalone server does not run that file, so the values are gone in production. scripts/release-prepare.sh fails if the commit appears in .next/static. A complete read is kept for the page; a partial one is asked again on the next open. Load as in Loading inside a panel: skeleton the values, keep the labels.
  • A value that did not load is — (sr-only "Not available"); the rest stays usable, and the copied text says unavailable for it.
  • A release shows its version; any other build shows branch and commit. A release (0.8.0, 0.8.1-canary.3) is a ReleaseVersionLink to its notes. A build that is not a release is for developers: BuildRef puts the branch and the commit on their own right-aligned lines, each after its git mark (GitBranch, GitCommitHorizontal), as TruncatedIds: a long branch keeps both ends (feat/h134-show-p…the-about-dialog), the commit its first 7 characters (truncate="prefix"), each with the full value in the tooltip and a copy on hover. Never linked: the commit may exist only in a fork. The section's copy gives main @ <full sha>.
  • Every Hub user sees branch and commit, not only admins. They are what a user needs to file an issue, including on a fork's deployment, and the commit is no secret. A later field (the git remote) can follow the same rule.
  • One home per fact. The versions are not repeated on Admin → Environment: platform admins have the same menu item, and a second copy is a second thing to keep in step.
  • Copy sits on the group it copies. The rows are a PanelSection ("Versions") with one CopyToClipboard (inline) in its aside that copies every row as plain text. Not a footer button (the footer is for actions that change something) and not an icon floating beside the rows (it reads as belonging to neither).
  • The product first, what it is built on after. Hub and API are the section's own rows. The SurveyJS libraries sit below them in one lifted group (bg-surface-container-lowest, a muted text-xs heading "Built on SurveyJS"): important for a form bug, not the product. When every library is on one version, the usual case, the group is one row ("All 5 libraries", linked to the survey-library release) with the package names in a muted line; any difference or missing package shows one row per package. The copied text always lists every package. Reference: features/about/view-versions/ui/surveyjs-version-group.tsx.

Loading inside a panel

A ResponsivePanel opens on the record the reader already has. Any further read — a third party, a slow detail — loads inside the section that shows it, while the header, the other sections and the footer stay usable (Sheet and Drawer alike). The list behind never waits on it, and it never starts per row. Reference: review-signup-request/ui/signup-visitor-section.tsx.

  • Start the request after paint — from an effect or an event, never during render (a server action called while rendering updates the router mid-render).
  • Skeleton the section, not the panel. Keep the PanelSection masthead; replace only its body with Skeleton bars shaped like the rows to come, mark it aria-busy, and add an sr-only line naming the wait ("Loading visitor details"). On a tinted section (bg-surface-container-low), tint the bars (bg-foreground/10): the default bg-accent matches that surface, so the pulse does not show.
  • One request per opened record. Cache a slow or third-party read (evidence, versions) on the client for a few minutes; changing step or reopening the same record must not ask again. The record's own facts that change by themselves are the exception: they are read again on every open and never cached (Fresh facts in a preview, below).
  • A check before a form (is this form ready to export?) skeletons the sections the form will fill, mastheads kept, so the panel does not jump from a spinner line to a full form.
  • Quiet states, never an error tone — the record is fine, and destructive belongs to an action the reader just took. Source answered with nothing: one muted line. Source did not answer: one muted line, plus a link out when a URL is known. Not configured: omit the section. A missing fact inside a successful read is —.

Fresh facts in a preview

Problem. An overlay opened from a list (a record's sheet, a details panel) starts with the row the list loaded, which may be minutes old. The Hub has no push channel (no websockets or SignalR), so nothing tells the page that a respondent submitted, a colleague disabled the record or a job finished. A reader who opens a record to check it is shown old facts and may act on them.

Pattern: open on the snapshot, re-read on open, skeleton what moves. The overlay is where the reader pays attention, so read again there. Reference: useFreshRecord (lib/utils/hooks/) in features/forms/ui/form-sheet.tsx.

  • Sort the fields first. Stable fields change only when someone edits them on purpose: the name, the id, the links built from the id. Volatile fields change without the reader: counts, lifecycle state, visibility, last changed, anything a respondent, a colleague or a job can move. Treat a field as volatile when in doubt.
  • Open at once on the snapshot. The title, description, links and footer render from the row immediately, so the overlay is never blank and its actions work during the read.
  • Read the record again on every open. Re-read when the panel opens, after paint, and never for every row or on hover. Do not cache the answer, because the next opening should read again. Mount the read inside the overlay content, which unmounts on close, so this needs no extra code.
  • Skeleton only the volatile values. Keep each fact's chrome (icon, label, card) and replace the value and its sentence (StatCard pending), with an sr-only "Loading …". Showing the old value and swapping it makes numbers jump and lets the reader act on stale data in between.
  • A failed re-read keeps the snapshot quietly. It is what the list shows, so it is not wrong, only old. Do not show an error tone or a toast for a read the reader did not ask for.
  • Drop a late answer. If the overlay switched record or closed, the answer is discarded.
  • The list behind is not refreshed by the preview. It refreshes on navigation or after a write (router.refresh()).
  • A page does not need this: a server page reads on navigation. Use it only where a client surface shows data loaded earlier. Revisit it if the Hub gains a push channel.

Progress inside a panel

Work the reader starts from a panel (prepare, export, retry) has one voice per place:

  • Footer button — spinner + the running stage's verb (Buttons, above).
  • Header description — one sentence for the step ("Updating incomplete submissions, then generating your file…"), aria-live="polite" so the change is announced.
  • Body — no spinner row and no second progress line. Controls stay mounted and locked, not hidden, so the reader can see what is being run and the panel does not jump. At most one status Alert (§6 Review and decide rule 2 applies to every panel).
  • Panel — not dismissible until the work ends (Overlays rule 8).
  • Outcome — a success Alert naming what was produced ("CSV file downloaded"), footer Done. Never a large centred icon plus a sentence that repeats the header.
  • A supporting step never blocks the action it supports unless it failed outright. If the reader lacks the permission for it (refreshing incomplete submissions needs edit rights, exporting does not) or it could only partly finish, run the action anyway and say so in the outcome: one extra sentence, and warning when rows may be missing.

View choices vs edits

A control that changes how a record is read (label language on a submission) must never be mistaken for an edit. Reference: features/submissions/ui/details/label-language.tsx.

  • One control, on the fact it re-reads (the metadata card's Language cell, same badge dropdown shape as its neighbours so the row does not jump). Never repeated in toolbars or dialogs.
  • The menu says what it changes: a DropdownMenuLabel ("Show labels in") and a DropdownMenuRadioGroup; mark the stored value (muted Submitted suffix).
  • No choice, no control — a single option renders as plain, named text.
  • Diverging from the record is info, never warning: one Alert variant="info" strip, role="status", naming both values, with a one-click way back ("Show in Spanish"). Solid warning is for facts about the record itself (a test submission).
  • Say concretely what did not change ("Answers are exactly as submitted in Spanish").
  • Downstream flows follow the view and confirm it (Export PDF, share link show the choice via LocaleLabel) — they never offer a second picker.

Counts, time and audit

  • A count that failed to load shows no number — never 0, which claims "empty".
  • The same destination has one title, one icon and one count source across sidebar, dashboard card and page.
  • Record the time with the actor, and show that time. An event that matters to an audit (a decision) stores who and when together, and the UI labels that time for the event (Decided), once. modifiedAt moves for unrelated reasons (a downstream process), so never show it as, or next to, the event time. Only records from before the time was stored fall back to Last updated, labelled as such. Never invent timeline events.
  • Who is a person, not an id. Resolve actors to names best-effort; when unknown, show Admin + TruncatedId — the id never disappears.
  • Why is shown verbatim, in full — a quoted block (bg-surface-container-lowest, whitespace-pre-wrap), never truncated.

Time-limited links

  • Sign when the reader acts, not when the page loads. Fetch a fresh signed URL on open or download (cache: no-store); a failed thumbnail re-signs once. Never put a presigned URL in an href that outlives the view that signed it.
  • Exports outlive tokens. A Hub-authenticated PDF links to the Hub page that signs on open; a share-link export (reader may have no account) keeps the signed URL and says once, muted, that links expire shortly.

Hand over a file

A file the reader takes away (a data list's items, personalized links, an export) comes through one control and one set of helpers, whether the server builds it or the browser does. References: DownloadMenu on a data list's page, features/audience/generate-links/.

  • One control: DownloadMenu. One format is an outline button that names it with its file mark ("Download CSV"). Several formats are a Download ▾ menu whose items are FileKindLabels. While a file is fetched, the control spins, says "Downloading…" and takes no second click.
  • One code path per source. A file the server builds comes through downloadFromUrl (lib/utils/files-download.ts): the server's file name, and its reason when it refuses (DownloadError), shown as the toast. A file the browser builds is written with writeCsv (lib/utils/csv.ts) and saved with downloadText. Never hand-roll the fetch-blob-anchor dance in a page.
  • CSV is UTF-8 with a byte-order mark and CRLF, so Excel shows accents and non-Latin names correctly. Name columns with the same keys the Hub reads, so a file the Hub writes can be imported back (the links file's first column is email or external_id, the match key's wire name, which the import suggests from).
  • Date the file name (personalized-links-<form>-2026-10-12.csv), so a second file never overwrites the first in the reader's downloads.
  • A file that is the only copy is saved the moment it exists. Personalized links are stored only as hashes, so the API returns each token once. The panel saves the file as soon as the answer arrives, without a second click, and says so in a success Alert ("20 links downloaded … It is the only copy"). Then it offers Download CSV again while it stays open. Before the run, one info Alert says the file will be the only copy and who can use it. Nothing new to hand over is info ("Everyone already has a link"), and no empty file is saved.
  • Read what labels the file before writing what it labels. When the write returns ids and the file needs names (a person's identifier for each token), read the names first. If the read fails after the write, the one-time answer can no longer be labelled.
  • Show a few rows to try, not the file. The outcome may preview the first rows (each value a reader might paste gets a copy affordance) and says the file has them all.

Evidence from third-party tools

What another tool recorded about a record's subject (an analytics profile behind a signup, a payment provider's risk check) is evidence for the reader's decision, not part of the record. Reference: features/platform-admin/review-signup-request/ui/signup-visitor-section.tsx.

  • Its own PanelSection, after the record it describes and before the decision, with the tool's TextLink external in aside, named for the tool.
  • Show what informs the decision, nothing more. For a person's origin: city and country (with time zone), browser, OS and device, referrer or campaign, landing page, first seen, and a Timeline of recent steps with the record's own event active.
  • Data minimisation. Never show IP addresses, coordinates, postal codes, raw user agents or accuracy fields: every operator would see them, and the decision does not need them. The tool's own page has them for the rare case that does.
  • Say which moment a value describes. First-touch values are labelled as such ("First came from", "First page"); unlabelled values are the latest.
  • Never block the record on a third party — load it as in Loading inside a panel, including its quiet states. "No data yet" says when to expect it ("can take a few minutes to arrive").
  • Credentials stay on the server. Read keys (read-only scopes) never reach the client; the client receives finished URLs and ids that already appear in the tool's own URLs.

Files & media

  • Never crop an upload — object-contain on bg-muted, at every size. A crop can hide the signature or measurement the reviewer needs.
  • Fixed height, width follows ratio (clamped), so mixed aspect ratios line up.
  • Wrap, don't scroll sideways (flex flex-wrap items-start) — a horizontal scroller hides uploads with no cue; top alignment keeps captions on one line.
  • Caption: name then MIME type, both truncated (name in title) — captions are secondary.
  • Reserve the space while loading so lazy content does not shift the page.
  • The tile promises, the dialog delivers — a video tile shows its first frame; playback and details happen in the dialog.
  • Print keeps the same promises: never crop, keep a row of images together (wrap={false}), keep a title with its first row, embed downscaled copies, single-line captions.

Marking a question on the designer canvas

A fact about a question that the author needs while designing (where its value comes from) is a small chip on the question, not a ring or a bare icon. A ring or outline competes with SurveyJS's selection and focus outlines, and an icon alone says nothing until hovered. Reference: lib/personalization/authoring/prefill-canvas.ts + features/forms/ui/editor/prefill-canvas.css.

  • The chip names the source, the card explains it. The chip is the icon of the section that owns the concept (the Personalization person) and the source's name (Age), nothing else. It is a role tag (§5 Chips): no dot, neutral fill, muted text. Hover or keyboard focus opens a card (role="tooltip", the chip's aria-describedby) with a heading in words (Prefilled from Age), one sentence on what it does to the answer, and where a click goes. The chip's accessible name is that heading, so a screen reader hears the fact without the card.
  • Name what SurveyJS leaves implicit. A default that reads Properties inside a calculation ({age} * 12) is personalization too: the chip lists every Property it reads, adds a muted ƒx, and the card shows the expression. Only a plain {age} is checked for fit.
  • It is a link to where the fact is managed, opening in a new tab so the design is not left (the form's Properties). It stops pointerdown and click so the designer does not select the question instead, and shows a --sjs2-color-utility-a11y ring on :focus-visible.
  • Top-right inside the card, clear of the corner where SurveyJS puts the collapse button of a selected question. One chip per question; it truncates rather than wraps. The card opens below it, right-aligned, on a floating surface.
  • A problem changes the same chip, it does not add a second mark. When Diagnostics has a finding for that question, the chip takes the warning tint and the card says what fits and where to fix it; the icon carries the warning colour and the text stays primary, because warning text on its own 10% tint is under 3:1.
  • Creator DOM, so --sjs2-* tokens only (§9), checked by a test that rejects literal colours and var() fallbacks. Font is inherit: the token font is not loaded in the Hub.

Recipe: list page

Title + description + primary action above a DataTableSurface; toolbar (search, filters, Reset) in DataTableToolbar; titled empty state; PagedTableFooter. Reference: features/platform-admin/list-tenants/.

Review queue — a list whose items each wait for a decision. Reference: features/platform-admin/list-signup-requests/.

  • Open on the work. The default filter is the undecided subset; it is the URL default, never a parameter and never counted as an active filter. The filter Select lists it first, closed states after, All statuses last.
  • Decision states use the status vocabulary: waiting attention, accepted on, declined off.
  • One row badge, the most urgent fact — the decision, unless the process behind it needs the reviewer (Setup failed, attention) or is still running (Setting up, off). The panel shows both.
  • Columns appear when they have data ("Decided by" and "Decided" hidden on the pending view).
  • One entry point per row, never decision buttons in the row. Review (secondary) when there is something to do, View (ghost) when closed; both open the Review-and-decide panel.
  • Say only what the page can do — the description names shipped actions only.

Recipe: review and decide

Any record awaiting a human decision with an audit trail (signup requests today; access requests, approvals, refunds tomorrow): review → decide → outcome in one ResponsivePanel (desktopType="complex"). Reference: features/platform-admin/review-signup-request/.

  1. Header — the record's identity as title; what it is and when it arrived as description.
  2. At most one status strip — the result of what the reviewer just did, otherwise a standing problem. Never two.
  3. PanelSections in the order the record lived: Request (what was submitted; carries the state badge only while undecided) → Evidence (optional; see Evidence from third-party tools) → Decision (who, when, why, badge in aside) → Downstream process (what the decision produced, its badge, a link to where it now lives).
  4. Footer — only the next step the record allows (Reject… outline + Approve… default while undecided, Retry … after a failed process, Check again while running, nothing when closed).
  • Decide steps are steps in the same panel, each with Back. The positive commit is default; a rejection commit is destructive because it is final. The form states its consequence once (what gets created, who is notified, that the decision is recorded under the reviewer's name and cannot be undone). A rejection reason is required and says who reads it.
  • Outcome: return to the review step showing the updated record, the strip naming what happened (success / destructive if a process failed / info while running), and the reviewer's own name in the Decision section.
  • A retry is not a new decision — it records no new decider and no new decision time.
  • The outcome keeps everything the review showed. Decision actions return the same view model as the list loader, so fields the Hub adds (evidence references, links) never vanish when the panel shows the result (project-structure.md "Signup request slices").
  • One state mapping in one file (describe*, e.g. signup-request-state.ts) owns decision → tone, process → tone, the row badge and the allowed next step. Grid and panel both read it, so a Setup failed row always opens on a panel offering Retry. Same for submissions: describe-collection-status.ts owns code → group → tone and whether Review applies.

Recipe: read-only settings page

"Let an operator review resolved configuration" (Admin → Environment, Auth, Storage, Email). Reference: features/platform-admin/view-environment-settings/ui/.

  1. PlatformAdminShell — eyebrow, headline, one-sentence purpose, Separator. Never hand-rolled.
  2. Overview strip — one full-width card answering "is anything wrong?": one runtime fact, one rollup badge (3 of 4 configured), a plain list of what is missing. Not a KPI dashboard.
  3. Section cards in .grid-card-list, h-full. Full width only for content that needs the measure (a table, a long form).
  4. Rows on a nested surface — dl with grid gap-4 rounded-lg bg-muted/40 p-4, following Displaying values.

Recipe: tenant settings page (review and change)

Pages under app/(main)/settings/…. Reference: features/export/manage-export-formats/ui/export-formats-settings.tsx. A record-scoped collection (a form's audience) is a page of a record workspace instead, with its lists as views.

  1. Masthead — h1.text-3xl.font-semibold.tracking-tight + muted one-sentence purpose in page.tsx (a SettingsPageHeader waiting to be extracted — do that as its own change).
  2. A Card per standalone control, the control constrained (max-w-md).
  3. A list section per collection (list-page recipe, no Card around it).
  4. Create/edit via ResponsivePanel (PanelForm), delete via AlertDialog.
  5. Sections in the order the reader sets things up — a choice that later locks (the match key) before the lists that depend on it.

A row's identity column carries the name plus inline state badges (Default), not a name stacked over a pill.

Recipe: record workspace

A record that has several pages — a form's Overview, Submissions, Participants, Analytics, Settings — is one workspace. The reader moves between them many times in one session, so every page is one menu away from every other, without spending a row of the page on navigation. Editing the record's content (the form designer) is not one of those pages: it is an immersive editor. References: features/forms/form-workspace/, app/(main)/@header/forms/[formId]/. It applies Navigation & wayfinding and Page masthead (above) to a record; this list adds what is specific to records.

  • Location, then aspect. The header reads Forms › folder › record │ page ▾: the trail ends at the record as the current crumb, and the record's pages are a NavSwitcher past a vertical divider, each with its icon (NAV_ICONS), the current one checked and on a hover surface so it reads as a control. Pages appear by flag, never disabled.
  • Record actions live in the header, the same on every page. Design is the one primary. Share is outline beside it from md up; below that it is the first item of the … menu, with Save as template and Delete. The form card's … menu matches that pair and adds Move to folder (a list action). Reference: form-record-actions.tsx, form-card.tsx.
  • The Overview is facts, not settings: StatCards for what a reader checks first (§5 Fact cards). Edits live on a Settings page.
  • A record's sheet on a list is a read-only preview (§5 Overlays): its name, the same fact cards, the list of its pages, and a footer of Share link (the public page in a new tab, as on the record's card) + the editor entry. A sheet holding the settings form becomes a second, cramped settings page. The sheet re-reads the record when it opens and skeletons the fact cards until that read lands (§6 Fresh facts in a preview).
  • An immersive editor is entered by a button, never a page in the switcher. It takes the whole screen with its own chrome (Creator's tabs and sidebars) and saves explicitly, so it shows no workspace navigation — more chrome would crowd it and every extra exit is a way to lose unsaved work. Its one exit goes back where the reader came from: the entry link carries ?from=<page>, Back says where it goes ("Back to Participants") and asks first when there are unsaved changes.
  • Views inside a page are LinkTabs with a count per view and a ?view= URL, the page's main task first and as the bare URL (Participants, then Properties). Each view has its own primary action.
  • A setup choice that later locks is a card until it locks, then a clause in the list's description (§6 Controls & consequences).

Recipe: create / edit overlay

A settings page asks "what is true?"; an overlay asks "what do you want to be true?" — same masthead and vocabulary, rows become controls. References: features/platform-admin/create-tenant/ui/create-tenant-panel.tsx, features/platform-admin/update-tenant/ui/edit-tenant-sheet.tsx. Single-submit create with draft + lock + in-panel failure (the common case): features/audience/create-person/ (PanelForm + use-add-person.hook.ts). Wiring layers are in project-structure.md (PanelForm state).

  1. Header — title + one sentence describing the current step. The title names the task (Add participant, Edit participant, Rename property), not the record: the record's identity is the first section, so it is said once, with its label and type.
  2. PanelSteps (multi-step only) — the progress track, first in the body.
  3. PanelSection per concern — icon, title, optional description, optional aside for status, on bg-surface-container-low. One icon per section, none on fields.
  4. Closing Alert when the step has a consequence worth stating.
  • An edit overlay mirrors its create overlay. It has the same sections in the same order under the same titles and icons. A field that became fixed on create is shown as a locked row in that section (Controls & consequences). Add participant's Participant section holds the identifier input, and Edit participant's holds the identifier as a locked row. The reader recognises the shape, and one concept keeps one section name.
  • A section owns its own surface. Shared field groups (TenantAccessFields) render their own PanelSection; call sites never wrap them in a tinted div.
  • Multi-step: show the track, don't narrate "Step 2 of 3". Step labels are nouns matching the section titles. The last input step is a review built from SummaryRow. The terminal step is an outcome, not a form: drop the track, lead with a success Alert naming what was created, and hand over the one artefact the user came for (e.g. the sign-in URL).
  • A multi-step form is still one PanelForm. The slice hook owns the step and hands the panel that step's header sentence, submit label and handlers. From step 2 the secondary button is Back (onBack), never Cancel: the earlier choices are still there. The outcome step has one button, Done (cancelable={false}), because Cancel would offer to undo what already happened. Continue is disabled until the step can be left. A new step opens at the top of the body (PanelSteps scrolls itself into view), not at the previous step's scroll position. Steps are an ordered list, so a later step slots in without renumbering the others. Reference: features/audience/import-csv/use-import-csv.hook.ts.
  • Nothing is written before the last input step. Earlier steps only read and choose, so closing the panel on any of them costs nothing. The one exception is a step whose records the write needs to exist first (an import's New properties): its Continue names the write with a count ("Create 2 properties"), and closing before it still creates nothing. The review step's primary names what it will do with a count ("Import 20 rows"), not "Confirm".
  • State is not in the chrome. PanelForm does not own field values. A slice hook (or, for a multi-step outcome, the panel itself) owns the draft, open/reset, and the write; the feature's mutation helper owns pending / in-panel error / toast + refresh. See PanelForm state in project-structure.md.

Configure and run (export today; bulk actions tomorrow; a file import is below) — an overlay whose commit is an operation, not a saved record. Reference: features/export/export-submissions/ui/export-dialog.tsx.

  • ResponsivePanel desktopType="complex": format + filters are 3+ fields.
  • A PanelSection per question the reader answers — what file (File: format, language), which records (Submissions: status, test, date ranges). Say where prefills came from in the section description ("Prefilled from the filters on the submissions table").
  • Opened from a list, the records section starts on the list's filters and stays honest about them. Reference: SubmissionsSection in features/export/export-submissions/ui/export-dialog-filters-form.tsx.
    • Same values, same controls: the list's Status facet is the dialog's Status field, its dates are the same date ranges.
    • A list filter the flow cannot apply is named in the description, by its toolbar name, only while it is active: "Its Review and Submitter filters don't apply to exports, so the file can include rows the table hides." The list computes the names (tableOnlyFilters); they are shown, never sent.
    • Once the reader changes a prefilled value, the description says "Changed from the filters on the submissions table." and the section aside offers Use table filters — a ghost button with type="button" (the dialog is a form) that restores every prefilled value and clears their errors. A value the dialog hid itself (Completed at, when no complete status is chosen) is not a change the reader made.
    • Opened without a list, the description says what to choose ("Choose which submissions to export."), never "Prefilled".
  • Opens on the primary action (Overlays rule 9); runs as in Progress inside a panel.
  • Readiness problems replace the form with one Alert and the one step that fixes them (Prepare for export); maintenance entry points (Rebuild reporting data…) are a ghost button after the sections.
  • Same noun as the list it came from — the dialog exports submissions, so it never says "responses".

Import from a file (form participants today; data lists and other bulk loads tomorrow) — the reverse of export: a file the reader brings, read into records they already have. It is a multi-step create overlay (above) whose steps answer, in order: which file, which column is which, what will happen. Reference: features/audience/import-csv/.

  • Steps: File → Columns → Review → outcome. A question the file raises later (new properties, what to overwrite, rows nobody matched) is its own step before Review, named for the question. The panel opens from an outline button beside the list's primary create action, since importing is the second way to add.
  • State the limits before the file is chosen. The file field's help line says the row limit and that the first row names the columns. Once a file is read, the same line says what was read (panel.csv: 20 rows, 12 columns.). A file that cannot be imported (no header, no rows, over the limit) is that field's error, in the line, with what to do. It is not an alert, because the reader fixes it by choosing another file.
  • The browser reads to preview; the server decides. Parse the file in the browser for the header, a sample and the row count, with a real CSV reader (quoted commas and line breaks). Refuse what the server certainly refuses (over the limit) before sending it. Every other check belongs to the server, and its answers come back as rejected rows.
  • Every choice is made against real values. Under each column, its help line shows its first values from the file, · apart because a value may hold a comma ("Values like London, UK · Leeds"). A column name alone does not tell the reader what the column holds.
  • Suggest, say so, never guess. The identifier column is suggested from its name ("Suggested from its name."). Each other column is matched to the target whose key its name produces (Family size → family_size). When nothing matches, the identifier select stays empty with a placeholder and Continue waits. A wrong silent guess would match every row to the wrong person.
  • Map from the file's side. One row per column, in file order: its name (monospace, a literal), its sample, and a select of targets with Don't import first, then Create new property…. A target fed by one column leaves the other columns' selects, so two columns can never fill one target. A column named like no target starts on Create new property…. The section aside keeps a running tally ("4 mapped, 2 to create, 1 ignored"), so a column left unhandled shows.
  • A new target is suggested, then confirmed. The New properties step appears only when a column is queued. Each row has a name (the tidied heading) and a type suggested from every value in the file, with its evidence in the help line ("Suggested from values like A · B: 2 distinct values."). A name something already holds (a form question, a property, another new row) is a warning with a Use <free name> button, never a block; only a name with no letter or digit holds Continue. A date whose day and month could swap never suggests date.
  • What is read by convention is listed, not offered. Columns the server maps by their names (brands__nike for a choice property) appear read-only under the selects, so the reader knows they will be imported. A target the file cannot fill yet is named in the section description, with the column name it would need.
  • What happens to existing records is chosen with the columns. Each overwrite choice is a RadioGroup with the safe option first, marked "(recommended)" and preselected, and the destructive one never preselected ("Empty cells in your file": keep or clear; "Properties not in your file": leave or clear). A choice that cannot apply (a test import skips existing records) is not shown. The choices go with the start and cannot change after it.
  • Review is built from the choices, as SummaryRows: the file, its rows, the identifier column, each target with the column that fills it, and the columns left out ("Not imported"), so a forgotten column shows before anything is written. Then one consequence Alert (info) on how rows meet existing records: what they are matched by, that an existing record is updated rather than added twice, and that a rejected row does not stop the others. The overwrite choices follow, read-only, with Back to change (it cancels the checked import and returns to the choices; the next start is a new import). When the check finds existing records, a checkbox says how many will be updated and that this cannot be undone, and the primary button (Import N rows) stays off until it is ticked.
  • The outcome is shown in the panel. No toast, and the list behind it is refreshed. The batch Alert is success only when nothing was rejected, otherwise warning. Its sentence gives the counts that are not zero ("18 added, 2 updated, 3 rejected") and what to do next. Rejected rows follow in a StaticDataTable (Line, Reason), numbered as in the file. When the server reports only the first rows, the section says "The first 50 of 1,290". Its DownloadMenu (Download CSV) saves every rejected row with its line, reason and the file's own cells (Hand over a file). The footer is Done.
  • When a file outgrows the request, the import becomes a page. A load the server must run as a background job (more rows than one request takes, or a check of the whole file before mapping) needs progress that survives the tab closing. It moves to its own route (…/audience/import) with the same steps and rules. The panel is right only while the import finishes within one request.

Recipe: file answers

A SurveyJS file answer (features/submissions/ui/answers/file-answer.tsx) follows Files & media: FileViewer size="small" tiles (h-40, min-w-40–max-w-72), per-kind preview (image; video first frame + play badge; inline AudioPlayer; FileKindIcon + label for PDF/other).

  • The whole tile is one button (View details for <name>) opening SubmissionFileDialog — never the raw storage URL. Audio's player stays interactive, so its caption is the button.
  • The dialog shares the files-list frame (FilePreviewDialog + SubmissionFileView): ResponsivePanel desktopType="simple" widened to sm:max-w-4xl, title = file name, description = MIME type, preview capped at max-h-[min(55vh,40rem)] so File details (PanelSection of SummaryRows: Stored as, Question, Size) and Download / Open in new tab stay in view.
  • Files outside submission storage (data: values, external URLs) open the plain preview without the details panel; so does a failed lookup.
  • PDF export: features/pdf-export/submission/answers/pdf-file-answer.tsx (image row packing, downscaling, link stamping in attach-pdf-file-links.ts).

Recipe: public status pages

Every page a non-Hub reader sees instead of what they came for — a respondent on /share or /embed, a /view / /edit link recipient, a failed PDF export. Rendered by PublicStatusPage; inventory and wiring rules: components/public-status/README.md.

Audience Brand Component
Hub users (signed-in operators) Endatix — sheep, primary eyebrow, watermark, diagnostics ErrorPage
Public readers (a customer's audience) The customer's — Endatix only as "Powered by" PublicStatusPage

Anatomy — one centred column: icon in a soft-tinted circle (same situation → same glyph on every route) → one-sentence h1 title → one or two muted sentences → at most one neutral action, only when the reader can act (Sign in, Try again) → optional PublicStatusReference support id → optional quieter note ("You can close this tab.") → "Powered by Endatix" footer.

  • No Endatix brand in the content — no mascot, no Hub primary, no Hub navy.
  • No HTTP status, no raw error text. The sentence is the whole answer; support gets a digest or trace id.
  • Three tones by what the reader should feel: success (they are done), neutral (it cannot work and nothing is broken — closed, denied, expired, not found), warning (something failed; retry may help). A closed survey is never red.
  • Copy: what happened, then what to do, using the link's own verb (an /edit link says edit).
  • Host copy is all-or-nothing — show host title + detail verbatim only when both exist.
  • Light/dark follows the reader's OS, never the Hub's stored theme; embed is light and opaque.

7. Review Checklist

Before finishing UI work, check:

  • Only semantic tokens; any new token is registered in @theme inline (§2).
  • No 1px sectioning borders, no Card inside an overlay or around a table (§2, §4).
  • Every state is a StatusBadge in one of four tones, the same label everywhere; many codes are grouped and the group picks the tone; only the lifecycle is called "Status" (§5).
  • File deliverables carry FileKindLabel on every surface; unknown kinds get the generic glyph (§5).
  • Peer cards use .grid-card-list, not viewport breakpoints (§5).
  • Lists use components/table; the empty state has the list icon, a title and a way out (§5).
  • A facet over states shows the column's badges; a grouped lifecycle filters group first, with group labels distinct from code labels; old filter URLs still work; a form reuses the facet as a labelled field (§5 Filters).
  • A flow prefilled from a list takes its values exactly, names list filters it cannot apply, and offers "Use table filters" once changed (§6 Configure and run).
  • Record lists are read-only rows with named row actions; edits open an overlay, deletes an AlertDialog that names what goes with it (§5, §6).
  • Typed values use typed controls, and an optional value can be emptied (§5 Inputs).
  • Overlays follow the table in §5, never stack, and have a title and description.
  • A record with several pages switches pages from the header trail's dropdown; the masthead is the page's name; its Overview is fact cards and its sheet a read-only preview; an immersive editor is entered by a button, shows no workspace navigation and returns where it was opened from (§6 Record workspace).
  • Each move uses its one control (trail, switcher, view tabs, editor button); every view a reader would share is a URL; no tab rows, no Home crumb, no "Back to …" between siblings; a URL return target is checked against known values (§6 Navigation).
  • The masthead is one row: the page's name, a description only if it adds something, the page's own actions; record-wide actions sit in the header (§6 Page masthead).
  • Destinations the tenant lacks (flags) are hidden; controls that cannot apply yet are disabled with a reason (§6 Controls).
  • A preview panel is read-only; a follow-up that would open a second overlay is a link or a view instead (§5 Overlays rule 12).
  • Fact cards hold facts, not actions; a card that leads somewhere is a whole-card link with the corner arrow; peer cards fill their row (§5 Fact cards).
  • Inline links are TextLink; external ones use external; nothing links to an unconfigured or unconfirmed target; links to our own sites carry UTM tags and a click event (§5).
  • Occasional reference facts sit behind one menu item and load on open, not in the sidebar (§6).
  • Sequences of steps use Timeline (one subject, oldest first, one active step, words not event names) — never for a bag of facts, a status, or a form's own steps (§5).
  • A further read inside a panel skeletons only its section, starts after paint, and is asked once per opened record (§6).
  • An overlay opened on a list row re-reads the record on every open, skeletons only the volatile facts, and keeps the snapshot quietly if the read fails (§6 Fresh facts).
  • Values the reader came for wrap, never truncate; unset vs empty are distinct (§6).
  • Third-party evidence loads on open, never blocks the record, shows no personal data beyond the decision's need, and disappears when unconfigured (§6).
  • Disabled controls say why; warnings are reachable; consequences stated once, on the control they follow from when there is one (§6).
  • Help text is a visible line under the label, for every sibling or none — no Info tooltips (§6).
  • Running work: spinner + stage verb on the button, sentence in the header, nothing repeated in the body; the panel is not dismissible until it ends (§5 Overlays, §6).
  • A batch with failures reports warning with counts, not success (§5).
  • A file import states its limits before the file, shows sample values under every column, says where each suggestion came from, writes nothing before Review, names the count on its button, and shows the outcome and rejected rows in the panel (§6 Import from a file).
  • Files go out through DownloadMenu and the shared download helpers; CSV carries a BOM and re-importable headers; a file that is the only copy is saved the moment it exists and said so (§6 Hand over a file).
  • A multi-step overlay shows Back from step 2 and only Done on its outcome (§6 Create / edit overlay).
  • An edit overlay is titled by its task and mirrors its create overlay's sections. Values it cannot change are LockedValue rows, never disabled inputs, and a copy of the record's key is not a field; where fields are listed, it is pinned first with a role tag and says why (§5 Chips, §6 Controls, Create / edit overlay).
  • No presigned URL outlives the view that signed it (§6).
  • Public pages use PublicStatusPage and have their own error.tsx (§6).
  • Seen in the running app: screenshots at desktop width and below 768px for overlays, in light and dark. The Hub's theme is the user's setting, not the OS scheme — switch it in the app; a browser prefers-color-scheme emulation leaves the Hub light.
  • A new shared component has a row in the §5 index; a new decision is written back here as a general rule.

8. Where the details live

Topic Document
SurveyJS / Creator theme sync, token maps, palette checklist lib/themes/README.md
Public status inventory, embed/theme wiring, "Powered by" components/public-status/README.md
Hub error pages (ErrorPage), auth screens (AuthStatus) AGENTS.md "Error page chrome", "Auth pages"
List URL state, paging, loading skeletons project-structure.md "List pages and tables"
Where a shared UI component should live project-structure.md "Where UI for a shared concept lives"

9. SurveyJS Theming (summary)

Full guide: lib/themes/README.md — read it before touching lib/themes/, Creator CSS, or any SurveyJS surface.

  • app/globals.css is the source of truth; Creator and Hub-internal survey themes derive from it via --sjs2-* source tokens only (lib/themes/endatix-themes.ts).
  • Public /share and /embed do not load globals.css; Hub values in theme objects are var(--token, <literal>) via hubToken(), and a test pins the literals to :root. When the palette changes, change both.
  • Hub CSS injected into Creator DOM names --sjs2-* tokens only, with no literal fallback. A mark on a canvas question follows §6 "Marking a question on the designer canvas".
  • Every Hub dialog is a shadcn Dialog / AlertDialog, never settings.showDialog.