The DESIGN.md standard

The format matters more than any one tool that reads it. A DESIGN.md sits in your repository, in your version control, reviewed the way the rest of your code is reviewed. Agents read it before they write UI; Crocotaste reads it after. It is not a Crocotaste file: if you stop using Crocotaste tomorrow, it keeps working.

The format

A Markdown file with YAML front matter between --- lines, then Markdown sections.

Front matter keys. version (currently alpha) and name, then optional description, omitted, and the token groups: colors, typography, spacing, rounded and components.

A value may reference another token with {path.to.token}, for example backgroundColor: "{colors.primary}", and the linter reports a reference that resolves to nothing. Components are keyed by role and state (button-primary, button-primary-hover) and carry properties such as backgroundColor, textColor, typography, rounded, padding, size, height and width.

Sections, in this order, using ## headings: Overview · Colors · Typography · Layout · Elevation & Depth · Shapes · Components · Do's and Don'ts. Any of them may be left out; the ones present must stay in order. The optional omitted key is where you list the sections you left out on purpose, so a reader can tell a deliberate gap from an oversight.

What Crocotaste takes from it

Four things: your tokens with their values, your component inventory, the conventions written as bullets under Do's and Don'ts and under the format's own sections (Layout, Shapes, Elevation & Depth, Colors, Typography, Components), and your team's decisions. A section's bullets are rules when its title names one of these: do's and don'ts, conventions, components, layout, shapes, elevation, depth, colours, palette, typography, responsive. Any leading number or letter is ignored, so a numbered file in the common layout reads too: ## 2. Color Palette & Roles, ## 4. Component Stylings, ## 5. Layout Principles, ## 6. Depth & Elevation, ## 7. Do's and Don'ts, ## 10. Decisions. An appendix is never read as rules, whatever its title names. A bullet wrapped over indented lines is read whole.

A finding may cite only those four. A line that defines nothing (a paragraph in Overview, a heading) is not something a finding can be proved against, so if you want a rule enforced, write it as a bullet or as a decision rather than as prose. Write it in things a diff can be held against, too: Dialog actions: right-aligned, gap-3, the safe choice last can be enforced, while dialogs look clean means something different to every reader, human or model. A rule that uses a word like clean, modern or consistent and names no token, component or value still counts, and the parse report (on the onboarding issue and on the pull request that merged the file) adds a line saying no review can cite it, so you know which rules to sharpen; reviews do not repeat it.

The one convention we add

A ## Decisions section, one H3 entry per decision:

## Decisions

### Success green is reserved for verdicts

`--color-success` marks a pass or a positive verdict. Marketing highlights use `--color-action-soft`.
Source: tokens.css:18.

The heading is the rule, and nothing else. An entry carries no date: a decision holds until someone removes it, and when it was written is a question your git history answers better than a heading does.

When you dismiss one of the AI findings with @crocotaste ignore <reason>, the reply drafts exactly this block, with a title, your reason and the source line filled in; in a repository that has no DESIGN.md yet, it drafts the file's first ## Decisions section. A deterministic finding gets a token nudge instead: those checks read your tokens, so the durable exception is a token, not a decision. Merge a decision and it holds on every future review and in every agent that reads the file. Crocotaste keeps no copy; there is no exception list on our side to drift out of sync with yours.

Working with the format directly

The specification and the reference CLI live at github.com/google-labs-code/design.md.

npx @google/design.md lint DESIGN.md

lint validates the file on its own terms (unresolved token references, component color pairs below the WCAG AA 4.5:1 minimum, section order), independently of Crocotaste. The CLI also has diff to compare two files, export to convert tokens to Tailwind or DTCG, and spec to print the format.

Running the linter in CI and Crocotaste on pull requests answers two different questions: the linter asks whether the file is well formed, Crocotaste asks whether the diff agrees with it.

Where to start

If you have no DESIGN.md, generate one from your code rather than writing it by hand. The point is to record what the repository already does, and an agent reading the repository is better at that than memory is.