# 视觉语言规格：墨与黄铜（Ink & Brass）

> 制定：2026-08-09 · 状态：**已实施（P7 视觉深化全系列竣工）** · 后续 UI 决策仍以本文气质词表为准 · 适用范围：src-ui 全表面
> 性质：设计宪法。本文档是视觉的唯一事实来源；任何 UI 决策回到本文档的「气质词表」打勾。
> 前置阅读：`src-ui/src/app/README.md`（当前前端约定）、根目录 `CONVENTIONS.md`；`docs/archive/visual-deepening-plan.md` 为旧视觉施工稿（已退役）

---

## 0. 定调声明

HoloGram 是 Agent 软件。它的主张是**确定性——事实，不是猜测**。旧视觉（深空 bloom 星图）表达的是"推测与观赏"，与主张相悖；3D 星图降级为可选仪器（见 §8）。

新视觉取材于**前数字时代的科研手作台**：严肃数学的线条秩序、羊皮纸与墨水、黄铜仪器、铅字排印。这不是复古戏服——**每一样材质都编码产品语义**：铅笔=未定稿，墨水=已定稿，烫金=关键仪式，朱砂=风险。材质即语义。

## 1. 气质词表（设计宪法）

所有设计决策必须通过以下五个词。任一决策无法同时满足五词，砍掉。

1. **精密** — 一切刻度、间距、对齐可数。拒绝"随手"。
2. **安静** — 无炫技、无弹性动效、无装饰性发光。声音先于画面。
3. **权威** — 材质有来历（铅字、黄铜、朱砂），不是贴图。权威来自"记录"。
4. **克制** — 强调元素（仪器）件数有限。颜色是语言，不是装饰。
5. **真实** — 每个纹理编码信息。不携带信息的"复古感"都是戏服。

**验收测试（logo 测试）**：遮住 logo，陌生人应能从视觉猜出这是"精密、权威的记录工具"。

## 2. 材质语义表（核心映射）

| 产品状态 | 材质表达 |
|:--|:--|
| Agent 思考 / 流式输出 | 铅笔在纸上走线（虚线、可擦除感） |
| 计划 / 待审批 | 铅笔稿卡片，烫金细框缓慢呼吸 |
| 执行中 | 墨水渗入纸纤维（进度填充） |
| 完成 / commit / 目标达成 | 烫金钢印落下 |
| 风险 / 错误 / 阻断 | 朱砂印（印章红，古代印泥色） |
| 对话转录 | 观测日志记录格式（铅字排印） |
| 工具调用 | 证据卡：仪器读数格式（日期·仪器·读数·可展开） |
| 代码图 | 制图版：墨水圆点 + 发丝制图线 + 极淡坐标格 |
| 新鲜 / 未读 / 批注 | 铅笔批注（手写体，见 §4 字体） |

## 3. 色板（tokens 基础）

| Token | 值 | 用途 |
|:--|:--|:--|
| `--ink-desk` | `#0A0D13` | 桌面底色（墨蓝近黑，真实深空摄影倾向） |
| `--ink-housing` | `#11151D` | 仪器外壳（侧栏/仪表条） |
| `--ink-paper` | `#1A1E26` | 烛光纸面（卡片/面板，暖倾向） |
| `--ink-paper-raised` | `#20252F` | 纸面凸起（悬浮层/浮层） |
| `--ink-primary` | `#E7E2D4` | 墨水主字（暖白） |
| `--ink-secondary` | `#A49E8F` | 墨水次字 |
| `--pencil` | `#7E7A70` | 铅笔灰（草稿/未定稿，配虚线） |
| `--brass` | `#C9A227` | 哑金黄铜（唯一强调色·状态动词） |
| `--brass-bright` | `#E5C55B` | 亮金（钢印落下的瞬间） |
| `--cinnabar` | `#B63A2A` | 朱砂（风险/错误/阻断） |
| `--ink-green` | `#4E6E5E` | 墨绿（信息/健康状态，第三色，慎用） |
| `--chart-line` | `#3A3F4A` | 制图线（图边，发丝 1px） |
| `--graticule` | `#262B35` | 坐标格（极淡，1px） |

**纪律**：全 UI 只允许 金/朱砂/墨绿 三种有彩色。其余全部来自墨蓝黑-暖白-铅笔灰的中性轴。禁止渐变（唯一例外：桌面到纸面的烛光过渡，≤2 层）、禁止辉光、禁止玻璃拟态。

## 4. 字体（复用现有资产，零新引入）

| 角色 | 字体 | 已装 |
|:--|:--|:--|
| 叙述 / 标题 | Noto Serif SC + Fraunces（数字/西文展示） | ✅ `fonts.ts` 已引入 |
| 数据 / 事实 | JetBrains Mono | ✅ |
| 铅笔批注（未读/草稿/旁注） | LXGW WenKai | ✅ |

字阶（唯一合法字阶）：
`12`（仪器标签·mono）· `13`（数据·mono）· `14`（正文·serif）· `16`（记录标题·serif）· `20`（页标题·Fraunces）· `28`（桌面首屏·Fraunces）

