sketch-design-to-code

Sketch MCP からコードへの変換

プロジェクトに応じた再利用、シンボル駆動のコンポーネント、視覚的な検証により、Sketch のデザインからコードを生成します。

必須の Sketch ガイド

• get_guide with topic: "mcp" — 必ず取得してください。MCP の前提条件、run_code のルール、失敗時の処理、視覚的な検証が記載されています。
• get_guide with topic: "use" — Sketch の調査、シンボル、オーバーライド、スタック、スタイル、書き出し、コンテンツの検証が記載されています。

タスクで必要になった場合は、次のサブトピックのガイドを取得してください：troubleshooting、layout、styling、symbols、assets、prototyping。

逆方向のワークフロー：コード／URL から Sketch を作成する場合は sketch-design-from-reference を参照してください

前提条件

• MCP が有効になった状態で Sketch が起動していること（Settings → General → Allow AI tools to interact with open documents）。
• 対象のドキュメントが開いていること。ユーザーが選択した対象、または明示的なフレーム ID／共有リンク（https://sketch.com/s/<doc-uuid>/f/<frame-uuid>）が必要です。
• プロジェクトのワークスペースにアクセスできること。エージェントがソース、設定、パッケージマニフェストを読み取れる必要があります。
• ユーザーの指定またはリポジトリの情報から対象プラットフォームを把握していること（例：package.json → Web、*.xcodeproj → iOS、android/ → Android）。曖昧な場合は確認してください。

MCP が失敗した場合は、作業を停止して topic: "troubleshooting" を指定した get_guide を呼び出し、MCP 接続失敗時のガイダンスに従ってください。MCP に接続できない状態で、記憶を頼りに実装してはいけません。

手順

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

Step 1 — Sketch のコンテキストを確認する

1. get_document_info でドキュメントのコンテキストを確認します。
2. 実装対象を次の優先順位で特定します。

• Sketch の共有リンク — https://sketch.com/s/<doc-uuid>/f/<frame-uuid> のような URL から /f/<canvas-frame-uuid> を抽出し、topic: "use" を指定した get_guide の共有リンクに関するガイダンスに従ってレイヤーを探し、選択します。現在の選択対象や名前の一致よりも、こちらを優先してください。
• Sketch でユーザーが選択したレイヤー。
• get_document_info／get_layer_tree_summary によるレイヤー ID または名前の検索。専用ツールで対象を特定できない場合に限り、対象を絞った run_code を使用します。一致する候補が複数ある場合は確認してください。

3. ユーザーが部分的なコンポーネント、セクション、切り抜きだと明示していない限り、対象フレームはページまたは画面全体として扱います。
4. 対象フレームで get_screenshot（targetDocumentID ＋ layerID）を実行し、参照用スクリーンショットを取得します。これは実装と検証の主要な視覚的参照です。

選択対象がなく、共有リンクからも対象を特定できない場合は、作業を停止して対象フレームを選択するようユーザーに依頼してください。

Step 2 — コードベースを調査する

ファイルを作成する前にプロジェクトを調査してください。一致するコンポーネントやトークンを再利用し、周辺ファイルの構成や状態管理のパターンに合わせ、ユーザーが追加の作業を依頼していない限り、対象範囲を選択したフレームに限定してください。

• 既存の UI コンポーネントはありますか？src/components、デザインシステムのパッケージ、Storybook を確認してください。
• デザイントークンやテーマはありますか？CSS 変数、Tailwind の @theme、tokens.ts、アセットカタログを確認してください。
• 対象の技術スタックは何ですか？package.json、Podfile、build.gradle、フレームワークのインポートを確認してください。
• 実行方法は何ですか？README、npm run dev、yarn ios、Makefile、mise の設定を確認してください。
• 新しい作業の配置先はどこですか？ユーザーの依頼、機能モジュール、ページ／ルートを確認してください。

Step 3 — デザインの構造とトークンを抽出する

カスタムの調査コードを書く前に、専用の読み取り専用 MCP ツールを使用します。

