DESIGN.md YAML Front Matter Schema: Complete Specification for Design Tokens

The DESIGN.md YAML front matter schema requires a strict structure starting and ending with --- delimiters, containing required fields like name and optional categories including colors, typography, rounded, spacing, and components.

The google-labs-code/design.md repository defines a machine-readable specification for declaring design systems. Understanding the exact schema for DESIGN.md YAML front matter is essential for properly configuring design tokens that tools can parse and validate.

Required and Optional Top-Level Fields

The front matter block must reside at the very top of every DESIGN.md file, enclosed between lines containing only three hyphens.

Core Metadata

Three fields govern the document identity:

• name (required) – A human-readable string identifying the design system.
• version (optional) – A string identifier for the spec version, such as "alpha".
• description (optional) – Free-form text describing the design system's purpose.

Design Token Categories

Four primary categories store visual design values:

• colors – Maps token names to Color values (hex codes, named colors, or CSS functional notation).
• typography – Maps token names to Typography objects containing fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing.
• rounded – Defines corner-radius tokens as Dimension values (e.g., 4px, 0.25rem).
• spacing – Defines spatial tokens accepting either Dimension strings or bare numbers.

Component-Specific Tokens

The components section accepts a nested map where each component name contains its own token definitions. Values may be literal strings or token references using the {path.to.token} syntax.

Token Types and Value Formats

According to the specification in docs/spec.md (lines 43-58), each category accepts specific data types:

Color values accept any CSS-compatible color string.

Dimension values for rounded must include units (px, em, rem), while spacing dimensions may alternatively be bare numbers.

Typography objects require structured fields:

typography:
  <token-name>:
    fontFamily: <string>
    fontSize: <dimension>
    fontWeight: <number>
    lineHeight: <number>
    letterSpacing: <dimension>

Token References in the components section use curly-brace notation to inherit values from other sections:

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    rounded: "{rounded.md}"

Practical Implementation Examples

Minimal Valid Configuration

A DESIGN.md file requires only the name field and at least one design token category:

---
name: Sunset Theme
colors:
  primary: "#FF5722"
  secondary: "navy"
typography:
  body:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0em
rounded:
  sm: 4px
spacing:
  base: 16px
  xs: 4px
---

Complete Configuration with Component Tokens

The following example from the repository specification demonstrates all optional fields including version, description, and component references:

---
version: alpha
name: Daylight Prestige
description: A high-contrast, modern UI theme.
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  md: 8px
spacing:
  base: 16px
  sm: 8px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.neutral}"
    rounded: "{rounded.md}"
    padding: 12px
---

Schema Validation and Reference Files

The authoritative schema definition resides in docs/spec.md at lines 43-58, which governs how parsers validate DESIGN.md files.

Real-world implementation examples include:

• examples/totality-festival/DESIGN.md – Demonstrates basic token definitions.
• examples/paws-and-paths/DESIGN.md – Shows advanced usage with optional fields and complex component sections.

Summary

• The DESIGN.md YAML front matter schema mandates --- delimiters at the document's top with strict indentation rules.
• Only name is required; version, description, and all token categories are optional.
• colors accepts CSS-compatible values, typography requires structured objects, and rounded/**spacing** accept dimensions.
• components supports token inheritance via {path.to.token} reference syntax.
• The official specification lives in docs/spec.md, with working examples in the examples/ directory.

Frequently Asked Questions

What is the required structure for DESIGN.md YAML front matter?

The structure must begin and end with a line containing only three hyphens (---). Inside this block, only the name field is mandatory. All other fields—including version, description, colors, typography, rounded, spacing, and components—are optional but must follow the type definitions specified in docs/spec.md when present.

How do I reference other tokens in component definitions?

Use curly-brace notation with dot-notation paths: {section.token-name}. For example, to reference a primary color in a button component, write backgroundColor: "{colors.primary}". This syntax allows components to inherit values defined in the global token categories.

What file defines the official schema specification?

The complete schema definition, including validation rules for Color, Dimension, Typography, and token references, is documented in docs/spec.md at lines 43-58. This file serves as the canonical reference for implementers building parsers for the DESIGN.md format.

Can spacing values be bare numbers or must they include units?

The spacing category accepts either Dimension values (strings with units like px, em, or rem) or bare numbers. In contrast, the rounded category strictly requires Dimension values with units. This distinction is enforced by the validation logic described in the repository specification.

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