# 先马 AI 设计平台
## 前端 UI 规范与需求说明 V1.1

本文档用于指导开发统一实现前端框架、首页、子页面与公共组件。目标不是"每个页面各做一套"，而是先把框架和通用交互抽出来，后续子页面只接业务数据和业务逻辑。

本次修订（V1.1）依据平台内置的 UI 规范页（顶部右侧「UI 样式」入口，对应 `src/app/ui-guide/page.js`）与设计令牌文件 `src/app/globals.css`，补齐了色彩、字体、间距、圆角、阴影等设计令牌，以及各基础组件的尺寸与状态规范，供开发直接落地。

## 0. 当前状态

- 本文档基于当前已调整完成的原型页面与内置 UI 规范页整理，适合作为前端开发实现依据。
- 当前为前端原型验证稿，已验证买家秀、商品套图两个页面的统一框架、图片队列、素材选择、大图预览、下载等交互。
- 其中图片队列、素材弹窗、大图预览、任务详情下载等交互，均以当前原型确认结果为准；接口、真实素材库、权限、埋点和任务数据仍需开发阶段对接确认。
- 所有设计令牌以 `src/app/globals.css` 中的 CSS 变量为唯一取值来源。文档中的色值仅供查阅，开发时一律引用 CSS 变量，不得硬编码十六进制值。
- 若后续原型再改动，应同步更新本文档，避免开发按旧稿返工。
- 顶部右侧的「UI 样式」入口会进入 `src/app/ui-guide/page.js`，是当前设计系统与组件规范的可交互样例，不属于业务子页面。开发时应对照该页面核对实现效果。

## 1. 目标

1. 首页不再重复堆叠所有能力模块，改为"最近使用 + 入口导航"。
2. 所有子页面遵循统一框架，保持顶部导航、侧边栏、面包屑、状态标签、内容区结构一致。
3. 画像、素材、预览、队列、下载、任务详情等通用能力抽为公共组件，避免每个子页面重复实现。
4. 后续修改一级菜单、面包屑、图片队列、大图预览等，只改公共组件或全局配置即可全局生效。

## 2. 技术栈与工程约定

- 框架：Next.js 16（App Router，Turbopack）+ React 19。
- 样式：Tailwind CSS v4 + `@theme` 内联令牌；组件基于 shadcn/ui（Base UI）。
- 图标：`lucide-react`，统一线性图标风格。
- 语言：项目使用 JavaScript（`.js` / `.jsx`），路径别名见 `jsconfig.json`。
- 设计令牌集中定义在 `src/app/globals.css` 的 `:root` 与 `@theme inline` 中，全局生效。
- 导航、路由、层级、状态是单一数据源，集中在 `src/config/navigation.js`，不得散落到各页面组件。

## 3. 设计令牌（Design Tokens）

所有取值以 `src/app/globals.css` 为准，开发一律引用 CSS 变量，禁止硬编码色值。

### 3.1 主题色（蓝色系）

仅用于主题、主操作、选中态、焦点态。大面积背景保持白色或浅中性色。

| 名称 | 变量 | 取值 | 用途 |
| --- | --- | --- | --- |
| Primary | `--brand-primary` | `#2563EB` | 主按钮、选中态、强调 |
| Primary Hover | `--brand-primary-hover` | `#1D4ED8` | Hover 加深 |
| Primary Active | `--brand-primary-active` | `#1E40AF` | 按下态 |
| Primary Deep | `--brand-primary-deep` | `#0F2F6F` | 深色强调 |
| Primary Soft | `--brand-primary-soft` | `rgba(37,99,235,0.08)` | 选中背景、标签底 |
| On Primary | `--brand-on-primary` | `#FFFFFF` | 主色上的文字 |

### 3.2 中性色

从浅到深 11 档灰度。`--gray-900` 用于标题，`--gray-700` 用于正文，`--gray-500` 用于辅助文字，`--gray-400` 用于禁用文字。

