Perguntas Frequentes
Tudo que você precisa saber sobre arquivos DESIGN.md e como usá-los com agentes de IA.
What is a DESIGN.md file?
A DESIGN.md is a Markdown file placed at the root of your project that describes your design system in a format AI coding agents can read. It contains YAML front matter with design tokens (colors, typography, spacing) and Markdown prose explaining how to apply them. When an AI agent like Claude Code, Cursor, or Kiro reads this file before generating UI code, it produces components that follow your visual rules consistently.
Why do I need a DESIGN.md if I already have Figma?
Figma is great for human designers, but AI coding agents cannot read Figma files. They work with text in your repository. DESIGN.md bridges this gap by putting your design decisions in a format that lives alongside your code and can be read by any LLM-based tool. Think of it as the machine-readable version of your Figma design system.
Which AI agents support DESIGN.md?
All major AI coding agents can read DESIGN.md since it is just a Markdown file. Specifically supported: Claude Code (via CLAUDE.md reference), Cursor (via .cursor/rules), Kiro (via .kiro/steering/ directory), Windsurf (via global_rules.md), and Google Stitch (native export). Any agent that reads project files can use it.
How is DESIGN.md different from design tokens in JSON?
Design tokens in JSON (like W3C Design Tokens format) are meant for build tools and code generation pipelines. DESIGN.md is meant for AI agents that need both the token values AND the reasoning behind them. The YAML section provides structured tokens, while the Markdown prose explains when and how to use them. An agent needs both to make good decisions.
What goes in the YAML front matter?
The YAML section contains your design tokens: colors (primary, surface, text, accent), typography (font families, sizes, weights), spacing scale, border radius, shadows, and any other quantifiable design decisions. Keep it concise — the agent needs values it can directly use in code.
What goes in the Markdown body?
The Markdown body contains qualitative guidance: an overview of the design philosophy, component patterns (how buttons, cards, and inputs should look), do's and don'ts, and any constraints the agent should follow. This is where you explain WHY certain decisions were made, not just WHAT the values are.
How long should a DESIGN.md be?
Between 30 and 150 lines is the sweet spot. Too short and the agent lacks context. Too long and it competes with your code for context window space. Most effective DESIGN.md files are 50-80 lines: a compact YAML section with 15-20 tokens and 3-5 short Markdown sections.
Can I have multiple DESIGN.md files in one project?
Yes, but it is not recommended for most projects. If you have a monorepo with distinct apps (marketing site + dashboard), each can have its own DESIGN.md. For a single app, one file at the root is clearest. Some teams use a base DESIGN.md with component-specific overrides in subdirectories.
What is designmd.app?
designmd.app is an open reference library of 454 pre-built DESIGN.md files covering every major design style — from Swiss minimalism to cyberpunk, from flat design to brutalism. Each file is a complete design system ready to download and use with any AI coding agent. The site also provides setup guides for each agent and articles about design system best practices.
Are the DESIGN.md files on this site free to use?
Yes. All DESIGN.md files in the library are available under Creative Commons Attribution 4.0 (CC BY 4.0). You can use them in personal and commercial projects. Attribution is appreciated but not required for the design system files themselves.
How do I choose the right DESIGN.md for my project?
Start with your product type and audience. B2B SaaS products typically work well with minimalist or flat systems. Consumer apps benefit from more expressive styles. Creative portfolios can use brutalist or maximalist approaches. Browse the library filtered by category, or search by keywords that match your brand personality.
Can I customize a DESIGN.md from the library?
Absolutely — that is the intended workflow. Download a DESIGN.md that is close to what you want, then modify the tokens (swap colors, change fonts, adjust spacing) and update the prose sections to match your specific brand. The structure stays the same; the values become yours.
Does DESIGN.md replace a component library?
No. DESIGN.md defines the visual rules; a component library implements them. They work together. The DESIGN.md tells the AI agent what a button should look like. The component library provides the actual React/Vue/Svelte component. If you do not have a component library yet, DESIGN.md helps the agent generate consistent components from scratch.
How often should I update my DESIGN.md?
Update it whenever your design system changes — new colors, new components, revised spacing. In practice, most teams update it a few times per quarter. The file should always reflect the current state of your design decisions, not aspirational future states.
What is the official DESIGN.md specification?
Google released the official DESIGN.md format specification at github.com/google-labs-code/design.md. It defines the canonical section order, YAML token schema, and linting rules. The @google/design.md npm package provides a CLI for linting, diffing, and exporting DESIGN.md files.
Does DESIGN.md work with Tailwind CSS?
Yes. Your DESIGN.md tokens can map directly to Tailwind config values. In the prose section, you can reference Tailwind utility classes (e.g., "Buttons use rounded-lg and bg-primary"). Agents like Cursor and Claude Code understand Tailwind and will generate appropriate utility classes based on your DESIGN.md tokens.
What if my agent ignores the DESIGN.md?
Make sure the agent is configured to read it. Each tool has a different mechanism: Cursor needs a rule in .cursor/rules pointing to the file, Claude Code needs a reference in CLAUDE.md, Kiro reads from .kiro/steering/ automatically. If the agent still ignores it, try referencing it explicitly in your prompt: "Follow the design system in DESIGN.md."
Can I generate a DESIGN.md from my existing codebase?
Yes. Ask your AI agent to analyze your existing components and extract a DESIGN.md. Prompt: "Analyze the UI components in src/components and generate a DESIGN.md that captures the current design patterns, colors, typography, and spacing." Review and refine the output, then save it as your canonical reference.
Tem uma pergunta não respondida aqui? Veja nossos guias de configuração ou navegue pela biblioteca.