pixel-perfect-ui

像素级精准的 UI 实现

自主工作流：将 Figma 设计转换为可用于生产环境、像素级精准的 React/Next.js 实现，并进行视觉验证。

🚀 自动触发条件

用户提出以下任意请求时，必须自动调用此技能：

• “实现这个 Figma 设计”
• “根据 Figma 构建这个页面/组件”
• “根据 Figma 创建”
• “实现这个设计”
• “构建这个区块/版块”
• “创建与设计匹配的组件”
• 任何涉及 Figma URL 或节点 ID 的请求
• 任何根据设计实现页面、区块或组件的请求

前置条件

• 已连接 Figma MCP 服务（用于提取设计）
• 已连接 Playwright MCP 服务（用于视觉验证）
• 已初始化 Next.js 或 React 项目

---

📋 阶段 0：创建必需清单（始终首先执行）

重要：在进行任何实现之前，必须：

步骤 0.1：分析设计并识别版块

首先，从 Figma 获取完整页面/组件并识别所有版块：

mcp0_get_design_context --nodeId <page-node-id>
mcp0_get_metadata --nodeId <page-node-id>

列出设计中的所有版块/区块（例如：页眉、首屏、功能、行动号召、页脚）。

步骤 0.2：创建实现清单文件

在 .windsurf/implementation-checklist.md 创建 Markdown 清单文件：

# Implementation Checklist: [Component/Page Name]

**Created**: [Date]
**Figma Source**: [URL or Node ID]
**Target Path**: [e.g., src/app/page.tsx or src/components/MyComponent.tsx]
**Status**: 🟡 Pending Approval

---

## 📋 Sections to Implement

[List each section identified from Figma]

1. **Section Name 1** (node-id: xxx)
2. **Section Name 2** (node-id: xxx)
3. **Section Name 3** (node-id: xxx)
...

---

## 🔄 SECTION-BY-SECTION IMPLEMENTATION

> ⚠️ **CRITICAL RULE**: For EACH section below:
> 1. First EXTRACT fresh Figma data for that specific section
> 2. Then IMPLEMENT based on that fresh extraction
> 3. Mark section complete
> 4. Move to next section
> 
> **NEVER rely on old/cached Figma data. Always re-extract before implementing!**

---

### Section 1: [Section Name]
**Node ID**: [figma-node-id]
**Status**: ⬜ Not Started

#### 1.1 Extract from Figma
- [ ] mcp0_get_design_context for this section
- [ ] mcp0_get_screenshot for visual reference
- [ ] Export any images/assets needed
- [ ] Note typography, colors, spacing

#### 1.2 Implement
- [ ] Create/update component structure
- [ ] Implement desktop layout (1440px)
- [ ] Implement tablet layout (768px)
- [ ] Implement mobile layout (375px)
- [ ] Add images with Next.js Image
- [ ] Apply styles (typography, colors, spacing)

#### 1.3 Validate
- [ ] Visual check matches Figma
- [ ] Responsive on all viewports
- [ ] No horizontal scroll

✅ **Section 1 Complete**: [ ]

---

### Section 2: [Section Name]
**Node ID**: [figma-node-id]
**Status**: ⬜ Not Started

#### 2.1 Extract from Figma
- [ ] mcp0_get_design_context for this section
- [ ] mcp0_get_screenshot for visual reference
- [ ] Export any images/assets needed
- [ ] Note typography, colors, spacing

#### 2.2 Implement
- [ ] Create/update component structure
- [ ] Implement desktop layout (1440px)
- [ ] Implement tablet layout (768px)
- [ ] Implement mobile layout (375px)
- [ ] Add images with Next.js Image
- [ ] Apply styles (typography, colors, spacing)

#### 2.3 Validate
- [ ] Visual check matches Figma
- [ ] Responsive on all viewports
- [ ] No horizontal scroll

✅ **Section 2 Complete**: [ ]

---

[Repeat for each section...]

---

## 🏁 Final Validation

- [ ] All sections implemented
- [ ] Full page visual comparison
- [ ] Resource validation passed (no broken links/images)
- [ ] Production checklist complete

---

## 📝 Notes

[Add any specific notes here]

