The diff that audited the design system
What happened when I stopped reading design values by eye and started pulling them through the API.
Design reviews run on eyes. Eyes are how we check that the build matches the design, that the chip is the right amber, that the words on the screen are the words in the file. Here’s the problem I can now prove: eyes normalize. They see what should be there. The only reviewer that doesn’t is a diff.
This is the story of three findings in one week, all caught the same way, and what they changed about how I treat design files.
The setup
I was mapping a coded prototype against the production component library: a 39-row inventory pairing each prototype component with its production counterpart, so engineering could adopt rather than rebuild. Matching by screenshot felt rigorous and wasn’t. So I changed the method: pull the design file’s actual token values through its API, pull the production palette from its source, and compare them byte for byte. No eyedropper, no judgment calls. Values against values.
20 of 21 status-chip tone values came back byte-identical. A perfect translation, except for the twenty-first.
Finding one: the collision
The mismatch wasn’t my error. Chasing it showed that in the production palette, the error foreground and the warning foreground were the same colour: byte-identical hex values in two different ramps. An error chip and a warning chip differed only by background tint. Severity, the one thing a status colour system exists to communicate, was invisible at the component level.
Same foreground value in both. Only the tint behind it differs.
The signature, one ramp’s value sitting in another ramp’s slot, says palette copy-paste, years old. It had survived every design review, every QA pass and every screenshot comparison, because both chips looked plausible on their own and nobody’s eye diffs hex values across a palette file.
I didn’t fix it. That matters: it was production’s palette, not mine, so it was filed as a finding for the team that owns it, with the diff as the receipt, rather than silently “corrected” by an outsider. Findings travel better than fixes you weren’t asked for.
Finding two: the invented word
The same extraction pass caught my own build rendering a status word that appeared zero times in the design file: a plausible synonym the code had invented, which no human had flagged because it sounded professional. The full ruling is in Part One: the delivery system. The short version is that it became a standing law: display vocabulary is a closed set ruled from the design source, and anything not in the set is an invention, however sensible.
Finding three: the audit points both ways
Then the diff turned around and caught me. Two adjacent lifecycle states in my own design file shared an identical tone family, possibly on purpose, possibly my own copy-paste. I’d looked at those components dozens of times. The method doesn’t care whose file it is: it got flagged for a ruling like everything else, instead of being quietly “fixed” to what I assumed I’d meant.
That’s the part of this story I trust most. A verification method you only aim at other people’s work isn’t verification. It’s ammunition.
What the inventory taught besides colours
Crawling the component workshop for the mapping produced two structural lessons.
Coverage lies in both directions. One production component matched my prototype’s almost word for word, with hundreds of lines of tests behind it, and had no workshop entry at all. Meanwhile the workshop’s most-represented component existed as ten near-identical copies in a duplication tree. Being in the catalog measures neither existence nor quality. Audits crawl the codebase, not the catalog.
Consolidation is an adoption gate, not a chore. You can’t adopt components out of a duplication tree. That turned a months-old cleanup backlog into the critical path, and turned my machine-built inventory into a gift for the designer who’d been asking for exactly that call. That partnership shipped its first win within weeks: a consolidated icon library, announced to all of engineering.
The method, portable
- Never eyedrop. Pull values through the design tool’s API and the palette’s source file.
- Diff byte for byte. A near-match is a list of specific questions, not a pass.
- Vocabulary is values too. Labels get diffed like hex values.
- File findings where ownership lives; fix only what’s yours.
- Aim it at your own files first. Eyes normalize, including yours. Diffs don’t.
The token parity and the foreground collision were verified by literal hex comparison in August 2026; the icon-library consolidation shipped in September 2026. The delivery machinery that made this check routine, the gates, the rulings and the law, is Part One, and the rulebook itself is the Foreman Method.
Building something in this lane? Email me.