| 变量 | 取值 | 变量 | 取值 |
| --- | --- | --- | --- |
| `--gray-25` | `#FCFCFD` | `--gray-500` | `#667085` |
| `--gray-50` | `#F7F8FA` | `--gray-600` | `#475467` |
| `--gray-100` | `#F2F4F7` | `--gray-700` | `#344054` |
| `--gray-200` | `#E4E7EC` | `--gray-800` | `#1D2939` |
| `--gray-300` | `#D0D5DD` | `--gray-900` | `#101828` |
| `--gray-400` | `#98A2B3` | | |

### 3.3 语义文本与背景色

| 变量 | 取值 / 引用 | 用途 |
| --- | --- | --- |
| `--text-title` | `--gray-900` | 标题 |
| `--text-body` | `--gray-700` | 正文 |
| `--text-secondary` | `--gray-500` | 辅助文字 |
| `--text-disabled` | `--gray-400` | 禁用文字 |
| `--bg-body` | `#F5F7FA` | 页面底色 |
| `--bg-card` | `#FFFFFF` | 卡片底 |
| `--bg-hover` | `#F2F4F7` | Hover 底 |
| `--border-base` | `#E4E7EC` | 常规边框 |
| `--border-light` | `#F2F4F7` | 浅分隔线 |

### 3.4 状态色

语义色，仅用于表达操作结果和状态反馈，配对使用「前景色 + 浅底色」。

| 状态 | 前景变量 / 取值 | 浅底变量 / 取值 |
| --- | --- | --- |
| 成功 Success | `--success` `#16A34A` | `--success-bg` `#EAF8F1` |
| 警告 Warning | `--warning` `#F59E0B` | `--warning-bg` `#FFF6E5` |
| 失败 Danger | `--danger` `#DC2626` | `--danger-bg` `#FEF3F2` |
| 信息 Info | `--info` `#0EA5E9` | `--info-bg` `#EFF6FF` |

### 3.5 字体与文本层级

字体栈：`Inter → system-ui → PingFang SC → Microsoft YaHei`（见 `--font-sans`）。正文默认 14px / 行高 1.5。

| 层级 | 字号 / 字重 | 用途 |
| --- | --- | --- |
| Display | 28px / 700 | 统计大数 |
| H1 | 22px / 600 | 页面标题 |
| H2 | 20px / 600 | 页面主要分区标题 |
| H3 | 16px / 600 | 卡片、面板标题 |
| Body | 14px / 400 | 默认正文 |
| Body Medium | 14px / 500 | 按钮、标签文字 |
| Small | 12px / 400 | 辅助说明、时间、角标 |

### 3.6 间距（4px 栅格）

所有间距为 4 的倍数，页面主区块之间统一 24px（`mb-6`）。

| 变量 | 取值 | 典型用途 |
| --- | --- | --- |
| `--space-1` | 4px | 标签之间、图标与文字 |
| `--space-2` | 8px | 表单项之间 |
| `--space-3` | 12px | 模块内边距 |
| `--space-4` | 16px | 卡片内边距、卡片间距 |
| `--space-6` | 24px | 页面主区块之间 |
| `--space-8` | 32px | 大分区之间 |

### 3.7 圆角

| 变量 | 取值 | 用途 |
| --- | --- | --- |
| `--radius-sm` | 6px | 标签、小元素 |
| `--radius-md` | 8px | 按钮、输入框 |
| `--radius-lg` | 16px | 卡片、面板、弹窗 |
| `--radius-xl` | 18px | 大号下拉面板 |
| `--radius-pill` | 999px | 胶囊、头像、状态点 |

### 3.8 阴影与焦点环

- `--shadow-card`：常规工作台卡片/面板阴影。
- `--shadow-card-hover`：Hover 态阴影，配合微上移 2px。
- `--focus-ring`：`0 0 0 3px rgba(37,99,235,0.14)`，所有可聚焦控件 `:focus-visible` 统一使用。
- 规则：卡片「阴影 / 边框」二选一，不叠加。可点击卡片 Hover 时由边框切换为阴影并微上移。

## 4. 整体框架

### 4.1 全局布局

