figma-storybook-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Figma to Storybook - STRICT Pixel-Perfect Workflow

Figma 转 Storybook - 严格像素级完美工作流

⚠️ CRITICAL RULES (NEVER VIOLATE)

⚠️ 核心规则（严禁违反）

ONE COMPONENT AT A TIME - Finish completely before moving to next
ALWAYS EXTRACT FRESH - Never use cached/old Figma data
ITERATE UNTIL PERFECT - Don't move on until user confirms it's correct
EXTRACT ONLY WHAT'S NEEDED - Don't load entire page context, only current component
NO ASSUMPTIONS - If unclear, extract again or ask user

一次处理一个组件 - 完成当前组件后再进行下一个
始终重新提取设计 - 绝不使用缓存或旧的Figma数据
迭代至完美为止 - 获得用户确认正确后再推进
仅提取所需内容 - 不要加载整个页面上下文，只提取当前组件
禁止主观假设 - 若有疑问，重新提取或询问用户

Description

工作流说明

Strict workflow enforcing pixel-perfect-ui methodology with iterative refinement. Each component is extracted, implemented, and perfected before moving to the next.

本严格工作流强制采用像素级完美UI方法论，结合迭代优化。每个组件需经过提取、实现、优化完善后，再推进到下一个组件。

When to Use

适用场景

Implementing Figma designs as Storybook components
Pixel-perfect accuracy required
User wants quality over speed
Multiple components need implementation

将Figma设计实现为Storybook组件
要求像素级完美精度
用户优先考虑质量而非速度
需要实现多个组件

🔒 MANDATORY WORKFLOW (FOLLOW EXACTLY)

🔒 必须严格遵循的工作流

Phase -1: 🚨 VISUAL VERIFICATION (ALWAYS FIRST)

阶段-1：🚨 视觉验证（必须首先执行）

For EACH component, ALWAYS:

```
mcp0_get_screenshot(nodeId)
```
→ SEE the design
DESCRIBE what you SEE - not what you assume
Check if similar component exists → REUSE with props
NEVER assume from names - verify visually

对于每个组件，必须执行以下步骤：

```
mcp0_get_screenshot(nodeId)
```
→ 查看设计图
描述你看到的内容 - 而非主观假设
检查是否存在相似组件 → 通过Props复用现有组件
绝不通过名称假设 - 必须视觉验证

