hms/docs/superpowers/specs/2026-05-16-miniprogram-unified-components-design.md

小程序统一组件库设计规格

日期: 2026-05-16 | 状态: 编写中 | 方案: 三层架构（原子 + 模式 + Hook）

---

1. 背景与问题

小程序端 66 个页面存在严重 UI 不统一：59 页手写骨架、119 处卡片重写、9+ 列表页无模板、关怀模式未覆盖 doctor 端。根因是缺少组件级统一抽象。

目标：改 1 处组件 = 全部页面同步；页面代码减少 ~70%；关怀 100% 覆盖。

2. 设计决策

三层架构 | 仅小程序端 | 温润东方风 | 组件级关怀 | 渐进迁移

3. 目录结构

components/ui/ (原子) → components/patterns/ (组合) → hooks/useListPage.ts (Hook)

4. 第 1 层：原子组件

PageShell — 页面容器。padding 语义化（none/sm/md/lg），safeBottom，scroll 包裹。 ContentCard — 卡片。3 种 variant，统一圆角/阴影/触摸反馈。 StatusTag — 状态标签。内置 5 色映射，pill 圆角。 SectionTitle — 段落标题。赤土橙竖线装饰。 LoadingCard — 骨架屏。与 ContentCard 同尺寸。

5. 第 2 层：组合模式

PageHeader — 页面顶部（title + back + actions）。 SearchSection — 搜索区域（搜索框 + 可选筛选标签）。 CardList — 列表容器（自动处理 loading/error/empty）。 PaginationBar — 分页控制（替代 2 种命名体系）。

6. 第 3 层：useListPage Hook

封装分页/搜索/筛选/加载/空状态。返回 listPageProps 可直接展开给组合组件。列表页从 ~120 行降至 ~35 行。

---

7. 关怀模式集成

现状问题

当前关怀模式通过 elder-mode.scss 全局 CSS 覆写实现，存在 3 个问题：

1. 按类名匹配，新增页面不用正确类名就漏掉
2. doctor 端页面完全不在覆写范围内
3. 每次改组件样式都要同步改 elder-mode.scss

新方案：组件级自适应

每个原子组件内部全部读取 CSS 变量，关怀模式只需改变量值：

1. 扩展 tokens.scss — 新增结构化 Token：

--tk-card-bg: #fff                  // 卡片背景
--tk-card-padding: 24px             // 卡片内间距
--tk-card-radius: 16px              // 卡片圆角
--tk-gap-sm: 12px                   // 小间距
--tk-gap-md: 16px                   // 中间距
--tk-gap-lg: 24px                   // 大间距
--tk-page-padding: 24px             // 页面内间距
--tk-touch-feedback-opacity: 0.85   // 触摸反馈透明度

2. 原子组件全部读变量 — ContentCard 的 padding 使用 var(--tk-card-padding)，border-radius 使用 var(--tk-card-radius)

3. elder-mode.scss 只覆写变量值：

.elder-mode {
  --tk-card-padding: 32px;          // 24px → 32px
  --tk-card-radius: 20px;           // 16px → 20px
  --tk-gap-md: 20px;                // 16px → 20px
  --tk-page-padding: 32px;          // 24px → 32px
  // ... 已有字号/触控变量保持不变
}

4. 新页面自动获得关怀支持 — 只要使用原子组件，无需额外代码

5. 精简 elder-mode.scss — 只保留页面级特殊覆写（如体征网格 2 列→1 列），不再需要组件级覆写

---

8. 迁移策略

Phase 1：创建组件 + Token 扩展（~2天）

• 扩展 tokens.scss 新增 --tk-card-*、--tk-gap-*、--tk-page-* 等结构化 Token
• 实现 5 个原子组件 + 4 个组合组件 + useListPage Hook
• 每个组件编写基本测试（渲染/Props/变体）
• 不动任何现有页面，新组件与旧代码并行

Phase 2：迁移 doctor 端列表页（~1.5天）

• 选择 patients 列表页做试点 — 完整迁移 + 截图对比验证
• 批量迁移剩余 8 个列表页：dialysis, prescription, report, alerts, consultation(doctor), followup, article, consultation(患者)
• 每页迁移后：截图对比 → 功能验证（搜索/分页/空状态）→ 确认无回归

Phase 3：迁移非列表页 + 关怀模式（~1.5天）

• 首页、详情页、表单页等迁移为 PageShell + ContentCard
• 扩展 elder-mode.scss 结构化 Token 覆写
• doctor 端页面首次获得关怀模式支持
• 全量页面关怀模式验证

Phase 4：清理旧代码 + 文档（~0.5天）

• 删除各页面不再使用的手写样式（.search-bar, .xxx-card, .pagination 等）
• 清理未使用的 mixins（card 等）
• 精简 elder-mode.scss 为纯页面级特殊覆写
• 编写组件使用文档

---

9. 预期效果

指标	改造前	改造后
页面模板代码	~120 行/页	~35 行/页
卡片样式定义	119 处分散	1 处 ContentCard
搜索栏实现	4 处重写	1 个 SearchSection
分页器体系	2 种混用	1 个 PaginationBar
状态标签实现	3 种方式	1 个 StatusTag
关怀模式覆盖	仅患者端 TabBar	100%（含 doctor 端）
新功能 UI 开发	从零手写	组装组件

---

10. 验证方式

每个迁移阶段完成后执行：

• 视觉对比 — 截图对比改造前后，确保一致
• 功能验证 — 搜索、分页、空状态、错误状态均正常
• 关怀模式 — 切换后全量页面自适应无异常
• 构建通过 — pnpm build 无报错
• 真机预览 — DevTools 或真机预览验证触摸反馈和交互