bulk-import

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bulk-import an existing design system into Subframe by discovering files on disk, building a manifest, and uploading via the CLI.

Use this skill only when the user explicitly asks to bulk-import many components in one batch (e.g. "use the bulk import skill to upload all my components"). For any other "bring my design system into Subframe" request — default to
/subframe:design
's incremental
design_component
,
design_snippet
, and
write_design_document
tools. Both paths route to the same underlying AI agent, so output quality is identical; bulk-import only saves orchestration time when the user genuinely wants to batch-submit many components in a single CLI invocation.

Availability: This feature is currently only available for select teams. If the CLI returns an error like
"Design system import is not enabled for this team"
, this means the feature has not been enabled for the user's team. Direct the user to request access here or proceed with an incremental import. Do not retry or troubleshoot further — this is an access gate, not a bug.

Goal state: All design system files are uploaded to Subframe for processing.

通过在磁盘上查找文件、构建清单并通过CLI上传，将现有设计系统批量导入Subframe。

仅当用户明确要求批量导入多个组件时才使用此功能（例如："使用批量导入功能上传我所有的组件"）。对于其他任何"将我的设计系统导入Subframe"的请求，请默认使用
/subframe:design
的增量式工具
design_component
、
design_snippet
和
write_design_document
。两种方式都会调用相同的底层AI Agent，因此输出质量一致；只有当用户确实希望通过单次CLI调用批量提交多个组件时，批量导入才能节省编排时间。

可用性说明：此功能目前仅对部分团队开放。如果CLI返回类似
"Design system import is not enabled for this team"
的错误，说明该用户的团队未启用此功能。请引导用户在此申请访问权限，或改用增量式导入。请勿重试或进一步排查问题——这是权限限制，并非程序缺陷。

目标状态：所有设计系统文件均已上传至Subframe等待处理。

MCP Authentication

MCP身份验证

If you cannot find any Subframe MCP tools (like

list_projects

generate_auth_token

), the MCP server likely needs to be authenticated. Ask the user to authenticate the Subframe MCP server. If the user is using Claude Code or Codex, instruct them to run

/mcp

to view and authenticate their MCP servers, and then say "done" when they're finished.

如果找不到任何Subframe MCP工具（如

list_projects

、

generate_auth_token

），则MCP服务器可能需要进行身份验证。请让用户对Subframe MCP服务器进行身份验证。如果用户使用的是Claude Code或Codex，请指导他们运行

/mcp

命令查看并验证其MCP服务器，完成后告知"done"。

Credentials

凭证信息

The CLI needs an auth token and project ID. If the user hasn't provided these, use MCP tools to get these automatically:

Project ID — Call
```
list_projects
```
to get the list of projects. Each project includes a
```
projectId
```
,
```
name
```
,
```
teamId
```
, and
```
teamName
```
.
- One project: Use it automatically.
- Multiple projects: Always ask the user which project to use. Present each project with its
```
teamName
```
  to disambiguate. If the user already mentioned a specific team or project name, match it against the
```
teamName
```
  and
```
name
```
  fields — but still confirm before proceeding. Never silently pick a project when multiple exist.
Auth token — Call
```
generate_auth_token
```
with the
```
teamId
```
from the user's selected project. Do not use a
```
teamId
```
from a different project.

The project ID is also visible in any Subframe URL:

app.subframe.com/<PROJECT_ID>/...

Fallback: If the MCP tools are not available, direct the user to

https://app.subframe.com/cli/auth

to get their auth token and project ID.

CLI需要身份验证令牌（auth token）和项目ID。如果用户未提供这些信息，请使用MCP工具自动获取：

项目ID — 调用
```
list_projects
```
获取项目列表。每个项目包含
```
projectId
```
、
```
name
```
、
```
teamId
```
和
```
teamName
```
字段。
- 单个项目：自动使用该项目。
- 多个项目：务必询问用户要使用哪个项目。展示每个项目时需附带其
```
teamName
```
  以区分。如果用户已提及特定团队或项目名称，需与
```
teamName
```
  和
```
name
```
  字段匹配，但在操作前仍需确认。存在多个项目时，切勿自行默认选择。
身份验证令牌 — 使用用户所选项目的
```
teamId
```
调用
```
generate_auth_token
```
。请勿使用其他项目的
```
teamId
```
。

项目ID也可在任意Subframe URL中查看：

app.subframe.com/<PROJECT_ID>/...

备选方案：如果MCP工具不可用，请引导用户访问

https://app.subframe.com/cli/auth

获取身份验证令牌和项目ID。

Workflow

工作流程

1. Discover design system files

1. 查找设计系统文件

We only want visual/presentational layer files — the reusable UI primitives that make up the design system. Skip anything that's deeply coupled to business logic, data models, API calls, or application state.

Include:

Pure UI components (buttons, inputs, cards, modals, badges, etc.)
Layout primitives (containers, grids, stacks, etc.)
Theme/styling files
Stories

Exclude:

Components that fetch data, call APIs, or manage application state
Page-level components that wire together business logic
Utility functions, hooks, or helpers that aren't visual
Test files (other than stories)

Use Glob and Read tools to find files. Look for:

Theme files (global styling):

```
tailwind.config.*
```
Global CSS files (e.g.
```
globals.css
```
,
```
global.css
```
,
```
app.css
```
,
```
index.css
```
)
Design token files (e.g.
```
tokens.json
```
,
```
tokens.ts
```
,
```
theme.ts
```
)

