Armed two-step delete
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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
guidelineguideline/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