hermes-ui/docs/ui-baseline.md

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. 字体栈

$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，不承载信息与交互。