株式会社パレットリンクの @BaspisKawaE です。
今回はDESIGN.mdと、それに伴って自己開発したツールを紹介いたします。
よろしくお願いします！

第0章本記事が紹介する対象

0.0 本記事を読むための前提知識

本記事は複数の読者層を想定している。
読み進めるうえで知っておくと理解が早まる用語を、最初に一覧化する。
「これは何だろう」と感じた用語があれば、対応する章に飛んで確認できるように設計した。
すべて理解してから読み進める必要はない。
必要に応じて参照する読み方を想定している。

用語	何を指すか(極めて簡潔に)	詳細を解説する場所
DESIGN.md	AIに渡すデザイン仕様書	第1章(成立経緯と仕様全体)
フロントエンド / UI / プロトタイプ	Webサイトやアプリの「見た目」に関する領域	第1章 §1.2
HTML / CSS / JavaScript	Webページを作るための3つの基本言語	第1章 §1.2
AIコーディングエージェント	自然言語の指示でコードを書くAI(Claude Code・Cursor・GitHub Copilot等)	第1章 §1.5.1
デザイントークン	色・フォント・余白といったデザインの構成値	第1章 §1.5.2
YAML / Markdown	機械にも人間にも読みやすい記述形式	第1章 §1.5.2
CLI(コマンドラインツール)	ターミナルから操作するソフトウェア	第1章 §1.6.1
オープンソース / MIT / Apache 2.0	ソフトウェアを共有する際のライセンス形式	第0章 §0.2、第1章 §1.6
Google Stitch / awesome-design-md / designmd.me	DESIGN.mdを扱う既存の3つの主要手段	第2章 §2.1〜§2.3
Playwright	実際のブラウザを自動操作する仕組み	第3章 §3.4.1
Node.js / npm	JavaScriptをブラウザ外で動かす環境	第0章 §0.4(シナリオA前提)
Claude Codeのスキル機構	プロジェクトに応じた手順をAIに学習させる仕組み	第0章 §0.3
VANILLA / INTERPRETED / DESIGN(三段階の文書)	本ツールキットが生成する3種類の文書	第0章 §0.3、第3章 §3.1
lexicon / patterns	DESIGN.md生成時に参照される辞書と経験則	第0章 §0.3、第3章 §3.2
`[要確認]` マーカー	文書内で「保留」を明示する記号	第0章 §0.3、第3章 §3.1

このリストは網羅的ではない。
読み始める時点で知っておくと迷わない最小限の用語である。
記事中で初めて使う技術用語は、本文内で都度補足することとする。

0.1 本記事の構成と読み進め方

本記事は、AIに対してデザインを記述する仕様書「DESIGN.md」を、抽出と生成の両方向で扱うために私が構築・配布したツールキットについて論じるものである。

論述の縦軸として、本記事は次の流れを採る。
第1章で、DESIGN.mdを巡る世間の熱狂的言説を記録する。
第2章で、既存3手段の実態を検証して、その言説との距離を観察する。
第3章以降では、その距離を私自身の手で埋めようとした試みを論じる。
世間の熱狂が約束したものを、ある個人が部分的にせよ自身の手で実現しようとした応答として、本ツールキットを位置づけたい。

想定する読者は複数の層にわたる。

AIを用いてUIを構築している開発者および設計者。Claude CodeやCursorを日常的に利用し、生成結果のデザインが揺れることに課題感を持つ者。
フロントエンドへの関心はあるものの、初学者寄りの位置にある者。DESIGN.mdという語は認識しつつ、今後の導入を検討している者。
独自のツール・スキルを設計している、あるいは設計しようとしている技術者。他者の設計事例から自身のワークフローへの示唆を得ようとする者。

これら複数層の読者を同時に想定するため、技術用語は初出の箇所で、即座に括弧書きで補足することとする。

本記事の章構成は以下の通りである。

第0章(本章): 構築されたツールキットの全体像と利用方法 ― 結論および到達点の先行提示
第1章: DESIGN.mdという概念の成立経緯と、その技術的構造
第2章: 既存のDESIGN.md生成手段を、同一の実在サイトに対して適用した場合の比較検証
第3章以降: 本ツールキットの設計判断と、AI時代のデザイン記述における観測と推測の分離

初学者寄りの読者は、第1章から順に読み進めることで理解が容易になる。
DESIGN.mdの概念を既に把握している読者は、第2章から読み始めても論旨に支障はない。
リポジトリの中身から確認したい読者は、本章を読んだ後にGitHubを開き、必要に応じて他章に遡ることもできる。

0.2 本記事が紹介する対象

本記事で紹介するのは、私がGitHub上で公開している以下のリポジトリである。

MaryCache/advanced-design-md

MITライセンスの下で公開しており、誰でもクローン・改変・利用が可能である。
MITライセンスとは、オープンソースソフトウェアで広く使われる緩いライセンス形式である。
著作権表示とライセンス条文を含めれば、商用・非商用を問わず自由に利用・改変・再配布できる。
日本語のREADMEに加え、英語版README、および「とりあえず動かしたい人向け」のQUICKSTARTを同梱している。

本リポジトリは、Claude Code(Anthropic社が提供するAIコーディングツール)向けの2つのスキルを組み合わせたツールキットとして設計されている。

design-extractor: 任意のURLからデザイン情報を抽出し、機械的観測と意味付け解釈を分離した形式で記録する
design-creator: 言語化されていない要望をクイズ形式で引き出し、構造化されたDESIGN.mdを生成する

要約すれば、「実在するサイトを観察してデザインを言語化する」方向と、「漠然とした要望をデザイン仕様に落とす」方向の、2つの異なる流れを同じ語彙体系の上で統合したツールキットである。

公式のGoogle Stitchや、既存のオープンソースリポジトリ(awesome-design-md等)とは異なる設計判断を複数含む。
相違点および設計判断の理由は、第2章以降で詳述する。
本章では、本リポジトリの内容と利用法の提示に限る。

0.3 リポジトリの構成

全体構造

advanced-design-md/
├── README.md ← 日本語版の主たる文書
├── README.en.md ← 英語版
├── QUICKSTART.md ← 簡易導入手順(日本語)
├── LICENSE ← MIT
├── settings.recommended.json ← Claude Code推奨権限
└── skills/
 ├── design-extractor/ ← URL → VANILLA.md / INTERPRETED.md
 │ ├── SKILL.md
 │ ├── package.json
 │ ├── scripts/fetch.js
 │ └── references/
 └── design-creator/ ← クイズ → DESIGN.md
 ├── SKILL.md
 ├── references/
 │ ├── question-bank.md ← 設問プール(20問・7層)
 │ ├── prompt-format.md ← 完了プロンプト仕様
 │ ├── extractor-handoff.md ← 補助抽出オファー手順
 │ ├── lexicon/ ← colors / typography / animations / parts辞書
 │ ├── patterns/ ← mood × use組み合わせ経験則
 │ ├── templates/ ← DESIGN.md空テンプレート
 │ └── samples/ ← 用途別サンプル
 └── assets/
 └── quiz.html ← 静的HTMLクイズ(JA/EN)

2つのスキルと、その関係

本ツールキットの中核は、skills/ 配下に置かれた2つのClaude Codeスキルである。
Claude Codeにはスキル機構(プロジェクトに応じた処理手順をAIに学習させる仕組み)があり、本リポジトリの2スキルもその上に実装されている。

design-extractor(抽出側)は、対象サイトのURLを入力として、以下の3つを生成する。

raw/: Playwright(Microsoftが公開するブラウザ自動化ツール)で取得したDOM・CSS・JavaScript・挙動ログの生データ
VANILLA.md: サイトから機械的に観測された値のみを記述した記録層。推測・補完・創作は一切含まない
INTERPRETED.md: VANILLA.mdを唯一の入力として、各要素に名前・印象(tone)・機能(effect)などの意味付けを加えた解釈層

design-creator(生成側)は、ユーザーの要望をクイズで引き出し、以下を生成する。

quiz-{name}.html: 回答済みのクイズHTML(履歴・再編集用に保存される)
DESIGN.md: クイズ回答を元に、辞書(lexicon)と経験則(patterns)を参照して組み立てた仕様書

両スキルは独立して動作可能である。
ただし、design-creatorは特定条件下でdesign-extractorを呼び出す権限を持つ(後述のStep 9補助抽出オファー)。
これにより、辞書だけでは表現できない固有ブランドへの言及を、参照サイトの抽出により補完できる。
連携は creator → extractorの単方向である。
extractor側からcreatorを呼ぶ経路は存在しない。

三段階の文書 ― VANILLA / INTERPRETED / DESIGN

本ツールキットは、目的の異なる3種類のMarkdown文書を生成する。
これが最も特徴的な設計判断である。

文書	生成元	役割	推測の許容
VANILLA.md	design-extractor	観測された事実のみを記述する	一切禁止
INTERPRETED.md	design-extractor	VANILLAを元にした意味付け・解釈	VANILLAに存在する範囲内のみ
DESIGN.md	design-creator	クイズ回答 + 辞書から組み立てた仕様書	辞書(lexicon)に存在する範囲内のみ

3種類とも以下の同じセクション構成を持つ。

## {先頭セクション} ← Meta(VANILLA/INTERPRETED) または Intent(DESIGN)
## Colors
## Typography
## Spacing
## Components
## Animations
## Constraints

先頭セクションのみが文書ごとに異なる。
VANILLA.mdとINTERPRETED.mdの先頭は ## Meta(取得元URL・抽出日)、DESIGN.mdの先頭は ## Intent(用途・ターゲット・第一印象軸など)となる。
これにより、後段の実装フェーズで3種類の文書を統一的に扱える。

なぜこの3層構造を採るのか。
既存のDESIGN.md生成手段の多くが、観測された事実とAIによる推測を文中で混在させて記述しているためである。
この混在は、AIへの引き渡し時に重大な問題を生む。
詳細は第2章および第3章で論じる。

lexicon と patterns の役割

design-creatorは、辞書(lexicon)と経験則(patterns) という2種類の参照データに依拠する。
これはAIがDESIGN.mdを「自由に書く」のではなく、事前に定義された語彙の中から選ぶようにするための装置である。

種別	パス	役割
lexicon	`references/lexicon/{colors,typography,animations,parts}.md`	何が使用可能かを定義する辞書
patterns	`references/patterns/{color-combos,animation-recipes,component-defaults}.md`	何と何が併用されやすいかの経験則

DESIGN.mdには、lexiconに存在する語彙のみが記録される。
利用者の自由入力でlexiconに該当しない語(例えば「Apple風」)は、原文のまま [要確認] というマーカーとして保持される。
これにより、「lexicon由来の選定」と「利用者独自の要望」が視覚的に区別され、実装フェーズで追加指示が必要な箇所が明示される。

`[要確認]` というマーカー

DESIGN.md / VANILLA.md / INTERPRETED.mdには、しばしば [要確認] という記号が現れる。
これは「不具合」や「欠落」ではなく、保留の明示である。
具体的には、以下のいずれかを示す。

観測または辞書に該当値が存在せず、AIが選定を保留した
ユーザーの自由入力が原文のまま保持され、後段で人間判断を要する
volume(後述)制約により設問が出題されず、値を確定できなかった

この記号があることで、実装フェーズの担当者は追加指示が必要な箇所を即座に把握できる。
「AIが知らないことを知らないと言える」設計が、本ツールキットの中核的な思想の一つである。

0.4 利用方法 ― 2つのシナリオ

本リポジトリの利用方法は、目的に応じて2通りに分かれる。
両者は独立して使用できる。

シナリオ A: 既存サイトからの抽出(design-extractor)

「他サイトの設計手法を観測したい」「自身が手本としたいサイトをDESIGN.md化したい」という読者を対象とする。

前提: Claude Codeが導入済みであること。Node.js 18以上が使用可能であること。

手順(対話の流れ):

ユーザー: このサイトを抽出してくださいhttps://www.apple.com
Claude: 保存フォルダ名(スラグ)を指定してください。
 例: apple-home / google-store / microsoft-corp
ユーザー: apple-home
Claude: → fetch.jsによりDOM / CSS / JSを取得
 → VANILLA.mdを生成(生抽出・推測補完なし)
 → INTERPRETED.mdを生成(VANILLAを意味付け解釈)
 → meta.yamlを生成
 ✓ 保存先: ~/my-design-library/sites/apple-home/

生成される成果物の構成:

<output-base>/apple-home/
├── raw/ # fetch結果(dom.html, styles/, scripts/, behavior-log.json)
├── VANILLA.md # 生抽出
├── INTERPRETED.md # 意味付け解釈
└── meta.yaml # 取得元URL、タグ、メモ

