docs: add taro visual guardrails

docs/refactor/frontend-handoff-index.md

@@ -20,13 +20,15 @@
    - Taro 启动、租户解析、请求封装、页面/API 映射、跨端注意事项。
 7. `docs/refactor/taro-h5-deployment.md`
    - H5 三域名部署、`runtime-config.json`、Nginx history fallback、缓存、CSP 和 CORS 边界。
-8. `docs/refactor/taro-production-integration-checklist.md`
+8. `docs/refactor/taro-visual-language.md`
+   - 学生端、租户后台、平台后台的视觉语言、旧题库参考边界、8px 圆角/工具型页面规范和 CSS 守卫。
+9. `docs/refactor/taro-production-integration-checklist.md`
    - 正式接 Supabase Auth、三套 H5、真实 provider、runtime-config 和上线门禁时逐项对照。
-9. `docs/refactor/multitenant-auth-security-contract.md`
+10. `docs/refactor/multitenant-auth-security-contract.md`
    - 多租户、鉴权、权限、资源签名和生产安全红线。
-10. `docs/refactor/content-import-contract.md`
+11. `docs/refactor/content-import-contract.md`
    - 后台内容导入、题目 JSON、单词、知识手册、分数线、视频的后端校验契约。
-11. `docs/refactor/production-launch-evidence.template.json`
+12. `docs/refactor/production-launch-evidence.template.json`
    - 上线前证据文件模板；真实生产验收结果填入 `production-launch-evidence.json` 后运行 `npm run launch:gate`，该真实证据文件不入 Git。
 
 ## 当前可进入的前端工作
@@ -46,6 +48,7 @@
 - 新增、删除或重命名 Taro 页面时必须同步 `apps/taro/src/app.config.ts`、启动页跳转、H5 静态烟测入口和本文页面清单，并运行 `node scripts/taro-route-contract-test.js`。该脚本会阻断“页面文件存在但未注册”“路由注册但文件缺失”“启动页或烟测跳到不存在页面”的漂移。
 - 新增或修改 Taro API service 时必须运行 `node scripts/taro-api-contract-test.js`。该脚本会比对前端 `apiRequest('/api/...')` 与后端 `RouteDefinition[]` 注册表，阻断调用不存在的接口、method 写错或绕过统一 API client；动态路由只能通过脚本 allowlist 明确声明。
 - 修改学生端、租户后台或平台后台关键页面时必须运行 `node scripts/taro-persona-contract-test.js`。该脚本按学生刷题/会员订单/错题收藏、租户学生运营/内容导入/营销财务/品牌权限、平台租户/账务/公共题库/员工权限三类角色旅程检查路由和服务调用，避免前端样式重做时误删核心业务入口。
+- 修改 Taro CSS 或新建页面样式时必须运行 `npm run guard:taro:visual`。该脚本会阻断大圆角卡片、视口字体、负字距、装饰性径向渐变/模糊背景和未登记线性渐变；视觉规范见 `docs/refactor/taro-visual-language.md`。
 - H5 构建完成后必须运行 `npm run smoke:taro:h5:interaction` 做真实浏览器点击验证。它会覆盖学生首页到题库练习、答题、收藏、会员收银台下单/支付参数/订单状态，租户后台工作台到题库内容/财务运营，以及平台后台工作台到租户管理/账务中心；如果 Chrome/Edge 缺失，可设置 `TARO_H5_SMOKE_BROWSER` 指向 Chromium 浏览器。
 - H5 可以优先验证 `@supabase/supabase-js` 管理 Auth session；微信小程序端先验证运行时兼容性，业务数据默认仍走 `apps/api`。
 - H5 生产部署优先用每个静态目录自己的 `runtime-config.json` 配置 `apiBaseUrl`、`supabaseUrl`、`supabasePublishableKey`、`tenantCode`；不要为了换域名重打包，也不要把任何 service role、数据库、支付、短信、对象存储密钥放进该文件。

docs/refactor/taro-production-integration-checklist.md

@@ -60,6 +60,7 @@
 ```bash
 npm run check:taro
 npm run test:readiness
+npm run guard:taro:visual
 npm run smoke:taro:h5
 npm run smoke:taro:h5:interaction
 node scripts/taro-h5-release-guardrails-test.js --require-dist --require-runtime-config

docs/refactor/taro-visual-language.md

@@ -0,0 +1,71 @@
+# Taro H5 视觉语言规范
+
+更新时间：2026-07-01
+
+这份规范用于约束 `apps/taro` 的学生端、租户后台和平台后台。旧题库前端参考目录为 `F:\project\参考\旧题库小程序前端文件`，只作为页面状态、学习流程、后台信息密度和微信平台交互的参考，不继承旧 PocketBase 直连、旧鉴权、旧字段模型或旧技术栈。
+
+## 总原则
+
+- Taro 是前端体验层：负责路由、布局、交互、公开运行时配置、Supabase Auth session 和统一 API client；复杂业务判断、权限、价格、权益、导入、支付、CRM 和对象存储签名以后端为准。
+- Web 首发优先做成可反复使用的工具型产品，不做营销落地页式的大图 Hero、装饰卡片堆叠、渐变背景和过度留白。
+- 学生端要接近旧题库小程序的学习节奏：入口清楚、题目阅读专注、答题卡稳定、错题/收藏/报告路径短。
+- 租户后台和平台后台要接近运营工具：信息密度高、层级清楚、操作按钮固定、列表和指标可扫读。
+
+## 视觉基线
+
+| 项 | 规范 |
+| --- | --- |
+| 页面背景 | `#f6f8fb`、`#f8fafc`、`#f7f9fc` 这类浅灰蓝工作台背景 |
+| 主文字 | `#0f172a`、`#111827`、`#172033` |
+| 次级文字 | `#64748b`、`#475569` |
+| 主色 | `#2563eb` / `#1d4ed8`，租户发布主题后可由后端安全 token 覆盖 |
+| 成功/强调 | `#10b981`、`#16a34a`，只用于进度、完成、兑换等状态 |
+| 危险 | `#be123c`、`#dc2626`，只用于退款、驳回、删除、失败 |
+| 圆角 | 卡片、按钮、输入框、面板统一不超过 `8px`；小进度条、chip、badge 可用 `999px` |
+| 字体 | 固定 px/rpx 风格，不使用 `vw/vh/vmin/vmax` 缩放字体 |
+| 字距 | 不使用负 `letter-spacing` |
+| 装饰 | 禁止径向渐变、模糊光斑、装饰性大渐变背景；头像预设和水印纹理是当前允许例外 |
+
+## 页面结构
+
+- 学生端页面使用 `student-page`、`student-topbar`、`section-block`、`list-stack`、`quiet-panel` 等现有类名体系。
+- 租户后台使用 `admin-page`、`admin-shell`、`admin-header`、`admin-metric`、`admin-row`、`admin-button`。
+- 平台后台使用 `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`，阻断：
+
+- 卡片、按钮、面板、输入框出现超过 `8px` 的圆角。
+- 进度条/chip/badge/pill 之外滥用 `999px` 大圆角。
+- 使用 `vw/vh/vmin/vmax` 做字体大小。
+- 负 `letter-spacing`。
+- 装饰性径向渐变、模糊背景和未登记线性渐变。
+
+如确实需要新增例外，必须先说明 UI 目的，再更新 `scripts/taro-visual-guardrails.js` 的白名单和这份文档。