Skip to content

Search design systems

Search for a design system by domain or name

Back
·11 min read

The DESIGN.md Specification: A Complete Reference

By DesignMD Team

Goals of the specification

The DESIGN.md file exists to standardize visual identity for AI coding agents. To achieve this, the specification enforces three core principles.

First, it must be portable, contained entirely within a single file, and native to the repository. Engineers should not need to configure complex plugins or maintain external cloud accounts to use it. Second, the file must remain machine-readable while maintaining human readability. A developer should be able to open the file and understand the brand identity at a glance, while an AI agent parses the exact same file to extract precise token values.

Finally, the specification ensures the file is AI-agent friendly. Large Language Models operate within context window constraints. A raw CSS file often exceeds these limits or dilutes the context with vendor prefixes and browser-specific hacks. The specification guarantees that a DESIGN.md file is compact enough to fit comfortably in context while remaining structured enough to parse accurately. To understand the foundational philosophy behind this approach, review what DESIGN.md is.

File structure at a glance

A compliant DESIGN.md file strictly separates token definitions from narrative context.

The file begins with a required YAML frontmatter block. This section houses the exact values for all design variables. The YAML structure ensures that automated extraction tools, linters, and AI agents can reliably map keys to values without attempting to parse natural language. For a less technical breakdown of these blocks, read how the design.md file format is explained.

Below the frontmatter sits the markdown body. The body provides structural guidance, component examples, and rules for applying the tokens defined above. While agents primarily read the YAML for exact values, they rely on the markdown body to understand the spatial relationships and interaction states. You can explore a variety of compliant examples in our gallery.

Frontmatter fields

The frontmatter enforces a specific schema. The version field currently tracks the specification maturity (e.g., "alpha"). The name field identifies the design system.

The colors block is mandatory. It requires definitions for primary, secondary, accent, background, surface, textPrimary, and textSecondary. Values must be exact hex codes.

yaml
---
version: "alpha"
name: "Acme Corp"
colors:
  primary: "#1A56DB"
  background: "#F9FAFB"
typography:
  fontFamily: "Inter, sans-serif"
  fontSize: "16px"
---

The typography block dictates fontFamily, fontSize, fontWeight, and lineHeight. Additional required blocks include spacing, radius, and shadows. Each block serves as an explicit dictionary for the agent.

Body sections

The specification recommends a strict order for the markdown body sections to optimize the AI's reading hierarchy.

The document opens with an Overview, setting the semantic tone. It then steps through Colors, Typography, Spacing, Shadows and Elevation, and Border Radius. This sequence mirrors the cascading nature of CSS, moving from foundational variables to specific structural constraints.

The Components section follows, detailing how the foundational tokens combine into UI elements. A Do's and Don'ts section provides explicit boundaries to prevent AI hallucinations. Finally, an optional Dark Mode block outlines token overrides for inverted themes. Note that automated dark mode token extraction is currently a Beta roadmap feature.

Token reference syntax

Within the markdown body, developers must reference the YAML tokens using a specific curly-brace dot-notation.

If a paragraph describes the background color of a card, it must state: The card uses the {colors.surface} value. This explicit syntax prevents the agent from guessing. It instructs the language model to perform a direct lookup against the YAML dictionary.

Resolution rules govern how an agent dereferences these tokens. If the agent encounters {spacing.md}, it immediately resolves it to the value defined in the frontmatter, typically a pixel or rem value. The specification restricts these references to string-based lookups and provides strict fallbacks if a value is missing.

Components block

The Components block defines the composition of complex UI elements. Instead of leaving interpretation up to the agent, the specification requires explicit property mapping.

Each component definition must outline the required style, variant, and state props. For example, a primary button definition must list its default style, its hover state, and its disabled variant.

markdown
## Components

### Primary Button
- style: { backgroundColor: colors.primary, textColor: colors.surface }
- state (hover): { backgroundColor: colors.secondary }

A compliant file includes definitions for at least a primary button, secondary button, card, and text link. Agents use these core definitions as a baseline to extrapolate styles for unlisted components.

Lint rules

Every DESIGN.md file must pass a linting process to ensure structural integrity.

Errors trigger when the linter detects broken token references (e.g., calling {colors.brand} when brand does not exist in the YAML) or when required color fields are entirely missing. Errors halt automated workflows and require manual intervention or auto-correction scripts. You can learn more about how tools handle extraction failures and validation states by reading about confidence scores and design extraction.

Warnings indicate low-confidence values or missing optional blocks, such as omitting the dark mode rules. Auto-correction behaviors, a planned V1+ feature, will automatically repair broken token references by mapping them to the closest available hex code in the frontmatter.

Versioning

The specification relies on strict versioning semantics.

The current "alpha" designation indicates that while the core schema is stable, additional top-level keys may be introduced. Beta semantics will freeze the schema, allowing tooling authors to build parsers with complete confidence. Compatibility guarantees ensure that any file extracted today will remain valid and parsable in future versions of the specification.

Frequently asked questions

Is the YAML frontmatter required?

Yes, the specification mandates the YAML frontmatter block for all token definitions to ensure reliable machine parsing.

How does the linting process handle missing tokens?

Currently, missing required tokens trigger an error. Future V1+ auto-correction features will attempt to resolve these automatically.

Can I add custom blocks to the frontmatter?

You can add custom keys, but AI agents are optimized to look for the standardized colors, typography, spacing, radius, and shadows dictionaries.

Get Started

Validate your DESIGN.md file in seconds — paste a URL or upload an existing file. Head to the designmd.run homepage to begin.