Figma Resources
使用 Figma 插件从 Kumo 定义生成 Figma 组件。
Kumo Figma 插件
Kumo Figma 插件直接从 Kumo 组件定义生成生产级的 Figma 组件。这让设计与代码保持同步 — Figma 中的组件与你代码中使用的 React 组件来自同一事实来源。
该插件读取 component-registry.json，生成带正确自动布局、语义颜色变量绑定和所有变体组合的 Figma 组件集（ComponentSet）。
本地开发环境搭建
按照以下步骤在任意 Figma 文件上本地构建和测试该插件。
1. 构建插件
从仓库根目录执行：
pnpm --filter @cloudflare/kumo-figma build这会生成主题数据、加载器数据和图标，然后将插件代码打包到 src/code.js。
2. 在 Figma 中导入插件
打开 Figma 桌面版（插件开发需要桌面应用，而不是网页版）。
- 在菜单栏中进入 Plugins
- 选择 Development → Import plugin from manifest…
- 在本地 kumo 仓库中定位到
packages/kumo-figma/src/manifest.json
3. 运行插件
导入成功后，插件会出现在你的开发插件列表中。
- 打开任意 Figma 文件（如果你有访问权限，也可以打开 Kumo 设计文件）
- 进入 Plugins → Development → Kumo UI Kit Generator
4. 使用插件界面
插件会打开一个面板，你可以选择要生成的组件。点击组件按钮即可生成对应的 Figma 版本。
注意： 要让组件正确绑定语义颜色变量，目标 Figma 文件必须包含
kumo-colors 变量集合。如果是在新文件中设置，请先运行令牌同步脚本。
环境变量
令牌同步脚本需要环境变量来使用 Figma API 鉴权并指定目标文件。
配置
- 从 Figma Settings → Personal Access Tokens 获取 Figma 个人访问令牌
- 复制环境变量模板：
cp packages/kumo-figma/scripts/.env.example packages/kumo-figma/scripts/.env- 在
.env中配置环境变量
必需变量
| Variable | Required | Description |
|---|---|---|
FIGMA_TOKEN | Yes | 用于 API 鉴权的 Figma 个人访问令牌 |
FIGMA_FILE_KEY | Yes | Figma URL 中的文件密钥：figma.com/file/{FILE_KEY}/... |
FIGMA_COLLECTION_NAME | No | Figma 中的变量集合名称。默认为 kumo-colors |
# packages/kumo-figma/scripts/.env
FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FIGMA_FILE_KEY=sKKZc6pC6W1TtzWBLxDGSU
FIGMA_COLLECTION_NAME=kumo-colors安全： 切勿把 Figma 令牌提交到仓库。.env 文件已被 gitignore 忽略。
令牌同步
在生成组件之前，先把 Kumo 的语义颜色令牌同步到 Figma。这会创建 kumo-colors 变量集合，组件绑定到这些变量以实现一致的主题。
运行令牌同步
pnpm --filter @cloudflare/kumo-figma figma:sync这会解析 theme-kumo.css 中的令牌，为两种模式解析 light-dark() 值，并通过 Variables API 推送到 Figma。
会生成什么
Kumo Figma 工作流会在你的目标 Figma 文件中生成两类输出：
1. Figma 变量（令牌同步）
令牌同步脚本会创建包含以下内容的 kumo-colors 变量集合：
- 颜色变量 — 所有语义化令牌，如
color-primary、color-surface、text-color-muted - 浅色和深色模式 — 每个变量都有两种配色方案下的取值
- 主题覆盖 — FedRAMP 等扩展模式及其特定的颜色覆盖
变量会出现在 Figma 的 Variables 面板中，可在整个设计文件中使用。切换模式时，所有绑定的颜色都会自动更新。
2. Figma 组件（插件）
插件会生成一个包含每个 Kumo 组件对应组件集（ComponentSet）的 “ui kit” 页面：
- 带变体的组件集 — 每个组件（Button、Badge、Input 等）都会成为一个包含其所有变体组合的 ComponentSet
- 变量绑定 — 填充、描边和文本颜色都绑定到
kumo-colors变量，而不是硬编码值 - 自动布局 — 组件使用与 CSS flexbox 行为一致的 Figma 自动布局
- 正确的尺寸 — 间距、内边距、圆角和字号与代码实现一致
当前生成的组件（30+）
Badge, Banner, Breadcrumbs, Button, Checkbox, ClipboardText, Code, CodeBlock, Collapsible, Combobox, CommandPalette, Dialog, Dropdown, Empty, Input, InputArea, Label, LayerCard, LinkButton, Loader, MenuBar, Meter, Pagination, Radio, RefreshButton, Select, SensitiveInput, Surface, Switch, Table, Tabs, Text, Toast, Tooltip
破坏性同步
插件采用破坏性同步 — 每次运行都会清除所有已生成的内容并重新创建。这确保 Figma 文件始终与代码库的当前状态一致。不要手动编辑生成的组件，你做的修改会在下次同步时被覆盖。
完整工作流
更新组件时的典型工作流：
# 1. Make changes to Kumo components
# ...edit packages/kumo/src/components/...
# 2. Regenerate component registry
pnpm --filter @cloudflare/kumo codegen:registry
# 3. Sync tokens to Figma (if colors changed)
pnpm --filter @cloudflare/kumo-figma figma:sync
# 4. Build the plugin
pnpm --filter @cloudflare/kumo-figma build
# 5. Run in Figma: Plugins > Development > Kumo UI Kit Generator
插件架构
| Directory | Purpose |
|---|---|
src/code.ts | 插件主入口，负责编排各生成器 |
src/ui.html | 插件界面（组件选择面板） |
src/generators/ | 30 多个组件生成器（badge.ts、button.ts 等） |
src/parsers/ | Tailwind 到 Figma 的转换器、注册表解析 |
scripts/ | 用于 Figma Variables API 的令牌同步脚本 |
添加新的组件生成器
当你向 Kumo 添加新组件时，请创建对应的 Figma 生成器：
- 创建
src/generators/yourcomponent.ts - 从
shared.ts导入共享工具 - 在
code.ts的GENERATORS数组中注册 - 运行
pnpm --filter @cloudflare/kumo-figma validate验证漂移检测通过
如果组件不需要在 Figma 中呈现（如工具类或纯布局组件），请把它添加到 drift-detection.test.ts 的 EXCLUDED_COMPONENTS 中。
故障排查
”kumo-colors collection not found”
目标 Figma 文件需要变量集合。请先运行令牌同步脚本：
pnpm --filter @cloudflare/kumo-figma figma:sync“Variable not found: color-primary”
变量名称必须与 kumo-colors 集合匹配。请检查 Figma 的 Variables 面板，确认令牌已正确同步。
“Font not found”
插件使用 Inter 字体，这是 Figma 的默认字体。请确保你的 Figma 字体中可用该字体。
插件未出现在菜单中
请确保你使用的是 Figma 桌面版（而非网页版），并从正确的路径导入清单：packages/kumo-figma/src/manifest.json
相关链接
- Colors — 语义颜色令牌参考
- Registry — 插件读取的组件注册表
- Contributing — 添加新组件和生成器