coulomb/whynot-design
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(refresh): make designbook-refresh orchestrator + drift-triage runbook (WHYNOT-WP-0002 T09)

Browse Source 
scripts/designbook-refresh.mjs chains the automatable steps
(check->pull->sync->ir->adapt-lit->parity) and stops for the human drift-triage
step, propagating the adapter-contract exit codes (3=stop for triage, 4=parity
fail). Gating steps call the node scripts directly so make doesn't collapse the
3/4 codes to 2. Best-effort steps (check/pull/sync) warn and continue; --no-pull
/--no-check/--no-parity flags. Documented the loop in stack-and-commands.md and a
step-6 drift-resolution runbook in designbook/README.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-06-30 09:19:44 +02:00
parent e4e3fe069c
commit 7cf524137f
4 changed files with 130 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.claude/rules/stack-and-commands.md
View File

@@ -18,10 +18,38 @@ npx playwright test -g "inbox" # run a single visual test by name
make # list make targets (help is the default goal)
make designbook-sync # after a /design-sync pull, record changes + last-sync time → RecentChanges.md
make designbook-check # ask Claude Design (via llm-connect) if the cloud is newer; warn if mirror is stale
make ir # extract the technology-neutral IR (ir/) from designbook/ (React → IR)
make adapt-lit # project IR onto Lit: regen tokens + scaffold stubs + drift reports (exit 3 on drift)
make parity-lit # render every <wn-*> (Playwright) + assert contract/visual parity (exit 4 on fail)
make designbook-refresh # the refresh loop: check→pull→sync→ir→adapt-lit→(drift triage)→parity. ARGS="--no-pull" etc.
make recent-changes # regenerate RecentChanges.md (alias; ARGS="--range main..HEAD" supported)
make sync-styles # = node scripts/sync-shared-styles.mjs
```
### Keeping Lit current with the designbook — the refresh loop (WHYNOT-WP-0002)
`make designbook-refresh` is the single routine that re-propagates a cloud designbook
change down to the Lit stack. It runs the automatable steps and **stops for you** when
drift needs a human decision:
```
1 designbook-check → has the cloud moved? (best-effort: needs llm-connect)
2 designbook-pull → pull React designbook→designbook/ (best-effort: needs `claude` binary)
3 designbook-sync → record the diff → RecentChanges.md
4 ir → re-extract ir/ (review the git diff — the blueprint change)
5 adapt-lit → regen tokens, scaffold new stubs, emit drift reports
6 ‹you› resolve drift ← STOP if step 5 exits 3 (adapters/lit/drift/*.md)
7 parity-lit → confirm contract + visual parity
```
Exit codes propagate the adapter contract: **3** = stop for drift triage (step 6),
**4** = parity failure. Steps 1–3 are best-effort (a network/`claude`/llm-connect
gap warns and continues; the IR just re-extracts from the current mirror). After
resolving drift, re-run `make designbook-refresh --no-pull` (via `ARGS=`) to re-check
and reach parity. Drift resolution itself is governed by
`.claude/rules/designbook-propagation.md` (fix the stack, or change the language in
Claude Design and re-propagate — never a stack→React back-edit).
There is no unit-test suite — correctness is verified by full-page Playwright screenshot diffs of the two `examples/` pages (`tests/visual/ui-kit.spec.mjs`, `maxDiffPixelRatio: 0.005`). Any visual change needs `pnpm test:visual:update` + baseline review.
## Integrating the designbook