pixel-perfect-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pixel-Perfect UI Implementation

像素级精准UI实现

Autonomous workflow for converting Figma designs to production-ready, pixel-perfect React/Next.js implementations with visual validation.

用于将Figma设计转换为可投产、像素级精准的React/Next.js实现的自主工作流，自带视觉校验能力。

🚀 AUTO-TRIGGER CONDITIONS

🚀 自动触发条件

This skill MUST be invoked automatically when the user requests ANY of:

"implement this Figma design"
"build this page/component from Figma"
"create from Figma"
"implement the design"
"build this block/section"
"create component matching design"
Any request involving Figma URL or node ID
Any request to implement a page, block, or component from a design

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

"implement this Figma design"
"build this page/component from Figma"
"create from Figma"
"implement the design"
"build this block/section"
"create component matching design"
任何包含Figma URL或节点ID的请求
任何要求基于设计实现页面、区块或组件的请求

Prerequisites

前置要求

Figma MCP server connected (for design extraction)
Playwright MCP server connected (for visual validation)
Next.js or React project initialized

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

📋 PHASE 0: MANDATORY CHECKLIST CREATION (ALWAYS FIRST)

📋 第0阶段：强制创建检查清单（始终为第一步）

CRITICAL: Before ANY implementation, you MUST:

重要提示：在开始任何实现工作前，你必须：

Step 0.1: Analyze Design & Identify Sections

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

First, get the full page/component from Figma and identify ALL sections:

bash

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

List all sections/blocks in the design (e.g., Header, Hero, Features, CTA, Footer).

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

bash

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

列出设计中的所有模块/区块（例如：Header、Hero、Features、CTA、Footer）。

Step 0.2: Create Implementation Checklist File

步骤0.2：创建设计实现检查清单文件

Create a markdown checklist file at

.windsurf/implementation-checklist.md

markdown

undefined

在

.windsurf/implementation-checklist.md

路径下创建Markdown格式的检查清单文件：

markdown

undefined

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]

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

[List each section identified from Figma]

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

🔄 SECTION-BY-SECTION IMPLEMENTATION

⚠️ CRITICAL RULE: For EACH section below:

First EXTRACT fresh Figma data for that specific section

Then IMPLEMENT based on that fresh extraction

Mark section complete

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

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

1.3 Validate

Visual check matches Figma
Responsive on all viewports
No horizontal scroll

✅ Section 1 Complete: [ ]

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

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

2.3 Validate

Visual check matches Figma
Responsive on all viewports
No horizontal scroll

✅ Section 2 Complete: [ ]

[Repeat for each section...]

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

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]

undefined

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

undefined

Step 0.3: Present Plan to User

步骤0.3：向用户展示实现计划

After creating the checklist, ALWAYS:

Display the plan to the user in chat (show all identified sections)
Ask for confirmation: "I've created the implementation checklist at
```
.windsurf/implementation-checklist.md
```
with X sections. Should I proceed?"
WAIT for user approval before proceeding

创建完检查清单后，始终需要执行以下操作：

在聊天窗口向用户展示计划（列出所有识别到的模块）
请求用户确认："我已在
```
.windsurf/implementation-checklist.md
```
路径下创建了包含X个模块的实现检查清单，是否可以开始推进？"
等待用户批准后再继续后续操作

Step 0.4: Execute Section-by-Section

步骤0.4：逐个模块执行实现

FOR EACH SECTION (in order):

┌─────────────────────────────────────────────────────┐
│  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                         │
└─────────────────────────────────────────────────────┘

CRITICAL:

Do NOT batch extract all sections at once
Do NOT implement from memory or old data
ALWAYS re-extract Figma data immediately before implementing each section
Update checklist after completing each section

按顺序对每个模块执行以下操作：

┌─────────────────────────────────────────────────────┐
│  模块工作流（每个模块重复执行）                     │
├─────────────────────────────────────────────────────┤
│  1. 📥 提取：获取该模块的最新Figma数据              │
│     - mcp0_get_design_context --nodeId <section-id> │
│     - mcp0_get_screenshot --nodeId <section-id>     │
│     - 按需导出图片/资源                             │
│                                                     │
│  2. 🔨 实现：基于刚提取的最新数据构建内容            │
│     - 仅使用你刚提取的数据                          │
│     - 不要使用旧的/缓存的数据                       │
│     - 按桌面端→平板端→移动端的顺序实现响应式        │
│                                                     │
│  3. ✅ 校验：检查模块是否与Figma设计匹配             │
│                                                     │
│  4. 📝 更新检查清单：将已完成项标记为 [x]            │
│                                                     │
│  5. ➡️ 进入下一个模块                                │
└─────────────────────────────────────────────────────┘

