molten-design

デザインシステム概要

AI コーディングエージェントが UI を生成する際に、一貫して適用できるデザインシステムドキュメントをユーザーが作成できるよう支援します。このファイルは Google Labs の DESIGN.md 仕様（YAML トークンのフロントマター＋順序付きの説明セクション）に準拠し、モーション、アイコン、アクセシビリティの拡張セクションを任意で追加できます。

入力パス（標準）： molten-brand の molten-docs/brand/brand.md。古いプロジェクトでは、プロジェクトルートの brand.md または /docs/brand.md を使用します。

出力パス（標準）： リポジトリルートの molten-docs/design/design.md。存在しない場合は molten-docs/design/ ディレクトリを作成します。

プレビューパス（標準）： molten-docs/design/example.html。デザイン概要の作成後、デザインシステムの使用例を示す、自己完結型の HTML プレビューを作成します。

このスキルは、molten-brand のビジュアル面を担います。ブランド戦略はブランド概要に、ビジュアルアイデンティティはデザイン概要に記載します。

最初に確認すること：デザイン対象

各実行の開始時に、このセッションのデザイン対象を 1 つ決めます。同じ作業で、ランディングページのマーケティング UI と、Web アプリ、モバイルアプリ、デスクトップアプリのプロダクト UI を混在させないでください。

ユーザーがすでに対象を明確に指定している場合（例：「ランディングページのデザインシステム」「モバイルアプリ UI」「SaaS ダッシュボード」）に限り、この確認を省略します。

構造化された質問ツールを使用します。

「このデザインシステムは何を対象にしていますか？」

選択肢：

• ランディングページ — マーケティング／コンバージョンページ（ヒーロー、セクション、CTA）。molten-landing と組み合わせます
• Web プロダクト — ブラウザー上で動作するアプリ UI（ダッシュボード、フォーム、ナビゲーション、複雑なワークフロー）
• モバイルプロダクト — スマートフォンを主な対象とするアプリ UI（リスト、タブ、親指の可動域、ネイティブ風のパターン）
• デスクトッププロダクト — デスクトップアプリ UI（ウィンドウの枠、メニュー、複数ペインのワークフロー、キーボード中心の操作）
• おまかせ — brand.md とコンテキストから推定（id: choose_for_me）

ユーザーがおまかせを選んだ場合は、brand.md とユーザーのプロンプトから推定します。

• マーケティングサイト、ウェイトリスト、ローンチ、単一ページのコンバージョン施策 → ランディングページ
• SaaS、管理画面、開発者ツール、社内ツール、ダッシュボード、レスポンシブなブラウザーアプリ → Web プロダクト
• コンシューマー向けアプリ、現場向けツール、外出先での使用を想定したスマートフォン中心のワークフロー → モバイルプロダクト
• Electron、ネイティブデスクトップアプリ、メニューバー、コマンドパレット、IDE／開発ツール、キーボード中心の複数ウィンドウアプリ → デスクトッププロダクト

選択内容とその理由を一文で伝えてから、続けてください。

デザイン対象に応じたリファレンスの振り分け

デザイン対象を決めたら、Pinterest の参照、トークン、コンポーネント、プレビューについて判断する前に、該当するリファレンスを 1 つだけ読みます。

選択した対象	必須のリファレンス
ランディングページ	references/landing-page.md
Web プロダクト	references/web-app.md
モバイルプロダクト	references/mobile-app.md
デスクトッププロダクト	references/desktop-app.md

これらのリファレンスには、対象に応じたレイアウト、情報密度、コンポーネントのセット、Pinterest 検索の基点、プレビュー範囲、対象ごとの注意事項が記載されています。共通の基盤として SKILL.md を維持してください。トリガーと出力が実質的に異なる場合を除き、デザインワークフロー全体を別々のスキルに重複して記載しないでください。

一度に扱うデザイン対象は 1 つ

• この実行におけるすべての判断（トークン、コンポーネント、Pinterest 検索、example.html、注意事項）を、選択した対象だけに絞ります。
• design.md の概要と前提のセクションにデザイン対象を記録します（例：Design surface: landing page）。
• ユーザーが複数の対象（例：ランディングページとWeb アプリ）を必要とする場合は、選択した対象について今回の実行を完了してから、次の対象に向けて改めて molten-design を実行します。セッションの途中で対象範囲を広げないでください。

まずは確認：スピード重視か、詳細重視か

このスキルを使う人の多くはデザイナーではありませんが、それでも、どの程度のガイダンスを希望するかを選べるようにしてください。

