Generate your DESIGN.md

Crocotaste never writes DESIGN.md. Your coding agent writes it from instructions Crocotaste supplies; you edit and merge. That merge is the trust boundary.

A DESIGN.md describes a design system in a form both people and coding agents can read: tokens with their values, the component inventory, the conventions the code already follows, and the decisions your team has made. It is an open format from Google Labs, and it is worth having whether or not you review pull requests with it: the same file that sharpens a review is the file your agents read before they generate the next screen.

Crocotaste's part is to ask for one and then read it. If you have not installed the App yet, start at Get started.

The flow

On the setup page, choose "Open an issue with instructions for your coding agent". You can skip it and come back later.
Crocotaste opens one issue per repository, titled "Generate your DESIGN.md". The body is a short note and a collapsed block of instructions.
You hand that block to Cursor, Claude Code, Copilot, Codex or whatever your team uses. The agent reads the repository and writes DESIGN.md at the root, and asks for nothing else in your repository.
You review it, edit what it got wrong, and land it the way you land anything else. Once it reaches your default branch Crocotaste parses the file, comments the parse report on the pull request that merged it, and closes the issue. The report reads:
```
Parsed DESIGN.md · 42 tokens · 12 components · 6 conventions · 0 decisions
```

From then on every review of that repository cites the file, and the dashboard shows those counts for the repository.

A DESIGN.md in another shape, a hand-written one with no YAML front matter, say, opens fine and reads as nothing. Then the report says so instead, names what Crocotaste reads (tokens and components from the front matter, rules from the bullets under ## Do's and Don'ts, ## Layout, ## Shapes and the other sections, decisions from ## Decisions), the issue stays open, the dashboard reads DESIGN.md · nothing read, and the next push that touches the file is read again:

Found `DESIGN.md` and read nothing from it · 0 tokens · 0 components · 0 conventions · 0 decisions

What the instructions ask for

They ask the agent to read, not to invent. That distinction is the whole value: a DESIGN.md full of plausible tokens nobody uses would make every review cite a fiction.

Tokens as the code spells them, with their real values: CSS custom properties, a Tailwind config, a theme file.
Components exported from your component library, with their variants and sizes.
Conventions the code already follows: which component is used for which role, how spacing and radius get chosen, what is never done. One rule per bullet, each one something a reviewer could check.
An empty ## Decisions section, ready for your team's first decision.

They also tell the agent to keep the file short, to prefer the 20 tokens the app really uses over the 200 it defines and never reads, and to change no other file. The exact text is on the public DESIGN.md page with a copy button, so you can hand it to an agent without installing anything.

When you change DESIGN.md later

A push to your default branch that touches DESIGN.md makes Crocotaste re-read it and comment the same parse report on the pull request that merged the change.

That comment is the receipt. It tells you what Crocotaste actually found in the file, which is the only way to notice that a section you added parsed as nothing.

Reviews without a DESIGN.md

They still run. Crocotaste parses the references straight out of the repository (CSS custom properties, a Tailwind config, component exports) and the summary says parsed system only rather than naming a file. If there is nothing at all to check against, no tokens and no components either, the review is skipped, free, and the check points at DESIGN.md.

What you lose is the part of your system that is not in code: conventions, and your team's decisions. A raw hex that duplicates a token is caught either way; "this uses the success green for a marketing highlight" is only catchable if somebody wrote it down. That is what @crocotaste ignore <reason> is for: dismissing an AI finding drafts the decision for you.