---

## ✅ Completion Summary

**Completed**: [Date when finished]
**Final Status**: [Pending/Complete]

步骤 0.3：向用户展示计划

创建清单后，始终：

1. 在聊天中向用户展示计划（列出所有已识别的版块）
2. 请求确认：“我已在 .windsurf/implementation-checklist.md 创建包含 X 个版块的实现清单。是否继续？”
3. 在继续之前等待用户批准

步骤 0.4：逐个版块执行

对于每个版块（按顺序）：

┌─────────────────────────────────────────────────────┐
│  SECTION WORKFLOW (repeat for each section)         │
├─────────────────────────────────────────────────────┤
│  1. 📥 EXTRACT: Get fresh Figma data for section    │
│     - mcp0_get_design_context --nodeId <section-id> │
│     - mcp0_get_screenshot --nodeId <section-id>     │
│     - Export images if needed                       │
│                                                     │
│  2. 🔨 IMPLEMENT: Build based on fresh extraction   │
│     - Use the data you JUST extracted               │
│     - Do NOT use old/cached data                    │
│     - Implement responsive (desktop→tablet→mobile)  │
│                                                     │
│  3. ✅ VALIDATE: Check section matches Figma        │
│                                                     │
│  4. 📝 UPDATE CHECKLIST: Mark items [x] complete    │
│                                                     │
│  5. ➡️ MOVE TO NEXT SECTION                         │
└─────────────────────────────────────────────────────┘

重要：

• 不要一次性批量提取所有版块
• 不要凭记忆或旧数据进行实现
• 在实现每个版块之前，始终立即重新提取 Figma 数据
• 完成每个版块后更新清单

步骤 0.5：跟踪进度

完成每个版块后：

1. 更新清单文件——将已完成项目的 - [ ] 改为 - [x]
2. 更新版块状态：⬜ 尚未开始 → 🔵 进行中 → ✅ 已完成
3. 更新整体 Status 字段：
   • 🟡 等待批准
   • 🔵 进行中 - 第 X/Y 个版块
   • 🟢 已完成
   • 🔴 已阻塞（附原因）

---

🚨 重要的生产规则

移动端优先的响应式设计（必须遵守）

• 绝不要使用硬编码的像素宽度（例如，w-[1728px]、width: 1728px）
• 始终使用响应式单位：max-w-7xl、百分比或视口单位
• 始终在移动端视口中测试（375px、768px、1024px、1440px）
• 不得出现水平滚动——必要时在 body 上使用 overflow-x-hidden
• 容器模式：使用 max-w-[size] mx-auto px-4 sm:px-6 lg:px-8

图像要求（必须遵守）

• 从 Figma 导出所有图像——绝不要使用占位路径
• 引用前检查图像是否存在
• 使用 Next.js Image 组件并设置适当尺寸
• 为缺失的图像提供回退方案
• 优化图像——优先使用 WebP 格式

生产检查清单（必须完成）

• 已测试所有视口（移动端、平板、桌面端）
• 所有设备上均无水平滚动
• 所有图像均已导出且可访问
• 移动端触控目标至少为 44x44px
• 无需缩放即可阅读文本
• 交互元素具有悬停/焦点状态
• 已实现加载状态
• 已添加错误边界
• 资源验证已通过（无失效链接/图像）

核心工作流

⚠️ 提醒：开始以下步骤之前，务必先完成阶段 0（创建清单）！

1. 提取设计

从 Figma 提取全面的设计数据：

# Get design context and code
mcp0_get_design_context --nodeId <node-id>
mcp0_get_variable_defs --nodeId <node-id>
mcp0_get_screenshot --nodeId <node-id>

解析提取的数据，包括：

• 字体排版（font-family、大小、粗细、行高、字间距）
• 颜色（十六进制值、不透明度）
• 间距（内边距、外边距、间隔）
• 布局（flexbox/grid 属性、对齐方式）
• 边框、阴影、圆角值
• 资源 URL 和 SVG 导出内容

2. 项目分析

检测项目配置：

• 框架：Next.js App Router 还是 Pages Router
• 样式：Tailwind、CSS Modules、styled-components
• 组件库：shadcn/ui、MUI、Radix
• 设计令牌位置：tailwind.config、theme.ts

