madsouris/sketch-design-from-reference

Sketch MCP でデザインを作成する

参照に合わせて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が実行中であること（設定 → 一般 → AIツールが開いているドキュメントと対話することを許可）。
• ターゲットドキュメントが開いているか、ユーザーが新しいドキュメントを作成/使用することを期待していること。
• 参照がURL、スクリーンショット、またはソースコードとして利用可能であること。
• スコープが明確で行動可能であること：フルページか単一フレームか、ターゲット幅、ダーク/ライトモード、ドキュメントに複数の候補がある場合のターゲットページ/フレーム。

MCPが利用できない場合は、停止して get_guide を topic: "troubleshooting" で呼び出してください。MCPにアクセスできない間は、メモリからレイアウトを推測しないでください。

手順

以下の手順を順に実行してください。メインフローは通常の作業で十分なはずです。ステップでさらに詳細や例が必要な場合のみ、参照ファイルを読み込んでください。

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

1. 必要なガイドを取得します。
2. get_document_info でターゲットドキュメントを特定します。
3. 参照タイプを分類します：
   • URL — ページタイトル、ビューポート幅、DOM構造、ソースHTML、利用可能なリンク/バンドルされたJavaScript/CSS、計算された色/フォント、コピー、アセットURLを収集します。
   • スクリーンショット — 寸法、領域、テキストコンテンツ、配置、キーカラーを収集します。
   • コード — テーマトークン、フォントスタック、スペーシングスケール、コンポーネント名、インラインSVG、アセットインポートを収集します。
4. 忠実度仕様を抽出し、レイアウト変更前にターゲット幅で参照アンカースクリーンショットをキャプチャします。仕様には領域（上から下）、正確なコピー、色、タイポグラフィ、レイアウト幅、アセットソースを含める必要があります — references/reference-extraction.md を参照してください。

参照固有の抽出については、references/reference-extraction.md を読んでください。比較と完了ゲートについては、ステップ5の前に references/validation.md を読んでください。

ステップ2 — 再利用可能なSketchコンテンツを発見する

変更する前に調査します。読み取り専用のMCPツールから始めます：

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

既存のフレームは、それが要求されたデザインに対応していると確信できる場合にのみ編集することを優先します。それ以外の場合は、新しいフレームを作成します。

ステップ3 — ピクセルよりも先に構造を計画する

描画前にレイヤープランを定義します：

• トップレベルの領域とその順序。
• 親子関係と兄弟グループ。
• 領域の幅、コンテンツの最大幅、全幅表示 vs インコラムセクション。
• 固定/ピン留めされた領域 vs スクロールコンテンツ。
• シンボル候補、スタック候補、アセット候補、再利用可能なスタックパターン。

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

すべての構造化領域について、描画前にSketchスタックモデルを決定します：方向、ギャップ、パディング、配置、サイズ設定、ラップ、意図された視覚的順序。行、列、ナビゲーションバー、ツールバー、カード、リスト、フォーム、ボタングループ、繰り返しコンテンツにはスタックを使用します。ただし、領域が自由形式である必要がある特定の理由がある場合は除きます。手動座標は、ページレベルの配置、ピン留めされたクローム、オーバーレイ、マスク、または真に自由形式のアートワークに使用します。

ステップ4 — トークンとベースフレームを確立する

背景、境界線、テキスト、ブランド、ミュートテキスト、重要なサーフェス用のドキュメントスウォッチ/共有スタイルを作成または一致させます。ページ/フレームの背景を意図的に設定し、構造グループの偶発的な塗りつぶしをクリアします。シンボルの詳細については、get_guide を topic: "symbols" で呼び出します。

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

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

小さく、元に戻せる run_code 編集を適用します。1つのスクリプトで1つの小さなアクションを実行します。

1つのスクリプトでページ全体、トップレベルの領域、または複数セクションのレイアウトを構築しないでください。同じ実行でプローブ、作成、スタイリング、並べ替えを組み合わせないでください。スクリプトはフラットに保ちます：ブートストラップ、ターゲットをIDで検索、1つの変更を実行、JSONをログ出力。深いヘルパー関数、ネストされたIIFE、長い制御フローツリーは避けてください。

外側から内側に構築します：

1. ページフレームと背景。
2. レイヤープランからのトップレベル領域コンテナ。
3. 詳細な子要素の前に、各領域のスタック設定。
4. 各領域内のテキスト、シェイプ、シンボルインスタンスを小さな兄弟バッチで。
5. 親構造が正しくなった後に、固定/ピン留めされた領域。

一度に1つのトップレベル領域を構築します。各領域のコンテンツバッチ後：

1. 参照アンカー幅でフレームの get_screenshot を取得します。
2. その領域バンドを参照アンカーと比較します — references/validation.md の分類法を使用して差異をリストします。
3. 次の領域を開始する前に、主要な不一致を修正します。

構造編集後、get_layer_tree_summary で再クエリするか、フレームのスクリーンショットを取得します。安全な並べ替え/再親子化パターンについては、references/editing-patterns.md を読んでください。

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