- 顶部一级菜单固定，来自 `src/config/navigation.js` 的 `topNavItems`：`工作台 / 工具中心 / 能力中心 / 无限画布 / 素材库 / 历史记录 / 帮助文档`。
- 顶部一级菜单、路由、层级、高亮状态统一由导航配置驱动，不允许散落在各页面组件中。
- 左侧为二级导航，按模块分组展示（见 `navGroups`）。
- 主区域为工作台内容区。
- 所有页面统一使用同一套壳层（`LayoutClient` / `Sidebar` / `Topbar` / `PageShell` / `PageHeader`），不允许各页面重新发明顶栏、侧栏和面包屑样式。

### 4.2 一级导航与路由

| 一级菜单 | 路由 | 匹配规则 |
| --- | --- | --- |
| 工作台 | `/home` | 精确匹配 |
| 工具中心 | `/image-tools` | 前缀匹配 |
| 能力中心 | `/ai-hub` | 前缀匹配 |
| 无限画布 | `/ai-canvas` | 前缀匹配 |
| 素材库 | `/materials` | 前缀匹配 |
| 历史记录 | `/history` | 前缀匹配 |
| 帮助文档 | `/help-docs` | 前缀匹配 |

### 4.3 二级导航分组

- 生图工具（`/image-tools`）：专家模式、一键改字、主体替换、产品微调、批量美颜、批量改图。
- AI 能力中心（`/ai-hub`）：AI 多角度、AI 区域重绘、AI 提示词、AI 买家秀、AI 视频流、AI 商品套图（带 `NEW` 角标）。
- 管理（`adminItems`）：数据智能、权限管理、系统设置。

### 4.4 页面状态标记

`routeMeta` 为每个路由标注 `status`，界面上的状态标签据此渲染：

- `ready`：已完成，可交付验证（当前仅 `/home`）。
- `prototype`：原型验证中（其余业务页面）。

新增页面时必须在 `routeMeta` 中登记 `label` / `section` / `status`，面包屑与状态标签会自动生成，不要在页面里手写。

### 4.5 页面结构

**首页**

- 不再重复展示所有模块卡片。
- 核心区域改为"最近使用"。
- 最近使用下方保留少量高频入口或推荐入口。
- 首页是"快速回到上次工作"的地方，不是能力总目录。

**子页面**

- 页面顶部统一信息条：面包屑、状态、标题、说明、右侧动作。
- 工作流类页面统一采用"左侧配置 + 右侧结果"的双栏结构。
- 页面主体只负责业务内容，不重复做基础控件。

## 5. 首页需求说明

### 5.1 最近使用

首页新增"最近使用"模块，展示用户最近打开或操作过的功能。

**展示内容**

- 功能名称
- 所属模块
- 最近使用时间
- 入口按钮
- 可选状态标签，如"原型验证中""已完成""NEW"

**排序规则**

- 按最近使用时间倒序。
- 同时间按业务优先级排序，优先展示最近真实发生的使用记录。

**行为要求**

- 点击直接进入对应子页面。
- 进入后顶部菜单、侧边栏、面包屑保持正确高亮。
- 支持空状态。

**空状态**

- 首次登录或没有最近使用时，展示常用入口或推荐能力。
- 不要显示大段解释文案。

### 5.2 首页优化点

- 删除重复能力卡片堆叠。
- 降低首页信息密度，只保留回访和快速进入的价值。
- 首页不承载复杂参数配置。

## 6. 基础组件规范

以下尺寸、状态以内置 UI 规范页（`/ui-guide`）为准，开发应对照核对。

### 6.1 按钮 Button

- 尺寸：Large 40px / Medium 36px / Small 32px（高度）；圆角 `--radius-md`（8px）。
- Primary：`--brand-primary` 底 + 白字，页面主操作。
- Default：白底 + `--border-base` 边 + `--text-body` 字，次要操作。
- Text：`--brand-primary` 字、无底无边，弱操作（如「← 返回」「查看更多」）。
- Danger：`--danger` 实底白字，或 `--danger` 描边字，破坏性操作。
- Disabled：`opacity: 0.5` + `cursor: not-allowed`。

### 6.2 输入框 Input / Textarea

