# 三联慧学 Pad · 统一设计规范（v4）

> 交付物：`设计图/v4/`　│　真值来源：`设计图/学生版/**`、`设计图/教师版/**` 原稿 + `sanlian-uniapp` 现有实现
> 基准画布：**1194×834**（iPad 横屏逻辑尺寸，设计稿 2388×1668 @2x ÷ 2）
> 一句话原则：**一套外壳、一套令牌、一套组件；先统一，再谈还原。**

---

## 一、为什么要有这份规范

原设计稿和现实现各有一套「自造」的规则，同一个 App 里能数出这些问题：

| # | 现象 | 证据（可核对） |
|---|---|---|
| 1 | **没有状态栏** | 所有原稿都是 1194×834 满屏内容，顶部没有时间/网络/电量；而工程里每个页面都是 `navigationStyle: "custom"`，状态栏必须 App 自绘 —— 现在是空白 |
| 2 | **返回按钮有 3 套写法** | 学生版 `.sd-back`（48px 字号当图标，`top:26 left:32`）；教师版 `.v2-screen__back`（绝对定位 `left:44 top:37`，19.5×29.5）；另有页面自己画一套 —— 位置、尺寸、触控区都不一致，还可能是「假返回」 |
| 3 | **字号被整体缩放** | `useViewport` 的 `scale = max(0.8, min(area/1194, area/834))`，`sl-stage` 用 `transform: scale()` 铺画布。768×1024 竖屏时 18px 正文只剩 11.6px |
| 4 | **两套左侧导航** | 学生版用整图 `nav-*.png`（圆底+图标+文字合成，67×61）；教师版 inactive 用 CSS 描边圆 + SVG、active 换整图 `ic-side-*.png`。同一个位置两种几何 |
| 5 | **科目控件有两份** | 外壳 `#top` 插槽一份 + 模块内部又一份 |
| 6 | **弹窗一刀切缩放** | `--v2-mm` 把 1194 宽弹窗整体 scale 到视口，长表单在窄屏够不着 |
| 7 | **状态只靠颜色** | 部分列表用红/绿区分对错，没有图标与文字 |
| 8 | **触控区不足 44px** | 原稿不少按钮 32px |
| 9 | **首页与二级页边界模糊** | 有的模块在首页内切 tab，有的又 `navigateTo` 跳页；返回后落点不明确 |
| 10 | **失败态缺失** | 「失败 0」恒为 0；生成中只有转圈 |

v4 的做法不是「再画一版更好看的图」，而是**把这 10 条逐条定成规则**，然后用一套 HTML/CSS 原型证明它能跑通。

---

## 二、统一外壳（本版核心新增）

```
┌──────────────────────────────────────────────────────────────┐
│ StatusBar  9:41  10月16日 周四 ⟨场景标识⟩   ▮▮ wifi  signal 86%│  24px（手机交给系统 + env 安全区）
├──────────┬───────────────────────────────────────────────────┤
│  Rail    │  AppBar   [‹返回 44×44]  标题/上下文   [动作 ≤3]      │  56px（手机 48px）
│  179px   ├───────────────────────────────────────────────────┤
│ 账号块    │                                                   │
│ 星球      │  Content（自身滚动，padding 24，卡片间距 20）        │
│ 模块项×N  │                                                   │
└──────────┴───────────────────────────────────────────────────┘
```

| 层 | 规则 | 令牌 |
|---|---|---|
| **状态栏** | 左：时间（等宽数字）+ 日期星期 + 场景标识（学习模式/教师端）；右：Wi-Fi、信号、电量 + 百分比。**深色页用 `--ink-3`，场景/玻璃页用白色**。高度 24px；手机不画（系统绘制），用 `env(safe-area-inset-top)` 让位 | `--h-status` |
| **页头 AppBar** | 左：返回按钮 **44×44 触控区**（22px 线性 chevron，线宽 2.4，颜色：浅色页 `--ink-1` / 场景页 `#fff`）；中：标题（`--f-h3` 20/700）或上下文控件；右：动作区（最多 2 个图标按钮 + 1 个文字按钮） | `--h-appbar`、`--tap` |
| **左侧导航 Rail** | 账号块（头像 50 + 姓名 + 年级/班级，整块点进个人中心）→ 星球（回首页）→ 模块项。宽 179px（竖屏 88px）。模块项 = 46px 图标圆 + 11px 标签；**选中态统一为「白圆 + 主色图标 + 5 色弧光 + 蓝底标签」**，学生/教师同一套 | `--w-rail`、`--w-rail-sm` |
| **内容区** | 自身滚动；内边距 24（手机 16）；卡片间距 20（手机 12）；PC 超宽屏限宽 1360 居中 | `--pad-page`、`--gap`、`--content-max` |

