The design system, and the gate that took my claim off me.

I audited my own repository as though a stranger had written it. Twenty-five of 167 routes had ever been scanned. The accessibility suite had been green for eight months and had never once loaded the rule that separates AAA from AA.

• 117Components
• 26ATS Workflows
• 174Routes Audited
• 0Axe Violations

All 117, not most of them, and that distinction matters because 93 of 117 was the number going into this pass and the 24 that were missing one turned out to be exactly where the problems had been living the whole time. A component library where coverage is nearly complete is a component library with a list of exceptions nobody's written down.

It runs from 280px, which is a Galaxy Fold shut, all the way out to 5120px, which is a 5K ultrawide, across twelve breakpoints with ninety visual baselines checked on every single run. I don't own a screen at most of those widths, which is exactly why something other than my eyes has to be doing the checking.

Honestly, most component libraries are a Storybook and a promise, so I wanted to know whether mine survived contact with a real product and built an applicant tracking system on top of it: pipeline boards, scorecards, interview schedulers, offer letters, diversity reporting. Recruitment software is data dense and permission heavy and legally exposed, and it's full of the sort of table nobody designs on purpose, so if a system holds up in there it holds up most places.

That last constraint is the whole reason the numbers in this case study are reproducible, because nothing here is coming from memory and anything that couldn't be traced back to a file didn't survive the pass. It's a low bar, and I'd rather clear a low bar in public than describe a high one and hope nobody asks.

The whole thing ran to a seven phase framework, written down before it started rather than reconstructed after: design foundations, codebase analysis, research, decisions, specification, implementation, documentation. Forty-seven documents came out of it. Eighteen research papers, three audit reports, and a fourteen document handover pack for a project with nobody to hand it over to, which is either thorough or daft depending on the morning you ask me. I wrote it that way because a system one person can run and nobody else can pick up isn't a system, it's a hostage.

The external read was twelve products, because this system has to hold up on two fronts at once: five recruitment platforms for the product surface, seven design systems for the documentation surface. Ashby, Greenhouse, Lever, Workable, iCIMS. Polaris, Carbon, Atlassian, Primer, Pajamas, Material 3, Spectrum. They're named on the page for a reason. Benchmarked against industry leaders is a sentence anyone can type and nobody can check.

The standards got read directly rather than from folklore, WCAG 2.2 and the DTCG Format Module, the whole way through. It's genuinely surprising how much accepted practice in this industry turns out to be a blog post about a specification, quoted by a second blog post, cited by a third, and by that point nobody involved has opened the actual document in years.

I want to be fair to V1 here, because it wasn't a bad build, but contrast maths on HSL is arithmetic dressed up as certainty and it'll sit there telling you two colours share a lightness while you're looking straight at the pair of them and one is obviously darker, which is not a rounding error. What it means is that every contrast call in the system was somebody eyeballing a swatch and hoping, which is fine right up until the morning you claim a ratio in public and somebody checks it.

OKLCH fixes it: same lightness number, same perceived lightness, right across the palette, and the moment that became true contrast stopped being a matter of judgement and turned into something a script could check on every commit. That one property is what made the gate possible and the register possible and every number on this page possible.

It cost a full rebuild of the token layer and 1,157 hardcoded utilities that had to be migrated before the tokens meant anything at all. Frankly, I put that off for longer than I should have, and the reason is embarrassing: the old palette looked fine.

A test written to confirm gets written against what the code already does, and a test written to fail gets written against what the standard says, which sounds like wordplay. It stops sounding like wordplay the first time you run the second kind and it comes back and takes six tokens off you and you have to go and change the palette.

The gate reads the token source directly rather than sampling rendered pages, and it models a tint on a card on a card because that's what the interface actually does, which turns out to matter, because a flat model had been telling me those pairings were fine. The composite model failed six text tokens sitting between 6.71 and 6.85 to one. Close enough to pass a glance and close enough to pass a screenshot and nowhere near close enough to pass the standard.

I could have patched the call sites instead, and a grep found that pairing in well over a hundred places, but patching them only fixes the symptom wherever a route happens to get scanned while leaving the guarantee false everywhere else. That's not a fix, it's picking the failure up and moving it somewhere nobody's looking.

This is the part I'd most want somebody else to read, because it's the part that generalises: a failing test gets fixed the day it fails, and a test that never runs gets trusted for exactly as long as nobody looks at it, with everything downstream of it inheriting that trust without ever having earned it.

Each of these got found by reading the configuration rather than the code, which isn't where anybody looks first. Four of the five were a single line, and every one of them had been sitting there passing. The fifth was an import that had been sitting in a setup file for months, correctly written and correctly registered and never once called by any of the 92 test files it was sitting there to serve.

1. The AAA target had zero automated coverage

   e2e/accessibility.spec.ts

   The axe suite ran with the tags wcag2a, wcag2aa, wcag21a, wcag21aa and wcag22aa. There's no wcag2aaa in that list, and without it axe never loads color-contrast-enhanced, which is the 7:1 rule.

   The suite was green for eight months and had never been asked the question the badge was making. A test that doesn't load a rule can't fail it, and a green suite reads identically either way.

2. Route coverage was fifteen percent

   the axe suite, against the app

   The suite enumerated 25 routes. The app had 167 page.tsx segments at the time. Of 114 component documentation routes, 6 were scanned.

   A result about 15 percent of a system read exactly like a result about the system. Nothing in the output said which one it was.

3. npm run test never terminated

   packages/react/package.json

   The script was declared as "test": "vitest", which is watch mode. The README documented running it with a coverage flag, and that command didn't return locally. It passed in CI only because vitest detects CI=true and switches to a single run.

   The documented command was broken for every human who ran it, and the one context where it worked was the context nobody watches.

