docs: update UI/UX spec per review feedback

- Add $font-size-4xl (64rpx) to font scale - Fix line-height-tight to match uni.scss (1.2) - Use existing $uv-* naming for neutral colors, add $uv-placeholder-color - Clarify $font-family-body change (serif → system fonts for body) - Split spacing into recommended vs reserved tiers - Fix $radius-md → $radius-base, add $radius-xl - Fix shadow values to match uni.scss rgba(15,23,42,...) base - Add PageResult<T> pagination type - Add MockStore for interactive mock data - Add image resource specs (sizes, formats) - Add accessibility guidelines - Fix page count (27 → 21) Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-26 09:12:16 +08:00
parent e328177067
commit 6e27b449bb
1 changed files with 139 additions and 35 deletions
@@ -37,7 +37,7 @@

 ### 1.2 字号体系

-9 级字号，消灭所有游离值：
+10 级字号，消灭所有游离值：

 | 变量 | 值 | 场景 |
 |------|-----|------|
@@ -49,6 +49,7 @@
 | `$font-size-xl` | 36rpx | 区域标题 |
 | `$font-size-2xl` | 44rpx | 页面大标题 |
 | `$font-size-3xl` | 56rpx | 大号展示数字 |
+| `$font-size-4xl` | 64rpx | 促销大数字（介于 3xl 和 display 之间） |
 | `$font-size-display` | 72rpx | 超大展示（极少使用） |

 **游离值迁移对照**：
@@ -75,7 +76,7 @@

 | 变量 | 值 | 场景 |
 |------|-----|------|
-| `$line-height-tight` | 1.25 | 标题 |
+| `$line-height-tight` | 1.2 | 标题 |
 | `$line-height-normal` | 1.5 | 正文 |
 | `$line-height-relaxed` | 1.75 | 长段落、说明文 |

@@ -96,19 +97,32 @@

 ### 2.2 中性色（文字 & 背景）

-统一灰阶，替代现有 55+ 种硬编码灰值：
+沿用 `uni.scss` 现有 `$uv-*` 命名，补充缺失值，替代现有 55+ 种硬编码灰值：
+
+**主变量（uni.scss 已有，保持不变）**：

 | 变量 | 值 | 用途 |
 |------|-----|------|
-| `$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` | 分割线、边框 |
+| `$uv-main-color` | `#111111` | 标题、重要正文 |
+| `$uv-content-color` | `#333333` | 正文 |
+| `$uv-tips-color` | `#666666` | 次要说明 |
+| `$uv-placeholder-color` | `#999999` | 占位符（**新增**，uni.scss 缺失） |
+| `$uv-disabled-color` | `#c8c9cc` | 不可操作文字 |
+| `$uv-bg-color` | `#f3f4f6` | 页面背景 |
+| `$uv-bg-color-hover` | `#f1f1f1` | 按压态背景 |
+| `$uv-border-color` | `#eeeeee` | 分割线、边框 |
+| `$color-card` | `#ffffff` | 卡片/模块背景（uni.scss 已有） |
+
+**语义别名（向后兼容，指向上述主变量）**：
+
+| 别名 | 指向 | 说明 |
+|------|------|------|
+| `$color-foreground` | `$uv-main-color` | uni.scss 已有 |
+| `$color-muted-foreground` | `$uv-content-color` | uni.scss 已有 |
+| `$color-background` | `$uv-bg-color` | uni.scss 已有 |
+| `$color-border` | `$uv-border-color` | uni.scss 已有 |
+
+> 迁移时优先使用主变量（`$uv-*`），语义别名仅在已有代码中保留，新代码禁止使用别名。

 ### 2.3 语义色

@@ -144,14 +158,14 @@ rgba(0, 0, 0, 0.12)  — 重投影（弹窗）

 | 现有硬编码值 | 迁移到 |
 |-------------|--------|
-| `#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` |
+| `#111`, `#1A1A1A`, `#222` | `$uv-main-color` |
+| `#333` | `$uv-content-color` |
+| `#666` | `$uv-tips-color` |
+| `#999`, `#888888` | `$uv-placeholder-color` |
+| `#cccccc`, `#BBBBBB`, `#dadbde` | `$uv-disabled-color` / `$uv-light-color` |
+| `#e5e7eb`, `#E2E8F0` | `$uv-border-color` |
+| `#f7f8fa`, `#f5f5f5`, `#f7f7f7`, `#FAFAFA`, `#F8FAFC` | `$uv-bg-color` |
+| `#fff`, `#ffffff`, `#FFFFFF` | `$color-card` |
 | `#e53935`, `#EF4444`, `#f53f3f`, `#E74C3C` | `$uv-error` 或 `$color-price` |
 | `#3c9cff`, `#0052FF`, `#4A90D9`, `#4D7CFF` | `$uv-primary` |
 | `#5ac725`, `#10B981`, `#00b42a` | `$uv-success` 或 `$color-status-success` |
