DESIGN.md
DESIGN.md is a Google Labs format specification for describing a visual identity and design system in a structured Markdown file that coding agents can read and apply.
Coding agents can write UI faster than teams can restate brand rules. DESIGN.md matters because it turns colors, typography, components, token schemas, and design intent into persistent context that can travel with a codebase.
The official google-labs-code repository describes DESIGN.md as a format specification for coding agents. The README documents file structure, token schema, token types, section order, component tokens, unknown-content behavior, and links an npm package for tooling around the format.
- Give coding agents repository-local design-system context.
- Represent brand colors, typography, spacing, and component intent in a readable file.
- Reduce repeated design explanations across UI implementation sessions.
- Bridge design-token standards with agent-readable project instructions.
DESIGN.md is not another screenshot or mood board. It is a structured file format intended to give an agent durable design-system context in the repository. The spec covers overview text, colors, token structure, component tokens, and how consumers should handle unknown content.
- File contract: a repository-level design context file for agents and tools.
- Token contract: a schema for colors, typography, spacing, and component-related design facts.
- Consumer contract: guidance for agents or tools that read sections they do not fully understand.
An AI design tool helps create screens, prototypes, or assets. DESIGN.md is closer to an interface contract between design systems and coding agents. It can support AI design tools, but its primary job is to make brand and UI rules readable by implementation agents.
Use the Google Labs repository and npm package for factual claims about the format. Related design-token standards can explain the broader token context, but they should not be treated as claims about Google Labs adoption or implementation behavior.
DESIGN.md is context infrastructure that AI design and coding tools can consume.
A harness can load DESIGN.md as part of the non-model context that shapes implementation.
Agent-readable files should be reviewed as part of the prompt and context supply chain.
DESIGN.md FAQ
Page-level questions for DESIGN.md.
Is DESIGN.md the same as AGENTS.md?+
No. AGENTS.md usually tells coding agents how to work in a project, while DESIGN.md describes visual identity and design-system rules. A UI project may use both: one for workflow and one for design context.
Is DESIGN.md an AI design tool?+
Not by itself. DESIGN.md is a format specification and context file. AI design tools or coding agents may use it to generate more consistent UI, but the file is not the visual editor or generator.
Why should coding agents read design tokens?+
Design tokens turn repeated visual decisions into explicit data. When an agent can read tokens and component intent, it has less reason to invent colors, spacing, typography, or UI patterns that break the product system.