DESIGN.md: what are the best use cases?

What does DESIGN.md actually do?

DESIGN.md gives AI coding agents a persistent description of how a product should look, so they stop making every design decision from scratch.

Google’s format combines two kinds of information in one plain-text file. The YAML front matter contains exact values such as colors, typography, spacing and border radii. The Markdown explains how those values should actually be used: what the product should feel like, which elements deserve emphasis, how dense the UI should be, which patterns belong in the product and which ones should never appear.

That second part is more important than it sounds. A CSS variable can tell Claude Code or Codex that an accent color is #B8422E. DESIGN.md can tell the agent that this accent belongs only on interactive elements and should never appear on headings, metadata or decorative backgrounds.

Google describes DESIGN.md as a living source of truth that humans and AI tools can both read and update. The format was created inside Stitch, then opened up so the same visual instructions could move between design and coding tools.

So the better question is: where does an AI agent repeatedly have to make visual decisions without enough context about what “good” looks like for this particular product?

Why is DESIGN.md getting so much attention right now?

DESIGN.md is taking off because AI coding has made building screens much easier while keeping those screens visually coherent is still a real problem.

The adoption curve has moved unusually fast. Google’s GitHub repository was showing roughly 14,900 stars in an earlier snapshot around three months ago. It currently shows about 27,700. That is roughly an 86% increase in a short period. Forks have reached around 2,300.

The npm activity points in the same direction. The official @google/design.md package currently records around 140,000 weekly downloads, while npm shows version 0.4.0 and five published versions already. We should not translate package downloads directly into active companies because CI installs, experiments and repeated downloads inflate that figure. Still, the combination of GitHub growth, npm usage and continued releases is much stronger evidence than GitHub stars alone.

Google is also using DESIGN.md in its own Stitch workflows. Its current Stitch tooling can create and update design systems around the format, while third-party projects are already building DESIGN.md libraries, MCP integrations and extraction tools around it.

The interesting part is how quickly usage has run ahead of maturity. DESIGN.md remains officially alpha. People are already trying to build workflows around a format that Google still expects to change.

Current DESIGN.md indicator	What we found	What it suggests
Google GitHub stars	~27,700	Strong developer interest
Approximate star growth from an earlier snapshot	~86%	Interest is still accelerating
GitHub forks	~2,300	People are actively adapting the project
Official npm downloads	~140,000 per week	The CLI is seeing meaningful usage
Current npm version	0.4.0	The tooling is still moving quickly
Format status	Alpha	Production users should expect changes

Will Claude Code, Codex and Cursor actually read DESIGN.md?

Claude Code, Codex and Cursor can all work with DESIGN.md, but simply dropping the file into a repository does not guarantee that every agent will automatically read it.

This is probably the most important implementation detail to understand.

Codex has its own persistent instruction system built around AGENTS.md. OpenAI’s documentation says Codex searches for these files through the repository hierarchy and combines the applicable instructions before working on files.

Claude Code uses CLAUDE.md for project memory and instructions. Cursor currently supports its own .cursor/rules system as well as AGENTS.md, and its documentation says it can also read CLAUDE.md.

The reliable workflow is therefore to connect DESIGN.md to whichever instruction mechanism the agent already respects. An AGENTS.md file might tell Codex to read DESIGN.md before changing frontend files. A Claude project can give the equivalent instruction through CLAUDE.md. Cursor can enforce the same behavior through a project rule.

This separation is actually quite clean. AGENTS.md, CLAUDE.md or Cursor Rules can explain how the repository should be worked on. DESIGN.md can stay focused on how the product should look.

A DESIGN.md sitting unnoticed in a repository has very little value. The useful version is one that reliably enters the agent’s context whenever UI work begins.

Coding tool	Project context it currently understands	Good way to use DESIGN.md
Codex	AGENTS.md and nested repository instructions	Tell Codex to read DESIGN.md before frontend work
Claude Code	CLAUDE.md	Reference DESIGN.md from the project instructions
Cursor	.cursor/rules, AGENTS.md, CLAUDE.md	Apply DESIGN.md to UI-related work
Google Stitch	Native DESIGN.md workflow	Import, export and reuse the design system directly

Is stopping AI design drift the best DESIGN.md use case?

Yes. Preventing visual drift across repeated AI coding sessions is probably the strongest DESIGN.md use case today.

Anyone who has built enough UI with coding agents has probably seen the pattern. The first screen has an eight-pixel radius. A later session decides twelve looks better. Another page suddenly gets gradients. A new modal has twice as much padding as the old one. One agent invents a secondary shade of blue that exists nowhere else.

Each individual decision can look perfectly reasonable. After twenty of them, the product starts feeling like several slightly different design systems stitched together.

