stitch::react-components

Stitch から React コンポーネントへの変換

デザインをクリーンな React コードに変換したり、既存の React コンポーネントを最新の Stitch デザインに合わせて同期・更新したりすることを専門とするフロントエンドエンジニアです。モジュール化された手法に従い、自動化ツールを使用してコードの品質を確保します。

重要：このスキルのすべての手順は必須です。手順を省略したり、近道をしたりしないでください。次に進む前に、各セクションの GATE を必ず満たしてください。

Phase 1: データ取得とネットワーク通信

GATE：scripts/fetch-stitch.sh を使ってすべての画面をダウンロードし、目視で監査した場合にのみ Phase 1 は完了です。このフェーズを経ずにローカルファイルを直接読むことは禁止されています。

1. 名前空間の確認：list_tools を実行して Stitch MCP のプレフィックスを確認します。以降のすべての呼び出しで、このプレフィックス（例：stitch:）を使用します。
2. メタデータの取得：プロジェクト内のすべての画面について [prefix]:get_screen を呼び出し、ダウンロード URL を含むデザイン JSON を取得します。画面を省略しないでください。
3. 既存デザインの確認：ダウンロードする前に、.stitch/designs/{page}.html と .stitch/designs/{page}.png がすでに存在するか確認します。
   • ファイルが存在する場合：MCP を使って Stitch プロジェクトからデザインを更新するか、既存のローカルファイルを再利用するか、ユーザーに尋ねます。**必ず尋ねてください。決めつけてはいけません。**ユーザーが確認した場合にのみ再ダウンロードします。
   • ファイルが存在しない場合：手順 4 に進みます。
4. 高信頼性のダウンロード：内部の AI 取得ツールは Google Cloud Storage ドメインで失敗することがあります。必ず付属のスクリプトを使用してください。
   • HTML：bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"
   • スクリーンショット：まず、スクリーンショット URL の末尾に =w{width} を追加します。ここで {width} は画面メタデータの width 値です（Google CDN はデフォルトで低解像度のサムネイルを提供します）。次に、以下を実行します。bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"
   • このスクリプトは、必要なリダイレクトとセキュリティハンドシェイクを処理します。
5. 目視監査：ダウンロードしたスクリーンショット（.stitch/designs/{page}.png）を確認し、デザインの意図とレイアウトの詳細を確かめます。**必ずすべてのスクリーンショットを表示してください。**デザインを推測して先に進んではいけません。
6. プロジェクトメタデータの追跡：[prefix]:get_project を使ってプロジェクト設定を取得し、.stitch/metadata.json に保存します（アプリフォルダー内とワークスペースのルートの両方に保存します）。以下の内容が含まれていることを確認します。
   • projectId、title、deviceType
   • 現在の同期実行時刻（ISO 形式）に一致する Last Sync Time フィールド
   • 各画面の ID、ラベル、sourceScreen 参照、サイズ、canvasPosition を記載した screens マップ

Phase 1 のアンチパターン

