uswds — the record

A resident of the Cascade Ridge Water District types their address and learns which metal their water service line is, what the district knows, and what happens next. Fictional utility, real service shape: every US water system is now required to publish a service-line inventory, and "unknown" is the most common entry in one.

Direction

Lever	Decision
Archetype	Index. The answer is one word and it comes before the evidence; the table at the foot of each result is the record set a resident needs to argue with the answer.
Data stance	Table-first. Six columns, five rows, no chart. Each row is one thing somebody did on one date.
Density	USWDS default. 8px spacing unit, 64rem container, the shipped sans type scale (0.87 / 1.00 / 1.06 / 1.13 / 1.46 / 2.13rem).
The bold thing	Grade arithmetic, honoured and printed. Every same-family pair states its grade difference; `--pair` measured every cross-family pair, and the measurements are a table in the spec panel.

The order

Both results run in the resident's order, not the record system's: the word, what it means for this household, what to do today, which half is which, what happens next, and only then the evidence. The record table is last in each section and the two record actions sit under it, where a person who wants to argue with the answer is standing.

The second state

The empty index. 1602 Halsey Street NE is on a street annexed in 2019 whose previous owner kept tap cards on paper, so the district holds no records at all. It reads Unknown in the same slot the first result reads Lead, and the sentence under it is the whole of the state: no record is not an all-clear, federal rules count an unknown line as a lead line, so use a filter until somebody looks. The alert under that answers the other question an empty result raises — whether the page is broken — by saying why nothing was ever filed. The table keeps its caption and its columns, and its one row says what a record carries, which of the two things fills it first, and how long that takes.

Generator

tokens.css is generated output. Nobody hand-edits it.

uswds_tokens.py --family blue
uswds_tokens.py --family red
uswds_tokens.py --family gold
uswds_tokens.py --family green
uswds_tokens.py --family gray
uswds_tokens.py --guarantee
uswds_tokens.py --pair <a> <b>      # once per pair listed below

--guarantee, re-derived over 2,069 same-family pairs: difference ≥ 50 reaches 4.5:1 in 606 pairs, 0 failures, tightest 4.56:1 (gray-50 on gray-100); difference ≥ 40 reaches 3:1 in 879 pairs, 0 failures, tightest 3.14:1 (gray-60 on gray-100). A difference of 49 tops out at 4.49:1, so 50 is a real threshold. The rule holds within a family only: blue-50 on red-50 is 1.00:1.

Every pair on the page, measured

Pair	Where	Grades	Measured
`gray-90` on `gray-1`	Body text	89, same family	16.79:1
`gray-1` on `blue-60v`	Primary button label	cross-family	6.55:1
`blue-60v` on `gray-1`	Links, step numerals	cross-family	6.55:1
`gray-1` on `blue-80v`	Masthead, spec panel	cross-family	13.29:1
`gold-20v` on `blue-80v`	Strapline, panel headings	cross-family	8.22:1
`red-60v` on `red-5v`	Lead chip, lead panel	55, same family	6.43:1
`gray-90` on `gold-20v`	Unknown chip	cross-family	10.38:1
`gray-90` on `gold-5v`	Unknown-record alert	cross-family	15.18:1
`gray-60` on `gray-5`	No-records chip	55, same family	5.87:1
`gray-1` on `blue-90`	Footer, generator block	cross-family	17.46:1
`gray-60` on `gray-1`	Hints, column labels, input border	59, same family	6.52:1
`gray-90` on `red-5v`	The word Lead, on the answer field	cross-family	15.87:1
`gold-20v` on `blue-90`	Links in the identifier	cross-family	10.80:1
`blue-40v` on `gray-1`	Focus ring against the page	cross-family	3.12:1
`blue-40v` on `blue-80v`	Focus ring against the masthead	40, same family	4.26:1
`blue-40v` on `gray-5`	Focus ring against the search band	cross-family	2.81:1
`blue-40v` on `blue-60v`	Focus ring against the primary button	20, same family	2.10:1
`blue-40v` on `gray-60`	Focus ring against the input border	cross-family	2.09:1

The focus ring is the finding this page owes to its own rule. blue-40v is USWDS's own focus colour, and the first version of this page measured it against one ground — the page, 3.12:1 — and recorded that it cleared 3:1. It lands on five. It clears the page and the masthead and misses the search band, the primary button and the input's own border, all three by enough to matter, and the grade rule cannot see two of those because they are cross-family. A 2px gray-1 keyline now sits between the control and the blue, at 6.55:1 on the button and 6.52:1 on the border, and carries the boundary the blue cannot. The measurement is the answer, in both directions — including when it is the answer you did not want.

gray-50 on gray-1 is difference 49 and 4.49:1, so the muted text on this page is gray-60.

Deviations

One theme. USWDS 3.14.0 ships one appearance. --list-themes returns base and vivid, two saturations of the same 25 families at the same grades, not a light and a dark palette. The page declares no dark block and pins color-scheme to light.
Surfaces are gray-1, not white. The generator emits no white token and the contract rules out a hex.
The record table takes a wider measure than the prose, from 72em up, by 4rem each side. USWDS argues its 64rem container from prose measure; a six-column evidence table is not prose, and the breakout never reaches the viewport edge. The caption stays on the prose edge, since it is prose.
Under 48em each record becomes six labelled lines, with the date and the metal sharing the first of them. 48em is the width at which the container first holds the table's 44rem, so the table never scrolls sideways at any width. The version it replaced cut the caption mid-sentence at 390px and put Material, How we know and Evidence off-screen with no affordance to say so. Stacking with display changes costs the table semantics at that width; the labels are rendered from data-label so every cell still reads with its column name.

Gates

audit_page, slop_scan, craft_lint, motion_lint, layout_lint, copy_lint, direction_check --ledger, aria_lint and uswds_lint all run clean of errors and genuine warnings. Verified in Chromium at 320, 375, 390, 640, 767, 768, 1152, 1440 and 1920: no horizontal scroll at any width, no element scrolling sideways inside the results, one h1 with no skipped level through h4, three tables and three captions, eleven tab stops in reading order each carrying the 4px blue-40v ring over a 2px gray-1 keyline, 44px controls, no title= tooltip, no <img>, and no script on the page at all.