feat(workbench-ui): design system v1 scaffold (ADR-0162 Branch 1) (#295 )

* feat(workbench-ui): design system v1 scaffold

* fix(workbench): close R1 (GroundingSource enum coverage) + R4 (digest test)

R1 — Promote GroundingSource to a typed Literal in core/epistemic_state.py
so it has the same single-source-of-truth shape as ReviewState.  The
existing epistemic_state_for_grounding_source() function already
enumerates the six labels (pack, teaching, vault, partial, oov, none);
this codifies them.

scripts/dump-enums.py now snapshots GroundingSource via the existing
literal_values helper.  workbench-ui's enumCoverage.test.ts gains a
fourth assertion that the badge mapping matches the Python source
1:1.  Adding a grounding-source value on the Python side without
updating the badge fails the build-time test loud — same discipline
as the other three enums.

R4 — Add an explicit DigestBadge test to StableJsonViewer.test.tsx:
asserts the badge text matches the SHA-256 prefix of the source bytes,
and clicking the badge copies the FULL digest (not the truncated
prefix).  Recomputes the expected digest via crypto.subtle to avoid
hard-coding a hex string that could drift.

R2 (component-level reduced-motion enforcement), R3 (EmptyState
copy-CLI affordance), and R5 (`uv run core` packaging paper cut) are
deferred — R2/R3 become meaningful with W-027/W-029, R5 is a
packaging-layer concern outside this PR's scope.

Validation:
- pnpm test: 19 passed (was 17, +1 enum coverage, +1 digest test)
- pnpm build: clean
- pnpm test:enum-coverage: 4 passed
- core test --suite smoke -q: 67 passed

2026-05-26 11:33:27 -07:00

2.3 KiB

Raw Blame History

Workbench Design System v1

This document records the Branch 1 substrate for ADR-0162, cross-referenced with ADR-0160 and ADR-0161.

The implementation lives in workbench-ui/. The preview page is /preview:

cd workbench-ui && pnpm install && pnpm preview

Branch 1 is intentionally static and read-only. It adds no backend, no API client, no route shell beyond /preview, and no runtime mutation surface.

Token Substrate

Tokens are defined in workbench-ui/src/design/tokens/tokens.css and mirrored to typed TypeScript by workbench-ui/scripts/generate-tokens.ts. The build prehook regenerates tokens.ts; the token test fails if CSS and TypeScript diverge.

The theme is dark-only. Fonts are self-hosted from workbench-ui/public/fonts/ and referenced through local @font-face rules only.

Badge Tables

Badge components live under workbench-ui/src/design/components/badges/. Each component accepts a typed enum value, never an arbitrary string.

Badge	Values	Source
`EpistemicStateBadge`	15	`core/epistemic_state.py`
`NormativeClearanceBadge`	4	`core/epistemic_state.py`
`ReviewStateBadge`	4	`teaching/proposals.py`
`GroundingSourceBadge`	6	ADR-0162 Branch 1 contract
`TraceHashBadge`	copyable digest	ADR-0153 / ADR-0160

scripts/dump-enums.py performs a read-only AST walk over the Python enum sources. pnpm test:enum-coverage regenerates workbench-ui/enum-snapshot.json and asserts exact UI coverage so engine enum drift fails loudly at build/test time.

JSON Viewer

StableJsonViewer preserves raw source spans for strings and numbers, renders object keys in deterministic lexicographic order, copies JSON Pointer paths, renders a source-byte SHA-256 badge, supports side-by-side leaf diffs, and refuses inline rendering above 16 MiB.

Motion And Keyboard

All motion uses tokenized durations/easing. prefers-reduced-motion: reduce collapses tokenized durations to instant.

The preview page installs the Branch 1 keyboard baseline:

Cmd+K / Ctrl+K opens the stub command palette.
Esc closes overlays.
Interactive primitives use --color-focus-ring.
Preview tab order follows DOM order.

2.3 KiB Raw Blame History