# Hierarchy — what a screen shows, and at what weight

[composition.md](./composition.md) says which shape carries which meaning. This says how much of
the data reaches the reader at all, in what order, and how loudly. The numbers are
[constitution.md](./constitution.md)'s; which entry draws a thing is [catalog.md](./catalog.md)'s.

The failure this page exists to prevent has one signature: every surface drawn at one weight. A
record that is a wall of equal fact rows, a header that carries five figures because five were
available, a row of four filled buttons. Nothing is wrong with any single part and the reader
cannot find anything.

## Three tiers

**Everything a surface holds is primary, secondary or tertiary, and the sort IS the design.**

| Tier | What it is | How it is drawn |
|---|---|---|
| Primary | what the job needs NOW — what the reader decides with, and the act that follows | first, unscrolled, in its own device at full ink |
| Secondary | context read on demand — the value consulted when something looks wrong | further down, or behind ONE disclosure |
| Tertiary | provenance — who entered it, when, where it came from | last, at the caption rung, or a stamp on the thing it explains |

**A summary goes BELOW the controls that produce it**, so the reader sees what they asked for
before what it came to.

**Name the JOB the surface exists for and the tier falls out.** It is not a vote on importance:
the same field is primary on the desk that acts on it and tertiary on the record that merely
carries it. A field nobody can name a decision for is tertiary however interesting it is.

**What the screen KNOWS and what it SHOWS are two lists, never one.** The rows carry every fact the
query returned; the columns carry the ones the reader decides with.

**SMALL is not QUIET.** Recede with ink, not with size (`constitution.md` §3); a caption at a
smaller size in default ink still shouts, and a supporting line demoted in BOTH size and weight has
left its subject and become a caption under a heading. One axis.

### How a record derives them

**STATED is the test.** A field the record is required to hold is shown, empty or not — absence is
work somebody owes, and a field that vanishes when unset cannot be filled
([data_entry.md](./data_entry.md)). An OPTIONAL field this record does not state is not drawn:
it and the system's own columns fold behind ONE link, opening the whole remainder at once.

**One link, not one per field, and never a grid of empty rows.** A fold per field is the wall of
equal weight again with a chevron on each line, and rows of dashes make the reader read the whole
grid to learn that it says nothing. The fold is the WAI-ARIA disclosure pattern: a named control
that states whether it is open, and content that is really removed when it is closed.

**Facts are a compact grid, tiered in reading order** — the primary ones first, the stated
remainder after them, the fold last. A glance is WIDE (`composition.md`) **and SHORT**: the first
band holds what the screen was opened for, and one disclosure the rest. A block that asks which
fields to LEAVE OUT is as wide as the table; one naming what to SHOW is a handful.

## One primary act per surface

**One act is primary. Everything else is quiet, and the outcomes are in a menu.** A second filled
button halves the first, and a row of four says the surface has no opinion about what to do.

- **Primary** — the act the surface exists for, one per surface, at the end of the work it commits.
- **Secondary** — peers the reader reaches for often, at rest weight, beside it.
- **The menu** — the outcomes, the corrections, the rarely-taken. A destructive act is the fence's
  (`composition.md` § Commit & feedback surfaces), never a peer of the primary one.

**An act taken once a year costs the one taken every hour nothing.** Frequency decides the ladder,
not how consequential the act sounds in a meeting.

## One fact, one place

**A value a stronger device already states is not drawn again.** Not as a second fact, not as a
column, not as a badge. The band's figure is not also a fact row; a day's heading is not also a
date column; the header's name is not also a Name field; a lifecycle rung is not also a status
pill.

**The stronger device is the one that shows the value AND what it means** — a meter over a bare
number, a heading over the cell it repeats on every row, an editor over a reading of the same
field. When two places both want a value, the weaker one drops it.

**The test is subtraction, not judgement**: cover one of the two — read the screen with it gone —
and ask whether anything was lost. If nothing was, it was noise.

## Depth — four surfaces, four jobs

**Every surface in the chain shows LESS than the next and enough to decide whether to open it.**
Repeating the whole of one inside the other is how a chain stops paying for itself.

| Surface | Carries | Not this |
|---|---|---|
| Register row | identity, and the job's ONE figure | a second figure because the column was free |
| Drawer | the next act and the facts it needs — a peek, with a door to the page | the whole record, so the page has nothing left |
| Page | the whole record, in ONE reading column | a column of work beside a column of facts, read twice |
| Rail | the way back, and one item per section | anything the reader came to READ |

**Nothing but navigation goes beside the column** — the way back, and the jumps within the page.
A field, a file, a picture, a run of rows or a conversation parked there competes with the
record's own work for the eye and is lost on a folded viewport: those are sections like the facts
are, near the end.

**Related records are LINKS, one short section** — `RecordRelated`. Rows that merely name this
record are handed to the register that owns them; a run of folds down the page is an outline of
other people's work.

## Markers on the minority side

**Mark the exception, never the rule.** A mark that is the same on every row carries nothing, and
one that is a different HUE on every row carries less: draw what is late rather than what is on
time, what is missing rather than what arrived, what is blocked rather than what is running. Where
the minority flips — a set that is mostly late — the mark flips with it, because the reader is
scanning for the few.

## Colour carries meaning only

**One accent, and where it goes is "where you are", and nothing else** (`constitution.md` §8) — a
page-scale position marker takes `primary`. **Tones mean state** — the valence families, whose
colour IS the meaning. **Marks are neutral** unless the hue is data.

**A colour that says "this is a heading" or "this is that kind of section" is decoration**, and it
spends the one signal a screen has for the thing that actually needs it.

## Whitespace is structure

**No box is taller than its content's floor.** A card padded to a height nothing fills claims a
weight its content does not have, and a row of them claims they are peers — so **cards in a row END
ON ONE LINE**, and the imbalance is fixed in the CONTENT rather than by letting one run two lines
past its neighbours. **Flat for work execution and data capture; carded for monitoring** — a person
entering values wants one uninterrupted column, a person scanning states wants the states boxed
apart.

**An empty section costs a line, not a card** — one sentence in the reader's own language, and the
one act that fills it (`composition.md` § Empty states).

**Air is the grouping device; a border is for a thing you press** (`constitution.md` §6).

## Ink and air state what a thing is

**A reader who has to press to find out what a thing is was told nothing**, and each of these is
countable off a rendered screen ([reviewing.md](./reviewing.md)).

| What | Drawn as |
|---|---|
| A section's heading | its WORDS — no glyph for the KIND of section. A mark belongs to the page's own title, which names one subject, and to a navigation item, which is scanned |
| An editor at rest | a CLOSED frame: four painted sides, on the control or on the box that paints for it. Three sides is decoration |
| A focus ring | whole — its painted extent inside every box that clips it |
| Two named groups | further apart than the rows inside either. An equal gap says they are one list |

## Budgets a reviewer can count

| Count | Budget |
|---|---|
| Primary facts on the surface, against primary facts visible without scrolling | equal — a primary fact under the fold is mis-tiered, at 1280 and at 375 alike |
| Primary acts per surface | 1 |
| Accents per page | 1 |
| Links out of the stated facts into the folded remainder | 1 |
| Places any one value is drawn | 1 |
| Weights a run of peers is drawn at | 1 |

**A budget failing is a tiering question, never a permission to shrink something.** The fix is to
move a fact down a tier, fold it, or take it off the screen.

## The names behind these rules

WCAG 2.2 for the floors a budget may never buy its way past — target size and focus visible. The
WAI-ARIA disclosure pattern for the fold. Progressive disclosure, and Nielsen's aesthetic and
minimalist design, for the tiering itself.