diff --git a/AGENTS.md b/AGENTS.md
index 9d26d16..7889b18 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -73,6 +73,7 @@ harmony-client/
 | 测试 Testing | `docs/testing.md` |
 | 构建/签名/部署 Build & Deploy | `docs/build-deploy.md` |
 | 分支模型与 Git 规范 Git Workflow | `docs/git-workflow.md` |
+| UI 主题与图标 Theme & Icons | `docs/ui-theme.md` |
 
 ## Common Tasks
 
diff --git a/docs/ui-theme.md b/docs/ui-theme.md
new file mode 100644
index 0000000..04c3105
--- /dev/null
+++ b/docs/ui-theme.md
@@ -0,0 +1,34 @@
+# UI 主题与图标资源
+
+> 品牌视觉对齐「明缘云道场」微信小程序（`wechat-clock-mini`）。
+> 色值 token 定义在 `uikit/src/main/ets/theme/Theme.ets`（`AppColor`），组件内禁止散落魔法值。
+
+## 品牌色板
+
+| Token | 值 | 用途 |
+|---|---|---|
+| `primary` | `#C67B30` | 品牌主色（金） |
+| `textPrimary` | `#2C1810` | 主文本（深棕） |
+| `textSecondary` | `#5A4A3A` | 次文本（暖棕） |
+| `background` | `#FDFBF7` | 页面背景（米白） |
+| `tabBg` | `#FFFFFF` | 底部导航背景 |
+| `tabInactive` | `#5A4A3A` | 底部导航未选中 |
+| `tabActive` | `#C67B30` | 底部导航选中（金） |
+
+## 底部导航图标
+
+四 tab（首页 / 打卡 / 计划 / 我的）入口在 `entry/src/main/ets/pages/Index.ets`，图标来源是小程序 `wechat-clock-mini/assets/tabbar/` 的 8 张 PNG，已复制到 `entry/src/main/resources/base/media/`（`-active` 重命名为 `_active` 以符合资源名规范）：
+
+| tab | 普通 | 选中 |
+|---|---|---|
+| 首页 | `home.png` | `home_active.png` |
+| 打卡 | `checkin.png` | `checkin_active.png` |
+| 计划 | `plan.png` | `plan_active.png` |
+| 我的 | `profile.png` | `profile_active.png` |
+
+关键决策与实现约定：
+
+- **选中态 = 换文件，不用 `fillColor` 着色。** `-active` 与普通版是同一图形、仅填充色不同（`#5A4A3A` → `#C67B30`）；`Image.fillColor` 对 PNG 无效且会压平抗锯齿，故按选中态切换 `Image` 资源。
+- **复用小程序的真实 PNG，保证像素级一致**，而非像 `android-client`（另一小程序客户端）那样用 Material 图标近似。`android-client` 可作为结构参考，但非像素级对齐。
+- **尺寸**：24×24 vp，`objectFit(ImageFit.Contain)` 保留图标自带透明留白，缩放后与小程序观感一致。
+- **主题无需改动**：`tabInactive/tabActive/tabBg` 已与小程序 `app.json` 的 `tabBar.color/selectedColor/backgroundColor` 完全一致。