Most of the design direction that used to go in the prompt now lives in a file the agent reads before every request. The prompt still matters, but it is the shortest-lived of the four places your decisions can sit, and the other three have changed more than it has.
Where the direction lives
A year ago, directing an AI model meant writing a longer prompt. Now the same instruction can sit in four different places, and where you put it determines how long it survives.
| Where it lives | How long it lasts | What belongs there |
|---|---|---|
| DESIGN.md | Every request, until you edit it | Colors, type, spacing, components, and why they are what they are |
| AGENTS.md or CLAUDE.md | Every request, until you edit it | How the agent works — stack, conventions, what to check before it stops |
| Model and effort setting | The session | How much reasoning, latency and money each turn costs |
| The prompt | One turn | The task, and the judgment call this particular screen needs |
| The verification loop | After the fact | Whether what came out matches what you asked for |
The failure everyone recognises — the purple gradient, three rounded cards, a glass panel, floating blobs — is what an agent produces when the first two rows are empty. It fills the gap with the most common answer.
The design file
Google Labs open-sourced DESIGN.md in April 2026 under Apache 2.0, derived from the format its Stitch design tool used internally. It is a single Markdown file at the repository root. YAML front matter holds machine-readable tokens; the Markdown body underneath holds the reasoning. Coding agents that read project files pick it up without configuration.
The split is the point. Tokens give the agent exact values. Prose tells it what those values are for. A hex code stops the agent inventing a shade of orange; the sentence “this is the only color that signals interaction” stops it using that orange as a background wash.
The file carries the direction. The prompt carries the task.
What the format contains
Top-level token keys are name, colors, typography, rounded, spacing and components. Colors accept any CSS color format, including oklch(). Typography tokens are objects with properties like fontFamily, fontSize, lineHeight and letterSpacing. Components reference other tokens with curly-brace paths rather than repeating literal values.
The prose sections are optional individually, but the ones you include have to appear in the spec’s order: Overview, Colors, Typography, Layout, Elevation and Depth, Shapes, Components, then Do’s and Don’ts. A duplicate section heading is an error and the file is rejected.
A short working example
---
name: Northlight
colors:
primary: "#14171A"
secondary: "#6B7280"
tertiary: "#C2410C"
neutral: "#F6F4F1"
typography:
h1:
fontFamily: Fraunces
fontSize: 3.5rem
lineHeight: 1.05
body-md:
fontFamily: Public Sans
fontSize: 1rem
rounded:
sm: 2px
spacing:
md: 16px
components:
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "{colors.neutral}"
rounded: "{rounded.sm}"
---
## Overview
Editorial, high contrast, almost no rounding. The page should read like a
printed broadsheet that happens to scroll.
## Colors
- Primary (#14171A): headlines and body copy. Near-black, never pure black.
- Tertiary (#C2410C): the only color that signals interaction. It never
appears as a background wash or inside a gradient.
- Neutral (#F6F4F1): warm paper, not white.Checking the file
The CLI ships with the spec. lint validates structure, catches token references that point at nothing, and checks component background and text pairs against the WCAG AA minimum contrast ratio of 4.5:1. diff compares two versions and flags regressions. export converts tokens to a Tailwind v3 config, a Tailwind v4 @theme block, or W3C DTCG tokens.json.
npx @google/design.md lint DESIGN.mdOutput is JSON, which means an agent can act on it directly rather than you reading a report. Accessibility checking sitting inside the brand file is the quiet win here: contrast normally gets audited separately, after the design is already built.
The format is at version alpha. The spec, the token schema and the CLI are all under active development, so expect the shape to move. It is worth adopting now for the persistence, not for stability.
Generating one from what you already have
Create a DESIGN.md at the repository root.
Source material: [paste brand guidelines, list the hex values and font families
already in use, or name the site whose visual identity this should match]
Run `npx @google/design.md spec` first and follow the specification it returns.
YAML front matter for tokens, Markdown body for rationale.
Body sections, in this order, omitting any that don't apply: Overview, Colors,
Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts.
In the prose, say what each color is for, not what it is. The token already
carries the value; the sentence has to carry the restriction.
Define a primary color and typography tokens. Reference colors from components
with {colors.token-name} rather than repeating hex values.
When the file is written, run `npx @google/design.md lint DESIGN.md` and fix
what it reports, including any contrast finding below WCAG AA.The behavior file
DESIGN.md covers what the interface looks like. It says nothing about how the agent should work. That belongs in AGENTS.md or CLAUDE.md, depending on the tool — the same idea, applied to process rather than appearance.
Splitting the two files
If the instruction would be true on every page of the site, it goes in DESIGN.md. If it is about how work gets done — which framework, where components live, what has to pass before the agent calls itself finished — it goes in the behavior file. If it is true only of the screen in front of you, it goes in the prompt.
Between them, these two files remove most of what people used to paste into every chat. The prompts that survive are shorter and more specific, because they no longer have to re-establish who you are.
Model and effort
Advice that treats all frontier models as one thing is now wrong. The current generation diverged, and the differences show up in exactly the areas that matter for design work — how long the output runs, how much the model checks itself, how many tokens a single screen costs.
| Model | Behavior that changes how you prompt it |
|---|---|
| Claude Opus 5 | Verifies its own work and catches its own mistakes without being asked. Default responses run longer than earlier Opus models, and lowering effort does not reliably shorten them. Delegates to subagents readily. |
| Claude Fable 5.1 | Writes fewer progress updates during agentic work and formats less than earlier models. Blanket anti-markdown instructions can suppress the structure the content actually needs. |
| Gemini 3.8 Flash | Takes smaller reasoning steps and calls tools iteratively, verifying as it goes. Uses more tokens on long, complex tasks by design. Default agent in Antigravity and the Antigravity SDK. |
| GPT-5.6 Sol | Reasoning effort runs from none to max, defaulting to medium. Sol is the flagship tier, with Terra and Luna below it for cheaper work. |
Instructions worth deleting
Half the standard prompt-hardening advice now costs money and produces worse results. These are the specific carry-overs to strip out.
| Instruction that used to help | What to do instead |
|---|---|
| “Double-check your answer before responding” | Delete it. Opus 5 already self-corrects; the instruction compounds with its own behavior and adds cost without improving the result. |
| “Include a final verification step” | Delete it. Same reason. This includes verification steps baked into older harness scaffolding. |
| “Only flag serious problems” | Ask for everything and filter in a second pass. Current models follow a conservatism instruction literally and report less. |
| “If in doubt, use [tool]” | “Use [tool] when it would help you understand the problem.” Blanket defaults now overtrigger. |
| “CRITICAL: you MUST…” | “Use this when…” Aggressive phrasing was needed to stop older models being lazy. It now causes the opposite failure. |
| A list of things never to do | Describe the thing you want. Positive descriptions of a style steer more reliably than a stack of prohibitions. |
Effort, and what it costs
Effort is a real dial, and it is usually more consequential than prompt wording. On Opus 5 it controls how much the model thinks, not how much it says — low and medium produce strong quality at a fraction of the tokens and latency of higher settings, and are the primary lever for cost. To shorten the visible response, ask for a shorter response.
The same session-level control exists across vendors under different names. Building a landing page rarely needs the top setting. A multi-file refactor does.
Cost is now a design constraint. Models that verify their own work, spawn subagents and iterate on tool calls are doing useful things, but each of those is billed. A scope instruction is cheaper than a rewrite:
Deliver what I asked at the scope I asked for. Make ordinary judgment calls
yourself and check in only where two readings of the request would produce
materially different work.
If you think the request is wrong or a better approach exists, say so in one
sentence and then build what I asked for.
Verify as you go rather than adding a separate verification pass. Delegate to
a subagent only for large, genuinely independent tracks of work.What is left for the prompt
Once the files exist, the prompt stops carrying the brand and starts carrying the brief. That is a smaller job, and it is better done in specifics than in adjectives.
“Make it premium” is not direction. It resolves to minimalist and monochrome for one person, cinematic and immersive for another, and dark and futuristic for a third. The model picks whichever reading is most common in its training data, which is how you end up with a page that resembles every other page.
The generic default, named precisely
Anthropic’s own frontend guidance is unusually blunt about where models converge, and the specifics transfer to any model. Overused typefaces: Inter, Roboto, Arial, system stacks. Clichéd palettes, purple gradients on white above all. Predictable section structures and interchangeable component patterns. Backgrounds that default to a flat color instead of building depth.
The most useful item on that list is the second-order one: even when told to avoid generic fonts, models converge on a small set of “distinctive” alternatives — Space Grotesk is named explicitly. Telling a model to be original produces a predictable kind of original. Naming the typeface yourself is faster than negotiating.
Two other things that reliably change output: dominant colors with a sharp accent outperform evenly distributed palettes, and one well-orchestrated page load with staggered reveals lands better than micro-interactions scattered across the page.
An art-direction pass on an existing site
Review this site as an art director before changing anything.
Walk the pages, then tell me where the interface reads as a default rather than
a decision — the typography, the rhythm of the layout, how sections begin and
end, and any depth or motion that isn't doing work.
Report everything you notice. I'll decide what's worth fixing.
Then propose one visual direction and describe it in a paragraph: what it draws
on, what it commits to, what it refuses. Follow DESIGN.md wherever it already
answers the question, and tell me where the direction needs a token the file
doesn't have yet.
Once I approve the direction, implement it. Keep the existing content and
business logic. Every animation and every 3D element should communicate
something I can name — if you can't say what it communicates, leave it out.
Variables to replace: the site or route to review, and the DESIGN.md path if it
isn't at the repository root.Note the separation between reviewing and building. Asking for the diagnosis first gives you a decision point before the agent starts editing files, and it is where a designer’s judgment actually applies.
Making the agent look at what it built
The prompt-and-hope loop is the part of 2025 that has genuinely gone. Build mode in Google AI Studio runs on the Antigravity agent, which holds context across a whole project, manages dependencies across files, and verifies its code updates rather than emitting them blind. Antigravity 2.0 and its CLI extend the same model to parallel subagents with sandboxed terminals.
For visual work, the key lever is giving the agent something to see. Opus 5 is strong on UI and frontend visual replication, and that performance is strongest when it has tools to iteratively analyze, crop, and visually verify its own output — a browser tool, a screenshot tool, or a browser-automation MCP server. Tool access is a more cost-effective improvement than raising effort.
Practically: an agent that can screenshot the page it just built will catch a broken hero on its own. An agent that cannot will describe the hero it intended.
Motion, 3D, and what the browser now handles
Three assumptions worth updating before you brief an agent on animation.
GSAP is free
Following Webflow’s acquisition, GSAP is free for everyone, including commercial use, and that covers the plugins that used to sit behind Club membership — SplitText, MorphSVG, DrawSVG, MotionPathPlugin, and the rest. Everything installs from the public gsap package on npm. Any prompt or tutorial that routes you to a private registry or a Club signup is out of date, and SplitText in particular was rewritten with screen-reader accessibility built in.
CSS covers some of this natively
Scroll-driven animations bind a standard keyframe animation to scroll position with animation-timeline, and run on the compositor rather than the main thread. Chrome and Edge have shipped them unflagged since Chrome 115; Safari added them in version 26. Firefox still keeps them behind a flag in stable, which is why the feature is not yet Baseline, though it is a named Interop 2026 priority.
The failure mode matters more than the support number. A browser that does not implement animation-timeline drops that declaration and keeps the rest of the rule, so a scroll-linked reveal becomes a time-based animation that fires on load — all your content flashing into place at once, in the wrong position. Gate it:
@media (prefers-reduced-motion: no-preference) {
@supports (animation-timeline: view()) {
.reveal {
animation: reveal linear both;
animation-timeline: view();
animation-range: entry 0% entry 100%;
}
}
}Agents will not add the @supports guard or the reduced-motion query unless asked. Put both in the behavior file once rather than in every prompt.
3D needs a reason
The test is whether the third dimension communicates something a flat image cannot. Rotating a product, moving through a space, placing destinations on a globe, visualizing a system’s structure — those earn the weight. A sphere in the hero because Three.js was available does not, and it costs you load time, battery, and a mobile fallback path you now have to design.
Ask for the fallback in the same breath as the effect. An agent given “3D hero” builds a 3D hero; an agent given “3D hero, with a static image path for low-end devices and reduced-motion users” builds both.
Troubleshooting
- The agent ignores DESIGN.md. Check that it is at the repository root and that
lintpasses — a duplicate section heading rejects the whole file. If tokens are defined but never referenced by any component, the linter flags them as orphaned, and the agent has no path from your value to your interface. - Output is still generic despite a long prompt. The prompt is probably a list of things to avoid. Replace it with a description of what you want, and name the typeface and the palette rather than asking for distinctiveness.
- Token spend is far higher than expected. Look for leftover verification instructions and unconstrained subagent delegation before blaming the model. Then run an effort sweep — you may be paying for a setting you carried over from an older model.
- Scroll animations flash on load for some users. Missing
@supportsguard. The declaration is dropped, and the keyframes run on a time-based timeline instead. - Responses are long and full of narration. Ask for the cadence you want in positive terms — one sentence before the first tool call, updates only on a change of direction, outcome first at the end. Describing the style works better than forbidding the alternative.
Common questions
No. Figma is where visual decisions get made and refined collaboratively. DESIGN.md is how those decisions reach a coding agent in a form it reads on every request. The file is downstream of the design work, not a substitute for it.
Availability depends on your plan, so test rather than assume. The more useful question is whether the model has tools to see its own output, and whether you have tuned effort for the task. A mid-effort setting with a screenshot tool usually beats a top-effort setting working blind.
It is at version alpha, and the spec, schema and CLI are all changing. The format itself is plain Markdown with YAML front matter, so the content survives even if the schema shifts. Treat the CLI commands as the part likely to move.
For orchestrated timelines, text splitting and complex sequencing, GSAP still earns its place, and it costs nothing now. For simple reveal-on-scroll, CSS handles it natively behind a support guard and runs off the main thread. Three.js is a decision about whether the content is spatial, not a default.
Starting from here
Write the DESIGN.md for one project, lint it, and fix what comes back. Then take a prompt you already use and delete every instruction from the table above. Both take under an hour and change more than any amount of prompt rewriting.