Component files:

React component files (
```
.tsx
```
,
```
.jsx
```
) in component directories
Story files (
```
.stories.tsx
```
,
```
.stories.jsx
```
,
```
.stories.ts
```
)
Component CSS modules

Use these search strategies:

Look for
```
tailwind.config.*
```
at the project root
Look for global CSS in
```
src/styles/
```
,
```
src/
```
,
```
app/
```
,
```
styles/
```

Look for components in common directories:

src/components/

components/

src/ui/

ui/

lib/components/

When unsure whether a component is a design system primitive or an application component, quickly read the file — if it imports data-fetching libraries, stores, or API clients, skip it.

我们仅需要视觉/展示层文件——即构成设计系统的可复用UI基础组件。跳过任何与业务逻辑、数据模型、API调用或应用状态深度耦合的文件。

需包含的文件：

纯UI组件（按钮、输入框、卡片、模态框、徽章等）
布局基础组件（容器、网格、堆叠布局等）
主题/样式文件
组件故事文件（Stories）

需排除的文件：

涉及数据获取、API调用或管理应用状态的组件
整合业务逻辑的页面级组件
非视觉相关的工具函数、Hooks或辅助工具
测试文件（组件故事文件除外）

使用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模块

使用以下搜索策略：

在项目根目录查找
```
tailwind.config.*
```
在
```
src/styles/
```
、
```
src/
```
、
```
app/
```
、
```
styles/
```
目录中查找全局CSS文件

在常见组件目录中查找组件：

src/components/

、

components/

、

src/ui/

、

ui/

、

lib/components/

如果不确定某个组件是设计系统基础组件还是应用组件，可快速查看文件内容——若文件导入了数据获取库、状态管理库或API客户端，则跳过该文件。

2. Group files by component

2. 按组件分组文件

For each component, separate files into two categories:

entrypoint
— the path to the main component file. Must reference one of the

sourceFiles

sourceFiles
— the primary component implementation:

The component source file(s) (
```
.tsx
```
,
```
.jsx
```
) containing markup and styles

supportingFiles
— everything else that helps understand the component:

Story files (
```
.stories.tsx
```
,
```
.stories.jsx
```
,
```
.stories.ts
```
)
CSS modules (
```
.module.css
```
,
```
.module.scss
```
)
Documentation files (
```
.md
```
)

Group by logical design system component — e.g.

Button.tsx

is a source file, while

Button.stories.tsx

Button.module.css

, and

Button.md

are supporting files for the "Button" component.

针对每个组件，将文件分为两类：

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. Write manifest

3. 编写清单文件

Create the

.subframe/

directory if it doesn't exist, then write the manifest:

bash

mkdir -p .subframe

Write the manifest to

.subframe/import-design-system.json

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"
      ]
    }
  ]
}

Component names must be unique. If there are conflicting component names, ask the user how they would like to resolve them, e.g. by adding a prefix based on the directory.

如果

.subframe/

目录不存在，先创建该目录，然后编写清单文件：

bash

mkdir -p .subframe

将清单文件写入

.subframe/import-design-system.json

：

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. Show summary before uploading

4. 上传前展示摘要

Before running the CLI, print a summary so the user can spot any issues:

List of component names
List of theme files
Total file count

Then proceed with the upload. The user can interrupt if something looks wrong.

在运行CLI命令前，打印一份摘要供用户检查是否存在问题：

组件名称列表
主题文件列表
文件总数

然后再进行上传。如果用户发现问题，可以中断操作。

5. Submit for import

5. 提交导入请求

Run the CLI to submit the design system for import. This uploads the files to Subframe and kicks off an asynchronous import job — it does not complete the import inline.

Always pass the auth token so the CLI doesn't prompt interactively.

bash

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

If any files are missing the CLI will abort with an error. Otherwise, report to the user that the import has been submitted and will be processed shortly.

运行CLI命令提交设计系统导入请求。此操作会将文件上传至Subframe并启动异步导入任务——导入过程不会在命令行内实时完成。

务必传入身份验证令牌，避免CLI弹出交互式提示。

bash

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

如果有文件缺失，CLI会报错并终止操作。否则，告知用户导入请求已提交，将很快开始处理。

Error Handling

错误处理

If the CLI exits with an error, show the full error output to the user
Access errors: If the CLI returns
```
"Design system import is not enabled for this team"
```
, this is not a bug or auth issue — the import feature is only available for certain teams. Let the user know and direct them to request access here. Do not retry with a new token or attempt workarounds.
Auth errors: try generating a new token with
```
generate_auth_token
```
, or suggest the user re-authenticate at
```
https://app.subframe.com/cli/auth
```
Network errors: suggest checking connectivity and retrying
If the manifest JSON is malformed, fix it and retry — don't ask the user to debug JSON

如果CLI报错退出，请向用户展示完整的错误输出
权限错误：如果CLI返回
```
"Design system import is not enabled for this team"
```
，这并非程序缺陷或身份验证问题——导入功能仅对特定团队开放。告知用户此情况并引导其在此申请访问权限。请勿尝试使用新令牌重试或寻找变通方法。
身份验证错误：尝试使用
```
generate_auth_token
```
生成新令牌，或建议用户前往
```
https://app.subframe.com/cli/auth
```
重新进行身份验证
网络错误：建议用户检查网络连接并重试
如果清单JSON格式有误，请修复后重试——不要让用户自行调试JSON