介绍
# Frontend Design Extractor
## 概述 通过盘点 UI 源码、记录基础规范、编录组件以及捕获页面级模式和交互行为，从前端代码库中提取可复用的 UI/UX 设计规范。排除业务逻辑和特定领域的工作流。框架无关：适配目标仓库中的实际技术栈。
## 快速开始 1) 确认模式：新项目 还是重构现有项目。明确业务逻辑不在范围之内。 2) 如果是现有仓库：运行 `scripts/scan_ui_sources.sh` 扫描仓库根目录（不假设目录布局）。它使用通用的通配符和关键词匹配，默认忽略常见的构建/缓存目录和提取输出文件夹。 3) 可选操作：`scripts/scan_ui_sources.sh <repo_root> [out_file] [extra_glob ...]` 或使用 `--root/--out/--ignore` 适用于非标准布局。 4) 通过 `scripts/generate_output_skeleton.sh` 创建输出文件夹（默认为 `./ui-ux-spec`），并在其中写入所有提取结果。 5) 按照默认结构生成输出（参见“输出结构”）。
## 模式（选择其一）
### A) 绿地项目（从零开始） 目标：创建不包含业务逻辑的可复用 UI/UX 基础和初始 UI。
1) 定义基础：Design Tokens（颜色/排版/间距/圆角/阴影/动效）、全局样式、断点、布局外壳。 2) 创建基准组件集：Button、Input、Select、Card、Modal、Table/List、Tabs、Toast、EmptyState。 3) 创建页面模板：包含占位数据的列表/详情/表单/仪表盘骨架。 4) 提供目标框架的实现说明（CSS 架构、主题机制、文件结构）。 5) 可选：运行 `scripts/generate_output_skeleton.sh [out_root]` 来搭建文件夹和空模板。默认输出根目录为 `./ui-ux-spec`。
交付物： - Design Tokens 文档 + 全局样式规范 - 包含变体/状态/无障碍特性的组件目录 - 包含布局规则的页面模板 - 工程约束（命名、CSS 方案、主题）
### B) 重构现有项目 目标：提取当前的 UI/UX，规范化 Design Tokens，并规划安全、渐进式的改进。
1) 盘点 UI 源码（扫描脚本 + 人工检查）。 2) 规范化 Design Tokens 并将现有样式映射到它们。 3) 识别第一轮优先处理的高影响力组件/模式。 4) 规划迁移方案以最小化差异（包装器、主题适配器、逐步替换）。 5) 记录行为和需要逐步修复的无障碍缺口。
交付物： - 提取的设计规范（同绿地项目） - 迁移计划（分阶段、低风险步骤） - 逐组件映射说明
## 基于规范的重构（固定流程） 将现有的 `ui-ux-spec/` 应用于目标项目时使用此流程。始终按照计划一步步执行，避免遗漏缺口。
### 0) 理解目标项目 - 识别框架、样式系统、组件库的使用情况以及入口点。 - 确认约束：仅限 UI/UX，不触及业务逻辑。 - 保持现有项目结构不变，除非明确要求。
### 1) 制定重构计划（必需） - 对比规范 → 当前项目，按类别列出差异： - Tokens 和全局样式 - 组件（按优先级排序） - 模式和页面 - 无障碍缺口 - 不要假设规范文件夹结构与目标项目匹配。按内容而非路径进行映射。 - 生成分阶段计划（第一阶段 tokens，第二阶段基础组件，第三阶段页面等）。 - 在计划被接受之前不要进行编辑。
### 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) 源码盘点（仅限现有仓库） - 不要假设固定的目录结构；扫描结果应指导读取位置。 - 运行扫描脚本并检查结果以查找： - tokens/themes、全局样式、主题提供者 - 组件库和本地包装组件 - Storybook、文档或视觉回归测试 - 资源和 i18n 源码
### 2) 基础（tokens + 全局样式） - 记录颜色、排版、间距、圆角、阴影、z-index 和 motion tokens。 - 捕获重置/归一化、body 默认值、链接/表单默认值、focus-visible、滚动条。
### 3) 布局与信息架构 - 记录断点、容器、网格规则、导航结构和布局外壳。
### 4) 组件目录 - 对于每个组件，捕获：用途、结构/插槽、变体、状态、交互、无障碍、响应式行为、动效和主题钩子。 - 如果使用了第三方库，重点关注本地包装组件和覆盖。
### 5) 页面模板与组合规则 - 提取页面骨架（列表/详情/表单/仪表盘等）和模块顺序。 - 捕获组合状态：加载/空/错误/权限/只读。
### 6) 行为与内容规则 - 捕获加载和错误策略、验证模式、撤销/乐观更新。 - 捕获微文案约定和 i18n 格式约束。
### 7) 打包输出 - 至少生成： - Design Tokens 文档 - 组件目录 - 页面模板 - 确保输出写入专用文件夹（默认为 `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 的详细检查清单。