visual-designer

visual-designer — ビジュアル仕様と、ツールがある場合の実行

デザインツールを開く前に、ビジュアル制作物で何を伝え、どう構成するかを記述します。制作物は、プロダクトインターフェース（画面と状態）、プレゼンテーション（スライド）、インフォグラフィック（一度に読み通せる単一の面）、または読み手と目的があるその他のビジュアル成果物です。汎用的なドメインの例：小規模クリニック向け B2B アプリの予約リマインダーフローの 4 画面、またはそのフローをクリニックに説明する 12 枚のスライド。

成果物は仕様書です。制作は、セッションにそのためのツールがある場合にのみ開く分岐です — 詳しくは末尾の「実行可否の確認」をご覧ください。

呼び出されるタイミング

タイミング	呼び出し元／呼び出し先
ideation-engine によるプロトタイプの概要が作成されたとき	ideation-engine（.agents/skills/ideation-engine/SKILL.md）からの開始 — その概要にある主要なフローと最小限の画面が、インターフェース仕様の入力になります
ビジュアル仕様が作成されたとき	次は実行です。セッションに制作可能なツールがあれば、その場で提案します。なければ、このドキュメントがこの工程の終点となり、制作担当者がここから制作します
読み手と目的があるあらゆる制作物	前の工程がなくても、単独で呼び出せます。スライド資料、インフォグラフィック、明日までに必要な画面などが対象です

最初のルール

制作物に含まれない内容を決して作り出しません。 裏付けとなるデータのない画面、誰も測定していない数値を載せたスライド、出典が記載されていないインフォグラフィックは、完成しているように見えても仕様としては不完全です。不足している情報は尋ね、不足したままのものは仕様書にギャップとして記載し、もっともらしい内容で決して埋めません。

インタビュー

構成を書く前に、.agents/skills/grill/SKILL.md#method の手法を使って、制作物の目的、読み手、成功条件を掘り下げます — パスを引用するだけで、内容は複製しません。特に重要なのは次の 3 つの質問です。どれも、担当者が「見栄えをよくしたい」と答えるだけでは解決しません。

• 誰が、どのような状況で読みますか？ 患者の合間にスマートフォンでスクロールする人と、プレゼンテーションを聴く人は同じではありません。
• 読み終えたあと、どんなことが起きる必要がありますか？ 1 つの行動、1 つの判断、1 つの理解です。目的が 3 つある制作物には、目的がないのと同じです。
• 伝わらなければ制作物が失敗となる、唯一の要素は何ですか？ それを軸に情報の優先順位を組み立て、ほかのすべてはその下位に置きます。

手法

共通のビジュアル基準です。パック内でビジュアル制作物について判断する必要があるツールは、このセクションをパス —.agents/skills/visual-designer/SKILL.md#method— で参照し、複製はしません。

1. 面ごとに優先順位は 1 つ

画面、スライド、または面には、主要な要素が 1 つあり、仕様書に明記します。主要な要素は最初に目に入り、最も大きいか、最もコントラストが強く、その条件を満たすのはそれだけです。主要な要素が 2 つあるなら、主要な要素は 0 です。目はどちらかを選びますが、こちらが意図したほうを選ぶとは限りません。

2. 余白もコンテンツ

空白は無駄なスペースではなく、優先順位を読み取りやすくするものです。空白を埋めるために追加された要素は、すでにある要素と競合します。余白を削らずに収まらないブロックは、収まりません — 何を削るかを決めるのであって、押し込むのではありません。

3. コントラストは意味を伝えるものであり、装飾だけに使わない

サイズ、太さ、色の違いは、何かを伝えるために使います — これが最初に来る、これは警告である、これは二次的である — そして仕様書では、違いごとにその意味を併記します。意味のないコントラストはノイズであり、有用なコントラストと同じだけ注意を消費します。意味を伝えるコントラストを色だけで表現することは決してありません。サイズ、太さ、位置も組み合わせることで、2 色を見分けられない読み手や、グレースケールで印刷された制作物にも意味が伝わります。

4. 1つのブロックに、1つのメッセージ

すべてのブロック――画面のセクション、スライド、インフォグラフィックの領域――は1つのことを伝え、1行で要約できます。その1行は、ブロックの内容を書く前に仕様書に記載します。要約できないものは、まだ十分に検討されていません。どれだけタイポグラフィを工夫しても、それを補うことはできません。

5. 望ましい状態ではないときの状態

空の状態、読み込み中の状態、エラー状態がないインターフェースは、仕様が半分しか定まっていません。想定される反論に対するスライドがないスライド資料も、仕様が半分しか定まっていません。それぞれの成果物について、都合の悪い状態と、その状態が起きたときに表示する内容を明確にします。

ビジュアル仕様書

最後に、成果物を、読み込まれたプロダクトノードの日付入りドキュメントとして、次の場所に作成します。

