# 前端 UI 规范（petstore）

## 目标

- 统一视觉风格，避免页面“各写各的”。
- 保证移动端可读性和可点击性。
- 降低后续新增页面的设计与维护成本。

## 设计基线

**唯一源**：`frontend/src/assets/global.css` 的 `:root` **CSS 变量（`--c-*`）**；`pages.json` 的 `navigationBarBackgroundColor` 与主色保持一致。

- 主色 / 品牌：`var(--c-brand)`（`#2db96d`）
- 品牌深 / 渐变收边：`var(--c-brand-dark)`（`#1e9a55`）
- 品牌浅底 / 选中弱背景：`var(--c-brand-light)`（`#eaf8f0`）
- 页面背景：`var(--c-bg)`（`#fafaf8`）
- 卡片表面：`var(--c-surface)` / `var(--c-surface-alt)`
- 主文案：`var(--c-text)`；次级：`var(--c-text-2)`；辅助：`var(--c-text-3)` / `var(--c-text-4)`
- 分割/边框：`var(--c-border)` / `var(--c-border-light)`
- 阴影：`var(--c-shadow-sm)` / `var(--c-shadow)` / `var(--c-shadow-lg)`
- 圆角：`var(--radius-sm)` / `var(--radius)` / `var(--radius-lg)`

业务页面**禁止**写死同类十六进制色，统一使用上述变量。历史文档中出现的 `--pet-*` 已废弃，以 `--c-*` 为准。

> 全站优化说明与决策记录见 [《产品全方位优化说明 v1》](./产品全方位优化说明-v1.md) §〇、§四。

## 字体与层级

- 页面标题：18px / 700（用 `.text-title`）
- 正文：14px / 400~500（用 `.text-body`）
- 说明/辅助：12px / 400（用 `.text-sub`）
- 避免 11px 及以下文本，移动端可读性较差。

## 间距规范

- 统一间距标尺：8 / 12 / 16 / 24（优先使用全局变量）
- 页面左右基础边距：16px（`.page-section`）
- 模块间距：12px（`.section-gap`）
- 卡片圆角：12~18px
- 表单项垂直间距：8~12px
- 底部保留区：至少 `120rpx`（避免被底栏遮挡）

推荐使用：

- 页面容器：`.page-shell`
- 模块容器：`.page-section`
- 模块间隔：`.section-gap`
- 表单项包装：`.form-field-wrap`
- 模块标题：`.module-title`

## 组件规范

### 顶部导航

- 使用绿色渐变背景 + 轻阴影（`.nav-gradient`）。
- 标题使用 18/700。
- 左侧返回统一使用 `AppIcon(back)`。
- 返回按钮触达区保持足够（建议 40px 以上），并使用统一按压反馈（`.nav-back:active`）。

### 按钮

- 主按钮：绿色渐变，白字，12px 圆角，高度 44px。
- 次按钮：浅底 + 边框，颜色低于主按钮一个层级。
- 同区域最多一个高强调按钮，避免视觉噪音。

### 输入框

- 使用统一 `.van-field` 样式。
- 聚焦态有明显边框和光晕反馈。
- 文本域最小高度 84~96px，行高 1.45+。

### 卡片

- 白底 + 细边框 + 轻阴影。
- 不要叠加过多投影层。
- 卡片内信息按“标题 > 关键值 > 说明”组织。
- 卡片点击态统一轻微下沉 + 透明度变化，避免“有的会动有的不会动”。

### 图标

- 全站优先使用统一 `AppIcon`，避免 emoji 与图标混用。
- 新增图标时先补充到 `src/components/AppIcon.vue`，再在页面内复用。
- 空态/占位图（如图片占位、头像角标）也使用同一套图标风格（如 `camera`）。

### 空状态

- 用统一 `.empty`，文案简短明确。
- 避免裸文本直接贴在背景上。

## 交互与可用性

- 可点击区域建议不小于 40x40。
- 反馈闭环完整：点击后要有 loading / toast / 状态变化。
- 关键操作（删除、取消）保持二次确认。
- 统一微交互：按钮、卡片、列表项按压反馈节奏一致（约 160ms）。

## 禁止项

- 禁止在模板里堆叠大量内联 `style`。
- 禁止同一功能页使用多个不同风格按钮。
- 禁止页面之间同类元素样式明显不一致（例如顶部导航、卡片、输入框）。
- 禁止在业务页面重复定义全局已有的间距/标题样式（如 `.module-title`、`.form-field-wrap`）。
- 禁止新增 emoji 图标作为主视觉元素。

## 新页面接入清单

- 引入并复用全局样式，不重复造轮子。
- 先搭框架：`page-shell -> nav -> sections -> bottom safe area`。
- 自检 4 项：
  - 视觉是否与已有页一致
  - 小屏是否可读
  - 点击区域是否足够
  - 是否存在硬编码颜色/间距

