Triage Design System v0.13.1-experiment

Guidelines

13 records · triage-evolution

Armed two-step delete

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

do: carry .arm-del with data-arm-label and a matching aria-label · arm on first activation (label becomes 'Confirm delete'), delete on second · auto-disarm after 4s, on Escape, outside click, or menu close · announce the result afterwards (banner or toast)

don't: no confirm() for entity deletes · no arming as a substitute for feedback

“No `confirm()` dialog, ever, for these.”

source: INTERACTION.md#item-deletes @ 2c701d2172

High-stakes confirmations

guideline
guideline/high-stakes-confirm

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

do: name the object and the consequence in the sentence · keep strings apostrophe-safe · reason-bearing reject/decline decisions pair the confirm with a required, labelled reason field recorded in history

don't: do not route entity deletes through confirm() (use arming)

“Representative set: remove account · reset tokens · rebuild the index · clear a chat · enable auto-apply · approve a risky plugin.”

source: INTERACTION.md#one-way-actions @ 2c701d2172

Reversible mutations show the reverse

guideline
guideline/reversible-mutations

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

do: pair remove ⇄ re-include, snooze ⇄ wake, tag ⇄ untag

don't: no confirms or danger styling for reversible edits

“Put the reverse control next to the action.”

source: INTERACTION.md#reversible-mutations @ 2c701d2172

Feedback routing: banner vs toast

guideline
guideline/feedback-routing

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

do: announce every mutation unless the new state is self-evident in the same viewport · wording is past tense and names the object

don't: no info kind · no page-local toast markup or query-param toasts

“There is no `info` kind — use `ok` for a benign outcome and `warn` when only part of it worked.”

source: INTERACTION.md#feedback @ 2c701d2172

Row actions

guideline
guideline/row-actions

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

do: inline the relevant few with .ra-inline; rest in details.menu with .ra-menu · sentence case menu items; destructive item is 'menu-item danger arm-del'

don't: no physical-direction CSS (use logical properties) · no grey tags/categories styling here — that's product convention

“Touch (≤767px): `.ra-inline` hides and the `⋯` menu shows.”

source: INTERACTION.md#lists-row-actions @ 2c701d2172

Editors end in a save bar

guideline
guideline/savebar-editor

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

do: render server-side validation at the top of the form and focus it · settings cards keep scoped partial saves

don't: a card never submits fields it does not own

“Settings cards keep scoped partial saves.”

source: INTERACTION.md#save-bars @ 2c701d2172

Empty state anatomy

guideline
guideline/empty-anatomy

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

do: use for any list or card with nothing to show · micro-empties inside a feed may be a single .sub line

don't: never a bare blank area or a bare 'failed'

“Give a specific reason and one recovery action.”

source: INTERACTION.md#empty-states @ 2c701d2172

Copy helper owns the clipboard

guideline
guideline/copy-helper

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

do: .copy marks the copy affordance

don't: never call navigator.clipboard from page code

“The helper owns the fallback and the confirmation labelling.”

source: INTERACTION.md#copy @ 2c701d2172

Labels & accessibility baseline

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

do: name the object in destructive labels and aria-labels · keep :focus-visible intact

don't: positive tabindex · icon-only controls without labels

source: INTERACTION.md#labels-accessibility @ 2c701d2172

Colour is never the only signal

guideline
guideline/colour-not-alone

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

do: label status lines directly · vary dash patterns or annotate in charts

don't: no colour-only dots or fills for meaning

“Do not rely on colour alone: label lines directly, vary dash patterns, or annotate.”

source: INTERACTION.md#labels-accessibility + dataviz guidance @ 2c701d2172

Page hierarchy

guideline
guideline/page-hierarchy

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

do: let a long page title wrap at --fs-page-title

don't: don't shrink a page title with inline font-size · don't use a section heading as a card label

“Don't skip levels or spend a level you don't need.”

source: site/pages_foundations.py#typography @ 2c701d2172

Overlay z-order

guideline
guideline/overlay-zorder

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

do: use ladder values from tokens

don't: no arbitrary z-index values

source: tokens.json#misc.zindex @ 2c701d2172

Spacing by role, not by vibe

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

do: snap new work to the preferred scale

don't: no ad-hoc spacing values

source: tokens.json#spacing @ 2c701d2172

Triage Design System · design authority v0.13.1-experiment — rendered live from authorities/triage-evolution; updates when the pack updates.