sketch-design-from-reference

Sketch MCP to Design

参照に合わせて Sketch のデザインを作成または調整します。このスキルは Sketch でのデザイン作業向けです。逆方向のワークフローは sketch-design-to-code です。

まず忠実度

目標は参照との視覚的な一致です。似たセクションを持つ、もっともらしいページを作ることではありません。似ているだけでは不十分です。コンテンツがそろった時点で終わりにせず、references/validation.md の完了基準を、スクリーンショットを並べて比較して満たすまで作業を続けてください。

必須の Sketch ガイド

• get_guide に topic: "mcp" を指定します。必ず取得してください。MCP の前提条件、run_code のルール、失敗時の対応、視覚的な検証について確認します。
• get_guide に topic: "use" を指定します。Sketch の編集、スタック、シンボル、スタイル、オーバーライド、アセット、プロトタイピングについて確認します。
• フレーム、グループ、スタック、ページ配置、サイズ、ピン、コンテナタイプの作成や再構成を行う前に、get_guide に topic: "layout" を指定します。

作業に必要な場合は、troubleshooting、layout、styling、symbols、assets、prototyping のガイドサブトピックを必要に応じて取得します。

前提条件

• MCP が有効な状態で Sketch が実行されていること（Settings → General → Allow AI tools to interact with open documents）。
• 対象ドキュメントが開いているか、新しいドキュメントを作成または使用することをユーザーが想定していること。
• 参照が URL、スクリーンショット、またはソースコードとして用意されていること。
• 作業範囲が明確であること。ページ全体か単一フレームか、対象幅、ダークモードかライトモードか、複数の候補がある場合は対象のページやフレームを確認します。

MCP が利用できない場合は作業を中断し、get_guide に topic: "troubleshooting" を指定してください。MCP に接続できない状態で、記憶を頼りにレイアウトを推測してはいけません。

手順

以下の手順を順番に実行します。通常の作業では基本的なフローで十分です。詳しい情報や例が必要な場合に限り、参照ファイルを読み込みます。

Step 1 — コンテキストと参照を確認する

1. 必須のガイドを取得します。
2. get_document_info で対象ドキュメントを特定します。
3. 参照の種類を分類します。

• URL — ページタイトル、ビューポート幅、DOM 構造、ソース HTML、利用可能な場合はリンク先またはバンドル済みの JavaScript/CSS、計算済みの色とフォント、テキスト、アセット URL を収集します。
• スクリーンショット — 寸法、領域、テキスト内容、配置、主要な色を収集します。
• コード — テーマトークン、フォントスタック、間隔の尺度、コンポーネント名、インライン SVG、アセットのインポートを収集します。

4. 忠実度仕様を抽出し、レイアウトを変更する前に、対象幅で参照の基準となるスクリーンショットを撮影します。仕様には、領域（上から下の順）、原文どおりのテキスト、色、タイポグラフィ、レイアウト幅、アセットのソースを含めてください。references/reference-extraction.md を参照してください。

参照の種類に応じた情報の抽出については、references/reference-extraction.md を読んでください。比較方法と完了基準については、Step 5 の前に references/validation.md を読んでください。

Step 2 — 再利用可能な Sketch コンテンツを見つける

変更を加える前に調査します。まず読み取り専用の MCP ツールから始めてください。

1. get_document_info を呼び出し、ページ、最上位のフレーム／グラフィック、レイヤー数、既存のレイアウト候補を確認します。
2. 候補のフレームまたは関連ページに対して get_layer_tree_summary を呼び出し、階層、ID、名前、寸法、テキストの抜粋、シンボルインスタンスのオーバーライド数、スタックのヒントを確認します。
3. get_design_assets と get_libraries を使い、再利用可能なシンボル／コンポーネントとライブラリアセットを確認します。
4. サマリーで必要な詳細が得られない場合に限り、対象を絞って run_code を使用します。

既存のフレームが依頼されたデザインに対応していると確信できる場合に限り、そのフレームを編集してください。それ以外の場合は、新しいフレームを作成します。

ステップ 3 — ピクセルを描く前に構造を計画する

描画する前に、レイヤー構成を定義します。

