Interaction standard (binding)
guidelineguideline/interaction-standard
The interaction standard is binding for every screen: armed two-step deletes, confirm() only for one-way actions, show-the-reverse for reversible mutations, the three-channel feedback standard (banner/toast/empty state), save bars for editors, copy rules, and an exceptions register for deliberate deviations.
verify: INTERACTION.md
aliases: interaction, behaviour, behavior, ux standard, interaction standard
source: INTERACTION.md
Consumption paths — global and scoped
guidelineguideline/consumption
Two sanctioned ways to adopt: the global path (four lines: tokens.css, base.css, optional patterns.css, components.js) styles the whole page; the scoped path wraps a region in .triage and loads scoped.css so host content is never restyled. Pair the scoped bundle with reset.css for parity; without it the host owns root sizing.
verify: README.md
aliases: consumption, getting started, adopt, integration, scoped, global
source: README.md + CHANGELOG.md 0.12.0
Verification levels (traceable conformance)
guidelineguideline/verification-levels
Four levels of conformance — static (shipped), behavioural (partial), rendered and product (proposed) — with the traceability contract: every conformance claim cites its rule id, implementation location and evidence; a lint score is a gate, never evidence. Coverage is declared per component.
verify: spec/proposals/verification-levels.md
aliases: verification, conformance, evidence, verification levels, traceability
source: spec/proposals/verification-levels.md
Design philosophy (paper and ink)
guidelineguideline/philosophy
Triage is a paper-and-ink interface language for tools that do real work on real data: one light paper (#fafafa), one ink layer, one accent, square geometry, and every machine action auditable. Depth is not faked with blur or gradient; only things that genuinely float cast shadows. Black ink is a material, not a theme; colour always means meaning, never decoration. Enforced by tokens and the spec, not just words.
verify: site/pages_foundations.py
aliases: philosophy, design philosophy, design principles, principles, paper and ink, the why
source: site/pages_foundations.py (philosophy)
Brand & theming
guidelineguideline/brand
One source of truth: Triage themes from tokens/tokens.json (W3C DTCG) and the core stylesheets carry no :root, so a re-theme is one JSON edit plus a rebuild. Two token tiers (semantic aliases over the raw palette — products prefer the alias column). The mark is a 24x24 ink square with an accent chip on the leading edge; lockups, favicon and templates ship in brand/. Never theme by overriding components.
verify: site/pages_foundations.py
aliases: brand, logo, brand mark, the mark, wordmark, theming, theming rules, re-theme, retheme, white label, white-label, brand assets, favicon, brand strategy
source: site/pages_foundations.py (brand)
Platform & themes
guidelineguideline/platform
One token file, four platform modes: dark theme, Windows High Contrast (forced-colors), RTL and print - all handled from the token layer and logical properties, no second stylesheet, no per-component overrides. In the dark theme surfaces rise instead of casting shadows.
verify: site/pages_foundations.py
aliases: platform, platform modes, themes, theme, dark mode, dark theme, light mode, high contrast, forced colors, rtl, rtl support, print, print styles, print stylesheet, platform support
source: site/pages_foundations.py (platform)
Iconography
guidelineguideline/icons
A transferable icon system - 174 glyphs, one spec. The registry is the Lucide set (ISC licence) normalised to the Triage drawing spec: 24x24 grid, fill:none, stroke:currentColor, stroke-width 1.7, round caps and joins. Ship it as a sprite (icons/sprite.svg), individual SVGs (icons/svg/*.svg), or a registry (icons/icons.json); original mail-triage names survive as aliases.
verify: site/pages_foundations.py
aliases: iconography, icons, icon, icon set, icon system, glyph, glyphs, icon sprite, sprite, lucide, svg icons
source: site/pages_foundations.py (icons)
Accessibility (WCAG 2.2)
guidelineguideline/accessibility
WCAG 2.2 scorecard against the source audit: focus visible, focus not obscured, non-text contrast, target size, contrast, animation, forced colours, resize and reflow pass; focus appearance partial. The ring is global - :focus-visible is never removed anywhere; inputs add a border and ring. Reduced motion is honoured.
verify: site/pages_foundations.py
aliases: accessibility, a11y, wcag, wcag 2.2, focus, focus visible, focus ring, contrast, contrast rules, target size, screen reader, reduced motion
source: site/pages_foundations.py (accessibility)
Voice & copy
guidelineguideline/voice
Sentence case for buttons, links and menu items (uppercase micro-labels are CSS). Verbs are Enable/Disable for entity state. Announce every mutation in past tense, naming the object. Three flash kinds only - ok, warn, err; info is retired. Name the object in destructive labels. Empty states: title + one-line reason + at most one action. One-way actions keep a native confirm().
verify: site/pages_foundations.py
aliases: voice, voice and copy, copy, copy rules, microcopy, tone, writing, wording, labels, message copy, empty state copy
source: site/pages_foundations.py (voice)
Localisation & i18n
guidelineguideline/localisation
RTL is mechanics; i18n is content. The system ships the mechanics - logical properties (TDS013), auto-mirroring chips/drawers/tooltips and core/i18n.js for locale, messages and formats. Content rules: whole-message placeholders (never concatenate sentences), counts through plural(), store ISO and display via Intl, room for extra width (German ~35%), bidi hygiene with <bdi> for embedded identifiers.
verify: site/pages_foundations.py
aliases: localisation, localization, i18n, internationalisation, internationalization, rtl, bilingual, bilingual copy, translations, locale, plural, intl
source: site/pages_foundations.py (localisation)
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
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
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
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
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