スキルの内部処理は第3章で詳述する。
要点を示せば、「動的レンダリング後のHTML/CSS/JSを取得」し、「アニメーションライブラリをJavaScript本体の署名から判定」し、「Claudeが自然言語として整形」するという3段構成である。

シナリオ B: ヒアリングによる新規仕様生成(design-creator)

「クライアントの曖昧な要望を仕様書に落としたい」「新規プロダクトのデザインシステムを起こしたい」という読者を対象とする。

手順(対話の流れ):

ユーザー: コーポレートサイトのデザインを検討したい
Claude: ボリュームを選択してください。
 - quick (5問・5分) → [要確認] が約50% 残存する想定
 - standard (10問・10分) → [要確認] 30% 以下
 - deep (20問・20分) → [要確認] 20% 以下
ユーザー: standard
Claude: → quiz-corporate-modern.htmlをlocalhostで配信
 → ブラウザで開き設問に回答してください
 → 回答完了後、出力プロンプトを貼り付けてください

ユーザーはブラウザでクイズに回答し、完了ボタンで生成された自然文プロンプトをClaudeに貼り付ける。
Claudeは以下を実行する。

Claude: → 回答プロンプトをパース
 → lexiconと照合(colors / typography / animations / parts)
 → patternsを参照(mood × useの組み合わせ経験則)
 → DESIGN.mdを生成
 ✓ 保存先: ~/.claude/outbox/DESIGN-corporate-modern.md

クイズの構造 ― 7レイヤー × 20設問

design-creatorのクイズは、7レイヤー × 20設問の固定プールから、選択したvolumeに応じて出題される。

layer	主目的	設問数	DESIGN.mdへの反映先
intent	用途・第一印象軸・差別化軸	4	`## Intent` セクション全項目
mood	明度・温度・エネルギー・形式感	4	Mood・Constraintsの派生
visual	配色戦略・アクセント戦略・質感	3	`## Colors` パレット選定
typography	Serif/Sans比率・日本語系統	2	`## Typography` テーブル
motion	テンポ・キャラクター・採用ライブラリ	3	`## Animations`
component	レイアウト型・必要パーツ群	2	`## Components` 構成
technical	デバイス優先度・外部依存許容度	2	`## Constraints` 制約条項

クイズには重要な設計判断が組み込まれている。
完了プロンプトには、選択されなかった選択肢も含めて全項目が記録される。
これによりClaudeは、「ユーザーがlightとの比較の上でdarkを選択した」といった排除された方向性を推論材料として活用できる。

補助抽出オファー(Step 9 Handoff)

クイズの自由入力に「Apple風」「ある特定のゲームのような」など固有名詞や辞書外の語が含まれる場合、Claudeは次のような提案を行う。

「Apple風」のニュアンスはlexiconのみでは表現が困難です。
参照可能なサイトURLがあれば抽出を実行可能ですが、いかがいたしますか? (yes / no)

yes と回答すると、design-creatorは背後でdesign-extractorを呼び出す。
抽出結果(INTERPRETED.md)は辞書と同格に扱われ、DESIGN.md生成へ反映される。採用された値には  というコメントが必ず付される。
後の監査時に「lexicon由来か、抽出由来か」を識別できるようにするためである。

これにより、シナリオA(抽出)とシナリオB(生成)が機能的に統合される。
要望を出発点とし、必要に応じて参照サイトを観測し、結果を生成に反映する流れが、ユーザーの判断を介在させながら成立する。

DESIGN.md の実装フェーズへの引き継ぎ

仕様書を起点とした実装には、複数の選択肢がある。
本ツールキットは、実装そのものは担わない設計である。

方法	概要
手動実装	DESIGN.mdを仕様書として参照し、HTML / CSS / Tailwind等を直接実装
自作スキル	DESIGN.mdを読み込みモックHTMLを生成するClaude Codeスキルを構築
他AIツール	DESIGN.mdをv0 / Lovable / Cursor等に投入し初稿を生成

3種類の文書(VANILLA / INTERPRETED / DESIGN)は同系統のセクション構成を採用しているため、実装側はいずれの文書も統一的に扱える。

0.5 本章のまとめ

本章では、advanced-design-mdの全体像 ―

2つのClaude Codeスキル(design-extractor / design-creator)
3種類の文書(VANILLA.md / INTERPRETED.md / DESIGN.md)による三段階の構造
辞書(lexicon)と経験則(patterns)による語彙制約
[要確認] マーカーによる保留の明示
7レイヤー × 20設問のクイズと、選ばれなかった選択肢の保持
Step 9による2スキルの単方向連携

および、2通りの利用シナリオを提示した。

シナリオAは「実在するサイトを観測して言語化する」流れである。
シナリオBは「漠然とした要望を構造化する」流れである。
両者は独立して使用できる一方、Step 9の補助抽出オファーを通じて統合的にも機能する。

次章以降は、この形態を採った経緯を遡る。
第1章では、DESIGN.mdという概念の成立史と、公式仕様の構造を整理する。
第2章では、既存のDESIGN.md生成手段を実在サイトにおいて検証する。
第3章以降で、本ツールキットの設計判断 ― 観測と推測の分離、辞書による語彙制約、保留の明示 ― を論じる。

読み進めるにつれ、本稿の論述対象は段階的に拡張される。
単なるツール紹介から、AI時代のデザイン記述という新たな領域における設計問題へと、論じる対象が広がっていく構造を採っている。
章を選択的に参照する読み方にも、順次読み進める読み方にも対応する設計である。

第1章 DESIGN.mdの誕生と意義

1.1 要約 ― DESIGN.mdとは何か

DESIGN.mdとは、ある製品やブランドのデザインシステム ― 色・タイポグラフィ・余白・コンポーネントの形 ― を、AIが読みやすい一つのテキストファイルにまとめたものを指す。
プロジェクトのフォルダにこのファイルが置かれていると、AIコーディングエージェントはセッションごとに「このサービスはどんな見た目を持つべきか」を毎回説明されなくても、自律的にブランドに沿ったUIを組み立てられるようになる。

人間の開発者にとってのREADMEが「このプロジェクトは何で、どう動かすか」を伝える文書であるならば、DESIGN.mdはそれと同じ位置づけを、デザインのために用意するものである。
「このブランドはどのような見た目を持ち、なぜそうなのか」をAIに伝える規範的な文書として機能する。
Claude Code・Cursor・GitHub Copilotをはじめとする任意のAIコーディングエージェント(自然言語の指示を受けてコードを書くAI)が、セッションを跨いで一貫した設計システムの理解を保持できるようにすること ― これが目的である。

DESIGN.mdという考え方は2026年3月、Google Labsが公開している実験的AIデザインツール Stitch の大型アップデートにおいて、その内部機能として最初に導入された。
本章では、StitchのローンチからDESIGN.md提唱に至る経緯を確認する。
その後に2026年4月21日のオープンソース化を経て現在に至るまでの流れを整理する。

1.2 前史 ― Stitchという実験の素地

DESIGN.mdの導入を理解するには、その器となったStitchの前史を辿る必要がある。

Stitchは2025年5月20日、Google I/O 2025で発表された実験的なAIデザインツールである。
Google Labsが運用する実験プロダクトとして、自然言語の指示や画像からWeb・モバイルアプリのUIモックアップを生成し、生成された画面のHTML・CSS・Figma互換コードを書き出せるという、当時としては野心的なツールであった。
基盤モデルにはGemini 2.5 Proが用いられ、ベータ版として一般公開された。

ローンチ時点のStitchには、後にDESIGN.mdとして結実するものは存在しない。
あくまで「自然言語と画像からUIを作る」ツールとして、FigmaやGalileo AIの文脈に位置づけられる。
生成されるのは個別の画面とそのコードであり、ブランド全体の設計システムを記述する仕組みは備わっていなかった。

この時期、Stitchは 「言葉からUIを作る」最初の試行 として注目を集めつつも、生成結果の一貫性 ― 例えば連続して生成した画面の間で色味が微妙に揺れる、フォントサイズが画面ごとに変わる、ボタンの形が安定しない ― という課題を抱えていた。
これはStitchだけの問題ではなく、AIによるUI生成全般に共通する課題であった。
この課題への一つの回答が、後のDESIGN.mdである。

1.3 2026年3月のStitch大型アップデートとDESIGN.mdの導入

2026年3月19日、Stitchは大規模なアップデートを受けた。
このアップデートはStitchを単一画面の生成ツールから、Google自身が「AIネイティブなソフトウェアデザインキャンバス」と呼ぶ統合作業空間へと変えた。
主な追加機能は以下の通り。

(1) 無限キャンバス: アイデアの発想から動くプロトタイプまでを、一つの広い空間で発散できるAI向けキャンバス。
テキスト・画像・コードを同じ空間に並べて参考資料として扱える。

(2) Vibe Design(バイブデザイン): ワイヤーフレーム(画面構造の下書き)から始めるのではなく、ビジネス目的・ユーザに感じてほしい雰囲気・現在のインスピレーションを説明するところからデザインを開始できる対話的なモード。

(3) デザインエージェント: プロジェクト全体の進化を跨いで考えられるAIアシスタント。
制作開始から完了までを伴走する。

(4) 最大5画面の同時生成とユーザジャーニー地図化: 相互に接続された複数画面を同時に生成し、画面間の遷移を自動的に地図化する。
「Play」ボタンで即座に動作確認できる。

(5) 音声対話: Gemini Live(リアルタイム会話型AI)を基盤とする音声対話機能。
キャンバスに向かって話しかけるとデザイン批評が返ってきたり、「3種類のメニュー案を出して」「この画面を別のカラーパレットで見せて」といった指示でリアルタイムに更新できる。

(6) 任意URLからのデザインシステム抽出: 既存WebサイトのURLを入力すると、その色・タイポグラフィ・レイアウトを解析する。

(7) MCPサーバとSDK: Cursor・Antigravity・Gemini CLIなどの外部AIツールからStitchの機能を呼び出せるようにする仕組み。
MCP(Model Context Protocol)とはAIと外部ツールをつなぐための共通プロトコルである。

(8) 7種のフレームワークへのコード出力: HTML/CSS, Tailwind, Vue.js, Angular, Flutter, SwiftUI等、実運用で使われる主要な実装方式にそのまま移行できるコードを出力する。

そしてこの2026年3月のアップデートで、DESIGN.mdはStitchの一機能として初めて導入された。
Googleの公式ブログはその目的をこう説明している。

デザインツールキットを、より深い文脈を持った制作を可能にするように拡張した。
任意のURLからデザインシステムを抽出できるようになり、あるいは新しいDESIGN.md― エージェント(AI)向けのMarkdownファイル ― を使って、他のデザインツールやコーディングツールへ/からデザインルールをエクスポート(書き出し)・インポート(読み込み)できるようになった。

ここで注目すべきは、DESIGN.mdが次の二つの役割を同時に担っていた点である。

他ツールへの書き出し形式(export): Stitch内で作ったデザインを、Claude CodeやCursorなどの外部AIコーディングツールに渡すための中間の形式。
他ツールからの取り込み形式(import): 外部で書かれたデザインをStitchプロジェクトに適用する入力の形式。

この双方向性は、DESIGN.mdが最初から「Stitch単体で閉じないこと」を意図していたことを示す。
そしてこの3月の時点で、生成されたDESIGN.mdはStitchのUI上で閲覧でき、ファイルとして取得・コピーすることができた。
Stitchを使えば誰でも、自分のプロジェクトのDESIGN.mdを手元に持ち帰り、Claude CodeやCursorに渡すことができた。

ただし、後述する4月21日のオープンソース化までの間は、正式な仕様書(spec)は公開されていなかった。
書式の構造を理解するには、Stitchが生成する出力例を観察し、そこから書式を逆算する必要があった。
検証手段(後述の lint のような機械的チェック)も存在しなかった。

Stitchの現在の提供条件を記録として付記する。
2026年4月時点でGoogle Labsの実験として無料で提供されており、標準モード(Gemini 3.0 FlashまたはGemini 2.5 Flash)で月350回、実験モード(Gemini 3.0 ProまたはGemini 2.5 Pro)で月200回の生成が可能である。
ただしLabs実験としての性質上、長期的な提供や価格体系は保証されていない。

1.4 オープンソース化以前から始まっていた動き

§1.3の末尾に記したコピペ可能性 ― これが本記事の論述において重要な意味を持つ。
DESIGN.mdは2026年4月21日のオープンソース化を待たずに、既に外部世界で動き始めていた。
本節ではその動きを整理する。