DESIGN.md gives the agent somewhere to check those decisions before improvising. It can define the spacing and color values, but the more useful instructions are often rules such as “cards stay flat,” “use one accent color,” “information density should remain high,” or “primary actions are the only elements using the accent background.”

The payoff grows with the number of screens an agent touches. Someone asking Cursor to tweak one button every few months probably does not need another project file. A founder building most of a SaaS frontend through Codex or Claude Code has a much stronger reason to create one.

These days, that second workflow is exactly where DESIGN.md makes the most sense.

Can DESIGN.md make a vibe-coded app look less generic?

A strong DESIGN.md can make a vibe-coded app look noticeably less generic because it gives the model a visual direction that goes beyond “clean modern SaaS.”

Google’s own DESIGN.md philosophy is unusually clear on this. The project says the prose is where the design really lives, and that generated quality depends heavily on how precisely the intent is described.

That explains why many AI interfaces converge on the same look. Tell a model to make an app “modern, premium and clean” and it still has an enormous number of design decisions to make. The model falls back on familiar patterns: huge hero text, rounded cards, soft gradients, lots of empty space and a bright accent color.

A DESIGN.md can narrow that space much more aggressively. Google gives the example of an old graduate-level university handout. That reference already suggests dense information, restrained typography and almost no decorative UI. Instructions such as “nothing bounces,” “never use pure white” or “the accent never appears on typography” narrow the design further.

That is the real advantage for vibe coding. You can decide on a recognizable visual world once and let the agent work inside it instead of repeatedly asking for something “less AI-looking.”

Of course, DESIGN.md will preserve mediocre taste just as faithfully as good taste. The starting direction still has to be worth preserving.

Is DESIGN.md even better for an existing product?

DESIGN.md is especially useful on an existing product because the design rules can be extracted from something real instead of invented from a blank page.

An established SaaS product may already have dozens of screens, CSS variables, components and years of small design decisions. A coding agent can inspect those files, but it still has to work out which patterns are intentional and which ones are historical accidents.

Imagine a product where buttons are nearly square, cards are rarely nested, forms are compact, neutral colors dominate most screens and one blue accent is reserved for important actions. Those relationships may be obvious to a designer who has worked on the product for two years. They are much less obvious to an agent opening the repository for the first time.

Google has been pushing in this direction with Stitch. Its newer workflow can extract a design system from an existing URL, while Google’s Stitch skills include processes for synthesizing existing visual material into DESIGN.md.

In practice, this is more reliable than asking an agent to invent a complete visual identity from prose alone. Screenshots, the live website and existing components provide evidence. DESIGN.md then records the decisions we want future generations to keep following.

For mature products, the best content in DESIGN.md is often the stuff that an agent cannot confidently infer from the code.

Is DESIGN.md especially useful for landing pages?

DESIGN.md works very well for teams generating lots of landing pages because the design changes often while the brand should stay recognizable.

Consider a startup using AI to create a homepage, pricing page, ten competitor pages, several integration pages and campaign landing pages. Every new page gives the model another chance to reinterpret the visual identity.

A persistent design file can keep the typography hierarchy, CTA style, spacing rhythm, card treatment, imagery direction and section density consistent while still allowing each page to have a different structure.

This is more useful now that AI agents can generate complete pages quickly. When creating a page took a designer and frontend developer several days, humans naturally carried much of the visual context between tasks. When an agent can create several pages in an afternoon, consistency becomes easier to lose.

There is already some ecosystem movement around this use case. Shadcn-related themes and independent DESIGN.md libraries are beginning to package agent-readable design guidance alongside the actual visual tokens.

For one disposable landing page, we would usually just give the agent a good reference and build it. DESIGN.md starts earning its place when the fifth, tenth and twentieth page should still look like the first.

Can DESIGN.md make an app redesign less chaotic?

DESIGN.md is very useful during a redesign because it lets us define the destination before an AI agent starts changing screens one by one.

“Modernize this dashboard” is a terrible instruction for a large migration. The agent might change the typography on one page, card radii on another and colors somewhere else. For weeks, the product can sit halfway between two visual systems.

A DESIGN.md gives the redesign a shared target. We can define the new typography, spacing, color roles, density, component treatment and visual rules first. Then the coding agent can migrate screens against the same reference.

Google’s CLI makes this workflow more concrete. The current diff command compares DESIGN.md versions and reports token changes. The export command can turn DESIGN.md tokens into Tailwind v3 configuration, Tailwind v4 CSS variables or DTCG tokens.

That gives teams a useful chain from design decision to implementation. A designer or founder changes the visual contract, the team can inspect exactly what moved, and the agent gets the same updated context while migrating the interface.

We would still inspect the resulting screens visually. A text file can tell an agent what it should aim for; it cannot tell us whether the final composition actually looks good.

Can one DESIGN.md follow you from Stitch to Claude Code, Codex and Cursor?

