Files

tegwick 0d688ca94a feat(designbook): technology-neutral IR + stack-adapter pipeline (WHYNOT-WP-0002 T01-T06)

Author the design language once in the canonical React designbook and project it
one-way onto each stack: React -> designbook/ -> ir/ -> adapters/<stack>/.

Phase 0 — contracts & governance (T01-T03):
- ir/SCHEMA.md + ir/schema/{component,tokens}.schema.json — neutral IR contract
  (W3C DTCG tokens; React prop -> HTML attribute mapping; non-portable props flagged).
- adapters/ADAPTER_CONTRACT.md — inputs, drift-report + parity-result shapes,
  idempotency rules, CI exit codes (0 ok / 2 usage / 3 drift / 4 parity / 5 internal).
- .claude/rules/designbook-propagation.md + DesignSystemIntroduction.md §5.1 —
  one-way directionality + drift-resolution workflow.

T04 — canonical React designbook + the missing pull tool:
- The bundled /design-sync skill only PUSHES repo->cloud; it cannot populate
  designbook/. Added scripts/designbook_pull.py + `make designbook-pull`, which drives
  the local claude binary headless (acceptEdits) so DesignSync fetch+write runs in a
  subprocess (contents never hit the orchestrator's context). Pulled 44 files;
  excludes the _whynot-design-seed/ self-copy. Corrected the docs that wrongly called
  /design-sync the pull.

T05 — IR extractor (scripts/ir-extract.mjs + `make ir`):
- ir/tokens.json (80 tokens, DTCG, var() -> {ref} alias resolution); ir/components/*.json
  (10 contracts parsed from .jsx signatures: enum/boolean/number inference, prop->attr
  map, style/callback marked non-portable); ir/exemplars/*.

T06 — Lit token adapter (adapters/lit/ + `make adapt-lit`):
- Full-gen tokens into src/styles/colors_and_type.css :root (marker-bounded, idempotent
  no-op on re-run; hand-authored type CSS preserved).

NOTE: token regen synced Lit to canonical React — fonts IBM Plex -> system stacks and 8
status tokens added. This is a VISUAL change: review and run `pnpm test:visual:update`
before merge. Remaining: T07 scaffold+drift, T08 parity, T09 runbook, T10 2nd-adapter.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-24 12:36:24 +02:00

3.3 KiB

Raw Blame History

Decision: the canonical React designbook (WHYNOT-WP-0002 · T04)

Status: RESOLVED. The canonical React designbook already exists — it is the "WhyNot Design System" project in Claude Design (fb2eef8c-c1fc-4c75-bff4-3782552e5511, owner Bernd). The remaining concrete action is the first /design-sync pull into designbook/.

Correction to the earlier premise

An earlier draft of this doc assumed the Claude Design project held only the hand-authored Lit experiment, and therefore proposed authoring a new React designbook. That premise was wrong. Inspecting the project (DesignSync.list_files / get_file) shows it already contains a real React source:

ui_kits/whynot-control/*.jsx — React function components: Atoms.jsx (Eyebrow, Tag, Button, StageDot, Stamp, Icon), Chrome.jsx, Screens.jsx, DocView.jsx, data.jsx. Props are expressed as JSX function parameters with defaults (e.g. Button({ variant = 'secondary', icon, … })).
preview/comp-*.html — per-component preview cards (the exemplar renders).
styles.css, colors_and_type.css, _ds_manifest.json, _ds_bundle.js — token/style layers + the grouping manifest.
_whynot-design-seed/ — a full copy of this Lit repo that seeded the project.

So Claude Design is genuinely canonical today, and /design-sync provides the React origin from which Lit (and any future stack) is generated. This is the directionality the workplan already assumes: React → IR → stacks.

Resolution

Canonical source: the existing "WhyNot Design System" Claude Design project. No new designbook is authored; nothing is adopted from a foreign kit.
How it reaches designbook/: run make designbook-pull (scripts/designbook_pull.py) — it drives the local claude binary headless (claude --print --permission-mode acceptEdits) so the DesignSync fetch+write happens in a subprocess, and stamps freshness on success. (The bundled /design-sync skill goes the other way — it pushes repo→cloud — so it does not populate designbook/.) Done 2026-06-23: 44 files pulled (the .jsx ui-kit, _ds_manifest.json, style layers, and preview/*.html exemplars); _whynot-design-seed/** excluded.

Consequence for the extractor (T05)

The React source is a bundled .jsx ui-kit (several components per file), not the per-component .d.ts + .prompt.md layout the T01 schema notes assumed. The neutral IR contract schema is unaffected (it describes the output shape), but scripts/ir-extract.mjs (T05) must:

read component props/defaults from the JSX function signatures in ui_kits/whynot-control/*.jsx (not .d.ts),
take grouping from _ds_manifest.json,
take exemplars from preview/comp-*.html,
take tokens from the project's styles.css / colors_and_type.css (and/or the seed tokens/*.json), normalising to W3C DTCG.

This is recorded so T05 is designed against the real source layout.

What unblocks the rest of the pipeline

Run /design-sync → designbook/ receives the React mirror (more than README).
Stamp + make designbook-sync.
make ir (T05) extracts the IR from the .jsx ui-kit + previews + manifest.
T06–T08 (Lit adapter + parity) then run against real data.

3.3 KiB Raw Blame History Unescape Escape