docs: add design system and UI refresh plan

2026-08-07 15:12:10 +08:00
parent 2182b6dfc9
commit 5cca31c295
4 changed files with 3935 additions and 345 deletions
@@ -0,0 +1,428 @@
+# 智绘微刻小程序全量 UI 换肤实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 按 `design.md` 将 Taro 微信小程序的全局样式、主题配置、自定义 TabBar、通用组件和全部页面 UI 从旧手账风格迁移到新的克制现代风格。
+
+**Architecture:** 以 `src/app.scss` 的 CSS Token 为单一视觉源；先建立新 token 和公共组件类，再把同名 `.btn-gradient`/`.btn-outline`/`.dashed-card`/`.star-badge` 逐页替换为 `--accent-primary` 等新语义；最后更新图标、主题配置并跑 `build:weapp` 验证。
+
+**Tech Stack:** Taro 3 + React + TypeScript + Sass，微信小程序，自定义 TabBar，CSS variables，`rpx` 为主单位。
+
+---
+
+## Global Constraints
+
+- 遵守 `/Users/broccoli/Project/wechat_wc/design.md` 的全部 token、组件、间距、圆角、毛玻璃和动效规范。
+- 浅色主背景 `#faf7f2`，深色主背景 `#191919`；主色 `#d96c6a` / 深色 `#f09198`；辅助色 `#6c7bdb` / 深色 `#8e97e8`。
+- 删除 `3px dashed` 卡片与 `star-badge` 星星贴纸装饰；所有卡片改为 `1rpx solid var(--border)` + `--shadow-card`。
+- 自定义 TabBar 和底部操作栏使用毛玻璃：浅色 `rgba(255,255,255,.55)`，深色 `rgba(25,25,25,.55)`，`backdrop-filter: blur(32px) saturate(1.2)` + `-webkit-backdrop-filter`。
+- 可滚动页面底部保留足够空白，避免浮动底栏遮挡内容；全局 `.safe-bottom-placeholder` 高度调整为 200px。
+- 尺寸以 750rpx 设计稿为准；主要触控目标不小于 88rpx。
+- 不使用 optional chaining、nullish coalescing；JS 中避免 `?.` 与 `??`。
+- 不直接修改 `dist/`；只改 `src/`，构建产物由 `npm run build:weapp` 重新生成。
+- 图标继续使用项目本地 SVG/PNG，不新增 emoji 图标；SVG 中旧粉色 `#ff9a9e` 统一换为 `#d96c6a`。
+
+---
+
+### Task 1: 全局 Token 与基础样式
+
+**Files:**
+- Modify: `src/app.scss`
+- Modify: `src/theme.json`
+- Modify: `src/app.config.ts`
+
+**Interfaces:**
+- Consumes: `design.md` 的 token 表。
+- Produces: 新的全局 CSS 变量名与公共类名，供后续所有页面使用。
+
+- [ ] **Step 1: 替换 `src/app.scss` 的 `.theme-light` token**
+  把浅色 token 更新为：
+
+```scss
+--bg-page: #faf7f2;
+--bg-card: #ffffff;
+--bg-muted: #f3eee7;
+--bg-input: #f5f1eb;
+--text-primary: #2e2622;
+--text-secondary: #8a7e76;
+--text-muted: #b3a89e;
+--accent-primary: #d96c6a;
+--accent-primary-strong: #c75b59;
+--accent-primary-soft: #f6e0dc;
+--accent-secondary: #6c7bdb;
+--accent-secondary-soft: rgba(108, 123, 219, 0.12);
+--success: #4fa477;
+--warning: #d99a4e;
+--danger: #d85d5d;
+--border: #ede5dc;
+--border-strong: #e0d5c8;
+--glass: rgba(255, 255, 255, 0.72);
+--glass-line: rgba(255, 255, 255, 0.55);
+--shadow-card: 0 8rpx 24rpx rgba(46, 38, 34, 0.08);
+--shadow-elevated: 0 12rpx 40rpx rgba(46, 38, 34, 0.12);
+```
+
+保留旧 token 作为过渡别名，指向新值，供尚未迁移的页面继续使用；最后一轮统一清理：
+
+```scss
+--line-card: 1rpx solid var(--border);
+--line-star: var(--border);
+--accent-pink: var(--accent-primary);
+--accent-blue: var(--accent-secondary);
+```
+
+- [ ] **Step 2: 替换 `src/app.scss` 的 `.theme-dark` token**
+  深色 token 更新为：
+
+```scss
+--bg-page: #191919;
+--bg-card: #23201d;
+--bg-muted: #2b2622;
+--bg-input: #2b2622;
+--text-primary: #f5efe8;
+--text-secondary: #b3a79c;
+--text-muted: #82766c;
+--accent-primary: #f09198;
+--accent-primary-strong: #ffa7ad;
+--accent-primary-soft: rgba(240, 145, 152, 0.14);
+--accent-secondary: #8e97e8;
+--accent-secondary-soft: rgba(142, 151, 232, 0.14);
+--success: #67c58e;
+--warning: #e0ad68;
+--danger: #ef7a7a;
+--border: #37312c;
+--border-strong: #463e37;
+--glass: rgba(25, 25, 25, 0.72);
+--glass-line: rgba(255, 255, 255, 0.14);
+--shadow-card: 0 8rpx 24rpx rgba(0, 0, 0, 0.32);
+--shadow-elevated: 0 12rpx 40rpx rgba(0, 0, 0, 0.48);
+```
+
+- [ ] **Step 3: 删除旧装饰类**
+  删除 `.dashed-card`、`.star-badge` 的旧视觉实现，删除 `.btn-gradient` 旧渐变属性、`.btn-outline` 旧虚线属性，改为设计系统类：
+
+```scss
+.surface-card {
+  background: var(--bg-card);
+  border: 1rpx solid var(--border);
+  border-radius: 24rpx;
+  box-shadow: var(--shadow-card);
+}
+
+.btn-primary {
+  background: var(--accent-primary);
+  color: #fff;
+  border-radius: 999rpx;
+}
+
+.btn-secondary {
+  background: var(--bg-card);
+  color: var(--text-primary);
+  border: 1rpx solid var(--border-strong);
+  border-radius: 999rpx;
+}
+
+.btn-ghost {
+  background: transparent;
+  color: var(--accent-primary);
+}
+
+.btn-danger {
+  background: var(--danger);
+  color: #fff;
+  border-radius: 999rpx;
+}
+
+.action-bar {
+  background: rgba(255, 255, 255, 0.55);
+  backdrop-filter: blur(32px) saturate(1.2);
+  -webkit-backdrop-filter: blur(32px) saturate(1.2);
+  border-top: 1rpx solid var(--glass-line);
+}
+```
+
+为兼容旧页面中的类名，保留两个按钮过渡别名：
+
+```scss
+.btn-gradient { @extend .btn-primary; }
+.btn-outline { @extend .btn-secondary; }
+```
+
+同时保留 `.badge`/`.badge-*` 基础结构，但颜色改为新 token：`--success`、`--warning`、`--danger`、`--accent-primary-soft`。
+
+- [ ] **Step 4: 更新 `.safe-bottom-placeholder`**
+  将 `height: 160px` 改为 `height: 200px`。
+
+- [ ] **Step 5: 更新 `src/theme.json`**
+  浅色 `bgColor`/`navBgColor`/`bgColorTop`/`bgColorBottom`/`tabBarBgColor` 改为 `#faf7f2`；`tabBarColor` 改为 `#8a7e76`；`tabBarSelectedColor` 改为 `#d96c6a`。
+  深色 `tabBarColor` 改为 `#b3a79c`；`tabBarSelectedColor` 改为 `#f09198`。
+
+- [ ] **Step 6: 更新 `src/app.config.ts`**
+  `window.navigationBarBackgroundColor`、`backgroundColor`、`backgroundColorTop`、`backgroundColorBottom` 改为 `#faf7f2`。
+
+- [ ] **Step 7: 提交**
+
+```bash
+git add src/app.scss src/theme.json src/app.config.ts
+git commit -m "feat: update global tokens and remove legacy decorations"
+```
+
+---
+
+### Task 2: 主题背景与自定义导航
+
+**Files:**
+- Modify: `src/utils/themeBackground.ts`
+- Modify: `src/components/ThemedPageMeta/index.tsx`
+- Modify: `src/hooks/useStatusBar.ts`
+
+**Interfaces:**
+- Consumes: Task 1 的浅色/深色背景 token。
+- Produces: 所有页面顶部状态栏、胶囊区、背景始终同步 `#faf7f2` / `#191919`。
+
+- [ ] **Step 1:** 将 `themePageColor('light')` 由 `'#ffffff'` 改为 `'#faf7f2'`。
+- [ ] **Step 2:** `ThemedPageMeta` 中 `bg` 由浅色 `'#ffffff'` 改为 `'#faf7f2'`，深色保持 `'#191919'`。
+- [ ] **Step 3:** `useStatusBar` 中浅色 `backgroundColor` 改为 `'#faf7f2'`。
+- [ ] **Step 4:** 跑 `npm run build:weapp` 确认无编译错误后提交。
+
+```bash
+git add src/utils/themeBackground.ts src/components/ThemedPageMeta/index.tsx src/hooks/useStatusBar.ts
+git commit -m "feat: sync theme background tokens"
+```
+
+---
+
+### Task 3: 自定义 TabBar 毛玻璃
+
+**Files:**
+- Modify: `src/custom-tab-bar/index.scss`
+- Modify: `src/custom-tab-bar/index.tsx`
+- Modify: `src/icon/*.svg`（默认色值批量替换）
+
+**Interfaces:**
+- Consumes: 自定义 TabBar 现有的 5 个 tab 配置和图标。
+- Produces: 悬浮毛玻璃 TabBar，选中态使用新主色。
+
+- [ ] **Step 1:** 重写 `src/custom-tab-bar/index.scss`
+  - 容器改为 `left: 12px; right: 12px; bottom: 12px;`，`border-radius: 24px`，`height: calc(96px + env(safe-area-inset-bottom))`。
+  - 浅色背景 `rgba(255, 255, 255, 0.55)`，深色背景 `rgba(25, 25, 25, 0.55)`，两者都加 `backdrop-filter: blur(32px) saturate(1.2)` 和 `-webkit-backdrop-filter`。
+  - 文字普通态 `#8a7e76`，选中态 `#d96c6a`；深色普通态 `#b3a79c`，选中态 `#f09198`。
+  - 图标尺寸沿用 40rpx，选中态 `transform: scale(1.08)`。
+
+- [ ] **Step 2:** 批量更新 SVG 图标默认颜色
+
+```bash
+perl -pi -e 's/#ff9a9e/#d96c6a/g; s/#b08d8d/#8a7e76/g' src/icon/*.svg
+```
+
+只替换纯文本 SVG 颜色；PNG 图标保持不变。
+
+- [ ] **Step 3:** 提交
+
+```bash
+git add src/custom-tab-bar src/icon
+git commit -m "feat: frosted floating tab bar and updated icon colors"
+```
+
+---
+
+### Task 4: 通用组件登录与主题按钮
+
+**Files:**
+- Modify: `src/components/LoginModal/index.scss`
+- Modify: `src/components/LoginModal/index.tsx`
+- Modify: `src/components/LoginGuard/index.scss`
+- Modify: `src/components/LoginGuard/index.tsx`
+- Modify: `src/components/ThemeToggle/index.scss`
+
+**Interfaces:**
+- Consumes: Task 1 的 `.surface-card`、`.btn-primary`、`.btn-secondary`。
+- Produces: 登录弹窗、登录守卫、主题按钮使用新视觉。
+
+- [ ] **Step 1:** `LoginModal/index.tsx` 中把 `login-card dashed-card` 改为 `surface-card login-card`，删除 `star-badge`。
+- [ ] **Step 2:** `LoginModal/index.tsx` 中把 `btn-outline` 替换为 `btn-secondary`，`btn-gradient` 替换为 `btn-primary`。
+- [ ] **Step 3:** `LoginModal/index.scss` 删除 `3px dashed var(--line-star)`；`avatar-btn`、`.nickname-input` 改 `1rpx solid var(--border)`，聚焦/错误按设计规范补 `--accent-primary`。
+- [ ] **Step 4:** `LoginGuard/index.tsx` 中 `btn-gradient` 替换为 `btn-primary`，`index.scss` 更新 token 引用。
+- [ ] **Step 5:** `ThemeToggle/index.scss` 圆角保持 50%，背景改为 `rgba(25, 25, 25, 0.42)`，文字仍简短保留。
+
+- [ ] **Step 6:** 跑 `npm run build:weapp` 后提交。
+
+```bash
+git add src/components src/custom-tab-bar
+git commit -m "feat: refresh login components"
+```
+
+---
+
+### Task 5: 首页与商品列表
+
+**Files:**
+- Modify: `src/pages/index/index.scss`
+- Modify: `src/pages/index/index.tsx`
+- Modify: `src/pages/shop/index.scss`
+- Modify: `src/pages/shop/index.tsx`
+**Interfaces:**
+- Consumes: Task 1 的 public classes 与 token。
+- Produces: 首页、商品列表页无旧虚线/星星，且主题、间距、卡片符合 `design.md`。
+
+- [ ] **Step 1:** 在 `index.tsx` 删除所有 `star-badge`，将所有 `dashed-card` 改为 `surface-card`，`btn-gradient` 改 `btn-primary`，`btn-outline` 改 `btn-secondary`。
+- [ ] **Step 2:** `index.scss` 中 `#f8f9fa`、`--accent-pink`、`--line-star` 全部替换为新 token；轮播 indicator 颜色改 `#d96c6a` / `#e0d5c8`。
+- [ ] **Step 3:** `shop/index.tsx` 底部 `height: 160px` 改为 `200px`；`shop-card-price` 颜色改 `var(--accent-primary)`。
+- [ ] **Step 4:** `shop/index.scss` 的 `#ff9a9e` 改 `var(--accent-primary)`，删除任何虚线和旧色硬编码。
+- [ ] **Step 5:** 跑构建并提交。
+
+```bash
+git add src/pages/index src/pages/shop
+git commit -m "feat: refresh home and shop pages"
+```
+
+---
+
+### Task 6: 商品详情与定制流程
+
+**Files:**
+- Modify: `src/pages/product/index.scss`
+- Modify: `src/pages/product/index.tsx`
+- Modify: `src/pages/shop/detail/index.scss`
+- Modify: `src/pages/shop/detail/index.tsx`
+- Modify: `src/pages/diy/index.scss`
+- Modify: `src/pages/diy/index.tsx`
+- Modify: `src/pages/diy/stickerEdit/index.scss`
+- Modify: `src/pages/diy/stickerEdit/index.tsx`
+- Modify: `src/pages/checkout/index.scss`
+- Modify: `src/pages/checkout/index.tsx`
+
+**Interfaces:**
+- Consumes: 全局毛玻璃 `.action-bar`、`.surface-card`、`.btn-primary`。
+- Produces: 商品详情、定制工作台、贴纸编辑、结算页统一为毛玻璃底部操作 + 新 token。
+
+- [ ] **Step 1:** 在所有 TSX 中删除 `star-badge`，把 `dashed-card` 改为 `surface-card`，把 `btn-gradient`/`btn-outline` 改为 `btn-primary`/`btn-secondary`。
+- [ ] **Step 2:** `product/index.scss` 顶部 `padding-bottom: calc(24px + 160px)` 改为 `calc(24px + 200px)`；`.action-bar` 借用全局毛玻璃样式。
+- [ ] **Step 3:** `checkout/index.scss` 与 `orderDetail/index.scss` 中 `addr-picker-add`、虚线边框全部改为 `1rpx solid var(--border-strong)` 或 `var(--border)`。
+- [ ] **Step 4:** `shop/detail/index.scss` 删除 `#ff9a9e`、`#fecfef` 渐变，改成新 token 和新毛玻璃/卡片阴影。
+- [ ] **Step 5:** `diy` 与 `stickerEdit` 的虚线边框、`--accent-blue`、`--accent-pink` 全部替换为新 token；底部操作栏使用 `.action-bar` 毛玻璃规则。
+- [ ] **Step 6:** 跑构建并提交。
+
+```bash
+git add src/pages/product src/pages/shop/detail src/pages/diy src/pages/checkout
+git commit -m "feat: refresh product and customization flows"
+```
+
+---
+
+### Task 7: 设计清单、订单、订单详情
+
+**Files:**
+- Modify: `src/pages/designList/index.scss`
+- Modify: `src/pages/designList/index.tsx`
+- Modify: `src/pages/orders/index.scss`
+- Modify: `src/pages/orders/index.tsx`
+- Modify: `src/pages/orderDetail/index.scss`
+- Modify: `src/pages/orderDetail/index.tsx`
+
+**Interfaces:**
+- Consumes: `.surface-card`、`.btn-primary`、`.btn-secondary`、新 token。
+- Produces: 设计清单、订单列表、订单详情页符合设计规范。
+
+- [ ] **Step 1:** 删除所有 `star-badge` 与 `dashed-card`，改用 `.surface-card`。
+- [ ] **Step 2:** 所有 TSX 的 `btn-gradient`/`btn-outline` 改 `btn-primary`/`btn-secondary`。
+- [ ] **Step 3:** `orders/index.scss` 删除 `#b08d8d`、`#ff9a9e`、`#5c3a3a`，改 token。
+- [ ] **Step 4:** `orderDetail/index.scss` 中虚线边框、`.addr-picker-*`、状态按钮颜色改为新 token 与毛玻璃规则。
+- [ ] **Step 5:** 跑构建并提交。
+
+```bash
+git add src/pages/designList src/pages/orders src/pages/orderDetail
+git commit -m "feat: refresh design list and order pages"
+```
+
+---
+
+### Task 8: 个人中心与入口页
+
+**Files:**
+- Modify: `src/pages/profile/index.scss`
+- Modify: `src/pages/profile/index.tsx`
+- Modify: `src/pages/settings/index.scss`
+- Modify: `src/pages/settings/index.tsx`
+- Modify: `src/pages/address/index.scss`
+- Modify: `src/pages/address/index.tsx`
+- Modify: `src/pages/agreement/index.scss`
+- Modify: `src/pages/agreement/index.tsx`
+
+**Interfaces:**
+- Consumes: Task 1 全局类。
+- Produces: 个人中心、设置、地址、协议页去掉旧装饰。
+
+- [ ] **Step 1:** 删除各 TSX 中 `star-badge`，`dashed-card` 改 `surface-card`，按钮类名更新。
+- [ ] **Step 2:** `profile/index.scss` 线性渐变背景只保留中性 `--bg-card`/`--bg-muted` 或极淡辅助色，不继续使用旧粉色/蓝色大渐变。
+- [ ] **Step 3:** `settings/index.scss`、`address/index.scss` 中 `--accent-pink`/`--accent-blue` 全部替换。
+- [ ] **Step 4:** `agreement/index.scss` 只更新 token 与间距，无装饰元素可保留。
+- [ ] **Step 5:** 跑构建并提交。
+
+```bash
+git add src/pages/profile src/pages/settings src/pages/address src/pages/agreement
+git commit -m "feat: refresh profile and settings pages"
+```
+
+---
+
+### Task 9: 客服、词云、用户数据库
+
+**Files:**
+- Modify: `src/pages/service/index.scss`
+- Modify: `src/pages/service/index.tsx`
+- Modify: `src/pages/wordcloud/index.scss`
+- Modify: `src/pages/wordcloud/index.tsx`
+- Modify: `src/pages/userDatabase/index.scss`
+- Modify: `src/pages/userDatabase/index.tsx`
+
+**Interfaces:**
+- Consumes: Task 1 全局类。
+- Produces: 客服、词云、用户数据库页无旧装饰。
+
+- [ ] **Step 1:** 删除 `star-badge`，`dashed-card` 改 `surface-card`，按钮更新为 `.btn-primary`/`.btn-secondary`。
+- [ ] **Step 2:** `wordcloud/index.scss` 中 `.upload-area`、`.input-section`、结果图容器改为 `1rpx solid var(--border)` + 24rpx 圆角。
+- [ ] **Step 3:** `userDatabase/index.scss` 中旧 `.btn-gradient`/`--accent-blue` 全部替换。
+- [ ] **Step 4:** 跑构建并提交。
+
+```bash
+git add src/pages/service src/pages/wordcloud src/pages/userDatabase
+git commit -m "feat: refresh service and tool pages"
+```
+
+---
+
+### Task 10: 构建验证与残留清理
+
+**Files:**
+- All `src/**/*.scss`, `src/**/*.tsx`
+
+**Interfaces:**
+- Consumes: 前序任务成果。
+- Produces: 一个可构建、无旧风格残留的代码库。
+
+- [ ] **Step 1:** 全局搜索确认不再出现旧风格残留（`--accent-pink`/`--accent-blue` 的过渡别名在此时移除后允许为 0 命中）：
+
+```bash
+rg -n "star-badge|dashed-card|accent-pink|accent-blue|btn-gradient|btn-outline|#ff9a9e|#fecfef|#b08d8d|#5c3a3a|--line-card|--line-star" src --glob '!**/*.png'
+```
+
+如仍有残留，修复到没有命中（除 Task 3 已批量替换外）。
+
+- [ ] **Step 2:** 删除 `src/app.scss` 中的过渡别名 `--line-card`、`--line-star`、`--accent-pink`、`--accent-blue`，并移除 `.btn-gradient` / `.btn-outline` 的 `@extend` 别名；把页面中残留的这两个类名改为 `.btn-primary` / `.btn-secondary`。
+
+- [ ] **Step 3:** 构建：
+
+```bash
+cd /Users/broccoli/Project/wechat_wc && npm run build:weapp
+```
+
+预期成功且无 TS/Sass 错误。
+
+- [ ] **Step 4:** 检查 `dist/` 重新生成，若需要提交则加入提交；如用户未要求则不手动覆盖 dist。
+
+---
+
+## Completion
+
+全部任务完成后执行 `superpowers:requesting-code-review` 做最终代码审查；确认无阻塞问题后用 `superpowers:finishing-a-development-branch` 收尾。