前端设计提取器

概述

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

快速开始

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) 从零开始（绿field）

目标：创建无业务逻辑的可复用 UI/UX 基础与初始界面。

1) 定义设计基础：设计令牌（颜色/排版/间距/圆角/阴影/动效）、全局样式、断点、布局骨架。

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。

交付物：

• 设计令牌文档 + 全局样式规范
• 包含变体/状态/无障碍支持的组件目录
• 带有布局规则的页面模板
• 工程约束说明（命名规范、CSS 方案、主题机制）

B) 重构现有项目

目标：提取当前 UI/UX，统一设计令牌，并规划安全、渐进式的改进。

1) 盘点 UI 资源（扫描脚本 + 手动检查）。

2) 统一设计令牌，并将现有样式映射到这些令牌。

3) 识别高影响组件/模式，作为第一轮优化重点。

4) 制定迁移方案，以最小差异（包装器、主题适配器、逐步替换）推进。

5) 记录需逐步修复的行为与无障碍缺陷。

交付物：

• 提取的设计规范（同绿field模式）
• 迁移计划（分阶段、低风险步骤）
• 组件级映射说明笔记

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

当将已有的 ui-ux-spec/ 应用于目标项目时使用。始终基于计划执行，逐步操作，避免遗漏问题。

0) 理解目标项目

• 识别框架、样式系统、组件库使用情况及入口点。
• 确认约束：仅限 UI/UX 改动，业务逻辑保持不变。
• 除非特别要求，否则保持原有项目结构不变。

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

• 对比规范 → 当前项目，按类别列出差异：

- 设计令牌与全局样式

- 组件（优先级排序）

- 模式与页面

- 无障碍缺陷

• 不假设规范文件夹结构与目标项目一致。应根据内容而非路径进行映射。
• 生成分阶段计划（如：第1阶段统一令牌，第2阶段基础组件，第3阶段页面等）。
• 未经计划确认前不得开始修改。

2) 分阶段执行

• 仅应用当前阶段的变更。
• 每阶段完成后重新核对规范。
• 保持变更量小且可逆。
• 不得重排文件夹或移动文件；原地更新。

3) 总结与验证

• 提供变更清单与剩余缺口。
• 仅在当前阶段完成后建议下一阶段。

重构提示模板

使用以下任一模板以确保请求清晰且基于计划。

模板 A：标准重构

请根据以下 UI/UX 规范重构现有项目：
- 项目路径：/path/to/target-project
- 规范路径：/path/to/ui-ux-spec
- 目标：仅限 UI/UX（令牌、样式、组件、布局），不得改动业务逻辑/API
- 范围：从全局样式 + 基础组件开始
- 约束：变更最小化、小步提交、可逆
- 交付物：重构计划 + 实际代码变更 + 受影响文件列表

模板 B：分阶段重构

请分阶段重构 UI/UX；仅执行第1阶段：
- 项目路径：/path/to/target-project
- 规范路径：/path/to/ui-ux-spec
- 第1阶段：对齐设计令牌与全局样式（颜色/排版/间距/圆角/阴影）
- 不得更改：业务逻辑/路由/API
- 交付物：变更文件列表 + 对齐差异说明

模板 C：组件级重构

请将以下组件对齐至规范，同时保持业务逻辑不变：
- 项目路径：/path/to/target-project
- 规范路径：/path/to/ui-ux-spec
- 组件列表：Button、Input、Modal、Table
- 目标：仅修改样式/结构/交互细节
- 交付物：每个组件的对齐说明 + 代码变更

工作流程

0) 明确范围与约束

• 确认仓库根路径、所用框架及设计系统相关包。
• 确认期望输出格式（默认为 Markdown）。
• 询问约束条件：必须保留的品牌规则、目标平台、无障碍等级。
• 再次确认：排除业务逻辑、业务规则及领域工作流。
• 不预设特定前端框架或语言；根据项目实际技术栈灵活适配。

1) 资源盘点（仅适用于现有仓库）

• 不假设固定目录结构；扫描结果应指导阅读位置。
• 运行扫描脚本并检查结果，重点关注：

- 设计令牌/主题、全局样式、主题提供者

- 组件库及本地封装

- Storybook、文档或视觉回归测试

- 资源文件与国际化源

2）基础规范（设计令牌与全局样式）

• 记录文档中的颜色、排版、间距、圆角、阴影、z-index 及动效相关的设计令牌。
• 捕获重置/归一化样式、页面默认设置、链接与表单默认行为、focus-visible 样式、滚动条样式。

3）布局与信息架构

• 记录断点设置、容器规范、网格规则、导航结构及布局模板。

4）组件库

• 每个组件需记录：用途、结构/插槽、变体、状态、交互行为、无障碍支持、响应式表现、动效设计以及主题化钩子。
• 若使用第三方库，重点聚焦于本地封装组件及自定义覆盖部分。

5）页面模板与组合规则

• 提取页面骨架（列表页、详情页、表单页、仪表盘等）及模块排列顺序。
• 记录组合状态：加载中、空状态、错误状态、权限限制、只读模式等。

6）行为与内容规则

• 记录加载与错误处理策略、校验模式、撤销操作与乐观更新机制。
• 记录微文案规范及国际化格式约束。

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 的详细提取检查清单。