Craft DESIGN.md rules AI agents actually understand

Design systems are built on tokens, but AI agents need more than values to follow your rules. A well-written DESIGN.md document bridges that gap by translating design principles into actionable instructions.

When an agent encounters a hex code like #1A1C1E, it sees a color. But when it reads prose that explains why that color should be used only for primary actions, the agent gains the ability to generalize beyond the literal token. This shift from value to rule is what transforms a static document into a functional guideline for AI-driven workflows.

From tokens to reasoning: why prose matters

Large language models process markdown with remarkable precision. Their training data is rich in structured documentation, making prose an ideal medium for conveying design intent. A token alone tells an agent what something is; prose tells it how and when to use it.

Consider a color token defined as primary: #1A1C1E. Without context, an agent might apply it to any element, from buttons to backgrounds. But if the DESIGN.md specifies that this color should only be used for the most critical action on a screen, the agent gains a rule it can apply universally—not just to the cases you’ve explicitly listed.

The essential sections every DESIGN.md must cover

A well-structured DESIGN.md answers the questions an AI agent would otherwise have to infer. Each section serves a distinct purpose in guiding behavior while minimizing ambiguity.

Overview: defining your system’s personality

This section sets the tone for your design system. Instead of listing generic values like "clean" or "modern," explain how these values manifest in your product. For example:

• Your system prioritizes clarity over decoration, ensuring every interaction guides the user toward their goal.
• Avoid ambiguity in language, using concise terminology to reduce cognitive load.

This prose helps the agent understand not just what your design values are, but why they exist and how they should influence decisions.

Colors: assigning roles, not just values

Weak prose restates tokens:

Primary color: #1A1C1E
Secondary color: #6C7278

Strong prose defines roles and rules:

Use high-contrast neutrals for primary actions only. The primary color (#1A1C1E) should appear in calls-to-action, while the secondary color (#6C7278) is reserved for supporting text and secondary actions. Avoid decorative use of the primary color—it must always signal importance.

This approach gives the agent a rule it can apply to situations you never anticipated.

Typography: clarifying the purpose of each style

Avoid generic descriptions like "body text" or "heading." Instead, specify:

• Heading 1 is reserved for page titles and should never appear more than once per screen.
• Body text uses the primary font family and maintains a minimum line height to ensure readability.
• Caption is for supplementary information and should never exceed two lines.

By defining the job of each typographic style, you prevent misuse and ensure consistency across AI-generated outputs.

Layout: enforcing grid and spacing rules

Prose in this section should eliminate guesswork about alignment, spacing, and hierarchy. For example:

• All content must align to an 8-pixel grid to maintain visual harmony.
• Spacing between sections should follow the 4-pixel increment rule, starting from 16 pixels.
• Avoid centering text blocks wider than 600 pixels to maintain readability.

These rules provide the agent with clear, non-negotiable constraints.

Do’s and Don’ts: the guardrails of your system

This section is where DESIGN.md delivers its highest value. Each rule directly prevents off-brand output by addressing common pitfalls. For example:

• Do use the accent color for exactly one primary action per screen.
• Don’t mix rounded and sharp corners in the same view.
• Do ensure all interactive elements meet WCAG AA contrast standards (4.5:1 for normal text).
• Don’t use more than two font weights on a single screen.

These directives remove entire categories of potential mistakes, making it easier for AI agents to produce output that aligns with your design identity.

How to measure the effectiveness of your DESIGN.md

A practical test for your prose: Would a designer who has never seen your product be able to apply your design system correctly based solely on your DESIGN.md? If the answer is yes, you’ve struck the right balance between specificity and conciseness.

Focus on writing rules that prevent mistakes, and omit anything that doesn’t serve that goal. Over-explaining can introduce new ambiguities, while under-explaining leaves too much room for interpretation.

Common questions about DESIGN.md

Should color names be descriptive?

Yes. Tie descriptive names to token values to help agents map rationale to values. For example, instead of color01, use primary-action-blue. This ensures the agent understands the purpose behind the token.

Which section is the most critical?

The Do’s and Don’ts section is where the most value is concentrated. It directly addresses the mistakes agents are likely to make, providing clear guardrails that prevent off-brand output.

The bottom line: tokens are just the beginning

Design tokens are the foundation of any modern design system, but they’re not enough to guide AI agents. The real work lies in crafting prose that transforms static values into dynamic rules. Spend your time refining the reasoning behind your design choices—not just listing them.

As AI tools become more integrated into design workflows, the ability to communicate intent clearly will separate functional systems from ineffective ones. Start with a well-structured DESIGN.md, and you’ll empower your agents to deliver consistent, on-brand output every time.