• 最上位領域とその順序。
• 親子関係と兄弟グループ。
• 領域の幅、コンテンツの最大幅、全幅表示かカラム内表示か。
• 固定／ピン留め領域とスクロールするコンテンツ。
• シンボル候補、スタック候補、アセット候補、再利用可能なスタックパターン。

デフォルトのページテンプレートを適用しないでください。参照の情報アーキテクチャに合わせます。

構造化された領域ごとに、描画する前に Sketch のスタックモデルを決めます。方向、間隔、パディング、配置、サイズ設定、折り返し、意図する表示順序を定めます。特別な理由があって領域を自由配置にする必要がない限り、行、列、ナビゲーションバー、ツールバー、カード、リスト、フォーム、ボタングループ、繰り返しコンテンツにはスタックを使用します。ページレベルの配置、ピン留めされたクローム、オーバーレイ、マスク、または本当に自由形式のアートワークには手動座標を使用します。

ステップ 4 — トークンと基本フレームを設定する

背景、境界線、テキスト、ブランド、控えめなテキスト、重要なサーフェスについて、ドキュメントのスウォッチ／共有スタイルを作成するか、既存のものに合わせます。ページ／フレームの背景を意図的に設定し、構造グループに誤って適用された塗りを解除します。シンボルの詳細については、topic: "symbols" を指定して get_guide を呼び出します。

参照の値を使用します。計算済み CSS、スクリーンショットからサンプリングした色、またはコードのトークンを利用できます。スタイルの詳細については、topic: "styling" を指定して get_guide を呼び出します。

ステップ 5 — レイアウトを段階的に構築する

小さく、元に戻せる run_code 編集を適用します。1つのスクリプトで行う操作は1つだけにします。

ページ全体、最上位領域、または複数セクションのレイアウトを1つのスクリプトで構築しないでください。同じ実行で調査、作成、スタイル設定、並べ替えを組み合わせないでください。スクリプトはフラットに保ちます。初期化、IDによる対象の検索、1つの変更の実行、JSONのログ出力だけを行います。深いヘルパー関数、ネストした即時実行関数、長い制御フローのツリーは避けてください。

外側から内側へ構築します。

1. ページフレームと背景。
2. レイヤー構成に基づく最上位領域のコンテナ。
3. 各領域の詳細な子要素を追加する前に、その領域のスタック設定。
4. 各領域内のテキスト、図形、シンボルインスタンスを、少数の兄弟要素ごとに追加。
5. 親構造が正しくなってから、固定／ピン留め領域を追加。

最上位領域を一度に1つずつ構築します。各領域のコンテンツを追加した後に、次の作業を行います。

1. get_screenshot で参照アンカー幅のフレームをスクリーンショットにします。
2. その領域の帯状部分を参照アンカーと比較し、references/validation.md の分類に沿って差分を列挙します。
3. 次の領域に取りかかる前に、大きな不一致を修正します。

構造を編集した後は、get_layer_tree_summary で再確認するか、フレームのスクリーンショットを撮ります。安全な並べ替え／親子関係変更のパターンについては、references/editing-patterns.md を参照してください。

ステップ 6 — シンボル、アセット、オーバーライド

繰り返し使う一時的なレイヤーグループを描画する前に、既存のドキュメント／ライブラリのシンボルを使用します。繰り返し使用する UI は、通常、インスタンスとオーバーライドを備えた1つのシンボルマスターにします。

詳細な図形を描く前に、テキスト以外の各ビジュアルを分類します。写真、スクリーンショット、イラスト、複雑な SVG、製品画像、ブランドマーク、詳細なアイコン、グラデーション、ノイズは、SVG／PNG／画像アセットとして書き出し／読み込みます。Sketch で再現するのは、シンプルな UI プリミティブ、編集可能なシンプルなベクター、区切り線、ピル型、基本的な図形だけにします。

アイコン／ロゴ／画像については、最初にシンプルなプレースホルダーを使ってレイアウトを設定し、ジオメトリとスタック順序が安定してから実際の画像アセットを読み込んで割り当てます。繰り返し使うアセットには、専用レイヤーのシンボル画像オーバーライドを優先します。

