coulomb/whynot-design
2
0
Fork 0
Code Issues Pull Requests Actions 1 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

26
designbook/README.md
View File

@@ -8,6 +8,32 @@ build scripts; `tokens/` and `src/styles/` in the repo root are *derived* from i
See `DesignSystemIntroduction.md` §1 (three places) and §5 (the atelier → repo hop),
and `RecentChanges.md` (regenerated by `make designbook-sync`) for the last diff.
## Refresh runbook — propagating a designbook change to Lit (WHYNOT-WP-0002)
When the cloud designbook moves, run **`make designbook-refresh`** — it chains
check → pull → record → `make ir` → `make adapt-lit` → (drift triage) → `make
parity-lit` and stops when a human decision is needed. See
`.claude/rules/stack-and-commands.md` for the step list and
`.claude/rules/designbook-propagation.md` for the one-way governance.
**Step 6 — resolving drift (the human step).** When `make adapt-lit` exits `3`,
the refresh halts and points you at `adapters/lit/drift/<Name>.md`. For each
**actionable** issue (informational `non-portable`/`prop-extra` are not gated):
| drift kind | what it means | how to resolve |
|---|---|---|
| `attribute-mismatch` | the Lit property reflects a different attribute than the IR contract | rename the Lit `attribute:` to match the IR, or — if the *language* is what's wrong — change it in Claude Design and re-propagate |
| `prop-missing` | the IR contract has a prop the `<wn-*>` element lacks | add the reactive property + behaviour to the element, **or** if the element models it differently (e.g. a slot, or state on a child), change the React designbook so the contract matches reality |
| `variant-axis-missing` | an IR variant axis has no backing Lit property | add the variant property, or correct the axis in Claude Design |
| `tag-mismatch` | the IR contract's tag has no element; a near-named one exists (e.g. `wn-pipeline-strip` vs the hand-authored `wn-pipeline`) | decide the canonical name **in Claude Design** and re-propagate, then realign the element — do not silently rename only the stack |
**Never** resolve drift by editing `ir/` or back-editing React from the stack —
that desyncs the canonical source (see `designbook-propagation.md`). After
resolving, re-run `make designbook-refresh --no-pull` to confirm `adapt-lit` is
clean and `parity-lit` passes (exit `0`). New components get a write-once stub in
`adapters/lit/stubs/<Name>.js` — move it into `src/elements/`, implement the
behaviour, register it, and re-run.
## How it syncs
The designbook is a cloud project of type `PROJECT_TYPE_DESIGN_SYSTEM`. Sync is