---
name: DESIGN.md Specification
slug: design-md-spec
url: "https://dontmakeitugly.com/resources/design-md-spec"
website: "https://github.com/google-labs-code/design.md"
github: "https://github.com/google-labs-code/design.md"
docs: "https://stitch.withgoogle.com/docs/design-md/specification"
npm: "https://www.npmjs.com/package/@google/design.md"
type: documentation
categories:
  - agent-resources
  - design-systems
tags:
  - design-md
  - specification
  - google-labs
  - design-tokens
  - linter
  - accessibility
  - open-source
  - markdown
frameworks:
  - agnostic
pricing: free
license: Apache-2.0
openSource: true
agentFriendly: excellent
agentAccessMethods:
  - github
  - documentation
  - npm
  - cli
  - copy_paste
installCommand: "npx @google/design.md lint DESIGN.md"
difficulty: beginner
staffPick: true
dateAdded: "2026-09-04"
lastVerified: "2026-09-04"
---

# DESIGN.md Specification

Google Labs' open format for describing a visual identity to a coding agent.

- Type: Documentation
- Categories: Agent Resources, Design Systems
- Pricing: Free · License: Apache-2.0
- Open source: yes
- Works with: Framework agnostic

## What it is

DESIGN.md is a file format that gives a coding agent a persistent, structured understanding of a design system. It pairs machine-readable tokens in YAML front matter, covering colours, typography, radii and spacing, with markdown prose explaining why those values exist and how to apply them. The repository holds the specification, worked examples and a linter you can run with npx, which validates a file against the spec, catches broken token references and reports WCAG contrast ratios as JSON an agent can act on. Apache-2.0, published by Google Labs.

## Why it's here

This is the thing all the DESIGN.md catalogues and extractors are built on, and it's worth reading the spec before you use any of them. The insight is that tokens alone aren't enough: an agent given values but no reasoning still makes ugly choices, so the format makes you write down the why. The linter is the underrated part, because a design file that fails contrast is a bug you can catch before it ships.

## Best for

- writing a DESIGN.md properly
- linting a design file
- giving an agent persistent design context

## Links

- Website: https://github.com/google-labs-code/design.md
- Docs: https://stitch.withgoogle.com/docs/design-md/specification
- GitHub: https://github.com/google-labs-code/design.md
- npm: https://www.npmjs.com/package/@google/design.md

## Can my agent use this?

Yes, completely. Point your agent at the repository so it reads the specification and the examples, then have it write a DESIGN.md for your project and check the result with the linter. Because the format is plain markdown with front matter, the finished file costs very little to keep in context and gives every later request the same reference to build against.

Agent friendliness: Excellent. Public docs, public source or an installable package. An agent can read, install and implement this directly.
Access methods: GitHub, Docs, npm, CLI, Copy/paste.
Install: `npx @google/design.md lint DESIGN.md`

## Prompt to hand your agent

```text
Use DESIGN.md Specification as a design and implementation reference for this project.

What it is: Google Labs' open format for describing a visual identity to a coding agent.

Website: https://github.com/google-labs-code/design.md
Documentation: https://stitch.withgoogle.com/docs/design-md/specification
GitHub: https://github.com/google-labs-code/design.md
npm: https://www.npmjs.com/package/@google/design.md
Install: npx @google/design.md lint DESIGN.md

Use it specifically for:
- writing a DESIGN.md properly
- linting a design file
- giving an agent persistent design context

How you can access it: GitHub, Docs, npm, CLI, Copy/paste.
Works with: Framework agnostic.
License: Apache-2.0. Respect it.

Read the documentation before writing code, and use the current version's API. Install it properly rather than re-implementing it. Adapt the defaults to this project's existing design tokens, typography, spacing and accessibility requirements. Do not blindly copy the entire resource.
```

## Related

- [getdesign.md](https://dontmakeitugly.com/resources/getdesign-md.md): A 550-strong catalogue of DESIGN.md files, following Google's spec.
- [designmd.supply](https://dontmakeitugly.com/resources/designmd-supply.md): Pre-generated DESIGN.md style guides for the world's best-known brands, MIT licensed.
- [Refero Styles](https://dontmakeitugly.com/resources/refero-styles.md): DESIGN.md files extracted from 2,000+ real product websites, written for agents.
- [DesignMD](https://dontmakeitugly.com/resources/designmd.md): Point it at a URL and it extracts that site's design system as a DESIGN.md.

## In collections

- [Give your agent a DESIGN.md](https://dontmakeitugly.com/collections/design-md-for-agents.md)

DESIGN.md Specification is an independent resource listed by Don't Make It Ugly. We link to it; we aren't affiliated with it. Pricing and licence details are as understood at the time of listing; check the official site.