stitch::react-native

Stitch から React Native コンポーネントへ

Stitch の Web デザインを、すっきりとした本番環境対応の React Native コードに変換する、または既存のネイティブコンポーネントを最新の Stitch デザインに合わせて同期・更新することに注力するモバイルエンジニアです。React Native のプリミティブと StyleSheet を使用して、HTML/CSS のレイアウトをネイティブのモバイルコンポーネントに変換します。

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

フェーズ 1：取得とネットワーク

ゲート：すべての画面が scripts/fetch-stitch.sh を使ってダウンロードされ、目視で監査されている場合にのみ、フェーズ 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 マップ

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

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

フェーズ 2：テーマの抽出

ゲート：現在のプロジェクトの HTML <head> から抽出したトークンを使って src/theme.ts が作成または更新されている場合にのみ、フェーズ 2 は完了です。カラーの 16 進コードをハードコードしたり、別のプロジェクトのテーマを使用したりすることは認められません。

1. tailwind.config の抽出：ダウンロードした各 HTML ファイルを開き、<head> 内の <script> ブロックにある tailwind.config オブジェクトを探します。次の項目を抽出します。
   • すべてのカラー・トークン
   • フォントファミリー
   • 間隔の値
   • 角丸の値
   • フォントサイズ／タイポグラフィのトークン
2. src/theme.ts の作成／同期：抽出したトークンを TypeScript 定数として src/theme.ts に記述します。すべてのカラー、間隔、タイポグラフィの値に、対応するトークンがあることを確認します。
3. テーマの検証：src/theme.ts のテーマカラーとフォントが、HTML デザインから抽出した内容と一致することを確認します。

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

• ❌ コンポーネントの StyleSheet 宣言内にカラーの 16 進コードや rgba 文字列を直接ハードコードする。
• ❌ 新しいデザインから抽出せず、以前のプロジェクトのテーマトークンを使用する。
• ❌ src/theme.ts の作成または更新を省略する。

フェーズ 3：アーキテクチャルールと HTML のマッピング

ゲート：すべてのコンポーネントは、以下のルールをすべて満たす必要があります。違反すると npm run validate が失敗します。

要素のマッピング

次のルールに従って、HTML 要素を React Native コンポーネントにマッピングします。

HTML	React Native	備考
<div>	View	デフォルトのコンテナー
<span>、<p>、<h1>-<h6>	Text	すべてのテキストは Text で囲む必要があります。インラインスタイルには Text をネストします。
<img>	Image	リモート画像には source={{ uri }}、ローカルアセットには require() を使用します。
<button>、<a>	Pressable	TouchableOpacity よりも Pressable を優先します。onClick の代わりに onPress を使用します。
<input>	TextInput	placeholder、value、onChangeText をマッピングします。
<scroll container>	ScrollView	短いリストにのみ使用します。長いリストや動的なリストには FlatList を使用します。
多数の項目を含む <ul>/<ol>	FlatList	data、renderItem、keyExtractor が必要です。
グループ化されたデータを含む <section>	SectionList	ヘッダー付きのグループ化されたデータに使用します。タブベースのレイアウトにはタブナビゲーターを使用します。
<select>	サードパーティ製ピッカーまたはカスタムモーダル	React Native には組み込みの select はありません。
<svg>	react-native-svg	SVG マークアップを Svg、Path、Circle などに変換します。
ルートラッパー	SafeAreaView	ノッチやステータスバーとの重なりを避けるため、最上位の画面を囲みます。

スタイルのマッピング

CSS と Tailwind クラスは React Native では機能しません。すべてのスタイルを StyleSheet.create() に変換します。

• レイアウト：デフォルトのレイアウトシステムは Flexbox です。flexDirection のデフォルトは 'column' です（Web CSS のように 'row' ではありません）。
  • すべての View では display: flex が暗黙的に適用されます。
  • justify-content は justifyContent にマッピングされます。
  • align-items は alignItems にマッピングされます。
  • gap は gap にマッピングされます（React Native 0.71 以降）。それ以前のバージョンでは、子要素に marginBottom を使用します。
• 寸法：文字列ではなく数値を使用します。width: 100 は密度非依存ピクセルで 100 を意味します。
  • パーセンテージ文字列を使用できます：width: '100%'。
  • レスポンシブなサイズ設定には、react-native の useWindowDimensions() を使用します。
  • vw/vh はありません。Dimensions.get('window') から計算します。
• タイポグラフィ：すべてのテキストスタイルは View ではなく、Text コンポーネントに指定する必要があります。
  • font-size は fontSize にマッピングされます（文字列ではなく数値）。
  • font-weight は fontWeight にマッピングされます（文字列：'400'、'700'、'bold'）。
  • line-height は lineHeight にマッピングされます（数値）。
  • letter-spacing は letterSpacing にマッピングされます。
  • text-transform は textTransform にマッピングされます。
  • color は Text にのみ適用されます。
• 境界線とシャドウ：
  • border-radius は borderRadius にマッピングされます。
  • box-shadow は存在しません。Android では elevation、iOS では shadowColor/shadowOffset/shadowOpacity/shadowRadius を使用します。プラットフォーム固有のシャドウスタイルを適用するには Platform.select() を使用します。
• サポートされていない CSS プロパティ：hover、transition、animation（アニメーションには react-native-reanimated を使用）、position: fixed（代わりに絶対配置を使用）は使用しないでください。

アーキテクチャのルール

