DESIGN.md vs AGENTS.md — Visual Design and Agent Behavior Are Different Things

Quick Verdict

These are not competitors. DESIGN.md defines how things should look. AGENTS.md defines how the agent should behave. One is the machine-readable design system. The other is the assistant’s code of conduct. Using only one is like hiring a painter who knows how to mix colors but has no idea which wall to paint, or who knows the floor plan perfectly but cannot tell blue from green. Use both.

Comparison Table

Dimension	DESIGN.md	AGENTS.md
Scope	Design system: visual appearance	Agent behavior and workflow
Typical contents	Tokens (colors, type, spacing), components, visual rationale	Conduct rules, available tools, code conventions
Who consumes it	AI agents generating UI/frontend	AI agents doing any task in the repo
When it updates	When the design system changes	When workflow or conventions change
Format	YAML tokens + explanatory Markdown	Pure Markdown (textual instructions)
Without it, the agent…	Generates inconsistent UI, ignores the design system	Ignores project conventions, does things it should not
Industry standard	Google Labs, 24K stars	Anthropic/Claude, adopted by multiple tools
File in repo	`DESIGN.md` (root or /docs)	`AGENTS.md` (root)

DESIGN.md in Detail

Domain: The Visual

DESIGN.md answers questions like:

What is the primary color and when should I use it?
Which font goes in headings vs body?
How much spacing between components?
Do cards get a border or a shadow? What radius?
What is the visual philosophy: minimal? brutalist? playful?

What it contains

# Tokens estruturados
colors:
  brand:
    primary: { value: "#1a1a2e", usage: "CTAs, headers" }
    accent: { value: "#e94560", usage: "Destaques, badges, alertas" }
  semantic:
    success: { value: "#10b981", usage: "Confirmações, status positivo" }
    error: { value: "#ef4444", usage: "Erros, validações" }

typography:
  display: { family: "Cal Sans", weight: 700 }
  body: { family: "Inter", weight: 400 }

spacing:
  unit: "4px"
  scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]

Plus Markdown sections:

## Filosofia Visual

Design minimalista com espaço negativo generoso.
Tipografia como elemento principal de hierarquia.
Cor usada com parcimônia — mostly neutral, accent para chamar atenção.

## Anti-padrões

- Nunca usar gradientes em backgrounds
- Nunca usar mais de 2 font-weights no mesmo componente
- Nunca usar sombras em elementos inline

Impact on agent output

Without DESIGN.md: the agent generates a button with bg-blue-500 text-white rounded-md px-4 py-2. Generic, functional, zero identity.

With DESIGN.md: the agent generates bg-primary text-primary-foreground rounded-lg px-6 py-3 font-display font-semibold. Consistent with the system, identity preserved.

AGENTS.md in Detail

Domain: The Behavior

AGENTS.md answers questions like:

What language should the agent respond in?
Which tools and credentials are available?
What is the repo structure?
What must the agent NEVER do?
How to commit, what message convention?
Which skills or workflows to follow?

What it contains (real example)

# AGENTS.md

## Regra Principal
Interaja em Português Brasileiro.

## Estrutura do Repositório
homelab/
├── .agents/skills/    ← Skills operacionais
├── brain/             ← Vault Obsidian
└── AGENTS.md          ← Este arquivo

## Convenções
- Commits: `docs(<skill>): <descrição>`
- Credenciais: SOPS + age, nunca exibir descriptografado
- Sempre ler SKILL.md antes de executar operação

## Segurança
- NUNCA exibir conteúdo descriptografado
- NUNCA criar repos públicos
- Menor privilégio em tokens

Impact on agent output

Without AGENTS.md: the agent responds in English, commits with a generic message, might expose credentials, does not know where scripts live.

With AGENTS.md: the agent responds in PT-BR, follows commit conventions, protects credentials, knows exactly which skill to consult.

They Are Complementary, Not Competing

The confusion arises because both are “Markdown files at the root that instruct AI agents.” But the overlap is zero:

Question	Who answers
”What color for the CTA button?”	DESIGN.md
”Which branch to commit to?”	AGENTS.md
”What font-family for the heading?”	DESIGN.md
”Run tests before committing?”	AGENTS.md
”How much border-radius on cards?”	DESIGN.md
”What language for documentation?”	AGENTS.md
”Dark mode uses which surface?”	DESIGN.md
”Where are the credentials stored?”	AGENTS.md

The only point of contact

If AGENTS.md says “follow DESIGN.md for visual decisions,” that is perfect. This cross-reference is the ideal pattern. AGENTS.md is the general manual that says “for design, check DESIGN.md.” They are layers.

Anatomy of a Well-Configured Project

