Triage design system v0.13.1-experiment
Home / Foundations / Philosophy

Philosophy

Paper and ink, one accent, square geometry, auditable machine work — and how each principle is enforced.
Why the system looks and behaves the way it does. Triage is a paper-and-ink interface language for tools that do real work on real data — mail triage, dashboards, admin surfaces, AI chat. The philosophy is deliberately narrow: one light paper, one ink layer, one accent, square geometry, and every machine action auditable. Everything else is derived from tokens and enforced by the spec.

Paper and ink

Grey paper (#fafafa) holds white cards with hairline borders and square corners. Depth is not faked with blur and gradient — content sits flat on the page and only things that genuinely float (menus, toasts, dialogs, drawers) cast shadows. Black ink is a material, not a theme: it marks the brand, the key number, the terminal, the primary action. A single saturated blue is the only accent; status colours (green / amber / red) appear only where a status exists, always with text.

The result is quiet: no decorative gradients, no coloured cards as decoration, no rounded bubbles. When everything is neutral, a red chip or a black tile carries real signal — which is exactly what an operations tool needs.

Principles

distilled from the README, the interaction standard and the audit findings
P1

Deterministic first, AI second

Rules and fast paths decide most cases; the model handles the rest. Machine decisions carry provenance (which rule, which category, which score) so they are always traceable.

P2

Every machine action is reviewable

Proposals, approval gates, audit trails, undo cards. The visual language for this — .proposal, .p-tag, .audit-row — is a first-class pattern, not an add-on.

P3

Colour never travels alone

Status colour is always paired with text (badges, dots + label, log levels). Tints are backgrounds behind bordered blocks.

P4

Ink is emphasis

Black panels (stat tiles, bulk bar, terminal logs, primary buttons) are a deliberate contrast layer on a grey/white field, not a dark theme.

P5

Squared off, bordered, flat

Zero radius, 1px borders, no card shadows. Shadows are reserved for layers that float (menus, toasts, drawers).

P6

Phone-first below 768px

Not merely responsive: bottom tab bar, card reflow, sheets, keyboard fit, safe-area insets are designed as a separate mode.

P7

One way to do each thing

The interaction standard (ui-conventions.md) fixes one mechanism per recurring action: armed two-step delete, .px-sw for booleans, three flash kinds, one toast channel.

P8

Reversibility is a design rule

Machine actions are gated, two-step or undoable; nothing irreversible happens without a stated consequence.

How the philosophy is enforced (not just written)

PrincipleMechanism
Tokens are the lawone DTCG source; core consumes aliases only; TDS009/TDS012 catch overrides and primitives
Square geometry*{border-radius:0 !important}; the single documented exception is the spinner circle (TDS003)
Colour never alonestatus always paired with text; TDS011 gates contrast in both themes
One way per actioninteraction standard: armed two-step delete, .px-sw for booleans, three feedback channels
Machine work is reviewableproposal cards, audit rows, undo affordances; the UI shows which rule/model decided
Phone-firsttable reflow, bottom tab bar, sheet dialogs and keyboard-lift rules ship with the shell
Accessible by default44px coarse targets, visible focus everywhere, forced-colors and reduced-motion fallbacks

What we deliberately do not do

  • No dark patterns: no countdowns, no disguised cancellation, no notification nagging.
  • No confirmation popups for entities: deletes arm in place; native confirm() is reserved for the six irreversible actions, and dialogs for those carry data-dlg-static.
  • No colour-only meaning and no emoji as status.
  • No grey-on-grey typography: every text token is contrast-checked, including placeholders.
  • No second stylesheet for dark mode — one token file flips both themes.
Triage Design System v0.13.1-experiment — the central, app-agnostic UI design authority. Source of truth: /tokens/tokens.json. Showcase chrome only: site/.