# OrcaSVN 视觉规范

维护日期：2026-10-02。适用于所有页面、对话框、空状态和设置页。

## 使用方式与维护边界

本规范定义设计要求；[审校记录](visual-audit-2026-10-01.md)记录当时的实现与验证结果。历史样式仍有固定值和重复声明，规范不能作为全部实现已经合规的证明。

| 修改类型 | 维护位置 | 约束 |
| --- | --- | --- |
| 共享颜色、字体、间距、尺寸、动效 | [设计变量](../src/design-tokens.css) | 先定义语义变量；颜色提供深浅主题取值 |
| 通用控件、Element Plus 映射 | [全局样式](../src/style.css) | 核对组件默认样式，避免叠加 padding 或重复覆盖 |
| 页面布局、组件局部状态 | `src/views/`、`src/components/`、`src/layouts/` | 复用共享变量，局部覆盖限定作用范围 |
| 主题切换 | [主题逻辑](../src/composables/useTheme.ts) | 统一切换，页面不自行判断系统主题 |

修改顺序：确认语义和状态 → 选用已有变量 → 实现布局 → 检查主题、焦点和窄窗口 → 记录验证范围。新增变量时同步更新本规范；固定品牌图形及特殊业务布局尺寸可以例外，但应说明用途。

快速索引：[颜色](#颜色) · [文字与图标](#文字与图标) · [间距、形状与尺寸](#间距形状与尺寸) · [交互状态](#交互状态) · [布局与响应式](#布局与响应式) · [对话框](#对话框) · [动效](#动效) · [验收标准](#验收标准)

## 颜色

颜色按用途命名。浅色和深色使用同一个变量名，由 `html.theme-dark` 切换取值；页面不按主题分别写固定颜色。

| 用途 | 变量 | 浅色 | 深色 |
| --- | --- | --- | --- |
| 主操作 | `--md-sys-color-primary` | `#1261a0` | `#8bc7fa` |
| 主操作上的文字 | `--md-sys-color-on-primary` | `#ffffff` | `#082840` |
| 选中背景 | `--md-sys-color-primary-container` | `#e4f0ff` | `#163c61` |
| 选中背景上的文字 | `--md-sys-color-on-primary-container` | `#17486f` | `#d9edff` |
| 应用画布 | `--md-sys-color-surface` | `#f5f7fb` | `#101820` |
| 内容表面 | `--md-sys-color-surface-container-lowest` | `#ffffff` | `#16212b` |
| 次级表面 | `--md-sys-color-surface-container-low` | `#f8fafc` | `#131d26` |
| 主要文字 | `--md-sys-color-on-surface` | `#1c2938` | `#e7eef6` |
| 次要文字 | `--md-sys-color-on-surface-variant` | `#536274` | `#aab9c8` |
| 分隔线 | `--md-sys-color-outline-variant` | `#dbe3ea` | `#344454` |

文件状态使用成对的背景和文字变量，不依赖透明度区分状态。

| 状态 | 变量前缀（分别追加 `-bg`、`-text`） | 浅色背景 / 文字 | 深色背景 / 文字 |
| --- | --- | --- | --- |
| 修改、替换 | `--app-color-status-modified` | `#fff3c4` / `#805000` | `#4a330a` / `#ffd278` |
| 新增 | `--app-color-status-added` | `#dcfce7` / `#166534` | `#123d2a` / `#7fe3a2` |
| 冲突、缺失、删除 | `--app-color-status-error` | `#ffe4e6` / `#ad1f32` | `#4d2028` / `#ff9da7` |
| 未版本文件 | `--app-color-status-unversioned` | `#e8ebff` / `#414aa4` | `#2b2e59` / `#b7bcff` |

主要文字、次要文字、主按钮以及上述状态文字与各自背景的对比度应至少为 4.5:1。危险实心按钮使用 `--md-sys-color-error` / `--md-sys-color-on-error`：浅色为 `#ba1a1a` / `#ffffff`，深色为 `#ffb4ab` / `#690005`。不要仅靠颜色表达状态：徽标同时保留文字。差异行仍保留 `+`、`-` 和行号。

## 文字与图标

正文字体为 `Inter`、系统 UI 字体和中文系统字体；文件路径使用 `--app-font-family-mono`。默认字号为 14px，窄窗口保持相同字号。

| 层级 | 变量 | 大小 | 常见用途 |
| --- | --- | --- | --- |
| 微型标注 | `--app-font-size-2xs` | 10px | 状态徽标、分组标题 |
| 辅助信息 | `--app-font-size-xs` | 11px | 版本号、路径摘要 |
| 说明 | `--app-font-size-sm` | 12px | 辅助文案、筛选项 |
| 控件标签 | `--app-font-size-label` | 13px | 导航、按钮、文件路径 |
| 正文 | `--app-font-size-body` | 14px | 表单和内容 |
| 小标题 | `--app-font-size-subtitle` | 16px | 设置分区 |
| 页面标题 | `--app-font-size-title` | 18px | 工作区和页面标题 |
| 欢迎标题 | `--app-font-size-display` | 30px | 仅用于空状态主标题 |

常规、强调和标题分别使用 400、600、700 字重，次级强调可用 500；正文行高 1.5，长说明行高 1.6。图标采用同一套 Material Symbols：常用尺寸 16、20、24px，常态轮廓、选中态填充。图标按钮必须有可访问名称。

## 间距、形状与尺寸

通用间距遵循 4px 网格：`--app-spacing-xs`、`--app-spacing-sm`、`--app-spacing`、`--app-spacing-md`、`--app-spacing-lg`、`--app-spacing-xl`、`--app-spacing-2xl` 分别为 4、8、12、16、24、32、48px。窄窗口不缩小文字，仅把 `lg`、`xl` 收紧到 16、24px。工作台外边距等紧凑布局可以使用文档明确列出的例外尺寸。

| 用途 | 变量 | 尺寸 |
| --- | --- | --- |
| 状态徽标 | `--app-radius-xs` | 4px |
| 按钮、输入框、导航项 | `--app-radius-sm` | 8px |
| 普通容器 | `--app-radius-md` | 12px |
| 工作台 | `--app-radius-sm` | 8px |
| 欢迎卡片、对话框 | `--app-radius-xl` | 24px |
| 控件 / 输入框 | `--app-size-control` / `--app-size-field` | 38 / 40px |
| 表格行 / 文件行 | `--app-size-table-row` / `--app-size-list-row` | 44 / 48px |
| 面板 / 页面标题栏 | `--app-size-panel-header` / `--app-size-page-header` | 52 / 62px |
| 工具栏 / 状态栏 / 侧边栏 | `--app-size-toolbar` / `--app-size-statusbar` / `--app-size-sidebar` | 64 / 28 / 224px |

交互控件的默认圆角为 8px；仅计数徽标等胶囊元素使用 `--app-radius-full`。工作台使用 6px 紧凑外边距，只保留一层外边框，内部面板以细分隔线区分，避免重复套卡片。

## 交互状态

| 状态 | 视觉与行为要求 |
| --- | --- |
| 默认 | 主要操作用主色填充，次要操作用内容表面和细边框 |
| 悬停 | 通过颜色、表面或边框变化反馈；不改变行高和控件尺寸 |
| 选中 | 使用主色容器及配对文字；工作区文件行只以背景表达选中，不增加整行蓝色边框 |
| 键盘焦点 | 用 `:focus-visible` 显示 2px 主色轮廓；输入框可用 2px 内嵌描边。文件行内的实际按钮保留焦点提示 |
| 禁用 | 保留可读标签，同时禁止触发；不能仅用颜色表达禁用 |
| 加载 | 显示状态文案；重复操作是否禁用由业务状态决定，动画不代表精确进度 |
| 空状态与错误 | 空状态解释当前情况并提供适用入口；错误保留可理解的文案及可用的恢复操作 |

鼠标点击会使按钮获得焦点，但不能因此给整行套上焦点边框。不要用容器 `:focus-within` 绘制选中边框；它可用于保持行内操作按钮可见。键盘导航使用 Tab、Enter，以及文件列表支持的方向键、Home、End。

长作者名和提交信息在列表中单行省略，并提供完整悬浮文本；详情中允许换行。文件路径须保留可辨识内容，确认框显示完整可选择路径。不要让悬浮提示成为唯一的操作名称。

## 布局与响应式

| 视口宽度 | 布局调整 |
| --- | --- |
| ≤ 900px | 侧边导航改为横向滚动 |
| ≤ 860px | 工作区文件列表与差异面板上下排列；其他多栏页面按各自媒体规则收紧，确保内容可达 |
| ≤ 650px | 工具栏与工作区切换器分两行 |
| ≤ 640px | 收紧较大间距，表单和筛选项按页面规则改为纵向排列 |

业务内容允许纵向滚动，导航和状态栏保持可见。表格与代码允许在所属区域内横向滚动，应用外壳不得被长路径或表单撑宽。390px 用于窄窗口验收，不代表新增移动端产品范围。

## 对话框

普通对话框使用 24px 圆角，外壳不再叠加 Element Plus 默认内边距；标题、内容和按钮区分别管理间距。带关闭按钮的标题必须预留按钮位置，长标题不能与关闭图标重叠。

确认框使用同样的圆角，内边距使用 `--app-spacing-lg`（桌面 24px，窄窗口 16px）。非全屏对话框和确认框宽度不超过视口减去 32px；全屏对话框是例外。文件还原、删除确认框桌面最大宽度为 480px，警告图标与正文顶部对齐，路径单独使用等宽字体和次级表面；长路径任意位置换行，路径区超过 160px 时滚动。

还原、删除均使用明确的危险操作按钮及取消按钮。点击遮罩不关闭此确认框；取消和关闭按钮退出且不执行操作。警告需说明操作后果，未版本文件删除明确提示永久删除及无法撤销。路径以文本节点呈现，不能作为 HTML 插入。日志详情桌面最大宽度 960px，窄窗口保持左右留白。

## 动效

| 用途 | 时长 | 规则 |
| --- | --- | --- |
| 悬停、颜色、边框、焦点 | 150ms | `--app-transition-fast` 已包含缓动，不能再追加 `ease-out` |
| 内容进入、加载遮罩退出 | 250ms | 使用 `--app-transition-normal` 或纯时长 `--app-duration-normal` |
| 较慢的局部过渡 | 350ms | 仅在必要时使用 |
| 加载循环 | 独立周期 | 仅在请求仍进行时播放，不用来表示精确进度 |

加载遮罩进入使用 150ms 淡入，退出使用 250ms 淡出；指示器最多放大到 1.05 倍，不逐帧动画化模糊滤镜。遮罩不阻塞指针操作，业务禁用状态由控件管理。

避免 `transition: all`，列出实际变化的属性。按钮按下可缩放到 0.98。系统开启 `prefers-reduced-motion: reduce` 时，全局动画只运行一次且时长压缩为 0.01ms，过渡延迟清零，取消平滑滚动和按钮按下缩放；加载状态文字仍然显示。

## 验收标准

每次变更按影响范围验收。纯文档修改核对链接、变量和实现描述；样式或组件行为修改运行 `npm run build`、`npm run test:unit`，并完成相关视觉检查。

| 检查维度 | 最低覆盖 | 通过标准 |
| --- | --- | --- |
| 主题与窗口 | 浅色、深色 × 1280px、390px | 文字可读，操作可达，外壳无横向溢出 |
| 交互 | 鼠标选中、悬停、键盘焦点、禁用 | 选中与焦点独立；工作区点击不产生整行蓝框 |
| 内容边界 | 长路径、长作者、长提交信息、空数据、错误 | 不撑破布局，完整内容可查看 |
| 对话框 | 长标题、长路径、取消、关闭、遮罩 | 标题与关闭按钮不重叠，取消不执行操作 |
| 动效 | 正常偏好、减少动态效果 | 正常状态无布局跳动；减少动态效果仍有状态反馈 |
| 桌面集成 | 真实工作副本的受影响流程 | 界面与 SVN 结果一致，不使用浏览器预览代替集成验收 |

审校记录应写明日期、变更、验证方式、实际覆盖及未验证项，保留历史结果，不把后续修复写成历史上已通过的检查。最近一次综合审校见 [2026-10-01 样式与动效审校](visual-audit-2026-10-01.md)；此后已移除工作区文件行 `:focus-within` 整行边框，本规范同步明确了选中与键盘焦点的区别。

后续实现及浏览器验证见 [2026-10-02 视觉规范落实记录](visual-implementation-2026-10-02.md)。