whynot-design/adapters/lit

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.

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.