用途:从组件契约生成 Figma 组件集。读取契约文件后,推导组件级(Tier 3)token,并在 Figma 中构建完全变量绑定的组件集。
前置条件:需先加载 figma-use(Plugin API 语法规则)、figma-generate-library(设计系统工作流);且 cc-figma-tokens 必须已运行,目标 Figma 文件中需存在 Primitives 与 Semantic 集合。调用 use_figma 时需传 skillNames: "cc-figma-component"。
主要能力与流程:
- 配置:读取项目根的 .component-contracts,使用 FIGMA_FILE_KEY 等;不得输出 FIGMA_ACCESS_TOKEN。
- 契约结构:读取 {CONTRACTS_DIR}/{id}.contract.json,涉及 tokens、props、a11y、platforms 等段。
- Tier 3 token 推导:按规则 --ds-{componentId}-{role}-{qualifier} 在运行时推导,并绑定到对应 Semantic 变量(如 brand.500 对应 brand/500);找不到变量则停止并报告。
- 组件集架构:主变体 prop 的每个值成为独立组件集,命名 {ComponentName}/{VariantValue};次要轴(Size、State)作为属性。
- 执行模式:默认快速模式顺序执行各阶段;debug mode 每阶段暂停等待确认。工作文件必须写入 scripts/ 子目录。
- 工作流阶段:Phase 0 发现(只读,检查集合与已有组件、推导 token、构建变体矩阵并展示计划);Phase 1 创建专用页面;Phase 2 构建基础组件(自动布局、创建后立即设 HUG),按 composition.slots 与 childOrder 添加子节点;Phase 3 变体矩阵,复制并重置 HUG,combineAsVariants 后手动网格布局并 resize;Phase 4 变量绑定;Phase 5 组件属性(TEXT label、BOOLEAN iconStart 等);Phase 6 画布注释(⚠️ Generation Notes 框架);Phase 7 最终校验。
限制与约束:
- 所有 frame 创建后须立即将水平与垂直 sizing 设为 HUG,唯一例外是槽位子项的 figma.sizing 明确为 "fixed"。
- 状态值需从契约的 states 数组读取,不得硬编码。
- disabled、loading 不作为 BOOLEAN 属性,仅作为变体状态。
- 除非文件中存在真实图标组件,否则不使用 INSTANCE_SWAP。
- fullWidth、iconOnly 定义为组件属性但不能自动驱动布局(已知限制)。
- 图标旋转、可见性等无法变量绑定。
- 资料未提供收费、价格或平台支持信息。
适用场景:已有组件契约、需要按设计系统规范批量生成 Figma 组件集并绑定 Semantic 变量的设计与开发工作流。