Skip to content
.mdDesign.md Store

Docs / Reference

Changelog

The DESIGN.md format specification and CLI changelog. The format is at alpha status — breaking changes may occur between minor versions until a stable 1.0 is declared.

Alpha notice. The DESIGN.md format is published by Google Labs under the Apache 2.0 license. During the alpha period, field names, lint rules, and CLI flags may change without a major version bump. Pin the CLI version in your project to avoid unexpected breakage.

April 2026 — Open-sourced by Google Labs

The DESIGN.md format specification and the @google/design.md CLI were open-sourced on GitHub under the Apache 2.0 license. Prior to this, the format was used internally within Google Stitch and was not publicly documented.

  • Format spec published at github.com/google-labs-code/design.md
  • CLI (@google/design.md) published to npm with lint, diff, export, and spec commands
  • Export targets: W3C DTCG (tokens.json) and Tailwind CSS (tailwind.tokens.js)
  • WCAG AA contrast checking added to the linter (7 rules total)
  • Apache 2.0 license — free to use, fork, and build on commercially

Pre-release — Google Stitch (2024–2026)

The DESIGN.md format was developed internally at Google Labs as part of Google Stitch, an AI-assisted design tool. Stitch used the format as the interchange layer between visual design sessions and code generation. The pre-release format was not publicly versioned or documented.

Key milestones in the pre-release period:

  • YAML front matter + markdown body structure established as the core two-layer format
  • Token reference syntax ({namespace.key}) introduced for DRY component definitions
  • Eight standard markdown sections defined (Overview, Colors, Typography, Spacing, Components, Do’s and Don’ts, Accessibility, Motion)
  • Native DESIGN.md generation and export added to the Stitch UI

What’s next

The format specification is under active development. Areas under consideration for future releases include:

  • Dark-mode token support at the format level (currently handled in prose)
  • Component state tokens (hover, focus, active, disabled)
  • JSON Schema for editor validation and autocomplete
  • Stable 1.0 declaration with a stability guarantee

Follow the GitHub repository for announcements and to participate in the RFC process for new format features.

REST API