ファイルを作成する前に、ユーザーがプロンプトですでに「fast」「quick」「detailed」「guided」など、同等の希望を示していない場合は、どちらの進め方にするか尋ねてください。

デザイン対象とスピード重視か詳細重視かの両方がまだ決まっていない場合は、構造化された質問ツールで1つにまとめて尋ねてください。

ワークフローの選択肢には、構造化された質問ツールで次の2つをそのまま使用してください。

• Fast draft： ブランド概要を読み、必要であれば平易な言葉で質問を最大3つ行い、トークン単位の選択を推定してから、design.md と example.html を作成します。
• Detailed guided pass： 不要な専門用語を避けて平易な言葉を使いながら、ファイルを書き始める前に、ユーザーとより多くの判断事項について確認します。

ユーザーがFast draftを選んだ場合は、次の手順で進めてください。

1. デザイン対象（ランディングページ、Web 製品、モバイル製品、デスクトップ製品）を確認します。
2. references/ から、該当するデザイン対象のリファレンスを読みます。
3. ブランド概要、既存の design.md（存在する場合）、既存の UI スタイルを読みます。
4. まだスキップも完了もしていない場合は、**Visual Reference Discovery（Pinterest）**を提案します。
5. 答えを推定できない場合に限り、平易な言葉で質問を最大3つ行います（確認済みの Pinterest リファレンスで雰囲気や方向性が分かる場合は、質問数を減らします）。
6. 選択したデザイン対象に合わせて、デザインの判断は自分で行います。
7. molten-docs/design/design.md を作成または更新します。
8. molten-docs/design/example.html を作成します。
9. ユーザーが具体的なドラフトを見て意見を述べられるよう、前提を列挙します。

Fast draft モードでは、次のような質問はしないでください。

• 「システムでアクセントカラーをどのように使いますか？」
• 「インターフェースのニュートラルカラーは、どのような色味にしますか？」
• 「デザイン概要では、背景をどのように指定しますか？」
• 「セマンティックカラーはどのように扱いますか？」
• 「システムでフォントをどのように組み合わせますか？」
• 「システムの基本スペーシングはいくつにしますか？」
• 「システムで立体感をどのように表現しますか？」
• 「システムで角の丸みをどのように設定しますか？」

これらの詳細は、molten-docs/brand/brand.md、既存のプロジェクトスタイル、控えめなデフォルト設定から推定してください。

ユーザーには、平易な言葉で次のようなことだけを尋ねてください。

• 遵守したい既存のロゴ、Web サイト、ブランドカラー
• たとえば、堅実、親しみやすい、高級感がある、活気がある、落ち着いた、実用的といった、希望する雰囲気
• たとえば、SaaS アプリ、マーケティングサイト、開発者向けツール、一般消費者向けアプリ、社内ツールといった、製品の種類
• ブランドのイメージに近い、参考にしたい Web サイトやアプリ（任意）
• 避けたいビジュアル要素

ユーザーが「choose for me」「use best practices」「you decide」と言った場合、または Fast draft を選んだ後に希望を示さなかった場合は、自分で判断して進めてください。

詳細なガイド付きプロセス

ユーザーが詳細な選択肢を選んだ場合、またはデザインを細かく調整したい、トークンを調整したい、デザイナーレベルのワークショップを行いたい、初回ドラフトを見た後にさらに詳しい作業をしたいと明示した場合は、この方法を使用してください。

詳細な進め方でも、まずは平易な言葉で選択肢を示し、回答をトークン単位の詳細に反映するのは自分で行ってください。

運用ルール

• 対話型の実行を開始する際は、ユーザーに次のように伝えてください。「このスキルを使う際は、音声モードでフィードバックを口述するのが最適です。」
• デザインを決める前に、ブランドブリーフを読んでください： molten-docs/brand/brand.md、次にプロジェクトルートにある旧版の brand.md または /docs/brand.md を読みます。成熟度、個性、参考要素、避けるべき要素、第一印象の手がかり、アクセントカラーの指針など、視覚面に関する示唆をすべて抽出してください。デザイン対象が明らかになった後（または対象として おまかせ を推測する際）に行ってください。
• デザインを決める前に、該当する対象のリファレンスを読んでください： references/landing-page.md、references/web-app.md、references/mobile-app.md、または references/desktop-app.md。
• ユーザーのプロンプトからすでに明らかな場合を除き、毎回の実行開始時にデザイン対象について質問してください。
• ユーザーがすでに進め方を選んでいる場合を除き、ファイルを作成する前に、Fast と Detailed のどちらで進めるかを質問してください。
• 1回の実行で扱う対象は、ランディングページ、Web製品、モバイル製品、デスクトップ製品のうち1つだけにしてください。1回の実行で複数の対象を混在させないでください。
• Fast ドラフトの質問数の上限内で、質問を簡潔にまとめ、少数ずつ尋ねてください。ユーザーがDetailedの進め方を選んだ場合は、その質問数の上限に従ってください。
• チャットで自由回答形式の質問をする際は、ユーザーが回答を指定しやすいよう、すべての質問に番号を付けてください。特に音声モードでの口述を想定してください。
• 推測できる場合は質問せずに推測してください。選択肢が平易な言葉で示され、ユーザーの負担を本当に軽減できる場合に限り、構造化質問ツールを使用してください。
• エージェント別の構造化質問ツール：
  • Codex： request_user_input
  • Claude Code： AskUserQuestion
  • Cursor： AskQuestion