1. get_document_info を呼び出し、ドキュメント ID、ページ、ページのレイヤー数、最上位のフレーム／グラフィックの位置と寸法を取得します。
2. 対象のページ、フレーム、またはレイヤーに対して get_layer_tree_summary を呼び出し、階層、ID、名前、寸法、テキストの抜粋、シンボルインスタンスのオーバーライド数、スタックのヒントを取得します。
3. これらのツールで取得できない詳細に限り、対象を絞って run_code を使用します。対象には、正確なスタイル値、ピン留め／サイズ設定、マスク、シンボルのマスター ID、オーバーライド可能なレイヤー、書き出し設定、画像ソース、カスタムジオメトリの確認が含まれます。スクリプトは小さく、簡潔に保ち、1 回の呼び出しにつき 1 つの調査またはプロパティに絞って、短いタイトルと JSON ログを付けます。

選択したフレームと関連する子孫レイヤーについて、階層、レイアウト、タイポグラフィ、スタイリング、再利用可能なスタイル、トークン、シンボル、アセット、ジオメトリを説明できるだけのデータを収集します。コーディングの前に、主要な領域と書き出し候補について、実際の Bitmap／Image レイヤー、純粋なイラスト／パスのアートワーク、アイコン／ロゴ／シンボルのアートワーク、テキストを含む UI、コード化する構造と書き出す内側のアートワークに分割すべき混在 UI を分類した簡潔なアセット分類台帳を作成します。書き出し候補については、設定されている場合、layer.exportFormats を記録します。これらの設定には、ファイル形式、倍率または絶対サイズのバリエーション、プレフィックス／サフィックスによる命名、プラットフォームごとのフォルダー名について、デザイナーの意図が反映されています。レイアウトについては、デザインでスタック、ピン留め／リサイズ、その他の相対レイアウト制約のどれが使われているかを特定します。これらがレスポンシブデザインの意図を定めます。大規模なツリーでは、まず浅くマッピングし、重要なサブツリーだけを詳しく調べます。

抽出例、アセット分類の調査コード、大規模なツリーに対する手順については、references/extraction.md を参照してください。

Step 4 — コンポーネントマップを計画する

コーディングの前に、シンボル／コンポーネントの簡潔なマップを作成します。同じ Sketch マスターのインスタンスが繰り返し登場する場合は、通常、データ駆動型の props を持つ 1 つの再利用可能なコンポーネントにします。ネストされたシンボルは通常、コードにフラット化せず、合成コンポーネントにします。

Sketch master                  → Code component        → Overrides / props
<Family>/<Variant A>           → <Family><VariantA>    → <override props>
<Family>/<Variant B>           → <Family><VariantB>    → <override props>
<Family>/<Container>           → <Family><Container>   → <override props>
<Family>/<Atom>                → <Family><Atom>        → <override props>

シンボルやオーバーライドが関係する場合は、インスタンスごとに get_symbol_overrides を呼び出します（kind: all）。シンボルのマッピング例については、references/symbol-to-code.md を参照してください。

Step 5 — アセットを書き出す

ドキュメントにアイコン、ビットマップ、ロゴ、純粋なアートワークのグループ、その他のデザイン済みアセットが含まれている場合は、該当する Sketch のレイヤーまたはシンボルのソースから正確に書き出します。デザイン済みアセットにプレースホルダー用のアイコンパックを使わないでください。また、画面全体のスクリーンショットから製品用アセットを切り出さないでください。スクリーンショットは検証用です。代替の書き出しオプションを選ぶ前に、各書き出し候補に設定されている layer.exportFormats を確認します。設定がある場合は、それらの形式を sketch.export に渡すことで、書き出したファイルにドキュメントの形式、サイズ、命名プリセットを反映させます。書き出しファイルは、プロジェクトで標準のパスまたは一時ディレクトリに保存し、フルパスをログに記録して、ファイルの存在を確認します。

アセット分類の詳細、正確な書き出しルール、忠実度の確認、パスの例については、references/assets.md を参照してください。

ステップ 6 — コードを実装する

デザインをプロジェクトの規約に合わせて実装し、Sketch のスクリーンショットと 1:1 の視覚的な一致を実現します。抽出したコンテキストも参照してください。

• 余白、配置、サイズ、階層を一致させます。
• タイポグラフィと色の使い方を一致させます。
• スタック、ピン留め／サイズ変更、相対レイアウトのメタデータがある場合は、レスポンシブ／制約ベースのレイアウト意図を維持します。
• トークン化された値を優先し、不必要なハードコード値は避けます。
• 既存の UI を編集する場合は、大規模な書き換えより段階的な更新を優先します。
• アセット分類台帳に従います。実際のビットマップレイヤーはビットマップのままにでき、純粋なアートワークはエクスポートでき、テキストを含む UI はコードで実装します。複合グループでは、レイアウトとテキストをコードで保持し、内側のアートワークのみをエクスポートします。

