screenshot-to-code

スクリーンショットからコードを作成

スクリーンショットは単なる着想ではなく、視覚的な証拠として扱ってください。レスポンシブで、アクセシブルかつ保守しやすい実装を維持しながら、デザイン言語と目に見える動作を再現してください。

作業基準

作業は、各段階に合格条件を設けた5つのフェーズで進めます。スクリーンショットを見てすぐにCSSの調整に進んではいけません。

1. 調査 — スクリーンショット、リポジトリ、対象ルート、利用可能なアセット、実行環境を把握します。
2. 仕様化 — 視覚的な証拠を、レイアウト、トークン、コンポーネント、コンテンツ、状態、レスポンシブ対応の判断に落とし込みます。
3. 構築 — 細部のスタイリングより先に、セマンティックな構造と大枠のジオメトリを整えます。
4. 比較 — ビューポートを一定にしてレンダリングし、参照画像との差を測定します。
5. 改善 — 影響が最も大きい不一致を修正して再撮影し、完了条件を満たすまで繰り返します。

個人のデザイン上の好みより視覚的な忠実度を、スクリーンショット専用の小手先の調整よりエンジニアリング品質を重視してください。優れた成果には、その両方が必要です。

まずコンテキストを把握する

1. 添付されているすべてのスクリーンショットを原寸で開いて確認します。ピクセル寸法、向き、ブラウザー／デバイスの表示要素、切り抜き、コンテンツ密度、想定されるCSSビューポートを記録します。
2. コーディングの前にリポジトリを確認します。フレームワーク、ルーティング、スタイリング手法、コンポーネントライブラリ、デザイントークン、フォント、アセット、ブレークポイント、テストツール、正しいページまたはコンポーネントのエントリーポイントを特定します。
3. 一致する実装がある場合は、まずレンダリングし、段階的に改善します。既存のアーキテクチャと動作している機能を維持してください。
4. ゼロから始める場合は、ユーザーが指定したスタックを使用します。指定がなければ、既存のスタックを優先し、都合だけを理由に置き換えてはいけません。
5. 安全に推測できず、結果に重大な影響を与える情報（判読できない重要なアセットや不明な対象ルートなど）についてのみ、質問してください。

既存アプリケーションを変更するとき、コンポーネントの境界を選ぶとき、または複数の画面を実装するときは、references/project-and-architecture.mdを変更前に読んでください。

対象ビューポートを適切に分類する

各スクリーンショットについて、主にデスクトップ、タブレット、モバイルのいずれを対象とするか判断します。この判断は、ファイル名や実際のピクセル幅だけでなく、視覚的な証拠全体に基づいてください。

• 横幅の広いナビゲーション、複数列の構成、常時表示されるサイドバー、ホバーを前提としたコントロール、大きなコンテンツ余白は、デスクトップの特徴です。
• 中程度の幅のレイアウト、タッチしやすいサイズのコントロール、列数の削減、一部が折りたたまれたナビゲーションは、タブレットの特徴です。
• 幅の狭い単一列の流れ、コンパクトなナビゲーションまたは下部ナビゲーション、縦に積み重ねられたアクション、画面端まで広がるコンテンツ、タッチ操作を優先したコントロールは、モバイルの特徴です。
• Retina／デバイスピクセル比による拡大縮小、ブラウザーのズーム、画像のリサイズ、切り抜き、大きなキャンバス内に埋め込まれたスクリーンショットを考慮します。画像のピクセル数とCSSピクセル数は一致するとは限りません。
• 証拠が矛盾する場合は、レイアウトの挙動を最も適切に説明できるデバイス分類を選び、その前提を明示します。選択によって求められる結果が大きく変わり、責任を持って推測できない場合に限り、ユーザーに確認してください。

推定した分類に基づいて、初期実装と比較用ビューポートを選びます。デスクトップのスクリーンショットはデスクトップウェブとして、タブレットのスクリーンショットはタブレットとして、モバイルのスクリーンショットはモバイルとして再構築し、検証してください。その参照サイズだけに固定せず、ページ全体をレスポンシブにしてください。

ビジュアル仕様を作成する

実装に入る前に、以下を抽出します。

• ページ領域、読み進める順序、グリッド、配置、幅、ガター、垂直方向のリズム
• 書体、ウェイト、相対サイズ、行の高さ、字間、折り返し、階層
• 色、グラデーション、境界線、角丸、シャドウ、不透明度、表面同士の関係
• 画像のトリミング、アスペクト比、アイコン、イラスト、装飾レイヤー
• 繰り返し使われるコンポーネント、バリエーション、状態、コンテンツパターン
• 表示されているコントロールと想定されるインタラクション
• 固定、スティッキー、重なり、クリッピング、スクロールに連動する要素
• 提供されたビューポート画像から確認できるレスポンシブな挙動の根拠

