design.md README

The project's README from github.com/google-labs-code/design.md. As one markdown file: README.md.

DESIGN.md

A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.

The Format

A DESIGN.md file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells them why those values exist and how to apply them.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

An agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.

Getting Started

Validate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.

npx @google/design.md lint DESIGN.md

{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 1 }
}

Compare two versions of a design system to detect token-level and prose regressions:

npx @google/design.md diff DESIGN.md DESIGN-v2.md

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] },
    "rounded": { "added": [], "removed": [], "modified": [] },
    "spacing": { "added": [], "removed": [], "modified": [] },
    "components": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1, "infos": 1 },
    "after": { "errors": 0, "warnings": 1, "infos": 1 },
    "delta": { "errors": 0, "warnings": 0 }
  },
  "regression": false
}

The Specification

The full DESIGN.md spec lives at docs/spec.md. What follows is a condensed reference.

File Structure

A DESIGN.md file has two layers:

  1. YAML front matter — Machine-readable design tokens, delimited by --- fences at the top of the file.
  2. Markdown body — Human-readable design rationale organized into ## sections.

The tokens are the normative values. The prose provides context for how to apply them.

Token Schema

version: <string>          # optional, current: "alpha"
name: <string>
description: <string>      # optional
omitted: <string[] | OmittedSection[]> # optional, list of sections to intentionally omit
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Token Types

Type Format Example
Color Any CSS color (hex, rgb(), oklch(), named, etc.) "#1A1C1E", "oklch(62% 0.18 250)"
Dimension number + unit (px, em, rem) 48px, -0.02em
Token Reference {path.to.token} {colors.primary}
Typography object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation See example above

Section Order

Sections use ## headings. They can be omitted, but those present must appear in this order:

# Section Aliases
1 Overview Brand & Style
2 Colors
3 Typography
4 Layout Layout & Spacing
5 Elevation & Depth Elevation
6 Shapes
7 Components
8 Do's and Don'ts

Component Tokens

Components map a name to a group of sub-token properties:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

Valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width.

Variants (hover, active, pressed) are expressed as separate component entries with a related key name.

Consumer Behavior for Unknown Content

Scenario Behavior
Unknown section heading Preserve; do not error
Unknown color token name Accept if value is valid
Unknown typography token name Accept as valid typography
Unknown component property Accept with warning
Duplicate section heading Error; reject the file

CLI Reference

Installation

npm install @google/design.md

On Windows, quote the package name if your shell treats @ specially (PowerShell, some terminals):

npm install "@google/design.md"

Or run directly (always resolves from the public npm registry):

npx @google/design.md lint DESIGN.md

On Windows/PowerShell, this direct form can produce no output (or open DESIGN.md in your Markdown editor) because the .md suffix in the design.md bin name collides with the Windows Markdown file association during command resolution. Run the dot-free designmd alias instead — point npx at the package with -p, then invoke designmd:

npx -p @google/design.md designmd lint DESIGN.md

The designmd shim resolves to the same entrypoint and works identically across all platforms.

npm error ENOVERSIONS (“No versions available for @google/design.md”)

The CLI is published as @google/design.md on npm. ENOVERSIONS almost always means npm is not querying the public registry (custom registry= in .npmrc, a corporate mirror that has not synced this package, or a misconfigured @google:registry for the @google scope).

Check your effective registry:

npm config get registry

For a normal install from the internet it should be https://registry.npmjs.org/. After fixing config, retry with npm cache clean --force if a stale 404 was cached.

All commands accept a file path or - for stdin. Output defaults to JSON.

Windows tip: when invoking the CLI directly from a package.json script (rather than through npx), use the designmd alias instead of design.md. The .md suffix in the original bin name confuses Windows command resolution with the file association for Markdown files. The designmd shim resolves to the same entrypoint and works identically across all platforms.