• 参考にするWebサイト、既存アセット、好ましくないビジュアル、製品の背景など、自由回答が必要な質問は、会話形式で尋ねてください。
• チャットの文章で選択肢を文字や箇条書きで列挙しないでください。選択式の質問には構造化質問ツールを使い、自由回答の質問には通常の文章を使ってください。
• 同じ段階でまとめられる構造化質問は、1回のツール呼び出しにまとめてください。
• アンケートではなく、コンサルタントとして対応してください。 最初の確認事項（デザイン対象とFastまたはDetailedの選択）より後に行う構造化質問には、ユーザーが判断を委ねられるよう、最後の選択肢として必ず「おまかせ」を含めてください。選択された場合は、brand.md と戦略的な文脈に最も合う案を選び、次に進む前に、その選択と理由を一文で伝えてください。黙って選択せず、必ず判断を明示してください。
• チャットで自由回答の質問をする際も、同じように選択を委ねられるようにしてください。質問の末尾に「または おまかせ と言ってください。brand.md をもとにこちらで選びます。」と添えてください。判断を委ねられた場合は、具体的な値（正確な16進カラーコード、フォント名、寸法など）を提案し、その理由を一文で説明してください。
• brand.md にすでに答えが記載されている場合は、同じことを再度尋ねないでください。内容が曖昧な場合に限り、値を示して確認してください。
• 「モダン」「すっきり」「プレミアム」「ミニマル」といった曖昧な好みの表現にはそのまま従わず、具体的なトレードオフに置き換えてください。
• デザインを決める際は、実用性を保ってください。フォントファミリーは最大2種類、タイポグラフィのレベルは通常8～12種類、名前付きカラーパレットは4～6種類、スペーシングの基準は1つに統一してください。
• 事実、仮定、未解決の質問を分けてください。
• このスキルが有効な間は、アプリのコードを生成しないでください。
• ブランドのペルソナ、声、メッセージは定義しないでください。ブランドブリーフに従ってください。
• ユーザーから十分な情報を得て、Pinterestの参考情報について確認を取ったか、明示的に見送った後に限り、デザインブリーフを作成または更新してください。
• ファイルへの書き込みが可能な場合は、molten-docs/design/design.md と molten-docs/design/example.html を作成または更新してください（必要に応じて親ディレクトリも作成してください）。書き込みができない場合は、両ファイルの完全な内容を提示し、保存先として指定されたパスをユーザーに伝えてください。

構造化された質問とチャットを使い分けるタイミング

Fast draft モードでは、以下の場合に限り、構造化された質問ツール（request_user_input / AskUserQuestion / AskQuestion）を使用します。

• 回答が、有限の選択肢からの1つまたは少数の選択である。
• ユーザーが、トレードオフを並べて確認できると役立つ。
• 選択肢がデザインシステムの内部仕様ではなく、平易な言葉で表した結果である。

このスキルで構造化された質問を使う場合の適切な例：

• デザイン対象：ランディングページ / ウェブ製品 / モバイル製品 / デスクトップ製品
• 平易な言葉で表した全体的な印象（例：真面目 / 親しみやすい / 高級感がある / 活気がある / 落ち着いた / 実用的）
• 製品の種類（例：SaaS アプリ / マーケティングサイト / 開発者向けツール / コンシューマーアプリ / 社内ツール）
• ビジュアルの類型（例：落ち着いた SaaS / 高級感のあるエディトリアル / 開発者向けツール / 親しみやすいコンシューマー向け / 大胆なローンチページ）
• ブランド概要だけをもとに進めるか、任意の参考ウェブサイトも含めるか

次の場合は、構造化された質問ツールを使わず、チャットで会話形式で尋ねます。

• 回答が自由記述である場合：参考ウェブサイト、既存のブランドカラー、避けたいもの、製品に関する背景など。
• 曖昧な回答に対して異議を唱える場合。
• フェーズを進める前に確認または要約する場合。

