Design Direction
On this page
The Generic AI Look is a list of things to strip out after the page exists. This page covers the decisions you make before the AI agent writes any CSS, so there is less to strip.
Start with the Problem#
Design solves a problem. Looking good is one way to solve it, and on some pages it is the wrong way.
Say you are building a tool that checks whether a URL is up. Someone opens it to get an answer in two seconds. Add a glass panel, an animated background and a rotating 3D globe and the page now takes six seconds to load, with the answer somewhere inside all of it. Each piece is impressive on its own. Together they work against the one thing the page is for.
Before you prompt, write one sentence at the top of your README: who opens this, and what do they need in the first five seconds? Your PROPOSAL.md already names who the page is for, so start from that. When you are deciding whether an effect stays, check it against that sentence.
Sketch the Layout#
Draw the page on paper before you look at anyone else's: what is on it, in what order, and what is biggest. Draw two or three different layouts and pick whichever serves your sentence best. Photograph the one you pick and commit it as sketch.jpg. If you drew one already for Running a Project With an Agent, draw one or two more beside it before you pick.
Words work too, if they settle the same things: the order from top to bottom, what is biggest, and what a phone shows before anyone scrolls. A sketch is quicker when you are comparing two or three layouts. If you write the layout in words, paste them wherever this page asks for your sketch.
The sketch can change. When a site below shows a better arrangement and you can state why, redraw the sketch, commit it over the old one, and put the reason in the commit message. Git keeps the first version.
Learn from Sites You Admire#
If you already know the look you want, skip this section and invent every direction in Compare Directions yourself.
Pick several sites whose look fits your sentence, starting with any your PROPOSAL.md names: sites that would work for the same kind of visitor. The galleries in Recommended Reading are a good place to browse. A famous site is a good reference only if its visitors want what yours want.
Look at each site before you read its code. Take a screenshot of each one at full window width with Win+Shift+S (Windows) or Cmd+Shift+4 (macOS), drag the screenshots into the chat, and ask:
Here are screenshots of sites whose look I like, one per site, and a photo
of my sketch. For each site, tell me what a visitor sees first, second and
third, how many columns it has, how crowded or open it feels, and where the
main action sits. Then say where it puts the thing my sketch puts first.
Do not suggest anything for my site yet.Under each answer, write one sentence of your own naming what you are taking from that site: "One narrow column with a lot of space around it." "The answer is the biggest thing on the page."
Then read the values. Ask your AI agent to extract each site's design system. It has to read the sites' stylesheets: a page fetched as text has lost its CSS, and an agent asked for values it cannot see may guess them. When VS Code asks you to approve the download commands, read them and approve them.
Here are sites whose look I like: <URL>, <URL>, <URL>.
Download each site's HTML and stylesheets and read the values from the CSS.
For each site, list its colors, fonts and sizes, spacing, corner radius,
shadows and layout, and how its buttons, links and form fields look on hover,
on focus and when something is wrong. Give the exact value and the file or
selector it came from.
If you cannot find a value, write "not found". Do not guess.
Do not write DESIGN.md yet.Go through the list with your sentences next to it and mark each value keep or drop. The sites will disagree with each other, one light and square, another dark and rounded, and deciding between them is your job. Then add at least one rule that none of the sites has, taken from your own content or your own users, and write down why and what it costs you. "The total is the page, so nothing else on the page competes with it" is a rule of that kind.
Borrow the system: layout, colors, type, spacing, shapes. Logos, images, text and licensed fonts belong to their owners, so leave them out, and ask the agent which fonts are free to use. Name the sites you learned from in your README, each with your sentence.
Compare Directions Side by Side#
"Make it look better" gets you one opinion with nothing to compare it to. Ask for three, in three throwaway files, before you write anything down.
Create option-a.html, option-b.html and option-c.html, and give the agent one named direction per file, built from what you took from the sites: "editorial, heavy type, no cards", "terminal, monospace, one green accent", "soft and warm, generous spacing". Put the same content in every file, arranged as in your sketch, so the only difference is the look. Leave your project files closed while you do this.
Open the three side by side and pick one. You will write DESIGN.md from that one. Delete the other two.
Write the System Down#
Give the agent a constitution before it starts guessing: a file called DESIGN.md at the top of your repo. DESIGN.md is an open format for describing a visual identity to coding agents, in two parts:
- Tokens at the top, between two
---lines: the exact colors, type, spacing and corner radius you kept, and how buttons, links and form fields look. - Sections below, in plain words: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.
The words carry more than the values. The format's own philosophy page puts it this way: "Adjectives describe a region. A specific reference describes a point." "Clean and modern" describes every page. "A public-service notice board in one narrow column, like a GOV.UK service page" describes one.
Attach sketch.jpg and ask the agent to write it from your notes:
Write DESIGN.md in the DESIGN.md format from the direction I picked, the
values I kept and my own rule, listed below, and my sketch, attached. Tokens
at the top, then the sections. Open the Overview with who opens this page and
what they need in the first five seconds, from my README, then the direction.
In Layout, follow my sketch: say what a visitor sees first, second and third,
and how the page stacks on a phone. For each color, say what it is for.
Include the buttons, links, form fields and messages the page uses, with one
entry for each state.
<the direction you picked, your keep list and your own rule>Read it before you commit it, and delete anything you did not decide. If you have Node installed, npx -p @google/design.md designmd lint DESIGN.md checks the file against the format and checks the contrast between its colors.
Then give the agent the rule along with the work. Put it in AGENTS.md, so it comes with every request:
Follow DESIGN.md. If you need a color, font or size that is not in it,
stop and tell me.Check Every Round Against It#
After each build round, before you judge how it looks:
Does this follow DESIGN.md?
List every color, font, size, radius or component style in the code that is
not in DESIGN.md.An agent will happily follow DESIGN.md on the section you asked about and hardcode #6366f1 two files over. Asking for the list catches that while the round is still fresh.
Write Down the Rule Behind Each Cut#
The Generic AI Look tells you to subtract first, removing decoration until something breaks and then putting that one thing back. Do the subtracting, then take one more step:
I removed the drop shadows, the badges and two of the three fonts.
What design rules do those cuts imply?
Add them to the Do's and Don'ts in DESIGN.md.Plan for Several Rounds#
Social media rewards the demo where one paragraph produces a finished product. Your build will take rounds.
Preparation is what shortens them: the sentence about who opens this, your sketch, the sites you learned from, the direction you picked out of three, DESIGN.md. Whether the build then takes two rounds or 10 does not matter.
🤖 AI tip: Attach
DESIGN.mdwhen you start a new chat about how a page looks. An agent that can see the palette uses it. An agent that cannot see it invents a color.
Key takeaway: You cannot ask an agent to follow a design system you have not written down. A
DESIGN.mdbuilt from sites you chose, and one sentence about who the page is for, will do more for how it looks than any prompt about looking good.
References#
- The Generic AI Look, the 23 patterns to strip out, and the companion to this page.
- DESIGN.md, the format specification, with example files. Its philosophy page explains why the words in the file matter more than the values.
- Web Design in 4 Minutes, a page by Jeremy Thomas that restyles itself step by step as you click through it, from content and centering through fonts, spacing and color to images. Most of its steps set a value that belongs in your
DESIGN.md. - Government Design Principles, short rules from the team behind GOV.UK, such as "Start with user needs" and "Do less".
- Recommended Reading, the Taste and Design section, for where a sense of direction comes from in the first place.
Last updated: Wednesday, 9/30/2026