VI EN
Tools

DESIGN.md: put your design taste in the repo so AI-built UIs stop looking generic

Binh Updated 3 min read Đọc bài này bằng tiếng Việt

TL;DR

DESIGN.md is a Markdown file describing a design system (colors, typography, spacing, elevation, responsive rules) for coding agents to read while building UI. VoltAgent/awesome-design-md and getdesign.md provide hundreds of references. Use them as starting points, not as a way to copy someone else's brand.

Ask a coding agent to build a landing page and you usually get something “correct but bland”: purple gradients, rounded cards, default fonts — like thousands of other AI-made pages. The reason is simple: the agent doesn’t know your design taste. DESIGN.md fixes exactly that: a Markdown file describing your design system for the agent to read before writing UI, just as AGENTS.md describes how to build the project.

What is DESIGN.md?

It’s a design-system document written in plain Markdown. Because models read Markdown very well, you don’t need Figma exports, JSON tokens or build tooling — just one file in the project root. The format builds on the DESIGN.md specification from Google Stitch, Google’s AI design tool.

What a complete DESIGN.md contains

SectionContent
1. Visual theme & atmosphereOverall mood: minimal, editorial, playful, technical…
2. Color palette & rolesColours with roles: primary, surface, text, border, states; light and dark
3. Typography rulesFonts, type scale, line-height, weights for headings/body/labels
4. Component stylingsButtons, cards, inputs… with hover/focus/disabled states
5. Layout principles4/8px spacing scale, max widths, grid, whitespace rhythm
6. Depth & elevationShadows, radii, layering
7. Do’s and don’tsWhat to do and avoid — the section that does most to prevent “AI slop” UI
8. Responsive behaviorBreakpoints and how things adapt on mobile
9. Agent prompt guideA quick colour reference and ready-to-use prompts

The template collection: VoltAgent/awesome-design-md

Instead of starting from scratch, you can begin with VoltAgent’s awesome-design-md repository — according to BrightCoding it holds 73 DESIGN.md files extracted from real brands’ websites and has around 102,000 GitHub stars:

  • AI platforms: Claude, Cohere, ElevenLabs…
  • Developer tools: Vercel, Cursor, Warp…
  • Fintech: Stripe, Coinbase, Revolut…
  • Automotive: BMW, Tesla, Ferrari…
  • “Retro Web”: Dell 1996, Nintendo.com 2001 — for nostalgic projects.

Each entry ships with preview.html and preview-dark.html so you can check the tokens in a browser before handing the file to an agent. The getdesign.md site lets you browse and download individual files.

Using it with Claude Code (or any agent)

  1. Pick a template close to the style you want on getdesign.md or in the repo, and open its preview to check.
  2. Copy it into your project root as DESIGN.md.
  3. Customise: swap colours, fonts and brand names for your own; drop components you don’t use. This step is mandatory — don’t ship another brand’s identity.
  4. Wire it to the agent: add one line to CLAUDE.md or AGENTS.md: “All UI work must follow DESIGN.md in the project root.”
  5. Make the agent self-check: ask it to review its UI against the Do’s and Don’ts section before reporting done.
Sample prompt:
Build a three-tier pricing page following DESIGN.md. Use the exact colour tokens and spacing scale.
When done, list where you applied the "Do's and Don'ts" section.

Important caveats

  • Brand rights: the repo structure and extraction work are MIT-licensed, but visual identities (logos, signature colours, proprietary fonts) belong to their owners. Learn the structure and principles; don’t clone someone else’s look for a commercial product.
  • Possible errors: files are extracted from public CSS and may have wrong hex values or missing tokens; values reflect the extraction date.
  • Non-web targets: for React Native or SwiftUI, quality depends heavily on the agent’s capabilities.

How to apply it

  • Developers: If your project already has a design system, ask the agent to read the current CSS/theme and reverse-engineer a DESIGN.md — every new screen will then stay consistent.
  • Tech Leads: Keep DESIGN.md next to AGENTS.md in the repo and review changes to it like design-token changes.
  • PMs / designers: DESIGN.md is the cheapest way to turn your team’s taste into something an agent understands. Fill the Do’s and Don’ts from the UI feedback you keep repeating.

Sources & references

  1. VoltAgent/awesome-design-md: DESIGN.md Files for AI UI Generation — BrightCoding
  2. VoltAgent/awesome-design-md — GitHub
  3. getdesign.md — getdesign.md
More on Tools