← designauthority.seanyong.xyz

Triage Design System

The central, app-agnostic UI design authority for these products.

pack triage-evolutionv0.13.1-experimentThe governed evolution line of Triage: agent updates land here first, as release candidates awaiting promotion.76 artifacts · 15 rules · 9 prohibitions · 3 fallbacks · 17 recipesgolden 27/27Gallery

Ask this authority

Golden set

27 / 27 cases pass
askexpectedgotresolved to
passshow whether a request is waiting for approvalCOMPOSECOMPOSErecipe/status-with-text
passshow a compact history of recent approval stepsRESOLVEDRESOLVEDcomponent/tl
passlet users enable or disable a ruleRESOLVEDRESOLVEDcomponent/px-sw
passshow an empty state when there are no requestsRESOLVEDRESOLVEDcomponent/empty
passlet users upload attachment files on a requestRESOLVEDRESOLVEDcomponent/drop
passassign a reviewer with a searchable pickerRESOLVEDRESOLVEDcomponent/cb
passmake the sidebar navigation links show which page is activeRESOLVEDRESOLVEDcomponent/nav-item
passshow a message when the server cannot be reachedRESOLVEDRESOLVEDcomponent/msg
passshow the status of a requestCOMPOSECOMPOSErecipe/status-with-text
passshow the result of saving the settings formCOMPOSECOMPOSErecipe/feedback-redirect
passannounce that a row was removed without reloading the pageCOMPOSECOMPOSErecipe/feedback-inplace
passlet users filter the requests list by category and statusCOMPOSECOMPOSErecipe/filter-row
passwe need a custom layout for the hero area before the designs arriveFALLBACKFALLBACKfallback/plain-content
passadd a progress bar for a long-running background jobRESOLVEDRESOLVEDcomponent/progress
passadd a gantt chart for the delivery scheduleUNDEFINEDUNDEFINED
passmake the corners roundedCONFLICTCONFLICTprohibit/rounded-corners
passremove the focus outline from linksCONFLICTCONFLICTprohibit/remove-focus-ring
passuse #ff6600 as the warning colourCONFLICTCONFLICTprohibit/raw-color
passdelete a saved template with a confirm dialogCONFLICTCONFLICTprohibit/custom-confirm-for-entity-delete
passassign a reviewer to a requestRESOLVEDRESOLVEDcomponent/select
passchoose one owner from a list of peopleCOMPOSECOMPOSErecipe/assign-picker
passshow how far a background scan has come and whether it is stuckCOMPOSECOMPOSErecipe/job-progress
passrejecting a request requires typing a reasonCOMPOSECOMPOSErecipe/high-stakes-confirm
passa skip link to jump past the navigationRESOLVEDRESOLVEDcomponent/skip
passa panel sliding in from the edge with a record's detailsRESOLVEDRESOLVEDcomponent/sheet-end
passthe chevron that reveals actions for a single rowCOMPOSECOMPOSErecipe/row-actions
passa navigation link in the sidebarRESOLVEDRESOLVEDcomponent/nav-item

Artifacts

componentButton component/btn

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)

componentIcon button component/iconbtn

Square icon-only control for compact toolbars and rows; must carry an aria-label.

class .iconbtn

· default

· hover

· active

· focus-visible

componentSwitch component/px-sw

The one boolean control for enabling/disabling an entity; auto-submits and announces.

class .px-sw

· checked

· unchecked

· disabled

· focus-visible

componentMenu item component/menu-item

Item inside a dropdown menu; sentence case; destructive items carry 'menu-item danger arm-del'.

class .menu-item

· default

· hover

· danger

· armed

· focus-visible

componentNav item component/nav-item

Sidebar/navigation link with icon, active rail state and aria-current.

class .nav-item

· default

· hover

· active(selected)

· focus-visible

componentChip component/chip

Compact filter/selection token used in filter rows; distinct from badge (not a status).

class .chip

· default

· hover

· active(selected)

· focus-visible

componentIndex row component/index-row

Standard row for list/index pages: primary text, meta, optional actions.

class .index-row

· default

· hover

· active

· focus-visible

componentTable component/tbl

Data table with sticky headers; collapses to card rows (.mcards) on phones.