重要提示：

不要一次性批量提取所有模块的数据
不要基于记忆或旧数据实现
每次实现单个模块前，务必重新提取该模块的Figma数据
完成每个模块后更新检查清单

Step 0.5: Track Progress

步骤0.5：进度追踪

As you complete each section:

Update the checklist file - Change
```
- [ ]
```
to
```
- [x]
```
for completed items
Update section status: ⬜ Not Started → 🔵 In Progress → ✅ Complete
Update overall Status field:
- 🟡 Pending Approval
- 🔵 In Progress - Section X of Y
- 🟢 Complete
- 🔴 Blocked (with reason)

每完成一个模块，执行以下操作：

更新检查清单文件 - 将已完成项的
```
- [ ]
```
改为
```
- [x]
```
更新模块状态：⬜ 未开始 → 🔵 进行中 → ✅ 已完成
更新整体状态字段：
- 🟡 待审批
- 🔵 进行中 - 第X个模块/共Y个模块
- 🟢 已完成
- 🔴 阻塞（标注阻塞原因）

🚨 CRITICAL PRODUCTION RULES

🚨 重要投产规则

Mobile-First Responsive Design (MANDATORY)

移动端优先响应式设计（强制要求）

NEVER use hardcoded pixel widths (e.g.,
```
w-[1728px]
```
,
```
width: 1728px
```
)
ALWAYS use responsive units:
```
max-w-7xl
```
, percentages, or viewport units
ALWAYS test on mobile viewports (375px, 768px, 1024px, 1440px)
NO horizontal scroll - Use
```
overflow-x-hidden
```
on body if needed

Container pattern: Use

max-w-[size] mx-auto px-4 sm:px-6 lg:px-8