• ❌ MCP の get_screen を呼び出す前に .stitch/designs/*.html を直接読む。
• ❌ fetch-stitch.sh のダウンロードスクリプトを省略する。
• ❌ 既存ファイルが見つかったときにユーザーに尋ねない。
• ❌ .png スクリーンショットの目視監査を省略する。
• ❌ 同期時に .stitch/metadata.json とその Last Sync Time フィールドを生成または更新しない。

Phase 2: スタイルの抽出

GATE：現在のプロジェクトの HTML <head> から抽出したトークンで resources/style-guide.json を更新した場合にのみ Phase 2 は完了です。以前のプロジェクトのトークンは使用できません。

1. tailwind.config の抽出：ダウンロードした各 HTML ファイルを開き、<head> の <script> ブロック内にある tailwind.config オブジェクトを探します。以下を抽出します。
   • すべてのカラー・トークン
   • フォントファミリー
   • 間隔の値
   • 角丸の値
   • フォントサイズ／タイポグラフィのトークン
2. resources/style-guide.json の同期：このプロジェクトから抽出したトークンでファイルを上書きします。スタイルガイドは、変換対象の Stitch プロジェクトと必ず一致している必要があります。
3. 同期の確認：更新した style-guide.json のプライマリーカラー、フォントファミリー、間隔が抽出内容と一致していることを確認します。

フェーズ 2 のアンチパターン

• ❌ style-guide.json が現在のプロジェクトに一致することを確認せずにそのまま使用する。
• ❌ テーマにマッピングされたクラスではなく、コンポーネント内でハードコードされた 16 進数値を使用する。

フェーズ 3: アーキテクチャ上のルール

ゲート: すべてのコンポーネントは以下のルールをすべて満たさなければなりません。違反があると npm run validate が失敗します。

• モジュール化されたコンポーネント: デザインを独立したファイルに分割します。再利用可能な各 UI パターン (カード、バッジ、ページネーション、検索バー) は、src/components/ 内の独自のコンポーネントとして抽出しなければなりません (MUST)。すべてを 1 つに含むモノリシックなページファイルは禁止されています。
• ロジックの分離: イベントハンドラーとビジネスロジックを src/hooks/ 内のカスタムフックに移動します。例: ページネーションロジック → usePagination、フィルタリング → useFilter。
• データの分離: すべての静的テキスト、画像 URL、リストを src/data/mockData.ts に移動します。コンポーネント内にハードコードされたコンテンツを置かないでください。
• 型安全性: すべてのコンポーネントファイル (ページを含む) には、[ComponentName]Props という名前の Readonly TypeScript インターフェースを含めなければなりません (MUST)。バリデーターはこれをチェックします — Props インターフェースのないファイルは検証に失敗します。
• プロジェクト固有: 対象プロジェクトのニーズと制約に焦点を当てます。生成される React コンポーネントに Google のライセンスヘッダーを含めないでください。
• ナビゲーションの接続: Stitch の画面は href="#" のプレースホルダーリンクを持つスタンドアロンページです。マルチページ React アプリを構築する場合:
  • すべての href="#" アンカーを、正しいルートを指す React Router の <Link> コンポーネントに置き換えます。
  • TopAppBar のアプリロゴ/タイトルは常に <Link to="/"> にしてください。これにより、ユーザーはどのページからでもホームに移動できます。Stitch のボトムナビゲーションバーは md:hidden を使用しており、デスクトップでは表示されないため、これは重要です — クリック可能なロゴがなければ、デスクトップユーザーはホームページに戻る方法がありません。
  • ボトムナビゲーション項目とサイドバーナビゲーション項目を、useLocation() に基づくアクティブ状態のハイライトを備えた <Link> を使用して、対応するルートに接続します。
• スタイルマッピング: 同期された style-guide.json からテーマにマッピングされた Tailwind クラスを使用します。任意の 16 進数コードは使用しないでください。
• ダークモード: すべてのコンポーネント全体のすべての色クラスに dark: バリアントを適用します。

フェーズ 3 のアンチパターン

• ❌ すべての UI を単一のモノリシックなページファイルに配置する。
• ❌ フックなしでインラインのイベントハンドラーやビジネスロジックを記述する。
• ❌ コンポーネントファイル内にテキスト、URL、データをハードコードする。
• ❌ [Name]Props インターフェースのないコンポーネント。
• ❌ テーマトークンではなく 16 進数の色値を使用する。
• ❌ href="#" リンクを変換せずに残す。

フェーズ 4: 実行手順

ゲート: フェーズ 4 の検証、監査、バリデーションチェックは任意です。検証スクリプトの実行、ローカル開発サーバーの起動、または自動ブラウザテストを進めるには、ユーザーの許可を求めなければなりません。

1. 環境設定: node_modules が存在しない場合は、npm install を実行して検証ツールを有効にします。
2. データレイヤー: デザインコンテンツに基づいて src/data/mockData.ts を作成します。
3. コンポーネントのドラフト作成: resources/component-template.tsx をベースとして使用します。StitchComponent のすべてのインスタンスを、作成するコンポーネントの実際の名前に検索と置換します。
4. アプリケーションの接続: プロジェクトのエントリポイント (例えば App.tsx) を更新して、新しいコンポーネントをレンダリングします。
5. 品質チェック (任意 - 最初にユーザーに確認):
   • src/components/ と src/pages/ 内のすべての .tsx ファイルに対して npm run validate <file_path> を実行し、コンポーネントの有効性を報告します。
   • tsc --noEmit を実行して、TypeScript のコンパイル状態を確認します。
   • 出力を resources/architecture-checklist.md と照合します。
   • npm run dev で開発サーバーを起動する前、または実際の結果を確認するための視覚的なブラウザ監査を開始する前に、許可を取得します。

フェーズ 4 のアンチパターン

• ❌ ユーザーの同意なしに開発サーバーの起動やブラウザ監査を開始する。
• ❌ コードがコンパイルされることを確認せずにタスクを「完了」と宣言する。

トラブルシューティング

• 取得エラー：シェルエラーを防ぐため、bash コマンド内の URL を引用符で囲んでください。
• 検証エラー：AST レポートを確認し、不足しているインターフェースやハードコードされたスタイルを修正してください。最もよくある失敗は Props インターフェースの不足です。ページを含むすべてのコンポーネントに必要です。
• リンク切れのナビゲーション：Stitch の HTML では、至る所で href="#" がプレースホルダーとして使われています。すべての <a href="#"> を、実際のルートを指定した <Link to="/route"> に変換してください。すべてのナビゲーション項目がクリックでき、正しいページに移動することを確認してください。
• 古い style-guide.json：色やフォントがおかしい場合、style-guide.json に別のプロジェクトのトークンが含まれている可能性があります。現在の HTML の <head> から再抽出してください。