meu-projeto/
├── AGENTS.md              ← "Como se comportar neste repo"
│   └── Menciona: "Para UI, siga DESIGN.md"
│
├── DESIGN.md              ← "Como as coisas devem parecer"
│   └── Tokens + rationale visual
│
├── .cursorrules           ← Regras específicas do Cursor (pode duplicar parts de AGENTS.md)
├── CLAUDE.md              ← Regras específicas pro Claude
│
├── src/
├── package.json
└── tailwind.config.js     ← Runtime que implementa os tokens do DESIGN.md

Each file has clear jurisdiction. There is no conflict because there is no domain overlap.

When to Use Which

Create DESIGN.md when:

Your project has UI (frontend, landing page, app, dashboard)
You use AI agents to generate visual components
The design system has custom tokens (not just framework defaults)
You need visual consistency across multiple contributors or agents
You want any agent (Cursor, Claude, Copilot) to generate on-brand UI

Create AGENTS.md when:

Your project uses AI agents for any task (not just UI)
You have code, commit, or branch conventions the agent must follow
You use credentials, external tools, or APIs that need instruction
Multiple agents or tools work on the same repo
You need security and behavioral guardrails

Create both when:

Any project with UI that uses AI agents. That is most projects in 2026.
You want visual AND behavioral consistency
Distributed team where agents do significant work

You do not need DESIGN.md when:

Pure backend project (API, CLI, infrastructure with no UI)
You do not use AI agents to generate frontend
The UI is terminal/text with no visual design

You do not need AGENTS.md when:

Personal project where you are the only operator
You do not use AI agents in any significant way
Conventions are obvious from existing code (rare, but it happens)

Common Mistakes

Mistake 1: Putting design tokens inside AGENTS.md

“AGENTS.md already instructs the agent, so I will put everything there.”

The problem: AGENTS.md becomes enormous, loses focus, and design tokens end up mixed with git rules and security policies. The agent has to parse everything to find a single color. DESIGN.md is focused and optimized for token consumption.

Mistake 2: Putting workflow rules inside DESIGN.md

“I want the agent to always run lint before committing, so I will add it to DESIGN.md.”

The problem: DESIGN.md is about appearance, not process. Workflow rules belong in AGENTS.md. Mixing domains confuses the agent about each file’s scope.

Mistake 3: No cross-reference

Both files exist but neither mentions the other. The agent might ignore DESIGN.md if AGENTS.md never points to it.

Solution: AGENTS.md should contain a line like: “For visual design decisions and tokens, see DESIGN.md.”

Mistake 4: Duplicating information

Copying tokens from DESIGN.md into AGENTS.md “just to be safe.” The result: drift. One version gets updated, the other does not. Single-source-of-truth: each piece of information lives in exactly one place.

FAQ

If I have AGENTS.md, do I still need a separate DESIGN.md?

Yes, if your project has UI. AGENTS.md is generalist. It covers git, security, workflow, language. DESIGN.md is specialist. It covers visual, tokens, components. Keeping them separate means each file stays focused and the agent does not have to parse 2000 lines to find a color token.

Which one should I create first?

AGENTS.md first. It is the general manual the agent reads immediately. Then DESIGN.md for projects with UI. In practice, create both during project setup (takes about an hour total).

Does DESIGN.md work without AGENTS.md?

It works for the visual scope. The agent will generate consistent UI. But it might get workflow wrong (bad commit messages, wrong language, wrong branch). The two together cover the full spectrum.

Can I use one AGENTS.md that points to multiple DESIGN.md files (monorepo)?

Yes. In monorepos, each app or package can have its own DESIGN.md: apps/marketing/DESIGN.md, apps/dashboard/DESIGN.md. The root AGENTS.md tells the agent to check the DESIGN.md for the current context.

Do other tools (Cursor, Windsurf, Copilot) recognize both?

AGENTS.md is natively recognized by Claude Code and is being adopted by other tools. DESIGN.md is recognized by any agent that reads project context, which includes all modern AI coding agents. It does not depend on native support. It is Markdown. Any LLM reads it.

Conclusion

DESIGN.md and AGENTS.md are two halves of an AI-ready project. One without the other works at half capacity.

DESIGN.md alone: beautiful UI, but the agent commits wrong, responds in the wrong language, exposes credentials.

AGENTS.md alone: well-behaved agent, but inconsistent UI with no visual identity.

Both together: an agent that behaves correctly AND generates on-brand UI. That is the minimum for a professional project in 2026.

The “which one should I use?” confusion reveals a misunderstanding about scope. It is not one or the other. The combination is what turns the agent from a glorified autocomplete into a colleague who actually knows the project. designmd.app catalogs 461 design systems in DESIGN.md format, and most of the well-configured projects have a neighboring AGENTS.md in the same root.