Yes, and portability between AI tools is becoming one of the more interesting DESIGN.md use cases.

Google explicitly opened the format so design context could travel beyond Stitch. Because DESIGN.md is plain text, there is very little technical lock-in at the document level. Claude Code, Codex, Cursor or another agent can read the same design instructions even when they use different mechanisms to load them.

That becomes useful when a workflow itself is fragmented. A team might explore a new interface in Stitch, implement it with Codex, fix a component later in Cursor and use Claude Code for a larger refactor. Rewriting the design brief every time would be absurd.

DESIGN.md gives those tools a common piece of context.

The ecosystem is starting to test this idea in practice. We are now seeing DESIGN.md-focused MCP servers, libraries of extracted design systems and agent skills aimed at several coding environments rather than a single editor.

There is still friction. Each coding agent handles persistent context differently, so portability currently applies more cleanly to the content than to the loading mechanism.

As AI development becomes increasingly multi-agent, though, a small vendor-neutral design file becomes more useful than a design prompt trapped inside one chat history.

Can DESIGN.md replace Figma?

No. Figma still handles important visual work that DESIGN.md cannot express properly.

A Figma file lets people judge complete compositions. Designers can compare layouts side by side, tune alignment visually, manipulate responsive variants, inspect states, change image crops and notice that a technically correct page simply feels wrong.

DESIGN.md works at another level. It can tell an agent that pages should feel dense, that secondary information should remain visually quiet, that cards use minimal depth and that an accent color has a specific semantic role. Those instructions are extremely useful when the agent encounters a component that nobody has designed yet.

The two formats can also share structured information. Google says DESIGN.md tokens are designed to be convertible to and from formats such as Figma variables, Tailwind themes and DTCG token files.

For teams already using Figma, we would keep it. DESIGN.md becomes an additional translation layer for agents.

The bigger change is for teams that have already reduced their Figma usage because coding agents let them design directly in the browser. Those teams may get disproportionately high value from DESIGN.md because more of their design decisions now happen inside code-generation sessions.

Can DESIGN.md replace Tailwind, shadcn or normal design tokens?

No. Tailwind, shadcn, CSS variables and production design tokens still control what the application actually renders.

Google’s current DESIGN.md philosophy says the structured values provide context to agents. The runtime styling system continues doing the implementation work.

The CLI itself shows how Google expects the pieces to fit together. DESIGN.md can currently export tokens into Tailwind v3, Tailwind v4 CSS or the W3C Design Tokens Community Group format. That is a bridge into existing tooling.

A shadcn project, for example, should continue using its real components and theme variables. DESIGN.md can explain the decisions around those components: when cards should be used, how strong destructive actions should appear, how much density the product wants and whether the agent is allowed to invent new visual primitives.

There is also a good reason to avoid making DESIGN.md the only technical source of truth right now. The format is still alpha, and recent issues in Google’s repository have exposed rough edges. One recent report found that the DTCG export could produce typography tokens missing properties required by the schema it declared. Another asked for physical units such as pt and mm, which the current format does not properly support for print-oriented systems.

Those are normal problems for a young spec. They are also a reminder to keep production styling infrastructure independent enough that a DESIGN.md change does not destabilize the application.

What should you actually put inside DESIGN.md?

The best DESIGN.md files explain the visual decisions an AI agent would otherwise keep getting subtly wrong.

Exact tokens still help. Colors, typography roles, spacing and component values remove unnecessary guesswork. But copying an entire CSS theme into YAML misses much of the point.

Google’s philosophy document currently puts much more emphasis on prose. A useful DESIGN.md might explain that a dashboard should feel like a technical control panel rather than a marketing website, that pages should be information-dense, that primary actions are scarce, that cards should almost never be placed inside other cards, and that animations should feel immediate rather than playful.

Negative constraints are useful too when they capture a recurring mistake. If agents repeatedly add gradients, giant titles or glass effects that do not belong in the product, write that down.

Specific references also beat vague adjectives. “Premium and minimal” gives the model very little information. “A 1970s graduate engineering handout” or “an institutional trading terminal with modern typography” gives it a much narrower place to explore.

Oddly, the most valuable part of the file may end up being a few exceptionally precise paragraphs rather than hundreds of tokens.

Can DESIGN.md catch design mistakes automatically?

DESIGN.md can now catch a useful set of design-system mistakes automatically, although its current checks cover only a small part of UI quality.

Google’s latest repository shows 11 linting rules. Earlier versions of the project documented seven, so the validation layer is already expanding.

The current linter can find broken token references, suspicious keys, missing primary colors, missing typography, unused color tokens and badly ordered sections. It also checks foreground/background component pairs against the 4.5:1 WCAG AA contrast threshold.

