tegwick
2de30beb7b
Make ir/ the unit of versioned downstream consumption so consuming repos can pin a version, inspect it, and follow changes at their own pace. - T03 ir/manifest.json: per-version inventory + diff anchor with deterministic sha256-over-canonicalised-JSON hashes; no-churn generatedAt; manifest schema. - T07 ir/INDEX.md: human-readable catalog generated by make ir. - T04 .whynot-design.lock sync-point format + lock schema. - T05 npx @whynot/design drift: consumer drift-check (bin entry), exit 0/2/3, --json/--update/--manifest/--version/--lock. - T06 CONSUMING.md guide + examples/consumer-fixture/ runnable demo; README + MultiFrameworkSupport cross-links; fix README version pin (@0.3.0 not @v0.3.0). - T09 CONSUMER_CONTRACT_PARITY.md design-only note (live-UI parity deferred). T02 (publish) and T08 (showcase, blocked on WP-0002 T11) remain wait. Repo stays in dev mode; no outward publish performed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
45 lines
2.2 KiB
Markdown
45 lines
2.2 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.
|
|
- `manifest.json` — the per-version inventory + diff anchor: `{ schemaVersion,
|
|
designVersion, generatedAt, tokensHash, components: [{ name, group, hash }] }`,
|
|
where each hash is a deterministic content hash (sha256 over canonicalised JSON).
|
|
This is what a consuming repo pins against and what the `drift` check compares
|
|
(WHYNOT-WP-0003). Validated by `schema/manifest.schema.json`.
|
|
- `INDEX.md` — the human-readable catalog, generated from the same contracts:
|
|
per component its group, description, props/variants/slots/events, and a link
|
|
to its exemplar. Browse a version without cloning or running anything.
|
|
- `schema/` + `SCHEMA.md` — the contract definitions (this is what T01 delivered).
|
|
|
|
`manifest.json` and `INDEX.md` are generated by the same extractor as the rest of
|
|
`ir/` and share its one-way rule — **do not hand-edit them.**
|
|
|
|
## 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.
|