**返回语义（唯一定义）**：`navigateBack()`；栈里没有上一页时 `reLaunch` 到当前角色的首页（学生 → `pages/student/home/home`，教师 → `pages/teacher-v2/home/home`）。返回按钮只出现在二级页，hub 页不出现。

---

## 三、设计令牌（`assets/tokens.css` 是唯一真值）

### 颜色

| 用途 | 令牌 | 值 | 依据 |
|---|---|---|---|
| 品牌主蓝 | `--brand` | `#2BAEFD` | 设计稿像素核验（3.21M px 命中）；旧值 `#2E86EE` 命中 649px，属抗锯齿噪声，已废弃 |
| 白底蓝色文字 | `--brand-dd` | `#0E86DA` | 原稿只有装饰蓝，白底上不达 AA，新增深一档 |
| 浅蓝底 | `--brand-100` | `#DFF3FF` | 个人中心年级 chip 同值 |
| 标题墨色 | `--ink-1` | `#524337` | 设计标注 |
| 正文灰 | `--ink-3` | `#808080` | 设计标注 |
| 辅助灰 | `--ink-4` | `#A6A6A6` | 设计标注（实测更浅一档） |
| 玻璃 | `--glass*` | `rgba(255,255,255,.08/.14/.22)` | 面板 = 纯模糊 + 1.2px 描边，**无白色蒙版**（逐像素结论） |

语义色（橙 `#FF9500` / 绿 `#35C759` / 红 `#FF5A5F` / 金 `#FFC53D`）一律再配一档**深色文字值**（`--orange-d / --green-d / --red-d`）保证白底 AA 4.5:1。

### 字体

- 字体族：内嵌「经典圆体简」`src/static/fonts/classic-round.woff2`（`ClassicRoundSC`），跨端一致；回退系统圆体栈。
- 字间距：`--ls: 1px`（设计标注）；长列表/表格用 `--ls-tight: 0.2px`。
- 字号刻度（8px 基线）：40 / 30 / 24 / 20 / 17 / 15 / 13.5 / 12 / 11。
- **窄屏只下调 display–h2，正文 15px 不缩**（这是原实现最大的可用性问题）。

### 间距 / 圆角 / 阴影 / 动效

- 间距：4 / 8 / 12 / 16 / 20 / 24 / 28 / 32 / 40 / 48 / 64（8pt 网格 + 4px 半步）。
- 圆角：8 / 12 / 14 / 20 / 26 / pill。阴影：`sh-sm`、`sh-md` 两档通用 + `sh-lg`（弹窗）+ `sh-brand`（主按钮），**不再堆多层黑阴影**。
- 动效：100/150/200/300ms；标准曲线 `cubic-bezier(.2,0,0,1)`，弹性 `cubic-bezier(.34,1.56,.64,1)`；尊重 `prefers-reduced-motion`。

---

## 四、信息架构（首页 hub + 二级页独立跳转）

这是本次明确采用的结构，**性能与返回语义都最省**：

| 角色 | 首页（单页 hub，左菜单/右内容，**不跳页**） | 二级页（独立页面，统一返回） |
|---|---|---|
| 通用 | — | **已交付**：欢迎页 `welcome`、登录页 `login`（`bare` 皮肤，无导航无页头）；个人中心 `common/account`（学生/教师同一页） |
| 学生 | `student/home.html`：首页 / 自主学习 / 数字课堂 / 精准练习 / 趣学英语 / 作文批改（左侧导航 6 项 + 顶部科目固定） | **已全部交付 21 页**：今日任务、试卷作答、好习惯训练、学霸进阶、大表速记、知识地图、单词连连看、跟课本学单词、查词、写作文、历史作文、作文批改结果、学情报告、错题解析、跟课本学（目录）、视频学习、10 题测真实水平、测试结果、通关挑战、数字课堂详情、大阅读 |
| 教师 | `teacher/home.html`：工作台 / 作业批改 / 智能组卷 / 班级学情 / 班级错题本（左侧导航 4 项） | **已全部交付 11 页**：批改工作台、参考答案核对、批改报告、组卷向导、题库、试卷预览、AI 出卷三态、历史组卷、班级学情（含学生个体学情弹窗）、错题解析、下载中心 |

