magicpath

MagicPath

AI を通じて UI コンポーネントを作成、共有、インストールするためのプラットフォームです。コンポーネントは magicpath-ai CLI を介して、ユーザーのプロジェクトにソースコードとして追加されます。

MagicPath のキャンバスコンポーネントは、npx -y magicpath-ai code ... サブコマンドを使って、ローカルコードから直接作成・編集することもできます。詳しくはコードからキャンバスコンポーネントを編集または作成するをご覧ください。この方法では編集できる範囲が厳密に定められており、コード作業ディレクトリ内の src/App.tsx、src/index.css、src/components/generated/ 以下のファイル、および assets/ 内の一時的な画像アセットのみ編集できます。

このスキルを、ブラウザーが組み込まれたエージェントホスト内で実行する場合は、適切に、エージェントの横にある永続的なビジュアルキャンバスとして MagicPath プロジェクトを使用してください。キャンバスの作成用にプロジェクトを作成する場合は、作成後、code start の実行前に、すぐに組み込みブラウザーでそのプロジェクトを開いてください。詳しくは組み込みブラウザーの使用をご覧ください。

用語： ユーザーは MagicPath コンポーネントを「デザイン」と呼ぶことがよくあります。この2つの用語は同じ意味です。ユーザーが「デザイン」「自分のデザイン」「あのデザイン」と言った場合は、MagicPath コンポーネントを意味するものとして扱ってください。それに応じて検索、確認、インストールしてください。

ユーザーは MagicPath のデザインシステムを「テーマ」と呼ぶこともあります。ユーザーが「テーマ」「自分のテーマ」「X のテーマを使って」と言った場合は、CSS 変数、フォント、スタイル設定の指示をまとめた MagicPath デザインシステムを意味します。これらを扱うには list-themes と get-theme を使用してください。

ユーザーはチーム（「ワークスペース」とも呼ばれます）に所属している場合があります。ユーザーが「チームのデザイン」「チームのコンポーネント」や、「Acme Inc」のようなチーム名を挙げた場合は、そのチームが所有するプロジェクトやコンポーネントを意味します。個人用ワークスペースとチームのワークスペースを切り替えるには、list-teams、--team、--personal フラグを使用してください。

ユーザーは、MagicPath で作成したスキルについて尋ねることもあります。これらは MagicPath チャットから呼び出せる再利用可能な指示のセットで、npx -y magicpath-ai skills ... で管理できます。個人用スキルはユーザーのワークスペースにあり、チームスキルは MagicPath のチームにあります。プラットフォームが別途明示しない限り、公開 MagicPath スキルは読み取り専用です。

最初の手順

npx -y magicpath-ai info -o json を実行して、認証状態とプロジェクトのコンテキストを確認してください。初回の実行では npx によるパッケージのダウンロードに数秒かかることがありますが、2回目以降はすぐに完了します。

• auth.authenticated が false の場合は、npx -y magicpath-ai login を実行し、ブラウザーでの認証が完了するまで待ってから、npx -y magicpath-ai whoami -o json で確認してください。

ゲストセッション

ユーザーからペアリングコード（gst_… のような短いコード。通常、アカウントを作らずに MagicPath を試している場合に提供されます）が渡されたら、一度だけ接続してください。

npx -y magicpath-ai login --guest-code <code>

次に npx -y magicpath-ai whoami -o json を実行します。ここで guest: true、作業可能な唯一の projectId、および canvasUrl が報告されます。通常の code start --project <projectId> → code submit のフローでそのプロジェクトを作成してください。送信するたびに、キャンバスにリアルタイムで反映されます。

ゲストセッションはその単一のプロジェクトに限定され、有効期限があります。セッション中は次の点に従ってください。

• プロジェクト上でデザインを作成・編集するには code start / code submit を使用してください。これがセッションの主な目的です。
• 組み込みブラウザーがあるホストでは、canvasUrl（whoami から取得）を開き、キャンバスの更新をユーザーが横で確認できるようにしてください。ゲストキャンバスを開く方法は canvasUrl のみです。完全なアカウントが必要な share や view は使用しないでください。
• チーム、追加のプロジェクト、テーマなど、その他のワークスペース機能を利用するには完全なアカウントが必要です。コマンドの実行時にアカウントが必要だと報告された場合は、ブラウザーで開いているキャンバスからサインアップするようユーザーに伝えてください。これにより、このプロジェクトがユーザーのアカウントに保存され、その他の機能も利用できるようになります。（セッションの有効期限がすでに切れている場合は、プロジェクトを保存できず、最初からやり直すことになります。）ペアリングコードなしで、ゲストに login を実行するよう伝えてはいけません。

チームでの作業

ユーザーは、共有プロジェクトやテーマを所有するチームに所属している場合があります。デフォルトでは、list-projects と search はすべてのワークスペース（個人用と、ユーザーが所属するすべてのチーム）の結果を返します。絞り込みフラグを使用して、対象範囲を限定してください。

チームを確認する

npx -y magicpath-ai list-teams -o json を実行すると、ユーザーが所属するチームを確認できます。

{ "teams": [{ "id": "123", "name": "Acme Inc", "role": "ADMIN" }] }

チームで絞り込む

• デフォルト（フラグなし）：list-projects と search には、個人用とすべてのチームのプロジェクトが含まれます。幅広く検索する場合、追加のフラグは不要です。
• --team "Acme Inc" または --team <teamId>：特定のチームに絞り込みます。list-projects、search、list-themes、get-theme で使用できます。
• --personal：ユーザー個人のプロジェクト／コンポーネントのみを表示します。list-projects と search で使用できます。

JSON 出力

プロジェクトと検索結果には、ownerType（"personal" または "team"）と ownerName（ユーザーのメールアドレスまたはチーム名）が含まれます。これらを使って、コンポーネントの保存場所をユーザーに伝えてください。

メンバーを確認する

npx -y magicpath-ai list-members --team "Acme Inc" -o json を実行すると、チームのメンバーを確認できます。

{ "team": { "id": "123", "name": "Acme Inc" }, "members": [{ "id": "456", "displayName": "Chloe Smith", "email": "[email protected]", "role": "MEMBER" }] }

メンバーで絞り込む

• list-components の --created-by <userId>：特定のユーザーが作成または編集したコンポーネントに絞り込みます。list-members で名前からユーザー ID を特定してから使用してください。
• プロジェクトの createdBy フィールド：list-projects に含まれる各プロジェクトの createdBy: { id, displayName } には、作成者が表示されます。
• コンポーネントの lastEditedBy フィールド：list-components に含まれる各コンポーネントの lastEditedBy: { id, displayName } には、最後に編集したユーザーが表示されます。

重要： 認証済みユーザーがアクセスできるプロジェクト（自分の個人用プロジェクトと、自分がメンバーであるチームのプロジェクト）のみを確認できます。他のユーザーの個人用プロジェクトにはアクセスできません。他のユーザーの作業を探す場合は、個人用プロジェクトではなく、チームのプロジェクト（--team）のみを検索してください。個人用プロジェクトは、メンバーとして明示的に招待された場合を除き、所有者だけが閲覧できます。

よくあるパターン