繰り返しの1回限りのレイヤーグループを描画する前に、既存のドキュメント/ライブラリシンボルを使用します。繰り返しのUIは通常、マスターシンボルとインスタンスおよびオーバーライドになります。

詳細なシェイプを描画する前に、テキスト以外のすべてのビジュアルを分類します。写真、スクリーンショット、イラスト、複雑なSVG、製品画像、ブランドマーク、詳細なアイコン、グラデーション、ノイズは、SVG/PNG/画像アセットとしてエクスポート/インポートします。Sketchでは、単純なUIプリミティブ、単純な編集可能ベクター、区切り線、ピル、基本シェイプのみを再作成します。

アイコン/ロゴ/画像の場合、まず単純なプレースホルダーでレイアウトを確立し、ジオメトリとスタック順序が安定したら実際の画像アセットをインポート/割り当てます。繰り返しアセットには、専用レイヤーでのシンボル画像オーバーライドを優先します。

シンボルオーバーライドパターンについては、references/symbols.md を読んでください。インポート/エクスポートの詳細については、get_guide を topic: "assets" で呼び出します。

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

ユーザーが問題を報告した場合、またはスクリーンショット比較で不一致が示された場合：

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

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

ステップ8 — 最終検証とハンドオフ

完了基準が合格するまで完了を主張しないでください — references/validation.md → 完了基準を参照してください。

1. 参照アンカー幅でフルフレームの get_screenshot をキャプチャします。
2. 忠実度仕様のすべてのバンドに対して、領域ゲートを参照アンカースクリーンショットに対して実行します。
3. 主要な差異が残っている場合は、ステップ7に戻って繰り返します。「ほぼ十分」なレイアウトでハンドオフしないでください。
4. 使用されたシンボル、作成されたトークン/スタイル、ターゲットアートボード/フレーム名とID、検証された領域、残っている軽微な差異を要約します。
5. タスクが完了するまで zoomToFitCanvas を実行しないでください。

ルール

Sketch → デザインの方向固有のルール。一般的なMCP/スクリプトルールは get_guide を topic: "mcp" で、Sketchコンテンツルールは get_guide を topic: "use" で取得します。

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を複製したりする可能性があります。代わりに安全な並べ替えパターンを使用します。
• スタックの順序は、インデックスとパッキング方向が誤解されると逆に見えることがあります。get_guide を topic: "layout" で使用し、スクリーンショットで確認します。
• ページ全体または領域全体のスクリプトは、検証、デバッグ、復元が困難です。領域、スタック設定、小さな兄弟バッチごとに分割します。
• 手動フレームで構築された構造化レイアウトは、スペーシングや順序が変更されるとずれます。行、列、リスト、フォーム、ナビゲーション、カード、繰り返し領域にはSketchスタックを使用します。
• プリミティブシェイプとして再構築された複雑なアートワークは、低品質の近似を生成します。SVG/PNGをエクスポート/インポートするか、画像オーバーライドを使用します。シェイプは単純なUIプリミティブ用に予約します。
• 最初のペイントのみのページスクリーンショットは、遅延画像やスクロールトリガーのUI状態を見逃す可能性があります。ブラウザまたはエージェントツールを使用し、スクロールしてコンテンツをトリガーしてから、ターゲットビューポートをキャプチャします。
• 早期完了：エージェントがヘッダー/ボディ/フッターを一般的なスタイリングで追加して停止します。領域ゲートと完了基準を実行します。主要な差異がなくなるまで修正を続けます。
• 即興のコピーと色：言い換えた見出し、Loremスタイルのフィラー、または抽出された値の代わりにデフォルトのグレー/ブルー。忠実度仕様を正確に使用します。参照から色を再サンプリングします。
• プレースホルダーの永続化：「ロゴ」や「ヒーロー画像」として残されたグレーのボックス。ユーザーがプレースホルダーを要求しない限り、ハンドオフ前に実際のアセットをエクスポート/インポートします。

トラブルシューティング

ブリッジ/ツール呼び出しの失敗、パーサーエラー、MCP接続の問題、またはスクリーンショットの失敗については、再試行する前に get_guide を topic: "troubleshooting" で呼び出します。

ドキュメント操作の失敗の場合：

• レイアウト/スタック/順序の問題 → get_guide を topic: "layout" で。
• シンボルオーバーライドの問題 → get_guide を topic: "symbols" で。
• エクスポート/インポート/画像の問題 → get_guide を topic: "assets" で。

デザインビルドの症状

• スクリプト後に子カウントが減少：ユーザーに元に戻すよう指示し、操作を調査します。バルクレイヤー割り当てを繰り返さないでください。
• get_screenshot が空または間違っている：フレーム/レイヤーIDを再解決し、必要に応じてページまたは親フレームのスクリーンショットを取得します。
• シンボルオーバーライドに効果がない：get_symbol_overrides を再取得し、commonOverrideIDPrefix + '_' + property からオーバーライドIDを再構築し、スクリーンショットを取得します。
• 行スタックでテキストが重なる：子の順序とギャップを調査します。一度に1つのスタックプロパティまたは子インデックスを修正します。

参照

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