<!-- https://getkonjo.com/design/start/overview · source: docs/design/README.md -->

# Konjo design

**Building a screen?** Don't start here — start with
[the design skill](../../.claude/skills/design/SKILL.md). It is the operational form of
everything in this directory and it routes to the right chapter.

This directory is the argument behind the instruction.

| | |
|---|---|
| [konjo-design-language.md](konjo-design-language.md) | The spine: the one idea, who we lose, the eight laws, and the index to every chapter |
| [foundations/](foundations/) | Colour, type, space, borders, metrics, elevation, motion, iconography, imagery, rank, content format, accessibility |
| [patterns/](patterns/) | Tab home, list, tile grid, detail, forms, pickers, serious actions, buttons, states, celebration, progress |
| [voice/](voice/) | The words the app uses |
| [studio/](studio/) | The desktop dialect |
| [governance.md](governance.md) | How a token is added and how these documents change |
| [provenance.md](provenance.md) | Where this came from |
| [reference/](reference/) | 44 curated screens, including the Konjo targets |
| [2026-09-29-kata-founder-interview.md](2026-09-29-kata-founder-interview.md) | **Kata** — the rebuild brief: fourteen interview rounds that reopened every decision |
| [research/2026-09-29-nike-apple-benchmark.md](research/2026-09-29-nike-apple-benchmark.md) | Nike's Podium, Apple's HIG and seventeen brand guides, crosswalked against Konjo |
| [2026-08-22-design-calibration.md](2026-08-22-design-calibration.md) | What was asked, chosen, rejected and corrected across sixteen rounds |

## The parts that are generated

Values are never hand-written. These three files are read out of the code on every run, with
every contrast ratio recomputed:

- [Token tables](../../.claude/skills/design/references/tokens.md) ← `packages/design-tokens/tokens.ts`
- [Component inventory](../../.claude/skills/design/references/components.md) ← `src/components/ui/index.ts`
- `apps/studio/src/app/tokens.generated.css` ← `packages/design-tokens/tokens.ts`

```bash
npm run design:sync      # regenerate
npm run design:check     # fail if stale, or if prose disagrees with the code
npm run design:gallery   # render every token in both themes, and screenshot it
```

`design:check` runs in CI. It is the reason this documentation can be trusted to still be
true — see [governance](governance.md) for what it does and does not cover.