# Taro H5 视觉语言规范

更新时间：2026-07-02

这份规范用于约束 `apps/taro` 的学生端、租户后台和平台后台。旧题库前端参考目录为 `F:\project\参考\旧题库小程序前端文件`，只作为页面状态、学习流程、后台信息密度和微信平台交互的参考，不继承旧 PocketBase 直连、旧鉴权、旧字段模型或旧技术栈。

## 总原则

- Taro 是前端体验层：负责路由、布局、交互、公开运行时配置、Supabase Auth session 和统一 API client；复杂业务判断、权限、价格、权益、导入、支付、CRM 和对象存储签名以后端为准。
- Web 首发优先做成可反复使用的工具型产品，不做营销落地页式的大图 Hero、装饰卡片堆叠和过度留白。
- 学生端要接近旧题库小程序/旧 Web 的学习节奏：浅灰网格背景、PC 左侧栏、移动底部 dock、蓝色学习横幅、彩色学习模块、白色统计卡和短路径练习入口。
- 租户后台和平台后台要接近旧后台运营工具：浅灰/白色密集工作台、圆角侧栏、深色 active nav、表格/列表优先、操作按钮固定、指标可扫读。

## 视觉基线

| 项 | 规范 |
| --- | --- |
| 页面背景 | `#f4f6f9` 为主，叠加旧题库 40px 网格线；后台主区可用白色/浅灰工作台背景 |
| 主文字 | `#0f172a`、`#111827`、`#172033` |
| 次级文字 | `#64748b`、`#475569` |
| 主色 | 旧题库蓝 `#1152d4`，辅以 `#2563eb` / `#1d4ed8`；租户发布主题后可由后端安全 token 覆盖 |
| 成功/强调 | `#10b981`、`#16a34a`，只用于进度、完成、兑换等状态 |
| 危险 | `#be123c`、`#dc2626`，只用于退款、驳回、删除、失败 |
| 圆角 | 延续旧题库圆润但克制的尺度：输入/小按钮约 `8-12px`，列表/卡片约 `12-18px`，首页模块/登录/侧栏面板可到 `24-32px`；进度条、chip、badge、头像、滚动条和装饰标记可用 `999px` |
| 字体 | 固定 px/rpx 风格，不使用 `vw/vh/vmin/vmax` 缩放字体 |
| 字距 | 不使用负 `letter-spacing` |
| 装饰 | 禁止径向光斑和裸 `filter: blur()` 装饰；允许旧题库样式里的网格背景、蓝色学习横幅、彩色模块卡、主按钮渐变、状态面板渐变，以及侧栏/dock 的受控 `backdrop-filter` |

## 页面结构

- 学生端页面使用 `StudentLegacyShell` 提供 PC 左侧栏和移动 dock；页面内部继续使用 `student-page`、`student-topbar`、`section-block`、`list-stack`、`quiet-panel` 等现有类名体系。
- 租户后台使用 `AdminLegacyShell` 提供旧后台侧栏/移动横向 nav，并复用 `admin-page`、`admin-shell`、`admin-header`、`admin-metric`、`admin-row`、`admin-button`。
- 平台后台使用 `AdminLegacyShell` 提供旧后台侧栏/移动横向 nav，并复用 `platform-page`、`platform-shell`、`platform-header`、`platform-metric`、`platform-row`、`platform-button`。
- 新页面优先复用这些体系，不要为同类按钮、卡片、列表重新发明一套视觉类名。
- 页面区域不要做卡片套卡片。重复列表项、工具面板、表单组可以是卡片；页面大 section 应保持无外框或全宽分区。

## 学生端重点

- 首页首屏突出当前租户品牌、地区、SVIP 状态、题库入口、背单词、知识手册、分数线、资料和个人中心，不默认展示排行榜。
- 刷题页优先保障题干/选项/解析可读，题目图片区、公式、阅读理解/案例分析子题不要挤压答题按钮。
- 错题本和收藏夹入口要保持短路径，复习入口必须走后端组卷。
- 资料和视频必须显示后端返回的短签名、过期时间、水印 traceId 或播放授权状态，不拼接私有 URL。
- 学生头像只提供男女预设，不做上传、裁剪或第三方头像同步。

## 后台重点

- 租户后台首页以权限驱动模块入口为主，按钮和 tab 可横向滚动，避免小屏换行导致操作错位。
- 内容导入、财务、分佣、CRM、学生运营这些页面要保留结果/错误/状态区域，不能只做提交表单。
- 平台后台要明显区分平台全局操作和租户操作，账务、授权、员工权限变更必须有二次确认或状态反馈。
- 前端菜单隐藏只做体验优化，所有权限以后端 permission keys、RLS 和审计为准。

## 自动守卫

新增或重做 Taro 样式后运行：

```bash
npm run test:readiness
node scripts/taro-visual-guardrails.js
npm run smoke:taro:h5
npm run smoke:taro:h5:interaction
```

`taro-visual-guardrails` 会扫描 `apps/taro/src/**/*.css`，阻断：

- 卡片、按钮、面板、输入框出现超过旧题库 `32px` 尺度的大圆角。
- 进度条/chip/badge/pill/头像/滚动条/装饰标记之外滥用 `999px` 大圆角。
- 使用 `vw/vh/vmin/vmax` 做字体大小。
- 负 `letter-spacing`。
- 装饰性径向渐变、裸 `filter: blur()`、未登记的 `backdrop-filter` 或未登记线性渐变。

如确实需要新增例外，必须先说明 UI 目的，再更新 `scripts/taro-visual-guardrails.js` 的白名单和这份文档。