DESIGN.md

Coding agents write great code and mediocre interfaces. One reason: they have no persistent sense of how this product is supposed to look. AGENTS.md and CLAUDE.md tell an agent how your code works. A design system file does the same for how your product looks — colors, typography, spacing, motion, component patterns, and the product context behind them — so every UI the agent ships is consistent with the last one instead of reinventing a generic look each time.

This is the design equivalent of llms.txt or AGENTS.md: a single, human-readable file an agent reads before it designs.

What goes in it

A good design system file is implementable without the codebase — an agent (or a person) should be able to build on-brand UI from it alone:

• Product context — what's being built, who it's for, the core value, key user journeys.
• Design tokens — colors, typography, spacing, radius, shadows.
• Motion — animation and interaction patterns.
• Components — the real patterns your product uses, with usage notes.

How Superdesign uses it

The Superdesign skill reads and writes this file at .superdesign/design-system.md. It can:

• Extract one from your existing codebase (tokens, components, patterns), or
• Create a new one from references when you're improving current UI.

If the file is missing, the skill runs Design System Setup first, then designs against it — so every draft on the canvas inherits the same system. See the README for the full workflow.

Why it matters

A design system file is the difference between an agent that produces default-shadcn-everything and one that produces UI that looks considered. Capture it once; every design after that is consistent, on-brand, and faster to ship.

---

Part of Superdesign, the AI product design agent. Browse the prompt library for ready-made style and component direction.