generate-design-md

AIが一貫したUIを生成するための DESIGN.md を、対話または既存トークンの取り込みから作成するスキル。

概要

DESIGN.md は、AIエージェントがUIを生成・修正する際のビジュアル判断基準を定義するMarkdownファイルです。 このスキルは対話を通じてユーザーのデザイン意図を引き出し、必要に応じて既存のトークンファイルを取り込みながら DESIGN.md を生成します。

前提知識

このスキルを実行する前に、以下のリソースを必ず読み込むこと：

• ../../DESIGN-MD-SPEC.md — フォーマット仕様（セクション構成、3層記述パターン、対応表フォーマット）
• resources/writing-guide.md — 良い記述と悪い記述の Before/After
• resources/examples/ — 完成例3パターン（saas-dashboard, creator-platform, minimal-zen）

実行フロー

Step 0: 状態確認

プロジェクトルートに DESIGN.md が既に存在するか確認する。

• 存在しない → Step 1 へ進む

• 存在する → 既存の DESIGN.md を Read で読み、以下の簡易診断を行う:

  簡易診断（内部処理）:

  1. 北極星の鮮度: Creative North Star のメタファーが現在のプロダクト方向性と一致しているか？
  2. 経過期間: frontmatter の generated 日付から3ヶ月以上経過している場合、全体的な見直しを推奨
  3. 例外の蓄積: Exception が3つ以上付いたルールがあれば、ルール自体の再定義を提案

  診断結果をユーザーに提示する: 「既存の DESIGN.md を診断しました:

  • Creative North Star: メタファー "XXX" — [現在も有効か確認が必要 / 問題なし]
  • 経過期間: [N ヶ月前に生成 — 見直し推奨 / 最近更新済み]
  • ルールの健全性: ["XXX Rule" に例外がN個 — ルール自体の再定義を検討 / 問題なし]

  更新しますか？ それとも新しく作り直しますか？」

  • 更新 → 診断で指摘した箇所を起点に、変更したい箇所をヒアリング
  • 新規 → Step 1 へ（既存ファイルは上書き前に確認を取る）

Step 0.5: 入力ファイルの棚卸し

ユーザーが渡したファイル、プロジェクト内のトークンファイル、既存CSSを確認し、「何を下敷きにできるか」を判断する。

重要:

• Claude Design 固有のファイル名に依存しない
• 「どのツールが出したか」ではなく「どんな構造を持つファイルか」で扱う
• トークンファイルがあっても、それだけでは Authored Layer（Creative North Star、競合時の優先順位、自由領域のトーン）は埋まらない。そこは対話で補う
• W3C DTCG JSON は下支えの交換フォーマットとして扱う。DESIGN.md の価値そのものを、その構造に閉じ込めない

構造ベースの判定ルール:

• W3C DTCG JSON: オブジェクトに $value があれば token、$type があれば型として扱う。$type は親グループから継承される前提で解釈する
• CSS Custom Properties: :root やテーマスコープ内の --color-*, --space-*, --font-*, --radius-*, --shadow-* などをトークン候補として読む
• 無効な構造: 1つのオブジェクトが $value を持ちながら子token/groupも持つ場合は不正。ユーザーに「このファイルは token と group が混在しているため、そのままは読めない」と伝える

W3C DTCG JSON の最低限の解釈:

• color → Color Strategy
• fontFamily, fontWeight, dimension（font size / line height を含む場合）→ Typography
• dimension（spacing / gap / inset 系）→ Spacing & Layout
• dimension（radius / border-width / stroke 系）→ Effects
• shadow → Effects
• duration, cubicBezier → Motion & Transitions
• dimension は汎用型なので、キー名と用途から spacing / radius / border / sizing を判定する

候補が見つかったらユーザーに短く確認する: 「既存のトークンファイルが見つかりました。これは値の正として取り込みますか？ それとも参考情報として扱いますか？」

Step 1: ヒアリング（最大5ターン）

進め方の原則:

