Google LabsがStitchプロジェクトで提案したDESIGN.mdフォーマットが興味深く、数日かけて仕様を読み込んだあと、自分だけで見て終えるのはもったいないと思い、韓国語で解きほぐして28チャプター構成のカリキュラム形式にまとめておきました。同じテーマを学ぶ方が最初から英語の仕様を読み漁らなくても済むように、そして私のように「AIにデザインシステムをどう読ませるか」という問いを持っている方が一度に見渡せるように、という感覚で作業しました。
DESIGN.mdは、デザインシステムを1つのMarkdownファイルで表現しようとするフォーマットです。色・タイポグラフィ・spacing・radius・component tokenといった値をYAML frontmatterに機械が読める形で置き、その下のMarkdownには「なぜこの色を使うのか」「このボタンスタイルはどんな場面で使うのか」「どんなパターンは避けるべきか」といったデザイン判断の基準を書きます。つまり、単なるスタイルガイドではなく、Claude Code、Cursor、CodexのようなAIコーディングエージェントが毎回参照する「デザインシステムの原本ファイル」に近いものです。
背景 — 整理しながら改めて確認した変化
• 以前の問い: 「デザインシステムをFigmaにどううまく整理するか」
• 今の問い: 「AIコーディングツールに私たちのデザインシステムをどう読ませるか」「新しいページを作るとき、AIに私たちのブランドの色・間隔・コンポーネント規則を守らせるには何が必要か」
• Claude Design、Claude Code、Figma MCPのような流れと噛み合いながら、デザインシステムがFigmaの中だけにとどまらずコードベースへ入り、PRでレビューされ、AIエージェントの「継続的なコンテキスト」になる変化
DESIGN.mdフォーマットの核心（仕様を読みながら印象深かった点）
• YAML（機械用）+ Markdown（人間・AI用）の二重構造 — トークンは機械がパースし、本文は人が判断根拠を残す層
• トークンが正解、本文は理由 — 両者が食い違ったときにどちらを信頼するかという優先順位をあらかじめ定めている点が明快
• 8つのセクション順序が固定 — colors、typography、spacing、componentsなど、セクション自体がデザインシステムのメンタルモデルとして機能
• lint / diff / export / spec CLI — 壊れた参照、コントラスト不足、孤立トークン、セクション順序違反のような項目を自動チェック
• DTCG、Tailwind、Figma Variablesとの相互運用ポリシーを別途明示
カリキュラム構成（28チャプター、7モジュール）
• M1 フォーマット哲学 · 3チャプター — このフォーマットが解こうとする問題、二重構造、トークン・本文の優先順位
• M2 トークンスキーマ · 5チャプター — スキーマ全体 / 色 / 長さ・単位 / フォント / トークン参照
• M3 セクション構造 · 6チャプター — 8つのセクション順序と各セクションの設計原則
• M4 実例を読む · 3チャプター — Atmospheric Glass、Paws & Paths、Totality Festivalのケース
• M5 CLI · 4チャプター — lint、diff、export、spec
• M6 リント規則 · 4チャプター — broken-ref、contrast、orphaned、section-orderなど8項目
• M7 拡張性 · 2チャプター — 不明な内容の処理ポリシー、DTCG・Tailwindとの関係
• 最終整理 · 1チャプター — 27チャプター要約 + 実務に持ち帰れる原則10個
整理しながら感じたこと
• AIがUIをより多く作るようになるほど、デザインシステムはむしろさらに重要になる気がします。問題は「AIがデザインを上手にできるか」ではなく、「AIが従うべき基準をチームがどれだけ明確に残しているか」へ移っているようです
• DESIGN.mdは、その基準をNotionやPDFではなくコードベースの中に置こうとする実用的な試みです。デザイナーの成果物がPR単位のレビュー対象になるという意味でもあります
• デザインシステムを作っている方や、AIコーディングツールでUIを作りながら「なぜ成果物が毎回ばらばらなのか」と感じたことのある方に一緒に見てもらえたらと思い、共有します。誤って理解してまとめた部分があれば、コメントでお知らせいただければ反映します。
2件のコメント
気になる点があるのですが、DESIGN.md はデザインを引き出すための指示書と考えると、結局は最初の数ページ、あるいは 1 ページのムードボードを生成するために使われるものですよね。その後はコードと指示.md の間で不一致が発生して、継続的に双方向の同期が必要になるのではないでしょうか?
結局、その後のデザインはコードを source of truth と見て、一貫性を保ちながら変数や名前のようなものを再利用すべきだと思います。DESIGN.md を継続的に更新して SSoT として管理しない限り、結局トークンをハードコーディングし続けることになるのではないかという気がします。実際の運用でこうした問題は起きないのか気になります。
DESIGN.md => コードの方向性は自動化しやすい一方で、逆にコードに新しく生まれたパターンをDESIGN.mdへ反映することは自動化できず、人が直接面倒を見る必要があるようでした。時間が経つとコードには細かなハードコーディングが積み重なるのに、文書には反映されないことが蓄積していきます。
ただ、このフォーマットの哲学自体が「デザインシステムをコードベースの中で継続的に育てていく」という方向なので、これは欠点というより意図された運用方法に近いと見ています。NotionやPDFに固定していたガイドをPR単位のレビュー対象へ引き下ろしたぶん、人が定期的に手を入れる責任も一緒についてくる構造のようです。私たちのプロジェクトにも導入してみましたが、導入前より画面の一貫性が確実に向上し、その効果を実感できたので手動レビューも負担には感じませんでした。結局、AIが従うべき基準をチームがどれだけ明確に残しておけるかの問題であり、その基準を生きたものとして維持する手入れまでは人が担う構造なのだと整理するようになりました。