@@ -164,10 +178,17 @@ rgba(0, 0, 0, 0.12)  — 重投影（弹窗）
 ### 3.1 字体声明

 ```scss
-$font-family-display: 'SourceHanSerifCN', '思源宋体', 'STSong', serif;
-$font-family-body: -apple-system, 'PingFang SC', 'Helvetica Neue', sans-serif;
+// uni.scss 现状（display 和 body 都用了思源宋体）:
+$font-family-display: 'SourceHanSerifCN', '思源宋体', serif;        // ✅ 保持不变
+$font-family-body: 'SourceHanSerifCN', '思源宋体', -apple-system, 'PingFang SC', sans-serif;  // ⚠️ 需修改
+
+// 修改后:
+$font-family-display: 'SourceHanSerifCN', '思源宋体', serif;        // 标题装饰字体
+$font-family-body: -apple-system, 'PingFang SC', 'Helvetica Neue', sans-serif;  // 正文系统字体
 ```

+> **为什么要改 `$font-family-body`**：uni.scss 现状把思源宋体（衬线体）用于正文，导致所有文字都是衬线风格，阅读体验偏重且加载慢。改为系统字体后，正文干净利落，仅标题/品牌名保留思源宋体的文化感。
+
 - `$font-family-display`：标题、品牌名、卡名等装饰性文字
 - `$font-family-body`：正文、按钮、表单、说明文字（默认字体，加载快）

@@ -208,10 +229,10 @@ $font-family-body: -apple-system, 'PingFang SC', 'Helvetica Neue', sans-serif;

 ```scss
 圆角：$radius-lg (24rpx)
-投影：$shadow-base → 0 4rpx 16rpx rgba(0, 0, 0, 0.04)
+投影：$shadow-base → 0 4rpx 16rpx rgba(15, 23, 42, 0.08)
 内边距：$spacing-4 (32rpx)
 卡片间距：$spacing-3 (24rpx)
-背景：$color-bg-card (#ffffff)
+背景：$color-card (#ffffff)
 ```

 ### 4.3 箭头/Chevron
@@ -219,13 +240,13 @@ $font-family-body: -apple-system, 'PingFang SC', 'Helvetica Neue', sans-serif;
 统一一种实现：
 - 尺寸：12rpx × 12rpx
 - border-width：2rpx
- 颜色：`$color-text-placeholder`
+- 颜色：`$uv-placeholder-color`
 - 右箭头：`transform: rotate(45deg)`
 - 下箭头：`transform: rotate(135deg)`

 ### 4.4 间距规则

-只允许使用以下变量，禁止硬编码间距值：
+**推荐使用**（日常开发只用这 7 个）：

 | 变量 | 值 | 场景 |
 |------|-----|------|
@@ -237,22 +258,38 @@ $font-family-body: -apple-system, 'PingFang SC', 'Helvetica Neue', sans-serif;
 | `$spacing-6` | 48rpx | 页面顶部/底部安全区 |
 | `$spacing-8` | 64rpx | 大区块分隔 |

+**保留但少用**（uni.scss 已有，仅特殊场景允许）：
+
+| 变量 | 值 | 场景 |
+|------|-----|------|
+| `$spacing-0` | 0 | 重置间距 |
+| `$spacing-10` | 80rpx | 超大区块分隔 |
+| `$spacing-12` | 96rpx | 页面级留白 |
+| `$spacing-16` | 128rpx | 极少使用 |
+| `$spacing-20` | 160rpx | 极少使用 |
+
+禁止硬编码间距值（如 `padding: 20rpx`）。
+
 ### 4.5 圆角规则

 | 变量 | 值 | 场景 |
 |------|-----|------|
 | `$radius-sm` | 8rpx | 标签、小徽标 |
-| `$radius-md` | 16rpx | 输入框、小卡片 |
+| `$radius-base` | 16rpx | 输入框、小卡片 |
 | `$radius-lg` | 24rpx | 卡片、弹窗 |
+| `$radius-xl` | 32rpx | 大面板（少用） |
 | `$radius-full` | 9999rpx | 胶囊按钮、圆形头像 |

 ### 4.6 投影规则

+以 `uni.scss` 现有值为准（使用 `rgba(15, 23, 42, ...)` 冷灰色基底）：
+
 | 变量 | 值 | 场景 |
 |------|-----|------|
-| `$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)` | 浮层、弹窗 |
+| `$shadow-sm` | `0 2rpx 8rpx rgba(15,23,42,0.04)` | 轻投影 |
+| `$shadow-base` | `0 4rpx 16rpx rgba(15,23,42,0.08)` | 卡片默认 |
+| `$shadow-lg` | `0 8rpx 32rpx rgba(15,23,42,0.12)` | 浮层、弹窗 |
+| `$shadow-xl` | `0 16rpx 48rpx rgba(15,23,42,0.16)` | 大弹窗/浮层 |

 ### 4.7 过渡动画

@@ -372,6 +409,20 @@ interface Announcement {
  title: string
  content: string
 }
