setup

Subframe でデザインしたページがローカルの開発環境でピクセル単位まで正確に表示されるよう、プロジェクトに Subframe をセットアップします。

目標の状態：開発サーバーが起動し、Subframe のページがデザインどおりに正確に表示されます。

MCP 認証

get_theme などの Subframe MCP ツールが見つからない場合は、MCP サーバーの認証が必要な可能性があります。Subframe MCP サーバーを認証するようユーザーに依頼してください。ユーザーが Claude Code または Codex を使用している場合は、/mcp を実行して MCP サーバーを表示・認証し、完了したら「done」と入力するよう伝えてください。

ワークフローの概要

1. MCP ツール（またはユーザーからの入力）を使って認証情報を取得する
2. プロジェクトの種類を判別する — リポジトリなし、既存の Subframe リポジトリ、または既存の Subframe 以外のリポジトリ
3. 適切な手順に従う — 新規プロジェクト、セットアップ済み、または既存のプロジェクト

• 上記のいずれかの手順を必ず実行してください。そうしないと Subframe は動作しません。これは重要なタスクであり、ユーザーが現在の作業を中断する必要がある場合でも実行してください。手順を省略しないでください。

4. フォントを設定する — すべての手順で必須です
5. セットアップを確認する — 開発サーバーを起動し、Subframe のページでテストする

---

認証情報を取得する

ユーザーが Subframe からコピーしたインストールプロンプトを貼り付ける場合があります。次の情報を抽出してください。

• Project ID — 短い英数字の文字列です（Subframe の URL app.subframe.com/<PROJECT_ID>/... にも含まれています）
• Auth token — 長い文字列で、通常は接頭辞またはラベルが付いています

ユーザーが認証情報を提供しない場合は、MCP ツールを使って自動的に取得してください。ユーザーに尋ねる必要はありません。

1. Project ID — list_projects を呼び出してプロジェクトの一覧を取得します。各プロジェクトには projectId、name、teamId、teamName が含まれています。
   • プロジェクトが1つの場合：自動的に使用します。
   • 複数のプロジェクトがある場合：必ず、使用するプロジェクトをユーザーに尋ねてください。区別できるよう、各プロジェクトの teamName を提示します。ユーザーがすでに特定のチーム名またはプロジェクト名を挙げている場合は、teamName と name のフィールドを照合します。ただし、続行する前に必ず確認してください。複数ある場合、黙ってプロジェクトを選択しないでください。
2. Auth token — ユーザーが選択したプロジェクトの teamId を指定して generate_auth_token を呼び出します。別のプロジェクトの teamId は使用しないでください。

フォールバック：MCP ツールが利用できない場合（例：MCP サーバーが認証されていない場合）は、https://app.subframe.com/cli/auth にアクセスして Auth token と Project ID を取得するようユーザーに依頼してください。

---

プロジェクトの種類を判別する

現在のディレクトリに package.json と .subframe/ フォルダーがあるか確認します。

条件	プロジェクトの種類	手順
package.json がない	新規プロジェクト	新規プロジェクト
package.json があり、.subframe/ フォルダーもある	セットアップ済み	セットアップ済み
package.json はあるが、.subframe/ フォルダーがない	既存の Subframe 以外のプロジェクト	ユーザーに確認してから、新規プロジェクトまたは既存のプロジェクト

既存の非 Subframe プロジェクトへの対応

現在のディレクトリに package.json があり、.subframe/ フォルダーがない場合は、次の 2 つの選択肢をユーザーに提示します。

• 新しいプロジェクトを作成（推奨） — 別のディレクトリに新しい Subframe プロジェクトを作成します。特に初めて Subframe を試す場合に、最も簡単な方法です。新規プロジェクトに進みます。
• このプロジェクトに Subframe を追加 — 現在のプロジェクトに Subframe をインストールします。既存のプロジェクトに進みます。

---

セットアップ済みの場合

プロジェクトに package.json と .subframe/ フォルダーの両方がすでにある場合、Subframe の初期化は完了しています。ユーザーが希望する操作を確認します。