规则：
1. hub 内切换用 `[data-hub-btn]` → 只切内容区，**不改 URL、不产生页面栈**；再点一次不会叠页面。
2. 二级页一律 `navigateTo` 独立页，页头左侧统一返回；`studentGo()` 里已有「已在 hub 栈中则先退回去再切 tab」的逻辑，保留。
3. 个人中心只有一份实现（工程里 `pages/common/account/account.vue` 已共用，设计稿保持同一版式）。

---

## 五、组件与状态（`assets/components.css`）

可用组件：头像、按钮（主/浅色/描边/灰底/文字/危险/幽灵/玻璃，含 sm/lg/block/icon 与 loading）、图标按钮、徽章、圆点、状态（颜色+图标+文字三重编码）、chip、segment、tabs、卡片（含 glass/link/flat/line）、列表、KPI、进度条、环形进度、柱图、分布条、排行、表格（手机转「标签+值」卡片）、分页、表单（input/select/textarea/search/check/radio/switch/stepper/dropzone）、步骤条、折叠、提示条、日志流、空态、骨架屏、加载圈、Toast、弹窗（手机自动变底部抽屉）。

做题类专用（学生做题页与教师批改页共用）：**选项 `.opt`**（默认 / 选中 / `is-right` / `is-wrong` 四态，含 A/B/C/D 键与对错勾叉）、**答题卡 `.q-nav`**（已答 / 当前 / 标记 / 未答）、**题干 `.q-stem`**、**底部固定操作条 `.actionbar`**（放在 `.content` 的第三行，不随内容滚动）。

**每个数据区必须给三态**：加载中（骨架屏 + 文案）、空结果（插画 + 一句话 + 一个动作）、失败（原因 + 重试）。

**统一交互尺寸**：所有可点元素 ≥ 44×44；表格行高 ≥ 48；弹窗宽度档位 480 / 640 / 880 / 1080，高度受视口约束、正文内部滚动、头尾固定。

---

## 六、断点策略

| 断点 | 设备 | 导航 | 内容 | 说明 |
|---|---|---|---|---|
| ≥1101px | 平板横屏 / PC | 179px 完整左栏（图标+文字） | 多列，PC 限宽 1360 | 基准 1194×834，与设计稿 1:1 |
| 701–1100px | 平板竖屏 | **88px 图标轨**（图标 + 11px 小字）；账号块改「头像 + 年级」**竖排、姓名收起** | 1–2 列 | 同一外壳，不做整体缩放。⚠️ 88px 里放不下「头像 + 4 字姓名」，保留横排会让姓名逐字竖排、左上角崩坏（实测已修） |
| ≤700px | 手机 | **底部 5 项 Tab**（首页/自主学/精准练/趣英语/我的；教师：工作台/改作业/智组卷/学情/我的） | 单列 | 场景皮肤转浅色 + 顶部品牌渐变头；页面级 Tab 保留在内容区 |

**手机版结论（评估后采用「同一套系统 + 换导航形态」，不另起一套视觉）**：
- 列数规则（`.g-2/.g-3/.g-4`）：≥1101 按类名；701–1100 最多 2 列；≤700 单列（`.g-4` 保留 2 列，避免 4 行堆叠）。**不要靠页面自己写死列数**。
- 平板是主场景（孩子用 iPad 上课、老师用 iPad 批改），1194×834 与 768×1024 必须 1:1 可靠；
- 手机主要是「看进度、做几道题、查作业」，因此手机端**只做 hub + 二级页的响应式重排**（单列 + 底部 Tab + 底部抽屉弹窗），不重画全部业务插画；沉浸式场景（蓝天 + 房间切图）在手机上换成品牌渐变头。
- 落地要点：关掉 `pages.json` 的 `pageOrientation: "landscape"`；小程序端不支持媒体查询，用 `uni.getWindowInfo().windowWidth` 换算成动态 class（`is-phone / is-tablet / is-pc`）切 `data-shell` 与列数；颜色/字号/间距令牌可 1:1 照搬。

