Design.md: One Design Standard File for People and Agents

UX CollectivePatrick Neeman

AI summary focused on the core points of the original article.

1. Background and Problems

Limitations of AI agents: when you ask a coding agent to create screens, it uses generic components without brand identity (Material, shadcn, etc.).

Fragmentation of design information : because the brand design system exists only in Figma, presentation slides, or the designer's head, AI cannot read it at build time.
Solution : place a single plain-text file (DESIGN.md) at the root of the code repository that both AI and humans can read, and make it the standard.

2. Two Structures of the DESIGN.md File

Within a single file, it separates and provides the information needed by machines and humans.

Top (YAML tokens - Machine) : standardized numeric values interpreted by the machine. It defines color hex codes, typography scales, spacing, radii, and more.
Bottom (Markdown Prose - Human & Agent Intent) : the design context and intent understood by humans. It describes why specific colors are used, guidelines, and rules to consider when rendering (Do's & Don'ts).
Core principle : if the explanatory body and the token data at the top conflict, the token value takes precedence.

3. Eight Sections That Make It Up

Overview: brand character, target users, emotional tone and manner
Colors: main and secondary color palettes
Typography: settings by typography step (9~15 categories)
Layout: grid model and spacing tokens
Elevation & Depth: visual hierarchy (shadows, borders, etc.)
Shapes: corner radius tokens
Components: detailed styles for each element such as buttons, input fields, and chips
Do’s and Don’ts: guidelines and cautions to follow

4. Practical Use and Management Methods

Role-based naming (Semantic Naming) : you should use names that indicate roles, such as button.primary, rather than names based on appearance like bigRedButton, so they remain usable even when branding changes.
Codebase agreement and version control : place it in the repository root next to README.md and review and record changes through Pull Requests (PRs).
Automation checking and conversion : by using CLI tools provided by Google and others, you can automate WCAG contrast ratio checks (accessibility linting), diff comparisons, Tailwind, and W3C token format conversions.

XPLORED View

This is a good article to look at for how to move a design system from a Figma document to a repository rule that an agent can actually read and apply.

Good situations to read it in

When an AI coding agent repeatedly makes generic UI that differs from the brand
When you want to organize design tokens and intent explanations into a single version-controlled file

Key takeaways

It is practical to separate tokens as rules that machines execute, and the body as context that humans and agents understand
Putting DESIGN.md into the same PR flow as code makes design changes into reviewable product assets

Read original