{"slug": "how-to-write-design-md-prose-that-ai-agents-actually-follow", "title": "How to Write DESIGN.md Prose That AI Agents Actually Follow", "summary": "A developer argues that DESIGN.md files should describe intent and rules rather than just token values to guide AI agents effectively. The post explains that prose explaining design rationale, such as color roles and typography jobs, enables agents to generalize correctly, with a 'Do's and Don'ts' section being the most critical for preventing off-brand output.", "body_md": "**To write DESIGN.md prose agents follow, describe intent and rules, not just values.** A token says a color is a hex; good prose says it is for the primary action only. Reasoning is what lets an agent generalise to cases you did not explicitly cover.\n\n```\n## Colors\n\n# WEAK - restates the tokens:\nPrimary is #1A1C1E. Secondary is #6C7278.\n\n# STRONG - explains intent:\nHigh-contrast neutrals with one warm accent. Use the accent\nonly for the single most important action. Never decoratively.\n```\n\nThe strong version gives the agent a rule it can apply to situations you never listed.\n\nLLMs read markdown with very high fidelity - most of their training is structured this way. That makes prose an ideal channel for design intent. The value tells the model what a color is; only prose tells it the rules.\n\nEach section answers a question the agent would otherwise guess at:\n\n``` php\n## Overview        -> the personality\n## Colors          -> roles and rules\n## Typography      -> the job of each style\n## Layout          -> grid and spacing\n## Do's and Don'ts -> hard guardrails\n## Do's and Don'ts\n- Do use the accent for one primary action per screen\n- Don't mix rounded and sharp corners in the same view\n- Do maintain WCAG AA contrast (4.5:1 for normal text)\n- Don't use more than two font weights on a screen\n```\n\nEach line removes a whole category of off-brand output.\n\nA good test: would the prose let a designer who had never seen your product apply your system correctly? Write what prevents a mistake, and stop there.\n\n**Descriptive color names?** Yes - tie them to the token name so the agent can map rationale onto values.\n\n**Most important section?** Do's and Don'ts - it directly prevents agent mistakes.\n\nTokens are easy; the rationale is the work. Spend your time on the prose that turns values into your identity.\n\n**Free starter:** The format, a complete annotated example, and the core idea are on a free cheat sheet: [DESIGN.md Quick-Start Cheat Sheet](https://promptmasterstore.gumroad.com/l/design-md-cheat-sheet)\n\n**Go deeper:** The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: [DESIGN.md: The Complete Guide to Design Systems for AI Agents](https://promptmasterstore.gumroad.com/l/design-md-guide)\n\nWhat is the one design rule you wish your agent would stop breaking? Drop it below - it probably belongs in your Do's and Don'ts.", "url": "https://wpnews.pro/news/how-to-write-design-md-prose-that-ai-agents-actually-follow", "canonical_source": "https://dev.to/promptmaster/how-to-write-designmd-prose-that-ai-agents-actually-follow-3bn7", "published_at": "2026-06-28 07:55:48+00:00", "updated_at": "2026-06-28 08:03:30.002040+00:00", "lang": "en", "topics": ["large-language-models", "developer-tools", "ai-agents", "generative-ai"], "entities": ["DESIGN.md", "WCAG", "Tailwind", "DTCG"], "alternates": {"html": "https://wpnews.pro/news/how-to-write-design-md-prose-that-ai-agents-actually-follow", "markdown": "https://wpnews.pro/news/how-to-write-design-md-prose-that-ai-agents-actually-follow.md", "text": "https://wpnews.pro/news/how-to-write-design-md-prose-that-ai-agents-actually-follow.txt", "jsonld": "https://wpnews.pro/news/how-to-write-design-md-prose-that-ai-agents-actually-follow.jsonld"}}