DESIGN.md Interface
A top-level design document for brand mood, visual rules, and layout philosophy.
Key takeaways
- DESIGN.md is the top-level layer that gives agents brand mood, visual hierarchy, density, and composition rules beyond tokens and specs.
- It answers product feel, what deserves attention first, layout philosophy, allowed motion, imagery, and which AI UI patterns are prohibited.
- A useful structure states product feel plus explicit layout and visual rules, such as semantic tokens only and no nested cards.
- Agents read DESIGN.md before creating new surfaces, then apply component docs for implementation detail rather than copying example screens.
- Verify generated screens against the stated product feel, the explicit forbidden patterns, and the density expected for the surface type.
Tokens and component specs are not enough to make a screen feel like the product. Agents also need
brand intent, visual hierarchy, density, and composition rules. DESIGN.md is that top-level layer.
Role of DESIGN.md
| Layer | Answers |
|---|---|
| Brand mood | What should the product feel like? |
| Visual hierarchy | What deserves attention first? |
| Layout philosophy | Dense tool, editorial page, dashboard, marketplace, or app shell? |
| Motion | What movement is allowed and why? |
| Imagery | What kind of assets represent the product? |
| Prohibitions | What common AI UI patterns should never appear? |
Suggested Structure
# DESIGN.md
## Product Feel
Quiet, precise, operational, and data-dense.
## Layout Rules
- Use full-width bands for page sections.
- Use cards only for repeated items, tools, and modals.
- Do not nest cards.
## Visual Rules
- Use semantic tokens only.
- Avoid decorative gradient blobs.
- Keep labels compact inside dashboards.How Agents Should Use It
- Read
DESIGN.mdbefore creating new UI surfaces. - Apply component docs for implementation details.
- Use visual examples only as grounding, not as permission to copy unrelated patterns.
- Run a screenshot check for any meaningful UI change.
Verification
- Compare generated screens to the stated product feel.
- Check forbidden patterns explicitly.
- Review whether density, hierarchy, and text scale match the surface type.