シンボルのオーバーライドパターンについては、references/symbols.md を参照してください。読み込み／書き出しの詳細については、topic: "assets" を指定して get_guide を呼び出します。

ステップ 7 — 対象を絞った修正のみ

ユーザーから問題が報告された場合、またはスクリーンショットの比較で不一致が見つかった場合：

1. 変更を加える前に、get_layer_tree_summary または対象を絞ったプローブで現在のレイヤーを確認します。
2. 報告されたプロパティのみを変更します。フレーム値、テキストスタイル、色、レイヤー順、スタックプロパティ、またはオーバーライドを 1 つ変更します。
3. スクリーンショットを撮り直し、削除が意図的でない限り、子の数が変わっていないことを確認します。

レイアウトが崩れたり、レイヤーが失われたりした場合は、すぐにその旨を伝え、続行する前に Undo/Revert するようユーザーに伝えます。

ステップ 8 — 最終検証と引き継ぎ

完了条件を満たすまで、完了したと主張しないでください。詳細は references/validation.md → 完了条件を参照してください。

1. 参照アンカー幅で、フレーム全体の get_screenshot を撮影します。
2. 忠実度仕様の各帯域について、参照アンカーのスクリーンショットと照合する領域ゲートを実行します。
3. 重大な差分が残っている場合は、ステップ 7 に戻って反復します。「ほぼ十分」なレイアウトのまま引き継がないでください。
4. 使用したシンボル、作成したトークン／スタイル、対象のアートボード／フレーム名と ID、検証済みの領域、残っている軽微な差分をまとめます。
5. タスクが完了するまで zoomToFitCanvas を実行しないでください。

ルール

Sketch → デザインに固有のルールです。一般的な MCP／スクリプトのルールは topic: "mcp" を指定して get_guide から、Sketch のコンテンツに関するルールは topic: "use" を指定して get_guide から取得します。

1. 作り直すのではなく、修正します。コンテンツが存在する場合、大きな領域を削除して再作成するのではなく、フレーム、スタイル、オーバーライド、順序を修正します。
2. 並べ替え、親の変更、追加、削除の各操作の前後で、子の数を基準値と比較します。
3. parent.layers = [...] は決して割り当てないでください。並べ替えには layer.index を、親の変更には child.parent = newParent を使用します。
4. 参照と同じ領域構造にします。意図的に異なる構造にする理由がない限り、同じ視覚コンテンツは同じ親子／兄弟関係にします。
5. 意味のある変更をまとめるたびにスクリーンショットを撮り、その差分に基づいて次の編集を選びます。
6. 構造化レイアウトでは、デフォルトでスタックを使用します。参照内の兄弟要素がフレックス、グリッド、リスト、フォーム、ナビゲーション、カードのように振る舞う場合は、各子要素を手動で配置するのではなく、Sketch スタックを作成するか、既存のスタックを維持します。
7. アセットはアセットとして扱います。複雑なアートワーク、写真、スクリーンショット、ブランドマークを、低忠実度のベクター近似で描き直さないでください。アセットをエクスポート／インポートするか、画像／SVG アセットを割り当てます。
8. 推測しないでください。記憶や一般的な UI パターンをもとにレイアウト、文言、色、間隔、アセットを捏造しないでください。参照から抽出します。値が欠けている場合は、再取得するかユーザーに尋ねます。
9. 常に参照アンカーを使用します。Sketch の出力は、ページの記憶ではなく、撮影した参照スクリーンショットと比較します。
10. 完了ゲート。セクションが存在するから、またはページが「似て見える」からといって作業を止めないでください。references/validation.md の完了条件を満たした時点で終了します。

落とし穴