Phase 0: Component Planning (QUICK - Don't Over-Analyze)

阶段0：组件规划（快速完成 - 无需过度分析）

Identify components to implement:

List component names from Figma/user request
Quick check: does similar component exist?
Present simple list to user

Present to user:

markdown

undefined

确定需要实现的组件：

从Figma或用户需求中列出组件名称
快速检查：是否存在相似组件？
向用户展示简洁列表

展示给用户的内容：

markdown

undefined

Components to Implement

待实现组件

ComponentName1 - [New/Reuse ExistingComponent]
ComponentName2 - [New/Reuse ExistingComponent]
ComponentName3 - [New/Reuse ExistingComponent]

Approach: Implement one at a time, iterate until perfect. Ready to start with Component 1?


**Wait for user approval, then START with first component.**

---

ComponentName1 - [新建/复用ExistingComponent]
ComponentName2 - [新建/复用ExistingComponent]
ComponentName3 - [新建/复用ExistingComponent]

实现方案：逐个实现，迭代至完美。 是否可以开始实现组件1？


**等待用户批准后，再开始第一个组件的实现。**

---

🔄 PER-COMPONENT WORKFLOW (Repeat for Each)

🔄 单组件工作流（每个组件重复执行）

Step 1: EXTRACT (MANDATORY - Never Skip)

步骤1：提取设计（必须执行 - 绝不跳过）

For current component ONLY:

bash

undefined

仅针对当前组件：

bash

undefined

Visual reference

视觉参考

mcp0_get_screenshot --nodeId <component-node-id>

Exact design extraction

精确设计提取

New Components to Create:

需创建的新组件：

Component	Reason	Generic Name	Where
Special layout	No similar pattern exists	UniqueSection	organisms/
Custom card	Different structure needed	SpecialCard	molecules/

组件	原因	通用名称	存放位置
Special layout	无相似模式存在	UniqueSection	organisms/
Custom card	需要不同结构	SpecialCard	molecules/

Inline Components to Extract:

需提取的内联组件：

Current Location	Component Type	New Generic Name
page.tsx:45-89	Card component	Card
page.tsx:120-150	List item	ListItem

当前位置	组件类型	新通用名称
page.tsx:45-89	Card component	Card
page.tsx:120-150	List item	ListItem

Components to Generalize:

需通用化的组件：

Current Components	Pattern	New Generic Component
AboutSection, TeamSection	Same layout	TwoColumnSection
ProductCard, ServiceCard	Same structure	Card

当前组件	模式	新通用组件
AboutSection, TeamSection	相同布局	TwoColumnSection
ProductCard, ServiceCard	相同结构	Card

Summary:

总结：

✅ Will REUSE: 3 existing components
🔨 Will CREATE: 2 new components
📦 Will EXTRACT: 2 inline components
🔄 Will GENERALIZE: 2 pairs into generic components

Questions for User:

Do you agree with this component strategy?
Should any of these be handled differently?
Any specific naming preferences?


**⛔ DO NOT PROCEED WITHOUT USER SAYING: "Yes, proceed" or similar approval**

✅ 将复用：3个现有组件
🔨 将创建：2个新组件
📦 将提取：2个内联组件
🔄 将通用化：2组组件为通用组件

向用户确认的问题：

你是否同意该组件实现策略？
是否有组件需要采用不同的处理方式？
是否有特定的命名偏好？


**⛔ 未收到用户“同意，继续”或类似批准前，禁止推进**

Phase 0.5: Decide Scope (CRITICAL - ASK FIRST)

阶段0.5：确定实现范围（核心 - 先询问用户）

Before ANY implementation, ask the user:

Are you building:
1. Only Storybook components (no page assembly)? 
2. Full page with components?

If Components Only → Skip page.tsx creation, focus ONLY on components and Storybook stories
If Full Page → Create both components and page assembly

在开始任何实现前，询问用户：

你需要实现的是：
1. 仅Storybook组件（不包含页面组装）？ 
2. 包含组件的完整页面？

如果选择仅组件 → 跳过page.tsx创建，仅专注于组件和Storybook故事
如果选择完整页面 → 同时创建组件和页面组装代码

DON'T load entire page context

不要加载整个页面上下文

DON'T extract multiple components at once

不要同时提取多个组件


**CRITICAL**: Extract shows EXACT:
- Dimensions (width, height, padding, margin, gap)
- Colors (hex codes, gradients)
- Typography (font-family, size, line-height, weight)
- Images (URLs to download)
- Spacing (exact pixel values)


**核心注意点**：提取的内容必须包含精确的：
- 尺寸（宽度、高度、内边距、外边距、间距）
- 颜色（十六进制代码、渐变）
- 排版（字体、字号、行高、字重）
- 图片（可下载的URL）
- 间距（精确像素值）

Step 2: DOWNLOAD ASSETS (If Any)

步骤2：下载资源（如有）

From extraction output, download ALL images:

bash

undefined

从提取结果中，下载所有图片：

bash

undefined

Extract image URLs from mcp0_get_design_context output

从mcp0_get_design_context输出中提取图片URL

Example: const img = "http://localhost:3845/assets/[hash].png"

示例：const img = "http://localhost:3845/assets/[hash].png"

curl -o /Users/mdascal/Projects/fuse/landing/public/assets/component-image-1.png "http://localhost:3845/assets/[hash].png" curl -o /Users/mdascal/Projects/fuse/landing/public/assets/component-image-2.png "http://localhost:3845/assets/[hash].png"

Verify file sizes (should be >10KB for real images)

验证文件大小（真实图片应大于10KB）

ls -lh /Users/mdascal/Projects/fuse/landing/public/assets/component-*


**If file size <10KB → Wrong image, re-download correct one**

ls -lh /Users/mdascal/Projects/fuse/landing/public/assets/component-*


**如果文件大小<10KB → 图片错误，重新下载正确的图片**

Step 3: IMPLEMENT EXACTLY

步骤3：精确实现组件

Use EXACT values from extraction:

Copy dimensions:
```
h-[696px]
```
,
```
w-[149.68%]
```
,
```
left-[-1.64%]
```
Copy spacing:
```
gap-[24px]
```
,
```
p-[96px]
```
,
```
px-[40px]
```
Copy colors:
```
#084EDD
```
,
```
rgba(255,255,255,0.6)
```
Copy typography:
```
text-[56px]
```
,
```
leading-[64px]
```

NO rounding, NO "close enough", NO assumptions

🚨 CRITICAL: FUNCTIONAL COMPONENTS (Not Just Visual)

ALWAYS implement as a PROFESSIONAL SOFTWARE ENGINEER:

Interactive Elements MUST Work:
- ✅ Search bars → filter data in real-time
- ✅ Dropdowns → show/hide options, update selection
- ✅ Pagination → change pages, calculate page numbers
- ✅ Tabs → switch content, highlight active tab
- ✅ Buttons → trigger actions, show hover/active states
- ✅ Forms → validate, submit, show errors
State Management:
- Use
```
useState
```
  for local state
- Use
```
useMemo
```
  for expensive calculations
- Use
```
useCallback
```
  for event handlers (if needed)
- Reset dependent state (e.g., page 1 when filtering)

Data Filtering Logic:

tsx

// Example: Combined filtering
const filteredData = useMemo(() => {
  return allData.filter(item => {
    const matchesSearch = searchQuery === '' || 
      item.title.toLowerCase().includes(searchQuery.toLowerCase())
    const matchesCategory = selectedCategory === 'All' || 
      item.category === selectedCategory
    return matchesSearch && matchesCategory
  })
}, [allData, searchQuery, selectedCategory])

Pagination Logic:

tsx

const totalPages = Math.ceil(filteredData.length / itemsPerPage)
const paginatedData = filteredData.slice(
  (currentPage - 1) * itemsPerPage, 
  currentPage * itemsPerPage
)

Props for Parent Control:
- Add callback props:
```
onTabChange
```
  ,
```
onSearch
```
  ,
```
onFilterChange
```
- Add controlled props:
```
activeTab
```
  ,
```
searchQuery
```
  ,
```
selectedFilters
```
- Allow both controlled and uncontrolled usage
Empty States:
- Show "No results found" when filters return empty
- Provide helpful messages
- Don't show pagination when no results
Icons:
- Use inline SVG for simple icons (search, arrows, chevrons)
- Download complex icons from Figma
- Ensure proper sizing and colors

❌ FORBIDDEN - Non-Functional Components:

Search that doesn't filter
Dropdowns that don't open
Pagination that doesn't change pages
Tabs that are just decorative
Buttons that do nothing

Create component + story:

Component file:

src/components/organisms/ComponentName.tsx

Story file:

src/components/organisms/ComponentName.stories.tsx

Use extracted values EXACTLY
Make it FULLY FUNCTIONAL like production software

完全使用提取的数值：

复制尺寸：
```
h-[696px]
```
,
```
w-[149.68%]
```
,
```
left-[-1.64%]
```
复制间距：
```
gap-[24px]
```
,
```
p-[96px]
```
,
```
px-[40px]
```
复制颜色：
```
#084EDD
```
,
```
rgba(255,255,255,0.6)
```
复制排版：
```
text-[56px]
```
,
```
leading-[64px]
```

禁止四舍五入、禁止“差不多”、禁止主观假设

🚨 核心要求：组件必须具备功能性（而非仅视觉还原）

必须以专业软件工程师的标准实现：

交互元素必须可正常工作：
- ✅ 搜索框 → 实时过滤数据
- ✅ 下拉菜单 → 显示/隐藏选项，更新选中状态
- ✅ 分页器 → 切换页面，计算总页数
- ✅ 标签页 → 切换内容，高亮激活标签
- ✅ 按钮 → 触发操作，显示悬停/激活状态
- ✅ 表单 → 验证、提交、显示错误
状态管理：
- 使用
```
useState
```
  管理局部状态
- 使用
```
useMemo
```
  处理高开销计算
- 使用
```
useCallback
```
  处理事件处理器（如有需要）
- 重置依赖状态（例如：过滤时重置为第1页）

数据过滤逻辑：

tsx

// 示例：组合过滤
const filteredData = useMemo(() => {
  return allData.filter(item => {
    const matchesSearch = searchQuery === '' || 
      item.title.toLowerCase().includes(searchQuery.toLowerCase())
    const matchesCategory = selectedCategory === 'All' || 
      item.category === selectedCategory
    return matchesSearch && matchesCategory
  })
}, [allData, searchQuery, selectedCategory])

分页逻辑：

tsx

const totalPages = Math.ceil(filteredData.length / itemsPerPage)
const paginatedData = filteredData.slice(
  (currentPage - 1) * itemsPerPage, 
  currentPage * itemsPerPage
)

父组件可控的Props：
- 添加回调Props：
```
onTabChange
```
  ,
```
onSearch
```
  ,
```
onFilterChange
```
- 添加受控Props：
```
activeTab
```
  ,
```
searchQuery
```
  ,
```
selectedFilters
```
- 支持受控和非受控两种使用方式
空状态处理：
- 过滤无结果时显示“未找到结果”
- 提供有帮助的提示信息
- 无结果时不显示分页器
图标处理：
- 简单图标（搜索、箭头、 Chevron）使用内联SVG
- 复杂图标从Figma下载
- 确保尺寸和颜色正确

❌ 禁止实现无功能性的组件：

无法过滤的搜索框
无法展开的下拉菜单
无法切换页面的分页器
仅装饰性的标签页
无任何操作的按钮

创建组件+故事：

组件文件：

src/components/organisms/ComponentName.tsx

故事文件：

src/components/organisms/ComponentName.stories.tsx

完全使用提取的数值
按照生产级软件标准实现完整功能

Step 4: ITERATE UNTIL PERFECT

步骤4：迭代至完美

Show implementation to user:

markdown

undefined

向用户展示实现结果：

markdown

undefined

ComponentName - First Implementation

ComponentName 首次实现完成

Implemented based on Figma extraction:

✅ Dimensions: [list key dimensions]
✅ Images: [list images used]
✅ Spacing: [list key spacing]
✅ Colors: [list key colors]

Please review and let me know if anything needs adjustment.


**User feedback loop:**
- User points out issues
- Re-extract if needed (don't assume fix)
- Implement corrections EXACTLY
- Show updated implementation
- Repeat until user says "perfect" or "move to next"

**ONLY when user confirms → Move to next component**

基于Figma提取内容实现：

✅ 尺寸：[列出关键尺寸]
✅ 图片：[列出使用的图片]
✅ 间距：[列出关键间距]
✅ 颜色：[列出关键颜色]

请审阅并告知是否需要调整。


**用户反馈循环：**
- 用户指出问题
- 如有需要重新提取（不要假设修复方案）
- 精确实现修正内容
- 展示更新后的实现
- 重复直到用户确认“完美”或“进行下一个组件”

**仅当用户确认后 → 推进到下一个组件**

Step 5: RESPONSIVE (After User Approves Desktop)

步骤5：响应式适配（用户确认桌面版后）

Add mobile/tablet breakpoints:

tsx

// Mobile: 375px
className="px-6 py-12 lg:px-24 lg:py-24"

// Tablet: 768px  
className="flex-col md:flex-row"

// Desktop: 1440px (already implemented)

Test: No horizontal scroll on any viewport

添加移动端/平板端断点：

tsx

// 移动端：375px
className="px-6 py-12 lg:px-24 lg:py-24"

// 平板端：768px  
className="flex-col md:flex-row"

// 桌面端：1440px（已实现）

测试：所有视口下无水平滚动条

✅ COMPLETION CRITERIA (Per Component)

✅ 组件完成标准

🚫 FORBIDDEN ACTIONS

🚫 禁止操作

❌ Batch extracting all components at once
❌ Implementing from memory or old extraction
❌ Moving to next component before user approval
❌ Rounding dimensions (use exact:
```
h-[696px]
```
not
```
h-[700px]
```
)
❌ Assuming image paths (download from extraction)
❌ Loading full page context (extract only current component)
❌ Skipping iteration (always show to user, get feedback)

❌ 批量提取所有组件
❌ 凭记忆或旧提取结果实现组件
❌ 未获得用户批准就推进到下一个组件
❌ 四舍五入尺寸（使用精确值：
```
h-[696px]
```
而非
```
h-[700px]
```
）
❌ 假设图片路径（从提取结果下载）
❌ 加载完整页面上下文（仅提取当前组件）
❌ 跳过迭代环节（始终向用户展示并获取反馈）

📝 WORKFLOW SUMMARY

📝 工作流总结

For Component 1:
  1. Extract (mcp0_get_design_context)
  2. Download assets
  3. Implement EXACTLY
  4. Show to user
  5. User feedback → Iterate
  6. User confirms → Add responsive
  7. User says "perfect" → DONE

For Component 2:
  1. Extract (fresh, don't reuse Component 1 data)
  2. Download assets
  3. Implement EXACTLY
  ... repeat ...

For Component N:
  ... same process ...

Key: ONE at a time, ITERATE until perfect, THEN move on

对于组件1：
  1. 提取设计（mcp0_get_design_context）
  2. 下载资源
  3. 精确实现
  4. 向用户展示
  5. 根据用户反馈 → 迭代优化
  6. 用户确认 → 添加响应式适配
  7. 用户确认“完美” → 完成

对于组件2：
  1. 提取设计（重新提取，不要复用组件1的数据）
  2. 下载资源
  3. 精确实现
  ... 重复上述流程 ...

对于组件N：
  ... 相同流程 ...

核心：一次处理一个，迭代至完美，再推进

🎯 SUCCESS METRICS

🎯 成功指标

Per component:

Zero assumptions made
All dimensions from extraction used exactly
All images downloaded and verified
User confirms pixel-perfect match
Responsive on all viewports

Overall:

Each component perfect before moving to next
No batch processing
No shortcuts taken
User satisfaction 100%

每个组件需满足：

无主观假设
完全使用提取的尺寸
所有图片已下载并验证
用户确认像素级匹配
所有视口下响应式适配正常

整体项目需满足：

每个组件完美后再推进下一个
无批量处理
无捷径
用户满意度100%

⚡ EFFICIENCY NOTES

⚡ 效率说明

This workflow is SLOWER but CORRECT:

Takes more time per component
Requires more user interaction
Uses more tokens (multiple extractions)
BUT: Zero rework, perfect first time (after iterations)

User explicitly wants:

Quality over speed
Multiple extractions if needed
Iterative refinement
Pixel-perfect results

Don't try to optimize or take shortcuts!

本工作流速度较慢但结果准确：

每个组件耗时更长
需要更多用户交互
消耗更多Token（多次提取）
但：零返工，迭代后首次即完美

用户明确需求：

质量优先于速度
如有需要可多次提取
迭代优化
像素级完美结果

不要尝试优化或走捷径！

📋 OLD SECTIONS (Kept for Reference)

📋 历史章节（仅供参考）

Asset Validation (If Needed)

资源验证（如有需要）

Before creating ANY component:

Check what images exist:

bash

list_dir("/public/assets")
find_by_name("*.png", "/public/assets")
find_by_name("*.svg", "/public/assets")

Map Figma assets to existing files:

markdown

## Asset Mapping
✅ Figma "hero.png" → /assets/hero.png (exists)
✅ Figma "logo" → /assets/logo-text.svg (exists)  
❌ Figma "team.png" → MISSING → use /assets/featured-team.png
⬇️ Figma "icon" → download from localhost:3845

Download missing Figma assets:

bash

# From mcp0_get_design_context output
curl "http://localhost:3845/assets/[hash].png" -o /public/assets/[name].png

NEVER reference non-existent images in code!

在创建任何组件前：

检查现有图片：

bash

list_dir("/public/assets")
find_by_name("*.png", "/public/assets")
find_by_name("*.svg", "/public/assets")

映射Figma资源到现有文件：

markdown

## 资源映射
✅ Figma "hero.png" → /assets/hero.png（已存在）
✅ Figma "logo" → /assets/logo-text.svg（已存在）  
❌ Figma "team.png" → 缺失 → 使用/assets/featured-team.png
⬇️ Figma "icon" → 从localhost:3845下载

下载缺失的Figma资源：

bash

# 从mcp0_get_design_context输出中获取
curl "http://localhost:3845/assets/[hash].png" -o /public/assets/[name].png

禁止在代码中引用不存在的图片！

Phase 1.6: Port Conflict Detection (MANDATORY BEFORE STARTING SERVERS)

阶段1.6：端口冲突检测（启动服务器前必须执行）

Before starting dev server or Storybook:

Check if ports are already in use:

bash

# Check if dev server is running (port 3001)
lsof -ti:3001

# Check if Storybook is running (port 6010)
lsof -ti:6010

Decision logic:

If port is FREE → Start the server normally

If port is IN USE → Check if it's the correct service:

bash

# Test if it's the dev server
curl -s http://localhost:3001 | grep -q "<title>" && echo "Dev server running"

# Test if it's Storybook
curl -s http://localhost:6010 | grep -q "Storybook" && echo "Storybook running"

If correct service running → Use existing server, don't start new one

If wrong service or broken → Kill and restart:

bash

# Kill process on port
kill $(lsof -ti:3001)
# or
kill $(lsof -ti:6010)

# Wait a moment
sleep 2

# Start the correct service
npm run dev  # or npm run storybook

Never start duplicate servers on different ports!
Use Figma MCP for Design Context
- Call
```
mcp0_get_design_context(nodeId)
```
  to get design details
- Call
```
mcp0_get_screenshot(nodeId)
```
  to capture visual reference
- Extract design specifications (colors, spacing, typography)
Create TODO List
- Analyze design from Figma
- Check existing implementation
- Present plan to user
- Wait for approval (if needed)
- Create/refactor component
- Add to Storybook
- Verify pixel perfect with Playwright
- Test responsive layouts

在启动开发服务器或Storybook前：

检查端口是否已被占用：

bash

# 检查开发服务器是否运行（端口3001）
lsof -ti:3001

# 检查Storybook是否运行（端口6010）
lsof -ti:6010

决策逻辑：

如果端口空闲 → 正常启动服务器

如果端口已被占用 → 检查是否是正确的服务：

bash

# 测试是否为开发服务器
curl -s http://localhost:3001 | grep -q "<title>" && echo "开发服务器正在运行"

# 测试是否为Storybook
curl -s http://localhost:6010 | grep -q "Storybook" && echo "Storybook正在运行"

如果正确服务正在运行 → 使用现有服务器，不要启动新的

如果错误服务或服务异常 → 终止并重启：

bash

# 终止端口上的进程
kill $(lsof -ti:3001)
# 或
kill $(lsof -ti:6010)

# 等待2秒
sleep 2

# 启动正确服务
npm run dev  # 或 npm run storybook

禁止在其他端口启动服务 - 始终使用配置的端口（3001用于开发，6010用于Storybook）
使用Figma MCP获取设计上下文
- 调用
```
mcp0_get_design_context(nodeId)
```
  获取设计细节
- 调用
```
mcp0_get_screenshot(nodeId)
```
  获取视觉参考
- 提取设计规范（颜色、间距、排版）
创建待办清单
- 分析Figma设计
- 检查现有实现
- 向用户展示计划
- 等待批准（如有需要）
- 创建/重构组件
- 添加到Storybook
- 使用Playwright验证像素级完美
- 测试响应式布局

Phase 2: Component Implementation with Immediate Testing

阶段2：组件实现与即时测试

After creating EACH component:

Create the component
Create story IMMEDIATELY

Test in Storybook RIGHT AWAY:

bash

# Check for TypeScript errors
npx tsc --noEmit | grep ComponentName

# Verify story loads
curl http://localhost:6010/index.json | grep -i "componentname"

Fix issues BEFORE moving to next component

创建每个组件后：

创建组件
立即创建Storybook故事

立即在Storybook中测试：

bash

# 检查TypeScript错误
npx tsc --noEmit | grep ComponentName

# 验证故事是否加载
curl http://localhost:6010/index.json | grep -i "componentname"

修复问题后再推进到下一个组件

Phase 2.5: Storybook Story Creation

阶段2.5：Storybook故事创建

Delegate to storybook skill for actual code:

skill("storybook") to create stories with:
- CSF 3.0 format
- Responsive viewport variants (Mobile, Tablet, Desktop)
- Interactive args for props
- Multiple variants showing different states

Required stories for each component:

Default story
MobileView (375px)
TabletView (768px)
DesktopView (1440px)
Custom variants (if needed)

委托给Storybook技能生成实际代码：

skill("storybook") 创建故事需包含：
- CSF 3.0格式
- 响应式视口变体（移动端、平板端、桌面端）
- 可交互的Props参数
- 展示不同状态的多个变体

每个组件必须包含的故事：

默认故事
MobileView（375px）
TabletView（768px）
DesktopView（1440px）
自定义变体（如有需要）

Phase 3: Visual Verification

阶段3：视觉验证

Use Playwright MCP (if available) or manual testing:

Navigate to story in Storybook
Capture screenshots for each viewport:
- Desktop (1440px)
- Tablet (768px)
- Mobile (375px)
Compare with Figma design:
- Spacing matches
- Typography matches
- Colors match
- Layout structure matches

If Playwright unavailable: Use manual browser testing in Storybook UI

使用Playwright MCP（如有）或手动测试：

导航到Storybook中的对应故事
为每个视口截图：
- 桌面端（1440px）
- 平板端（768px）
- 移动端（375px）
与Figma设计对比：
- 间距匹配
- 排版匹配
- 颜色匹配
- 布局结构匹配

若无Playwright： 在Storybook UI中进行手动浏览器测试

Phase 4: Refinement

阶段4：优化完善

When fixing issues, delegate to appropriate skill:

For Next.js/React component fixes:

skill("next-best-practices") for:
- Component structure
- Image optimization
- Responsive design
- Performance issues

For Storybook story fixes:

skill("storybook") for:
- Story structure
- Args/decorators
- Viewport configuration
- Story variants

Common issues to fix:
- Adjust spacing to match Figma
- Fix responsive breakpoints
- Update typography variants
- Ensure no hardcoded widths

修复问题时，委托给合适的技能：

Next.js/React组件修复：

使用skill("next-best-practices")处理：
- 组件结构
- 图片优化
- 响应式设计
- 性能问题

Storybook故事修复：

使用skill("storybook")处理：
- 故事结构
- 参数/装饰器
- 视口配置
- 故事变体

常见问题修复：
- 调整间距以匹配Figma
- 修复响应式断点
- 更新排版变体
- 确保无硬编码宽度

Phase 4.5: Verification Before Marking Complete (NEVER SKIP)

阶段4.5：标记完成前的验证（严禁跳过）

DO NOT mark ANY task complete without:

Build verification:

bash

# Check TypeScript
npx tsc --noEmit

# Build Storybook (if needed)
npm run build-storybook

Story verification in Storybook:

bash

# List all component stories
curl http://localhost:6010/index.json | jq '.entries | keys' | grep -i component

# Verify story renders (should return > 0)
curl "http://localhost:6010/iframe.html?id=organisms-component--default" | grep -c "ComponentName"

Asset verification:

bash

# Check for missing images (if page exists)
curl http://localhost:3001/page | grep -o 'src="[^"]*"' | while read path; do
  [ ! -f "/public$path" ] && echo "Missing: $path"
done

未完成以下步骤，禁止标记任何任务为完成：

构建验证：

bash

# 检查TypeScript
npx tsc --noEmit

# 构建Storybook（如有需要）
npm run build-storybook

Storybook故事验证：

bash

# 列出所有组件故事
curl http://localhost:6010/index.json | jq '.entries | keys' | grep -i component

# 验证故事是否渲染（应返回>0）
curl "http://localhost:6010/iframe.html?id=organisms-component--default" | grep -c "ComponentName"

资源验证：

bash

# 检查缺失图片（如有页面）
curl http://localhost:3001/page | grep -o 'src="[^"]*"' | while read path; do
  [ ! -f "/public$path" ] && echo "缺失：$path"
done

Phase 5: Documentation

阶段5：文档更新

Update TODO List
- Mark completed tasks
- Add any new tasks discovered

Summary Pattern

markdown

## ComponentName Implementation Complete ✅

### Verified Implementation
- Desktop View: [description]
- Tablet View: [description] 
- Mobile View: [description]

### What Was Completed
1. Created Storybook stories
2. Fixed [specific issues]
3. Responsive design verified

### Component Structure
- Main component: [description]
- Supporting components: [list]

更新待办清单
- 标记已完成任务
- 添加发现的新任务

总结模板

markdown

## ComponentName 实现完成 ✅

### 已验证的实现
- 桌面端视图：[描述]
- 平板端视图：[描述] 
- 移动端视图：[描述]

### 完成内容
1. 创建了Storybook故事
2. 修复了[具体问题]
3. 验证了响应式设计

### 组件结构
- 主组件：[描述]
- 支持组件：[列表]

Key Principles

核心原则

Workflow Focus

工作流重点

This skill focuses on:

Component planning and analysis
Asset validation
Port management
Testing and verification
Error recovery

本技能专注于：

组件规划与分析
资源验证
端口管理
测试与验证
错误恢复

Code Writing Delegation

代码编写委托

Next.js/React code → Use
```
skill("next-best-practices")
```
Storybook stories → Use
```
skill("storybook")
```

Next.js/React代码 → 使用
```
skill("next-best-practices")
```
Storybook故事 → 使用
```
skill("storybook")
```

Component Organization

组件组织

Organisms: Full sections (HeroSection, StatsSection, etc.)
Molecules: Reusable components (StatCard, FeatureCard, etc.)
Atoms: Basic elements (Button, Typography, etc.)

Organisms：完整区块（HeroSection、StatsSection等）
Molecules：可复用模块（StatCard、FeatureCard等）
Atoms：基础元素（Button、Typography等）

Tools Required

所需工具

Figma MCP: For design context and screenshots
Playwright MCP: For browser testing and verification
Storybook: Running on port 6008 (or configured port)
File operations: edit, write_to_file, read_file

Figma MCP：获取设计上下文与截图
Playwright MCP：浏览器测试与验证
Storybook：运行在端口6008（或配置的端口）
文件操作：编辑、写入、读取文件

Success Criteria

成功标准

Example Workflow Sequence

工作流示例序列

Analysis: Check existing components, identify patterns
Figma: Get design context and screenshot
Assets: Validate images exist, download missing ones
Ports: Check if Storybook running, reuse or restart
Component: Delegate to
```
skill("next-best-practices")
```
Story: Delegate to
```
skill("storybook")
```
Verify: Check story loads in Storybook
Visual: Compare with Figma design
Refine: Fix issues using appropriate skills
Complete: Update TODO list

分析：检查现有组件，识别模式
Figma：获取设计上下文与截图
资源：验证图片存在，下载缺失的图片
端口：检查Storybook是否运行，复用或重启
组件：委托给
```
skill("next-best-practices")
```
故事：委托给
```
skill("storybook")
```
验证：检查故事在Storybook中是否加载
视觉对比：与Figma设计对比
优化：使用合适的技能修复问题
完成：更新待办清单

Real Example: How Planning Matrix Prevents Mistakes

真实示例：规划矩阵如何避免错误

Without Planning Matrix ❌

无规划矩阵 ❌

Developer sees Security page → starts creating:
- SecurityHero (duplicate of HeroSection)
- CaseStudyCard (duplicate of ImageCard) 
- SecurityRevenue (duplicate of GridSection)
Result: 3 unnecessary components created

开发者看到安全页面 → 开始创建：
- SecurityHero（重复HeroSection）
- CaseStudyCard（重复ImageCard） 
- SecurityRevenue（重复GridSection）
结果：创建了3个不必要的组件

With Planning Matrix ✅

使用规划矩阵 ✅

Phase 0 Analysis reveals:
- Hero section → REUSE HeroSection with props
- Case study cards → REUSE ImageCard 
- Revenue section → REUSE GridSection
Result: 0 unnecessary components, everything reused

阶段0分析发现：
- Hero区块 → 复用HeroSection并传入Props
- 案例研究卡片 → 复用ImageCard 
- 收入区块 → 复用GridSection
结果：0个不必要组件，全部复用现有组件

Common Mistakes to Avoid

需避免的常见错误

🚨 0. CRITICAL: Making Assumptions Without Visual Verification ❌

🚨 0. 核心错误：无视觉验证的主观假设 ❌

This is the #1 mistake that MUST be avoided!

Wrong:

Seeing "ContactForm" in a name → assuming it has form inputs
Reading text description → creating component without checking screenshot
Assuming component structure from name alone

Right:

ALWAYS call
mcp0_get_screenshot()
FIRST
LOOK at the actual visual before writing ANY code
Describe what you SEE in the screenshot, not what you assume
If user says "it's a variation" → check existing component, add props, DON'T create new

Verification Checklist Before ANY Component:

□ Did I call mcp0_get_screenshot()?
□ Did I LOOK at the screenshot image?
□ Did I describe what I SEE (not assume)?
□ Does an existing component match this visual pattern?
□ If user said "variation" → am I reusing existing component?

Example of this mistake:

User: "Contact Form is a variation of BusinessSection"
❌ Wrong: Create new ContactFormSection with textarea
✅ Right: Look at screenshot → see it's just title+subtitle+button+images → reuse BusinessSection with props

这是必须避免的头号错误！

错误做法：

看到名称中的"ContactForm" → 假设包含表单输入
阅读文字描述 → 未查看截图就创建组件
仅通过名称假设组件结构

正确做法：

始终首先调用
mcp0_get_screenshot()
在编写任何代码前，查看实际视觉效果
描述你看到的内容，而非主观假设
如果用户说“这是变体” → 检查现有组件，添加Props，不要创建新组件

创建任何组件前的验证清单：

□ 是否调用了mcp0_get_screenshot()？
□ 是否查看了截图？
□ 是否描述了看到的内容（而非假设）？
□ 是否存在匹配该视觉模式的现有组件？
□ 如果用户说是“变体” → 是否复用了现有组件？

错误示例：

用户：“Contact Form是BusinessSection的变体”
❌ 错误做法：创建新的ContactFormSection并添加文本框
✅ 正确做法：查看截图 → 发现只是标题+副标题+按钮+图片 → 复用BusinessSection并传入Props

1. Creating Duplicate Components ❌

1. 创建重复组件 ❌

Wrong: Creating

ProductHero

ServiceCard

when similar components exist Right: Use existing

HeroSection

Card

components with different props

错误做法： 当相似组件已存在时，创建

ProductHero

、

ServiceCard

正确做法： 使用现有

HeroSection

、

Card

组件并传入不同Props

2. Not Generalizing Patterns ❌

2. 未通用化模式 ❌

Wrong: Keeping

TeamSection

and

AboutSection

as separate components when they share same layout Right: Create generic

TwoColumnSection

GridSection

错误做法： 当

TeamSection

和

AboutSection

布局相同时，仍保留为独立组件 正确做法： 创建通用的

TwoColumnSection

或

GridSection

3. Component Naming ❌

3. 组件命名错误 ❌

Wrong: Page-specific names like

HomeFeatures

AboutCard

ContactHero

Right: Generic names like

FeatureGrid

Card

HeroSection

错误做法： 使用页面特定名称如

HomeFeatures

、

AboutCard

、

ContactHero

正确做法： 使用通用名称如

FeatureGrid

、

Card

、

HeroSection

Generalization Principles

通用化原则

When to Create Generic Components

何时创建通用组件

Visual Pattern Matching: If 2+ sections have same layout but different content
Props Over Duplication: Use props for variations, not new components
Generic Names: Name by pattern, not content (e.g.,
```
CardGrid
```
not
```
CaseStudies
```
)

视觉模式匹配：如果2个及以上区块布局相同但内容不同
Props优先于重复：使用Props实现变体，而非创建新组件
通用名称：按模式命名，而非内容（例如：
```
CardGrid
```
而非
```
CaseStudies
```
）

Component Hierarchy

组件层级

Pages (compose components with content props)
  ↓
Organisms (full sections: HeroSection, GridSection, FeatureSection)
  ↓
Molecules (reusable blocks: Card, ListItem, Accordion)
  ↓
Atoms (basic elements: Button, Typography, Icon, Link)

页面（通过内容Props组合组件）
  ↓
Organisms（完整区块：HeroSection、GridSection、FeatureSection）
  ↓
Molecules（可复用模块：Card、ListItem、Accordion）
  ↓
Atoms（基础元素：Button、Typography、Icon、Link）

Common Patterns

常见问题处理

Figma Node ID Issues

Figma节点ID问题

If Figma node ID doesn't work:

Try using
```
mcp0_get_metadata("0:1")
```
to explore structure
Check project documentation for node ID references
Use grep_search to find node IDs in existing files

如果Figma节点ID无效：

尝试使用
```
mcp0_get_metadata("0:1")
```
探索结构
查看项目文档中的节点ID参考
使用grep_search在现有文件中查找节点ID

Playwright Timeout Issues

Playwright超时问题

If Playwright times out:

Close and restart:
```
mcp1_browser_close()
```

Navigate to base URL first:

mcp1_browser_navigate("http://localhost:6008")

Then navigate to specific story

如果Playwright超时：

关闭并重启：
```
mcp1_browser_close()
```

首先导航到基础URL：

mcp1_browser_navigate("http://localhost:6008")

然后导航到特定故事

Image Loading Issues

图片加载问题

Ensure images are in
```
public/assets/
```
Use Next.js Image component
Check browser console for 404 errors
Verify image paths in Storybook static dirs config

确保图片位于
```
public/assets/
```
使用Next.js Image组件
检查浏览器控制台的404错误
验证Storybook静态目录配置中的图片路径

Error Recovery Procedures

错误恢复流程

When Playwright Browser Fails

Playwright浏览器故障时

Check if browser already running

Try manual Storybook testing:

bash

curl "http://localhost:6010/iframe.html?id=component--story"

Take manual screenshots if needed
Continue with Storybook verification only

检查浏览器是否已运行

尝试手动Storybook测试：

bash

curl "http://localhost:6010/iframe.html?id=component--story"

如有需要手动截图
仅继续Storybook验证

When Images Are Missing

图片缺失时

Find similar existing image:

bash

ls /public/assets/ | grep -i "similar_name"

Use existing image as fallback
Download from Figma localhost if available
Document the substitution

查找相似的现有图片：

bash

ls /public/assets/ | grep -i "similar_name"

使用现有图片作为备选
如有可用从Figma localhost下载
记录替代方案

When Component Doesn't Render in Storybook

组件无法在Storybook中渲染时

Check import paths
Verify all props have defaults
Check browser console for errors
Start with minimal props, add complexity gradually
Test component in isolation first

检查导入路径
验证所有Props是否有默认值
检查浏览器控制台的错误
从最小Props开始，逐步增加复杂度
先在隔离环境测试组件

When TypeScript Errors Occur

TypeScript错误时

Run
```
npx tsc --noEmit
```
to see all errors
Check missing imports
Verify prop types match
Ensure all dependencies installed

运行
```
npx tsc --noEmit
```
查看所有错误
检查缺失的导入
验证Props类型是否匹配
确保所有依赖已安装

When Port Conflicts Occur

端口冲突时

Check what's running on the port:

bash

# Check port 3001 (dev server)
lsof -ti:3001
curl -s http://localhost:3001 | head -n 1

# Check port 6010 (Storybook)
lsof -ti:6010
curl -s http://localhost:6010 | grep -o '<title>.*</title>'

If correct service is running:
- Use the existing server
- Don't start a new one
- Example: "Storybook already running on port 6010, using existing instance"

If wrong service or broken:

bash

# Kill the process
kill $(lsof -ti:6010)
sleep 2

# Start correct service
npm run storybook

Never start on alternative ports - Always use the configured ports (3001 for dev, 6010 for Storybook)

检查端口上运行的服务：

bash

# 检查开发服务器（端口3001）
lsof -ti:3001
curl -s http://localhost:3001 | head -n 1

# 检查Storybook（端口6010）
lsof -ti:6010
curl -s http://localhost:6010 | grep -o '<title>.*</title>'

如果正确服务正在运行：
- 使用现有服务器
- 不要启动新服务器
- 示例："Storybook已在端口6010运行，使用现有实例"

如果错误服务或服务异常：

bash

# 终止进程
kill $(lsof -ti:6010)
sleep 2

# 启动正确服务
npm run storybook

禁止在其他端口启动服务 - 始终使用配置的端口（3001用于开发，6010用于Storybook）