changelog.md

# Change log

> **Historical record, Human Essentials migration, 2026.** See
> [`docs/field-notes.md`](field-notes.md) for how to read this alongside the other evidence
> documents from that migration.

A running record of what changed, in order, with the commit that carries it. The companion
documents answer different questions:

| Document | Question it answers |
| --- | --- |
| **This file** | What changed, when, and where to find it. |
| [design-decisions.md](design-decisions.md) | Why a judgement call went the way it did. |
| [migration-map.md](migration-map.md) | What replaced what, and how to verify a page. |
| [design.md](../design.md) | How to build a screen now. |
| [domain-model.md](domain-model.md) | How the records relate. |
| [todo.md](todo.md) | What was found, verified, and deliberately not fixed yet. |

Newest last. Dates are commit dates.

---

## Phase 1 — Foundation (2026-08-17)

Tailwind installed alongside the existing stack, so that nothing broke while pages were moved
across one area at a time.

| Commit | Change |
| --- | --- |
| `d4ec1e400` | Design system documentation, and the layout accessibility baseline: skip link, one `<main>`, `lang` bound to `I18n.locale`, zoom lock removed. |
| `8e98ea0be` | Tailwind v4 via `tailwindcss-rails`, no Node. Tokens, Figtree and Bootstrap Icons self-hosted. |
| `6a01113ea` | The app shell and the component layer: `essentials_app`, `essentials_partner`, `essentials_auth`, and `shared/essentials/*`. |

## Phase 2 — Area by area (2026-08-17)

Each commit moves one area onto the new shell and leaves the rest untouched.

| Commit | Area |
| --- | --- |
| `d2a2ed4ec` | Dashboard |
| `f35dca40a` | Authentication |
| `0e4e811aa` | Storage locations |
| `a5e7f044a` | Vendors, manufacturers, donation sites, product drive participants |
| `f02fbdd0d` | Donations |
| `f2e1963f7` | Purchases; the "add a new one" modals became native `<dialog>` |
| `39b24a53f` | Product drives, barcode items, item categories |
| `db4dba1bd` | Requests |
| `587ef132d` | Distributions |
| `6f6f6252c` | Transfers and adjustments |
| `eaf175fac` | Items, kits, audits — inventory complete |
| `1a20d6e64` | Bank-side partner management |
| `691d662ad` | Partner portal shell and profile partials |
| `0b27c58da` | Partner portal |
| `007c4d41a` | The remaining bank-side areas |
| `f3a0f2b42` | Indentation autocorrect after the sweep |
| `71ed53360` | Icons, error pages, account request flow |

## Phase 3 — Removing the old stack (2026-08-17)

| Commit | Change |
| --- | --- |
| `cda053539` | Deleted the Bootstrap/AdminLTE view layer: five layouts, four navbar and sidebar partials. |
| `3efdd73a2` | Removed Bootstrap, AdminLTE, sass-rails, bootstrap-select and the Font Awesome CDNs from the `Gemfile`, the asset path and the importmap. |

After this point a legacy class is a defect, not a page awaiting its turn: nothing defines
those class names any more, so they render as nothing at all.

## Phase 4 — What removal exposed (2026-08-18)

Deleting the old stack turned silent breakage loud. The system specs went from 298 failures to
zero across these commits; several were pre-existing bugs the old markup had been hiding.

| Commit | Change |
| --- | --- |
| `4a50aa72d` | Helpers, icons, the last accessibility fixes. |
| `93d8295a5` | The Bootstrap markup the browser sweep never reached. |
| `2c3341476` | `design.md` rewritten as the Tailwind specification. |
| `4db829472` | Test clock shim, confirm mechanism, flash hooks. |
| `f5611e000` | Admin navigation and the staging warning restored. |
| `62ef1a7ce` | Four broken controls; the partner show page's structure. |
| `b0d6169b9` | **Approve partner posted to a GET route.** A pre-existing bug. |
| `415719d7f` | **The distribution confirmation never ran**, and forms submitted with `<input>`. Pre-existing. |
| `8942e5a69` | Cold-start empty states given their own wording; two stale globals fixed. |
| `2b1a7496e` | Spec selectors retargeted at what they mean, not at styling. |
| `86b4f9eeb` | Three defects in the admin area; select2 had no stylesheet. |
| `f0dfb990d` | The account request form's reveal. |
| `18204c6bd` | **The partner profile form's fields were outside the form.** Pre-existing. |
| `8d4b8b742` | Request specs updated to the migration's copy. |
| `8d5f93060` | The date picker is asked whether it is open, rather than trusting a global. |
| `ee1d8b410` | Decisions from the system spec pass recorded. |
| `d49e4ce5d` | The last classes that draw nothing; browser sweep checked in. |
| `6077ba541` | Wait for the date picker before typing into it. |

## Phase 5 — Error pages and local access (2026-08-18)

| Commit | Change |
| --- | --- |
| `7cd23ab5b`, `1ef1dcb26` | `403`, `404`, `422` and `500` rebuilt as self-contained documents: inline tokens, vendored typeface, no stylesheet or script, because they must render when the app cannot. |
| `839bcf57b` | Behind a proxy, relax the CSRF origin check rather than forcing https. Forcing `assume_ssl` broke plain-http port forwarding with "Your session expired". |

## Phase 6 — Documentation (2026-08-18)

| Commit | Change |
| --- | --- |
| `20c0b0587` | `design.md` made to stand on its own, opening with the domain rather than the components. |
| `fee6f6090` | `migration-map.md` added. |
| `e3092bf80` | `onboarding.md` added (maintainers). |
| `dffb25b7f` | Keeping these documents current made a standing instruction in `CLAUDE.md`. |
| `dfb7b8f89` | `domain-model.md` added, read off the models rather than recalled. |
| `b5bc183e6`, `57e8cddc3` | The last references to the design system's origin app removed, including from the ADRs; one sentence mangled by that edit repaired. |
| `f61d7a22e` | The user-facing half of `onboarding.md`. |
| `dbe7418b1` | **Four invisible icons** on the bank-side partner profile editor. Found by grepping for undefined classes, not by the tooling. |
| `3cf21e1f9` | This change log. |
| `f61a4fd5f` | The migration map brought to the current measured state; the grep for undefined classes promoted into the verification commands. |
| `4f7b7fdd1` | `design.md` given the full document set and its measured status; today's four decisions logged; the standing instruction in `CLAUDE.md` extended to six documents and a stated cadence. |
| `0fd3f13ca` | A change log hash orphaned by an amend, corrected; the ancestry check and the reason the last row lags written down. |
| `e0c31a7e9` | All 27 index tables audited for row-action weight and badge density; `docs/table-audit.md` and `bin/design/table-audit.js` added; the row-action and badge rules made explicit in `design.md`. |
| `bc04f2243` | Corrected the audit: the empty `recertification_required` action cell is right, not a defect. |
| `a9f8d26ab` | **Every table row action is now `:ghost`.** 13 cells across 12 views moved off the legacy `*_button_to` shims and off `:secondary`. The audit script reports 0 tables with more than one weight, down from 7, and 0 filled buttons in rows, down from 6. |
| `e6ac2c21d`&hellip;`011c24fbb` | Partner list rebuilt on the shared filter bar, developed on `design-preview-partner-status` over five review rounds. |
| *(merge)* | **`design-preview-reports-hub` merged into `design`** — 13 commits, 139 files. Reports, page actions, 49 form and show pages, and the WCAG audit. Verified on the merge: 2904 examples 0 failures, axe 0 violations across 61 pages, all interaction checks pass, rubocop and erb_lint clean. |
| *(reports hub branch)* | **All 9 show pages cleared.** `bin/design/page-audit.rb` replaces the form-only script and covers show, index, form and partial, separating defects from debt. Found: a `<tr>` never closed, five `<td>`s closed with `</th>`, one `<h1>` per section inside a loop, an empty `<h2>` card header, and ten `width: %` inline styles summing past 100%. |
| *(reports hub branch)* | **All 40 form pages from the audit rewritten**, in three batches: partner portal, admin area, bank-side. `page_header` with a back link, the card component, fields through `f.input`, fieldsets for radio and checkbox groups, sentence case. Found on the way: three forms whose divs did not balance so the submit sat outside the fields, a stray expression printing `true` onto a page, a second `<h1>`, an empty collapse button, and an inline `<style>` block duplicating the vendored trix CSS. `bin/design/form-audit.rb` reports 0 findings, down from 40. |
| *(reports hub branch)* | Partner groups given their own page and URL; the Groups tab became a link so the page's primary action follows it, removing the fourth button that sat above the table. New `page_tabs` component for tabs that navigate. `docs/form-page-audit.md` added: 40 of 98 form pages still hand-roll their header, card or inputs inside a correct shell. |
| *(reports hub branch)* | **Reports rebuilt.** Four summary reports removed and their figures folded onto the index pages they duplicated; `<tfoot>` totals dropped in favour of a filtered band above the table; old report URLs redirect. The sidebar's 15-item Reporting group became one rail entry leading to a six-card hub for the eleven reports an index page cannot show. On `design-preview-reports-hub`; mockup in `docs/mockups/`. |
| *(merge)* | **Merged into `design`.** Status chips replaced by a labelled select; single-filter bars apply on change and drop "Clear filters"; "All statuses" added; status colour now means *who is blocked*; pill icons dropped and pills no longer wrap. Two bugs fixed on the way: a blank status filter matched every partner including deactivated ones, and the select chevron sat 4px from the border because padding does not move a native arrow. |
| `51b81a0cd` | Two modulepreload links dropped from every page: the `@fullcalendar/core/` directory pin, which has no module at its URL, and `sinon`, 180KB of test-only fake-timer support. The dead `esms-options` script removed from the shared head — es-module-shims has not shipped with importmap-rails since 2.0. 66 preload links per page, down to 64. |
| `152ca4b34` | **The last 42 view defects cleared** — 14 index pages and 30 partials. `bin/design/page-audit.rb` reports 329 views, 0 defects, 3 documented items of debt. |
| `751d16757`, `1d17753f6` | Date range picker options mocked up before building: the measured diagnosis, three industry patterns, and the wire-format constraint. The injected-rule count corrected from an estimate to a measurement, 72. |
| `e64e7a42b` | **Litepicker replaced by a preset `<select>` plus two native date inputs.** Both unversioned jsDelivr pins removed, along with `window.isLitepickerActive` and 102 lines of `application.js` (192 lines to 90). Preset ranges now computed server-side in `Time.zone`, so "Today" cannot disagree with the day the query filters on. Two latent bugs fixed on the way: the server rendered *prose* into the `filters[date_range]` field and Litepicker overwrote it during setup, and `filters[date_range_label]` carried that same prose rather than the preset name, so every named period collapsed to the generic wording after one round trip. Validation moved from `window.alert()` into the page. Three unused spec page objects pointing at the removed summary routes deleted. Wire format unchanged. |
| `d955031f7` | The "showing" line mocked up before building. Measuring `#date_range_label` first is what found that it could not produce the sentence: 4 of 13 outputs wrong, ambiguous or empty. |
| `1bb4d1d76` | **The selected period is now said in words**, in a sentence-case caption above the stats band on 4 index pages and in the `:no_results` empty state on 7. `#date_range_label` fixed first — **five** bugs, none of which anything could have caught because nothing read the method: `to_fs(:short)` carries no year, so *All time* rendered as "during the period 19 Aug to 19 Aug"; *This year* and *All time* had no clause and fell through to their dates; a range starting today returned `""`; and with no parameter it claimed "this year", which is the state every index page opens in and describes neither the default window nor anything else. The preset/clause pairing is now tested exhaustively. |
| `ab982834f` | The summary band mocked up before rebuilding. `CLAUDE.md` told to document and push without being asked; the `<iframe srcdoc>` / rack-mini-profiler trap recorded in the mockup README. |
| `c58dac6aa` | **The summary band is one card with hairline separators**, and its column count follows the figure count. It was a flat `sm:grid-cols-2 lg:grid-cols-3` whatever the number of figures, so it orphaned a tile on every page that had one — 3 + 1 at 1360px with four figures, 2 + 1 at 900px with three. Measured after: every row full at every breakpoint on all five call sites. The per-figure `slate-50` fill is gone, and the radius is 16px like every other card rather than 12px. Separators are a `gap-px` grid over a `slate-200` backdrop rather than `divide-x`, which borders by DOM order and so draws in the wrong place in any grid of more than one row. |
| `8a59c3297` | Filter bar and summary card options mocked up before building: the measured widths and trailing gaps, the Turbo Drive constraint on auto-applying, and three subheaders. |
| `2b5df7653` | **The filter bar is a grid**, so the controls are one width and the rows are full — it was `flex flex-wrap` with content-sized items, giving six widths across four pages and up to 852px of trailing space. 43 cell wrappers across 15 files. The summary card gained a title and a scope sentence (`essentials_stats_scope`), and `Default (recent and upcoming)` became `Last 2 months and next month`. |
| `a79452bd5` | **Filters apply on change, into a Turbo Frame; the Filter button is gone.** Sixteen bars plus the report card. Four details were each found by breaking them: `target="_top"` on the frame, without which every row action fetches a page with no matching frame and Turbo discards it (66 specs); `data-turbo="true"` on the form, without which Drive being off means a silent full page reload; `turbo_action: "advance"` to keep the URL shareable; and keeping the form outside the frame so focus survives. The export link is rebuilt from the form on each frame load — it sits outside the frame and would otherwise export the previous filter's rows. A `role="status"` region announces the new count, and `wait_for_filters` waits on network idle because Turbo never marks these frames busy. `events` and `distributions_by_county/report` were rebuilt rather than converted: both hand-rolled their filters, and `page-audit.rb` calls both clean. |
| `71f8468cc` | Filter density mocked up: the two defects measured, and three densities offered. |
| `1ae7f6e0a` | **The date range cell is one column like every other**, the actions follow the last filter instead of taking a row, and a bar of five filters or more collapses behind a Filters button with chips for whatever is set. `/donations` 264px to 38px, `/distributions` and `/requests` 188px to 38px, `/transfers` and `/items` to 64px from the two fixes alone. The threshold is counted in the partial so no call site decides it. Chips are built in the browser because the bar does not re-render when a filter applies. Three traps recorded in `docs/design-decisions.md`: `turbo:frame-load` fires on first connect too, so clearing the flash there deleted it on every page load; clearing the flash reflows the page and a coordinate-driven click lands where the button was; and the spec helper's quiet period has to exceed the 400ms text debounce. |
| `83a2fd534` | Filter consistency mocked up, and two bugs recorded with it: every modal opening top-left, and Calculate product totals living inside the filter bar. |
| `e543a08d7` | **Every dialog in the app was in the top-left corner** — 28 files. A native modal is centred by the browser's `margin: auto` and Tailwind's preflight resets it; one rule in `@layer base` restores that plus the `max-height` it also takes. `bin/design/overlay-audit.js` added, because the bug survived both existing audits: one reads markup, the other scans the page as loaded, and **neither had ever opened anything**. On its first run it found a second real thing, a dialog list that could not be scrolled by keyboard. Also: the disclosure threshold is gone so every filter bar behaves the same; the duplicate "Clear filters" inside the panel is gone; the date range is a popover, which removes the 216px cell that inline custom dates produced; the account menu moved onto the same `popover` controller and off `shadow-lg`; Calculate product totals moved into the page header; and Capybara's default wait went 2s to 5s, because filtering is asynchronous now and the failures read as wrong row counts rather than timeouts. |
| `c14ed96c2` | **Sidebar weight now follows the level, not the behaviour.** Dashboard, Reports and My organization were at the child weight (500/slate-600) beside Operations and Inventory at the parent weight (600/slate-700), all six at the same indent, so a top-level destination read as a child that had lost its parent. The rail's pinned item and the page footer are both `h-14` with a full-bleed border, so their rules meet at one height and run into the rail's `border-r` as a single line — they were 12px apart. Nav ordering written into `design.md`; *Reports* sitting at the top beside *Dashboard* is noted as against that rule and left pending a decision. |
| `8a90b6437` | **Reports moved below the working groups**, and nav spacing made uniform: one `space-y-4` between every top-level entry, where *Dashboard* and *Reports* had shared a list at the 2px inner spacing while everything else sat 16px apart. **The flash no longer clears when a filter applies** — that was added a commit earlier and is reversed here: removing 56px above the results shifts everything below it under the cursor, and it broke three specs that click a row action after filtering. One real bug found on the way: `auto_submit_controller` resolved its frame in `connect()`, but the form is parsed before the frame, so the export link and the announcement could silently never work. |
| `0536b3a68` | **Sprockets replaced by Propshaft** (ADR 0012). After the design system migration there was nothing left for a compiler to do: no `//= require` directives, no ERB assets, no Sass, no bundling, and one stylesheet the Tailwind CLI had already minified. Three pieces of configuration existed only to stop the compiler compiling — a disabled CSS compressor, an initializer rejecting the Tailwind source from the load path, and a hand-kept precompile list — and all three are gone, along with `manifest.js` and `terser`. Measured: the served stylesheet differs from the build by 24 bytes, which is Propshaft quoting 12 `url()` values; every font still resolves, icons render, 70 JS modules load, no failed requests. The development trap inverted — precompiling locally now *freezes* assets rather than refreshing them — and `CLAUDE.md`, `design.md` and `docs/onboarding.md` were updated to say so. |
| `292dfe41f` | The Propshaft row's own hash filled in — a commit cannot contain it. |
| `b56845b5c` | **Pagination audited across all 22 index tables**, and the nine mockups repaired: under Propshaft the undigested `/assets/tailwind.css` 404s, so every one of them had silently fallen back to Times New Roman. Found by measuring the heading font, not by looking. The audit's two findings: `items_controller` assigns `@paginated_items` and the name appears nowhere else in the repository, so the view renders all 51 items at 121px a row — a 6,442px page with no pager; and row heights differ 4.5× across the app, from 45px on `/users` to 205px on `/purchases`, which is why one page size cannot serve every table. |
| `081711102` | **Three page-size bands, and every unbounded index table now has a pager.** `Pagination::TALL/MEDIUM/COMPACT` (15/25/50) chosen by measured row height, so every full page lands between 1.8 and 3.4 screens; nineteen call sites name their band. Kaminari's default went from *5 in development, 50 elsewhere* to 25 everywhere — the split meant a page under review never looked like the page in production, so nobody ever saw the long table. Five tables gained a pager (audits, transfers, barcode items, announcements, admin base items) and `items` finally renders the collection its controller had always computed: 6,442px to 1,815px. Three defects found on the way, each on every page that used the component: the pager sat between **two** hairlines twelve pixels apart, because both the card footer and the partial drew the chrome; a single-page collection drew an **empty bordered strip**, because `capture` of a blank render is not blank in development where `annotate_rendered_view_with_filenames` puts a comment in the buffer — now `essentials_pagination_footer` returns `nil` instead; and page links did a whole-page visit rather than updating the results frame, losing the scroll position. `broadcast_announcements` was ordered with `.reverse` in the view, which reverses one page and not the collection, so it is ordered in the query now. Design options for the pager itself mocked up rather than built. |
| `727c59bda` | **The pager says how many rows matched.** "Page 3 of 19" became "Showing 31–45 of 272 requests" — option A of four designs put up in `docs/mockups/pagination-designs.html`. A page number is a proxy: it changes meaning whenever the page size does, which the three bands had just made concrete, and it never answered the question an index page's filter bar raises. The noun comes from Kaminari's `entry_name`, lowercased word by word so a word with an internal capital keeps it and a future `/admin/ndbn_members` reads "NDBN members". `« First` and `Last »` were kept although the mockup's A panel dropped them — jumping to the oldest record is a real task on audits and events. A rows-per-page select and load-more were both argued against in the mockup and not built. |
| `30cc779ee` | **The pager is always there, and so are its controls.** Option A of three in `docs/mockups/pagination-count-options.html`. A table that fitted on one page showed no strip at all — nine of sixteen index pages — so nothing said how many rows matched; measuring that turned up the same fault on longer tables, where the control set changed width as you paged (`/requests` was 7 controls on page 1, 14 on page 5, 8 on page 10). Now `‹ Prev` and `Next ›` are always drawn and disabled when they lead nowhere, `« First` and `Last »` appear only when there is more than one page, and the strip renders for any table with rows — an empty one still gets nothing, rather than a bar reading "0 of 0". Disabled is `<span aria-disabled="true">` at `opacity-60`, the app's existing treatment, measured at 2.88:1 against a live link's 7.56:1. Kaminari renders nothing for a single page by design and returns nil so the caller can supply fall-back HTML, which is the hook the one-page control set uses. Two passing bugs found on the way: `/product_drives` read "2 product drive", because Rails only pluralises a locale entry written as a one/other hash and `product_drive: "Product Drive"` is a plain string; and a spec context called "there are no organizations" had one, the super admin's own, created after its `delete_all` — its assertion passed only because a single page drew no Next. The filter announcement stops saying "Results updated" on paginated pages and reads the real total. |
| `3fc211c7f` | **The three historical trend pages migrated** — they were the last screens the first sweep missed. Their controllers had been given `layout "essentials_app"` and marked migrated in a comment; the views were never touched, so each was a bare Highcharts config with no page header, no card and **no `<h1>`**, and the tab title was just the organization name. Three near-identical 39-line files became one partial. Each now also carries the same figures as a table: `design.md` says a chart is never the only representation of the data, and these were the only chart pages in the app, so the rule had nowhere it was being kept. `bin/design/status.rb` was reporting them as migrated because its heuristic looked for `essentials_` with an underscore and so missed every `render "shared/essentials/…"` — it understated the migrated count by 51 pages and now excludes mailers and `static/` too. **A test-isolation bug surfaced on the way**: the test environment used the default `FileStore` cache under `tmp/cache`, which survives between runs, and `historical_data_cache_job_spec` writes a stubbed series into it — a bare Hash, a shape `HistoricalTrendService#series` cannot return. A later run read it back for a different organization that had been given the same id. 65MB and 9,317 files had accumulated. Test now uses `:memory_store` and the stub is the real shape. |
| `5a953fe9d` | **Callout extracted as a component** — 21 copies of the same twelve-class string across 20 files, each with its own margin baked in and no two agreeing on whether the role was `status`, `alert`, `note` or absent. Tint, border and glyph now come from `FLASH_STYLES`, the map the flash strip already used, so the two cannot drift into different shades of amber. Every call site's tone, role and margin were preserved exactly and the result diffed against the rendered pages to prove it. Two traps recorded in `design.md`: a partial rendered *somewhere* with a given local keeps it `defined?` and nil at the call sites that omit it, so `defined?(role) ? role : default` silently dropped the default on every callout that relied on it — `local_assigns` is the only safe idiom; and ERB tags inside an ERB comment end the comment early, which had already happened once in `_pagination`. |
| `46aea92d5` | **Dead scaffolding, dead classes and two unlabelled selects.** `donations/add_item`, `donations/remove_item` and `distributions/print` were Rails scaffold stubs from 2018 reading "Find me in app/views/…"; the first two had no controller action, so implicit rendering served that text to anyone who hit the route. Templates and the two dead routes removed. The four `account_requests` status pages were hand-rolled cards starting at `h3` with no `h1`, one with an orphan `</li>` and one with `style="color: #ff0505"` — rebuilt on the card and callout components. Classes that style nothing removed: `custom-select` ×3, `form-check`/`form-check-input`, `custom-control-input`, `text-md`, and `row flex-row` ×2 (which had no `flex`, so its alignment utilities did nothing either). Two selects were unlabelled: `admin/barcode_items` used `label_tag` with one argument, making `for="filter_by_item_category"` against `filters_barcodeable_id`, and `account_requests/new` repeated the `f.input`-wrapping-`f.association` defect already fixed once in `organizations/edit`. Two grids built their column class from a runtime value — Tailwind only generates a class it can find literally, so `lg:grid-cols-<%= n %>` worked by luck; both go through `essentials_grid_columns` now. |
| `11c7a3869` | **Disclosure extracted, and the last three hand-rolled cards cleared** — `page-audit.rb` reports **0 defects and 0 debt** for the first time. The FAQ lists and the partner profile accordion each hand-rolled the same open/close card, and the three copies had drifted: only one wrapped its trigger in a heading, only one put its row actions outside the button. `organizations/_details` had **two Edit buttons** on one card, and the top one was wrapped in `border-t` — footer chrome — so it drew a stray hairline above the heading; it is one card action in the header now. `bin/design/undefined-classes.py` added as a fourth audit: it reports the class tokens the stylesheet does not define, separating deliberate JS, spec and gem hooks from the 26 genuine orphans, which `migration-map.md` now lists with the reason each is left alone. `bin/design/status.rb` counts `render "shared/essentials/…"` as migrated markup and skips mailers and `static/`. |
| `6c3da46d5` | **The sweep asks the router now, and found eleven more unlabelled controls.** `bin/design/route-sweep.js` and `route-targets.rb` replace a hardcoded list of 56 paths with every GET route that renders HTML — 139 screens, visited as a super admin, a bank admin and a partner, with a real record id substituted for `:id`. The list is what hid the historical trend pages: they were in the sidebar, never on it, and had no `<h1>` for the length of the migration. On its first run the new sweep found the partner portal, which the old list never visited at all: nine unlabelled selects on the profile editor (`label: false` and nothing else, so the county and client-share controls had no accessible name), two on the child form, and an unlabelled file input. The two `date_of_birth` fields were the last in the app still using three dropdowns — simple_form labels only the year — and are now `html5: true` like every other date, with `start_year`/`end_year` becoming `min`/`max`. |
| `3c8401103` | **The storage-locations flake was a real bug in every row action.** It had been recorded twice as a pre-existing flake and measured at 4 runs in 8 on a clean `HEAD`. It is a defect: row actions are `button_to` forms inside a results turbo-frame, and Turbo's `elementIsNavigatable` returns true inside a frame **even with Drive off** — so Turbo intercepted the submission, fetched the redirect and had to promote it to a top-level visit because the frame targets `_top`. Half the time that did nothing: confirm accepted, PUT handled, page unchanged. `essentials_action_button` sets `data-turbo="false"` now, so the browser submits the form. 0 failures in 20 runs. Diagnosed by instrumenting rails-ujs — the failing and passing runs made identical server requests, and both fired `confirm:complete answer=true` and a `submit` event, which is what ruled out everything else. |
| `cfeee9130` | **Responsive audit: 163 screens × 5 widths, 700 combinations, now clean.** `bin/design/responsive-audit.js` added. The headline defect: at 320px `/items` could be **swiped 821px sideways**, taking the heading from `left: 16` to `left: -805` and leaving the user on blank space — Chrome counts content clipped inside a scroll container towards the root's scrollable overflow, so a data table properly wrapped in `.table-scroll` still moved the page. Fixed with `html { overflow-x: clip }` (`clip`, not `hidden`, which would make the root a scroll container and can break the `lg:sticky` sidebar). Also: the partner request history was a hand-rolled table with no scroll container, 248px wider than a phone; `/account_requests/new` broke out of the auth column by maths that ignored `lg:w-1/2` and landed 12px past the viewport at exactly 1024; the events table's links had **no classes at all**, so under preflight they were invisible as links and 6px wide as targets; and the drawer's open/close buttons were 32×32 and 22×32, now `size-11`. Checkbox labels gained `py-0.5` so a choice row meets 24px. **`wcag-manual.js` had measured the decisive signal into a variable called `scrolled` and never read it** — that is how the 821px shipped past a clean audit. Both audits now swipe rather than calling `scrollTo`, which is the only measurement that matches what a finger can do. |
| `5f67fbba5` | **The date range applies itself, reorders itself, and fits in its button.** The Apply button is gone — it was a second click for something the user had already said, and Stripe, Shopify, Linear and Notion all commit on selection. The argument for keeping it was that two separate date fields cost two requests; that is a 350ms debounce, not a second click. The panel stays open while custom dates are edited (only a preset closes it), and the From/To fields stop their `change` bubbling to the filter bar — without that, editing a date fired a query carrying the **previous** range and then another with the new one. Measured on `/donations`: three requests for one edit, now one, and it carries the right range. An end-before-start range now **reorders** instead of showing "The end date must be on or after the start date." and refusing, which is what Google Flights, Airbnb and Material's range picker do. And the trigger shows `6/19/2026 – 9/19/2026`: spelled out it needed 233px in a 223px button and was truncated, so the one thing the control exists to say was the part cut off. Wire format untouched — `strptime` still gets "%B %-d, %Y". |
| `cb86ecdd0` | **Second responsive pass, widened: 1,540 combinations, and the date range popover did not fit a phone.** The audit now runs **both sides of every breakpoint** — 320, 375, 639, 641, 767, 769, 1023, 1025, 1280, 1440 — plus a landscape phone at 740×360, and checks three things it did not: content clipped with no ellipsis, a nav drawer that cannot be opened below `lg`, and fixed chrome covering more than half a short viewport. `overlay-audit.js` opens every dialog and popover at **320×640 as well as 1360×900**, which is what found the real defect: the date range panel ran **143px off the bottom** on three pages. Its controller flipped above the trigger only when there was more room there, and at 320 neither side fit — it caps its height and scrolls now. The page header's back link was 20px tall and is 24px. Four false-positive sources fixed in the audit itself, each of which would have buried the real finding: `<option>`s inside select2's 1×1 `<select>` read as clipped text, the auth shell has no sidebar to open, the drawer was measured mid-transition, and rack-mini-profiler's badge read as app chrome. A fifth claim in this row's first version — that reCAPTCHA blocked the account request form at every width — was wrong and is corrected in `design-decisions.md`: the field is hidden until an account type is chosen, and the probe was asking `elementFromPoint` about a zero-sized element. |
| `67647c765` | **Required fields and validation errors audited across all 32 forms; every one had findings, and 28 are clean now.** `bin/design/form-validation-audit.js` added. Three systemic fixes cleared 19 forms: `aria-required` (simple_form derives `required` from `browser_validations`, which is off here, so nothing conveyed the state programmatically); `aria-describedby` linking each field to its own error message (the `<p>` had no id, so a screen reader user tabbing into an invalid field heard the label and nothing else); and the "Fields marked * are required." legend, absent from 27 forms — rendered once by `essentials_form_for` and shown by `form:has(label abbr[title=required])`. Four controller fixes: `items`, `kits` and `admin/users` each re-rendered a **fresh object built from the same params**, so the errors were lost and every field came back clean with only a flash sentence at the top; and **`/admin/questions` returned a 500 on every invalid submission** because both `create` and `update` called `@question.punctuate(...)`, a method that exists nowhere. The error summary now links each message to its field — its own comment had claimed that for months above a plain `<li>`. Five specs updated to assert the inline error and the summary rather than the flash they replaced. |
| `fc4e62d32` | **The last four forms finished; the form audit reports no findings.** `partners/users` and `partners/family_requests` both **redirected** on failure, throwing away what had been typed or selected along with the errors — both re-render now, and the family request page never rendered `@errors` at all. `partners/users`' view was the last form built from `form_for` with hand-rolled `label`/`text_field` pairs, which is why it had no required marker and no aria; it is `essentials_form_for` with `f.input`. `/audits/new` and `/account_requests/new` turned out **not** to be defects — the probe could not drive either, because a `data-confirm` dialog nobody accepts cancels the submit and the account request form hides its fields until an account type is chosen. Both taught the tool something: it accepts dialogs, it sets a marker on `window` so "never submitted" can be told from "submitted and came back empty", and it reports the forms it could not exercise **even when there are no findings**. The 2021 `partners/requests` error and success panels — `bg-red-200`, a 150px inline SVG, `text-4xl font-extrabold` — were the last unmigrated error UI and are now callouts; a blank organization email had been rendering "Contact Some Bank at ." |
| `236033619` | **Accessibility and keyboard audited; axe went from 61 pages to 152 and now reports zero.** `bin/design/keyboard-audit.js` added, and `wcag-audit.js` made route-driven — the four hand-kept lists were covering 61 of 152 screens. **The headline defect: below `lg` the closed off-canvas sidebar kept all 27 of its links in the tab order**, so a keyboard user on a phone tabbed from "Skip to main content" through the entire navigation, invisibly, before reaching the page — it is `inert` when closed now, recomputed on resize. Broadening axe found four more: `.table-scroll` could be scrolled by mouse only (all 62 are focusable now, with a name, a role and a focus ring); select2's combobox and value display had no accessible name; `/privacypolicy`'s footer was 4.06:1 against the 4.5 AA needs; and `/partners/authorized_family_members/new` **returned a 500** on any visit without a `family_id`. The select2 naming had been written once already and did not apply here, because that select is initialised by a second controller — it is a shared util now. |
| `3c8401103` | **Two dead-class bugs in JavaScript, and the audit extended to find them.** `password_visibility_controller` toggled `fa-eye`/`fa-eye-slash` — Font Awesome, removed in the migration — against markup that had been moved to Bootstrap Icons, so the icon never changed and the button's `aria-label` stayed "Show password" whatever the state. `file_input_controller` added Bootstrap's `font-weight-bold` and `list-unstyled`, so the selected-files heading was not bold and the list kept its bullets. And `application.js` called `classList.contains(".fc-prev-button")` with a leading dot, which is always false, so every unnamed calendar button was announced as "Next period" — including Today. `undefined-classes.py` scans JavaScript now. **The 23 remaining inert class names were removed** rather than left documented: a permanently non-zero audit is one people stop reading. Three of them turned out not to be inert and would have been deleted on the script's word — `filterrific-periodically-observed` and `form-inputs` belong to gems, and `filter-bar-submit` is defined in an inline `<style>` inside a `<noscript>`, which is what makes the filter bar work without JavaScript. The script reads gem `lib/` and inline `<style>` blocks now. |
| `f644de0ef` | **29 routes that could not work, removed.** `bin/design/dead-routes.rb` added: it asks of every route whether the request would raise. 28 did and one more resolved somewhere other than where it was declared; there are 0 of each now, over 346 verb-and-path combinations. Nearly all were actions `resources :x` generates and the controller never implemented — `requests` had six (`new`, `create`, `edit`, `update`, `print`, `partner_requests`), `users` four, `kits` three. Three were reachable by typing a plausible URL: `/partners/donations` raised `uninitialized constant Partners::DonationsController`, and `/requests/new` raised rather than saying requests come from partners. `resources :requests` was declared **twice**, and the second block's collection route sat below the first's `/requests/:id`, so `/requests/partner_requests` resolved to `requests#show` with an id of `"partner_requests"` — not a 404, a wrong page. It is one declaration now. The **manufacturers CSV import** lost its button and modal as well as its route: no `Importable`, no `Manufacturer.import_csv`, no `public/manufacturers.csv`, so every layer was missing and pressing it raised; it predates this branch, and the migration rebuilt it faithfully because it looked fine. Eleven route helpers disappear and none is referenced in `app/`, `spec/` or `lib/`. The audit itself was wrong twice before it was right — it called `POST /users` dead when Devise answers it, then silently dropped `/partners/donations` because `recognize_path` raises for constraint-guarded routes outside a request. |
| `4e4e74fcc` | **The unreachable `Importable` include removed from `ProductDrivesController`.** No `post :import_csv` on `resources :product_drives`, no `ProductDrive.import_csv`, no template CSV — unreachable code rather than a dead route, which is why the route cleanup wrote it down instead of removing it. CSV import now corresponds exactly in all four layers: five controllers include the concern, five routes reach `import_csv`, five models implement it, `public/` holds five templates, and it is the same five each time. The include looked load-bearing — `Importable` declares `helper_method :current_organization, :current_user`, and `product_drives/show` calls `current_user.has_cached_role?` — but both helpers come from elsewhere: `current_organization` from `ApplicationController`, `current_user` from `ActionController::Base::HelperMethods`, which Devise registers when the routes are drawn. A probe in `bin/rails runner` said otherwise because **the runner does not draw the routes unless something asks**, so it was reading the app before `devise_for` had run. See design-decisions.md. |
| `af58446c6` | **Dead-code audit: 118 findings, and two live defects that were hiding behind them.** `bin/design/dead-code.rb` added — the companion to `dead-routes.rb`, asking for code with nothing in front of it: 6 controllers no route reaches, 2 actions, 1 template, 4 partials, 24 helper methods and 81 `public/` files. Services, queries, jobs, mailers, events, concerns, Stimulus controllers, importmap pins and CSS classes are all at zero. **Five of the six dead controllers are the `app/controllers/users/` Devise overrides**: `devise_for` names only `sessions` and `omniauth_callbacks`, so Devise's own classes serve passwords, registrations, invitations, confirmations and unlocks, and one shell inherits from the wrong base class entirely. Their *views* are live — `scoped_views` sends Devise to look there — which is most of why it survived. **Two defects fixed.** `Devise::InvitationsController` was missing from the `to_prepare` layout block and `layouts/application` no longer exists, so `/users/invitation/new` and `/users/invitation/accept` served **200 OK with no layout at all** — no stylesheet, Times New Roman — to every invited user; `app/controllers/users/invitations_controller.rb` sets the right layout and never runs. And the product drive participants import offered `/product_drive_participants.csv` while the file on disk was still called `diaper_drive_participants.csv`; the file is renamed. **`route-targets.rb` skipped `devise/`**, which is why the sweep never visited the screens with the broken layout — it does now: 139 screens became 140 and axe went from 152 pages to 154. Thirteen classes of false positive were found and disproved before any of this was believed, the most expensive being that Figtree and Bootstrap Icons are named only by `@font-face`, so a glob without `.css` recommends deleting the fonts every page needs. The 118 are reported, not removed. |
| `333f12dbf` | **The account menu is the avatar alone.** Both top bars put the user's name beside the initials — `display_name` on the bank side, `email` on the partner side — and both already hid it below `sm` and truncated it above, so the trigger had two layouts and the narrow one was the honest one. It is the avatar and the chevron at every width now; the name, email and role were always in the panel and still are. The chevron stays, because it is the only thing marking a circle of letters as a control. **Removing the text removed the button's accessible name**: the avatar span is `aria-hidden`, so the trigger became icon-only and design.md's rule about icon-only controls started applying to it — it carries `aria-label="Account menu for …"`, which keeps for a screen reader the identity the initials keep for everyone else. Verified in both portals: 64×44 trigger, `"JB"` visible, panel unchanged. |
| `f25f683c8` | **The item catalogue is five page tabs, not five panels of one response.** Four of the five tabs on `/items` carried a 55px strip between the tab strip and the first row, holding one secondary button. **Two of them were not a design question**: "Items, quantity and location" and "Item inventory" both offered **New item**, the page header's own primary action, eleven lines up in the same template, rendered a second time — deleting those is 110px back and nothing else changes. The other two strips held actions that were real — "New item category" and "New kit" — and `design.md` already said where those go: the page header, which can only follow the tab if the tab is a URL. It is `/items`, `/item_categories`, `/items/quantity_and_location`, `/items/inventory` and `/kits` now, each with the primary action for what it shows, and 0px between the tabs and the table on all five. `item_categories#index` existed as `except: [:index]` because the table lived inside `items#index`; create and destroy redirected to `items_path`, which is to say to a different tab from the one you were on. **Kits keeps its own title** rather than borrowing the strip's, because it is also a sidebar destination and the rail has to be telling the truth about where it just sent you — the one place the partners precedent and the sidebar disagree. A consequence that was not the point: `items#index` built all five tabs' data on every request, so the item list paid for `ItemsByStorageCollectionAndQuantityQuery` every visit; it is a `before_action` on the two matrix views now. The tab-row variant was rejected on measurement — the five labels are 598px, the tightest container is 702px at a 1024px viewport, and "New item category" is 146px, so it wraps at 1024 and below. **Filters are exempt by design**: the 125px date band on `storage_locations/show` stays, because a filter changes the rows underneath it and an action does not. See design-decisions.md. |
| `5510c24d2` | **Eight specs the avatar change broke, and the fifth page kind `page-audit.rb` did not know about.** Three specs opened the account menu by clicking the user's name or email in the top bar, which the avatar change had removed; two more asserted the name was visible after saving it. They use `[data-account-menu]` now — the hook `admin/users_system` already used — and the account spec opens the menu before looking for the name, which is where the name now is. **They did not fail when the avatar change landed because only a subset of the system specs was run**; the full 2958 are green here. Separately, `page-audit.rb` classified views as show, index, form or partial, and those four are not exhaustive — a template named after a collection action matched none of them and was audited by nothing. An `action` catch-all found **25 views that had never been audited**, and one real gap behind them: Devise's mailer views live in `users/mailer/`, which the `_mailer/` exclusion misses, so six HTML emails were being read as pages with layout `&nbsp;` in them. The per-kind totals used looser exclusions than the scan itself, so every "N files" line was slightly too big — `index` counted `static/index.html.erb` and then skipped it. Both go through one `audited?` predicate now: 354 views, 0 defects. |
| `0bf55a97e` | **The storage location date band becomes a filter bar, and the chip it could not draw.** The "Inventory" tab held the app's last hand-rolled filter — a `form_for`, a `label_tag`, a `date_field_tag` with its own copy of the control classes, a bare submit and a `w-full` hint that forced a second line — **125px, always open**, while nineteen other pages used the component. It is `filter_bar` + a new `filter_date` helper now: **71px collapsed**, 183px open. It stays inside the tab panel, because above the card it would look like it scoped all three tabs instead of one. **It applies into a frame, and that is load-bearing**: a full reload re-renders the tab strip with whichever tab the server marked selected, so the filter only ever worked because Inventory happens to be first — on tab two it would have silently bounced the user back to tab one. `filter_date` submits a **bare param**, not `filters[…]`, for the same reason `filter_checkbox` does: `class_filter` sends every key in that hash to the model as a scope, so a non-scope in there raises — which also keeps existing `?version_date=` URLs working. And the chip: `filter_summary_controller` skipped **every** `input[type=date]`, correct while the only ones were the two inside the date range popover that report through a hidden field. The first standalone one inherited the exclusion, so arriving at a filtered URL gave the right rows and **no chip, no count and no "Clear all"**. It now discriminates on the `date-range` ancestor, the same test `clearField` already used; `/donations` still shows exactly one range chip. Two system specs cover the chip and the tab. |
| `0b55e0b35` | **The admin barcode filter, which had never filtered anything.** The other filter that was not the component, and the styling was hiding a defect: `Admin::BarcodeItemsController#index` was `@barcode_items = BarcodeItem.global` with **no `class_filter` call anywhere**, so the select and its Filter button reloaded the same full list with the choice in the query string. A request spec covers it and fails against the old action — which is how it was checked, because `BarcodeItem.global.count` is 0 in the dev database and nothing on screen could have shown it. `filter_params` was also carrying **four names that are not scopes** (`less_than_quantity`, `greater_than_quantity`, `equal_to_quantity`, `base_item_id`), so wiring up `class_filter` without narrowing it would have shipped a 500 alongside the fix; it permits the one name the page offers. The view is the component now, and matches its non-admin twin: filter bar into a frame, **"New barcode" as the page header's primary action** rather than a third button in the filter's button row, `Pagination::COMPACT` where there had been none, and a table with a caption, `scope="col"` and a scroll region. Its div nesting also did not balance — four closing tags with nothing open, and a second card hand-rolled from `CARD_CLASSES` inline, which `page-audit.rb` misses because the file renders one real card as well. See design-decisions.md. |
| `6c3b7dd1e` | **The hand-rolled card check reported 0, and there were 4.** `page-audit.rb`'s debt check was `src.include?(CARD_CLASSES) && !src.include?("shared/essentials/card")`, and each half was enough to hide every instance on its own. The **escape hatch** excused any file that rendered one card properly and pasted another inline — which is what `admin/barcode_items` and `admin/ndbn_members` both do; `shared/essentials/` is already skipped higher up, so it was protecting nothing else. The **substring** wanted `rounded-2xl border border-slate-200 bg-white shadow-sm` contiguous, and three of the four write `bg-white p-4 shadow-sm`, so one padding utility defeated it. A card is a surface, not a string: it is now those four tokens inside one `class` attribute, in any order, all four in the *same* attribute so a rounded wrapper round a white child is not a card. **And it proves itself before it runs**, like `undefined-classes.py` — a probe table including the padding-interleaved case and a split-across-two-elements case that must not match, aborting with the failing input rather than printing a clean-looking zero. Regressing it to the old substring now exits 1. The four found — `reports/index`, `admin/ndbn_members/index`, `admin/dashboard`, `partners/_show_header` — are reported, not converted: two are a plain swap and two use the surface for a `flex` tile that does not want the component's header. Debt does not change the exit code. |
| `3d96f5642` | **`admin/ndbn_members` rebuilt; one of the two "straight swaps" turned out not to be one.** The NDBN page was the same shape `admin/barcode_items` had been: a real card at the top, four closing tags with nothing open, and a second card hand-rolled around the table — with the upload form and the table both accidentally nested inside the first card's block. It is two cards now, the second `padded: false` around a table with a caption, `scope="col"` and a scroll region, plus an empty state for a bank that has uploaded nothing. Sentence-case headings moved the request spec's `th` assertion. **`reports/index` was not a swap** and is left alone: its six cards are `<section>`s carrying `aria-labelledby` at their own `<h2>`, an icon tile, a count and a `text-sm` heading, none of which `shared/essentials/card` can express — converting would remove six labelled regions and add ~25px to each card, against a layout decision the file documents. Debt is 4 → 3. The remaining three, plus `essentials_stats` in `app/helpers` which the audit cannot glob at all, want the card *surface* without the card *component*; the fix for those is one shared surface definition, not four conversions. See design-decisions.md. |
| `ee4e2a1e2` | **One definition of the card surface, and two detectors that were wrong the same way.** Six places drew `rounded-2xl border border-slate-200 bg-white shadow-sm` and only one was the card component — `essentials_stats` builds its own container, `admin/dashboard` and `partners/_show_header` build `flex` stat tiles, `reports/index` a compact labelled `<section>`, `shared/essentials/_disclosure` a panel. None wants the component's header, so converting them was never the fix; what they share is a surface. It is **`.card-surface`** now, a component class beside `.data-table`, used by all six including the component. It is the only `@apply` in the entry, deliberately: the class must be *exactly* those four utilities and `shadow-sm` alone composes five custom properties, so restating it by hand would be the copy this removes. **Verified as a no-op**: computed radius, border, background and shadow read from all 26 matching elements across five pages before and after — identical, counts unchanged. The audit's card check moved out of the per-kind loop into a sweep over views, helpers, JavaScript and components including `shared/essentials/`, because the last two copies were in exactly the places the per-kind scan cannot reach; there is no definition left to protect now that it is a CSS class. And `BARE_CARD` was `/class="[^"]*\bcard\b[^"]*"/`, whose comment claimed word boundaries excluded `card-body` and `content-card` — they do not, `-` is a non-word character, and adding `.card-surface` made every card in the app report as a dead Bootstrap class. It splits class tokens now, with its own probe table. Debt 3 → **0**. |
| `f81f35dc5` | **The announcement megaphone moves to the card header, where the design system already said it belonged.** Both announcement cards — bank and partner — stamped `essentials_icon_tile("bi-megaphone")` on **every row**, inside a card already titled "Announcements". `design.md` had the rule: *"one icon per card, not one per row… repeating it down every row gives the eye a second column of glyphs to skip and marks nothing out"* — but it sat under **Cards in a grid**, written while building the reports hub, so it read as a fact about grids. It is restated under **Icon tiles and avatars** now, with a mechanical test: **is the icon a literal, or does it come from the row?** Four places put a tile inside a loop; the three passing `stat[:icon]`, `metric[:icon]` and `option[:icon]` vary per row and are correct, and the two passing a string literal were not. Industry agrees from the other end — Material, Polaris, Primer and Atlassian all specify a list row's leading visual as *identifying that row*, and put section-level icons in the header; GitHub's issue list is the apparent exception and is the proof, because its glyph changes with state. The card gained `icon:`/`icon_tone:` rather than taking markup through `title:`, which would have put the tile inside the `<h2>` and its accessible name. **Measured, not assumed**: header height and `h2` position for every card on five pages before and after, and the only change anywhere is the announcements `h2` moving 48px right — the 36px tile plus its `gap-3`. |
| `51c1ca268` | **The icon tile gets one definition too, and a sweep of its own.** `essentials_icon_tile` rendered 36px/`rounded-xl`/`text-brand-600`; the reports hub rendered 28px/`rounded-lg`/`text-brand-700`, inline. **Three properties had drifted, not one** — which is what a single hand-rolled copy looks like after a while. Forcing the hub onto the default would have been wrong: its card is a compact cell in a 3×2 grid with a `text-sm` heading, and a 36px tile beside 14px text is heavy. So the helper takes `size:` — `md` default, `sm` at 28px/`rounded-lg` — named the way the button sizes already are. The hub's icon moves from `text-brand-700` to `text-brand-600` (7.07:1 → 5.62:1 on `bg-brand-50`; the floor for non-text is 3:1 and the icon is `aria-hidden` decoration), and **geometry is unchanged** — 28×28, 8px radius, same header, card and grid heights. `page-audit.rb` now sweeps for hand-rolled tiles beside the card-surface sweep, with **`rounded-full` as the whole discriminator**: a circle is an avatar or a numbered step badge, which design.md keeps deliberately disjoint from tiles, and both exist here. Of the eight tone-coloured rounded boxes in the app, two are avatars, five are step badges, and the hub was the only tile. Still 0 defects, 0 debt. |
| `f9f61d837` | **Three dropdown chevrons become one.** Measured across 151 screens, every `<select>` in the app drew its arrow somewhere different: **75** simple_form selects kept the browser's native arrow at **4.5px** from the border, **41** filter selects painted an SVG chevron at **18.5px**, and select2 drew a 2014 CSS triangle in `#888` at **7px** with 8px of text padding against everyone else's 12px. Three causes. **The chevron was positioned by its box, not its glyph** — the path was drawn `M6 8l4 4 4-4` inside a `0 0 20 20` viewBox, inset 6 units from each side, so `right 0.75rem` (chosen to mirror `pl-3`) actually left the painted glyph 18.5px out; the viewBox is tight around the path now and the constant means what it says. **simple_form's `wrapper_mappings` had no `select` entry**, so the majority of the app's dropdowns fell through to the text-input wrapper, where `px-3` cannot move a native arrow. **select2 was vendored rather than restyled** when it was kept. One `--chevron-down` variable now, one `.select-chevron` class, an `:essentials_select` wrapper and an unlayered select2 override. The names were part of how it happened: `filter-select` and `FILTER_SELECT_CLASSES` both said "filter" about a thing belonging to every select, and seven selects had been given `FILTER_CONTROL_CLASSES` — the *text input* constant — and kept the native arrow because of it. They are `.select-chevron` and `SELECT_CLASSES`. Nine call sites also wrote `"mt-1.5 #{FILTER_CONTROL_CLASSES}"` where the constant already begins `mt-1.5`. **Verified by pixels**, screenshotting each control at 4× and scanning for the stroke colour, because a glyph inset inside its own background box is invisible to a computed-style check. The app-wide sweep reports one signature for all 116 visible selects where it reported three. |
| `3bc02dcfb` | **The required marker is a red asterisk, and the legend explaining it is gone.** The marker was `<abbr title="required">*</abbr>`, which inherits the label's **slate-700** and picks up every browser's default `text-decoration: underline dotted` for `abbr[title]` — a grey asterisk with three dots under it, on every form in the app, where the convention is a red one. It is `rose-600` with the decoration off. **The class comes from the `required.html` locale key, not an attribute selector**, because the `title` is localised and `abbr[title="required"]` would have worked in English and silently not in Spanish. Evidence the browser default had been met before and patched locally: `requests/_request_row` puts `no-underline` on an unrelated `<abbr>`. **The "Fields marked * are required." legend is removed, reversing `fc4e62d32`** — it was added for WCAG 3.3.2 on the grounds that a sighted user got a bare glyph, and a red asterisk is not a bare glyph; grey-with-dots was. It cost ~32px at the top of every form's card, and the two profile step pages carried a second one, an Instructions callout that pushed the first card from 274px to 350px. **Nothing programmatic changed**: `abbr@title` and `aria-required` both remain. Two things moved with it — `form-validation-audit.js` asserted the legend existed and would have reported "asterisk with nothing saying what it means" on **26 forms** (verified by running the old audit against the new app); it checks `markerStyled` now, that the marker neither inherits the label colour nor keeps a text decoration. And `product_drive_participants/_form` wrote a literal `*` into four labels for conditionally-required fields, which was harmless while both asterisks were grey and is not once one is red; the asterisks went, the parentheticals that carried the meaning stayed. |
| `6d2cdb6e2` | **One convention for a validation error, and the glyph the colour rule already asked for.** Submitting `/donations/new` empty produced **two `role="alert"` regions**: a flash above the back link and the summary above the first card. Measured across every `new` and `edit` form, **18 did this** and 13 showed the summary alone — and they disagreed, `/adjustments` flashing `storage_location: must exist` under a summary saying "Storage location must exist", eight flashing "Something didn't work quite right -- try again?". design.md had already decided it twice: the summary is the GOV.UK pattern, and the entry on rebuilding a failed record calls "the only sign of trouble is a sentence at the top" the *symptom* of the old bug. Deleting the flash outright would have been wrong — a service can raise without touching the record, and the summary renders nothing for a record with no errors — so `flash_error_unless_summarised(record, message)` sets it only when there is nothing to summarise. **Operational failure gets the flash; validation failure gets the summary; never both.** 33 call sites, 21 controllers. `admin/partners/edit` had no summary at all and now renders one; the two profile step forms mark accordion sections instead and keep their flash. **The inline message gains `bi-exclamation-triangle`** — design.md says "never colour alone… usually an icon too", and an error and the hint it replaces are the same size in the same place, so hue was the only thing separating them; the summary heading gains the same glyph, its `gap-2` having sat there with one child since it was written. **The text stays `rose-700` rather than going grey**, a deliberate departure from the request: design.md maps failure to `danger`, text tones to `-700`, and names error text as `rose-700`, and grey is the hint colour in the same slot. **52 specs asserted the flash**; they assert the summary now via a `data-error-summary` hook and a `have_error` matcher that reads both, with three controller specs asserting the record's errors because controller specs render no view. The sweep that found the 18 was itself wrong — the danger flash carries `bg-rose-50` inside `<main>`, so a flash-only page counted as both; **18 → 0 is the number after fixing the check**. |
| `a5cef7c35` | **The error message goes slate, and three checks keyed to its colour go with it.** Reverses the half of `6d2cdb6e2` that kept the inline message `rose-700`. The argument for red was design.md's colour table; the argument against is that **there is a glyph now**, and it is the glyph doing the signalling — so the sentence is just words, and words read better as body text (`slate-700` is **10.35:1** on white against rose-700's **6.29:1**), without a six-problem form becoming six lines of red. The earlier objection, that a grey error looks like the grey hint in the same slot, is answered by the same glyph: the hint is `slate-500` with none. The summary followed — `slate-900` heading, `slate-700` items, on its unchanged `rose-50`/`rose-200` frame. **The glyph gets a `rose-50` chip on white and a plain mark on a tint**: the summary's version was built as a tile and could not be seen, both surfaces measuring `oklch(0.969 0.015 12.422)` — which is what design.md already says about the flash bar, *"a soft -50 tile on a -50 surface is invisible"*. **The summary bullets had a red underline under grey words**, `decoration-rose-300` left over from when the items were rose-800; they are ordinary `brand-700` links now, 7.19:1, which is what the GOV.UK pattern wanted them to look like anyway. And **three audit checks were testing for a colour rather than a thing**: `form-validation-audit.js` found an inline error by `p.text-rose-700` and a linked description by any `rose` class in the ancestry, so the moment the message went slate it reported first 2 and then **27** forms with defects that did not exist. Both key on `.field-error` now. Separately, `admin/partners/edit`'s three `f.input ... do f.input_field` blocks are plain `f.input`, restoring `aria-required`, `aria-invalid`, `aria-describedby` and an inline message to fields that had none. |
| `3af24bff9` | **The error summary becomes a plain bulleted list, offset under its heading.** The previous entry made the summary's items `brand-700` links with an underline, on the reasoning that they *are* links and should look like the app's links. In a rose box they read as blue underlined links — a third colour in a component that already had two. **design.md had already ruled it out**, under Interaction: *"a link that is its own block — a table cell, a list item, a card row — does not need one, because there is no body text for it to be confused with."* These are list items; the rule for a link inside a sentence had been applied to them instead. They are plain `slate-700` text now, with no anchor at all, which is what Polaris, Carbon and Atlassian all show for a summary. **The jump is not missed**: `6d2cdb6e2` put every message at its own field, tied to the input by `aria-describedby`, so the summary says *what* is wrong and the field says *where* — the GOV.UK anchor is worth restoring only if a form gets long enough that scrolling is real work. The glyph also moved into **its own flex column**, so the bullets line up under the heading's text rather than under the glyph; the alignment is structural rather than left padding measured against an icon, which is a number that goes stale the moment the type scale moves. Measured on `/purchases/new`: heading text at x=41, bullet marker at 46–49, item text at 61, and **zero blue pixels** anywhere in the component. All 21 specs that assert a summary key on `data-error-summary` and its text, not on its anchors, so none moved. |
| `40067ae2e` | **The line item row measured and mocked up before anything is changed.** `docs/mockups/line-item-row-options.html`. The "Items in this donation" card puts five controls on what is supposed to be one line and lands them on **three different bottom edges** — 910, 924 and 926px. Measured against the app's 38px/8px/14px control: the barcode input matches, the scanner button is **42px** and 34px wide rather than square, the remove link is 28px, and the item dropdown is **28px tall, 4px radius, 16px text, 575px wide** — wrong on every axis. Three causes, and the largest is not this page's: **select2's box was never restyled**. The chevron pass `f9f61d837` fixed its arrow and text padding and stopped there, so the widget still carries its vendored 2014 metrics on **six selects across five views**. The row also passes `wrapper: :essentials` explicitly, which is the *text input* wrapper, so its select never reaches the `:essentials_select` mapping; and the barcode input and scanner button are hand-rolled class strings that nothing keeps in step. A fourth defect found while measuring: the remove control asks for `text-rose-700` through a `ghost` button's `extra:`, and **renders slate-600**, because two colour utilities in one class attribute are resolved by the cascade and not by attribute order. The mockup offers three row shapes and recommends the scan-first one every inventory app converges on — one scan bar per document rather than one per line, labels in a header row, an icon-only remove — which measures **59px a row against today's 96px**. Nothing is built yet; the decision is the user's. Two of the README's own traps were hit while writing it and are the reason it is honest: the first draft's icon buttons collapsed to 24px and its joined input group had four rounded corners, because Tailwind does not scan `docs/mockups/` and six of the utilities the proposals depend on were simply absent from the snapshot. |
| `3aabb25df` | **select2 gets the app's box, which the chevron pass left behind.** `f9f61d837` replaced select2's 2014 arrow and moved its text to 12px, and stopped there — so the widget kept a **28px-tall, 4px-radius, 16px-text control in a `#aaa` border** while every other control in the app is 38px, 8px and 14px in `slate-300`. On the donation form that put a 28px item picker on the same line as a 38px quantity field, which is most of why that row looks wrong. **Six selects across five views**, and it is not only the single: **four of the six are multi-selects** — product drives' tags, a partner's requestable items and both of `/manage/edit`'s — carrying the same radius, border and font. The single takes `height`, the multiple takes `min-height`, because a multi-select is supposed to grow as chips are added to it. Also restyled: the value's colour (`#444` → `slate-900`), the placeholder (`#999` → `slate-400`), the arrow box (`top: 1px; height: 26px` centred a glyph in a 28px control and left it 5px high in a 38px one, so it is `calc(100% - 2px)` now) and **focus, which select2 does not style at all** — tabbing through a form used to lose the ring on exactly one field. All unlayered, like the arrow rules beside them. design.md gains the number itself: **38px is the app's control height**, it is not a Tailwind step, and the three places that write `2.375rem` by hand are named there so the next one is not a fourth guess. |
| `15e49758f` | **The line item row becomes a table, and the scan field leaves the row.** Option C of `docs/mockups/line-item-row-options.html`, chosen by the user. All **seven** forms that take line items — donation, purchase, distribution, transfer, adjustment, audit, kit — assembled the card body by hand and had drifted; they render one `line_items/_line_item_table` now. **The scan field is one per card, not one per row.** A barcode field belongs to the document being built, not to a line of it, which is why Square, Zoho, Odoo and Amazon Seller all put one at the top of a receiving screen — this form drew "Scan a barcode", an "or" and a full item picker *per row*, so a ten-line donation had ten of them. **Column headings appear once** instead of three labels per row, through new `:essentials_cell` wrappers that render no label and no bottom margin but keep the inline error; the controls carry the column word as `aria-label` and the heading row is `aria-hidden`, so it is not announced twice. The remove control is **the glyph alone**, `slate-500` until hover, and the footer carries a **running total** — "2 items · 36 units" — which every inventory app has and this card had none of. The row is **58px against 96px**, and its three controls share one bottom edge where there were three. **Below `sm` it stacks**, because four columns at 320px left the item picker **72px** and 320 is the width WCAG 1.4.10 Reflow is defined at; stacked it is 196px, and each cell grows its own `sm:hidden` label since the heading row goes with the columns. The scan bar's button is *joined* to its field rather than sitting beside it, which is what stops them drifting to 38px and 42px again. **The three-scan package prompt is preserved** and now means what it says: it used to detect a repeat by comparing the value left in every row's own barcode input, and the count is `data-scan-count` on the row. Also fixed: `remove_element_button` asked for `text-rose-700` through a `ghost` button's `extra:` and rendered **slate-600** on all five call sites, because two colour utilities in one class attribute are resolved by the cascade and not by attribute order — there is a `ghost_danger` variant now, and one caller that had worked around it with a whole replacement class string no longer needs to. **Two defects created and fixed here, both promoted to design.md** because neither is specific to this screen: a `MutationObserver` whose callback wrote `textContent` *inside* the subtree it observed, an unbroken loop that hung the tab on the first scan; and the assumption that jQuery's `.val()`/`.trigger()` reach a native `addEventListener`, which they do not, leaving the running total one scan behind the quantity it was adding. **Nine spec blocks scoped `within "#..._line_items"` around a field that is no longer inside it**, and five assertions encoded the old behaviour — including the Issue #526 test for *unique ids across per-row barcode fields*, which is now the stronger invariant that adding rows never produces a second scan field. **A correction to the row above this table**: it read *333 of 366* views carrying design system markup, and the figure measured at that commit is **331**. It was wrong by two when it was written. 332 of 367 is measured here — one view added, one more carrying. |
| `dcaa81400` | **The camera drew itself into the button, and the scan field was three times the width of a barcode.** Two reports, four defects. **The scan field is 15rem now, measured** — a 14-digit GTIN, the longest barcode in common use, renders at **138px** in Figtree at 14px, and the field was `max-w-md`: **410px of field for 138px of content**, picked by eye in the mockup and never measured. Not one column wide, which was the other option offered: the Item column is `1fr` — 904px at 1440 and 377px at 641 — so matching it would make the width of a barcode box depend on the size of the window, and a barcode is 12–14 digits on every screen. The alignment that means something is already there, both sharing the card's `px-5`. GOV.UK and USWDS both ship fixed-width input classes for exactly this; the rule is in design.md now, with the carve-out that free text takes its column. **And the icon that jumped left**: Quagga fills whatever element it is handed as `target` with a `<video>` and a `<canvas>`, and it was handed the *button* — measured, the glyph moved from x=730 to **x=391**, 339px outside the 38px control that owns it. On a successful read the code then called `.empty()` on that button, deleting the glyph outright; both looked like they "reset on refresh" because neither was ever persisted. Underneath was the reason no id-based fix would have held: **`id="barcode-scanner-btn"` is in three partials and a donation form renders two of them**, so the dialog's camera button drew its picture inside the scan bar's button — and axe does not report that, `duplicate-id` having been deprecated in axe-core 4.9. Each scanner is a `[data-barcode-scan]` region with its own `[data-barcode-viewport]` now, the button toggles with `aria-expanded`, and nothing is wired by id. A fourth defect found while reading rather than from the report: `last_target.prev()` took `$(e.target)`, which is the `<i>` inside the button as often as the button, and an icon's previous sibling is nothing — so a camera read frequently had nowhere to write its result. Verified with a fake camera device: the glyph holds at x=522 through start and stop, the button keeps exactly one child, the dialog's viewport no longer leaks into the scan bar's, and there are zero duplicate ids. The remove button's mobile alignment came out of this too: the first version cleared the label's height with an `&nbsp;` spacer, which `page-audit.rb` flags as a defect and was right to — it is `self-end sm:self-start` now, which puts the button's bottom on the control's bottom without a number in it. |
| `ea3870fa2` | **The scan field takes a grid column, and the width rule gets its missing half.** Option A of `docs/mockups/scan-field-width-options.html`. **This reverses the entry above it, one day old.** That one sized the field to its content — `15rem`, from the 14-digit GTIN that is the longest barcode in common use, measuring 138px — cited GOV.UK and USWDS, and wrote the rule into design.md *without the condition that makes it true*. The condition is **neighbours**: GOV.UK's narrow inputs sit in a column of stacked fields where the one above and the one below share the left edge, and that repetition is what makes a short width read as deliberate. This field is alone in a tinted band, so the same width reads as unfinished. Both rules are real; I applied the one whose precondition did not hold. **The measurement settles it**: a fixed width cannot align to a fluid grid at more than one viewport — `15rem` was 106px short of the column at 1440, 53px short at 1280, and at **1024 it was 33px *wider* than the column**, overhanging a boundary every other control respects. That is not a ragged right edge, which is defensible; it is a control crossing its cell. The scan bar is on the same `gap-x-5 sm:grid-cols-2 lg:grid-cols-3` grid as the cards above it now and takes column one: **346/293/207/329/265/301/246px at the seven audited widths, both edges aligned with the storage location select at every one**. The content measurement became the check in the other direction — the column must never be too *small* — and at 1024, where the grid is narrowest, the field is 169px against 138px of barcode. Half the card was rejected with a number too: at `lg` the cards use thirds so a half falls between columns two and three, and at `md`, where it ought to coincide with a two-column grid, it overshoots by exactly **10px**, half the `gap-x-5` gutter. |
| `d23bb54c6` | **The dev server did not need stopping for the test suite, and the note saying otherwise was treating a symptom.** `docs/onboarding.md` told contributors to stop the server before `rspec`, on the evidence that running both drove available memory under 600MB and turned 2,962 passing examples into six failures and then a hundred. The evidence was real; the diagnosis was not. Two things were eating the memory, neither inherent: `config/puma.rb` boots a **two-worker cluster** — 1.4GB for a server one person is looking at, where `WEB_CONCURRENCY=0` is **301MB** — and, much worse, **`pkill -f foreman` does not reap foreman's children**, so every restart orphaned a Delayed Job worker. Six restarts in one session had left **seven `rails jobs:work` processes holding 2,260MB**, which is where the pressure was actually coming from. Started lean the whole stack is **930MB**, and the full suite is **2,962 examples, 0 failures with the server running throughout** and still answering 200 afterwards. The onboarding entry now says how to stop the stack properly rather than how to work around it, and names the leak so the next person checks `ps -eo rss,cmd \| grep jobs:work` before believing a flaky spec. |
| `8212a78ef` | **A copy audit, and the words it found.** `design.md` had **no copy guidance at all**, which is why none of this had a rule to drift from; it gains a **Copy** section, and `bin/design/copy-audit.rb` checks the mechanical half — link text (WCAG 2.4.4), sensory instructions (WCAG 1.3.3), gendered wording, ableist wording, "please", and all-capital shouting. **Gendered: 0. Ableist: 0** — the app was already clean on both, and the checks exist so it stays that way. Fixed: **5 vague link labels** ("click here", "this link", "here"), **2 sensory instructions**, **1 piece of shouting**, and **48 instances of "please"** across views, seven mailers and the Devise locale. Three of the confirmations "the list above" went with them, since a position fails 1.3.3 and goes stale at every breakpoint. **Two "More info" links keep their visible words and gain an `aria-label` that extends them** — replacing the text outright would satisfy 2.4.4 and break **WCAG 2.5.3 Label in Name**, and voice control with it. **The audit was wrong three times before it was right, and its own probe table caught each**: it read source rather than copy, so `he/she` matched `render "organizations/header"`; it did not know a link from a heading, so it reported **all sixteen cards titled "Details"** as WCAG failures (22 → 5); and its `/x` regexes had their literal spaces stripped by Ruby, so `VAGUE_LINK` was looking for `clickhere`. A fourth, blunter: the acronym allowlist was too short and FPL, JPEG, PDX and GMT reported as shouting (21 → 1). **Found on the way**: `account_requests/new` was still rendering simple_form's `f.error_notification` instead of `essentials_error_summary` — the single-convention sweep in `6d2cdb6e2` looked for a *flash* beside a summary and never saw it, and it surfaced now only because that notification's message, "Please review the problems below:", is copy with both a "please" and a position in it. **13 specs asserted the old wording** and were updated to the new. |
| `9c364508a` | **Four column headings that had gone back to uppercase, and a preview for the row dividers.** The line item grid's headings were `text-xs font-semibold uppercase tracking-wide`, and the app's standard is `.data-table thead th`, which sets **`text-transform: none`** — the only `text-transform` in the whole stylesheet, and set deliberately. The design system had already rejected uppercase **twice**, and both refusals are recorded in comments: the nav group's header ("It was uppercase... uppercase removes word shape, which is the thing you scan a rail by") and `essentials_stats` ("deliberately not the uppercase-with-tracking eyebrow this slot usually attracts"). The audit found **4 live instances** — the line item headings, two profile subheadings and the sign-in "or" divider — and `uppercase` now appears nowhere in `app/views` or `app/helpers` except in those two comments. The line item headings measure identical to `.data-table thead th`: none / 12px / 600 / `oklch(0.554 0.046 257.417)` / normal. design.md's Sentence case rule gains the missing half: **a `text-transform` breaks it exactly as much as typing the capitals would**, and a column heading is `text-xs font-semibold text-slate-500` and nothing else. Separately, `docs/mockups/line-item-divider-options.html` puts up four treatments for the row dividers, measured: with them the card draws **7 card-wide rules** for four rows, without them **4**. Nothing built there yet. **Two faults in that preview were caught before it was shown**, both of them the mockup README's own traps: the zebra panel rendered identically to the no-divider one, because Tailwind does not scan `docs/mockups/` and the striping class did not exist; and the self-measurement counted every control border as a rule, because in a narrower page a select is 95% of the panel width — which had also produced the "15 rules" figure quoted for the real page before it was re-measured at 7. |
| `0c6a31e21` | **The line item rows lose their dividers, and the spacing becomes one number.** Option B of `docs/mockups/line-item-divider-options.html`. A divider separates rows of *text*; between rows of *controls* it is redundant, because every cell already draws its own box, and it put a second horizontal line between each pair. Measured on `/donations/new` with four rows: **7 card-wide rules became 4**. Xero, Stripe and Shopify all draw none between editable line items. The rules that stay separate **bands** — under the scan bar, under the headings, above the footer — because those mark a change of kind; index tables keep their row dividers, since there the rows *are* text. **The spacing was wrong in a way the dividers had been hiding**: at `py-1` on the container the band edges were **12px** against **20px** between rows, so the first row read as attached to the heading strip rather than as the first of a set. It is `py-2.5` on both the container and the row now — **20px between every pair of controls and 20px from either band border**, one number, against 8px between the stacked controls *within* a row below `sm`. Between beats within, which is the grouping the divider had been papering over. **The remove button was checked rather than assumed**: 38×38 at all ten widths from 320 to 2560, against WCAG 2.5.8's 24×24 AA floor, and in its own grid column at every one of them — it cannot wrap, because it is placed explicitly rather than by auto-flow. Its glyph samples **#62748e on white = 4.76:1**, well past the 3:1 that WCAG 1.4.11 asks of a non-text control and past 4.5:1 as well. **Two contrast measurements were wrong before that one was right**: parsing the numbers out of an `oklch()` string as though they were RGB, and painting a swatch the canvas would not convert — both produced a confident 8.48:1 and then 3.54:1 for a colour that is neither. Sampling the painted glyph at 4× gives the token exactly. |
| `a1ae22196` | **The icon buttons announced themselves as buttons and ignored Space.** `add_element_button` and `remove_element_button` both rendered `<a href="javascript:void(0)" role="button">`. The name was impeccable — `aria-label`, icon `aria-hidden`, accessibility tree reading `{role: button, name: "Remove this item"}` — and the *behaviour* was not: a native anchor fires on Enter and ignores Space, and the ARIA button pattern requires both. Measured on `/donations/new`, **Enter removed a line item and Space did nothing**, which is **WCAG 4.1.2**. **axe reported no violations throughout**, correctly: it reads markup, and the markup was fine. The fix is to stop pretending — both helpers render `<button type="button">` now, which gets Enter and Space for free and takes fourteen inert "Add another item" entries out of a screen reader's list of links. `type: "button"` is load-bearing, since these sit inside forms where a button defaults to submit. **Icon-only itself is kept and now has a condition in design.md**: it is for a *repeating row action*, where the row supplies the context and eight "Remove" labels would be eight repetitions of nothing — QuickBooks, Xero, Shopify and Stripe all do this — and not for a one-off, which gets its words. **No tooltip**, deliberately: `title` is invisible to keyboard focus, absent on touch and doubles the announcement over the `aria-label`, and a real one owes WCAG 1.4.13 dismissible/hoverable/persistent behaviour that this app has no component for. 7 specs asserted the anchor and were updated. |
| `46b8b1fda` | **One remove button for all five call sites, a destructive ghost that is not red, and the empty state the card never had.** Option C of `remove-control-and-empty-state.html` for the control and option B for the empty state. **The control reverses my own recommendation from two rounds earlier**, which argued icon-only on density: a good argument about line item editors and the wrong one about this app, because `remove_element_button` has five call sites and four already rendered the words — including `partners/requests/_item_request`, the same shape as the bank row, two screens away rendering "Remove" at 83×28. One rendering now; the `icon_only:` branch and the `ICON_BUTTON_CLASSES` constant that existed only to serve it are gone. **The preview drew the button rose at rest and that was wrong**: `design.md` already carried the opposite rule for this control — *"`slate-500` until hover… so an eight-row form does not carry eight red marks down its edge"* — and I had written that sentence for the icon, then contradicted it in the `ghost_danger` variant and again in the preview. It is **`slate-600` at rest**, rose on hover and focus: measured rest `oklch(0.446 0.043 257.281)`, hover `oklch(0.514 0.222 16.935)` on `rose-50`. A consequence worth having — `partners/profiles/step/_attached_documents_form` was passing a whole replacement class string to force rose, a workaround for the old cascade collision, and it stops being the only Remove in the app still red at rest. **The empty state** is `:cold_start`, switched on by `line_item_total_controller` because rows come and go without a round trip; the column headings go with it, there being no columns left to head. It offers **no action** deliberately, the footer's Add another item being 60px below. **And the sweep**: all **64** empty states in the app already pick a `kind:` deliberately — 29 `cold_start`, 13 `all_clear`, 9 `no_results`, 13 choosing at render time — **0 defects**. The first pass reported 13 without a kind, which was the audit reading a proxy again: those pass `kind: essentials_filtered? ? :no_results : :cold_start`, the documented pattern. Separately it found **16 collection-driven tables with no empty state at all**, triaged in `docs/todo.md` — nine reachable-empty, seven that cannot be. |
| `058637e01` | **Nine empty states built, and 27 destructive buttons that had never once rendered the colour they asked for.** The nine reachable-empty tables from the previous sweep now have states, each with a `kind:` chosen for its context: `admin/organizations`, `admin/partners`, `admin/users` (**`:no_results`**, because that list is behind a filterrific search), `admin/users/_roles`, both broadcast announcement indexes, `partner_users`, `users/index`, and `reports/annual_reports/show` (**`:all_clear`** — a section with no figures is not a failure). Proved in both directions rather than assumed: `/admin/users` with a search matching nothing renders 0 rows and the state, and `/admin/broadcast_announcements` with one row correctly renders no state. **The bigger find was next door.** Twenty-seven views passed `variant: :ghost` with `class: "text-rose-700 hover:bg-rose-50"` — the same cascade collision fixed in the previous commit for `remove_element_button`, in every destructive row action in the app. Measured on `/transfers`: a Delete carrying both `text-rose-700` and `text-slate-600` and rendering **slate-600**. The override has been inert everywhere, at rest *and* on hover, since `ghost` brings its own `hover:bg-slate-100`. They are `variant: :ghost_danger` now, which is the same slate at rest they already had and the rose-on-hover they never got: verified rest `oklch(0.446 0.043 257.281)`, hover `oklch(0.514 0.222 16.935)` on `rose-50`. The visual change is confined to hover, because the intent had never been reaching the page. design.md gains the rule for when a `cold_start` should *not* offer an action, and `docs/todo.md` keeps the seven tables whose empty branch is unreachable — each shows a saved record's line items, and every one of those models validates it has at least one. |
| `8eb0fb5ce` | **Free text in a table gets a `.notes` column, and `/purchases` goes 2,711px to 1,111px.** Rows there measured **145–245px** against a normal 45px, because a comment cell sets the row height to whatever somebody typed and a table's value is that rows are comparable at a glance. `.notes` joins `.numeric`, `.quantity` and `.date` as the fourth kind of column the app has: one line, ellipsis, capped. Applied to **16 columns across 15 views**. Carbon, Material, Salesforce, Atlassian, Stripe, Linear and GitHub all clip to one line; Polaris and Notion allow two, which was the near miss — two lines gives the column two row heights, the original problem in miniature. **Three tables were deliberately left alone.** Two already used a `<details>` disclosure whose comment says it replaced a Bootstrap tooltip; I had not shown that option in the preview and should have, since it was in the app already. Checking why gave the rule: those rows **lead nowhere**, so a clipped comment would be unreadable rather than one click away — *is the full text one click away? clip. Is it not? disclose.* The third, `item_categories`, renders a `<ul>` of anchors, where clipping would leave focusable links invisible. **16rem is load-bearing and the first value was 22rem**: `nowrap` makes a column demand its max-width rather than shrink by wrapping, so that number sets how wide every table carrying one becomes, and at 22rem the purchases table grew to 1,298px, crossed its scroll region and **started the whole document swiping sideways at 1440** — a regression I caused and then measured my way back out of. Chasing it exposed a **pre-existing** bug: `html { overflow-x: clip }` is set for exactly this and does not work — at 375px the `h1` could already be swiped from `left: 16` to `left: -670` before any of this — and **`responsive-audit.js` cannot see it**, because it compares `scrollWidth` with `clientWidth`, which is the very number that `clip` rule exists to neutralise. Recorded in `docs/todo.md` with the measurements, along with the link-column question and the fact that `/distributions` rows are tall because of their **actions**, not their text. |
| `98d275537` | **A clipped cell gives its text back on hover and focus, which is the half of the pattern the previous commit was missing.** `clipped_text_controller` reveals what `.notes` clips. **This reverses three earlier refusals without contradicting them**: the scan button, the remove button and the clipped cell were one case — a control that needed a *name*, where a word solved it for free — and truncated text is the opposite, words already written and hidden on purpose. Carbon ships a documented tooltip for truncated table text, Ant Design pairs `ellipsis` with a Tooltip, AG Grid has `tooltipField`; clipping alone was the incomplete half. **Only where the text is actually clipped**, from `scrollWidth > clientWidth`: `/adjustments` has **42** notes cells, **0** clipped, so it gains neither a tooltip nor a tab stop, while `/purchases` has 14 and all 14 do. **The bubble is `aria-hidden` and the cell gets no `aria-describedby`** — a correction to the mockup, which used one: the whole string is already in the DOM and has already been read, so describing the cell with a copy of its own text would announce it twice, which is the main fault of `title`. **WCAG 1.4.13** is why this is a controller rather than an attribute — dismissible with Escape, hoverable so you can move onto the bubble, persistent — and the mockup got "hoverable" half right, leaving the bubble on screen forever once the pointer left, because only the cell had a `mouseleave`. Rescans on resize and on `turbo:frame-load`, both proved rather than assumed: injecting a long cell and dispatching the event flips it to clipped and focusable. Five system specs cover hover, focus, Escape, the double-announcement, and a short comment getting nothing. |
| `cd25ebfb1` | **A row's actions stop wrapping.** Five row partials used `flex flex-wrap justify-end`, and on a wide table the actions column gets squeezed until the buttons stack one per line: `/distributions` had **155–171px** rows with its two visible actions on two lines in a **114px** cell, and `/items` **121px** with three on three. Healthy tables give theirs 250–284px and keep them on one line, so these two were the outliers rather than the norm. They are `whitespace-nowrap` now, which makes the column take the width it needs and the table scroll inside `.table-scroll` — what that region exists for. Measured after: distributions **85–105px**, items **65–85px**, every action on one line, and `kits`, `partners` and the organization user list moved with them. Modal footers keep `flex-wrap`, because those *should* wrap. **The residual is not the actions column and is recorded rather than guessed at**: with the buttons on one line, what is left crushing the distributions row is ordinary text — "Pawnee Pregnancy Center" wrapping to **three lines in a 105px Partner column**, twelve columns in a 1,118px region. That is a decision about which columns the table carries, so it is in `docs/todo.md` with the alternative (every cell in a scrolling table `nowrap`, which is what Carbon and Material do) rather than folded in here. Also corrected: design.md still told people to tint a destructive row action with `text-rose-700 hover:bg-rose-50`, which is exactly the inert override 27 views were fixed out of two commits ago; it says `:ghost_danger` now. |
| `c83bb783b` | **A table row is one line, with three classes that make that survivable.** `.data-table td` is `nowrap`. A wide table can have short rows or fit the screen, not both, and Carbon, Material, Stripe and Linear all pick the short row — a table is read *down* a column and a ragged row height breaks that, while WCAG 1.4.10 Reflow exempts data tables from the no-sideways-scroll rule for the same reason. Measured: `/distributions` **1,339px tall with three row heights → 943px with one**, `/purchases` 1,111 → 783; four tables were already single-line. **Nowrap alone was not enough, and the gap was found in review rather than by me**: it hands the layout to whoever typed the longest value, and one 72-character partner name took that column from 263px to **493px**, dropping the columns visible without scrolling from **8 to 6** with Total value the first to go. Three classes close it. **`.name`** caps a name column at 18rem — measured, not chosen: the longest values in the database are a 32-character partner and a 36-character item, about 263px, so the cap is inert on everything that exists today. A *width*, not a character count, because "Illinois" and "Warehouse" are both nine characters and 12px apart. **`.pin-col`** pins the identifying column, which answers the half a cap cannot: without it the partner cell sits at **−542px** once the table is scrolled right. It takes `background-color: inherit`, so a hovered row does not show a white stripe through it — verified, row and pinned cell both `oklch(0.984 0.003 247.858)`. **`.wrap`** is the escape hatch, and it is not hypothetical: `/item_categories` renders a `<ul>` of item links in a cell and keeps all twelve with it. **A claim of mine was wrong and is corrected here**: recommending the cap I said the reveal was "already built for any clipped cell", and `clipped_text_controller` queried `td.notes` — a capped name would have clipped with no way to read it. It keys on any cell where `scrollWidth > clientWidth` now, which *is* the property, since a wrapping cell grows downwards and an uncapped `nowrap` cell grows sideways; a class list would have failed again at the third kind of column. Reads are batched before writes, because `/adjustments` is 42 rows. |
| `cb9bfde76` | **The question mark under the pointer, and the focus ring that never followed.** Two defects from the previous commit, one visible and one not. `cursor: help` was on clipped cells, which is what drew a **question mark over a partner's name** — `help` means "there is an explanation of this", and a name whose end is cut off is not a thing needing explanation but a thing needing reading. Removed: **the ellipsis is the affordance**, which is why Carbon, Ant Design and AG Grid all leave the cursor alone on truncated text. The second was hiding behind it: the focus ring was keyed on `td.notes[data-clipped]` while the controller had been generalised to mark **any** overflowing cell, so a capped `.name` cell was focusable with the **browser's default `1px rgb(16, 16, 16)` outline** instead of the brand ring's `2px rgb(79, 70, 229)`. The same mistake as scoping the controller by class, one file over, and found only because the cursor question sent me back to that rule. Both keyed on `td[data-clipped]` now, and both pinned by a spec. |
| `dbb2082fb` | **Row actions collapse into a menu, and `role="menu"` stops being a lie.** Option C of `row-action-menus.html`. The actions column on `/distributions` was **331px** — the second-widest in the table, wider than Total items, Total value and Status together — and is **60px**. `/vendors` keeps a visible View and its table **fits its region for the first time**. Row heights are one value everywhere. A named pattern rather than a convention: Carbon ships an `OverflowMenu` for table rows, Salesforce calls it row-level actions, Polaris uses an `ActionList` in a `Popover`. **No visible View on `/distributions`, `/items` or `/purchases`**, because their first cell already links to the record and a View beside it is two controls with one destination. **Building it found two pre-existing defects.** The account menu has declared **`role="menu"` since the day it was written while `popover_controller` had no arrow-key handling at all** — a promise in an attribute that nothing kept, and nothing noticed until the row menus multiplied it into **62 overlay-audit findings**. Rather than copy the false promise or dodge it with a vaguer role, the controller now implements `ArrowDown`, `ArrowUp`, `Home` and `End`, **gated on the role** — the date range panel is `role="dialog"` and holds date inputs, where an arrow key belongs to the input. And `.table-scroll`'s `overflow-x: auto` forces `overflow-y` to `auto`, so an absolutely positioned panel was clipped on **both** axes and the last row's menu was cut off by the bottom of the table; `data-popover-fixed-value` places it against the viewport, hit-tested at the first and last row of three tables. Also: a `<form>` cannot sit between `role="menu"` and its items, so `button_to`'s wrapper takes `role="none"`; and an unavailable action stays in the menu as a genuinely `disabled` `<button>`, which is what design.md already required and what a request spec was right to assert. **The keyboard check lives in `overlay-audit.js`, not RSpec**: Cuprite would not deliver a key to the focused node, and the first version of that spec **passed for the wrong reason** because focus had gone to a filter input. 19 specs asserted the old buttons and use a `click_row_action` helper now. |
| `015da3b36` | **A scrolling table admits it scrolls.** `/distributions` hid **486px of columns** behind an overlay scrollbar taking **0px** of height, with no fade, shadow or hint — the only signifier was `aria-label="Table, scrollable"`. `table_scroll_controller` puts `start`, `end`, both or neither in `data-overflow` and the CSS draws a fade at whichever edge has content behind it, which is what Carbon, Material, Ant Design, GitHub and Notion all use. **Directional on purpose**: a table that fits gets none — verified, `/adjustments` and `/vendors` report `""`. **Why no audit caught it, which is the useful part**: the region was built for the keyboard and the screen reader and serves both, and that is exactly what `keyboard-audit` and axe check — while an overlay scrollbar is *invisible to a computed-style test*, since `offsetHeight - clientHeight` is 0 whether the platform draws an overlay or nothing. Every audit reported clean and the group left out was people looking at the page with a mouse. **The fade is the signal and the scrollbar is a bonus**: `::-webkit-scrollbar` makes Chrome and Safari reserve space, Firefox ignores it, and it could not be verified in headless Chromium even with `--disable-features=OverlayScrollbar` — so the preview labelled that panel unverifiable rather than implying it worked. Built on the **parent** via `:has()`, because a pseudo-element on the scroller scrolls away with the content, and that let all **66** regions gain it without a wrapper; and driven by **one controller on the shell** rather than 66 attributes, since `scroll` captures even though it does not bubble. `pointer-events: none` throughout, hit-tested against the actions trigger and the pinned link. |
| `bd47ec251` | **Never fade a frozen column.** The fade added the day before was drawn at the container's `left: 0`, which is where `.pin-col` sits. Sampling the painted pixels of the ID cell on `/distributions` at 4×, it lifted the darkest ink from **69 to 144** — **9.59:1 down to 3.19:1** against white, failing WCAG 1.4.3 on the one column pinning exists to keep readable, with **19 of the 26 inked columns** under it. It was wrong before any measurement too: a frozen column does not move, so fading it as a scroll signal says something untrue. **Six of the seven tables that overflow have one**; only `/items` does not. Now the frozen column casts a shadow to its right instead, and only once content has passed underneath — Carbon, Ant Design, AG Grid and Airtable all mark the boundary that way — while a table with nothing frozen keeps its edge fade. **axe reported 0 violations across 156 pages while this was live**, because it computes contrast from declared colours and cannot see a gradient painted on top by a pseudo-element; the same proxy-checking failure as the overlay scrollbar the day before. The controller supplies `data-pinned` because CSS cannot ask the question — **`:has()` may not be nested**. Verified on all nine tables: contrast back to 9.59–17.93:1, start fade at opacity 0 where pinned and 1 where not, shadow deepening only when scrolled. Four specs added. Still open, and previewed in `table-scroll-controls.html`: the scrollbar is an overlay taking 0px and sits **below the fold on five of the seven** overflowing tables — 296px below on `/distributions` — so there is still no control to act on. |
| `65f0622e5` | **A table that scrolls gets a rail, and the fade turned out to be invisible.** Reported as "unclear how the fade is triggered — I don't see it and cannot replicate it", and both halves were findings. The trigger was never the issue: the end signal is on from first paint, `data-overflow="end"` before anything is scrolled. **The fade was white on a white table.** Screenshotting the 68px strip with it on and off and diffing painted pixels, it moved the background by a mean of **0.28 of 255** — 0.1% — while **erasing 26% of the text** it lay over: invisible, and its only measurable effect was damage. I had been verifying its computed `opacity`, a **proxy**, for the third time this month. A scrim only works against content darker than the scrim; fading to white is right for dark text leaving a box and wrong for a white table. Measured the alternatives — hard rule 1.83 (also imperceptible), inset shadow 8.35, grey gradient 9.59 — and took the **inset shadow**, which erases no text and matches the frozen column's. Shipped it reads 7.95 on `/distributions` and 8.12 on `/items`. **And an edge signal cannot say *you can move*, so the table now has a rail** (option B of `table-scroll-controls.html`): a drawn horizontal scroll control that rides the fold and settles below the table, as Ant Design's `<Table sticky />`, Confluence and Jira all do — because the platform scrollbar is an overlay taking 0px and on five of seven overflowing tables sits below the fold, 296px below on `/distributions`. **`fixed`, not `sticky`**: `section.card-surface` is `overflow: hidden`, and a probe rail inside it did not track the viewport. **Below the table, not over it**: the first version overlaid the last row and, being a control, took the pointer — the hover on the bottom row's comment cell went to the rail and the tooltip never opened, which **three already-passing specs caught**. **`aria-hidden`, as a native scrollbar is**, reversing what the preview promised: the region is already a focusable named `role="region"` the arrow keys scroll, so a focusable rail would only add a second tab stop per table. Track 24px for 2.5.8, injected by the controller rather than written into 66 views. |
| `cb831742d` | **A narrow table stops being a table.** Below **640px of card** a `.data-table` becomes a list of labelled fields — one field column below 416px, two above it. Before this, **all fifteen tables scrolled sideways at 320px and at 375**, thirteen at 640, and the worst hid **80% of its width**: `/distributions` needs 1,638px and had 320; on `/purchases` you could see a fifth of the table. **This reverses a written convention on purpose** — `design.md` said tables scroll, citing the WCAG 1.4.10 Reflow exemption for data tables, but that exemption is *permission, not advice*, and the system already contradicted itself since the line item row stacks below `sm` for the recorded reason that "four columns at 320px leaves the item picker 72px". **The threshold is the card's width, not the viewport's**: on `/purchases` a 1023px viewport gives a 973px card and 1024px gives **702px**, because that is where the sidebar appears — a breakpoint at `lg` would restore the table exactly where it has least room. **Not a `@container` query**, which was the obvious tool: `container-type` computes to `contain: layout`, making the element a containing block for *fixed* descendants, and every row-action menu is fixed to escape this card. Labels are copied from `<thead>` by column index into a real element rather than hand-written on 299 headings across 71 views, and the table's **ARIA roles are restored explicitly**, since a browser drops table semantics the moment `display` is not `table` and `thead` is `display: none` here. Two defects found by things already passing: the scroll controller drew a **rail for a stacked table** (it now listens for `table:stack-change`), and a `font-weight` on the card title **did nothing**, because a utility beats a rule in `@layer components` — removed rather than forced. The cost, stated: `/purchases` at 320px goes 1,448px to **7,614px** tall. |
| `cafd3b53d` | **`process.doc` added.** The working process, written from what this branch actually did rather than an ideal: read the system first, measure, audit app-wide, preview, you choose, build once centrally, verify with the instrument that found the defect, document in the same commit, push. Opens with a process map readable at a glance, and records how the design system gets found in the first place — `CLAUDE.md` loads automatically and declares `design.md` normative. Carries the table of **proxies that lied** and the honest instrument for each, because that is the failure mode the process exists to prevent: every browser audit here has at least once reported clean while a reported defect was live. |
| `b205ff7f1` | **The edge signal drops to 6%, and a shadow that had never painted is found.** The grey edge read as a vignette, and measured so: isolated by shooting the strip with it and without it, the shipped shadow changed the background by up to **62 of 255** and tinted **28.5% of the visible table** — six times Ant Design's production value for the same signal. Now `rgb(5 5 5 / 0.06)` at 10px offset and 8px blur on **both** the container edge and the frozen-column boundary, which had been 40% and 28%: one number for one meaning. Max change **10**, touching **6.6%**. **It got heavy because of a bad metric** — ranking candidates by average luminance change over a 68px strip rewards a broad smear and punishes a crisp line, scoring a 1px rule 1.83 and calling it "imperceptible" when by sharpest local step it is **43.4**. **The larger find**: a `box-shadow` on a `td` is **never painted** under `border-collapse: collapse` — verified with a solid red 40px shadow showing **0%** of its pixels on the cell and **50.9%** on a control div. So the frozen column's shadow had never appeared in any version, nor had the `1px 0 0` hairline that was its divider, and **the spec passed throughout** by asserting on `getComputedStyle().boxShadow`, which reports a declared value whether or not a pixel changes. The divider is a `border-right` now and the boundary shadow moved to the wrapper, offset by a `--pin-width` the controller measures — Ant Design's own arrangement, and now it is clear why. This revives an option rejected two days ago as "more machinery than the question deserves"; the cheaper option could not work. |
| `a7a046797` | **Four page actions become two, and every button gains a border.** `/requests` carried four header buttons where design.md allows three — the **only** page in the app that broke it, out of **27 headers across three roles**. The rule had been written for weeks and even anticipated the check; nothing counted, so `bin/design/button-audit.js` does now, in a browser because half these actions are conditional on a role or a count. The CSV and picklist PDF are one **Export** menu — named after its contents, since design.md's own "More actions" names nothing — via a new `shared/essentials/menu_button`, the page-level counterpart to `row_actions`, both rendering items through a shared `menu_items` so a menu item has one definition. The header went from **707px of buttons wrapping at every width, 242px tall at 320px**, to **56px from 1440 down to 768**. "Calculate product totals" moved onto the card whose rows it totals — the exact diagnosis design.md gives for a fourth button — gained a `<tfoot>` **grand total** it never had (46 figures, no sum), and became "Show product totals", since nothing is calculated on press. It does follow the filters: 119 requests to 20 took it from 23,035 units to 3,804, and my first test saying otherwise was broken. **The find along the way**: `border` is 1px top and bottom and only `:secondary` had one, so every `:primary` and `:ghost` was **36px against a documented 38px** — 25 secondary at 38, **16 primary and 4 ghost at 36** across 17 pages. Invisible until a header had few enough buttons to sit on one row. The overlay audit then caught the new panel running off screen at 320×640, fixed with the clamped `fixed` placement `row_actions` already uses. |
| `282b91a24` | **One item is not a menu.** Both items in yesterday's Export menu are conditional and independently so — the CSV needs any requests, the picklist needs an *unfulfilled* one — so an organisation with requests but none outstanding got a menu holding a single entry, which is worse than the button it replaced. Proved rather than reasoned: the seed data is 119 pending requests and can never produce the case, so it took a spec creating one fulfilled request to get `MENU ITEMS: ["Requests as CSV"]`. `menu_button` collapses to a plain button now, in the component rather than the caller, since a caller cannot know how many of its conditional items will survive. It collapses to the **menu's** label — "Export", not "Requests as CSV" — which is safe only because a menu here is named after its contents, and is the one that is a verb. design.md also now says where the ceiling is: two to about four related outputs in one menu, each naming content and format; past that it belongs in the `/reports` hub, which already carries six. |
| `834358d58` | **Page subtitles say what you do, not what the title means.** Measured: all **40 index pages** carried a subtitle and about **20 defined their own heading** — "Requests" over "Essentials requested by partner agencies". 22 rewritten verb-led, 8 left alone. The rule came from the app's own four good ones (`/reports` says how they work, `/events` the ordering, `/admin/account_requests` the scope of both halves, the dashboard the purpose): each says something the **title cannot**. **Scope was rejected on a measurement**, and it was the tempting option since design.md prescribes it for a *card* and a helper could have generated all forty — but the pagination line already says "Showing 1–15 of 119 requests" on every one of these pages, the same duplication that removed the `<tfoot>` totals. Deleting them was the other real option and was rejected because "kit", "product drive" and "inventory audit" are not words a volunteer arrives knowing, so where the noun is jargon the sentence carries the gloss **and** the action. **Two of my own drafts were false** and were cut — `/users` has no roles column — and **three empty greps were wrong file paths, not missing features**. Inclusive, gender-neutral and non-ableist checked rather than asserted: `copy-audit.rb` is clean on all six checks, and coverage was proved by planting `Please`, `below` and `insane` in a new subtitle and confirming all three were caught. |
| `0f6a4d1ec` | **Copy review documented, and the partner portal finished.** Showing the portal after the app-wide subtitle rewrite found the bank side complete and the portal not: **three pages carried no subtitle at all** (`requests/new`, `individuals_requests/new`, the profile form), one defined "family", and the dashboard's subtitle was the partner's own name where the bank dashboard says what needs attention. All five fixed; the org name was checked to be in the top chrome first, so the dashboard loses nothing. The generalisable part is in `design.md` as a new **Reviewing copy** section and in `process.doc` as step 6a: run the audit, **then plant a violation to prove it read your files** — `0 findings across 0 checks` is a pass and is also what a broken audit prints — then the judgement half by hand, then check the **portal separately**, because it is a second product with a second audience and sweeping the bank side feels like finishing. Records that verifying a claim means opening the view, since an empty grep and a missing feature look identical. Two voice inconsistencies flagged and left alone deliberately: first person "Edit my organization" against second person everywhere else, and "Need help?" as the only title that is a question. |
| `48fe59c0e` | **The app speaks in second person, and an audit that reported a clean sweep of nothing.** Option B: the reader is "you", never "my", never third person. Where the possessive added nothing it went — "Edit my profile" → **Edit profile**, "My account" → **Account**, "My organization" → **Organization**, "My co-workers" → **Co-workers**; "your" survives where it distinguishes, so "Our impact" → **Your impact**; and where the speaker was the maintainers it is named or dropped, so "how to reach us" → **how to get in touch** and three `We can't delete…` errors became `… cannot be deleted.` **"Need help?"** was the only page title that was a question and the bank side already called it **Help** — now all four places do. **"Say how many of each item you need" described half its form**: every row is a "Select an item" dropdown *and* a quantity, so it reads "Choose the items you need, and how many of each." **My own first measurement was incomplete** — it scanned only `.erb` with specific key prefixes, so it missed nav labels in helpers, service error messages, a mailer and every capitalised variant; the real sweep found nine more. **And the audit work is the more useful half.** Proving `copy-audit.rb` had read a changed file fired two checks where three were planted: the sensory check missed "the items below" because `item` was not in its noun list. Broadening it produced a false positive on real dashboard copy ("Items below their recommended quantity", where below means *less than*), and the negative lookahead that fixed that **silently suppressed a genuine finding** — `a|an` without a trailing `\b` matched the first letter of "**a**bout", so "the details below about your bank" stopped being reported. All three cases are in the probe table now. Two real 1.3.3 failures were fixed as a result. Separately, **`route-sweep` printed "0 screens rendered" followed by "no design findings"** when the dev server died mid-run — a clean bill of health from an audit that made no requests. It exits 2 on an empty sweep now, verified both ways. |
| `5c26178e9` | **"We" goes where it was filler, and an audit that could not see half a heading.** 26 strings across the interface and the transactional mailers: "We're contacting you to notify you that your password has been changed" is "Your password has been changed" with eleven words of throat-clearing, and every one got shorter. **Three places keep it**, on the line of whether a reader expects a sender: the onboarding welcome email (a letter, with a voice), the privacy policy (legal, where "we" is the party committing), and the marketing page (brand voice, plus a **customer quotation** that is not ours to edit). A grammar defect fell out — the cancellation notification said "**a** essentials request" in both parts and had since it was written. **Then `page-audit` flagged my own new heading** "Contact Human Essentials" as Title Case: a false positive whose real cause was that the check had no notion of a proper noun, so any heading naming the product would trip it. It has a `PROPER_NOUNS` list now. Fixing it meant rewriting the scan, which exposed how narrow the old one was — it only matched a capitalised run **starting immediately after the tag**, and captured `[^<]+`, so a heading whose text sits inside `<strong>` was **unreachable entirely**. **Four genuine Title Case headings** surfaced, all in a section whose siblings were already sentence case, one contradicting its own edit-side card. |
| `58444c659` | **The dev server was not crashing; the CSS watcher was finishing.** `bin/start` runs three processes under foreman, which kills the whole group when any one exits — and the Tailwind CLI's `-w` needs a TTY. Without one it prints `Done in 1s` and exits **0**, so foreman SIGTERMed the web server and the worker. Nothing in the log looked like an error, which is why this was blamed on orphaned job processes earlier in the branch. `Procfile.dev` passes `[always]` now — verified both ways: plain `watch` exits in 1s with code 0, `watch[always]` was still running when killed at 12s. The Procfile also binds `0.0.0.0`, since the Rails default is localhost only and unreachable through the port forward this app is normally viewed through. Stack held 45s with zero `exited with code` lines and answers on both localhost and the container IP. |
| `646726044` | **The calendar is restyled, and its toolbar is ours.** FullCalendar shipped its own defaults on `/distributions/schedule`: buttons filled `rgb(44,62,80)` at a **4px radius and 16px text**, a 28px/400 month title, day headings at 16px/700 where a table heading is 12px/600, and grid lines in `rgb(221,221,221)`, a grey outside the palette. **The font was never the problem** — it is Figtree throughout; what read as another typeface was 16px/400 against the app's 14px/500. The grid is restyled in CSS as design.md already prescribes for select2, whose note describes the **identical numbers**; the toolbar is `headerToolbar: false` with Today, "‹ Prev" and "Next ›" as ordinary `:secondary, size: :sm` buttons driven by a new `calendar_controller`, because three buttons are cheap to own and cannot then be silently reverted by an upgrade. Three findings fell out. **`!important` is needed here and not for select2**, because FullCalendar injects its sheet into `<head>` at runtime, unlayered and later than anything this file emits. **A palette swap broke a contrast pair I never touched**: `--fc-today-bg-color: brand-50` put the existing slate-500 day number at **4.0:1**, caught by axe on the first run and now `brand-700` at **8.59:1**. And **the mobile list view had never worked** — `defaultView` and `eventLimit` are v4 spellings on a v6 install, so both were ignored; verified by running the new spec against the stashed old code, which reported `fc-dayGridMonth-view` at 375px. A wrong option name is not an error, it is nothing. |
| `fc9ae530f` | **`db:seed:calendar`.** The ordinary seeds scatter twenty distributions over a couple of years, which leaves the calendar page thin where you need to look at it: a sparse landing month, an often-empty next month, no day crowded enough to overflow, and nothing on today. The task adds 24 positioned ones — one on today, **six on a single day** so the `+N more` link appears, a spread through the next two months so Prev and Next both land on something, and four **completed** ones last month so the data is not uniformly "scheduled". Goes through `DistributionCreateService` rather than `Distribution.create`, since inventory here is event-sourced and a raw insert leaves `InventoryAggregate` disagreeing with the rows. Marked `Calendar test data`, and the task prints the line that removes it. Writing it hit `PG::UndefinedColumn` on `organizations.short_name`, which does not exist — the error names the query rather than the mistake. |
| `cde4ff54f` | **The calendar gets a Month and a Week, and the view lives in the URL.** There was no view switching at all before — FullCalendar's default toolbar carries none unless asked. **No Day view, on a measurement**: over a year, 22 days had any distribution, mean **1.9**, and 13 of those held exactly one. Week earns it at mean 3.5 and a peak of 16, which is the case the month grid handles worst. **Week is `dayGridWeek`, not `timeGridWeek`** — the times are real (the form takes `minute_step: 15`) but a distribution has **no end column**, so every event on an hour axis is zero-length, and **24 of 48 rows sit at 00:00** because `db/seeds.rb` writes a date with no time, so a time grid would show missing data as a midnight appointment. It also needs no new plugin. **The view is a URL parameter, not `localStorage`**, because the page-tabs rule already settled that argument — with `pushState` so Back genuinely returns, and `month`/`week` rather than the library's vocabulary. A narrow window defaults to the week as a list. **Separately, seeding the past turned out to be irreversible**: `check_no_intervening_snapshot` refuses to destroy a distribution a SnapshotEvent has folded into inventory, so the task printed a removal line that did not work. That group is `PAST=1` now and says it is permanent. Two mistakes of mine on the way — trimming a double-run by `created_at`, which the seeder **backdates**, so it deleted the latest-dated records rather than the newest; and running cleanup and re-seed in one command without checking the cleanup succeeded, leaving 12 permanent July rows. **And the seed data exposed a CRITICAL axe violation that had been latent**: FullCalendar renders "+N more" as an `<a>` with no `href` carrying `aria-expanded` and an empty `aria-controls`, neither allowed on a roleless element — invisible until a day was crowded enough to overflow. `moreLinkDidMount` gives it `role="button"` and drops the dead attribute; Enter and Space were measured working already. |
| `b71c0adfd` | **`destroy_all` on a distribution loses stock, and the seed task was printing it as advice.** `Distribution` carries only `before_destroy :check_no_intervening_snapshot`; nothing on the model publishes a `DistributionDestroyEvent` — only `DistributionDestroyService` does. So `destroy_all` deletes the row and leaves its `DistributionEvent` behind, holding inventory down for a distribution that no longer exists. Measured: 20 seeded distributions holding **150 units**, destroyed that way, moved inventory by **0**. There is a `db:seed:calendar:clear` task now and the round trip is lossless — **162,608 → 162,437 → 162,608**. **Underneath that**, the reason backdated seed rows could not be removed turned out not to be permanence but emptiness: `Event` validates `no_intervening_snapshot` **on create** and `DistributionEvent.publish` uses `create` rather than `create!`, so the event fails **silently** and `DistributionCreateService` still reports success — leaving a distribution that shows everywhere and moved no stock. The twelve such rows carried 0 events and deleting them moved inventory by 0. The seeder writes nothing before today now, and `PAST=1` is gone as the wrong answer to a misdiagnosis. |
| `ae3a982e1` | **A conditional requirement moves to the group's legend, and modal forms get audited for the first time.** "(phone or email required)" was written into the label, so a screen reader announced **"Phone (phone or email required)" as the field's name** — and again on Email, the same condition twice, as identification rather than instruction. It was the residue of an earlier pass that removed hand-written asterisks and left the words where they were. The condition now sits on a `<fieldset>` legend, which is where design.md already puts a requirement belonging to a group rather than a control; the rule is generalised from "a radio or checkbox group" to "a requirement that belongs to a group", which is what it always meant. **The audit had a hole exactly where the report was**: `form-validation-audit` visited every `new` **route**, and a modal has no route — so **four modal forms had never been audited**. It opens them now and found two things at once: `New quantity request` carried a `required` select with **no visible marker** (programmatically required, silently), and `Import from CSV` could not be opened from `/product_drive_participants` at all, because four of the five pages carrying it render the trigger only while the list is empty. Two mistakes in the audit change were caught before shipping — a helper referenced from a function handed to `page.evaluate`, which serialises it and drops its closure; and `markedFor` still reading legends only for radios, which would have silently stopped recognising these fields the moment the condition moved. `/partners/family_requests/new` is left as found: no inline error, no `aria-invalid`, verified identical on a stashed tree. |
| `f207b6d12` | **The family request form's real defect was not the one the audit reported.** It flagged `/partners/family_requests/new` for showing no inline error and no `aria-invalid`. The form had **not been submitted**: every child's checkbox is pre-checked, so the submit opened the confirmation dialog — *"You are ordering 2,500 total items"* — and the audit's summary selector read that as an error. It now ignores anything inside an open `<dialog>` and reports the case as "the submit opened a confirmation instead". And there is nothing field-level for the error to attach to: the only inputs are 36 checkboxes and the failure is about the set, so a callout is right and `aria-invalid` on 36 boxes would be a lie. **The real defect was beside it**: every checkbox was labelled `Include This Child?` — **36 identical accessible names**, so a screen reader hears the same six words 36 times with nothing to say which child. axe does not flag duplicate labels. Same defect `row_actions` already records, same fix — the label names the child; verified 36 checkboxes, 36 distinct names. Also fixed a flaky spec of my own: the calendar Back test called `go_back` straight after asserting the rendered class and raced the popstate handler, failing about once in twenty. |
| `59558a092` | **Import is offered whether or not the list has anything in it.** On vendors, donation sites, storage locations and product drive participants, `Import X` was the **`else` of the Export branch** — so the moment a bank had a single row the importer became unreachable, and taking on a batch is not something that only happens to an empty list. `/partners` was the one page that had it right, which is what made this look like a styling inconsistency rather than a missing feature. All five now read `Import X`, `Export`, `New X`, primary last — three actions, at the limit and not over it, confirmed by `button-audit`. **Export stays conditional** on purpose: an empty CSV is not a useful file and the import modal carries its own template. Surfaced by the modal audit, which could not open the CSV modal from `/product_drive_participants` at all. **And a mistake a linter could not catch**: the explanatory comment went in as an ERB comment inside a `capture { }` block, which is Ruby rather than template, and all four pages then rendered with **no actions container at all** — `erb_lint` passed on the broken version, and what caught it was loading the page and counting buttons. |
| `079280326` | **The calendar's Week button did nothing below 992px, and now there are three views.** "Week" meant a `dayGridWeek` above 992px and a `listWeek` below it, and since the list was *also* the narrow default, Week arrived already pressed, `switchView` returned early, and the button was inert — Month worked, so only Week looked broken. Measured at 1440, 1200, 1000, 991, 900, 768 and 375: every width under 992 was dead, and 992 is not unusual (a 1440 screen at 150% scaling is 960 CSS px). The mapping was the mistake rather than the threshold, so **List is a third button** and each label now means exactly one view; the regression test was run against the old controller and fails there. **Month and year are now two native selects**, because Prev and Next move one step and March next year was seven clicks away. Not `<input type="month">`: it is a picker in Chrome and Edge and a text box expecting `2026-08` in desktop Firefox and Safari, and only Chromium was installed to measure with — the same argument that deleted Litepicker. The year list is bounded by the organization's own `issued_at` range and grows when Prev or Next walks past either end. `essentials_inline_select_classes` is new: `SELECT_CLASSES` is `mt-1.5 block w-full` and would have stood 38px in a row of 30px buttons. A date **range** stays on `/distributions`, which the subtitle now links to — a grid cannot draw an arbitrary span. |
| `c3b5f4f0d` | **Controls that are already at their destination now say so.** The calendar's Today did nothing on arrival — the page opens on today, so it had nowhere to go, and that is the state you meet it in. It is dimmed while today is on screen and live once you navigate away, carrying `aria-disabled` **from the server** so there is no frame where it looks available, with the reason as sr-only text. `aria-disabled` rather than `disabled`: FullCalendar's own toolbar uses a real `disabled` here (measured on 6.0.1), which drops the button out of the tab order, so the toolbar's tab stops would change as you navigate. **Today was not marked at all in the list view** — FullCalendar sets `fc-day-today` on the row but `--fc-today-bg-color` only reaches day cells, so it painted `rgba(0, 0, 0, 0)`; on a phone, where the list is the default, nothing said which day was today. **The same fix reached the three "Reset search" buttons** on partner children, families and family requests, which had the identical shape. Those needed the filterrific AJAX to re-render the button too: it replaces only `#filterrific_results`, so the first version stayed dimmed and claiming there was no search while the list below showed a filtered one — measured, typing cut 86 rows to 82 and the button never moved. `essentials_link_button` gained `available:` and `reason:`, because a link cannot be disabled. |
| `ffa4da1be` | **Today is always enabled again, and the rule behind it is sharper for it.** Dimming it while today was on screen lasted a day. The reasoning had been design.md's pagination rule — a control that leads nowhere stays drawn and disabled — but that rule is really about controls whose press *costs* something: "Reset search" with nothing searched reloads the page for no change, a pagination end navigates to where you already are. Pressing Today on today calls an idempotent function and returns. The accessibility case against disabled controls is aimed at ones that **gate** a task, and Google, Outlook, Apple and Notion all keep Today live. Measured on the way to this: none of the three views scroll (`scrollHeight` = `clientHeight`, 35/35, 35/35, 478/478), so Google's own reason for keeping it live — re-centring a scrolling grid — does not transfer, which is what made this a judgement call rather than a correction. **What stays**: today is marked in the list view, which is the fix that makes a no-op fair, and the three Reset buttons stay gated because pressing one does cost a page load. The design.md rule now turns on that distinction instead of on "leads nowhere". |
| `8d91195d8` | **The calendar switcher splits into a duration and a layout.** Month/Week for how long, Grid/List for how it looks — because "List" named a *shape* where its neighbours named a *duration*, so nothing said how much time it covered. It is a week: measured, this week drew 4 of 7 days and started on a Wednesday, and the week of 7 September drew **one row**, indistinguishable from "there is one distribution, ever". Splitting the two questions also reaches **a whole month as one list**, which three buttons could not express; FullCalendar has all four views already. **A list now says what it covers** — "Monday, September 7 – Sunday, September 13 · 1 of 7 days has a distribution" — hidden in the grids where empty days are already visible. Four things the plan did not predict: **`format` is reserved by Rails routing** (`?format=grid` raised `ActionController::UnknownFormat`, a 406, so the parameter is `layout`); **clicking one axis writes both**, or a shared link would resolve the other against the *reader's* window width; **`Intl` has no pattern for a weekday plus a bare day** (en-US rendered `24 Monday – Sunday, August 30`, so the caption uses `formatRange`); and **the two list views cannot be made to order a day heading the same way** — overriding `listDayFormat` makes the alt mirror it and every heading renders its date twice, so the library's defaults stand. `?view=` links from before the split still work. |
| `15144236a` | **Five repairs to the partner pages.** The status pill was inside `[data-page-header="actions"]`, where a pill among buttons reads as a greyed-out button; it rides on the title line now via a new `status:` slot. **A Service area card** puts the counties a partner *declares* beside the zipcodes their families *actually live in* — measured, those sat **2,527px apart** (y=2733 and y=206) in two visual languages, and the declared table had **no class at all**, a bare unstyled `<table>`. This was option **B**, not the **A** originally recommended: asked why, looking at what else could go in the card reversed the answer. **Edit details and Manage users** moved into the card header, from two zones 63px apart. **Modal centring** is fixed in the shared partial — a `<dialog>` inside `space-y-6` had its `margin: auto` replaced and pinned to `top: 0`; proven by toggling the class with it open (0 → 453 → 0). **Edit partner profile** was 12px off the gutter with a duplicated action row, 36px buttons from raw utility strings, a 0px gap and one icon on 10 of 13 sections — now one row at the end, from the helper, aligned. Two self-inflicted bugs on the way, neither caught by a linter: an ERB comment **nested inside an ERB output tag** (500, and the second time on this branch), and a nil `@impact_metrics` for uninvited partners that failed 8 specs, attributed by stashing to a 47-example clean baseline. |
| `36ed92982` | **The Service area card rebuilt, and a primary button moved.** The card put its two facts in two columns and never made the comparison it exists for — measured, the right column was **273px tall holding one number**, ~85% empty beside a four-row table, with the zipcode link stranded in the card header. It is stacked now: the comparison stated in the card's `subtitle:` (*"They serve 4 counties. Their families live in 13 zipcodes."*), the counties table full width and sorted by share, and the **zipcodes shown rather than hidden** — max 13, median 8 per partner, so the dialog is not rendered at all below 16. Column headers, headings and the subtitle all follow the sentence-case and `text-xs font-semibold text-slate-500` rules; the table carries its visually hidden `<caption>`. Separately, **the profile form's primary moved to first**: design.md's "primary last" is the *page header* rule, describing a right-aligned row, and a form's row is left-aligned — measured, six of six forms read `[Save] Cancel`. One rule now covers both: the primary sits at the row's alignment edge. |
| `cd108bb62` | **Zipcodes are five digits, in bordered boxes, and the count was wrong.** The list read as a run of digits: ten of thirteen carried a `+4` and three did not, so widths were ragged (**35 of 67** across the database), and nothing said how it was sorted. The suffix names a block rather than an area — and `uniq` over the stored values counted `45612-123` and `45612-126` as **two** zipcodes when they are one. `spec/models/partner_spec.rb` **asserted that pair and that count**, so the bug had been pinned down as a requirement; both specs now expect 1. `family_zipcodes_list` truncates, deduplicates and sorts. Display is square-cornered `font-mono` boxes — square specifically, because both chip shapes in this app are `rounded-full` (a status pill carries a tone, a filter chip an `×`), so a square inert box is a third object. **An aligned grid was recommended first and withdrawn**: measured at the real 1144px card it renders 12×2 with an orphan and ~90px between neighbours, which separates the codes rather than bounding them. |
| `ba3f72fdf` | **Forms pair their short fields, and design.md finally says how wide a form is.** There was no rule: **36 views** set their own max-width and had drifted into 672px (480px of dead page) and 1120px. **Centring was ruled out by measurement** — every `h1` in the app sits at 288, so a centred form would move its heading 144–256px and the page title would slide sideways between a list and its form; centring is also the convention for *standalone* pages, and this app's own auth screens are a split panel. So the fix is width, spent by pairing rather than stretching: `essentials_field_row` puts value beside quantity, the two on-hand thresholds together, start date beside end date, phone beside email, square footage beside warehouse type. Six forms widen to `max-w-4xl` and get **shorter as well as wider**; **kits keeps 672** because three fields have nothing worth pairing. The helper documents both conditions — short enough that full width is absurd, and related enough to read as a pair, since DOM order is announcement order. |
| `d7543ecff` | **The ghost scrollbar was two scrollbars, and the thumb never met its contrast requirement.** `.table-scroll` forced a persistent native bar and `.table-rail` built a floating custom one — both on, both permanent. Measured on `/distributions` at 1280: rail top and region bottom both at **637**, the native bar in the last ~10px inside and the rail immediately below. It seemed to come and go because the rail rides the fold and travels down to meet the table's end. The native one is now hidden under `[data-railed]`, so it only goes once the controller has built its replacement. The rail also loses its 25px bar, 92%-white backdrop and hairline — **six elements to two** — keeping the 24px transparent band because the track is the pointer target and 2.5.8 asks for 24. And the thumb moves to **slate-500**: a custom thumb is author content so 1.4.11 applies, and against the slate-100 track the shipped slate-400 was **2.34:1**, under 3:1. The preview had recommended slate-300, which would have been **1.36:1** — axe cannot see any of this, because nothing in the markup says that div is a control. |
| `bb272a510` | **The rail, reported four ways: two defects from the night before and two that had been there all along.** "Very dark, hovers in an odd way at the bottom of the page, no padding above the pagination, no border radius." I first attributed three to the previous commit and had to correct it — **`--radius-full` dates to `015da3b36`**, the first rail commit, and the gap was zero then too (25px strip, 25px rail). The previous change *unmasked* them: a square slate-400 thumb under a 92%-white backdrop is a quieter object than a square slate-500 thumb with nothing behind it. **The corners never rendered at all**: `border-radius: var(--radius-full)` on the track and the thumb, and that token does not exist — Tailwind v4's scale stops at `--radius-2xl` and `rounded-full` compiles to `calc(infinity * 1px)` as a literal — so the declaration was invalid, silently dropped, and both measured **0px** for weeks. Resolved all **30** custom properties the stylesheet references against the running app: **28 resolve**, the other miss being `--pin-width`, which the controller sets at runtime and is correct. One bad token, not a pattern. **The thumb was over-corrected, not just under-corrected**: slate-500 is **4.35:1** where 1.4.11 asks 3:1, chosen only because the scale has **no step between slate-400 (2.40:1, fails) and slate-500**. Solved for the lightest slate-hued value that still clears the floor — `oklch(0.636 0.044 257.1)`, painting `rgb(122, 140, 166)` at **3.13:1**. A floor says which values are available; it does not pick one, and the entry a week earlier records me getting this wrong in the *other* direction. **The pagination gap was arithmetic**: a 24px strip holding a 24px rail left its bottom edge **0.14px** above the pagination's border; strip to 32px for 8px of air. **And "hovers oddly" was the backdrop**: traced down `/distributions`, the rail rides the fold for **448 of 611 scrollable pixels — 73%** — lying on live rows, and last night's change removed the backdrop that separated it from them. That reasoning was about the *settled* state, where nothing is behind it, so the backdrop returns gated on `data-floating`, with the hairline as an **inset shadow rather than a border** — under `border-box` a border would take the track to 23px and put 2.5.8 a pixel short in the hardest state to hit. **Three specs added and each verified to fail when its fix is reverted**, since the radius bug proves a passing suite can miss this entirely. Ratios here are sampled from **painted pixels**, which corrects two older figures: slate-400 reads 2.40 not 2.34 and slate-500 4.35 not 4.34, both previously computed from Tailwind **v3** hex. Not built: `absolute` once settled (option C), offered for the judder reading of "hovers oddly" that could not be reproduced headless. |
| `38c4162a2` | **The bar looked stuck to the pagination, and padding was never going to fix it.** Reported again after the strip had already gone 24px → 32px. **The box measurement said there was no problem**: 8.14px of gap, and I confirmed 8.14 on every page with a pager, at three widths, seven viewport heights and *every scroll position* in a full sweep — nothing overlapping, nothing touching. Stopping there would have been true and useless. Sampling the **painted pixels** instead — every full-width line the card draws, with its width and darkest value — found it at once: the row dividers run **1px slate-200 on a 53px rhythm**, and the bar is **6px at darkest 143**, the heaviest line in the card, sitting **18px** above the footer's rule. Proximity decides grouping, so it read as part of the pager. *A box gap is not a visual gap* — when a spacing complaint contradicts the measurement, measure the ink. **Padding alone could not close it**: the gap above the bar is 62px, a whole row, so evening the two sides needs a strip near a row's height, and a strip that tall reads as an empty row (0.14 → 8.14 only moved the ratio 3.4:1 → 2.6:1). So the strip goes to **44px** for 29px of clear space, **and the duplicated line goes** — one boundary, one line, and the bar is the heavier of the two. Not a new principle here: `_pagination` already draws no border of its own because doing so *"put the pager inside two stacked hairlines twelve pixels apart"*, the same defect and the same answer five weeks earlier. Gated on **`data-railed="settled"`** rather than `[data-railed]`, so a rail riding the fold cannot blank a rule it is not standing in for — it cannot happen today (floating puts the footer ≥20px below the viewport) but the rule should not rest on placement arithmetic holding. The controller writes `floating`/`settled` where it wrote an empty string; `[data-railed]` still matches either. Verified: **0** positions across 4 pages × 4 viewport heights × every scroll offset where the footer has neither a rule nor a bar. **Two specs added** — the footer's rule in both rail states, and a no-rail table keeping its own — plus the existing gap spec tightened from 7.5 to 19; both new thresholds were checked to fail with the fix reverted. `!important` on the override, because a utility beats a rule in `@layer components` whatever its specificity. |
| `4e0132f1e` | **Four goes at one gap, and the unit I kept measuring was the wrong one.** "Too much padding between the pagination component and the scroll — it needs to be the same as the padding below pagination." The strip went **24 → 32 → 44 → 24**, and the through-line is that *nobody can see the strip*: the rail is a 24px pointer target with a 6px bar centred in it, so the strip's height and the gap anyone is actually looking at differ by a constant **9px**. Three fixes running were aimed at a number nobody was reporting. **When a report and a measurement disagree four times, the measurement is of the wrong object** — the spec now asserts the gap *above* the pager's controls against the gap *below* them, which is the thing being complained about. The reference was given: the footer's `py-3`, **12px**; measured above, **42px**. **A floor had to be designed around**: the strip cannot go under 24px without the rail's box reaching into the footer, and that box is a pointer target — overlap it and a click meant for *Next* jumps the table sideways — which puts the closest centred-bar gap at **22px**, still lopsided. So the bar moves *within* its track instead: **bottom-aligned when settled**, spending its 9px of dead space upward into the strip where there is nothing, giving **13px above against 12px below** with the full 13px of clearance intact. Painted pixels: **23px** of white above the pager's text, **21px** below. **Centred while floating**, where the rail's bottom edge is the window's and a bar sitting there would be pinned to the screen edge. **The three changes only make sense together**: 24px of strip was wrong two days ago and is right now, not because the strip changed but because the footer no longer draws a rule for the bar to pair with. And an invariant fell out — the strip now being exactly the rail's height makes "rail bottom at the fold" and "footer top at the foot of the window" the same boundary, so the footer is *provably* never on screen without the bar above it, which is what the `data-railed="settled"` gate depends on. Exact rather than comfortable (the margin can be a fraction of a pixel), so still asserted: **0** bad positions across 4 pages × 4 viewport heights × every scroll offset. |
| `221055351` | **A form's buttons go below the card, and the design system finally says where a button goes.** Asked why New item, New kit "and so on" nest the button inside the card under a divider, and to check the system for the pattern. **There was none**: `design.md` had one line about a form's action row — the primary comes *first*, because the row is left-aligned — and nothing about where the row lives. The app held **three** answers: a divider inside the card body (**33** views), buttons below the cards with no divider (**7**), the card's `footer:` slot (**2**). **The divider was the symptom and it measured**: drawn inside the card's 20px body padding it came out **854px of rule in an 896px card, inset 21px each side**, against `/users/new`'s real footer slot at **958 of 960** — the only rule in the app that did not reach the edges of what it divided. **Option C chosen**: below the card, no divider at all. The argument is scope rather than looks — a card groups content, the submit commits the *form*, and on seven forms the form spans two or three cards and belongs to none of them. Those seven already worked this way, which is the tell: the app had derived the right rule where the distinction is visible and got it wrong where it is invisible. C leaves **one** rule for all **42** forms; A (the footer slot) would have left two and a judgement call at every new form. **`essentials_form_actions` renders the row** so the rule has one definition instead of 42 utility strings; the 8 already-correct multi-card forms were converted too, because a rule enforced in one place beats one that happens to be followed. **The risky half is structural, not visual**: 31 views had `card > form`, and a submit cannot be outside the card and inside the form at once, so the nesting swapped — and a form boundary in the wrong place puts fields outside the form that submits them, which renders fine and quietly loses data. This app has done it **twice**, and both scars are still commented in `profiles/edit` and `partners/requests/new`. So it was verified in a browser: **12 form pages, 0 orphaned controls**, every submit inside its form and outside its card, plus the **full system suite at 674 examples** and a new spec verified to fail when the divider returns. **The caveat, asked for explicitly**: a button stays inside a card when the card is its scope — *Add another item*, *View all users*, a pager — and those keep the card footer's full-bleed rule. The test is what pressing it affects: a card action changes what is in the card, a form action commits the whole form. **It never competes with the page header**, which on form pages carries navigation only: exactly one form view puts `actions:` on its header and it holds a status pill, not a button. Left alone deliberately: the fieldset dividers that separate *bands of fields* within a card, which are the line item card's pattern and correct. |
| `12bc20d95` | **A status is not an action — and on a page-titled page it is not a pill either.** The inconsistency the previous commit recorded and left: **four** partner-facing headers passed a status pill into `data-page-header="actions"`, all after `partners/show` had been fixed for exactly this and the reasoning written into the `page_header` partial. **The audit could not have caught them**: `button-audit` counts `a, button` and a pill is a `span`, so it reported those headers as carrying *zero* actions — true, and useless, because the container held something that was not an action. The new spec counts spans instead; a rule enforced by counting what it permits will not notice what it forbids. **The obvious fix was wrong on half of them**: `status:` renders the pill inside the `h1`, which is right where the title names its subject (`partners/show` reads "Pawnee Homeless Shelter Approved") but produces **"Distributions Approved"** where the title names a page. **Retitling was tried and reverted by a spec** — changing the dashboard's title to the agency's name broke `partner_system_spec.rb:293`, which asserts `h1` text "Dashboard" to prove a *redirect* landed there; it was not testing headings and caught the design change anyway. So: `status:` on the two profile pages, with title and subtitle swapped so the agency names its own page; **removed** on distributions, where a partner's standing has no bearing on what has already been delivered; and on the dashboard a **callout**, shown only when unapproved. That last one fixes a real gap rather than relocating a decoration — the request options card is hidden outright for an unapproved partner (`render … if @partner.approved?`) and the pill was the only thing explaining it: one word, in a corner, next to an unrelated title, never naming the consequence. It names it now, and an approved partner sees nothing where before they saw "Approved" every day. Not a new pattern — `partners/profiles/show` already answered `recertification_required` with a callout five lines above the pill this removed. **Copy per state, not the enum**: the first draft printed `status.humanize.downcase` and produced *"Your agency is recertification required"*. Three specs added, verified to fail when a pill is put back. **Left alone**: `admin/dashboard`'s two pills sit in *card* headers as counts beside a title, which is a badge, not a status among buttons. |
| `ad32406f4` | **The admin dashboard's count pills — and the number one of them showed had been wrong all along.** The two I had named as "left alone" last commit, on the grounds that they are *card* headers and the pills are counts. Looking properly found what the placement argument had missed: **the number was false**. `@recent_users` is `.limit(20)` and the pill printed `@recent_users.count`, which on a limited relation returns the **cap** — verified against the seeded database, **23** users had signed up that week and the relation counted **20**. The card read "20 new users", and would have read "20 new users" if two hundred had joined. A page size presented as a total: the exact failure `essentials_pagination_summary` exists to prevent, its own comment noting that a proxy number "never answers the question … how big is this result set?" **It stayed hidden because it is only wrong once the list overflows** — not the state anyone looks at on the day a `.limit` is added — so the spec creates `RECENT_LIMIT + 3` users, since one that does not overflow the cap passes against the broken code. So: three faults in one control, and only two were placement. A card has no `status:` slot, but it has **`subtitle:`**, which the *third* card on that same page already used for its explanatory line. **What it should say was the better question**: the organizations count was *correct* and still not worth keeping, because its list is uncapped so the number equalled the length of the list directly beneath it — the redundancy that killed the `<tfoot>` totals. But deleting outright would have lost something, since **the period was stated only in the card's *empty* state**, so a reader with data was never told what "recently" meant. `essentials_recent_subtitle` states the period always and a total only when truncated: **"The 20 most recent of 23 users added in the last week."** `total:` defaults to the shown count, so adding a `.limit` later forces the caller to say whether the number is the whole of it. Seven specs added — six on the helper, one on the controller wiring — and the wiring one verified to fail when reverted to `@recent_users.count`. Named rather than fixed: the card still truncates at 20 with no in-card paging, which is right for a dashboard card whose footer links to the full list, but it is *said* now rather than silently true. |
| `27e8a7c82` | **Four months of `main` merged in — main's behaviour, design's presentation.** `origin/main` had moved **104 commits** while this branch did **330**. **Merge rather than rebase, for a reason specific to this repo**: a rebase rewrites every SHA, and this changelog is keyed by commit hash with **165 rows all pointing at design-branch commits** — it would have left the record of what happened referencing commits that no longer exist, on top of **78** conflict resolutions. The merge was one pass over **21 conflicted files**, 110 auto-merged, every hash still resolving; both figures measured in a throwaway worktree before choosing. **Rails 8.0.2 → 8.1.3.1**, discard 1.4 → 2.0, standard 1.54 → 1.56 and the rest of main's bumps, with **no Bootstrap, sassc, autoprefixer or popper** in the lock — the Gemfile no longer asks for them. The lock was rebased on *main's*, not design's: taking design's kept its older gems and silently dropped the dependency bumps that are most of main's 104 commits. **`KitItem` is gone — `Kit < Item` by STI now**, so `@kit.kit_item.line_items` became `@kit.line_items`, `item.kit_id` became `item.is_a?(Kit)`, and the kit form builds line items on the kit's own builder; two data migrations moved the rows and the `kits` table and `items.kit_id` stay behind, vestigial and reversible. **Features brought across and rebuilt in the design system**: Date leads the donations table (#5599, and it takes the frozen column, since `.pin-col` is `left: 0`); a donation's page names its drive participant (#5598) in the detail list rather than a `<table>`, showing "—" not "N/A" like the sixteen other blank fields; product drive participants filter by business and contact name (6ece95935) on the filter bar rather than a Bootstrap card, gaining a `:no_results` empty state; a product drive exports its participants (#5596) from the page header rather than a `card-footer` with a `float-right`; finalized audits and closed account requests cannot be edited. **The toast could not come across, and that is a fact**: main built it on `toastr`, and the essentials layouts load *only* `tailwind.css` with no toastr CSS in the build, so it would inject markup nothing styles — its element also carried `d-none`, which renders as nothing here, so the "hidden" trigger was a visible empty div. The background-download *feature* is kept: the fetch controller came across untouched and the announcement is a `flash[:notice]`. That surfaced two more: `flash[:trigger_csv_download] = true` would have drawn **a message bar reading "true"** (hence `NON_MESSAGE_FLASH_KEYS`), and `auto_submit` rebuilding an export href from the filter form **dropped `export_csv=true`**, so the first filter change would have silently reverted the export to a foreground request. **The best find was not a conflict**: main's new filtered participants export returned 3 rows whatever the filter said, because `public/product_drive_participants.csv` — an *import template* this branch added — shadowed the export route, Rails serving `public/` ahead of the router. `public/vendors.csv` shadowed the vendors export the same way. Both were the only two of five templates not named `*_template.csv`; renamed, both routes work. A live bug on this branch that took main adding an export to reveal. Also fixed: `kits_helper` called **`can_deactivate?`, defined nowhere on any of the three branches** — every render of that branch raised NoMethodError, surviving because no spec reached it. Two of main's flake-fix spec changes were reverted deliberately, both encoding a UI this branch no longer has (`#nav-partner-groups`, a tab panel that became a page; `'Request Received!'`, now sentence case), keeping main's intent where it had one. **`schema.rb` left alone on purpose**: the migrations under 8.1 reformat the dump and reorder every column — a thousand-line, semantically identical diff at the same migration version, which would bury the merge and conflict with everyone. Verified: **2140** non-system and **683** system examples green, rubocop clean across 663 files, `erb_lint --lint-all` clean across 422, and twelve pages rendered in a browser with no Bootstrap classes and no JS errors. |
| `f2c390d36` | **The last toastr call, and a message nobody could see.** The leftover flagged at the end of the merge. `barcode_items/create.js.erb` confirmed a successful scan with `toastr.success(...)` on a page using the essentials layout — and **it was invisible**, measured rather than assumed: driving `/donations/new` and calling the same function, **zero toastr CSS rules load**, so the container came out `position: static`, `z-index: auto`, no background, no padding, appended at the foot of the document at **y=1284 on a 900px viewport**. Below the fold. The scan worked, filled the field, and said nothing. **The spec passed throughout** — `have_content` finds text in the DOM whether or not anyone can see it, the same proxy-assertion shape as three earlier findings on this branch. It asserts `[data-flash]` now, and was checked to fail with the `toastr` call restored. **The fix is the strip that already existed**: the message is appended to `[data-flash-region]`, rendered from a new `shared/essentials/_flash_message` extracted from the strip, so the server and this JavaScript emit the *same* markup and a message raised after load is indistinguishable from one that arrived with the page. **The strip is always in the DOM now and hides itself** — JS needed somewhere to append to, and an always-present wrapper would have cost `pt-6`, 24px above every page, so `.flash-strip:not(:has([data-flash]))` is `display: none`. CSS rather than a server-toggled class, so appending is all it takes to reveal it and nothing must remember to switch it off. Verified: 0px and the `h1` unmoved with no flash; a 48px bar at y=93 once one is appended. **`toastr` removed entirely**, importmap pin and `application.js` import, that being its last caller — a dependency that renders nothing is worse than none, because it looks like a working notification system to whoever reaches for it next. 2140 non-system and 683 system examples green; rubocop clean across 663 files, `erb_lint --lint-all` clean across 422. |
| `c824bb2eb` | **A migrated shell around an unmigrated body: the organization page rebuilt.** Reported as looking "not migrated at all" — and it *had* been, page header and card and no Bootstrap classes, with the 28 fields inside left exactly as they were. **That combination is the finding.** The page returns 200, carries no legacy class, throws no JS error, and passes `undefined-classes`, `button-audit` and the system suite: every check this app has says it is migrated. Measured live, it had **28 label/value pairs and zero `<dl>`**; **6 `<hr>` rendering `oklch(0.208 0.042 265.755)` — slate-900**, because preflight sets `border-color: currentColor` so an unstyled `<hr>` draws in the *text* colour; **7 different vertical gaps** (24/36/44/45/54/61/93px); **15 of 28 labels in Title Case**; an icon on 14 rows; and invalid nesting that made the browser manufacture **2 empty `<p>`** — `</address>` was closed inside an `if` branch with a stray `</p>` after it, the same shape as the three profile partials that closed wrappers they never opened. **"No Bootstrap classes" is not the same as "migrated", and nothing automated can tell the difference** — every audit here answers *is anything from the old system present?*, none answers *is this built the way the new one builds things?* **Option A built**: one card of eight bands — the line item card's tinted strip, which is what makes six rules unnecessary rather than merely recoloured — with the fields as a `<dl>` on a two-column grid through a new **`essentials_detail`** helper, so the em dash for a blank is decided once rather than 28 times. Two columns and not four because the approval and request labels would wrap at four. **The preview's height claim was wrong and is corrected in place**: it predicted roughly halving, and the card went **1,519px → 1,516px** — the eight bands cost ~368px, almost exactly what the second column saves. The case is consistency and the broken markup, not height. Verified: heading order `1,2,3×8,2,2` with **no skips**, no stray `dt`/`dd`, every `<dl>` child a `<div>` (valid HTML5 grouping), **one** 16px gap throughout, 11 em dashes, 0 `<hr>`, 0 `<br>`. Two spec files updated — they asserted the Title Case labels and one searched a `<p>` whose sibling held the value, the coupling that makes a rewrite look like a regression — and they now also assert what the page must *not* have. 2140 non-system and 683 system examples green; rubocop clean across 663 files, `erb_lint --lint-all` clean across 422. `fa_icon` stays: it is a shim onto Bootstrap Icons and renders fine, but these 14 were nearly every use in the app and **one call site now remains**. |
| `a7bcbf4a2` | **A detector first, then the sweep: fourteen pages with the wrong gap, and nine more unmigrated bodies.** Prompted by a fair complaint -- three more defects on the organization page after its card had been rebuilt, and *why is there a need to individually point out elements on the same page.* The cause was diagnosing a **partial** instead of a **page**: `_details.html.erb` was named, so it was measured, and the two partials beside it in the same `show` template were never opened. **So the order was inverted**: `bin/design/shell-first-audit.rb` was written *before* anything was touched, and it is why this covers **24 templates** rather than the 3 that were pointed at. It asks the question none of the other eleven audits do -- every one of them answers *is anything from the old system present?*, which a shell-first page passes by construction; this one answers *is this built the way the new system builds things?* **The header gap was the biggest find and nobody had reported thirteen of them**: the shape is a `px-4 py-6 sm:px-6 lg:px-8` closed after the page header and a second one opened for the content, stacking two paddings, measured at **72px against the design system's 24** (the header's own `mb-6`). `/organization` was reported by eye; the other **13 were found by counting the wrapper in the templates**, and all fourteen render, validate and pass `route-sweep.js` -- 142 screens, no findings, before *and* after. All fifteen affected screens now measure exactly 24. On `admin/users/edit` the roles card had been outside every wrapper, running to the window edge with no gutter. **The organization page's other three defects**: the users table was `<table class="table border">` -- Bootstrap's `.table`, defined nowhere here, so it styled nothing -- in a card whose header was written by hand with the invite button pushed over by `float-right` (the row partial had been migrated; the table around it had not), and Edit sat in the "Organization info" card header where it read as editing that card's six fields rather than the record's 28. `/users` had the same card with an **empty** `border-b` strip: a hand-written header holding nothing, drawing a hairline for no reason. **Nine more bodies the audit found**: a bare `<table>` with a loose `<th>` row on the partner profile; `admin/users/_roles` rendering the card component and then writing its header out underneath it; `profiles/_show` holding fifteen sections apart with **15 `<br>`** and using a `<strong>` as a heading; a `bg-yellow-200` notice on the account request form -- a raw palette colour no callout uses -- split by two `<br>`; two admin lists positioning a button with `float-right`, one of them wrapping it in an `<h2>` that announced the button as a heading; a bare `<hr>` between served-area rows; and four button class strings pasted inline, of which **the filter bar's had already drifted** to `font-semibold` and a `shadow-sm` no other secondary button carries -- which is the whole argument for `essentials_button_classes`. **The narrowings are the substance of the audit, not a footnote.** Four of its eight checks were false-positive factories first, and each fix is a statement about the design system: a `<br>` inside an `<address>` is correct HTML (unnarrowed it reported 31 and **29 were right**); `text-xs text-slate-500` is the documented *meta* style, so a detail pair needs `font-medium` -- what `essentials_detail` puts on a `<dt>` -- and four of them, or a stat card's caption matches; a **modal's** header is a card's header exactly, so matching markup reported all fourteen modals in the app, and three keep their `<dialog>` in `confirmation_controller.js` where no `<dialog>` check could see it; and an icon-only chrome control is `inline-flex rounded-lg` with a `size-*` and no padding, not a copy of anything the helper produces. Like `page-audit.rb` it proves its detectors against a probe table and aborts if one is wrong, which **caught its own first bug**: `'\\n'` in a single-quoted Ruby string is two characters, so the card-header detector was dead when written and said so instead of reporting a clean zero. **Two dev-only overlays lie to any DOM-reading audit**: the browser probe written to confirm these fixes reported 19 non-`.data-table` tables and 27 layout `<br>` on a page with one table and none, all of it **rack-mini-profiler**, and a later `<br>` belonged to **bullet**'s eager-loading notice. **`.pin-col` came off `/users`**: freezing a column keeps a *scrolling* table's identifying column in view, and on two columns it held **417px of a 740px** landscape phone -- caught by `responsive-audit.js` at 740x360, the only finding in 110 page/width combinations. **One copy change, stated plainly**: `_area_served` said "No County Specified" and "% of Clients in county", asserted verbatim in four request specs; design.md names table headers explicitly under sentence case, so the templates changed and the assertions followed. New `spec/system/page_layout_system_spec.rb` pins seven invariants no other spec asserts, **each verified to fail with its fix reverted** -- and the empty-card-header assertion was rewritten when that check revealed it passed against the very markup it was meant to catch, because `> div` misses a header the card wraps. Verified: **2394** non-system and **690** system examples green, rubocop clean across 665 files, `erb_lint --lint-all` clean across 424, `page-audit.rb` and `undefined-classes.py` at zero, `route-sweep.js` clean across 142 screens in 3 roles, `keyboard-audit.js` clean at 1280 and 375, and `responsive-audit.js` clean across 110 page/width combinations. |
| `e7e62985c` | **The last band on the organization card had no bottom padding.** Reported by eye: the "Annual survey" section ran into the foot of the card. `_details_band` dropped from `py-4` to `pt-4` on the final band, on the assumption that the card would supply the bottom padding -- it does not, because the card is rendered `padded: false` and its body has none at all. Measured: the last field sat **1px** from the card's bottom edge against the **16px** each of the seven bands above it had. `py-4` on every band now, the `last:` local removed since nothing else used it, and the last field sits 17px off the edge (16 plus the border). Pinned in `page_layout_system_spec.rb`, verified to fail with the change reverted -- it reports all eight bands at `16px/0px`. The general rule is in design.md: if a container's padding is the reason a child skips its own, check the container has some. |
| `62aae6e5a` | **Button labels: two or three words, and the page supplies the rest.** Asked for a recommendation on "Invite user to this organization", which reads verbose -- and the measurement agrees: of the app's **41 distinct button labels, 31 are one word, 26 two, 12 three, two four**, and that was the only five. **The fault is restating the context, not length**: it sat in the footer of a card titled *Users*, on a page whose `<h1>` is the organization's name, so three of its five words repeated what the screen said twice. WCAG 2.4.4 is Link Purpose *In Context*, and the card and heading are that context. Now **`Invite user`** -- verb plus object, the shape 26 other labels use, consistent beside `Promote to admin` and `Demote to user` in the same table. `New user` was rejected because the action sends an invitation and leaves a pending record while every other `New X` in the app creates immediately; matching the pattern would have cost the meaning. **The context moved rather than vanished** -- the modal is still headed "Invite a new user to {organization}", which is where naming it tells you something. `/admin/users` said `Invite a new user` for the same action, so the two disagreed; both agree now. **Four Title Case button labels went with it**, and the reason nothing caught them is that `page-audit.rb` enforces sentence case on **headings only** -- buttons were never in its scope, so `New Announcement` (x2), `Add New Organization` and `New Donation` sat outside a normative rule for the length of the migration. `Add New Organization` became **`New organization`** rather than `Add new organization`: `New <noun>` is what the other nine create buttons say and it was the only one carrying two verbs. Three specs asserted the old strings and follow. **Named and not done: 57 Title Case *form field* labels** in the partner profile forms -- non-conforming under the same rule, but a large user-visible copy change across two parallel trees that must stay in step (`profiles/edit/` and `profiles/step/` render the same fields), and a decision to take on its own rather than as a rider on a button. The label rule is now written in design.md, which it never was, with the scan that finds violations -- over the button helpers, not `label:`, which belongs to form fields. Verified: **2394** non-system and **691** system examples green, rubocop clean across 665 files, `erb_lint --lint-all` clean across 424, `copy-audit.rb`, `page-audit.rb` and `shell-first-audit.rb` at zero, `route-sweep.js` clean across 142 screens in three roles. |
| `92e4c4659` | **The organization settings form: bands, spacing, a readable field and a rich text editor the design system did not have.** Six things reported on `/manage/edit`; five were defects and the sixth needed a component that did not exist. **The gap under the heading was 48px against 24** -- two page wrappers again -- and the check written for the previous fourteen **missed seventeen more**, including this page, because it required both wrappers to be the exact string `px-4 py-6 sm:px-6 lg:px-8` and these open the header with `pt-6`. Matching the *gutter* finds both shapes; `shell-first-audit.rb` carries the check now, and the 22 merged wrappers took `py-6` so the pages have a bottom edge. **The divider that started mid-sentence** was seven `<fieldset class="border-t">` with a `<legend>`: a legend is rendered *in* its fieldset's top border and the browser cuts a gap for it, so the rule began where the legend text ended. Not a pattern -- a rendering artefact. Sections are a new **`shared/essentials/form_section`** band now, the same band the organization page uses, so a record and the form that edits it look alike; `display: block; width: 100%` is what makes a legend layout-able. **Radio spacing was 24px rows with a 0px gap** in all 14 groups and everywhere else in the app, because `:essentials_collection` set the gap between control and label and nothing between rows. Stated precisely, that *passes* WCAG 2.5.8 -- the row is exactly the 24px minimum -- and sits on its floor; **GOV.UK** pairs a 40px control with a 10px gap, **Material 3** asks 48dp, **Apple** 44pt. Now 32px rows with 8px between, set once on the wrapper. **"Deadline day" was cut off mid-word**: the field measured **44px against a 92px placeholder**, because both number fields were rendered inside `f.input ... do` and a block *replaces* the wrapper's input, skipping the whole `:essentials` pipeline -- the same shape that cost three profile fields their error handling earlier. The partial was unmigrated besides: a label, a `<br>`, a radio, a second label for the same radio and another `<br>`, plus a `label:` on `f.radio_button`, which is not an option that helper has, so it rendered as an HTML attribute and named nothing. **The rich text editor had no design system section at all.** The body had been styled to match a text input; the fourteen controls above it had not -- `#bbb` borders, a 3px radius against the app's 8, 42x26 buttons, a `#cbeefa` active state found nowhere else, and **fourteen SVG data-URI icons, a second icon set in an app that retired Font Awesome to have one**. Now 32x32 ghost buttons in a `rounded-lg` slate-300 group, `bg-brand-50` when active, and Bootstrap Icons added as `bi-*` classes by the toolbar controller rather than as CSS codepoints, so the name is the one any view writes. **The phone bug was flex, not width**: below 768px Trix caps the buttons at about 22px, under 2.5.8, and overriding the width did nothing twice because the buttons are flex children and fourteen 32px buttons do not fit a 375px row -- they were *shrinking* to 19px. `flex: none`, and the row was already `overflow-x: auto`. **Two specs pinned the wrong thing**: `find('small[data-...]')` coupled 31 examples to an element name, so the design system's hint `<p>` failed them for no behavioural reason -- the data attribute is the contract, as `[data-flash]` concluded earlier. Labels also moved to sentence case, and four spec files followed. Five new assertions in `page_layout_system_spec.rb`. Verified: **2394** non-system and **696** system examples green, rubocop clean across 665 files, `erb_lint` clean across 425, `shell-first-audit`, `page-audit`, `undefined-classes` and `copy-audit` at zero, `route-sweep.js` clean across 142 screens in three roles, `keyboard-audit.js` clean, and `responsive-audit.js` clean across **429** page/width combinations. |
| `fe949b3e2` | **The icons I added yesterday drew nothing, and a spacing over-correction.** Reported as "weird squares" under the email fields, and that is what they were: **fourteen empty boxes**. Adding the `bi-*` class to the *button* could never work -- Trix sets `content: ""` on `.trix-button--icon::before` at a specificity that outranks `.bi-type-bold::before`. **The spec passed the whole time**: it asserted the class was present and the computed font family was `bootstrap-icons`, both true, and neither is evidence a glyph was painted. Counting painted pixels per button box found **0 of 14**. The glyph is an `<i class="bi-…">` child now -- how design.md says an icon is written -- so the specificity fight disappears rather than being won, and the spec reads computed `content`, rejecting `none` and the empty string. **Third time on this branch a passing assertion has hidden an invisible feature**, after the toastr message below the fold and the frozen-column shadow; the shape is identical each time, checking declared state rather than result. **Radio spacing was over-corrected and is now 24/8**: yesterday took the row to 32px *and* added an 8px gap, on GOV.UK's 40+10 and Material 3's 48dp, and it was too loose. Those are the wrong comparators -- GOV.UK sizes for a full-page public service form, Material for a touch list. **Carbon, Ant Design, Atlassian and Bootstrap 5 all sit at a 24px row with 8px between**, and the row was already exactly WCAG 2.5.8's minimum, so the gap was the only thing missing. **CTA icons audited across 39 screens in three roles**: **27 of 27** page-header CTAs carry one and agree on which -- `bi-plus-lg` create, `bi-upload` import, `bi-download` export. One action button lacked one, the users card's **Invite user**, now `bi-person-plus` to pair with the `bi-person-dash` beside it. Pagination and "View all …" links are deliberately not CTAs and stay iconless. **The settings address was four placeholders** -- Street, City, State and Zipcode named only by `placeholder` and `aria-label`, which vanish on input, each running the full 726px card width. Visible labels now, State and Zip sharing a row. **`<code>` had no styling at all**, so `%{partner_name}` and its three siblings read as a templating bug leaking into the page; they are tinted chips now. **The footer gap went 24px to 48**, via `pb-6` on `<main>` in both shells rather than 31 templates: 24 is the rhythm *between peers*, and the footer rule is chrome. Also **`docs/mockups/request-units.html`**, the preview for the custom request units field -- the shipped select2 hides its dropdown so it looks like a select that opens nothing, its chip remove target measures **9x21** against 2.5.8's 24x24, and its chips are select2's own greys. Three options, A recommended, **decision open**. Verified: **2394** non-system and **698** system examples green, rubocop clean across 665 files, `erb_lint` clean, all four static audits at zero, `route-sweep.js` clean across 142 screens, axe clean, and `responsive-audit.js` clean across **429** page/width combinations. |
| `f8042fd2a` | **A design preview has to be reachable, not merely written.** "I cannot see the Preview" -- the third time, and the first two are already quoted in `docs/mockups/README.md`, which is what makes this one worth recording: **the rule written after the first two was followed and it still failed.** That rule was "write every mockup self-contained so it opens from disk", and `request-units.html` is self-contained, opens by double-clicking and renders with no dev server at all. It was still invisible, because **the reader's browser is not on the machine the repo is on** -- the app runs in a container, and a browser that can reach `localhost:3000` cannot reach a `file:///Users/…` path. No amount of self-containment changes that. The rule is now about delivery rather than about the file: **send a URL, never a path.** New `bin/design/serve-mockup <name>` copies a mockup into `public/`, where Rails serves it ahead of the router, refreshes `mockup.css` for the older ones that link it, warns when the served copy is not gitignored, suggests a name on a typo, and prints the URL. Self-containment is still required for a smaller reason: it stops a preview rendering against a stale stylesheet snapshot, which has already made one mockup lie about a disabled control's colour. **A script rather than another README line, because there was already a README line** -- it said `open docs/mockups/<file>.html`, which is precisely the advice that failed; three occurrences is where the thing being remembered should stop needing to be remembered. `.gitignore` takes a `/public/*-options.html` glob instead of one line per mockup. Verified by rendering the served copy: HTTP 200, Figtree actually loaded rather than fallen back, four option cards, chips at brand-50 `rgb(238,242,255)` against the shipped select2 grey `rgb(228,228,228)`, no failed requests and no JS errors. rubocop clean across 666 files. |\n
| `7adc91e9d` | **Custom request units: option A built.** Chosen from `docs/mockups/request-units.html`. The shipped field was select2 in free-tagging mode with `select2-hide-dropdown-value` -- it looked like a select, so clicking it did nothing, and the screen never said the interaction was "type, then comma". Measured before: the chip remove target **9x21** against WCAG 2.5.8's 24x24, chips in select2's `#aaa` on `#e4e4e4`, used nowhere else here. Now `shared/essentials/tag_input` with `tag_input_controller.js`: Enter commits, comma and Tab still work for anyone with the habit, Backspace on an empty box removes the last chip, and the hint says so. **The `<select multiple>` is still the field** -- the chips are a view of it, the submitted parameter is the same repeated `name[]`, and `OrganizationUpdateService` did not change. Hiding it is gated on `[data-tag-input="ready"]`, the arrangement the table rail already uses, so with JavaScript off the native multi-select is exactly what it was rather than nothing at all. **Two departures from the preview, both named**: duplicates are refused case-insensitively, so `Pack` cannot join `pack` -- the comparison table said A did not do this, which was true as drawn and is a cheap improvement on it -- and the remove button is **24x24** rather than the 20px drawn, so it passes 2.5.8 outright instead of through the spacing exception. **Three findings the audits caught and review would not have**: `undefined-classes.py` reported `tag-input-box`, a class I had put on the box and then styled entirely with utilities on the same element, so it selected and styled nothing; `keyboard-audit.js` reported a click handler on a non-focusable `<div>`, the click-the-padding-to-focus convenience, removed rather than worked around since the input is `flex-1` and already fills the row; and the rule hiding the native select **did nothing at all** while it sat in `@layer components`, because the select carries `block w-full` from `SELECT_CLASSES` and a utility beats a layered rule however specific -- it belongs with the third-party overrides the stylesheet already keeps outside the layer. select2 stays for the five other views that use it. Verified end to end in a browser: added a unit, removed one, saved, and the reload showed exactly the staged values. New `spec/system/request_units_system_spec.rb`, 8 examples, including one that pins the native select as the thing that submits. **2394** non-system and **706** system examples green, rubocop clean across 667 files, `erb_lint` clean, all four static audits at zero, `route-sweep.js` clean across 142 screens, `keyboard-audit.js` clean at 1280 and 375, axe clean, responsive clean. |\n
| `0f87f5605` | **Breadcrumbs everywhere, and ten screens that could be reached but not left.** The reports complaint generalised: every report is listed on the hub, **none is in the sidebar, and none linked back**, so for all five reports plus the by-county report and three trend pages the browser's back button was the only way out. `/events`, `/help` and `/users` were the same -- `/users` is reached from the account menu's "Co-workers", a menu rather than a nav landmark. **The design system had no breadcrumb at all**; `design.md` did not mention the word. It had `back:` on `page_header`, 99 call sites, rendering "Back to X". **The breadcrumb replaces it rather than joining it** -- the first ancestor is the same destination and the trail also says where you are, and shipping both would put two wayfinding devices in the same 8px. **No call site changed**: the parent's name is derived from the label, which is `Back to <noun>` at all 99, verified before relying on it; `breadcrumb:` takes an explicit trail where one is deeper. Structure is the **W3C ARIA APG** pattern, which GOV.UK, Carbon, Material and Bootstrap 5 all implement identically, so the standard is not a judgement call: named `<nav>`, ordered list, ancestors as links, current page plain text with `aria-current="page"`, separator generated and `aria-hidden` because a literal `/` is announced as "slash". 14px, slate-500 trail on slate-700 current, 24px link targets. New **`bin/design/wayfinding-audit.js`** checks the property across 151 screens in three roles, and **got three things wrong first**, each kept in its comments: it judged the requested URL rather than the landed one, so a redirect looked like an orphan; page tabs count as a way out, since `/item_categories` and `/partner_groups` are reached and left through them; and signed-out screens have no chrome for a breadcrumb, so the landing page, the legal documents, the account-request flow and Devise's invitation acceptance are excluded by name. **The reports tables had the class and not the component**: `.data-table` with no `.table-scroll`, so no focusable named region for the arrow keys, no edge shadow, and nothing to scroll when the table outgrows the card -- plus unscoped `<th>` in Title Case using `text-right` rather than the `.numeric` column class. Fixed on all three itemized reports. **Two bugs the audit surfaced**: `partners/authorized_family_members/new` rendered its form *outside* the page wrapper so it had no gutter, and its `page_header` call carried **two `back:` keys** -- a duplicate key in a Ruby hash literal is not an error, the last silently wins, so the first had been doing nothing. Five spec assertions followed the copy: two report titles to sentence case, two back-link labels to their breadcrumb names. New `spec/system/breadcrumb_system_spec.rb`. Verified: **2394** non-system and **712** system examples green, rubocop clean across 667 files, `erb_lint` clean, all four static audits at zero, `wayfinding-audit.js` clean across 151 screens, `route-sweep.js` clean across 142, `keyboard-audit.js` clean, axe clean, responsive clean across **429** page/width combinations. |\n
| `fde77c24d` | **Row action treatment audited across 31 tables; preview built, decision open.** Reported as inconsistent -- two buttons behind a kebab on `/items` while `/barcode_items` shows three inline, and the partner and organization-users tables "especially bad" with actions of different sizes appearing and disappearing. All of it confirmed by measurement. **design.md already settles most of this** (`:ghost` for every row action, three or more collapse into a menu, `size-7` trigger); the rule is applied per *row* rather than per *table*, and says nothing about a column whose action set changes between rows. New **`bin/design/row-actions-audit.js`** reports four shapes and finds **10 of 31 tables** wrong: `3+ inline, no menu` on `/storage_locations`, `/barcode_items` (a **349px** actions column) and `/donation_sites`; `varies row to row` on `/events`, `/partners`, `/partner_groups` and `/organization` -- `/partners` picks its actions from a five-branch `case` on status, so measured widths down one screen were **170, 120, 170, 241, 0, 170px**; `mixed control heights` on `/vendors` and `/requests`, where a labelled 30px ghost button sits beside a 28px kebab; and `menu for 2 or fewer` on `/items`. **The audit counts actions inside a closed menu**, which is what makes it useful: the panel is in the DOM while hidden, and without reading it `/distributions` (three behind the menu, correct) is indistinguishable from `/items` (two, the defect). **`docs/mockups/row-actions.html`** shows the measured state and three options. **A recommended**: keep the existing rule but move the threshold from the row to the table, add that a varying action set is itself a reason to collapse, and match a visible action's height to the kebab's -- 10 tables change rather than B's 22 or C's 26, and the tables whose actions are settled keep one-click access. Nothing applied yet; awaiting a choice. |\n
| `7df1ae6d5` | **Row actions: option A applied across the app, plus one canonical actions header.** design.md already had the rule -- `:ghost` for every row action, three or more collapse, `size-7` trigger -- so most of this was conformance. Four amendments: **the threshold is per table, not per row**; **a varying action set collapses whatever the count**, which is the case that produced the complaint and the rule did not cover; **every control in the column is 28px**, via a new `essentials_row_icon_link` that renders a visible action icon-only, because a labelled `sm` ghost is 30px and the 2px step showed on `/vendors` and `/requests`; and **one actions column header**. That last was asked about directly and was worth asking -- **four variants across 43 tables**: 33 hidden and plural, 8 visible, one `<th>Action` with no `scope` and no alignment, one hidden and singular. Now always `<th scope="col" class="text-right"><span class="sr-only">Actions</span></th>`: hidden because the column holds icon buttons that carry their own names and a visible label widens a 60px column to state the obvious, present because a column with no accessible name is announced as nothing when a screen reader crosses the header row. Carbon and Salesforce both use assistive text here. **Nine tables changed and 10 headers normalised**: `/partners` went from a ragged **279px** -- 170, 120, 170, 241, 0, 170px down one screen -- to a stable **60px**; `/organization`'s users table 288 to **75**; `/donation_sites` 274 to **76**; `/barcode_items` 349 to **275**; `/vendors` and `/requests` now 28px throughout. An action that does not apply is a disabled menu item with the reason as sr-only text rather than an absent control, so "why can I not delete this group?" has an answer on screen. **Two things the measurement got wrong, both kept in the tooling.** `/items` was reported as a menu holding two actions, which the rule says to open up -- but it builds Delete, Deactivate or a disabled Deactivate from item state, and on seed data every row lands in the same branch, so one render cannot tell a settled pair from a varying one. That check is **advisory** now. And `/events`, which has no actions column at all, was reported as ragged because the audit read the last cell of every table; it keys off the actions header now, which is reliable precisely because the header was just made uniform. **And one I got wrong**: I collapsed `/barcode_items` because it showed three inline, but the third was View, which comes out anyway since the row's first cell links to the record -- leaving a settled pair that the rule says stays inline. Reverted. Remove the redundant action before counting. Twelve spec call sites moved to `click_row_action`. Verified: **2394** non-system and **712** system examples green, rubocop clean across 668 files, `erb_lint` clean, all four static audits at zero, `row-actions-audit.js` and `table-audit.js` clean, `route-sweep.js` clean across 142 screens, `wayfinding-audit.js` clean across 151, `keyboard-audit.js` clean, responsive clean across 429. |\n
| `ec866f5d0` | **Preview: the actions column header, and why a disabled action says nothing.** Two follow-ups. **The header** -- industry is split and splits on what the column holds: Salesforce, GOV.UK, Carbon and Atlassian hide it, Ant Design shows it. **A correction to the previous commit**: I justified hiding it partly on width, and it measures **15px** on `/partners` and `/items` and 18px on `/donation_sites` -- not a real cost, and I should not have leaned on it. The recommendation changes to **visible**, because the facts changed: collapsing nine tables turned columns of labelled buttons into a single unlabelled glyph, and a column whose entire visible content is "⋯" is where a header earns its place. **The disabled action** is a defect I introduced: the reason is `sr-only`, so a screen reader hears "unavailable while this item is still in inventory or used by a kit" and a sighted user sees a grey word and nothing else, with no tooltip either. Recommended fix is the reason as **visible help text** under the label -- Polaris's `helpText` -- since a tooltip fires no pointer events on a `disabled` control and does not exist on a phone. `docs/mockups/actions-header-and-disabled.html`; nothing applied yet. |
| `55135e76b` | **A visible actions header, and a disabled action that says why out loud.** Both applied. **The header is visible on all 43 tables** -- `<th scope="col" class="text-right">Actions</th>`. Industry splits on what the column holds: Salesforce, GOV.UK, Carbon and Atlassian hide theirs, Ant Design shows one. **I changed my own recommendation from a commit earlier, because the facts moved**: hidden suits a column of labelled controls, which describes itself, and collapsing nine tables had just turned most of these columns into a single unlabelled "⋯". Also a correction -- I had justified hiding it partly on width, and it measures **15px** on `/partners` and `/items`, 18px on `/donation_sites`. Not a real cost, and leaning on it was sloppy. **The reason an action is unavailable is now visible help text** under the label, Polaris's `helpText`. It was `sr-only`, so a screen reader heard "Deactivate, unavailable while this item is still in inventory or used by a kit" and everyone else saw a greyed-out word and nothing at all -- reported as confusing on `/items`, and a defect the row-actions change introduced. My own comment said it was sr-only "so it reaches a screen reader without needing hover", which was true and silently traded away every sighted user to get there. Rejected: a tooltip (a `disabled` control fires no pointer events, and there is no hover on a phone), not disabling at all (a click and a page load to deliver one sentence), and omitting the action (what made the column ragged). **A contrast trap inside the fix**: `opacity-60` sat on the whole item, so the new sentence painted at **2.32:1**. WCAG 1.4.3 exempts an inactive component and **that exemption is no argument** -- the point of showing a reason is that it is read. The opacity is on the label alone now and the reason is slate-500 at **4.75:1**. The five reasons were reworded into standalone sentences, since they had been phrased to be read after the label. New `spec/system/table_actions_system_spec.rb` pins both, each verified to fail when reverted -- the reason check asserts the *opacity chain above it is empty*, not just that the text exists. Verified: **2394** non-system and **714** system examples green, rubocop clean across 668 files, `erb_lint` clean, all four static audits at zero, `row-actions-audit.js` clean, `route-sweep.js` clean across 142 screens, axe clean, keyboard clean, responsive clean across 429. |\n
| `a2d13e2e2` | **A menu item is not a button, and the confirm dialog nothing could audit.** Three things reported on the items row menu. **The alignment was a bug, now fixed**: `_menu_items` rendered an enabled action through `essentials_action_button`, which applies `inline-flex justify-center` and wraps the form in `form_class: "inline-block"` -- and the actions cell is `text-right`, so the inline-block inherited it and shrink-wrapped. Measured on `/vendors`: *Edit* at **x=1 across 222px**, *Deactivate* at **x=117, 106px wide**, in one 224px menu. Every enabled action in every row menu looked like that. A plain `button_to` with the item's own classes now, keeping `data-turbo=false`; all nine menus report identical lefts, widths and glyph positions. The rule is in design.md: **reaching for the button helper because a thing is clickable imports layout decisions made for a different context.** **The native confirm is confirmed** -- all **44** `confirm:` call sites render `window.confirm`, browser chrome that announces the page's hostname. **Why three audits missed it is three separate reasons**: `overlay-audit.js` exists specifically to open dialogs and finds them with `[data-action*='dialog#open']`, but a native confirm **is not in the DOM**, so the audit built for this class of bug cannot see this instance; axe scans the document and has nothing to scan; and **the system suite depends on it**, because Capybara's `accept_confirm` only drives a native dialog -- a green suite is evidence *for* the browser dialog. Third time on this branch, after the toastr message below the fold and the frozen-column shadow that drew nothing. The check that finds it is not a DOM query but a listener on the browser's `dialog` event; added to `overlay-audit.js`, reporting **2**. **Converting the 44 is not folded in** -- every `accept_confirm` becomes a click on a real button, which is its own change. `docs/mockups/row-menu-followups.html` previews that and the disabled-action question, where the honest note is that much of the "odd" was the alignment bug, so it should be judged against the fixed menu. Verified: **2394** non-system and **714** system examples green, rubocop clean across 669 files, `erb_lint` clean, `row-actions-audit.js` clean, `overlay-audit.js` clean on 8 dialogs and 102 popovers. |\n
| `670d7f7e6` | **Option B, and the app's own confirmation dialog.** **An action that will fail is now offered**, and the server answers with the reason *and the next step* -- after two worse shapes: omitting it made the column ragged and answered nothing, and disabling it with an `sr-only` reason told screen readers and nobody else. Making that reason visible fixed the silence but not the shape: a line under a label holds a phrase, and what someone needs is what to do. The three messages were rewritten from log lines into sentences -- `Cannot deactivate item - it is in a storage location or kit!` became *"Adult Briefs still has stock in a storage location, or belongs to a kit. Move or distribute the remaining stock and remove it from any kits, then deactivate it."* -- each naming the record, the reason and the next step. **One exception kept**: your own row on the organization's users table stays disabled, because the action is unavailable for *who you are* rather than the record's state, so there is no request to make and nothing for a flash to answer. That is the line -- disable only when there is no attempt to send. **The confirmation is the app's `<dialog>` now**, all **44** call sites, none of which changed. It **intercepts the click in the capture phase and replays it**, because rails-ujs's confirm hook is *synchronous* and a `<dialog>` is not -- there is no way to answer synchronously from one. Two things found the hard way: `stopImmediatePropagation` rather than just `preventDefault`, since rails-ujs binds on `document` and would otherwise raise its own confirm on top; and the replay must **remove `data-confirm` from the element**, because marking it already-answered was not enough and the first attempt fired the native dialog on the replay while the action never completed. The dialog names the action on its button -- *Delete*, not "Continue" -- and reddens it for a destructive variant, both derived from the control's tone. **One place could not use the attribute**: `utils/donations.js` guards a large donation from inside its own click handler with the only raw `confirm()` in the app, invisible to any attribute-based fix; it takes a promise API and the handler was restructured to prevent, ask, then `requestSubmit`. **35 spec call sites** moved off Capybara's `accept_confirm`, which only drives a native dialog -- and two things surfaced: `page.find` inside a `within` block is still scoped to the block, so the helper needs `page.document`; and several specs were relying on Capybara *auto-accepting* an unhandled native confirm, so they passed while never confirming anything. `overlay-audit.js` reported 2 native confirms before and reports **0**. Verified: **2394** non-system and **716** system examples green, rubocop clean across 670 files, `erb_lint` clean, `undefined-classes` and `copy-audit` at zero, `row-actions-audit.js` clean, `route-sweep.js` clean, `keyboard-audit.js` clean. |\n
| `ef062982a` | **Do not confirm what cannot happen.** A mistake in how I first built option B: every branch of the three converted actions kept its `confirm:`, including the branch that **cannot succeed**. So deactivating an item still held in stock went click, confirm *"are you sure you want to deactivate this?"*, and only then read that it was never possible -- **two steps to a dead end, the second asking you to affirm something that will not occur.** The rule, now in design.md: a confirmation guards a destructive act that is *about to happen*, so where nothing is about to happen there is nothing to guard. The `confirm:` stays on the branch that can succeed and is omitted from the one that cannot -- same button, same label, one asks and one goes straight through. Verified in a browser: an item that cannot be deactivated shows **no dialog** and the flash arrives on the first click; a vendor that can be deleted still confirms. **Why I got it wrong is the part worth keeping**: converting from "disabled" to "offered" I carried over every attribute the working branch had, because they looked like the same action -- and they are not, one destroys something and one is going to be refused. A branch that exists *because* an action is impossible should be read as its own case, not as a copy of the possible one with the disabling removed. Two specs updated. Verified: **2394** non-system and **716** system examples green, rubocop clean across 670 files, `erb_lint` clean, `overlay-audit.js` reporting 0 native confirms and no findings. |\n
| `ce7354939` | **One destination, one place in the navigation.** Asked why "Organization" is in the sidebar footer *and* the account menu. Measured: both link `organization_path`, both behind the identical `can_administrate?` gate -- same link, same audience, two places. The **only** duplicated destination across 22 sidebar entries and 3 menu entries. **The standard is clear on one half and split on the other.** Near-universal: an avatar menu is for the *person* -- Slack, GitHub, Linear, Notion, Stripe, Atlassian and Shopify all keep workspace or organization settings out of it. Split: where those settings live, either pinned to the foot of the sidebar (Shopify, most admin tools) or under the workspace name where it doubles as a switcher (Slack, Notion, Linear). This app already does the first and its sidebar header already shows the organization's name, so the footer entry stays and the menu entry goes. **`wayfinding-audit.js` checks for it now**, and why nothing caught it is the useful part: every check the app has asks whether a page can be *reached*; none asked whether it can be reached **twice**, and neither entry was wrong alone. Verified to fail when the duplicate is put back. **The mirror-image finding, in the same menu**: "Co-workers" pointed at `/users` gated on `can_administrate?` **and** `has_cached_role?(:partner)` -- and a bank admin has no partner role, so **it rendered for nobody**, confirmed against the seeded admin. That way since the shell was built (`6a01113ea`), and it reads as a gate copied from the partner top bar. **Removed rather than repaired**, on the same principle: `/users` shows *name and email*, where the organization page's table shows those plus role, last sign in, status, reinvite and the actions -- a strictly weaker view of a list one click away, so fixing the gate would have added a second users page rather than restored a missing one. **Said plainly: `/users` now has no inbound link and is not deleted** -- deleting a page is a decision to take deliberately, not a side effect of tidying a menu, and it is written down so it is not rediscovered as a mystery. Verified: **2394** non-system and **716** system examples green, rubocop clean across 670 files, `erb_lint` clean, `route-sweep.js` clean, `wayfinding-audit.js` clean across 151 screens. |\n
| `e3e12881d` | **A warning that arrives after the decision is not a warning.** Asked what triggered the callout on `/kits/new` and why it sat at the bottom. **Nothing triggers it** -- it is unconditional on that form, and the form is new-only (`resources :kits, except: %i[edit update destroy]`), so its claim is true and design.md even cites this exact case. The content was right; the **placement** was wrong, and there was no placement rule to be wrong against. Measured: **y=922 on a 720px viewport**, 765px below the `h1`, under both cards -- you had to scroll past the thing you were composing to be told composing it was final. Same shape as the toastr message earlier on this branch: correct content delivered where nobody looks. Now **y=205**, 48px under the heading. **The rule is scope, not position**: a callout about the whole task goes under the page header, one about a section sits with that section. Audited all **26** callouts -- four sat below a card and only **one** was a defect. The other three are section-scoped: two are hidden until a checkbox reveals them and sit directly above the fields they describe, the third follows the sentence it qualifies on a 17-line page. Written as "callouts go at the top" the rule would have moved three correct ones. **The copy also leaked an implementation detail**: "changed later via the kit's item" is accurate -- `Kit < Item` by STI, and `/items/:id/edit` is the screen -- and accurate in a vocabulary the user has no access to. It names *Items & inventory* now, in the sidebar's own words, and links there; verified the link resolves and that a kit does appear in the items index. Verified: **2394** non-system and **716** system examples green, rubocop clean across 670 files, `erb_lint` clean, `copy-audit` and `undefined-classes` at zero, responsive and axe clean on the page. |\n
| `7d12647dd` | **`/users` deleted as redundant.** It listed *name and email*; the organization page's table shows those plus role, last sign in, status, reinvite and the row actions -- a strictly weaker view of a list one click away, and by then reachable from nothing. Removed: the `:index` route, `UsersController#index`, `users/index.html.erb`, and `users/shared/_account_management_menu.html.erb`, which was rendered by no one and linked to both helpers so it would have broken anyway. `/users/new` **stays** -- the dashboard's getting-started prompt links to it -- with its back link now pointing at the organization page. **Deleting the route broke a form on a different page**, which is the part worth keeping: `users/new.html.erb` called `essentials_form_for(@user)` with no URL, Rails infers one from the model, and for a `User` that is `users_path` -- a helper that existed *only* because `resources :users` declared `:index`. The page 500'd with `undefined method 'users_path'` and its request spec caught it. The URL is explicit now; `user_registration_path` is the same `/users`, so nothing about the behaviour changed and the dependency is visible instead of incidental. **A `form_for` with no `url:` is coupled to a route you cannot see from the template**, and deleting an apparently unused index is exactly when that bites. **A finding underneath it, deliberately not fixed**: `POST /users` resolves to `devise_invitable/registrations#create` and there is no `UsersController#create` -- so *Add other users at your bank* submits to Devise's **registration** create, not to any bank-side action, while the organization page's *Invite user* posts to `invite_user_organization_path`. Whether `/users/new` should exist given that is a real question and not one to answer as a side effect of deleting a list. Verified: **2391** non-system and **714** system examples green, rubocop clean across 670 files, `erb_lint` clean, `dead-routes.rb` 0 dead and 0 shadowed, `wayfinding-audit.js` clean across 150 screens, `route-sweep.js` clean across 141. |\n
| `f093ab425` | **`/users/new` adds a user now, which it never did.** The finding from the previous commit, fixed -- and it was worse than "posts to the wrong action": **the form did nothing at all.** It asked for name, email, password and confirmation with **no `UsersController#create` behind it**; `essentials_form_for(@user)` inferred `users_path`, `POST /users` resolves to `devise_invitable/registrations#create`, and for an already-signed-in admin -- the only person who can reach the page -- that answers *"You are already signed in."* and bounces to the dashboard. Confirmed by reverting the fix and reading the response: the dashboard, that sentence, no user created. The one link to it is the getting-started prompt's **"Add other users at your bank"**, so a step the app suggests to a brand-new bank was a dead end. **Now an invitation through the existing action.** `UserInviteService.invite` is what this app means by adding a user, and the evidence is in the domain rather than in taste: the users table has an `invitation_status` column and a *Reinvite* row action, and `resend_user_invitation` exists -- a directly-created account with an admin-chosen password would have neither. **Posted to `invite_user_organization_path` rather than a new `UsersController#create`**: a second action calling the same service is the duplication this branch has spent the week removing; two entry points into one code path is not. That is also why it is a `form_tag` with flat `name`, `email` and `org` params rather than `form_for @user`. **The password fields are gone**, which is a behaviour change worth stating rather than assuming: an admin can no longer set someone's initial password here. They never could, because the form did not work, and the invitee sets their own exactly as the organization page's modal has always done. Verified end to end in a browser -- invited, redirected to `/organization`, flash *User invited to organization!*, the person in the table with `org_user@Organization#1` and the invitation pending. New system spec, verified to fail when the form is pointed back at `user_registration_path`. Verified: **2391** non-system and **715** system examples green, rubocop clean across 670 files, `erb_lint` clean, `shell-first-audit`, `page-audit` and `copy-audit` at zero, `wayfinding-audit.js` clean. |\n
| `b6b471ee3` | **The barcode form gets the camera scanner it already had.** `/barcode_items/new` and `/edit` asked you to type a barcode by hand -- the one thing a barcode exists to avoid. **The scanner was already built and already loaded**: quagga is pinned, `utils/barcode_scan` is imported by `application.js` on every page, and the glyph appears on the line-item tables and both barcode modals. It had simply never been put on the form for *creating* a barcode. No new dependency and no new JavaScript -- the modal's markup, unchanged. **Copied the region, not just the button**, which is the point: the scanner resolves its input and viewport by walking up to `[data-barcode-scan]`, so a button pasted on its own is inert. There is deliberately no id -- three partials once carried `id="barcode-scanner-btn"` and a donation form renders two of them, so pressing the dialog's button drew the camera inside the scan bar's button. **Verified with a fake camera** rather than assumed: Chromium with `--use-fake-device-for-media-stream`, viewport hidden to a **612x459** `<video>`, `aria-expanded` flipping to `true`, then hidden and emptied on a second click, no console errors. **A measurement mistake worth keeping**: the first probe reported the viewport still hidden after the camera started, and it was not -- the check was `className.includes("hidden")` and the class list contains `[&_canvas]:hidden`, a Tailwind arbitrary variant. `classList.contains` is the correct test, and **substring matching against a Tailwind class attribute is unsafe** now that arbitrary variants embed utility names inside other names. New spec asserts the wiring rather than driving the camera, verified to fail when the region attribute is renamed. Verified: **2391** non-system and **715** system examples green, rubocop clean across 670 files, `erb_lint` clean, `undefined-classes` and `shell-first-audit` at zero, axe and responsive clean on the page. |\n
| `2765a2cc5` | **Preview: the barcode scan field should be joined, not an overlay.** Two criticisms, both confirmed. **The design system already settles it** -- `design.md` says the scan field and its button are *joined*, one rectangle sharing a border, "which is what keeps them the same height by construction; as separate boxes they had drifted to 38px and 42px". The inventory audit's scan bar does that; I matched the barcode modal's overlay instead. **And the overlay is broken**: measured on `/barcode_items/new`, a **38px** field against a **36px** button that `absolute right-2 top-8` puts **4px below** the field's bottom edge, not centred -- the offset is tuned to one label height and cannot survive being moved to a form with different spacing. **I copied the bug rather than inventing it**: both barcode modals measure the same 38/36 with the same 4px spill. Three of the four scan regions use the overlay; only `line_items/_line_item_table` is joined. `docs/mockups/barcode-scan-field.html`; nothing applied yet. |
| `69db1e060` | **The barcode scan field is joined now, and there is one of it.** Two criticisms, both right, and the second explains the first. **I matched the wrong existing thing**: there were two renderings in the app -- the line item table's, used by the inventory audit, donations, purchases and distributions; and the barcode modals'. I copied the modal. `design.md` had already settled which was correct, in the line items section: *the scan field and its button are joined, one rounded rectangle sharing a border, "which is what keeps them the same height by construction; as separate boxes they had drifted to 38px and 42px"*. **And the one I copied was broken in exactly the way that rule predicts**: `absolute right-2 top-8` over a `pr-10` field gave a **38px** field, a **36px** button, **4px below** the field's bottom edge, not centred, with a 28x36 tap target -- an offset tuned to one form's label height, so it broke the moment it was pasted onto a form with different spacing. Three of four scan regions had it. **Extracted rather than fixed in place**, because three identical copies is how two renderings came to exist and fixing three copies leaves three copies: it is `shared/essentials/_barcode_scan_field` now. Measured against the audit's bar afterwards the two are **identical** -- input `1px` on four sides, button `1px` with `border-left: 0`, **0px** seam, both 38px, target 38x38. **Hand-rolled rather than `f.input`, and the cost is named in the file**: simple_form stacks label, input and error as three blocks and the button must sit inside the row, so the wrapper cannot be used and everything it supplies -- label, `field-error` paragraph, `aria-invalid`, `aria-describedby` -- is reproduced by hand, which means a change to the `:essentials` wrapper will not reach it. **Why it is still not identical to the audit's, and should not be**: the pattern and geometry are, the words are not, because scanning on the audit is a *lookup* that adds a row while scanning here is *data entry* that fills the field being saved. **A leftover the audits caught**: `form-validation-audit.js` still opened its "Invite a new user" check at `/users`, deleted earlier today; it points at `/organization` now. Verified: **2391** non-system and **717** system examples green, rubocop clean across 670 files, `erb_lint` clean, `undefined-classes` at zero, axe clean, responsive clean, `form-validation-audit.js` back to no findings. |\n
| `622d4023f` | **A camera that would not start said nothing.** Reported as "clicking the button does not trigger the camera" -- and it was not the wiring: with a fake camera the viewport opens and a 612x459 `<video>` appears. The failure was in a path the test never took. Quagga's init callback did `console.log(err); stop()`, and **`stop()` hides the viewport** -- so on any failure the panel opened and shut within a frame, `aria-expanded` went back to `false`, and the only record was in the console. From the outside, a button that does nothing. **Both real causes reproduced in Chromium** rather than reasoned about: no camera device (`NotFoundError`) and blocked permission (`NotSupportedError`), each ending with the viewport hidden and empty. Each failure now writes a sentence where the picture would have been, and each says what to **do** rather than naming the exception -- `NotReadableError` teaches a reader nothing; *"the camera is in use by another application"* tells them to close Zoom. **The insecure-origin case is separated and is the one to expect in development**: browsers expose `navigator.mediaDevices` only on `https` or `localhost`, so a port forward or tunnel on plain `http` removes the camera API entirely. That branch existed but said *"this browser will not give the page a camera"*, which points at the wrong thing -- it is the address, not the browser -- so it branches on `window.isSecureContext` now. **The shape this branch keeps meeting**: a failure handled only by `console.log` is a failure the user experiences as nothing happening, and the branch three lines above already had a message for exactly that reason. Pinned by a system spec that exercises the real failing path, since the test browser has no camera, and verified to fail against the old version. Verified: **2391** non-system and **718** system examples green, rubocop clean across 670 files, `erb_lint` clean. |\n
| `9ff4ba9b9` | **A purchase can start a distribution, and can be printed.** Reported as a missing CTA on the purchase page. **It was not missing -- it had never existed**, which is worth separating from a regression before fixing anything: checked against `origin/main`, the pre-migration page carried exactly *Make a correction* and a delete button, both still present, and no spec expected the distribution one. **And it could not have been added as a link alone**: `copy_line_items` hardcoded `itemizable_type: "Donation"` and `distributions#new` understood only `request_id` and `donation_id`, so a `purchase_id` would have been read by nothing and opened an empty form -- the version that looks right and is wrong. **Generalised rather than duplicated**: `copy_line_items(itemizable_id, itemizable_type)` takes the type, defaulting to `"Donation"` so the existing caller is untouched, with `copy_from_purchase` beside `copy_from_donation`. A spec asserts the query is made with `itemizable_type: "Purchase"`, because getting that wrong fails silently -- a donation and a purchase can share an id. **The print gap needed a document, not a route**: `PurchasePdf` is deliberately the same shape as `DonationPdf`, and honours the same `hide_value_columns_on_receipt` setting, with *Purchased from* and *Amount spent* where the donation says *Donation from* and *Money Raised*. **Verified end to end**: clicking through on purchase 21 lands on `/distributions/new?purchase_id=21&storage_location_id=1` with *Kids (Preemie)* x **976** pre-filled -- matching the purchase exactly -- and the storage location set; `/purchases/21/print.pdf` returns 200, `application/pdf`, **30,024 bytes** beginning `%PDF-1.4`. **Named and not done**: `PurchasePdf` duplicates ~110 lines of layout from `DonationPdf`; extracting a shared base is the obvious follow-up and not this change, since the two have never diverged and a premature base class would have to guess what is common. Verified: **2395** non-system and **718** system examples green, rubocop clean across 671 files, `erb_lint` clean, `dead-routes.rb` 0 dead and 0 shadowed, `route-sweep.js` clean across 141 screens. |\n
| `c8eed479e` | **Render the state, do not correct it.** Reported as "a strange ghost button that appears for a second when you click refresh" on `/distributions/new`. It was the **shipping cost** field: the server rendered it visible and `distribution_delivery_controller` hides it on `connect()` unless the delivery method is `shipped` -- which a new distribution never is -- so on every load it was drawn, painted and removed, visible for exactly as long as Stimulus took to boot. **The rule, now general in design.md**: the server renders the correct initial state and JavaScript may reveal but never un-draw. `[data-railed]` and `[data-tag-input="ready"]` already worked this way; this states it for the app rather than leaving two local precedents. **The audit is the deliverable more than the fix**: new `bin/design/flash-of-hidden-audit.js` loads each page at `waitUntil: "commit"` -- before scripts run -- lists what is visible, lists it again once settled, and reports the difference. It found a second instance immediately, in the reminder day fields on `/manage/edit`, which I had rebuilt myself two days earlier and not noticed. **And my first fix was wrong in an instructive way**: I defaulted the unset schedule to `day_of_month`, reasoning it is the first radio -- but with nothing set *neither* radio is checked and the controller hides *both*, so the "correct initial state" put the field back for a frame and the audit still reported it. The server's guess has to match what the controller actually does, **including the case where it does nothing**; `nil` matching neither branch is the answer. `<select>` is excluded from the audit, since select2 *replaces* one with its own container -- a swap, not a hide. Both toggles verified still working: shipping cost appears on *Shipped* and hides again, the deadline fields appear on choosing a schedule. Verified: **2395** non-system and **718** system examples green, rubocop clean across 671 files, `erb_lint` clean, and the audit reports nothing painted and then hidden. |\n
| `2d6250d9b` | **A conditionally revealed field goes under the answer that reveals it.** Reported on `/distributions/new`: "the location and size of the shipping cost field does not make any sense... shouldn't it be below the shipping cost radio button?" **Measured at 1440px**: every field on the card is **346px** on a three column grid at x = 309/675/1041, while shipping cost opened a *second*, two column grid -- **529px**, left edge at **x = 858** on no column line, and its label at y = 503 against the *Shipped* radio at y = 597, so the field sat **94px above its own trigger**. Three faults: wrong width, aligned to nothing, cause below effect -- and for the two options that are not Shipped, including the default, the right half of the band was empty. **Industry**: GOV.UK, NHS and USWDS all put the revealed content below the triggering radio, indented, with a left rule; Carbon, Material and Polaris place dependent fields after their trigger in reading order. **None of the five uses a parallel column.** Three options previewed (`docs/mockups/shipping-cost-reveal.html`), reveal-under-trigger chosen. New `shared/essentials/conditional_reveal`, and **the whole app moved onto it** -- 6 reveals that had each been built their own way: the distribution grid column, a bare `pl-5` on the partner group form, and nothing at all on three others. **The numbers are derived, not copied**: GOV.UK's 18/4/33 is sized to a 40px radio, ours is 16px with a `gap-2`, so `ml-1.5` (6px = 16/2 - 4/2) centres the rule under the radio and `pl-3.5` lands the field at 24px -- the label's own left edge, verified at x = 333 for both. **`aria-expanded` measured rather than assumed**: axe reports `aria-allowed-attr` x3 when it is added to the radios (ARIA 1.2 does not allow it on `role=radio`); `aria-controls` alone is clean, so that is what every trigger carries. Two exemptions, read from `data-conditional-reveal` rather than guessed: a **table cell** (its column *is* the relationship) and a **callout** (already carries its own box). **The audit found the real bug**: the reminder note on the partner form passed its Stimulus target to the callout as `data:`, which the partial splatted at the top level, so it rendered as a literal `checkbox_with_nested_element_target` attribute and Stimulus threw `Missing target element` on connect *and on every click* -- that callout had never once appeared. Also fixed `item_units_controller`, which set `style.display = 'inline'`, flashing on load *and* overriding the `block w-full` every other select has. New `bin/design/disclosure-audit.js` (**10 reveals, 0 defects**; verified to report 9 when the marking is removed) and `spec/system/conditional_reveal_system_spec.rb` (**9 examples**, verified to fail 4 when reverted). Verified: **1468** non-system and **1654** system/request examples green, rubocop clean across 672 files, `erb_lint` clean across 428, and axe reports **0** WCAG A/AA violations on all five affected pages. |\n
| `e81f8f4f3` | **The actions column is frozen to the right edge, and pays for its width in icons.** Reported: "having the action all the way at the end of a horizontal scroll for a user who is processing multiple rows is a very frustrating experience." **Measured**: at 1440 five of sixteen tables scroll and at 1024 thirteen do; on `/distributions` the Actions header started **327px past** the right edge at 1440 needing **402px** of scrolling, and **818px** at 1024. It did not stay scrolled either -- acting on a row reloads and a reload puts `scrollLeft` back to **0** (402 -> 0 measured), so a page of 15 rows cost **402 x 15 = 6,030px** of dragging, redone after every action. Keyboard users never had this: one Tab reaches the menu and the browser scrolls it into view, so it was the pointer that paid. **0px off screen now, at every viewport.** Four options previewed (`docs/mockups/row-actions-reach.html`); pinning chosen, as Ant Design, AG Grid, Material React Table, Salesforce and Excel all ship. `.cell-actions` on 43 tables' `<th>` and `<td>`; **sticky is inert without overflow**, so the eleven tables that fit are untouched, and the separator is drawn only while something is behind the column. **`/kits` became a menu** -- it branched on `kit.active` for Deactivate-or-Reactivate, the varying-set case design.md already required collapsing, and was the widest scrolling actions column at **273px**; its unavailable Deactivate is now *offered* and answered by the controller rather than greyed out, matching `/items`. **Inline actions became 28px icons** at 55 call sites across 30 files: a labelled pair was **168-273px** and is now a uniform **94px**, narrower than three of the five kebab columns, at no extra click -- the alternative, collapsing settled pairs into menus, would have hidden a one-click action behind two forever. **New `tooltip_controller`**: `title` is browser chrome, silent on keyboard focus, and fails WCAG 1.4.13 three ways, so every icon carries `data-tooltip` and no `title`, and the bubble is `aria-hidden` because `aria-label` already names the control. **The bug this uncovered is the reusable part**: making the cell `position: sticky` trapped the row menu, because `position: fixed` escapes an ancestor's overflow but **not its stacking context** -- measured in test, the rail spanned y=417-441, the menu item's centre was y=423, and `elementFromPoint` returned `.table-rail-track`. An open `fixed` panel is moved to `<body>` and put back on close, the same move `table_scroll_controller` already makes for the rail; trigger and panel gained `aria-controls`/`id` to stay paired. `Capybara.enable_aria_label` is now on, because "Delete" *is* what that control is called. Also fixed: **`admin/base_items` had four headers against three cells**, "Child Items" written twice, so its actions sat under the wrong heading. New `bin/design/tooltip-audit.js` (**364 controls, 301 icon-only, 0 defects**) and `spec/system/row_actions_reach_system_spec.rb` (**8 examples**). Verified: **1468** non-system and **1663** system/request examples green, rubocop clean across 673 files, `erb_lint` clean, and the overlay, keyboard, WCAG, row-actions and tooltip audits all report no findings. |\n
| `c17635dec` | **Select rows, act on them together.** The second half of the row-actions complaint: freezing the actions column removed the *travel*, and this removes the *repetition*. New `table_selection_controller` with `shared/essentials/selection_bar` and `selection_cell`, in the shape of Carbon's `TableBatchActions` -- the pattern Gmail, GitHub, Linear, Jira and Airtable all use. **On `/requests` only, deliberately**: `PicklistsPdf` already takes a collection, so printing several picklists is a real operation and exactly the case that used to mean opening each row's menu in turn. Everywhere else the row actions are per-record and cannot be batched, and **a checkbox column that leads nowhere is a column of noise** -- the component is ready for the next table that earns one. New `requests#print_picklists`, scoped through `current_organization.requests` so a guessed id from another bank selects nothing (asserted, not assumed). **The selection column is frozen with the identifier** at `left: 0`, with `--select-width` pushing `.pin-col` clear, which is Ant Design's and AG Grid's arrangement: a checkbox you must scroll back to find is no better than an action you must scroll forward to reach. **Shift-click extends a range, and binding it was a real bug**: Stimulus's default event for a checkbox is `change`, which **carries no `shiftKey`**, so the first version selected the two ends and nothing between -- measured as "2 selected" where 4 was meant. `indeterminate` on the header box is a *property*, so only JavaScript can set it; Escape clears; the count is `aria-live="polite"`; the bar is server-rendered `hidden` and revealed. A batch action is an ordinary link with the ids on its query string -- no fetch, no form, and it opens in a new tab if asked. New `spec/system/table_selection_system_spec.rb` (**6 examples**) and `spec/requests/request_picklists_requests_spec.rb` (**3**). Verified: **1468** non-system and **1672** system/request examples green, rubocop clean across 675 files, `erb_lint` clean, axe reports **0** violations on `/requests` both with and without the bar showing, and the flash-of-hidden, keyboard, tooltip and row-actions audits all report no findings. |\n
| `5632fb1a9` | **A tab is a place, so the strip does not move.** Reported on Partner agencies: "the group tab does not have a filter so the card jumps up and down" and "when the user clicks on groups, it automatically collapses the side nav." **Measured**: the tab strip landed at **y=228** on a tab with filters and **y=174** on one without -- a **54px jump** on every switch, across two tab sets -- because the filter bar sat *above* the card holding the strip. New `in_card: true` on `filter_bar` puts it inside the card under the strip, with the results frame around **the table alone**, so the strip holds its height and applying a filter cannot re-render it with whichever tab the server thought was current. That is what GitHub, Jira, Linear, Notion and the Ant, Material and Carbon tab components all do: **the tablist is chrome, and what varies goes in the panel**. Five pages moved (`/partners`, `/items`, `/items/quantity_and_location`, `/items/inventory`, `/kits`) and `storage_locations/show`, which had been built this way by hand, now uses the option -- one definition rather than six copies of a class string. **Rejected**: a filter bar on every tab for symmetry (Groups has **2 rows** and Item categories **3**; a filter over three rows is furniture every reader pays for) and reserving 54px of blank space (paying the cost permanently to hide the symptom). **The sidebar half was a bug**: the rail marks its entry and keeps its section open from the current *controller*, and `active_on` named only the first tab's -- so `/partner_groups` and `/item_categories` had **nothing** active and the whole section shut underneath the reader. Every tab's controller is listed now; GitHub, GitLab, Jira and Linear all behave this way. New `bin/design/tab-set-audit.js` checks both invariants (**7 tabs across 3 sets, no findings**), verified to fail on each: reverting `active_on` gives 4 findings, and moving one filter bar back above its card reports "the strip moves by 54px across this set". Neither was visible to any existing audit -- wayfinding asks whether a page can be *left*, not whether arriving moves it. New `spec/system/tab_set_system_spec.rb` (**5 examples**). Verified: **1468** non-system and **1677** system/request examples green, rubocop clean across 676 files, `erb_lint` clean, and the wayfinding and flash-of-hidden audits still report no findings. |\n
| `a86426a2e` | **Audited the app for layout shift, and fixed the two worst.** New `bin/design/layout-shift-audit.js` reads Chrome's own `layout-shift` performance entries -- the ones CLS is scored from, **0.1 good, 0.25 poor** -- across **147 screens**, naming what moved. Shifts the reader caused are excluded by the browser; the dev-only profiler and Bullet badges are filtered out. **Found the three historical trend charts at CLS 0.352**, the worst in the app: the Highcharts container was an empty div until the chart inflated it to **850px** on `connect()`, throwing the buttons and the whole table card down the page a moment after they were readable. The height is now reserved from the same number the chart draws at. **And the donation form's four source selects**, all rendered and three hidden on load, worth **100px** of reflow -- the "render the state, do not correct it" rule broken in a file that predates it. **The interesting part is why the flash audit missed the second**: it excused every `<select>` for select2's sake, an exclusion too broad by exactly the amount that hid four real cases. It now recognises the *actual* swap (`select2-hidden-accessible`, a `.select2-container` sibling, a tag input), and reverting the donation form makes it report those four and nothing else. **A third finding is reported and not fixed**: at 390px, six screens are POOR (`/admin/base_items` **0.658** down to `/broadcast_announcements` 0.290) because `table_stack_controller` restacks tables into cards after paint. Measured across four pages and twelve widths, the container width is a pure function of the viewport -- stacks at <=640, does not at >=700 -- so the threshold *is* expressible as a media query, and the reason recorded for using JavaScript was about `@container` rather than `@media`. Left alone because a complete fix also needs the 299 column labels rendered server-side, which is a decision worth making deliberately. New `spec/system/layout_shift_system_spec.rb` (**4 examples**). Verified: **1468** non-system and **1677** system/request examples green, rubocop clean across 676 files, `erb_lint` clean, and the flash-of-hidden audit reports nothing painted and then hidden. |\n
| `ecfadf38f` | **Table stacking becomes a media query, and the last POOR layout shifts go.** The third finding of the layout-shift audit: at 390px six screens were past Chrome's "poor" threshold -- `/admin/base_items` at **CLS 0.658**, `/admin/partners` 0.616, `/admin/users` 0.512 -- because `table_stack_controller` measured the container, wrote `data-stack`, and the browser rebuilt a *painted* table into cards. It is `@media (max-width: 689px)` and `(max-width: 449px)` now, applied before first paint. **The recorded reason for using JavaScript was an argument against `@container`** (`contain: layout` would break the fixed row-action menus) and never applied to `@media`; the question had not been re-asked. **The translation is measured, not estimated**: across four pages and twelve widths the container is the viewport less 34px, and a 1px scan put the transitions at **450** and **690**, so the old card-width thresholds are reproduced to the pixel and a spec asserts all four boundaries. **Two failed attempts, both informative**: leaving the labels above their values put back half the shift, because they are inserted by JavaScript (299 headings across 71 views) and added a line per field after paint -- **0.163**; and gridding only the cells that *had* a label was worse, since the value had full width until the label landed and then got narrowed and wrapped. **Every field is gridded whether or not its label has arrived**, so the value's width and the row's height never change; the label is `nowrap` for the same reason. Label-beside-value is also how a record's `<dl>` already reads. **It exposed a defect in the day's selection column**: `/requests` measured **0.312** because the stacking controller marks any cell whose heading has no text as the *actions* cell, and a selection heading is a checkbox -- excluded explicitly now, with a real title line of checkbox, title, actions. **And the responsive audit caught a second**: those checkboxes were 16x16 against WCAG 2.5.8's 24px floor, 16 per page at every width, because a control plus its `<label>` is one target and these had only an `aria-label`. They get a 24x24 label wrapping the box with an `sr-only` name. **Result: 0.658 -> 0.068 at 390px and 0.007 at 1400** -- every screen inside Chrome's "good" threshold at both widths. Verified: **1468** non-system and **1682** system/request examples green, rubocop clean across 677 files, `erb_lint` clean, and the responsive audit clean across **1,562** page/width combinations. |\n
| `d51657774` | **The selection bar replaces the toolbar; the totals button joins the filter row.** Two reports on `/requests`, one change. The bar was "the blue background and no padding": `brand-50` with a **16px radius** and no side margin, so a rounded tinted box sat hard against the card's edges -- and it **pushed the table down 68px on every tick**. And "Show product totals" had a **63px** card header band, rule and all, for one 30px button. **Three bars previewed** (`docs/mockups/selection-bar-and-totals.html`), all replacing the table's toolbar rather than adding a row: Carbon's `TableBatchActions`, Material's contextual toolbar, GitHub and Gmail -- **three of the four keep it in the toolbar, because an inserted row moves the table and a replaced one does not.** Brand tint chosen over neutral (a bar you can miss is a bar you do not use) and over Carbon's inverse (this app has no other inverse surface). **Then "is the helper row necessary?" removed the last of the design**: nothing in Carbon, Gmail, GitHub or Material tells you a checkbox can be ticked, so there is no idle band at all -- the **filter row is the toolbar**, the bar replaces it, and the totals button sits on it. Covering the filters while a selection is live is also correct rather than merely tidy: filtering with rows selected is ambiguous, and Carbon puts the filters out of reach for the same reason. New `actions:` slot on `filter_bar` for a control belonging to *this table*; that row had **1,011px** of empty space at 1440, and the totals are "across every request matching the current filters". Measured after: the table head sits at **y=228 whether the toolbar or the bar is showing**, and **63px higher** than before. Two new examples in `spec/system/table_selection_system_spec.rb` (**8** total). Verified: **1468** non-system and **1684** system/request examples green, rubocop clean across 677 files, `erb_lint` clean, and the layout-shift audit reports every screen inside Chrome's "good" threshold, worst **0.011**. One pre-existing order dependency found on the way and left alone: `admin/organizations_requests_spec:126` fails at seed **29928** and passes at others -- verified to fail identically with these changes stashed, so it is not from this work. Noted in the design.md backlog. |\n
| `475c3b69d` | **A single filter is shown, and a filter checkbox joins the control line.** Three things reported on Items &amp; inventory; two were the same thing. **The checkbox floated** -- the filter panel is a grid of stretching cells, a labelled filter puts 26px of label above a 38px control so its control lands at the cell's bottom, and a checkbox has no label and landed at the top: measured on `/items`, the select's centre at **y=327** against the checkbox's at **y=292**, **35px apart**. That is also what read as "unequal padding above and below the filter dropdown" -- the band's own padding was already 16/16, and the gap was under a checkbox that had floated to the ceiling. `filter_checkbox` is the grid cell now and bottom-aligns a 38px row inside it; measured after, **0px apart**, and the hand-tuned `pb-2` came off four views. **And a single filter is no longer hidden behind a disclosure**: measured across the eighteen filtered pages, **4 have one control** (on `/vendors` and `/donation_sites` it is a *checkbox*), 6 have two, 3 have three and 5 have four or more, up to **9 on `/donations`**. This is not the two-behaviours problem design.md rejected when the old five-filter threshold went -- that objection was about a reader learning where things are *hidden*, and a filter that is simply visible teaches nothing wrong. The count is taken from the **rendered cells**, so a page gaining or losing a filter cannot forget to say so, and no chips are drawn in the single case because a chip repeating a filter you can see and change is duplication (`storage_locations/show` asserted that chip and now asserts the shape that replaced it). **Rejected**: the Polaris/Stripe/Jira "common filters inline, More filters for the rest" -- the most standard answer and the largest, needing a per-page decision about which filters are common plus a responsive rule, so it is its own work. New `spec/system/filter_bar_system_spec.rb` (**4 examples**). Verified: **1468** non-system and **1688** system/request examples green, rubocop clean across 678 files, `erb_lint` clean, and the layout-shift and keyboard audits report no findings. |\n
| `992483d79` | **Two filters is what fits, and the inline row had a margin it did not need.** Both halves of the previous change reported again. **The padding really was unequal**: the inline row kept the `mb-3` that separates it from the panel, and inline there is no panel -- measured on `/partners`, **16px above and 29px below**. The band's own padding was 16/16 all along; the extra 13 was a margin doing a job that no longer existed. Inline the row has no bottom margin now and the band measures **16/16**. **And the threshold was wrong**: `/items` has two controls by the code's count and one by the reader's -- *"the only filter is NDBN reporting category"* -- because the second is *Also include inactive items*, a **modifier of the first filter** rather than a second one. Every such checkbox in the app is that species. Rather than classify controls, the threshold is now **what fits on a line**, which is two: the panel's cells are 261px at 1440, so two plus a gap is ~530px against 1078px of card, and it still fits at 656px -- the narrowest the table stays a table. Ten of the eighteen filtered pages show their filters; eight fold them. **The first attempt reintroduced the fault sideways**: wrapping all inline controls in one `sm:w-72` box put two of them in a *column*, a select and a checkbox **38px apart vertically** -- the previous day's 35px misalignment, rotated. They use the panel's own grid now, so a control is the same width folded or not, and the centres measure equal. **A Ruby note**: the first version wrote `INLINE_LIMIT = 2` in the template, which is a dynamic constant assignment in a compiled method body and a SyntaxError -- and the symptom was **no filter bar at all, on every page**, not an error. Verified: **1468** non-system and **1690** system/request examples green, rubocop clean across 678 files, `erb_lint` clean, and the responsive audit clean across **1,562** page/width combinations. |\n
| `e70f9eebe` | **The selection bar floats, and the filters stay usable.** Reported: "the print pick lists batch action makes the filter disappear... they should not be mutually exclusive." Correct, and **the reasoning recorded yesterday does not survive checking**. design.md said the bar replaces the filter row because "three of the four keep it in the toolbar", citing Carbon, Material, GitHub and Gmail -- but only **Carbon** takes the filters away. GitHub's batch header replaces a *list header* below its filter bar; Gmail's toolbar is its *action* toolbar and search is separate; Linear, Notion, Airtable and Drive cover nothing. Three systems were counted as agreeing with a fourth by describing them all as "keeping it in the toolbar" -- true, and not the point. **And the layout argument was wrong on its own terms**: "an inserted row moves the table and a replaced one does not" treats a shift the reader *caused* as an unprompted one, which `bin/design/layout-shift-audit.js` -- written the day before -- explicitly skips, as Chrome does. Two options previewed (`docs/mockups/filters-and-batch-together.html`); the **floating bar** chosen over a bar inserted under the filters, on a measurement rather than a preference: `/requests` is **1,289px against a 900px viewport**, so a bar pinned to the top of the list is off screen exactly when you have scrolled to the bottom to finish choosing -- which is why Linear, Notion, Airtable and Drive all float theirs. Measured after: filters and *Show product totals* reachable with a selection live, the table head unmoved at **y=228**, the pill at **798-852** clear of the scroll rail at **876-900** (`bottom-12` and `z-40`, because at `bottom-6` it sat on the rail), and it stays put when the page is scrolled. Dark, and the app's only inverse surface: yesterday's objection was right for a band *in* the card and wrong for one *over* it. Verified: **1468** non-system and **1691** system/request examples green, rubocop clean across 678 files, `erb_lint` clean, and the keyboard audit reports no findings across 142 screens. |\n
| `52f943cd8` | **Six tables reach their card's edge, and the industry citations get audited.** Reported: "on the partner announcements page, there is extra padding in the table to the left. The hover shows this clearly, and the divider line below the column headers doesn't span all the way to the left." The table sat in a hand-written `<div class="px-5 py-4">` inside a `padded: false` card, inseting it **21px** on both sides. Auditing the shape found **six** index tables like it -- `/broadcast_announcements`, `/admin/broadcast_announcements`, `/admin/base_items`, `/admin/organizations`, `/admin/partners`, `/admin/users` -- **none** of them in a `.table-scroll` region, so none had a rail, an overflow shadow or a named region; four had no `<caption>`; two carried `w-50`, Bootstrap's 50% utility, defined nowhere in Tailwind v4. Both announcement pages also kept **New announcement** in a `flex justify-end` div *inside the card*; it is in the page header now. **Five tables are deliberately left alone** and recorded: three partner-portal *form* tables, the kit allocation change-summary panel, and the partner service-area table -- the first audit rule flagged all five, and the distinction is whether the card is `padded: false`. **And the citation audit**: new `bin/design/citation-audit.py` classifies every claim naming two or more systems -- **97**, of which **29 name an artefact** (`OverflowMenu`, `slds-truncate`, `<Table sticky />`), 24 attribute numbers, **34 assert unanimity** and 10 are observational. **32 assert unanimity across four or more systems without naming anything checkable** -- the form the selection-bar error took. Four were wrong in form and are fixed: a "none of the five" that **named six**, an "identically" four systems do not manage, a **28px of ours** attributed to two of them, and four recalled spacing figures now marked as recalled. The rest are unevidenced rather than known-wrong, and rechecking them needs the products in front of you, so it is in the design.md backlog. Verified: **1468** non-system and **1691** system/request examples green, rubocop clean across 678 files, `erb_lint` clean. |\n
| `86a10c9c9` | **The unevidenced citations, all 32 of them.** After the selection-bar error, `bin/design/citation-audit.py` found **97** claims naming two or more systems, of which **32 asserted unanimity across four or more without naming anything a reader could look up**. All 32 are now dealt with, in the two ways available to someone who cannot open the products. **15 rewritten in design.md**, which is normative: where a system publishes something it is named -- Carbon's `Button` with `hasIconOnly` and `iconDescription`, Primer's `IconButton`, MUI's and Atlassian's `Tooltip`, Ant Design's `Tooltip`, Salesforce's `lightning-button-icon` with `alternativeText`, the ARIA APG's "Breadcrumb", GOV.UK's style guide, Apple's HIG -- and where nothing is published (the avatar menu, the floating bar, rail ordering, applying filters on change) the claim says **observed**, names the products as a description of seven or four interfaces, and the decision leans on the measurement of this app that was doing the real work anyway. **17 annotated rather than rewritten**, each with a dated correction line: the decision log records what was reasoned at the time, and editing it to look better reasoned would be the same fault one level up. **Two still flag and are correct as written** -- the tool's proximity test cannot tell an absolute about *this app* ("every tab's controller goes in `active_on`") from one about someone else's product, and it now says so in its own output. The standard recorded: **name the component, or say what you observed** -- the tool checks the *form*, not the truth, and what it enforces is "give the reader enough to catch you being wrong". Verified: rubocop clean across 678 files, `erb_lint` clean, and the three system specs touching this week's components green. |\n
| `73f554b69` | **Finished the citation audit, and gated it.** Two questions: what the audit left undone, and how to stop it recurring. **Unfinished: the numeric bucket** -- the audit sorted 97 claims into four kinds and only the 32 asserting unanimity had been remediated. Tightening the test showed most of the 24 "attributes numbers" were false positives: it flagged any block holding both a number and two system names, which catches nearly every entry in the log, because the numbers here are measurements of **this app** sitting beside the systems it was compared against. Asking instead whether a number stands next to a system's name *with nothing to say the measurement is ours* took **24 to 6**, of which three were genuine and one was **wrong**: "Apple's HIG and Material both say" 44x44, when Apple specifies **44pt** and Material **48dp**. Annotated. **Prevention**: a new design.md section, **"Citing another system"** -- name the artefact or say you are describing an interface; check each system against the *specific behaviour*, not the category; a number belongs to whoever measured it; avoid the absolute unless you have checked every case. It also records what the audit kept showing: **the citation is rarely what decides anything**, since every softened decision still had a measurement of this app behind it. And `citation-audit.py --check` now holds a baseline in `citation-baseline.json` and **fails when the unevidenced count goes up** -- verified, one sentence of the old form takes it 2 to 3 and exits 1. Plain about the limit: it checks the *form*, not the truth, because nothing here can open Carbon or Linear. The two claims still counted are the proximity test's known limit (absolutes about our own code beside a system's name) and it prints that in its own output rather than being tuned until it lies. Verified: rubocop clean across 678 files, `erb_lint` clean, `--check` green at the baseline. |\n
| `5ddf9e126` | **A syntax error that four checks and 3,159 specs did not catch.** Running the full suite plus the rest of the checks found a defect from the icon-only sweep: a Python regex interpolated `None` as a *string*, leaving `icon: "bi-check-circle"None` in `distributions/_pickup_day_row`. **The template does not compile**, so `/distributions/pickup_day` raises for any day that has a pick-up on it. **Why nothing caught it**: `erb_lint` checks that ERB *tags* are well formed and does not compile the Ruby inside them; `rubocop` does not read templates; all **3,159** specs passed including the request specs for that action; and the page returned **200**, because Rails skips a partial rendered through `collection:` when the collection is empty and never compiles it -- every spec and dev load happened to be on a day with no pick-ups. Brakeman found it, as a parse error printed under `== Errors ==`, a heading I had been skipping past for weeks. New `bin/design/template-compile-audit.rb` and `spec/views/every_template_compiles_spec.rb` compile all **431** templates in about a second; verified to fail on the exact character when it is put back. Two smaller lessons recorded: a compiled template is a *method body*, and my first checker reported four healthy partials for "Invalid yield" by compiling at the top level; and **coverage of an action is not coverage of its view** -- the `#pickup_day` request specs never create a pick-up, so they never reach the row. Also recorded: **I contaminated my own first full run** by starting the system suite in the background and then running the non-system suite against the same database -- `DatabaseCleaner` truncated underneath it, Postgres deadlocked, and the run reported a failure with `<<ERROR>>` stale nodes, *the same symptom I twice attributed to flakiness earlier this week*. Run serially: **1468** non-system and **1691** system/request examples green, rubocop clean across 680 files, `erb_lint` clean, every template compiles, and the citation gate at its baseline. |\n
| `73994adc3` | **The "flake" was an application bug.** Asked to re-run the three specs I had called flaky, to test the database-contamination theory. Clean serial runs, one seed at a time: `admin/organizations_requests_spec:126` **failed again** at seed 29928, while `distribution_system_spec:115` (11588) and `request_system_spec:119` (50705) passed. So contamination was not the explanation, and `rspec --bisect` reduced **1,690 non-failing examples to 31** in 32 minutes -- all storage-location specs, which named the cause: `Admin::OrganizationsController#show` asked for `StorageLocation.find_by(id: @organization.storage_locations)`, **the whole association as the id**. That builds `WHERE id IN (SELECT id FROM storage_locations WHERE organization_id = ?)` and returns whichever row the database hands back first, so the admin organization page showed an **arbitrary** storage location as its "Default intake storage location". The bank's own controller had always had it right; only the admin copy was wrong. **The spec was correct the whole time** -- it passed whenever the arbitrary row happened to be the intake one, which depends on how many storage locations earlier specs inserted. That is not flakiness, it is what a **non-deterministic query** looks like from outside, and I mislabelled it twice. The tell I ignored: **it reproduced at a specific seed, twice**, and a timing-flaky spec does not do that -- a seed that reproduces is a bisect waiting to be run. New spec pins it with three decoy storage locations created before the intake one, verified to fail against the old query. **On the other two the honest position is that I do not know**: they do not reproduce, but fifteen spec files were added this week (1,654 -> 1,692 examples) so the same seed no longer produces the same ordering, and at least one run they failed in was demonstrably contaminated. They are out of the backlog, because there is no evidence they are order dependencies. Verified: **1692** system/request examples green **at seed 29928**, the seed that reproduced it; rubocop clean across 680 files; `erb_lint` clean. |\n
| `a596d0c0f` | **"Edit", and a delete that had inherited the primary's slot.** Reported on the product drive page: the buttons read *Make a correction* and *Delete*, the placement looked reversed, and would *Edit* not do. **The label**: measured, **30 call sites say "Edit"** against four saying "Make a correction", and the decision log shows the latter was **inherited, not chosen** -- pre-migration wording kept through the migration. It is also a claim the app cannot support: a *correction* says the record is wrong when you may be adding a tag. The locked-record callout changed with it, to "cannot be edited or deleted". **The placement exposed a rule the app has never followed**: design.md said "at most three actions, **exactly one** of them primary", but measured across 101 bank pages, **63 have no header actions at all** and **11 of the 38 that do have no primary** -- almost all record pages, whose job is to be read. Polaris, Material, Carbon and Atlassian all make it optional. With no primary on `/product_drives/:id`, **Delete inherited the last slot**. The rule now says *at most* one: **requiring a primary does not produce one, it produces a false one.** **And a record's Edit and Delete now live in the header's overflow** (`essentials_record_actions`) rather than at the foot of the page, where donations, purchases and distributions had them -- below the last card, which is where a form's Save goes. Two details took a second pass: **one item is not a menu**, so a lone Edit renders as a button before the primary rather than a kebab hiding one action; and it is the **kebab, not a named menu**, because "name the menu after its contents" works for two exports and not for "edit and delete" -- `row_actions` takes `size: :md` for 38px, since `size-10` is 40 and sat proud. **A spec helper that navigated**: `record_action_labels` closed the menu with Escape, but `popover_controller` focuses the first item on open, so the keys went to the *Edit link* and the browser followed it -- traced to the exact line, and it toggles the trigger now. Verified: **1469** non-system and **1692** system/request examples green, rubocop clean across 680 files, `erb_lint` clean, button audit 0 findings. |\n
| `3632ce82f` | **Import points in, export points out, and a lexicon so the next one cannot drift.** Reported on the donation sites page: the Import and Export icons look mixed up. They were -- **Import wore `bi-upload`, an arrow leaving a tray, and Export wore `bi-download`, an arrow entering one**, checked by rasterising both glyphs out of the font rather than reading the class names. **Two frames of reference had collided**: *upload/download* is measured from the server, up to it and down to you, while *import/export* is measured from the app, in to it and out of it -- so whichever way a reader took the row, half of it was inverted. Shopify's `polaris-icons` ships `ImportIcon` as an arrow **down into** a tray and `ExportIcon` as one **up out of** it, and IBM Carbon draws `export` the same way while shipping `download` **separately**, so an export is explicitly not a download; both were fetched and rasterised, not recalled. Now `bi-box-arrow-in-down` and `bi-box-arrow-up`, on **13 and 18 controls**, with `bi-download` left meaning the *Download example CSV* button that sits on the same page. **The rule that was missing**: design.md said how to *mark up* an icon and had never said **which glyph means what**, and a new audit walking **124 pages as three roles** found six more disagreements behind the reported one -- *Invite user* wearing **three different glyphs on three pages**, *Save* wearing a floppy disk on 12 forms and nothing on 29 (all twelve from one default argument in `submit_button` that no view mentioned), two glyphs for "done", and refuse sharing a glyph with deactivate. So **`bin/design/icon-lexicon.json`** -- 27 meanings, 5 structural glyphs, 16 generic verbs, 2 exceptions -- read by both `bin/design/icon-audit.js` and `spec/system/button_icons_system_spec.rb`, so the table and the app cannot drift; **the audit fails on a glyph it cannot find**, which makes adding one a decision rather than a reflex. **I drew the Save rule in the wrong place first**: "a form's own actions carry no glyph" flagged the filter bar's *Filter* and the dialog's *Import CSV*, both of which name real actions -- the line is between **a word that names what happens and a word that only says "commit this form"**, so `bi-envelope` went back on *Broadcast announcement* and `bi-person-plus` onto all four *Invite user* buttons. **45 Save buttons now carry no glyph** and `bi-save` is used nowhere. Two exceptions are carried **with their reasons**, the sharper being *Reject request*, whose label **toggles to "Close request"** while its fixed `bi-slash-circle` could not -- wrong on every closure. Also `/requests` had a row action called **Cancel**, the word this app uses on 122 pages to mean "abandon this form", while here it destroyed a record; it says *Cancel request* now. And one for the record: **`%>` inside a Ruby comment still closes the ERB block** -- writing it inside `<% %>` terminated the block and turned the rest of an array into HTML, caught by `template-compile-audit.rb`. Verified: **1469** non-system and **1701** system/request examples green, 9 new examples that fail when the fix is reverted, rubocop clean across 681 files, `erb_lint` clean across 430, icon audit **0 findings**, button audit 0, citations at baseline. |
| `48d85b71a` | **The kit warning came back, because nothing was holding it.** Reported: the callout on `/kits/new` sits at the bottom where you cannot see it -- **the same page, in the same words, as 2026-08-29**. The text quoted was the *pre-fix* wording, `kit's item` leak and all, which is not in the codebase: it is in `stash@{0}`, the snapshot of the **fifth workspace reset**, which reverted 316 files including `app/views/kits/_form.html.erb`. Checked with `git show stash@{0}:...`, not guessed. The live page measures **y=205, 48px under the `h1`**, where `e3e12881d` put it. **The lesson is not that the reset did it** -- it is that the fix had no test: `e3e12881d` moved a callout in one template and wrote the rule into design.md, and neither of those can fail. So `spec/system/callout_placement_system_spec.rb` pins both halves of the scope rule in a browser -- the kit warning above its first card, above its submit and **above the fold at 720px**, and the partner group's reminder note staying *below* its card, since the rule is scope and not position. Verified against the old markup: it fails at **y=922**, the number from the original report. Two faults in the first draft, both kept in the log: it **matched an empty live region** (`/kits/new` carries three `[role=status]`, two of them empty at y=0) and so compared nothing to the card; and its counter-example was **vacuous**, because `/partners/new` renders no callout at all -- a green example that could not have gone red reads like coverage and is worse than none. |
| `321e6772c` | **The confirmation was the browser's, and nothing was watching for that.** Reported: Delete on `/product_drives/:id` puts up the browser's own confirm box. **Why it happened**: the mechanism was gone -- `confirm_dialog_controller.js`, `_confirm_dialog.html.erb` and `spec/support/confirm_dialog.rb` were among the 81 files deleted by the **fifth workspace reset**, and both shells reverted to not rendering the host element, so `intercept` bailed on `!this.hasDialogTarget` and rails-ujs raised `window.confirm` for **every** `data-confirm` in the app. Verified from `stash@{0}`. **Why no audit caught it**: no audit ever pressed a button. `overlay-audit.js` opens dialogs, `page-audit.rb` reads markup, `wcag-audit.js` scans the page as loaded -- and a confirmation does not exist until a control is clicked, which for a *destructive* control is the thing an audit is least likely to do. Thirteen spec files do drive the dialog through `accept_confirm_dialog`, but only at the call sites they exercise, and this one **had no spec**: it moved into the header overflow the day before in `a596d0c0f`. So **`bin/design/confirm-audit.js`** -- every page as three roles, every `data-confirm`, the menu it hides behind opened, the control **pressed and dismissed**: **59 confirmations on 22 pages, 0 findings**, reporting a native box, a dialog that never opened, an empty message, or a destructive action without the red button. It **never accepts**, so it runs against a seeded database without deleting anything; verified to report `NATIVE confirm` and exit 1 when the layout's render is removed. `spec/system/confirm_dialog_system_spec.rb` pins the same contract in CI and fails 4 of 5 without it. **Two bugs were mine, not the app's**: keying on the panel `id`, which `row_actions` builds from `SecureRandom.hex(4)` and so differs per request (**20 false 'unreachable'**), then marking the first label match anywhere in the document, where every *closed* row menu still holds its own *Reclaim* (**37 false 'could not press'**). **And one real finding fell out**: four row triggers on `/organization` shared the accessible name *"More actions for Name Not Provided"*, because `User#display_name` falls back to that literal string -- indistinguishable to a screen reader. They use `preferred_name` now, which falls back to the email. Verified: 65 examples green across the confirm, organization, admin-organization and product-drive specs; rubocop clean; erb_lint clean. |
| `db64bbec9` | **What is resetting the workspace, and what can be done about it.** Asked whether the resets can be stopped. **Not from inside the repo**, and the diagnosis says why. Both snapshots of a reset land within **6 and 4 files of `548db78f6`** and hundreds from everything else -- and that commit is **the one that was `HEAD` when the session started**. The reflog shows **`HEAD` never moved**; `/tmp` and `.git` both survive, so it is not a filesystem snapshot. What is left is an external `git checkout 548db78f6 -- .`, which restores tracked files, brings back files later commits deleted, and leaves HEAD and the index alone -- exactly the damage seen, resurrected `app/models/kit_item.rb` included. Nothing in the repo does it: no hooks, `core.hooksPath` unset, `postCreateCommand` runs no git, no watcher. And **git has no `pre-checkout` hook**, so nothing here can get in front of it. So: detect, attribute, recover. **`.githooks/post-checkout`** records any path-limited checkout leaving >10 files adrift -- timestamp, commit, drift, and **the process tree that ran it** (verified: `post-checkout` does fire for `git checkout <c> -- <path>` with branch flag 0). **`bin/workspace-check`** returns **0 clean, 1 uncommitted work, 2 a rollback** -- three codes, because `bin/start` runs it and a check that shouts at every developer is one people scroll past. **`bin/workspace-restore --yes`** snapshots, restores, and **deletes the resurrected files**, which `git checkout .` does not. **Three of my own errors, kept in the log**: *untracked is not resurrected* -- the first restore offered to delete the three scripts being written to fix the problem, where a deleted-then-restored file has path history and new work has none; *an exact tree match is the wrong test* -- one stray untracked file defeats equality, so it called a 412-file rollback "work in progress", and closeness (6 files vs 412) is the real signal, opt-in behind `--identify` because the last rollback was **215 commits back**; and *the snapshot holds the damage, not the work* -- rehearsing a rollback destroyed three uncommitted files of mine and the stash faithfully captured the rolled-back contents. **Committing is the only thing that protects work in progress**, now with a measurement behind it. |
| `df0f4c9d6` | **A row header is a cell, and a report is not an index.** Reported on the monthly distributions table: padding missing on both sides, and had pagination been applied. **The padding was a hole in the design system, not a mistake in the view**: `.data-table` styles `thead th`, `tbody td` and `tfoot td, tfoot th` and never the fourth combination, so any table whose first column is a `<th scope="row">` had **no cell padding at all** and sat flush against the card edge -- measured `padding-left: 0px` against `16px` on `/donations`, and 17px in from the card on both after. Three tables, all three historical trend pages, and the row header is the *right* markup there, so the rule was punishing the correct thing. **Pagination: no, and it should not be** -- every report table is **one row per item** (27, 46 and 47 rows measured), bounded by the bank's catalogue, where an index table is one row per transaction and unbounded; and a report is read, exported and printed whole, all three of which a pager breaks. Recorded as a decision with a spec pinning the absence. **And the audit found a worse fault of the same class**: two reports marked "below the on-hand minimum" with **`table-danger`**, Bootstrap's class, defined nowhere since ADR 0011 -- so the warning was not subtle, it was **invisible**. It now uses the dashboard's existing low inventory treatment unchanged: the number in rose *and* a pill with the word and an icon, since design.md does not allow colour alone. Verified: 3 new examples, all three failing when their fix is reverted. |
| `d3b833994` | **Measured the three trend charts, and previewed four ways out.** Asked to show options for the report data visualisations. The measurements are worse than the aesthetics: **all three trend charts open completely empty** -- `HistoricalTrendService` creates every series with `visible: false`, so `/historical_trends/distributions` draws an **850px box, a legend of 47 names, and no data at all** until you press *Select all*. Donations and purchases are the same with 34 and 37 series. Press it and you get **47 series across 12 months in a 1034px plot -- about 1.8px per bar** -- keyed by a legend that is **191px tall, 22% of the chart**, over a **10-colour palette**, so five different items share every swatch and the legend cannot identify a bar even in principle. The **top 8 items are 75.2%** of all volume. Four options previewed at `docs/mockups/report-charts.html`, drawn as SVG from this bank's real figures rather than sketched: **A** one total per month, **B** top 8 + Other stacked, **C** top 8 + Other grouped, **D** a sparkline in every table row. Recommended **A with D** -- the chart's job on that page is the month-to-month shape, and the table beneath already answers "which item" completely, so a top-8 cut would put a partial answer next to a complete one; D gives all 47 items a trend without spending a colour. Awaiting a choice. |
| `8d608dda0` | **One total per month, and a sparkline for every row.** Chose **A with D** from the four previewed options. The three trend charts drew **47, 34 and 37 column series with every one `visible: false`** -- an 850px box, a 47-name legend and nothing drawn until you pressed *Select all*, which gave **~1.8px bars** keyed by a **10-colour palette** five items shared apiece. They plot **one total per month** now: one series, one colour, no legend, the figure printed on each column. **B (top 8 + Other) was the near miss and was rejected** because it would set a *partial* answer beside the complete one already in the table -- and the 75.2% that makes a top-8 cut viable is the same figure that makes it misleading, since a quarter of everything would be "Other". **D**: `essentials_sparkline` renders inline SVG on the server (47 a page, none interactive, so a charting library would cost an instance and a layout shift per row); `polaris-viz` ships `SparkLineChart` for the same reason. **The drawing is `aria-hidden` and the cell says "Peaks at 3,042 in Aug 2026"** -- not a restatement of the twelve figures a reader has just heard, but the one thing the shape adds. Measured after: **320px instead of 850**, so the table is above the fold; bars **55px at 1440 and 10px at 320** against 1.8px; contrast **6.29:1** column, **10.35:1** data labels, **7.58:1** axis, **6.29:1** sparkline, against 3:1 for 1.4.11 and 4.5:1 for 1.4.3; no horizontal document scroll at 320px; **axe 0 violations across 155 pages**. `Select all` / `Deselect all` are gone with the reason they existed, and `HistoricalTrendService` no longer returns a Highcharts rendering flag from a service whose job is figures. **One mistake of mine**: scripting the toggle methods out of `highchart_controller.js` left the class unclosed, and my syntax check was `node --check … || node -e …`, whose `||` swallowed the failure -- the console said `Failed to register controller: highchart` five times and the chart did not draw. **A check with a fallback is not a check.** 6 new examples, all six failing against the old chart. |
| `ee3742acf` | **Audited the other eight report pages, and fixed four rules that were half-kept.** All eleven reports walked as three roles: one `h1` each, no heading skips, a card on every page, every scroll region labelled, no leftover Bootstrap classes, no console errors. Four faults, each a rule design.md already had and nothing checked. **Three tables had no `<caption>`** -- the trend and county tables did, the three itemized reports did not, so a screen reader user reached them with no idea what they list. **Four pages were Title Case** -- *Monthly Distributions*, *Monthly Donations*, *Monthly Purchases*, *Activity Graph* -- against "sentence case for everything a person reads", while the reports hub linking to them was already correct, so the link said *Activity graph* and the page said *Activity Graph*. **The activity graph reserved no height**: the only chart not going through `shared/_highcharts`, which is the exact shape that measured **CLS 0.352** on the trend pages; it measured 0 today by luck, and the box is reserved now. **And it had no table** -- the last chart in the app without the text alternative design.md requires. **A spec of mine broke, correctly**: `layout_shift_system_spec` pinned `min-height == "850px"`, so shortening the chart failed it. It asserts that **the reserved height equals the height the chart draws at** now, which is the real invariant and covers both chart pages -- *a spec that pins a number instead of a rule breaks on the change it should have allowed*. Verified: axe **0 violations across 155 pages**, route sweep **0 findings across 141 screens**, table audit clean, and both suite halves green at two seeds -- **1469** and **1728** examples. |
| `0d6c0ec7e` | **The trend table scrolled at 1440, and the sparkline was not why.** Reported: the sparkline column makes the table too wide and adds a horizontal scroll on desktop. Measured first: the table was **1,423px in a 1,118px card, 305px over**, and the sparkline column was **140** of it -- the twelve month columns were **1,054px, 74% of the table**, set not by the figures but by the *headings*, `Sep 2025`, eight characters over a five-character number. Three trims, smallest last: `Sep 2025` → `Sep 25` via **`last_12_months_short`** (~190px), a new **`.data-table.dense`** taking horizontal cell padding 16px → 10px while leaving vertical padding and so row height and target sizes alone (~180px), and the Trend column 124px → 64px with a one-word heading (~76px). **No scroll at 1366, 1440, 1512 or 1920**; 1280 is down from 465px of overflow to 81 and still scrolls, because fifteen columns do not fit in 958px -- it scrolls inside `.table-scroll`, which **WCAG 1.4.10 exempts a data table from**, and clearing it would cost the per-row total. **Two digits of year, not none**: a twelve-month window crosses a year boundary, so `Sep` and `Aug` are in different ones; the long form stays on the chart axis and in the sentence a screen reader hears about each sparkline. **And a second spec of mine broke the same way as the first** -- it asserted the row header's padding was `16px` and failed the moment the table took `dense`, which is exactly the fault I had written up an hour earlier about `850px`. It now asserts the row header matches **the data cells in its own row**. *Writing down the lesson is not the same as having learned it.* Verified: 113 examples green, axe **0 violations across 155 pages**, responsive audit unchanged at its 2 pre-existing findings, rubocop and erb_lint clean. |\n
| `9af65361d` | **Previewed date-range handling, extra parameters and other chart styles for the reports.** Asked what the industry standard is for a date range on a data visualisation, whether month/year granularity applies, and what other parameters or chart styles would help. Measured first: **six report pages carry the 11-preset day-granular picker and the three trend charts carry nothing at all** -- their window is welded into `HistoricalTrendService` as `where(issued_at: 1.year.ago.beginning_of_month..Time.current)` with twelve fixed buckets. **The catch is granularity**: the existing picker is day-granular and the charts bucket by month, so any custom range produces **partial months at both ends** -- short end columns with nothing on the chart saying why, which reads as a fall that is an artefact of the range. The industry splits cleanly on exactly that: **Xero and QuickBooks use month/year pickers** so a partial month cannot be expressed, **Grafana and Metabase make granularity its own control**, **Stripe re-buckets to suit the span**, and **GA4 keeps day granularity and warns about the incomplete period**. Nobody offers a day range over a monthly chart and leaves it unexplained. Options at `docs/mockups/report-date-ranges.html`, all drawn from real figures: **A** month/year range in the same popover as the existing picker, **B** window presets only, **C** window plus a granularity control; plus parameters (compare with previous period, item category, partner, location, cumulative, units) and styles (line, stacked by category, calendar heatmap). Recommended **A + compare + category** -- category because **3 categories cover 35 of 51 items**, which is the composition answer a top-N cut could not honestly give. Awaiting a choice. |\n
| `472f3f10b` | **A month range for the trend charts, and the current month marked rather than withheld.** Built option A: `shared/month_range_picker`, the same popover, presets and apply-as-you-choose as the date filter, with a native **month** field instead of a date one -- because a day-granular range over a monthly chart gives **partial months at both ends**, short columns a reader takes for a fall. Asked whether only completed months should be selectable: **no**. *"How are we doing this month"* is the most common question of a trend, so the current month is offered and **marked** -- lighter fill with a border, *"so far"* on the axis label and on the table header, and *"Aug 2026 is still running"* in the subtitle. **Three of the four signals are words**: a fill pattern is a colour by another name and design.md does not allow colour alone. The marking disappears on the last day of a month, when the bucket is not partial, and there is an example asserting that absence. **Measuring it found something else**: a distribution can be dated ahead of itself -- **10 here, 82 line items** -- and the service dropped them silently at `Time.current`. They stay out, since a trend is what happened rather than what is booked, but the page now says so in a callout linking to the distributions list; donations and purchases have none and never show it. **Dropping data silently was the wrong part, not dropping it.** Three fixes on the way: the bucket index was `record.issued_at.month - Date.current.month - 1`, modular arithmetic that only worked for exactly twelve months ending this month; the cache key carried no window, so a new range would have been served the old figures; and the picker threw `Missing target element "form"` because **a Stimulus target must be a descendant of its controller** and I had put the controller on a div inside the form. Verified: 9 new examples, 25 across the neighbouring report specs, axe **0 violations across 155 pages**, rubocop clean across 688 files, erb_lint clean. **Not built**: 24 months is 27 columns and 653px of overflow, where a line beats columns past ~18 points -- that, the previous-period comparison and the category filter are still to come. |\n
| `e18b3d7c1` | **The month picker was in the wrong slot.** Reported: the range picker is on the right and squeezed into a narrow column. Measured **142px wide at x=1266**, against **271px at x=288** for the date picker on a sibling report page. I had put it in the page header's `actions:` slot -- a **right-aligned flex row sized for buttons**, which shrinks a labelled control to its content. The six report pages that already had a date filter all use `shared/essentials/filter_bar`; **a filter is not a page action**, and the app had said so by construction six times over. It is in the filter bar now -- **x=288, 256px, aligned with the `h1`** -- and brings **no form of its own**, sitting inside the bar's form and contributing one hidden field, which also removed the controller-must-be-on-the-form problem from the previous change. **Two more faults the move exposed, both mine**: *Clear all* appeared on a page nobody had filtered, because `filter_summary_controller` skips `type="date"` inside the date popover and `<input type="month">` is not that, so both visible fields counted as filters -- the rule is widened; and **my own spec for it was vacuous**, asserting `have_no_button("Clear all")` when "Clear all" is an **anchor**, so it was true no matter what the page did and would have passed while the bug was present. `have_link` now, and it fails when the skip is removed. **That is the third vacuous assertion this session, all three the same shape**: a negative check against a selector that could never match. Verified: 11 examples green and each failing when its own fix is reverted, 1739 system/request examples, axe **0 violations across 155 pages**, rubocop clean across 688 files, erb_lint clean. |\n
| `211547289` | **Comparing and categories, and where a view option is not a filter.** The last two pieces of the approved recommendation. **Comparing is not a filter**: built as a third checkbox in the filter bar, it made the bar fold **all three controls behind a Filters button** -- including the month range, one change after the page was given one. That limit is measured, not arbitrary: two controls plus the gap is ~530px against 656px of card at the narrowest width the table stays a table. **A third control in a bar does not cost a third of the row; it costs the whole row.** So the distinction did the work rather than the limit -- a filter *narrows*, and comparing narrows nothing -- and it sits on the chart card's `actions:` as a link, needing no JavaScript. **The comparison window is the current one shifted back by its own length**, not "the same months last year", which is wrong for any window that is not a whole year. Drawn as **one dashed grey line over the columns** -- the preview drew both as lines, and keeping the current period as columns satisfies the same argument, since the point was never "lines" but "not two sets of columns a month" -- plus a `tfoot` row of the same figures, because a dashed grey line is the thing a reader who cannot see it most needs written down, and the change in **words** (*"up 241% on the previous period"*). **Categories**: the chart stacks by item category with nothing chosen and narrows to a single series when one is; it **stacks only when more than one band has data**, so an organization that does not use categories gets option A unchanged; **`Uncategorised` is an option** because 16 of 51 items have none; and band colours are capped by `CHART_BAND_COLOURS` rather than by the data, since past about eight a legend stops being a key. Two things measured: `left_joins(:item_category)` raises `AmbiguousSourceReflectionForThroughAssociation`, so the lookup is two plucks; and the category totals were checked against the whole -- 12,717 + 71,065 + 76,163 + 7,333 = **167,278**. Verified: 8 new examples, 37 across the four report specs, axe **0 violations across 155 pages**, rubocop clean across 689 files, erb_lint clean. **Known and not fixed**: with comparison on, the table overflows 332px at 768 and 514px at 390, scrolling in its own region; and the line-instead-of-columns switch past ~18 points is still unbuilt. |\n
| `5842a7905` | **Measured the stacked chart's colours, and they cannot be fixed by choosing better ones.** Reported: the stacked bands all look similar. Measured every pair against WCAG 1.4.11's 3:1 floor under normal vision and three kinds of colour blindness -- **all six pairs of the four bands fail**, the worst at **1.03:1**, two bands that are the same colour to a reader with deuteranopia. A single-hue lightness ramp does not rescue it either (adjacent ratios 1.43, 1.76, 2.16). So I worked out the ceiling instead of guessing at more palettes: **at most three fills can be mutually 3:1 apart on a white card** -- luminance steps 0.0, 0.10, 0.40, and the next is past white -- of which only **two** are also 3:1 against the card. **Four bands distinguished by fill alone is arithmetically impossible.** Four options previewed at `docs/mockups/stacked-chart-accessibility.html`: **A** stop stacking and let the category filter do it, **B** small multiples with one chart per category in one colour, **C** keep the stack and direct-label the bands, **D** patterns as well as colour. Recommended **A with B** -- no pair of colours anywhere that a reader has to tell apart. **Also corrected a claim I made in design.md without measuring it**: that the palette is "ordered so adjacent bands differ in lightness as well as hue" -- sky is 0.33 and teal 0.37. **Two other things fixed in passing**: the category select had `appearance: auto` and `padding-right: 12px`, so the browser's own arrow sat on the text -- it used `FILTER_CONTROL_CLASSES` where `SELECT_CLASSES` exists for exactly this and says so in its comment; an audit of **142 selects across 98 pages** found no others. And the categories themselves are **seed placeholders** from `db/seeds.rb:130`, not real names. |\n
| `aab8e0768` | **I sized a chart from the seed data, and the seed data was a placeholder.** Challenged on the stacked-by-category chart: the categories could be 50, what bounds them, and look at the seeded data of the chart just replaced. Correct throughout. **The chart I replaced had 47 series; the one I replaced it with has as many bands as the bank has categories, and nothing bounds that number** -- changing what a series *means* did not change the fact that its count came from the data. Measured: `ItemCategory` has **no count validation and no database constraint**, **any signed-in bank user** can add them (not admin-only), the seed's **3** per organization is a placeholder named `"Category One"` which I read as evidence, and with 46-55 items a bank could have **51 bands**. There *is* a bounded taxonomy and the report does not use it: `BaseItem#category` is system-wide with **11 values**. **The rule I should have applied**, now in design.md: **a chart's series count is a constant the design picks, never a number the data supplies** -- GA4 makes the table drive the chart, Amplitude/Mixpanel/Datadog/Grafana ship top-N with an explicit *Other* (Grafana says "showing top 20 of 143 series"), Stripe never breaks the chart down at all. Options at `docs/mockups/unbounded-categories.html`, drawn at **20 and 50 bands** so the failure is visible rather than argued: **A** one total always, O(1) in categories; **B** the table plots what you tick, which fits because the table already has a sparkline per row and answers the original 47-item question too; **C** top N with an *Other* carrying its item count. Recommending **A + B, and dropping the stack** -- and noting my earlier rejection of C was too strong, since "a partial answer beside a complete one" is a weaker objection when the alternative is an unreadable one. Awaiting a choice. |\n
| `200fd56e1` | **Previewed the category filter, and measured the app's own long-select habit first.** Asked for recommendations on the category control before building A+B. Measured across **142 selects on 98 pages**: 81 have 10 options or fewer, **54 have more than 50**, the longest is a **153-option** time zone picker, and **none has any search, combobox or autocomplete wrapper**. So the app's existing answer to "one of many" is a plain native select at any length -- a real precedent that cuts both ways. Verified rather than recalled: **GOV.UK maintains `accessible-autocomplete` as a separate component** for choosing from a list, and **Carbon ships `ComboBox`** and **Polaris `Combobox`**, both distinct from their plain Select; I could not fetch GOV.UK's prose guidance, which lives on their site rather than the repo, so it is not quoted. Four options at `docs/mockups/category-filter.html`, drawn at 3 and 15 categories: **A** leave it a plain select, **B** a searchable popover reusing the shape the date and month pickers already use, **C** a real combobox, **D** no filter at all, with category as a table column. Recommended **B** -- one pattern, already built and specced here, scaling with no threshold and avoiding the full combobox ARIA surface -- **with the caveat stated rather than buried**: it would make this the only searchable list in an app with 54 selects over 50 options, including 52-item pickers on eight pages that matter more than this filter, so if it is worth building here it is worth extracting for those. **A** is the honest alternative if that door should stay shut. Awaiting a choice. |\n
| `f8f21ac77` | **A+B built, with a measured cap of four.** Built the chart-is-one-total default and the table-plots-what-you-tick comparison, plus the searchable category picker. The question that came with the approval -- what it looks like with several selected, and whether there should be a cap -- is what decides whether B beats the stack it replaces: **without a cap it is the same unbounded series count, handed to the user instead of taken from the data**. So, four, and measured rather than picked -- both non-colour distinguishers run out there. **Four dash patterns** (solid, dashed, dotted, dash-dot) are the most that stay distinct at 2px, and **a fourth direct label is the first to collide**: end-gaps of 55 and 18px at three lines, **6px** at four, against the 16px a 12px label needs. **Colour cannot be the distinguisher at all** -- of 28 pairs from an eight-colour set, **none** clears 3:1 across normal vision and three kinds of colour blindness; each line is >=3:1 against the white plot, which is the separate thing 1.4.11 asks. At the cap the remaining boxes are **disabled with a visible reason** -- *"4 of 4 plotted. Clear one to plot another."* -- not `sr-only`, which is the fault fixed once already in the row menus; the four chosen stay enabled so there is a way out. **The stacked-by-category chart is gone**, and with it the last series count taken from the data. **Three things to get right**: the checkboxes are in the table and the filter bar's form closed three cards earlier, so the table has its own form carrying window, category and comparison forward as hidden fields; the category picker filters in the browser, with a `role="status"` empty message; and **a spec of mine broke on the new column** -- `month_columns` was `thead th - 3`, the **third** time this session a spec pinned an arithmetic constant instead of a rule, after `850px` and `16px`. Verified: 7 new examples, 44 across the five report specs, **1469** non-system and **1754** system/request green, axe **0 violations across 155 pages**, rubocop clean across 690 files, erb_lint clean. **One unreproduced failure reported rather than swept up**: `layout_shift_system_spec`'s activity graph example failed once and has passed five runs since, including at the same seed and alone. |\n
| `52d289cd5` | **Ticking rows in a table is the wrong control, and I should have measured it.** Reported: the category dropdown is still there, ticking a row throws you to the top of the page, and plotting from the table is too much friction. **Measured, worse than it reads**: ticking the 21st of 47 rows loses **1,702px of scroll**, costs **a full document reload**, and leaves the row **off screen** -- four rows is four reloads and four scroll-downs. **Foreseeable and I did not foresee it**: the checkbox submits a GET and a GET is a new page. I verified the cap, the dash patterns, and that the window and category survived -- **every check was about a state, none about the path between states**. The second complaint is fair too: a single-select in the filter bar *and* checkboxes in the table are two answers to "what am I looking at". Options at `docs/mockups/choosing-what-to-plot.html`; recommending the proposal as put -- **one multi-select beside Months**, replacing both controls, picking categories, narrowing the table and drawing a line each, **applied on close** so four choices cost one request and no scrolling, with chips in the trigger doubling as the chart's key. The cap of four is unchanged, having been measured against dash patterns and label collisions. Alternatives named rather than dismissed: **B** the same control listing categories *and* items (keeps per-item comparison, costs a 62-entry list of two kinds of thing), **C** no plotting at all with the sparkline column carrying it, **D** keeping the checkboxes and applying into a frame, which **fixes the flinch and not the cost**. On spacing: the two sit 27px apart on one row and belong together, since both govern the chart *and* the table. **The scroll loss gets fixed whichever wins** -- 1,702px is a defect, not a design choice. |\n
| `4f573f776` | **One Compare control: categories and items in one searchable, capped multi-select.** Built option B, replacing both the single-select category filter and the checkbox on every table row. **Measured before and after**: choosing four things went from **four document reloads and 1,702px of lost scroll** to **one request and no scrolling**. Categories and items sit in one list because somebody thinking *"how are nappies doing"* should not have to know first which of the two nappies is; **what you choose is what the page is about**, drawing the lines *and* narrowing the table, where before the select narrowed and the checkboxes drew -- two rules wearing one label. **Three things the interaction needed**: *applied on close, not on change*, since a range is one answer but a set is not finished until you stop adding to it -- `popover_controller` now dispatches **`popover:close`** so a panel has one place to listen instead of three (trigger, Escape, click-outside); **`stopPropagation` on the checkbox**, because the boxes sit in the filter bar's form and the first tick navigated immediately, *the exact friction the control exists to remove, one level down*; and **waiting for the navigation in the spec**, because `close()` sets `aria-expanded="false"` synchronously and submits after, so the helper read the page it was leaving -- *an assertion that can run against the page you were leaving is not an assertion*. Group headings are **`text-xs font-semibold text-slate-500`**, sentence case with no uppercase or tracking, as design.md already requires of a heading over a column -- my mockup had used the uppercase eyebrow the rule exists to prevent -- and a heading over an empty group hides with it. The cap of four moved across unchanged, being measured against dash patterns and label collisions rather than against how the choosing happens. Verified: 7 new examples run three times, 50 across the report specs, **1469** non-system and **1754** system/request green, axe **0 violations across 155 pages**, rubocop clean across 691 files, erb_lint clean. |\n
| `f604a0157` | **Five small things, and a cache bug behind the fifth.** Reported together: too much space between the two filters, "Months" being narrower than the question it asks, no way to clear a chip without opening the panel, whether hints would help, and a subtitle meaningless to a non-technical reader. **The gap was 27px where the grid says 12** -- the bar uses 271px columns with a 12px gap and both pickers carried `sm:w-64` (256), so 15px of leftover read as padding; design.md already said the inline controls use the panel's own grid, and two controls did not. The spec asserts the gap **equals the grid's own**, not that it equals 12. **"Months" is "Date range"**, the name the six other report pages give the same question, with the granularity in the hint. **Clearing needed the trigger taken apart**: a chip carries a remove button and a button inside a button is not valid HTML, so the trigger is now a field-shaped row of chips with their own ×, plus a smaller button that opens the panel -- the bar's own chip row was unavailable and deliberately so, since design.md keeps chips out of an *inline* bar, and these chips are not a repetition of the control but the control itself. **Clear all** also sits in the panel, hidden while nothing is chosen. **Hints added** under both controls, wired with `aria-describedby`. **And the subtitle was hiding a bug**: *"Cached, so it may be up to 24 hours behind"* described a nightly job that had been writing `"#{org}-historical-#{type}-data"` since before the trend pages gained a date range -- after which the page read a key built from the window, so the job spent every night, for every active organization and three record types, **writing something nothing read**. Verified before removal: the only other reference was its own spec. Worse, my replacement had **no `expires_in`**, which on `solid_cache_store` freezes a window's figures until the window moves -- next month -- so a distribution recorded today would not have appeared. Five minutes now, against **6ms** measured to compute. **Two flaky examples turned out to be one fault, and mine**: `layout_shift` and `request_units` both read with **`evaluate_script`, which does not retry**, straight after a navigation -- measuring a chart Highcharts had not drawn and a chip that did not exist. Audited every spec written this session for the same shape and found **four more**; a wait comes first in all of them, and the suite passes at the seed that failed and at a fresh one. Verified: **1467** non-system and **1761** system/request green, axe **0 violations across 155 pages**, rubocop clean across 690 files, erb_lint clean. |\n
| `c47724183` | **Measured the three things pushing the chart around, and previewed the fixes.** Reported: the Compare field is taller than the date range field, "September 2026 so far" breaks the chart's symmetry, and the chips make the field so wide it pushes the visualisation down. All three measured. The Compare field is **46px against the date range's 38 before a single chip is added**, and grows to **76px at two chips and 166px at four** -- pushing the chart card from **y=313 to y=433, 120px down the page**. The two field faults are one fault: chips inside a field make the field grow. On the axis, the last label is **29px tall against every other one at 14**, because "so far" sits under it on a second line. Options at `docs/mockups/field-height-and-axis.html`: for the field, **A** move the chips to the foot of the chart card where a legend would be -- which is what they already are, since each carries its line's dash pattern -- leaving a plain 38px control saying how many are chosen; **B** keep them in the field on one line with a `+3` overflow, which costs the removal that was asked for; **C** a chip row under the bar, still above the chart and so still able to push it. For the axis, **A** take "so far" off it, since the marking is already carried by the lighter fill, the table header and the card subtitle; **B** an asterisk at one line height with a note. Recommending **chips onto the chart, and "so far" off the axis** -- a key that grows downwards cannot push the thing it explains, and it replaces Highcharts' own legend rather than sitting beside it. Awaiting a choice. |\n
| `2b18c064c` | **"so far" off the axis, and a fourth vacuous assertion.** Approved and done: the current month's marking is off the chart's axis, where it sat on a second line under the last category and made that label **29px against every other one at 14** -- one column's label twice its neighbours' height, and the axis 12px deeper for one word. All twelve now measure 14px. **Nothing was lost**: the month was marked four ways and is marked three -- the lighter fill and outline, the table header for that column, and the card subtitle *"Sep 2026 is still running"* -- and the axis was the only one of the four that cost symmetry and the only one not also said in words. **And the assertion I wrote for it was vacuous, the fourth this session**: I measured the axis labels' heights and asserted they were equal, and it passed with the two-line label put back, because **the test browser renders the newline flat** -- `tspans: 0`, every label 14px, the text reading `"Jun 2026\nso far"` on one line. It asserts the label *text* now, which fails on the bug and passes on the fix. Found by reverting the fix and watching the spec stay green, **which is the only reason to bother reverting**. Three of the four were negative checks against a selector that could not match; this one was a positive check against a measurement the environment flattens. **Also previewed, not built**, at `docs/mockups/where-the-chips-go.html`: where the chips go, B against C. The measurement decides it -- four chips are **659px**, the field **256px**, the bar row **1,120px** -- so they cannot fit in the field and fit on one row beneath it with 461px spare. Carbon's `MultiSelect` puts a **`selectionCount` badge** in the field rather than chips (read from source), Polaris ships `Tag` for a row, and Material separates an *input chip* inside a text field from a *filter chip* in a chip set. Recommended **C**, with a **"Comparing:"** prefix so the relationship is carried by a word as well as position. Verified: **1762** system/request examples green, rubocop clean across 690 files, erb_lint clean. |\n
| `0b4206c14` | **The chips moved out of the field, and the measurement chose where.** Built C: the control says **how many**, a row under the bar says **which**. **Why not B** -- four chips are **659px** and the Compare cell is **256**, so only one plus an overflow badge fits, and the three behind the badge could be neither seen nor removed without opening the panel, which is what was asked for two changes earlier. Under the bar there is **1,120px**: four sit on one line with 461px spare, and the row costs a fixed **26px** however many there are. **Measured after**: both controls **38px** at every count, where Compare had been 46px empty and **166px at four**; the chart card sits at y=347 with one, two or four chips, moving once when the row appears and then not at all, against **120px** of shove before. **Read from source**: Carbon's `MultiSelect` puts a `selectionCount` badge in the field and not the chips, Polaris ships `Tag` for a row, and Material distinguishes an *input chip* inside a text field from a *filter chip* in a chip set -- two of three put the summary in the control and the chips in a row, which was also the only thing the width allowed. **On proximity**, the row is immediately under the bar and prefixed **`Comparing:`**, so the relationship is carried by a word as well as position; aligning it under the Compare column would have been perfect proximity and three rows of height. **Two things fell out**: the chips are **links**, since the row is outside the bar's form and a link needs no JavaScript and no second controller -- which deleted `compare-picker#remove` -- and the clear control is **`Clear comparison`**, not *Clear all*, because the bar already has a *Clear all* that resets the date range too, and two controls with the same word doing different things is the fault the row action called *Cancel* had. **One mistake recorded**: my first attempt at the edit failed on a missing anchor and wrote nothing while a sibling edit succeeded, so the page briefly had chips in **both** places -- caught by measuring, not by reading the diff. *A batch of edits where one silently does nothing looks exactly like a batch that worked.* Verified: 18 examples in the picker spec, **1467** non-system and **1766** system/request green, axe **0 violations across 155 pages**, rubocop clean across 690 files, erb_lint clean. |\n
| `37e65d5c3` | **"Narrowed to what you are comparing", and an audit of the app's explanatory prose.** Reported: the table's helper text does not make sense. It named **what the code did** and left the reader to work out what was left; it says **"27 of 47 items."** now, which is the app's habit everywhere else. **Prefer a figure to a description of a state.** Then audited every card subtitle, page-header subtitle and filter hint the app *renders* -- **38 distinct strings across 129 pages** -- rather than grepping source, since a grep cannot tell a hint from an identifier and half are interpolated. Four faults: **hints disagreed on punctuation** (21 ended in a full stop, 3 did not, and a hint is a sentence); **the same rule written two ways** -- *"500 character maximum"*, *"500 characters maximum."* and *"Cannot be more than 250 characters"*, now all *"N characters maximum."*; **a hint describing the feature rather than the field** -- *"Categories help organize and identify items"* became *"Categories group items for reporting and for partner requests."*, which is checkable, since `ItemCategory has_and_belongs_to_many :partner_groups` means a category really does gate what partners can request; and **four spellings of one thing** -- *Zip code*, *Zip Code*, *Zip Codes Served*, *Zipcode* across seven places, three of them Title Case, now all *Zip code* including the pluralised *"8 zipcodes"* in the service area card. **And a check so it cannot drift back**: `copy-audit.rb` gains a *hint without a full stop* check, with `hint` carrying its own kind in the extractor so the rule applies to hints and not every label, plus **six probes** including the two a careless version would fail -- a label is not a hint, and a hint built from a value ends in a brace in the source. Verified by putting the old string back and watching the audit report it. Verified: **1467** non-system and **1767** system/request examples green, rubocop clean across 690 files, erb_lint clean. |\n
| `1fc9e1f58` | **Measured what is wrong with the manufacturer donations report, and previewed a redesign.** Reported: the page does not look right. Six faults, four of them the same thing -- **it is the one report that is not a table**. The list is a `<div class="manufacturer">` per row and **that class is defined nowhere**, so the only link into a manufacturer renders in near-black with no underline and does not look like a link. **`(2,901)` has no unit**: it is `sum(line_items.quantity)` -- *items*, not donations -- while the model calls the column `donation_count`, and the stat directly above reads *Items donated 2,901*, so the page shows one figure twice and labels it once. **A date it has and never shows**: the query already selects `max(donations.issued_at) as donation_date` and orders by it, so the reader gets a list in date order with no dates in it. **Capped at 10 silently** by `by_donation_date(10, …)`. Plus *"1 Manufacturer"* from `pluralize(1, "Manufacturer")` under a label already reading *Manufacturers donating* -- the word twice and a capital M against sentence case -- and **New donation** sitting in the card body where page actions do not go. Options at `docs/mockups/manufacturer-donations.html`: **A** make it a table like the other five reports, which fixes four faults at once because the missing unit, date, total and scannability are all consequences of having no columns; **B** the same table with a rank and an in-row **share bar**, which is what GA4's report tables and Stripe's breakdowns do for "top N by a measure" and which scales to any number of rows, unlike a series per manufacturer; **C** a chart, named and rejected on the rule already written down -- the row count comes from the data. Recommended **A with B's share bar**. One open question in the preview: the query orders by most recent donation and B sorts largest first, and I would keep largest first with the date in its own column. Awaiting a choice. |\n
| `8c6cb11ca` | **The manufacturer report becomes a table, with a share bar in the row.** Built A with B's share bar. **Four of the page's six faults were one fault** -- it was the only report in the app that was not a table -- and a table fixed all four **without computing anything new**: `donation_date` was already selected and ordered by and never shown, and `sum(line_items.quantity)` was already there and printed bare. **Two renames that were corrections**: `donation_count` → **`items_donated`**, since it sums quantities and the old name had the page printing an items figure as though it counted donations, directly beneath a stat labelled *Items donated* holding the same number; and `by_donation_date` → **`donating_in`**, because the order is now largest first -- the page summarises who gives most, the period is the date filter's job, and the old ordering was invisible since no dates were shown. **The share bar rather than a chart**: a bar per row scales to any number of rows where a series per manufacturer would be a count taken from the data, and the bar is `aria-hidden` with the percentage as its text alternative -- verified at 390px, where the track collapses to **0px** and the cell still reads *SHARE 80%*. **Two faults a table alone would not have fixed**: *New donation* was in the card body, so `shared/filtered_card` takes an `actions:` local now and every report can put a page action in the header; and *"Manufacturers donating: 1 Manufacturer"* repeated its own label and capitalised a word mid-value. **Three things measured on the way**: `.size` on a grouped relation returns a **Hash of group counts**, not a number, which is why the count says `.count.size` and the controller hands the view an array; the model spec's example named *"in order of their most recent donation"* used **`match_array`, which ignores order** and so asserted nothing; and two request specs asserted the old rendering, rewritten to the new design rather than the code bent to keep them green. Verified: 8 new system examples, **1469** non-system and **1775** system/request green, axe **0 violations across 155 pages**, table audit clean, rubocop clean across 691 files, erb_lint clean. |\n
| `72ea16b0f` | **Four faults on the History page, and the audit that reported none of them.** Reported together: a funnel button next to *Refers to* whose effect and reversal were both unclear, "the scroll bar is stuck on the item drop down", an icon button with no label or tooltip, and "the alignment looks wrong". Four separate faults on one screen, all four fixed and each pinned by an example verified to fail when reverted. **The funnel is a row action now**: `essentials_row_icon_link` in a `cell-actions` column, 28x28 with `aria-label` *and* `data-tooltip`, against a hand-rolled 34x30 ghost button sitting inline in the *Refers to* cell three pixels from a 24px link, in the table's narrowest column (93px), on 24 of the 25 rows. Moving it made the table **narrower** -- 107px of hidden columns became **45px** at 1440 -- because the snapshot row had been stretching *From location* to 202px with a dump that did not belong there. **The narrowing is a filter the bar can see.** It submitted `?eventable_id=` as a bare param outside the form, so nothing counted it, no chip appeared, *Clear all* could not undo it and the only way back was the browser's Back button; it goes in through a new `hidden_fields:` slot with `data-filter-label`, `data-filter-display` (an id chips as *Refers to: Adjustment 12*) and `data-filter-group` so the type and id clear as one thing. The controller now tests `params[:eventable_id].present?` -- clearing the chip submits `""`, which is truthy in Ruby and narrowed the page to the events of record `""`. **The stuck scrollbar was a rail outliving its table**: rails live on `document.body` keyed on their region, `markAll` only visits regions still in the document, so every Turbo frame swap stranded one -- one rail before filtering, **two** after, at y=876 and y=832. `sweep()` drops them. **The snapshot row was a column out of true**, rendering its whole location-and-quantity dump under *From location* with *Items* empty, at 97px against 55px, and formatting its date with `to_s` where every other row uses `strftime`. **`title="Internal Event ID: N"` removed** from 24 cells -- browser chrome, silent on keyboard focus, and an internal id a diaper bank has no use for. **The tooltip audit reported 0 defects while there were 14**, because it read `main .cell-actions` on 25 hardcoded pages: both halves of that scope were wrong in the same way, since the rule is about an icon-only control rather than about where one sits, and a hardcoded list goes stale in silence. It walks all **153** screens `route-targets.rb` knows about now and reads every control whose visible text is empty -- **640** icon-only controls against 364 -- which also found the barcode-scan button untooltipped on nine `/new` and `/edit` forms. A chip's x is exempt, **declared** with `data-chip-dismiss` rather than inferred: the obvious test, *its parent has visible text*, would have exempted the `/events` funnel too. `row-actions-audit.js` separates "rows with actions disagree" (a defect) from "some rows carry no action" (an advisory) -- a SnapshotEvent has no `eventable` to narrow to. **Three versions of the rail spec passed with the fix reverted** before one caught it: the funnel is a plain link and Turbo Drive is off, so clicking it reloads the page and strands nothing; then a rail *count* was satisfied by one stranded rail plus no live one; then `evaluate_script` read the page before `turbo:frame-load` had laid the new rail out. Also fixed: `"No Name Provided"` -> `"Not recorded"` in both row partials. Verified: **848** system examples green, `tooltip-audit.js` 0 defects across 153 screens, `row-actions-audit.js` and `table-audit.js` clean, `template-compile-audit.rb` clean across 433 templates, rubocop and `erb_lint` clean. |
| `d0046ca11` | **Two standing `page-audit` findings, and the rule that was wrong rather than the code.** The audit reported an inline style in `shared/_highcharts.html.erb` and in the manufacturer report's share bar, and had done since each was written. Its own comment says it fails *a hardcoded inline style*; the implementation was `src.scan(/style=['\"]/)`, which counts every style attribute there is -- so two **data bindings** were being reported as presentation, and a finding that is always there and always fine is how an audit stops being read. **Neither can be a class.** Tailwind compiles the classes it can see in the source, so a share percentage computed per row names nothing; and the chart height has to reach the reserved box *and* the `height` in the chart's JSON config from one Ruby local, so a class would be a second copy of the number and the two disagreeing is the fault reserving the box exists to prevent. `<meter>` was considered for the bar and rejected on vendor-specific styling, its semantics already being carried by the percentage beside it. **The line is drawn at the custom property**: the markup carries a value (`style="--share-fill: 37.2%"`), the stylesheet carries the declaration (`width: var(--share-fill, 0%)`), and a custom property cannot style anything on its own. The audit checks every declaration in the attribute now -- verified by planting `style="color: red"`, `style="--ok: 1px; color: red"` and `style="<%= \"color: red\" %>"` and confirming all three are still reported. Deliberately **not** "does it contain ERB", which would make the rule about how a string was built and would let that third one through. **A spec was asserting the wrong half**: `manufacturer_report_system_spec` checked the bar exists and the figure says 83%, never that the bar is 83% long -- with the width moving into the stylesheet, an unfilled bar would have looked exactly like a pass. It measures drawn width against the track now and fails at 100 with the CSS rule removed; `layout_shift_system_spec` already covered the chart box and fails on both charts without `.chart-box`. **design.md had no rule about inline styles at all** -- the constraint lived only inside an audit, enforced more strictly than it was written; it is a Foundations section, *A value is not a style*. Verified: `page-audit.rb` 0 defects, `undefined-classes.py` clean, 848 system examples green. |
| `5373291a2` | **Address fields: one definition across seven screens, and a ZIP column that was losing data.** Reported on the vendor form -- its address box does not match the address/city/state shape used elsewhere. The app collected an address in **five shapes across seven screens**. `AddressHelper::ADDRESS_FIELDS` owns the label and the WCAG 1.3.5 autocomplete token for each part now, and `address_field(role)` hands them to simple_form; six screens call it, and a form that writes its own `label:` for part of an address has drifted by definition. **17 address inputs measured across the 7 screens, and not one `autocomplete` attribute between them** -- a AA criterion failing everywhere, and the largest usability gain available on a form a volunteer fills in repeatedly. The tokens are not interchangeable and that is the part usually got wrong: `street-address` is defined as a *multi-line whole* address, so a two-line form uses `address-line1`/`address-line2`, and city/state are `address-level2`/`address-level1`. **The integer ZIP was losing data, not just looking untidy**: `partner_profiles.program_zip_code` was an `integer` while `zip_code` beside it was a string, so `\"04194\".to_i` is `4194` and every ZIP in MA, RI, NH, ME, VT, CT, NJ and Puerto Rico was silently truncated, with ZIP+4 impossible -- **4 of the 7 string zip_codes use ZIP+4**, so it is the normal case here, and **2 of 5** program values were already damaged. Migration `20260901180000` changes the type and pads values under five digits back out, which is the exact inverse of the cast that broke them; it is reversible, and `safety_assured` is justified in the file on the table holding one row per partner. **State was a free text box on the partner profile** while `us_states` sat unused in a helper and the organization form has offered the 51 as a select all along. **One spelling of ZIP** across nine views (\"Zip code\", \"Zipcode\", \"Zip Code\", \"zip code\"), and two `<dt>`s on the profile page that both read \"Program Address\" now say which line is which. New **`bin/design/address-audit.js`** reads each field's role off its **name** rather than from a list of pages -- the lesson from the tooltip audit's hardcoded list -- and checks the token, that a state is chosen and never typed, that a ZIP is text with a numeric inputmode, and that the label ends in the app's word for the part. It found **two things the manual sweep missed**: the family form's guardian ZIP, and that the program ZIP was still `type=number` until the server picked up the new schema. Verified by planting six defects and confirming each is reported. **Two exemptions, both declared rather than inferred**: `third_party: true` renders `autocomplete=\"off\"` for an address that is not the filler's own -- a partner typing a client's ZIP -- and printed rather than waved through; and a label may be *qualified* (\"Guardian ZIP code\") so the check is ends-with, not equality. `spec/helpers/address_helper_spec.rb` pins the audit's JavaScript table against the Ruby one, verified to fail when either moves. **Left open and previewed, not quietly skipped**: whether the four freeform `address` columns become four fields. See `docs/mockups/address-fields.html` -- it is a schema migration on four tables, four CSV templates banks keep local copies of, and a parse that succeeds on **10 of 18** seed rows. Verified: **1780** system and request and **1475** unit examples green, `address-audit.js` 0 findings across 26 fields, copy/page/form-validation audits clean, rubocop and `erb_lint` clean. |
| `55798e633` | **Option B: four address fields, and a CSV that still takes one column.** Chosen from `docs/mockups/address-fields.html`. `Vendor`, `DonationSite`, `ProductDriveParticipant` and `StorageLocation` each stored one freeform `address` string; they store `street`, `city`, `state` and `zipcode` now through a new **`StructuredAddress`** concern, which is `Organization`'s long-standing pattern extracted -- `#address` composes \"street, city, ST zip\" for the geocoder and the four PDFs, `#address_changed?` answers `Geocodable`, and `#address=` parses. **The CSV import templates deliberately did not change**: `import_csv` does `new(row.to_hash)`, so a bank's saved template with one `address` column is still valid and the importers were not touched at all. Option C changed the templates and lost on that alone -- 200+ organizations keep local copies, and a stale file would fail at the moment they are least able to debug it. A spec pins the property and was verified to fail when `#address=` is removed. **The parser refuses to guess.** It reads from the end inwards, where the shape is: a ZIP is unmistakable, a state is one of 51 known codes, the last comma separates city from street. A two-letter word that is not a state code stays part of the street, and an address with no comma keeps its street whole rather than having a city invented from the last two words -- which matters because **every vendor in the seed database is written that way**. The invariant is that nothing is discarded: anything unplaced stays in `street`, so the worst case is a city to fill in by hand. Measured over the backfill: **18 of 18 addresses compose back to exactly the string they were**, 10 of 18 split into all four parts. The migration carries its own copy of the parser, the house pattern set by `20260612120000`, because a migration must work with no application code around it -- the two were verified identical on all 26 inputs. **The `address` column is not dropped**, only `ignored_columns`; dropping it is a separate release so a deploy does not leave an old process reading a column that has vanished. `RemoveAddressFromProviders` is named in migration-map.md as the only thing left. The audit gained a rule that **guards this decision: a single freeform `address` input is now a finding** -- verified by putting one back on the vendor form and watching it fail. Eleven system examples said `fill_in \"Address\"`; they say `fill_in_address` now, a helper that splits with the same parser the app uses, so a spec cannot pass with an address the app would read differently. **A miss recorded rather than buried**: the previous commit reported the suite green after changing `program_zip_code` to a string, and it was -- against a *stale test schema*. Two examples asserting `eq(80401)` were still passing against an integer column and failed the moment `db:test:prepare` caught up. A suite run after a migration is not evidence until the test database has the migration too. Verified: **3269** examples green (the whole suite), `address-audit.js` 0 findings across **50** fields, page/copy/template-compile audits clean, rubocop clean across 696 files, `erb_lint` clean. |
| `188e7fd45` | **`RemoveAddressFromProviders`: the freeform `address` column dropped.** Asked for directly, and the second half of `20260901185000`. The four models have stored `street`, `city`, `state` and `zipcode` since that migration, with `address` in `ignored_columns`, so nothing has read or written the column. **The concern was stated before running it and is recorded in the migration's own comment**: the two migrations are separate files because the gap between them is meant to be a *release*, so a rolling deploy finds the column still there for processes running the previous code. Collapsed into one release, that window is open for the length of the deploy -- a bounded cost, and the deploying team's call, but written down so nobody later reads two files and assumes the split was accidental. **The drop flushed out one thing `ignored_columns` had not**: `db/seeds.rb` looked donation sites up with `find_or_create_by!(address:)`, which kept working for the whole previous release because `ignored_columns` hides an *attribute* while the SQL still resolves against a column that exists -- so it would have failed at the drop and not before. It keys on name and organization now, the model's own uniqueness rule, and a better key regardless since two organizations may collect at one address. I swept for the whole class first rather than after: `find_by(address`, `where(address`, `pluck(:address)`, `order(:address)` and raw SQL across `app/`, `lib/`, `db/` and `spec/` -- **one hit, and it was the seed**. The rule is now in design.md and domain-model.md: `#address` is a method, not a column, so it cannot appear in a query. Migration verified **reversible with its data**: rolling back restores the column and repopulates it from the four parts. `ignored_columns` stays one more release for the mirror-image reason -- new code meeting an un-migrated database -- and is the last thing left of this change. Verified: **2421** unit and request examples green, 848 system, addresses read and write correctly on all four models with the column gone. |
| `266c15e57` | **WCAG audit of the whole app: the suite was clean against a superseded standard.** axe reported 0 violations on 155 screens, the keyboard audit 0 on 142, the manual criteria 0. All true, and all against **WCAG 2.1** -- a W3C Recommendation superseded by 2.2 in October 2023, which adds six A/AA criteria. The app already met one (2.5.8 Target Size) and had **no check for the other five**. New `bin/design/wcag22-audit.js` covers 2.4.11, 2.5.7, 3.2.6, 3.3.7 and 3.3.8. **2.4.11 Focus Not Obscured (Minimum), AA, was failing on five screens**: the scroll rail is `position: fixed` at the bottom of the window and a browser scrolls a newly focused element only far enough to touch that edge -- measured on `/items/quantity_and_location` at 1280x900, a focused link at y=876 height 24 with the rail at y=876, entirely covered; a sixth came from the frozen actions column at the right edge. Fixed with `scroll-padding` on `html` and `.table-scroll`, taking the rail's height and the two column widths the scroll controller already measures, so they cannot drift. Reverting brings back exactly the four rail failures and not the column one, which attributes each fix. **A sample of eight was hiding fourteen more failures.** `wcag-manual.js` visited 8 pages against axe's 155, and 2.4.2 is partly a question about *uniqueness*, which eight cannot answer about a hundred and fifty. Its cheap checks now run over **92** screens and found **14 pages failing 2.4.2**: five reports and five account-request screens had no `content_for :title` at all, the annual-reports index reused the hub's title, the broadcast index and its form shared one. All titled. It had also been **crashing on the third page of its own list** on a `networkidle` wait, so the eight it claimed had lately been two. **Three of my own new checks were wrong first, and each is written up where it lives**: 2.5.7 clicked the rail at a fixed 85% of the track and hit the thumb where the thumb fills 95% of it, then failed again because the audit's own tab-through had already scrolled the table to its limit; 3.2.6 measured the help link as a *fraction* of a page's focusables, so one place looked like two, and matched on an href that is role-dependent so it tested nothing for two of three roles; and **3.3.7 was named in the header and printed in the pass line with no check behind it at all**. Every check is now proved by planting the defect it catches -- track handler removed, a link added after the help link, `onpaste=\"return false\", `copy_from_request` deleted -- and all fired. Two more false positives came out of the widening: 2.4.1 flagged five autofocused forms because **`blur()` does not move the sequential focus navigation starting point**, and two standalone pages whose whole repeated header is three links -- so the requirement is scaled to what there is to skip (more than five controls before `main`) rather than excusing pages by name. **design.md now carries the full 55-criterion coverage table**, naming what verifies each one; the eleven marked not applicable were each checked rather than assumed (no media elements, no orientation lock, no `setInterval`, a 7-day session which 2.2.1 exempts, one language per document, and Escape as the only document-level key, which is not a character so 2.1.4 does not apply). The stated target is **WCAG 2.2 AA**. New `spec/system/focus_not_obscured_system_spec.rb`, both examples verified to fail when the CSS is reverted. Verified: **3271** examples green, axe 0 across 155 screens, keyboard 0 across 142, wcag-manual 0 across 92, wcag22 0 across 150. |
| `a4b058c21` | **The slow WCAG target: every check over every screen, and ten more page titles.** `wcag-manual.js --all` runs the expensive checks -- reflow, 200% zoom, text spacing, a full tab traverse -- over all **139** screens in all three roles, against the 8-page sample the default uses. A flag rather than a second script, because a copy drifts: the checks are defined once and the scope is an argument. Measured: default **38s**, `--all` **4.5 minutes** -- my pre-measurement estimate was 40 minutes, wrong by an order of magnitude. **Sampling is least defensible for exactly these checks**, because reflow and text-spacing failures come from a page's content rather than from the layout system. It found **2.4.2 failing on ten more pages**, all admin and partner screens the earlier single-role pass never visited: a partner's help page titled after the *bank* rather than the agency, `/admin/questions` with no title at all, three admin forms sharing their index's title, two partner show pages inheriting their index's. All fixed. **Three of the findings were the audit's fault, and two would have produced a fix for something never broken.** 1.4.12 reported `sr-only` labels on two partner forms as clipped -- 1px wide with `overflow: hidden`, the visually-hidden technique working correctly, and clipped *before* the spacing too; the check measures before and after and reports the difference now. 2.4.7 reported `/privacypolicy`, and kept reporting it after a focus ring was added, which is what forced the question: the check read `getComputedStyle` in the same tick as `focus()` and caught the style mid-recalc. With two frames between them it measures correctly -- **and with the author rule removed entirely Chromium still paints `auto 1px`, so 2.4.7 was never failing**. The CSS stays as a consistency improvement and its comment now says so rather than claiming a fix. 2.4.2 on `/admin` vs `/admin/dashboard` is one action at two paths with no redirect, so the target list is deduped on `controller#action`. That is five false positives from new or widened checks in two days: **a new check's first findings are evidence about the check**. Each was reproduced by hand before anything changed, and each corrected check re-proved by planting the defect it catches -- which is how the 2.4.7 artifact was caught, because after the timing fix the planted defect stopped reproducing. Two more holes closed in the audit itself: a page returning **500 is now reported rather than skipped** -- a bad `content_for :title` I wrote produced a 500 on `/partners/children/1`, the audit skipped it in silence and the *test suite* is what caught it, so an audit that stops looking at what it cannot load was reporting its own blind spot as a pass; and the skip-link check **polls for focus to reach main** instead of reading once after a fixed pause, which was failing on the slowest screen about one run in three. Both proved: breaking a view now reports `server error /partners/children/1: HTTP 500`, and `--all` is clean across two consecutive runs. Verified: `wcag-manual --all` 0 failures across 140 screens, twice, default run 0 three times, axe 0 across 155, `wcag22-audit` 0 across 150, **3271** examples green, rubocop and `erb_lint` clean. |
| `dc0b97093` | **Auditing the audits: two controls per check, because planting a defect cannot catch a false positive.** Five checks reported failures the app did not have in two days, and all five *were* tested the usual way -- plant the defect, watch it fire, revert -- and all five passed that test. **A check that fires when it should not still fires when it should.** New `bin/design/audit-selftest.js` gives each check a **positive** control (break the page, the check must report) and a **negative** control (change the page benignly, the check must stay silent). The negative one is what was missing, and the claim was checked before building on it: all five incidents are benign pages being flagged, so all five would have failed a negative control -- a table that only just overflows, a region an earlier check had scrolled, a longer page with the same nav, an `sr-only` label, a transitioned focus ring. Mutations are injected into a live page rather than written to app files: reversible, fast, and impossible to leave in a working tree. Both WCAG audits are importable now (a swappable sink, `require.main` guard) so the harness drives one check at a time. **Building it found three more problems, all in my own controls**: a `body::after` overlay that `elementFromPoint` cannot see (so the check saw `BODY`, which contains everything); a \"barely overflows\" control that widened the region and pushed the rail off screen, testing the viewport rather than the check; and a box sized from a block element's `scrollWidth`, which is the *container's* width, so nothing ever clipped. Same taxonomy one level up. **The second half is a vacuous-pass guard**, because a check that does nothing is silent on both controls: each check counts what it examined and the run prints the tally -- `2.4.11x150  2.5.7x20  3.2.6x143  3.3.7x1  3.3.8x3` -- and **a zero is a finding**. Verified by breaking a selector: `2.5.7x0`, reported as `EXAMINED NOTHING`. That also catches the quieter version that actually happened, where `consistentHelp` matched an href only one of three roles has and silently tested nothing on 114 pages. design.md carries the six failure modes these came from -- vacuous pass, no baseline, read before settle, order dependence, fixture assumption, wrong metric -- so the next check is written against them. **Named and not claimed**: a negative control only covers the benign case somebody thought of, so this does not prevent a sixth failure mode; the narrower claim is that the five that happened cannot happen again silently. Verified: **11 controls over 5 checks, 0 wrong**; `wcag22-audit` 0 across 150 screens; `wcag-manual` 0 default and 0 across 140 with `--all`; **3271** examples green; rubocop clean across 697 files. |
| `df8a3e8db` | **The audit self-test runs in CI, on every push and pull request.** New `.github/workflows/audit-selftest.yml` — the only workflow that boots a real server and drives it with Playwright, which is why it is its own job rather than a step in `rspec-system`: that suite runs the app in-process through Cuprite, and porting the checks would mean two implementations of each, the drift the harness exists to prevent. **`development`, not `test`**, because it is the environment the audits are written against and because `Geocodable` skips geocoding there — measured, seeding under `test` takes 46s and makes real HTTP calls to the geocoder, under `development` 25s and none. A CI job that talks to a third party to build its fixtures goes red for reasons unrelated to the change. **The controls now build their own preconditions, and this is the part that would have shipped broken**: the harness was written against a development database with a session's worth of data, where `/distributions` overflows and grows a scroll rail; on a freshly seeded database it does not, `.table-rail-track` was null and half the controls threw. Caught by validating the whole chain locally against a scratch database — create, schema, seed, boot, run — which is the only reason it was not a red build on the first PR after merge. The controls widen the table themselves and wait for the app's own controller to build the rail, so they exercise the checks rather than the data. **`bin/` is deliberately absent from this workflow's `paths-ignore`** where the other three exclude it: the audits live in `bin/design/` and a filter that skipped them would leave the job running on everything except the thing it tests. Measured end to end: schema 2s, seed 25s, stylesheet 1s, boot 3s, self-test 11s, with the Chromium download dominating. **Not done and deliberately**: the audits themselves are not in CI, only their self-test — they read seeded data and answer \"is the app accessible today\" rather than \"is this change sound\", which is better asked deliberately than on every push. Verified: 11 controls, 0 wrong, against both a freshly seeded scratch database and the development one; npm resolves Playwright from `bin/design/` with no `package.json` present; workflow YAML parses. |
| `ceaa1c261` | **The four skill questions answered, and a correction to my own coupling figures.** `docs/skill-proposal-v2.md`. **The correction matters most**: v1 said 22 of 33 audits encode the stack and 11 reference this app's models, measured with a crude grep that counted mentions of app vocabulary and read them as coupling. Almost every hit is a **hardcoded page list** or a seed email. Measured properly: **23 of 33 are browser-driven** and need exactly five things from the app — base URL, sign-in path, two field selectors, a credential — plus a list of URLs; 8 Ruby and 2 Python audits read source and are genuinely stack-bound. **So stack-agnostic is achievable for most of the value, and as a layer rather than a second document** — two documents drift, which this project proved and then guarded with a spec that fails when the Ruby and JavaScript copies of one table disagree. The adapter is two things: the five sign-in values, and a command printing every screen as JSON. **A prerequisite fell out of the analysis**: only 6 of the 23 browser audits enumerate routes from the router, the other 17 carry hardcoded lists, and every scope failure in this project's record came from exactly that — so migrating them is the first step, in this repo, for this app's benefit. **Personal vs repository**: develop in `.claude/skills/` where it is versioned and reviewable, symlink into `~/.claude/skills/` for use elsewhere, extract to its own repository once a second app has exercised it. **Greenfield and brownfield stay one skill** — four files of difference against a shared core, greenfield becomes brownfield by week three, and the expensive lessons are not migration-specific. **Prescriptive like GOV.UK**, which is the one of the five big systems that publishes its evidence and a design history rather than a component catalogue — with every rule tagged **Portable** or **Local**, because a design system can say \"buttons are 40px\" flatly and a cross-app skill cannot. When in doubt, Local: an under-claimed rule costs a decision, an over-claimed one costs a wrong implementation that looks authorised. v1 annotated in place rather than rewritten. |
| `278cbd1a8` | **Every instruction on the project, collected and sorted — and a proposal for the skill, not the skill.** `docs/prompt-history.md` holds all **199 prompts** from 22 August to 2 September, read out of the three Claude Code transcripts for this repository and filtered to records that are a person typing — tool results, system reminders, hook output and compaction summaries excluded. Grammar, punctuation and dictation artefacts cleaned (\"Syed NAV\" for *side nav*, \"Moodle\" for *modal*, \"next year refers to\" for *next to Refers to*); the ask, scope, reasoning and tone left alone, including the two places frustration is on the record. Sorted into ten categories, every prompt tagged with its transcript position so it can be found again, and **verified programmatically that all 199 appear** — the counts in the summary table are measured, and the rows sum to 214 because fifteen prompts genuinely belong to two categories. The shape: **79 defect reports found by using the app**, 56 choices between presented options, 23 requests for research and a preview, 11 app-wide sweeps, and only 3 about rigour — which changed the work more than any of the others. `docs/skill-proposal.md` is the recommendation asked for *before* building: a ~900-line skill of one short entry point plus reference files loaded on demand, against the 16,377 lines of documentation and 33 audits this project produced. **Include** the five-demand loop, the audit-discipline lessons, the route enumerator, the self-test harness and empty document templates; **exclude** design.md's content, 22 of the 33 audits (11 reference this app's models by name and most assume Rails, Propshaft, Tailwind and Cuprite) and the migration map. Three scope options with B recommended, and C deferred until a second app exists to generalise *from* — because generalising from one system is a mistake this project already made once, at prompt `[158]`, and it cost 28 unevidenced claims. Four open questions raised rather than assumed: the next app's stack, personal or repository skill, migration or greenfield, and how prescriptive the design rules should be. |
| `f6cab8e43` | **Route enumeration across the audit suite, and the enumerator's own blind spot.** Step one of the skill proposal, done for this app's benefit. New `bin/design/targets.js` is the single seam to the application -- the screen list, the three roles, `signIn`, `visit` -- able to replace **21 hand-copied `signIn` functions**, seven copies of the role predicates and six of the targets read — *able to*, and this row originally said "replacing", which was wrong: seven audits were migrated that day and **16 files still carried their own `signIn` on 2026-09-04**, at least two of them byte-identical. Corrected when the adapter work re-measured it; four copies had drifted, one not signing out (so a second role silently audited the first's pages) and one waiting on `networkidle`. Seven audits migrated: disclosure 5 pages to 151, flash-of-hidden 10 to 150, table 26 to 151, button 43 to 89 headers across four roles, tab-set from three hand-written sets to **discovering** them from the page. **The count was wrong twice before starting** -- the proposal said 17, then 14; the real number was 7, because my grep looked for `targets.json` and missed every audit already shelling out to the generator. Same mistake twice: grep one spelling, read absence as fact. **`button-audit` found six real violations** on show pages its index-only list never visited -- `/donations/1` and `/purchases/1` emitted the primary action second, and `/requests/1` gave the last slot to the destructive Cancel, exactly the fault reported at prompt `[163]` for `/product_drives` and fixed there but nowhere else. **The enumerator itself was missing a screen**: `SKIP_ACTION` matches bare action names, so `inventory` -- there for a storage-locations partial -- also skipped `items#inventory`, a full screen in the item catalogue's tab strip, leaving *every* audit blind to it. Controller-specific skips are `SKIP_PAIR` now; 153 screens becomes 154. **`sweep.js` deleted**, not migrated: `route-sweep.js` does every one of its checks. Three findings were the audits' fault, each confirmed by measuring first -- a trigger in a collapsed accordion has no box and matches no grid column; a page can show a tab strip without being one of its tabs; and `/partners/1/approve_application` redirects to `/partners` carrying a flash bar that puts the strip 72px lower. **`overlay-audit` was widened and reverted**, for a reason that is a measurement I skipped: it takes **525 seconds for nine pages**, 58 a page, and always has -- so four attempts to fix the widening were four attempts at the wrong problem. It is the one audit still carrying a hardcoded list, the README says so, and its header records the evidence. Verified: **3271** examples green, rubocop clean across 697 files, `erb_lint` clean. |
| `92dbdb80d` | **The skill files were not actually committed, and the row above said they were.** `.claude` is gitignored — local Claude Code settings and session state — so the ten files written in the previous commit existed on disk and in no commit at all, unprotected against the rollback that has hit this tree six times. `.gitignore` now reads `.claude/*` with `!.claude/skills/`, because **git cannot re-include anything inside a directory that is itself excluded**: the directory has to stay visible for the exception to work. Verified that exactly the ten skill files are tracked and no local state came with them. The distinction is the one in the proposal: a skill in the repository is versioned, reviewed in pull requests and available to anyone who clones; one in a home directory is none of those. |
| `e2f8c96d7` | **Three of the ten prompt categories were missing from the skill, and the ask was to build it *from* them.** Checked rather than assumed, and the gap was real: **copy and language had zero coverage — not a mention** — setup and environment had two incidental references, and the shape of an engagement was absent entirely. The loop was stated as rules without any account of how the work arrives. Added `reference/copy-and-language.md` (sentence case and the acronym exception, helper text that says something the title cannot, second person and never \"we\", the inclusive-language list as a *check* rather than a review, two-to-three word buttons because WCAG 2.4.4 is Link Purpose *In Context*, and error messages that name the record, the reason and the next step); `reference/keeping-work-reviewable.md` (keep the server up, seed enough data to see the thing, serve previews over HTTP and print a URL never a path, say how to test it, confirm before anything destructive); and a **How the work actually arrives** section in `SKILL.md` — that it comes from somebody opening a page, that one message carries four compounded demands and answering one produces the same instruction next week, that a single report often names four unrelated faults, that frustration is feedback about method (\"why do I need to point out elements individually\" means the sweep was too narrow), that **the riders on a choice are where the rules come from**, and that the work moves outward from components to screens to the tools themselves. Verified: all ten categories now resolve to a file. |
| `6ef25c98d` | **Four more skills, in the recommended order, and the design skill loses its duplicate.** `.claude/skills/` now holds five, **972 lines** total. **`audit-suite`** first and largest, because nothing in it is specific to design, a browser or a language: an audit is a rule you can run *and a claim about what it looked at*, and it is the second that nobody checks. It carries the three scope failures, revert-testing, the counter-intuitive one — **planting a defect cannot catch a false positive**, with the five that a negative control would have caught — the six ways a check lies, and measure-the-baseline. `reference/control-harness.md` covers building the two-control suite, including that **your controls will be wrong too**: three of the first ones written were fixture assumptions and a wrong metric, the same taxonomy one level up. **`design-system-migration` deletes its own `audit-discipline.md` and points at the new skill** — two copies of one thing is how they drift, which is the argument that skill itself makes. **`evidence-discipline`**: measure in the session you write it, a grep is not a measurement, keep provenance, correct by annotating, name what you chose not to do — with the three wrong numbers this project produced and a table of phrasings that usually mean a claim was not checked. **`wcag-conformance`**: WCAG 2.2 has been a Recommendation since October 2023 and most suites still target 2.1; the six added criteria, why 2.4.11 is the one most apps fail, the two measurement traps that produced false failures here, and why sampling is *least* defensible for the expensive checks. **`session-durability`**: commit and push at every checkpoint, and a reverted tree does not look like a bug — `git status` looks plausible and `HEAD` has not moved, so the reflex is to debug the fix rather than the tree. Cross-linked rather than duplicated, and every reference verified to resolve. |
| `82af3e607` | **The skill, built — and the tangent that delayed it recorded as to-do.** `.claude/skills/design-system-migration/`: `SKILL.md` (116 lines) plus five reference files loaded on demand and four empty templates, **552 lines** against the 16,377 of documentation and 33 audits this project produced. Option B from `skill-proposal-v2.md`, with the Portable/Local tagging on every rule so this app's arbitrary constants -- 28px row icons, a four-item comparison cap -- cannot be cargo-culted onto an app where they are wrong. The loop is the five demands the prompt history shows recurring in almost every substantive instruction: read the spec, find what the industry does, preview before building, apply it everywhere, write the decision down. **`reference/audit-discipline.md` is the substance** -- scope-is-a-claim with the three incidents that proved it, revert-testing, positive *and negative* controls with the table of five false positives a negative control would have caught, the six named ways a check lies, and measure-the-baseline-before-you-optimise with the 525-seconds-for-nine-pages story. Greenfield and brownfield stay one skill: `retiring-a-legacy-system.md` simply does not load when there is no legacy. **`docs/todo.md` gains the `overlay-audit` entry** with everything measured -- 58 seconds a page, 203ms of it navigation, 31 seconds of it `/organization` -- so picking it up does not start with re-deriving it. Not done: the Rails/Tailwind adapter, deliberately, until the core has been used once on another app. |
| `77c8a0bd4` | **Five verified findings were never written down, and one entry had gone stale.** Asked what was outstanding, and the honest answer needed the list fixing first. **Added**: the skills are only active in this repository and nothing has been written to `~/.claude/skills/` (reminder requested rather than run, with the symlink-versus-copy tradeoff and the one thing unverified — whether this client reads that directory at all); **24** Title Case labels on the partner profile forms, measured, sitting outside a normative rule because `page-audit.rb` enforces sentence case on *headings only*; **seven** dead anchors in design.md, down from twelve; `ignored_columns` for the dropped address column, now a no-op and the last thing left of that change; and the skill's missing Rails adapter, deferred until the core has been used on a second app. **Corrected**: the distributions-columns entry claimed Actions was 331px and needed an overflow menu this app did not have. `row_actions` was built during the migration and the column measures **76px** — a 255px saving against the 251 predicted, and the table is 1,521px against 1,759. It still scrolls by 403px, so the entry now says which half is done and that what remains is a *data* decision about dropping columns, not a layout one. A to-do that is silently complete is worse than none, because it makes the rest of the list untrustworthy. |
| `f4479ea26` | **The overlay audit: 58 seconds a page to 1.6, and the cause was three empty catch blocks.** It had always been slow — 525s for nine screens — and four earlier rounds of optimisation had all addressed the widening rather than the audit. **The cause was `element.click().catch(() => {})`**: Playwright retries an unclickable element until its default **30-second** timeout and an empty catch hides it. Measured on `/organization`, **30,335ms** in `checkNativeConfirms` for seven triggers that are menu items in a *closed* kebab and have no box; the same pattern on the filter disclosure cost 30s on every screen without a filter bar. Two visits per screen at ~30s each is the 58. Found by timing the baseline, then each phase, then each step, then splitting what the timer covered — and by rejecting four hypotheses cheaply on the way: `networkidle` (0.7–1.4s here), axe injection (fixing it changed nothing), overlay count (9s at worst), a single pathological page (it was all of them). **Fixed**: `clickOrReport` with an explicit 2s timeout that **reports** a failed click, because a visible control that cannot be clicked is a real defect the empty catch was hiding as thoroughly as the delay; only rendered triggers are clicked, since a closed row menu still holds its Delete in the document and those are `confirm-audit.js`'s job; and fixed sleeps became condition waits — 100 popovers had been spending 57 seconds asleep. Then widened onto route enumeration like every other audit: **154 screens in 254s**, 20 dialogs and 456 popovers opened, no findings. Verified by stripping `aria-labelledby` from the shared modal partial and confirming the check reports it on every screen that renders one. **No audit in `bin/design/` carries a hardcoded page list now** — the two exceptions take a path on the command line or use a deliberate fixture. |
| `eb2a0039d` | **Two accessibility to-dos, one real and one wrong about itself.** **The account menu** carried `aria-expanded` with no `aria-controls` in both top bars, and the panel had no `id` to point at — a conformance gap against design.md's disclosure rule (line 447), not a missing convention, so no new rule was needed. The id is `SecureRandom.hex(4)` because both shells render one per page. Verified in the browser for bank and partner: the trigger's `aria-controls` resolves to the `role="menu"` panel before and after opening. **The family request form**'s entry claimed it *"shows only an error summary, with no inline errors and no `aria-invalid`"* and needed per-field rendering. Driving it showed both halves wrong: every error on that path is `errors.add(:base, …)` so **no field-level errors exist**, the only controls are 36 child checkboxes so **there is no field to mark invalid**, and the callout already gets `role="alert"` from `_callout`'s danger default. The real defect was copy — submitting with nobody selected returned *"Every line needs an item selected and a quantity greater than zero. Items that come in packs also need a unit chosen"*, naming **three fields that are not on the page**. `partners/requests/_error` is shared by three forms and that sentence is right for the other two, so the guidance became a caller-supplied local defaulting to the existing text — the two item-request forms render byte-identically, confirmed by rendering the partial both ways. **The guard is the negative assertion**: `not_to include("Every line needs an item selected")`, because the positive one passes just as well with the default restored. Watched it fail with the fix reverted before trusting it green. **Left deliberately, both in `docs/todo.md` with measurements**: `"completely empty request"` still reaches partners verbatim (a model validation, three specs assert the string, shared by all three request types), and **no error summary in this app is focused on re-render** — `document.activeElement` is `BODY` after a failing submit, which belongs to all **41** views that render one at once rather than to one page. **Recovered from the seventh workspace rollback**, which took `bin/workspace-check` itself; all commits were intact and pushed, and only the uncommitted account-menu edit was lost and redone. |
| `70bdc7a4f` | **The flake's reproduction had gone stale, and a real seeding bug turned up while looking for it.** The to-do carried `rspec --seed 43125` fails 7 examples, all `create(:kit)` raising `Validation failed: Name has already been taken`, and said the hard part was already done. That exact command now gives **3272 examples, 0 failures**; four further seeds (11111, 22222, 33333, 44444) are also clean, and **none of the five runs contains the string anywhere**. **A seed is only a reproduction against an identical set of loaded files** — RSpec shuffles the groups it loaded, so a permutation of a different list is a different order. **31 spec files have been added and 1 removed since the entry was written** (267 → 297), so the seed stopped selecting that ordering at roughly the next commit. The durable tool is `rspec --bisect`, which reduces a *currently failing* run to a minimal list of examples and does not rot when a file is added. **The bug found on the way**: `Item`'s name uniqueness has a custom message, so the default `"has already been taken"` had to come from `BaseItem`, the one model whose name uniqueness is unscoped. `Seeds.seed_base_items` passed `created_at`/`updated_at` to `find_or_create_by!`, which **builds its lookup from every attribute given to it** — so "created at this exact instant" went into the WHERE, no stored row could match, and the find fell through to a create that tripped the unique name. Written in the idiom for idempotency and not idempotent. `db/seeds.rb:27` calls it **unguarded**, so `bin/rails db:seed` raised on any already-seeded database — onboarding's `bin/setup # first time only` was documenting the bug as a design. The suite never hit it because the organization factory guards with `if BaseItem.count.zero?`, which is exactly what let it survive. Fixed by dropping the two timestamps; the guard stays as a 47-query saving and its comment now says **47** (46 JSON entries plus the global `Kit`) instead of 45. `spec/lib/seeds_spec.rb` covers it, watched failing with the real message first. **Not claimed to be the flake** — the factory guard means that path is not reached with a populated table in a spec run, so the to-do stays open with the bisect instructions rather than being closed on a fix that may be unrelated. |
| `dd6633691` | **The sideways swipe and the audit blind spot: neither existed, and the control that "proved" one was invalid.** **The page does not pan** — 320px and 375px across all 154 routes, nothing swipes; and checked properly by deleting `html { overflow-x: clip }` and rebuilding, still nothing (`root 320/320`, `body 320`). The layout no longer overflows the root, most likely from the `.notes` column cap, so the rule now guards nothing. **The audit was never blind**: the to-do said it "compares `scrollWidth` with `clientWidth`" and asked for a gesture check that watches the `h1` — that check was added in `cfeee9130` on **2026-08-21, three days before the entry claiming its absence was written**. `bodyOverflow` is its `else` branch. **The invalid control is the reusable part.** Deleting the clip rule and running the audit gave *no findings*, which reads exactly like a caught false negative — and is not one: nothing panned because nothing overflowed. **A guard and the condition it suppresses are two things, and a control needs both.** Only clip-off *plus* an injected 2000px element produced a real pan (900px, `h1` from `left: 16` to `left: -884`), which the audit reported as `swipes 900px sideways` first time. Written up in `audit-suite`'s control harness as its own failure mode, since the shape recurs far beyond CSS — a validation with no invalid record, a rate limiter with no traffic. **One real gap hardened**: the gesture sat inside `if (anchor)`, so a screen with no `<h1>` skipped it silently; **0 of 151** screens today, and in the tested case the `bodyOverflow` fallback still flagged it, so the old code was not blind there — the case it would truly miss is stated as reasoning, not measurement, because the pan can no longer be reproduced. Re-verified after: 429 combinations, same 2 findings, no new false positives. **Third to-do entry in a row wrong about its own subject**; what rots is the scope, not the measurement. |
| `a68fd8c2e` | **The error summary takes focus, across all 41 views that render one.** A validation failure re-rendered the form and left focus on `<body>` — measured first on `/manufacturers`, `/vendors` and `/storage_locations`: `activeElement` `BODY` on all three, no `tabindex`, `scrollY` 0 whether or not the summary was on screen. **`role="alert"` was never enough**, which is why this looked handled: a live region is defined in terms of a subtree *changing*, and with Turbo Drive off app-wide a failed submit is a full page load where the summary is already in the markup as the accessibility tree is built. Focus does not depend on that timing, and it puts a keyboard user *at* the errors. **The live region moved inside the focused element** — focusing something that is itself `role="alert"` reads its contents twice on several screen readers, so the focused container is a plain `div[tabindex=-1]` and the role sits on the wrapper within it, the shape GOV.UK's error summary settled on. New `error_summary_controller`, which **takes focus only from nothing** (`activeElement` must be `<body>` or `<html>`) so a frame update cannot steal a caret mid-typing — tested by focusing an input and injecting a summary. `shared/essentials/_callout` gains **`focusable:`**, one local rather than two because `tabindex` without moving the role gives the double announcement and moving the role without `tabindex` gives a live region nothing can focus; `partners/requests/_error` uses it. Focus ring is the app's `outline-2 outline-offset-2` in `brand-600`, not Chrome's 1px default, since focus moved *for* you is when you most need to see it. **Stated limit**: the mechanics are verified — focus lands, page scrolls, on four forms across both shells — the announcement follows the published pattern, because no screen reader can be driven here. Five system examples, each watched failing reverted, two of them negative assertions; **468 examples 0 failures**, axe **156 pages no violations**, `wcag22-audit` 151 screens no failures, `form-validation-audit` 26 forms no findings. |
| `26838e967` | **The "Current state" table refreshed, and the two documents that disagreed about it reconciled.** It had been pinned to 2026-08-28 / `d7543ecff` and recorded rather than fixed one commit earlier — the reason given (a table mixing two dates is worse than one uniformly old) argued for doing it properly, not for deferring it. **`migration-map.md` carried a second copy that had drifted further**: 299 of 392 views and 30 Stimulus controllers against the change log's 332 of 367 and 37. Both are now measured together and dated. Current: **624** commits, **1,078** files against `main`, 63 of 65 controllers on a design system layout, **346 of 383** views carrying design system markup, **45** Stimulus controllers, 0 undefined legacy classes, 0 of **350** routes that would raise, **149** dead-code findings. Audits re-run at this commit: `page-audit` 0 defects across 358 views, `route-sweep` 142 screens, axe 156 pages 0 violations, `wcag22` 151 screens, `overlay` 20 dialogs and 456 popovers across 154 screens, `form-validation` 26 forms, `undefined-classes` 0, `dead-routes` 0 of 350 — all clean. **`rubocop` found 1 offence, mine**: `Rails/FindEach` on `page.all(...).each`, a false positive since a Capybara result set has no `find_each`, rewritten rather than silenced. **The suite is not reliably green and the table no longer claims it is.** Three full runs gave a self-inflicted `PG::TRDeadlockDetected` (a second `rspec` against the same test database — an artefact, and it cost a run before being recognised), one `request_system_spec` failure with six `<<ERROR>>` stale-element reads that passes in isolation, and one clean run. **The same seed gave both a failure and a pass**, so it is timing rather than ordering; a genuine baseline at that seed without the day's changes was clean at 3,275. The callout change was proven a **no-op for every existing call site** by diffing the rendered partial — which also caught a stray space from an empty attribute, now gone. Recorded in `todo.md` as a second, distinct flake. |
| `0e5768f90` | **`table-audit.md` re-run after 17 days, and the row-action half of it is now history.** All **seven** deviations it documented are fixed: `more than one weight: 0`, `filled button in a row: 0`, across **152** screens rather than the 27 that were hand-listed — the audit had been widened to route enumeration since. `row-actions-audit` agrees: every actions column consistent within its table and across the app, every trigger 28px. **The source grep that found nine table cells on legacy button helpers now returns nothing**; one call survives anywhere in `app/views` (`organizations/_header.html.erb:23`), and it is a page header rendering `:primary`, which is what design.md asks a page's main action to be — recorded in the not-migrated list rather than changed. **`/partners` lost the problem that mattered**: `partners/_statuses.html.erb` no longer exists and nothing renders `#partner-status`, so the filter strip that shared a visual language with the status column is gone — 13 badges on that screen became 6. **"Badge on every row" went 1 → 6 without anything getting worse**, which is a scope artefact: five of the six are newly *looked at*, and `badgedRows === rows` is trivially true of a one-row table, which four of them are. The script prints the row count beside each path now and says how many are below three, because the bare number invited the wrong conclusion. **Two findings left.** `/partner_groups` pills both states of a boolean column (`Yes` success, `No` neutral) — a design call with three readings, previewed rather than decided; and invitation status is still plain text in one view and three pills in another. **One old finding retired as untrue**: a partner in `recertification_required` now gets "View partner" from a fallback, measured across all six seeded rows. |
| `6f689ac46` | **One invitation-status helper for both tables — and the audit blind spot that had been protecting the inconsistency.** The ask was to stop invitation status being plain text on the bank's user table and pills on the partner's. They did not merely differ, they **disagreed**: `User#invitation_status` separates *accepted* from *joined*, the partner side recomputed from `invitation_accepted_at` alone and collapsed both, so one user read "joined" on one screen and "Accepted" on the other. `essentials_invitation_status_pill` is now the single rendering — Joined and Accepted `:success`, Invited `:warning` because it is the row an admin might act on, and neutral "Not invited" where the bank table showed an empty cell. **Why it survived the whole migration**: `route-targets.rb` did `IDS[controller]` for every `:*_id` segment, so `/partners/:partner_id/users` got a *user* id and became `/partners/10/users` — no such partner, 404, and every browser audit logged it under "not reached" and moved on. **A skipped page and a clean page produce the same summary line.** That table therefore kept three stacked `button_to`s in two weights, a 264px actions column against 76–198px elsewhere, 38px triggers against 28px, Title Case headers and `scope="col"` on one of four `<th>`s, while `table-audit.js` reported the app clean and was telling the truth about every page it looked at. Segments now resolve against the model they name; 154 targets, and `/requests/1/cancelation/new` became reachable too. **A second bug hid the first fix**: `targets.js` invalidated its cache on `config/routes.rb` but not on the generator, so `table-audit.js` kept reading the stale list and reporting 152 clean while `row-actions-audit.js` — which shells out directly — saw the new screen and found two weights on it. Two audits, one tree, different answers. **A cache may not be older than anything that determines its contents.** The table is converted to `row_actions` and the audit is green at 154. New helper spec, 4 examples, watched failing; one spec asserting the raw lowercase `"invited"` updated to the label a user sees. axe 0 violations, overlay/form-validation/wcag22/confirm all clean, `page-audit` 0 defects. **Still skipped**: `/broadcast_announcements/1/edit` and `/partners/children/new` 404 — recorded, because the prior is now that a skipped route is hiding something. |
| `3403c72b7` | **The last two skipped routes fixed — every route the router knows is now audited, and the first run of the new ones found a defect.** `/broadcast_announcements/1/edit` 404'd because `IDS` used `BroadcastAnnouncement.first`, which is a **global** announcement with a nil `organization_id`, while the controller scopes `where(organization_id: current_organization.id).find` — the org-scoped record is id 2. `/partners/children/new` 404'd because it is scoped by a **query parameter**, not a path segment: `current_partner.families.find_by!(id: params[:family_id])` raises on a missing param, and a RecordNotFound reads exactly like a route that does not exist. Added a deliberately short explicit `QUERY` map rather than a guessing scheme, which would invent plausible URLs for screens it had got wrong. **155 targets, and axe no longer prints a `skipped:` line at all.** Then the payoff: `form-validation-audit` immediately reported `/requests/1/cancelation/new`, a screen no audit had ever seen — its controller **redirects with a flash on failure**, so the cancellation reason the user typed is discarded, against design.md's *re-render the record that failed* and *validation failure gets the summary, never both*. Recorded rather than fixed, being its own piece of work. Everything else clean at 155: table audit 0 mixed weights, axe 0 violations, overlay, wcag22 and confirm no findings. |
| `44477286a` | **Three design decisions, previewed as rendered HTML and then built.** **`/partner_groups`**: the "Send reminders?" column pilled both states, so every row carried a badge; `No` is now plain text and `Yes` keeps its pill and bell. A badge marks the exception — but this does *not* contradict a status column whose values genuinely vary, which is why `/partners` still badges every row across five statuses. The page dropped off the audit's "badge on every row" list, 9 → 8. **`/item_categories`**: the items column printed everything — **19 links, 710 characters, a 439px row**, three categories making the table 979px. Now three names and "+N more", **127px** a row. `.notes` clipping was never an option here: clipping leaves focusable anchors invisible, which is a keyboard trap. **The link needed a destination first** — the category page did not list its items, so a truncation pointing at it would have been a broken promise; it gained an "Items in this category" card. **`/distributions`**: **1,521px against 1,118px**, scrolling by 403px with the actions column already at 76px, so the saving had to come from data. Dropped source inventory (202px), shipping cost (108px) and comments (146px) — the table now measures **1,118px, overflow 0**. All three remain in the CSV export and on the distribution's own page: dropping a column from an index is a decision about what is worth *scanning*, not what is worth recording, and the export is what makes that true. Five system examples, **four watched failing** with the changes reverted; the fifth guards that the export was *not* changed, so it passes both ways by design. 219 examples 0 failures, table audit clean at 155, responsive clean apart from two pre-existing landscape findings. Three new rules in design.md with anchors. |
| `209cd7e41` | **Cancelling a request no longer sends you back to a form that cannot succeed.** Found by `form-validation-audit` on 2026-09-04, the first run after that route became reachable — no audit had ever seen the screen. Measured: cancel a request, then try again, and you were redirected to `/requests/:id/cancelation/new` with an empty textarea and *"could not be removed because request already cancelled"*. **The reason you had written was discarded**, and retyping it could never work: `RequestDestroyService` fails only on states — "we could not find it", "it has already been cancelled" — neither of which anything the user types can change. Someone whose colleague cancelled first would loop forever. It now goes to the **request's own page**, which shows the Cancelled status and the reason that *was* recorded, falling back to the list when there is no request to show, because `request_path` on a missing id would answer a failure with a 404. **The flash was never the problem** — an operational failure is what a flash is for — the destination was; design.md gains that rule. Copy fixed with it: the service's developer-facing fragments (`request_id is invalid`, `request already cancelled`) now read as sentences, and the success flash says *cancelled* rather than *removed*, since the action is Cancel and the record is discarded rather than deleted. 4 request examples, **3 watched failing** (the fourth is the happy path, which already worked); 65 examples across the request specs, 0 failures. **Found and left**: the reason field carries a `*` and `aria-required="true"` with no HTML `required` and no server validation — the form claims a requirement it does not enforce, which is a product call rather than a patch. |
| `935e5b336` | **The skills catch up with four days of findings — 1,179 lines to 1,375.** They had not been touched since 2026-09-03 while the work kept producing reusable lessons, which is the documentation-rot this project keeps finding in its own notes. **`audit-suite`** gains the sharpest form of scope-is-a-claim — *a skipped page and a clean page produce the same summary line* — with the id-substitution bug that made a whole unmigrated screen invisible to every audit for the length of a migration, plus the rule that some resources are addressed by query parameter and need an explicit map rather than a guessing scheme. And a new section, **two audits disagreeing about one tree means one of them is caching**: *a cache may not be older than anything that determines its contents*, from the freshness check that watched the routes file but not the generator that reads it. **`evidence-discipline`** gains *a recorded finding is a claim with a timestamp*, with the measured pattern behind it — **counts of strings in files all held up weeks later; three claims about behaviour in a row were wrong** — and *a seed is not a reproduction*, since a seed permutes a file list nobody records, plus the same-seed-different-outcome test for telling timing from ordering. **`wcag-conformance`** gains why `role="alert"` on a freshly loaded page may announce nothing, and the instruction to say plainly that the mechanics were measured and the announcement follows a published pattern. **New: `design-system-migration/reference/error-and-failure-states.md`** (98 lines) — the theme running through this week's UI defects: send a non-retryable failure somewhere that reflects reality rather than back to a dead form, flash for operational and summary for validation, focus the summary with the live region *inside* it, never mark a field required unless something enforces it, one concept one rendering, and errors written for developers reach users verbatim. Every cross-reference verified to resolve. |
| `f406bdb04` | **`/admin/barcode_items` gains the barcode filter — and only that one, because the to-do was half wrong.** The entry said it offered one filter against its twin's three, and that adding `by_base_item_partner_key` and `by_value` was safe because both are real scopes. **The base item filter was already there.** These barcodes are `barcodeable_type: "BaseItem"` and `partner_key` is unique on BaseItem, so `by_base_item_partner_key` selects exactly what the existing `barcodeable_id` control selects — verified by filtering a fixture both ways and comparing results, and pinned in a spec so the next person does not rediscover it. The twin needs both only because its barcodes hang off `Item`, where several items map to one base item. Adding it would have been two controls doing one thing, on a page whose permit list already has a comment about carrying names nobody uses. **Added `by_value`**, the "Barcode (boop it!)" box — genuinely missing, and the fastest way to answer *is this one already registered*, which is what the screen is for. Three new examples, **two watched failing**; the third pins the equivalence and passes either way by design. 78 examples 0 failures. **A false alarm worth recording**: `by_base_item_partner_key` appeared to raise `PG::AmbiguousColumn` until the cause turned out to be `.pluck` in my own probe — `default_scope` orders by an unqualified `created_at`, which is ambiguous once the scope joins `base_items`. The controller's path never hits it. **Found**: `BarcodeItem.global.count` is 0 in development against 13 org-scoped ones, so this page cannot be eyeballed at all and the filter had to be proven by spec — recorded, since that is plausibly why a filter sat inert here for years. |
| `07d47cb82` | **Sentence case on every form label and field name — 106 strings, and the audit that should have caught them.** The to-do said 24 labels across two trees in the partner profiles. **Extending `page-audit.rb` to `label:` found 52, across 14 files including `account_requests/new` and `admin/base_items/_dropdown`, which were nowhere near the partner profiles.** design.md has asked for sentence case on "headings, buttons, labels, table headers…" since the migration; the check covered headings only, which is exactly how these survived it — a rule with no audit is a suggestion. The audit was written and watched reporting all 52 before anything was changed. **Fixing the labels alone would have been half a job**: the same field names are *read back* as `<dt>` terms in the partner profile's read-only `show/` tree and in `profiles/_show.html.erb` where the bank views the same profile — another **54** terms, none of them a `label:`. When you rename a field, search for the string, not the construct. **Deliberately untouched: the CSV export headers.** `export_partners_csv_service.rb` holds "Year Founded" and friends as literals independent of the views; sentence case governs what a person reads on a screen, and an export header is an interchange format something downstream may key on. Acronyms and proper nouns keep their capitals — `% at FPL or below`, `Pacific Islander`, `Form 990 filed`, `501(c)(3) IRS determination letter` — via a `LABEL_PROPER_NOUNS` list, after a dry run caught the conversion lower-casing `Islander`. 11 spec assertions updated to the visible text; **237 examples, 0 failures**; `page-audit` 0 defects. **Found and left**: the show views say "Current providing diapers" where the form says "Currently providing diapers?" — a typo, and its own line rather than a rider on this. |
| `d0e99d895` | **The seven dead anchors, plus a typo, plus the check so neither comes back — and the check caught itself being wrong twice.** All seven turned out to be sections that had been **renamed**, not sections nobody wrote: `#target-size` is "Tap targets", `#pills` is "Status pills", `#icons` is "Iconography", `#interaction` is "Accessibility"; `#contrast` gained an explicit `<a id>` on the paragraph that states the ratios; and `#reports` and `#behind-a-proxy-or-tunnel` were bare fragments pointing at headings in `docs/onboarding.md`. **`page-audit.rb` now resolves every `](#...)` in `design.md` and `docs/*.md`** against the target file's headings and anchors. **Two faults in the new check, both found by reading what it accused rather than trusting the count**: its slug regex was `^#{2,6}`, so it never saw h1 headings and reported `onboarding.md`'s own table of contents as broken; and its cross-document branch resolved paths against the working directory, so `../design.md` did not exist and the guard `: !File.exist?(target)` turned "cannot find the file" into "fine" — it was passing `docs/design-decisions.md: ../design.md#target-size` while that very anchor was being renamed. A lookup that fails is not a pass; written into `audit-suite`. Proven by planting a dead link and watching it report. **The typo**: the partner-side profile said "Current providing diapers" where the form and the bank-side view both say "Currently" — one file, one word, its spec assertion updated. The CSV export header keeps its own spelling, being an interchange format. 28 examples, 0 failures; `page-audit` 0 defects and **0 dead links across all seven documents**. |
| `92192cbdf` | **`"completely empty request"` no longer reaches partners.** A partner who submitted an empty request got that as a bullet — lowercase, unpunctuated, written as a note to self. It is a model validation (`Request#not_completely_empty`), and `partners/requests/_error` prints every base error verbatim, so a validation string is UI copy whether or not anyone wrote it as one. Now **"The request is empty: it has no items and no comment."** — a sentence, and one that describes the **state** rather than the remedy, because the remedy differs by form and the callout's guidance line already supplies it: *Choose at least one child* on the family form, *every line needs an item selected* on the other two. Verified in the browser as a partner sees it. The cost was the three specs asserting the exact string, which is exactly the blast radius recorded when this was deferred, and it was worth paying. design.md gains the general rule. **Last one left**: `"detected a unknown item_id"` — recorded rather than tidied, because unlike the other two it is a should-never-happen guard, so the right copy tells the partner they have hit a bug and to contact the bank, not a neater sentence about item ids. 235 examples, 0 failures. |
| `41d4ecc55` | **`essentials_step_number` replaces five copies of an eleven-class string.** The getting-started guide wrote the numbered disc out once per step — the case design.md argues against when it explains why `.data-table` is a component class rather than a utility string. The helper's output is **byte-identical** to the literal it replaced, checked by rendering both and comparing; 21 dashboard examples pass, including the one that renders the guide, and every template compiles. It carries `aria-hidden`, because the number is already in the `<ol>` and without it a screen reader reads the list semantics twice — *"1, 1, Set up storage locations"*. **Two things measured and deliberately not done.** The brand link class `font-medium text-brand-700 hover:text-brand-800` is **40 occurrences across 26 views** — app-wide convention rather than local copy-paste, so collapsing it is a 26-file change with no visual effect and wants its own commit; a component class in `application.css` would fit how `.data-table` already works. And the two top bars still hand-roll an `h-8 w-8` avatar disc, the same idea at a different size holding initials rather than an index — near enough to look like one component, far enough apart in purpose that merging them needs a size *and* a semantics argument at every call site. Both recorded in `docs/todo.md`, with the trigger for revisiting the second: a third size. |
| `21d586e32` | **The `request_system_spec` flake, hunted and fixed: a missing wait after "Clear all".** Ran the full suite on fresh seeds until one failed — it took **one attempt**, seed 38162 — then read the failure rather than reaching for `--bisect`, which would have been the wrong tool: the same seed had previously produced both a pass and a failure, so this is **timing, not ordering**. The signature said so too: six `<<ERROR>>` entries, Capybara's marker for elements going stale mid-read, on the assertion immediately after `click_on "Clear all"`. Clearing re-renders the results frame exactly as selecting does, and the `select` two lines above already had `wait_for_filters` — **this was the only `click_on "Clear all"` in the suite without one**, against `storage_location_system_spec:252` which has it. Verified as far as a timing bug allows: three further full-suite runs, **including the reproducing seed twice**, all clean at 3,296 examples. **A second, distinct flake surfaced while verifying**: `donation_site_spec.rb:198`, a *model* spec, so no browser timing — `DonationSite.active` is unscoped by organization and the assertions index `.first`/`.second` off a query with no `ORDER BY`. Recorded rather than guessed at, because the hunt script deleted the failing run's output and kept only the seed. **Keep the output of a failing run; the seed alone is not enough.** |
| `94f89a2cb` | **What the flake hunt actually found: the suite has low-rate background flakiness, and a seed is not a handle on it.** **15 full-suite runs**, 5 failures, **4 distinct examples, never the same one twice**. Seed 20085 gave a failure then two clean runs on identical code; seed 51001 gave `donation_site_spec:198` on one run and `audit_system_spec:74` on the next. That is timing, not ordering — so `--bisect`, which the earlier to-do recommended, is the wrong tool here, and the recommendation is corrected. **One of the four had a genuine cause and is fixed** (the missing wait after "Clear all"). Of the rest, `await_select2` exhausting a *ten-second* wait reads as a slow container rather than a spec fault; `donation_site_spec:198` is the best next candidate precisely because it is a **model** spec and so cannot be browser-timing — it queries `DonationSite.active` unscoped by organization and indexes `.first`/`.second` off a result with no `ORDER BY`, both readable without reproducing anything. The to-do now carries the table of signatures and two operational notes learned expensively: **keep the output of a failing run** — a hunt script that logs the seed and deletes the run is useless when re-running the seed gives a different failure — and never run a second `rspec` against the test database mid-run, which manufactures deadlocks that look like defects. Both generalised into `evidence-discipline`. |
| `03233d807` | **The second flake diagnosed from the source and fixed: the spec was not running the query the app runs.** `donation_site_spec`'s CSV examples called a bare `DonationSite.active`, where `DonationSitesController#index` builds `current_organization.donation_sites.alphabetized.active`. Two differences, and **both produced flakiness rather than a stable wrong answer**: it was **unscoped by organization**, so any other organization's site changes the count; and it was **unordered** while the assertions index `.first` and `.second`. Postgres promises no order without `ORDER BY` — a sequential scan returns heap order, and the `before` blocks `update` a row, which writes a new tuple at the *end* of the heap, so the expected order held by accident of MVCC until one run in fifteen. **Diagnosed entirely by reading**, with no reproduction: a model spec cannot be browser-timing, which is what made it the tractable one of the three. Fixed by calling what the controller calls. **Two guards added, each watched failing against the old query**: one creates another organization's active site and expects it excluded, one creates a site that sorts first but is inserted last — without them the fix would be invisible, since every existing example passed before it too. 40 examples across the model, request and system specs, 0 failures. One flake left, `audit_system_spec:74`, where a ten-second `await_select2` wait expires — which reads as a slow container rather than a spec fault. |
| `4891ff81b` | **The last flake was not a slow container after all — `await_select2` read the DOM with a snapshot.** I had written this one off as environmental, on the grounds that a ten-second wait expiring reads as load. Reading it says otherwise. The helper took the starting `data-select2-id` from a single non-retrying `Nokogiri::HTML.parse(page.body)`; select2 stamps that attribute when it initialises, so a snapshot taken first finds nothing, `nil.to_i` gives **0**, and the helper waits ten seconds for an id of `1` that never arrives. **Proven without a reproduction**: rebuilding the old selector from a nil id yields `" select option[data-select2-id=\"1\"]"`, byte-identical to the failure message. A second fault in the same two lines — the wait selector dropped the `select2` argument entirely and matched any `select` on the page, rendering as a leading space with `container` nil, which is how all **eight** call sites use it. Both fixed: a retrying `find` for an option that *has* the attribute, and a selector anchored to the element passed in. 119 examples across the three files that use it, twice, 0 failures. **All three flakes the hunt turned up had real causes and all three are fixed**; the "slow container" assessment was wrong and is corrected in `docs/todo.md`. Generalised into `audit-suite`: read the DOM with the retrying finder, never with a snapshot. |
| `de63b6c30` | **Stability check: eight consecutive clean runs, and both test-suite entries close.** Three flakes were fixed on 2026-09-04 with one clean run each — which is exactly the thin evidence this project keeps criticising — so the result was measured properly. Eight fresh seeds: **3,298 examples, 0 failures, 1 pending, every time.** Against a prior rate of 5 failures in 15 runs, **eight consecutive clean runs would happen about 4% of the time**, so that rate almost certainly no longer holds. Stated with its limit, because the limit matters: this **does not establish zero** — a 5% residual rate would still produce eight clean runs two times in three, and no number of passing runs can prove a race absent. The changelog's verification paragraph said *"the suite is not reliably green"*; it now says what is true and what is not supported. **The `--seed 43125` entry closes as unreproducible** after **23 full-suite runs** across two days with no occurrence and no run containing the string at all — kept as a record with its context rather than deleted, since the seven failures were real when someone saw them. All outputs kept this time, per the lesson from the previous hunt. |
| `c7afeed39` | **Four of the five outstanding decisions, done.** **(1)** `"detected a unknown item_id"` now says *"Something went wrong at our end and this request could not be read. Nothing you did caused it -- please contact your bank."* Every id on that form comes from the form, so a partner cannot cause it; telling them their "item_id" was "unknown" invited them to hunt for a mistake they did not make. **(2) The cancellation reason is genuinely required.** The label carried an asterisk and `aria-required="true"` while a blank one saved. Making it true needed an object to attach the error to: the form was `essentials_form_for :cancelation`, a bare **symbol**, so there was no inline error, no `aria-invalid` and no summary — which is exactly what `form-validation-audit` reported the first time that route became reachable. New `Requests::Cancelation` form object, `as: :cancelation` to keep the param key. **The rule lives in one place**: the form object, not the service, because a missing reason is retryable and the two service failures are not — putting it in the service also made four existing examples fail that legitimately do not care about the reason. Verified in a browser: whitespace rejected, the typed text survives the re-render, and typing a real reason on that same page succeeds. `form-validation-audit` now reports **no findings at all**. **(3) Three global barcodes in `db/seeds.rb`** — `/admin/barcode_items` lists only `BarcodeItem.global` and there were none, so it showed an empty state on a fully seeded database and its filters could not be exercised in a browser; the `by_value` filter added earlier had to be proven by request spec. Now three rows unfiltered, one when filtered, none for a barcode that does not exist. **(4) The item list pager stays inline**, closed as won't-fix with the reasoning in the file: it renders identically, so the move is unreviewable and untestable, and `footer:` is not an enforced rule. **`ignored_columns` deliberately untouched**, pending an explanation of what it does. 110 examples, 0 failures. |
| `6971f9503` | **`ignored_columns` stays; the to-do entry goes; the reasoning moves into the code.** The fifth decision, taken after explaining what the line does. It is a no-op wherever `20260901200000` has run — which is here and in CI — but removing it against a database where the drop has *not* run lets ActiveRecord generate an `address` attribute accessor that collides with `StructuredAddress#address`; depending on load order the raw empty column wins and every address on four models renders blank **with nothing raising**. A silent wrong answer against a one-line cost. The comment beside the line was itself stale — it said the column "is dropped in a later *release*", a future that has already happened — and now states what is true, what breaks if it goes early, when it is safe to delete, and the one standing cost of keeping it: a *new* `address` column added to those models later would be hidden without a word. Recorded there rather than on a list because it is a fact about that line and that is where a reader meets it. |
| `373503a6e` | **Asked why the design-system items were not done, re-measured them, and two of the three entries were wrong about themselves.** **"One legacy button helper survives"** implied a straggler in a finished migration. It is not: **11 of `UiHelper`'s 27 methods are live**, `submit_button` alone in 18 files, and `migration-map.md:180` already records the decision to keep them — the shim emits design system classes, and `type:`/`size:` map onto variants so ~60 call sites keep working. The nine that mattered were *table cells*, where `type: "primary"` drew a filled button in a row; that grep returns zero. There is nothing to complete, and the entry now says so instead of implying a loose end. **The brand link class is bigger and different than recorded**: 40 occurrences of `font-medium text-brand-700 hover:text-brand-800` *and* **23 of the same colours without the weight** — 63 hand-written link styles in two shapes, with no rule saying which a link should take. That makes it a **decision, not a sweep**: collapsing them changes the weight of 23 links or preserves a distinction nobody has articulated, and design.md has to answer which before any of the 63 move. **The third is a genuine judgement** and stands: the two avatar discs are the step-number disc at a different size holding initials, and merging needs a size and a semantics argument at every call site — with a stated trigger, a third size appearing. |
| `b1c97ada2` | **`.link-brand`: 71 hand-written link styles become one class, and every link gains a non-colour cue.** Previewed as rendered HTML before building, and the preview changed the answer. My first recommendation covered colour and weight and was **silent on affordance**; asked "shouldn't it have an underline for accessibility", measuring settled it. **Brand colour against the prose these links sit in: 1.04:1 on `slate-600`, 1.31:1 on `slate-700`, 2.26:1 on `slate-900`** — WCAG technique **G183 wants 3:1** when colour is the only marker, so colour was doing essentially nothing. Against white it is 7.90:1: the links were readable, just not *identifiable*. And of **78** brand link strings, **3** had `hover:underline` and **6** any focus style — a table-cell link had no non-colour cue at rest, on hover or on focus, verified in a browser. The class carries the colour plus `underline` on **hover and `:focus-visible`**. **It carries no weight**, deliberately: a table cell is already `font-medium` and the link inherits it, a list of nineteen item names should not be medium per line, a sentence adds it — measured after, the name-cell link is **500** and the list link **400**, exactly as before. Baking weight in would have bolded six list links to make the rule tidier than the design is. **Nothing changes at rest**: colour identical, weight per context, no decoration. 71 strings in 13 shapes across 48 files; the 5 `file:text-brand-700` and 2 avatar discs correctly untouched. `page-audit` now reports a hand-written `hover:text-brand-800` as a defect, proven by planting one. axe 156 pages 0 violations; 46 examples 0 failures. |
| `58e10a924` | **The "Current state" table is generated, and CI fails when it drifts.** It was hand-maintained, and hand-maintained meant wrong: refreshed on 2026-09-03 and **42 commits stale two days later**, and before that it had drifted far enough that `migration-map.md` carried a second copy disagreeing with it. Every figure in it was already computed by something — `status.rb`, `dead-routes.rb`, `dead-code.rb`, `undefined-classes.py`, a couple of `git` counts — so the only reason they went stale is that a person had to copy them across. `bin/design/state.rb` rewrites the block between two markers; the prose around it stays hand-written, because a generator has nothing useful to say about which numbers are misleading. **`--check` is wired into the `audit-selftest` workflow** and fails when a figure has drifted, the same discipline as a schema dump. **It deliberately excludes the commit and file counts** — those change on every commit, and a gate that fails every pull request for a reason nobody can act on is a gate that gets switched off. Proven both ways: corrupting `Routes whose request would raise` fails the check, corrupting the commit count does not. Two faults found while building it — `sh` resolves to Rake's `FileUtils#sh` under `rails runner`, which echoes the command and returns `true`, so every figure came back as `true`; and CI checks out shallow, so `main..HEAD` resolves to nothing and the git counts would have printed a confident **0**. They say `n/a (no main ref)` now, verified by renaming the branch. |
| `380833de9` | **The avatar disc deferral was wrong, and the duplication was hiding a defect.** Asked why it had not been done, and looking settled it: the reason on file — that merging with `essentials_step_number` needs a size *and* a semantics argument — is true and **beside the point**. The two copies were **byte-identical to each other**, so extracting them needed no argument at all. Deferring a two-line job because a *different* question about it was hard is how it survived the whole migration. **Both copies were also wrong**: they passed `display_name`, which returns the literal `"Name Not Provided"`, so a nameless user's avatar read **"NN"** — **9 such users** in the development database. The partner bar appeared to guard against it with `display_name.presence || email`, but `display_name` is never blank, so that fallback was **dead code** and it rendered "NN" as well. `essentials_avatar_disc(user)` owns the markup and the name choice, using `preferred_name`. **The same fault was in the trigger's `aria-label`**, so two different users announced as *"Account menu for Name Not Provided"* — identical to the defect this project found and fixed in `users/_organization_user`, and missed here because the topbar was edited three times this week without anyone reading that line. Measured after: bank `org_admin1@example.com`, partner `Justine Baumbach`, admin `superadmin@example.com` — three distinct names. 4 helper examples watched failing with `got: "NN"`; 144 examples, axe 156 pages 0 violations, `page-audit` 0 defects. `essentials_step_number` stays separate and that half stands. |
| `11456a0d8` | **The adapter, written — and the deferral was half right, which is why measuring it first mattered.** The reason on file was that inventing a cross-stack abstraction from a sample of one repeats an earlier mistake. **That still holds**, and nothing here claims the interface generalises. But it was doing double duty: it also deferred writing down the Rails adapter that **already exists and works**, for which the evidence is 34 audit scripts over 155 screens. Two jobs, one reason — the same shape as the avatar disc deferral an hour earlier. `templates/adapter-rails.md` (128 lines) records what runs: the nine-export seam, route enumeration behind one `TARGETS_CMD` variable, the Devise sign-in with the four details that were each a bug first, role predicates including the awkward `/partners/12` case, and `visit` returning null so a caller can tell *not checked* from *fine*. **The most useful part is the honest measurement**: only **7** browser audits import the seam, **13** shell out to the generator directly, and **16** files still carry their own `signIn`, at least two byte-identical. **A change log row was overstated and is corrected**: it said the seam was "replacing 21 hand-copied `signIn` functions" when the commit changed three files and converted one audit — it made 21 *replaceable*. A seam nobody adopts is a ninth way of doing something with none removed, and the skill now says so, with the cheap first step: a check that fails on a new private `signIn` so the number can only go down. |
| `2d8e35593` | **A ratchet on the audit seam, so the copies can only decrease.** `targets.js` exists so no other audit needs to know what framework the app is, and **15 still carry their own `signIn`** — the earlier figure of 16 counted `targets.js`, which legitimately owns it. Migrating them touches every audit and wants its own commit; `bin/design/seam-check.rb` is the cheap thing that can be done first. It fails when the count goes **up**, and — the half that is easy to leave out — when it goes **down** without `BASELINE` being lowered, so a migration cannot be done and then quietly undone. No browser or server, so CI runs it before everything else. **The second control found a bug in the check**: `/async function signIn/` has no word boundary, so `signIn_MIGRATED` still matched and the control that migrates one by renaming it passed in silence — a ratchet that cannot see the direction it protects. Fixed and both directions re-proven. Why the copies matter, from faults this project actually had: one did not sign out first, so a second role silently audited the first's pages; one waited on `networkidle`, which never settles on three form pages here; one used a bare `button[type=submit]`, which matches the sign-out button in the closed account menu and waits 30 seconds for it. Each was fixed once in the seam, and a copy is a place for it to come back. |
| `dca252687` | **All 15 private `signIn` copies migrated onto the seam, verified against captured output.** The ratchet went in first, then the job it was ratcheting: **15 → 0**, audits importing `targets.js` **7 → 21**. **The mitigation was the point and it earned itself.** Every audit's output was captured *before* any edit; afterwards **13 came back byte-identical**, and the fourteenth — `responsive-audit` — reported a new finding at 320px on `/items/inventory`. Rather than assume either way, it was run three times on identical code: **9, 9, 8**. The audit is non-deterministic and the migration had nothing to do with it; the baseline had simply caught the minority outcome. Without the before-and-after that would have been recorded as "the migration changed a result" and either reverted or waved through, and both would have been wrong. **The six shapes the copies had drifted into**: three did not sign out first, three waited on `networkidle` (which the seam's own comment says never settles on three form pages here), five used a bare `button[type=submit]` that matches the sign-out button inside a closed account menu, and two hardcoded the password. Tested before migrating whether the missing sign-out was corrupting results — it was not, because Devise here re-authenticates over an existing session, which is worth knowing and was not assumed. `audit-selftest` passes 11 controls over 5 checks; `BASELINE` is 0 and the ratchet now guards a clean sheet. |
| `621cf6bee` | **The route reads join the seam too: 13 → 0, and four of them were broken.** With `signIn` done, the other half — every audit reading the target list its own way. **Four read `/tmp/targets.json` with no regeneration**, so `icon-audit` and `tooltip-audit` **crash with `ENOENT`** on a machine that has never run another audit (proven by deleting the file), and use a silently stale list on one that has. **A fifth was worse**: `wcag-manual` fell back to an *empty* list when the file was missing, narrowing its cheap per-page checks from 155 screens to **zero** while printing a summary that read like a pass — the fallback for a missing input was to check nothing and report success. The remaining eight spawned Rails on every run and skipped the cache whose staleness rule is the entire point. All 13 now call `targets()`; **21 audits import the seam and none read the generator directly**. **Verified the same way, and it found two more things.** Eleven came back byte-identical. `layout-shift-audit` named a different worst page — four runs gave **three different answers** (`/admin/questions/1/edit` 0.011, `/admin/questions/new` 0.011, `/partners/children/1/edit` 0.007 twice), so it is non-deterministic: CLS measures shifts *during* load. And `row-actions-audit` moved a column width 129 → 125 → 129px, which is sub-pixel rendering variance, recorded so nobody chases it. Neither was the migration. `audit-selftest` 11 controls over 5 checks, 0 wrong. |
| `bd4bed6cf` | **One of the two non-deterministic audits fixed; the other narrowed and left, after three failed attempts.** **`layout-shift-audit` is fixed.** Every screen measures 0.007–0.011 against Chrome's 0.1 "good" threshold — an order of magnitude inside it — so ranking them was sorting noise: four runs named **three different** worst pages. Its `score > 0.01` display cutoff had the same fault a level down, listing a page at 0.0105 and dropping the same page at 0.0099. It now reports against a **0.02 noise floor set from measurement**, names no page below it, and does not print the varying number at all — because printing it invites a diff between two runs to look like a change. Verdict identical across runs. **`responsive-audit` is not fixed**, and three attempts are recorded rather than a fourth guess: the fixed `waitForTimeout(350)` became a condition, then a three-reading stability check on the measured count itself; it still alternates 8/9. Ruled out by measurement: the page probed directly at 320px gives **52 under-24 targets at 0, 150, 350, 700, 1200, 2000 and 3000ms** — the number does not move with time on a fresh page — and it is never skipped. Narrowed to `/items/inventory` at **320px only**, the first width measured after the largest resize. **Two real bugs found on the way and fixed**: the audit silently dropped any page that redirected or timed out — **9 screens**, including `/` and `/kits/143`, absent from every figure with nothing printed — and it now reports what it could not reach, while correctly *not* reporting redirects whose landing page another target already visits. |
| `46352abf8` | **A fourth attempt at the `responsive-audit` flicker: not fixed, but narrowed to one line and instrumented for the next.** Added a `DUMP` flag that prints the *elements* rather than the count, and it answered in one run what four count-comparisons could not: `all=133 undersized=52 small=0` — the **undersized set is stable at 52**, so the swing is entirely inside the spacing exception, and it is **bimodal (0 or 50)**, so one global factor flips all fifty rather than a target drifting over a threshold. **Six hypotheses eliminated by measurement**, each recorded: an early measurement (52 at 0/150/350/700/1200/2000/3000ms), a skipped page, the fixed `waitForTimeout(350)`, unsettled geometry, a font swapping in (`document.fonts.status` is already `loaded`), and scroll moving the sticky pinned columns (forced both page and rail scroll; the result did not move). **The tell for the next attempt**: a standalone probe of that page gives `small=1` where the audit gives 0 or 50, so the cause is in the audit's environment — one page object reused across 155 paths and ten widths — not in the page. Generalised into `audit-suite`: **when a count flickers, stop comparing counts** — a count is a hash of the thing you want to diff, and it discards what identifies the cause. |
| `166cda001` | **A live Bootstrap button survived the entire migration, because the class audit read `app/views` and never `app/helpers`.** Found while chasing the `responsive-audit` flicker, which is the only reason anyone was looking at `/organization` at 320px: a **14×20** button carrying `btn btn-outline-primary btn-xs` — three classes the stylesheet has not defined since ADR 0011 removed Bootstrap — named only by `title`, with `alt` on a `<button>`, where that attribute means nothing. `undefined-classes.py` had reported **0 orphans throughout**, and helpers building markup is the whole reason. **Widening the glob was not enough, and that is the part worth keeping**: the "is this a deliberate hook?" test greps `*.rb` under `app/`, so once helpers were read the helper's own `class:` counted as a reference to itself and every helper-only token was filed as a hook. That test had always excluded `.erb` for precisely this reason — a view writing `class="foo"` is not evidence that `foo` means anything — and helpers write class attributes in a file type it does read. The scanned files are now subtracted from its matches. **The run in between reported clean and looked like proof**, which is the general lesson: widening what an audit reads can require widening what it discounts. **With both halves in it found four undefined tokens in two helpers.** `reinvite_user_link` is now `essentials_action_button`, measured in the browser before and after: **14×20 → 28×28**, accessible name moved from `title` to `aria-label`, `bi-envelope` and the POST preserved. Three unreferenced `PartnersHelper` methods emitting `label label-teal`, `badge badge-pill bg-primary` and `col-sm-3 col-3` are deleted. **The line between deleting and keeping**: an unused helper that renders design system output is inert and stays on the documented list — `UiHelper#status_label` has no callers after this and stays, because a future caller gets a correct pill — while an unused helper that renders classes nothing defines hands that caller invisible markup. Controls run both ways: a class planted in a helper is now reported, and one planted in a view still is. **`state.rb` carried the same false-clean shape and is fixed too**: it counted the audit's indented output lines, so a crashed audit and a clean one both answered `0`. It reads the printed count and says `n/a (audit produced no count)` when there is none — proven against clean, 2-finding and crashed output. **Rollback #8 landed in the middle of this**, and is why the first negative control appeared to fail: the `grep` that showed the widened script and the `sed` that showed the original were reading either side of it, so the "failure" was never a measurement. Disk had gone back to `548db78f6` with **368 commits of content missing** while `HEAD` stayed put and matched the remote exactly; `bin/workspace-restore` put it back and the two uncommitted edits were redone. 100 examples 0 failures across the helper, request and system specs. |
| `c855ff0ec` | **The `responsive-audit` flicker, fixed at the fifth attempt — and it had been hiding two real defects.** Findings alternated 8/9, always `/items/inventory`. **A target's own ancestor is not a neighbour**: WCAG 2.5.8's spacing exception excuses an undersized target when a 24px circle on it reaches no *other* target's hit area, and "other" was implemented as `o.el !== t.el` — which is true of the target's own parent, whose box necessarily contains the child's centre. So any control inside a focusable container could never pass. `clipped_text_controller` gives a truncated `<td>` `tabindex="0"` so a keyboard user can reach its tooltip, and on that page the marked cell **wraps** each row's disclosure button: fifty buttons reported, at every width, and whether 320 joined them varied per run. One predicate — `!a.contains(b) && !b.contains(a)` — and three full runs are **byte-identical**. Verified the honest way: the underlying population still swings (`allTargets` 133 or 183 between runs) and the output no longer moves with it, which is better than suppressing the swing because the audit no longer depends on it. Four isolated controls, one of which corrected **my expectation** rather than the code — a focusable *wrapper* that is itself under 24px is a real target and is still reported. **Why four attempts missed it**: they compared counts, then positions. The number that moved was neither the sizes (`undersized` sat at 52 throughout) nor the geometry but the size of the *comparison set*, and nothing printed that. **Then 8 findings became 2, which is where a fix turns into a suppression unless you read what vanished** — every removed line was the same page and the same message, and two genuine defects were underneath. **The button really was 20×28**, a hand-written near-copy of `ROW_ICON_CLASSES` missing `size-7`, against design.md's rule that every actions-column control is 28×28; the audit had said so at every width for as long as it had flickered and it read as more flicker. *A permanently noisy check is a check whose true findings get filed as noise.* **And the clipped-cell scan counted `sr-only` text**: `textContent` includes it, so any cell whose only text was a screen-reader label qualified — **55 cells marked at 320px, 50 holding nothing but "Show storage locations for …"**, each a tab stop raising a bubble repeating a deliberately hidden string over a cell showing a chevron, which is the tab-stop-per-row that controller's own comment exists to prevent, reached from the other side. After: 5 marked, 0 unreadable, button 28×28. Both pinned by `item_system_spec.rb` and **both specs watched failing first** (`got: [20, 28]`; 2 spurious tab stops). 13 + 31 examples 0 failures, audit-selftest 11 controls 0 wrong, erb_lint and rubocop clean. Left open deliberately and written down: that 133/183 swing is the clipped scan reacting to `resize` while stacking labels arrive on a `matchMedia` change — no audit result and no user symptom depends on it now. |
| `daba48850` | **`responsive-audit` reports zero across the whole app, and the last two findings were the same class of false positive as the flicker.** Both remaining findings were "fixed/sticky chrome covers 186px of a 360px viewport", on `/admin/base_items` and `/admin/partners`. The check sums the vertical bands of everything `fixed` or `sticky`; **a `sticky` element with `top` and `bottom` both `auto` is pinned to a horizontal edge**, and its band scrolls away with the content rather than occluding a fixed strip. The frozen actions column is precisely that — measured on `/admin/partners` at 740×360, eight `td.cell-actions` at `top: auto, bottom: auto, right: 0px` in consecutive bands (216..269, 269..322, 322..375), unioned to 186 of 360 and over the 50% threshold, for a column that eats **no height at all**. Same family as the ancestor bug fixed an hour earlier: a geometric rule reading an element whose geometry does not mean what the rule assumes. **Five controls, all correct**: a right-pinned column over eight rows scores 0, a sticky topbar 64, a fixed bottom bar 56, both together 120 (unioned, not summed), and a topbar beside a pinned column scores only the topbar's 64. Three full runs byte-identical, **0 findings across 155 routes**. **Then the interesting part, which is a correction of my own.** Having removed the column, a four-page spot check showed nothing pinned and I concluded — and wrote into the code and the to-do — that the check had gone inert on this app. So the run now prints what it considered, per the suite's own "count what you examined" rule, and that line **falsified me in one run**: it considers **30 elements across 146 page visits**, identical on three runs, every one of them `.table-rail`, the fixed 24px scroll rail on a wide table, at 24px of 360 — about 7%. Live input, negative verdict. Both claims corrected in place. What is genuinely unexercised is the *reporting* path above 50%, which no real screen reaches; the five controls live nowhere yet because the check is inline rather than exported, and `docs/todo.md` names the extraction. **Two doc corrections in the same commit.** `design-decisions.md` still said `/broadcast_announcements/1/edit` and `/partners/children/new` "still 404 and are still skipped by every audit" — fixed the next day by `3403c72b7`; marked superseded rather than rewritten, because a dated entry is a record and not a status page, and re-verified at 155 routes with an empty not-reached list. And `todo.md`'s skills figures said 17 files/1,383 lines against an actual **18/1,599**. The other two numbers in that file were re-measured and both still hold: 11 of `UiHelper`'s 27 methods live, and 9 users whose `display_name` is the placeholder. |
| `3c4812e72` | **The skills-symlink premise, verified — it holds, and symlinks are followed.** The standing item to make `.claude/skills/` available outside this repo rested on a claim nobody had tested here: that Claude also reads `~/.claude/skills/`. It had never been tested because that directory has never existed on this machine, so the plan's foundation was an assumption. **Asking a model whether it can see a file is the weakest available evidence**, so it was checked with a canary: a skill at `/tmp/canary-skill/SKILL.md` carrying **two different random tokens**, one in the frontmatter `description` and one in the body, installed exactly as the plan proposes — as a symlink, `~/.claude/skills/canary-probe -> /tmp/canary-skill`. `claude -p` run from `/tmp`, a directory with no `.claude/skills` of its own, returned **both**. Two tokens because they answer different questions: the description token proves *registration*, the body token proves the file was *read*. **The negative control is what makes it evidence** — the symlink was removed while the file was left on disk inside the working directory, and the same prompt returned `NO-CANARY-SKILL`, excluding the confound that a positive result alone leaves open (the file simply being near the session's cwd). Corroborating but insufficient on its own, and ranked as such: the client binary carries **14** references to `~/.claude/skills/`, including a `synced` subdirectory named in help text — string evidence shows the path is *known*, only the canary shows it is *loaded*. Both artefacts were removed and `~/.claude/skills/` left absent, so `todo.md` still describes the machine as it stands. **The symlink itself is still not done** and still needs a decision: it writes outside the repo, and the one real tradeoff is unchanged — a symlink points at a path, so if this repo moves the skills stop working silently, while a copy trades that for two versions that drift. Generalised into `evidence-discipline` as "verify a mechanism with a canary, not with a self-report". |
| `718e5cbaf` | **Ran the seven audits I had skipped, and built the thing that stops the skipping.** Yesterday's changes removed **fifty keyboard tab stops** and altered two control sizes, and the audits re-run afterwards were chosen from memory — so `keyboard-audit`, `wcag22-audit`, `row-actions-audit`, `tooltip-audit`, `wcag-audit`, `icon-audit` and `table-audit` were all skipped, every one of them a check measuring exactly what had changed. **Run now, and the tab-stop removal broke nothing**: keyboard-audit 146 screens at 1280 and again at 375, no findings; axe 160 pages 0 violations; wcag22 no failures with its examined counts printed; tooltip 653 icon-only controls 0 defects; table-audit 155 tables, 0 mixed weights, 0 filled buttons in a row. **Two audits exit non-zero and neither is from yesterday**, which is worth stating rather than implying: `icon-audit` reports `bi-arrow-left-right` ("Compare with the previous period") and `bi-key` ("Reset password") as glyphs absent from the lexicon, and `row-actions-audit` reports `/admin/barcode_items` carrying 3 inline actions with no menu, plus advisories on nine tables that need a human. **One genuine inconsistency surfaced**: `bi-envelope` now carries three labels — "Re-send invitation" on `/organization` against "Re-send invite" in `admin/users/_list` and `partners/_partner_row` — for the same action. Pre-existing (the old `title` said "Re-send invitation" too), but it took a proper `aria-label` for the audit to see it. **The fix for the skipping is `bin/design/which-audits.rb`.** Not a checklist, deliberately: a checklist is memory written down, correct the day it is written and silently wrong the day an audit is added. Instead omission is impossible by construction — each audit declares its inputs in its own header (`AUDIT-READS: RENDER`), the script **enumerates `bin/design/` itself** rather than carrying a list, and **a file that neither declares nor is named a non-audit fails the run**, so a new audit cannot drop silently out of every future selection. Six non-audits are excused with a reason each, because an unexplained absence reads identically to an oversight. Bundles are coarse on purpose: a browser audit drives real pages, so for a render-path change the honest answer is *most of them* — asked by hand about one view and one controller I picked six and the truthful number was twenty-eight. **Three controls, in the three directions the failure can hide**: a view change selects the render audits; a **docs-only change selects zero browser audits** (otherwise it is not selecting, it is saying "everything"); and a planted undeclared file fails with exit 2, proven both with the file present and after removing it. It also prints what it considered and did *not* select, and a pasteable command for the selected set. Fixed on the way: the `state.rb` paragraph in `onboarding.md` was **inside** a ```bash fence and rendering as shell. Generalised into `audit-suite` as "after a change, do not choose the audits from memory". |
| `923e562d1` | **Both red audits cleared, the label unified, and the new selector earned its keep by finding two bugs in itself.** `icon-audit` **2 findings → 0** and `row-actions-audit` **1 → 0**, both now exit 0. **The row actions fix is the one its sibling already made.** design.md settles that a row reaching three actions gets the menu, and `/admin/barcode_items` carried View, Edit and Delete — but `/barcode_items` had the identical shape and resolved it the cheaper way, with the reasoning recorded in the partial: the View goes because the record's name in the first cell links to it, leaving a settled pair that is always both present, so they stay inline. Two clicks saved over a menu and a column that cannot move, because nothing in it is conditional. Collapsing to a menu would have satisfied the rule and left two parallel tables looking different for no reason. design.md now records **dropping to two** as an accepted resolution beside "gets the menu", since the rule is about reaching three and not about the menu being the only cure. **The two icon findings were unregistered, not wrong**: the lexicon is a meaning→glyph registry whose own note says a new glyph must be a decision rather than a reflex, so `bi-key` = *reset a password* and `bi-arrow-left-right` = *compare with another period* are now in it. **And the lexicon had already drifted from design.md** in the way its note warns against — "change both together" — with **6 entries** (`bi-people`, `bi-person-gear`, `bi-filetype-csv`, `bi-sliders`, `bi-clipboard`, `bi-calculator`) in the JSON and absent from the prose table. All 8 are in both now, checked both directions. **The label is "Re-send invitation" in all three places**, chosen because the code and the user-facing noun already say *invitation* everywhere (`invitation_status`, `reinvitable?`, `resend_user_invitation_path`) — the two `Re-send invite` call sites changed, the dated mockup left as a record. **`which-audits.rb` selected all 30 and they were all run, which is the point**: 30 clean, including axe 0 violations over 160 pages, keyboard no findings, responsive no findings, page-audit 0 defects, template-compile all compile, `dead-code` at its documented 147. `form-validation` names `/partners/family_requests/new` under "7 forms an empty submit does not exercise" — informational, not a finding, and the right discipline. **Using the tool found two defects in the tool.** It printed `ruby bin/design/dead-code.rb`, which fails: three Ruby audits need the app booted, and they are exactly the three that mention `Rails.`, so the runner is now inferred rather than listed and a new Rails-using audit gets it for free. And the pasteable command reported only each audit's last four lines — so it now prints **`exit=`** too, because several of these say something reassuring in prose while exiting non-zero and `dead-code` exits 1 by design. 81 examples 0 failures. |
| `450b150e3` | **The short-viewport chrome check is extracted and its controls live in the harness — and the negative one had no teeth until it was broken on purpose.** `shortViewportChrome(page, where)` is exported from `responsive-audit.js` behind a `require.main === module` guard, with a swappable sink so the 50% threshold has **one** definition: the run installs a collector that pushes onto its findings list, `audit-selftest` installs its own. **Why bother**: this check has no live positive anywhere in the app. Once the frozen actions column stopped counting as vertical chrome no screen crosses the threshold — a full run considers 30 pinned elements across 146 page visits, all `.table-rail` at 24px of 360 — so the run exercises the measurement and never the reporting, and nothing but a control would notice if the threshold arm broke. **Harness now 13 controls over 6 checks, 0 wrong, in 12 seconds**, and the full run is byte-identical either side of the extraction: same 1,606 combinations, same 30 across 146, same findings. **Both controls were verified by breaking the code, and that is what caught the real problem.** The negative injected a right-pinned sticky table and expected silence; it was silent — and **still silent with the fix removed**, because `document.body.append` put the table below a page far taller than the 360px window, so every cell failed the check's own on-screen test and the control measured nothing while reading as a pass. Sited at the top of the document it now fails correctly without the fix (`covers 360px of a 360px viewport`), and the positive fails when the threshold is made unreachable (`> vh * 0.5` → `> vh * 5`). **A control has to be sited where the check looks** — the second time that exact mistake was made in one day, after an "alone in open space" target control was placed over a dense table. **One bug fixed on the way**: the harness's `settle` never reset the viewport, and one page object serves all thirteen controls, so a control that resizes would have left the other twelve running at 740x360 and quietly changed what they measured — the same shape as the existing "a region an earlier check had already scrolled" control. The reset is central now, where a future control cannot forget it. Generalised into `audit-suite`: site the control where the check looks, break the reporting arm too, and reset shared state in the harness rather than per control. |
| `4a8d37890` | **Merged 151 commits of `main` into the design branch: 45 conflicts, 3,387 examples green, and four defects found on the way.** `main` had moved 12 days and 151 commits (11 of them dependency bumps) across **180 files, 88 of which this branch had also changed** — 33 of those views it had rewritten wholesale, so the conflicts were markup-versus-feature rather than line-versus-line. **The rule applied throughout: design owns the markup, main owns the behaviour.** Re-applied onto migrated views: the **request item limits** (#5386) including a per-unit limit paired with each custom-unit checkbox; **reminder disable toggles** (#5668) on both organization forms with the schedule and reminder text hidden when they are off; the **audit status rename** to *pending finalization* (#5683); **phone numbers** on the partner table, row and detail page (#5674); transfers relabelled **Undo** (#5560); the **annual report range export** (#4987); the partner CSV import's new template (#5171); the **kit event direction** fix (#5568); and the password-reset greeting and signature (#5678). **`enable_packs` is gone** (#5251) — 11 view guards and two spec contexts removed, including one asserting the flag *off*, which is now the opposite of what ships. **Four defects found while merging, each recorded where it was fixed.** *main's new `reminder_toggle_controller` toggled `d-none`* — a Bootstrap class ADR 0011 left defined nowhere, so the fields would never have hidden; `migration-map.md` already records **four** earlier controllers with the identical fault and this was the fifth. *`items/_form` would have silently stopped saving custom units*: the merged controller reads `item[unit_ids][]` and this branch's `f.association` emitted `item[request_unit_ids][]`. *main's inline `<script>`* for the unit limits became a Stimulus controller, because there are no inline scripts here. *`shared/_reminders_disabled_notice`* arrived as `callout callout-info` with an `h5.font-weight-bold` and was migrated to the callout component. **Two things that were not the merge, and saying so mattered.** Three pages reported HTTP 500 by `route-sweep` and rendered 200 by hand: the dev server had been running across a `bundle install` that changed the gem set, and a fresh server sweeps **145 screens with no findings**. And one spec failed on a CSV export nothing in the path had touched — the cause was `public/product_drive_participants.csv`, **untracked debris from rollback #8** that `workspace-restore` could not see (it is gitignored, and the scan read only `git status`; fixed 2026-09-09), shadowing the route because Rails serves `public/` before routing. **`Gemfile.lock` needed care twice**: `sprockets` and `terser` are bumps of gems ADR 0012 removed, so they stay out; and taking main's lock dropped this machine's `aarch64-linux` platform, which broke `tailwindcss:build` and left the class audit reading a stale stylesheet — it reported `max-w-28` as dead when the real fault was that nothing had rebuilt. Schema regenerated by migration rather than hand-merged: version `2026_09_01_200000`, main's four columns and this branch's structured address both present. **Verified**: 3,387 examples 0 failures; route-sweep 145 screens; axe 0 violations; keyboard 146 screens 0 findings; icon, tooltip, table, copy, page-audit, template-compile and undefined-classes all clean; audit-selftest 13/6/0. |
| `c3261d338` | **The post-merge routine, and the check that would have saved the worst hour of it.** Yesterday's merge of 151 upstream commits found four defects and cost roughly two hours on two failures that were **not** the merge — and there was no written routine for any of it. There is now, in three places. **`docs/onboarding.md` gets the ordered eight steps**, in the order that finds things: syntax-check what you touched (a conflict region rarely aligns with a block boundary, and a leftover `end` reads as a merge that went fine); regenerate the lockfile and **check its platform list**; migrate and let Rails rewrite the schema, then prepare the *test* database; rebuild Tailwind **before** any class audit; restart the server; run `undefined-classes.py`; run the new shadow check; then the suite and whatever `which-audits.rb` names. It also records the rule that made 45 conflicts tractable — **design owns the markup, main owns the behaviour** — with `git diff -w` per file, because one file looked like a 19-line conflict and was pure reindentation while another looked identical and carried a whole feature. And the trap that bit twice: **stage each file the moment you resolve it**, because `git checkout --ours` on a still-unmerged path silently discards edits already made to it. **`bin/design/route-shadow.rb` is the new audit.** Rails serves `public/` before the router, so a file there answers a route and the controller never runs — with a 200 and plausible content. That is how untracked rollback debris returned three unfiltered rows for a CSV export while the controller, view model, concern, model, factory and spec were all byte-identical to pre-merge. It reports whether each shadow is **tracked**, because that decides the fix: untracked is debris and can be deleted, tracked is somebody's decision and the answer is a name — which is why every import template here ends in `_template.csv`. Three controls: a file named after a real route fires and is marked untracked, a file matching no route stays silent, and the real templates stay silent. It prints the candidate count either way, so "nothing shadows a route" cannot be read as "nothing was looked at". **The selector picked it up with no edit** — 30 audits considered became 31, and the runner was inferred as `bin/rails runner` from the file mentioning `Rails.`, which is the ratchet working as intended. **A correction went in first**: an hour after the merge I had written that `undefined-classes.py` *cannot* catch a dead class in a Stimulus controller. It can — planting `d-none` back into `reminder_toggle_controller` names the class and the file. I had written it from reading the code instead of running it. Generalised into `design-system-migration` as `reference/merging-upstream.md` (103 lines): which side owns markup and which owns behaviour, what to do with upstream's specs, and the two failures that look like merge damage and are not. |
| `fe03e1254` | **The migration was finished and the check could not tell: 347 of 384 was a measurement error, and the six views it named were all migrated.** Asked what remained, I read the files `status.rb` reported — **all six were done, and the check was wrong six times out of six**. Three were bare `f.input`, which is the *finished* state rather than an unmigrated one, because `config.default_wrapper = :essentials` makes the wrapper supply the div, the label, the control classes and the error — each of those three files carries a comment saying the hand-pasted classes were *removed* for that reason. The others carried a data-table cell class (`class="percent"`), a Stimulus controller (`data-controller="highchart"`), and a helper call whose argument was a variable rather than the symbol literal the pattern wanted. **Widening it was the wrong instinct, and I did it three times before noticing.** The page wrapper, `link-brand`, `EssentialsUiHelper` and the cell conventions took 347 → 360; resolving "renders a migrated partial", which the check's own comment already claimed it did, took it to 364; simple_form builder calls took it to 346 of 349 — and the last three files would have needed a fourth pass. The comment in the file records that the pattern had **already** been widened once, for 51 pages, for the same reason. **That is a check that cannot be finished**: the design system gains vocabulary with every component, so a positive-marker test is permanently one behind, and every miss reports completed work as outstanding. **So the measure is inverted.** The legacy vocabulary is closed — ADR 0011 deleted both frameworks and they cannot gain words — so the question is now *does this view still use the old system?*, which is what "is the migration done" means, and it reads **0 of 350**. The positive count survives as a labelled indicator, because a four-line table row can be migrated and have nothing to mark. Files that cannot carry a marker for the system they *are* — the 34 components in `shared/essentials/` plus gem and framework partials — are named separately rather than counted as failures, because a silent exclusion reads like an oversight. **The first draft of the inverted check was wrong too**, and the controls caught it: it flagged `admin/dashboard`, `partners/_show_header` and `reports/index`, all three of which carry `card-surface` — ours — because `\bcard\b` matches the "card" inside it. `float-right` came out as well, being a Tailwind utility as much as a Bootstrap one. **Thirteen controls**, one per legacy group, plus those two which must stay silent; without them the inversion would have traded six false negatives for three false positives. `state.rb` reads the new line and says `n/a` rather than 0 when the parse fails, proven against clean, 4-legacy and crashed output. Both status tables corrected — the change log's generated one and `migration-map.md`'s hand-maintained copy, whose own paragraph had guessed "the 37 are not a backlog" correctly and never checked. |
| `b4e217f4b` | **A stored XSS, found by running the CI gate nobody had run.** The branch is 600 commits ahead of `main` with no pull request, so I checked which workflows one would trigger: six, of which the design suite covers four. **I had never run `brakeman` or `factory-bot-lint`.** Brakeman failed — `LinkToHref`, weak confidence, on `organizations/_details.html.erb` — and it was real. `Organization#url` validated with `URI::DEFAULT_PARSER.make_regexp` and **no scheme argument**, which accepts any scheme, so `javascript:alert(document.cookie)` was a valid organization URL — and that field is rendered with `link_to`. An organization admin sets it; anyone who views the page and clicks runs script in their own session. Weak confidence describes the static analysis, not the exposure. **The more interesting half is that restricting the scheme is not enough.** `BroadcastAnnouncement#link` *already* restricted it to `http https` and was still bypassable, because `format:` is unanchored and matches a substring: `"javascript:alert(1) http://decoy.example.com"` satisfied it. That field is the "More info" link on **every user's dashboard** — the widest exposure of the three, and it had looked fixed. Found by testing the fix rather than trusting the pattern already there. **`HttpUrlValidatable`** is anchored and `http https` only, on all three fields that take a URL from a user (`Organization#url`, `BroadcastAnnouncement#link`, `AccountRequest#organization_website`), and **`essentials_external_link` / `essentials_safe_href`** guard the four render sites. Two layers deliberately: the validation guards one write path, and a row can arrive by CSV import, from the console, or from a backup predating it. The helper is split because the dashboard link carries its own classes and accessible name and needs the href checked rather than the anchor built for it. A dangerous URL renders as **plain text rather than nothing** — dropping it hides the problem from the only people who can fix it. **Checked before changing anything**: 0 rows across all three fields held a non-http(s) value, so nothing was invalidated; had there been any, the data migration would have had to come first. 43 examples, and **21 of 36 watched failing** against the old pattern. Brakeman 1 warning → **0, exit 0**; `factory_bot:lint` exit 0. The lesson is not about URLs: four of six gates were covered, the two that were not are where this was hiding, and it only surfaced because **`main` bumped brakeman 8.0.5 → 8.0.6** in the merge and a new version brings new checks. The post-merge routine has a step 9 now, naming both. |
| `b666920d4` | **A staged plan for landing 602 commits, and executing it corrected it twice.** `CONTRIBUTING.md` asks for PRs "limited to one particular issue"; this branch is **1,051 files, +89,606/−24,093**, and one pull request of that size gets approved on trust or left to rot. `docs/review-plan.md` splits it into stages that each leave `main` working: foundation, audit suite, fifteen per-area PRs, retire the old stack, docs. **The order is forced by one fact** — `main` has 20 Sass files and Propshaft compiles no Sass, so the pipeline switch cannot precede the view migration. The branch's own history proves the order works: Tailwind entered at commit **2 of 602** alongside Sprockets, Sass left at **22**, Propshaft arrived at **114**. Composition measured rather than guessed: **41% of added lines are documentation**, and **221 of 602 commits are "Fill in the change log hash"** bookkeeping, leaving 376 substantive — so stages are reviewed as diffs, not commit sequences. **Then I began, and stage 1 disproved itself.** It was to be the ADRs alone — reasoning first, arguable before any code. Built against `main` it failed a link check: **ADR 0010 links to `design.md`**, which arrives with the foundation, and dropping 0010 broke a second link because **0010 and 0011 reference each other**. The ADRs and the spec are one unit; they are stage 1 now, and ADR 0012 travels with the Propshaft change it describes. **The second correction is worse and quieter**: the obvious way to assemble a stage is `git checkout design -- <paths>`, and the tip's `Gemfile` has Propshaft and **no** Sass, Bootstrap or Sprockets — stage 4's removals baked in. Taking it would land stage 4 inside stage 1 and unstyle every unconverted screen. The state each stage needs is the one the branch was in when that stage finished, and it exists: `cda053539` carries `bootstrap`, `sass-rails`, `sprockets` **and** `tailwindcss-rails` together with all twenty `.scss` files. Both findings are in the plan, and the per-stage checklist gained two steps ahead of the tests: every relative `.md` link must resolve against that stage's own files, and no later stage's removals may be present — check `Gemfile` and `app/assets/`. **Stage 0 is not the migration at all**: the stored XSS is live on `main` today, same validations and the same `link_to` in two views, so it should go first and alone — but there is no `SECURITY.md` and no disclosure channel, and a public PR announcing it to an app used by 200+ non-profits is a decision for the maintainers, not for me. |
| `c84d41394` | **Stage 0 built and verified against `main`, and building it corrected the plan a third time.** `ruby bin/design/build-stage.rb 0` assembles it off `origin/main`: the `HttpUrlValidatable` concern, three models, `safe_http_url`, two specs — **41 examples, rubocop clean, brakeman 0 warnings**, and `javascript:alert(1)` rejected where `http://` is accepted. **The render guard moved out of the design system first**, because the two views that render `BroadcastAnnouncement#link` are the widest exposure and are vulnerable on `main`, and having the fix depend on `EssentialsUiHelper` meant they could only be repaired as part of a UI migration — the wrong dependency for a security fix. `safe_http_url` is in `ApplicationHelper` now and `essentials_safe_href` delegates to it. **Then the correction**: those two views still cannot go in stage 0, because the migration rewrote them entirely into `essentials_status_pill` and `essentials_row_icon_*`, so taking the files drags the migration into a security PR. The check caught it — **8 design-system references in a stage that must not have any**. Stage 0 therefore stops every new bad row (there are **0** today) and leaves `main`'s two render sites until the announcements area converts; guarding them sooner is a two-line hand patch, not an extract, and is deliberately outside the script. **`bin/design/build-stage.rb` is the durable form of this work**: unpushed branches do not survive a tree that has been rolled back eight times, so the stages are reproducible from a committed script instead. Each stage names the commit its files come from, because the tip has every later stage's *removals* baked in — its `Gemfile` carries Propshaft and no Sass, Bootstrap or Sprockets. A marker check refuses a source commit carrying a later stage's changes, **proven by pointing stage 1 at the tip: four complaints, exit 2**. Two bugs of my own found by running it: it resolved `HEAD` *after* switching branches, so the files a stage adds did not exist to check out; and a commit message with backticks was mangled by the shell. Also recorded: verifying a stage costs a `bundle install` each way, because `main`'s lockfile wants `sprockets`, `terser` and `execjs` that this branch removed. Nothing pushed anywhere but `design`. |
| `9751edca6` | **Stage 1 attempted; it fails, the reason is a fourth correction to the plan, and the script detects it now.** Assembled from `cda053539` it booted and then failed **878 of 1,753 examples**, every one reporting something like `undefined method 'address=' for StorageLocation` — nothing to do with the design system. Two causes, both about *state that persists across a checkout*. **The test database** carries whatever schema the last branch left, so `main`'s models were looking for a column this branch had dropped; a stage needs `db:test:prepare`, not just `bundle install`. And the real one: **taking `Gemfile.lock` from a historical commit drags that commit's whole dependency set backwards**. `cda053539` pins **Rails 8.0.2.1** where `main` is on **8.1.3.1**, so the stage silently downgraded Rails and could not then load `main`'s `db/schema.rb`, which declares `Schema[8.1]`. **That refines the second correction rather than replacing it**: take a file from the stage's completion commit if the branch *adds* it, but compose by hand — `main`'s current version plus this stage's additions — if `main` also has it and has moved it since. For stage 1 that is one line, `gem "tailwindcss-rails"` on `main`'s Gemfile, then `bundle install`. `build-stage.rb` refuses with exit 3 and names each file with how far behind `main` it is: `Gemfile` 5 commits, `Gemfile.lock` 30. Stage 0 still passes both checks. **What did hold**: the coexistence source is right — `cda053539` gives bootstrap, sass-rails, sprockets *and* tailwindcss-rails with 10 `.scss` files kept — the layouts are correctly additive (`essentials_*` only, `application.html.erb` untouched), and the app boots. Two of my own slips on the way: `git checkout design 2>/dev/null` was refused because of staged changes and I did not see it, so I then edited a file on the wrong branch and it appeared to have vanished — `workspace-check` said the tree was fine, which is what a real rollback would not have said. |
| `dd2ffba7b` | **Rollback #9, and the recovery tool could only see eleven of the thirteen files it put back.** Disk went to `548db78f6` again — 551 commits back, **0 differing paths**, so the restore was lossless and took a minute. The hour after it was worth more. `public/product_drive_participants.csv` and `public/vendors.csv` were on disk, absent from `HEAD`, and **in no `git status` output**: `.gitignore` gained `/public/*.csv` at `db64bbec9`, and **a rollback restores an old tree without consulting the ignore rules of the tree it overwrites**. The same file shadowed a route after rollback #8 and failed a CSV spec; the change log blamed a policy — "debris `workspace-restore` deliberately leaves alone" — where the truth was that the tool never saw it. That row and the decision-log passage are corrected in place rather than quietly fixed. It would have missed it twice over: the predicate was `git log --oneline -1 -- <path>`, and history simplification reports **0 commits** for that path. **Two wrong queries, both measured.** `--full-history` is required — the default prunes a file whose blob is plainly in the ancestor. And `--diff-filter=D`, which *sounds* like the definition of resurrected, **misses everything a merge removed**: over the whole history it yielded 7,815 paths, intersecting the disk to exactly one — the false positive — and none of the three real files. The result inverted. **The predicate that holds is content**: the bytes on disk are a version git once held *at that path*. It separates a reverted file from a runtime artifact squatting on a deleted path (`spec/example_failures.txt` has history *and* a deleting commit; rspec rewrites it every run), and matching bytes is the licence to delete, because git can give the file back. **Making it cheap took a wrong turn worth recording**: running the content test on everything took **156.7s** and timed `new_work` out, because Propshaft's digests in `public/assets/` are byte-identical to their sources so all 163 passed a "does git know this blob" filter and each cost a full-history walk. One command — `git log --full-history --name-only --format=`, 10,550 paths in 0.95s — cuts 212 candidates to **4** and the scan to **5.8s**. Ignored directories are expanded (`--ignored=matching` collapses `public/assets/`, which Rails serves before any route) under a **500-file bound**, `tmp/` holding 36,127; both scripts print what they skipped, because an unscanned directory nobody mentions is the same blind spot one level up. **Controls both ways**: before, `resurrected`=1 with both CSVs unseen; after, =3 with `example_failures.txt` and `tailwind.css` correctly rejected and `workspace-restore --yes` deleting all three end to end. The rollback count was stale in three places — `CLAUDE.md` said five, `skill-proposal-v2.md` and a skill reference said six — all now nine. `session-durability` gains both rules. rubocop clean; page-audit 0; `state.rb --check` up to date. |
| `ed2ea85b0` | **`build-stage.rb` composes stage 1's Gemfile instead of taking it, which is what the fourth correction actually requires.** The refusal added the commit before was right to stop the build; it left the fix as prose. `main` still carries `gem 'bootstrap', '~> 5.2'` — single-quoted, which is why the first grep for it read 0 — along with `sass-rails` and `sprockets`, so **stage 1's Gemfile is main's plus one line**, `gem "tailwindcss-rails", "~> 4.6"`, and `cda053539`'s copy is not needed at all. `Gemfile` and `Gemfile.lock` leave the stage's `paths`; a `gems:` key replaces them; the build step appends the line to main's Gemfile, runs `bundle install`, and **prints the resolved Rails version beside main's** so a silent downgrade cannot happen twice. It also prints the `db:test:prepare` step, the other half of that 878-failure run. **The marker check had to move with it**: it read `#{source}:Gemfile`, and with the Gemfile no longer taken from the source that is a file the stage does not use. A `stage_content` resolver now answers "what will this stage's copy say" — composed where composed, source where taken — so the propshaft-absent and sprockets/sass-rails/bootstrap-present rules are checked against the Gemfile that will exist. Stage 1 `--check`: 54 files, markers clean, no stale shared files. **The hash on the row above was wrong for one commit**: the row went in still saying `TBD` and the fill step then claimed the next commit's hash. |
| `539422c6d` | **Stage 1 assembled, run, and the suite found that its file list was a guess: 150 failures from five files nobody had listed.** It built, booted, and then failed with `Sprockets::Rails::Helper::AssetNotPrecompiledError` on `controllers/csv_download_controller.js` — an asset that is on `main`, is declared in `main`'s `manifest.js`, and has nothing to do with the design system. **The control made it tractable in minutes**: the same example passes on pristine `main`, so the stage caused it; asking Sprockets directly gave `manifest.js found: false` against `true` with 68 links on main, and one extra load path — `app/assets/tailwind`. Tailwind v4 source uses `@import "tailwindcss"`, Sprockets cannot parse it, **the whole manifest dies and every asset then reports as not precompiled**, so the error names whichever one the layout asked for first. `cda053539` had already solved this in `config/initializers/assets.rb`, with a comment saying Sprockets must serve the build and never the source — **and stage 1's paths listed no initializers at all.** Five files were missing: that initializer, `simple_form_essentials.rb`, `config.assets.css_compressor = nil` from `config/application.rb`, and two specs — `asset_resolution_spec.rb`, which pins which `application.css` wins and is the guard for precisely this, and `essentials_shell_spec.rb`. **Three rules, all now enforced by the builder rather than written down.** *A stage carries its own specs* — stage 1 listed none, and the spec that would have caught this was in the source commit, unlisted. *Additive by default, every overwrite named* — the stage silently replaced `confirmation_controller.js` and `donations_modal_controller.js`, both rewritten at `cda053539` from Bootstrap's modal to the native `<dialog>`; stage 1 migrates no views, so main's `<div class="modal">` would have reached `showModal()`, which is not a function on a div. `overwrite:` is an allowlist now and anything else is reverted and reported. *Some files are neither taken nor one-line composed* — `config/application.rb` at `cda053539` also switches the Devise layouts to `essentials_auth`, a later stage, so it is an `insert:` of anchor plus text. **Two environment traps** joined the checklist: main's lock omits `aarch64-linux` so `tailwindcss-ruby` has no executable (the builder adds the local platform), and **Sprockets caches its manifest in `tmp/cache` across branch switches**. Also found: `bin/rails` cannot run *any* rake task on this mount — it is case-insensitive, `File.exist?("rakefile")` answers true, and Rake loads the lowercase spelling and fails; `bundle exec rake -f Rakefile` works. Stage 1 `--check` now: 58 files. |
| `0282f2c71` | **Two fixes to the stage builder, both from watching it run.** The additive check reverted the script's *own* composition: its allowlist was only `overwrite:`, so the first run undid the `.gitignore` entry the `ignore:` step had written a moment earlier and the 120KB Tailwind build came back as an untracked artifact. The allowlist now includes what the script composed — the `insert:` targets and `.gitignore`. **And the builder commits the stage.** A stage left staged-but-uncommitted is a trap that has now sprung twice: the next `git checkout design` is *refused*, `-q` swallows the message, and the commit intended for `design` lands on the stage branch instead — the first time it looked as though `build-stage.rb` had vanished, the second time a builder fix was committed onto stage 1 under the wrong message. Both times `git checkout` had told the truth and nothing had read it. A built stage is meant to be a reviewable commit anyway, and a clean tree makes switching away work. Verified on the rebuild: 2 controllers reverted, `.gitignore` kept. |
| `2cdc62152` | **Stage 1 rebuilt with the five missing files: 150 failures down to 13, then to 2 that it does not cause.** `2,976 examples, 13 failures`. Ten were `essentials_shell_spec.rb` — the stage's own new spec, and **it does not belong to stage 1**: it asserts that real pages render the essentials chrome (Tailwind stylesheet and not the Bootstrap one, one `<main>`, `aria-current="page"`, self-hosted fonts) and stage 1 switches no controller to the new layout, so every example measures a later stage. Deferred to the first stage that switches a controller to `essentials_app`. *Adding a stage's specs is right; adding the specs of the stage after it only looks right.* One was `asset_resolution_spec.rb` finding a **sixth missing path**: `public/vendor/`, the Figtree and Bootstrap Icons woff2 files the built stylesheet points at — the spec earned its place immediately. **The last two were not the stage, and the controls say so rather than intuition.** Two date-range-picker examples in `distribution_system_spec.rb` failed in the full run; on **pristine main in isolation, 6 examples 0 failures**, which pointed at the stage — but on the **stage in isolation, also 6 and 0**, and the whole 55-example file passes on the stage too. So they are order-dependent or flaky across files, not a regression, and the honest next step is the full suite at the same seed (8576) rather than a claim either way. Stage 1 `--check` is 69 files. |
| `095ebf5ad` | **The stage builder puts you back where you started, and checks its own markdown links — both learned by walking into the same trap three times in one hour.** Building a stage leaves you *on* the stage branch, where `bin/design/` does not exist; the next edit to the builder then writes into a branch that has no such directory, and the next `git checkout design` is refused because the stage is half-built. It looked like a lost file once, a commit on the wrong branch once, and a `git stash pop` conflict once. **Printing "Return with: git checkout design" was not enough — it was printed all three times.** The builder now runs the checkout itself, on the success path *and* the failure path. **Step 0 of the review plan is code now**: every relative link in a markdown file the stage touches must resolve against the files the stage contains. Only the stage's own files are checked, because `main` carries **19 broken links of its own** in `docs/user_guide` and elsewhere and a check that reports those every run is one people stop reading. It found the one that matters: `design.md` links to `docs/design-decisions.md`, 9,700 lines covering every stage, which has no business arriving with the first. A `replace:` key rewrites it to a plain code span. **Watched failing first**: with `replace:` removed the build stops at exit 4 and names the link. Two false starts on that control are worth recording — the first ran the variant from `/tmp`, where `ROOT` is not a git repository, and the second was defeated by the `git stash` that was supposed to clean the tree, which restored the good file before the run. The discipline that actually works: **commit the tool, then test it.** |
| `70986b9ca` | **Stage 1 is verified.** Built from `design` onto `origin/main` as `36e927c76`, 69 files: **2,962 examples, 0 failures**, 1 pending; rubocop 647 files 0 offenses; erb_lint 442 files no errors; **brakeman 0 errors, 0 security warnings**; `factory_bot:lint` clean; every relative markdown link resolves inside the stage; no later-stage markers; Rails 8.1.3.1 matching `main`. **The seed is deliberate** — 8576 is the one that produced two date-range-picker failures on the earlier build, and produces none on this one, which settles those as flaky rather than leaving it to a shrug. Neither stage branch has been pushed and the remote has none; `build-stage.rb` rebuilds them on demand, which is the point, because an unpushed branch does not survive a tree that has been rolled back nine times. **One environment fact came out of it and is now in onboarding**: on a case-insensitive mount `bin/rails` cannot run *any* rake task. Rake tries `rakefile` before `Rakefile`, `File.exist?` answers true for the wrong case, and it then fails to load what it just found — `db:test:prepare` and `tailwindcss:build` both hit it, and `bundle exec rake -f Rakefile` is the way through. Five corrections to the assembly method got here; stages 2–5 should be expected to need their own. |










---

## Current state

Re-run the commands in [migration-map.md](migration-map.md#verifying-a-migration) to check them.

<!-- state:begin -->
Generated by `bin/rails runner bin/design/state.rb` on 2026-09-09 at `f5008dfcc`. Do not edit by hand.

| | |
| --- | --- |
| Commits on the branch | 864 |
| Files changed against `main` | 1,190 |
| Controllers on a design system layout | 63 of 65 |
| Views still using Bootstrap or AdminLTE | 0 of 350 |
| Views carrying a design system marker | 345 of 350 (indicator; a small partial can be migrated and carry none) |
| Stimulus controllers | 47 |
| Undefined legacy classes left in `app/views` and `app/helpers` | 0 |
| Routes whose request would raise | 0 of 351 |
| Code no route, render or caller reaches | 147 findings, documented in design-decisions.md |
<!-- state:end -->

Re-run at this commit: `bundle exec rspec` **3,280 examples, 1 pending** (a pre-existing `xit`) —
see the note below on the one failure; `rubocop` no offenses; `erb_lint` 432 files, no errors;
`page-audit.rb` 0 defects across 358 views, 0 with debt; `route-sweep.js` 142 screens as three
roles, no findings; `wcag-audit.js` 156 pages, 0 axe violations; `wcag22-audit.js` 151 screens,
no failures; `overlay-audit.js` 20 dialogs and 456 popovers across 154 screens at two viewports,
no findings; `form-validation-audit.js` 26 forms, no findings; `undefined-classes.py` 0 orphans;
`dead-routes.rb` 0 dead and 0 shadowed over 350; `dead-code.rb` 149 findings, all of them
documented rather than removed.

**The suite is green across eight consecutive runs, after three flakes were fixed on 2026-09-04.**
It was not before: 15 runs that day produced 5 failures across 4 distinct examples, never the same
one twice. All three diagnosable causes were found and fixed — a missing `wait_for_filters` after
"Clear all", a spec querying `DonationSite.active` unscoped and unordered where the app queries
`current_organization.donation_sites.alphabetized.active`, and `await_select2` taking a widget's id
from a non-retrying `Nokogiri` snapshot. The fourth failure was a self-inflicted
`PG::TRDeadlockDetected` from running a second `rspec` against the same test database.

Eight fresh seeds afterwards: **3,298 examples, 0 failures, 1 pending**, every time. Stated
carefully — at the previous rate of roughly one failure in three runs, eight consecutive clean runs
would happen about **4%** of the time, so that rate almost certainly no longer holds. A *low*
residual rate is not excluded and cannot be by this method: 5% would still produce eight clean runs
two times in three.

Three of those numbers moved for reasons worth naming. **354 views, not 330**: `page-audit.rb`
only knew four page kinds and a template named after a collection action matched none of them,
so 25 views had never been audited — see the entry above. **156 pages and 142 screens**, up two
each, are the two new item URLs. **4 dialogs, not the 6 recorded here before**: measured at
`c0de28eb1` as well, before any of this branch's last three commits, and it was 4 there too. The
number was already stale; the audit's nine pages include nothing these commits touched.

Not re-run at this commit, and carried forward from `af58446c6`: `wcag-manual.js` 8 pages,
`responsive-audit.js` 1,551 page-and-width combinations across 152 routes,
`form-validation-audit.js` 26 forms, `keyboard-audit.js` 141 screens at 1280 and again at 375.

The 33 views without design system markup are not a backlog. 28 are partials and 21 are ten
lines or fewer. The largest are simple_form field lists — the five `partners/profiles/step/`
forms — whose markup comes from the `:essentials` wrapper rather than from the template. The
rest carry none of their own: the `<head>` partial, chart configuration, and Kaminari's
paginator template. Mailer templates and the `static/` marketing pages are excluded from the
count altogether: HTML email is table layouts and inline styles on purpose, and `static/`
renders with `layout false` and its own stylesheet.

### Known inert leftovers

Not defects — they render nothing and change nothing — but they are still there:

- `class: 'form-horizontal'` on 12 forms. A Bootstrap 4 class that Bootstrap 5 had already
  dropped, so it was doing nothing before this work either. Left in place because removing it
  means editing option hashes rather than substituting a token, and that is the kind of edit
  that has already broken markup once on this branch.

---

## Keeping this current

Add an entry in the same change that makes it. One row: the commit, and what changed in a
sentence that will still mean something in a year.

A commit cannot contain its own hash, so the last row is filled in by the next commit. Check
the hashes are real and on the branch before you trust them — `git cat-file -e` is not enough,
it succeeds for dangling objects left behind by an amend:

```bash
grep -oE '`[0-9a-f]{9}`' docs/changelog.md | tr -d '`' | sort -u |
  while read -r h; do git merge-base --is-ancestor "$h" HEAD || echo "NOT ON BRANCH: $h"; done
```

- A **decision** — a judgement call someone could reasonably have made differently — goes in
  [design-decisions.md](design-decisions.md) as well, with its reasoning.
- A change to **how screens are built** updates [design.md](../design.md).
- A change to **what replaced what** updates [migration-map.md](migration-map.md).
- A change to the **models or their relationships** updates [domain-model.md](domain-model.md).

If a number appears in any of these documents, measure it before you write it down. Counts in
these documents have been wrong when they were recalled instead of counted, including twice
during the migration itself — which is why the verification commands are written down rather
than left as something you are supposed to remember.