ui-analyzer

UI 分析器

此技能提供了一套系统化的方法，用于分析 UI 设计截图，并使用 TypeScript 和 Tailwind CSS 将其转换为可用于生产环境的 React 组件。

用途

将 UI 设计截图转换为结构清晰、易于访问且易于维护的 React 组件。此技能将引导你分析布局、提取设计令牌、识别组件，并生成简洁的代码，在遵循最佳实践的同时还原设计。

何时使用此技能

在以下情况下使用此技能：

• 用户提供 UI 设计截图、模型图或 Figma 导出文件
• 用户要求“实现此设计”或“构建此 UI”
• 用户要求“分析此截图”
• 用户想将设计转换为代码
• 用户需要帮助理解 UI 的结构
• 用户要求匹配现有设计

分析工作流

分析 UI 截图时，请按以下步骤系统地进行：

第 1 步：初步观察和截图阅读

如果用户提供了文件路径，或在对话中分享了图片，请先使用 Read 工具阅读提供的截图。

查看截图后：

1. 描述你在 UI 中看到的内容
2. 识别屏幕／页面类型（登录、仪表板、表单等）
3. 确定目标设备（桌面设备、移动设备、自适应布局）
4. 记录整体风格（现代、极简、色彩丰富等）
5. 继续之前先与用户确认你的理解

第 2 步：布局分析

识别高层布局结构：

1. 主要布局类型 - 参考 references/layout-patterns.md 进行识别：

   • 单列
   • 侧边栏布局
   • 页眉 + 内容
   • 网格布局
   • 分屏
   • 仪表板
   • 主从布局
   • 其他模式

2. 布局层级 - 拆分为以下区域：

   • 页眉／导航
   • 主要内容区域
   • 侧边栏（如有）
   • 页脚（如有）
   • 嵌套结构

3. 自适应布局注意事项：

   • 布局应如何适配移动设备？
   • 哪些元素应堆叠或隐藏？
   • 断点策略

参考 references/layout-patterns.md 获取 Tailwind 实现模式。

第 3 步：识别组件

使用 references/ui-analysis-checklist.md 系统地识别所有 UI 组件：

导航组件：

• 顶部导航、侧边栏导航、面包屑、选项卡等

数据展示组件：

• 卡片、表格、列表、统计信息、徽章、头像、图标等

输入组件：

• 文本输入框、选择框、复选框、单选框、开关、日期选择器等

操作组件：

• 按钮（主要、次要等）、图标按钮、链接等

反馈组件：

• 警告提示、Toast、进度条、加载状态等

浮层组件：

• 模态框、抽屉、工具提示、弹出层、下拉菜单等

列出所有已识别的组件，并注明：

• 组件类型和用途
• 在布局中的位置
• 大致尺寸和样式
• 交互状态（如可见）

步骤 4：提取设计令牌

使用 references/design-tokens.md 提取设计系统的值：

配色方案：

1. 识别设计中所有不重复的颜色
2. 按用途分类：
   • 品牌主色
   • 辅助色／强调色
   • 背景色（主背景、次要背景）
   • 文本颜色（主要、次要、弱化）
   • 边框颜色
   • 状态颜色（成功、警告、错误、信息）
3. 将每种颜色映射到最接近的 Tailwind 颜色，或注明需要自定义颜色
4. 创建颜色参考表

排版：

1. 识别字体系列（衬线、无衬线、等宽）
2. 列出观察到的所有文本字号
3. 映射到 Tailwind 排版比例（text-xs 到 text-6xl）
4. 记录使用的字重（常规、中等、半粗、粗体）
5. 识别标题层级（H1-H6）

间距：

1. 观察内边距模式（卡片内边距、按钮内边距等）
2. 观察外边距／间隔模式（区块之间、项目之间）
3. 映射到 Tailwind 间距比例（p-4、m-6、gap-8 等）
4. 记录间距单位（通常以 4px 或 8px 为基准）

其他令牌：

• 边框圆角（从 rounded-none 到 rounded-full）
• 阴影（从 shadow-sm 到 shadow-2xl）
• 边框宽度
• 图标尺寸

请参阅 references/design-tokens.md 中的完整映射表。

步骤 5：详细分析组件

针对识别出的每个主要组件：

