whynot-design/adapters/lit/README.md

# Lit reference adapter

Projects the technology-neutral IR (`ir/`) onto the Lit stack. This is the
**reference** adapter — the contract every stack adapter implements lives in
[`adapters/ADAPTER_CONTRACT.md`](../ADAPTER_CONTRACT.md).

Run it with **`make adapt-lit`** (`adapters/lit/adapt.mjs`).

## What it does

Per the contract, an adapter is **scaffold + drift-detect**, never a rewrite:

| Concern | Behaviour | Status |
|---|---|---|
| **Tokens** | **Fully generated** from `ir/tokens.json` into the `:root` block of `src/styles/colors_and_type.css`, between `@generated tokens` markers. Deterministic — re-running with an unchanged IR is a byte-identical no-op. The hand-authored type/utility CSS after the block is preserved. | **done (T06)** |
| **New component** | Generate a `<wn-*>` Lit stub (`adapters/lit/stubs/<Name>.js`) from the IR contract's prop→attribute map + a behaviour `TODO`. **Write-once** — into a staging dir, never the hand-authored tree; the human integrates it. | **done (T07)** |
| **Changed component** | Emit a **drift report** (`adapters/lit/drift/<Name>.md` + machine `_report.json`) — never overwrite the hand-authored element. | **done (T07)** |

### Drift severity

`make adapt-lit` exits `3` only on **actionable** drift — `prop-missing`,
`attribute-mismatch`, `variant-axis-missing`, `tag-mismatch`. **Informational**
issues do not gate: `non-portable` (React `style`/callbacks that inherently have
no attribute form — the Lit element is right to omit them) and `prop-extra` (the
Lit element is richer than the minimal React designbook). Resolve actionable drift
per `.claude/rules/designbook-propagation.md` (fix the stack, or change the language
in Claude Design and re-propagate — never a stack→React back-edit).

## Parity — `make parity-lit`

`adapters/lit/parity.mjs` renders every `<wn-*>` in a real browser (Playwright) and
writes `adapters/lit/parity/_parity.json` (the contract's parity-result shape):

- **Contract parity** — each element must upgrade and carry no `attribute-mismatch`
  vs its IR contract (computed statically, so no runtime type-coercion false
  positives). A prop the element *lacks* is a coverage note (already surfaced as
  drift), not a parity failure.
- **Visual parity** — a render smoke: the element renders non-empty with a positive
  box; a screenshot is saved to `adapters/lit/parity/<Name>.png` (gitignored) as the
  artifact. The `ir/exemplars/<Name>.html` are designbook **gallery cards** (a grid
  of all variants), not single-component baselines, so an automated pixel diff
  against them is not meaningful — per-component Lit appearance regression is owned
  by the Playwright baseline suite (`tests/visual/`); the exemplar is the human
  visual reference. Exit `4` on a contract or render failure.

## Directionality

One-way: **React → `ir/` → Lit**. This adapter is downstream of the IR; it never
writes back to `ir/` or to the React designbook. A change to the shared language is
made in Claude Design and re-propagated (`make designbook-pull && make ir &&
make adapt-lit`). See `.claude/rules/designbook-propagation.md`.

## Token regeneration is a visual change

Because tokens are fully generated, regenerating them can change rendered
appearance when the canonical React designbook has moved (e.g. a font-stack or
colour change). That makes the Playwright baselines diverge **by design** — it is a
human review point, not an error:

```
make adapt-lit          # regenerates tokens
pnpm test:visual        # will fail where appearance changed
# review the change, then if correct:
pnpm test:visual:update # accept new baselines
```

Never run `test:visual:update` to silence a token change without reviewing it — that
defeats the parity gate (T08).

## Exit codes

`0` ok · `2` usage/config · `3` drift detected · `4` parity failure · `5` internal.