develop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement Subframe designs in the codebase. Fetch the design via MCP, sync components, and add business logic.

在代码库中实现Subframe设计稿。通过MCP获取设计内容，同步组件并添加业务逻辑。

MCP Authentication

MCP 身份验证

If you cannot find the

get_page_info

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

/mcp

to view and authenticate their MCP servers.

如果你找不到

get_page_info

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

/mcp

来查看并验证其MCP服务器。

Detect Project State

检测项目状态

Before starting, check for

package.json

and

.subframe/

folder in the current directory:

Condition	Action
No `package.json`	Run `/subframe:setup` first — there's no project to implement into yet.
Has `package.json` AND has `.subframe/` folder	Proceed with the workflow below.
Has `package.json` but NO `.subframe/` folder	Ask the user (see below).

开始前，请检查当前目录下是否存在

package.json

和

.subframe/

文件夹：

条件	操作
无 `package.json`	先运行 `/subframe:setup` — 目前没有可用于实现的项目。
存在 `package.json` 且存在 `.subframe/` 文件夹	继续执行下方的工作流。
存在 `package.json` 但无 `.subframe/` 文件夹	询问用户（见下文）。

Existing non-Subframe project

现有非Subframe项目

If the current directory has a

package.json

but no

.subframe/

folder, ask the user which approach they prefer:

Use the design as inspiration — Fetch the design via MCP for reference, but implement the page using the existing styles, components, and patterns already in the repo. Translate the Subframe design's layout and structure into whatever UI framework the project already uses (e.g., existing component library, CSS modules, styled-components). Do NOT install Subframe or sync components. Skip to Inspiration Workflow.
Use Subframe styles and components — Install Subframe into the project so the design renders pixel-perfect with Subframe's generated code. Run
```
/subframe:setup
```
first, then continue with the Workflow below.

如果当前目录有

package.json

但没有

.subframe/

文件夹，请询问用户偏好以下哪种方案：

将设计作为参考灵感 — 通过MCP获取设计内容作为参考，但使用仓库中已有的样式、组件和模式来实现页面。将Subframe设计稿的布局和结构转换为项目当前使用的UI框架（例如现有组件库、CSS模块、styled-components）。请勿安装Subframe或同步组件。跳至灵感工作流。
使用Subframe样式和组件 — 在项目中安装Subframe，使设计稿通过Subframe生成的代码实现像素级还原。先运行
```
/subframe:setup
```
，然后继续执行下方的工作流。

Workflow

工作流

Fetch the design - Use
```
get_page_info
```
with the URL, ID, or name
Sync components if needed - Only if components don't exist locally
Create the page - Put it in the right place per codebase patterns
Add business logic - Data fetching, forms, events, loading/error states

获取设计内容 - 使用
```
get_page_info
```
工具，传入URL、ID或名称
按需同步组件 - 仅当组件在本地不存在时进行同步
创建页面 - 根据代码库的规范将页面放置在正确位置
添加业务逻辑 - 数据获取、表单处理、事件绑定、加载/错误状态

Inspiration Workflow

灵感工作流

Use this workflow when the user chose to use the design as inspiration in an existing non-Subframe project.

Fetch the design - Use
```
get_page_info
```
with the URL, ID, or name to get the design's layout and structure
Study existing patterns - Look at the project's existing components, styles, and conventions
Create the page - Implement the design using the project's existing UI framework, mapping Subframe components to their equivalents in the codebase (e.g., Subframe
```
Button
```
→ the project's own button component)
Add business logic - Data fetching, forms, events, loading/error states

当用户选择在现有非Subframe项目中将设计作为参考灵感时，使用此工作流。

获取设计内容 - 使用
```
get_page_info
```
工具，传入URL、ID或名称以获取设计稿的布局和结构
研究现有模式 - 查看项目中已有的组件、样式和约定
创建页面 - 使用项目现有的UI框架实现设计，将Subframe组件映射为代码库中的等效组件（例如Subframe
```
Button
```
→ 项目自身的按钮组件）
添加业务逻辑 - 数据获取、表单处理、事件绑定、加载/错误状态

Fetching Designs

获取设计内容

// By URL
get_page_info({ url: "https://app.subframe.com/PROJECT_ID/design/PAGE_ID/edit" })

// By ID (e.g., from /subframe:design)
get_page_info({ id: "PAGE_ID", projectId: "PROJECT_ID" })

// By name
get_page_info({ name: "Settings Page", projectId: "PROJECT_ID" })

// List all pages first if needed
list_pages({ projectId: "PROJECT_ID" })

Get the

projectId

from

.subframe/sync.json

// By URL
get_page_info({ url: "https://app.subframe.com/PROJECT_ID/design/PAGE_ID/edit" })

// By ID (e.g., from /subframe:design)
get_page_info({ id: "PAGE_ID", projectId: "PROJECT_ID" })

// By name
get_page_info({ name: "Settings Page", projectId: "PROJECT_ID" })

// List all pages first if needed
list_pages({ projectId: "PROJECT_ID" })

从

.subframe/sync.json

中获取

projectId

。

Syncing Components

同步组件

Sync components when they don't exist locally. You can sync specific components by name:

bash

npx @subframe/cli@latest sync Button Alert TextField

Or sync all components:

bash

npx @subframe/cli@latest sync --all

When to sync:

Components don't exist locally → Sync those specific components before implementing
Components already exist → Don't sync automatically. If the user wants the latest versions, they'll ask.

Never modify synced component files - they get overwritten. Create wrapper components if you need to add logic.

当组件在本地不存在时进行同步。你可以按名称同步特定组件：

bash

npx @subframe/cli@latest sync Button Alert TextField

或同步所有组件：

bash

npx @subframe/cli@latest sync --all

同步时机：

组件在本地不存在 → 在实现前同步这些特定组件
组件已存在 → 不要自动同步。如果用户需要最新版本，他们会提出要求。

请勿修改已同步的组件文件 - 这些文件会被覆盖。如果需要添加逻辑，请创建包装组件。

Sync Disable

禁用同步

If you must modify a synced component file directly, add

// @subframe/sync-disable

to the top of the file:

tsx

// @subframe/sync-disable
import * as React from "react"
// ... rest of component

This prevents the file from being overwritten on future syncs.

Updating a sync-disabled component:

If the user wants to update a component that has sync-disable, the sync command will skip it. To get the latest version:

Use
```
get_component_info
```
to fetch the latest code from Subframe
Manually merge the changes with the local modifications

如果你必须直接修改已同步的组件文件，请在文件顶部添加

// @subframe/sync-disable

：

tsx

// @subframe/sync-disable
import * as React from "react"
// ... rest of component

这将防止该文件在未来的同步中被覆盖。

更新已禁用同步的组件：

如果用户想要更新已禁用同步的组件，同步命令会跳过该组件。要获取最新版本：

使用
```
get_component_info
```
从Subframe获取最新代码
手动将更改与本地修改合并

Adding Business Logic

添加业务逻辑

Subframe generates presentational code with placeholder data. You add:

Data fetching:

tsx

const { data, isLoading, error } = useQuery(...)

if (isLoading) return <Skeleton />
if (error) return <Alert variant="error">{error.message}</Alert>

return <PageComponent {...data} />

Form handling:

tsx

const handleSubmit = async (e: FormEvent) => {
  e.preventDefault()
  await submitForm(formData)
}

Event handlers:

tsx

<Button onClick={handleClick}>Submit</Button>
<Card actionSlot={<IconButton onClick={handleDelete} />} />

Subframe生成的是带有占位数据的展示型代码。你需要添加以下内容：

数据获取：

tsx

const { data, isLoading, error } = useQuery(...)

if (isLoading) return <Skeleton />
if (error) return <Alert variant="error">{error.message}</Alert>

return <PageComponent {...data} />

表单处理：

tsx

const handleSubmit = async (e: FormEvent) => {
  e.preventDefault()
  await submitForm(formData)
}

事件处理：

tsx

<Button onClick={handleClick}>Submit</Button>
<Card actionSlot={<IconButton onClick={handleDelete} />} />

Updating Existing Pages

更新现有页面

When a design changes:

Fetch the updated design
Update layout/structure from new design
Preserve existing hooks, handlers, and state management
Sync any new components

When diffing the updated design against the existing code, if there are design changes beyond what the user asked you to design (e.g., layout tweaks, new elements, removed sections), call those out and ask whether to include them.

当设计稿发生变化时：

获取更新后的设计内容
根据新设计更新布局/结构
保留现有的钩子、处理器和状态管理逻辑
同步任何新增的组件

在对比更新后的设计稿与现有代码时，如果存在用户未要求的设计变更（例如布局调整、新增元素、移除部分），请指出这些变更并询问是否需要包含。

MCP Tools Reference

MCP 工具参考

Tool	Purpose	Key Parameters
`get_page_info`	Fetch page code	`url` , `id` , or `name` ; `projectId`
`get_component_info`	Fetch component code	`url` , `id` , or `name` ; `projectId`
`list_pages`	List all pages	`projectId`
`list_components`	List all components	`projectId`
`get_theme`	Get Tailwind config	`projectId` , `cssType`

工具	用途	关键参数
`get_page_info`	获取页面代码	`url` 、 `id` 或 `name` ； `projectId`
`get_component_info`	获取组件代码	`url` 、 `id` 或 `name` ； `projectId`
`list_pages`	列出所有页面	`projectId`
`list_components`	列出所有组件	`projectId`
`get_theme`	获取Tailwind配置	`projectId` 、 `cssType`