- Input：高 40px，圆角 8px，`--border-base` 边框。
- Textarea：最小高度 112px，可纵向拉伸，右下角展示字符计数。
- Focus：边框变 `--brand-primary` + `--focus-ring`。
- Error：`--danger` 边框 + 下方 `--danger` 错误文案。
- Disabled：`--gray-50` 底 + `--text-disabled` 字 + `not-allowed`。

### 6.3 标签 & 徽章 Tag / Badge

- 分类标签：`--gray-100` 底 + `--text-secondary` 字，高 24px，圆角 6px。
- 能力状态标签：`--brand-primary-soft` 底 + `--brand-primary` 字。
- 任务状态标签：语义色底 + 语义色字（已完成 / 处理中 / 失败 / 排队中，分别对应 success / warning / danger / info）。
- 图片 Badge：`--gray-900` 暗底白字、胶囊形，用于卡片右下角。

### 6.4 卡片 Card

- 默认卡片：白底 + `--border-base` 边框，无阴影，圆角 `--radius-lg`。
- 可点击卡片：Hover 时边框转 `--shadow-card-hover` 阴影并微上移 2px（边框与阴影二选一，不叠加）。

## 7. 表单与选择组件

### 7.1 单选 Radio / 复选 Checkbox

- Radio：圆形，选中时 `--brand-primary` 描边 + 实心点，用于互斥选项（模型、比例、画质）。
- Checkbox：方形，选中时 `--brand-primary` 实底 + 白色对勾，用于非互斥多选。

### 7.2 下拉选择 Select

- 高 40px，圆角 8px，`--border-base` 边框，Focus 变蓝。选项较多时的单选（模型切换、分类筛选）。

### 7.3 模型下拉选择（卡片式）

- 触发按钮：58px 高，双行（标签 + 当前值），圆角 `--radius-xl`。
- 展开为下拉面板（非弹窗），选项以卡片形式展示图标、名称、耗时、描述。
- 选中项：`--brand-primary` 边框 + `--brand-primary-soft` 底 + 右侧「✓ 已选」。
- 用于需要展示辅助信息的选择（模型、模板）。

### 7.4 参数调节下拉面板

- `select-card` 触发按钮 + `dropdown-panel` 下拉面板（非弹窗），宽约 460px。
- 面板内含清晰度、图片尺寸、图片张数等参数区，组合选择后回显到触发按钮。

### 7.5 分段与数量选择

- 分段控件：`--gray-100` 灰底槽 + 白色选中项（`--shadow-card`），用于互斥模式/参数。禁止彩色边框、彩色选中底。
- 数量九宫格：1–9，`--gray-100` 底槽，选中项白底 + 阴影。
- 比例选择：图形化边框直观展示比例，选中项白底 + 阴影 + `--brand-primary` 图形边框。

### 7.6 开关 Switch / 滑块 Slider

- Switch：44×24 胶囊，开启 `--brand-primary` 底，关闭 `--gray-300`。
- Slider：`accent-color: --brand-primary`，用于连续值（强度、数量）。

## 8. 导航与数据展示

### 8.1 Tabs / 分段控件

- 页面级 Tabs：底部蓝色下划线选中态（`--brand-primary`）。
- 分段控件：灰底槽 + 白色选中项，见 7.5。

### 8.2 表格 Table

- 白底 + 水平分隔线（`--border-light`），表头 `--gray-50` 灰底，行 Hover `--bg-hover`。
- 任务 ID 用等宽字体 + `--text-disabled`；状态列用任务状态标签。

### 8.3 分页 Pagination

- 当前页 `--brand-primary` 实底白字，其他页灰色；两端「上一页 / 下一页」为描边按钮。

## 9. 反馈与弹层组件

### 9.1 进度条 Progress

- `--brand-primary` 填充 + `--gray-200` 底槽，圆角胶囊，展示任务进度百分比。

### 9.2 上传入口 Upload

- 高 88px，圆角 8px，白底虚线边框；Hover 边框变 `--brand-primary` + `--brand-primary-soft` 底。
- 提示支持 JPG / PNG / WebP，最大 20MB（以实际接口约束为准）。

### 9.3 Toast 通知

- 全局操作反馈，右上角弹出；成功 / 失败 / 警告 / 信息四种，语义色圆形图标 + 文案；自动消失或手动关闭。

