Getting Started
Best DESIGN.md examples
Examples of DESIGN.md files, templates, and public tools for AI-readable design systems.
Example: a SaaS dashboard DESIGN.md
A strong SaaS dashboard DESIGN.md starts with density and navigation. It specifies how the sidebar works at different screen sizes, how the top bar handles actions versus breadcrumbs, and how data tables render with sorting, pagination, and bulk actions. It defines card structure: a compact header with an icon or metric label, a body area that holds either table content or a chart, and an optional footer with right-aligned actions. It names the chart library, chart colors, and axis text treatment. It describes the dashboard home layout: typically a stats row at top, then content sections below. It includes empty states for every major data surface: an empty table, an empty chart, a new account with no data yet. It closes with anti-patterns: no marketing copy inside the app shell, no decorative gradients on operational surfaces, no oversized hero sections inside the authenticated product.
Example: a docs site DESIGN.md
A docs site DESIGN.md focuses on typography, navigation, and content formatting. The most important rules cover readability: line width, line height, base font size for prose and code blocks, heading hierarchy, caption style, and callout or note treatment. Navigation rules specify how the sidebar is organized, how depth is shown with indentation, how the active page is highlighted, and whether search is always visible. Code block rules define language-specific syntax coloring, inline code treatment, and copy button placement. Callout rules distinguish between info, warning, and danger states with specific background colors and border styles. A docs DESIGN.md also specifies image rules: maximum width, caption placement, and border treatment for screenshots. The mobile rules describe how the sidebar collapses, how code blocks handle overflow, and how the header adapts to smaller viewports.
Where to look
Several reliable sources exist for DESIGN.md examples. Official tool documentation is one: Google Stitch published its own DESIGN.md format when it launched, making it the canonical public reference for the convention. Community GitHub collections are another: searching GitHub for "DESIGN.md" returns real files from active projects, ranging from minimalist token lists to detailed multi-section specs covering full product surfaces. DesignMD Directory itself catalogs these files and links to examples by product category, making it the fastest way to browse by product type. Refero Styles and Neuform collect visual systems that can serve as a foundation when building design rules from scratch. The strongest approach is to look at two or three real examples in a category similar to your product, then write a file that adapts the structure to your specific context. Copying structure is reasonable; copying rules blindly produces a file that does not reflect your actual design system.
How to evaluate one
The test for a DESIGN.md file is whether it is implementable without any other design reference. Ask this question: could an AI agent read only this file and rebuild a page that looks like it belongs to the product? If the answer is no, identify what is missing. If the file only describes colors and fonts, it is missing component rules and page layout patterns. If the file describes components but not states, it is missing interaction context for loading, empty, and error conditions. If the file uses adjectives without measurements, it needs concrete values in place of abstract language. A practical evaluation method is to give the file to Claude Code or Cursor and ask it to generate a settings page from nothing but the DESIGN.md. Then compare the output against a real page in the product. Every place where the output diverges is a gap in the spec. Document the gap as a new rule, refine, and test again.
Building your own based on examples
Using examples as a foundation is faster than starting from scratch, but the goal is a file that reflects your product specifically. Take an example that matches your product category — SaaS dashboard, docs site, marketing page, AI tool — and work through it section by section. Replace the example color tokens with your actual values. Replace the typography stack with your fonts and sizes. Replace the component descriptions with how your actual components work in production. When you reach sections that describe something your product does not have, remove them rather than leaving generic placeholder content. When you realize your product has a surface the example does not cover, add a new section. The process typically takes two to three hours for a first complete file. After that, it is a maintenance document: you add a rule when the AI gets something wrong, you update a value when the design changes, and you refine a section when a new product surface is added. The file improves in proportion to how actively you use it.
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.
Related guides
What is DESIGN.md?
DESIGN.md is a markdown file that explains a product visual system to AI agents before they generate UI.
DESIGN.md vs CLAUDE.md
Keep engineering behavior and visual behavior separate so agents can follow both well.
DESIGN.md vs AGENTS.md
A clean mental model for splitting agent instructions by domain.