Skip to content
Sign in

BlogMCP & Agents

How to build reusable design context for AI agents

By Attuna · · 3 min read

Reusable design context is the set of files and sources that tells any AI agent how your product should look and feel, without you restating it each session. In practice it has four layers: shared instructions (AGENTS.md or CLAUDE.md), machine-readable tokens (CSS variables, or a format such as DESIGN.md), principles you can state, and visual references. The first two belong in the repository. The last two often don’t, which is why they’re the ones that get lost.

What “reusable” has to mean

  • Across sessions: nothing depends on what was said in chat yesterday.
  • Across agents: Claude Code, Codex and Cursor read the same sources.
  • Across people: a teammate’s agent gets the same direction as yours.
  • Across projects: what belongs to you (taste) is separate from what belongs to one codebase (its rules).

Layer 1: shared instructions

Rules and commands for a codebase belong in an instruction file. AGENTS.md is the most portable choice: Codex creates one with /init, Cursor’s rules docs support it as a simple alternative to .cursor/rules, and Claude Code can read it or import it from a short CLAUDE.md, per its memory documentation.

CLAUDE.md
@AGENTS.md

# Claude Code only
- Use the Chrome integration to screenshot UI changes at 1440 and 390.

What goes in the UI section is covered in CLAUDE.md for UI design; the same content works in AGENTS.md.

Layer 2: tokens

Exact values (colour, type scale, spacing, radius) should exist once, in a form both code and agents can read. For most web projects that’s CSS variables mapped into your styling system; see design tokens for AI coding agents.

A newer option is DESIGN.md, a format from Google Labs “for describing a visual identity to coding agents”. A DESIGN.md file pairs YAML tokens (the normative values) with written rationale, and comes with a CLI that lints the file, diffs versions and exports tokens to formats including Tailwind and W3C DTCG. The project describes the format as alpha, so expect changes.

Terminal
npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md

Whichever you use, keep one source of truth. Tokens in a DESIGN.md that disagree with the CSS are worse than no DESIGN.md.

Layer 3: principles

Principles cover what tokens can’t: how dense, when to use a table, what to avoid. Write them as short prefer and avoid pairs, scoped to the kind of work they apply to. They’re the part of design context most often left in someone’s head. The method is in how to give AI coding agents better design taste.

Layer 4: references

References show what words can’t. They’re also the hardest layer to make reusable: images are large, they belong to many projects at once, and without notes they’re ambiguous. Keep them annotated and organised for retrieval, as described in how to build a design inspiration library, and make them reachable by agents rather than pasted per task.

What goes where

  • Repository: instruction files, tokens, component library, an example page. Versioned with the code.
  • Skills: long reference material and repeatable workflows, loaded only when needed.
  • MCP sources: context that spans projects or doesn’t fit in a repository, such as Figma files and reference libraries.
  • Not in context at all: anything that changes daily, or that an agent can read from the code itself.

For the difference between the last two mechanisms, see MCP vs Agent Skills.

Keep it current

  • Make corrections permanent. When you correct an agent twice, add a rule.
  • Prune. Stale rules and outdated references teach the wrong thing.
  • Check that it loads. In Claude Code, /context lists the memory files in use.
  • Lint what can be linted. Tokens and contrast can be checked automatically; principles need review.

A minimal starting kit

Repository
AGENTS.md              shared rules, commands, precedence
CLAUDE.md              @AGENTS.md plus Claude-specific notes
src/app/globals.css    tokens (or DESIGN.md as the source)
docs/design/principles.md
refs/README.md         annotated references, if they live in the repo

Keeping the layers that don’t fit in a repository

Layers 3 and 4 are what Attuna holds. In Attuna, in private beta, a project carries a brief, rules to prefer and avoid, likes and dislikes, and references and collections, all readable over MCP by Claude Code, Codex, Cursor and other agents that support MCP over HTTP. The repository keeps its tokens and instructions; Attuna’s project context tells agents to keep an existing design system’s conventions, and puts accessibility and function above everything else.

Sources