产品设计技能

自动化设计审查、提取标记、组件映射和实施计划。通过直接Figma MCP集成，将设计交接时间从6-10小时减少到5分钟。当用户提及设计审查、Figma原型或设计交接时自动调用。

何时调用

自动调用当用户说：

• “审查这个设计”
• “分析Figma原型”
• “[功能]的设计交接”
• “检查设计系统影响”
• “为设计规划实施”
• “从Figma提取标记”
• “设计有什么变化？”

这是做什么的

5步工作流程：

1. 设计分析：从Figma提取模式、组件、标记
2. 代码库审核：比较设计与实现，发现偏差
3. 实施计划：生成分阶段任务分解
4. 任务分配：创建Navigator任务文档
5. 交接：让用户审查或开始实施

节省时间：6-10小时 → 15-20分钟（减少95%）

先决条件

必需

1. Python依赖

   cd skills/product-design
   ./setup.sh  # 自动安装
   # 或手动：pip install -r requirements.txt
   

2. Figma桌面（用于自动化工作流程）

   • 下载：https://www.figma.com/downloads/
   • 启用MCP：Figma → Preferences → 启用本地MCP服务器
   • 在设计审查期间必须运行

3. 项目结构

   • .agent/design-system/目录（首次运行时创建）
   • 包含组件的项目（React/Vue/Svelte）

可选（增强功能）

• Figma企业版：Code Connect自动组件映射
• Tailwind CSS：通过@theme集成设计标记
• Storybook：组件文档和视觉回归

安装

快速开始：

cd skills/product-design
./setup.sh

查看INSTALL.md了解详细的安装指南和故障排除。

工作流程协议

第0步：检查设置（自动运行）

在开始之前，验证Python依赖是否已安装：

# 获取Navigator插件路径
PLUGIN_PATH=$(dirname "$(dirname "$(dirname "$PWD")")")

# 检查venv是否存在
if [ ! -d "$PLUGIN_PATH/skills/product-design/venv" ]; then
  echo "❌ product-design skill not set up"
  echo ""
  echo "运行设置（30秒）："
  echo "  cd $PLUGIN_PATH/skills/product-design && ./setup.sh"
  echo ""
  echo "或使用手动工作流程（不需要Python）"
  exit 1
fi

如果设置缺失：

• 显示设置说明
• 提供手动工作流程作为替代方案
• 不要继续自动化Figma工作流程

如果设置完成：

• 继续进行第1步（设计分析）

---

第1步：设计分析

目标：从Figma或手动描述中提取设计模式

带Figma MCP（自动化）✨ 简化

新架构（v1.1.0+）：Python直接连接到Figma MCP - 无需手动编排！

# Python函数现在自动处理MCP连接
from figma_mcp_client import FigmaMCPClient

async with FigmaMCPClient() as client:
    # 逐步细化 - 只获取所需内容
    metadata = await client.get_metadata()
    components = extract_components(metadata)

    # 仅在复杂组件需要时获取详细信息
    for comp in components:
        if comp['complexity'] == 'high':
            comp['detail'] = await client.get_design_context(comp['id'])

    # 获取设计标记
    variables = await client.get_variable_defs()

工作流程（完全自动化）：

1. 用户提供Figma URL
2. 运行python3 functions/design_analyzer.py --figma-url <URL>
3. Python连接到Figma MCP（http://127.0.0.1:3845/mcp）
4. 获取元数据 → 分析 → 仅在需要时获取详细信息
5. 返回完整分析

好处：

• ✅ 无需Claude手动MCP工具调用
• ✅ 逐步细化（智能标记使用）
• ✅ 自动连接管理
• ✅ 内置错误处理

要求：

• 运行中的Figma桌面
• MCP在偏好设置中启用
• 安装Python依赖（./setup.sh）

手动工作流程（无MCP）

**向用户询问设计信息**：

功能名称是什么？[例如，"Dashboard Redesign"]

