Philosophy
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 findingsDeterministic 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.
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.
Colour never travels alone
Status colour is always paired with text (badges, dots + label, log levels). Tints are backgrounds behind bordered blocks.
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.
Squared off, bordered, flat
Zero radius, 1px borders, no card shadows. Shadows are reserved for layers that float (menus, toasts, drawers).
Phone-first below 768px
Not merely responsive: bottom tab bar, card reflow, sheets, keyboard fit, safe-area insets are designed as a separate mode.
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.
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)
| Principle | Mechanism |
|---|---|
| Tokens are the law | one 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 alone | status always paired with text; TDS011 gates contrast in both themes |
| One way per action | interaction standard: armed two-step delete, .px-sw for booleans, three feedback channels |
| Machine work is reviewable | proposal cards, audit rows, undo affordances; the UI shows which rule/model decided |
| Phone-first | table reflow, bottom tab bar, sheet dialogs and keyboard-lift rules ship with the shell |
| Accessible by default | 44px 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.