• モジュール化されたコンポーネント（Atomic Design）：デザインを独立したファイルに分割します。コンポーネントは、アトム（ボタン、ラベル、アイコン）、モレキュール（入力グループ、カード）、オーガニズム（ヘッダー、リスト、フォーム）として整理します。src/components/atoms/、src/components/molecules/、src/components/organisms/ に配置します。巨大なページ／画面ファイルは禁止です。
• ロジックの分離：イベントハンドラー、API 呼び出し、ビジネスロジックは src/hooks/ 内のカスタムフックに移します。コンポーネントは描画のみを担当します。
• データの分離：すべての静的テキスト、画像 URL、リストを src/data/mockData.ts に移します。コンポーネント内にハードコードされたコンテンツを記述してはいけません。
• 型安全性：すべてのコンポーネントファイル（画面を含む）で、readonly プロパティ修飾子を持つ [ComponentName]Props という名前の TypeScript インターフェースをエクスポートする必要があります。バリデーターではインターフェースがエクスポート済みであることが必須です。Props インターフェースをエクスポートしていないファイルは、バリデーションに失敗します。
• スタイルのハードコード禁止：色、スペーシング、フォントサイズを src/theme.ts に抽出します。StyleSheet.create() ではこれらを参照します。コンポーネントファイルで生のカラー16進コードや rgba 文字列を使うことは一切禁止です。
• ナビゲーション：画面遷移には React Navigation を使用します。画面の型は NativeStackScreenProps または BottomTabScreenProps で定義します。
• アクセシビリティ：すべてのインタラクティブ要素に accessibilityLabel と accessibilityRole を指定する必要があります。画像には accessibilityLabel が必要です。トグルやチェックボックスには accessibilityState を使用します。
• セーフエリア：トップレベルの画面コンポーネントは、react-native のデフォルトの SafeAreaView ではなく、react-native-safe-area-context の SafeAreaView でラップします。
• プロジェクト固有の要件：対象プロジェクトのニーズと制約に重点を置きます。生成するコンポーネントに Google のライセンスヘッダーを含めないでください。

プラットフォーム固有のコード

デザインで iOS と Android に異なる動作が必要な場合：

import { Platform } from 'react-native';

const styles = StyleSheet.create({
  shadow: Platform.select({
    ios: {
      shadowColor: '#000',
      shadowOffset: { width: 0, height: 2 },
      shadowOpacity: 0.1,
      shadowRadius: 4,
    },
    android: {
      elevation: 4,
    },
  }),
});

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

• ❌ すべての UI を単一の巨大な画面ファイルに記述する。
• ❌ React Native コンポーネントの代わりに HTML タグ（div、span、p など）を使用する。
• ❌ カスタムフックを使わずに、イベントハンドラーやビジネスロジックをインラインで記述する。
• ❌ コンポーネントファイルにテキスト、URL、色をハードコードする。
• ❌ エクスポート済みの [Name]Props インターフェースがないコンポーネント。
• ❌ StyleSheet.create() で生の16進カラー値や rgba 文字列を使用する。

フェーズ 4：実行手順

ゲート：フェーズ 4 の検証、監査、シミュレーター／パッケージャーでのテストは任意です。検証スクリプトの実行、パッケージャーの起動、シミュレーター監査を行う前に、必ずユーザーの許可を求めてください。

1. 環境のセットアップ：node_modules がない場合は、検証ツールを利用できるように npm install を実行します。
2. テーマレイヤー：抽出した Tailwind 設定を基に src/theme.ts を作成します。
3. データレイヤー：デザインのコンテンツを基に src/data/mockData.ts を作成します。
4. コンポーネントの作成：resources/component-template.tsx をベースとして使用します。StitchComponent のすべてのインスタンスを、実際のコンポーネント名に置き換えます。HTML 要素を React Native のプリミティブに対応付けます。
5. ナビゲーションの接続：デザインに複数の画面がある場合は、App.tsx にスタックまたはタブナビゲーターを含む NavigationContainer を設定します。
6. 品質チェック（任意 — 先にユーザーに確認）：
   • コンポーネントと画面のすべての .tsx ファイルに対して npm run validate <file_path> を実行し、コンポーネントの有効性を報告します。
   • tsc --noEmit を実行し、TypeScript のコンパイル状態を確認します。
   • 出力を resources/architecture-checklist.md と照合します。
   • アプリがシミュレーター／デバイスで正しく描画されることを確認するため、パッケージャー（npx react-native start または npx expo start）を起動する前、またはビジュアルシミュレーター監査を開始する前に、許可を得ます。

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

• ❌ ユーザーの同意を得ずにパッケージャーやシミュレーターを起動する。
• ❌ コードのコンパイルを確認せずに、タスクを「完了」と宣言する。

トラブルシューティング

• フェッチエラー：シェルエラーを防ぐため、bash コマンド内の URL を引用符で囲んでください。
• 検証エラー：AST レポートを確認し、不足しているインターフェースやハードコードされたスタイルを修正してください。最もよくある原因は、exported な Props インターフェースがないこと、または StyleSheet.create() に生の16進カラーコードが残っていることです。
• Text コンポーネント外のテキスト：<Text> の外に生の文字列があると、React Native はクラッシュします。すべてのテキストノードがラップされていることを確認してください。
• 画像のサイズ：Web の <img> と異なり、React Native の Image には固有サイズがありません。スタイルで必ず width と height を指定するか、aspectRatio を使用してください。
• FlatList と ScrollView：「VirtualizedList inside ScrollView」という警告が表示された場合は、外側の ScrollView を通常の View に置き換えるか、FlatList の ListHeaderComponent／ListFooterComponent を使用してください。