• 「Chloe が最後に作業していたのは何ですか？」 → list-members --team "Acme Inc" -o json で Chloe のユーザー ID を確認 → list-projects --team "Acme Inc" -o json でチームのプロジェクトのみを取得 → 各プロジェクトで list-components <projectId> --created-by <chloeId> --sort-by createdAt --order desc -o json を実行します。最も新しいコンポーネントを報告してください。他のユーザーの作業を探すために個人用プロジェクトを検索しないでください。個人用プロジェクトは所有者だけが閲覧できます。
• 「チームのデザインを見せて」または「Acme Inc が作成したものは何ですか？」 → list-teams でチームを確認し、次に list-projects --team "Acme Inc" -o json、続いて list-components <projectId> -o json を実行します。
• 「チームの最新デザインを見せて」 → 上記と同じ手順ですが、list-components に --sort-by createdAt --order desc --limit 1 を指定します。
• 「このプロジェクト／コンポーネントを作成したのは誰ですか？」 → それぞれの一覧コマンドで、プロジェクトの createdBy フィールド、またはコンポーネントの lastEditedBy フィールドを確認します。
• チームに言及せず**「自分のデザイン」**と尋ねられた場合 → 通常はデフォルト（すべてのプロジェクト）が適切です。チームのプロジェクトを明示的に除外したい場合にのみ、--personal を使用してください。
• 「チームのテーマを使って」 → list-themes --team "Acme Inc" -o json を実行し、続いて get-theme <name> --team "Acme Inc" -o json を実行します。

MagicPath スキルの管理

ユーザーが MagicPath に保存されたスキルの作成、一覧表示、確認、更新、インポート、削除、有効化／無効化、またはローカルへのインストールを依頼した場合は、この手順を使用してください。データを返すすべてのコマンドでは、JSON モードを優先してください。

npx -y magicpath-ai skills list -o json
npx -y magicpath-ai skills list --team "Acme Inc" -o json
npx -y magicpath-ai skills get <skillIdOrSlug> -o json
npx -y magicpath-ai skills create --name "Skill name" --description "When to use it" --instructions-file ./SKILL.md -o json
npx -y magicpath-ai skills import ./skill-package.skill -o json
npx -y magicpath-ai skills update <skillIdOrSlug> --disable -o json
npx -y magicpath-ai skills delete <skillIdOrSlug> -y -o json

スコープと所有権

• スキルがチーム／ワークスペースに属するとユーザーが述べた場合は、--team <nameOrId> を使用します。
• 個人用スキルには --team を指定しません。
• skills list には、チャットでユーザーが利用できる MagicPath の公開スキルがデフォルトで含まれます。ユーザーが編集可能なスキルを求めている場合は、--owned-only を指定します。
• 公開スキルは読み取り専用です。コマンドの出力で所有者／編集可能であることが明確に示されていない限り、公開スキルを更新または削除しようとしないでください。
• インポートした .zip または .skill パッケージのコンテンツは MagicPath では変更できませんが、skills update <id> --enable/--disable を使って有効化または無効化できます。

スキルの作成または更新

• 短い一行の指示を超える場合は、指示をローカルファイルに書き込み、--instructions-file を使用します。これにより、シェルの引用符に関する問題を避け、Markdown を保持できます。
• MagicPath のスキルには、空でない名前、説明、指示が必要です。説明にはスキルを使用すべき状況を記載し、指示には作業の進め方を記載してください。
• 観察したワークフローを再利用可能なスキルにする場合は、トリガー、制約、手順、例、および将来のエージェントが読むべきファイルや参考資料をまとめてください。

MagicPath スキルのローカルへのインストール

ユーザーが MagicPath のスキルを外部のコーディングエージェントにインストールしたい場合は、まずスキルを取得し、その後、ローカルの Agent Skills フォルダーとして作成します。

1. npx -y magicpath-ai skills get <skillIdOrSlug> -o json を実行します。
2. スキルのスラッグと同じ名前のフォルダーを作成します。
3. name と description を少なくとも含むフロントマターを記述し、その後に取得した instructions を続けた SKILL.md を作成します。

---
name: example-skill
description: Use when ...
---

...instructions from MagicPath...

4. スキルに同梱ファイルがある場合は、npx -y magicpath-ai skills get <skillIdOrSlug> --files -o json を実行し、次に各ファイルを --file <path> で取得して、ローカルのスキルフォルダー内に同じ相対パスで再作成します。
5. 現在のエージェントホストのローカルスキルのワークフローを使って、そのフォルダーをインストールまたは登録します。ホストが Agent Skills CLI に対応している場合は、そのツールでローカルフォルダーからインストールします。対応していない場合は、ホストのドキュメントに記載されたローカルスキルディレクトリにフォルダーを配置します。

ユーザーの現在のプロジェクトの外部、またはグローバルなエージェント設定ディレクトリに書き込む前に、確認してください。

ワークフロー

データを返すすべてのコマンド（search、list-projects、list-components、list-teams、list-themes、get-theme、skills、selection、active-project、info、add、inspect、code）では、必ず -o json を使用してください。 人間が読みやすい表ではなく、扱いやすい構造化出力が得られます。

フェーズ 1：調査