// package.json
{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

lint

Validate a DESIGN.md file for structural correctness.

npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md
cat DESIGN.md | npx @google/design.md lint -
Option Type Default Description
file positional required Path to DESIGN.md (or - for stdin)
--format json json Output format

Exit code 1 if errors are found, 0 otherwise.

diff

Compare two DESIGN.md files and report token-level changes.

npx @google/design.md diff DESIGN.md DESIGN-v2.md
Option Type Default Description
before positional required Path to the "before" DESIGN.md
after positional required Path to the "after" DESIGN.md
--format json json Output format

Exit code 1 if regressions are detected (more errors or warnings in the "after" file).

export

Export DESIGN.md tokens to other formats.

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
Option Type Default Description
file positional required Path to DESIGN.md (or - for stdin)
--format json-tailwind | css-tailwind | tailwind | dtcg required Output format
Format Output Description
json-tailwind JSON Tailwind v3 theme.extend config object
css-tailwind CSS Tailwind v4 @theme { ... } block with CSS custom properties
tailwind JSON Alias for json-tailwind
dtcg JSON W3C Design Tokens Format Module

Exit code 0 on a successful export (regardless of any lint findings in the source — run lint to gate on those), 1 on an invalid --format or an emitter error, and 2 if the input file cannot be read.

spec

Output the DESIGN.md format specification (useful for injecting spec context into agent prompts).

npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json
Option Type Default Description
--rules boolean false Append the active linting rules table
--rules-only boolean false Output only the linting rules table
--format markdown | json markdown Output format

Linting Rules

The linter runs eleven rules against a parsed DESIGN.md. Each rule produces findings at a fixed severity level.

Rule Severity What it checks
broken-ref error Token references ({colors.primary}) that don't resolve to any defined token
missing-primary warning Colors are defined but no primary color exists — agents will auto-generate one
contrast-ratio warning Component backgroundColor/textColor pairs below WCAG AA minimum (4.5:1)
orphaned-tokens warning Color tokens defined but never referenced by any component
token-summary info Summary of how many tokens are defined in each section
missing-sections info Optional sections (spacing, rounded) absent when other tokens exist
missing-typography warning Colors are defined but no typography tokens exist — agents will use default fonts
section-order warning Sections appear out of the canonical order defined by the spec
unknown-key warning A top-level YAML key looks like a typo of a known schema key (e.g. colours: → colors:); custom extension keys stay silent
token-like-ignored warning An unknown top-level key has token-like values (e.g. hex colors, font families, dimensions) suggesting it was dropped or misspelled
omitted-rules info Validates the omitted configuration mapping for unknown or redundant sections

Programmatic API

The linter is also available as a library:

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);       // Finding[]
console.log(report.summary);        // { errors, warnings, info }
console.log(report.designSystem);   // Parsed DesignSystemState

Design Token Interoperability

DESIGN.md tokens are inspired by the W3C Design Token Format. The export command converts tokens to other formats:

Status

The DESIGN.md format is at version alpha. The spec, token schema, and CLI are under active development. Expect changes to the format as it matures.

Disclaimer

This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.

design.md (google-labs-code/design.md)

Searching Database…

28.4K ·GitHub
Design.md
这是什么？DESIGN.md 是一种格式规范，用于描述视觉识别系统（颜色、排版、布局、组件），让编码智能体能够持续、结构化地理解一套设计系统。
这是文件格式还是应用？这是一种文件格式（DESIGN.md 文件由 YAML 前置元数据和 Markdown 正文组成），并配有一个配套的命令行工具，用于校验、比较和导出这些文件。
如何在我自己的 DESIGN.md 文件上运行命令行工具？通过 npx 安装并运行，例如 'npx @google/design.md lint DESIGN.md'；在 Windows 上请改用不带点的 'designmd' 别名，因为 .md 后缀会与 Windows 的 Markdown 文件关联冲突。
使用命令行工具需要安装 Node 或 npm 吗？需要。该工具发布在公共 npm 仓库中，包名为 '@google/design.md'，通过 npx（Node/npm 工具链）运行；开发时内部使用 Bun。
这个格式已经定稿、稳定了吗？没有。它明确处于 alpha 阶段，因此规范、设计令牌的结构和命令行工具都预计会持续变化。
命令行工具在 Windows、macOS 和 Linux 上的表现都一样吗？所有平台都支持，但在 Windows/PowerShell 下，直接使用 'design.md' 命令可能因文件关联冲突而出错，因此建议在该平台改用 'designmd' 别名。
命令行工具究竟能检查 DESIGN.md 文件的哪些内容？它运行十一条校验规则，涵盖失效的设计令牌引用、缺少主色、违反 WCAG AA 对比度标准、孤立的设计令牌以及章节顺序等问题，并以结构化 JSON 格式输出检查结果。
我能把 DESIGN.md 中的设计令牌导出到 Tailwind 吗？可以。'export' 命令可将设计令牌转换为 Tailwind v3 的 theme.extend JSON 对象、Tailwind v4 的 CSS @theme 代码块，或 W3C DTCG tokens.json 格式。
如何比较两个版本的设计系统？使用 'diff' 命令，并分别指定修改前和修改后的 DESIGN.md 文件；它会报告设计令牌和正文层面的回归问题，若出现新的错误或警告，则以退出码 1 结束。
DESIGN.md 文件可以包含哪些章节？最多八个有序章节——Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components 和 Do's and Don'ts。任何章节都可以省略，但若出现，则必须按此顺序排列。
What are similar projects?lint, ui-ux-pro-max-skill, liteparse, sass, prettier, open-knowledge-format, transitions.dev, ux-ui-agent-skills
Which topics is it in?specification, yaml, design-system, tailwindcss, design, json, command-line, markdown, npm, frontend, tool, nodejs
Creator
google-labs-code
Size
0.3 MB
Stars
28.4K
Updated
CommitOct 16Release0.4.0Jul 27
Age
6mo
Commits · 90 Days