·10 分で読めます

DESIGN.md を CI に組み込む：lint でデザイン規約を検証する

DESIGN.md のエンジニアリングガイド：YAML 値と Markdown 意図の二層構造、公式の lint／diff／export／spec の4コマンド、WCAG AA 検証の境界、exit code の落とし穴、そして完全な CI 導入例。

S
Stitch Prompt Team
Content Team
StitchAIチュートリアルGitHub

この 1 年、「エージェントに一貫したスタイルの UI を書かせる」ことが現実のエンジニアリング課題になりました。答えは素朴な解決策へと収束しつつあります。設計規約をプレーンテキストのファイルに書き下し、エージェントが着手前にそれを読む、という方法です。

DESIGN.md はこの解決策の中で最も注目されているものです。Google Labs の公式オープンソースリポジトリ（Apache-2.0 ライセンス、現在は alpha 段階）から生まれ、単体で動く公式 CLI が付属します。lint、diff、export、spec の 4 コマンドに対応し、最新の v0.4.0 は 10 月上旬にコミュニティで繰り返し実測されています。

さらに重要なのはその位置づけの変化です。DESIGN.md はもはや「エージェントに見せる説明ドキュメント」ではなく、lint でき、diff でき、CI でブロックできるエンジニアリング成果物です。デザイントークンのガバナンスに、初めて公式の実行可能なツールチェーンが生まれました。

注意：DESIGN.md フォーマットは現在も alpha で、仕様は今後変わります。CI に組み込む際は CLI のバージョンを固定してください。本記事は v0.4.0 の挙動を基準にしています。

1. 「エージェントに見せるドキュメント」から「検証可能なエンジニアリング成果物」へ

エージェント時代は 1 つの取り決めを形成しつつあります。異なる責務は、異なるプレーンテキストの規約ファイルに委ねる、というものです。

ファイル管轄中核の役割
CLAUDE.md振る舞いエージェントにタスクの進め方と従うべきフローを伝える
DESIGN.mdビジュアル色、フォント、余白、コンポーネントのルールなどのデザイン意図を定義する
AGENTS.md協業複数のエージェントやツール間の協業の取り決めを定義する

コミュニティで流れているまとめが的確です。CLAUDE.md は振る舞いを、DESIGN.md はビジュアルを、AGENTS.md は協業を管轄する。

DESIGN.md の真の価値は検証可能性にあります。色のコントラスト比、トークンの参照、セクションの完全性を、すべて 1 つのコマンドでチェックでき、そのチェックを CI に組み込めば、規約に適合しない設計規約をメインブランチにマージできなくなります。

2. DESIGN.md フォーマット速覧：YAML の値＋Markdown の意図

DESIGN.md は二層構造を採用します。

  • YAML frontmatter：規約の値（トークン）を置きます。色値、フォント名、文字サイズの比率など。
  • Markdown 本文：デザインの意図を置きます。これらの値がなぜこう定義されているか、どう使うべきかを説明します。

この役割分担の意味は、機械は YAML を読んで検証とエクスポートを行い、人とエージェントは Markdown を読んで文脈を理解する、という点にあります。

固定のセクション順序

公式の規約は、セクションを固定の順序で構成することを求めます。lint ツールはこの順序に依存して完全性をチェックします。

  1. Overview
  2. Colors
  3. Typography
  4. Layout
  5. Elevation & Depth
  6. Shapes
  7. Components
  8. Do's and Don'ts

プロンプト型の設計規約を書くとき、あるいはエージェントに DESIGN.md の草稿を生成させるときは、この順序で構成してこそ検証を通過できます。

構造の示意

以下は最小構成の示意です（フィールドは実際の規約を基準にしてください）。

---
colors:
  primary: "#1a1a1a"
  background: "#ffffff"
  accent: "#2563eb"
typography:
  base: "Inter"
  scale: "1.25"
---

## Overview

これはドキュメント型のプロダクトで、読みやすさと抑制されたアクセントカラーを重視する……

## Colors

primary は本文とメインボタンに、accent はリンクとフォーカス状態にのみ使う……

3. 公式 CLI の 4 コマンド：lint／diff／export／spec

4 つのコマンドが設計規約のライフサイクル全体をカバーします。

コマンド役割
lintルールに沿って DESIGN.md を検証。WCAG AA のコントラストチェックを含む
diff2 つの規約、または 2 つのバージョン間の差分を比較
exportTailwind config または W3C DTCG のデザイントークンとしてエクスポート
spec規範化された説明を出力し、チームのフォーマット統一を支援

ローカルで 1 回検証を実行します。