research/<YYYY-MM-DD>-visual-spec.md

日付を付け、上書きはしません。パスは、脳自身の tree.md にある content: */products/*/research/*.md の行の範囲内に収まるため、新しい glob も resolver の行も必要ありません。プロダクトノードがない場合は、同じファイル（<YYYY-MM-DD>-visual-spec.md）を代わりに現在のフォルダーに保存します。

仕様書には、次の5つのセクションをこの順で、指定された見出しをそのまま使って記載します。

## The piece and its purpose
## Structure and hierarchy
## Content, block by block
## Visual criteria applied
## Gaps and what it does not cover

• 成果物とその目的：成果物の種類、誰がどのような状況で読むのか、その後に何が起きる必要があるのか、そして必ず伝えなければならない唯一のこと。
• 構成と階層：画面、スライド、領域など、順番に並べた各要素と、それぞれの主要要素（主要と明記）。
• ブロックごとのコンテンツ：すべてのブロックについて、最初に1行のメッセージを示し、その後に実際の内容を記載します。具体的なテキスト、入れるデータ、画像や図とその内容を含めます。ダミーテキストではなく、実際に使うコピーを記載します。
• 適用したビジュアル基準：上記5つの要素のうち、各判断の根拠となったものと、いずれかに反する判断をした場合はその理由。
• 不足事項と対象外の内容：不足しているデータやコピー、それを提供する人、今回意図的に対象から外した状態や画面。

実行確認

ドキュメントを書き終えてから、その後に限り、この種の成果物を作成できるツールがセッションにあるかを確認します。たとえば、Figma MCP など、ハーネスに接続されたデザイン統合機能が該当し、インターフェースやスライドを扱えます。

• ツールがある場合：その旨を伝え、ツール名を挙げて、仕様書に基づく成果物の作成を提案します。作成は別のステップであり、オペレーターが依頼します。ドキュメントはすでに作成済みで、どちらの場合もそのまま残ります。作成する成果物は仕様書に従い、コンテンツを追加しません。不足しているものはすべて、創作で補わず不足事項として返します。
• ツールがない場合：ドキュメントを提示して、Figma を接続すれば、この同じスキルで作成できます と1行添えて終了します。何もインストールせず、認証情報を求めず、ツールがないことを理由に仕様書の質を下げることもありません。納品物は仕様書であり、ツールはそれを転記する手間を省くだけです。

インフォグラフィックや、接続されたツールの対象外となる成果物も、ドキュメントを提示して終了します。ツールを提案するのは、実際にその成果物を作成できる場合であり、単に接続されているからではありません。

この納品物が保証しないこと

ビジュアル仕様書は、成果物が機能することを検証するものではありません。実際に読まれ、理解され、行動につながるかどうかを判断できるのは、実際の読者だけです。また、プロダクトの機能を決めるものでもありません。仕様書で定めるフローは ideation-engine のプロトタイプブリーフに基づき、対象範囲は prd（.agents/skills/prd/SKILL.md）に基づきます。

保存先

スキルは成果物を作成する前に保存先を解決し、作成後に解決することはありません。ケースは3つ、保存先は2つです。

• プロダクトノードが読み込まれている場合：成果物は、そのノードの research/<YYYY-MM-DD>-<name>.md に保存されます。
• brain はあるものの、プロダクトノードがない場合 — まだワークスペースがない、またはワークスペースはあるがプロダクトノードがない場合：成果物は現在のフォルダー内のファイルに書き込まれます。
• brain がまったくない場合：成果物は現在のフォルダー内のファイルに書き込まれます。

プロダクトノードがない場合は、いずれにしてもファイルは現在のフォルダーに書き込まれます。終了メッセージには、直前に書き込んだパスだけを記し、その後は何も続けません。これは、このスキルが通常どおり終了する方法であり、例外として注釈するものではありません。

このスキルは、どの保存先を使うかを尋ねることも、3つ目の保存先を勝手に作ることもありません。

パックの残りは、一度に1つずつスキルをインストールします。まず .agents/skills/、次に .claude/skills/ を確認し（両方にあるスキルは1つとして数えます）、まだないものだけを提示します。これはセッションごとに1回だけです。このスキルがそのセッション内で初めて終了するときに提示し、同じ成果物または別の成果物で後から終了するときには提示しません。

• grill — npx skills add pedroromeroluna/ai-first-product-skills --skill grill
• ideation-engine — npx skills add pedroromeroluna/ai-first-product-skills --skill ideation-engine
• prd — npx skills add pedroromeroluna/ai-first-product-skills --skill prd

パック全体を一度にインストールするには、npx skills add pedroromeroluna/ai-first-product-skills を実行します。このコマンドはパックに含まれるものをインストールします。上記に記載されたものは、スキル名を指定してインストールします。