| name | design-cli |
| description | DESIGN.md 格式规范与 @google/design.md CLI 工具使用指南。涵盖设计系统的 YAML token 定义（颜色、字体、圆角、间距、组件）、Markdown 设计说明文档结构、lint 校验、diff 对比、export 导出（Tailwind v3/v4、DTCG）等全部功能。 当用户需要创建或编辑 DESIGN.md 设计系统文件、校验设计规范、对比设计 token 变更、导出设计 token 到 Tailwind/DTCG 格式、了解 DESIGN.md 格式规范，或使用 @google/design.md CLI 时使用。
|
| license | MIT |
| metadata | {"origin":"https://github.com/mymx2/skills/skills/design-cli","author":"mymx2 <https://github.com/mymx2>","version":"2026.06.17"} |
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, "info": 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": [] }
},
"regression": false
}
The Specification
File Structure
A DESIGN.md file has two layers:
- YAML front matter — Machine-readable design tokens, delimited by
--- fences at the top of the file.
- 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>
name: <string>
description: <string>
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.
{
"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 |
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 nine 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 |
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);
console.log(report.summary);
console.log(report.designSystem);
Design Token Interoperability
DESIGN.md tokens are inspired by the W3C Design Token Format. The export command converts tokens to other formats:
- Tailwind v3 config (JSON) —
npx @google/design.md export --format json-tailwind DESIGN.md — emits a theme.extend JSON object for tailwind.config.js. --format tailwind is a backwards-compatible alias.
- Tailwind v4 theme (CSS) —
npx @google/design.md export --format css-tailwind DESIGN.md — emits a CSS @theme { ... } block using Tailwind v4's CSS-variable token namespaces (--color-*, --font-*, --text-*, --leading-*, --tracking-*, --font-weight-*, --radius-*, --spacing-*).
- DTCG tokens.json (W3C Design Tokens Format Module) —
npx @google/design.md export --format dtcg DESIGN.md
Source