• 再インストール／再同期 — CLI の init と sync を再実行して、コンポーネントと設定を更新します。古くなっている場合や、正常に動作しない場合に便利です。再初期化するには、既存のプロジェクトに進みます。
• 何もしない。セットアップ済み — セットアップをすべてスキップします。次の手順として /subframe:design や /subframe:develop などを提案します。

ユーザーが再インストールを希望すると確認できるまで、セットアップを進めないでください。

---

新規プロジェクトの場合

これが推奨される方法です。CLI によって、Subframe があらかじめ設定されたプロジェクト一式が作成されます。

1. ユーザーの希望を確認する

次の項目をユーザーに選んでもらいます。

• プロジェクト名：新しいプロジェクトディレクトリの名前（デフォルト：subframe-app）。既存のディレクトリと名前が重複してはいけません。CLI を実行する前に、そのディレクトリがすでに存在しないことを確認します。
• フレームワーク：Vite（推奨）、Next.js、または Astro
• Tailwind のバージョン：v3（tailwind）または v4（tailwind-v4）

2. CLI の init を実行する

必要なファイルをすべて正しくセットアップできるよう、このコマンドはサンドボックスの外部で実行する必要があります。対話型プロンプトを回避するため、すべての引数を直接渡します。

npx @subframe/cli@latest init \
  --name {PROJECT_NAME} \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --template {FRAMEWORK} \
  --css-type {TAILWIND_VERSION} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --tailwind \
  --css-path {CSS_PATH} \
  --install \
  --sync

各項目の内容は次のとおりです。

• {PROJECT_NAME} はプロジェクトディレクトリ名です（例：subframe-app）。
• {FRAMEWORK} は nextjs、vite、または astro です。
• {TAILWIND_VERSION} は tailwind（v3）または tailwind-v4 です。
• {CSS_PATH} はグローバル CSS ファイルのパスです。
  • Vite：src/index.css
  • Next.js：src/app/globals.css
  • Astro：src/styles/global.css

重要：対話型プロンプトが表示されないよう、すべての引数を明示的に渡す必要があります。対話なしで実行すると、CLI が何も表示せずに終了する場合があります。

CLI は次の処理を行います。

• スターターキットのテンプレートをダウンロードする
• .subframe/sync.json を作成する
• Tailwind を設定する
• すべてのコンポーネントを同期する
• 依存関係をインストールする

3. フォントを設定する

以下のフォントの設定を参照してください。新規プロジェクトでも必須です。

4. セットアップを確認する

以下のセットアップの確認を参照してください。

---

既存のプロジェクトの場合

既存のプロジェクトでは、追加の設定が必要になることがあります。CLI がセットアップの大部分を処理しますが、手動で修正が必要なプロジェクトもあります。

1. フレームワークを特定する

フレームワークを示す要素を確認します。

フレームワーク	判定要素
Next.js	package.json の依存関係に next がある、または next.config.* ファイルがある
Vite	package.json の devDependencies に vite がある、または vite.config.* ファイルがある
Astro	package.json の依存関係に astro がある、または astro.config.* ファイルがある

2. 前提条件を確認する

プロジェクトに必要な依存関係があることを確認します。

• React 16+ — package.json に react がある
• Tailwind CSS 3.4+ — package.json に tailwindcss がある
• TypeScript — package.json に typescript がある

不足しているものがある場合は、先にユーザーへ伝えてください。

3. CLI Init を実行する

このコマンドはサンドボックスの外で実行する必要があります。そうすることで、必要なファイルをすべて正しく設定できます。対話形式のプロンプトを避けるため、すべての引数を直接渡してください。

npx @subframe/cli@latest init \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --install \
  --sync

重要：対話形式のプロンプトを避けるため、すべての引数を明示的に渡す必要があります。対話形式以外で実行すると、CLI が何も表示せずに終了することがあります。

CLI は次の処理を試みます。