「私に選ばせて」パターン（必須）

このスキルで行うすべての質問では、ユーザーが判断をあなたに委ねられるようにする必要があります。あなたはデザインコンサルタントとして対応しています。ユーザーはいつでも「あなたが決めて」と伝えるだけで、あなたが根拠に基づきブランドに沿った選択をすると信頼できる必要があります。

構造化された質問ツールの場合

必ず最後の選択肢として、id: choose_for_me と、選択する行動および判断の根拠を示すラベルを追加します。例：

• "私に選ばせて — brand.md に基づいて提案する"
• "あなたが決めて — ブランドに最も合うものを選ぶ"
• "私に選ばせて — このブランドの成熟度に最も合う無難な初期設定にする"

ユーザーが choose_for_me を選択した場合：

1. brand.md の情報、戦略的な背景、DESIGN.md のベストプラクティスに最も合う選択肢を選びます。
2. 選択を明確に伝えます。「X を選びます。理由は、[brand.md または調査内容に基づく1文の説明] だからです。」
3. 選択が労力をかけないと元に戻せない場合（例：メインカラー、フォントファミリー）を除き、追加確認をせずに次のフェーズへ進みます。

チャットで自由記述の質問をする場合

質問の最後に、明確なオプトアウトの選択肢を付けます。

「…または あなたが選んで と伝えていただければ、brand.md に基づいて値を提案します。」

ユーザーが判断を委ねた場合は、具体的な値を1つと、その理由を1文で提案します。範囲や「X 前後」といった曖昧な値は提示せず、トークンに設定する正確な値を示します。

フローの例

質問（構造化された質問ツール）：「製品にどのような印象を持たせたいですか？」 選択肢：真面目 / 親しみやすい / 高級感がある / 活気がある / 落ち着いた / 実用的 / 私に選ばせて — brand.md に基づいて提案する

ユーザーが「私に選ばせて」を選択。

エージェントの返答：「落ち着いた SaaS を選びます。理由は、brand.md が控えめな自信と、明快で信頼感のあるインターフェースを求めているためです。この方向性に基づいて、詳細なトークンを決めます。」

判断を委ねてもらわない場合

ユーザーが brand.md またはそれ以前の会話で明確な制約をすでに示している場合は、再度尋ねず、その制約を適用したことを伝えます。

ブランド概要を取り込む

デザイン対象が選択された（または推定された）後、Pinterest やトークンの作業に進む前に、以下を行います。

1. molten-docs/brand/brand.md（正規のファイル）を確認します。見つからない場合は、プロジェクトルートの brand.md、または旧プロジェクトの場合は /docs/brand.md を確認します。
2. 存在する場合は読み込み、以下を抽出します。
   • ブランドの成熟度、性格特性、組み合わせて使うトーンの特徴
   • 第一印象を表す言葉
   • ビジュアルの参考例と避けるべき例
   • リスクへの姿勢とカテゴリーに対するスタンス
   • ペルソナから読み取れる情報密度と感情状態への示唆
3. 抽出したビジュアルの情報をそのまま活用します。実際に曖昧さや矛盾がある場合に限り、ユーザーに確認または修正を求めます。
4. brand.md がない場合は、先に molten-brand を実行するか（推奨）、それなしで進めるかをユーザーに尋ねます。

既存のデザインブリーフとサーフェスレイヤー

molten-docs/design/design.md を唯一の正式なデザインブリーフとして使用します。ユーザーからブランドを分けるよう明示的に依頼されない限り、ランディングページ、ウェブ、モバイル、デスクトップ用に、互いに関連のない別々のデザインシステムを作成しないでください。

出力は次のように構成します。

• 共通コア： 色、セマンティックカラー、タイポグラフィのファミリー、基本の文字サイズスケール、角丸の方針、基本の余白、モーションの原則、アイコノグラフィー、アクセシビリティのデフォルト設定。
• サーフェスレイヤー： 選択したサーフェスのレイアウト、密度、コンポーネントセット、ナビゲーションパターン、セクションパターン、インタラクション状態、プレビュー範囲。

molten-docs/design/design.md がすでに存在する場合：

1. 新しいトークンを決める前に、その内容を読みます。
2. ユーザーからブランドシステムの再設計を明示的に依頼されない限り、共通コアのトークンは変更しません。
3. 選択したサーフェスレイヤーのみを追加または更新します。
4. Assumptions に、継承内容を記録します：既存のdesign.mdから共通コアを継承。更新したサーフェスレイヤー：[surface]