1.4.1 Stitchを経由しない手書きの可能性

DESIGN.mdはYAML(機械が読みやすい、キーと値のペアで書くシンプルな記法)とMarkdownという汎用的な形式で構成されている。
特殊なバイナリ形式ではなく、テキストエディタで開ける一般的なファイルだった。
この性質により、Stitchが出力したDESIGN.mdを観察すれば、書式の構造は人間にも把握できた。

つまり理屈の上では、Stitchの出力例を参考に、誰でも自分のテキストエディタを開いてDESIGN.mdを手書きすることが可能だった。
「うちのブランドは深い紺色(#0A1A3F)を基調とする。
理由は信頼感と静けさを表現するため」と書き、それをプロジェクトのフォルダに置いてClaude Codeに渡す ― これだけで、実質的なDESIGN.mdとして機能した。
Stitchを経由する必要はなかった。

1.4.2 派生ツール・キュレーションの先行

この自由度を活用して、オープンソース化以前から複数の動きが進んでいた。

designmd.me のような外部Webツールは、ユーザがフォームに入力した情報からDESIGN.mdを生成するサービスとして、独自に展開していた。
Stitchとは無関係に動作し、自前の解釈でDESIGN.mdを組み立てていた。
本記事では第2章でこの実装の精度を検証する。

awesome-design-md リポジトリは、Apple・Stripe・Linearなど著名ブランドのデザインをDESIGN.md化したサンプル集として、コミュニティ主導でキュレーションされていた。
これもStitchを介さず、人間の手作業による解釈で書かれたファイルの集積であった。

そして筆者(私)自身の advanced-design-md ツールキット ― 本記事が紹介する対象 ― も、オープンソース化以前から開発を進めていた。
Stitch出力の構造を観察し、独自に拡張(特に動きを記述するAnimationsセクションの追加)を施したDESIGN.mdを生成・抽出するためのスキル群として組み上げていた。

1.4.3 既に開かれていたもの、まだ開かれていなかったもの

以上から分かるのは、「考え方」と「読める形」は元々開かれていた ということである。
コピペで取得できる以上、書式を観察することは誰にでもできた。
それを真似て手書きすることも、独自に拡張することも、別の生成ツールを作ることも、原理的には可能だった。

一方で、まだ開かれていなかったもの もある。

正式な仕様書(spec) ―Stitch出力例から逆算するしかなく、ブレが残った
書式準拠を機械的に検証する手段 ― 人間の目視に頼るしかなかった
ライセンスの法的な明確さ ―Stitch出力を改変・再配布する際の権利関係が曖昧だった
Apache 2.0のような外部貢献を受け入れる枠組み ― 仕様の進化に外部から関与する経路がなかった

オープンソース化はこの「まだ開かれていなかったもの」を解放する転換点であった。
次節以降では、まずオープンソース化を待たずに既に動いていたDESIGN.mdの本質を整理し(§1.5)、その上で4月21日のオープンソース化が 何を新たに加えたか を確認する(§1.6)。

1.5 DESIGN.mdの本質 ― 仕様書という「考え方」と、その一つの書き方

§1.4で確認した通り、DESIGN.mdはStitchという器の中から生まれたが、その器に閉じ込められていなかった。
本節では、本仕様について一つの大事な区別を立てておきたい。

1.5.1 「AIに渡すデザイン仕様書」という考え方

Webサイトやアプリの「フロントエンド」とは、ユーザの目に触れる部分 ― 色・文字・レイアウト・ボタンの形など、画面上で見えるすべての要素 ― を指す。
従来、デザイナーがフロントエンドの仕様を伝える手段は、Figmaなどのデザインツールで作ったビジュアルのモックアップや、色のコードやフォントサイズをまとめた説明書(スタイルガイド)であった。
これらは主に 人間の開発者 に向けて書かれていた。

しかし生成AIがコードを書く時代に入ると、新たな読み手が現れた。
Claude Code、Cursor、GitHub Copilotのような AIコーディングエージェント である。
これらは文章の指示からコードを生成するが、ブランドの色やフォントといったデザイン固有の情報をセッションごとに繰り返し指示しなければならず、一貫性を保つのが難しかった。
「ダッシュボードを私のブランドカラーで作って」と指示しても、汎用的な青いボタンが並んだ出力が返ってくる。
手で修正し、もう一度指示し直し、次のコンポーネントでは違う見た目が出てくる ― そういう反復が当たり前になっていた。

「AIが読める、言葉で書かれたデザイン仕様書」というアイデア自体は、ここでひとつの独立した考え方として成立する。
特定のツールに依存しない。
特定の書き方に縛られない。
本質は次の一点に尽きる ― 色やフォントといった機械が読める値と、その値が存在する理由の自然な説明を、AIが読める形でひとつの文書にまとめること。

1.5.2 Stitchが実演したのは「具体的な一つの書き方」

ではGoogle Stitchが2026年3月に導入した「DESIGN.md機能」は何をしたのか。

Stitchがしたのは、この抽象的な考え方を、具体的で真似しやすい書式として実演したこと である。
Stitchが生成するDESIGN.mdは「これだけの細かさで、これだけ構造化すれば、AIはここまでデザインを一貫して作れる」という参考の型を提示するものであった。

具体的には次のような構造である。

ファイルの冒頭に、色・タイポグラフィ・余白といった値(これをデザイントークンと呼ぶ)をYAML形式で並べる
その後に続く本文で、「なぜその値なのか」を自然な言葉で記述する
{colors.primary} のような記法で、値と値のつながりを明示する(たとえばボタンの背景色はこの色を使う、と指定する)
決まった8つのセクション(Overview/Colors/Typography/Layout/Elevation & Depth/Shapes/Components/Do's and Don'ts)を、決まった順番で並べる

これらは 考え方として必須というわけではなく、Stitchが選んだ一つの設計判断 である。
YAMLという書式でなくても考え方は成立する。
8セクションでなくても成立する。
Stitchはあくまで「こう書けば十分に機能する」という一つのお手本を世に出したのである。

そして§1.4で確認した通り、この実演はStitch出力のコピペを通じて広く参照可能だった。
書式は誰でも観察でき、誰でも真似でき、誰でも拡張できた。
awesome-design-md・designmd.meなどの動きは、まさにこの参照可能性の上で進んでいた。

1.5.3 公式準拠と独自拡張の二択

この区別は、実用上の選択肢に直結する。
利用者は次のどちらの立場も取れる。

(A) 公式の書き方に従う: Stitch由来の書式で書き、互換エージェントとの相互運用性(違うツール同士でも同じファイルを読めて、同じように解釈される性質)を最大化する。
OpenAPIがREST API(サーバとやり取りするための共通ルールを記述する標準)に対して果たしたような「業界標準」としてのDESIGN.mdに乗る道である。

(B) 考え方だけ引き継ぎ、独自の書き方を採る: AIに渡すデザイン仕様書という思想は共有しつつ、記述形式を自分の使い方(例: アニメーションや状態変化をもっと細かく書きたい)に合わせて拡張する。
公式書式との完全な互換性は部分的に犠牲になるが、表現の自由度は高い。

どちらも正当な選択肢である。
advanced-design-mdは(B)の立場をとり、特に「動きを記述する領域」の不足を独自拡張で埋めている(これは第3章で詳述する)。

1.6 2026年4月21日 ― 慣習から契約書へ

Stitchの内部機能としてDESIGN.mdが導入されてからおよそ一ヶ月後、2026年4月21日に重要な節目が訪れる。
Google Labsはこの日、DESIGN.mdのドラフト仕様をGitHubリポジトリ google-labs-code/design.md 上で Apache 2.0ライセンス の下に公開した。

§1.4で整理した通り、DESIGN.mdはオープンソース化以前から「コピペで取得でき」「手書きで書ける」状態にあった。
本節では、その上で4月21日のオープンソース化が 何を新たに加えたか を整理する。

1.6.1 オープンソース化「以後」に追加されたもの

公開されたGitHubリポジトリには、以下が含まれている。

(1) 正式仕様書 docs/spec.md ― これまでStitch出力例から逆算するしかなかった書式が、Google Labs自身による正式な記述として公開された。
トークンスキーマ・参照記法・必須セクションの構造が、正規の参照点を持つようになった。

(2) CLIツール @google/design.md(初版0.1.1) ―DESIGN.mdを機械的に検証・変換するためのコマンド群が、npmパッケージとして公開された。
主なサブコマンドは以下の通り。

lint: 仕様への準拠を検証し、トークン参照の不整合・WCAGコントラスト比違反・循環参照などを構造化されたJSONで報告する
diff: 二つのバージョンのDESIGN.mdを比較し、トークンレベルの追加・削除・変更と本文の回帰を検出する
export: DESIGN.mdのトークンをTailwind CSSテーマやW3C DTCG(Design Tokens Community Group)形式に書き出す
spec: 仕様書本体をAIプロンプトに注入する用途のために出力する

(3) Apache 2.0ライセンス ― 派生物の再配布・改変が法的に明確化された。
それまでStitch出力をどこまで改変・再配布できるかは曖昧であったが、Apache 2.0の下では特許条項(特許侵害訴訟からの保護)も含めて企業利用での安心感が担保される。

(4) stitch-skills リポジトリの同時公開 ―Claude Code・Cursor・Antigravity・Gemini CLIなど各種AIコーディングエージェントから利用可能な「Agent Skills」のライブラリが、別リポジトリとして公開された。
design-md スキルはStitch MCPサーバを経由してプロジェクトの画面・HTML・メタデータを取得し、DESIGN.mdを生成する。

(5) 正式バージョニング(alpha 0.1.1) ― 仕様の進化を追跡できるバージョン番号が付与された。
alpha段階であり「仕様変更を予期せよ」と明記されているが、互換性議論ができる土台が整った。

1.6.2 「ゼロからの解放」ではなく「既に進行していた動きへの正式な合流地点」

これらが追加されたことの意味は、しばしば「StitchからDESIGN.mdが解き放たれた」という言い方で表現される。
例えばawesomeagents.aiの評論記事は、本オープンソース化を「Stitchという内部慣習(internal Stitch convention)を、ブランドとAIエージェントの間の、持ち運び可能な契約書(portable contract)に変えた」と表現している。
慣習から契約書へ ― この比喩は実態を的確に捉えている。

ただしここで、§1.4で整理した文脈を改めて重ねる必要がある。
Stitch出力をコピペで取得できた以上、「使えること」は元々開かれていた。
awesome-design-md・designmd.me・本記事が紹介するadvanced-design-mdは、いずれもオープンソース化を待たずに動いていた。
これらはコピペ可能性の上で、それぞれ独自の解釈・拡張・キュレーションを進めていた。

オープンソース化が解放したのは、「使えること」ではなく「正式な参照点を共有できること」 である。
これまで個別に進んでいた動きが、共通の仕様書・共通の検証ツール・共通のライセンス的安心感の下に合流できる土台が、4月21日に用意された。

つまりオープンソース化は ゼロからの解放ではなく、既に進行していた動きへの正式な合流地点 として位置づけるのが、より正確な理解である。

1.6.3 公開後の反応

リポジトリは公開直後から急速な注目を集めた。
本章執筆時点(2026年4月24日)で既にスター数(GitHub上でのブックマーク相当)6,200超、フォーク(複製して自分の改変版を作った件数)600超を記録している。
awesomeagents.aiの評論は「公開から72時間で5,200スター、awesome-design-mdは64,000スターを突破」と報じている。

GitHub Topicsの design-md タグには、Chrome/Firefox/Edgeの各ブラウザ拡張、独自のCLI、著名サイトから抽出したDESIGN.mdの集積リポジトリなどが、短期間のうちに積み上がりつつある。
Anthropicの公式skillsリポジトリでも、frontend-designスキルへのDESIGN.md統合提案が議論されている。
「設計システムの記述をAIに渡すための共通の書き方」という問題設定は、もはやGoogle単独の構想ではない。

1.7 提唱以降の熱狂 ― X(Twitter)で交わされた期待

DESIGN.md― とくにawesome-design-mdと4月21日のオープンソース化を巡る ― 反響は、X(Twitter)上で2026年3月下旬から急速に拡大した。
本節では、その熱狂を当時の発言として記録に残す。
本章執筆時点で本仕様の登場から1ヶ月強しか経過していないが、その短い期間に交わされた言説の温度は、本論の後段(第2章)で示す実態とのコントラストにおいて意味を持つ。

X上での代表的な発言を引用形式で示す。

awesome-design-mdというGitHubリポジトリを発見した。
Apple、Stripe、Linearといった有名ブランドのDESIGN.mdがそのまま入っている。
これは公式じゃないけど、信じられない。
誰でも一流ブランドの設計システムを自分のプロジェクトに引き込める時代になった。

DESIGN.mdをCursorに放り込んでみたら、最初の30秒でブランドそのまま色味で何もかも返してきた。
これが当たり前になったらフロントエンドの初稿はもう手作業で書く時代じゃない。

面白いのは、これがコードじゃなくてMarkdownだってこと。
誰でも書ける。
デザイナーが直接AIに向かって書ける。
GitHubにコミットして、PRでレビューして、AIに消費させる。
設計システムがGitで動く時代が来た。

AppleのDESIGN.mdがあるってことは、どんなウェブサイトでもスキャンして瞬時に再構築できるってことだ。
これ、世界が変わるよ。
5分で終わる。

これら4本以外にも、awesome-design-mdリポジトリの存在とDESIGN.mdのオープンソース化を結びつけて「プロのデザインシステムを誰もが手元に取り込める」「大手企業の参入障壁が取り払われた」と表現する投稿が相次いだ。
投稿には数万から100万を超える表示数が付き、「誰でもプロデザイナーになれる」という期待が広く共有された。

これらの発言の背景には、AIコーディングエージェントを用いた開発における実感のある問題がある。
すなわち「AIにUIを作らせると毎回デザインが揺れる」「色が微妙に違う、フォントサイズが統一されない、ボタンの形が毎回変わる」という一貫性の崩壊だ。
DESIGN.mdはまさにこの問題への回答として提示された。
AIが毎回このファイルを読んでからコードを書くから、ブランドの一貫性が自動で保たれる ― これがDESIGN.md推進の基本線である。

さらにawesome-design-mdリポジトリの存在と4月21日のオープンソース化は、この基本線にもうひとつの魅力を加えた。
AppleやStripeやLinearのような世界的ブランドのデザインシステムが、無料で、マークダウンファイル一つで、手元のプロジェクトに引き込める ― 書くことすら必要ない。
この「すでに書かれたもの」を使える手軽さが、開発者とデザイナーの双方に対して強いメッセージを放った。

DESIGN.mdという考え方の成立から、Stitchによるひとつの具体化、3月の大型アップデートでの導入、それと並行して進んでいた外部の動き(awesome-design-md / designmd.me / 個人プロジェクトの派生)、そして4月21日のオープンソース化による合流まで ― 本章ではこの一連の経緯を時系列で追った。
オープンソース化は熱狂の開始点ではなく、既に進行していた動きが共通の参照点の下に合流した一つの節目 として位置づけられる。

次章では、この熱狂の実態を検証する。
「どんなウェブサイトでも瞬時にDESIGN.md化できる」と語られた手段が、具体的に何を生み出すのか。
オープンソース化以前から動いていた既存3手段(Google Stitch・designmd.me・awesome-design-md)を同じ実在サイトに対して適用し、その出力を観察する。

第2章既存のDESIGN.md生成手段の実態検証

2.0 検証の方法

第1章で述べた通り、DESIGN.mdへの熱狂は2026年3月のStitch提唱以降すでにX(Twitter)上で広がっており、その言説は「どんなウェブサイトでもスキャンして、デザインシステムを瞬時に再構築できる」という趣旨を含んでいた。
4月21日のオープンソース化は、この既に進行していた動きが共通の参照点の下に合流した節目であり、熱狂そのものはそれ以前から継続していた。
本章はこの言説に対する実態調査として、同一の実在サイトを対象に、既存のDESIGN.md生成手段3つを適用し、出力を比較する。

比較を行うためには、まず比較基準そのものを定める必要がある。
本節ではこの基準について述べる。

2.0.1 比較基準 ― VANILLA.mdとは何か

本章における比較の参照軸は、本ツールキットが独自に定義する VANILLA.md である。
VANILLA.mdとは、対象サイトから観測された事実のみを記述し、推測・補完・創作を一切含めない記録層である。
第0章で予告した二段モデル(VANILLA / INTERPRETED)のうち、観測のみを担う層に位置する。
本章で比較の基準として用いるため、最低限の仕様を先に示す。

生成方法:

Playwright(Microsoftが公開するブラウザ自動化ツール。ChromeやFirefoxを自動操作できる)により、対象URLを実際のブラウザで読み込む
JavaScriptによって動的に生成された後のHTML・CSS・JavaScriptを全て取得する
アニメーションライブラリはURLの文字列判定ではなく、JavaScript本体のコード内容(メソッド呼び出し等の署名)から識別する
取得した全資源をClaudeが読み込み、観測された値のみを整形して記述する
Chromeがサイトによってブロックされる場合、Firefoxに自動で切り替えて再取得する

記述上の原則:

観測された事実のみを記述する。「このサイトにありそうな一般的な値」は記述しない
観測できなかった項目は、空欄にせず [未取得] と明記する
取得できなかった理由が判明している場合は [未取得: requires_scroll](スクロール前で未発火)、[未取得: lazy_loaded](遅延読み込みで初期DOMに未存在)のように理由を付記する
JavaScriptで動的に値が変更される要素は [動的: JS制御] と明示する

この原則は、VANILLA.mdが**「記述されていないことを記述する」能力を持つ**ことを意味する。
「知らないことを黙って補完する」ことを構造的に禁止しているため、観測の限界がそのまま記録される。

本章における用途:

本検証では、私自身がdesign-extractorを実行して取得した複数のサイトのVANILLA.mdを比較基準として用いる。
これらは対象サイトから直接観測された事実の集積である。
本章では、既存の3手段の出力をこのVANILLA.mdと照合し、出力内の各記述が観測事実と一致するか、推測・創作によるものかを判定する。

VANILLA.md自体の設計思想 ― なぜ観測と推測を分離するか、二段モデルにおいてVANILLAを観測専用の層に置く意義は何か ― は、第3章で論じる。
本章では比較基準としての機能に限って使用することとする。

2.0.2 検証対象の3手段

検証対象とする手段は以下の3つである。

Google Stitch: 2026年3月の大型アップデートで導入された、DESIGN.md規格の提唱者であるGoogle自身のツール。URLを与えるとDESIGN.mdを自動生成する
designmd.me: 第三者(Crowdlinker社)が公開する、任意のURLからDESIGN.mdを生成するWebアプリケーション
awesome-design-md: VoltAgent社が運営する、大企業の公開サイトを手動で抽出したDESIGN.mdのキュレーション型リポジトリ。利用者自身は抽出せず、収録済みのファイルを利用する

2.0.3 判定基準と公平性

本章では、公平性のため次の原則を守る。

対象サイトは固定: 原則として「魔法使いの約束1st Anniversary」(mahoyaku.com/1st/)を使用する。ただしawesome-design-mdは国内サイトを収録していないため、その比較には「linear.app)を使用する
VANILLA.mdと照合する: 各出力の色値・タイポグラフィ・コンポーネント仕様等が、VANILLA.mdに記録された観測値と一致するかを判定する
解釈の妥当性ではなく、観測された事実との一致度を判定基準とする。例えば「deep navyという印象」の妥当性は問わず、出力された具体値(例: #05101A)がVANILLA.md記載値(例: #07161f)と一致するかを問う

以降、各手段の出力を個別に検討する。

2.1 Google Stitch ― 題材の先入観が創作を誘発する

2.1.1 出力の概観

Google Stitchにmahoyaku-1stのURLを与えた結果、生成されたDESIGN.mdは約40行であった。
公式仕様が規定する8セクション(Overview / Colors / Typography / Layout / Elevation & Depth / Shapes / Components / Do's and Don'ts)のうち、実際に埋められたのは6セクションにとどまった。

# Design System: Promise of Wizard 1st Anniversary (Mahoyaku)
## Brand Personality
- Mystical & Magical
- Elegant & Sophisticated
- Celebratory
- Celestial
## Color Palette
### Primary Colors
- Midnight Navy (#05101A)
- Radiant Gold (#D4AF37)
- Starry White (#FDFDFD)
### Secondary Colors
- Celestial Blue (#1A3A5A)
- Sunlight Amber (#FFD700)
## Typography
### Headings
- Primary: Cormorant Garamond または Cinzel
- Secondary: Playfair Display または Montserrat
### Body
- Noto Sans JP または Inter
...

2.1.2 VANILLA.mdとの照合

mahoyaku-1stのVANILLA.mdに記録された色は、次の3値のみである。

#07161f (body 背景・ブラインド・モーダル)
#debb54 (body テキスト・リンク)
rgba(7,22,31,0.85) (モーダルオーバーレイ)

Stitchの出力とVANILLA.mdを対応させると、以下の通りになる。

項目	VANILLA.md	Stitch出力
背景	`#07161f`	`#05101A`(不一致)
ゴールド	`#debb54`	`#D4AF37`(不一致)
テキスト	画像化された要素が多く、CSS上はほぼ白のモーダル内のみ	`#FDFDFD`
Secondary Blue	存在しない	`#1A3A5A`(創作)
Sunlight Amber	存在しない	`#FFD700`(創作)

VANILLA.mdと一致する色は1件もない。
背景とゴールドは同系統の色ではあるが、桁単位で値が異なる。
#05101A は「深い紺」という印象に基づいてAIが再構築した値であり、#D4AF37 は「アンティークゴールド」として一般に流通する既成の色値である。
さらに "Celestial Blue" と "Sunlight Amber" は、VANILLA.mdに記録されていない色を、世界観(celestial=天体的)に基づいて追加している。

タイポグラフィも同様の傾向を示す。

項目	VANILLA.md	Stitch出力
見出し	`-apple-system, Noto Sans JP, 游ゴシック` (システムフォント)	"Cormorant GaramondまたはCinzel"(推奨例)
本文	同上 + 多くのテキスト要素が画像化	"Noto Sans JPまたはInter"

Stitchの出力は全てのフォント指定に "e.g., ..." 形式の推奨例しか記載しておらず、VANILLA.mdに記録された実際のフォントスタックを抽出していない。
これは観測結果ではなく、「celestial系デザインに合うフォント」という一般的な推奨である。

2.1.3 題材の先入観がもたらす汚染 ― JJKの場合

同じStitchを呪術廻戦キャラクターページ(jjk-character)に適用すると、異なる形での問題が顕在化する。
出力されたDESIGN.mdのOverviewセクションには、次のような記述が現れた。

1. Overview & Creative North Star: "Cursed Brutalism"

This design system is a high-energy, editorial framework inspired by the supernatural tension and raw power of the Jujutsu Kaisen universe. Our Creative North Star is Cursed Brutalism.

... we move beyond the template by utilizing intentional asymmetry, overlapping typography, and "Cursed Energy" accents that pierce through a monolithic dark background.

"Cursed Brutalism" という設計哲学名、"Ghost Borders"、"Ambient Light Bleed"、"Cursed Energy Progress Bars" といった造語が多数現れる。
この記述は、読み物として極めて魅力的である。

しかしjjk-characterのVANILLA.mdと照合すると、以下の乖離が明らかになる。

色: VANILLA.mdには赤系(crimson)は一切記録されていないが、Stitchは "Blood Crimson" をPrimary/Secondaryの核として配置している
タイポグラフィ: VANILLA.mdはCinzel + 游明朝 + Noto Serif JP(セリフ・明朝主導)だが、StitchはSpace Grotesk + Inter(モダンサンセリフ)を推奨している
Brutalism哲学: VANILLA.mdのletter-spacing 0.07em、line-height 1.8、明朝主導のデザインは、本来editorialでelegantな美学に属する。Brutalismとは対極的な設計である
"Cursed Energy Progress Bars": VANILLA.mdにプログレスバーは記録されていない

Stitchは対象サイトの「原作(呪術廻戦)」の先入観から、サイトの実装とは無関係の設計哲学を創作している。
より一般的に表現すれば、AIが持つ題材への既成イメージが強いほど、観測を無視した「魅力的な創作」に流れる傾向が観察される。

2.1.4 観察の整理

Stitchの2件の出力から得られる所見は以下の通りである。

色値・フォント名といった機械的に抽出可能な情報ですらVANILLA.mdと一致していない
Componentsセクションの記述に数値(padding・border-radius・height等)がほぼ含まれない
「Generous Whitespace」等の情景描写的記述にspacingの具体値が伴わない
題材に関するAIの事前知識が強い場合、観測を無視した哲学的フレーミングが発生する
公式自身が規定した8セクション規約を、Stitch自身の出力が満たしていない

Stitchの役割はDESIGN.mdという概念の実演であり、仕様の提案者としての影響力は大きい。
しかし「任意のサイトからDESIGN.mdを抽出する実用ツール」としての精度は、本検証の範囲ではVANILLA.mdへの忠実性を欠く。

2.2 designmd.me ― 観測と推測の区別が構造的に存在しない

2.2.1 出力の概観

designmd.meにmahoyaku-1stのURLを与えた結果、生成されたDESIGN.mdは約300行で、9セクション(awesome-design-mdが提案する拡張構成に準拠)がほぼ全て埋まっていた。
色は7色、タイポグラフィは9階層、Componentsは11種が記述された。

量の観点ではStitchを大きく上回る。
しかし内容を検証すると、別種の問題が現れる。

2.2.2 色の検証

designmd.meが出力した7色をVANILLA.mdと照合する。

色名	出力値	VANILLA.mdにおける対応
Golden Accent	`#DEBB54`	VANILLA.mdに記録あり(`#debb54`)
Deep Background	`#07161F`	VANILLA.mdに記録あり(`#07161f`)
White	`#FFFFFF`	VANILLA.mdに記録あり(モーダル内のみ使用)
Secondary Blue	`#5A8FBA`	VANILLA.mdに記録なし
Deep Navy	`#004986`	VANILLA.mdに記録なし
Link Primary	`#5A8FBA`	上記を流用(VANILLA.mdと無関係)
Link Secondary	`#004986`	上記を流用(VANILLA.mdと無関係)

7色中3色はVANILLA.mdと一致するが、残り4色はVANILLA.mdに記録されていない値である。
特筆すべきは、記録されていない4色に対して「Secondary Blue」「Link Primary」といった役割名が割り振られている点である。
読み手は、これらが観測された役割分担であると受け取る構造になっている。

Stitchが全色を別値に置き換えたのに対し、designmd.meは3色を正確に抽出し、そこに4色を創作して混ぜている。
この混合は、Stitchよりも判別を困難にする。
部分的に観測を含むため、全体が観測されたかのような印象を与える。

2.2.3 タイポグラフィの検証

mahoyaku-1stのVANILLA.mdに記録されたCSSレベルのタイポグラフィ情報は、次の通りである。

font-family: システムフォントスタック(-apple-system, ..., Noto Sans JP)
font-size: body 14px(PC)/ 3.73vw(SP)、見出しは18px / 12px / 10px等
font-weight: 300の明示的指定のみ(Noto Sans JPに対して)

さらに重要な事実として、VANILLA.mdは「テキスト要素は画像(.png)で代替されているケースが多い。
全体デザインはCSS + 画像ファイルで構成」と明記している。

designmd.meの出力は、以下のタイポグラフィ階層を提示する。

Role	Size	Weight
Display / H1	48px	700
Heading / H2	32px	700
Heading / H3	24px	700
Body Large	16px	400
Body	14px	400

48px / 32px / 24pxの見出しサイズも、weight 700の使用も、VANILLA.mdには記録されていない。
これは「典型的なWebサイトにはこのような階層があるはずだ」という既成の知識に基づく記述である。
サイト固有の事実(テキストが画像化されている、CSS上のweight指定は300のみである)は、出力から完全に欠落している。

2.2.4 コンポーネントの検証

designmd.meが記述する11種のコンポーネントのうち、VANILLA.mdに記録されているものと記録されていないものを整理する。

出力されたコンポーネント	VANILLA.mdにおける記録
Primary Button (344×52px)	記録なし(このサイトに明示的なCTAボタンは存在しない)
Secondary Button (344×52px)	記録なし
Ghost Button	記録なし
Standard Card	記録なし
Ornamental Container	記録なし
Text Input	記録なし(入力フォームは存在しない)
Textarea	記録なし
Form Label	記録なし
Breadcrumb Navigation	記録なし
Status Badge (Success)	記録なし
Accent Badge	記録なし

記述された11種のうち、VANILLA.mdに記録されているものは1つもない。
にもかかわらず、出力には 344×52px、border: 1px solid #DEBB54 といった具体的な数値が付されている。
この具体性が、出力を観測結果であるかのように見せる効果を持つ。

2.2.5 観察の整理

designmd.meの出力の特性は、以下の通りである。

基本的な色・背景色の抽出は部分的に成功している(主要3色はVANILLA.mdと一致)
抽出に失敗した情報を、AIの既成知識で補完している。そしてその補完箇所に観測との区別を示す記号が付されない
存在しないコンポーネントを、具体的な数値付きで記述する
動的要素(JSで制御されるアニメーション、jQueryによる挙動等)が完全に欠落している

出力形式としてはawesome-design-mdが提案する9セクション構成を踏襲しているため、形式の充実度が高く見える。
しかし充実度と観測精度は独立しており、形式が整っているほど、読み手が出力を信頼する傾向があるという点で、この種のツールはStitchよりも注意深い扱いを要する。

2.3 awesome-design-md ― 精度は比較的高いが、射程が限定される

2.3.1 リポジトリの性格

awesome-design-mdは前2者とは質が異なる。
これはツールではなく、既に抽出されたDESIGN.mdのキュレーションである。
2026年4月時点で55件前後の大企業サイト(Apple / Stripe / Linear / Spotify / Vercel / Notion等)のDESIGN.mdを収録している。
利用者はリポジトリから目的に合うDESIGN.mdを選択し、自身のプロジェクトにコピーする。

重要な制約として、本リポジトリは国内サイトを収録していない。
対象の55件は全て英語圏の大企業である。
したがってmahoyaku-1stやjjk-characterのような日本国内のコンテンツ系サイトに対しては、そもそもデータが存在しない。

この制約のため、本節では代替としてLinearのDESIGN.mdを検証対象とし、本ツールキットのlinear-app/VANILLA.mdと照合する。

2.3.2 LinearのDESIGN.mdの検証

awesome-design-mdが収録するLinearのDESIGN.mdは、約500行にわたる詳細な記述である。
以下に特徴的な箇所を抜粋する。

色の記述:

- Marketing Black (#010102 / #08090a)
- Panel Dark (#0f1011)
- Level 3 Surface (#191a1b)
- Primary Text (#f7f8f8)
- Brand Indigo (#5e6ad2)
...

linear-appのVANILLA.mdと照合すると、#010102 #08090a #0f1011 #191a1b #f7f8f8 #5e6ad2 は全てVANILLA.mdに記録されている。
透過ボーダー(rgba(255,255,255,0.05))や状態色(#27a644, #eb5757 等)も正確に記述されている。

タイポグラフィの記述:

- Primary: Inter Variable (OpenType features "cv01", "ss03" enabled globally)
- Monospace: Berkeley Mono
- Weight 510 is the signature weight
- Letter-spacing at display sizes: -1.584px at 72px, -1.056px at 48px

OpenType featuresの具体値、signature weightの510、display sizeでの負のletter-spacingの具体値まで、VANILLA.mdと一致する。
単なる「font-family: Inter」ではなく、Linear固有のカスタマイズまで記述されている。

2.3.3 観測精度の評価

awesome-design-mdのLinear DESIGN.mdは、前2者と比較して明確に精度が高い。
少なくとも色・タイポグラフィ・spacingスケールに関しては、VANILLA.mdと一致する値が多数含まれる。
これは手動抽出のキュレーションという性格上、当然の結果ではある。
AIによる自動抽出ではなく、人間がサイトを実際に解析して書き起こしているため、観測精度は高水準である。

ただし同時に、以下の限界も観察される。

2.3.4 欠落する情報の層

(a) 動きの記述

LinearサイトのVANILLA.mdには、次のアニメーションが記録されている。

hero-pulse: box-shadow 0→10px rgba(243,79,82,0), 1.75s cubic-bezier(.66,0,0,1) infinite
text-shine: background-position 0→300%, 1.8s linear infinite
glass-fade: backdrop-filter blur(1.5px) + mask-image gradient
marquee-scroll: 水平/垂直無限ループ
hover-snap: .16s var(--ease-out-quad) による全インタラクション統一
press-shrink: transform scale(.97) active state
3D hero: transform: rotateX(47deg) rotateY(31deg) rotate(324deg) + perspective:4000px
Radix UI Navigationのdropdown状態遷移アニメーション

awesome-design-mdのLinear DESIGN.mdには、これらが一切記述されていない。
「Visual Theme & Atmosphere」セクションに「dark-mode-first product design」等の印象的な記述があるものの、実際のアニメーション仕様は欠落している。

これはawesome-design-md単体の欠陥ではなく、採用している9セクション構成にアニメーション記述領域が存在しないという構造的な制約である。
Stitch純正の8セクションと同様、動きを記述する場所がない。

(b) 推測と観測の区別

awesome-design-mdは、推測された記述に (Inferred) という注記を一部のコンポーネントに付している。
例えば以下のような記述がある。

**Primary Brand Button (Inferred)**
- Background: #5e6ad2 (brand indigo)
- Text: #ffffff
- Padding: 8px 16px
- Radius: 6px

(Inferred) は「推定」を意味する。
この注記により、当該コンポーネントの仕様が実測ではなく推測であることが読み手に示される。
これは前2者にはない誠実な設計判断である。

しかし同じDESIGN.mdの他のコンポーネント(Ghost Button、Subtle Button等)にはこの注記がない。
観測と推測の区別は部分的であり、体系的ではない。
読み手は、注記のない箇所を観測値と解釈することになるが、実際のところ注記の有無が観測・推測の境界に対応しているのか判別できない。

(c) 記述対象の偏り

awesome-design-mdに収録される55件は、全て以下の特性を共有する ―

英語圏の企業サイト
開発者向けプロダクトが多数(Linear / Stripe / Vercel / Supabase / Cursor等)
モダンなCSS変数体系とフレームワーク(React / Next.js等)を採用
デザインシステムが社内で体系化されている

この偏りは、リポジトリが「デザインシステムが整った企業サイト」を前提とした収録方針を採っているためである。
対象として日本国内のゲーム・アニメ系サイト、TweenMaxやjQueryによる古い実装、テキストが画像化されたサイト等は射程外となる。

2.3.5 観察の整理

awesome-design-mdの特性は、以下のように整理できる。

色・タイポグラフィ・spacingの抽出精度は高い(手動キュレーションの成果)
動きの記述は欠落する(9セクション構成の構造的制約)
推測と観測の区別は部分的で、体系的ではない
収録対象が英語圏の大企業デザインシステムに偏る
利用者自身は抽出できず、収録されているもののみを利用可能

設計思想としては「AIによる自動抽出の不正確さ」を手動キュレーションで補う方針であり、精度面での優位は認められる。
しかし動きを扱わない、日本語圏を扱わない、利用者の自己抽出を許容しないという構造的な限界は、本リポジトリの性質上、解消されない。

2.4 3手段に共通する構造的欠陥

前3節の検証から、手段別の特性差は明らかとなった。
一方で、3手段すべてに共通する欠陥もまた浮かび上がる。
本節ではこの共通構造を整理する。

2.4.1 アニメーション記述領域の不在

3手段はいずれも、動きの層を体系的に記述する領域を持たない。

Stitch: 公式の8セクション構成にアニメーション項目がない
designmd.me: 9セクション構成を採用するが、動きの記述は含まない
awesome-design-md: 9セクション構成を採用するが、動きの記述は含まない

この欠落は、各手段の実装品質の問題ではなく、DESIGN.mdという書式自体が静的スナップショットを前提としているという設計上の前提に起因する。
色・タイポグラフィ・余白・影・形状・コンポーネント・Do's and Don'ts― これらはいずれもある時点における見た目の記述である。
時間軸を持つ情報(hover遷移、scroll連動、keyframe、状態変化)を記述する枠組みが仕様に存在しない。

この欠落の重大性は、対象サイトの性質によって変動する。
Linearのような静的マーケティングサイトでは、アニメーションは補助的な要素に留まるため、欠落の影響は部分的である。
一方、mahoyaku-1stのようなアニメーションが個性を担うサイトでは、動きを記述できないことがそのままサイト固有性の喪失を意味する。

2.4.2 観測と推測の混在

程度の差はあるものの、3手段のいずれも、観測された事実とAIによる推測を文中で明示的に区別していない。

Stitch: 区別なし。観測も推測も同じ文体で記述される
designmd.me: 区別なし。観測値と創作値が同じ形式で並列される
awesome-design-md: (Inferred) 注記が部分的に存在するが体系的ではない

この混在は、AI引き渡し時に重大な問題を引き起こす。
DESIGN.mdを受け取ったAIエージェントは、記述された内容を実装すべき仕様として解釈する。
推測された値と観測された値の区別がない場合、AIは全てを等しく実装要件として扱い、結果として「架空の値に基づく架空のデザイン」が生成される可能性がある。

「AIに正確にデザインを引き渡す」ことがDESIGN.mdの目的である以上、記述内容の真正性を担保する仕組みが不可欠である。
しかし現行の3手段はこの仕組みを持たない。

対照的に、比較基準としたVANILLA.mdは「観測された事実のみを記述する」という原則と「未取得は [未取得] と明記する」というルールにより、記述された内容が観測に裏打ちされていることを構造的に保証する。
本章で3手段との照合が成立したのは、この保証があったからである。

2.4.3 題材への先入観に汚染される脆弱性

StitchのJJK例で観察された「題材の既成イメージが記述を汚染する」現象は、程度の差はあれdesignmd.meにも観察される。
mahoyaku-1stに対するdesignmd.meの出力は、「celestial(天体的)」「magical(魔法的)」という題材連想から、VANILLA.mdに記録されていない色(Celestial Blue、Sunlight Amberに相当する補色)を導入していた。
awesome-design-mdは手動キュレーションであるため題材汚染は相対的に少ないものの、Visual Themeセクションにおける詩的記述(「content emerges from darkness like starlight」等)は、書き手の印象に基づく解釈を含む。

題材汚染が発生する原因は、抽出対象サイトに対するAIの事前知識が、観測を上書きするためである。
特に有名な題材(呪術廻戦、Apple、Linear等)はAIの訓練データに豊富に含まれるため、観測を見る前からAIは当該題材の印象を持っている。
この事前知識は、しばしば観測結果よりも記述を支配する。

2.4.4 利用者の自己抽出能力の欠如または制限

Stitch: 任意URLから抽出可能だが、精度がVANILLA.mdと著しく乖離する
designmd.me: 任意URLから抽出可能だが、精度の問題はStitchと同質
awesome-design-md: 任意URLからの抽出機能を持たない(収録物の利用のみ)

利用者が「自分が参照したいサイトのDESIGN.mdを得る」手段として、3手段はそれぞれ制約を持つ。
自動抽出系(Stitch・designmd.me)は精度が低く、キュレーション系(awesome-design-md)は選択肢が固定される。
利用者が自身の参照先を、実態を歪めない形で、自ら選択・抽出する手段が、既存の3選択肢の中には存在しない。

2.5 本章のまとめ

本章では、既存のDESIGN.md生成手段3つ ―Google Stitch、designmd.me、awesome-design-md― を、本ツールキットのVANILLA.mdを比較基準として同一の実在サイトで比較検証した。

3手段には個別の特性差がある。

Stitchは仕様の提唱者でありながら、自動抽出の精度はVANILLA.mdと乖離する。題材への事前知識が強い場合、創作的記述に流れる傾向が顕著である
designmd.meは形式上の充実度は高いが、観測3色に創作4色を混入させるなど、出力の一部にVANILLA.mdに記録されていない値が含まれる
awesome-design-mdは手動キュレーションによる精度で優位に立つが、動きの記述領域を持たず、収録対象が英語圏大企業に限定される

同時に、3手段に共通する欠陥が確認された。

動きの層を記述する領域の不在
観測と推測を明示的に区別する仕組みの欠如
題材への事前知識が観測を汚染する現象への脆弱性
利用者が任意のサイトの実態を歪めずに抽出する手段の不在

これら4点は、「AIに正確にデザインを引き渡す」というDESIGN.mdの本来の目的に直結する。
現行の3手段が揃ってこれらの欠陥を示す以上、欠陥は個別実装の問題ではなく、現在のDESIGN.md生成のパラダイムそのものに内在する構造的問題と解釈できる。

第1章で述べた「X(Twitter)上での期待」― 「どんなサイトもスキャンして瞬時に再構築できる」「誰でもプロデザイナーになれる」― は、Stitch提唱の時点から広く共有されていた。
しかし本章で観察された実態との間には、無視し得ない差がある。
少なくとも「実態を歪めず、動きを含み、題材への先入観に汚染されないDESIGN.md」を任意のサイトから得る手段は、2026年4月時点では存在しない。

次章では、この構造的問題への応答として本ツールキットが採用した設計判断 ― 抽出側の二段モデル(VANILLA / INTERPRETED)、生成側の辞書モデル(lexicon / patterns / [要確認])、Animations拡張セクション、design-extractorの実装、抽出と生成の連携(Step 9補助抽出オファー) ― を論じる。
本章で比較基準として用いたVANILLA.mdの設計思想も、そこで改めて位置づける。

第3章本ツールキットの設計判断

3.0 設計の指針 ― なぜ自分で作ることになったか

第1章で記録したX上の熱狂は、Stitch提唱以降の1ヶ月強の間に「どんなウェブサイトでもスキャンして瞬時に再構築できる」「誰でもプロデザイナーになれる」という言葉を生んだ。
第2章ではその実態を検証した。
同一の実在サイトに対して既存3手段(Google Stitch / designmd.me / awesome-design-md)を適用した結果、熱狂が想定する精度には届かない出力が並んだ。
動きの層は記述されず、観測と推測は文中で混在し、題材への先入観が観測を汚染し、利用者が任意のサイトを歪めず抽出する手段は存在しなかった。

期待されているほどのものではなかった ― 第2章で確認できたのはこの事実である。

しかし、熱狂が描いた問いそのもの ― AIに対してデザインを正確に言葉で渡せるか ― は、依然として価値ある問いとして残る。
世間の言説が約束したものと実態のギャップを目の前にしたとき、私は「ならば自分の手で、せめて部分的にでも、その問いに応える形を作ろう」と考えた。
advanced-design-mdは、この動機の下で組み上げたツールキットである。
本章では、第2章で観察された4つの構造的欠陥に対して、私が採用した5つの設計判断を論じる。
各節の対応関係は §3.6.1の対応マップに集約するが、本章の中心となる思想を先に提示しておく。
設計判断の中心は、「観測と推測を明示的に分離する」という思想を、抽出側と生成側の両方に異なる形で実装することである。

抽出側(design-extractor) では、VANILLA.md(観測のみ)とINTERPRETED.md(解釈のみ) という二段モデルとして実装した(§3.1)
生成側(design-creator) では、lexicon(辞書)とpatterns(経験則)による語彙制約、および [要確認] マーカーによる保留の明示として実装した(§3.2)

これに加えて、3つの設計判断が応答として加わる ―

動きを記述する領域をAnimations拡張セクションとして3文書すべてに共通で組み込んだ(§3.3)
利用者の自己抽出能力をdesign-extractorのスキル化として実装した(§3.4)
抽出と生成の連携を、creatorからextractorへの単方向呼び出し(Step 9の補助抽出オファー)として実装した(§3.5)

以下の議論は、個別の実装詳細の網羅を目的としない。
なぜその設計を採ったか、その設計が第2章で指摘した欠陥にどう応えるかを中心に論じる。

3.1 観測と推測の分離 ― 抽出側の二段モデル

3.1.1 VANILLA ― 観測のみを許す層

design-extractorが生成する第一の文書、VANILLA.mdについては、第2章 §2.0.1で比較基準としての仕様を既に提示した。
観測のみを記述し、推測・補完・創作を一切含めないという原則と、未取得の値を [未取得] で明示する運用がその核である。
本節では、第2章では触れなかったこの設計判断の意義を整理する。
なぜわざわざ「観測のみ」を担う層を独立に置くのか、なぜそれを [未取得] のような不完全さの明示と組み合わせるのか。
VANILLA.mdの制約はSKILL.md(スキル定義)に明示的な禁止事項として記述されている。
Claudeは本来「質問に答えようとする」傾向を持つため、データが不完全な箇所を創作で埋めようとする。
これを防ぐには、ルールを書き手側が意図的に提示する必要がある。
VANILLA.mdの価値は、記述されたことの信頼性に加えて、記述されなかったこと(= [未取得])の明示性にある。
読み手は「何が観測できて、何が観測できなかったか」を正確に把握できる。
この能力は、AI引き渡し時に「架空の値を実装させない」ための仕組みとして担保される。

3.1.2 INTERPRETED ― 解釈のみを許す層

VANILLA.mdは観測された事実の記録に徹するため、そのままではAIに「どう使うか」を伝える力が弱い。
例えばVANILLA.mdに #debb54 が記録されていても、その色がブランドの何を担っているか、どんな印象を担っているかは記述されない。
これはVANILLAの原則が推測を排除するためである。
この空白を埋めるのがINTERPRETED.mdである。
VANILLA.mdを唯一の入力として、AIによる解釈を加えた層である。
INTERPRETED.mdの各要素は、以下のフィールドを持つ。

name: 英語のkebab-caseによる短い識別子(例: ghost-fade, rise-in)
ja: 日本語による併記(例: ゴーストフェード, ライズイン)
source: VANILLA.md内の対応箇所(CSSセレクタやkeyframe名)からの引用
tone: 印象を表すリスト(例: [控えめ, 主張しない])
effect: 機能(例: 汎用的なホバー時の存在フィードバック)
strength: 長所
weakness: 短所
good-for: この要素が向くコンポーネント(concrete / abstract の二系統)
avoid: この要素が向かないコンポーネント

重要な原則として、INTERPRETED.mdはVANILLA.mdに存在する値しか使用してはならない。
解釈を加えるが、新たな色値・新たなフォント・存在しないkeyframeをINTERPRETEDに記述することは、この層の定義に反する。
以下は実際のINTERPRETED.mdの一部である。

- name: ghost-fade
 ja: ゴーストフェード
 source: ".ah:hover"
 spec: "opacity 0.7, 0.4s ease"
 tone: [控えめ, 主張しない]
 effect: 汎用的なホバー時の存在フィードバック
 strength: ロゴ・アイコン等の汎用ホバーとして邪魔しない
 weakness: 印象が薄く記憶に残りにくい
 good-for:
 concrete:
 - page-top-button
 - nav-link
 abstract:
 - logo
 - sns-icon
 avoid:
 concrete:
 - hero-title
 abstract:
 - primary-cta

tone(印象)とeffect(機能)が分離されている点に注目していただきたい。
多くの既存の記述形式では、「控えめなホバー演出」のような記述に両者が混在する。
この混在は、「どのコンポーネントに使うべきか」を判断するときの指針を曖昧にする。
本ツールキットでは印象と機能を別フィールドとして分離することにより、解釈そのものが構造化される。
また good-for と avoid が concrete(命名体系が確定済みの部品名)と abstract(未確定の仮ラベル)に分離されている点も、構造化の一環である。
命名の確定度に応じて責任範囲を分ける。
design-extractorは references/parts-naming.md に確定済みの部品名リストを持ち、この一覧にない名前は concrete 側には書けない。
命名体系外の用途は abstract 側、または自由文フィールド(weakness / note など)に記述することとする。

3.1.3 二段モデルが応える欠陥

二段モデルの意義は、第2章で指摘した欠陥 (2)(3) への直接的な応答として理解できる。
欠陥 (2): 観測と推測を明示的に区別する仕組みの欠如への応答として、VANILLAとINTERPRETEDを分離する。
VANILLA層は観測のみを記述し、推測が禁止される。一方、INTERPRETED層は解釈のみを記述し、新たな値の創作が禁止される。
どちらの層も自分の役割にのみ専念する。
この分離により、「記述された値が観測なのか推測なのか」という問いが、層を見れば明確に答えられる構造になる。
欠陥 (3): 題材への事前知識が観測を汚染する現象への脆弱性への応答としても、VANILLAの独立性が働く。
題材の既成イメージが解釈に影響を与えるのは避けがたいが、VANILLA層を観測に固定しておく限り、題材への先入観による汚染はINTERPRETED層に閉じ込められる。
読み手は、解釈に違和を感じた場合、VANILLAに戻って「元の観測ではどうだったか」を確認できる。
二段分離は一見すると冗長に見える。
同じサイトの記述が複数の文書に分かれるため、書き手の負担は増える。
しかし既存の単層のDESIGN.mdが直面している問題(観測と推測の混在)は、単層のままでは原理的に解決できない。
層を分けることは、負担の増加を受け入れる代わりに、解決不可能な問題を解決可能にする判断である。

3.2 観測と推測の分離 ― 生成側の辞書モデル

抽出側で「観測vs推測」の分離を二段モデルで実装したのに対し、生成側(design-creator)では同じ思想を異なる形で実装する必要がある。
生成側には観測対象が存在しないため、二段モデルは適用できない。
代わりに、辞書(lexicon)による語彙制約と [要確認] マーカーを組み合わせる。

3.2.1 lexicon ― 使用可能な語彙の固定

design-creatorは、references/lexicon/ 配下に4種類の辞書を持つ。

lexicon/colors.md: 配色パレット(slug + bg + primary + accent + sub-accent + mood + best-for)
lexicon/typography.md: フォント組み合わせ(role + font + source + weight + mood親和)
lexicon/animations.md: アニメーション(scope + name + spec + mood親和)
lexicon/parts.md: 部品(ja名 + 推奨アニメscope + 初期reason)

design-creatorがDESIGN.mdを生成する際の最も重要なルールは、**「この辞書にない値をDESIGN.mdに書いてはならない」**である。
配色はlexicon/colors.mdに登録されたパレットからのみ選ぶ。
フォント名はlexicon/typography.mdに登録されたものからのみ選ぶ。
このルールが意味するのは、AIに「自由に書く」のではなく「事前に定義された語彙の中から選ぶ」ことを強制する設計である。
AIは本来、知識の組み合わせから自然に新しい値を生成する。
例えば「darkでゴージャスな配色」と指示されれば、AIは #1a1a2e のような値を即興で出してくる。
この値は「それっぽい」が、書き手のブランド設計とは無関係である。
lexiconを介在させることで、AIの出力は「lexiconの中のどのパレットを選ぶか」という有限の選択問題に変換され、即興の捏造はそもそも起こりえなくなる。

3.2.2 patterns ― 組み合わせの経験則

lexiconが「何が使えるか」を定義するのに対し、references/patterns/ は「何と何が併用されやすいか」の経験則を定義する。

patterns/color-combos.md: mood × useの組み合わせで頻出するパレット選定パターン
patterns/animation-recipes.md: mood × scopeを横断したアニメーションの組み合わせレシピ
patterns/component-defaults.md: use × moodに応じた必須パーツ構成のテンプレート

例えば「dark + ファンタジー + 神秘性」というmoodの組み合わせがあったとき、lexicon/colors.mdには複数のパレット候補が該当する(night-sky-gradient / lavender-black / purple-gold など)。
第一候補を一意に決めるためにpatterns/color-combos.mdが参照される ― 「ダーク × ファンタジー / 神秘性」セクションが night-sky-gradient を優先指定することで、最終的な選定が確定する。
patternsはlexiconを上書きしない。
あくまでlexicon内の選択肢の中で「どれを優先するか」を経験則的に示すだけである。
これにより、lexiconの網羅性とpatternsの判断補助が衝突せず、両者を併用できる。

3.2.3 `[要確認]` ― 保留の明示

lexiconに該当値が存在しない場合、design-creatorは新たな値を創作しない。
代わりに [要確認] という記号で保留を明示する。
この記号は以下のいずれかを示す。

観測または辞書に該当値が存在せず、AIが選定を保留した
ユーザーの自由入力が原文のまま保持され、後段で人間判断を要する
volume(quick / standard / deep)制約により設問が出題されず、値を確定できなかった

[要確認] は「不具合」ではなく「保留の明示」である。
実装フェーズの担当者が当該箇所に追加指示を与えるための明示的な空欄として機能する。
design-creatorはvolume別の [要確認] 残存率の目安をユーザーに事前提示する ―

volume	出題数	`[要確認]` 比率の目安
quick	5問	50% 以下
standard	10問	30% 以下
deep	20問	20% 以下

これにより、ユーザーは「クイズが短いほど保留が増える」という事実を生成前に把握する。
「思ったより空欄が多い」という後発の不満を避けるための事前合意である。

3.2.4 辞書モデルが応える欠陥

辞書モデル(lexicon + patterns + [要確認])もまた、欠陥 (2)(3) ― 観測と推測の混在および題材への先入観 ― への応答である。
観測対象を持たない生成の場面で、抽出側と同じ思想をどう実装するかが、抽出側との違いの核となる。
抽出側ではVANILLA / INTERPRETEDの層分離によって、観測領域から推測を構造的に締め出した。
観測対象が存在しない生成側では、この方法は採れない。
代わりに、有限の語彙(lexicon)をあらかじめ用意し、AIに「事前定義からの選択」のみを許すことで、即興の創作を起こりえなくする。
「Apple風」とユーザーが書いたとき、AIが即興でApple的な配色を捏造することは禁じられ、[要確認] として保留される(または §3.5のStep 9経路で参照サイトを抽出する)。
両者は実装は異なるが、思想は同じである ― AIが「知らないことを知らないと言える」設計を、文書側からも語彙側からも担保する。

3.3 動きを記述する領域 ― Animations拡張セクション

3.3.1 5サブセクション構成

第2章で指摘した通り、既存のDESIGN.md生成手段は全て、動きを体系的に記述する領域を持たない。
Stitch純正の8セクション構成にも、awesome-design-mdが採用する9セクション構成にも、アニメーションの項目がない。
本ツールキットは、この欠落への応答として、VANILLA.md / INTERPRETED.md / DESIGN.mdのすべてに 独自のAnimationsセクションを新たに追加した。
拡張の最初の判断は、「動きをどのような粒度で記述するか」である。
本ツールキットでは以下の5サブセクションを採用する。

サブセクション	対象
Libraries	使用されているJavaScriptアニメーションライブラリの特定(GSAP, jQuery, Lenis, Three.js等)
Keyframes	CSS `@keyframes` による定義
Transitions	CSS `transition` による状態変化
Scroll Behaviors	スクロール連動の挙動(IntersectionObserverによる状態切り替え等)
Hover / Interaction	hoverやclickなどユーザー操作に連動する挙動

この5分割は、アニメーションを発火させる条件別に分類したものである。
一度きりのkeyframeと、状態変化のtransitionと、スクロールで発火する動作と、ユーザー入力で発火する動作は、それぞれ異なる実装パターンを持つ。
同じセクション内で雑居させると、実装時の参照がしにくい。

3.3.2 lexicon/animations.mdによる語彙固定

DESIGN.md側では、Animationsセクションの記述もlexiconの制約下にある。
references/lexicon/animations.md に登録されたscope(page-load / hero-enter / scroll-reveal / hover / nav-toggle / modal / page-transition / bg-decoration / complex-sequence)とname(blur-reveal / rise-in / ghost-fade等)からのみ選ぶ。
scopeごとに採用が推奨されるlibもlexicon内で固定されている。
例えばscroll-revealはCSS + IntersectionObserver、hoverはCSS transitionのみ、というように。
GSAP / Three.jsのような外部ライブラリは「complex-sequence」scopeでのみ [要確認: GSAP候補] として残される。
これにより、生成されたDESIGN.mdは外部CDNへの依存を最小化する。
Animations Librariesテーブルの大半は「CSS + IntersectionObserver」「CSS @keyframes」「CSS transition only」に収まる。

3.3.3 7レイヤー構成におけるMotion層

design-creatorのクイズには、Animationsの方針を決めるための Motion層(Q-motion-01〜03)が含まれる。

Q-id	テーマ
Q-motion-01	テンポ(fast / medium / slow / minimal)
Q-motion-02	キャラクター(subtle / expressive / theatrical / mechanical)
Q-motion-03	採用ライブラリの許容度(CSS only / GSAP allowed / WebGL anything goes / case-by-case)

これらの回答はlexicon/animations.mdのscope別第一候補選定と組み合わされる。
例えば「mood = dark / luxury」+「Motion tempo = slow」ならhero-enterにはblur-reveal(1.5s ease)、scroll-revealにはfade-blur-in(1.2s ease)が選ばれる。
同じmoodでもtempoがfastなら、より短いdurationの選択肢に変わる。
moodとMotionの組み合わせを、patterns/animation-recipes.mdがレシピ化している。
「mystic stack」「minimal stack」「vivid stack」のような名前付きの組み合わせとして、複数のscopeを一括して決められる。

3.4 利用者の自己抽出能力 ― design-extractorの実装

3.4.1 Playwrightによる動的レンダリング

第2章で指摘した欠陥 (4)「利用者が任意のサイトの実態を歪めずに抽出する手段の不在」への応答として、本ツールキットは design-extractor をClaude Codeスキルとして実装した。
design-extractorの最初の設計判断は、単純なHTTP GETではなくPlaywrightによる動的レンダリングを使うことである。
理由は、現代のWebサイトの多くが以下の特性を持つためである。

JavaScriptによる動的なDOM構築(React / Vue / Next.js等のSPAフレームワーク)
Lazy loading(遅延読み込み)による初期DOMの最小化
ユーザーエージェント・地域によるコンテンツの分岐
Bot検知による静的取得の遮断(Akamai、Cloudflare等)

静的なHTTP GETでは、これらのサイトから意味のあるCSS・DOM構造を取得できない。
design-extractorはChromiumを起動し、実際のブラウザとして対象サイトを訪問する。
networkidle イベント(ネットワーク活動が一定時間停止する時点)を待ってからDOMを取得するため、SPAであってもレンダリング後の状態を取得できる。
Chromiumがbot検知で遮断された場合(403/429応答時)は実行を停止して理由を報告する設計とし、ユーザーが BROWSER=firefox環境変数を指定して再実行することで、Firefoxエンジンに切り替えられる経路を用意している。

3.4.2 JSシグネチャによるライブラリ判定

取得したJavaScriptファイルから、どのアニメーションライブラリが使われているかを判定する処理は、URLの文字列判定ではなく、JavaScript本体のコード内容(シグネチャ)を精査する方式を採る。
URL判定では、例えば gsap.min.js というURLからGSAPを判定することになる。
しかし現代のビルド環境では、ファイル名が難読化されるか、バンドルされて一つのファイルに統合される。
URLに gsap の文字列が現れないケースが多い。
代わりに、本ツールキットは以下のようなコード内のメソッド呼び出しパターンをJS本体の文字列から検出する。

gsap.to( → GSAP
gsap.timeline( → GSAP
ScrollTrigger.create( → ScrollTrigger
lottie.loadAnimation( → Lottie
anime({ targets: → Anime.js
fadeIn( / fadeOut( → jQuery
new Swiper( → Swiper

これらのシグネチャは、バンドル後のコード内でも残存しやすい。
判定対象からGoogle Tag ManagerやGoogle Analyticsのようなデザインに無関係な分析スクリプトを除外するリストも、fetch.js に組み込まれている。
さらに、DOMから <script src> 属性を抽出して補完取得を行うフォールバックも実装している。
シグネチャ判定で検出されなかった本体JavaScriptを、DOM構造から逆引きで取得する。
この二段構えにより、様々な実装スタイルのサイトに対応できる。

3.4.3 behavior-log ― 観測の限界をデータとして残す

静的なHTML・CSS・JavaScriptを取得しただけでは、実際にサイトがどう振る舞うかは完全には分からない。
特にスクロール連動やhover応答は、ユーザー操作が発生した時点で初めて実行される。
design-extractorは、Playwrightの page.evaluate フックを利用して、サイトが読み込まれた直後の時点で挙動を観測する機構を組み込んでいる。
出力される behavior-log.json には、以下の情報が記録される。

eventListeners: 登録されたイベントリスナー(scroll, click, mousemove等)
observers: IntersectionObserverの生成有無
classSamples: DOMに存在するクラス名のサンプル(アニメーション制御クラスの推定手がかり)
gsapPlugins: window.gsapが存在する場合、登録されたプラグイン一覧
missingReasons: 観測できなかった要素の理由(requires_scroll, requires_hover, lazy_loaded 等)

特に missingReasons は、観測の限界をデータとして残すための機構である。
「スクロール前のためhoverアニメーションが未発火」という事実自体が記録され、Claudeがこれを入力としてVANILLA.mdを生成する際に、[未取得: requires_scroll] 等の明示的な注記として反映される。

3.4.4 `[未取得]` の運用ルール

design-extractorの設計判断のうち、おそらく最も重要な一つは、**「Claudeに観測できなかったことを黙って補完させない」**という運用方針である。
通常、大規模言語モデルは「質問に答えようとする」傾向がある。
不完全なデータを渡されても、なんとか回答を組み立てようとする。
この傾向は、デザイン仕様の記述においては汚染を引き起こす。
「観測できなかったから [未取得] と書く」よりも「celestial系サイトなら一般にこの色を使う」と書く方が、モデルにとっては自然な応答である。
本ツールキットは、design-extractorの SKILL.md(スキルの動作を規定する指示書)において、以下のルールを明示している。

### 解析時の注意
読み込んだソースから以下を抽出する:
- Colors / Typography / Spacing / Components
 - CSSの変数・クラス定義から読み取る
 - JSで動的に設定される値は `[動的: JS制御]` と明記
- Animations
 - `references/animation-patterns.md` を参照してライブラリを特定する
 - @keyframes・animation・transitionプロパティを抽出
 - behavior-log.jsonのeventListeners・observersからScroll/Hover挙動を読み取る
 - missingReasonsがある場合は該当箇所に `[未取得: <理由>]` と明記
**推測補完していないか**(出力前チェック項目)

「推測補完していないか」が明示的なチェック項目としてClaudeに提示される。
これにより、Claudeはデータが不完全な箇所を、創作で埋めずに [未取得] として残す挙動を取る。
この設計は、第2章で検証した3手段との決定的な差分である。
「知らないことを知らないと言う」能力は、AIを用いた抽出ツールにおいて、自動的には獲得されない。
意図的に禁止ルールとして記述する必要がある。

3.5 抽出と生成の連携 ― Step 9補助抽出オファー

3.5.1 lexiconの有限性という構造的制約

§3.2で論じたlexiconモデルには、原理的な制約がある ― lexiconは有限である。
世界に存在する全てのデザイン語彙を辞書に登録することはできない。
新しいブランド・新しい流行・特定の固有名詞へのニュアンスは、lexiconの網羅範囲を超える。
例えばユーザーが「Apple風のクリーンさ」と書いたとする。
lexicon/colors.mdに「Apple風」というパレットは存在しない。
lexicon/typography.mdにApple専用のフォントスタックは登録されていない。
この場合、§3.2のルールに従えば、関連するフィールドは [要確認] として保留される。
しかしこれだけでは、ユーザーの意図が後段に伝わらない。
「Apple風」という言葉自体は原文として保持されるが、それを実装に変換する手段がDESIGN.md内に存在しない。

3.5.2 単方向連携の設計判断

この制約への応答として、design-creatorは特定条件下でdesign-extractorを呼び出す権限を持つ。
SKILL.mdのStep 9として明示的に定義されている。
発動条件(いずれか1つ以上)は以下の通り。

固有名詞・ブランド言及 ― 自由入力にブランド名・作品名・URLが含まれる
mood衝突 ― lexicon第一候補がユーザーの別要件と矛盾する
[要確認] 多発 ― volume別目安(quick: 50%, standard: 30%, deep: 20%)を超過
lexiconカバー外シグナル ― 自由入力にlexiconにないスタイル名が含まれる

発動時、design-creatorはユーザーに以下を提示する ―

「Apple 風」のニュアンスは lexicon のみでは表現が困難です。
参照可能なサイト URL があれば抽出を実行可能ですが、いかがいたしますか? (yes / no)

ユーザーがyesと回答した場合、design-creatorは対象URLをユーザーから受け取り、design-extractorを起動する。
抽出完了後、得られたINTERPRETED.mdの値はlexiconと同格に扱われ、DESIGN.mdの対応フィールドに採用される。
採用された値には  というコメントが必ず付され、後の監査時に「lexicon由来か、抽出由来か」を識別できる。
連携の方向は creator → extractorの単方向である。
extractor側からcreatorを呼ぶ経路は存在しない。
これはextractorを「ライブラリ素材を生成する独立ユーティリティ」として保つための判断である。
extractorはcreatorの存在を知らないままで動作し続ける。

3.5.3 ユーザー判断を介在させる経路

Step 9の最も重要な設計判断は、AIが勝手にextractorを呼び出さない点にある。
発動条件に該当しても、Claudeはまずユーザーに提案する。
URLもユーザーから受け取る。
ClaudeがAIの記憶ベースでURLを捏造することは、SKILL.mdの extractor-handoff.md で明示的に禁止されている。
この設計の意図は、AIが「ユーザーの代わりに考える」のではなく、「ユーザーの判断を引き出す」ように振る舞わせることである。
「Apple風」と書いたユーザーが本当にApple公式サイトの抽出を望むのか、それとも別のサイトを想定していたのか、それともlexicon内の妥協で十分なのか ― これはユーザーにしか判断できない。
加えて、Step 9の発動には1セッション1回までという暴走防止ルールがある。
1サイト抽出してまだ不足を感じても、design-creatorから再オファーは行わない。
ユーザーが自分から /design-extract を呼ぶ形に任せる。
AIが連続的に外部リソースを取得し続ける動作を仕組みとして防止している。

3.6 設計判断と構造的欠陥の対応関係

3.6.1 対応マップ

本章で論じた5つの設計判断が、第2章で提示した4つの構造的欠陥にどう対応するかを整理する。

構造的欠陥	本ツールキットの応答
(1) 動きの層を記述する領域の不在	Animations拡張セクション(5サブセクション構成) + lexicon/animations.mdによる語彙固定
(2) 観測と推測を明示的に区別する仕組みの欠如	抽出側: VANILLA / INTERPRETEDの二段モデル / 生成側: lexicon厳守 + `[要確認]` マーカー
(3) 題材への事前知識が観測を汚染する現象への脆弱性	VANILLAの独立性による汚染の隔離 + lexiconの有限性による即興抑制 + Step 9のユーザー判断介在
(4) 利用者が任意のサイトの実態を歪めずに抽出する手段の不在	design-extractorスキル(Playwright + JSシグネチャ判定 + behavior-log + `[未取得]` 運用)

特に欠陥 (2)(3) に対しては、抽出側と生成側の双方で異なる実装を持つ。
同じ思想を、観測対象がある場面とない場面の両方で具体化していることが、本ツールキットの構造的特徴である。

3.6.2 残される課題

一方、本ツールキットの設計にも現状では解決できていない課題がある。
主要なものを列挙する。
第一に、INTERPRETED層の解釈の質は、現状ではClaudeの解釈能力に依存する。
VANILLA.mdを渡しても、Claudeがtoneやstrengthを書き間違える可能性はある。
この問題は、複数のAIに同じINTERPRETEDを生成させて比較する等の方法で緩和できるが、本ツールキットの現段階では十分に体系化されていない。
第二に、JSシグネチャ判定は既知のライブラリに対してのみ有効である。
新しいライブラリや、自社開発のアニメーション実装は、シグネチャ辞書に追加しない限り判定できない。
辞書のメンテナンスは継続的な作業となる。
第三に、Bot検知が強いサイトは現状でも取得できない。
Akamai / Cloudflareの一部保護下にあるサイトは、Firefoxフォールバックでも取得できない。
これはサイト側の防御であり、本ツールキット側から根本的に解決する手段はない。
第四に、lexiconの網羅性は時間とともに陳腐化する。
新しいデザイントレンドが登場するたびに、辞書を拡張する必要がある。
これはStep 9の補助抽出オファーで部分的に補完できるが、根本的にはコミュニティによる継続的な更新が望ましい。
MITライセンスでの公開は、この更新を外部から受け入れる前提に立っている。
第五に、題材への先入観の完全な排除は不可能である。
VANILLAの独立性によりINTERPRETED層への汚染の隔離はできるが、ClaudeにINTERPRETEDを書かせる段階で、Claudeの事前知識が介入することは避けがたい。
本ツールキットでは「INTERPRETEDはVANILLAにある値しか使用してはならない」という制約でこれを緩和しているが、解釈の語彙自体(「celestial」「elegant」等)はClaudeの訓練データに依存する。
これらの課題は、本ツールキットの設計そのものの欠陥ではなく、AIを用いた抽出・生成というアプローチに内在する限界として理解する必要がある。
完全な解決は本ツールキットの射程を超える。

3.7 本章のまとめ

本章では、第2章で提示した4つの構造的欠陥に対する本ツールキットの設計判断を論じた。
中心的な思想は、「観測と推測を明示的に分離する」ことを、抽出と生成の両側で異なる形で実装することであった。

抽出側(design-extractor): VANILLA(観測のみ) / INTERPRETED(解釈のみ)の二段モデル
生成側(design-creator): lexicon(語彙の固定)+ patterns(組み合わせの経験則)+ [要確認](保留の明示)

これに加えて ―

Animations拡張セクションが、欠陥 (1)「動きの層の記述領域の不在」に応答する
design-extractorスキル(Playwright + JSシグネチャ + behavior-log + [未取得] 運用)が、欠陥 (4)「利用者の自己抽出能力の不在」に応答する
Step 9補助抽出オファーが、抽出と生成を単方向で連携させ、lexiconの有限性を救済する

これらの設計判断は、個別の技術的工夫の集積ではなく、第2章で観察された現在のDESIGN.md生成パラダイムの構造的問題への、体系的な応答として互いに連関している。
advanced-design-mdの位置づけを、第1章・第2章との関係において改めて整理しておく。
第1章で記録したX上の熱狂は「どんなウェブサイトでもスキャンして瞬時に再構築できる」「誰でもプロデザイナーになれる」という言説を生んだ。
第2章での検証はこの言説と実態との間の距離を明らかにした。
本ツールキットは、その距離を埋める一つの試みである。
世間の熱狂が約束したものを、ある個人が自身の手で、部分的にではあれ、実現しようとした応答として位置づけられる。
完全な実装ではない。
ただし、熱狂が描いた問い ― AIに対してデザインを正確に言葉で渡せるか ― に対する、一つの具体的な答えである。
同時に、本ツールキットの設計にも残される課題がある。
解釈の質・シグネチャ辞書のメンテナンス・Bot検知への対応限界・lexiconの陳腐化・題材への先入観の完全排除の不可能性 ― これらはAIを用いた抽出・生成というアプローチそのものが持つ限界である。
本ツールキットをMITライセンスで配布する判断は、これらの限界に対するもう一つの応答である ― 完全な解決は単一の作者によっては成し得ないため、外部からの拡張・改修・批評を受け入れる前提に立つ。
advanced-design-mdは到達点ではなく、出発点であることをここに明記しておく。

パレットリンクでは、日々のつながりや学びを大切にしながら、さまざまなお役立ち記事をお届けしています。よろしければ、ぜひ「Organization」のページもご覧ください。
また、私たちと一緒に未来をつくっていく仲間も募集中です。ご興味をお持ちの方は、ぜひお気軽にお問い合わせください。一緒に新しいご縁が生まれることを楽しみにしています。

参考文献

TechCrunch (2025). Stitch is Google's AI-powered tool to help design apps. https://techcrunch.com/2025/05/20/google-launches-stitch-an-ai-powered-tool-to-help-design-apps/
Google Developers Blog (2025). From idea to app: Introducing Stitch, a new way to design UIs. https://developers.googleblog.com/stitch-a-new-way-to-design-uis/
Tech Insider (2026). Google Stitch AI: Vibe Design and 5-Screen Canvas. https://tech-insider.org/google-stitch-ai-design-tool-march-2026-update/
Google Blog (2026). Design UI using AI with Stitch from Google Labs. https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-ai-ui-design/
AI Business (2026). Google's Stitch and the Shift in AI-Driven Development. https://aibusiness.com/generative-ai/google-s-stitch-and-ai-driven-development
Neowin (2026). Google updates Stitch with 'vibe design' and infinite AI canvas. https://www.neowin.net/news/google-updates-stitch-with-vibe-design-and-infinite-ai-canvas/
aipedia.wiki (2026). Google Stitch: Features, Pricing & Review. https://aipedia.wiki/tools/google-stitch/
Medium - fernandocomet (2026). Google makes DESIGN.md open source on its way to become a industry standard. https://medium.com/design-bootcamp/google-makes-design-md-open-source-on-its-way-to-become-a-industry-standard-16119f2368dd
Google Labs Blog (2026). Stitch's DESIGN.md format is now open-source so you can use it across platforms. https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-design-md/
google-labs-code (2026). design.md: A format specification for describing a visual identity to coding agents. GitHub. https://github.com/google-labs-code/design.md
Pillitteri, P. (2026). Google Stitch Open-Sources DESIGN.md: The Spec That Makes AI Agents Consistent With Your Brand. https://pasqualepillitteri.it/en/news/1251/google-stitch-design-md-open-source-spec-2026
GitHub Topics: design-md. https://github.com/topics/design-md
mindwiredai (2026). DESIGN.md Is Now Open Source: Google's New File Format That Makes AI Build Your Brand Correctly. https://mindwiredai.com/2026/04/23/design-md-is-now-open-source-googles-new-file-format-that-makes-ai-build-your-brand-correctly/
google-labs-code/design.md Releases v0.1.1 (2026-04-21). https://github.com/google-labs-code/design.md/releases
google-labs-code (2026). stitch-skills: A library of Agent Skills designed to work with the Stitch MCP server. GitHub. https://github.com/google-labs-code/stitch-skills
Awesome Agents (2026). DESIGN.md Goes Open Source - AI Agents Get a Style Sheet. https://awesomeagents.ai/news/google-design-md-open-source-spec/
anthropics/skills Issue #1008 (2026). frontend-design: consider consuming/producing DESIGN.md per Google Labs open spec. GitHub. https://github.com/anthropics/skills/issues/1008