• ユーザーの最初の発言が十分な情報を含んでいる場合（プロダクト概要 + 印象の方向性）、追加質問せずに Step 2 に進んでよい
• ヒアリングは「足りない情報を補う」ためであり、「全項目を埋める」ためではない
• 5ターンは目安。ユーザーが積極的に情報提供している場合は柔軟に延長してよい
• 2ターン目以降で必須情報（質問1, 2）が揃ったら、残りは仮説提示でカバーして生成に進む
• ユーザーが「わからない」を繰り返す場合は、仮説を3-5個提示し「この中で最も近いのは？」で判断を引き出す
• 言語判定: ユーザーの最初の発言言語で DESIGN.md の説明文を記述する。トークン名・CSS値は常に英語

以下の情報を対話で引き出す。すべてを聞く必要はなく、ユーザーが提供できる情報に合わせて柔軟に進める。

必須で聞くこと：

1. 「どんなプロダクト/サービスですか？ 誰が使いますか？」 → Product Context、Creative North Star の素材
2. 「UIの印象を形容詞3つで表すと？ または参考にしているサービスはありますか？」 → Visual Language、Mood & Tone
3. 「UIの主なコンテンツは何ですか？（例: テキスト記事、データテーブル、画像ギャラリー、フォーム入力）」 → Typography（Serif/Sansの判断）、Layout（コンテンツ幅）、Density Guide の素材

任意で聞くこと（ユーザーが答えられれば）： 4. 「既存のデザインシステムやトークンファイルはありますか？（W3C DTCG JSON、CSS variables、tokens.json など）」 → Token References、具体値の取得 5. 「絶対に避けたい印象やスタイルはありますか？」 → Global Constraints、Creative North Star の "This does NOT mean" 6. 「対象プラットフォームは？（Web/Mobile/両方）」 → Frontmatter の platform 7. 「現在のUIやブランドで、変えたくない要素はありますか？」 → Global Constraints、Color Strategy の制約として反映 8. 「絶対に手を抜けない画面はどれですか？理由も教えてください」 → 品質の重点領域の特定、TL;DR の死守ライン、名前付きルールの粒度判断に使用

補助入力を活用する：

• ユーザーが URL を提供した場合 → WebFetch で取得し、デザイン要素を分析して対話のたたき台にする
• ユーザーが画像を提供した場合 → 画像を分析し、色・タイポ・レイアウトの特徴を抽出する
• ユーザーが Figma URL を提供した場合 → Figma MCP でデザインデータを取得する
• ユーザーが GitHub リポジトリを指定した場合 → コードから実装パターンを分析する

ヒアリングの心得：

• 聞いても「わからない」が返ってくることは多い。その場合はデフォルト値で埋めて先に進む
• 「こんな感じですか？」と仮説を提示して Yes/No で進める方が効率的
• 5ターン以内で切り上げる。完璧を目指さない。80%の精度で生成し、後から修正する

Step 2: DESIGN.md 生成

ヒアリングで得た情報をもとに DESIGN.md を生成する。

生成ルール

ルールの検証可能性チェック（出力には露出しない）:

• 生成した各ルールを内部で以下に分類する:
  • Verifiable（機械的に検証可能）: 値の範囲チェック、コントラスト比、最小サイズ等。例: 「コントラスト比 4.5:1 以上」。検証条件を具体値で明示する（例: 「≥ 4.5:1」「≤ 12px」）
  • Observable（目視で検証可能）: スクリーンショットで確認できる。例: 「1ビューにフォーカルポイントは1つ」
  • Interpretive（解釈が分かれうる）: 判断者によって結論が異なりうる。例: 「堅すぎない信頼感」
• Interpretive が全ルールの50%を超える場合、具体的な判定基準または例示を補って Observable 以下に引き下げる努力をする
• この分類は DESIGN.md の出力には含めない

フォーマット:

• ../../DESIGN-MD-SPEC.md の構成に厳密に従う
• Frontmatter を含める（generated, mode, version, platform, token_source）
• mode は主な入力源に合わせて選ぶ
  • 対話中心 → conversation
  • 外部トークンファイル中心 → tokens-import
  • URL/Figma/コード + トークン併用 → hybrid
• ユーザーの回答量に応じてミニマム/スタンダードを判断する
  • 情報が少ない → ミニマム（4セクション、80-120行）
  • 情報が十分 → スタンダード（7セクション、250-350行）

3層記述パターンを守る:

• 各セクションで「原則（Why）→ スケール（What）→ 対応表（When）」の順に書く
• 対応表は必ずテーブル形式で、Reasoning 列を含める
• Color の対応表には Do/Don't 列を含める

