## Designbook propagation & adapter governance (WHYNOT-WP-0002)

The whynot design language is **technology-neutral**. It is authored once and
projected onto each UI stack through an intermediate representation. These rules
keep that flow one-way and the stacks in sync.

### Directionality — one way only

```
Claude Design (React, canonical)  →  designbook/  →  ir/  →  adapters/<stack>/ → stack source
```

- **Claude Design (the React designbook) is the source of truth** for the *language*.
- **Never hand-edit `ir/`** — `ir/tokens.json`, `ir/components/*.json`, and
  `ir/exemplars/*` are written only by the extractor (`scripts/ir-extract.mjs`,
  `make ir`). They are committed so blueprint changes show up as a git diff.
  Authored-by-hand exceptions: `ir/schema/`, `ir/SCHEMA.md`, `ir/README.md`.
- **Never back-edit React/Claude Design from a stack.** A Lit (or any stack) change
  that should alter the shared language must be made in Claude Design and
  re-propagated. A direct stack→React edit that bypasses Claude Design is a
  governance violation — it desyncs the canonical source from the implementation.
- **Adapters never overwrite hand-authored behaviour.** Tokens regenerate fully;
  new components get stubs; changed components get a **drift report**, never a
  rewrite. See `adapters/ADAPTER_CONTRACT.md`.

### When the cloud designbook moves

Run the refresh sequence (orchestrated by `make designbook-refresh`, WHYNOT-WP-0002
Phase 5); do not shortcut it:

1. `make designbook-check` — detect the cloud designbook moved ahead.
2. `make designbook-pull` — pull the latest React designbook into `designbook/`
   (drives the local `claude` binary headless via `DesignSync`; stamps freshness
   itself). The bundled `/design-sync` skill *pushes* repo→cloud and does **not**
   populate `designbook/` — use `make designbook-pull` for the pull.
3. `make designbook-sync` — record the diff in `RecentChanges.md`.
4. `make ir` — re-extract the IR; **review the `ir/` git diff** (the blueprint change).
5. `make adapt-lit` — regenerate tokens, scaffold new components, emit drift reports.
6. **Resolve drift** (human) — fill/adjust Lit behaviour per `adapters/lit/drift/*.md`.
7. `make parity-lit` — confirm appearance + contract parity (gate).

### Drift triage

A drift report (`adapters/lit/drift/<Name>.md`, command exit code `3`) is resolved
by a human, not the adapter:

- Decide direction: stale stack → fix the stack to match IR; language should change
  → edit Claude Design and re-propagate (never patch only the stack).
- **Non-portable props** (React objects, render props, callbacks) are surfaced as
  drift on purpose and must be handled explicitly — never silently dropped.
- A report is closed when a fresh `make ir && make adapt-lit` produces no issues
  for that component and `make parity-lit` passes (exit `0`).

### Exit codes (CI)

`0` ok · `2` usage/config error · `3` drift detected (stop for human triage) ·
`4` parity failure (fail) · `5` internal error. See `adapters/ADAPTER_CONTRACT.md`.

Full narrative: `DesignSystemIntroduction.md` §5.1.