toor
4baccd5d88
- Vendor ArkScope decorative layers (ScrambleTitle / IsometricWave) with provenance notes; decorative-only per AGENTS.md red lines - Migrate theme tokens to Arco, register the Arco theme, and add hook adapter composables (useMessage / useDialog / useNotification) with matching signatures - Sample pages: LoginView and AppSidebar on the new baseline; docs/arco-mapping.md and docs/ui-baseline.md land - agent-bridge: prefer the PM-selected venv from facts.json over legacy in-tree venvs (legacy lacks the mcp extra, so every MCP server showed 0 tools / not connected) - agent-bridge python (vendored, deliberate deviation): MCP discovery import fallback and pyyaml -> hermes_yaml so plugins and MCP work under the PM env; install the mcp extra via `hermes pm install --extra mcp` - Chat-chain fragment: docs/chat-chain-changes/2026-10-17-phase005-arkscope-baseline.md Verified: harness:check, test (2020 passed), test:e2e (30 passed), build all green; manual: plugins 100/0 warnings, MCP 6/6 servers connected with 104 tools.
135 lines
6.7 KiB
Markdown
135 lines
6.7 KiB
Markdown
# 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`**，不承载信息与交互。
|