---
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` |