Figma 资源
@cloudflare/kumo

Figma 资源

通过 Kumo Figma 插件在 Figma 中使用 Kumo 组件。

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 桌面版 (插件开发需要桌面应用，而非网页版)。

  1. 在菜单栏中进入 Plugins
  2. 选择 Development → Import plugin from manifest…
  3. 在本地 kumo 仓库中定位到 packages/kumo-figma/src/manifest.json

3. 运行插件

导入后，插件会出现在你的开发插件列表中。

  1. 打开任意 Figma 文件 (如果有权限，也可以使用 Kumo 设计文件)
  2. 进入 Plugins → Development → Kumo UI Kit Generator

4. 使用插件界面

插件会打开一个面板，你可以在其中选择要生成哪些组件。点击组件按钮，即可生成对应的 Figma 等价物。

注意: 要让组件正确绑定到语义色变量，目标 Figma 文件必须包含 kumo-colors 变量集合。如果你正在配置一个新文件，请先运行令牌同步脚本。

环境变量

令牌同步脚本需要环境变量，以便通过 Figma API 认证并定位到正确的文件。

设置

  1. 从 Figma Settings → Personal Access Tokens 获取 Figma 个人访问令牌
  2. 复制环境模板：
cp packages/kumo-figma/scripts/.env.example packages/kumo-figma/scripts/.env
  1. 在 .env 中配置环境变量

必需变量

变量是否必需说明
FIGMA_TOKEN是你的 Figma 个人访问令牌，用于 API 认证
FIGMA_FILE_KEY是来自你 Figma URL 的文件 key:figma.com/file/{FILE_KEY}/...
FIGMA_COLLECTION_NAME否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 组件 (插件)

插件会生成一个 “ui kit” 页面，其中包含每个 Kumo 组件对应的 ComponentSet:

  • 带变体的 ComponentSet —— 每个组件 (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. 修改 Kumo 组件

# ...编辑 packages/kumo/src/components/...

# 2. 重新生成组件注册表

pnpm --filter @cloudflare/kumo codegen:registry

# 3. 将令牌同步到 Figma(如果颜色有改动)

pnpm --filter @cloudflare/kumo-figma figma:sync

# 4. 构建插件

pnpm --filter @cloudflare/kumo-figma build

# 5. 在 Figma 中运行:Plugins > Development > Kumo UI Kit Generator

插件架构

目录用途
src/code.ts插件主入口，调度各个生成器
src/ui.html插件 UI(组件选择面板)
src/generators/30+ 组件生成器 (badge.ts、button.ts 等)
src/parsers/Tailwind 到 Figma 的转换器、注册表解析
scripts/面向 Figma Variables API 的令牌同步脚本

添加新的组件生成器

当你为 Kumo 添加新组件时，创建对应的 Figma 生成器：

  1. 创建 src/generators/yourcomponent.ts
  2. 从 shared.ts 导入共享工具函数
  3. 在 code.ts 的 GENERATORS 数组中注册
  4. 运行 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 桌面版 (而非网页版),并且从正确路径导入了 manifest:packages/kumo-figma/src/manifest.json

相关内容

  • 颜色 —— 语义色令牌参考
  • 注册表 —— 插件读取的组件注册表
  • 贡献指南 —— 添加新的组件和生成器