### 9.4 骨架屏 Skeleton

- 灰色矩形（`--gray-100`）+ 脉冲动画，加载占位，避免页面跳动。

### 9.5 空状态 Empty State

- 所有列表 / 数据区必须处理。线性图标（约 32px）+ 说明文字 + 引导动作，不堆大段文案。

### 9.6 弹窗 Dialog / Modal

- 居中弹窗，遮罩 `--overlay-scrim` + 背景模糊；结构为标题 + 内容 + 底部按钮。
- 点击遮罩或关闭按钮关闭；破坏性确认底部主按钮用 `--danger`。

### 9.7 侧出面板 Sheet / Drawer

- 从右侧滑出，宽约 400px（`max-width: 90vw`）；用于详情、筛选、移动端菜单。点击遮罩关闭。

## 10. 业务公共组件规范

### 10.1 图片队列组件

统一抽象为一个公共组件，买家秀、商品套图、后续所有需要上传/选图的页面都复用。

**支持能力**：素材库选择、本地上传、列表态展示、查看大图、替换/刷新、删除、拖拽交换顺序。

**组件规则**：

- 队列顺序代表业务顺序。
- 首张图可作为主图/主参考图。
- 页面不应自己手写一套图片列表和按钮。

### 10.2 素材选择弹窗

统一用于个人素材库、公共素材库、本地上传。

**支持能力**：来源切换、搜索、类目筛选、标签筛选、多选、本地上传、确认/取消。

**交互要求**：

- 选中后再筛选，不应丢失已选结果。
- 新增选择时，最多数量应按当前剩余容量计算。
- 替换图片时只允许替换单张。
- 除非业务交互完全不同，否则子页面不得重新实现图片队列、素材弹窗、大图预览、任务详情弹窗，只允许通过 props / 配置项扩展。

### 10.3 大图预览组件

统一用于结果查看、素材查看、队列查看。

**支持能力**：上一张 / 下一张、放大 / 缩小、鼠标滚轮缩放、以中心为基准缩放、按住拖动平移、左右翻转、上下翻转、下载图片。

**交互要求**：

- 放大后不要偏到角落。
- 图片缩放和拖拽状态切换时应自动复位到合理初始状态。
- 多图时切换不应保留上一张的拖动偏移。

### 10.4 任务详情弹窗

用于买家秀等任务流页面。

**支持能力**：结果图列表、文案列表、下载图片压缩包、单图下载、复制、删除 / 编辑 / 重生成。

## 11. 子页面开发规范

### 11.1 统一规则

- 子页面只做业务内容，不复制公共交互。
- 视觉样式优先使用已有 token、公共按钮和公共面板。
- 新页面必须先判断是否属于现有工作流，再复用对应壳层。
- 图片上传、预览、下载、弹窗一律优先走公共组件。

### 11.2 页面责任边界

- 页面负责：业务状态、接口、结果拼装、业务文案。
- 公共组件负责：布局、按钮、弹窗、上传、预览、下载、拖拽、空态。

### 11.3 需要统一的页面元素

- 顶部菜单
- 左侧二级导航
- 面包屑
- 状态标签
- 返回按钮
- 历史记录入口
- 主操作按钮
- 通用空状态 / loading / disabled 状态

## 12. 当前框架建议

**首页**：最近使用模块、常用入口模块、轻量状态信息。

**工作流页**：顶部信息条、左侧配置栏、右侧结果栏、底部固定主操作区。

**素材与结果类页面**：图片队列使用统一组件；预览、下载、翻转、拖拽统一行为。

## 13. 给开发的建议

开发不要把它理解成"页面美化"，而要理解成"框架和通用能力标准化"。

建议优先顺序：

1. 先统一全局框架和导航（复用壳层 + `navigation.js`）。
2. 再抽公共图片组件（队列、素材弹窗、大图预览、任务详情）。
3. 再改首页最近使用。
4. 最后补齐各子页面业务差异。

这样后续新增页面时，只要按规范接入，不需要每次重新调 UI。落地时始终对照内置 UI 规范页（`/ui-guide`）核对视觉与交互效果。