# UI 基线（Phase 005 定稿）

本文件是 hermes-ui 的**视觉语言唯一依据**。Phase 006/007 的批量迁移照此执行，
页面样式与本文冲突时，以本文为准；本文没覆盖的场景，先在 `docs/arco-mapping.md`
补映射、再回本文补约定，然后才动代码。

- 样板页：`views/LoginView.vue`（装饰位面 + 表单）、`components/layout/AppSidebar.vue`（导航 + 弹窗 + tag）
- 令牌源：`packages/client/src/styles/variables.scss`（CSS 变量）+ `styles/arco-theme.ts`（Arco 组件主题）
- 组件映射：`docs/arco-mapping.md`

---

## 1. 色板

黑白水墨（Pure Ink）——**纯黑白灰，无彩色**（status/info 色除外）。三主题：ink light / ink dark / comic。

### 浅色（`html:not(.dark)`）

| 角色 | 变量 | 值 |
|---|---|---|
| 页面底 | `--bg-primary` | `#fafafa` |
| 次级底 / 侧栏 | `--bg-secondary` / `--bg-sidebar` | `#f0f0f0` / `#f5f5f5` |
| 卡片 / 输入底 | `--bg-card` / `--bg-input` | `#ffffff` |
| 分割线 | `--border-color` / `--border-light` | `#e0e0e0` / `#ebebeb` |
| 强调色 | `--accent-primary` / `--accent-hover` | `#333333` / `#1a1a1a` |
| 正文 | `--text-primary` / `--text-secondary` / `--text-muted` | `#1a1a1a` / `#666666` / `#999999` |
| 状态 | `--success` / `--error` / `--warning` / `--accent-info` | `#2e7d32` / `#c62828` / `#f57f17` / `#4a90d9` |

### 深色（`.dark`）

| 角色 | 变量 | 值 |
|---|---|---|
| 页面底 | `--bg-primary` | `#1a1a1a` |
| 次级底 / 侧栏 | `--bg-secondary` / `--bg-sidebar` | `#252525` / `#202020` |
| 卡片 / 输入底 | `--bg-card` / `--bg-input` | `#2a2a2a` |
| 分割线 | `--border-color` / `--border-light` | `#3a3a3a` / `#333333` |
| 强调色 | `--accent-primary` / `--accent-hover` | `#e0e0e0` / `#f5f5f5`（反相） |
| 正文 | `--text-primary` / `--text-secondary` / `--text-muted` | `#e0e0e0` / `#a0a0a0` / `#888888` |
| 状态 | `--success` / `--error` / `--warning` / `--accent-info` | `#66bb6a` / `#ef5350` / `#ffb74d` / `#6ba3d6` |

- 需要 `rgba()` 透明度时用配套 `--*-rgb` 变量（如 `rgba(var(--accent-primary-rgb), 0.12)`）。
- 反色场景（强调底上的字）一律用 `--text-on-accent`，不要硬编码白/黑。
- **Arco 组件配色**：`arco-theme.ts` 冻结 `colorPrimary: #2f2f2f`、`borderRadius: 6`，
  延续克制灰阶；暗色由 `body[arco-theme='dark']` CSS 变量覆盖承载，
  **不用** Arco 的 dark theme + overrides 双轨。
- 主题切换机制：`useTheme.ts` 同时切 `<html>` 的 `dark`/`comic` class（项目令牌）
  和 `arco-theme` 属性（Arco 组件）；FOUC 脚本内联在 `index.html`，两边同步改。

## 2. 圆角 / 间距 / 字号阶梯

**圆角**（`$radius-*`）：

| token | 值 | 用途 |
|---|---|---|
| `$radius-sm` | 6px | 按钮、输入框、小卡片、tag（与 Arco `borderRadius: 6` 对齐） |
| `$radius-md` / `$radius-lg` | 8px | 面板、弹窗、大卡片 |

**间距**：4px 基数，常用档 `4 / 8 / 12 / 16 / 24 / 32`（组件内边距多用 12/16，区块间 24/32）。
布局尺寸：侧栏 240px（折叠 64px）、顶栏 60px、移动端断点 768px。

**字号阶梯**：

