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".
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.
- 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.
- 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.
- Tokens, never palette steps. Everything must work in light and dark from
app/globals.css. - Tone carries meaning; decoration does not. Colour is reserved for status. Icons mark sections and kinds of things, not individual fields.
- 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.
- 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:
- Does a sibling page already solve it? Match it. Cross-page consistency beats a locally nicer idea.
- 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.
- What is the page for? Principle 1.
- Can you remove something instead? Principle 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).
- 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.
- 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_lowagainst asurfacemain 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">).
| 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.
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.
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).
- Tonal layering first (§2). A raised element never sits inside another raised element to
express one boundary — no
Cardin an overlay, noCardaround a table. - Ambient shadow for floating elements (command menu):
shadow-[0_8px_30px_rgb(0,52,94,0.06)], tinted withon_surface. Never#000shadows. - Ghost border when containment is required for accessibility:
outline_variantat 15% opacity. Never a 100% opaque border. - Glass for floating chrome (nav bars, dropdowns, modals):
bg-surface/80 backdrop-blur-xl(orsurface_container_lowestat 80% +backdrop-blur-md).
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.
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 |
destructiveis 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 leadingsize-1.5 rounded-full bg-currentdot. 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) isidle, still collecting (In progress,Expired) isattention,Completeison, ended without completing (Screened out,Quota full,Abandoned,Cancelled) isoff— 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.
idleis only the first step of a lifecycle — the record exists and nothing has happened to it. It is quieter thanattention(no one has to act) and must not read asoff(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"}, useStatusBadge. - Alerts use the same mapping:
infofor a consequence or a view choice,warningfor a risk the operator is choosing,successfor a completed write,destructivefor a failure. Neverinfofor a security-relevant choice. - A batch that finished with some failures is
warning, notsuccess— 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).
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).
- All or none. Every option in a list gets a mark, or none do.
- 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.) - Never guess. An unknown kind renders the generic file glyph; resolvers return
FileKindKey | undefined, never a defaulted icon. - Resolve the kind, not the icon. Feature code maps its vocabulary to a
FileKindKey(features/export/utils.ts) and never returns aLucideIcon. - Specific source first, coarser fallback (wire key
csv-shojibefore delivery enumCsv). - Catalog stays server-safe.
lib/file-kinds/index.tsdoes not re-export icons; import glyphs from@/components/common/file-kind-icon. - Same format → same label on every surface (
FILE_KINDS.xlsx.label=Excel (XLSX)). When aSelectItem's children are aFileKindLabel, settextValueto that label.
overlay(default) for a normal-width field with spare room;inlineas 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.
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
BackToTableButtonrestores list state). - External links say they leave:
TextLink externalopens a new tab (rel="noopener noreferrer"), adds a trailingExternalLinkmark and ansr-only"(opens in a new tab)". Never hand-rolltarget="_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>andutm_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, andnoreferrerdrops 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.
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
DataTableSurfaceas plainh2+p+Button. ACardis for controls and prose. - Class-name helpers before TanStack. A handful of static rows needs
DataTableSurface+StaticDataTable(the helpers, assembled), not a table instance. PassisStatic: trueto the header helper when you hand-roll the header and it never scrolls under sticky positioning. - Zebra parity is
index % 2 === 1, matchingDataTableGrid. - 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 toC…and the reader loses the one column they scan first. Icon-only columns stayw-12. - A per-row control that cannot apply to this row yet is
—with ansr-onlyreason ("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
Actionscolumn (DataTableRowActions). Eacharia-labelnames 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
—withsr-only"Not set", and the table scrolls inoverflow-x-autoinstead 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(toneon 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'sStatusDotand 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 ownLabel 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 throughdescribedBy. 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.
onClearFiltersresets 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-basetitle,EmptyMedia variant="icon"onbg-muted); the page-levelEmptyis 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:SignupRequestsEmptyinfeatures/platform-admin/list-signup-requests/.
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-fillalso scales to ultrawide screens with one knob instead of a breakpoint ladder. auto-fill, notauto-fit— card width must not depend on card count.- Keep the
min(…, 100%)guard, or narrow containers overflow. - Set
--grid-card-minfrom the card's narrowest legible content (default 380px; below ~320px only for tiny tiles). Three columns need3 × 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-fullso a row shares a bottom edge.
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,Exportand 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/10tile — the one place a card carries an accent; the card itself staysbg-cardwith its ghost border. - A card that leads somewhere is the link, as a whole, marked by
ArrowUpRightin 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-listwith a--grid-card-minchosen 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).
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 (StatusBadgeorAlert), 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 arefont-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 externalaway). - 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
primaryat 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.
| 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 |
- Use
ResponsivePanel—desktopType="simple"(Dialog) or"complex"(Sheet). If a Dialog scrolls on desktop, it should be a Sheet. - Never
side="bottom"on a Sheet for mobile — swap to Drawer for Vaul's touch behaviour. Never a Drawer on desktop. - One scrollable body; the footer stays outside it.
- Every overlay has an accessible title and description.
- 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.
- Widen a Dialog with an
sm:prefix (sm:max-w-4xl) —DialogContentshipssm:max-w-lgand an unprefixed class loses to it. - Every Hub dialog is shadcn — never a SurveyJS popup (§9).
- 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 guardonOpenChange, and never leave a visible close control that silently does nothing. - A short panel gets a short Drawer.
ResponsivePanelsizes the Drawer at90vhfor forms; a few rows of reference passdrawerContentClassName="h-auto". - An overlay opened from a menu is rendered outside the menu. Keep its
openstate in the component that owns theDropdownMenu, set it from the item'sonSelect, and render the panel as the menu's sibling. InsideDropdownMenuContentit unmounts when the menu closes. - 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. - 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 linkopens 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: primary (
primary/on_primary, no shadow) for the one high-intent action; secondary (secondary_container); ghost (primarytext) for low emphasis;destructiveonly 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 areoutline. A view (§6 Record workspace) counts as a page:Add participantis primary on a form's Participants view,Add propertyon its Properties view. - A record's main action sits in the header's action area and is always primary (
Designon every form page). The page's own create action stays in the page. A button that goes to another page is aLinkstyled as a button (Button asChild), so it can open in a new tab and shows its URL. - Inputs:
surface_container_lowfill; on focus the ghost border goes from 15% to 100%primary. Labelslabel-mdinon_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-timedatetime-local, a numbertype="number", a yes/no aSelect(Yes/No), a choice from a list aSelector checkboxes. Free text is for text only. An optional value can always be emptied: a select carries an explicitNot setfirst 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-localhas 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-fullto distinguish from buttons. Status tags areStatusBadge, and its dot marks a state. A role tag says what a row is, not its state (Identifieron the property that copies the match key). It is aBadge 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.
Cross-cutting patterns first; recipes after them only add what is specific to their shape.
- Align label → value. Label left, value right-aligned into one scannable column
(
SummaryRow, ordt/ddwithjustify-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-allfor ids/URLs/emails,break-words whitespace-normalfor prose). Truncate only secondary text, with the full value intitle. - Unset ≠ empty. Never configured →
—withsr-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-variantsub-label under the human label — on every row, secrets included. A row ofCircleHelpicons is noise standing in for design. - Help is visible text, not a tooltip. What a field means goes in one
text-xs text-muted-foregroundline under its label or legend, wired witharia-describedby. Siblings get one each or none (three date ranges → three lines). AnInfoicon on one label is decoration. - Literal values are monospace. Nested detail rows indent
pl-4intext-xs text-muted-foreground— no left-border rule. - A value keeps its type everywhere — a state is a
StatusBadge, a language aLocaleLabel, a format aFileKindLabel, an id aTruncatedId, a product version aReleaseVersionLink. - 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 areh-auto, and the grid scrolls inoverflow-x-autorather 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 aClientEndatixConfigfield 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.
- A control that cannot take effect is disabled, with one
text-xs text-muted-foregroundline 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
Alertabove 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
Lockedbadge where the reader works (the audience match key in the Participants description). - Immutability belongs on the field it constrains (a
Lockedbadge + 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
SummaryRowwhose value is wrapped inLockedValue, copyable when it is a key or an id, with onetext-xsline 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,
emailorexternal_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 anIdentifiertag 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-onlySummaryRow(copyable) with aLockedbadge 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
AlertDialogstays 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
StatusBadgein itsaside; 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 visiblen / maxcounter, and a description saying who will read it. - Errors land where they belong. Field validation under the field (
aria-invalid,aria-describedby); anything else adestructiveAlert at the top, with the form keeping its values —PanelFormputs 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, notCancel, 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).
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
Homecrumb), 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 fromnav-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.
h1names 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.
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
simpleResponsivePanel: title names the thing ("About Endatix"), the description says when it is useful ("Include them when you report an issue"), the body isSummaryRows on a nested surface. - Read on open, never on page load, and nothing reaches public HTML or the client bundle.
next.config.tsresolves the build and passes it throughenv, which inlines it whereprocess.env.HUB_*is read: server code only (lib/hosting/hub-version.ts), so it lands in server chunks. Never assignprocess.envinnext.config.ts: a standalone server does not run that file, so the values are gone in production.scripts/release-prepare.shfails 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 saysunavailablefor it. - A release shows its version; any other build shows branch and commit. A release
(
0.8.0,0.8.1-canary.3) is aReleaseVersionLinkto its notes. A build that is not a release is for developers:BuildRefputs the branch and the commit on their own right-aligned lines, each after its git mark (GitBranch,GitCommitHorizontal), asTruncatedIds: 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 givesmain @ <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 oneCopyToClipboard(inline) in itsasidethat 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 mutedtext-xsheading "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 thesurvey-libraryrelease) 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.
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
PanelSectionmasthead; replace only its body withSkeletonbars shaped like the rows to come, mark itaria-busy, and add ansr-onlyline naming the wait ("Loading visitor details"). On a tinted section (bg-surface-container-low), tint the bars (bg-foreground/10): the defaultbg-accentmatches 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
destructivebelongs 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—.
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 ansr-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.
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
successAlertnaming what was produced ("CSV file downloaded"), footerDone. 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
warningwhen rows may be missing.
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 aDropdownMenuRadioGroup; mark the stored value (mutedSubmittedsuffix). - No choice, no control — a single option renders as plain, named text.
- Diverging from the record is
info, neverwarning: oneAlert variant="info"strip,role="status", naming both values, with a one-click way back ("Show in Spanish"). Solidwarningis 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.
- 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.modifiedAtmoves 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 toLast 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.
- 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 anhrefthat 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.
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 anoutlinebutton that names it with its file mark ("Download CSV"). Several formats are aDownload ▾menu whose items areFileKindLabels. 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 withwriteCsv(lib/utils/csv.ts) and saved withdownloadText. 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
emailorexternal_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
successAlert ("20 links downloaded … It is the only copy"). Then it offersDownload CSVagain while it stays open. Before the run, oneinfoAlert says the file will be the only copy and who can use it. Nothing new to hand over isinfo("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.
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'sTextLink externalinaside, 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
Timelineof 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.
- Never crop an upload —
object-containonbg-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.
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'saria-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
pointerdownandclickso the designer does not select the question instead, and shows a--sjs2-color-utility-a11yring 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 andvar()fallbacks. Font isinherit: the token font is not loaded in the Hub.
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
Selectlists it first, closed states after,All statuseslast. - Decision states use the status vocabulary: waiting
attention, acceptedon, declinedoff. - 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.
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/.
- Header — the record's identity as title; what it is and when it arrived as description.
- At most one status strip — the result of what the reviewer just did, otherwise a standing problem. Never two.
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 inaside) → Downstream process (what the decision produced, its badge, a link to where it now lives).- Footer — only the next step the record allows (
Reject…outline +Approve…default while undecided,Retry …after a failed process,Check againwhile running, nothing when closed).
- Decide steps are steps in the same panel, each with
Back. The positive commit isdefault; a rejection commit isdestructivebecause 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/destructiveif a process failed /infowhile 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 aSetup failedrow always opens on a panel offeringRetry. Same for submissions:describe-collection-status.tsowns code → group → tone and whether Review applies.
"Let an operator review resolved configuration" (Admin → Environment, Auth, Storage, Email).
Reference: features/platform-admin/view-environment-settings/ui/.
PlatformAdminShell— eyebrow, headline, one-sentence purpose,Separator. Never hand-rolled.- 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. - Section cards in
.grid-card-list,h-full. Full width only for content that needs the measure (a table, a long form). - Rows on a nested surface —
dlwithgrid gap-4 rounded-lg bg-muted/40 p-4, following Displaying values.
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.
- Masthead —
h1.text-3xl.font-semibold.tracking-tight+ muted one-sentence purpose inpage.tsx(aSettingsPageHeaderwaiting to be extracted — do that as its own change). - A
Cardper standalone control, the control constrained (max-w-md). - A list section per collection (list-page recipe, no
Cardaround it). - Create/edit via
ResponsivePanel(PanelForm), delete viaAlertDialog. - 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.
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 aNavSwitcherpast 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.
Designis the one primary.Shareisoutlinebeside it frommdup; 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
LinkTabswith 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).
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).
- 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. PanelSteps(multi-step only) — the progress track, first in the body.PanelSectionper concern — icon, title, optional description, optionalasidefor status, onbg-surface-container-low. One icon per section, none on fields.- Closing
Alertwhen 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, andEdit 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 ownPanelSection; call sites never wrap them in a tinteddiv. - 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 asuccessAlert 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 isBack(onBack), neverCancel: the earlier choices are still there. The outcome step has one button,Done(cancelable={false}), because Cancel would offer to undo what already happened.Continueis disabled until the step can be left. A new step opens at the top of the body (PanelStepsscrolls 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
Continuenames 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.
PanelFormdoes 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 ownspending/ in-panelerror/ toast + refresh. See PanelForm state inproject-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
PanelSectionper 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:
SubmissionsSectioninfeatures/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
asideoffers Use table filters — a ghost button withtype="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
Alertand 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
outlinebutton 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 andContinuewaits. 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 importfirst, thenCreate 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 onCreate new property…. The sectionasidekeeps 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 holdsContinue. 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__nikefor 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
RadioGroupwith 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 consequenceAlert(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, withBack 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
Alertissuccessonly when nothing was rejected, otherwisewarning. Its sentence gives the counts that are not zero ("18 added, 2 updated, 3 rejected") and what to do next. Rejected rows follow in aStaticDataTable(Line,Reason), numbered as in the file. When the server reports only the first rows, the section says "The first 50 of 1,290". ItsDownloadMenu(Download CSV) saves every rejected row with its line, reason and the file's own cells (Hand over a file). The footer isDone. - 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.
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>) openingSubmissionFileDialog— 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 tosm:max-w-4xl, title = file name, description = MIME type, preview capped atmax-h-[min(55vh,40rem)]so File details (PanelSectionofSummaryRows: 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 inattach-pdf-file-links.ts).
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
/editlink says edit). - Host copy is all-or-nothing — show host
title+detailverbatim only when both exist. - Light/dark follows the reader's OS, never the Hub's stored theme; embed is light and opaque.
Before finishing UI work, check:
- Only semantic tokens; any new token is registered in
@theme inline(§2). - No 1px sectioning borders, no
Cardinside an overlay or around a table (§2, §4). - Every state is a
StatusBadgein 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
FileKindLabelon 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
AlertDialogthat 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
Homecrumb, 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 useexternal; 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
Infotooltips (§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
warningwith counts, notsuccess(§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
DownloadMenuand 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
Backfrom step 2 and onlyDoneon 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
LockedValuerows, 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
PublicStatusPageand have their ownerror.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-schemeemulation 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.
| 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" |
Full guide: lib/themes/README.md — read it before touching lib/themes/, Creator CSS, or any
SurveyJS surface.
app/globals.cssis the source of truth; Creator and Hub-internal survey themes derive from it via--sjs2-*source tokens only (lib/themes/endatix-themes.ts).- Public
/shareand/embeddo not loadglobals.css; Hub values in theme objects arevar(--token, <literal>)viahubToken(), 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, neversettings.showDialog.