AI coding assistants can now build entire interfaces. What they cannot do is guess your taste. A design.md file closes that gap: a plain markdown document that encodes your brand voice, tokens, and conventions so every AI-generated screen looks like it belongs to your product. Here is what goes in one, why the format emerged, and how to write yours.
What is a design.md file?
A design.md is a markdown file, kept in your repository, that describes how your product should look, feel, and speak, in language both humans and AI coding assistants can read. It typically covers color tokens, typography, spacing, component conventions, tone of voice, and explicit do/don't rules. Think of it as a design system distilled into instructions rather than artifacts.
Traditional design documentation lives in Figma libraries, Storybook instances, Notion wikis, and PDF brand books. All useful. None of it is visible to the AI assistant writing your code. When a developer prompts "add a settings page," the model sees the codebase and its instruction files, not your Figma variables, not your brand deck. If the design intent is not in a file the model reads, the model improvises. Improvisation is how you end up with a product that has four shades of blue and three border radii.
A design.md fixes this by making design intent a first-class artifact in the repo: versioned with git, reviewed in pull requests, and loaded into the AI's context on every task. Design decisions stop being tribal knowledge. They become executable documentation.
Why did design.md emerge with AI coding assistants?
Because AI assistants read files, not Figma. As tools like Claude Code, Cursor, and Copilot became capable of generating full features, teams discovered a new class of instruction file (CLAUDE.md, AGENTS.md, .cursor/rules), and design.md is the design-focused sibling of that family. The convention exists because context is the only steering wheel these tools have.
The pattern is consistent across the ecosystem:
- CLAUDE.md gives Claude Code project-wide instructions (build commands, architecture notes, coding standards) loaded automatically at the start of a session.
- AGENTS.md is an emerging cross-tool convention for the same idea, readable by multiple agents.
- Cursor rules (
.cursor/rules) scope instructions to file patterns and behaviors inside Cursor.
All three answer the same question: how do we tell the machine things it cannot infer from code alone? Engineering teams answered it first, with conventions about testing and architecture. Design teams are answering it now. A design.md is often referenced directly from CLAUDE.md, with one line like Read design.md before writing any UI code, so the design contract loads whenever the assistant touches the interface.
There is a second force at work: AI collapsed the distance between a design decision and shipped code. When a model can go from prompt to component in seconds, the bottleneck is no longer implementation speed. It is intent transfer. Markdown design docs are the highest-bandwidth way to transfer intent to a language model, because language models are (unsurprisingly) very good at language.
What belongs in a design.md file?
Everything an unfamiliar but competent designer would need to ship an on-brand screen without asking questions. In practice that means brand voice, design tokens, component conventions, art-direction keywords, and explicit do/don't lists. Keep it opinionated and keep it short: a bloated design.md gets skimmed by humans and diluted in the model's context.
A strong design.md covers:
Brand voice and tone. How the product speaks. Sentence length, formality, humor policy, capitalization rules for headings and buttons. "Sentence case everywhere. No exclamation marks. Confirmations state what happened, not how excited we are."
Color tokens. Named tokens with hex values and usage rules. A hex code alone tells the model what a color is; the rule tells it when to use it. "--accent is for primary actions only, never for decoration."
Typography. Font families, the type scale, weights, and pairing rules. Include line-height and when to use each step, not just the list of sizes.
Spacing and layout. The spacing scale (4px or 8px base), container widths, grid behavior, border-radius values. Models are notorious for inventing arbitrary padding; a stated scale ends that.
Component conventions. Naming patterns, variant structure, state requirements (hover, focus, disabled, loading, empty, error), and which primitives to reach for before building anything new.
Art-direction keywords. Adjectives that compress an aesthetic: "editorial, restrained, generous whitespace, no gradients, no glassmorphism." These words steer generative output more than most teams expect. They are the difference between a model defaulting to generic SaaS purple and matching your actual sensibility.
Do/don't lists. The highest-leverage section. Explicit prohibitions ("never use pure black #000," "no drop shadows above 8% opacity," "don't center-align body text") prevent the most common off-brand failures with a single line each.
What does a real design.md look like?
Here is a condensed, annotated example, the shape we use for client work at Things:
# Design.md: Atlas Dashboard
## Voice
- Confident, plain, brief. Sentence case everywhere.
- Buttons are verbs: "Save changes", not "Submit".
- Errors say what happened + what to do next. Never blame the user.
## Color
| Token | Value | Use for |
|--------------|-----------|----------------------------------|
| --ink | #16181D | Primary text. Never pure black. |
| --paper | #FAFAF7 | App background. Never pure white.|
| --accent | #2D5BFF | Primary actions ONLY. |
| --danger | #C93B2E | Destructive actions + errors. |
- One accent per view. If two elements compete, demote one.
## Type
- UI: Inter. Editorial surfaces (marketing, empty states): Tiempos.
- Scale: 13 / 15 / 18 / 24 / 32. Body is 15/1.6.
- Weight 600 max in UI. No 700+ except marketing headlines.
## Space & shape
- 8px scale: 8, 16, 24, 32, 48, 64. Nothing in between.
- Radius: 8px inputs/cards, 999px pills. Nothing else.
- Shadows: single layer, ≤8% opacity, or none.
## Components
- Check src/components/ui before creating anything new.
- Every interactive element needs hover, focus-visible,
disabled, and loading states. No exceptions.
- Empty states get an illustration + one action. Never just text.
## Art direction
Editorial, calm, generous whitespace, quietly confident.
NOT: playful, gradient-heavy, glassmorphic, dense.
## Never
- Pure #000 or #FFF. Center-aligned body text.
- More than one accent-colored button per view.
- Placeholder text as a label substitute.
Notice what makes it work: every value has a rule attached, the tables read as constraints rather than inventory, and the "Never" list handles the failure modes head-on. The whole file fits comfortably in an AI context window alongside the code.
How does a design.md keep AI-generated UI on-brand?
It turns implicit taste into explicit constraints, applied on every single generation. Without it, the model falls back on the statistical average of the interfaces it was trained on: competent, generic, and unmistakably not yours. With it, every prompt runs through your rules before a line of JSX exists.
The mechanics are simple. When the assistant loads the file (automatically via CLAUDE.md, or through cursor rules scoped to UI paths), your constraints become part of the generation itself, not a review step afterward. Ask for a pricing card and the model already knows the radius is 8px, the accent appears once, and the CTA is a verb. Consistency stops depending on whoever happens to be reviewing the pull request.
The compounding effect matters more than any single screen. Ten features generated against the same design.md look like one product. Ten features generated without it look like ten products. And when the design evolves, you edit one file and every future generation inherits the change. The doc is upstream of the code, the way a design system should be.
How does design.md fit into design systems and design-to-code workflows?
It is the narrative layer of a design system: the "why and when" that token files and component libraries cannot express. Your tokens.json defines what exists; your design.md defines how to use it. AI assistants need both, and they need the second one far more than most teams realize.
In a mature setup, the layers stack cleanly: design tokens exported from Figma feed the codebase, the component library implements them, and design.md governs usage (which variant when, what the empty state must include, what never ships). For handoff, the effect is blunt: the document is the handoff. Instead of designers annotating mockups and developers interpreting them, both sides (and the AI between them) read the same contract. Disagreements become pull requests against a file, not Slack threads. New teammates onboard by reading one document. Lost intent, the quiet killer of design quality, has nowhere to hide.
How does Things use markdown design docs in its own process?
At Things, design and engineering run in parallel (no handoff gaps, no lost intent), and markdown design docs are how we hold that line at AI speed. For every product we build, art direction and UX copy live as versioned markdown in the repo from day one, loaded into our AI-augmented workflows on every task.
We are a studio, not an agency, and it shows in how these documents get made. Since 2018, from Istanbul and Elazığ, we have shipped 50+ products across research, UX/UI, design systems, and engineering (Red Dot awarded along the way), and the pattern that survives every project is the same: research findings become art-direction keywords, brand strategy becomes a voice section, and the design system's rules become constraints the AI cannot ignore. When our engineers prompt an assistant, it already writes in the client's voice and stays inside the client's system. The craft is in the document; the speed is in the tooling. Design. Code. Mastery.
FAQ
Is design.md an official standard? No. Like CLAUDE.md and AGENTS.md, it is a convention, not a specification. The name matters less than the practice: a markdown file of design constraints, in the repo, loaded into AI context. Some teams fold it into CLAUDE.md; larger systems split it into linked files.
How is design.md different from CLAUDE.md? CLAUDE.md covers project-wide instructions: build commands, architecture, coding standards. Design.md focuses on visual and verbal identity. Keep them separate and reference design.md from CLAUDE.md so it loads for UI work without bloating every backend task.
How long should a design.md be? Short enough to read in five minutes, roughly one to three pages. Every line competes for the model's attention, so cut inventory and keep rules. If a rule never prevents a mistake, delete it.
Do I still need Figma and a component library? Yes. Design.md complements them; it does not replace them. Figma is where design is explored, the component library is where it is implemented, and design.md is where its rules become legible to AI tools and new teammates.
Who should own the design.md? Designers author the intent; engineers keep it wired into the tooling. The healthiest version is co-owned and updated through pull requests, so every design decision leaves a reviewable trail.
Bring your design system into the AI era
If your team is shipping with AI assistants but your design intent still lives in slide decks, you are leaving consistency to chance. Things helps product teams turn brand and system knowledge into working documentation, and builds the product to match. Research-driven, craft-obsessed, design and engineering in parallel.
Talk to us: hello@things.ist · things.ist