将 Figma 令牌映射到项目现有令牌。

3. 实现

使用提取的值生成组件：

// For complex layouts, use references/layout-patterns.md
// For component patterns, use references/component-patterns.md
// For responsive patterns, use references/responsive-patterns.md

严格的实现规则：

• ❌ 禁止：硬编码宽度，例如 w-[1728px]、width: 1728px
• ✅ 必须：使用响应式容器 max-w-7xl mx-auto px-4
• ✅ 必须：采用移动端优先的断点 sm:、md:、lg:、xl:
• ✅ 必须：从 Figma 导出并验证所有图片
• ✅ 必须：使用 Flexbox/Grid 实现灵活布局
• ✅ 必须：在 375px、768px、1024px、1440px 视口下进行测试

图片处理：

// 1. Export from Figma
mcp0_get_screenshot --nodeId <id> --filename "hero-image.png"

// 2. Save to public/assets/
// 3. Use with Next Image
<Image src="/assets/hero-image.png" alt="..." width={...} height={...} />

4. 多设备验证循环

必须：在所有视口下运行验证：

# Desktop validation
python scripts/visual-compare.py --viewport 1440x900

# Tablet validation  
python scripts/visual-compare.py --viewport 768x1024

# Mobile validation (CRITICAL)
python scripts/visual-compare.py --viewport 375x667

# Responsive issues check
python scripts/responsive-validation.py --url <url>

# Resource validation (CRITICAL - Run before deployment)
python scripts/resource-validator.py --directory src/app --strict

验证要求：

• ✅ 所有视口均无水平滚动
• ✅ 所有图片均能正确加载（通过 resource-validator.py 验证）
• ✅ 没有损坏的链接或缺失的资源
• ✅ 没有占位内容（lorem ipsum、临时图片）
• ✅ 移动端触控目标 ≥ 44x44px
• ✅ 无需缩放即可清晰阅读文字
• ✅ 移动端正确堆叠（没有重叠）
• ✅ 交互元素可访问

需要修复的常见问题：

• ❌ 硬编码宽度导致溢出
• ❌ 图片缺失或损坏（由 resource-validator.py 检测）
• ❌ 内部或外部链接失效
• ❌ 占位内容（lorem ipsum、临时图片）
• ❌ 外部依赖项未缓存在本地
• ❌ 移动端文字过小（<14px）
• ❌ 小屏幕上的元素相互重叠
• ❌ 固定定位在移动端显示异常

5. 响应式实现

从 Figma 中提取不同断点下的变化：

• 桌面端（1440px）
• 平板（768px）
• 移动端（375px）

使用项目的断点系统应用响应式规则。

快速命令

完整页面实现：

python scripts/extract-and-implement.py --figma-url <url> --output-path <path>

组件提取：

python scripts/extract-component.py --node-id <id> --component-name <name>

视觉验证：

python scripts/visual-compare.py --implementation-url <url> --figma-node <id>

资源验证（损坏的链接、缺失的图片）：

# Validate single file
python scripts/resource-validator.py --file src/app/page.tsx

# Validate entire app (REQUIRED before production)
python scripts/resource-validator.py --directory src/app --strict --report validation-report.txt

文件组织

• 页面：遵循项目的路由约定
  • App Router：app/[route]/page.tsx
  • Pages Router：pages/[route].tsx
• 组件：components/ui/[component].tsx
• 资源：public/assets/ 或 src/assets/
• 样式：与组件放在同一目录，或放在 styles/ 中

令牌映射

请参阅 references/token-mapping.md，了解：

• Figma → Tailwind 映射
• Figma → CSS 变量映射
• 阴影和渐变转换
• 字体排版比例映射

组件模式

请参阅 references/component-patterns.md，了解：

• 卡片布局
• 导航模式
• 表单组件
• 模态框实现
• 网格系统

验证阈值

可接受的差异：

• 字体字距：±2px
• 行高：±1px
• 抗锯齿差异

必须完全匹配：

• 颜色（十六进制值）
• 圆角
• 间距值
• 组件尺寸
• 阴影属性