npx @google/design.md lint DESIGN.md

lint のルールと WCAG AA の境界

lint には 8 つの検証ルールが内蔵されており、最も存在感があるのはコントラストチェックです。WCAG AA の 4.5:1 基準でテキストと背景の組み合わせを照合します。

その境界を明確にしておく必要があります。lint はフォーカス状態をチェックせず、セマンティックな構造もチェックせず、モーションもチェックしません。止められるのは「明確な欠陥」であり、デザインレビューの代わりにはなりません。

exit code の落とし穴：なぜコントラスト問題で CI が失敗しないのか

これが最も踏みやすい落とし穴です。lint はコントラスト問題を発見しても警告するだけで、エラーにはしません。プロセスは exit 0 で終了します。つまり、lint をそのまま CI に組み込んでも、コントラストが不合格の規約は通過してしまいます。

CI で厳格にブロックするには、lint の JSON 出力を読み取り、自分で判断して非ゼロの終了コードを返す必要があります。以下のチェックロジックは示意です（実際の出力形式を基準にしてください）。

# 示意：lint の結果を保存し、コントラスト警告が出たら手動で CI を失敗させる
npx @google/design.md lint DESIGN.md > lint-result.json
if grep -qi "contrast" lint-result.json; then
  echo "コントラスト検証に失敗しました"
  exit 1
fi

4. 実践：DESIGN.md の検証を CI パイプラインに組み込む

そのまま参考にできる GitHub Actions の設定です。2 点に注意してください。公式 workaround にある designmd コマンド名を使うこと、そしてバージョンを固定することです。

name: design-lint

on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Lint DESIGN.md
        run: npx -p @google/design.md@0.4.0 designmd lint DESIGN.md

厳格モード：JSON 出力を解析する

チームが「コントラストが基準未満なら必ずマージをブロックする」ことを求めるなら、上記に 1 ステップ追加します。JSON 出力を保存し、コントラストの警告が存在するか確認し、該当すれば非ゼロの終了コードで終えます。考え方は前節の示意と同じで、鍵は「警告」を CI のセマンティクスにおける「失敗」に翻訳することです。

5. Tailwind config と DTCG へのエクスポート：デザイントークンの着地経路

lint は規約が「正しく書かれている」ことを保証し、export は規約が「使い物になる」ことを解決します。

  • Tailwind config としてエクスポート：フロントエンドのエンジニアリングがデザイントークンを直接消費でき、配色とフォントがコンポーネントの中に散らばらなくなります。
  • W3C DTCG 形式としてエクスポート：より広いデザインツールチェーンと相互運用できます。

特筆すべきは、DESIGN.md の CLI は独立して動作し、Stitch アカウントを必要としない点です。チームが Stitch で画面を生成する予定がなくても、単独で設計規約の検証とエクスポートのツールとして使えます。

6. トラブルシューティング：3 種類のよくある問題

現象原因対処
ENOVERSIONS依存関係またはバージョンの解決に失敗CLI のバージョンを固定し、キャッシュを消して再インストール
Windows で出力がないdesign.md コマンドとファイル関連付けの衝突workaround のコマンドを使う
broken-ref規約内で存在しないトークンやセクションを参照エラーの行番号に従って参照を修正

Windows／PowerShell のユーザーがコマンドの衝突に遭遇した場合は、次を使います。

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

7. よくある質問（FAQ）

Q1：Stitch アカウントなしで、DESIGN.md とこの CLI を単独で使えますか？

はい。フォーマット規約と CLI はどちらも独立したプロジェクトで、ローカルでの実行も CI への組み込みも Stitch のクラウドサービスに依存しません。

Q2：なぜコントラスト問題で CI が失敗しないのですか？

lint はコントラスト問題に対して警告を出力するだけで exit 0 で終了します。厳格にブロックするには JSON 出力を解析し、自分で非ゼロの終了コードを返す必要があります。

Q3：チームで使い始めたばかりですが、最小限の実行可能な方法は？

2 ステップです。AGENTS.md に「UI 作業の前に必ず DESIGN.md を読む」と 1 行加え、次にリポジトリに lint の CI チェックを 1 つ追加します。規約の中身は使いながら補充していけます。

8. まとめ

DESIGN.md は「設計規約」を口頭の取り決めからエンジニアリング成果物へと変えました。書けて、検証できて、エクスポートできて、ブロックできる。すでに CI の習慣があるチームにとっては、ほぼゼロコストで導入できます——1 つのコマンドでチェックし、1 本のパイプラインで下支えを守る。

続けて読む：

← ← ブログに戻る