figma-to-design-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Initialize Design System

初始化设计系统

You are initializing the design-to-code workflow for this project. Your job is to deeply understand the existing codebase's design patterns and produce a

design-tokens.json

file at the project root.

你正在为这个项目初始化设计转代码工作流。你的任务是深入理解现有代码库的设计模式，并在项目根目录生成

design-tokens.json

文件。

Pre-check: Incremental Update

预检：增量更新

Before scanning, check if

design-tokens.json

already exists at the project root.

If it does not exist: proceed with a full scan (Steps 1-7).
If it does exist: read it into context. Then run a targeted scan:
1. Check if the styling approach or config file has changed. If yes, re-extract tokens (Step 2).
2. Scan only for new, modified, or deleted components and hooks since the file was last generated (compare file paths in the existing JSON against what's on disk).
3. Merge changes into the existing
```
design-tokens.json
```
  — add new entries, update changed entries, remove entries for deleted files.
4. Skip Steps 6-7's Playwright install if already installed.

This avoids re-reading the entire codebase when only a few components have changed.

在扫描前，检查项目根目录是否已存在

design-tokens.json

。

如果不存在：执行全量扫描（步骤1-7）。
如果存在：将其读入上下文，然后执行定向扫描：
1. 检查样式方案或配置文件是否发生变化。如果是，重新提取tokens（步骤2）。
2. 仅扫描自上次生成该文件以来新增、修改或删除的组件和hooks（将现有JSON中的文件路径与磁盘上的文件做对比）。
3. 将变更合并到现有
```
design-tokens.json
```
  中——新增条目、更新变更条目、移除已删除文件对应的条目。
4. 如果Playwright已安装，跳过步骤6的Playwright安装流程。

这样可以避免仅少数组件变更时重新读取整个代码库。

Step 1: Identify the Styling Approach

步骤1：识别样式方案

Scan the project for how styles are written. Look for:

```
tailwind.config.ts
```
or
```
tailwind.config.js
```
→ Tailwind CSS
```
*.module.css
```
or
```
*.module.scss
```
files → CSS/SCSS Modules

styled-components

@emotion/styled

, or

@emotion/css

package.json

→ CSS-in-JS

```
.css
```
files imported directly into components → Vanilla CSS
A combination of the above

Record the primary styling approach. If mixed, note the dominant one and secondary ones.

扫描项目确认样式编写方式。查找以下特征：

```
tailwind.config.ts
```
或
```
tailwind.config.js
```
→ Tailwind CSS
```
*.module.css
```
或
```
*.module.scss
```
文件 → CSS/SCSS Modules

package.json

中存在

styled-components

、

@emotion/styled

或

@emotion/css

→ CSS-in-JS

组件中直接导入
```
.css
```
文件 → Vanilla CSS
以上多种方案混合使用

记录主要样式方案。如果是混合方案，标注占主导的方案和次要方案。

Step 2: Extract Design Tokens

步骤2：提取Design Tokens

Based on the styling approach, extract tokens from the appropriate source:

If Tailwind: Read

tailwind.config.ts/js

and extract the

theme

extend

values — colors, spacing, fontFamily, fontSize, borderRadius, boxShadow, screens (breakpoints).

If CSS Variables: Search for

:root

[data-theme]

blocks in CSS files. Extract all custom properties.

If CSS-in-JS / Theme file: Look for theme objects (commonly in

theme.ts

styles/theme.ts

lib/theme.ts

, or similar). Extract the token values.

If Vanilla CSS: Scan the most-used CSS files for recurring values. Group them as tokens even if they aren't formally defined as such.

For all approaches, extract:

Colors: primary, secondary, background, surface, text, border, error, success, warning, info — and any other semantic color names used
Spacing: the scale or common spacing values used
Typography: font families, size scale, weight scale, line heights
Breakpoints: responsive breakpoints
Shadows: box-shadow values
Borders: border-radius values, border widths

基于识别到的样式方案，从对应来源提取tokens：

如果是Tailwind： 读取

tailwind.config.ts/js

，提取

theme

extend

下的配置值——颜色、间距、fontFamily、fontSize、borderRadius、boxShadow、screens（断点）。

如果是CSS Variables： 搜索CSS文件中的

:root

或

[data-theme]

块，提取所有自定义属性。

如果是CSS-in-JS/主题文件： 查找主题对象（通常位于

theme.ts

、

styles/theme.ts

、

lib/theme.ts

或类似路径），提取token值。

如果是Vanilla CSS： 扫描使用最频繁的CSS文件，提取重复出现的数值。即便这些值没有被正式定义为token，也将它们归类为tokens。

针对所有样式方案，都需要提取：

颜色： 主色、辅助色、背景色、表面色、文本色、边框色、错误色、成功色、警告色、信息色——以及项目中使用的其他语义化颜色名称
间距： 项目使用的间距体系或通用间距值
排版： 字体族、字号体系、字重体系、行高
断点： 响应式断点
阴影： box-shadow值
边框： border-radius值、边框宽度

Step 3: Discover Reusable Components

步骤3：发现可复用组件

Scan the project for existing UI components. Common locations:

src/components/

src/components/ui/

components/

app/components/

Any barrel export files (
```
index.ts
```
) that re-export components

For each component found, record:

name: The component name
path: File path relative to project root
description: What it does, written in plain English. Read the component code to understand it — don't just guess from the name.
props: The props it accepts (read from TypeScript types, PropTypes, or the JSX usage)

Prioritize components that are clearly meant for reuse:

UI primitives (Button, Input, Select, Checkbox, Radio, Toggle, Textarea)
Layout components (Container, Grid, Stack, Sidebar, PageLayout)
Feedback components (Alert, Toast, Modal, Dialog, Tooltip, Popover)
Data display (Card, Table, Badge, Avatar, Tag, List)
Navigation (Navbar, Tabs, Breadcrumbs, Pagination, MobileNav)

Skip page-specific components that are not reusable.

扫描项目中现有的UI组件。常见位置包括：

src/components/

、

src/components/ui/

、

components/

、

app/components/

任何重新导出组件的桶导出文件（
```
index.ts
```
）

对每个找到的组件，记录：

name： 组件名称
path： 相对于项目根目录的文件路径
description： 组件功能的英文简明描述。阅读组件代码理解其功能，不要仅通过名称猜测。
props： 组件接受的属性（从TypeScript类型、PropTypes或JSX使用方式中读取）

优先收录明确可复用的组件：

UI基础组件（Button、Input、Select、Checkbox、Radio、Toggle、Textarea）
布局组件（Container、Grid、Stack、Sidebar、PageLayout）
反馈组件（Alert、Toast、Modal、Dialog、Tooltip、Popover）
数据展示组件（Card、Table、Badge、Avatar、Tag、List）
导航组件（Navbar、Tabs、Breadcrumbs、Pagination、MobileNav）

跳过页面专属、不可复用的组件。

Step 4: Discover Shared Hooks and Utilities

步骤4：发现共享Hooks和工具函数

Look for custom hooks relevant to UI development:

```
useMediaQuery
```
,
```
useBreakpoint
```
→ responsive behavior
```
useDebounce
```
,
```
useThrottle
```
→ input handling
```
useClickOutside
```
→ dropdowns, modals
```
useForm
```
,
```
useFormField
```
→ form state
Any data fetching hooks

Record these in a

hooks

section with name, path, and description.

查找与UI开发相关的自定义hooks：

```
useMediaQuery
```
、
```
useBreakpoint
```
→ 响应式行为
```
useDebounce
```
、
```
useThrottle
```
→ 输入处理
```
useClickOutside
```
→ 下拉菜单、弹窗
```
useForm
```
、
```
useFormField
```
→ 表单状态
任何数据请求hooks

将这些信息记录在

hooks

字段下，包含名称、路径和描述。

Step 5: Generate design-tokens.json

步骤5：生成design-tokens.json

Write the file to the project root as

design-tokens.json

. Structure:

json

{
  "styling_approach": "<tailwind | css-modules | css-in-js | vanilla-css | mixed>",
  "styling_config_path": "<path to tailwind config, theme file, or primary CSS file>",
  "colors": { },
  "spacing": { },
  "typography": { },
  "breakpoints": { },
  "shadows": { },
  "borders": { },
  "components": [
    {
      "name": "ComponentName",
      "path": "src/components/ui/ComponentName.tsx",
      "description": "What it does in plain English",
      "props": ["variant", "size", "children"]
    }
  ],
  "hooks": [
    {
      "name": "useHookName",
      "path": "src/hooks/useHookName.ts",
      "description": "What it does"
    }
  ]
}

将文件写入项目根目录，命名为

design-tokens.json

。结构如下：

json

{
  "styling_approach": "<tailwind | css-modules | css-in-js | vanilla-css | mixed>",
  "styling_config_path": "<path to tailwind config, theme file, or primary CSS file>",
  "colors": { },
  "spacing": { },
  "typography": { },
  "breakpoints": { },
  "shadows": { },
  "borders": { },
  "components": [
    {
      "name": "ComponentName",
      "path": "src/components/ui/ComponentName.tsx",
      "description": "What it does in plain English",
      "props": ["variant", "size", "children"]
    }
  ],
  "hooks": [
    {
      "name": "useHookName",
      "path": "src/hooks/useHookName.ts",
      "description": "What it does"
    }
  ]
}

Step 6: Check Playwright

步骤6：检查Playwright

Ensure Playwright is installed globally and ready for the visual verification workflow:

Run
```
npx playwright --version
```
to check if Playwright is available.

If not installed, run

npm install -g playwright

and then

npx playwright install chromium

If already installed, skip this step.

确保Playwright已全局安装，可用于视觉验证工作流：

运行
```
npx playwright --version
```
检查Playwright是否可用。

如果未安装，运行

npm install -g playwright

，然后运行

npx playwright install chromium

。

如果已安装，跳过本步骤。

Step 7: Verify and Confirm

步骤7：验证与确认

After generating the file:

Show the user a summary: styling approach detected, number of colors/tokens, components discovered, hooks found
Ask if anything looks wrong or missing
If they correct something, update the file
Confirm initialization is complete and they can now use
```
/figma-to-design-build
```

生成文件后：

向用户展示摘要：检测到的样式方案、颜色/token数量、发现的组件数量、找到的hooks数量
询问是否有错误或遗漏
如果用户提出修正，更新文件
确认初始化完成，用户现在可以使用
```
/figma-to-design-build
```
命令

Important Rules

重要规则

Do NOT invent tokens that don't exist in the codebase. Only record what's actually there.
If the project is new with almost no tokens or components, say so. A sparse file is fine.
If you find inconsistencies (e.g., 5 different grays with no naming convention), note them but record as-is. Don't "clean up" the design system — that's the user's job.

不要编造代码库中不存在的tokens。仅记录实际存在的内容。
如果是新项目，几乎没有tokens或组件，直接说明即可。内容稀疏的文件是可以接受的。
如果发现不一致问题（例如存在5种没有命名规范的灰色），标注问题但按原样记录。不要“清理”设计系统——这是用户的工作。