観察した事実と推測を分けます。不確かな詳細を記録し、スクリーンショットを説明できる、最小限で一貫したルールセットを選びます。抽出方法については、references/visual-analysis.md を参照してください。

大規模なコーディングに入る前に、簡潔な再構築の仕様を作成します。

• 対象のルート／コンポーネントと、各スクリーンショットの参照ビューポート
• 画面に表示される正確なコンテンツと必要なアセット
• 共通シェルと繰り返し使われるコンポーネント
• 主要なレイアウトとタイポグラフィのルール
• 根拠のあるレスポンシブな変更
• 実装するインタラクション／状態
• 再現度に影響する未解決の仮定

ユーザーから求められない限り、作業メモに留め、プロジェクトのドキュメントには追加しないでください。

忠実に実装する

1. 色、タイポグラフィ、間隔、角丸、シャドウ、コンテナ幅、ブレークポイントの共通トークンを定義します。
2. 装飾の詳細より先に、セマンティックな構造を構築します。見出し、ナビゲーション、ボタン、フォーム、リスト、テーブルには適切な要素を使用します。
3. 実際に繰り返されるパターンにはコンポーネントを作成します。巨大なコンポーネントも、不要な抽象化も避けます。
4. まず大まかな形状を合わせます。ページ幅、領域の高さ、グリッド、配置、大きな間隔を調整してから、タイポグラフィ、コンポーネント、仕上げを調整します。
5. スクリーンショットの座標をハードコードするのではなく、CSS のレイアウトシステムを使用します。絶対配置は、実際のオーバーレイやアートワークに限定します。
6. 読み取れる表示テキストは正確に維持します。スクリーンショットにない宣伝文句を作り出さないでください。
7. 示唆されている場合は、ホバー、フォーカス、アクティブ、展開、選択、無効、読み込み、エラーなど、表示されているインタラクションと有用な状態を実装します。
8. データに基づく繰り返しコンテンツは、マークアップを重複させず、配列またはプロジェクトのデータソースに保持します。

適切な再現手法を使用します。

• 折り返しが必要なコンテンツには、通常のドキュメントフローを使用します。
• 行や列の配置が共通している場合は、グリッドを使用します。
• 一方向の配置や分散には、フレックスボックスを使用します。
• 実際のオーバーレイ、バッジ、浮遊するアート、意図的にレイヤー化された構成には、絶対配置を使用します。
• 単純な装飾には疑似要素を使用し、意味のあるコンテンツには使用しません。
• 単純な形状をきれいに再現できる場合に限り、SVG／CSS の図形を使用します。複雑なアートには実際のアセットを使用します。
• スクリーンショットから補間が想定される場合は、流動的なサイズまたは上限付きのサイズを使用します。ページ全体を単一のキャンバスサイズに固定しないでください。

元のデザインを汎用テンプレートに作り替えないでください。根拠またはユーザーからの要望がない限り、流行のグラデーション、ガラス効果、カード、バッジ、アニメーション、角丸コンテナを追加しないでください。

コンポーネント設計、スタイルの規律、データ、ルーティング、パフォーマンス、保守性については、references/frontend-quality.md を参照してください。

アセットを正直に扱う

代替品を作成する前に、リポジトリ内を検索して、ロゴ、アイコン、フォント、写真、イラストの正確なアセットを探してください。一致する既存のアセットがあれば再利用してください。グリフが明らかに該当する場合は、すでに導入されているアイコンライブラリを使用してください。

目立つ画像を、グラデーションの四角形や適当な絵文字で表現しないでください。正確なアセットが入手できない場合は、法的に使用可能な近似アセットを使う、許可されておりツールが利用可能ならアセットを生成する、または明確に分離したプレースホルダーを作成してその旨を報告してください。ブランドロゴを捏造したり、出所不明の画像を黙ってホットリンクしたりしないでください。

スクリーンショットに重要な画像、ロゴ、アイコン、または判読しにくいテキストが含まれている場合は、references/assets-and-content.md を読んでください。

レスポンシブな挙動を推測する

すべてのスクリーンショットを制約条件として使ってください。どの寸法が固定、可変、上限付き、順序変更、非表示、折りたたみ、スクロール可能なのかを推測してください。デスクトップ用のキャンバスを単に縮小するだけにしないでください。

