# How it works

Edit a source, rebuild the outputs, run the checks.

The harness is the code in `harness/` that turns a few source files into outputs and checks that the two still agree.

## The loop

<figure class="illustration"><svg viewBox="0 0 720 240" role="img" aria-label="A loop: you edit the sources, the harness rebuilds the outputs, and the checks pass or fail. A failed check sends you back to the sources.">
<defs><filter id="sketch-loop" x="-3%" y="-5%" width="106%" height="110%"><feTurbulence type="fractalNoise" baseFrequency="0.035" numOctaves="2" seed="7" result="n"/><feDisplacementMap in="SourceGraphic" in2="n" scale="2.4"/></filter><marker id="arrow-loop" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z" fill="currentColor"/></marker></defs>
<g filter="url(#sketch-loop)" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
<rect x="24" y="72" width="180" height="84" rx="8"/>
<rect x="270" y="72" width="180" height="84" rx="8"/>
<rect x="516" y="72" width="180" height="84" rx="8" stroke="var(--sb-color-primary)" stroke-width="2"/>
<path d="M206 114 L262 114" marker-end="url(#arrow-loop)"/>
<path d="M452 114 L508 114" marker-end="url(#arrow-loop)"/>
<path d="M606 158 L606 206 L114 206 L114 162" marker-end="url(#arrow-loop)" stroke-dasharray="5 4"/>
</g>
<g font-family="inherit" text-anchor="middle">
<text x="114" y="110" font-size="17" font-weight="600" fill="var(--sb-color-foreground)">Edit sources</text>
<text x="114" y="134" font-size="13" fill="var(--sb-color-muted-foreground)">brand · tokens · contracts</text>
<text x="360" y="110" font-size="17" font-weight="600" fill="var(--sb-color-foreground)">Rebuild outputs</text>
<text x="360" y="134" font-size="13" fill="var(--sb-color-muted-foreground)">generated/ · styles</text>
<text x="606" y="110" font-size="17" font-weight="600" fill="var(--sb-color-primary)">Check</text>
<text x="606" y="134" font-size="13" fill="var(--sb-color-muted-foreground)">pass or fail</text>
<text x="360" y="232" font-size="13" fill="var(--sb-color-muted-foreground)">a failed check sends you back to the sources</text>
</g>
</svg>
<figcaption>Edit the sources, rebuild the outputs, check. A failed check sends you back to the sources.</figcaption></figure>

1. **Edit a source of truth.** Change a brand setting, a semantic token, a contract or a decision.
2. **Rebuild.** Generators write the foundation tokens, CSS and component styles.
3. **Run the checks.** `sketchbook check` verifies the sources are valid and the outputs match them.
4. **Pass the gates.** A new component stops at the planning gate and is built test-first.
5. **Read the outputs.** Storybook, the design file and the docs show the result.

```terminal
sketchbook tokens set color.primary "#0F766E"
sketchbook check
```

## What you edit

| You edit | It controls | Generated (never edit) |
| --- | --- | --- |
| `brand.config.json` | every foundation, as a preset or your own values | `spec/tokens/foundation/*` |
| `spec/tokens/semantic/*.tokens.json` | what each color or size means, per mode | `generated/**` |
| `spec/components/<name>/contract.json` and `contract.md` | a component's API, tokens and accessibility | `src/components/*/*.styles.ts`, `src/index.ts` |
| `spec/decisions/DECISIONS.md` | why things are the way they are | |

> **Note** Change the source, not the output. A hook blocks Claude's edits to generated files and names the source to change. A hand edit to a foundation token is the one exception: it is kept as a flagged override (`sketchbook check` exits 2). Any other generated file is overwritten by the next rebuild.

The harness has four parts: generators, deterministic checks (plain code, each can fail), gates for new components, and the `sketchbook` CLI that wraps them.

## Outputs

- **Tokens and CSS:** `spec/tokens/foundation/*`, `generated/**` and component styles.
- **Component library:** built from the contracts, shown in [the demo](/demo/). It is one output, and you can edit or replace it.
- **Storybook:** the preview and the reference for how a component looks.
- **Design file:** variables, styles and components synced to Figma with `sketchbook sync`.
- **Kits:** whole pages and blocks in `src/patterns/<kit>/`, built only from system components.
- **Docs:** `sketchbook docs <component>` prints a tool-neutral document.

The contracts, tokens and checks work the same whichever components you keep.

## Adapters

`harness.config.json` names the tool behind each output: `components` (lit), `tokens` (style-dictionary), `preview` (storybook), `tests` (playwright) and `design` (figma). The spec does not change when a tool does. `sketchbook swap tokens plain` or `sketchbook swap design none` replaces an adapter, rebuilds and checks.

## Next steps

- [Foundations and tokens](/concepts/foundations-and-tokens/)
- [Contracts](/concepts/contracts/)
- [Checks](/concepts/checks/)