---

## 七、落地到 `sanlian-uniapp` 的映射

| v4 文件 | 工程目标 | 说明 |
|---|---|---|
| `assets/tokens.css` | `src/styles/v2.scss` 的 `page { --v2-* }` 块 | 令牌合并进来即可，变量一一对应（`--brand` → `--v2-blue` 等） |
| `assets/base.css` | 新建 `src/styles/base.css` | reset、排版工具类、`[hidden]` 修正（组件写了 `display:flex` 会吃掉 `hidden`，真机上表现为首页下面拖出几百 px） |
| `assets/components.css` | 新建 `src/styles/components.css` | 逐步替换各页面局部样式；`wd-*` 组件保留，但色值/圆角/间距必须走令牌 |
| `assets/shell.css` | 改 `components/sl-shell/sl-shell.vue` + `sl-student-design-shell.vue` + `v2-sidebar.vue` | 状态栏与页头加进 `SlStage` 之上；**删掉 `fit()` 式整体 `scale()` 与 `pageOrientation: landscape`** |
| `assets/teacher.css` / `student.css` | 各模块局部样式 | 保留模块内部构图，只把硬编码色值/字号换成令牌 |
| 左侧导航三种形态 | `windowWidth` 阈值 + 动态 class | 不用 CSS 媒体查询（小程序不支持） |

---

## 八、验收方式（本版已跑过）

1. **全站溢出审计**（38 页 × 3 个宽度 = 114 个视口）：
   ```
   chrome --headless=new --allow-file-access-from-files --screenshot=out.png --window-size=1540,800 \
     "file:///…/设计图/v4/_tools/audit.html?p=welcome.html,login.html,index.html,student/home.html,…&w=390,768,1194&h=844"
   ```
   结果：**114/114 溢出 = 0**（见 `_shots/99-audit-A-通用与学生端1.png`、`99-audit-B-学生端2.png`、`99-audit-C-教师端.png`）。三点使用须知：
   - 溢出时会额外打印「祖先宽度」链，便于区分「容器被撑破」与「子项越界」；
   - 审计会**跳过横向滚动容器内部**的元素（`.tbl-wrap` 表格、`.level-track` 关卡轨道等横滑是设计意图），只报真正的越界；
   - 页面超过 12 个时分两批渲染，避免文字被缩得看不清。
2. **多断点并排目检**：`_tools/check.html?p=student/home.html&w=390,768,1194&h=844`；一屏纵览全部页面用 `_tools/gallery.html?w=1194&s=0.33`（Windows 无头 Chrome 的最小窗口宽度约 500px，量手机必须用 iframe 绕开，且**校验工具自身也要先自检**：`_tools/_breakpoint-test.html`）。
3. **截图留证**：`_shots/`（平板 1194×834、平板竖屏 768×1024 与 900×1200、手机 390×844、各批页面并排缩略图、断点工具类自检、三批溢出审计）。
4. 任意页面 URL 后加 `?probe=1`：页面顶部浮出 `vw / scrollWidth / 越界元素`，越界元素描红边。
5. ⚠️ 改本目录文件不要走 PowerShell 的 `Get-Content | Set-Content`（默认按 ANSI 读，会把中文写成乱码）。

---

## 九、已知边界（诚实说明）

- 数据全为**样例数据**（春田花花 / 石政彬 / 四年级(9)班 / 砂糖酱 / 四年级），未接任何接口；三态只在代表性位置给出示例。
- 图表用纯 CSS（柱图/分布/环形）示意，落地时换 `v2-echarts.vue` 或 uCharts。
- 欢迎页 / 登录页（`bare` 皮肤）未在本版重画；原稿是独立沉浸式页面，建议单独一轮。
- 深色模式、打印样式未做；令牌已集中，追加 `prefers-color-scheme: dark` 覆盖即可。
- 手机版只覆盖 hub + 已交付的二级页；剩余二级页在补页面时按同一断点规则重排即可。