How to Write a DESIGN.md: the Complete Spec Guide

DESIGN.md is a plain-text file that travels with your code. It holds design tokens in YAML frontmatter and design rationale in Markdown prose. This guide covers every section of the @google/design.md 0.3.0 spec: token types, reference syntax, linting rules, and the canonical section order that validators enforce.

Start

DESIGN.md OverviewFormat basics, file structure, frontmatter fields, and canonical section order.

Sections

ColorsHex color tokens, reference syntax, and the WCAG AA contrast-ratio lint rule.TypographyAll seven typography sub-fields: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation.LayoutElevation & DepthShapesComponentsDo's and Don'ts

Reference

DESIGN.md Field Reference

Lint Rules

Lint Rules OverviewFixing broken-ref in DESIGN.mdFixing missing-primary in DESIGN.mdFixing contrast-ratio in DESIGN.mdUnderstanding orphaned-tokens in DESIGN.mdReading token-summary in DESIGN.mdUnderstanding missing-sections in DESIGN.mdFixing missing-typography in DESIGN.mdFixing section-order in DESIGN.mdFixing unknown-key in DESIGN.md

Topics

Design Tokens: The Complete GuideBrand Guidelines and DESIGN.mdAI Coding Agents and DESIGN.md
Upload a DESIGN.md and see your brand guideline rendered instantly.Open the tool