Detecting design drift between two repos with a hash
Two sites share a design system by copying two files. Nothing enforced that, so a check hashes both against the original and fails when they diverge. It also reports when it cannot see the original, which is the part most checks get wrong.
The documentation moved into its own repository and its own deployment. It should look identical to the product it documents, and the way it achieves that is by containing copies of two files. Nothing made those copies stay in step, so a check does.
The problem
Two sites, two repositories, one visual identity. The shared surface is small: a Tailwind config carrying the colour, spacing and type scales, and a stylesheet carrying the token definitions and base layer. Everything else differs.
The correct answer is to publish those as a versioned package and depend on it from both. That is also a package to build, version, release and consume, for two files and one consumer, before anyone knows how often they will actually change. Doing it too early is its own cost.
So they are copies, which is a decision with a known failure mode. Somebody adjusts a colour ramp on the product, ships it, and the documentation quietly stops matching. Nobody notices, because nobody has both sites open beside each other, and the drift accumulates in small steps that each look fine alone.
The gap between "we should share this properly" and "we have shared it properly" is where the project actually lives. The question is what to do during it.
What the check does
At build time, hash both local files, fetch their counterparts from the other repository's default branch, hash those, and compare:
const digest = text =>
createHash('sha256').update(text.replace(/\r\n/g, '\n').trimEnd()).digest('hex');Line endings are normalised and trailing whitespace trimmed before hashing, so a checkout on a different platform is not reported as a design change.
A hash rather than a diff, for one reason: the answer required is binary. Either these files are the same or they are not, and if they are not, a human has to decide which version is correct, which is not a decision a build step can make. Computing a diff would mean rendering it in CI output nobody reads, and inviting an argument about which hunks are acceptable drift. There is no acceptable drift. They match or the build fails.
The failure message tries to be useful rather than merely correct:
[design] tailwind.config.js DIFFERS from eight-west/fred
Either copy the upstream version over, or land the same change in both
repositories. To see what differs:
curl -s https://raw.githubusercontent.com/.../tailwind.config.js | diff tailwind.config.js -It names both remedies, and hands over the command that produces the diff it deliberately did not compute. A failing check that leaves you to work out what to do next has done half its job.
The part most checks get wrong
The product repository is private. An unauthenticated fetch of its raw files returns 404, so without a token the check cannot see anything to compare against.
The naive handling is to treat unreachable as fine and pass. The check then reports success on every build, forever, having verified nothing, and the first person to see green concludes the design is in sync.
Instead, when every file is unreachable it warns and says exactly that:
[design] could not reach any upstream file
This check is INERT until eight-west/fred is reachable
Passing here proves nothing about whether the design has drifted.That last line is the whole point. A check has three outcomes rather than two: it passed, it failed, or it did not run. Collapsing the third into the first is how a suite accumulates checks that everyone trusts and none of which are doing anything. It is worth writing that sentence into the output, where somebody reads it, rather than into a comment nobody opens.
The distinction generalises past design tokens. Any check that depends on a resource it might not reach, an external API, a service that might be down, a credential that might be absent, has this third state, and the default handling of it is usually silence.
What it costs
It detects, it does not fix. The script's own header comment says so: the real fix is publishing the tokens as a package, worth doing once the two get edited often enough that this check starts firing. The check is explicitly a placeholder that reports when its own replacement has become worth building.
It compares against a moving target. The upstream fetch is the default branch, so an unmerged change to the tokens does not exist yet and a merged one is immediately authoritative. A docs build can start passing or failing because of a commit in another repository, with nothing in this one having changed.
Two files is a guess. The shared surface was decided by inspection, not derivation. A third file that matters and is not on the list drifts unobserved, and nothing would reveal that.
Where it breaks
It is inert today. The token was never set, so it has warned on every build since it was written and compared nothing. Being loud about that is the difference between a known gap and a false sense of coverage, but it is still a gap, and the fix is one repository secret.
Byte equality is stricter than visual equality. A reordered key or a reformatted comment fails the check without changing a single rendered pixel. That is the right trade for two rarely-edited files, since the alternative is parsing and comparing semantically, which is a much larger thing to maintain. It does mean the check will occasionally cry wolf, and a check that cries wolf gets disabled.
A shared token is not a shared component. Identical configs mean the two sites can express the same design. They do not mean they do. Every component in the documentation is a separate implementation, and nothing compares those at all.
More on what the documentation covers. FRED itself is at biofred.us.
References
Tailwind CSS. Theme configuration.