1. トークン — CSS/Tailwind の @theme、Swift の Color 拡張、Android の colors.xml、またはプロジェクトに相当するものを使います。
2. シンボルコンポーネント — props はオーバーライドを反映し、デフォルト値はマスター値と一致させます。
3. 画面／ページ — セクションを組み合わせます。余白はスタックの gap／フレームレイアウトから設定します。デザインでスタックや相対レイアウトが使われている場合は、その制約をレスポンシブに実装します。使われていない場合は、参照画像を崩さない範囲でコンテナー、余白、メディアを柔軟に保ちながら、フレームで定義されたビューポートにおけるページレイアウトを一致させます。
4. アセット — Sketch の正確なソースからエクスポートしたパスを参照し、プラットフォームに適した img／Image／AsyncImage を使います。

過剰に設計しないでください。一度きりのレイヤーに余計な抽象化を追加しないでください。

ステップ 7 — 実行可能な Web アプリ：セットアップ、実行、比較

対象が Web アプリの場合：

1. すでに実行可能ですか？README／package.json のスクリプト／mise に従います。開発サーバーを起動します（npm run dev など）。
2. まだ実行できませんか？ユーザーに次のように尋ねます。「このプロジェクトには Web 開発環境がありません。新しいフォルダーに実行可能なアプリ（例：Vite + React + Tailwind）をスキャフォールドしますか？」承諾された場合は、最小限のスキャフォールドを作成してページを組み込み、README に実行方法を記載します。
3. ページを開きます（開発 URL またはプレビュー）。
4. ブラウザーのスクリーンショットと、同じフレームの Sketch get_screenshot を比較します（validation.md を参照）。
5. 対象を絞って修正し、両方のスクリーンショットを再取得して、十分に一致するまで繰り返します。

最終回答には、検証した内容を記録します。

ステップ 8 — その他のプラットフォーム

対象がモバイルまたはネイティブ（ブラウザーでの反復確認がない）の場合：

1. プラットフォームの慣例と既存のプロジェクト構成に従ってコードを生成します。
2. ユーザーがシミュレーター／エミュレーターを実行できる場合は、ビルドして比較することを提案します。それ以外の場合は、該当する範囲で validation.md を使って構造を検証します。
3. 視覚的に検証できなかった内容と、ユーザーがローカルで実行すべきことを明確に伝えます。

ステップ 9 — 完了と検証

完了を報告する前に、最新の Sketch スクリーンショットと実装を対象に検証チェックを実行します（Web の場合はブラウザーで比較した後に行います）。

• 使用したスタックのビルド／型チェックが成功することを確認します。
• 追加／変更したファイル、シンボルからコンポーネントへの対応、実行方法（Web の場合は URL も含む）をまとめます。
• 意図的な差異（技術的な制限、アクセシビリティの改善）を記録します。
• 繰り返しをインラインのままにした場合は、今後シンボルを再利用できる箇所に言及します。
• Sketch の古いデータをそのまま信用せず、値が不確かな場合は run_code で再取得します。

コード固有のスクリーンショットチェックと不一致への対処方法については、references/validation.md を参照してください。

ルール

Sketch → コードの方向に固有のルールです。Sketch MCP の汎用ルールは、get_guide の topic: "mcp" → Critical Rules、get_guide の topic: "use" → Mandatory Constraints、および Visual Verification & Completion から取得し、以下の項目とあわせて従ってください。

