Templates

DESIGN.md template

A starter structure for writing a DESIGN.md file for your own product.

April 5, 20267 min read

Suggested outline

A DESIGN.md template that works for most products follows nine sections in a predictable order. The first section is product personality: a short paragraph describing the emotional register of the product, the target user, and the visual direction. The second is color: primary, secondary, neutral, semantic (success, warning, danger, info), and background values with exact hex codes or CSS token names. The third is typography: font stack, base size, heading scale from h1 to h6, body line height, and caption treatment. The fourth is spacing: the scale values and which values to use for which contexts. The fifth is border radius and shadows. The sixth is component rules. The seventh is page layout patterns. The eighth is examples of correct implementation. The ninth is anti-patterns. This structure works because AI agents scan headings before reading bodies, and consistent headings across sessions reduce the overhead of locating relevant rules before implementation begins.

Writing the product feel section

The product feel section is where you set the register for every visual decision the agent will make. It does not need to be long — two to four sentences — but it should be specific enough to distinguish your product from a generic SaaS. A good example: "This is a project management tool for distributed engineering teams. It should feel focused, information-dense, and respectable — not playful, not minimalist for its own sake. The product competes with Linear and Jira, so the standard is a professional tool, not a consumer app. Marketing surfaces can be warmer; the app shell should be consistently calm and task-focused." That paragraph gives the agent a mental model for thousands of edge cases not covered by specific rules. When the agent has to decide between a subtle hover treatment and a bold one, the personality statement tilts the decision toward subtle. It is the design philosophy that makes individual rules feel coherent together.

Color and typography tokens

The color section should go beyond listing palette values to mapping colors to their semantic meaning. Hex codes alone are not enough; the agent needs to know when to use each color. A useful structure maps each color to its role: "Primary: #3B82F6 — used for CTAs, active state indicators, focus rings, and primary action buttons. Never use for informational text or decorative backgrounds." If your product uses a CSS variable system or a Tailwind config, map the variables to human meaning: "--color-surface-raised" is more useful than "--gray-100" because the name signals intent rather than just a value. The typography section should give exact numbers: "Body text is 15px with 1.6 line height. H1 is 32px weight 700, H2 is 24px weight 600, H3 is 18px weight 600, small labels are 12px weight 500 uppercase with letter spacing." Those exact values allow an agent to catch mismatches between new components and existing ones.

Component and layout rules

The component section should cover the six to ten UI patterns that appear most often in the product. For a SaaS app, that typically means buttons (primary, secondary, ghost, danger), cards (standard and compact), form fields (input, select, textarea, validation), data tables (headers, rows, pagination, empty states), modals and dialogs (tone, sizing, button placement), and navigation (sidebar, top bar, breadcrumbs). For each component, write one concise paragraph that an agent could read and implement directly: "Cards use 16px padding at standard density and 12px at compact density. Border radius is 8px. Border is 1px solid the neutral-200 token — never a shadow on standard cards. Card headers sit above the content without a separator line. Actions go in the footer, right-aligned, using ghost or secondary buttons." The layout section should describe one to three page types the product uses most, with specifics on content organization. Specificity here prevents agents from inventing layout patterns that do not belong.

Minimum useful file

If you are just getting started and cannot write a comprehensive file yet, focus on the five areas with the most impact on AI-generated UI quality. First, define the primary color, neutral scale, and danger color with exact hex values. Second, write the font family, base text size, and the h1 and h2 heading sizes with weights. Third, state the default border radius and the padding values for cards and form fields. Fourth, describe how buttons work: fill style, font size, padding, and border radius for primary and secondary variants. Fifth, add one to two anti-patterns: visual choices the agent is likely to make by default that do not belong in the product. A file that covers those five areas in under 300 words will produce noticeably better output than an agent working with no design guidance. Grow it over time by adding a new rule each time you have to correct AI-generated UI.

Submitting to the directory

Once your DESIGN.md file exists and is publicly accessible — in a GitHub repository, a Gist, or a hosted documentation URL — you can submit it to DesignMD Directory. The directory catalogs real files from real products and is indexed for discovery by builders, designers, and AI agents looking for starting points. Submission helps others working on similar products find working examples faster than searching generic web results. It also provides discoverability for open source projects and design systems that want to demonstrate how they handle AI-assisted development. The simplest submission is a GitHub repository link: the directory will index the file, display the product name and description, and make it browsable by category. If your file contains sensitive internal naming conventions, consider creating a sanitized public version that preserves the structure without exposing proprietary details. The value of the directory grows with the number of real examples: each new file makes the whole catalog more useful.

Use DESIGN.md with a real product reference

Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.

Browse directory Submit DESIGN.md

Related guides

Templates7 min read