class .tbl

· default

· row hover

· selected

· reflowed (mcards)

componentBulk bar component/bulkbar

Selection-only toolbar for batch operations; hidden until rows are selected.

class .bulkbar

· hidden

· shown with selection

componentSave bar component/savebar

Sticky footer for editors: primary Save plus Cancel; validation renders above, focused.

class .savebar

· sticky

· keyboard-lifted (JS transform)

componentFlash message component/msg

Banner for server/redirect feedback; exactly ok/warn/err kinds.

class .msg

· ok

· warn

· err

componentToast component/toast2

Transient in-place feedback (one at a time) from the shared toast host.

class .toast2

· ok

· warn

· err

· auto-dismiss

componentBadge component/badge

Compact status label (uppercase micro-badge); pair colour with text, never colour alone.

class .badge

· neutral

· ok

· warn

· err

· acc

· solid

componentEmpty state component/empty

Empty state anatomy: title, one-line reason, at most one primary CTA.

class .empty

· default

componentDialog (native) component/dlg

Native dialog element for modals/confirms; static-backdrop variant available; dialog is the confirm primitive.

class .dlg

· open (showModal)

· backdrop

· wide variant

componentTooltip component/tip

Tooltip for supplementary hints; hover/focus triggered.

class .tip

· hover

· focus-visible

componentSpinner component/spinner

Loading indicator for waiting states; pair with text describing what is loading.

class .spinner

· spinning

· reduced-motion (slowed)

componentField error component/field-err

Inline field validation message; form-level summary focuses at top.

class .field-err

· message

· aria-invalid input

componentTabs component/tabs

In-place view switcher; roving tabindex + arrow keys via components.js.

class .tabs

· selected

· hover

· focus-visible

· overflow-scroll

componentBreadcrumbs component/crumbs

Breadcrumb trail for hierarchical navigation.

class .crumbs

· default

· current

componentRadio component/radio

Square single-choice control.

class .radio

· checked

· unchecked

· focus-visible

· disabled

componentSlider component/slider

Range control with numeric readout.

class .slider

· default

· focus-visible

· disabled

componentCombobox component/cb

Combobox: type-to-filter select, optionally multi-select with chips and a mirror input.

class .cb

· closed

· open

· filtered

· selected

· multi-chips

componentDate picker component/dp

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)

componentAccordion component/acc

Accordion/disclosure for collapsible sections.

class .acc

· closed

· open

· focus-visible

componentAvatar component/avatar-sq

Square avatar chip for people. (avatar-sq)

class .avatar-sq

· initials

· image

· ink

· group

componentImage component/img

Image presentation with system borders; always alt text.

class .img

· 16:9

· 4:3

· 1:1

· contain

· caption

componentUpload / dropzone component/drop

Dropzone + file input for uploads; dispatches triage:files.

class .drop

· idle

· dragover

· focus-visible

· file-list

componentNotifications component/notif

Notifications panel with unread dot and mark-all-read.

class .notif

· unread

· read

· empty

· mark-all

componentCommand palette component/cmd

Command palette dialog (cmd-k style) with input, items and triggers.

class .cmd

· closed

· open

· filtered

· active-item

· empty

componentFull-page state component/page-state

Full-page state (e.g. fatal/empty app shell) with message and action.

class .page-state

· 404

· 500

· 403

· offline

· maintenance

componentNumbered pagination component/pager-num

Numbered pagination with page-size control; phone-trimmed.

class .pager-num

· first

· middle

· current

· gap

· disabled

componentTimeline component/tl

Timeline for histories (e.g. approval steps): ordered entries with markers, time, actor.

class .tl

· default

· status-dots

componentDiff component/diff

Diff presentation for before/after comparison.

class .diff

· context

· added

· removed

· empty

componentSheet dialog component/sheet-end

End sheet: slide-over dialog variant for secondary panels.

class .sheet-end

· side

· bottom

componentSelect (native) component/select

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

componentProgress bar component/progress

Determinate progress bar; compose with badge + text readout via recipe/job-progress; indeterminate waits use component/spinner.

class .progress

· determinate (aria-valuenow)

· complete (100%)

componentSkip link component/skip

