AI Guides › Playbooks
By Nigel Guy · 7 min read
The default way to get a front end from a coding agent is to type "make it clean and modern" and accept whatever arrives. It feels fine because the page renders, the buttons work and nothing is broken. It is also why so many AI-built landing pages share the same gradient, the same card grid and the same safe sans-serif: the agent was given no taste, so it averaged everyone's.
The rule: never ask an agent to design from adjectives. Hand it one plain-text design file, make it read that file first, and check the result against the file's own Do's and Don'ts.
The idea is a "taste library": single Markdown files, each describing one site's visual system (colours, type, spacing, layout rules, guardrails), that an agent reads before it writes any UI. Two real, public projects sit behind it.
I could not confirm a single official "Brand Taste Library" product. This guide is therefore built around the durable part: the file format and the habit of using one.
The collection's files use nine sections: visual theme and atmosphere, colour palette and roles, typography rules, component styling, layout principles, depth and elevation, Do's and Don'ts, responsive behaviour, and an agent prompt guide. Google's own spec uses a slightly different canonical order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Both agree on the useful part: tokens for the numbers, prose for the judgement, and an explicit list of things not to do.
The Do's and Don'ts section does the most work. A hex value tells the agent what blue is. A rule such as "use the primary colour only for calls to action and active states" tells it where blue is allowed.
Five passes, in order. Tick each before you accept the page.
| Pass | What you do | Fails if |
|---|---|---|
| 1. Pick | Choose one reference file whose mood matches your product (not your favourite brand) | You mix three files and get none of them |
| 2. Place | Copy it into your project root as DESIGN.md | The agent cannot see it, so it guesses |
| 3. Read-first | Tell the agent to read the file and summarise its rules before writing code | It skips straight to building |
| 4. Build | Generate one page or component, not the whole site | You review forty files at once |
| 5. Audit | Compare the output with the file: tokens, then Do's and Don'ts | You judge "looks nice" instead of "matches the file" |
DESIGN.md. The collection's own instruction is simply to put it in the project root and tell your agent to use it.npx @google/design.md lint DESIGN.md. On Windows PowerShell the README gives npx -p @google/design.md designmd lint DESIGN.md. Given the alpha status, check the README if a command fails.Fill in the bracketed parts: your project, the page you want, and the stack.
You are a senior front-end engineer working in [PROJECT_NAME], built with [STACK, e.g. Next.js and Tailwind].
Context: DESIGN.md in the project root is the only design authority for this work. Do not rely on your own default style.
Goal: build [PAGE_OR_COMPONENT] for [AUDIENCE], so that someone who knows the design file would recognise it as following it.
Steps:
1. Read DESIGN.md fully. Before writing code, reply with a short summary: the colour roles, the font families and sizes, the spacing scale, and every Do and Don't.
2. Wait for my "go" only if something in the file contradicts itself or is missing something you need (for example, no body font). Otherwise continue.
3. Build the page using the file's tokens, as variables or theme values rather than hard-coded repeats.
4. Finish with a table: each rule you applied, and where in the code.
Constraints:
- Use only colours, fonts and spacing values defined in DESIGN.md. If you need one that is not there, stop and ask me.
- Do not copy any brand's logo, wording or imagery. Use placeholder text and shapes.
- Keep the content to [CONTENT_BRIEF].
Self-check before answering: list any place you used a value that is not in the file, and any Don't you came close to breaking. Fix them first.
Paste the code or describe the page; the agent should have DESIGN.md available.
You are a design reviewer. Compare [FILES_OR_COMPONENT] with DESIGN.md.
Check in this order: colours and their roles, typography, spacing and layout, components, then each item under Do's and Don'ts.
Output a table with columns: Rule, Pass or Fail, Evidence (file and line), Fix. Put failures first.
Constraints: quote the rule from DESIGN.md for every failure. If you cannot find evidence either way, mark "Unclear" and say what you need to see. Do not praise; do not suggest changes the file does not support.
Self-check: confirm you have covered every Do and Don't before you answer.
Fill in your brand details; this is the file to build once you outgrow borrowed ones.
You are a design-systems writer. Draft a DESIGN.md for [BRAND_NAME], a [WHAT_IT_SELLS] aimed at [AUDIENCE].
Inputs I will give you: [LIVE_URL_OR_SCREENSHOTS], [BRAND_COLOURS_IF_KNOWN], [FONTS_IF_KNOWN], [MOOD_WORDS].
Output format: YAML front matter with name, colors, typography, rounded and spacing tokens, then Markdown sections in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts.
Rules: every colour needs a role; every Don't must be specific enough to check in code; mark anything you inferred rather than saw as "assumed". If I have not given a value you need, ask me instead of inventing one.
Self-check: confirm every token you reference exists in the front matter.
Imagine a small Manchester bakery wanting a one-page site. The owner picks a file from the collection with a warm, editorial feel, drops it in as DESIGN.md and runs the build prompt for the homepage hero only. The agent's summary says the headline font is a serif and the primary colour is reserved for the order button. The owner spots that the file bans a second accent colour, but the agent has used a green badge. The audit prompt flags it; the owner fixes the badge, then edits the file to say "no decorative badges", so the next page inherits the correction.