初めてデザインを作成する場合は、選択したサーフェス用の完全な design.md を作成し、将来ほかのサーフェスに共通コアを引き継げるよう、どの決定が共通コアで、どれがサーフェスレイヤーかを明記します。

ビジュアルリファレンスの探索（Pinterest）

brand.md を読み込んだ後、デザイントークンを確定したり design.md を作成したりする前に、Pinterest で参考画像を厳選します。これにより、デザインシステムの専門用語で好みを説明するよう求めることなく、デザイナーではない人にも具体的なビジュアルの方向性を示せます。

このフェーズ（参考画像の確認）が完了するか、明示的にスキップされるまで、design.md を作成しないでください。

Pinterest の検索語を5つ生成する

brand.md、選択したデザインサーフェス、すでに示されている平易な言葉での印象、選択したサーフェスリファレンスにあるPinterest 検索の切り口に基づいて、検索語をちょうど5つ作成します。フェーズをユーザーに提示する前に作成してください。

ルール：

• 5つすべての検索語を、選択したサーフェスの範囲内に収めます。無関係なコンセプト（パレットのみ、汎用的なタイポグラフィ、抽象的なムードボード、エディトリアル印刷物、ロゴマークなど）に検索を広げないでください。
• 選択したサーフェスリファレンスのアンカーワードと例のパターンを使用します。
• 自然に使える場合は、brand.md からブランドや文脈を表す修飾語を1つ加えます（カテゴリ、印象、B2B/B2C、ダーク/ライトなど）。ただし、すべての検索語にサーフェスのアンカーワードを必ず含めます。
• 検索語は3〜6語にし、視覚的で Pinterest の検索に適したものにします。「モダン」「高級」「美的」のような抽象的な戦略用語だけにはしないでください。
• 反参考例や、ユーザーが避けたいと述べたものは除外します。
• 同じパターンを重複させず、選択したサーフェスのパターンの範囲内で変化をつけます。
• 5つすべてが選択したサーフェスに明確に属していない場合は、ユーザーに提示する前に書き直します。

フェーズを提示する

ユーザーがすでに参考画像を添付している場合、または参考画像をスキップすると明示している場合は、このサブセクションを省略します。

Pinterest を見たいかどうかは尋ねないでください。すでに用意した内容を提示してから、検索結果を開くかどうかを尋ねます。

チャットでは、次のように伝えます。

ブランドに合うビジュアルの参考画像を Pinterest で集めました。検索結果を開いて、デザインの方向性の参考としてお気に入りを1つ選べるようにできます。

用意した5つの検索語はこちらです。

1. …
2. …
3. …
4. …
5. …

次に、構造化質問ツールを使用します。

「これらの Pinterest 検索結果を開きますか？」

選択肢：

• はい — 開いて、お気に入りを選ぶ
• スキップ — brand.md だけをもとに判断する
• 選んでください — brand.md に基づいておすすめする（id: choose_for_me）

選んでくださいが選ばれた場合：brand.md に強いビジュアルリファレンス、または明確な成熟度・パーソナリティの指標がすでにある場合はスキップをおすすめします。ブランドブリーフに視覚的な手がかりが少ない場合、またはユーザーが詳細な手順を選んだ場合ははいをおすすめします。おすすめを1文で伝えてから、その選択に従います。

異なる切り口をユーザーから求められた場合にのみ、新しい検索語を作成します。Pinterest を使うかどうかを改めて尋ねないでください。

Pinterest のタブを5つ開く

各検索語の URL を作成します。

https://www.pinterest.com/search/pins/?q={url_encoded_term}

（スペースは + または %20 に URL エンコードします。）

ユーザーのデフォルトブラウザーで、5つすべてを別々のタブで開きます。現在の環境で動作する最初の方法を優先し、開けなくてもワークフローを止めないでください。

1. シェル（macOS）： open "url1" "url2" "url3" "url4" "url5"
2. シェル（Linux）： xdg-open "url1" "url2" ...（複数の URL に対応している場合は、1回の呼び出しで実行）
3. シェル（Windows）： URL ごとに start "" "url1" を実行
4. cursor-app-control の open_resource： 利用可能な場合は URL ごとに1回呼び出す
5. フォールバック： ユーザーが手動で開けるよう、5つのリンクを Markdown として貼り付ける

開いた後（またはフォールバックの場合）は、ユーザーに次のように伝えます。

5つのタブを確認してください。お気に入りのピンを1つ選んでください。目指したい方向性に最も近いと感じる例です。その画像1枚だけをここに貼り付けるか添付してください（スクリーンショット、保存した画像、またはドラッグ＆ドロップ）。デザインシステムを確定する前に、その画像から読み取った内容を説明します。

