gongxue-base/docs/refactor/taro-visual-language.md

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 样式后运行：

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 的白名单和这份文档。