Repository navigation
One design system, in one place — and the contrast number it was getting wrong - #12
Merged
Merged
Conversation
There are two consoles and there was one design system maintained twice. This
repo renders the OSS gateway's /console page; fold-cloud's services/console
renders the hosted control plane. Both are Vite and Preact, both draw on
fold.run's 2026-08-10 revision, and both had their own copy of it.
The copies had already drifted, in the three ways a duplicated design system
drifts:
- the four woff2 subsets were byte-identical, but only this repo carried
their provenance — fonts-src/sources.json and subset-fonts.py. The other
had orphan copies nobody could verify;
- the wordmark path was byte-identical, under a comment saying it was taken
verbatim "so the two surfaces cannot drift" — and it had drifted, because
only this side grew wordmarkTransform for the topology node;
- the token for a drawn relationship was --fold-line here and --wire there.
Same concept, two names, two values, two rationales. The next commit is
about which of them was right.
So packages/ui holds the tokens, the fonts and their provenance, and the
wordmark. This console consumes it as a workspace dependency; fold-cloud will
consume it by pnpm's git-subdirectory syntax pinned to a commit, which is the
discipline fold already uses for CONSOLE_COMMIT and CONFORMANCE_COMMIT and is
here for the same reason: a tag is mutable, and the safety property is that
what you build is a function of an immutable upstream point.
The fonts reach dist/fonts/ through publicDir pointed at the package rather
than through a copy back into this repo, which is the point of the package —
one set of bytes, one provenance record. They stay public assets referenced at
root-absolute URLs, not module imports, for the reason already recorded above
the @font-face block: a module import lets the bundler rename them or
content-address two identical files into one, and fold's vendoring manifest
pins those four filenames exactly.
This commit changes no output. dist/ rebuilds byte-identical — same file set,
same sizes, empty diff — which is the check that matters, because dist/ is
what fold vendors into every binary it ships.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PtWxKRXJXRWj6Swqq4rJyQ
Merging the two token sets forced a choice on the one token where they
disagreed on the value and not just the name. This console had
--fold-line: #6E6E6E "clears the 3:1 bar for non-text at 4.0:1"
and fold-cloud's canvas had
--wire: #707070 "clears it at 3.78:1"
Both cannot be right, and the console's was wrong. Against Backplane
(#121212), #6E6E6E measures 3.67:1 and #707070 measures 3.78:1 — computed with
the WCAG relative-luminance formula, not read off a chart. The lighter colour
has the higher ratio, so a comment claiming 4.0:1 for the darker one had the
arithmetic backwards.
Nothing was failing: WCAG 1.4.11 asks 3:1 of any graphic required to
understand the content, and in a topology drawing the edges are the content,
so both values cleared the bar. What was wrong was the number written down —
which is the part a future reader trusts when they decide whether the token
has room to go darker. It did not have as much room as it said.
The shared token takes #707070: the higher ratio, and the one whose recorded
number is true. fold-cloud aliases --wire to it, so its canvas is unchanged in
both name and appearance.
Worth stating plainly, because it is why this sat wrong for so long: axe does
not evaluate stroke contrast. Every accessibility run over this console passed
while the claim was false, and would have kept passing. The only thing that
catches it is recomputing rather than copying the claim forward, which
packages/ui/README.md now asks of anyone changing a token.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PtWxKRXJXRWj6Swqq4rJyQ
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
There are two consoles and there was one design system maintained twice: this
repo renders the OSS gateway's
/consolepage, and fold-cloud'sservices/consolerenders the hosted control plane. Both are Vite + Preact,both draw on fold.run's 2026-08-10 revision, and both carried their own copy.
The copies had already drifted in all three ways a duplicated design system
drifts — identical font bytes with the provenance on only one side, an
identical wordmark path under a comment promising the two "cannot drift"
(they had), and one token that disagreed on its value.
Two commits, deliberately
1. The move.
packages/uinow holds the tokens, the four woff2 subsetswith
fonts-src/sources.jsonandsubset-fonts.py, and the wordmark. Thisconsole consumes it as a workspace dependency; fonts reach
dist/fonts/viapublicDirpointed at the package rather than a copy back into this repo.This commit changes no output.
dist/rebuilds byte-identical — same fileset, same sizes, empty diff. That is the check that matters, because
dist/is what fold vendors into every binary it ships.
2. The contrast correction. Merging the token sets forced a choice where
they disagreed:
--fold-line#6E6E6E--wire#707070The lighter colour has the higher ratio, so the comment claiming 4.0:1 for the
darker one had the arithmetic backwards. Nothing was failing — WCAG 1.4.11
asks 3:1 and both cleared it — but the number a future reader would trust when
deciding whether the token had room to go darker was false. It had less room
than it said.
The shared token takes
#707070. fold-cloud will alias--wireto it, so itscanvas is unchanged in name and appearance.
axe does not evaluate stroke contrast. Every a11y run over this console
passed while the claim was false and would have kept passing. Only recomputing
catches it, which is what
packages/ui/README.mdnow asks of anyone touchinga token.
Consuming it from fold-cloud
Pinned by commit, the discipline fold already uses for
CONSOLE_COMMITandCONFORMANCE_COMMIT:Verified against a scratch repo before relying on it: pnpm 10.33 resolves the
subdirectory package correctly and pins it to the SHA.
Checks
dist/byte-identical after commit 1; after commit 2 the only bundle changeis
--fold-line: #6E6E6E→#707070tsc --noEmitandeslint(now coveringpackages/) cleanspecs that render
--fold-linepnpm install --frozen-lockfileconsistent, which is what CI runsOne thing for the record:
tests/dashboard.spec.ts:295("hints use glyphs theshipped font actually carries") flaked once under parallel load and passed in
isolation and on both full runs. Pre-existing and unrelated — a hex colour
cannot change glyph coverage — but it is a real flake and worth a look.