• .subframe/sync.json を作成する
• Tailwind を検出して設定する
• インポートエイリアスを設定する
• すべてのコンポーネントを同期する
• @subframe/core をインストールする

4. 設定を確認する

初期化後、すべてが正しく設定されたことを確認してください。CLI で設定されなかった項目がある場合（標準的でない構成ではよくあります）、手動で修正してください。

directory、importAlias、projectId を含む .subframe/sync.json が存在することを確認します。

Tailwind の設定を確認する：

• Tailwind v3 — tailwind.config.js に Subframe プリセットが設定されていることを確認します。

  presets: [require("./src/ui/tailwind.config")],
  

また、content 配列に Subframe ディレクトリが含まれていることを確認します。

content: ["./index.html", "./src/**/*.{js,jsx,ts,tsx}"],

Subframe プロジェクトでダークモードが有効になっている場合、CLI はライトモードとダークモード用の CSS 変数を含む theme.css ファイルも同期します。グローバル CSS ファイルでこれをインポートする必要があります。

@import "./ui/theme.css";

• Tailwind v4 — グローバル CSS ファイルでテーマをインポートする必要があります。

  @import "tailwindcss";
  @import "./ui/theme.css";
  

インポートエイリアスを確認する — @/* が正しく解決されることを確認します。正しく動作しない場合：

• Vite：tsconfig.app.json に baseUrl と paths を追加し、vite.config.ts に resolve.alias を追加します
• Astro：tsconfig.json に baseUrl と paths を追加します
• Next.js：通常は設定済みです。tsconfig.json を確認してください

5. トラブルシューティング

問題が発生した場合は、SearchSubframeDocs MCP ツールを使って解決策を探してください。

SearchSubframeDocs({ query: "tailwind configuration troubleshooting" })
SearchSubframeDocs({ query: "manual installation" })

ドキュメントには、トラブルシューティング用の包括的な手動インストールガイドが含まれています。

6. フォントを設定する

以下のフォントを設定するを参照してください。

7. セットアップを確認する

以下のセットアップを確認するを参照してください。

---

フォントを設定する

CLI はフォントを設定しません。get_theme MCP ツールを使ってフォント情報を取得してください。

get_theme({ projectId: "PROJECT_ID" })

テーマ設定には、Google Fonts を参照する fontFamily エントリーが含まれています。対応する <link> タグを追加してください。

Vite / Astro — index.html の <head> に追加します。

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous" />
<link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />

Next.js（App Router） — app/layout.tsx の <head> に追加します。

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
  <link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />
</head>

Next.js（Pages Router） — pages/_document.tsx の <Head> コンポーネント内に追加します。

フォントリンクの形式：

• フォント名のスペースを + に置き換えます（例：Inter+Tight）
• テーマに含まれるウェイトを wght@ パラメーターに指定します（セミコロン区切り）
• フォントファミリーごとに <link> を1つ追加します。ただし、プリコネクトリンクは1組のみ追加します

---

セットアップを確認する

設定後、Subframe のページが正しくレンダリングされることを確認してください。

1. 既存のページについて尋ねる

ユーザーに、**「Subframe でデザイン済みで、テストしたいページはありますか？」**と尋ねます。

• ある場合：/subframe:develop を使って実装し、レンダリングを確認します
• ない場合：/subframe:design を使ってページをデザインするよう提案するか、開発サーバーを起動してエラーがないことを確認します

2. 開発サーバーを起動する

npm run dev

3. 要約する

設定した内容をまとめます。

• .subframe/sync.json を設定済み
• Tailwind を設定済み（v3 プリセットまたは v4 インポート）
• コンポーネントを src/ui/（または設定したディレクトリ）に同期済み
• フォントを設定済み

次のステップを案内します。

• /subframe:design — AI を使って新しいページをデザインする
• /subframe:develop — Subframe のデザインをコードベースに実装する

---

重要な注意事項

• セットアップに関する問題のトラブルシューティングには、SearchSubframeDocs MCP ツールを使用してください。