docs: add UI/UX standardization design spec

Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-26 09:05:59 +08:00
parent 4ad874adf9
commit e328177067
1 changed files with 454 additions and 0 deletions
@@ -0,0 +1,454 @@
+# UI/UX 标准化设计规范
+
+> 湖南12301文旅专区微信小程序（C端）  
+> 2026-06-26
+
+## 背景
+
+项目现有 35 个 .vue 文件，存在以下问题：
+- 双 token 系统冲突（`uni.scss` vs `_tokens.scss`）
+- 14 个页面自定义局部 SCSS 变量，绕过全局体系
+- 3 套字体族混用（SourceHanSerifCN / Noto Serif SC / 系统字体）
+- 55+ 种硬编码颜色值（4 种品牌蓝、4 种错误红、5 种背景灰）
+- 19 种字号仅 8 种有对应变量
+- 9 种按钮高度
+- mock 数据分散在各页面，格式不统一
+
+目标：统一所有页面的字体、字号、颜色、间距、组件规范，以及 mock 数据管理方式，为后续后端 API 对接做好准备。
+
+## 已确认的决策
+
+| 决策项 | 选择 | 理由 |
+|--------|------|------|
+| 颜色体系 | uni.scss 体系 | 偏暖偏亮，`#3c9cff` 主色 |
+| 字体族 | 思源宋体系 | 文化/旅游感强 |
+| 模拟数据 | 集中管理 + 类型先行 | 对接 API 时页面零改动 |
+| 执行节奏 | 基础设施先行 → 核心链路 → 剩余页面 | 风险最小 |
+
+---
+
+## 1. Token 体系统一
+
+### 1.1 Source of Truth
+
+- 保留 `src/uni.scss` 作为唯一 token 文件（uni-app 自动注入到所有 `<style lang="scss">`）
+- `_tokens.scss` 中与 `uni.scss` 冲突的变量值改为直接引用 `uni.scss` 变量，或删除
+- 禁止任何页面在 `<style>` 中重新定义 `$font`、`$primary`、`$text-main` 等局部变量
+
+### 1.2 字号体系
+
+9 级字号，消灭所有游离值：
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$font-size-xxs` | 18rpx | 辅助标注、库存提示、角标 |
+| `$font-size-xs` | 20rpx | 标签、小徽标 |
+| `$font-size-sm` | 24rpx | 次要说明、辅助文字 |
+| `$font-size-base` | 28rpx | 正文、按钮文字 |
+| `$font-size-lg` | 32rpx | 卡片标题、区域小标题 |
+| `$font-size-xl` | 36rpx | 区域标题 |
+| `$font-size-2xl` | 44rpx | 页面大标题 |
+| `$font-size-3xl` | 56rpx | 大号展示数字 |
+| `$font-size-display` | 72rpx | 超大展示（极少使用） |
+
+**游离值迁移对照**：
+
+| 原值 | 迁移到 | 理由 |
+|------|--------|------|
+| 18rpx | 新增 `$font-size-xxs` | 使用频率高，值得单独层级 |
+| 22rpx | `$font-size-xs` (20rpx) | 视觉差异极小 |
+| 26rpx | `$font-size-base` (28rpx) | 正文统一 28rpx |
+| 30rpx | `$font-size-lg` (32rpx) | 卡片标题统一 32rpx |
+| 34rpx | `$font-size-xl` (36rpx) | 差异极小 |
+
+### 1.3 字重
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$font-weight-normal` | 400 | 正文、说明 |
+| `$font-weight-medium` | 500 | 次要标题、按钮 |
+| `$font-weight-bold` | 700 | 主标题、价格数字、强调 |
+
+禁止使用 CSS 关键字 `bold`，统一用数字变量。
+
+### 1.4 行高
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$line-height-tight` | 1.25 | 标题 |
+| `$line-height-normal` | 1.5 | 正文 |
+| `$line-height-relaxed` | 1.75 | 长段落、说明文 |
+
+---
+
+## 2. 颜色体系
+
+### 2.1 品牌 & 功能色
+
+以 `uni.scss` 现有值为准，不做修改：
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `$uv-primary` | `#3c9cff` | 主色/品牌蓝 |
+| `$uv-error` | `#e53935` | 错误/危险红 |
+| `$uv-warning` | `#f9ae3d` | 警告/橙 |
+| `$uv-success` | `#5ac725` | 成功/绿 |
+
+### 2.2 中性色（文字 & 背景）
+
+统一灰阶，替代现有 55+ 种硬编码灰值：
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `$color-text-primary` | `#111111` | 标题、重要正文 |
+| `$color-text-regular` | `#333333` | 正文 |
+| `$color-text-secondary` | `#666666` | 次要说明 |
+| `$color-text-placeholder` | `#999999` | 占位符、禁用文字 |
+| `$color-text-disabled` | `#cccccc` | 不可操作文字 |
+| `$color-bg-page` | `#f3f4f6` | 页面背景 |
+| `$color-bg-card` | `#ffffff` | 卡片/模块背景 |
+| `$color-bg-hover` | `#f5f5f5` | 按压态背景 |
+| `$color-border` | `#eeeeee` | 分割线、边框 |
+
+### 2.3 语义色
+
+订单状态、标签等场景专用：
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `$color-price` | `#e53935` | 价格红 |
+| `$color-price-highlight` | `#FFD600` | 促销亮黄（首页大卡专用） |
+| `$color-status-pending` | `#ff9500` | 待处理/待支付 |
+| `$color-status-success` | `#00b42a` | 已完成/已支付 |
+| `$color-status-cancel` | `#86909c` | 已取消/已关闭 |
+
+### 2.4 透明度规范
+
+暗底白字（5 档）：
+```
+rgba(255, 255, 255, 0.35)  — 最弱（信任标签等）
+rgba(255, 255, 255, 0.55)  — 弱（次要说明）
+rgba(255, 255, 255, 0.7)   — 中（描述文字）
+rgba(255, 255, 255, 0.85)  — 强（正文）
+rgba(255, 255, 255, 0.95)  — 最强（标题）
+```
+
+白底投影（3 档）：
+```
+rgba(0, 0, 0, 0.04)  — 轻投影（卡片）
+rgba(0, 0, 0, 0.08)  — 中投影（浮层）
+rgba(0, 0, 0, 0.12)  — 重投影（弹窗）
+```
+
+### 2.5 硬编码颜色迁移对照
+
+| 现有硬编码值 | 迁移到 |
+|-------------|--------|
+| `#111`, `#1A1A1A`, `#222` | `$color-text-primary` |
+| `#333` | `$color-text-regular` |
+| `#666` | `$color-text-secondary` |
+| `#999`, `#888888` | `$color-text-placeholder` |
+| `#cccccc`, `#BBBBBB`, `#dadbde` | `$color-text-disabled` |
+| `#e5e7eb`, `#E2E8F0` | `$color-border` |
+| `#f7f8fa`, `#f5f5f5`, `#f7f7f7`, `#FAFAFA`, `#F8FAFC` | `$color-bg-page` |
+| `#fff`, `#ffffff`, `#FFFFFF` | `$color-bg-card` |
+| `#e53935`, `#EF4444`, `#f53f3f`, `#E74C3C` | `$uv-error` 或 `$color-price` |
+| `#3c9cff`, `#0052FF`, `#4A90D9`, `#4D7CFF` | `$uv-primary` |
+| `#5ac725`, `#10B981`, `#00b42a` | `$uv-success` 或 `$color-status-success` |
+| `#f9ae3d`, `#F59E0B`, `#ff9500`, `#ff7d00` | `$uv-warning` 或 `$color-status-pending` |
+
+---
+
+## 3. 字体族 & 排版
+
+### 3.1 字体声明
+
+```scss
+$font-family-display: 'SourceHanSerifCN', '思源宋体', 'STSong', serif;
+$font-family-body: -apple-system, 'PingFang SC', 'Helvetica Neue', sans-serif;
+```
+
+- `$font-family-display`：标题、品牌名、卡名等装饰性文字
+- `$font-family-body`：正文、按钮、表单、说明文字（默认字体，加载快）
+
+全局在 `App.vue` 中声明 `font-family: $font-family-body`，仅需要装饰性的元素单独指定 `$font-family-display`。
+
+### 3.2 字号场景对照
+
+| 场景 | 变量 | 值 |
+|------|------|-----|
+| 页面大标题 | `$font-size-2xl` | 44rpx |
+| 区域标题 | `$font-size-xl` | 36rpx |
+| 卡片标题 | `$font-size-lg` | 32rpx |
+| 正文/按钮 | `$font-size-base` | 28rpx |
+| 次要说明 | `$font-size-sm` | 24rpx |
+| 辅助标注/标签 | `$font-size-xs` | 20rpx |
+| 极小文字/角标 | `$font-size-xxs` | 18rpx |
+
+---
+
+## 4. 组件规范
+
+### 4.1 按钮
+
+从 9 种高度收敛到 3 种：
+
+| 尺寸 | 高度 | 字号 | 场景 |
+|------|------|------|------|
+| sm | 64rpx | `$font-size-sm` (24rpx) | 列表内操作、小按钮 |
+| md | 80rpx | `$font-size-base` (28rpx) | 页面内主要操作 |
+| lg | 96rpx | `$font-size-lg` (32rpx) | 底部固定栏、支付按钮 |
+
+- 统一圆角 `$radius-full`（胶囊形）
+- 主操作：`$uv-primary` 填充色 + 白色文字
+- 次要操作：描边样式（border `$uv-primary` + `$uv-primary` 文字）
+- 按压态：`transform: scale(0.95)` + `transition: transform $transition-fast`
+
+### 4.2 卡片
+
+```scss
+圆角：$radius-lg (24rpx)
+投影：$shadow-base → 0 4rpx 16rpx rgba(0, 0, 0, 0.04)
+内边距：$spacing-4 (32rpx)
+卡片间距：$spacing-3 (24rpx)
+背景：$color-bg-card (#ffffff)
+```
+
+### 4.3 箭头/Chevron
+
+统一一种实现：
+- 尺寸：12rpx × 12rpx
+- border-width：2rpx
+- 颜色：`$color-text-placeholder`
+- 右箭头：`transform: rotate(45deg)`
+- 下箭头：`transform: rotate(135deg)`
+
+### 4.4 间距规则
+
+只允许使用以下变量，禁止硬编码间距值：
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$spacing-1` | 8rpx | 图标与文字间隙 |
+| `$spacing-2` | 16rpx | 紧凑元素间距 |
+| `$spacing-3` | 24rpx | 列表项间距、卡片间距 |
+| `$spacing-4` | 32rpx | 区域内容边距 |
+| `$spacing-5` | 40rpx | 区块间距 |
+| `$spacing-6` | 48rpx | 页面顶部/底部安全区 |
+| `$spacing-8` | 64rpx | 大区块分隔 |
+
+### 4.5 圆角规则
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$radius-sm` | 8rpx | 标签、小徽标 |
+| `$radius-md` | 16rpx | 输入框、小卡片 |
+| `$radius-lg` | 24rpx | 卡片、弹窗 |
+| `$radius-full` | 9999rpx | 胶囊按钮、圆形头像 |
+
+### 4.6 投影规则
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$shadow-sm` | `0 2rpx 8rpx rgba(0,0,0,0.04)` | 轻投影 |
+| `$shadow-base` | `0 4rpx 16rpx rgba(0,0,0,0.04)` | 卡片默认 |
+| `$shadow-lg` | `0 8rpx 32rpx rgba(0,0,0,0.08)` | 浮层、弹窗 |
+
+### 4.7 过渡动画
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$transition-fast` | `150ms ease` | 按压、hover |
+| `$transition-base` | `250ms ease` | 展开/收起、淡入淡出 |
+
+禁止使用 `0.15s ease`、`0.2s ease` 等硬编码值。
+
+---
+
+## 5. 类型定义 & Mock 数据
+
+### 5.1 文件结构
+
+```
+src/
+├── api/
+│   ├── types.ts              # 所有业务类型（唯一来源）
+│   ├── request.ts            # HTTP 封装（已有，不动）
+│   ├── scenic.ts             # 景区接口
+│   ├── card.ts               # 年卡接口
+│   ├── order.ts              # 订单接口
+│   ├── user.ts               # 用户接口（已有，补充类型）
+│   └── reserve.ts            # 预约接口
+├── mock/
+│   ├── index.ts              # 统一导出 + USE_MOCK 开关
+│   ├── scenic.ts             # 景区 mock
+│   ├── card.ts               # 年卡 mock
+│   ├── order.ts              # 订单 mock
+│   ├── reserve.ts            # 预约记录 mock
+│   ├── notice.ts             # 公告 mock
+│   └── images.ts             # 占位图片 URL 常量
+```
+
+### 5.2 types.ts 业务类型
+
+```typescript
+interface Scenic {
+  id: number
+  name: string
+  cover: string
+  address: string
+  lat: number
+  lng: number
+  openTime: string
+  description: string
+  ticketPrice: number
+  freeTimes: number
+}
+
+interface ScenicSession {
+  id: number
+  scenicId: number
+  date: string
+  startTime: string
+  endTime: string
+  stock: number
+  remainStock: number
+}
+
+interface Card {
+  id: number
+  name: string
+  price: number
+  originalPrice: number
+  cover: string
+  benefits: string
+  scenicIds: number[]
+}
+
+interface Order {
+  id: number
+  cardId: number
+  cardName: string
+  amount: number
+  status: 'pending' | 'paid' | 'cancelled' | 'closed'
+  payTime: string | null
+  createTime: string
+}
+
+interface OrderDetail extends Order {
+  orderNo: string
+  userId: number
+  userName: string
+  phone: string
+  payMethod: string
+}
+
+interface ReserveRecord {
+  id: number
+  scenicId: number
+  scenicName: string
+  date: string
+  session: string
+  status: 'pending' | 'confirmed' | 'cancelled' | 'used'
+}
+
+interface Notice {
+  id: number
+  title: string
+  content: string
+  publishTime: string
+  isTop: boolean
+}
+
+interface QuickAction {
+  id: number
+  icon: string
+  label: string
+  path: string
+}
+
+interface Announcement {
+  id: number
+  title: string
+  content: string
+}
+```
+
+### 5.3 Mock 切换机制
+
+```typescript
+// mock/index.ts
+export const USE_MOCK = import.meta.env.VITE_USE_MOCK === 'true'
+
+// api/scenic.ts
+import { USE_MOCK } from '@/mock'
+import { mockScenicList } from '@/mock/scenic'
+import type { Scenic[] } from './types'
+
+export function getScenicList(): Promise<Scenic[]> {
+  if (USE_MOCK) return Promise.resolve(mockScenicList)
+  return request.get('/mp-api/scenic/list')
+}
+```
+
+- `.env` 文件中 `VITE_USE_MOCK=true` 控制开关
+- 对接 API 时改为 `false`，页面代码零改动
+
+### 5.4 占位图片规范
+
+统一收到 `mock/images.ts`：
+
+```typescript
+export const IMG_SCENIC_COVER = 'https://images.unsplash.com/...'
+export const IMG_AVATAR = 'https://...'
+export const IMG_CARD_BANNER = 'https://...'
+// ...
+```
+
+对接 API 后这些常量直接废弃，不影响页面代码。
+
+---
+
+## 6. 执行计划
+
+### 第1步：基础设施（不改任何页面）
+
+| 序号 | 任务 | 验证方式 |
+|------|------|---------|
+| 1.1 | 清理 `uni.scss`：补齐 `$font-size-xxs`、语义色、行高、字体族变量 | 编译通过 |
+| 1.2 | 处理 `_tokens.scss`：冲突值改为引用 `uni.scss` 或删除 | 编译通过，无变量冲突 |
+| 1.3 | `api/types.ts` 补全所有业务 interface | `pnpm run type-check` 通过 |
+| 1.4 | 创建 `src/mock/` 目录，迁移所有硬编码数据，实现 `USE_MOCK` 开关 | mock 数据可正常 import |
+| 1.5 | `App.vue` 全局字体声明统一为 `$font-family-body` | 构建预览正常 |
+| 1.6 | 删除 14 个页面中的局部 `$font`、`$primary`、`$text-main` 等变量声明 | 编译通过 |
+
+### 第2步：核心链路迁移（4 个页面）
+
+迁移页面：`首页 → 年卡列表 → 年卡详情 → 购买/订单`
+
+每页迁移清单：
+1. 删除局部 SCSS 变量，改用全局 token
+2. 硬编码颜色值 → 全局变量
+3. 硬编码字号 → 对应 `$font-size-*` 变量
+4. 硬编码间距 → 对应 `$spacing-*` 变量
+5. 模板中硬编码数据 → import mock 数据
+6. 组件样式对齐规范（按钮高度、卡片圆角、箭头样式）
+
+验证：`pnpm run dev:mp-weixin` 构建 + 微信开发者工具预览，确认视觉无回退。
+
+### 第3步：剩余页面迁移（~27 个页面）
+
+- 同样 6 项清单逐页执行
+- 分包页面（`packages/user/pages/card/`）6 个文件同步处理
+- 纯 CSS 组件（`card-item.vue`、`empty-state.vue`、`McGlass.vue`）改为 SCSS + 全局变量
+
+---
+
+## 7. 迁移规则（禁止项）
+
+- ❌ 禁止在 `<style>` 中定义 `$font`、`$primary`、`$text-main` 等局部变量
+- ❌ 禁止使用 `font-weight: bold` 关键字，必须用 `$font-weight-bold`
+- ❌ 禁止硬编码颜色值（如 `#333`、`#666`），必须用全局变量
+- ❌ 禁止硬编码间距值（如 `padding: 20rpx`），必须用 `$spacing-*`
+- ❌ 禁止在页面中硬编码业务数据，必须从 `mock/` 或 `api/` import
+- ❌ 禁止使用 `0.15s ease` 等硬编码过渡值，必须用 `$transition-*`