diff --git a/docs/miniprogram-ui-spec-sanqiang.md b/docs/miniprogram-ui-spec-sanqiang.md
index 9c5812ac6..c67cf91b2 100644
--- a/docs/miniprogram-ui-spec-sanqiang.md
+++ b/docs/miniprogram-ui-spec-sanqiang.md
@@ -98,6 +98,14 @@ $success: #189b65;
 - 标题左对齐，退出/操作按钮右对齐
 - 下缘采用较大圆角（20~24px）形成模块感
 
+#### 自定义导航与微信胶囊（SHALL）
+
+- 使用 `navigationStyle: custom` 的页面，业务顶栏 SHALL 避开状态栏与右上角胶囊。
+- 量纲 SHALL 来自 `statusBarHeight` 与 `getMenuButtonBoundingClientRect`（见 `utils/safeArea.js`）。
+- CSS 变量：`--sq-safe-top`、`--sq-nav-height`、`--sq-header-height`、`--sq-capsule-right-safe`；微信端 SHALL 通过顶栏根节点内联 style 注入，不得仅依赖 H5 `document`。
+- 白底顶栏：总高 `--sq-header-height`，内容行高 `--sq-nav-height`，右侧列预留 `--sq-capsule-right-safe`，该列 SHALL NOT 放置可点击业务按钮。
+- 渐变大头：`padding-top` 含 `--sq-safe-top`，`padding-right` 含 `--sq-capsule-right-safe`。
+
 ### 3.3 卡片与容器
 
 - 默认白底 + 浅边框（`$border`）