A production-tested template for giving AI coding agents a consistent brand system to work from.
Built from a live production site stylesheet — not a demo, not a starter kit. Every placeholder in this template maps to a real value extracted from working production CSS.
→ Need a custom DESIGN.md built from your codebase? flohcreative.com
DESIGN.md is an emerging open format (originated by Google Stitch, community-expanded via VoltAgent/awesome-design-md) for describing a visual identity to AI coding agents. Instead of re-explaining your brand colors and component styles in every prompt, you maintain one file at the root of your project repo and the agent reads it first on every task.
This template gives you the full 9-section structure with:
- Every placeholder clearly marked as
{{ PLACEHOLDER_NAME }} - Inline comments explaining what each section does and how to fill it in
- Production-tested component CSS patterns for buttons, cards, forms, navigation, and badges
- An Agent Prompt Guide (Section 9) — a cheat sheet the agent reads last as a rules summary
| Covered | Not Covered |
|---|---|
| ✅ Brand colors, typography, spacing tokens | ❌ Header & footer (server-rendered by CMS) |
| ✅ Component styles (buttons, cards, forms, nav, badges) | ❌ Responsive behavior testing (agent interprets, cannot test) |
| ✅ Layout principles and grid system | ❌ Image sizing, cropping, and focal point instructions |
| ✅ Responsive breakpoints (documented) | ❌ CMS integration (WordPress, WooCommerce, WPBakery, ACF) |
| ✅ Do's and Don'ts with compliance hooks | ❌ Dynamic data (menus, product catalogs, user state) |
| ✅ Agent Prompt Guide for consistent output | ❌ JavaScript behavior and interactions |
Honest assessment: DESIGN.md covers approximately 30–40% of what a complete production page needs. It is a design token and component specification — not a full page architecture. Agent output should be treated as a first draft that a developer reviews and integrates, not a finished page ready to publish.
- Greenfield static HTML/CSS pages — Claude Code reads this file and generates on-brand pages without re-briefing every session
- AI-assisted landing page drafts — generate structure and styling, developer finalizes and integrates
- QR code product landing pages — on a clean builder like Elementor/Hello Theme, this file produces consistent results
- Developer CSS token reference — hand alongside Figma layouts as the definitive production value reference
- Claude Code prompt anchor — consistent brand copy, component patterns, and page structure across sessions
- Replacing a developer on complex CMS builds (WordPress/Salient/WPBakery/Elementor)
- Generating pages to publish directly without human QA
- Replicating existing CMS site architecture — the agent cannot access your live theme files
- Regulated industry deployments where compliance copy accuracy is legally required (always human-review agent output)
Open DESIGN.md and replace every {{ PLACEHOLDER }} with your actual brand values. Read the inline comments for guidance on each field.
Best practice: Pull values directly from your live stylesheet or Figma file — do not estimate. Agents use these values exactly as written.
Before giving this file to an AI coding agent, remove all HTML comments (<!-- ... -->). Comments slow down context processing and can confuse the agent's interpretation of instructions.
If you are using the design.md CLI:
npx @google/design.md lint DESIGN.mdThis validates token references and checks WCAG contrast ratios automatically.
Save as DESIGN.md (all caps) in the root of your project repository. Most AI coding agents look for it here by convention.
Start Claude Code sessions with:
Read DESIGN.md before generating any page output. Follow all component styles,
color tokens, and rules in Section 7 (Do's and Don'ts) exactly.
All placeholders follow {{ SCREAMING_SNAKE_CASE }} convention — recognizable to both humans and AI agents as slots to fill.
| Placeholder Category | Examples | Where to Find Values |
|---|---|---|
| Brand colors | {{ PRIMARY_HEX }}, {{ ACCENT_1_HEX }} |
Live stylesheet, Figma styles panel |
| Typography | {{ PRIMARY_FONT_NAME }}, {{ BODY_SIZE }} |
Google Fonts embed, computed CSS |
| Spacing | {{ BTN_PADDING }}, {{ CARD_PADDING }} |
Browser DevTools → computed styles |
| Layout | {{ CONTENT_MAX_WIDTH }}, {{ MODAL_MAX_WIDTH }} |
Stylesheet or Figma frame settings |
| Brand voice | {{ BRAND_TONE }}, {{ WHITESPACE_PHILOSOPHY }} |
Brand guidelines or brief |
| Industry compliance | {{ INDUSTRY_COMPLIANCE_DO_1 }} |
Legal/regulatory requirements |
Section 7 (Do's and Don'ts) includes dedicated placeholders for industry compliance rules:
{{ INDUSTRY_COMPLIANCE_DO_1 }}/{{ INDUSTRY_COMPLIANCE_DONT_1 }}{{ INDUSTRY_AGENT_RULE_1 }}/{{ INDUSTRY_AGENT_RULE_2 }}in the Agent Prompt Guide
These are particularly important for regulated industries including legal cannabis, alcohol, financial services, healthcare, and pharmaceuticals — where agent-generated copy must never include prohibited claims, must always include required disclaimers, and should always be reviewed by a human before publishing.
As of June 2026, design.md is an alpha-stage specification (v0.2.0). This means:
- The spec is still evolving — file structure may change between versions
- AI agent interpretation varies by model and version — output is not guaranteed to be consistent
- Works best for greenfield static builds; CMS integration requires developer effort
- Treat all agent output as a draft requiring human QA before publishing
This template will be updated as the spec matures.
This template was built and tested by Floh Creative — derived from a production website's live stylesheet, tested against real brand assets, and validated against the limits of current AI coding agent capabilities.
If you need a DESIGN.md file built from your actual codebase — not a template you fill in yourself — we build them. Every value pulled from your live CSS, every component pattern tested, every compliance requirement documented.
MIT — free to use, adapt, and build on. Attribution appreciated but not required.
If this template helped you, a GitHub star helps others find it. ⭐
