design.md as a Design Primitive
Argument for a design.md at the repo root so coding agents stop shipping generic UI
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.
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.
- design.md convention
- AGENTS.md / CLAUDE.md split
- why agents default to generic Tailwind
- what belongs in a visual spec file
Verified 2026-08-15. not fetched by policy (x.com); record built from the pre-retrieved full article text supplied in the batch
