AtlassianのDESIGN.md公開 - ポータブルなデザインコンテキストを実践で検証して得た教訓

• AIが生成するUIがブランドの独自性を失って画一化する "slop" 問題を解決するための ポータブルなMarkdownフォーマット で、デザインシステムの中核要素を1つのファイルにまとめてプロンプトへ含める方式
• DESIGN.mdは、機械可読の デザイントークン と、人間・エージェントが読む デザインの根拠(rationale) の2部で構成され、システム全体の技術仕様ではなく 意図(intent) を収める
• Team '26のキーノートデモで Figma Make によるダッシュボード生成へ適用した結果、色・間隔・形状・タイポグラフィがAtlassianのシステムに沿って整い、ワンショットのプロトタイプでは良好な性能を示した
• ただし本番コードベースでは、自社の MCPサーバー・skills と比べてトークン消費が約92%増え、生成時間も伸び、実行ごとのトークン消費のばらつきも約2.7倍となり、効率は低下した
• ポータビリティと簡潔さという固有の強みは、クロスプラットフォーム移植、顧客テーマ設定、新しい環境でのプロトタイピング に価値があり、豊富なデザインシステムツールを置き換えるのではなく補完する位置づけ

---

背景 - AI UIの「slop」問題

• AIがUIを生成すると、グラデーションのボタン、すべて大文字の見出し、ありふれたカードレイアウト、不要なホバーアニメーションなど、似たような結果になりやすく、機能はしても視覚的なアイデンティティが欠けがち
• デザインコミュニティでは、こうした成果物を "slop" と呼んでおり、機能的ではあっても意図されたデザイン判断がない出力を指す
• 原因はブランド・コンポーネント・パターンに関するコンテキスト不足で、AIは学習データの平均値へ寄った既定出力を返してしまう → "Generic in, generic out"
• Atlassianのデザインシステムチームは、AI時代に向けた コンテキストエンジン を構築中で、ADS MCPサーバー と詳細なAI skillsを通じて、エージェントに豊富なデザインコンテキストを提供している
  • これによりAIのトークンコスト削減と、何千人ものプロダクトビルダーが生成する成果物の精度・品質向上を確認している

DESIGN.md概要

• Googleが自社の Stitch デザインツール向けに設計したオープンソースのMarkdownフォーマットで、チームのブランドやUIパターンを収めた移植可能なスナップショット
• ファイルをプロンプトに含めると、生成結果が自社製品らしく見え始めるというシンプルな仕組み

• 何であるか (What it is)

  • デザインシステムの中核要素だけを記述したポータブルなMarkdownファイル
  • 最初の部分では機械可読向けに デザイントークン を列挙
  • 2つ目の部分では人間・エージェント向けに、色・間隔・レイアウト・elevation・コンポーネントなどの デザインの根拠 を記述

