Design Systems
DESIGN.md vs Figma design systems
Why DESIGN.md is the agent-readable counterpart to a traditional design system.
Different consumers
Figma design systems are built for human designers and engineers working in a visual handoff workflow. They are interactive, browsable, and visual. A designer can open a Figma library, see a component in its active state, drag it onto a frame, and inspect spacing and color values. An engineer can use the inspect panel to extract font properties, spacing, and color codes. This workflow is well-established and useful for human-driven development. But AI coding agents cannot interact with Figma. They cannot open a URL in a browser, browse a component library, or use an inspect panel. They work with files in the repository — code, markdown, configuration. A Figma design system, however complete, is invisible to an agent unless its content is translated into a format the agent can read. DESIGN.md is that translation: it takes the decisions documented in Figma and expresses them in plain text that an agent can parse and apply.
What Figma cannot tell an agent
Even if an agent could read Figma data, the information in a Figma file is organized for visual inspection rather than textual instruction. Component names and layer names are visible, but the rules governing when to use each component are typically not explicit. A Figma file shows that a button exists with a specific color and radius, but it does not say "use the primary button for the single most important action on the screen and the secondary button for all other actions." It does not say "never place a primary button adjacent to a destructive action in the same button group." It does not say "use the compact card variant in data tables and the standard card variant in dashboard overviews." These decision rules live in the designer's head and in unwritten team conventions. DESIGN.md makes those conventions explicit and machine-readable, turning tacit design knowledge into an implementable specification.
Where DESIGN.md fills the gap
DESIGN.md fills the gap between a Figma design system and an AI agent's needs in three specific ways. First, it provides text-format values: instead of an agent needing to inspect a Figma component to find the border radius, DESIGN.md states "card radius is 8px." Second, it provides semantic rules: instead of an agent inferring which button variant to use from surrounding context, DESIGN.md states when each variant applies and under what conditions. Third, it provides negative space: it tells the agent what not to build, which is information entirely absent from Figma. A Figma library contains examples of what to build. DESIGN.md contains both examples and explicit prohibitions. Together, they create a more complete design specification: Figma for visual proof and component exploration, DESIGN.md for agent instruction and consistent implementation guidance.
The combined workflow in practice
The most effective setup treats Figma and DESIGN.md as complementary sources of truth, each serving a different consumer. Figma is where designers create, review, and approve components; DESIGN.md is where those same decisions are translated into agent-readable rules. When a design change happens — a new card radius, a tighter spacing system, a revised neutral palette — the Figma library is updated and DESIGN.md is updated in the same sprint. Engineers review the Figma diff and read the DESIGN.md update in the same pull request, keeping implementation and intent synchronized. A practical recommendation: do not wait until the Figma system is complete before writing DESIGN.md. A file with just the primary color, type scale, card density, and three anti-patterns is immediately useful to an agent; a complete Figma library with no markdown equivalent is invisible to the agent. Start DESIGN.md as soon as the core visual decisions are stable and expand it as the system matures. Maintaining both files tends to have a useful side effect: writing rules in prose forces a level of specificity that a purely visual system can sidestep. Teams often discover that drafting DESIGN.md surfaces implicit conventions in the Figma library — assumptions about component hierarchy and density defaults that were previously held only in individual designers' heads.
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
DESIGN.md vs design tokens
Why DESIGN.md complements tokens instead of replacing them.
DESIGN.md for shadcn/ui
How to keep shadcn/ui fast without letting your product feel generic.
DESIGN.md for Tailwind CSS
Use DESIGN.md to stop Tailwind-generated UI from collapsing into generic utility soup.