Brand Guidelines and DESIGN.md

What "brand guidelines" means in practice#

A brand guidelines document is a collection of decisions about how an organization presents itself visually and verbally. In practice these documents vary widely in scope. Some are short style sheets covering fonts and colors. Others run to hundreds of pages and include logo construction rules, photographic direction, tone-of-voice frameworks, and legal trademark guidance.

DESIGN.md targets a specific, narrowly defined slice of that space.

What DESIGN.md captures#

DESIGN.md is precise about what it holds. The frontmatter section contains four token maps:

• colors: semantic color tokens (primary, secondary, tertiary, surface, etc.) as hex values.
• typography: named type scale entries (fontFamily, fontSize, fontWeight, lineHeight, etc.).
• spacing: a named dimension scale for layout rhythm.
• rounded: a named border-radius scale.

Below the frontmatter, the Markdown body adds prose rationale for how and why the tokens apply. This is the part that carries the design intent a number alone cannot convey.

Together, these two layers represent the information a developer or coding agent needs to produce consistent UI: not a complete brand manual, but a complete implementation-ready design system specification.

For a full breakdown of each token type, see Design Tokens: The Complete Guide.

What DESIGN.md does not cover#

Being precise about scope matters here. DESIGN.md does not include:

• Logo files or logo construction rules. There is no image asset mechanism in the format.
• Photography or illustration direction. Visual content guidance lives outside the spec.
• Motion and animation principles. No timing or easing tokens are defined in the current spec (version alpha, 0.3.0).
• Iconography systems. Icon selection and sizing are not part of the token model.
• Tone of voice and verbal identity. Copy and messaging guidelines require a different structure.
• Legal and trademark information. Brand protection language belongs in separate documents.

If your brand guidelines encompass any of these areas, a DESIGN.md sits alongside them, not in place of them. The file answers "how do the UI components look?" not "how does the brand communicate?" or "what may we put on a billboard?"

The traditional brand book vs a DESIGN.md#

A traditional brand book is authored for humans, laid out in PDF, and reviewed periodically. It is authoritative but static: it describes decisions as of the publication date and requires manual effort to update.

A DESIGN.md is:

• Plain text in the repository. It travels with the code, is versioned with git, and is editable in any text editor.
• Machine-readable. The YAML frontmatter is parseable by tools without any proprietary runtime.
• Lintable. Run npx @google/design.md lint DESIGN.md to catch broken token references, missing required keys, and WCAG AA contrast failures at commit time.
• Exportable. The same file produces a Tailwind v4 @theme block or W3C DTCG JSON with a single CLI command.

The result is a design source that stays synchronized with the implementation rather than diverging from it over time.

Where each document type fits#

These are complementary, not competing. Many teams maintain a Figma library as the visual source of truth for designers and a DESIGN.md as the implementation source of truth for developers and agents.

Living brand guidelines and the AI era#

The phrase "living brand guidelines" has been used in design practice to mean documentation that is actively maintained and updated. DESIGN.md gives that concept a concrete implementation mechanism:

When a brand color changes, a developer updates one value in DESIGN.md, runs the linter to confirm no references broke, and commits the change. The token export regenerates. Any agent reading the file in a new session picks up the updated value without a separate briefing.

This is the practical difference between a PDF brand book (update it, re-export, distribute the new version) and a DESIGN.md (update it, commit, done). The file is the distribution channel.

For the AI-specific angle on this, including how coding agents read DESIGN.md at session start, see Brand Guidelines and AI Coding Agents.

Scope in the spec: what the Markdown body can hold#

While the frontmatter is normative (tokens win in any conflict), the Markdown body is expressive. Common sections in the body:

• Overview: A short characterization of the visual identity.
• Colors: How and where to apply each named token. Which surfaces use which colors.
• Typography: Role distinctions between token names. When to use headline-display vs headline-md.
• Layout: Grid decisions, content-width constraints, spacing philosophy.
• Components: Interaction patterns, state conventions, variant naming.
• Do's and Don'ts: Specific guidance on what the design language avoids.

Custom sections (Icons, Accessibility, Voice and Tone) are accepted by the parser and do not trigger errors, even though they are outside the normative token structure.

See the DESIGN.md spec overview for the full section order and accepted section names.

Starting from scratch#

If your team does not yet have a formalized set of design tokens, author a DESIGN.md by hand or use a generator to produce a starting file, then render it in the viewer at /tool to confirm every token resolves. The tool renders an existing file entirely in your browser; nothing is uploaded.

For a step-by-step authoring guide, see How to Write a DESIGN.md. For the tools that create a starting file, see DESIGN.md Tools Compared.

Where to go next#

• Design Tokens: The Complete Guide: the token model, the three-tier architecture, and every token type in detail
• AI Coding Agents and DESIGN.md: how a DESIGN.md serves as persistent design context for coding agents
• How to Write a DESIGN.md: authoring the file from scratch, field by field
• DESIGN.md Overview: structure, frontmatter fields, and the canonical section order

Try it in the tool