CLI で検証する

@google/design.md CLI は、デザインシステムを仕様に照らして検証し、壊れたトークン参照を検出し、WCAG コントラスト比をチェックし、トークンを他の形式にエクスポートします。そのすべてを、エージェントが利用できる構造化 JSON として出力します。

インストール

npm install @google/design.md

インストールせずに直接実行することもできます：

npx @google/design.md lint DESIGN.md

すべてのコマンドはファイルパス、または標準入力の - を受け付けます。出力はデフォルトで JSON です。

DESIGN.md を lint する

DESIGN.md ファイルの構造が正しいかを検証します。linter は YAML front matter を解析し、すべてのトークン参照を解決し、8 つの lint ルールを実行して、検出結果を報告します。

npx @google/design.md lint DESIGN.md

出力例：

{
  "findings": [
    {
      "severity": "warning",
      "path": "colors",
      "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette."
    },
    {
      "severity": "info",
      "message": "Design system defines 4 colors, 3 typography scales, 2 rounding levels."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 1 }
}

DESIGN.md ファイルをプログラムで生成している場合は、標準入力からパイプします：

cat DESIGN.md | npx @google/design.md lint -

オプション	型	デフォルト	説明
file	positional	required	DESIGN.md へのパス（標準入力の場合は -）
--format	json	text	json

エラーが見つかった場合は終了コード 1、それ以外は 0 です。

2 つのバージョンを比較する

2 つの DESIGN.md ファイル間のトークンレベルの変更を検出します。diff コマンドは、追加、削除、変更されたトークンを報告し、リグレッション（「after」ファイルでのエラーや警告の増加）にフラグを立てます。

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

出力例：

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1 },
    "after": { "errors": 0, "warnings": 2 },
    "delta": { "errors": 0, "warnings": 1 }
  },
  "regression": true
}

オプション	型	デフォルト	説明
before	positional	required	「before」の DESIGN.md へのパス
after	positional	required	「after」の DESIGN.md へのパス
--format	json	text	json

リグレッションが検出された場合は終了コード 1 です。

トークンをエクスポートする

DESIGN.md のトークンを、コードベースで使える他の形式に変換します。

Tailwind CSS

theme.extend 設定オブジェクトを生成します：

npx @google/design.md export --format tailwind DESIGN.md

出力は、デザイントークンからマッピングされた colors、fontFamily、fontSize、borderRadius、spacing を含む JSON オブジェクトです。tailwind.config.js にそのまま貼り付けてください。

DTCG (W3C Design Tokens)

W3C Design Tokens Format Module に準拠した tokens.json を生成します：

npx @google/design.md export --format dtcg DESIGN.md

オプション	型	デフォルト	説明
file	positional	required	DESIGN.md へのパス
--format	tailwind	dtcg	required

仕様を表示する

DESIGN.md のフォーマット仕様を出力します。これは、仕様のコンテキストをエージェントのプロンプトに注入し、エージェントがどの構造を生成すべきかを正確に把握できるようにするのに便利です。

npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json

オプション	型	デフォルト	説明
--rules	boolean	false	有効な lint ルールの表を追加
--rules-only	boolean	false	lint ルールの表のみを出力
--format	markdown	json	markdown

プログラム API

linter は TypeScript ライブラリとしても利用できます：

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

const report = lint(markdownString);

console.log(report.findings);      // Finding[]
console.log(report.summary);       // { errors, warnings, infos }
console.log(report.designSystem);  // Resolved DesignSystemState
console.log(report.tailwindConfig); // Generated Tailwind theme