Skip to content

One design system, in one place — and the contrast number it was getting wrong - #12

Merged
blakebauman merged 2 commits into
mainfrom
design-system-package
Sep 1, 2026
Merged

blakebauman merged 2 commits into
mainfrom
design-system-package

Conversation

@blakebauman

Copy link
Copy Markdown
Member

There are two consoles and there was one design system maintained twice: this
repo renders the OSS gateway's /console page, and fold-cloud's
services/console renders 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/ui now holds the tokens, the four woff2 subsets
with fonts-src/sources.json and subset-fonts.py, and the wordmark. This
console consumes it as a workspace dependency; fonts reach dist/fonts/ via
publicDir pointed at the package rather than a copy back into this repo.

This commit changes no output. dist/ rebuilds byte-identical — same file
set, 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:

value claimed measured
this console --fold-line #6E6E6E 4.0:1 3.67:1
fold-cloud --wire #707070 3.78:1 3.78:1

The 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 --wire to it, so its
canvas 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.md now asks of anyone touching
a token.

Consuming it from fold-cloud

Pinned by commit, the discipline fold already uses for CONSOLE_COMMIT and
CONFORMANCE_COMMIT:

"@fold-run/ui": "github:fold-run/fold-console#<40-hex>&path:/packages/ui"

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 change
    is --fold-line: #6E6E6E → #707070
  • tsc --noEmit and eslint (now covering packages/) clean
  • 91 e2e passed, including the CSP walk, the axe pass, and the topology
    specs that render --fold-line
  • pnpm install --frozen-lockfile consistent, which is what CI runs

One thing for the record: tests/dashboard.spec.ts:295 ("hints use glyphs the
shipped 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.

blakebauman and others added 2 commits August 31, 2026 21:29
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
@blakebauman
blakebauman merged commit ef4124d into main Sep 1, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant