import

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

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

通过识别本地磁盘文件、构建清单文件并通过CLI上传，将现有设计系统导入Subframe。

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

Credentials

凭证信息

The CLI needs an auth token and project ID. If the user hasn't provided these, direct them to:

Go to
```
https://app.subframe.com/cli/auth
```
Copy the project ID and auth token shown on that page

The project ID is also visible in any Subframe URL:

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

CLI需要认证令牌（auth token）和项目ID。如果用户尚未提供这些信息，请引导他们执行以下步骤：

访问
```
https://app.subframe.com/cli/auth
```
复制该页面显示的项目ID和认证令牌

项目ID也可以在任意Subframe URL中找到：

app.subframe.com/<PROJECT_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组件（按钮、输入框、卡片、模态框、徽章等）
布局基础组件（容器、网格、堆叠布局等）
主题/样式文件
Story文件

需排除的文件：

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

使用Glob和Read工具查找文件，重点关注：

主题文件（全局样式）：

```
tailwind.config.*
```
全局CSS文件（例如
```
globals.css
```
、
```
global.css
```
、
```
app.css
```
、
```
index.css
```
）
设计令牌文件（例如
```
tokens.json
```
、
```
tokens.ts
```
、
```
theme.ts
```
）

组件文件：

组件目录下的React组件文件（
```
.tsx
```
、
```
.jsx
```
）
Story文件（
```
.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
—— 所有有助于理解组件的其他文件：

Story文件（
```
.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
Auth errors: suggest the user check their token or 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运行出错，请向用户显示完整的错误输出
认证错误：建议用户检查令牌或重新访问
```
https://app.subframe.com/cli/auth
```
进行认证
网络错误：建议用户检查网络连接并重试
如果清单JSON格式有误，请修复后重试——不要让用户自行调试JSON问题