1. 组件边界——从哪里开始／到哪里结束？
2. 属性／数据——接收哪些数据？
3. 内部结构——子组件和元素
4. 样式细节：
   • 背景颜色
   • 文本颜色和字号
   • 内边距和外边距
   • 边框和圆角
   • 阴影
5. 交互状态（如果可见或可推断）：
   • 悬停
   • 激活／按下
   • 聚焦
   • 禁用
   • 加载中
   • 错误
6. 无障碍需求：
   • ARIA 标签
   • 语义化 HTML
   • 键盘导航

步骤 6：实现策略

规划实现方式：

1. 组件层级——应先构建哪些组件？
2. 可复用性——哪些模式会重复出现？将其提取为可复用组件
3. 状态管理——组件是否需要 Zustand，还是使用局部状态即可？
4. 与 react-component-generator 集成——能否使用现有模板？
5. 文件结构——组件应放在哪里？

如果 react-component-generator 技能可用：

• 参考其常见组件模板（表单、卡片、按钮、模态框等）
• 使用其组件结构最佳实践
• 遵循其命名约定

步骤 7：生成代码

按照以下原则生成 React 组件：

结构：

1. 先为属性编写 TypeScript 接口
2. 使用带有 React.FC 的函数组件
3. 添加 JSDoc 注释
4. 同时导出具名导出和默认导出

样式：

1. 仅使用 Tailwind CSS 进行样式设计
2. 应用提取出的设计令牌
3. 按逻辑组织类名（布局 → 间距 → 颜色 → 效果 → 状态）
4. 在需要时使用响应式类（sm:、md:、lg:、xl:）

最佳实践：

1. 使用语义化 HTML 元素
2. 添加 ARIA 属性以满足无障碍需求
3. 处理加载和错误状态
4. 支持键盘导航
5. 使用恰当的 TypeScript 类型（不要使用 any）
6. 保持组件专注且易于组合

组件模板示例：

import React from 'react';

interface ComponentNameProps {
  // Props based on analysis
  title: string;
  description?: string;
  onClick?: () => void;
  className?: string;
}

/**
 * ComponentName - Brief description based on UI purpose
 *
 * @param props - Component props
 * @returns JSX.Element
 */
export const ComponentName: React.FC<ComponentNameProps> = ({
  title,
  description,
  onClick,
  className = ''
}) => {
  return (
    <div className={`/* Tailwind classes from design */ ${className}`}>
      {/* Implementation based on screenshot */}
    </div>
  );
};

export default ComponentName;

步骤 8：验证和完善

生成代码后：

1. 对照截图检查——是否符合设计？
2. 检查响应式效果——能否适配不同屏幕尺寸？
3. 验证无障碍性——是否包含 ARIA 标签和语义化 HTML？
4. 验证设计令牌——颜色、间距和排版是否正确？
5. 考虑边缘情况——长文本、空状态、加载状态
6. 注明假设——明确说明哪些内容是推测的，哪些已确认

第 9 步：交付内容

向用户提供：

1. 分析摘要：

   • 布局描述
   • 组件拆解
   • 提取的设计令牌

2. 生成的代码：

   • 完整的 React 组件
   • TypeScript 接口
   • 应用的 Tailwind 类

3. 实现说明：

   • 安装要求（如需安装软件包）
   • 使用示例
   • 自定义建议
   • 响应式行为说明

4. 后续步骤：

   • 建议改进或变体
   • 指出可能需要调整的部分
   • 提供生成其他相关组件的帮助

常见场景

场景 1：简单表单截图

用户：“实现这个登录表单设计 [截图]”

方法：

1. 查看截图
2. 识别：包含表单输入框和按钮的居中卡片布局
3. 提取：颜色、输入框样式、按钮样式、间距
4. 参考 layout-patterns.md →“居中弹窗／卡片”模式
5. 参考 react-component-generator → FormComponent 模板
6. 生成：结构规范的 LoginForm.tsx，并包含验证
7. 应用与设计相符的 Tailwind 类

场景 2：仪表盘截图

用户：“构建这个仪表盘 UI [截图]”

方法：

1. 查看截图
2. 识别：包含网格状统计卡片的页眉 + 侧边栏布局
3. 拆分为多个组件：
   • 页眉组件
   • 侧边栏导航
   • StatCard 组件（重复使用）
   • 仪表盘主体布局
4. 提取设计令牌，确保风格一致
5. 参考 layout-patterns.md →“仪表盘布局”模式
6. 从可复用的 StatCard 开始生成组件
7. 将组件组合成主 Dashboard 组件

