tegwick
0d688ca94a
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>
64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# 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
|
||
|
||
1. Run `/design-sync` → `designbook/` receives the React mirror (more than README).
|
||
2. Stamp + `make designbook-sync`.
|
||
3. `make ir` (T05) extracts the IR from the `.jsx` ui-kit + previews + manifest.
|
||
4. T06–T08 (Lit adapter + parity) then run against real data.
|