Where to Find the Official DESIGN.md Format Specification

The official DESIGN.md format specification is defined by Google's Stitch DESIGN.md specification, available at stitch.withgoogle.com/docs/design-md/specification/.

The VoltAgent/awesome-design-md repository collects production-ready examples of design system documentation. If you are implementing or validating a design system document, you need the authoritative DESIGN.md format specification that governs file structure, metadata schemas, and token definitions.

Official Specification Location

The canonical source for the DESIGN.md format specification resides in Google's Stitch documentation. According to the repository's README.md at line 96, every document in the collection explicitly follows the Stitch DESIGN.md format. This specification establishes the machine-readable schema for documenting design tokens, color palettes, typography scales, and component libraries in markdown.

Repository Structure and Examples

The VoltAgent/awesome-design-md repository demonstrates practical applications of the specification through validated implementations. Key reference files include:

• README.md: Contains the definitive reference link to the official spec at line 96, confirming the repository adheres to the Stitch standard.
• design-md/meta/DESIGN.md: A complete reference implementation showing how to structure design system metadata according to the spec.
• design-md/figma/DESIGN.md: An example integration demonstrating how Figma-specific design tokens map to the standard format.

These files serve as concrete validation references when authoring your own design documentation.

DESIGN.md Structure and Syntax

Based on the Stitch specification, a valid DESIGN.md file combines YAML frontmatter with structured markdown tables. The format expects specific sections for colors, typography, spacing, and components.

Example YAML frontmatter:

---
version: 1.0

# Reference: https://stitch.withgoogle.com/docs/design-md/specification/

---

Example color table structure:

## Colors

| Name       | Hex     | Role          |
|------------|---------|---------------|
| primary    | #0064E0 | Brand accent  |
| on-primary | #FFFFFF | Text on primary |

Summary

• The official DESIGN.md format specification is maintained by Google as the Stitch DESIGN.md specification.
• The VoltAgent/awesome-design-md repository explicitly references this spec in README.md at line 96.
• Valid files use YAML frontmatter followed by structured markdown tables for design tokens.
• Reference implementations are available in design-md/meta/DESIGN.md and design-md/figma/DESIGN.md.

Frequently Asked Questions

What is the official DESIGN.md format specification?

The official specification is Google's Stitch DESIGN.md format, which defines a standardized markdown structure for documenting design systems, including color palettes, typography scales, and component specifications.

Where is the DESIGN.md specification documented?

The specification is officially hosted at https://stitch.withgoogle.com/docs/design-md/specification/. The VoltAgent/awesome-design-md repository links to this URL in its README.md file to confirm compliance.

How do I validate my DESIGN.md file against the official spec?

Compare your file structure against the reference implementations in design-md/meta/DESIGN.md and design-md/figma/DESIGN.md within the repository. These files demonstrate the correct YAML frontmatter syntax and table structures required by the Stitch specification.

Does the DESIGN.md format require specific frontmatter?

Yes, the format typically includes YAML frontmatter at the top of the file for metadata such as version numbers, followed by standardized markdown sections for design tokens and components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}