← Back to the screen

Design system portfolio

Design record: Find your lead service line

The four direction lines behind this page, the generator command that produced its tokens, and the pairs it was measured against.

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

LeverDecision
ArchetypeIndex. 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 stanceTable-first. Six columns, five rows, no chart. Each row is one thing somebody did on one date.
DensityUSWDS 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 thingGrade 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, until a crew looks treat it as lead and use a filter. A filter alert sits under that, then the alert 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

PairWhereGradesMeasured
gray-90 on gray-1Body text89, same family16.79:1
gray-1 on blue-60vPrimary button labelcross-family6.55:1
blue-60v on gray-1Links, step numeralscross-family6.55:1
gray-1 on blue-80vMasthead, spec panelcross-family13.29:1
gold-20v on blue-80vStrapline, panel headingscross-family8.22:1
red-60v on red-5vLead chip, lead panel55, same family6.43:1
gray-90 on gold-20vUnknown chipcross-family10.38:1
gray-90 on gold-5vUnknown-record alertcross-family15.18:1
gray-60 on gray-5No-records chip55, same family5.87:1
gray-1 on blue-90Footer, generator blockcross-family17.46:1
gray-60 on gray-1Hints, column labels, input border59, same family6.52:1
gray-90 on red-5vThe word Lead, on the answer fieldcross-family15.87:1
gold-20v on blue-90Links in the identifiercross-family10.80:1
blue-40v on gray-1Focus ring against the pagecross-family3.12:1
blue-40v on blue-80vFocus ring against the masthead40, same family4.26:1
blue-40v on gray-5Focus ring against the search bandcross-family2.81:1
blue-40v on blue-60vFocus ring against the primary button20, same family2.10:1
blue-40v on gray-60Focus ring against the input bordercross-family2.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

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.

Uplift round (2026-10-29)

What changed, and why. The archetype, the people and the generator flags are unchanged; tokens.css was not touched.

Round two: the first screen is the answer (2026-10-29)

A cold critic scored the first fold 4.5/10: the title sat in the left third of a white band, the answer started near 500px, the drawing was cut at the fold, and the type jumped from 16px to 40px. Now, at 1440x900, one screen holds the address as entered (xl, 2.13rem, the city on a second line at md), the word at 2.5 times the 2xl step (106px), both halves of the pipe drawn beside it with the curb stop between, and the warning alert as a full-width bar under both. The grey search band is gone: the title and the search share one compact row on the page ground, the way a USWDS results page keeps its search reachable and second. Steps in use above the fold: 1.00, 1.13, 1.46, 2.13, 6.65rem. On a phone the lede is dropped from that row so the word lands at about 540px. The old grey search band no longer exists, so the blue-40v on gray-5 pair above applies to the banner only; the search field's ring now sits on gray-1 (3.12:1). The address hint is shortened to one line; the apartment note remains in the correction form.

Round four

Round nine: the world-class pass (2026-11-09)

Heuristics, ten, 0 to 4: 30 before, 34 after. Status 3 to 4, recovery 3 to 4 (the failed search said "not found" and left a result under it; now it says what to type and labels the result as the last one), match 3 to 4 (the filter and the cost now say where and how much), help 2 to 3 (the filter has an address and hours). Still under 3: flexibility, 2. A repeat visitor retypes the address; the page keeps none. Held at 3: control, consistency, prevention.

Fixed, severity-sorted:

Left, with reasons:

Round ten: the harsh second read (2026-11-09)

Heuristics, ten, 0 to 4: 34 before (round nine), 31 after a cold read, 35 after the fixes. The cold read took status, recovery and help down a point each: the sent form changed nothing on the page it was about, the filter instruction ended too early, and the diagram's hatch was explained nowhere.

Fixed, severity-sorted:

Left:

Inventions, each minimal: "the middle income for households in our area" is the definition of a median; the pending note on the records is a state the brief did not describe, and its promise that records change only after review follows from "we change the record if you are right"; "until we tell you to stop" is the district's wording for an end date the brief leaves open.

Driven after the last edit at 1440, 1920 (dark scheme), 390 and 360 (touch): search to each result, failed search, look up another, the three-step form to Send, the confirmation and its link; no horizontal scroll, no console error.

Round thirteen (2026-11-10)

Round fifteen (2026-11-10)

Round seventeen (2026-11-10)

Round nineteen (2026-11-10)