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, 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
| 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-themesreturnsbaseandvivid, 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 pinscolor-schemetolight. - 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
displaychanges costs the table semantics at that width; the labels are rendered fromdata-labelso 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.
Uplift round (2026-10-29)
What changed, and why. The archetype, the people and the generator flags are unchanged; tokens.css was not touched.
- The answer is a band, edge to edge, with the word at twice the
xlstep (clamp(2.66rem, 15vw, 4.26rem); the skill's table stops atxl2.13rem and a one-word answer is the one place a display step earns its size). Beside it the service line is drawn: a rail with our pipe, the curb stop, your pipe. Lead is solid red; anything the rules count as lead without a look is hatched, so the two read apart in greyscale. The warning (lead) and notice (unknown) alerts sit under the word in the band. - Official banner with its expanding explanation (a
detailselement, so it works without script), and a full identifier. Deviation: the banner says "An official website of the Cascade Ridge Water District", not "of the United States government", because a water district is local government. - Alerts use the five USWDS variants as specified: warning (lead instruction), info (why nothing is filed), error (form summary), success (sent). Summary box is "Before you start". Step indicator with the heading counter,
aria-current="step", three segments. - The one interaction: a three-step correction with a review step. Validation follows USWDS: an error alert at the top that takes focus, each entry linking to its field, and a message plus a 4px bar on the field. Fixing a field clears its error as the person types. On the review step every Change link returns to the exact field, relabels the button "Save and check your answers", and brings the person straight back.
- Real federal-form edge cases: a single full-name field with a hint that accents, hyphens and apostrophes are fine (Zoe with a diaeresis, Nunez-Alvarez with tilde and acute); street address plus an apartment line that says units share the building's line (the search also ignores a trailing "Apt 3B"); state select; ZIP or ZIP+4; a three-field memorable date (month select, day, year) that names what is missing, rejects 30 February, and rejects a date after the page's own today; a 300-character count that announces on a pause.
- Dates, money, counts agree. US format throughout. The page's today is Monday March 9, 2026. Ten working days from it is March 23, 2026 (the success message). Form due March 27, openings March 24 and 25, replacement week of April 13, a card two weeks before. Five records, two where a crew looked at the pipe. $2,500, 80% of area median income. One phone number.
- Phone first. The record becomes labelled lines, the line runs down the page, buttons go full width, the review rows keep Change within thumb reach.
- Still one theme. USWDS ships one appearance; the page stays pinned to
color-scheme: lightin both schemes, as before. - Script returns, small, inline: banner needs none; the search jump, the steps, the checks and the review need it. Without it the form is one page with a plain Send button.
- New pairs measured with
--pair: red-60v on gray-1 6.81:1, gray-90 on blue-5v 15.53:1, gray-90 on green-5 15.16:1, gray-60 on red-5v 6.16:1, gray-60 on gold-5v 5.89:1, gray-60 on blue-5v 6.03:1, red-60v on gray-5 6.13:1. The unfilled step segment (gray-30) is decoration; the heading counter carries the state in text. - Boson: the skip link's offscreen-panel and the launch-check policy findings are artefacts (an intentional skip link; a specimen is not a site).
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
- The pipe diagram has its own hierarchy. The three places (water main, curb stop, meter) are the labels: 700 weight, one step larger, with the sentence about each in a quiet muted weight beside them; the segment notes are muted too. Screen readers still hear "Water main, under the street".
- The second answer is marked. A dark rule with a "Second address" tag and one line ("The answer when the district holds no records. The same page, the other state.") sits between the two results, so scrolling from 1428 to 1602 Halsey reads as the other state, not a stall. Neither result is hidden.
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:
- Sev 2. A failed search left the last result under the error as if it were the answer. The label now reads "Last result, for", and returns to "Result for" when a search succeeds. The error also says what is wrong: no house number gets "Start with the house number, then the street, like 1428 Halsey Street NE"; a miss echoes the address back in quotes and says to check the spelling.
- Sev 2. The urgent action had no path. "Pick up a free filter at any district office" named no office. It now names the counter (400 Ferry Road, weekday hours, matching the footer) and links "ask us to post one".
- Sev 2. The Unknown result said "use a filter" and said how to get none. It now carries the same filter alert as Lead, above the alert that says why the district holds nothing.
- Sev 2. Claims that outran their source. "Federal rules count an unknown line as a lead line" is gone. EPA's published rule text asks a system to notify customers of a line whose material it does not know and to identify every unknown line by the replacement deadline; the page says that. "We are replacing both halves" became "our half, and yours too if you say yes".
- Sev 2. Two instructions disagreed. Six months of cartridges, but "keep using the filter until the second result", which arrives at about three months. Now six months in both places.
- Sev 2. A dead end in the cost. "The state grant covers the rest if your household earns under 80% of area median income" said nothing for a household that earns more. It now says the district quotes the rest in writing before any work starts.
- Sev 2. A record that could not have seen what it claims. A 2016 meter replacement was filed as a crew seeing our side of the pipe, which a meter crew cannot see. It is now a curb stop valve repair. The count (two records where a crew looked) and every date still agree: May 14, 2024; February 20, 2025; March 9, 2026 as today.
- Sev 1. "What happens next" was the same size as the steps under it. Section headings are now 1.46rem over 1.13rem step headings, and the evidence table has a heading of its own, so "See the records" lands on a title.
- Sev 1. Step dates (the deadline is the most useful word in each step) are bold ink, not small grey. "Enter the month, day, and year" has its comma and its "and". Link targets under a coarse pointer are 44px high. The design-notes line about narrow screens describes the page as it is rather than the version it replaced. Footer prose uses
text-wrap: pretty, so no word is left alone on the last line.
Left, with reasons:
- Sev 0, taste. At 1920 the page is the 64rem USWDS container with 480px on each side. That is the system's own measure, argued in the deviations above.
- Unsourced, flagged, not invented. Three details are the fictional district's own policy, not federal rule, and are written as the district's: the $2,500 and the 80% of area median income grant, tests "three days and three months after", and the two-minute flush after six hours. EPA's 3Ts and state guidance give flush times from 30 seconds to several minutes and warn that flushing is not a substitute for a filter, which is why the page says to use the filter regardless. Whether a system may charge a household for its side is governed by the rule and by state law; this page does not claim a federal position on it.
- Phone numbers are all (425) 555-0142, inside the fiction range.
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:
- Sev 3. The filter instruction stopped at the wrong moment. The warning read "until both sides are replaced" while step 3 said to keep the filter for six months, and the Unknown warning read "until a crew looks", which a resident who then learns the line is lead would take as permission to stop. The first is now "until six months after both sides are replaced", the second "until we tell you to stop", step 3 starts "After the work", and the correction's success message says the same instead of "until then".
- Sev 2. The urgent line sat below the answer. On a phone the warning began at the bottom edge of the first screen. Both answer sentences now carry it ("Use a filter for drinking and cooking now"), ahead of the replacement offer.
- Sev 2. The act changed nothing it touched. A sent correction now shows "Correction requested", its reference and its reply date at the top of the records it is about, and the confirmation links to it. The note says the records do not change until the district has looked again.
- Sev 2. A figure with no help beside it. "80% of the area median income" now says what that is in the same sentence. The hatched pipe has a one-line key under each diagram.
- Sev 2. A self-check read as a clearance. The photo option now says to keep the filter until the district writes back.
- Sev 1. "Call to say yes" became "Call to replace your side too" and "to book an inspection". Counter hours are written once, "8 a.m. to 6 p.m., Monday to Friday", as in the footer. "Look up another address" at the foot of each result returns to the search with the old address selected (flexibility, still the weakest heuristic). The second-address bar no longer describes the design; it says which search gives the result. A reference number cannot break at its hyphens.
Left:
- Sev 2. Cartridges cover six months; "until both sides are replaced" can be longer for a household that declines to replace its side. The page does not say what happens then. That is the district's policy to write; not invented.
- Sev 1. A sent correction has no undo. The review step is the confirmation. "Send another" is the only way back, and nothing says the newest is read.
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)
- Defect. A dark "Second address" band ("Search for 1602 Halsey Street NE to see the answer when the district holds no records for an address") sat between the two results. It was an instruction to a reviewer, and both results were stacked on the page at once, which no resident sees. Reproduced at 1440: the band was present and both results had height.
- Fix. The band and its
.lsl-casestyles are gone. The page now shows one result at a time, the one for the address in the search field.result-2startshidden;showResult(id)shows the searched address and hides the other. Round four's "second answer is marked" decision is superseded: with one result on screen there is no second state to mark. - How each state is reached, by a resident's own actions.
- Records found (lead): the page opens on 1428 Halsey Street NE; typing "1428 halsey st ne" in any case or abbreviation, then "Find my record", returns here.
- No records (unknown): type 1602 Halsey Street NE (any case or abbreviation) and press "Find my record". "Look up another address" at the foot of each result returns focus to the field with the old address selected.
- Address not found: type anything else, such as 77 Nowhere Avenue, or leave the field empty. The error shows, and the result on screen is labelled "Last result, for".
- A sent correction: the form's street decides which records show it. "See it on your records" now first shows that address's result and puts its address in the search field, then jumps to its records, so a correction for 1602 does not point at a hidden section.
- Invention. None in copy. Without JavaScript only the 1428 result shows; the search needs script in this prototype either way (its form posts back to the same file).
- Correction form opens empty. The form opened with sample data: full name "Zoë Núñez-Álvarez", street "1428 Halsey Street NE", city "Cascade Ridge", state WA and ZIP 98053 (set in markup and again in script, and again by "Send another"). All five are gone; the fields carry only their USWDS labels, hints and autocomplete tokens (name, email, address-line1, address-line2, address-level2, address-level1, postal-code). The name hint no longer quotes the sample name; it reads "Write it as it appears on your bill. Accents, hyphens, and apostrophes are fine." The non-ASCII check lives here, not in the field: a name with a diaeresis, tilde and acute ("Zoë Núñez-Álvarez") typed into the empty form reaches the review step and the confirmation unchanged (NFC-normalised on review). An empty submit still lists six problems on step 1 and three on step 2. The one value that can still arrive in the street field is the address the resident searched for, copied in after a search unless they have typed there themselves.
Round fifteen (2026-11-10)
- Defect 1, reproduced (1440, 390). "Ask us to correct a record" scrolled to the form and left
document.activeElementon BODY. Fix:#c-titlehastabindex="-1", and everya[href="#correct"]runs a click handler that scrolls the heading to the top and focuses it (smooth unless reduced motion). The heading carries the existing[tabindex="-1"]focus-visible ring. Without script the link still jumps to the same anchor. Checked at 1440, 390, 360 and 1920: active element isH2#c-title. - Defect 2, reproduced (1440 x=176 against heading x=240; 1920 x=416 against 480). The record table broke out 4rem each side from 72em up. That decision (see Deviations) is reversed: the table now starts on its heading edge at every width, 960px wide at 1440 and 1920, with no change in row wrapping. The breakout rule and the caption inset are gone.
- Defect 3, reproduced. "Call by March 27, 2026" ended step 2 while the Call button sat under the whole list after step 3. The button now sits inside step 2, directly under its deadline, and the list-level actions block is gone. Same link, same label.
- Extra, reproduced (390 and 360, coarse pointer). The "Based on 5 records" line had a loose line gap: the "See the records" link is inline-block with 44px-tall padding. A matching negative block margin keeps the tap target and returns the line to normal leading.
- Invention. None. No copy changed.
Round seventeen (2026-11-10)
- Defect, reproduced (1440). After a lookup, "Ask us to correct a record" opened a form that asked again for the address just looked up. On the default 1428 result Street and City were both empty; after a search for 1602 the street was copied in but City, State and ZIP were still empty.
- Fix. Step 1 of the form now carries the address on show. Under "Service address" a record row reads "Record to correct", the street, the city, and a "Change" link, in the same row pattern as the review step. The street and city come from the heading of the result on screen (
carryAddress(), called fromshowResult, so every successful lookup updates it) and are written into the hidden street and city fields, so validation, the review, the confirmation and "See it on your records" keep working. A failed or empty search keeps the last result on screen, so it leaves the form on the last good address. "Change" opens the full address fields (street, unit, city, state, ZIP) filled with the carried street and city and moves focus to Street; "Use the address I looked up" closes them, drops what was typed and returns focus to Change. In that opened state a later search leaves the typed address alone. "Send another" resets to the carried record. Step 1 now has two required fields (name, email) in the carried state; the review shows street and city only. - Kept. Focus on
H2#c-titlefrom "Ask us to correct a record"; no name, phone or email is prefilled and no sample person exists. - Invention (named). Rule: a lookup carries street and city, which is all the page knows of the address, so State and ZIP are asked only when the resident chooses Change. The page states no state or ZIP and none was made up. The 1602 result has no "Ask us to correct a record" link (unchanged); its form, further down, carries 1602 all the same.
Round nineteen (2026-11-10)
- Defect, reproduced (1440, 390, 360, 1920). After a successful search the result heading was scrolled to the top edge, so the "Result for" eyebrow above it was cut off (scrollY 325 at 1440 and 1920, 461 at 390, 482 at 360; eyebrow top -9px).
- Fix. The submit handler scrolls the whole result section to the top (
$(id).scrollIntoView) instead of its heading, and still focuses the heading withpreventScroll. The page's ownscroll-padding-top(--u-2, 16px) is the gap above the band. After a lookup the eyebrow top is 64px at 1440 and 1920, 56px at 390 and 360, and the heading bottom is inside the viewport. Measured for 1428 (found), 1602 (unknown), an empty submit and 77 Elm Court (not found): the last two keep the page at the search with the "Last result, for" eyebrow below it (top 368 to 549px), never above the viewport. - Invention. None. No copy changed.