トークン取り込み時の扱い:

• 外部トークンファイルの値は「何が既に決まっているか」を理解するための出発点として使う
• 値があっても理由がない場合は、その値を盲信せず「なぜその値なのか」を対話または周辺文脈から補う
• token_source には実際の参照元パスを書く。複数ある場合は最も支配的なソースを書くか、Design Token References セクションで列挙する
• W3C DTCG の dimension は spacing / radius / border-width / sizing に分かれうるため、名称と利用文脈を確認してからマッピングする
• shadow / radius / border の判断基準が明示的に存在する場合は Effects セクションを生成する

名前付きルール:

• プロダクト固有のルールに名前をつける
• ルール名は Creative North Star のメタファーから自然に導出する（例：メタファーが「台所」なら「One-Spice Rule」、「秘密基地」なら「Terminal Window Rule」）
• 「Flat Card Rule」「No Nesting Rule」「Surface Layering Rule」等の汎用的な名前は使わない
• 例外がある場合は「理由」を付ける
• 境界が曖昧なルール（適用範囲の判断が割れやすいもの）には Violation（違反例）を追加する。全ルール必須ではない
• テンプレートルール（No-Line Rule, Ghost Border 等）をそのまま使わない
• そのプロダクトの文脈から導出されたルールだけを書く

Creative North Star:

• メタファーを1つ設定する
• 「This means」を3-5個の箇条書きで（具体的な値を含む）
• 「This does NOT mean」を2-3個で（過度解釈を防ぐ）

否定形の扱い:

• Don't / Avoid は必ず肯定形の代替とペアにする
• ❌ Don't: 影を使うな → ✅ 影を使わない → 代わりにサーフェス色差で階層を表現する

言語:

• 説明文はユーザーの言語で書く（日本語なら日本語で）
• トークン名、クラス名、CSS値は英語のまま

具体値 vs 原則:

• カラーパレット、タイポスケール、スペーシングスケール、ブレイクポイント → 具体値必須
• Radius / Shadow / Border が既に定義されている場合 → Effects に具体値必須
• レイアウト方針、アニメーション、トーン → 原則 + 代表例で十分
• カラー値は Hex でもデザイントークン変数名でもよい

コンテンツ特性に応じた判断基準:

• Typography の line-height を決める際、「このプロダクトの主要コンテンツは何か？」を問う
• 長文中心のプロダクトと、UI操作中心のプロダクトでは、本文に必要な行間は根本的に異なる
• 日本語・中国語・韓国語のように字面が大きい言語では、英語と同じ行間では窮屈になりやすい。言語特性を考慮しているか？
• 書体選択: 全場面で同じ書体が最適か？「読むコンテンツ」と「操作するUI」の区別があるなら、書体を分けることで境界を暗黙的に伝えられないか？

感情を伴うインタラクションへの判断基準:

• そのプロダクトに「ユーザーが感情的に反応する操作」があるか？（いいね、フォロー、購入完了、達成等）
• それらの操作は、通常のUI操作（フィルター変更、ページ遷移等）と同じ視覚処理になっていないか？
• 感情的な操作には、通常操作より「報酬感」のある視覚フィードバックを検討する余地があるか？

テンプレートバイアスの回避:

• すべてのセクションが「このプロダクト固有の内容」を含んでいるか自己検証する
• 汎用的すぎるルール（「コントラスト比4.5:1以上」等）は Global Constraints に1回だけ
• 不要なセクションは [SKIP] として省略可能
• 名前付きルールは Creative North Star のメタファーから導出する。汎用的な名前（Flat Card Rule, Surface Layering Rule 等）を使わない
• Spacing Scale はプロダクトのコンテンツ特性に合わせてカスタマイズする（全プロダクト共通の4/8/16/32ではなく、例えば画像中心なら gallery gap を定義する等）

DESIGN.md は「制約」ではなく「創造の方向性」:

