前端设计提取器

概述

通过清点UI来源、记录设计基础、分类组件以及捕捉页面级模式和行为，从前端代码库中提取可复用的UI/UX设计规范。排除业务逻辑和特定领域的工作流。框架无关：适应目标代码库的实际技术栈。

快速开始

1. 确认模式：新项目（绿地项目）还是重构现有项目。明确业务逻辑不在范围内。
2. 如果是现有代码库：运行scripts/scan_ui_sources.sh来扫描代码库根目录（不假设目录结构）。它默认使用通用的glob模式+关键词匹配，并忽略常见的构建/缓存目录和提取输出文件夹。
3. 可选地：scripts/scan_ui_sources.sh <repo_root> [out_file] [extra_glob ...]或--root/--out/--ignore用于非标准布局。
4. 通过以下命令创建输出文件夹（默认为./ui-ux-spec）：scripts/generate_output_skeleton.sh并将所有提取结果写入其中。
5. 按默认结构（参见“输出结构”）生成输出。

模式（选择其一）

A) 绿地模式（从零开始）

目标：创建一个可复用的UI/UX基础和起始UI，不包含业务逻辑。

1. 定义基础：设计令牌（颜色/字体/间距/圆角/阴影/动效）、全局样式、断点、布局框架。
2. 创建基础组件集：按钮、输入框、选择器、卡片、模态框、表格/列表、标签页、提示条、空状态。
3. 创建页面模板：列表/详情/表单/仪表板骨架，使用占位数据。
4. 为目标框架提供实现说明（CSS架构、主题机制、文件结构）。
5. 可选运行scripts/generate_output_skeleton.sh [out_root]以搭建文件夹和空模板。默认输出根目录为./ui-ux-spec。

交付物：

• 设计令牌文档 + 全局样式规范
• 组件目录，包含变体/状态/无障碍性
• 具有布局规则的页面模板
• 工程约束（命名、CSS方法、主题化）

B) 重构现有项目

目标：提取当前的UI/UX，规范化设计标记，并规划安全、渐进式的改进。

1. 清点UI来源（扫描脚本 + 人工检查）。
2. 规范化设计标记，并将现有样式映射到它们。
3. 识别第一批次的高影响力组件/模式。
4. 规划最小化差异的迁移方案（包装器、主题适配器、逐步替换）。
5. 记录行为和可访问性差距，以便逐步修复。

交付成果：

• 提取的设计规范（与绿地项目相同）
• 迁移计划（分阶段、低风险的步骤）
• 逐个组件的映射说明

根据规范进行重构（固定流程）

在将现有的ui-ux-spec/应用到目标项目时使用此方法。始终按计划工作并逐步执行，以避免遗漏。

0) 理解目标项目

• 确定框架、样式系统、组件库使用情况以及入口点。
• 确认约束条件：仅涉及UI/UX，不触及业务逻辑。
• 除非明确要求，否则保持现有项目结构不变。

1) 制定重构计划（必需）

• 对比规范 → 当前项目，并按类别列出差异：
  • 设计令牌与全局样式
  • 组件（按优先级排序）
  • 模式与页面
  • 无障碍访问性差距
• 不要假设规范文件夹结构与目标项目匹配。根据内容而非路径进行映射。
• 制定分阶段计划（阶段1：设计令牌，阶段2：基础组件，阶段3：页面等）。
• 在计划被接受之前，不要进行编辑操作。

2) 分阶段执行

• 仅应用当前阶段的更改。
• 每个阶段完成后，重新对照规范进行检查。
• 保持改动最小化且可逆。
• 不要重组文件夹或移动文件；在原位置进行更新。

3) 总结与验证

• 提供变更清单和剩余缺口。
• 当前阶段完成后，再建议下一阶段。

重构提示词模板

使用以下模板之一，以保持请求的精确性和计划驱动性。

模板 A：标准重构

Please refactor the existing project based on this UI/UX spec:
- Project path: /path/to/target-project
- Spec path: /path/to/ui-ux-spec
- Goal: UI/UX only (tokens, styles, components, layout), do not change business logic/APIs
- Scope: start with global styles + base components
- Constraints: minimal changes, small-step commits, reversible
- Deliverables: refactor plan + actual code changes + list of impacted files

模板 B：分阶段重构

Please refactor UI/UX in phases; only do Phase 1:
- Project path: /path/to/target-project
- Spec path: /path/to/ui-ux-spec
- Phase 1: align tokens + global styles (colors/typography/spacing/radius/shadows)
- Do not change: business logic/routing/APIs
- Deliverables: list of changed files + alignment diff notes

模板 C：组件级重构

Please align the following components to the spec while keeping business logic unchanged:
- Project path: /path/to/target-project
- Spec path: /path/to/ui-ux-spec
- Component list: Button, Input, Modal, Table
- Goal: only change styling/structure/interaction details
- Deliverables: alignment notes per component + code changes

工作流程

0) 范围和约束

• 确认仓库根目录、框架以及任何设计系统包。
• 确认期望的输出格式（默认为 Markdown）。
• 询问约束条件：必须遵守的品牌规则、目标平台和可访问性级别。
• 再次确认：排除业务逻辑、业务规则和领域工作流。
• 不要假设特定的前端框架或语言；需适应项目的技术栈。

1) 源代码清单（仅针对现有仓库）

• 不要假设固定的目录结构；扫描结果应指导读取位置。
• 运行扫描脚本并检查结果，关注：
  • 代币/主题、全局样式、主题提供者
  • 组件库和本地包装器
  • Storybook、文档或视觉回归测试
  • 资源文件和国际化源文件

2) 基础部分（代币 + 全局样式）

• 记录颜色、排版、间距、圆角、阴影、z轴层级和动效代币。
• 记录重置/标准化样式、body默认值、链接/表单默认值、焦点可见样式、滚动条样式。

3) 布局与信息架构

• 记录断点、容器、网格规则、导航结构和布局外壳。

4) 组件目录

• 针对每个组件，记录：用途、结构/插槽、变体、状态、交互、无障碍性、响应式行为、动效和主题挂钩。
• 如果使用第三方库，重点关注本地包装组件和覆盖样式。

5) 页面模板与组合规则

• 提取页面框架（列表/详情/表单/仪表板等）和模块排列顺序。
• 记录组合状态：加载/空状态/错误/权限/只读。

6) 行为与内容规则

• 捕获加载与错误处理策略、验证模式、撤销/乐观更新。
• 捕获微文案约定与国际化（i18n）格式限制。

7) 打包输出

• 至少生成：
  • 设计令牌文档
  • 组件目录
  • 页面模板
• 确保输出内容写入专用文件夹（默认ui-ux-spec/）。
• 除非用户要求其他布局，否则请使用以下输出结构。

输出结构（默认）

此结构是推荐的文档布局。它不需要与目标项目的目录结构完全匹配，可以重命名或重新定位（例如，docs/ui-ux-spec/）。

ui-ux-spec/
  01_Foundation/
  02_Components/
  03_Patterns/
  04_Pages/
  05_A11y/
  06_Assets/
  07_Engineering_Constraints/

资源

• scripts/scan_ui_sources.sh：在代码仓库中查找候选UI源文件。
• scripts/generate_output_skeleton.sh创建标准输出文件夹和占位模板。
• references/design-extraction-checklist.md: 从README派生出的详细检查清单。