The diff command adds another useful behavior. Teams can compare an old DESIGN.md with a new one and make CI fail when the new design system introduces additional lint errors or warnings.

That makes DESIGN.md more interesting than an ordinary style-guide document that quietly goes stale in a repository.

The limits are easy to see. A passing DESIGN.md cannot tell us whether keyboard navigation works, whether HTML semantics are correct, whether responsive layouts break, whether focus states are usable or whether the screen simply looks ugly.

We would use the linter as a cheap extra guardrail. Browser checks, accessibility testing and human visual review still have much more work to do.

When is DESIGN.md overkill?

DESIGN.md is overkill when an AI agent rarely makes new visual decisions.

A backend service gets almost nothing from it. A disposable prototype may disappear before maintaining the file pays off. If we are reproducing one fixed screen from a screenshot, giving the agent that screenshot can be far more useful than first documenting an entire design system.

Very mature frontends can also have less need for DESIGN.md when almost every visual decision is already locked into reusable components and agents are strictly told to reuse those components. Even there, it can still help with the judgment calls that the component library leaves open, but the gain is smaller.

Staleness is the bigger danger. An outdated DESIGN.md can confidently steer agents toward yesterday’s product. If the company changes its typography, button system and accent color while nobody updates the file, persistent context starts working against us.

The alpha status deserves some respect too. Google is still changing the schema and CLI, and version 0.4.0 is only one step in a fairly young project.

So we would add DESIGN.md when we can point to a real recurring problem: inconsistent AI-generated UI, repeated design prompting, messy multi-agent handoffs or a redesign that needs a stable target.

Adding it to every repository because DESIGN.md is fashionable these days would create more documentation than value.

What is the best DESIGN.md setup right now?

The best DESIGN.md setup today is simple: make sure the coding agent reads it, keep the real components and tokens in code, and visually check what the agent produces.

For Codex, AGENTS.md can tell the agent to consult DESIGN.md whenever it touches frontend code. Claude Code can get the equivalent instruction from CLAUDE.md. Cursor can apply it through project rules or one of the compatible instruction files it currently supports.

Inside DESIGN.md, we would spend most of our effort on the visual choices agents have trouble inferring: overall aesthetic, semantic color usage, typography hierarchy, information density, spacing philosophy, component behavior and a small number of important constraints.

Existing code should remain the implementation reference. If there is already a good Button component, the agent should use it. If the runtime theme defines the production colors, those values should remain dependable. DESIGN.md gives the agent the context needed to make sensible decisions around those existing pieces.

Google’s CLI can then lint the file and, where useful, export its structured values into Tailwind or DTCG formats.

Finally, look at the screen. This sounds obvious, but agentic coding makes it remarkably easy to review diffs instead of interfaces. DESIGN.md becomes much more valuable when the workflow closes the loop by comparing the generated result with the intended visual system.

So what are the best DESIGN.md use cases?

The best DESIGN.md use cases today are projects where AI agents repeatedly build or modify UI and need to preserve the same visual taste over time.

We would put preventing design drift first. Extending an existing product comes very close because the agent has a real visual language to preserve. Repeated landing-page creation, vibe-coded apps, redesigns and moving work between Stitch, Claude Code, Codex and Cursor are also strong cases.

The evidence since Google opened the format makes the idea more credible than it looked initially. The official repository has grown rapidly, npm usage is substantial, Google is still expanding the CLI, and an independent tooling ecosystem is already forming around the file.

The alpha-stage problems are also pretty clear. DESIGN.md still needs the coding agent’s own instruction system to be reliably loaded. Its interoperability tooling is evolving. Visual review remains essential. Production components and styling systems still carry the actual application.

The bigger idea behind DESIGN.md is stronger than the current specification itself. Coding agents are getting good enough at frontend implementation that the difficult part increasingly becomes preserving taste and context over hundreds of small decisions.

That is where DESIGN.md is genuinely useful. It gives those decisions somewhere to live after the original prompt disappears.

DESIGN.md use case	How useful is it today?	Why
Preventing AI design drift	Excellent	Keeps repeated generations inside the same visual system
Extending an existing app	Excellent	Gives agents design context that code alone may not explain
Vibe-coded products	Very good	Reduces dependence on generic model aesthetics
Repeated landing pages	Very good	Keeps branding consistent while layouts change
AI-assisted redesigns	Very good	Gives every migrated screen the same target
Moving between AI coding tools	Very good	The same visual context can travel with the project
Design-system QA	Useful	Current linting catches several cheap-to-detect mistakes
Multi-brand or agency work	Useful	Each project can carry its own visual context
One-off prototypes	Usually unnecessary	There is little repeated context to preserve
Replacing Figma	Poor fit	Complete visual composition still needs visual tools or browser review
Replacing Tailwind, CSS or components	Poor fit	Those systems still implement the actual interface