• DESIGN.md に書いてあることは守る。しかし書いていないことは自由に工夫してよい
• 「禁止」より「推奨」を多く書く。何を避けるかだけでなく、何を積極的に使うかを明示する
• URL抽出モードでは「既存UIの忠実な再現」ではなく「デザインのエッセンスを抽出し、昇華する」。コピーではなく、そのサービスが大切にしている判断基準を言語化する
• 各セクションで「AIが自由に工夫してよい領域」を明示する
• 自由領域には「何が自由か」だけでなく「どういう方向で攻めてよいか」のトーンを添える。トーンがないとAIは保守的な選択をする

  ❌ **自由領域:** ホバーエフェクトの演出は自由
  ✅ **自由領域:** ホバーエフェクトの演出。書斎で本を手に取る瞬間のように、静かだが確かな変化を
  

• 自由領域の比率が DESIGN.md 全体の30%を大きく超えないこと（自由すぎるとDESIGN.mdの意義が薄れる）

カラーコントラスト検証（必須）:

• Color Palette を生成したら、主要な組み合わせのコントラスト比を計算する
• テキスト色 × 背景色の組み合わせが WCAG AA（4.5:1以上）を満たすか確認
• 特にアクセントカラー上の白テキスト、muted色の小サイズテキストに注意
• 4.5〜5.0:1 の場合は警告を付与する（ギリギリ合格だがレンダリング環境で不合格のリスクあり。可能なら暗くする）
• 不合格の場合は色を調整してから出力する
• 検証結果を DESIGN.md 内にHTMLコメントで記録する

特殊コンポーネントへの対応:

• コードエディタを含む場合 → シンタックスハイライトカラーの定義を促す
• 地図・チャートを含む場合 → データビジュアライゼーション用カラーの定義を促す
• ダーク/ライト混在の場合 → 領域ごとのモード方針とトークン分離を記述する
• 引用・コードブロック・コールアウト等の特殊コンテンツブロックを含む場合 → 本文との視覚的区別が十分か問う

When Principles Conflict の独自性:

• プロダクト固有のジレンマを少なくとも2つ含める
• 「見た目 vs 実用性 → 実用性」のような普遍的な対立だけで終わらせない
• 例：EdTechなら「初学者のわかりやすさ vs 上級者の効率」、ECなら「ブランド演出 vs 購買導線の明瞭さ」

Step 3: 自己検証（内部処理）

生成した DESIGN.md をユーザーに提示する前に、以下の観点で内部チェックする。 問題があれば Step 2 に戻って修正する。チェック結果はユーザーに表示しない。

構造チェック:

• Frontmatter が含まれているか
• TL;DR が5行以内か（死守ラインがある場合は6行まで許容）
• Creative North Star に「This does NOT mean」があるか
• 対応表がテーブル形式で Reasoning 列があるか
• Color テーブルに Do/Don't 列があるか
• 外部トークンを取り込んだ場合、mode と token_source が入力実態に合っているか
• radius / shadow / border のトークンが主要な判断材料なら Effects セクションがあるか

品質チェック:

• 名前付きルールがプロダクト固有か（テンプレートの流用でないか）
• ルール名が Creative North Star のメタファーから自然に導出されているか
• Don't に肯定形の代替がペアになっているか
• 各セクションに具体値またはトークン名が含まれているか（曖昧な形容詞だけでないか）
• 推奨行数の範囲内か
• Typography、State Handling 等の主要対応表に Reasoning 列があるか（Density Guide は Use case 列で代替可）
• 取り込んだトークン値をそのまま並べるだけで終わっていないか（Why / When が補われているか）

表現力チェック:

• 日本語等CJK言語の長文コンテンツがある場合、body の line-height は言語特性を考慮した値か？
• State Handling の hover が opacity 変化だけに留まっていないか？要素の役割に応じた変化があるか？
• 感情的インタラクション（いいね、フォロー等）がある場合、通常操作と差別化された演出が定義されているか？
• 自由領域が各セクションに明示され、トーン（方向性のヒント）が添えられているか？
• コンテンツ系プロダクトで書体の使い分け（Serif/Sans等）を検討したか？（1書体が最適な場合もある）
• 引用・コードブロック等の特殊ブロックがある場合、本文との視覚的区別が定義されているか？

カラーコントラストチェック（必須）:

• Primary/Accent 色の上に白テキストを載せたとき、コントラスト比 4.5:1 以上か
• Muted テキスト色と Surface 背景のコントラスト比が 4.5:1 以上か
• 不合格の組み合わせがある場合、色を調整して再生成したか

一貫性チェック:

• Creative North Star と各セクションのルールが矛盾していないか
• Color Strategy の値と Typography の値がスペーシングスケールと整合しているか
• Global Constraints で宣言した基準（WCAG AA等）をパレット内の全色が満たしているか

曖昧性チェック:

• 「控えめ」「適度に」「最小限」等の形容詞が数値や具体的基準なしに残っていないか
• 2つのルールが矛盾しうる場面で、When Principles Conflict に判断基準が記載されているか
• 頻出UIパターン（エラーステート、空ステート、ローディング）への視覚的な判断基準が欠落していないか

Step 4: ユーザーへの提示

生成した DESIGN.md をユーザーに提示する。

提示時のメッセージ：

DESIGN.md を生成しました。

**Creative North Star:** [メタファー名]

**セクション構成:**
- [含まれるセクションの一覧]

**特に確認してほしいポイント:**
- [Creative North Star のメタファーが意図に合っているか]
- [Color Palette の色が期待通りか]
- [Global Constraints に違和感がないか]

修正したい箇所があれば教えてください。
また、この DESIGN.md を使って実際にUIを1つ生成してみて、意図通りか確認しますか？

ユーザーから修正指示があった場合は、該当箇所を修正して Step 3（自己検証）→ Step 4（再提示）を繰り返す。

Step 5: デモ検証（ユーザーが希望した場合）

生成した DESIGN.md を使って、サンプルUIコンポーネント（例：ログインフォーム、カード一覧、ダッシュボードヘッダー等）を1つ生成する。

ユーザーのプロジェクトの技術スタックで生成する。不明な場合は HTML + Tailwind CSS で生成する。

ユーザーに「意図通りですか？」と確認し、必要に応じて DESIGN.md を修正する。

Step 6: ファイル保存

ユーザーの承認を得たら、プロジェクトルートに DESIGN.md として保存する。

必要であれば、DESIGN.md から W3C DTCG 形式の design-tokens.json を任意出力してよい。 ただし、これは外部ツールとの接続のための下支えであり、DESIGN.md の本文を置き換えるものではない。

W3C DTCG JSON を出力する場合の必須手順:

1. WebFetch で最新の公式 format spec（https://design-tokens.github.io/community-group/format/）を読む
2. その時点の仕様に合わせて JSON を組み立てる。記憶ベースで決め打ちしない
3. 参照した仕様URLと取得日を、隣接ドキュメント（例: design-tokens.meta.md）または生成時の説明文に記録する
4. dimension は spacing / radius / border-width / sizing を区別して出力し、用途が曖昧な値はユーザーに確認する

出力の目安:

• Color → color
• Font family → fontFamily
• Font weight → fontWeight
• Font size / spacing / radius / border width → dimension
• Shadow → shadow
• Motion duration → duration

判断原則:

• 標準に落とせるものは落とす
• ただし、Creative North Star / 競合時の優先順位 / 自由領域のトーンのような上位判断は DESIGN.md 本文に残す
• 「W3C DTCG に準拠していること」自体を目的化しない

保存後のメッセージ：

DESIGN.md をプロジェクトルートに保存しました。

[必要な場合のみ] W3C DTCG 形式の `design-tokens.json` も出力しました。

**次のステップ（推奨）:**
1. CLAUDE.md に `@DESIGN.md` を追記すると、AIが自動で参照します
2. Claude Design や他のトークン対応ツールに渡す場合は、最新仕様に合わせた `design-tokens.json` を併用できます
3. 使いながら気になった点があれば、いつでも修正してください

**この DESIGN.md を見直すタイミング:**
- 画面数が10を超えたとき（Component Patterns の拡充が必要になります）
- 新しい種類のUIパターンが出てきたとき（例: データ可視化、マルチステップフォーム）
- 3ヶ月以上経過したとき（Color Strategy や Typography の微調整）
見直したくなったら `/design-md:generate` を再実行してください。既存の内容を読んだうえで更新を提案します。

---

リソース

• ../../DESIGN-MD-SPEC.md — フォーマット仕様
• resources/writing-guide.md — 記述ガイド（Before/After）
• resources/examples/saas-dashboard.md — BtoB SaaS ダッシュボードの例
• resources/examples/creator-platform.md — クリエイタープラットフォームの例
• resources/examples/minimal-zen.md — ミニマル瞑想アプリの例（ミニマムレベル）