DEV Community: Chaos Wang

How to write a DESIGN.md your AI will actually follow

Chaos Wang — Mon, 31 Aug 2026 03:04:52 +0000

A DESIGN.md only works if the machine reading it never has to guess. That is the whole craft of writing one: put orientation before detail, state values instead of adjectives, and cover the components the agent will actually build.

If you're new to the format, start with What is a DESIGN.md? — this post is the practical sequel: the structure that works, and the mistakes that quietly break it.

Start with orientation, not detail

The first thing in the file should tell the machine what it is looking at: the style's name, a one-line essence — the sentence you would use to describe the look to someone who has never seen it — and the flags that change everything downstream, like whether the style is light or dark.

Most specs put this in a small structured block at the top (YAML frontmatter is the common convention, and the one Google's open DESIGN.md spec uses). An agent reads that block first and interprets every later section through it. A file that opens with fifty color values and no orientation makes the model reconstruct the intent — which is exactly the guessing you are trying to eliminate.

---
name: <style name>
essence: <one sentence: the look, to someone who has never seen it>
isDark: false
---

State values, not adjectives

"Warm, minimal, editorial" means something different to every model on every run. "Background <hex>, ink <hex>, one accent <hex>, body type at <px> with a 1.5 line height, spacing on an <px> rhythm" means the same thing every time. Tokens are the contract; adjectives are decoration.

Name your tokens by role, not by appearance: background, ink, accent, line — not "light gray" or "blue". Role names survive theme changes and tell the agent where a value belongs, not just what it is.

Keep prose in the file, but give it a job: explain why the values are what they are and how they combine. "The accent is reserved for one action per screen" is prose an agent can obey. "The palette feels calm" is not.

Cover the components the agent will build

Tokens alone underdetermine a UI. Two styles can share a palette and still look nothing alike, because the difference lives in component logic: are buttons filled or outlined, sharp or rounded? Do cards float on shadows or sit inside hairline borders? Is emphasis done with weight, size, or color?

Write these as short declarative rules for the handful of components that appear everywhere — buttons, cards, inputs, navigation. Then add usage bounds: where the style fits and where it does not. An agent that knows a style is built for editorial pages will not force it onto a dense dashboard.

The mistakes that quietly break a spec

Adjectives without values. The most common failure: a beautifully written mood description with no numbers. The agent nods along and then invents its own palette.

Dumping the whole brand book. A DESIGN.md is a working spec, not an archive. If the file takes longer to read than the screen takes to build, the agent will skim — and skimming is guessing with confidence. Keep it to what changes the output.

No usage bounds. A spec that never says where the style should not go gets applied everywhere, badly.

Letting it rot. The file is plain text in your repo; treat it like code. When the design changes, the DESIGN.md changes in the same commit — otherwise the agent faithfully applies last quarter's design.

Inconsistent internal references. If the type section says one scale and a component example implies another, the agent has to pick one — and it will not tell you which it picked.

FAQ

How long should it be? As short as it can be while still deciding every visual question the agent will face. In practice that is usually a page or two: one orientation block, the core token sections, component rules for the recurring elements, and usage bounds. If a section would not change what the AI builds, cut it.

Where does the file live? The project root, next to README.md — that is where coding agents look first, and it follows the convention the name implies.

One file or several? One. The point of the format is that an agent reads the whole design system in a single pass. The moment the spec is spread across files, you are relying on the agent to find and reconcile them — reintroducing the guessing the format exists to remove.

Do I need YAML frontmatter? It is the convention Google's open spec uses and the easiest block for a machine to parse, so it is a good default. But the deeper rule is orientation-before-detail: whatever the syntax, the file should open with what the style is before it lists values.

Or skip the writing: pick a ready-made one

Writing a DESIGN.md is worth it for a design system you own. But if what you want is an established style — Bauhaus, Swiss International, a contemporary brand-grade look — writing the file means reverse-engineering a whole movement's rules yourself, and getting them subtly wrong is the default outcome.

That is the case for a library. Curio ships hundreds of real design styles, each already encoded as a complete DESIGN.md — researched, structured, and ready for your AI to apply over MCP, a share link, or a download. Pick the style; the file is already written.

Originally published as How to Write a DESIGN.md on Curio. Related: a complete DESIGN.md example · Google Stitch's DESIGN.md, explained.

What is a DESIGN.md? The file that gives your AI a design system

Chaos Wang — Tue, 25 Aug 2026 16:28:24 +0000

How to give your AI design taste

Chaos Wang — Mon, 24 Aug 2026 06:30:58 +0000

AI has no design taste of its own. What you can do is supply taste from the outside — and some ways of doing that work far better than others.

What 'taste' means for an AI

Taste, in design, is a consistent set of intentional choices — a point of view applied the same way across every screen. An AI has none of this by default. Left alone it returns the average of its training data, which reads as competent but anonymous.

So 'giving your AI taste' is not about unlocking something inside the model. It is about feeding it a specific point of view from outside, in a form it can apply consistently. The question is only which form works best.

Lever 1 — better prompts (weakest)

The first lever is the prompt itself: be specific, name constraints, show one example. This is real but limited. The instruction shapes a single output and then evaporates; across many screens the model drifts back to its default, so consistency is hard to hold.

Prompts are the right tool for a one-off and the wrong tool for a system. If you need ten slides or twenty components to feel like one product, the prompt is too thin a thread to carry the taste.

Lever 2 — reference images and examples

The second lever is showing, not telling: paste a screenshot, link a site you like, give a few examples to imitate. This lands better than adjectives because it points at something concrete.

But references are lossy. The model infers what it thinks matters from a picture, and different runs infer differently — it might copy the color but miss the spacing logic, or borrow the type but not the grid. You get closer to the look without ever pinning it down.

Lever 3 — a machine-readable design spec (strongest)

The strongest lever is to hand the AI an actual design system in a form it can read: the real colors, type scale, spacing rhythm, shape language, and component rules, written down. Now the AI is not guessing at taste from a picture or an adjective — it is applying a defined system, value by value, the same way every time.

This is what closes the consistency gap. A spec does not evaporate between prompts and it does not have to be re-inferred from an image; it is the same input the model can apply to slide one and slide forty. The clearest form of this is a DESIGN.md — a single machine-readable file that carries a complete style, ready for an AI to consume.

Curio exists to supply exactly this lever: each design style packaged as a spec your AI can apply directly, so you are not relying on prompt-luck for a consistent, intentional look.

Putting it together

Use the levers in order of strength. Start from a real design spec as the backbone, lean on references where the spec is silent, and reserve prompts for the small, local adjustments. The spec carries the taste; the prompt carries the task.

The practical move: pick one documented style, give your AI its spec, and keep every screen on that same system. Taste, for an AI, is just specificity supplied consistently from outside.

FAQ

Can't I just tell the AI to 'use good design'?

No — 'good design' is an adjective, and to a model an adjective resolves to its average. Every style in the training data claims to be good, clean, and modern, so the instruction points nowhere specific and you get the mean. Taste has to be supplied as concrete, consistent rules.

Reference images or a design spec — which is better?

A spec, for anything beyond a one-off. References are lossy and re-inferred differently each run, so consistency suffers. A spec is the same deterministic input every time, complete and reusable across many screens — which is exactly what a consistent look requires.

What format does the AI actually consume?

A machine-readable spec it can parse and apply — for Curio styles, a DESIGN.md: one file holding the full palette, type, spacing, and component logic. You hand it over by download, share link, or an MCP connection, and the AI applies the values directly.

Originally published on designbycurio.com. Curio is a design style library for AI agents — 1,000+ real design styles as machine-readable specs your AI can actually follow. Related: Why AI-generated design all looks the same and What is DESIGN.md?

Why AI-generated design all looks the same

Chaos Wang — Sat, 22 Aug 2026 06:25:46 +0000

If everything your AI produces looks vaguely the same — clean, competent, and completely forgettable — you are looking at AI slop. It happens for a structural reason, and there is a structural fix.

What is AI slop?

AI slop is the generic, average-looking output that AI tools produce by default — design that is technically fine but has no point of view. In a design context it shows up as the same soft gradients, the same rounded cards, the same purple-to-blue hero, the same safe sans-serif, on site after site and deck after deck.

The word 'slop' is doing real work: it names the feeling that the output was generated rather than designed. Nothing is wrong with any single element. The problem is that the whole thing is a statistical average — and averages, by definition, belong to no one.

Why AI-generated design looks generic

A model trained on millions of designs learns the center of that distribution, not its edges. Ask it for 'a modern, clean, beautiful landing page' and you are asking for the most probable design — which is, almost by definition, the most average one. Researchers call this homogenization: as more people lean on the same models, creative output converges toward a shared mean.

Generic input compounds the effect. Adjectives like 'modern', 'clean', 'professional', and 'minimal' do not point anywhere specific — every style in the training data claims them — so the model falls back on its default aesthetic. The more open the request, the more average the result.

This is not a bug that a future model fixes. A model with no instruction to be specific will always reach for the center. Distinctiveness is information you have to add from the outside.

Why better prompts don't fix it

Prompting helps at the margin. You can hand the model a reference, name a constraint, or paste an example, and the next output will be a little less generic. But the model still has no internal taste to anchor to — between your instructions it drifts back toward its average, and consistency across many screens collapses.

You cannot prompt your way into a specific aesthetic the model does not hold. 'Make it look like a high-end fintech product' is still an adjective cluster; ten people will get ten different interpretations, and the same person will get a different one tomorrow. To get a specific look reliably, the specificity has to live outside the prompt.

The fix: give your AI one real design style

The cure for an average is a commitment. Instead of letting the AI blend everything, constrain it to one specific, real, documented design style — a movement or a brand that already has a point of view and a set of rules. Bauhaus has rules. Swiss style has rules. Memphis has rules. A real style forces non-average choices, because it was built around a stance, not around being inoffensive.

Crucially, the style has to arrive as rules the model can apply — an actual palette, type scale, spacing system, and component logic — not as an adjective. 'Use Bauhaus' is still vague; the primary-color palette, the hard-offset shadows, the strict grid, and the zero-ornament principle are not. When the AI is following a defined system, it is no longer averaging — it is executing.

This is exactly the gap a curated style library fills. Curio packages real design styles as specs an AI can read and apply directly, so the distinctiveness is supplied from the outside and your AI stops reaching for the mean.

How to beat AI slop in practice

Pick a style with a real identity, not an adjective. 'Editorial Swiss grid' or 'Memphis' gives the model something to execute; 'modern and clean' does not.

Give the AI the style's actual rules — colors, type, spacing, shape language — rather than describing the vibe. Specifics are what survive the gap between prompts.

Commit to one style and do not blend. Slop often comes from averaging two or three influences; a single committed system reads as intentional. The whole point is a point of view.

FAQ

Is 'AI slop' just an insult, or a real phenomenon?

Both the term and the effect are real. 'AI slop' is informal, but it names a measurable tendency — homogenization, the convergence of AI output toward a statistical average. It is a structural property of how models generalize, not a temporary quality problem.

Won't a more detailed prompt fix the generic look?

Only at the margin. A detailed prompt nudges one output, but the model still has no taste to hold between requests, so it drifts back toward its average and consistency breaks down. A concrete, reusable style spec fixes the look reliably; a prompt does not.

Does using a named style make everything look derivative?

No — a real style is a grammar, not a template. It gives the AI consistent rules to compose with, the way a typeface or a grid does. Distinctiveness comes from committing to a point of view; derivative work comes from averaging several without committing to any.

Originally published on designbycurio.com. Curio is a design style library for AI agents — 1,000+ real design styles as machine-readable specs your AI can actually follow. If you want the practical follow-up, see How to give your AI design taste.

Your AI doesn't understand design. So I gave it a library it can read.

Chaos Wang — Sat, 22 Aug 2026 06:18:47 +0000

Ask any LLM to "make this landing page look like a high-end Swiss design studio" and you'll get something that gestures at the idea — a sans-serif font, some whitespace, maybe a red accent because it half-remembers Müller-Brockmann. It looks AI-generated because it is. The model has read a billion words about design but has no grounded, reusable representation of what "Swiss International Style" actually specifies: the exact grid, the type scale, the spacing ramp, the rules for what you must not do.

That gap is the whole problem. Models are great at language and bad at design systems, because a design system isn't language — it's a set of constrained values plus the discipline to apply them consistently. So I built the missing piece: a library of real design styles, turned into something a machine can actually consume.

It's called Curio. This post is about the part I think is interesting to other builders: making design machine-readable, and publishing the catalog for agents instead of for humans.

A design style is just tokens + rules

The insight is boring and that's why it works. Pick any coherent visual language — Bauhaus, Memphis, the Edo woodblock palette, Stripe's product aesthetic — and you can decompose it into:

Tokens: color families, type families and scale, spacing ramp, radii, shadow/elevation, motion timing.
Components: how a button, card, input, nav actually look in this language.
Rules: the "always" and the "never." (Swiss: never center body text, never more than two weights. Memphis: never subtle.)

Once a style is expressed that way, an AI doesn't have to imagine the look. It interpolates within a fixed, internally-consistent set of values. The output stops looking like a guess because it isn't one. Each style in Curio is packaged exactly like this — tokens, component specs, and an explicit "avoid" list — as a DESIGN.md file — markdown with YAML frontmatter — that a model can read in one shot (what is DESIGN.md?).

# excerpt of a design package an agent consumes
meta:
  name: Swiss International Style
  isDark: false
color:
  ink: "<hex>"
  paper: "<hex>"
  accent: "<hex>"   # values intentionally omitted here
type:
  family: "Helvetica Neue, Inter, sans-serif"
  scale: [<px>, <px>, <px>, …]   # 7-step modular scale
rules:
  always: ["strict baseline grid", "flush-left, ragged-right body"]
  never:  ["centered paragraphs", "more than two weights", "decorative type"]

The part I didn't expect to care about: publishing for agents

Here's the design decision I keep getting questions about. Curio's primary user isn't a person browsing a gallery — it's the agent acting on a person's behalf. When someone tells their assistant "design my deck like a 1980s arcade," the agent should be able to discover that a matching style exists and fetch its tokens, without a human in the loop.

So the catalog is published the way you'd publish for a crawler that thinks:

An llms.txt at the root — the llmstxt.org convention — that tells a model what the site is and how to apply a style in four steps.
An llms-full.txt with one line per style: name, blurb, URL.
An open index.json — the entire catalog as structured data (id, name, tags, color family, era, region, usage), so an agent can filter "give me dark, East-Asian, editorial" without scraping HTML.

This costs almost nothing to maintain (it's generated from the same source the site is built from) and it changes who the product is for. A human-first directory makes agents scrape and guess. An agent-first directory just answers. If you're building anything an LLM is supposed to consume, I'd push the llms.txt + open-JSON pattern hard — it's the cheapest "API" you'll ever ship.

Why this is also an SEO/discovery bet

There's a second reason to publish structured, citable pages: AI search. When someone asks Perplexity or ChatGPT "where do I find design tokens for a Bauhaus look," the answer comes from indexed, structured pages — not from a JS app that renders an empty shell. Every Curio style has a server-rendered page with the spec in the HTML, schema markup, and a stable URL. The same discipline that makes a page good for Googlebot makes it good for an AI engine citing sources. Designing for "the crawler is now a model" turns out to be the same checklist, just with the bar raised.

Where it's at

Curio has 1,000+ styles right now and grows weekly. Browsing and using it is free; there's a Pro tier for the full set. But honestly, the reason I wrote this is the pattern, not the pitch: treat design as data, and publish your catalog for the agent, not just the human. If you try the llms.txt approach on your own project I'd love to compare notes — and if the "why does AI design all look the same" problem is your itch too, I wrote up the longer argument here.

If you want to poke at it: designbycurio.com — and the llms.txt / index.json are right there to read.