场景 3：包含多个部分的复杂页面

用户：“实现这个落地页 [截图]”

方法：

1. 查看截图
2. 识别各个部分：主视觉区、功能网格、用户评价、行动号召
3. 使用清单分别分析每个部分
4. 提取共享的设计令牌
5. 逐个生成各部分组件
6. 展示如何将各个部分组合成完整页面
7. 提供响应式行为说明

场景 4：组件库截图

用户：“根据这张设计系统截图创建组件 [截图]”

方法：

1. 查看截图
2. 识别：展示了多种按钮、输入框和卡片变体
3. 提取系统的设计令牌
4. 生成每个组件变体
5. 记录 prop 变体
6. 创建使用指南
7. 建议如何在项目中组织这些组件

参考文件的用法

references/ui-analysis-checklist.md

• 何时使用：第 3 步（组件识别）期间，以及作为全面的分析指南
• 用途：确保不遗漏任何组件或细节
• 方法：系统地逐项检查清单中的各个部分

references/layout-patterns.md

• 何时使用：第 2 步（布局分析）和第 7 步（代码生成）期间
• 用途：快速识别常见模式并获取实现代码
• 方法：将观察到的布局与模式匹配，并根据提供的代码进行调整

references/design-tokens.md

• 何时使用：第 4 步（设计令牌提取）和第 7 步（代码生成）期间
• 用途：准确地将视觉元素映射到 Tailwind 类
• 方法：使用颜色表、间距比例和组件尺寸指南

准确分析的技巧

1. 系统化分析——按顺序执行工作流步骤，不要跳步
2. 测量尺寸——仔细估算尺寸和间距
3. 寻找规律——重复出现的元素表明设计系统风格一致
4. 标注不确定之处——清楚区分假设与已确认的细节
5. 考虑响应式设计——始终考虑移动设备上的表现
6. 优先考虑无障碍性——从一开始就加入 ARIA 标签和语义化 HTML
7. 遵循 DRY 原则——在模式重复时提取可复用组件
8. 查阅参考资料——充分使用参考文件，确保准确性
9. 与用户确认——大量生成代码前，先确认理解无误
10. 迭代优化——根据用户反馈进行调整

与其他技能集成

与 react-component-generator 技能配合使用

当这两项技能都可用时：

1. 使用 ui-analyzer 理解设计并提取需求
2. 参考 react-component-generator 模板中的类似组件
3. 将 ui-analyzer 提取的设计令牌应用到模板中
4. 遵循 react-component-generator 的命名和结构约定

这将打造一套强大的工作流：分析 → 确定模板 → 自定义 → 实现。

完整工作流示例

用户提供登录页面截图

1. ✅ 阅读截图并描述 UI
2. ✅ 确定：居中卡片布局，带图片的分屏布局
3. ✅ 提取设计令牌：
   • 主蓝色：#3B82F6 → bg-blue-500
   • 文本：#1F2937 → text-gray-800
   • 背景：#F9FAFB → bg-gray-50
   • 卡片内边距：约 32px → p-8
   • 输入框高度：约 40px → h-10
   • 按钮：蓝色背景、白色文本、圆角 md
4. ✅ 确定组件：
   • Logo/品牌元素
   • 标题和副标题
   • 电子邮件输入框（带标签）
   • 密码输入框（带标签和显示/隐藏图标）
   • “记住我”复选框
   • “忘记密码？”链接
   • 提交按钮
   • 底部的注册链接
5. ✅ 参考 layout-patterns.md → 分屏 + 居中卡片模式
6. ✅ 生成 LoginForm.tsx：
   • 用于 props 的 TypeScript 接口
   • 表单验证结构
   • 与设计匹配的 Tailwind 类
   • 无障碍属性
   • 响应式行为（在移动端堆叠显示）
7. ✅ 提供用法示例和说明
8. ✅ 提出生成配套图片区域或调整样式

注意事项

• 在进行任何分析前，始终先阅读截图
• 大量生成代码前，优先请用户确认是否理解正确
• 不确定颜色或间距时，选择最接近的 Tailwind 默认值
• 清晰记录所有假设
• 提供完整、可运行的代码，而不是伪代码
• 在匹配设计的同时，考虑提出改进建议
• 根据用户反馈做好迭代准备