# FAQ — DESIGN.md Questions & Answers

> Frequently asked questions about DESIGN.md files, AI coding agents, and the designmd.app library.

## 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.

## 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.

## 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).

## How is DESIGN.md different from design tokens in JSON?

Design tokens in JSON 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.

## 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.

## What goes in the Markdown body?

The Markdown body contains qualitative guidance: an overview of the design philosophy, component patterns, do's and don'ts, and any constraints the agent should follow. This is where you explain WHY certain decisions were made.

## How long should a DESIGN.md be?

Between 30 and 150 lines is the sweet spot. 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, each can have its own DESIGN.md. For a single app, one file at the root is clearest.

## What is designmd.app?

designmd.app is an open reference library of 759 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.

## 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.

## 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.

## 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 and update the prose sections to match your specific brand.

## 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 component.

## 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.

## 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.

## 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.

## 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, Claude Code needs a reference in CLAUDE.md, Kiro reads from .kiro/steering/ automatically.

## 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."

---
Source: https://designmd.app/faq