design.md

What is DESIGN.md?

DESIGN.md is a plain-text markdown file placed in the root of a project repository. It serves as a "visual source of truth" for AI coding assistants. While traditional design systems are meant for human consumption, a DESIGN.md file is structured specifically for LLMs — it provides the colors, typography, spacing, component rules, and overall "vibe" needed to generate consistent, brand-aligned UI code.

Anatomy of a DESIGN.md File

• YAML front matter— machine-readable design tokens (hex codes, font scales, border radii)
• Markdown prose— human- and AI-readable rationale, guidelines, and explicit "Do's and Don'ts"

Why It Works

• Prevents UI drift — every component generated adheres to the same visual language
• Rapid iteration — visual preferences change in one place
• Version control — design decisions live alongside the code

Key Repositories

• google-labs-code/design.md (opens in a new tab) — the official format spec, documentation, and a linter
• VoltAgent/awesome-design-md (opens in a new tab) — curated DESIGN.md files inspired by top-tier brands

Basic Template

1---
2brand:
3  name: "Enpitech"
4  vibe: "Modern, technical, precise"
5colors:
6  primary: "#8E2DE2"
7  background: "#090715"
8  surface: "#110D26"
9typography:
10  font_sans: "'Inter', sans-serif"
11  font_mono: "'Fira Code', monospace"
12---
13
14# Design Rules
15- **DO** use flexbox for layouts.
16- **DO** use sentence case for buttons.
17- **DON'T** use drop shadows, use 1px borders instead.

Advanced Template (Semantic Tokens)

1---
2brand:
3  name: "Enpitech"
4  vibe: "Modern, technical, precise, and approachable"
5tokens:
6  colors:
7    primary:
8      DEFAULT: "#8E2DE2"
9      foreground: "#FFFFFF"
10    background: "#090715"
11    surface:
12      DEFAULT: "#110D26"
13      border: "rgba(255,255,255,0.1)"
14  typography:
15    sans: "'Inter', sans-serif"
16    mono: "'Fira Code', monospace"
17  spacing:
18    container: "max-w-6xl"
19    card_p: "24px"
20  motion:
21    default: "200ms ease-out"
22---
23
24# Design System Philosophy
25Our interfaces should feel invisible. We prioritize clarity over decoration.
26
27## Component Rules
28### Cards
29- Always use `colors.surface.DEFAULT` for background.
30- Inner padding should strictly adhere to `spacing.card_p`.
31
32### Interactive Elements
33- Hover states must apply `motion.default` transition.
34- **DON'T** use rounded corners greater than `12px`.
35- **DON'T** introduce colors outside the token palette.

Best Practices

• Be explicit with "DON'Ts"— AI models respond better to negative constraints. "DON'T use drop shadows on buttons" beats "make the buttons look nice"
• Keep it concise— bullet points and direct instructions, not flowery prose
• Test and iterate— prompt the agent to build a component, review the output, add rules to prevent specific mistakes

Pair It With figma-to-code

Pair your DESIGN.md with figma-to-code for pixel-perfect UI. Without DESIGN.md, that skill generates generic CSS or hardcoded hex values; with it, raw Figma colors and spacing values map directly to your design system tokens.