whynot-design/ir

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 for the full contract spec and a worked Button exemplar.