stitch-nextjs-components

Stitch → Next.js 15 App Router コンポーネント

あなたは Next.js のシニアエンジニアです。HTML ソース（Stitch の画面、ローカルファイル、URL）を、最新の App Router の規約に従った、クリーンで本番環境に対応できるコンポーネントに変換します。Pages Router や Vite の SPA ではありません。すべてのコンポーネントには、ダークモード、レスポンシブレイアウト、基本的なアクセシビリティが最初から備わっています。

このスキルを使う場面

次の場合は、react-components ではなくこのスキルを使ってください。

• 対象プロジェクトが App Router（app/ ディレクトリ）を使う Next.js 13 以降である
• ユーザーが next.js、app router、server components、server actions、next-themes に言及している
• プロジェクトに app/layout.tsx、app/page.tsx、または next.config.* ファイルがある

前提条件

HTML ソースが必要です。次のいずれかを使用できます。

• Stitch の画面 — Stitch MCP へのアクセスと、生成済みの画面が必要です
• ローカル HTML ファイル — Stitch アカウントは不要です
• URL — Stitch アカウントは不要です

また、以下が必要です。

• ダークモード用に、対象プロジェクトに next-themes がインストールされている（または、ユーザーが追加を承認している）

ステップ 1：ソースを解決する

以降のすべての処理では、1 つのファイル temp/source.html を読み込みます。ユーザーから提供されたものに応じた方法で HTML を取得し、そこに保存したらステップ 2 に進んでください。マークアップの取得元にかかわらず、このスキルの残りの手順は同じです。

Stitch の画面から取得する場合：

1. ネームスペースを特定する — list_tools を使って Stitch MCP のプレフィックスを見つけます
2. メタデータを取得する — [prefix]:get_screen を使ってデザイン JSON を取得します
3. HTML をダウンロードする — GCS URL には、信頼性の高いダウンローダーが必要です。

   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
   

4. 視覚的に確認する — 書き換える前に screenshot.downloadUrl を確認します。完全な解像度で取得するには URL に =s0 を追加してください。API が報告する width／height にかかわらず、そのままの URL では 512px のサムネイルが返されます。

ローカル HTML ファイルから取得する場合：

mkdir -p temp && cp "path/to/design.html" temp/source.html

URL から取得する場合：

bash scripts/fetch-stitch.sh "https://example.com/page" "temp/source.html"

名前に反して、このスクリプトは汎用の堅牢なダウンローダーです。リダイレクトに対応し、一時的な失敗時には再試行し、gzip を処理し、結果が空の場合はエラーを明示します。URL が Stitch を指しているかどうかは問いません。

スクリーンショットから取得する場合： アップロードする方法はありません。Stitch MCP API には画像アップロード用のツールがありません。stitch-mcp-generate-screen-from-text を使ってテキストプロンプトからデザインを再現するか、HTML を手書きして上記のローカルファイルの方法を使ってください。

API キーが必要なのは Stitch を使う方法だけです。ローカルファイルや URL の変換には、Google アカウントは一切必要ありません。

ステップ 2：サーバーコンポーネントとクライアントコンポーネントを選ぶ

この判断ツリーはファイル単位ではなく、コンポーネントごとに適用してください。

条件	使用するもの
onClick、onChange、useState、useEffect、アニメーションがある	'use client'
データの表示のみで、インタラクティブ性がない	サーバーコンポーネント（ディレクティブは不要）
クライアントコンポーネントのライブラリをラップする	'use client'
Server Action を使うフォーム	サーバーコンポーネント + <form action={serverAction}>

サーバーコンポーネントをデフォルトにしてください。 必要な場合に限り 'use client' を追加します。これは App Router で最も大きな効果をもたらすパターンです。

ステップ 3：コンポーネントのアーキテクチャ

ファイル構成

app/
├── [route]/
│   ├── page.tsx              ← Server Component (route entry)
│   └── components/
│       ├── [Name].tsx        ← Logic-heavy Client Component
│       ├── [Name].module.css ← Scoped styles (optional)
│       └── index.ts          ← Re-exports
src/
├── components/
│   └── ui/                   ← Reusable primitives
├── data/
│   └── mockData.ts           ← Static content decoupled from components
└── types/
    └── index.ts              ← Shared TypeScript types

ルール

• Props の契約：すべてのコンポーネントには、ファイルの先頭に Readonly<ComponentNameProps> インターフェースを定義します。
• データの分離：すべての静的テキスト、画像 URL、リストデータは src/data/mockData.ts に置きます。コンポーネントには Props 経由でデータを渡します。
• 色のハードコード禁止：CSS カスタムプロパティのクラス（bg-[var(--color-primary)]）またはセマンティックな Tailwind トークンを使います。JSX 内で任意の hex 値を使わないでください。
• インラインスタイル禁止：例外は、JS の計算による幅など、本当に動的な値に限ります。

Step 4: CSS 変数を使ったダークモード

このプロジェクトでは、next-themes と連携する CSS 変数のアプローチを採用しています。ソースから色を次の順序で解決し、セマンティックトークンに割り当てます。

1. <head> 内の インライン tailwind.config（Stitch が出力するもの）— 存在する場合はそのまま使用します。
2. ソース内の CSS カスタムプロパティ（:root { --color-primary: ... }）— 手書きやテンプレートの HTML で一般的です。
3. リンクまたはインラインのスタイルシート — 宣言されている色、フォントファミリー、角丸、間隔を解析します。
4. 最後の手段 — マークアップ内で最も頻繁に使われている計算済みの値（主要な背景色、テキスト色、アクセントカラー、見出し／本文フォント、角丸）からトークンを導き、推定した内容をユーザーに伝えて修正できるようにします。