1. まずプロジェクトを確認 — コンポーネントやフォルダーを作成する前に、既存のコードを読みます。
2. シンボル → コンポーネント — オーバーライド → props。同一のボタン実装を3つコピー＆ペーストしないでください。
3. 16進数カラーよりトークンを優先 — ドキュメントのスウォッチや共有スタイルを優先し、Sketch でリンクされていない場合にのみハードコードします。
4. フレームの範囲 — ユーザーがコンポーネント、セクション、または切り抜きのみだと明示しない限り、フレームはページまたは画面全体だとみなします。
5. レスポンシブの意図 — スタック、ピン留め／サイズ変更、相対レイアウトがある場合はそれに従います。ない場合は、まずフレームのビューポートに合わせ、実用的な範囲でレイアウトの柔軟性を保ちます。
6. 差分を最小限に — 要求されたフレームを実装します。ついでのリファクタリングは行いません。
7. 足場作成の前に確認 — 新しい実行可能な Web アプリは、既存のものがなく、ユーザーが同意した場合にのみ作成します（ただし、スタンドアロンの実装フォルダーをすでに依頼されている場合を除きます）。
8. 最新データを使用 — 不明な場合は Sketch に再クエリします。セッション中の以前の抽出結果が古い可能性があるため、それに依存しないでください。
9. アセットを分類 — デザイン内のビットマップはビットマップのままでもかまいません。テキストを含む UI、カード、フォーム、ナビゲーション、セクションは、ソースが実際のビットマップレイヤーでない限り、コードで実装します。
10. 正確にエクスポート — 検証用スクリーンショットの切り抜きではなく、選択した Sketch のレイヤー／グループ／シンボルから本番用アセットをエクスポートします。

注意点

以下はコードに関する注意点のみです。ブリッジ／スクリプトの問題は get_guide の topic: "mcp" → Common Mistakes に、ドキュメント操作の問題は get_guide の topic: "use" → Common Content Mistakes に記載されています。

• シンボルをフラット化するとオーバーライドの仕組みが失われます。1つのマスターにつき1つのコンポーネントを使ってください。symbol-to-code.md を参照してください。
• テキストを含むカードやセクションを画像にフラット化すると、壊れやすくアクセシビリティに欠ける結果になります。ソースのビットマップレイヤー、または意味を持たないアートワークのみをエクスポートしてください。
• ソースのビットマップコンテンツを HTML/CSS で再構築するのも誤りとなる場合があります。Sketch でコンテンツが Image レイヤーとされている場合、ユーザーから再構築を明示的に依頼されない限り、エクスポートしたビットマップを使用してください。
• スクリーンショットからアセットを切り抜くと、意図しないピクセル、倍率、マスク、隣接コンテンツが含まれます。代わりに、Sketch で正確なレイヤーを選択してエクスポートしてください。
• run_code で fs を使用すると、fs is not a core package エラーになります。シェルで mkdir -p を使い、Sketch スクリプトではエクスポートのみを行ってください。
• 誤った領域モデルを使うと、たどったサブツリーの外側にある UI を見落とします。ステップ3では階層を浅く調査し、コーディング前に主要な兄弟／親グループをすべてマッピングしてください。
• 巨大な run_code スクリプトはデバッグや復旧が困難です。調査または対象ごとに小さくフラットなスクリプトを1つ使い、調査、変更、スタイリング、エクスポートの設定を1回の呼び出しにまとめないでください。

トラブルシューティング

ブリッジ／ツール呼び出しの失敗については、topic: "troubleshooting" を指定して get_guide を呼び出し、再試行する前に run_code の失敗を分析してください。Sketch ドキュメントの操作に失敗した場合は、失敗した領域に該当するトピック（layout、symbols、または assets）を呼び出してください。

選択範囲が空／スクリーンショットの取得に失敗

• 対象のフレームを選択するようユーザーに依頼するか、共有リンク /f/<uuid> から特定します。
• get_screenshot で明示的な layerID を指定して、対象を再度特定します。

実装がデザインと一致しない

• get_screenshot を再取得し、一致しないサブツリーを詳しく調べて、references/validation.md と比較します。
• 抽出した階層がコードに反映されていることを確認します。主要な領域、正しい親要素、エクスポートしたアセット、マッピングしたトークンをすべて確認してください。

既存プロジェクトで異なるパターンが使われている

• スキルの例よりプロジェクトのパターンを優先します（例：Tailwind ではなく styled-components）。
• シンボルを、リポジトリが使用しているコンポーネントシステムに対応付けます。

ユーザーはモバイルを希望しているが、リポジトリは Web（またはその逆）

• 大規模な実装に着手する前に停止し、プラットフォームを確認します。

参考資料

• get_guide の topic: "mcp" — MCP のワークフロー、run_code、視覚的な検証、完了ルール
• get_guide の topic: "use" — Sketch の確認、スタック、シンボル、スタイル、エクスポート、コンテンツの検証
• 抽出パターン
• シンボルからコードへのマッピングパターン
• アセットのエクスポートパターン
• 検証チェックリスト
• Sketch MCP サーバーのドキュメント
• Sketch JavaScript API