@google/design.md — DESIGN.md フォーマットと CLI（google-labs-code/design.md）

何か

DESIGN.md は、ブランドの見た目・雰囲気・振る舞いをプレーンテキストで記述するオープンフォーマット。YAML フロントマターに機械可読なデザイントークン、Markdown 本文に人間（とエージェント）向けの設計意図を書く。同梱 CLI が構造検証・WCAG コントラスト・トークン参照の解決・Tailwind / DTCG への変換を JSON 出力で返す。

alpha フォーマット版

4 CLI サブコマンド

9 Lint ルール

3 export 形式

lint diff export spec Tailwind v3/v4 DTCG WCAG AA

Awesome DESIGN.md との違い: google-labs-code/design.md はフォーマット仕様とリンター本体。Awesome DESIGN.md は既存サービスから抽出した DESIGN.md ファイルのキュレーション集。

二層構造

1 ファイルにトークン（規範値）と散文（適用文脈）を同居させる。トークンは正確な値、散文は「なぜその値か」「どこに使うか」をエージェントへ伝える。

YAML front matter

先頭 --- で囲んだトークン群。colors / typography / rounded / spacing / components など。参照は {colors.primary} 形式。

Markdown body

## 見出しで区切った散文セクション。Overview → Colors → Typography → … の順序が推奨。未知のセクションは保持され、エラーにならない。

flowchart TB
  subgraph file["DESIGN.md"]
    FM["YAML front matter\n(name, colors, typography, components…)"]
    MD["Markdown body\n(Overview, Colors, Do's and Don'ts…)"]
  end
  FM -->|"規範値"| Agent["コーディングエージェント"]
  MD -->|"意図・制約"| Agent
  Agent --> UI["一貫した UI 生成"]

最小スキーマ

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
---

## Overview
Architectural Minimalism meets Journalistic Gravitas…

## Colors
- **Primary (#1A1C1E):** Deep ink for headlines…

セクション順（存在する場合）

#	セクション	別名
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	—

拡張: motion や iconography など仕様外キーも受理される。リンターは既知スキーマキーの typo のみ警告し、カスタム拡張は黙認する。

散文が主役

PHILOSOPHY.md の中心命題: 生成品質は値の精度より、意図の記述の明確さで決まる。トークンは散文の参照用コンテキストであり、レンダリング命令ではない。

→具体参照 > 形容詞: 「1970 年代の大学院配布資料」は「モダンでクリーンで信頼感」より情報量が大きい。参照が点を、形容詞が領域を示す。
→否定制約: 参照が具体なら「グラデーション禁止」等は暗黙に伝わる。Do's and Don'ts は意図的な補強として併用する。
→ユーザー主導の成長: 仕様は colors / typography 等の最小集合を標準化し、motion 等は各チームが prose + 任意 YAML で拡張する。

リポジトリ構成

モノレポ（Bun + Turbo）。packages/cli が @google/design.md 本体。examples/ に Atmospheric Glass・Paws and Paths・Totality Festival など実例 DESIGN.md と design_tokens.json が同梱される。

インストールと実行

npm install @google/design.md

# 検証（JSON 出力、エラー時 exit 1）
npx @google/design.md lint DESIGN.md

# 2 版のトークン差分
npx @google/design.md diff DESIGN.md DESIGN-v2.md

# Tailwind / DTCG へエクスポート
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

# 仕様本文をプロンプトへ注入
npx @google/design.md spec --rules

Windows: design.md バイナリ名が .md ファイル関連付けと衝突する場合がある。npx -p @google/design.md designmd lint DESIGN.md または package.json scripts で designmd エイリアスを使う。

サブコマンド一覧

コマンド	役割	終了コード
`lint`	構造・参照・コントラスト・セクション順を検査。findings + summary を JSON 出力	error ありで 1
`diff`	2 ファイル間のトークン added / removed / modified と prose 回帰フラグ	回帰ありで 1
`export`	`json-tailwind` / `css-tailwind` / `dtcg` へ変換	—
`spec`	フォーマット仕様（`--rules` で Lint 表付き）を stdout へ	—

プログラム API

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

const report = lint(markdownString);
// report.findings, report.summary, report.designSystem

flowchart LR
  MD["DESIGN.md"] --> Parse["parser"]
  Parse --> Lint["lint / 9 rules"]
  Parse --> Export["export"]
  Lint --> JSON["structured JSON"]
  Export --> TW["Tailwind v3/v4"]
  Export --> DTCG["tokens.json (DTCG)"]

9 ルール

ルール	重大度	内容
`broken-ref`	error	`{colors.primary}` 等の参照が未定義トークンを指す
`missing-primary`	warning	colors があるのに `primary` が無い
`contrast-ratio`	warning	component の backgroundColor / textColor が WCAG AA 未満（4.5:1）
`orphaned-tokens`	warning	定義された color がどの component からも参照されない
`missing-typography`	warning	colors のみで typography が無い
`section-order`	warning	Markdown セクションが canonical 順序から外れている
`unknown-key`	warning	既知 YAML キーの typo（例: `colours:`）
`token-summary`	info	セクション別トークン数のサマリ
`missing-sections`	info	spacing / rounded 等の推奨セクション欠落

lint 出力例

{
  "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 }
}

相互運用

トークン体系は W3C Design Tokens Format を参考に設計。CLI が既存ツールチェーンへ橋渡しする。

`--format`	出力	用途
`json-tailwind` / `tailwind`	JSON	Tailwind v3 `theme.extend`
`css-tailwind`	CSS `@theme { … }`	Tailwind v4 の CSS 変数（`--color-`, `--font-` 等）
`dtcg`	JSON	W3C DTCG `tokens.json`（Figma variables 等と相互変換しやすい）

公式・関連

GitHub: google-labs-code/design.md — 仕様・CLI・examples
npm: @google/design.md — CLI パッケージ
docs/spec.md — 生成された完全仕様
PHILOSOPHY.md — 散文中心の設計哲学
Awesome DESIGN.md — 58+ サービス由来の DESIGN.md キュレーション（別リポジトリ）