The pull request check for your DESIGN.md
Every UI change, checked against the file your agents already read
⋯ front matter, lines 1 to 18---version: alphaname: Acme Storefrontcolors: primary: "#0f1a16" success: "#4ade80"spacing: "3": 12px "4": 16pxrounded: inner: 12px card: 20pxcomponents: button-primary: backgroundColor: "{colors.success}" textColor: "#ffffff"--- ## OverviewAcme's storefront design system. Tokens live in src/app/globals.css. ## Do's and Don'ts- Use the Button component for every action; never hand-roll a <button>.- Use tokens for every color and spacing value; never a raw hex or px value. ## Decisions### Success green is reserved for verdicts`--color-success` marks a pass. Marketing highlights use `--color-action-soft`.Source: tokens.css:18.
Your DESIGN.md is read at the pull request's base, and every finding cites the line it comes from.
A raw <button> where your system has Button: use the component
Lint checks the file, Crocotaste checks the code against it
Run both. Google's design.md linter (opens in a new tab) keeps the file valid, and Crocotaste keeps the code on it.
design.md lintchecks the file- Broken token references, contrast between the file's own colors, and its structure
- Crocotastechecks the code against it
- Every pull request's UI against the tokens, components, rules and decisions the file declares
Works with the DESIGN.md you already have
Any file in Google's format, at the root of the repository or in docs/, is read as it is: the tokens and components in its front matter, the rules under its sections, and the entries under Decisions. Files written by Stitch, getdesign.md or by hand all work.
- 84
- files in the awesome-design-md gallery, every one read
- 71
- parsed in full, tokens and components included
- 10
- written as prose only, so their rules are read
- 3
- carry a YAML error Google's linter warns about too, and their rules are still read
Decisions land back in the file
Reply @crocotaste ignore with your reason, and it drafts the entry for your Decisions. Merge it, and every review and every agent follows your call. Nothing is configured on our side.
### The campaign embed can use a plain button the campaign embed can use a plain button: it renders outside the app and can't import Button. Source: src/components/Button.tsx:21.
No DESIGN.md yet
Hand these instructions to the coding agent you already use
You are working in the repository OWNER/REPO. Write a DESIGN.md at the repository root that describes this codebase's design system as it actually is, in the Google Labs DESIGN.md format (https://github.com/google-labs-code/design.md).
Read the code first, and take every value from it:
- Tokens: the design tokens defined in CSS custom properties (`--color-*`, `--spacing-*`, `--radius-*`, `--font-*`), a Tailwind config, or a theme file. Copy each name and value exactly as the code writes it, and where light and dark are both defined, record both.
- Components: the components the app imports from its own library (`components/`, `ui/`, or the package it depends on), with their variants and sizes.
- Conventions: the rules the code already follows. Which component is used for which role, how a spacing or radius value gets chosen, and what this codebase never does.
Write the file in this shape:
1. YAML front matter. `name` and `colors` are the only keys the format requires; add `version: alpha`, and `typography`, `spacing`, `rounded` and `components` wherever the code has them. Reference another token with `{path.to.token}`.
2. Markdown sections, in this order and each at most once: `## Overview`, `## Colors`, `## Typography`, `## Layout`, `## Elevation & Depth`, `## Shapes`, `## Components`, `## Do's and Don'ts`. Leave out any section this codebase has no answer for and list what you left out under `omitted` in the front matter. A repeated heading makes the file invalid.
3. Last, `## Decisions`, the one section Crocotaste adds to the format, holding this line and nothing else yet: `_Team decisions are recorded here as undated entries; each one is a rule, its reason, and its source._`
Two of those sections carry most of the weight:
- `## Overview` names the files the tokens and the components actually live in, so anyone reading a rule can go and check the value behind it.
- `## Do's and Don'ts` is one rule per bullet, each one something a reviewer could hold a diff against, and it names the patterns this codebase never uses as well as the ones it prefers.
And for every rule:
- Every rule names the token, component, class or value it means (`Dialog actions: right-aligned, gap-3, the safe choice last`), never an adjective alone (`dialogs look clean`): each reader takes an adjective its own way, and a rule nobody can check a diff against is never enforced.
- Beyond tokens, record what a design reviewer checks, wherever the code already has an answer: accessibility (every image has alt text, an icon-only button has an aria-label, focus stays visible, tap targets are at least a given size), interaction states (which controls carry hover, pressed, focus, disabled and loading states, and how empty and error states look), copy (casing, the words the product uses and the ones it avoids), and dark mode (how it is switched on and which tokens change with it). Only rules the code already follows; leave out any it does not.
Hold to these:
- Every value comes from the code. Where the repository has no token for something, say so instead of inventing one.
- Prefer the 20 tokens the app really uses to the 200 it defines and never reads, and keep the file under 400 lines.
- Check the result with `npx -p @google/design.md designmd lint DESIGN.md` and fix what it reports.
- Write DESIGN.md and change no other file.Your agent reads the repository and writes the file; you review it and land it like any other change. Until then, Crocotaste reviews against the tokens and components already in your code. If you ask for it at setup, Crocotaste opens these instructions as one issue in each repository you pick. No look to describe yet? The Claude Code plugin brainstorms one with you.

Install on one repo, open a pull request
Your first review in about a minute, 3 free and no card
- 00:00 PR #1 opened by your agent
- 00:04 queued · UI files detected
- 00:19 read tokens.css, Button.tsx at base
- 00:41 checks done · AI read running
- 00:58 On-system · approved