Decisions › D09
Quiet until something is wrong: no green, a shape for every problem, colour reserved for diagnostics
Context
Zach found the first tree visually busy and said what would help. High Performance HMI, the ISA-101 way of building industrial screens, was the prior art: grey when normal, colour only for the abnormal. A day later the Utilities menu had amber and red pills, and he drew the line.
The decision
A healthy row shows nothing: no green dot. A warning or an error gets a shape as well as a colour (a triangle for a warning, an octagon or cross for an error, a clock for stale), so it never relies on colour alone. Not connected is fully greyed; connected is normal grey text; only problems get colour.
On 23 October the colours for warn, error, stale and unknown (and their soft tints) were reserved for true diagnostic results. Utilities lost their amber and red danger pills (danger is a neutral word or icon), an unmet precondition reads in muted text, and a busy button greys out with quiet text under it. A test enforces the token use.
Why
“all the green actually is distracting”
Zach Yamaoka, notes, 22 Oct 2026
“quiet by default and only call out on the things with errors”
Zach Yamaoka, notes, 23 Oct 2026
“Serverse that color for annotating true diagonistics warning and errors and nothing else!!!”
Zach Yamaoka, notes, 23 Oct 2026
“the tulities are not the main thing and shouldn't be drawing attention”
Zach Yamaoka, notes, 23 Oct 2026
Options considered
The five tree drawings of the v1 build, all quiet when OK, each checked by 100 measured tests together. None was scored against the others; the first was the default.
| Tree drawing | What it does |
|---|---|
| Quiet IDE tree | Hover chevrons in a left gutter, a type icon and name, muted ids, a status shape at the far right only on problem rows. The default. |
| Notion toggle | A hover swaps the row's icon for the chevron; thin indent guides; a folded parent with problems shows a count pill. |
| Problems first | Only the paths that hold a problem open by themselves; each level's healthy rows fold into one muted “N OK” line. |
| Status rail | Type icon, name and id on the left; a right-edge rail that is invisible when OK and takes the problem shape and colour otherwise. |
| Columns tree | The tree is also the table: one nested name column, then quiet aligned columns; the status shape and message last, only when the row is not OK. |
Round 2 added an ISA-101 skin, and round 3 added five more Bare Metal takes on the same idea (Ink, Phosphor, Operator Grey, Paper, Top).
Consequences
- Every skin has to pass a quiet-when-OK gate: an OK row may not paint any colour (chroma at or above 0.12 in its background, text, icon or border fails it).
- Text must reach 4.5:1 contrast on every surface it is drawn on, and the shapes 3:1.
- The calm rule also shaped the first screen: one answer on top, detail a click deeper.
Evidence
- IO diagnostics v1: the first end-to-end buildReport, 2026-10-22. Evidence for this decision.
- Round 2: the panel on the real rackReport, 2026-10-22. Evidence for this decision.
- IO diagnostics v1: build planContract doc, 2026-10-22. The decisions, the plugin boundary (a subprocess speaking JSON lines), the lanes, and the interfaces frozen between them.
- Round 3 briefContract doc, 2026-10-23. What was settled in round 3 (resizable panes, warning colours reserved, quieter utilities) and the three sets of proposals.
- Bring your own tokens: writing a skinContract doc, 2026-10-22. A skin is one file of token declarations; the 39 base tokens, the gates a skin must pass, and a 20-line example.
Commits in the app's repository (private):
3d692622026-10-22 Round 2 foundation: semantic tokens826dacf2026-10-23 Skins bare-1 to bare-5 applying ISA-101 ideasf5cc2962026-10-23 Warning colours reserved for diagnostics (gate, mutation-proven)