utils/unified-design-system/DOCS-phase3-record.md

Phase 3 record — ~/src/utils/web_ui (@kuhyx/web-ui)

The web counterpart to Phase 1's Dart design_system. Companion to nielsen-audit.md, which holds the grid and the deferred clusters.

Shipped as web_ui-v0.3.1, consumed by dufs-cloud and awesome-mcp-explorer.

Gated like Phase 1: web_ui/.pre-commit-config.yaml + .github/workflows/web-ui-tests.yml run lint, the 100% coverage bar, the ramp proof, and a dist/-is-fresh check — that last one caught a stale build on its very first run, which is the one failure mode a committed dist/ introduces.

What shipped

Item	Notes
tokens.css	Full palette, spacing, radius, type, shadow tiers, focus ring, and the global :focus-visible rule.
RangeSlider	Reconciled from the two drifted copies; keyboard-operable.
quantile.ts	nth, clamp01, quantileValue, valueQuantile, fractionFromPointer.
fuzzyMatch	Was fuzzyMatch in dufs-cloud and matchesFuzzy in amx.
Categorical ramp	--cat-1…6; see tokens.md. New token group, see below.

FilterBar was NOT extracted — and should not be

The phase brief listed FilterBar + filter-sort.ts as the third component, to be "reconciled" between dufs-cloud (174 lines) and awesome-mcp-explorer (225). Inspection says they are a name collision, not a duplicate — exactly the Phase 1 trap the brief itself warns about, one level deeper than the three FilterSheets.

They share a name and nothing else:

	dufs-cloud	awesome-mcp-explorer
Shape	horizontal <div class="filterbar"> strip	vertical <aside class="filters"> sidebar
Controls	search input, <select>s, sort key + direction	tri-state chip pickers, no search, no sort
Domain	files (DirEntry + MetaIndex)	MCP servers (Server)
Props	onFilter + onSort	one onChange
FilterState	type/extIncludes/minSize/minDurationMs/minPixels	languages/scope/os/foss/cost/grades
SortKey	9 file keys	disjoint server keys

applyFilterSort differs in arity and parameter types. Extracting a component over this would mean inventing a generic that neither caller wants, then threading both vocabularies through it — the "shipping a widget nobody imports" failure mode, with a forced abstraction on top.

What was genuinely duplicated inside those files was extracted: the fuzzy subsequence matcher (identical algorithm, renamed identifiers) and the whole quantile.ts module (near-verbatim, comments aside).

Do not re-raise FilterBar as an extraction candidate without new evidence — specifically, a third repo whose filter surface is structurally like one of these two. A shared sort-direction toggle or filter-chip is a plausible future extraction; the bar itself is not.

passesTri/TriSelect was checked as a possible third duplicate: dufs-cloud carries extIncludes/extExcludes in its ExtensionPicker, but the logic is inline and file-extension-specific, not a shared generic. One repo is not two, so it stays in amx.

The categorical ramp (new)

The brief flagged that the design system has one accent and therefore no answer for "N mutually distinguishable hues", and said to raise it rather than invent one inline. It was raised; the decision was to design a real ramp rather than map grades onto success/warning/danger (which would have collapsed six ordinal steps into three and made A and B identical).

Six colours, chosen by search under measured constraints, documented in tokens.md and re-checkable with scripts/ramp_check.py (exits non-zero on a regression). The binding constraint turned out to be theme independence: a colour readable on both ink and paper must sit in L* 44–59, which is why the ramp is mid-toned throughout. A seventh hue is not available at ΔE 20 — the best candidate reaches 17.9.

amx's grades now map onto it. This changed those colours visibly, and for the better: the old hand-picked A/B pair (#2f8f5b green vs #4f8f2f olive) was nearly indistinguishable under deuteranopia.

Follow-ups

1. Dart side does not have the ramp. tokens.md is the source of truth for both stacks and now documents cat-1…6, but ~/src/utils/design_system ships only the original palette. A design_system bump should add it, so the "same hex values everywhere" invariant holds. Deliberately not done here: Phase 1 is tagged with six consumers, and that retag is its own change.
2. Python/Tk side likewise has no ramp (no consumer needs one yet).
3. eslint-plugin-testing-library is not installed here, so the one query-by-class in the slider test carries a prose comment instead of a disable directive (an unknown-rule disable is itself an error). If more component tests land, installing the plugin to match the consumers is the tidier answer.
4. npm cannot consume this package. utils has no root package.json, and npm's github: shorthand has no subdirectory syntax — it clones the root and fails with ENOENT (verified, npm 11.16). pnpm's &path:/web_ui works, so both consumers are pnpm. A future npm-only consumer needs either its own repo or a published tarball.

Verification performed

• pnpm test + 100% coverage in all three repos (web_ui 84, amx 405, dufs 224).
• Built bundles grepped: shared tokens present, every bespoke value absent — definitions and var() references, since checking only definitions lets a shadowed token survive.
• Real headless Chrome at 1366x768 and 1024x600: scrollWidth <= innerWidth, and :focus-visible computed as 2px solid rgb(184,134,46) after a real Tab (a programmatic .focus() does not match :focus-visible and will report no ring even when one is correctly styled).
• dufs-cloud checked against a live dufs backend, since a static file server answers 501 to PROPFIND and the app never renders its filter bar.

The bug jsdom could not catch

The first cut of the keyboard support stepped by array index. Every unit test passed, on an evenly spaced ten-value fixture. In the browser the arrow keys did nothing: ~1500 of amx's ~2981 star values are 0, so a step inside that run moved the index and left the value — and therefore the thumb, the readout and the filter — exactly where it was.

steppedValue now walks to the next distinct value. The lesson is about fixtures, not about arrows: an evenly-spaced fixture is not a distribution, and the component's whole reason for existing is that real distributions are lumpy.