画像が送られるまで待ちます。ユーザーが参照画像を1つ送信するか、スキップすると伝える（例：「スキップ」「参照画像なし」「参照画像なしで続けて」）まで、トークンの決定に進まないでください。

参照画像を解釈する

ユーザーが画像を1枚添付したら、内容を分析し、わかりやすい言葉で次の見出しの下にまとめます。

• 色 — 主なパレット、アクセントの使い方、明るい色調か暗い色調か、暖色系か寒色系か、彩度
• タイポグラフィの印象 — サンセリフ／セリフ／等幅フォントの傾向、太さのコントラスト、見出しと本文の階層（明らかな場合のみ正確なフォント名）
• レイアウトと密度 — 余白、グリッド型かエディトリアル型か、情報密度
• 形状と奥行き — 角丸の半径、シャドウに対する境界線の使い方、フラットかレイヤー構造か
• ムード — 目に見える特徴に結び付いた具体的な形容詞を2〜3個。曖昧な好みを表す言葉は避ける
• トークンへの反映 — design.md への具体的な反映内容（例：「角丸半径12px」「温かみのあるオフホワイトのサーフェス、約#FAF8F5」「ニュートラルなベースに、彩度の高いアクセントを1色」）
• 避ける点 — brand.md のアンチリファレンスと矛盾する要素、または使いやすさを損なう要素（コントラスト、タップ領域など）

画像が不鮮明、低解像度、または無関係な場合は、その旨を伝え、別のピンを送るかスキップしてよいか尋ねます。

確認ゲート（必須）

参照画像をトークンに反映する前に、明示的な承認を得ます。利用可能な場合は、構造化質問ツールを使います。

「参照画像について、気に入った点がこの解釈と一致していますか？」

選択肢：

• はい — この方向性をデザインシステムに反映する
• 調整 — 変更したい点を説明する
• 別の参照画像 — 別の画像を貼り付ける
• 参照画像をスキップ — brand.md のみを使う

その後：

• はい： 採用する要素を具体的な YAML トークンと design.md の説明文に反映します。Assumptions に次を記録します：Visual reference: user-selected pin → [採用した要素の1行要約]。
• 調整： 修正内容を受けて解釈を見直し、承認またはスキップされるまで再確認します。
• 別の参照画像： 新しい画像だけを使って解釈と確認を繰り返します（一度に扱う参照画像は1枚です）。
• スキップ： 破棄した参照画像をトークンに反映せず、brand.md のみをもとに進めます。

参照画像を黙って反映してはいけません。design.md を作成する前に、ユーザーの確認またはスキップが必要です。

詳細な第2パス

ユーザーがより細かな調整を明示的に求めた場合に限り、最初の design.md と example.html のドラフトを作成した後で、この工程を実行します。

この第2パスでは、色、タイポグラフィ、余白、レイアウト、エレベーション、形状、コンポーネント、モーション、アイコン、画像、アクセシビリティを調整できます。まず現在のプレビューのどこに違和感があるかを尋ね、的を絞って変更します。最初のヒアリング全体をやり直すことは避けてください。

詳細な第2パスでも、まずは平易な言葉で質問することを優先します。可能な限り、ユーザーの回答は自分でトークン単位の詳細に落とし込んでください。

molten-docs/design/design.md を生成する

十分な情報を収集したら、以下の構成で molten-docs/design/design.md にファイルを作成します。YAML フロントマターは規範的なもので、説明文はその根拠を示します。

ファイルでは、次の内容を明確に分けてください。

• 共通コア： ランディングページ、Web、モバイル、デスクトップの各画面で安定して維持すべき、再利用可能なブランドシステムのトークンと原則。
• 画面レイヤー： 選択した画面のレイアウト、情報密度、コンポーネントの優先順位、プレビューのガイドライン。

---
version: alpha
name: [Design System Name]
description: [One sentence describing the system]
colors:
  primary: "#RRGGBB"
  secondary: "#RRGGBB"
  tertiary: "#RRGGBB"
  neutral: "#RRGGBB"
  surface: "#RRGGBB"
  on-surface: "#RRGGBB"
  error: "#RRGGBB"
typography:
  headline-display:
    fontFamily: [Family]
    fontSize: [Size]
    fontWeight: [Weight]
    lineHeight: [Line height]
    letterSpacing: [Tracking]
  headline-lg:
    fontFamily: [Family]
    fontSize: [Size]
    fontWeight: [Weight]
    lineHeight: [Line height]
  body-md:
    fontFamily: [Family]
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-md:
    fontFamily: [Family]
    fontSize: 14px
    fontWeight: 600
    lineHeight: 1
    letterSpacing: 0.02em
  label-sm:
    fontFamily: [Family]
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.05em
rounded:
  none: 0px
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px
spacing:
  base: 8px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-surface}"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary}"