Figma链接（可选）：[figma.com/file/...]

**设计标记**：
列出新的或修改后的标记：
- 颜色（名称：值，例如，"primary-600: #2563EB"）
- 间距（例如，"spacing-lg: 24px"）
- 排版（例如，"heading-xl: 36px/600"）
- 其他（圆角，阴影等）

**组件**：
列出设计中的组件：
- 组件名称
- 类型（原子，分子，有机体）
- 变体（如果有，例如，"Button: primary/secondary, sm/md/lg"）
- 类似于现有组件？（如果知道，请提供名称）

**收集信息后进行第2步**

运行design_analyzer.py

# 准备输入（MCP或手动JSON）
# MCP：已经有/tmp/figma_metadata.json
# 手动：根据用户输入创建JSON

python3 functions/design_analyzer.py \
  --figma-data /tmp/figma_combined.json \
  --ui-kit-inventory .agent/design-system/ui-kit-inventory.json \
  --output /tmp/analysis_results.json

分析输出：

• UI工具包中没有的新组件
• 类似组件（重用机会）
• 新设计标记
• 重大变更（如果有）

---

第2步：代码库审核

目标：比较设计与实现，检测偏差

标记提取

python3 functions/token_extractor.py \
  --figma-variables /tmp/figma_variables.json \
  --existing-tokens .agent/design-system/design-tokens.json \
  --output /tmp/token_extraction.json

输出：DTCG格式标记+差异摘要

组件映射

python3 functions/component_mapper.py \
  --figma-components /tmp/analysis_results.json \
  --code-connect-map /tmp/figma_code_connect.json \
  --project-root . \
  --output /tmp/component_mappings.json

输出：Figma组件 → 代码组件映射，带置信分数

设计系统审核

# 合并数据以供审计员使用
python3 functions/design_system_auditor.py \
  --figma-data /tmp/combined_figma.json \
  --code-data /tmp/combined_code.json \
  --output /tmp/audit_results.json

审计结果：

• 标记对齐（同步，偏差，缺失，未使用）
• 组件重用机会
• Tailwind配置建议
• 优先级（关键，高，中，低）

---

第3步：实施计划

目标：生成分阶段实施任务文档

生成任务文档

python3 functions/implementation_planner.py \
  --task-id "TASK-{{next_task_number}}" \
  --feature-name "{{feature_name}}" \
  --analysis-results /tmp/combined_analysis.json \
  --review-reference ".agent/design-system/reviews/{{date}}-{{feature-slug}}.md" \
  --output .agent/tasks/TASK-{{next_task_number}}-{{feature-slug}}.md

任务文档包括：

• 分阶段实施（标记 → 原子 → 分子 → 有机体）
• 每阶段复杂性估计
• 验收标准清单
• 文件修改
• 测试策略
• 推出计划

创建设计审查报告

使用模板：templates/design-review-report.md

保存到：.agent/design-system/reviews/YYYY-MM-DD-{{feature-name}}.md

内容：

• 设计分析摘要
• 标记变更（新增/修改/删除）
• 组件变更（新增/扩展/重大变更）
• 设计系统影响
• 实施建议

---

第4步：任务分配

目标：创建任务并分配实施上下文

创建PM票据（如果配置）

**如果PM工具配置**（Linear, GitHub Issues, Jira）：
- 创建带有任务摘要的票据
- 链接到任务文档和设计审查
- 分配给前端开发人员或团队

**如果没有PM工具**：
- 跳过票据创建
- 任务文档作为真相来源

更新Navigator文档

**更新文件**：
1. `.agent/tasks/TASK-{{number}}-{{feature}}.md`（第3步创建）
2. `.agent/design-system/reviews/{{date}}-{{feature}}.md`（设计审查）
3. `.agent/DEVELOPMENT-README.md`（将任务添加到索引）

**使用TodoWrite跟踪实施阶段**

---

第5步：实施交接

