Google LabsがStitchプロジェクトで提案したDESIGN.md形式が興味深く、数日かけて仕様を読み込んだうえで、自分だけで見て終わらせるのはもったいないと思い、韓国語で解きほぐして全28章のカリキュラム形式にまとめておきました。同じテーマを学ぶ方が最初から英語の仕様を調べ回らなくても済むように、そして私のように「AIにデザインシステムをどう読ませるか」という問いを持っている方が一度に見渡せるように、という感覚で作業しました。
DESIGN.mdは、デザインシステムをMarkdownファイル1つで表現しようとするフォーマットです。色・タイポグラフィ・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変数との相互運用ポリシーを別途明示
カリキュラム構成（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 lintルール・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が従うべき基準をチームがどれだけ明確に残しておけるかの問題であり、その基準を生きたものとして維持する手入れまでは人が担う構造なのだと整理するようになりました。