Do you write a DESIGN.md

AI tools are powerful, but they need context. Without clear design rules, they can generate UI that looks good in isolation but does not match your product.

A DESIGN.md file gives AI tools a shared source of truth for how the UI of your site should look and feel. It documents the small decisions that often live only in people’s heads: spacing, typography, button styles, card patterns, colours, tone of voice, responsive behaviour, and interaction states.

What is a DESIGN.md file?

Google Stitch helped popularise the DESIGN.md convention and has open-sourced a format specification for describing visual identity to AI coding agents.

Similar to a SKILL.md, SOUL.md or an AGENTS.md file, the DESIGN.md file acts as a single source of truth for the brand identity of your project. It is to act as the foundation for design decisions made when creating new content for a site.

Why does a DESIGN.md matter?

When there is either too little context; or too specific instructions when creating new UI/UX elements, AI agents often end up with too much flexibility which will lead to differing results over a site. This creates "design debt”.

Design debt often starts when developers (or agents) make reasonable one-off decisions:

• “This card needs a bit more padding”
• “This button should be slightly smaller”
• “This heading feels too bold”
• “This empty state just needs some quick copy”

Each decision might be fine on its own, but over time they create inconsistency. Do you use AI to reduce design debt?

A DESIGN.md helps stop this by making your UI rules explicit.

What should be in a DESIGN.md file?

A good DESIGN.md should include:

• Brand identity - What the product should feel like
• Product voice - How the UI copy should sound
• Design principles - The rules that guide decisions (e.g. consistency over novelty, reuse components, avoid one-off styling)
• Spacing Rules - Your spacing scale, common gaps, card padding, section spacing, and form spacing.
• Typography hierarchy - Rules for page titles, headings, body text, labels, helper text, and metadata
• Colour usage - When to use primary, secondary, muted, destructive, success, warning, and background colours.
• Component patterns - How buttons, cards, forms, modals, tables, navs, and alerts should look and behave
• Interaction states - Rules for hover, focus, active, disabled, loading, empty, error, and success states
• Responsive behaviour - How layouts should adapt on mobile, tablet, and desktop
• Accessibility expectations - Contrast, focus states, labels, keyboard access, and not relying on colour alone.
• Common anti-patterns - Things the team should avoid (e.g. random spacing, custom button styles, weak empty states, inconsistent border radius)
• AI instructions - How AI agents should use the file when generating, reviewing, or changing UI

The goal is to add the necessary context; but not bloat the file.

How do you use a DESIGN.md file?

Put the product’s design rules in DESIGN.md, then make each agent’s instruction file point back to it. This gives Claude, Codex, Copilot, Cursor, and other agents the same design context before they touch the UI.

An example of this for CLAUDE.md file:

# Claude instructions

Before making UI changes, read DESIGN.md.

Use DESIGN.md as the design source of truth for:
- Layout
- Spacing
- Typography
- Components
- Colour usage

Do not introduce new visual patterns if an existing component or token can be reused.

How do you create a DESIGN.md file?

Creating a DESIGN.md file can be done either manually; or with AI assistance (recommended).

You can work with any agent to create one, however you may get better results with tools designed to craft them:

• Impeccable via /impeccable document
• Figma AI within your Figma design system
• Download from a community DESIGN.md catalogue (e.g. designmd.ai)

Going beyond code

As AI tools become part of more workflows, your DESIGN.md should not only help with frontend code. It can also help keep your brand consistent across anything AI generates, such as:

• Presentations - Give tools like Claude Cowork your brand rules before creating slides
• Images - Give ChatGPT image generation your colours, tone, and visual style before creating assets
• Client demos - Make AI-generated materials feel like they belong to the same product or company
• Marketing content - Keep landing pages, social posts, emails, and banners aligned with the product voice