目标：展示结果并获得用户决策

展示摘要

✅ 设计审查完成 {{Feature Name}}

**生成文档**：
- 设计审查：`.agent/design-system/reviews/{{date}}-{{feature}}.md`
- 实施计划：`.agent/tasks/TASK-{{number}}-{{feature}}.md`
{{#if pm_configured}}- PM票据：{{ticket_id}}（状态：准备开发）{{/if}}

**摘要**：
- 设计标记：{{new_count}} 新的，{{modified_count}} 修改
- 组件：{{new_components}} 新的，{{extend_components}} 扩展
- 预计时间：{{total_hours}} 小时
- 复杂性：{{complexity_level}}
{{#if breaking_changes}}- ⚠️ 重大变更：{{breaking_count}} 组件{{/if}}

**下一步**：
[1] 现在开始实施
[2] 先审查计划（加载任务文档）
[3] 修改计划后再开始

**推荐**：实施后，设置视觉回归测试：
  "为 {{components}} 设置视觉回归"

这确保了像素完美的实现，并防止未来的偏差（15分钟设置）。

回复选择或"开始实施"

用户决策分支

如果用户选择[1]或说"开始实施"：

1. 加载任务文档：`Read .agent/tasks/TASK-{{number}}-{{feature}}.md`
2. 加载设计审查：`Read .agent/design-system/reviews/{{date}}-{{feature}}.md`
3. 开始第1阶段（通常是设计标记）
4. 完成后遵循自动完成协议
5. 完成后，建议："为 {{components}} 设置视觉回归"（可选但推荐）

如果用户选择[2]：

1. 加载并显示任务文档
2. 突出关键阶段和验收标准
3. 问："准备好开始还是要修改？"

如果用户选择[3]：

1. 加载任务文档
2. 问需要什么修改
3. 编辑任务文档
4. 如果有重大更改则重新生成
5. 然后继续实施

---

预定义函数

functions/design_analyzer.py

目的：从Figma MCP数据或手动输入中提取设计模式

用法：

python3 functions/design_analyzer.py \
  --figma-data /path/to/figma_mcp_combined.json \
  --ui-kit-inventory .agent/design-system/ui-kit-inventory.json \
  --output /tmp/analysis.json

输入格式（figma_mcp_combined.json）：

{
  "metadata": { ... },  // get_metadata响应
  "variables": { ... }, // get_variable_defs响应
  "code_connect_map": { ... } // get_code_connect_map响应（可选）
}

输出：组件分析，包括分类（原子/分子/有机体）+相似度分数

---

functions/token_extractor.py

目的：将Figma变量转换为DTCG格式，并进行差异比较

用法：

python3 functions/token_extractor.py \
  --figma-variables /path/to/figma_variables.json \
  --existing-tokens .agent/design-system/design-tokens.json \
  --format full \
  --output /tmp/tokens.json

输出格式：

• full：DTCG标记+差异+摘要
• tokens-only：仅DTCG标记
• diff-only：仅差异和摘要

DTCG格式（W3C设计标记规范）：

{
  "color": {
    "primary": {
      "500": {
        "$value": "#3B82F6",
        "$type": "color",
        "$description": "主品牌颜色"
      }
    }
  }
}

---

functions/component_mapper.py

目的：将Figma组件映射到代码库组件

用法：

python3 functions/component_mapper.py \
  --figma-components /path/to/analysis_results.json \
  --code-connect-map /path/to/code_connect.json \
  --project-root . \
  --output /tmp/mappings.json

映射策略：

1. 首先代码连接（100%置信度）
2. 模糊名称匹配（70%+置信度）
3. 未映射=需要创建

输出：带有置信分数的映射+变体属性映射

---

functions/design_system_auditor.py

目的：审核设计系统以发现偏差和重用机会

用法：

python3 functions/design_system_auditor.py \
  --figma-data /path/to/combined_figma.json \
  --code-data /path/to/combined_code.json \
  --output /tmp/audit.json

审计检查：

• 标记对齐（偏差检测）
• 组件重用机会（相似度>70%）
• 未使用的标记（清理候选）
• 优先级分配

---

functions/implementation_planner.py

目的：生成带有分阶段细分的Navigator任务文档

用法：

python3 functions/implementation_planner.py \
  --task-id "TASK-16" \
  --feature-name "Dashboard Redesign" \
  --analysis-results /path/to/combined_analysis.json \
  --review-reference ".agent/design-system/reviews/2025-10-21-dashboard.md" \
  --output .agent/tasks/TASK-16-dashboard-redesign.md

输出：完整的Navigator任务文档，包括：

• 分阶段实施（原子设计顺序）
• 复杂性估计（低/中/高）
• 每阶段的验收标准
• 测试策略
• 推出计划

---

模板

templates/design-review-report.md

何时：第3步 - 创建设计审查文档

结构：

# 设计审查：{{Feature Name}}

**日期**：{{YYYY-MM-DD}}
**Figma**：[链接]({{figma_url}})
**审核员**：Navigator产品设计技能

## 新设计标记
[标记变更]

## 新增所需组件
[按类别列出组件列表]

## 设计系统影响
[高/中/低影响分析]

## 实施建议
[分阶段方法]

---

设计系统文档结构

初始设置（首次运行）

mkdir -p .agent/design-system/reviews

# 创建初始文件
touch .agent/design-system/design-tokens.json
touch .agent/design-system/ui-kit-inventory.json
touch .agent/design-system/component-mapping.json

design-tokens.json（DTCG格式）：

{
  "color": {},
  "spacing": {},
  "typography": {},
  "radius": {},
  "shadow": {}
}

ui-kit-inventory.json：

{
  "components": [
    {
      "name": "Button",
      "path": "src/components/ui/Button.tsx",
      "category": "atom",
      "variants": ["primary", "secondary", "ghost"],
      "figma_link": "..."
    }
  ],
  "tokens": {}
}

文件加载策略

永不加载：

• 所有设计审查报告（50+文件=250k+标记）
• 完整的Figma MCP响应（可能超过350k标记）

技能激活时始终加载：

• ui-kit-inventory.json（~3k标记）
• design-tokens.json（~2k标记）
• 当前任务的特定设计审查（~5k标记）

总计：~10k标记vs 150k+（93%减少）

---

Figma MCP集成

MCP服务器检测

在技能调用时：

1. 检查Figma MCP工具是否可用
2. 检测本地vs远程服务器
3. 根据能力调整工作流程

本地服务器（推荐）：

• URL：http://127.0.0.1:3845/mcp
• 工具：全部（元数据，变量，code_connect，design_context）
• 需要：运行中的Figma桌面应用程序

远程服务器（后备）：

• URL：https://mcp.figma.com/mcp
• 工具：有限（无code_connect，需要明确的URL）
• 需要：互联网连接，明确的Figma链接

处理标记限制

问题：大屏幕返回>350k标记（超过默认25k限制）

解决方案：

1. 首先使用`get_metadata`（稀疏XML，~5k标记）
2. 解析元数据以识别组件节点ID
3. 通过`get_design_context`逐个获取组件
4. 从多个小调用中聚合结果

**环境变量**（推荐）：
export MAX_MCP_OUTPUT_TOKENS=100000

MCP工具使用

get_metadata：始终首先用于大型设计

• 返回带有节点ID、类型、名称的稀疏XML
• 低标记成本（~5-10k）
• 用于规划组件提取策略

get_variable_defs：提取所有设计标记

• 一个调用即可获得所有变量
• 中等标记成本（~10-20k）
• 关键标记提取

get_code_connect_map：获取组件映射

• 需要Figma企业计划
• 返回node_id → code_path映射
• 最高置信度映射

get_design_context：提取组件代码

• 按组件使用（不要整个屏幕）
• 可以通过提示生成React/Vue/HTML
• 最高标记成本 - 谨慎使用

---

Tailwind CSS集成

设计标记 → Tailwind @theme

样式字典管道：

# 1. 标记提取到design-tokens.json（DTCG格式）
# 2. 运行样式字典构建
npx style-dictionary build

# 3. 生成tailwind-tokens.css
# @theme {
#   --color-primary-500: #3B82F6;
#   --spacing-md: 16px;
# }

# 4. Tailwind自动生成实用程序
# .bg-primary-500, .p-md, 等。

Figma自动布局 → Tailwind类

翻译规则（代码生成期间应用）：

方向：
  水平 → flex-row
  垂直 → flex-col

间距：
  Gap → gap-{token}
  Padding → p-{token}, px-{token}, py-{token}

对齐：
  开始 → items-start, justify-start
  中心 → items-center, justify-center
  空间之间 → justify-between

尺寸：
  拥抱 → w-auto / h-auto
  填充 → flex-1
  固定 → w-{value} / h-{value}

---

标记优化

Navigator原则

按需加载：

• 当前任务的设计审查
• UI工具包库存（始终需要）
• 设计标记（始终需要）

使用任务代理进行代码库搜索：

• 查找所有组件文件（节省60-80%标记）
• 在Tailwind配置中搜索标记使用情况
• 分析组件变体模式

完成后压缩：

• 设计审查后清除上下文
• 在标记中保留任务文档
• 实施新的清洁垫

---

故障排除

“Figma MCP工具未找到”

问题：MCP服务器不可用

解决方案：

1. 检查Figma桌面应用程序是否正在运行（对于本地服务器）
2. 验证是否添加了MCP服务器：claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
3. 回退到手动工作流程（仍然提供价值）

“标记限制超出”

问题：get_design_context响应过大

解决方案：

1. 首先使用get_metadata，然后逐个获取组件
2. 设置MAX_MCP_OUTPUT_TOKENS=100000
3. 在Figma中将设计分成较小的选择

“代码库中未找到组件”

问题：component_mapper.py找不到匹配项

解决方案：

1. 检查--project-root是否指向正确的目录
2. 验证组件文件扩展名（tsx, jsx, vue）
3. 检查组件是否在排除的目录中（node_modules）

“设计标记不在DTCG格式”

问题：现有标记使用旧格式

解决方案：

1. 使用token_extractor.py与--format tokens-only进行转换
2. 首先备份现有标记
3. 更新样式字典配置以读取DTCG格式

---

成功指标

效率提升

之前：每次设计交接6-10小时 之后：15-20分钟 节省：95%时间减少

质量指标

• 自动检测设计系统偏差
• 100%标记一致性通过自动同步
• 跟踪组件重用率
• 通过验收标准实现准确性

---

示例用法

用户："从Figma审查仪表板重新设计：https://figma.com/file/..."

Navigator：
1. 检查Figma MCP可用性
2. 提取元数据、变量、code_connect_map
3. 运行design_analyzer.py → 发现3个新组件，12个新标记
4. 运行token_extractor.py → 生成DTCG标记，发现5个漂移问题
5. 运行component_mapper.py → 映射2个组件，需要1个新的
6. 运行design_system_auditor.py → 优先级：高（检测到漂移）
7. 运行implementation_planner.py → 生成TASK-17，分为3个阶段
8. 创建设计审查报告
9. 提供摘要，带有[开始/审查/修改]选项

用户："开始实施"

Navigator：
1. 加载TASK-17文档
2. 开始第1阶段：设计标记
3. 使用12个新标记更新design-tokens.json
4. 运行样式字典构建
5. 更新Tailwind配置
6. 提交更改
7. 进入第2阶段：StatBadge组件
8. ... 通过所有阶段继续
9. 完成后自动完成

---

最后更新：2025-10-21 Navigator版本：3.2.0（目标） 技能版本：1.0.0