Figma / Pencil 到 FSD + Tailwind 4

将设计文件转换为代码，且不破坏宿主仓库的架构、设计系统或可访问性保障。本能力与框架无关；以下规则适用于任何现代 React 技术栈，并在可选组件（RSC、基础组件库、FSD 检查器）缺失时优雅降级。

前提假设

本能力适用于满足以下全部条件的任意前端仓库：

• 现代基于组件的框架（React，或具备类似组件模型的任意框架）。
• Tailwind CSS。Token 规则面向 v4（CSS 优先、@theme、OKLCH）。对于 v3 项目，请回退至项目现有配置，并跳过仅适用于 v4 的章节。
• Feature-Sliced Design（或类似的分层架构）。各层名称可能因仓库而异；标准命名如下：app、pages、widgets、features、entities、shared。
• 基础组件库为可选项。若项目已采用（如 shadcn/ui、Radix、Mantine、Headless UI 或任意内部设计系统），应复用而非重复实现基础组件。
• 服务端/客户端组件划分亦为可选项。RSC 相关指引仅在项目所用框架明确区分 Server/Client 组件时适用。

若任一前提不成立，请优先遵循宿主仓库约定。

工作流

1. 生成代码前，先检查仓库约定。参见 references/project-contracts.md。本地规则覆盖本能力中所有默认设定。
2. 限定工作范围为单个 Frame、单个屏幕或单个组件。拒绝“翻译整个文件”类请求。
3. 分析设计：Token、组件、布局意图、重复模式、状态。
4. 编码前，先在纸上完成 FSD 分层拆解。仅当宿主框架支持 Server/Client 划分时，才确定其边界。参见 references/fsd-mapping.md 和 references/rsc-boundaries.md。
5. 将设计变量与项目 Token 进行对齐。禁止静默新增 Token。参见 references/tailwind-tokens.md。
6. 优先复用项目组件库中的已有基础组件，再考虑在 shared/ui 中新建。
7. 按层生成代码：从 shared 基础组件 → entities → features → widgets → pages → app-shell（若存在）→ app。路由入口保持精简。
8. 实现设计中展示的所有状态，以及标准状态：default、hover、focus-visible、active、disabled、loading、empty、error。
9. 依据 references/accessibility-checklist.md 验证可访问性。
10. 提交任务完成前，须执行下方验证清单。

分层映射（摘要）

详细规则见 references/fsd-mapping.md。

• shared — 基础组件、Token、工具函数、格式化器、API 客户端、Hook、类型定义。
• entities — 领域模型及小型领域 UI。
• features — 用户操作与交互流程。
• widgets — 跨页面复用的大型组合区块。
• pages — 仅负责页面级组合。
• app-shell（可选）— 包裹多个页面的持久化布局框架（公开或认证后）。
• app — 路由入口点、Provider、全局样式。

当某组件可归属多个层级时，选择最高复用层级，且不得违反导入方向约束。

服务端 vs 客户端（如适用）

若宿主框架无 Server/Client 组件划分，请完全跳过本节。详细规则见 references/rsc-boundaries.md。

• 默认使用服务端组件（Server Component）。
• 仅当组件需使用 state、refs、effects、事件处理器或仅限浏览器的 API 时，才标记为客户端专属（client-only）。
• 将客户端标记（client marker）置于尽可能小的叶子节点上，切勿应用于整页或 Shell 层。
• 数据获取应放在服务端（页面级 fetch、server actions），只要服务端 fetch 可行，就不得在客户端 effect 中执行。

设计分析规则

• 识别哪些元素是重复出现的、全局通用的，或仅限于特定页面。
• 将每个设计变量映射至一个已存在的语义化 Token。发现不匹配时需标记并交由设计评审——禁止自行创建新 Token。
• 尊重源设计中的自动布局、命名规范和组件复用逻辑。
• 优先采用最小且准确的作用域：选定的 Frame、选定的屏幕或选定的组件。
• 在完成设计拆解（Token、区块、分层、以及（如适用）Server/Client 边界）前，禁止生成代码。
• 面对非平凡设计时，应在编码前输出一份简明的实现计划。

Figma 流程

详细规则见 references/figma-mcp-workflow.md。

• 优先使用 MCP 提取的上下文：变量、组件、布局、选中节点树、本地资源。
• 如有可用，应复用项目已有组件及 Code Connect 映射关系。
• 直接使用 MCP payload 中提供的本地资源 URL。真实资源存在时，禁止虚构占位符。
• 将自动布局（Auto Layout）翻译为 Flexbox 工具类，而非绝对定位。

Pencil 流程

详细规则见 references/pencil-workflow.md。相比 Figma MCP，该路径尚属实验性。

• 将 .pen 文件与代码置于同一工作区，并在作为事实来源（source of truth）时纳入版本控制。
• 优先复用 Pencil 中已有的变量与组件，避免凭空定义新值。
• 依据结构化计划生成代码，再逐步重构至 FSD 各层。禁止直接提交单组件快照（single-component dumps）。

Tailwind 4 规则

详细规则见 references/tailwind-tokens.md。

• Token 统一定义于单一全局样式表内，位于 @theme { ... } 块中。v4 项目中禁止使用 JS 端的 theme.extend。
• 颜色、间距、圆角、排版、阴影等均须使用语义化 Token。每个填充类 Token 必须配对对应 *-foreground Token。
• 每种语义含义必须严格对应唯一 Token。禁止出现 primary-2、surface-alt 等歧义命名。
• 未经设计系统明确批准，禁止新增 Token。临时性需求请使用任意值（如 bg-[oklch(...)]），并添加 TODO(design) 注释。
• 明暗主题共用 Token 名称；通过 .dark 选择器（或项目指定的暗色变体）覆盖具体值。
• style={{ ... }} 内联样式仅允许用于作者期无法预知的值（如动态位置、滚动驱动值、动画值）。静态样式一律通过工具类实现。
• 除非项目约定强制要求，否则不得引入自定义 CSS 文件。

可访问性规则

详细规则见 references/accessibility-checklist.md。所有设计转代码任务均强制执行。

• 优先使用原生语义化 HTML： 表示操作， 表示导航，
  配合 label 使用。
• 每个可交互元素均可通过键盘聚焦，并显示可见的 focus-visible 环。
• 纯图标按钮须携带 aria-label；图片须携带 alt 属性。
• 正文文本在明/暗主题下对比度均不得低于 4.5:1。
• 复合型组件（dialog、menu、tabs、combobox）必须来自经充分测试的基础组件库，禁止手写 ARIA 实现。