DESIGN.md: AIのUI一貫性問題を解決する

問題: Claude Codeはローカルコンテキストが強く、プロダクトコンテキストが弱いです。編集中のファイルは把握しています。しかし、あなたのプロダクトがどのような見た目であるべきかは把握していません。セッションをまたぐとデザインシステムが消えます。リンクがあるべき場所にボタンが現れます。空の状態が消えてしまいます。あるコンポーネントで#E07850だった色が、次のコンポーネントではorange-400になります。

すぐできる改善: プロジェクトルートにdesign.mdファイルを置き、CLAUDE.mdから参照しましょう。デザインの値がコードベースと一緒に移動します。すべてのセッションが同じ制約をコンテキストに持った状態で始まります。

design.mdとは何か

design.mdファイルはプレーンテキストのデザインシステムです。特別な構文は不要です。ツールも不要です。色、スペーシング、タイポグラフィ、コンポーネントルール、インタラクション状態を読みやすいMarkdownで記述します。

Google Stitchは2026年3月にこのフォーマットを導入し、README.mdが普遍的な慣例になったのと同様に、相互運用性のインフラとして位置付けました。GitHubのawesome-design-mdコレクションは2026年4月に62,300スターを超え、Stripe、Linear、Supabase、Vercel、Notionなど60以上のブランドデザインシステムがこのフォーマットで収録されています。

アイデアはシンプルです。Claude Codeはファイルを読みます。デザインシステムがファイルであれば、Claude Codeはデザインシステムを読みます。

ファイルがないとセッションがずれる理由

Claude Codeは各セッションの開始時にコンテキストをロードします。CLAUDE.mdを読み、開いているファイルをスキャンし、プロジェクトの全体像を構築します。明示的なデザインファイルがなければ、UIの決定を真実の源泉に結びつけるものは何もありません。

どこかのコメントにプライマリカラーを記述しているかもしれません。あるいは1つのコンポーネントのTailwindクラスかもしれません。Claude Codeは最初に開いたものを読み、そこから推論します。3セッション後には、UIは最善の推測の集合体になっています。

CLAUDE.mdにdesign.mdファイルを追加すると入力が変わります。値は推論されるのではなく明示的になります。すべてのセッションが同じ真実の源泉をコンテキストに持った状態で開きます。

Google StitchからdesigndXを取得する

Google Stitchは、Google Labsが開発したUIデザインツールで、2025年5月のGoogle I/Oで発表されました。Gemini 2.5 Proで動作し、stitch.withgoogle.comにあり、Labsフェーズ中は無料です（Googleアカウントが必要で、ウェイトリストなし、無料ティアで月350回生成可能）。design.mdエクスポートは2026年3月18日のStitch 2.0で追加されました。

ファイルを生成するワークフロー:

stitch.withgoogle.comにアクセスし、Webタブをクリックします（Appではなく）。利用可能な最高のProモデルを選択します。
オプションで、現在のUIのリファレンススクリーンショットやインスピレーション画像をアップロードします。
ブランドを説明するブリーフを書きます。色、トーン、コンポーネントスタイル、プロダクトの説明などです。
出力が意図と一致するまで会話的にイテレーションします。
Exportをクリックし、DESIGN.mdを選択して、ファイルをプロジェクトルートに保存します。

Stitchはカラートークン、タイポグラフィスケール、スペーシング単位、コンポーネントパターン、状態定義（ホバー、フォーカス、アクティブ、無効）をカバーする構造化ファイルを作成します。出力はポータブルです。Claude Code、Cursor、Windsurf、またはファイルを読む任意のツールで動作します。

CLAUDE.mdをファイルに接続する

ルートにdesign.mdを置くだけでは不十分です。CLAUDE.mdに明示的な指示がなければ、Claude Codeはそのファイルを参照するかもしれないリファレンス資料として扱います。明示的な指示があれば、Claude Codeはその値を従うべき制約として扱います。

機能するブロック:

## Design System
This project uses a design system defined in `design.md` at the project root.
Always refer to this file when generating or modifying any UI component.
- Use only colors, fonts, and spacing values defined in design.md.
- Do not invent new values or use defaults from any framework.
- Match component states (hover, focus, active, disabled) to the patterns in design.md.
- Follow the typographic scale and weight assignments in design.md.
@design.md

末尾の@design.mdインポートは、セッション開始時にファイルの全内容を注入します。4つの箇条書きは、受動的な参照を積極的な制約に変えます。両方の部分が重要です。インポートだけでは、Claude Codeにドキュメントを渡すだけです。指示があって初めて、Claude Codeにルールが与えられます。