绝对不要使用硬编码的像素宽度（例如
```
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

Image Requirements (MANDATORY)

图片要求（强制要求）

EXPORT all images from Figma - Never use placeholder paths
CHECK image existence before referencing
USE Next.js Image component with proper dimensions
PROVIDE fallbacks for missing images
OPTIMIZE images - WebP format preferred

从Figma导出所有图片 - 不要使用占位路径
引用前检查图片是否存在
使用Next.js Image组件并配置正确的尺寸
为缺失的图片提供兜底方案
优化图片 - 优先使用WebP格式

Production Checklist (MUST COMPLETE)

投产检查清单（必须全部完成）

Core Workflow

核心工作流

⚠️ REMINDER: Always complete Phase 0 (Checklist Creation) before starting these steps!

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

1. Design Extraction

1. 设计提取

Extract comprehensive design data from Figma:

bash

undefined

从Figma提取完整的设计数据：

bash

undefined

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>


Parse extracted data for:
- Typography (font-family, size, weight, line-height, letter-spacing)
- Colors (hex values, opacity)
- Spacing (padding, margin, gap)
- Layout (flexbox/grid properties, alignment)
- Borders, shadows, radius values
- Asset URLs and SVG exports

mcp0_get_design_context --nodeId <node-id> mcp0_get_variable_defs --nodeId <node-id> mcp0_get_screenshot --nodeId <node-id>


解析提取到的数据，获取以下内容：
- 排版（字体、字号、字重、行高、字间距）
- 颜色（十六进制值、透明度）
- 间距（内边距、外边距、间距）
- 布局（flexbox/grid属性、对齐方式）
- 边框、阴影、圆角值
- 资源URL和SVG导出内容

2. Project Analysis

2. 项目分析

Detect project configuration:

Framework: Next.js App Router vs Pages Router
Styling: Tailwind, CSS Modules, styled-components
Component library: shadcn/ui, MUI, Radix
Design tokens location: tailwind.config, theme.ts

Map Figma tokens to existing project tokens.

检测项目配置：

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

将Figma令牌映射到现有项目的令牌体系中。

3. Implementation

3. 实现

Generate component with extracted values:

typescript

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

STRICT Implementation Rules:

❌ FORBIDDEN: Hardcoded widths like
```
w-[1728px]
```
,
```
width: 1728px
```
✅ REQUIRED: Responsive containers
```
max-w-7xl mx-auto px-4
```
✅ REQUIRED: Mobile-first breakpoints
```
sm:
```
,
```
md:
```
,
```
lg:
```
,
```
xl:
```
✅ REQUIRED: Export and validate all images from Figma
✅ REQUIRED: Flexible layouts using Flexbox/Grid
✅ REQUIRED: Test on 375px, 768px, 1024px, 1440px viewports

Image Handling:

typescript

// 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={...} />

基于提取到的值生成组件：

typescript

// 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视口下测试

图片处理：

typescript

// 1. 从Figma导出
mcp0_get_screenshot --nodeId <id> --filename "hero-image.png"

// 2. 保存到 public/assets/
// 3. 配合Next Image使用
<Image src="/assets/hero-image.png" alt="..." width={...} height={...} />

4. Multi-Device Validation Loop

4. 多设备校验循环

Mandatory: Run validation on ALL viewports:

bash

undefined

强制要求：在所有视口下运行校验：

bash

undefined

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


**Validation Requirements**:
- ✅ No horizontal scroll on any viewport
- ✅ All images loading correctly (verified by resource-validator.py)
- ✅ No broken links or missing resources
- ✅ No placeholder content (lorem ipsum, temp images)
- ✅ Touch targets ≥ 44x44px on mobile
- ✅ Text legible without zooming
- ✅ Proper stacking on mobile (no overlaps)
- ✅ Interactive elements accessible

**Common Failures to Fix**:
- ❌ Hardcoded widths causing overflow
- ❌ Missing or broken images (detected by resource-validator.py)
- ❌ Broken internal/external links
- ❌ Placeholder content (lorem ipsum, temp images)
- ❌ External dependencies not cached locally
- ❌ Text too small on mobile (<14px)
- ❌ Elements overlapping on small screens
- ❌ Fixed positioning breaking on mobile

python scripts/resource-validator.py --directory src/app --strict


**校验要求**：
- ✅ 所有视口下无横向滚动条
- ✅ 所有图片正常加载（由resource-validator.py验证）
- ✅ 无损坏链接或缺失资源
- ✅ 无占位内容（lorem ipsum、临时图片）
- ✅ 移动端可点击区域 ≥ 44x44px
- ✅ 无需缩放即可清晰阅读文本
- ✅ 移动端元素堆叠正常（无重叠）
- ✅ 交互元素可访问

**需要修复的常见问题**：
- ❌ 硬编码宽度导致溢出
- ❌ 图片缺失或损坏（由resource-validator.py检测）
- ❌ 内部/外部链接损坏
- ❌ 占位内容（lorem ipsum、临时图片）
- ❌ 外部依赖未本地缓存
- ❌ 移动端文本过小（<14px）
- ❌ 小屏幕下元素重叠
- ❌ 固定定位在移动端表现异常

5. Responsive Implementation

5. 响应式实现

Extract breakpoint variations from Figma:

Desktop (1440px)
Tablet (768px)
Mobile (375px)

Apply responsive rules using project's breakpoint system.

从Figma提取断点适配规则：

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

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

Quick Commands

快捷命令

Full page implementation:

全页面实现：

bash

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

bash

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

Component extraction:

组件提取：

bash

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

bash

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

Visual validation:

视觉校验：

bash

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

bash

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

Resource validation (broken links, missing images):

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

bash

undefined

bash

undefined

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

undefined

python scripts/resource-validator.py --directory src/app --strict --report validation-report.txt

undefined

File Organization

文件组织

Pages: Follow project routing convention
- App Router:
```
app/[route]/page.tsx
```
- Pages Router:
```
pages/[route].tsx
```
Components:
```
components/ui/[component].tsx
```
Assets:
```
public/assets/
```
or
```
src/assets/
```
Styles: Co-located or in
```
styles/
```

页面：遵循项目路由规范
- App Router：
```
app/[route]/page.tsx
```
- Pages Router：
```
pages/[route].tsx
```
组件：
```
components/ui/[component].tsx
```
资源：
```
public/assets/
```
或
```
src/assets/
```
样式：与组件同目录或存放于
```
styles/
```
下

Token Mapping

令牌映射

See

references/token-mapping.md

for:

Figma → Tailwind mapping
Figma → CSS variables mapping
Shadow and gradient conversion
Typography scale mapping

查看

references/token-mapping.md

获取以下内容：

Figma → Tailwind 映射
Figma → CSS 变量映射
阴影和渐变转换规则
排版比例映射

Component Patterns

组件模式

See

references/component-patterns.md

for:

Card layouts
Navigation patterns
Form components
Modal implementations
Grid systems

查看

references/component-patterns.md

获取以下内容：

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

Validation Thresholds

校验阈值

Acceptable differences:

Font kerning: ±2px
Line height: ±1px
Anti-aliasing variations

Must match exactly:

Colors (hex values)
Border radius
Spacing values
Component dimensions
Shadow properties

可接受的差异：

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

必须完全匹配：

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