bulk-import

既存のデザインシステムを一括インポートするには、ディスク上のファイルを検出してマニフェストを作成し、CLI でアップロードします。

このスキルは、ユーザーが「すべてのコンポーネントを一括インポートする」のように、1 回のバッチで多数のコンポーネントを一括インポートするよう明示的に求めた場合にのみ使用してください。 それ以外の「デザインシステムを Subframe に取り込む」という依頼では、/subframe:design の design_component、design_snippet、write_design_document ツールを使った段階的なインポートをデフォルトにしてください。どちらの方法でも同じ基盤の AI エージェントを利用するため、出力品質は同じです。ユーザーが実際に多数のコンポーネントを 1 回の CLI 呼び出しでまとめて送信したい場合に限り、一括インポートでオーケストレーションの時間を短縮できます。

利用可能なチーム: この機能は現在、一部のチームのみ利用できます。CLI が "Design system import is not enabled for this team" のようなエラーを返した場合、ユーザーのチームではこの機能が有効になっていません。こちらからアクセスをリクエストするよう案内するか、段階的なインポートに進んでください。再試行や追加のトラブルシューティングは行わないでください。これはバグではなく、アクセス制限です。

目標の状態：すべてのデザインシステムファイルが、処理のために Subframe にアップロードされています。

MCP 認証

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

認証情報

CLI には認証トークンとプロジェクト ID が必要です。ユーザーからこれらの情報が提供されていない場合は、MCP ツールを使って自動的に取得してください。

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

プロジェクト ID は、任意の Subframe URL（app.subframe.com/<PROJECT_ID>/...）にも表示されます。

代替手段：MCP ツールを利用できない場合は、認証トークンとプロジェクト ID を取得するために https://app.subframe.com/cli/auth を開くようユーザーに案内してください。

---

ワークフロー

1. デザインシステムのファイルを見つける

対象は視覚的／プレゼンテーション層のファイルのみです。デザインシステムを構成する、再利用可能な UI プリミティブが該当します。ビジネスロジック、データモデル、API 呼び出し、アプリケーションの状態と密接に結び付いているものは除外してください。

含めるもの：

• 純粋な UI コンポーネント（ボタン、入力欄、カード、モーダル、バッジなど）
• レイアウトプリミティブ（コンテナー、グリッド、スタックなど）
• テーマ／スタイルのファイル
• ストーリー

除外するもの：

• データの取得、API の呼び出し、アプリケーションの状態管理を行うコンポーネント
• ビジネスロジックを組み合わせるページレベルのコンポーネント
• 視覚的でないユーティリティ関数、フック、ヘルパー
• テストファイル（ストーリーを除く）

Glob ツールと Read ツールを使ってファイルを探します。以下を確認してください。

テーマファイル（グローバルスタイル）：

• tailwind.config.*
• グローバル CSS ファイル（例：globals.css、global.css、app.css、index.css）
• デザイントークンのファイル（例：tokens.json、tokens.ts、theme.ts）

コンポーネントファイル：

• コンポーネントディレクトリ内の React コンポーネントファイル（.tsx、.jsx）
• ストーリーファイル（.stories.tsx、.stories.jsx、.stories.ts）
• コンポーネントの CSS モジュール

次の検索方法を使います。

1. プロジェクトのルートにある tailwind.config.* を探します
2. src/styles/、src/、app/、styles/ にあるグローバル CSS を探します
3. よく使われるディレクトリにあるコンポーネントを探します：src/components/、components/、src/ui/、ui/、lib/components/

コンポーネントがデザインシステムのプリミティブなのか、アプリケーションコンポーネントなのか判断できない場合は、ファイルをすばやく確認してください。データ取得ライブラリ、ストア、API クライアントをインポートしている場合は除外します。

2. コンポーネントごとにファイルをグループ化する

コンポーネントごとに、ファイルを次の 2 つのカテゴリに分けます。

entrypoint — メインコンポーネントファイルへのパスです。sourceFiles のいずれかを指定する必要があります。

sourceFiles — 主要なコンポーネントの実装です。

• マークアップとスタイルを含むコンポーネントのソースファイル（.tsx、.jsx）

supportingFiles — コンポーネントを理解するために役立つその他のすべてのファイルです。

• ストーリーファイル（.stories.tsx、.stories.jsx、.stories.ts）
• CSS モジュール（.module.css、.module.scss）
• ドキュメントファイル（.md）

論理的なデザインシステムコンポーネントごとにグループ化します。たとえば、Button.tsx はソースファイル、Button.stories.tsx、Button.module.css、Button.md は「Button」コンポーネントの補助ファイルです。

3. マニフェストを作成する

.subframe/ ディレクトリが存在しない場合は作成してから、マニフェストを記述します。

mkdir -p .subframe

マニフェストを .subframe/import-design-system.json に記述します。

{
  "theme": ["tailwind.config.ts", "src/styles/globals.css"],
  "components": [
    {
      "name": "Button",
      "entrypoint": "src/components/Button.tsx",
      "sourceFiles": ["src/components/Button.tsx"],
      "supportingFiles": ["src/components/Button.stories.tsx", "src/components/Button.module.css"]
    }
  ]
}

コンポーネント名は一意である必要があります。コンポーネント名が重複する場合は、ディレクトリに基づくプレフィックスを追加するなど、どのように解決するかをユーザーに尋ねてください。

4. アップロード前に概要を表示する

CLI を実行する前に、ユーザーが問題に気付けるよう概要を表示します。

• コンポーネント名の一覧
• テーマファイルの一覧
• ファイルの合計数

その後、アップロードに進みます。問題があるように見える場合、ユーザーは中断できます。

5. インポートを送信する

CLI を実行して、デザインシステムをインポート用に送信します。これによりファイルが Subframe にアップロードされ、非同期のインポートジョブが開始されます。インポートがその場で完了するわけではありません。

CLI が対話形式でプロンプトを表示しないよう、必ず認証トークンを渡してください。

npx @subframe/cli@latest import -p {PROJECT_ID} --manifest .subframe/import-design-system.json --auth-token {TOKEN}

ファイルが見つからない場合、CLI はエラーで中止します。問題がなければ、インポートが送信され、まもなく処理されることをユーザーに伝えてください。

---

エラー処理

• CLI がエラーで終了した場合は、エラー出力の全体をユーザーに表示します。
• アクセスエラー：CLI が "Design system import is not enabled for this team" を返した場合、これはバグでも認証の問題でもありません。インポート機能は一部のチームのみが利用できます。ユーザーにその旨を伝え、こちらからアクセスをリクエストするよう案内します。新しいトークンで再試行したり、回避策を試したりしないでください。
• 認証エラー：generate_auth_token で新しいトークンを生成するか、https://app.subframe.com/cli/auth で再認証するようユーザーに案内します。
• ネットワークエラー：接続を確認して再試行するよう案内します。
• マニフェスト JSON の形式が正しくない場合は、修正して再試行します。ユーザーに JSON のデバッグを求めないでください。