tegwick
0d688ca94a
Author the design language once in the canonical React designbook and project it
one-way onto each stack: React -> designbook/ -> ir/ -> adapters/<stack>/.
Phase 0 — contracts & governance (T01-T03):
- ir/SCHEMA.md + ir/schema/{component,tokens}.schema.json — neutral IR contract
(W3C DTCG tokens; React prop -> HTML attribute mapping; non-portable props flagged).
- adapters/ADAPTER_CONTRACT.md — inputs, drift-report + parity-result shapes,
idempotency rules, CI exit codes (0 ok / 2 usage / 3 drift / 4 parity / 5 internal).
- .claude/rules/designbook-propagation.md + DesignSystemIntroduction.md §5.1 —
one-way directionality + drift-resolution workflow.
T04 — canonical React designbook + the missing pull tool:
- The bundled /design-sync skill only PUSHES repo->cloud; it cannot populate
designbook/. Added scripts/designbook_pull.py + `make designbook-pull`, which drives
the local claude binary headless (acceptEdits) so DesignSync fetch+write runs in a
subprocess (contents never hit the orchestrator's context). Pulled 44 files;
excludes the _whynot-design-seed/ self-copy. Corrected the docs that wrongly called
/design-sync the pull.
T05 — IR extractor (scripts/ir-extract.mjs + `make ir`):
- ir/tokens.json (80 tokens, DTCG, var() -> {ref} alias resolution); ir/components/*.json
(10 contracts parsed from .jsx signatures: enum/boolean/number inference, prop->attr
map, style/callback marked non-portable); ir/exemplars/*.
T06 — Lit token adapter (adapters/lit/ + `make adapt-lit`):
- Full-gen tokens into src/styles/colors_and_type.css :root (marker-bounded, idempotent
no-op on re-run; hand-authored type CSS preserved).
NOTE: token regen synced Lit to canonical React — fonts IBM Plex -> system stacks and 8
status tokens added. This is a VISUAL change: review and run `pnpm test:visual:update`
before merge. Remaining: T07 scaffold+drift, T08 parity, T09 runbook, T10 2nd-adapter.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
# 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 from the IR contract's prop→attribute map + a behaviour `TODO`. | T07 |
|
|
| **Changed component** | Emit a **drift report** (`adapters/lit/drift/<Name>.md`) — never overwrite the hand-authored element. | T07 |
|
|
|
|
## 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.
|