---

# [Design System Name]

Visual identity for [product name]. Pairs with `molten-docs/brand/brand.md` for brand strategy and voice.

## Overview

[Holistic description of look and feel. Personality, target audience, emotional response. Reference brand.md. State the design surface — landing page, web product, mobile product, or desktop product — and what this system optimizes for.]

## Shared Core

[Describe the stable cross-surface choices: color philosophy, type family pairing, radius philosophy, spacing base, motion posture, iconography posture, and accessibility defaults. If this file inherited an existing shared core, say so.]

## Colors

[Shared core. Prose describing each key palette with its role. One bullet per palette, named with descriptive language (e.g. "Midnight Forest Green") and the hex from tokens.]

- **Primary (#RRGGBB):** [Role and when to use]
- **Secondary (#RRGGBB):** [Role and when to use]
- **Tertiary (#RRGGBB):** [Role and when to use]
- **Neutral (#RRGGBB):** [Role and when to use]

## Typography

[Shared core. Prose describing the type strategy. Family choices and their roles.]

- **Headlines:** [Family, weight, voice it creates]
- **Body:** [Family, size, readability decisions]
- **Labels:** [Family, treatment, where it appears]

## Layout

[Surface layer. Grid model, max width, spacing rhythm, containment strategy for the chosen surface. Use the selected `references/*.md` file.]

## Elevation & Depth

[How visual hierarchy is conveyed. Shadows, borders, tonal layers, or flat.]

## Shapes

[Corner radius philosophy and where deviations occur.]

## Components

[Surface layer. Per-component prose: anatomy, variants, states, accessibility notes. Token specifics live in front matter. Include only components relevant to the chosen surface from the selected reference — e.g. hero/CTA/proof for landing page; nav/forms/tables for web product; tab bar/list rows/FAB for mobile product; window chrome/menus/panes for desktop product.]

### Buttons

- Anatomy: [parts]
- Variants: [primary, secondary, ...]
- States: default, hover, focus, active, disabled
- Accessibility: [target size, focus ring, ARIA]

### Input Fields

[Same structure]

### Cards

[Same structure]

## Do's and Don'ts

- Do [specific rule]
- Do [specific rule]
- Don't [specific rule]
- Don't [specific rule]
- Don't [specific rule]

## Motion & Animation

[Optional. Only if defined.]

## Iconography

[Optional. Only if defined.]

## Accessibility

[Optional. Minimum contrast, focus rings, target sizes, reduced-motion.]

## Open Questions And Assumptions

### Open Questions
- [Question that still needs a user decision]

### Assumptions
- [Assumption made due to missing information]
- [Design surface: chosen surface]
- [Shared core: newly created or inherited from existing design.md]

### Next Step
Reference `molten-docs/design/design.md` from your agent config (CLAUDE.md, AGENTS.md, `.cursor/rules/`) so it loads every session. Validate with `npx @google/design.md lint molten-docs/design/design.md`.

molten-docs/design/example.html を生成する

molten-docs/design/design.md の作成後、デザインシステムを人が読みやすい形でプレビューできる molten-docs/design/example.html を作成します。

目的：

• 抽象的なデザイントークンを、デザインの専門家でない人にも具体的に示します。
• ユーザーがブラウザーですぐに開けるものを提供します。
• 視覚的な見本を通して、後続のエージェントが意図された見た目や雰囲気を理解できるようにします。

ルール：

• 自己完結させます。インライン CSS を含む HTML ファイル 1 つで構成してください。フレームワーク、ビルド手順、パッケージのインストール、CDN、外部アセットは不要です。
• design.md の最終的なトークンを基にした CSS カスタムプロパティを使用します。
• 本番用のアプリコードは作成しないでください。これはドキュメントとプレビューのみです。
• 洗練された仕上がりにしつつ、すばやく確認できる小さな例にしてください。
• トークンが不足している、または曖昧な場合は、プレビューのためだけに追加の質問をせず、design.md にすでに記録されている前提を使用します。

プレビューには次の内容を含めてください。

• 短いタイトルと、デザインのテーマを一文で示す説明（デザイン対象の画面を明記）。
• トークン名と HEX 値を添えたカラースウォッチ。
• ディスプレイ／見出し、本文、ラベル、キャプションのタイポグラフィ見本。
• ボタンの例：プライマリー、セカンダリー、破壊的操作、無効、フォーカス表示。
• 入力欄の例：デフォルト、フォーカス時、エラー、無効（Web およびモバイルのプロダクト画面）。
• 余白、角丸、境界線、シャドウ、コンテンツ階層を示すカードの例。
• 選択した画面に合わせた、現実的な要素を組み合わせた UI セクションを 1 つ：
  • ランディングページ： ヒーロー ＋ CTA ＋ 実績または機能を示すセクション
  • Web プロダクト： ナビゲーション／サイドバーの一部と、カード、フォーム、または表
  • モバイルプロダクト： 幅約 390px のフレーム、ステータス／ヘッダー領域、リストまたはタブバー、親指で操作しやすいコントロール
  • デスクトッププロダクト： デスクトップ幅のアプリウィンドウ、タイトル／メニュー領域、サイドバーまたは分割ペイン、キーボード操作を重視したコントロール領域

次の構成を使用してください。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>[Design System Name] Preview</title>
    <style>
      :root {
        --color-primary: [value from design.md];
        --color-secondary: [value from design.md];
        --color-tertiary: [value from design.md];
        --color-neutral: [value from design.md];
        --color-surface: [value from design.md];
        --color-on-surface: [value from design.md];
        --color-error: [value from design.md];
        --font-body: [font stack from design.md];
        --radius-sm: [value from design.md];
        --radius-md: [value from design.md];
        --space-sm: [value from design.md];
        --space-md: [value from design.md];
        --space-lg: [value from design.md];
      }
    </style>
  </head>
  <body>
    
  </body>
</html>

プレースホルダーではなく、実際に使われていそうなラベルを優先してください。たとえば、「ボタン」や「カードのタイトル」より、「プロジェクトを開始」、「デモを予約」、「メールアドレス」、「ローンチ準備状況」のほうが適切です。

品質チェック

molten-docs/design/design.mdを最終確定する前に、次の点を確認してください。

• YAML フロントマターが有効であること（---のフェンスが対応しており、キーが重複していない）。
• セクションが仕様の順序（概要、共有コア、色、タイポグラフィ、レイアウト、エレベーションと奥行き、形状、コンポーネント、避けるべきこと）に並び、拡張項目がその後に追加されていること。
• primaryカラーが定義されていること（定義されていない場合、リンターが警告します）。
• すべての{token.path}参照が、定義済みのトークンに解決されること。
• コンポーネントで使用するすべてのテキストと背景の組み合わせで、WCAG AA のコントラスト基準を満たしていること。
• フォントファミリーが2種類以内であること。
• タイポグラフィのレベルがデフォルトで8〜12種類あり、それぞれに明確な役割があること。
• コンポーネントのバリアントでは、ネストではなく兄弟キー（button-primary-hover）を使用していること。
• 「避けるべきこと」が5つのルールで構成され、それぞれが具体的であること（曖昧な好みを示す言葉を使わない）。
• ブランド戦略、ペルソナ、ボイスをここで定義していないこと。これらはmolten-docs/brand/brand.mdに記載します。
• 選択したデザイン対象（ランディングページ、ウェブ製品、モバイル製品、デスクトップ製品）が「概要」と「前提条件」に明記され、一度に複数の対象を扱おうとしていないこと。
• 既存のdesign.mdを拡張する際に、共有コアの決定事項にラベルを付け、維持していること。
• 表層レイヤーの決定事項が、選択した参照ファイルと一致していること。
• ユーザーが「Choose for me」で委任したすべての決定事項が、その時点で示した1文の理由とともに「前提条件」セクションに記載されていること。
• Pinterest の参照が確認済みの場合、採用したビジュアル上の特徴を「前提条件」セクションに1行で記載していること。
• 残りの前提条件が明示されていること。
• molten-docs/design/example.htmlが存在し、単体で動作すること。
• プレビューで、最終確定したdesign.mdのトークンに一致する CSS 変数を使用していること。
• プレビューに、スウォッチ、文字サンプル、ボタン、入力欄、カード、および現実的な複合 UI セクションが含まれていること。
• プレビューが、本番アプリケーションのコードではなく、ドキュメントであることが明確であること。

npx @google/design.mdを利用できる場合は、次のコマンドを実行するようユーザーに提案してください。

npx @google/design.md lint molten-docs/design/design.md

リンターの指摘事項がある場合は、ファイルを最終版として扱う前に、ユーザーと一緒に確認してください。

参考資料

仕様、トークンスキーマ、リンターのルール、作成原則について詳しくは、プロジェクト内にあればdesign-md-research.mdを、なければ正規仕様のhttps://github.com/google-labs-code/design.mdを参照してください。