## 5. 纹理与形态

- **纸纹**：纸面上叠加极淡噪点（SVG feTurbulence data-URI，一次性成本，禁止大图）
- **分隔线**：发丝线（1px `--chart-line`），拒绝阴影。边框用**铅字双线框**（双 hairline = 印刷规则线）
- **圆角**：4-6px 小圆角，仪器件（按钮/刻度）用 2px——纸张方、仪器方
- **刻度语言**：状态/进度一律画成黄铜刻度尺（tick marks），不是进度条

## 6. 动效（材料行为学）

每一条动效必须是"桌上发生的事"，且全部为线性/缓出，**禁止弹性、禁止缓入表演**：

| 场景 | 行为 | 规格 |
|:--|:--|:--|
| 流式输出 | 铅笔走线 | 线性连续，无闪烁 |
| 加载 | 圆规画弧 | 1200ms 弧线循环，线性 |
| 进度 | 墨水渗入 | 由左至右填充，200ms 内均匀 |
| 审批 / commit | 烫金钢印 | 180ms scale 0.92→1.0 + 60ms 亮金闪现 |
| 错误 | 朱砂印 | 200ms 落下，无抖动 |
| 视图切换 | 纸页翻过 | 220ms 交叉淡入 + 4px 垂直位移 |
| 状态变化 | 指针移动 | 200ms 淡变，一次到位 |

`prefers-reduced-motion`：全部材料动效关闭，仅保留 100ms 内必要反馈。

## 7. 布局：Agent 工作台（主屏倒置）

```
┌────────────┬───────────────────────────────┬──────────────┐
│ 仪器轨      │  日志本（对话转录，主舞台）      │  事实面板      │
│ (左侧dock)  │  编辑面（点证据卡/节点浮入）     │  证据卡·仪表条  │
│ 制图版      │                               │  Agent 状态    │
│ 数据流      │                               │  上下文预算     │
│ 时间轴      │                               │  TaskBoard     │
├────────────┴───────────────────────────────┴──────────────┤
│ 仪表条（status bar：黄铜刻度 · 引擎状态 · 路径 · 时间）       │
└────────────────────────────────────────────────────────────┘
```

- **主舞台 = 日志本**：转录即记录。聊天不再是"侧边配件"，是全桌面的中心
- **事实面板**：工具调用证据卡、影响面内联小图（主张即数据）
- **制图版 = 2D 图**：降级后的代码图，制图线 + 坐标格，读图如读工程图纸

## 8. 3D 星图处置

- 主舞台退役，改为命令面板可唤起的**遗留仪器**（`view: 'legacy-map'`），默认隐藏
- 不再为星图做任何新开发；保留其运行所需的最小 CSS
- 3D 美学（bloom/辉光/星空氛围）全部不迁移到新视觉

## 9. 禁区（违反即打回）

1. 无神秘学符号（六芒星/炼金阵/魔法元素）——只许"数学线条的秩序感"
2. 无做旧/磨损/蜡烛特效——材料在场，不做旧
3. 无任何不编码信息的装饰纹理
4. 无苹果式极简（删除式克制）——我们是用"选材"表达克制，不是用"留白"
5. 仪器件数限制：任何一屏的强调元素（金/朱砂）不超过 3 件

## 10. 落地清单（对应代码）

| 步骤 | 位置 | 说明 |
|:--|:--|:--|
| 1 | `src-ui/src/app/tokens.css` | `--obs-*` 全部替换为 §3 色板 + §4 字阶 + 间距/圆角 token |
| 2 | `src-ui/src/main.ts` | CSS 入口保持单一；新增纸纹 data-URI 文件 |
| 3 | `src-ui/src/app/App.tsx` | 布局倒置：日志本居中、事实面板右侧、仪器轨左侧 |
| 4 | `src-ui/src/app/chat/chat.css` | 转录→日志记录格式；证据卡；铅笔流式 |
| 5 | `src-ui/src/app/shell.css` | 桌面底色、仪表条黄铜刻度 |
| 6 | `src-ui/src/app/graph-chrome.css` | 制图版化（2D 重着墨，3D chrome 退役） |
| 7 | `src-ui/src/ui/dock-*` | 仪器轨面板配置化 |
| 8 | `src-ui/src/app/fonts.ts` | 已齐备，零改动 |

**门禁**：`npm run build` + `npx vitest run` + `npx biome ci src/app` 全绿。测试即回归网——换皮不改逻辑，逻辑层测试全绿是硬要求。

## 11. 验收

- [ ] 气质词表五词全部通过（逐屏走查）
- [ ] logo 测试通过：遮住 logo 可猜出"精密权威的记录工具"
- [ ] 全 UI 有彩色 ≤3（金/朱砂/墨绿）
- [ ] 单屏强调元素 ≤3 件
- [ ] 3D 星图默认不出现
- [ ] 三端测试全绿