+
+// 分页通用
+interface PageResult<T> {
+  list: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+// 分页请求参数
+interface PageQuery {
+  page: number
+  pageSize: number
+}
 ```

 ### 5.3 Mock 切换机制
@@ -394,7 +445,34 @@ export function getScenicList(): Promise<Scenic[]> {
 - `.env` 文件中 `VITE_USE_MOCK=true` 控制开关
 - 对接 API 时改为 `false`，页面代码零改动

-### 5.4 占位图片规范
+### 5.4 Mock 状态管理
+
+对于需要交互的 mock 数据（如订单状态变更、预约操作），提供简单的内存状态管理：
+
+```typescript
+// mock/store.ts
+import { ref } from 'vue'
+import type { Order, ReserveRecord } from '@/api/types'
+import { mockOrders } from './order'
+import { mockReserves } from './reserve'
+
+export const orderStore = ref<Order[]>([...mockOrders])
+export const reserveStore = ref<ReserveRecord[]>([...mockReserves])
+
+export function updateOrderStatus(orderId: number, status: Order['status']) {
+  const order = orderStore.value.find(o => o.id === orderId)
+  if (order) order.status = status
+}
+
+export function addReserve(record: Omit<ReserveRecord, 'id'>) {
+  const id = Math.max(...reserveStore.value.map(r => r.id)) + 1
+  reserveStore.value.push({ ...record, id })
+}
+```
+
+> 仅 mock 模式使用。对接 API 后这些操作改为 API 调用，页面逻辑不变。
+
+### 5.5 占位图片规范

 统一收到 `mock/images.ts`：

@@ -409,13 +487,39 @@ export const IMG_CARD_BANNER = 'https://...'

 ---

-## 6. 执行计划
+## 6. 图片资源规范
+
+| 类型 | 尺寸 | 格式 | 说明 |
+|------|------|------|------|
+| TabBar 图标 | 81px × 81px | PNG | 无透明通道，选中/未选中各一套 |
+| 页面分享图 | 500px × 400px | JPEG | < 128KB |
+| 年卡封面 | 750px × 420px | JPEG | < 200KB |
+| 景区封面 | 750px × 420px | JPEG | < 200KB，统一裁切比例 16:9 |
+| 背景图 | 优先 CSS 渐变 | — | 避免大图，减小包体积 |
+
+- 网络图片必须在微信公众平台配置 `downloadFile` 合法域名
+- 本地图片放 `src/static/` 目录，构建时自动打包
+- 占位图统一使用 `mock/images.ts` 中的常量
+
+---
+
+## 7. 无障碍规范
+
+- 所有可交互元素（`<view @click>`、`<button>`）必须设置 `role` 或 `aria-role` 属性
+- `<image>` 标签必须提供有意义的描述（小程序用 `aria-label` 或父容器 `aria-role`）
+- 颜色对比度至少 4.5:1（WCAG AA 标准），正文文字不得仅靠颜色传达信息
+- 错误状态必须配合图标 + 文字，不能只用红色标识
+- 表单输入框必须关联 `<label>` 或使用 `aria-label`
+
+---
+
+## 8. 执行计划

 ### 第1步：基础设施（不改任何页面）

 | 序号 | 任务 | 验证方式 |
 |------|------|---------|
-| 1.1 | 清理 `uni.scss`：补齐 `$font-size-xxs`、语义色、行高、字体族变量 | 编译通过 |
+| 1.1 | 清理 `uni.scss`：补齐 `$font-size-xxs`、`$font-size-4xl`、`$uv-placeholder-color`、语义色、修改 `$font-family-body` 为系统字体 | 编译通过 |
 | 1.2 | 处理 `_tokens.scss`：冲突值改为引用 `uni.scss` 或删除 | 编译通过，无变量冲突 |
 | 1.3 | `api/types.ts` 补全所有业务 interface | `pnpm run type-check` 通过 |
 | 1.4 | 创建 `src/mock/` 目录，迁移所有硬编码数据，实现 `USE_MOCK` 开关 | mock 数据可正常 import |
@@ -436,7 +540,7 @@ export const IMG_CARD_BANNER = 'https://...'

 验证：`pnpm run dev:mp-weixin` 构建 + 微信开发者工具预览，确认视觉无回退。

-### 第3步：剩余页面迁移（~27 个页面）
+### 第3步：剩余页面迁移（~21 个页面）

 - 同样 6 项清单逐页执行
 - 分包页面（`packages/user/pages/card/`）6 个文件同步处理
@@ -444,7 +548,7 @@ export const IMG_CARD_BANNER = 'https://...'

 ---

-## 7. 迁移规则（禁止项）
+## 9. 迁移规则（禁止项）

 - ❌ 禁止在 `<style>` 中定义 `$font`、`$primary`、`$text-main` 等局部变量
 - ❌ 禁止使用 `font-weight: bold` 关键字，必须用 `$font-weight-bold`