Can design.md be the design system?
A portable, versioned instruction layer can help AI coding agents produce interfaces that belong to the same product.
AI coding agents are very good at producing a plausible screen. The harder problem appears after the third, fifth, or twentieth screen: local decisions drift, one-off patterns multiply, and the product starts to look like several unrelated applications sharing a repository.
A traditional design system helps, but components and tokens alone do not always tell an agent how to use them. That is where a design.md file can become surprisingly powerful.
An instruction layer for design
A useful design.md describes the system in terms an agent can apply while working:
- Design tokens and when to use them
- Shared components and preferred composition patterns
- Layout, spacing, hierarchy, and responsive behavior
- Rules for reuse before invention
- Examples of what belongs in the product and what does not
Once these rules live beside the code, they become part of the implementation workflow. The agent can check a proposed screen against the same guidance every time instead of improvising from the nearest existing page.
Not a replacement for components
The component library remains the implementation. design.md is the instruction layer that makes the implementation legible to AI.
Both matter. Tokens without guidance are easy to misuse. Guidance without real components creates repeated bespoke code. Together they create a system that is portable, versioned, reviewable, and much easier for agents to follow.
A small file with compounding value
The most interesting part is portability. A strong design.md can live in starter repositories and product templates, carrying design judgment into every new project from the first generated screen.
It does not need to be an enormous specification. It needs to make the important decisions explicit enough that both humans and agents can recognize when a new interface belongs to the same product.