| px | 用途 |
|---|---|
| 10 | 分组标签（uppercase + letter-spacing） |
| 11–12 | 辅助信息、meta、tag |
| 13 | 次要正文、列表项、错误提示 |
| 14 | 正文默认（`body` 基准） |
| 15 | 输入框文字（`$font-code` 场景） |
| 16 | 小标题 |
| 26 | 登录页等展示型大标题 |

## 3. 字体栈

```scss
$font-ui:   Inter, system-ui, -apple-system, sans-serif;   // 中英混排 UI（fallback 系统字体）
$font-code: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;  // 代码、命令、版本号
```

- comic 主题下 `--font-ui` 被覆盖为 `'Comic Neue', 'ZCOOL KuaiLe', ...`，其余不变。
- 等宽字体只用于：代码块、命令、版本号、命令行提示（`$font-code`）。

## 4. 阴影 / 分割线

- **分割线**：`1px solid var(--border-color)`（面板/区块）或 `--border-light`（弱分隔）。
  水墨主题以线为主，不滥用阴影。
- **阴影**：常规浮层 `0 1px 4px rgba(0, 0, 0, 0.1)`；comic 主题用
  `3px 3px 0 rgba(0, 0, 0, 0.15)` 硬投影（`--comic-shadow`）。
- 弹窗/抽屉的遮罩、投影由 Arco 组件自带，页面不重复加。

## 5. 组件使用约定

- **消息 / 对话框 / 通知**：只准调 `composables/useMessage|useDialog|useNotification`
  适配层（签名冻结），**不得**在页面里直接 import Arco 的 `Message` / `Modal` / `Notification`。
- **Modal vs Drawer**：短内容确认、纯信息展示用 `a-modal`
  （信息型弹窗 `:footer="false"`，如样板页 changelog / docker 升级指引）；
  需要表单编辑、长内容滚动的场景用 `a-drawer`。naive `preset="dialog"` 无直接对应。
- **按钮**：语义 `type` + `status` 组合（warning 按钮 = `type="primary" status="warning"`）；
  占满宽用 `long`（naive `block`）；尺寸 `size="mini|small|medium|large"`
  （naive `tiny`→`mini`）；提交按钮 `html-type="submit"`，加载态用 `:loading`。
- **输入框**：`a-input` 关闭了 attrs 透传，`autofocus` 无效——需要自动聚焦时
  `ref` + `onMounted` 调 `focus()`；密码框 `type="password"`。
- **表格空态**：用 `a-empty`，不手写占位文案。
- **loading**：按钮级用 `a-button :loading`，区域级用 `a-spin :loading`，
  全局任务进度用 `useMessage().loading(...)`（用完 close/destroy）。
- **表单**：`a-form` + `a-form-item`，校验规则 API 与 naive 不同，逐例适配。
- **tag**：naive `type="info"` → `a-tag color="arcoblue"`（内建色），
  `:bordered="false"` 直接支持。

## 6. 装饰位面的边界

装饰位面（ArkScope vendor 组件等纯视觉层）的判定标准：

> **不得承载信息、不得承载交互、不得影响可读性。**

| 允许 | 禁止 |
|---|---|
| 登录页标题区装饰位面 | 聊天页（消息区 / 输入区 / 侧边栏） |
| Journey 图谱的背景层 | 任何表单页（Skills / Profiles / Settings / Models） |
| 首屏 loading / 空状态 | 任何表格页（Usage / Logs / Jobs / Kanban） |
| | 任何点击交互密集区域 |

**`pointer-events: none` 是硬要求**，装饰层绝不能吃掉点击
（样板：`LoginView.vue` 的 `.login-decor`，外加 `aria-hidden="true"`）。

vendor 素材边界：`vendor/arkscore/` 下**零图片/音视频素材**，
由 `tests/client/arkscope-vendor.test.ts` 机械化卡住；Provenance 见
`vendor/arkscore/PROVENANCE.md`。

## 7. 三条不可破的规则

1. **不引入第三个 UI 库**——只允许 Arco Design Vue（+ 现有图标/工具链）。
2. **消息气泡内部不用 Arco 组件**（性能红线，见 Phase 006）。
3. **装饰层一律 `pointer-events: none`**，不承载信息与交互。