Where to Find the Formal Specification for the DESIGN.md Format

The formal specification for the DESIGN.md format is located at docs/spec.md in the google-labs-code/design.md repository, defining the YAML front-matter schema, required markdown section hierarchy, and design token reference syntax.

The DESIGN.md format standardizes how design systems document tokens, components, and guidelines in human-readable markdown. If you are building tools that parse these files or authoring design system documentation, you need the authoritative schema that governs structure and validation. This guide identifies the exact location of the formal specification for the DESIGN.md format and details what it covers.

Location of the DESIGN.md Formal Specification

The canonical specification lives at docs/spec.md in the root of the repository. This document serves as the single source of truth for all DESIGN.md implementations, detailing the mandatory structure and parsing rules that compliant tools must enforce.

According to the google-labs-code/design.md source code, the specification defines:

• YAML front-matter schema – Valid keys, value types, and delimiters
• Section ordering rules – Mandatory sequence of markdown headings
• Token syntax – Reference patterns and validation logic
• Consumer behavior – How parsers handle unknown content, duplicates, and invalid values

Core Components Defined in the Specification

YAML Front-Matter Schema

The specification mandates an optional YAML block delimited by --- at the start of the file. This block declares design tokens including colors, typography, spacing, and component properties.

The schema supports typed tokens such as:

• Color – Hex, RGB, or HSL values
• Dimension – Pixels, rems, or ems for spacing and sizing
• Typography – Font family, size, weight, line height, and letter spacing

Token values can reference other tokens using the syntax {path.to.token}, enabling systematic aliasing and theming.

Required Section Hierarchy

DESIGN.md files must follow a strict heading order as defined in docs/spec.md:

1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

The specification details how parsers should treat unknown sections and enforce this sequence when validating files.

Component Token Structure

For component definitions, the spec outlines how to define variants and property token types. Components reference design tokens using the {namespace.token} syntax, allowing buttons, inputs, and other UI elements to inherit values from the global token system.

Practical Examples from the Specification

Front-Matter Implementation

The following YAML block demonstrates the required structure for declaring tokens:

---
version: alpha
name: Example System
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  sm: 4px
spacing:
  base: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.secondary}"
    rounded: "{rounded.sm}"
    padding: 12px
---

Markdown Body Structure

The markdown content must follow the required section order:

## Overview

The system conveys a modern, high-contrast brand identity focused on legibility and trust.

## Colors

- **Primary (#1A1C1E):** Core text and interactive elements.
- **Secondary (#6C7278):** Supporting UI components and borders.

## Typography

- **Headlines:** Public Sans Semi-Bold, 48 px.
- **Body:** Public Sans Regular, 16 px.

## Layout

A fluid grid with an 8 px spacing scale.

## Elevation & Depth

Uses tonal layers instead of heavy shadows.

## Shapes

All components use a 4 px corner radius.

## Components

Buttons, chips, lists, and inputs are defined with token references.

## Do's and Don'ts

- **Do** maintain WCAG AA contrast ratios.
- **Don't** mix rounded and sharp corners on the same screen.

These snippets obey the schema and section ordering defined in docs/spec.md, making them compatible with any tool implementing the DESIGN.md consumer logic.

Reference Files and Implementation Resources

Beyond the primary specification, the repository contains several authoritative resources:

• docs/spec.md – The full formal specification containing normative definitions of tokens, sections, and parsing rules
• README.md – General repository overview and quick start guide
• examples/totality-festival/DESIGN.md – Real-world implementation demonstrating complete front-matter and section compliance
• examples/paws-and-paths/DESIGN.md – Additional practical example showing variant component definitions
• packages/cli/src/linter/fixtures/DESIGN-test.md – Test fixture used by the CLI linter to validate specification compliance and edge cases

Summary

• The formal specification for the DESIGN.md format is located at docs/spec.md in the google-labs-code/design.md repository
• It defines the YAML front-matter schema for design tokens and the mandatory markdown section hierarchy
• Token references use {path.to.token} syntax with specific validation rules for resolution
• Required sections follow the strict order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts
• Example implementations in examples/totality-festival/DESIGN.md and the CLI test fixture demonstrate compliant file structures

Frequently Asked Questions

What file contains the official DESIGN.md specification?

The official specification is located at docs/spec.md in the main branch of the google-labs-code/design.md repository. This document contains the normative definition of the format's schema, parsing rules, and validation requirements for both authors and tool builders.

What is the required section order in a DESIGN.md file?

According to the specification, sections must appear in this exact sequence: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts. Parsers must handle unknown sections gracefully while enforcing this hierarchy for standard sections to ensure consistent document structure.

How do I reference design tokens in DESIGN.md front-matter?

Use the token reference syntax {path.to.token} within YAML values. For example, backgroundColor: "{colors.primary}" references the primary color token defined elsewhere in the front-matter. The specification in docs/spec.md details validation rules ensuring these references resolve to valid token definitions.

Are there example files that follow the DESIGN.md specification?

Yes, the repository includes compliant examples such as examples/totality-festival/DESIGN.md and examples/paws-and-paths/DESIGN.md. Additionally, the CLI linter uses packages/cli/src/linter/fixtures/DESIGN-test.md as a reference fixture for validating specification compliance and testing parser behavior.

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