ユーザーが指定しない場合、ビューポートの決定はエージェントが行います。作業サマリーで、推測したデスクトップ／タブレット／モバイルの分類を説明し、その分類を代表するビューポートで結果を検証してください。添付されたすべての画像をデスクトップ向けと決めつけないでください。

ビューポートが1つしか提示されていない場合は、コンテンツの優先度とコンポーネントの意味に基づき、慎重なレスポンシブルールを実装してください。重要なコンテンツとアクションを表示したままにし、読みやすい行の長さを保ち、ナビゲーションを適切に折りたたみ、必要な場合にのみ縦積みにして、オーバーフローを防いでください。提示されていないビューポートでピクセル単位まで忠実に再現できると主張しないでください。

複数ビューポート、モバイル、フォーム、ナビゲーション、または操作の多い作業を完了する前に、references/responsive-and-accessibility.md を読んでください。

見た目だけでなく挙動を再現する

画面上で確認できる操作の手がかりや一般的なセマンティクスから操作方法を推測しますが、スクリーンショットに根拠のない大規模なプロダクトフローを作り込まないでください。再現した画面に信頼性と使いやすさを持たせるため、必要な挙動を実装してください。

• 表示されている場合は、ナビゲーション、タブ、アコーディオン、メニュー、ダイアログ、カルーセル、フィルター、フォーム、選択コントロールを動作させてください。
• リポジトリですでに定義されている場合は、URL／ルーティングの挙動を維持してください。
• デモ用の視覚的なデータと実際のアプリケーション連携を区別してください。動作するバックエンドを静的なモックデータに置き換えないでください。
• コンポーネントに合理的に必要な場合は、空、読み込み中、エラー、長いコンテンツ、狭い幅に対応する安定した状態を用意してください。
• 動きは控えめにし、根拠に基づかせてください。シーケンスや実際の参照先で裏付けられる場合に限り、継続時間、方向、イージングを合わせてください。

状態のモデル化と安全な推測については、references/interaction-and-states.md を読んでください。

レンダリング結果で検証する

1. プロジェクトを実行し、参照ビューポートごとに実装をキャプチャしてください。
2. 可能であれば、参照画像とレンダリング結果を並べるか、オーバーレイ／差分ツールを使って比較してください。
3. 次の順に差異を修正してください。構造と寸法、タイポグラフィと折り返し、間隔と配置、色と表面、アセット、細部の装飾。
4. 残る差異が軽微になるか、元の情報不足に起因するものになるまで繰り返してください。
5. ユーザーが提示していない中間幅を少なくとも1つ確認し、脆弱なブレークポイントがないか検出してください。
6. キーボード操作、フォーカスの視認性、セマンティックなランドマーク、アクセシブルな名前、コントラスト、ズーム、動きを減らす設定、オーバーフローをテストしてください。
7. リポジトリに適したフォーマッター、リンター／型チェック、テスト、本番ビルドを実行してください。

レンダリング結果を確認せずに、忠実に再現できたと宣言しないでください。比較の優先順位と完了基準については、references/verification-loop.md を読んでください。

references/fidelity-rubric.md で結果を評価してください。細かな装飾の高得点で、構成、タイポグラフィ、レスポンシブ対応の誤りや、操作の不具合を補うことはできません。

禁止されている近道

• スクリーンショット自体をページや全画面の背景として埋め込まないでください。
• セマンティック HTML と CSS で再現できる場合に、キャンバス／SVG パスでインターフェース全体をトレースしないでください。
• 1 つのビューポートに合わせるために、何百もの座標をハードコードしないでください。
• ぼかし、過剰なグラデーション、オーバーレイ、切り抜いたコンテナーで差異を隠さないでください。
• 正確に見えるアセットを、絵文字、無作為なアイコン、または無関係なストック画像に置き換えないでください。
• 現在のプロジェクトに適切な基盤がなく、選択を正当化できる場合を除き、新しいフレームワーク、CSS システム、コンポーネントライブラリをインストールしないでください。
• 静的なスクリーンショットに表示されていないという理由だけで、既存の動作を削除しないでください。
• テストを行わずに、レスポンシブ表示の忠実性、アクセシビリティ、ピクセル単位の正確さを主張しないでください。

レポート

実装した内容、変更したルート／コンポーネント、確認したスクリーンショットとビューポート、実行したコマンド、残っている視覚的な差異、推測した動作、およびユーザーから提供が必要なアセットやフォントをまとめてください。