# `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.