How to Build an AI Design System With DESIGN.md and CLAUDE.md

Stop re-explaining your brand's colors, spacing, and component rules in every prompt. Learn how to write a DESIGN.md file that gives AI coding agents durable visual rules to follow.

Quick Answer

DESIGN.md is a Markdown file that captures a project’s visual design rules, colors, typography, spacing, components, layout conventions, so an AI coding or design agent can follow them automatically instead of you re-explaining your brand every session. Paired with CLAUDE.md for general project instructions, it turns one-off design corrections into a standing system the agent actually reads.

Why One-Off Design Prompts Fail

Picture asking an AI coding agent to “build a pricing page that matches our brand.” It has no idea what your brand actually looks like beyond whatever it can infer from the rest of the codebase, so it guesses: a plausible-looking blue, a reasonable font pairing, spacing that seems fine in isolation. Sometimes it’s close. Often it drifts, a slightly different shade of blue than your logo, a button style that doesn’t match the one three pages over, spacing that doesn’t line up with your existing grid.

Multiply that across dozens of prompts and pages, and a product built with AI assistance starts to look like it was designed by several different people with slightly different taste, because in a sense, it was, a different guess every session. The fix isn’t better individual prompts. It’s writing the rules down once, in a place the agent reads automatically.

What DESIGN.md Is

DESIGN.md is the visual counterpart to CLAUDE.md. Where CLAUDE.md typically holds your tech stack, build commands, and general coding standards, DESIGN.md holds the specific, checkable visual rules: what colors exist and what each is for, what fonts and sizes to use, how spacing scales, what a button, card, or form field should look like, and what “on-brand” concretely means for your project.

The reason to separate it from CLAUDE.md isn’t strict, some teams keep everything in one file. But once your visual rules grow past a few lines, a dedicated DESIGN.md keeps CLAUDE.md focused on project mechanics while giving design rules a clear, referenceable home.

What Belongs in DESIGN.md

Color system. Your actual palette, ideally as named tokens rather than raw values, background, text, primary, danger, and what each is for. An LLM-safe design system goes a step further and uses intent-based design tokens, naming colors by purpose (background-card) rather than value (gray-100), so an agent picks the right one by reading the name.

Typography. Font families, the size scale, and when to use each weight or size, not just “we use Inter.”

Spacing. Your spacing scale and the rule for applying it consistently, so an agent isn’t inventing arbitrary padding values per component.

Layout rules. How content areas are structured, grid conventions, and page-level patterns that should stay consistent.

Buttons, cards, and forms. Concrete patterns for your most-reused components, including what states look like (hover, disabled, error).

Visual hierarchy. How importance is communicated, size, weight, color, position, so new pages read consistently with existing ones.

Responsive behavior. How layouts should adapt, and any breakpoints that matter.

Accessibility. Contrast requirements, focus states, and any rules that shouldn’t be silently dropped for the sake of a “cleaner” look.

Image style. What kind of imagery fits the brand, and what to avoid.

Motion and animation. If your product uses animation, the rules for when and how, restraint included.

Good and bad examples. Concrete before/after or right/wrong examples are often more effective than abstract rules. Showing an agent what “off-brand” looks like next to what’s correct teaches faster than a paragraph of description.

Reusable Components and Templates

Where possible, point DESIGN.md at your actual reusable components rather than re-describing them in prose. If you have a component library, reference it directly: “always use the <Button> component with its defined variants, never build a custom button from scratch.” Templates for common page types work the same way, give the agent a real starting pattern to extend rather than a blank page and a description.

What Belongs in CLAUDE.md Instead

Keep general project mechanics in CLAUDE.md: the tech stack, build and test commands, file structure, and non-visual coding standards. Reference DESIGN.md from CLAUDE.md so an agent working on anything visual knows to check it: a line like “For any UI or styling work, read DESIGN.md first and follow its rules exactly” is often enough to make the connection reliable. This mirrors the same pattern covered in How to Set Up CLAUDE.md, SKILL.md, and PITFALLS.md, applied specifically to visual work.

Turning Corrections Into Standing Rules

The most useful DESIGN.md files aren’t written in one sitting, they grow from real corrections. When you catch an agent using an off-brand color, don’t just fix that one instance, add the rule to DESIGN.md so it doesn’t happen again: “never use a raw hex value, only tokens defined in the palette.” Treat every repeated correction as a signal that a rule is missing, not just a one-off mistake to fix and forget.

Versioning the Design System

As your brand or component library evolves, DESIGN.md should evolve with it. Update it when real design decisions change, not preemptively, and keep old, contradicted rules out rather than leaving stale guidance for an agent to follow by mistake. If your project uses version control, DESIGN.md changing is itself a useful signal of when and why the visual system shifted.

Using It Beyond Websites

The same approach works for slide decks, marketing one-pagers, internal admin tools, or any AI-generated visual output where consistency matters. The file’s job is the same regardless of medium: give the agent concrete, checkable rules instead of a vague adjective like “modern” or “clean.”

Example Folder Structure

project/
  CLAUDE.md          # general project instructions, references DESIGN.md
  DESIGN.md          # visual design rules
  src/
    components/      # the reusable components DESIGN.md points to
    styles/
      tokens.css      # the actual design tokens DESIGN.md documents

A Starter DESIGN.md Template

# Design System

## Colors
Use only tokens from tokens.css. Never use raw hex values.
- background-page, background-card, text-primary, text-muted, border, primary, danger

## Typography
- Headings: [font], weights [x/y/z]
- Body: [font], base size [Npx], line-height [N]

## Spacing
Use the spacing scale only: 4, 8, 16, 24, 32, 48, 64px. No arbitrary values.

## Components
Always use existing components from src/components. Do not build one-off
buttons, cards, or form fields from raw HTML/CSS.

## Good vs Bad
Good: [screenshot or description of an on-brand example]
Bad: [screenshot or description of a common mistake to avoid]

Starter CLAUDE.md Reference Line

For any UI, styling, or visual work, read DESIGN.md first and follow its
rules exactly. Do not invent new colors, spacing values, or component
patterns outside what DESIGN.md and the existing component library define.

Common Mistakes

Writing an exhaustive design system before any real inconsistency has shown up, which produces a long file nobody, human or agent, actually reads closely. Describing rules with vague adjectives (“modern,” “clean,” “professional”) instead of checkable specifics. Never updating the file after catching a repeated mistake, so the same correction has to be made over and over. And treating DESIGN.md as a replacement for reviewing AI-generated UI, rather than a tool that reduces, but doesn’t eliminate, the need for a human look before shipping.

Final Takeaway

A design system built for AI agents doesn’t need to be more elaborate than a human-facing one, it needs to be more explicit and more checkable. Write down your actual colors, type, spacing, and component rules once, reference the file from CLAUDE.md, and turn every real correction into a standing rule instead of a one-time fix. The payoff is the same one CLAUDE.md gives you for code: you stop being the memory of the project, and the agent starts behaving like it already knows your brand.