• 小さな不一致を直すためにページを作り直すと、調整済みの作業が無駄になり、新たなバグも発生します。スクリーンショットの差分に基づいて、必要な箇所だけを修正してください。
• シンボルのインスタンスに画像を直接配置すると、階層が崩れたり、API で失敗したりすることがあります。画像レイヤーはマスターに配置し、インスタンスごとの画像オーバーライドで制御してください。
• スクリーンショットを省略すると、レイアウト、順序、色の誤りを見落とします。すべての作業バッチでスクリーンショットを撮影してください。
• parent.layers = [...] で順序を変更すると、子が削除されたり、オブジェクト ID が重複したりすることがあります。代わりに、安全な並べ替え方法を使用してください。
• インデックスと配置方向を誤解すると、スタックの順序が逆に見えることがあります。topic: "layout" を指定して get_guide を使い、スクリーンショットで確認してください。
• ページ全体や領域全体を操作するスクリプトは、検証、デバッグ、復旧が困難です。領域ごと、スタック設定ごと、少数の兄弟レイヤーごとに分割してください。
• 手動のフレームで構築した構造化レイアウトは、間隔や順序が変わると崩れます。行、列、リスト、フォーム、ナビゲーション、カード、繰り返し領域には Sketch のスタックを使用してください。
• 複雑なアートワークを基本図形で作り直すと、品質の低い近似になります。SVG/PNG をエクスポートしてインポートするか、画像オーバーライドを使用し、図形はシンプルな UI の基本要素に限って使用してください。
• 最初の描画時のページスクリーンショットだけでは、遅延読み込み画像やスクロールで表示される UI の状態を見落とすことがあります。ブラウザーまたはエージェントのツールを使い、スクロールしてコンテンツを表示してから、対象のビューポートを撮影してください。
• 完了を早まると、エージェントが汎用的なスタイルでヘッダー、本文、フッターを追加しただけで作業を止めてしまいます。領域ごとのゲートと完了基準を実行し、大きな差分がなくなるまで修正を続けてください。
• コピーや色をその場で作ると、見出しの言い換え、ダミーテキスト、抽出した値ではなく既定のグレーや青が使われてしまいます。忠実度仕様をそのまま使用し、参照から色を再度サンプリングしてください。
• プレースホルダーが残ると、グレーのボックスが「ロゴ」や「ヒーロー画像」のままになります。ユーザーがプレースホルダーを求めた場合を除き、引き渡し前に実際のアセットをエクスポートしてインポートしてください。

トラブルシューティング

ブリッジ／ツール呼び出しの失敗、パーサーエラー、MCP 接続の問題、スクリーンショットの失敗が発生した場合は、再試行する前に topic: "troubleshooting" を指定して get_guide を呼び出してください。

ドキュメント操作で失敗した場合：

• レイアウト／スタック／順序の問題 → topic: "layout" を指定して get_guide を呼び出します。
• シンボルのオーバーライドの問題 → topic: "symbols" を指定して get_guide を呼び出します。
• エクスポート／インポート／画像の問題 → topic: "assets" を指定して get_guide を呼び出します。

デザイン構築時の症状

• スクリプト実行後に子の数が減った：ユーザーに操作を元に戻すよう伝え、その後で操作内容を確認してください。一括レイヤー割り当てを繰り返してはいけません。
• get_screenshot の結果が空または誤っている：フレーム／レイヤー ID を再解決してから、必要であればページまたは親フレームのスクリーンショットを撮影してください。
• シンボルのオーバーライドが反映されない：get_symbol_overrides を再取得し、commonOverrideIDPrefix + '_' + property からオーバーライド ID を再構築してから、スクリーンショットを撮影してください。
• 行スタックでテキストが重なる：子の順序と間隔を確認し、スタックのプロパティか子のインデックスを一度にひとつずつ修正してください。

参考資料

• topic: "mcp" を指定した get_guide — MCP ツール、run_code、トラブルシューティング、視覚的な確認、完了ルール
• topic: "use" を指定した get_guide — Sketch の編集、スタック、シンボル、スタイル、オーバーライド、アセット、コンテンツの検証
• topic: "layout" を指定した get_guide — スタック、ページ上の配置、サイズ設定、ピン、コンテナの種類、並べ替え／親の変更、レイアウトのずれ
• 参照の抽出
• 安全な編集パターン
• シンボルオーバーライドのパターン
• 検証ループ
• Sketch JavaScript API
• StackLayout
• シンボルのオーバーライド（MCP の get_symbol_overrides で確認）