1. 認証を確認する — npx -y magicpath-ai whoami -o json を実行して、認証を確認します。
2. 現在の選択項目を確認する — ユーザーが「選択したコンポーネント」「選択した画像」「選択中のデザイン」と言及するなど、特定のキャンバス上の選択項目を指している場合は、npx -y magicpath-ai selection -o json を実行します。コンポーネントが返された場合は、そのまま使用します。検索／確認のフローを省略し、返された generatedName を使って次に進みます。返された各コンポーネントには、そのコンポーネントのキャンバス上に現在表示されているリビジョンを示す selectedRevisionId も含まれています。レスポンスには、選択した images が含まれることもあります。その場合、後で code start を実行すると、以下で説明するように、それらの選択した画像を assets/selected/** から使用できます。code context --revision など、後続のコマンドがリビジョンを受け取る場合は、この値を渡して、データベース上で正規のものとされているバージョンではなく、ユーザーが見ているバージョンを対象に処理します。
3. アクティブなプロジェクトを確認する — ユーザーが「開いているプロジェクト」「このプロジェクト」「作業中のプロジェクト」と言及するなど、特定のコンポーネント名を挙げずに作業中のプロジェクトを指している場合は、npx -y magicpath-ai active-project -o json を実行します。何も選択されていない場合でも、ブラウザーで現在開いているプロジェクトが返されます。プロジェクトが1つ返された場合は、それを作業中のプロジェクトとして扱い、プロジェクト選択を省略します。複数返された場合は一覧表示し、どれかを尋ねます。空のリストが返された場合、ユーザーはキャンバスを開いていないため、list-projects を実行してユーザーに尋ねます。ユーザーの発言に応じて適切なコマンドを選びます。コンポーネントへの言及には selection、プロジェクトへの言及には active-project、どちらにも該当しない場合は list-projects を実行してユーザーに尋ねます。（selection の出力にもアクティブなプロジェクトが含まれるため、ユーザーがコンポーネントに言及している場合は、別途 active-project を実行せずにプロジェクトも取得できます。）
4. コンポーネントを探す — npx -y magicpath-ai search <query> -o json を使ってすべてのプロジェクトを検索するか、list-projects -o json の後に list-components <projectId> -o json を実行して一覧を確認します。active-project ですでにプロジェクトがわかっている場合は、すべてのワークスペースを検索する代わりに、list-components <projectId> -o json を使って検索対象をそのプロジェクトに絞ります。
5. プロジェクトの画像を確認する — プロジェクトのキャンバスにどのスタンドアロン画像があるか（参照、重複の回避、またはユーザーへの説明のため）を確認するには、npx -y magicpath-ai image list <projectId> -o json を実行し、各 url をダウンロードして表示します。コンポーネントの previewImageUrl を使う場合と同じ方法です。（これらはキャンバス上の画像であり、code フローの assets/ ビルド入力とは別のものです。） スタンドアロンのラスター画像（写真、イラスト、テクスチャ、または背景が透明な切り抜き画像）のリクエストには、キャンバスデザインを構築する代わりに npx -y magicpath-ai image generate --prompt "..." -o json を使います。既存の写真を編集またはスタイル変更するには、--ref <path> を渡します。結果を image add でキャンバスに配置するか、コードセッションの assets/ フォルダーにコピーしてデザイン内で使用します。フラグについては、image generate を参照してください。
6. コンポーネントの見た目を確認する — search と list-components の結果には previewImageUrl フィールドが含まれています。これらの画像をダウンロードして分析し、コンポーネントを推奨する前に、それぞれの見た目を把握します。プレビュー画像は自分で内容を把握するためのものです。ユーザーから明示的に求められない限り、埋め込みプロジェクトのキャンバスで個別デザインのプレビューに移動しないでください。
7. ユーザーに確認する（停止して待つ） — ユーザーが正確な generatedName を指定していない場合は、見つかった内容（名前、generatedName、プロジェクト）を伝え、それが正しいコンポーネントか尋ねます。埋め込みプロジェクトのキャンバスがアクティブな場合は、キャンバスをプロジェクトのままにし、ユーザーから明示的に求められた場合にのみ個別のデザインを開くか共有します。埋め込みプロジェクトのキャンバスがない場合は、通常の確認手段として npx -y magicpath-ai view <generatedName> でブラウザープレビューを開きます。一致候補が複数ある場合は、すべて一覧表示して、どれかを尋ねます。ここで必ず停止し、ユーザーの返答を待ちます。ユーザーが明示的に確認するまで先に進まないでください。 まだ add または inspect を実行しないでください。

フェーズ 2：対象のコンテキストを理解する

このフェーズは非常に重要です。 何かをインストールする前に、コンポーネントをどこで使い、そこで何をする必要があるのかを必ず理解してください。この手順を省略すると、見た目は正しくても動作が異なるコンポーネントになってしまいます。

MagicPath の外部でデザインを使用する場合： フォルダーへのエクスポート、アプリへのインストール、ローカル UI の置き換え、別のフレームワークへの変換を行う前に、ローカルコードで MagicPath のデザインを使用するを読み、内容に従ってください。このガイドでは、正確なリビジョンを固定する方法、変更を加える前に 1:1 の一致を確立する方法、ローカルの動作を維持する方法、レンダリング結果を検証する方法、そして差分をユーザーが明示的に要求した変更に限定する方法を定めています。

7. MagicPath コンポーネントのソースを確認する — npx -y magicpath-ai inspect <generatedName> -o json を使用して、ソースコードを読み取ります。何をレンダリングするのか、どの props を受け取るのか、レイアウトについてどのような前提があるのか（固定幅、絶対配置など）を特定します。
8. 対象コードベースのコンテキストを確認する — インストールする前に、コンポーネントを配置するファイルを読みます。以下を理解してください。
   • 既存の機能：コンポーネントを置き換える場合、現在のコンポーネントは何をしていますか？ どのようなコールバック、状態、API 呼び出し、ナビゲーション、検証、または副作用を処理していますか？ 既存の動作はすべて維持するか、意図的に対処する必要があります。
   • レイアウトのコンテキスト：親レイアウトはどのようなものですか？ flex/grid コンテナですか？ レスポンシブブレークポイントはどこですか？ 余白はどのように設定されていますか？ 単独では完璧に見えるコンポーネントでも、サイズに関する前提が合わなければレイアウトを崩す可能性があります。
   • データフロー：周囲のコードからどのような props、コンテキスト、または状態が渡されますか？ 何を受け取る想定ですか（コールバック、フォームデータ、イベントなど）？
   • デザインシステム：プロジェクトではどのようなスタイル設定のパターン（Tailwind、CSS modules、テーマトークンなど）が使われていますか？ MagicPath コンポーネントのスタイルは、既存のスタイルと調和させ、衝突させないようにする必要があります。

テーマの適用（該当する場合）

ユーザーが適用したいテーマを指定している場合、またはブランド／デザインシステムを名前で参照している場合：

1. 利用可能なテーマを一覧表示する — npx -y magicpath-ai list-themes -o json を実行して、すべてのテーマを確認します。
2. テーマ定義を取得する — npx -y magicpath-ai get-theme <id-or-name> -o json を実行して、定義全体を取得します。
3. prompt フィールドを読む — フィールドがある場合、デザイナーによる自然言語のスタイル指示（例：「角を丸くする。境界線より影を優先する。CTA にはブランドの青を使う」）が含まれています。コンポーネントを調整する際は、これらの指示に従ってください。
4. CSS 変数を適用する — テーマの light オブジェクトと dark オブジェクトでは、CSS 変数名が値に対応付けられています（例：--background: #ffffff、--primary: #3b82f6）。MagicPath コンポーネントを調整する際は、ハードコードされた色の代わりにこれらの CSS 変数を使用します：bg-[var(--background)]、text-[var(--primary)] など。コンポーネントが defaultTheme（light または dark）を尊重するようにしてください。
5. フォントを扱う — テーマに fonts が含まれている場合は、プロジェクトでこれらのフォントを読み込む（Google Fonts のリンクまたはカスタムフォント用の @font-face 宣言）とともに、コンポーネントがテーマのフォント CSS 変数（例：font-family: var(--font-body)）を通じてフォントを参照するようにします。
6. React/JS 以外のプロジェクト — テーマデータはスタイルシートではなく、参照用のデータです。CSS 変数を対象プラットフォームに応じた形式に変換します（SwiftUI の Color アセット、Android のテーマ XML、Python のテンプレートコンテキストなど）。prompt フィールドと色／フォントの値が表すのは、プラットフォームに依存しないデザインの意図です。CSS をそのまま使うのではなく、各プラットフォームのネイティブなパターンに対応させてください。

コードからキャンバスコンポーネントを作成または編集する

ユーザーが MagicPath のキャンバスコンポーネントを直接作成したい場合にのみ、このフローを使用してください。

npx -y magicpath-ai code start --project <projectId> --dir . --name "Component Name" -o json
npx -y magicpath-ai code start --component <componentId> --dir . -o json
npx -y magicpath-ai code context <componentId> --dir . -o json  # read-only
npx -y magicpath-ai code submit --dir . --wait -o json

code start は、状態を保持するコーディングセッションを開始する唯一のコマンドです。新しいコンポーネントを作成するには --project を、既存のコンポーネントを編集するには --component を使用してください。編集可能なファイルを書き込み、キャンバス上に保留中のリビジョンを作成または再利用し、エージェントのプレゼンスを表示します。

code context は読み取り専用です。既存のコンポーネントの正確なソースリビジョンを確認またはエクスポートするために使用してください。送信経路として使用してはいけません。

編集できるのは、次の箇所のみです：src/App.tsx、src/index.css、src/components/generated/**、および assets/** 内の一時画像アセットです。

src/App.tsx には、生成されたコンポーネントをレンダリングする設定がすでに組み込まれています。編集できるのは、最上位のテーマ値を変更する場合のみです。

code start の実行時にキャンバス上で画像シェイプが選択されていると、JSON レスポンスに selectedImages が含まれる場合があります。CLI は、短時間のみ有効なこれらの画像 URL を assets/selected/** にダウンロードします。レスポンス内のローカルな assetPath を TSX／CSS で使用してください。期限切れになるため、一時的な accessUrl をコンポーネントのソースに貼り付けてはいけません。

Tailwind v4 のルール

MagicPath テンプレートでは Tailwind v4 を使用しています。次の方法でスタイルを設定してください。

• src/index.css には @tailwind base;、@tailwind components;、@tailwind utilities; ではなく、@import 'tailwindcss'; を記述する必要があります。
• テーマトークン（bg-background、text-foreground、border-border、bg-primary など）は、index.css の @theme inline { ... } ブロックを介して設定されています。削除しないでください。
• :root ブロックと .dark ブロックで、実際のトークン値を定義しています。削除しないでください。
• カスタムのユーティリティクラスを追加する場合、既存の内容を置き換えずに index.css の末尾に追加してください。
• tailwind.config.js はありません。設定は、Tailwind v4 の @theme ディレクティブを介して index.css に記述されています。

フェーズ 3：インストールと調整

9. プロジェクトに追加する — npx -y magicpath-ai add <generatedName> -y を使用して、コンポーネントファイルをインストールします。非対話型のコンテキストでは、必ず -y を指定してください。React 以外のプロジェクト（Swift、Python など）の場合は、add を実行しないでください。代わりに npx -y magicpath-ai inspect <generatedName> -o json を使用してソースを参照し、対象の言語とフレームワークでコンポーネントを作り直してください。
10. 本番環境で使用できるようコンポーネントを調整する — MagicPath コンポーネントはデザイン成果物です。視覚的な意図と構造を表現していますが、多くの場合、そのままでは本番環境で使用できる状態ではありません。追加した後、必ずコンポーネントファイルを編集し、次の点に対応してください。

• レスポンシブにする：ハードコードされた幅や高さ（例：w-[300px]）を、レスポンシブなユーティリティ（w-full max-w-sm、md:w-64 lg:w-80 などのレスポンシブブレークポイント）に置き換えてください。デザインが単一のビューポートのみを対象としている場合でも、すべてのビューポートで動作するようにするのが役割です。
• 実際のインタラクティブ機能を追加する：静的なコンテンツやプレースホルダーを、実際の props、state、イベントハンドラーに置き換えてください。「Submit」と表示される MagicPath のボタンには onClick prop と読み込み状態が必要です。フォームにはバリデーションと onSubmit が必要です。
• データフローを接続する：コンポーネントをアプリの実際のデータに接続してください。親からの props、コンテキストプロバイダー、API 呼び出し、ルーターの状態などが対象です。モックデータを残さないでください。
• 既存の機能を維持する：既存のコンポーネントを置き換える場合は、以前のコンポーネントが提供していたすべての機能（フォーム送信、エラー処理、読み込み状態、アクセシビリティ、キーボードナビゲーション、分析イベント）を確認し、新しいコンポーネントでもすべて対応できるようにしてください。
• 再デザインせず、プロジェクトのパターンに合わせる：同じ状態管理とエラー処理の方法を使用してください。算出結果が MagicPath のデザインを維持する場合に限り、スタイルの抽象化を再利用してください。正確な値を、似ているだけのローカルトークンやプリミティブに置き換えてはいけません。

フェーズ 4：ページに統合する

11. インポートしてレンダリングする — add の出力にある importStatement を使ってコンポーネントをインポートします。定義した props を渡します。
12. レイアウトへの適合を確認する — コンポーネントを配置した後、親レイアウトを確認し、問題なく統合されていることを確かめます。コンポーネントがはみ出したり、予期しない余白が生じたり、ページのレスポンシブなレイアウトを崩したりしていないか確認します。

デザインから本番環境への考え方

MagicPath はデザインツールです。 MagicPath のコンポーネントは、見た目と構造を表すものであり、コードで表現されたデザイン仕様です。ただし、デザインカンプと本番用コンポーネントは別物です。

デザイン成果物	エージェントとしての役割
固定幅 w-[400px]	レスポンシブにする：w-full max-w-md またはブレークポイントに基づく指定
静的なテキスト "John Doe"	動的な props に置き換える：{user.name}
プレースホルダー onClick={() => {}}	実際のハンドラーに接続する：onClick={handleSubmit}
3 項目のハードコードされたリスト	実際のデータをマッピングする：{items.map(…)}
エラー状態・読み込み状態がない	読み込みスピナー、エラーバウンダリー、空の状態を追加する
アクセシビリティ属性がない	aria-label、role、キーボードハンドラー、フォーカス管理を追加する
デスクトップ専用のレイアウト	レスポンシブブレークポイントやモバイルナビゲーションのパターンを追加する
src="/photo.jpg" を指定した装飾用画像	実際のアセット、またはプロジェクトに適したプレースホルダーを使う

基本原則：MagicPath のコンポーネントが示すのは、何を作るべきかです。レスポンシブで、アクセシブルで、アプリケーションに完全に接続された状態で動作するようにするのが、あなたの役割です。

よくあるシナリオ

既存のコンポーネントを置き換える場合（例：古いログインフォームを MagicPath のデザインに置き換える）：

1. 古いコンポーネントをよく読み、すべての prop、コールバック、バリデーションルール、副作用を列挙します
2. npx -y magicpath-ai inspect <generatedName> -o json で MagicPath コンポーネントのソースを調べます
3. npx -y magicpath-ai add <generatedName> -y で MagicPath コンポーネントをインストールします
4. MagicPath コンポーネントを編集し、同じ prop とコールバックをすべて受け取れるようにします
5. 古いコンポーネントの機能がすべて新しいコンポーネントにもあることを確認します
6. 親コンポーネントでインポートを差し替えます。親のコードはほとんど変更しないでください

MagicPath のデザインライブラリから新しいページを構築する場合：

1. list-components でプロジェクトのコンポーネントを確認します
2. まずページのレイアウトを計画し、各セクションに対応する MagicPath コンポーネントを特定します
3. npx -y magicpath-ai add <generatedName> -y で必要なコンポーネントを 1 つずつインストールします
4. 各コンポーネントをインポートしてページのレイアウトを構築します
5. 各コンポーネントを調整します：レスポンシブなサイズ設定、実際のデータ、適切なルーティング、状態管理
6. すべてのコンポーネントで、余白、タイポグラフィ、色の使い方に一貫性があることを確認します

MagicPath の単一コンポーネントを参考にする場合：

1. npx -y magicpath-ai inspect <generatedName> -o json でソースを調べます
2. 色、余白、レイアウト構造、タイポグラフィなど、デザインの意図を把握します
3. コンポーネントをインストールして調整するか、同じデザイン言語に沿った独自のものを構築する際の参考にします

重要なルール

• addはインストールして使うためのコマンドです。 インストールしたコンポーネントをインポートしてレンダリングする場合にのみaddを実行してください。ソースコードを読むだけであれば、代わりにinspectを使用してください。
• addの実行後は、必ずコンポーネントをインポートしてください。 addの目的は、インポートして使うソースファイルを取得することです。コンポーネントを追加した後、そのスタイルやマークアップを別のファイルにコピーしてはいけません。コンポーネントを直接インポートしてレンダリングしてください。
• MagicPathのコンポーネントは、自分で所有するソースコードです。 addの実行後、コンポーネントファイルはプロジェクト内のsrc/components/magicpath/<name>/に配置されます。必要なプロパティの追加、動作の変更、スタイルの調整、アプリの状態との連携のために、直接編集してかまいません。また、そうするべきです。
• コンポーネントの連携が必要な場合： （1）コンポーネントをaddし、（2）必要なプロパティ（例：onSubmit、placeholder、className）を受け取れるようコンポーネントファイルを編集し、（3）親コンポーネントからインポートして、それらのプロパティを渡してください。コンポーネントのJSXやスタイルを親ファイルにコピーしてはいけません。
• コンポーネントをそのまま配置するだけではいけません。 必ず周辺のコードを読み、レイアウト上の制約を把握し、コンポーネントが合うように調整してください。調整せずに配置されたMagicPathコンポーネントは、機能ではなくバグです。
• inspectは読み取り専用です。 ファイルを書き込まずに、ソースコード全体を表示します。インストールを決める前に、コンポーネントが要件に合うかどうかを判断する場合に使用してください。
• addはReact/TypeScriptプロジェクト専用です。 addコマンドは.tsxファイルをsrc/components/magicpath/に書き込み、npm依存関係をインストールします。addはJavaScript/TypeScriptプロジェクトでのみ使用してください。JavaScript以外のプロジェクト（Swift、Pythonなど）では、inspectでコンポーネントのソースを読み、その後、プロジェクトの言語とフレームワークに合わせてデザインと動作を実装してください。
• viewコマンドを並列実行してはいけません。 viewコマンドはユーザーのためにブラウザーウィンドウを開きます。一度に開く対象は1つだけにしてください。
• 埋め込みブラウザーはプロジェクトのキャンバスに表示したままにしてください。 ユーザーから明示的に求められない限り、個別のデザインプレビューに移動しないでください。それで十分な場合は、代わりにデザイン共有リンクを返してください。
• 新しく作成したプロジェクトに作業を始める前に、そのプロジェクトを開いてください。 埋め込みブラウザーが利用可能で、新しいプロジェクト内での作業が依頼に含まれる場合は、code startまたはcode submitの前に、create-projectの直後にプロジェクトのキャンバスを表示してください。

プロジェクトの作成

プロジェクトとは、デザインやコンポーネントを保存するワークスペースです。ユーザーが明示的にプロジェクトの作成を依頼した場合（「新しいプロジェクトを作って…」「…のプロジェクトを作成して」など）、または新しいデザインを依頼していて、プロジェクトのコンテキストがまだなく、新しいプロジェクトが適切な保存先である場合に使用してください。

ワークスペースの選択

作成する前に、プロジェクトが個人用かチーム用かを判断してください。

• ユーザーがチーム名を指定した場合（「Acme Incにプロジェクトを作成して」など）、そのチームを特定して指定してください。
• ユーザーが「個人用プロジェクトを作成して」と言った場合、またはチームに言及せず、所属チームがない場合は、個人用をデフォルトにしてください。
• ユーザーの指定が曖昧で、1つ以上のチームに所属している場合は、npx -y magicpath-ai list-teams -o jsonを実行し、個人用かチーム用か、どのワークスペースにするかを尋ねてください。推測してはいけません。停止して、ユーザーの返答を待ってください。

コマンドの実行

npx -y magicpath-ai create-project --name "My Stuff" -o json                       # personal
npx -y magicpath-ai create-project --name "My Stuff" --team "Acme Inc" -o json     # team

• --nameは省略可能です。省略すると、プロジェクトには自動生成された仮の名前が付けられます。ユーザーがプロジェクト名を指定した場合は、必ず--nameを渡してください。
• --teamにはチーム名またはチームIDを指定できます。ユーザーの意図に合うチームを、list-teamsが返したチームの中から特定してください。
• JSON出力：{ project: { id, name, ownerType, ownerName, ... } }。idは後続のコマンドで必要になります。

プロジェクト作成後

ユーザーが新しいプロジェクト内でのデザインも依頼した場合は、レスポンスからidを取得し、コードからキャンバスコンポーネントを編集または作成するに記載されているキャンバスコンポーネント作成フロー（code start --project <id> --name "..."を実行し、ひな形として生成されたファイルに内容を記入して、code submit --waitを実行）を続けてください。デザインごとにプロジェクトを作り直してはいけません。1つのプロジェクトに多数のコンポーネントを格納できます。

新しく作成したプロジェクト内でデザインを作成または編集するタスクでは、そのプロジェクトをキャンバスとして扱ってください。埋め込みブラウザを備えたホストでは、次の順序を必ず守ってください。create-projectがidを返したら直ちにnpx -y magicpath-ai share <projectId> -o jsonを実行し、返されたプロジェクトURLを埋め込みブラウザで開いてから、code startまたはcode submitを開始してください。作業がキャンバスに表示されている間は、そのプロジェクトのキャンバスを表示したままにしてください。送信後に生成されたデザインのプレビューへ移動してはいけません。ただし、ユーザーがそのデザインだけを見たいと明示した場合は除きます。埋め込みブラウザがない場合、ユーザー向けの画面遷移が必要であればnpx -y magicpath-ai view <projectId>を使用してください。

利用可能な場合は、MagicPathプロジェクトを埋め込みキャンバスとして使用する

Codexや一部のCursorワークフローなどのエージェントホストでは、埋め込みブラウザまたはアプリ内ブラウザが利用できる場合があります。この機能が利用可能な場合、MagicPathのプロジェクトをエージェントの横に開いたまま、永続的なキャンバスとして使用できます。エージェントはローカルのコードとコンテキストを使って作業し、ユーザーはキャンバス上で作業内容を確認して選択できます。

新しく作成したプロジェクトを開く場合、ユーザーが現在使用しているプロジェクトに再接続する場合、または名前を指定したプロジェクトでキャンバスの作成を始める場合に、この方法を使用してください。ユーザーから特定のデザインを開くよう明示的に依頼された場合を除き、埋め込みブラウザで個別のデザインやコンポーネントへ自動的に移動してはいけません。

埋め込みブラウザを備えたホストでプロジェクトを開く場合、最初にviewを呼び出してはいけません。viewはOSのブラウザを開きます。代わりにnpx -y magicpath-ai share <projectId> -o jsonを実行して、ウィンドウを開かずにURLを取得し、ホストの埋め込みブラウザで返されたurlに移動してください。埋め込みブラウザがない場合、確実に操作できない場合、またはユーザーが通常のブラウザを明示的に希望している場合は、view <projectId>を使用してください。

CLIの認証と埋め込みブラウザの認証は別々です。whoamiまたはcreate-projectコマンドが成功しても、表示中のブラウザペインでMagicPathにサインイン済みとは限りません。返された/files/<projectId> URLを開いたときにホーム画面またはサインイン画面へリダイレクトされる場合は、引き続きそのプロジェクトに集中してください。ユーザーに埋め込みブラウザでMagicPathへサインインするよう伝え、サインイン後に同じプロジェクトURLへ戻ってください。プロジェクトキャンバスのセッションなしで表示できるという理由だけで、公開されている個別デザインのプレビューに切り替えてはいけません。

info、whoami、データの一覧表示や検索、テーマの取得、ソースの確認、アプリケーションへのコンポーネントのインストールなどのバックグラウンド作業では、プロジェクトを自動的に開いてはいけません。判断の指針と手順については、埋め込みブラウザの使用を参照してください。

既存のリポジトリを MagicPath に取り込む

ユーザーが Git リポジトリ（ローカルまたはオンライン）にすでにある UI を MagicPath のキャンバス上に再現したい場合（例：「アプリのサイドバーを MagicPath に取り込んで」「このプロジェクトを MagicPath に表示して」「このランディングページをここに再現して」）、code start → code submit のフローでキャンバスコンポーネントとして再現します。

これは add／inspect の逆です。信頼できる情報源はユーザーのリポジトリで、出力先はキャンバスです。この場合、add、inspect、code context は使用しないでください。手順は次のとおりです。

1. コードを取得する — ローカルパスを直接読み込むか、オンラインリポジトリを git clone --depth 1 <url> で一時ディレクトリ（--dir とは別の場所）にクローンします。非公開リポジトリにはユーザーの認証情報が必要です。推測せず、ユーザーに確認してください。
2. まずデザインの基盤を読み取る — グローバル CSS（globals.css／index.css／app.css）、デザイントークン（tailwind.config.*、CSS 変数、トークンファイル）、フォント、テーマ設定の方針、共有 UI プリミティブを確認します。これにより、近似ではなく忠実な再現が可能になります。
3. 対象を特定する — 単一の要素（例：サイドバー）の場合、そのファイルを開き、すべてのインポート（子コンポーネント、アイコン、スタイル、データ）に加え、サイズと位置を決めるレイアウトの親要素もたどります。ページまたはプロジェクト全体の場合は、エントリーポイントを特定し、1 つのインタラクティブなフレームにするか、画面ごとに別々のフレームにするかを決めます（Design Default ルール 5）。判断がつかない場合はユーザーに確認し、返答を待ってください。
4. キャンバス上に再現する — code start --project <id> --dir <workdir> --name "..." --width <px> --height <px> を実行し、src/components/generated/<Name>.tsx に忠実に実装します（リポジトリのフレームワークとスタイルを React + Tailwind v4 に変換します）。色、余白、タイポグラフィを正確に合わせ、実際のインタラクションを組み込み、データはローカルでモックしたうえで、code submit --wait を実行します。Design Defaults（レスポンシブ、中央揃え、デバイスのモックアップなし、単一画面、完全なインタラクティブ性）に従ってください。
5. 検証する — view を使って、ソースアプリと結果を比較します。

スタイル変換の表、エッジケース（モノレポ、React 以外のソース、サーバーコンポーネント、Tailwind v3 から v4 への移行）、および「アプリのサイドバーを取り込む」「このプロジェクトを表示する」の簡単なレシピを含む詳しい手順は、リポジトリの操作に記載されています。

コードからキャンバスコンポーネントを編集または作成する

ユーザーが別のアプリケーションに既存のコンポーネントをインストールしたいのではなく、MagicPath のキャンバスコンポーネント自体を作成または変更したい場合に、このワークフローを使用します。code サブコマンドは作業ディレクトリと、ディレクトリがどのコンポーネントとリビジョンに属するかを記録する小さなマニフェストファイル（magicpath-code.json）を操作します。

MagicPath のキャンバス上で作成するときは、美しく、機能的でインタラクティブな React コンポーネントを構築する、経験豊富なデザインエンジニアとして作業してください。 キャンバス上に作成するコンポーネント（code start／code submit 経由）は、静的なデザイン見本ではなく、実際に動作する小さなアプリであるべきです。状態に応じた動作があり、ホバー／フォーカス／アクティブ状態が機能し、ボタンを押すと何かが起き、フォームで入力を検証し、トランジションに意図が感じられるものにしてください。見た目は美しくても動きのないコンポーネントは失敗です。（このペルソナが適用されるのは code フローのみです。ユーザーのプロジェクトにコンポーネントをインストールする場合は、代わりにデザインから本番環境へのマインドセットに従ってください。）

最重要 — Design Defaults

ユーザーがリクエストで明示的に上書きしない限り、これらのルールは code サブコマンドで作成または編集するすべてのキャンバスコンポーネントに適用されます。add／inspect のインストールフローには適用されません。その場合はデザインから本番環境へのマインドセットを参照してください。これらのルールは、キャンバス上での作成に関して、このスキル内のほかのすべてのルールに優先します。

1. デバイスのモックアップは絶対に追加しないでください

コンポーネントを、iPhone／Android／ノートパソコン／デスクトップ／ブラウザーのフレーム、ステータスバー、ノッチ、ホームインジケーター、アドレスバーなど、デバイスの外観を模した要素で囲まないでください。ユーザーが「スマートフォンのフレーム内に表示して」「iPhone のモックアップに入れて」「Mac のウィンドウのようにして」と明示的に依頼した場合に限り、デバイスのモックアップを追加してください。モバイル向けのビューポートに合わせてデザインすることは、モックアップの依頼ではありません。キャンバスそのものがデバイスのフレームです。その中に別のデバイスを描かないでください。

2. あらゆる幅に常に対応させてください

ボタン、入力欄、バッジ、カードなどの小さなプリミティブも含め、すべてのコンポーネントをあらゆる幅で動作させてください。w-full、max-w-*、パーセント幅、flex／grid のサイズ指定、ブレークポイントユーティリティ（sm:、md:、lg:）を使ってください。外側のコンテナにピクセル単位の幅や高さをハードコードしないでください。例外は、アバター、アイコン、固定サイズのメディアなど、本質的にサイズが固定された要素だけです。

3. キャンバス内で常に中央に配置してください

コンポーネントのルートを、そのフレーム内で横方向に中央揃えにしてください。デザインが短い場合は、縦方向にも中央揃えにしてください。ルートで min-h-screen flex items-center justify-center、mx-auto、またはグリッドによる中央揃えを使ってください。キャンバスがコンテンツより大きい場合に、デザインが隅に寄ってはいけません。また、キャンバスが小さい場合に、はみ出してもいけません。

4. キャンバスのサイズ ≠ デバイスのモックアップ

ターゲットデバイスに合わせて、code start／code submit に --width／--height を指定してかまいません。指定することをおすすめします。たとえば、モバイルデザインなら --width 390 --height 844、デスクトップなら --width 1440 --height 900 とします。これにより、「これはモバイルデザインです」と伝えられます。ただし、中のコンテンツは流動的なままにしてください。同じコンポーネントを後から幅の広い、または狭いコンテナに配置しても、元のピクセルサイズに固定されたままではなく、適応する必要があります。

5. 1つのフレームに複数の画面を絶対に並べないでください

MagicPath コンポーネントは、1つのフレームです。「画面 1／画面 2／画面 3」を、1つのキャンバス内で横並び、縦並び、またはスライドショーとして描かないでください。そのような出力は不適切です。レンダリングも画面遷移もできず、ユーザーのキャンバスを無駄にします。

複数のビューにまたがるものをユーザーが求めている場合は、次の2つのパターンのいずれかを選び、そのパターンに従ってください。

A. 1つのフレーム内に自己完結したアプリを作る（ビューが同じフローに属する場合に推奨）。 React の state、条件付きレンダリング、タブコンポーネント、クライアントサイドルーティング、または useState によるビュー切り替えを使えば、1つのコンポーネントに複数のビュー、画面、モーダル、タブ、ステップ、ルートを含められます。ログイン → 新規登録 → パスワードを忘れた場合のフロー、複数ステップのウィザード、タブナビゲーション付きの設定ページ、詳細パネルをスライド表示するダッシュボードは、いずれも複数のフレームをつなぎ合わせるのではなく、内部 state を備えた1つのコンポーネントに含めてください。

B. 画面が本当に独立している場合は、複数のフレームを作る（画面ごとにコンポーネントを1つ）。 ユーザーが「ログイン画面、ダッシュボード、設定ページをデザインして」のように個別の成果物を求めている場合、それぞれを独立した MagicPath コンポーネントにしてください。code start --name "..." のセッションを別々に作成し、各セッションにそれぞれ独自の --dir を指定してください（作業ディレクトリを共有する並行セッションでは、互いの magicpath-code.json が上書きされます）。並行して作成してください。環境が並列サブエージェントに対応している場合は、フレームごとに1つずつ起動してください。対応していない場合は、ランナーで可能な方法を使ってセッションを並行実行してください。時間を「節約」するために、すべてを1つのキャンバスにレンダリングしようとしないでください。不適切な成果物が生成されます。

どちらのパターンが適切かわからない場合は、ユーザーに「内部ナビゲーションを備えた1つのインタラクティブなコンポーネントにしますか、それとも画面ごとに別々のフレームにしますか？」と尋ねてください。そして、回答を待ってください。

6. 静的なマークアップではなく、インタラクティブなコンポーネントを構築する

あなたはエンジニアであり、スクリーンショット生成ツールではありません。キャンバス上のすべてのコンポーネントは完全にインタラクティブでなければなりません。ボタンは実際のアクションを実行し、入力は制御され、フォームは送信と検証に対応し、ホバー／フォーカス／アクティブ／無効状態にスタイルが適用され、モーダルは開閉し、タブは切り替わり、ドロワーはスライドし、ドロップダウンは展開し、トグルは切り替わり、アコーディオンは折りたためる必要があります。ローカル状態には useState ／ useReducer を使用し、実際のイベントハンドラー（onClick、onChange、onSubmit、onKeyDown、onBlur）を設定し、アクセシビリティのために aria-* 属性を使用します。また、効果を高めるために適切なトランジション（Tailwind の transition-*、Framer Motion、または CSS アニメーション）を使用してください。プレースホルダーの onClick={() => {}} を残したコンポーネントや、インタラクティブな画面を静的なマークアップにしたものは未完成です。code submit の前に動作するよう実装してください。コンポーネントが複数の画面で構成されるフローを表す場合は、状態を使って画面間の移動を動作させてください（ルール 5.A を参照）。

編集可能なファイルの範囲。 code API が受け付けるのは、次のファイルの完全な置き換えのみです。

• src/App.tsx
• src/index.css
• src/components/generated/**
• 一時的な画像アセットに限り assets/**

package.json、vite.config.*、src/main.tsx、ロックファイル、その他のファイルは編集または送信しないでください。これらは拒否されます。

画像アセット。 ローカルの画像ファイルは <workdir>/assets/ に置き、たとえば ../../../assets/hero.png、/assets/hero.png、url("../../assets/hero.png") のようにコードまたは CSS から参照してください。MagicPath はこれらの一時アセットをアップロードし、参照先を安定した公開アセット URL に書き換え、ビルド前に assets/ ステージングフォルダーを削除します。data:image/...;base64,... をインライン化しないでください。base64 の画像データがある場合は、アセットファイルに移してください。

選択されたキャンバス画像。 ユーザーが code start の前にキャンバス上の画像シェイプを選択している場合、CLI はそれらを selectedImages に含め、短期間のみ有効なアクセス URL を使って各画像を assets/selected/** にダウンロードします。インポートまたは CSS では、ダウンロードした assetPath を使用してください。期限切れになるため、accessUrl を直接使用しないでください。

編集モードではソースファイルの削除と名前変更が可能です。 編集可能なソースファイルを削除するには、<workdir> からそのファイルを削除してください。code submit が削除を検出し、反映します。名前変更は、同じ送信内での削除と書き込みとして行います。アセットは一時的なステージング用入力であり、ローカルファイルを削除してもサーバーからは削除されません。作成モードでは削除するものはありません。ファイルを書き込まないでください。

このワークフローでは add や inspect を使用しないでください。 add／inspect は、再利用可能なレジストリーコンポーネントを別のアプリにインストールするためのものです。code ... はユーザーの MagicPath キャンバス上のコンポーネントを編集するためのもので、これらは別々のフローであり、混在させてはいけません。

既存のコンポーネントを編集する

1. npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json を実行します。これにより、保留中の編集リビジョンが作成または再利用され、キャンバス上にエージェントの存在が表示され、編集可能なファイルが書き込まれ、magicpath-code.json が <workdir> に書き込まれます。デフォルトでは、CLI はコンポーネントで現在選択されているリビジョンを基に開始します。特定のリビジョンを基に開始するには、--revision <revisionId> を渡します。これは、ユーザーが現在のものではないリビジョンを表示または参照している場合（たとえば、npx -y magicpath-ai selection から渡された値）に便利です。
2. <workdir> 内の許可されたファイルを編集、追加、または削除します（上記の境界を参照）。新しい画像は <workdir>/assets/ に置き、生成されたコンポーネントまたは CSS から参照します。サブコンポーネントファイルが使われなくなった場合は、そのソースファイルも削除してください。リビジョンに孤立したファイルを残さないでください。名前の変更は、削除してから書き込む形で行います。
3. npx -y magicpath-ai code submit --dir <workdir> --wait -o json を実行します。編集によってキャンバスの意図したサイズが変わる場合は、送信時に --width <px> と --height <px> の両方を渡します。
4. ジョブの結果が failed の場合は、返されたサニタイズ済み診断情報を読み、許可されたファイルのみを修正して、再度送信します。ビルド失敗を回避するために新しいコンポーネントを作成しないでください。
5. 送信結果に競合または古いベースが報告された場合は、npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json を再度実行して、編集セッションの状態を更新してから変更を再適用します。

新しいコンポーネントを作成する

重要な体験上のルール： コンポーネントのファイルを書く前に、必ず code start を実行してください。これにより、保留中のコンポーネントがキャンバスに登録され、ユーザーはエージェントが黙って作業するのではなく、作業中であることを確認できます。

想定されるファイル構成。 MagicPath コンポーネントでは、スリムな src/App.tsx から src/components/generated/ 内のトップレベルコンポーネントをインポートしてレンダリングします。実際の実装は src/components/generated/<ComponentName>.tsx（PascalCase のファイル名、名前付きエクスポート）に置きます。大きなコンポーネントは、必要なものをそれぞれインポートする追加の兄弟ファイルに分割してください。既存の MagicPath コンポーネントはすべてこの構成になっています。既存の任意のコンポーネントに対して code context が返す内容と比べてください。

CLI は code start の実行時に、この構成を自動で生成します。 code start が完了すると、作業ディレクトリには配線済みの src/App.tsx と、スタブの src/components/generated/<ComponentName>.tsx がすでに用意されています。コンポーネントのファイル名は --name を PascalCase にした形式と一致します（例：--name "Hero Card" → HeroCard.tsx）。スタブを実装で埋めてください。App.tsx は書き換えないでください。すでに正しく設定されています。App.tsx を編集するのは、最上部にある theme（'light'／'dark'）の値を変更する場合に限ります。

手順：

1. npx -y magicpath-ai code start --project <projectId> --dir <workdir> --name "Component Name" --width <px> --height <px> -o json を実行します。キャンバスのデフォルトサイズに頼らず、作成するコンポーネントに合った寸法を選んでください。保留中のコンポーネントを作成し、スリムな App.tsx とスタブを生成して、magicpath-code.json を書き込みます。注意： コンポーネントはレスポンシブで、中央に配置し、デバイスのモックアップを含めず、単一画面（複数画面のフローには内部状態を使用するか、画面ごとに code start セッションを並行して実行）にし、完全にインタラクティブ（実際のハンドラー、制御された入力、状態駆動のビュー、ホバー／フォーカス／アクティブ状態）にする必要があります。上記のデザインのデフォルトを参照してください。
2. <workdir>/src/components/generated/<ComponentName>.tsx にコンポーネントの実装を記述します。コンポーネントの規模が大きい場合は、同じディレクトリに追加ファイルを作成して分割してください。
3. 必要に応じて、<workdir>/src/index.css を編集してカスタムスタイルを追加します。画像ファイルは <workdir>/assets/ に置き、base64 を埋め込むのではなく、TSX または CSS から参照してください。
4. npx -y magicpath-ai code submit --dir <workdir> --wait -o json を実行します。最終的な実装に、開始時に選んだものとは異なるキャンバスサイズが必要な場合は、ここで --width <px> と --height <px> の両方を指定してください。
5. ビルドに失敗した場合は、コンポーネントのファイルを修正し、code submit --wait を再実行します。ユーザーから明示的な依頼がない限り、2つ目のコンポーネントを開始しないでください。

code create コマンドを使うと、start と submit を1回の呼び出しにまとめられます。明示的な2段階のフローを推奨します。ファイルを書き込んでいる間もキャンバス上で進捗を確認でき、生成されたひな形を出発点として作業できるためです。

ジョブの個別確認

後からジョブのステータスを確認する必要がある場合（たとえば、--wait を指定せずに送信した後）は、npx -y magicpath-ai code status <jobId> -o json を使用してください。pending、processing、completed、failed、cancelled のいずれかが返されます。

クイックリファレンス

# Auth
npx -y magicpath-ai login                    # one-click browser login
npx -y magicpath-ai whoami -o json           # check auth status
npx -y magicpath-ai info -o json             # full project context

# Teams and people
npx -y magicpath-ai list-teams -o json                  # list teams you belong to
npx -y magicpath-ai list-members --team "Acme" -o json  # list members of a team

# Create a new project
npx -y magicpath-ai create-project --name "My Stuff" -o json                    # personal
npx -y magicpath-ai create-project --name "My Stuff" --team "Acme" -o json      # team

# Find components (always use -o json)
npx -y magicpath-ai search "input box" -o json          # search across all workspaces
npx -y magicpath-ai search "button" --team "Acme" -o json   # search within a team
npx -y magicpath-ai list-projects -o json               # list all projects (personal + team)
npx -y magicpath-ai list-projects --team "Acme" -o json     # list only team projects
npx -y magicpath-ai list-projects --personal -o json        # list only personal projects
npx -y magicpath-ai list-components <id> -o json      # list components in a project
npx -y magicpath-ai list-components <id> --created-by <userId> -o json  # filter by person

# Inspect / open components and projects
npx -y magicpath-ai view <generatedName>              # open a component preview in browser
npx -y magicpath-ai view <projectId>                  # open a project in browser
npx -y magicpath-ai share <generatedName> -o json     # print a shareable URL for a component (no browser open)
npx -y magicpath-ai share <projectId> -o json         # print a shareable URL for a project (no browser open)
npx -y magicpath-ai inspect <generatedName> -o json   # show source code (no install)
npx -y magicpath-ai add <generatedName> --dry-run     # show what would be installed

# Install and use components
npx -y magicpath-ai add <generatedName> -y         # add to project (no prompts)

# Themes (design systems)
npx -y magicpath-ai list-themes -o json                 # list personal themes
npx -y magicpath-ai list-themes --team "Acme" -o json   # list team themes
npx -y magicpath-ai get-theme <id-or-name> -o json    # get theme CSS vars, fonts, prompt

# Current canvas context
npx -y magicpath-ai selection -o json                 # get currently selected component(s)
npx -y magicpath-ai active-project -o json            # get the project(s) the user has open

# Project canvas images
npx -y magicpath-ai image list <projectId> -o json            # list images on the project canvas (download each `url` to see it)
npx -y magicpath-ai image add <projectId> ./hero.png -o json  # add a local image (or an http(s) URL) to the canvas
npx -y magicpath-ai image generate --prompt "..." [--aspect-ratio 16:9] [--ref ./photo.jpg] [--out ./img.png] -o json  # AI-generate (or edit via --ref) a raster image; returns local path + hosted URL

# Author/edit canvas components from code (external-agent)
npx -y magicpath-ai code start --project <projectId> --dir <workdir> --name "Name" --width <px> --height <px> -o json # start a new pending component with chosen canvas size
npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json                 # start editing an existing component
npx -y magicpath-ai code start --component <componentId> --revision <revisionId> --dir <workdir> -o json # start editing a specific revision
npx -y magicpath-ai code context <componentId> --dir <workdir> -o json                           # read-only source fetch/export; not for submit
npx -y magicpath-ai code submit --dir <workdir> --width <px> --height <px> --wait -o json         # submit edits/size + wait for build
npx -y magicpath-ai code status <jobId> -o json                                                  # poll a build job

主な概念

• 各コンポーネントには generatedName（例：wispy-river-5234）があり、すべての操作で識別子として使用します
• コンポーネントはソースコードとして src/components/magicpath/<name>/ に追加されます
• add コマンドは importStatement と usage を返します。コードではこれらを使用してください
• インストールせずにソースコードを確認するには inspect を使用してください。コードを読むだけの目的で add を使用しないでください
• MagicPath コンポーネントは React/TypeScript のソースコードです。JS/TS プロジェクトでは add を使用し、他の言語では inspect で確認してから翻訳してください
• テーマ（デザインシステム）には CSS 変数（light／dark マップ）、任意の fonts、およびエージェント向けのスタイル設定の指示を含む任意の prompt があります。「テーマ」と「デザインシステム」は同じ意味で使用されます。list-themes で一覧を参照し、get-theme で定義全体を取得してください
• ソースの編集内容を MagicPath キャンバスに公開するには、code start と code submit を使用してください。code context は読み取り専用の正確なリビジョン取得機能で、外部へのエクスポート用にソースのスナップショットを提供することもできます。add／inspect は引き続き、レジストリ内のコンポーネントをインストールおよび確認するために使用します。

現在のプロジェクトコンテキスト

!`npx -y magicpath-ai info -o json 2>/dev/null || echo '{"error": "Could not run magicpath-ai via npx. Ensure Node.js is installed and the registry is reachable."}'`

上記の JSON には、認証状態、プロジェクト、CLI バージョンが含まれています。auth.authenticated が false の場合、他の操作を行う前にユーザーがログインする必要があります。

参考資料

• CLI リファレンス
• ローカルコードでの MagicPath デザインの使用 — コンポーネントまたはリビジョンを正確にエクスポートしたり、ローカル UI を置き換えたり、1:1 の忠実度と明示的に指定された差異を保ちながら MagicPath デザインを翻訳したりできます
• リポジトリの操作 — 既存のローカルまたはオンラインの Git リポジトリの UI を MagicPath キャンバスに取り込みます（例：「このプロジェクトを MagicPath でレンダリングして」「アプリのサイドバーを MagicPath に取り込んで」）
• 埋め込みブラウザーの操作 — Codex、Cursor、またはアプリ内ブラウザーを備えた別のホスト内で、MagicPath プロジェクトを永続的なキャンバスとして使用します