← designauthority.seanyong.xyz
The central, app-agnostic UI design authority for these products.
| ask | expected | got | resolved to | |
|---|---|---|---|---|
| pass | show whether a request is waiting for approval | COMPOSE | COMPOSE | recipe/status-with-text |
| pass | show a compact history of recent approval steps | RESOLVED | RESOLVED | component/tl |
| pass | let users enable or disable a rule | RESOLVED | RESOLVED | component/px-sw |
| pass | show an empty state when there are no requests | RESOLVED | RESOLVED | component/empty |
| pass | let users upload attachment files on a request | RESOLVED | RESOLVED | component/drop |
| pass | assign a reviewer with a searchable picker | RESOLVED | RESOLVED | component/cb |
| pass | make the sidebar navigation links show which page is active | RESOLVED | RESOLVED | component/nav-item |
| pass | show a message when the server cannot be reached | RESOLVED | RESOLVED | component/msg |
| pass | show the status of a request | COMPOSE | COMPOSE | recipe/status-with-text |
| pass | show the result of saving the settings form | COMPOSE | COMPOSE | recipe/feedback-redirect |
| pass | announce that a row was removed without reloading the page | COMPOSE | COMPOSE | recipe/feedback-inplace |
| pass | let users filter the requests list by category and status | COMPOSE | COMPOSE | recipe/filter-row |
| pass | we need a custom layout for the hero area before the designs arrive | FALLBACK | FALLBACK | fallback/plain-content |
| pass | add a progress bar for a long-running background job | RESOLVED | RESOLVED | component/progress |
| pass | add a gantt chart for the delivery schedule | UNDEFINED | UNDEFINED | |
| pass | make the corners rounded | CONFLICT | CONFLICT | prohibit/rounded-corners |
| pass | remove the focus outline from links | CONFLICT | CONFLICT | prohibit/remove-focus-ring |
| pass | use #ff6600 as the warning colour | CONFLICT | CONFLICT | prohibit/raw-color |
| pass | delete a saved template with a confirm dialog | CONFLICT | CONFLICT | prohibit/custom-confirm-for-entity-delete |
| pass | assign a reviewer to a request | RESOLVED | RESOLVED | component/select |
| pass | choose one owner from a list of people | COMPOSE | COMPOSE | recipe/assign-picker |
| pass | show how far a background scan has come and whether it is stuck | COMPOSE | COMPOSE | recipe/job-progress |
| pass | rejecting a request requires typing a reason | COMPOSE | COMPOSE | recipe/high-stakes-confirm |
| pass | a skip link to jump past the navigation | RESOLVED | RESOLVED | component/skip |
| pass | a panel sliding in from the edge with a record's details | RESOLVED | RESOLVED | component/sheet-end |
| pass | the chevron that reveals actions for a single row | COMPOSE | COMPOSE | recipe/row-actions |
| pass | a navigation link in the sidebar | RESOLVED | RESOLVED | component/nav-item |
Action trigger. Use a real button or link; variants (primary/ghost/danger/small), busy state via guardApply. Never a clickable div.
class .btn
· default
· hover
· active
· focus-visible
· disabled
· busy (guardApply)
Square icon-only control for compact toolbars and rows; must carry an aria-label.
class .iconbtn
· default
· hover
· active
· focus-visible
The one boolean control for enabling/disabling an entity; auto-submits and announces.
class .px-sw
· checked
· unchecked
· disabled
· focus-visible
Item inside a dropdown menu; sentence case; destructive items carry 'menu-item danger arm-del'.
class .menu-item
· default
· hover
· danger
· armed
· focus-visible
Sidebar/navigation link with icon, active rail state and aria-current.
class .nav-item
· default
· hover
· active(selected)
· focus-visible
Compact filter/selection token used in filter rows; distinct from badge (not a status).
class .chip
· default
· hover
· active(selected)
· focus-visible
Standard row for list/index pages: primary text, meta, optional actions.
class .index-row
· default
· hover
· active
· focus-visible
Data table with sticky headers; collapses to card rows (.mcards) on phones.
class .tbl
· default
· row hover
· selected
· reflowed (mcards)
Selection-only toolbar for batch operations; hidden until rows are selected.
class .bulkbar
· hidden
· shown with selection
Sticky footer for editors: primary Save plus Cancel; validation renders above, focused.
class .savebar
· sticky
· keyboard-lifted (JS transform)
Banner for server/redirect feedback; exactly ok/warn/err kinds.
class .msg
· ok
· warn
· err
Transient in-place feedback (one at a time) from the shared toast host.
class .toast2
· ok
· warn
· err
· auto-dismiss
Compact status label (uppercase micro-badge); pair colour with text, never colour alone.
class .badge
· neutral
· ok
· warn
· err
· acc
· solid
Empty state anatomy: title, one-line reason, at most one primary CTA.
class .empty
· default
Native dialog element for modals/confirms; static-backdrop variant available; dialog is the confirm primitive.
class .dlg
· open (showModal)
· backdrop
· wide variant
Tooltip for supplementary hints; hover/focus triggered.
class .tip
· hover
· focus-visible
Loading indicator for waiting states; pair with text describing what is loading.
class .spinner
· spinning
· reduced-motion (slowed)
Inline field validation message; form-level summary focuses at top.
class .field-err
· message
· aria-invalid input
In-place view switcher; roving tabindex + arrow keys via components.js.
class .tabs
· selected
· hover
· focus-visible
· overflow-scroll
Breadcrumb trail for hierarchical navigation.
class .crumbs
· default
· current
Square single-choice control.
class .radio
· checked
· unchecked
· focus-visible
· disabled
Range control with numeric readout.
class .slider
· default
· focus-visible
· disabled
Combobox: type-to-filter select, optionally multi-select with chips and a mirror input.
class .cb
· closed
· open
· filtered
· selected
· multi-chips
Date picker: text input plus calendar popover; min/max supported.
class .dp
· open
· today
· selected
· out-of-month
· disabled-day
· roving-focus (one tabbable cell)
Accordion/disclosure for collapsible sections.
class .acc
· closed
· open
· focus-visible
Square avatar chip for people. (avatar-sq)
class .avatar-sq
· initials
· image
· ink
· group
Image presentation with system borders; always alt text.
class .img
· 16:9
· 4:3
· 1:1
· contain
· caption
Dropzone + file input for uploads; dispatches triage:files.
class .drop
· idle
· dragover
· focus-visible
· file-list
Notifications panel with unread dot and mark-all-read.
class .notif
· unread
· read
· empty
· mark-all
Command palette dialog (cmd-k style) with input, items and triggers.
class .cmd
· closed
· open
· filtered
· active-item
· empty
Full-page state (e.g. fatal/empty app shell) with message and action.
class .page-state
· 404
· 500
· 403
· offline
· maintenance
Numbered pagination with page-size control; phone-trimmed.
class .pager-num
· first
· middle
· current
· gap
· disabled
Timeline for histories (e.g. approval steps): ordered entries with markers, time, actor.
class .tl
· default
· status-dots
Diff presentation for before/after comparison.
class .diff
· context
· added
· removed
· empty
End sheet: slide-over dialog variant for secondary panels.
class .sheet-end
· side
· bottom
Native single-select for small fixed option sets; class .select for explicit citation (identical to the bare element); for the labelled assign flow (action + outcome) compose recipe/assign-picker; component/cb is the large/filtered-set option.
class .select
· default
· focus
· invalid
· disabled
Determinate progress bar; compose with badge + text readout via recipe/job-progress; indeterminate waits use component/spinner.
class .progress
· determinate (aria-valuenow)
· complete (100%)
Skip link: first in body; hidden until focused, jumps to #main. Keeps keyboard users out of the nav.
class .skip
· default
· focus
Landing overview: hero metric strip, status/automation chips (the .status-chips row), recent-activity feed, follow-up cards.
Single-record page: page head with actions, fields, related lists, timeline.
Task-sectioned settings cards with scoped partial saves.
Builder canvas for trigger → filter → action chains (node spine, insert-on-connector).
Two-column draft|report layout for previewing what an automated pipeline would do.
Multi-step task flow with step rail and per-step actions.
Work-queue page: progress stats, per-item review rows, blind-labelling flow.
Deleting an entity listed in the UI is a two-step, in-place action with auto-disarm; no confirm() dialogs for these.
Irreversible, security-relevant, or multi-item actions keep a native confirm() whose sentence names the object and consequence.
Edits undoable in place need no confirmation and no danger styling; put the reverse control next to the action.
Server/redirect results render an .msg banner; in-place JS results call toast(); kinds are exactly ok/warn/err.
Clicking a row opens the record; secondary actions live in .rowacts, revealed on hover/focus (always visible on touch).
Editors end in .savebar: primary Save <thing> plus Cancel. Cancel is the way out; Back is only for a navigation backlink.
.empty = optional icon, h4 title, one line of reason, at most one CTA (.btn primary).
Use the shared cp() helper / .copy element; the helper owns fallback and confirmation labelling.
Sentence case for buttons/links/menu items; name the object; keep the global focus ring; 44px touch targets; colour never the only signal; every interactive element has an accessible name.
Status and meaning are carried by text or icon as well as colour; charts must survive greyscale and colour-blindness.
One element, one token and one job per level: page title → section heading → card heading → body → meta. Don't skip levels.
New full-screen overlays must clear the mobile tab bar; the ladder is tokenised (misc.zindex).
Use semantic spacing roles (page/card/field/control) and the preferred scale 2/4/8/12/16/24/32/48; legacy steps remain only for compatibility.
Primitives plus semantic aliases (surface-*, text-*, status-*, interactive-*, ink), tints and solid status surfaces; both themes.
Geist / Geist Mono families, relative --base-size root, --fs-* scale, weights and line-heights.
Preferred scale 2/4/8/12/16/24/32/48 + semantic roles --space-page/card/field/control + legacy steps (compatibility).
Duration set (100–400ms) and easings; ad-hoc durations are off-token.
Radius policy 0, breakpoint set, z-index ladder, fixed layout widths (--layout-sidebar/content-max/dock).
Eight categorical series (Okabe-Ito derived), CVD-checked, for downstream chart code.
Reference screen (85 classes used).
Reference screen (160 classes used).
Reference screen (87 classes used).
Reference screen (50 classes used).
Reference screen (68 classes used).
Reference screen (55 classes used).
Reference screen (66 classes used).
Global vs scoped adoption, load order, component dependencies, theme and density switches.
Action grammar, feedback, save bars, empty states, copy, a11y labels, exceptions register, review checklist.
How to change the system: generated files, gates, spec disciplines, provenance policy (repo-internal).
Upgrade guide for consumers on older versions.
Pre-Triage (mail-triage era) names → current names; TDS001 enforcement source.
Uses a pre-Triage (mail-triage era) class, id or global instead of the renamed vocabulary.
fix: Rename via /RENAME-MAP.md (or run: python3 tools/assemble_from_pack.py --apply-map <files>).
A colour literal appears where a token exists (palette match = error) or that is not in the palette (off-system colour = warning).
fix: Use var(--token) (prefer semantic aliases: --surface-*, --text-*, --status-*) or add the colour to tokens.json.
A non-zero border-radius (CSS property or JS style key).
fix: Remove the radius, or fork the system deliberately by changing the token and deleting the global rule.
outline:none / outline:0 without a visible focus replacement in the same rule.
fix: Keep the global ring, or provide :focus-visible with a 2px+ ring or a compensating box-shadow/border change.
Margin/padding/gap/inset px values outside the normalised spacing scale.
fix: Snap to the nearest scale value or extend the scale in tokens.json deliberately.
Transition/animation duration not in the motion token set.
fix: Use a motion duration token value (100/120/150/180/200/240/250/280/400ms).
z-index outside the documented ladder.
fix: Use a ladder value or extend misc.zindex in tokens.json.
font-family declaration not using Geist / Geist Mono (or inherit).
fix: Use the system stacks (or var(--mono)), or change the token in tokens.json for a deliberate rebrand.
A project stylesheet redefines a Triage custom property (--bg, --acc, --surface-* …).
fix: Edit tokens/tokens.json and regenerate, or use a distinct non-system variable name for local values.
A class used in markup that core.css / patterns.css do not define (opt-in, may be a project class).
fix: Use a system class, or allowlist the project class in .triagerc.json.
A defined token pair fails WCAG contrast (4.5:1 text / 3:1 non-text).
fix: Adjust the token value(s) so the pair meets the threshold, or extend .triagerc.json contrastPairs for intentional exceptions.
A product stylesheet consumes a primitive token directly where a semantic alias exists.
fix: Use the alias (e.g. var(--surface-card) instead of var(--card)). Definitions inside tokens.css are exempt.
Physical direction property (margin-left, left:, text-align:left …) instead of logical properties.
fix: Use margin-inline-start/end, padding-inline-*, border-inline-*, inset-inline-*, text-align:start/end.
<img> without an alt attribute.
fix: Add alt with a description, or alt="" when the image is decorative.
Interactive element with no accessible name (empty button/link, no aria-label), or a positive tabindex.
fix: Add text or aria-label; never use tabindex > 0.
Non-zero border-radius anywhere — zero radius is a system policy (enforced globally).
signals: rounded corner, border-radius, rounded edges, soft corners, rounded, corner radius, pill-shaped
Removing focus outlines without an equivalent visible :focus-visible replacement.
signals: remove focus, remove the focus, hide the outline, no focus ring, disable outline, outline: none, outline none
Raw colour literals where tokens exist; off-palette colours must be added to the token source deliberately, not inlined.
signals:
Off-system font stacks (Geist / Geist Mono or inherit only).
signals: comic sans, futura, custom typeface, off-system font, different font family, helvetica
Redefining a system custom property (--bg, --acc, --surface-*, …) in product CSS.
signals: override the css variable, redefine the token, change --bg, redefine --, override --
Conveying status by colour alone.
signals: colour only, color only, by colour, by color, colored dot only, coloured dot only
A confirm() dialog or custom modal to delete a listed entity — entity deletes use the armed two-step pattern instead.
signals: confirm before deleting, popup to confirm delete
Page-local toast markup or query-param toasts — the shared toast host owns feedback.
signals: page-local toast, query param toast, query-param toast
Chart colours chosen ad hoc instead of the dataviz palette (CVD-checked, greyscale-safe).
signals: chart colors, chart colours, graph colors, graph colours
Render plain content using the system type scale, spacing roles and layout tokens: system text styles on a system surface, no new visual language, no invented component skin.
scope: layout, content, typography, status
If no system control fits, use the platform's native element with minimal token-conformant styling; keep native semantics and degrade without JS.
scope: forms, controls, input
When nothing sanctioned fits and any fallback would mislead users, omit the feature area rather than inventing canon, and report a gap.
scope: *
After a server round-trip / redirect, announce the outcome with a .msg banner at the top of the content.
· redirect flows only; in-place actions use the toast host
· kinds exactly ok|warn|err
· past tense and name the object
JS/fetch actions announce via toast() from the shared host; one toast at a time.
· host it once per page (toasts aria-live)
· no page-local toast markup, no query-param toasts
Deleting a listed entity (rule, flow, classifier, template, chat, record) is a two-step armed action; never a confirm() dialog.
· first activation arms, second deletes
· auto-disarm 4s / Escape / outside click
· announce the result afterwards
Irreversible, security-relevant, or multi-item actions confirm with a sentence naming the object and consequence.
· native confirm() on the form; sentence names object + consequence
· the listed set plus reason-bearing reject/decline decisions
· when the rationale must be recorded, pair the confirm with a required, labelled textarea (native control); the reason surfaces in the history (component/tl)
Every boolean enable/disable of an entity uses .px-sw; verbs are Enable/Disable; the route announces the new state.
· verbs Enable / Disable only (never Pause/Resume or On/Off)
· auto-submit announces
State of an item is shown with a compact label/cell plus text (or icon); colour alone is prohibited.
· pair colour with text or an icon
· one status treatment per row cell
Any list or card with nothing to show gets title + one line of reason + at most one CTA.
· never a bare blank area or a bare 'failed'
· specific reason + one recovery action
Batch operations on selected rows appear in .bulkbar only with a selection; triggers in .tactions.
· appears only with a selection
· announce the count/result afterwards
Editors (forms that configure something) end in .savebar with primary Save plus Cancel; Cancel is the way out.
· Server-side validation renders at the top of the form and receives focus
· settings cards keep scoped partial saves
Record actions appear on hover/focus with .ra-inline for the key few and a details.menu for the rest; touch shows the menu.
· sentence case; destructive item is menu-item danger arm-del
· every .rowacts ships both variants
Page title + one-line description + actions; hierarchy levels are not skipped.
· don't shrink a page title to fit a long subject; let it wrap
· section headings and card headings mark different scopes
Popups/modals are built on the native dialog element (.dlg), with static-backdrop when closing must be deliberate.
· autofocus the first meaningful control
· Esc/backdrop behavior deliberate
Long result sets page with the numbered pager plus page-size control; phone view trims chrome.
·
Copy-to-clipboard goes through cp()/.copy so fallback and labelling stay consistent.
· never call navigator.clipboard from page code
Narrow a list with a row of chips above the table; chips are selection tokens, not status badges.
· chips mark selection, badges mark status — do not conflate
· active filters stay visible with a clear affordance
A labelled single-select (native select) beside one assign action; the outcome announces the new assignee by name.
· native select for small fixed sets; component/cb only when the set is large or needs filtering
· the control is always labelled and the submit announces the new value by name
· if the assign is handled in place (fetch), the outcome uses recipe/feedback-inplace instead of the redirect banner
· degrades without JS
Compose the progress bar with a state badge, a scanned/total readout and text for queued/running/stalled/failed/done; failures name the reason and offer retry; updates arrive by JSON polling.
· state is always text + colour (recipe/status-with-text)
· queued and done are labelled states too (same text+colour treatment; a completed bar is not left unlabelled)
· stalled is detected by the count not advancing and shown as a text label
· failed names the reason and offers a retry action
· aria-valuenow updates on the bar; state changes are announced via an aria-live region on the status line (or the shared toast host)
· poll JSON; no page reloads