为 Figma 转代码工作流生成项目专属设计系统规则（需…

当团队要用 AI 编码代理把 Figma 设计稿实现成代码、并希望代理自动遵循项目既有的组件、样式与令牌约定时，生成并落地一份项目级设计系统规则文件。

适用场景

解决思路

1. 调用 Figma MCP server 的 create_design_system_rules 工具，传入 clientLanguages（逗号分隔的语言列表，如 "typescript,javascript"）和 clientFrameworks（如 "react"、"vue"、"svelte"、"angular"、"unknown"），拿到基础提示词与模板，并按其模板格式组织规则。
2. 分析代码库的组件组织：UI 组件放在哪里（如 src/components/、app/ui/、lib/components/）、是否有专门的设计系统目录、组件是按功能还是按类型组织。
3. 分析样式方案：使用哪种 CSS 框架或方式（Tailwind、CSS Modules、styled-components 等）、设计令牌定义在哪里（CSS 变量、主题文件、配置文件）、是否已有颜色/字体/间距令牌。
4. 分析组件模式：命名约定（PascalCase、kebab-case、前缀）、props 结构惯例、常见组合模式。
5. 分析架构决策：状态管理方式、路由系统、特定的 import 模式或路径别名。
6. 生成通用组件规则：优先复用 [YOUR_PATH] 下的组件、新 UI 组件放在 [COMPONENT_DIRECTORY]、遵循 [NAMING_CONVENTION] 命名、组件以 [EXPORT_PATTERN] 导出。
7. 生成样式规则：使用 [CSS_FRAMEWORK/APPROACH]、设计令牌位于 [TOKEN_LOCATION]、IMPORTANT 禁止硬编码颜色而必须用 [TOKEN_FILE] 中的令牌、间距使用 [SPACING_SYSTEM] 刻度、字体遵循 [TYPOGRAPHY_LOCATION] 定义的刻度。
8. 生成 Figma MCP 集成规则中的必需流程：先运行 get_design_context 获取目标节点的结构化表示；若响应过大或被截断，先运行 get_metadata 获取高层节点图，再用 get_design_context 只重新获取所需节点；运行 get_screenshot 获取该变体的视觉参考；只有在同时拿到 get_design_context 和 get_screenshot 之后，才下载所需资源并开始实现；把输出（通常是 React + Tailwind）翻译成本项目的约定、样式与框架；完成前对照 Figma 校验 1:1 的外观与行为。
9. 生成 Figma 实现规则：把 Figma MCP 输出（React + Tailwind）视为设计与行为的表示而非最终代码风格；在适用时用 [YOUR_STYLING_APPROACH] 替换 Tailwind 工具类；复用 [COMPONENT_PATH] 中的既有组件而非重复实现；一致使用项目的颜色系统、字体刻度和间距令牌；遵守既有的路由、状态管理与数据获取模式；力求与 Figma 设计 1:1 视觉一致；用 Figma 截图校验最终 UI 的外观与行为。
10. 生成资源处理规则：Figma MCP server 提供可返回图片和 SVG 的 assets endpoint；IMPORTANT 若返回 localhost 源则直接使用该源；IMPORTANT 不要引入或新增图标包，所有资源都应来自 Figma payload；IMPORTANT 若已提供 localhost 源则不要使用或创建占位符；下载的资源存放在 [ASSET_DIRECTORY]。
11. 补充项目专属约定：独特的架构模式、特殊的 import 要求、测试要求、无障碍标准、性能考量。
12. 检测用户使用的 AI 编码代理并把规则保存到对应文件：Claude Code 存到项目根目录 CLAUDE.md（也可用 .claude/rules/figma-design-system.md 做模块化组织）；Codex CLI 存到项目根目录 AGENTS.md（已存在则追加为新章节，总大小上限 32 KiB）；Cursor 存到 .cursor/rules/figma-design-system.mdc。若不确定代理类型，检查项目中已有的规则文件或询问用户。
13. 为 Cursor 的规则包裹 YAML frontmatter（description、globs、alwaysApply），并把 globs 定制为项目中 Figma 派生代码所在目录（如 "src/**/*.tsx" 或 ["src/components/**", "src/pages/**"]）。
14. 保存后验证与迭代：用一个简单的 Figma 组件实现做测试、确认代理正确遵循规则、修正不生效的规则、收集团队反馈、随项目演进更新规则。
15. 编写必备规则：组件发现（UI 组件在 src/components/ui/、功能组件在 src/components/features/、布局原语在 src/components/layout/）、设计令牌使用（颜色定义在 src/styles/tokens.css 的 CSS 变量中，禁止硬编码 hex，使用 var(--color-*) 令牌，间距用 4px 基准刻度 --space-1/--space-2 等）、样式方案（用 Tailwind 工具类，自定义样式放组件级 CSS modules，主题定制在 tailwind.config.js）。
16. 编写推荐规则：组件模式（所有组件接受 className prop 以便组合、variant prop 用联合类型如 'primary' | 'secondary'、图标组件接受 size 和 color prop）、import 约定（使用路径别名 @/components、@/styles、@/utils，按 React、第三方、内部、类型分组，不使用超出父目录的相对导入）、代码质量（导出的组件加 JSDoc 注释、为所有 props 提供 PropTypes 或 TypeScript 类型、把魔法数字提取为具名常量）。
17. 按需编写可选规则：无障碍（交互元素必须有 aria-label、颜色对比度满足 WCAG AA、所有交互支持键盘导航）、性能（用 @/components/Image 懒加载图片、对接收复杂 props 的组件使用 React.memo、图标用 SVG 组件而非图标字体）、测试（新组件在 __tests__/ 目录加单元测试、使用 Testing Library 查询如 getByRole/getByLabelText、测试所有交互状态与变体）。
18. 遵循最佳实践：从最重要的约定开始、逐步迭代而非一次写全；规则要具体（写“始终使用 src/components/ui/Button.tsx 的 Button 组件并传 variant prop ('primary' | 'secondary' | 'ghost')”而不是“使用设计系统”）；规则要可执行（写“颜色定义在 src/theme/colors.ts，导入并使用这些常量”而不是“不要硬编码颜色”）；对绝不能违反的规则加 "IMPORTANT:" 前缀；对看似随意的规则说明原因（如“所有数据获取放在 server components 以减少客户端包体积”“使用 @/ 绝对导入便于重构并避免相对路径断裂”）。
19. 遇到问题时按对应方案处理：代理不遵守规则时，把规则写得更具体可执行、确认保存在正确的配置文件、重启代理或 IDE 重新加载、给关键规则加 "IMPORTANT:" 前缀；规则互相冲突时，审查所有规则、建立明确优先级、删除冗余规则、把相关规则合并为单一清晰表述；规则过多导致延迟时，聚焦解决 80% 一致性问题的 20% 规则、删除极少适用的过细规则、合并相关规则、用渐进式披露（基础规则在前，进阶规则放链接文件）；规则随项目演进而过时时，安排定期审查（每月或每季度）、架构决策变更时更新规则、把规则文件纳入版本控制、在 commit message 中记录规则变更。

适用边界 · 注意事项

• 未连接或无法访问 Figma MCP server 时（该技能依赖 create_design_system_rules 等 MCP 工具）。
• 项目不使用 Figma 设计稿、也不存在 Figma 转代码工作流时。
• 无法访问项目代码库进行分析、或团队尚未形成（也不愿建立）任何组件约定时。