• 何ではないか (What it isn't)

  • 本番環境でデザインシステムが動作するための完全な技術仕様や、システムの完全な詳細情報ではない
  • 既存のコードライブラリ、コーディング標準を保つためのlinter、Figma上の詳細なデザイン仕様は含まない
  • 仕様では、このフォーマットをシステム全体の詳細ではなく意図(intent) の把握として位置づけている

独自のDESIGN.md構築

• Atlassianは、MCPサーバー、構造化コンテンツパイプライン、多様なエージェントskillsを通じて、デザインシステムをAIが消費しやすい形へ整備してきた
• MCPとエージェントskillsを支える同じ 構造化コンテンツパイプライン から独自のDESIGN.mdを生成
• 一般的なvibe codingツールでフォーマットをテストし、既存ガイドにはなかったよくあるミスに対して、より厳格な指針を追加した

Team '26でのテスト

• 1か月前にアナハイムで締めくくられたTeam '26キーノートデモが、ちょうどよい検証事例として使われた
• キーノートのあるデモでは、Figma Make が Teamwork Graph を使ってカスタムダッシュボードを生成し、内部のMCPサーバーやツールに依存せず一発でデザイン言語を合わせることが目標だった
• DESIGN.mdを適用すると、ありがちな「slop」から、色・間隔・形状・タイポグラフィで期待どおりの値を使い、コンポーネントにもシステムに整合したelevationを適用するなど、Atlassianらしいと認識できる成果物へ変わった
• ファイル内の高レベルな指針と仕様は、Tailwind や Shadcn のような共通ライブラリをカスタマイズし、UIをゼロから生成する用途に向いている

本番適用時のトレードオフ

• 本番コードベースは、既存のトークンやコンポーネントライブラリ、厳格なlintルールと型チェックが適用された環境であり、ゼロから作る隔離環境とは大きく異なる
• ユーザーログイン画面のような単純な作業で、DESIGN.mdを唯一のデザインガイドとして使うと、トークン消費が約92%増え、生成時間も長くなり、実行ごとのトークン消費のばらつきも約2.7倍になった
  • ただし、この結果は決定的ではなく、モデル・プロンプト・デザインシステム・環境・コンテキスト品質によって変わりうることも明記している

• 限界1 - コンテキストがオンデマンドではなく一括で渡される

  • MCPサーバーは ads_plan のような tool call で、特定コンポーネントに関する指針だけをオンデマンドで取得する
  • 何百ものアイコンや膨大なセマンティックデザイントークンといった重い部分で、不要な項目の読み込みを避けられる
  • DESIGN.mdは毎回全体を読み込むため、最初からコストが高く応答も遅くなり、ターン数が少ないとコンテキストが切れて精度が落ちる可能性がある

• 限界2 - ファイルを短く保つとコンテキストが失われる

  • デザインシステムは、何千ものビュー、Figmaファイル、フロントエンドコンポーネントの共有言語を圧縮した複雑な対象
  • オンデマンドのMCPとskillsは約2.5 MBの指針へ蒸留されている一方、DESIGN.mdは一括読み込みのため、はるかに強い圧縮が必要
  • 結果のファイルは80 KB、約19,800 LLMトークン（frontmatter除き約10,700）で、コミュニティの例と比べても大きい部類
  • このサイズに収めるため、50以上のコンポーネントの利用指針のかなりの部分を削り、基本指針も大幅に縮小し、使用頻度の低いデザイントークンも一部削除した
  • コンテキスト欠落のため、本番品質を目指すエージェントでは精度が下がるか、自らコンテキストを集めたり、仕様にない利用指針を探そうとしてコンポーネント実装そのものを読む傾向が見られた

• 限界3 - 仕様がデザインシステムの内部を露出する

  • DESIGN.mdは、デザインシステムを散文で書き直した移植可能なスナップショットであり、システムをゼロから複製実装するための原則・仕様・指針を提供することが目的
  • 確立された本番環境ではこの情報は不要だったり、エージェントを 技術的負債(tech debt) の生成へ誘導したりすることがあり、とくにコンポーネントで顕著
  • ボタンのスタイル全体の詳細（backgroundColor、textColor、borderColorなど）を読んで解釈するより、既存コンポーネントをimportして使うほうが望ましい
    • 例: import Button from '@atlaskit/button'; の後に <Button appearance="primary" spacing="compact" />
  • 共有コンポーネントの利用は保守性に不可欠で、ボタンを1か所で変更すればコードベース全体へ反映でき、コードレビューや保守も容易になる
  • DESIGN.mdはコード上の指針を意図的に除外し、再実装仕様だけを提供するため、テストでは既存システムを使うよりコンポーネントを再生成する傾向が強かった
  • MCPサーバーとskillsは、技術基盤に根ざしたより適切な抽象化レベルを提供し、再実装の案内ではなく既存システムを使うための説明書として機能する
  • これを、トークン消費なしでコーディング標準を強制する lintルール と組み合わせることで、エージェントに前向きなフィードバックループを形成できる

DESIGN.mdが最も有用な場面

• 高レベルな芸術的方向性 (High-level artistic direction)

  • 最もシンプルなDESIGN.mdは、システムの視覚的方向性や雰囲気に集中でき、それをまだ文書化していないなら有用な成果物になる
  • ただしfrontmatterは、すでにコードベースにある内容を重複している

• 不慣れな環境での高速プロトタイピング

  • blue-skyプロトタイピングや新しいツールのテストでは、技術スタック全体の構築や既存コンポーネントの制約を気にせず、ブランドに沿ったUI生成を支援する

• デザインツールとの相互運用性 (Interoperability)

  • 一部のAIツールは、デザイン言語に合わせた既製コンポーネントをカスタマイズしてUIを組み立てるため、DESIGN.mdはそうしたツールに適した粒度の指針を与える

• 適応型UIのための顧客テーマ設定 (Customer theming)

  • レポート・チャート・ダッシュボードなど、動的なインターフェース生成が必要な製品では、顧客が自社ブランドを簡単に記述できるようにし、AI出力を顧客ブランドらしく感じさせられる
  • 管理者やブランドチームが業務ツールへアップロードする選択肢として構想できる
• これらに共通するのは、既存のデザインシステム出力が使えない、あるいは実用的でない環境でのエージェント生成UIという点

はじめ方と標準への貢献

• Atlassianは標準に反応するのではなく形作りたいという考えから、自社のDESIGN.mdファイルを atlassian.design/DESIGN.md で公開した
• 自社ファイルは現行標準といくつか差異があり、コンポーネント描画用の非標準属性を含み、標準がテーマ設定を未サポートのため 別のダークモード版 も提供している
• GitHubでフィードバックを共有しており、いくつかの提案はすでに仕様へ反映されている。業界全体での参加も呼びかけている

結論

• DESIGN.mdはデザインシステムのスナップショットとして有用なポータブルフォーマットだが、より豊かなデザインシステムツールの代替ではない
• エージェントがMCPやskillsをサポートしていれば、より低コストでより良い結果を得られる
• クロスプラットフォーム移植、顧客テーマ設定、blue-skyプロトタイピングでは、よく構造化されたDESIGN.mdが意味のある改善をもたらす
• デザインシステムがAIにとって可読になることで、エコシステム全体が利益を得る