design.md template
A design.md template gives an AI coding agent persistent design instructions inside a project. Instead of repeating taste preferences in every prompt, you define the visual system once: mood, audience, palette, typography, layout, components, imagery, motion, accessibility and QA rules.
Why persistent instructions matter
Coding agents can implement quickly, but they often drift visually across pages. A design.md file acts as a stable design contract for the repo.
It gives the agent reusable rules for layout, spacing, palette and visual tone. That matters when work spans several sessions or multiple agents.
Where it should live
Put design.md at the project root or in a docs folder that agents are explicitly told to read. It should be close enough to the codebase that it becomes part of the implementation workflow.
If the repo already has agent instructions, reference design.md from that file instead of duplicating the same design rules in several places.
What to include
A strong design.md includes brand mood, target audience, visual references, palette, typography, layout rules, components, imagery, motion, responsiveness, accessibility, anti-patterns and a QA checklist.
The file should contain practical rules the agent can execute and test, not just adjectives.
Prompt example
# design.md
Mood: sharp, editorial, useful, quietly premium.
Audience: builders using coding agents.
Palette: off-white, graphite, muted teal, sparing cyan.
Typography: serif headlines, clean sans body, mono for code.
Layout rules: shallow cards, strong grid, no nested panels.
Do not do: no generic gradients, no fake logos, no AI blobs.
QA: inspect screenshots before final, mobile first viewport included.Common mistakes
- Turning design.md into a moodboard with no rules.
- Listing colour values without usage guidance.
- Omitting mobile, accessibility and component states.
- Letting the file get stale as the site evolves.
- Duplicating conflicting instructions across several docs.
Workflow
- Create design.md before building a substantial UI.
- Reference it in agent instructions or task prompts.
- Ask the agent to extract tokens and component rules before coding.
- Review screenshots against the file.
- Update design.md only when the visual system materially changes.
FAQ
What is a design.md file?
It is a markdown file containing persistent design direction for an AI coding agent or project repo.
Where should design.md live?
Usually at the project root or in a docs folder where the agent can easily read it.
What should design.md include?
It should include visual mood, audience, palette, typography, layout rules, imagery, motion, accessibility and QA checks.
Is design.md a replacement for a design system?
No. It is a lightweight agent-readable layer that can reference or summarise a fuller design system.