diff --git a/docs/superpowers/specs/2026-08-08-home-scroll-top-mask-design.md b/docs/superpowers/specs/2026-08-08-home-scroll-top-mask-design.md
new file mode 100644
index 0000000..9b39046
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-08-home-scroll-top-mask-design.md
@@ -0,0 +1,64 @@
+# 首页滚动顶部渐变遮罩设计
+
+## 背景
+
+当前小程序使用 `navigationStyle: 'custom'`，首页内容全屏铺开，顶部的时间、电量等状态栏信息在浅色/图片内容经过时缺少稳定的层级衬托。目标是在用户上滑接近首页大标题距离时，让顶部自然形成一层柔和遮罩：既能让状态栏信息更清楚，又能形成类似 iOS 26 的层级感。
+
+## 范围
+
+本次只改首页：
+
+- `/Users/broccoli/Project/wechat_wc/src/pages/index/index.tsx`
+- `/Users/broccoli/Project/wechat_wc/src/pages/index/index.scss`
+
+商城、订单、我的等其他 Tab 页暂不处理。
+
+## 选定方案
+
+使用页面级滚动监听 + 固定渐变层：
+
+1. 首页加载后通过 `Taro.createSelectorQuery()` 测量首页大标题节点位置，得到标题底部相对视口的距离。
+2. 用 Taro 页面滚动能力监听当前页面的滚动距离。
+3. 顶部放置一个 `position: fixed` 的渐变遮罩层，覆盖状态栏与胶囊按钮附近区域，并向下渐隐。
+4. 根据滚动距离和测量结果计算 `0~1` 的遮罩透明度进度，设置到遮罩层上。
+5. 遮罩层设置 `pointer-events: none`，不影响页面点击。
+
+不采用毛玻璃和标题吸顶/缩放，以保证真机兼容性，并保持首页大标题自然滚走。
+
+## 交互细节
+
+- 页面初始位置：遮罩完全透明。
+- 开始上滑到大标题接近状态栏区域时：遮罩逐渐显现。
+- 继续滚动约一个标题高度的过渡距离后：遮罩达到完整强度。
+- 下拉回顶部：遮罩按相同进度淡出。
+- `智绘微刻` 大标题继续随页面自然滚动，不吸顶、不缩小、不变色。
+
+## 视觉细节
+
+- 遮罩使用柔和线性渐变，不使用 `blur`。
+- 浅色模式顶部使用页面背景色 `#faf7f2`，向下过渡到透明。
+- 深色模式顶部使用页面背景色 `#191919`，向下过渡到透明。
+- 渐变层高度覆盖安全区顶部和自定义导航区域，并额外向下延伸一段距离，使边缘柔和。
+- 初始通过样式保持透明，避免首屏闪烁。
+
+## 适配与约束
+
+- 复用现有 `useSafeArea()` 获取 `statusBarHeight`、`headerPaddingTop` 等信息。
+- 继续使用现有 `useStatusBar(resolvedTheme)` 控制状态栏文字颜色。
+- 阈值通过节点测量计算，不写死具体机型像素。
+- 若节点测量失败，使用保守回退：从约一个首页标题高度附近开始过渡。
+
+## 测试要点
+
+- 首页从顶部上滑时，遮罩在接近标题位置自然出现。
+- 下拉回顶部时，遮罩自然消失。
+- 搜索框、轮播卡片和分类卡片点击不受遮罩影响。
+- 浅色/深色主题下状态栏信息都清晰可见。
+- 不同刘海屏/胶囊按钮位置下遮罩覆盖范围正常。
+
+## 非目标
+
+- 不抽公共顶部遮罩组件。
+- 不修改其他页面。
+- 不做毛玻璃效果。
+- 不改变首页大标题本身的布局和滚动行为。