4. A single mis-pathed line disabled a check

   .prettierignore

   The file contained public/sw.js, and that pattern anchors at the ignore file's own directory, so it matched a path that doesn't exist. The real file lives at apps/docs/public/sw.js and is regenerated on every prebuild, so format:check could never pass after a build.

   The line directly beneath it used the correct full-path form. One line that looked exactly like its working neighbour, silently doing nothing.

5. jest-axe was wired up and never called

   src/test/setup.ts

   The setup file imported toHaveNoViolations and registered it. Zero of 92 test files ever called it.

   The README described "jest-axe per component". The import was real, the registration was real, and the assertion was never made once.

Not one of these is a bug. Every one is a check that looked like it was running. That is the category worth worrying about, because a failing test gets fixed on the day it fails, and a test that never runs gets trusted for as long as nobody looks.

Level A, not AAA, not AA, the most basic tier of the whole standard, sitting underneath a system I'd been advertising as meeting the top one. Truthfully that's the part that stung, and it wasn't the enhanced contrast work that caused it, or the tokens, or anything I'd actually been worrying about, it was the coverage.

Then the gates started returning things no amount of reading the code would ever have surfaced. Every skip link in the product rendered as an invisible one by one box across 37 routes, because a hand written sr-only rule with !important beat the focus style that was meant to reveal it, and when you take the !important out the cascade layers go and beat it again. That's 2.4.7 Focus Visible, Level AA, and I found it while investigating AAA.

Every sheet in the system produced an unnamed dialog, mobile navigation included. A menu marked the current page by colour alone whenever it was driven by onClick instead of href. A rich text editor's toolbar states had never worked at all, because it read the selection during render and held no state to re-render with. Not one of those is a thing you find by reading code, or by clicking round the product for an afternoon, or by asking somebody to have a look at it for you. You find them by writing something whose entire job is to fail you, and then running it.

Read the full account of the audit

1. Say AA, earn AAA

   Stop making a blanket AAA claim the evidence didn't support.

   The system was advertising AAA while shipping text that failed AA. The honest position is AA as a non-negotiable baseline, AAA where the visual language genuinely allows it, and the exceptions published rather than omitted. Loses a louder headline. Gains a claim that survives someone checking it.

2. Do not fabricate the demo data

   Label demo data as demo data, and make the interactions believable client-side instead.

   An ATS demo shows diversity and pipeline metrics. Inventing numbers there isn't a harmless placeholder. It's fabricated D&I reporting, on exactly the content where a reader is most entitled to trust what they see. A less impressive-looking dashboard. It's not a close call.

3. Migrate colour with the redesign, not before it

   Fold roughly 1,751 hardcoded palette utilities into the redesign rather than sweeping them mechanically first.

   A blind sweep would have touched every screen with no visual review and no way to tell a fix from a regression. Doing it behind semantic tokens during the redesign meant the visual work and the token work landed together, verified together. Slower. The alternative was faster and unverifiable.

4. Diagnose before prescribing

   Treat 2,430 TypeScript errors as a symptom before treating them as a workload.

   The obvious reading was an untyped library needing a rewrite. It was a publishing defect: the library shipped no declaration files, so every consumer silently fell back to bundled JavaScript and every component's props collapsed to any. Emitting declarations took it to 599. A single directive in a service worker, stripping the DOM lib from the whole program, accounted for the rest. Days of investigation before a line was changed. It replaced a rewrite with a config fix.

Publishing what's still missing is the same discipline as publishing the exceptions in the register rather than quietly leaving them out. An exception you disclose is a decision. One you leave out is a defect, sitting there waiting for somebody else to find it and tell you about it in public.

The first of these is the one I'd lead with if somebody asked me what's weakest here, because it's the gap between a thing being verified and a thing being used, and I've spent this whole case study arguing that verification is what makes a claim worth anything, and it does, but it still isn't the same as somebody else running it on their machine.

1. Nobody has ever installed it

   The package sits at 0.0.1 and has never been published, and everything about it is verified. The exports map resolves under both node16 ESM and bundler resolution, the use client directive survives on all 23 chunks that need it, and publint and attw both pass against the real tarballs.

   Verified isn't used, and the distance between a gate saying the tarball's correct and somebody installing it on their own machine and having it work is exactly where packaging bugs live, and this pass found two of them sitting in that gap. Both invisible to a green build. So the strongest honest claim is packaged correctly, not shipping. I'd rather say the smaller true thing.

   Cost to close An afternoon. The steps are written down and the verification is already automated.

2. Storybook is not hosted

   117 components and more than 500 stories, and the only way to look at any of them is to clone the repository and run a dev server.

   For a design system the browsable component explorer is the shop window, and mine is currently a locked door with a note on it saying the stock's excellent. The static build works and emits 239 files. It isn't hosted because I hadn't got to it, and that's the whole reason.

   Cost to close Under an hour on Vercel.

3. Nothing reviews a component visually on its own

   The visual suite covers 14 routes across 2 themes and 3 widths, which comes out at 84 snapshots of pages. No component is snapshotted on its own. So a regression in one variant of one component gets caught only if that variant happens to turn up on one of those 14 routes.

   Chromatic's installed and registered and has no project token and no CI job, so it does nothing at all. That's the sixth thing on this site that was wired up and never ran, and I found it the same way as the other five. By reading the configuration rather than trusting it.

   Cost to close About an hour, and free at this volume.

None of this is hard and none of it's expensive. It's on the list because the list is public, and a list of everything that went well is a brochure.