ビルド前に接続を確認する

CLAUDE.mdを更新したら、Claude Codeが値を正しくロードしたことを確認します。

Claude Codeに聞いてみましょう: What primary color is defined in design.md?

正しい16進数が返ってきたら、インポートは機能しています。曖昧な答えや推測が返ってきたら、@design.mdがブロックの末尾に現れていること、ファイルパスが正確であること（Linuxでは大文字と小文字を区別する）を確認してください。

UIに関わるセッションの開始時にこのチェックを実行してください。10秒で完了し、ドリフトの問題になる前に欠落しているインポートを検出できます。

Tailwind強制レイヤーを追加する

CLAUDE.mdはコンテキストです。Tailwindは強制です。両者は連携します。

design.mdのトークン値をtailwind.config.jsに変換しましょう。Claude Codeがbg-primaryの代わりにbg-blue-500と書いたとき、ビルドは失敗します。これが正しい動作です。ビルド時の型エラーは、4画面目で気づく視覚的な不一致よりも優れています。

2色のブランドのための最小限の設定ブロックは以下のようになります:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#E07850',
        'primary-dark': '#C5613A',
        surface: '#1A1A1A',
        'surface-elevated': '#1E1B18',
        text: '#FFFFFF',
        'text-muted': '#999999',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
}

design.mdのすべての値は、この設定に名前付きトークンを持つべきです。Claude Codeはその後、生の値ではなくトークンを書きます。ビルドがすり抜けたものを検出します。

6つの失敗パターン

以下は実際の運用でこの設定が壊れるパターンです。

早すぎるエクスポート。 ブリーフが薄いと、Stitchはプレースホルダーの色や欠落した状態を生成します。エクスポートする前に出力が完全になるまでイテレーションしましょう。design.mdのギャップは、Claude Codeの制約のギャップになります。

曖昧なCLAUDE.md指示。 インポートだけでは不十分です。上記ブロックの4つの箇条書きがドキュメントをルールセットに変えます。それらがなければ、Claude Codeはファイルを読んでからどれだけ従うかを自分で決めます。

Tailwind変換なし。 4画面後の視覚レビューで検出されたドリフトは、1コンポーネント後のビルドエラーで検出されたものよりコストがかかります。ビルドを開始する前に設定レイヤーを追加してください。

design.mdがバージョン管理されていない。 リポジトリにない場合、新しいクローンや新しいチームメンバーはデザインシステムなしで始まります。作成した瞬間にファイルをコミットしてください。

再設計後のファイルが古い。 ブランドを変更したら、Stitchから再エクスポートしてください。前四半期の色を説明しているdesign.mdは、ファイルがないより悪いです。Claude Codeに自信を持った間違った答えを与えてしまうからです。

長いファイルのコンテキスト劣化。 長いコンテキストウィンドウの中央にある情報は、先頭や末尾にある情報よりも確実性が低く想起されます。design.mdは2,000から3,000トークン以内に保ちましょう。ファイルがそれを超えて大きくなる場合は、カテゴリ（色、タイポグラフィ、スペーシング、コンポーネント）で分割してください。

Stitchの代替手段

Stitchは完全なdesign.mdへの最速の道ですが、4つの他のアプローチも機能します。

DevToolsからの手動抽出。 Chrome DevToolsを開き、主要な要素（ボタン、見出し、カード）を調べ、計算されたCSSをClaude Codeにコピーして、このデザインシステムをmarkdownファイルとして変換してくださいと依頼します。5分かかります。新しいシステムを定義するのではなく、現在の状態をキャプチャする必要がある既存のプロダクトに適しています。

GitHubのawesome-design-md。 github.com/VoltAgent/awesome-design-mdのコレクションは、2026年4月時点で60以上のブランドデザインシステムをDESIGN.mdフォーマットで持っています。既存のブランド美学に隣接するものを作っている場合は、スクラッチから生成するのではなく、リファレンスから始めて編集してください。

Figma MCP。 Claude CodeはMCPを通じてFigmaに直接接続し、デザイントークンをリアルタイムで読み取ります。Parallel HQのケーススタディでは、6ヶ月間でデザインの不一致が62%減少し、ワークフロー効率が78%向上したと報告しています。トレードオフは認証の摩擦です。Stitchはスタンドアロンのファイルをエクスポートしますが、Figma MCPはライブ接続とトークン管理が必要です。