URL のルートでダウンロードされるのは単一の HTML レスポンスのみです。外部リンクされたスタイルシートは取得されない場合があります。上記の方法でトークンを解決できない場合は、パレットを独自に作り出さず、その旨を伝えてください。

app/globals.css 内：

:root {
  --color-background: #ffffff;
  --color-surface: #f4f4f5;
  --color-primary: /* dominant action color from the source */;
  --color-primary-foreground: #ffffff;
  --color-text: #09090b;
  --color-text-muted: #71717a;
  --color-border: #e4e4e7;
}

.dark {
  --color-background: #09090b;
  --color-surface: #18181b;
  --color-primary: /* same hue, lighter shade for dark bg */;
  --color-primary-foreground: #09090b;
  --color-text: #fafafa;
  --color-text-muted: #a1a1aa;
  --color-border: #27272a;
}

app/layout.tsx では、next-themes の ThemeProvider でラップします：

import { ThemeProvider } from 'next-themes'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Step 5: レスポンシブレイアウト

すべてのコンポーネントは、sm（640px）、md（768px）、lg（1024px）、xl（1280px）のブレークポイントで動作する必要があります。

ソースデザインに基づいて、次のパターンを適用します。

• ナビゲーション：デスクトップナビゲーションには hidden md:flex、モバイルのハンバーガーメニューには flex md:hidden を使用します。
• グリッド：grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 — まずは1列にします。
• タイポグラフィ：text-2xl md:text-4xl — 画面が大きいほど拡大します。
• パディング：px-4 md:px-8 lg:px-16 — 画面幅が広いほど余裕を持たせます。
• 画像：CLS を防ぐため、必ず sizes 属性を指定して next/image を使用します。

Step 6: アクセシビリティの基本

依頼されなくても、すべてのコンポーネントに次の内容を含めてください。

• セマンティック HTML：<nav>、<main>、<section>、<article>、<header>、<footer> を使用します。セマンティック要素が適切な場合に <div> を使ってはいけません。
• インタラクティブ要素：ボタンには <button> を使用し、<div onClick> は使用しません。リンクには <a> または next/link を使用します。
• 画像：<Image> には必ず内容を説明する alt 属性を指定します。装飾用画像には alt="" を指定します。
• ARIA ラベル：アイコンのみのボタンには aria-label を指定します。同じ種類のランドマーク領域が複数ある場合は、それぞれに aria-label を指定します。
• フォーカスリング：独自の focus-visible:ring-* による代替なしに outline-none を使用してはいけません。
• 色のコントラスト：くすんだ背景にくすんだテキストを使用しないでください。コントラスト比を目視で確認します。

デザインにモーダル、ドロップダウン、タブなどの複雑なインタラクションがある場合は、stitch-a11y スキルを使用して完全な監査を行ってください。

Step 7: 実行手順

1. 環境の確認 — node_modules がない場合は、npm install を実行します。
2. データレイヤー — デザインのコンテンツから src/data/mockData.ts を作成します。
3. コンポーネントの作成 — resources/component-template.tsx を出発点として使用します。StitchComponent のすべての箇所を実際のコンポーネント名に置き換えます。
4. ダークモードのトークン — app/globals.css に CSS 変数の宣言を追加します。stitch-design-system スキルを使用する場合は、代わりに生成された design-tokens.css をインポートします。
5. アプリケーションへの組み込み — app/page.tsx または該当するルートページを更新し、新しいコンポーネントをインポートして表示します。
6. 品質チェック — 完了を宣言する前に、resources/architecture-checklist.md に沿って確認します。
7. 開発時の検証 — npm run dev を実行し、ライトモードとダークモードの両方を確認します。

Step 8: アニメーション（任意）

ソースデザインに明確な動きの意図（ホバー状態、トランジション、表示アニメーション）がある場合は、コンポーネントの作成後に stitch-animate スキルを使用します。場当たり的にアニメーションを追加せず、prefers-reduced-motion への対応を含め、適切に処理できるこのスキルに任せてください。

トラブルシューティング

問題	解決方法
GCS URL で fetch が失敗する	bash では常に URL を引用符で囲みます：bash scripts/fetch-stitch.sh "$URL" out.html
ダークモードでハイドレーションの不一致が発生する	<html> タグに suppressHydrationWarning を追加します
next-themes が見つからない	npm install next-themes
Server Component でフックを使用している	コンポーネントを独自のファイルに移し、'use client' ディレクティブを追加します
ダークモードで CSS 変数が適用されない	.dark クラスが <body> ではなく <html> にあることを確認します

他のスキルとの連携

• stitch-design-system — 最初に実行して design-tokens.css を生成します。globals.css にインポートします。
• stitch-animate — その後に実行して、生成されたコンポーネントにモーションを追加します。
• stitch-a11y — デザインにモーダル、ドロップダウン、または複雑なインタラクションがある場合は、その後に実行します。

参考資料

• resources/component-template.tsx — 本番環境ですぐに使えるコンポーネントのボイラープレート
• resources/architecture-checklist.md — リリース前の品質チェックリスト
• scripts/fetch-stitch.sh — 信頼性の高い GCS HTML ダウンローダー