1

_DEL/mp-h5-dev.md

@@ -0,0 +1,130 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "**/*.wxml,**/*.wxss,**/h5_ui/**,**/miniprogram/miniprogram/pages/**,**/miniprogram-dev/**"
+name: mp-h5-dev
+description: 小程序页面开发详细规范。读取 wxml/wxss/h5_ui/miniprogram 页面文件时自动加载。
+---
+
+# 小程序页面开发详细规范
+
+硬性规则见 always-on steering `mp-h5-rules.md`。本文件补充开发流程和详细参考值。
+
+## 完整颜色灰阶（13 级）
+
+| Token | Hex | 用途 |
+|-------|-----|------|
+| gray-1 | #f3f3f3 | 页面背景 |
+| gray-2 | #eeeeee | 分隔线 |
+| gray-3 | #e7e7e7 | 边框 |
+| gray-4 | #dcdcdc | 禁用态 |
+| gray-5 | #c5c5c5 | — |
+| gray-6 | #a6a6a6 | 辅助文字 |
+| gray-7 | #8b8b8b | TabBar 默认色 |
+| gray-8 | #777777 | — |
+| gray-9 | #5e5e5e | 次要文字 |
+| gray-10 | #4b4b4b | — |
+| gray-11 | #393939 | — |
+| gray-12 | #2c2c2c | — |
+| gray-13 | #242424 | 主文字 |
+
+## border-radius 标准值
+
+sm 8rpx(rounded) | md 16rpx(rounded-lg) | lg 24rpx(rounded-xl) | xl 32rpx(rounded-2xl) | 3xl 48rpx(rounded-3xl)
+
+## 阴影标准值
+
+lg: `0 8rpx 32rpx rgba(0,0,0,0.06)` | xl: `0 16rpx 48rpx rgba(0,0,0,0.08)`
+
+## 固定高度元素（切断 rpx 取整累积漂移）
+
+Tab 栏 84rpx | 筛选栏 120rpx | 列表项 96rpx(标准)/112rpx(含副标题) | 按钮 80rpx | 底部操作区 112rpx
+
+## 页面模式（截图裁剪）
+
+模式 A（系统 navBar，无需裁剪）：board-finance, board-coach, board-customer, task-list, my-profile
+模式 B（自定义 navBar，裁剪头部 96px）：task-detail 系列, coach-detail, customer-detail, performance, notes, chat, chat-history, customer-service-records, performance-records
+
+## Sticky 高度
+
+board-finance 116px | board-coach 110px | board-customer 110px | 其他 0
+
+## 全局结构处理
+
+| H5 元素 | MP 处理 |
+|---------|---------|
+| `.safe-area-top` | 去除 padding-top，MP 由 navigationBar 处理 |
+| `#bottomNav` | 不迁移，MP 用原生 tabBar |
+| `.ai-float-btn-container` | `wx:if="{{false}}"` |
+| `<dev-fab />` | `wx:if="{{false}}"` |
+| `::before/::after` 视觉元素 | 额外 `<view>` 绝对定位模拟 |
+| Tab 指示线 `::after` | 额外 `<view>` 模拟 |
+| 气泡尖角 `::after` | 绝对定位 `<view>` + `transform: rotate(45deg)` |
+
+## 复杂视觉元素分层策略
+
+| 复杂度 | 示例 | 方案 |
+|--------|------|------|
+| L1 简单 | 纯色标签、单色图标 | WXSS 原生 |
+| L2 中等 | 渐变标签、多层 gradient | WXSS 多层渐变 |
+| L3 复杂 | 伪元素纹理、SVG data URI | 导出为图片/SVG 文件 |
+| L4 不可迁移 | `background-clip:text`、`conic-gradient` | 降级为近似纯色 |
+
+## Banner 迁移模板
+
+```xml
+<view class="banner-bg">
+  <view class="banner-texture"></view>  <!-- 替代 ::before -->
+  <view class="banner-glow"></view>     <!-- 替代 ::after -->
+  <view class="banner-content"><!-- 内容 --></view>
+</view>
+```
+
+## SVG 处理决策树
+
+1. TDesign 有等价图标 → `<t-icon name="xxx">`
+2. 品牌/自定义图标 → 导出到 `assets/icons/<name>.svg`，`<image>` 引用
+3. CSS 背景 `data:image/svg+xml` → 导出独立文件
+4. 简单几何图形 → WXSS border/transform 替代
+
+## 不可消除差异白名单
+
+字体渲染差异(Chromium vs WebView) | 行内元素高度偏小~7% | 抗锯齿差异 | 环比箭头(SVG vs 文字↑↓) | CSS 渐变文字→纯色
+
+## CSS 风险特性速查
+
+| 特性 | 出现页面 | 替代方案 |
+|------|---------|---------|
+| `backdrop-filter: blur()` | board-finance | `rgba(255,255,255,0.95)` |
+| `-webkit-background-clip: text` | board-customer | 纯色文字 |
+| `data:image/svg+xml` | reviewing, no-permission | 导出 PNG/SVG |
+| `position: fixed` | board-finance/coach/customer, task-list | `position: sticky` 或页面级 fixed |
+| `@font-face` 远程 | 所有页面 | 系统字体（推荐） |
+
+## 新页面 Checklist
+
+- [ ] 无 HTML 标签残留（div/span/p/a/img）
+- [ ] 内联 SVG 已提取为文件
+- [ ] 样式全部 WXSS（rpx 单位）
+- [ ] 不支持的 CSS 已替代
+- [ ] 事件 `bindtap`，传参 `data-*`
+- [ ] TDesign 组件在 .json 注册
+- [ ] 安全区适配（JS statusBarHeight）
+- [ ] `getDiagnostics` 零错误
+- [ ] `wx:key` 已添加
+- [ ] 布尔属性用 `{{}}` 包裹
+- [ ] mock 数据与 H5 一致
+
+## 关联资源路径
+
+| 资源 | 路径 |
+|------|------|
+| H5 原型 | `docs/h5_ui/pages/*.html` |
+| 设计 Token | `docs/h5_ui/design-tokens.json` |
+| 图标映射 | `docs/h5_ui/icon-mapping.md` |
+| 交互说明 | `docs/h5_ui/interactions/<page>.md` |
+| 截图产物 | `docs/h5_ui/compare/<page>/` |
+| MP 源码 | `apps/miniprogram/miniprogram/pages/` |
+| 迁移进度 | `docs/miniprogram-dev/04-audit/PROGRESS.md` |
+| 踩坑速查 | `docs/miniprogram-dev/05-lessons/pitfalls.md` |
+| 收敛模式 | `docs/miniprogram-dev/05-lessons/convergence-patterns.md` |
+| 页面结构速查 | `docs/miniprogram-dev/03-reference/page-structure-map.md` |