Skip link: first in body; hidden until focused, jumps to #main. Keeps keyboard users out of the nav.

class .skip

· default

· focus

patternDashboard / overview pattern/dashboard

Landing overview: hero metric strip, status/automation chips (the .status-chips row), recent-activity feed, follow-up cards.

patternDetail / record page pattern/detail

Single-record page: page head with actions, fields, related lists, timeline.

patternSettings pattern/settings

Task-sectioned settings cards with scoped partial saves.

patternFlow / automation builder pattern/flows

Builder canvas for trigger → filter → action chains (node spine, insert-on-connector).

patternDry-run / simulator report pattern/dry-run

Two-column draft|report layout for previewing what an automated pipeline would do.

patternStepper / wizard pattern/stepper

Multi-step task flow with step rail and per-step actions.

patternIndex & eval queue pattern/index-eval

Work-queue page: progress stats, per-item review rows, blind-labelling flow.

guidelineArmed two-step delete guideline/armed-delete

Deleting an entity listed in the UI is a two-step, in-place action with auto-disarm; no confirm() dialogs for these.

guidelineHigh-stakes confirmations guideline/high-stakes-confirm

Irreversible, security-relevant, or multi-item actions keep a native confirm() whose sentence names the object and consequence.

guidelineReversible mutations show the reverse guideline/reversible-mutations

Edits undoable in place need no confirmation and no danger styling; put the reverse control next to the action.

guidelineFeedback routing: banner vs toast guideline/feedback-routing

Server/redirect results render an .msg banner; in-place JS results call toast(); kinds are exactly ok/warn/err.

guidelineRow actions guideline/row-actions

Clicking a row opens the record; secondary actions live in .rowacts, revealed on hover/focus (always visible on touch).

guidelineEditors end in a save bar guideline/savebar-editor

Editors end in .savebar: primary Save <thing> plus Cancel. Cancel is the way out; Back is only for a navigation backlink.

guidelineEmpty state anatomy guideline/empty-anatomy

.empty = optional icon, h4 title, one line of reason, at most one CTA (.btn primary).

guidelineCopy helper owns the clipboard guideline/copy-helper

Use the shared cp() helper / .copy element; the helper owns fallback and confirmation labelling.

guidelineLabels & accessibility baseline guideline/labels-accessibility

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.

guidelineColour is never the only signal guideline/colour-not-alone

Status and meaning are carried by text or icon as well as colour; charts must survive greyscale and colour-blindness.

guidelinePage hierarchy guideline/page-hierarchy

One element, one token and one job per level: page title → section heading → card heading → body → meta. Don't skip levels.

guidelineOverlay z-order guideline/overlay-zorder

New full-screen overlays must clear the mobile tab bar; the ladder is tokenised (misc.zindex).

guidelineSpacing by role, not by vibe guideline/spacing-roles

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.

token-setColour tokens token-set/color

Primitives plus semantic aliases (surface-*, text-*, status-*, interactive-*, ink), tints and solid status surfaces; both themes.

token-setTypography tokens token-set/typography

Geist / Geist Mono families, relative --base-size root, --fs-* scale, weights and line-heights.

token-setSpacing tokens token-set/spacing

Preferred scale 2/4/8/12/16/24/32/48 + semantic roles --space-page/card/field/control + legacy steps (compatibility).

token-setMotion tokens token-set/motion

Duration set (100–400ms) and easings; ad-hoc durations are off-token.

token-setSystem constants token-set/misc

Radius policy 0, breakpoint set, z-index ladder, fixed layout widths (--layout-sidebar/content-max/dock).

token-setDataviz palette token-set/dataviz

Eight categorical series (Okabe-Ito derived), CVD-checked, for downstream chart code.

exampleExample: Chat — skeleton example/chat

Reference screen (85 classes used).

exampleExample: Component gallery — design system example/components

Reference screen (160 classes used).

exampleExample: Dashboard — skeleton example/dashboard

Reference screen (87 classes used).

exampleExample: Settings — skeleton example/form

Reference screen (50 classes used).

exampleExample: List — skeleton example/list

Reference screen (68 classes used).

exampleExample: App name example/shell

Reference screen (55 classes used).

exampleExample: Viewer — skeleton example/viewer