URLからの抽出。 StitchはパブリックURLを入力として受け付けます。クリーンなマーケティングサイトのURLを貼り付けると、Stitchはビジュアルスタイルを読み取ります。クリーンなパブリック向けページには適していますが、認証済みダッシュボードには苦手です。

Claude DesignとdesignXの比較

Claude Designは2026年4月17日に、新しい2,576pxビジョンモードを持つOpus 4.7によって動作する形で公開されました。会話を通じてビジュアル作業を作成し、Anthropicエコシステム内にハンドオフバンドルを生成します。あるEdTechの会社では、他のツールで20回以上のプロンプトが必要だったページが、Claude Designでは2回で済んだと報告しています。

design.mdワークフローとの違いはポータビリティにあります。Claude Designは Anthropicスタックに結びついたアーティファクトを生成します。StitchからエクスポートされたXdesign.mdは、ファイルを読む任意のツールで動作するプレーンファイルです。Claude Code、Cursor、Windsurf、またはカスタムビルドスクリプトなどです。

Anthropicエコシステムに留まる場合はClaude Designの方が高速です。デザインシステムをコードベースと一緒に、それが管理するコードと並べてバージョン管理したい場合はdesign.mdの方が優れています。

得られるもの

リポジトリルートの1つのファイル。CLAUDE.mdの4行。tailwind.config.jsの名前付きトークン。

すべてのセッションが同じデザイン制約をコンテキストに持った状態で開きます。すべてのビルドがドリフトを蓄積させる代わりに生の値で失敗します。Claude Codeが触れるすべての画面が前の画面と同じルールに従います。

デザインの一貫性はレビュープロセスではありません。それはファイルです。

よくある質問

Claude Codeのdesign.mdとは何ですか？

design.mdはプロジェクトルートにあるプレーンテキストファイルで、デザインシステムを定義します。色、タイポグラフィ、スペーシング、コンポーネントルール、インタラクション状態などです。@design.mdインポートを使ってCLAUDE.mdで参照すると、Claude Codeはセッション開始時にこれらの値をロードし、提案ではなく制約として扱い、セッションをまたいですべての画面を一貫した状態に保ちます。

Claude Codeでdesign.mdを使う方法は？

Google Stitchからdesign.mdファイルをエクスポートするか手動で作成し、プロジェクトルートに置いてから、@design.mdインポートと4つの箇条書きルールを含む## Design SystemブロックをCLAUDE.mdに追加します。最後に、システムを迂回する生の値をビルドが失敗するよう、トークン値をtailwind.config.jsに変換します。

Google Stitchは無料ですか？

はい、Google Labsフェーズ中は無料です。stitch.withgoogle.comの無料ティアは月350回の生成を含み、すべてのコア機能にアクセスでき、Googleアカウントのみが必要でウェイトリストはありません。design.mdエクスポートを導入したStitch 2.0は2026年3月18日に公開されました。StitchがLabsフェーズを終えると料金が変わる可能性があります。

awesome-design-mdリポジトリとは何ですか？

awesome-design-mdはVoltAgentがgithub.com/VoltAgent/awesome-design-mdでメンテナンスしているGitHubコレクションです。Stripe、Linear、Supabase、Vercel、Notionなどの実際のブランドデザインシステムをモデルにした60以上の即使用可能なDESIGN.mdファイルが含まれています。スクラッチから生成するのではなく、1つをプロジェクトに直接組み込んで出発点にし、ブランドに合わせて編集できます。

Claude Codeにデザインシステムを無視させないようにするには？

2つのことが別々ではなく、一緒に必要です。まず、CLAUDE.mdのデザインブロックの末尾に@design.mdインポートを追加し、セッション開始時にファイルの内容がロードされるようにします。次に、インポートの上にファイルからの値のみを使用し新しい値を作り出さないようにClaude Codeに指示する明示的な箇条書きルールを追加します。インポートだけではClaude Codeにドキュメントを渡すだけです。ルールがあって初めてClaude Codeに制約が与えられます。

design.md vs Figma MCP: Claude Codeにはどちらが良いですか？

両者は同じ問題を異なる方法で解決します。Figma MCPはClaude Codeをリアルタイムでとフigmaに接続し、ライブデザイントークンとコンポーネントへのアクセスを提供しますが、認証設定と持続的な接続が必要です。Stitchのdesign.mdはオフラインで動作し、リポジトリと一緒に移動し、コードと並べてバージョン管理できるスタンドアロンのファイルです。Figma MCPはFigmaに深く入り込んでいるチームに適しています。design.mdはインフラをゼロにしたいソロビルダーに適しています。

DESIGN.md: AIのUI一貫性問題を解決する

On this page