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>
34 lines
1.4 KiB
Markdown
34 lines
1.4 KiB
Markdown
# `ir/` — technology-neutral design blueprint
|
|
|
|
This directory holds the **intermediate representation (IR)** of the whynot design
|
|
language: tokens, per-component contracts, and reference exemplars, in a form that
|
|
carries no framework assumptions.
|
|
|
|
## Decision: `ir/` is committed
|
|
|
|
`ir/` is **checked into git**, on purpose. The IR is the diffable blueprint of the
|
|
shared language — committing it means a re-extract (`make ir`) surfaces every
|
|
blueprint change as a reviewable git diff, and adapters have a stable, versioned
|
|
input. It is a build *input*, not a throwaway build *output*.
|
|
|
|
What is committed:
|
|
|
|
- `tokens.json` — all tokens, W3C DTCG format.
|
|
- `components/<Name>.json` — one contract per component.
|
|
- `exemplars/<Name>.{png,html}` — reference renders from the designbook preview.
|
|
- `schema/` + `SCHEMA.md` — the contract definitions (this is what T01 delivered).
|
|
|
|
## Direction of flow
|
|
|
|
```
|
|
Claude Design (React) ──/design-sync──▶ designbook/ ──make ir──▶ ir/ ──make adapt-lit──▶ adapters/lit/
|
|
```
|
|
|
|
One-way. The only writer of `tokens.json`, `components/`, and `exemplars/` is the
|
|
extractor (`scripts/ir-extract.mjs`, T05). **Do not hand-edit those** — change the
|
|
language in Claude Design and re-propagate. The `schema/` files and these docs are
|
|
the exception: they are authored here.
|
|
|
|
See [`SCHEMA.md`](./SCHEMA.md) for the full contract spec and a worked `Button`
|
|
exemplar.
|