design.md as a Design Primitive
Argument for a design.md at the repo root so coding agents stop shipping generic UI
Tier B · UsefulArticleDesign Mdx.com
A long-form X article that argues the most load-bearing design file in a 2026 codebase is a markdown file named design.md, not a Figma library. It traces the convention from CLAUDE.md to .cursorrules to .windsurfrules to AGENTS.md, then argues for splitting the agent brain in two: AGENTS.md/CLAUDE.md for project rules and design.md for visual rules — color tokens, semantic naming, typography, component and layout rules, accessibility constraints. The stated failure mode is the useful part: with no design.md, every agent falls back to 'generic Tailwind dashboard'. Written for teams pointing Cursor, Claude Code, Codex, Lovable, v0, Windsurf, or Figma Make at an existing brand.
For an agent
Treat this as the rationale document for the spec file you should be writing, not as a spec itself — it names the sections (tokens, semantic color names, typography scale, component rules, layout rules, a11y constraints) but ships no template. Reach for it when a user asks why their agent-generated UI looks off-brand, then convert the argument into an actual design.md next to their AGENTS.md. Do not try to fetch the URL: x.com blocks server-side fetches, so the text has to come from a cached copy.
Why it is here. It is the clearest statement of the premise this whole index rests on — agents read markdown, so brand rules have to live in markdown or they do not exist.
Facts
- License
- Unknown
- Pricing
- Free
- Framework
- Not applicable
- Styling
- Not applicable
- Distribution
- Article, thread, or post
- Platform
- Web, Social / marketing creative
- Content type
- Prose / writing
- Agent readiness
- Blocks bots
- Accessibility
- Not applicable
- Maturity
- Stable
Notable for
- design.md convention
- AGENTS.md / CLAUDE.md split
- why agents default to generic Tailwind
- what belongs in a visual spec file
Provenance
Verified 2026-08-15. not fetched by policy (x.com); record built from the pre-retrieved full article text supplied in the batch
Also in Agent Design Tooling
6- Awesome DESIGN.md · 73 MIT-licensed DESIGN.md brand analyses you drop into a project root
- Impeccable · Design vocabulary and anti-slop detector for AI coding agents
- Impeccable · Design skill for AI coding agents: 23 slash commands and 59 detector rules
- Loora · Canvas design tool with a remote MCP server your coding agent edits live
- Mobbin MCP · MCP server that gives coding agents 621,500+ real shipped app screens
- Open Design · Local-first desktop app that turns your coding agent into a design engine