Reference screen (66 classes used).

referenceConsumption quickstart reference/quickstart

Global vs scoped adoption, load order, component dependencies, theme and density switches.

referenceInteraction standard (binding) reference/interaction-standard

Action grammar, feedback, save bars, empty states, copy, a11y labels, exceptions register, review checklist.

referenceRepository agent contract reference/agents-contract

How to change the system: generated files, gates, spec disciplines, provenance policy (repo-internal).

reference0.6 → 0.12 migration reference/migration

Upgrade guide for consumers on older versions.

referenceVocabulary rename map reference/rename-map

Pre-Triage (mail-triage era) names → current names; TDS001 enforcement source.

Rules

ruleTDS001 · deprecated-name error

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

ruleTDS002 · raw-colour warning

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.

ruleTDS003 · non-zero-radius error

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.

ruleTDS004 · focus-removed error

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.

ruleTDS005 · off-scale-spacing warning

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.

ruleTDS006 · off-token-motion info

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

ruleTDS007 · off-ladder-zindex info

z-index outside the documented ladder.

fix: Use a ladder value or extend misc.zindex in tokens.json.

ruleTDS008 · off-system-font error

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.

ruleTDS009 · token-override error

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.

ruleTDS010 · unknown-class info

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.

ruleTDS011 · contrast error

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.

ruleTDS012 · primitive-use warning

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.

ruleTDS013 · physical-direction warning

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.

ruleTDS014 · image-alt error

<img> without an alt attribute.

fix: Add alt with a description, or alt="" when the image is decorative.

ruleTDS015 · accessible-name error

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.

Prohibitions

prohibit/rounded-corners

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

prohibit/remove-focus-ring

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

prohibit/raw-color

Raw colour literals where tokens exist; off-palette colours must be added to the token source deliberately, not inlined.

signals:

prohibit/off-system-font

Off-system font stacks (Geist / Geist Mono or inherit only).

signals: comic sans, futura, custom typeface, off-system font, different font family, helvetica

prohibit/token-override

Redefining a system custom property (--bg, --acc, --surface-*, …) in product CSS.

signals: override the css variable, redefine the token, change --bg, redefine --, override --

prohibit/color-only-status

Conveying status by colour alone.

signals: colour only, color only, by colour, by color, colored dot only, coloured dot only

prohibit/custom-confirm-for-entity-delete

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

prohibit/page-local-toast

Page-local toast markup or query-param toasts — the shared toast host owns feedback.

signals: page-local toast, query param toast, query-param toast

prohibit/ad-hoc-chart-colors

Chart colours chosen ad hoc instead of the dataviz palette (CVD-checked, greyscale-safe).

signals: chart colors, chart colours, graph colors, graph colours

Fallbacks

Plain content on system surfaces

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

Native control, token-conformant

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

Omit and report

When nothing sanctioned fits and any fallback would mislead users, omit the feature area rather than inventing canon, and report a gap.

scope: *

Recipes

Redirect feedback is a banner recipe/feedback-redirect

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

In-place feedback is a toast recipe/feedback-inplace

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

Entity delete is armed, two-step, in place recipe/entity-delete-armed

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

High-stakes actions keep a native confirm() recipe/high-stakes-confirm

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)

Entity on/off is the switch, not a button recipe/entity-toggle

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

Status is never colour-only recipe/status-with-text

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

Empty areas use the empty anatomy recipe/empty-with-cta

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

Bulk actions live in the selection bar recipe/bulk-actions

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 end in a save bar recipe/editor-savebar

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

Row actions: inline + menu variants recipe/row-actions

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

Pages open with a page head recipe/page-head

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

Modal tasks use the native dialog recipe/dialog-task

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 lists paginate with numbered pager recipe/paginated-list

Long result sets page with the numbered pager plus page-size control; phone view trims chrome.

·

Copy affordances use the shared helper recipe/copy-value

Copy-to-clipboard goes through cp()/.copy so fallback and labelling stay consistent.

· never call navigator.clipboard from page code

Filtering a list is a chip row over the table recipe/filter-row

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

Assign one person to a small fixed set recipe/assign-picker

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

Long-running background work shows determinate progress recipe/job-progress

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