DESIGN.md in 2026: How to Describe a Design System for AI Agents

Current as of August 21, 2026. In April 2026, Google Labs published the open DESIGN.md specification for describing visual systems to coding agents. The current CLI version is 0.4.0, released July 27, 2026, while the format itself still has alpha status. It is a formal specification, but not a W3C Standard or a universally loaded instruction file.

The problem is not “memory,” but sources

The claim that “every AI session starts from scratch” is no longer accurate. Claude Code can load CLAUDE.md and maintain auto memory; Cursor applies project rules and AGENTS.md. But memory and instructions remain context, not enforced configuration.

The main problem is different: an agent is often given a design and a repository without being told what constitutes the source of truth. It then chooses a plausible HEX value, creates a new component instead of using an existing one, or copies a value from outdated documentation.

The purpose of agent-facing documentation is not to rewrite the entire design system in Markdown, but to provide a concise map:

where tokens live and how they are built;
which components are approved for use;
where to find APIs, examples, and states;
what must not be hardcoded;
which checks validate the result.

What DESIGN.md is in 2026

Google Labs’ DESIGN.md combines two layers:

YAML frontmatter containing normative machine-readable tokens;
Markdown explaining the visual intent, usage rules, and permitted exceptions.

---
version: alpha
name: Product UI
colors:
  text: "#212223"
  background: "#fdfdfc"
spacing:
  sm: 8px
  md: 16px
---

## Overview
A calm product interface with high information density.

## Do's and Don'ts
- Use semantic colors
- Do not add decorative gradients to task-oriented flows

The @google/design.md CLI can validate structure, compare versions, print the specification, and export tokens, including in DTCG and Tailwind formats. Because the schema and CLI are evolving rapidly, pin the package version and expect breaking changes.

The mere presence of DESIGN.md does not mean Cursor, Claude Code, or another agent will read it automatically. Add an explicit reference from a supported entry point: AGENTS.md, CLAUDE.md, or .cursor/rules/*.mdc.

Four layers instead of one large file

1. A machine-readable source of truth

Tokens should live in a structured format from which platform-specific artifacts are generated. In October 2025, the Design Tokens Community Group released the first stable DTCG 2025.10 specification. It defines an exchange format, value types, aliases, groups, and a resolver.

It is a stable Community Group Report suitable for production, but not a W3C Standard or part of the Standards Track. Support in any particular tool still needs to be verified.

{
  "color": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.13, 0.13, 0.14],
          "alpha": 1
        }
      }
    }
  }
}

Markdown should not duplicate every value from this file. Doing so creates two sources of truth that will inevitably diverge.

2. DESIGN.md for visual intent

Use DESIGN.md for normative visual tokens and concise rationale: the product’s character, composition principles, typography, color, and key do’s and don’ts. Do not turn it into a copy of the entire component documentation.

3. Component and pattern documentation

Token names do not explain intent. Usage rules are needed: when to apply a semantic token, which states are required, when to choose a Dialog instead of an inline message, and how a component behaves on a narrow screen.

This documentation can live in Storybook, a documentation site, component comments, or separate Markdown files. What matters is that the agent entry point links to the current sections instead of copying them wholesale.

4. Agent-specific instructions

For Cursor, use:

AGENTS.md — plain Markdown in the repository root or subdirectories;
.cursor/rules/*.mdc — rules with a description, globs, and an application mode.

A regular .cursor/rules/design-system.md file is ignored by the rules system: the extension must be .mdc. In Claude Code, project instructions live in ./CLAUDE.md or ./.claude/CLAUDE.md. Cursor CLI also reads root-level AGENTS.md and CLAUDE.md, but do not rely on incidental overlap between formats—document the team’s primary path.

A minimal AGENTS.md for UI work

# Design system

## Sources of truth
- Tokens: packages/tokens/src/tokens.json
- Components: packages/ui/src
- Examples: apps/storybook
- Accessibility tests: packages/ui/tests/a11y

## Rules
- Reuse an existing component before creating a new one
- Use semantic tokens; do not add raw colors or spacing values
- Preserve keyboard navigation, focus states and ARIA semantics
- Do not copy generated CSS from Figma into production

## Validation
- pnpm lint
- pnpm test
- pnpm test:a11y
- pnpm build

This is a repository map with clear constraints. A list of hundreds of HEX values, dimensions, and variants would only weaken the signal.

When Cursor Project Rules are needed

If different parts of a monorepo use different systems, it is better to limit the rule with a glob pattern:

---
description: UI implementation rules for the web app
globs:
  - "apps/web/src/**/*.{ts,tsx,css}"
alwaysApply: false
---

- Import components from @company/ui
- Use semantic tokens from @company/tokens
- Check responsive states at 360, 768 and 1440 px
- Run pnpm --filter web test before handoff

A narrowly scoped rule is more useful than a global manifesto: the agent receives only the relevant context.

Describe components through decisions, not screenshots

For each complex component, document its contract rather than its entire visual appearance:

Purpose: the problem the component solves.
When not to use it: the closest alternatives.
API: props, slots/children, controlled state.
States: loading, empty, error, disabled, focus.
Content: length constraints, localization, and number and date formats.
Accessibility: role, name, keyboard interaction, focus management.
Responsive behavior: what changes and what remains invariant.

## Dialog

Use for a short blocking decision or focused task.
Do not use for long multi-step forms; use a page or drawer.

Required:
- accessible name
- focus moves inside on open
- Escape closes when dismissal is allowed
- focus returns to the trigger

Composition:
- DialogHeader
- DialogBody
- DialogFooter

Figma and Code Connect

Figma MCP provides the agent with design structure, variables, and components. Code Connect adds a curated link to the actual implementation. This is more useful than manually listing every prop in Markdown.

But that connection does not replace documentation. Code Connect answers “which component should be used, and what does its code example look like?” Rules should answer “when is this component appropriate?” and “how should the result be validated?”

As of August 17, 2026, Figma no longer updates framework-specific Code Connect parsers. For new mappings, use framework-agnostic .figma.ts template files; legacy parser-based integrations should be migrated with npx figma connect migrate.

Checks matter more than promises

Instructions help an agent make the right decision, but they do not guarantee compliance. Automate the checks that can be automated:

linting for prohibited raw values and imports;
type-checking the public component API;
unit and interaction tests;
accessibility checks;
visual regression tests for key states;
building token outputs from a single source file;
checking documentation for broken links and outdated snippets.

There is no universal “audit script” that can automatically select the correct token for every hardcoded value. Such checks depend on the project’s token structure and rules. Do not equate the absence of regex matches with interface quality.

How to avoid creating a second source of truth

Keep values in a structured token source, preferably one compatible with DTCG.
Generate CSS, iOS, Android, and other outputs automatically.
Keep the component API close to the code and validate it with tests.
Keep only links, constraints, and validation commands in agent instructions.
Update documentation and implementation in the same pull request.
Remove outdated rules: concise, current context is better than a long archive.

What counts as a successful result

A good agent-facing specification does not promise an identical result in every session. It makes deviations visible and inexpensive: the agent finds the right component, uses semantic tokens, runs checks, and leaves a reviewable diff.

DESIGN.md is a useful open alpha specification for visual context, but it is not a replacement for DTCG, component documentation, or agent-specific rules. Infrastructure begins when a source of truth is designated, formats are explicitly connected, and automated validation works.