# Alune 月光主题与动效设计规范 · Issue #86

版本：v2 · 仅视觉皮肤与状态动效。依据 [Issue #86](https://github.com/ShaoClean/Alune/issues/86)、当前 Alune 页面源码与既有工作区截图。随附画板是基于现有结构的主题对照稿；画板交互是演示，不执行 Git / SSH。

## 0. 变更边界（开发优先阅读）

**本 Issue 不重设计布局。** 保留现有组件树、文案、字体和字号、间距、圆角、面板宽度、导航顺序、操作位置、已保存布局及快捷键。不要根据上一版画板新增左侧文件栏、仓库大标题、连接表单侧栏、设置页卡片总览，或把仓库视图移到右侧。此版 UI 稿已移除这些偏差。

| 既有区域 | 必须保持 | 本次允许改变 |
| --- | --- | --- |
| 工作区外壳 | 左侧约 236px 可调仓库导航；顶部 48px 仓库标签，下方保留仓库工具栏及分支上下文原有层次；底部 32px 状态栏 | 背景、文本、选中、边线、焦点的色值 |
| 工作区主体 | 中间 Diff / 历史主内容 + 4px 拖拽缝 + 右侧约 320px 可调改动栏；**没有额外文件栏** | Diff 行底色、状态标签、选中反馈 |
| 仓库工具栏 | “改动 / 提交历史 / 分支 / 更多”保持左侧；原位置保留分支、Worktrees、刷新、拉取和推送；获取属于推送下拉选项 | 不移动、不增加独立获取按钮；仅改颜色/等待态 |
| 右侧改动栏 | 顶部“改动”、筛选框；**未暂存位于已暂存之前**；提交摘要、描述、AI 操作、提交按钮固定在底部 | 背景、状态色、短动效；保留操作与禁用逻辑 |
| 连接页 | 原有页标题、刷新/添加连接、三项状态卡、连接卡片；添加连接使用弹窗 | 不常驻新建表单，不更换入口；仅换色与状态动效 |
| 设置 | 既有独立设置窗口：左 236px 分类导航 + 顶部品牌条 + 主内容区 + 底部说明 | 如落地主题选择，在现有设置分类内增加“外观”一项和同结构表单；不改变原有分类、返回入口和布局设置 |

工作区默认宽度、断点及键盘行为以现有 `workspace-layout.css`、`Layout.tsx`、`RepositoryDetailPage.tsx`、`ChangesView.tsx`、`RepositoryToolbar.tsx` 为准。画板 1440×900 是对照视口，不是调整应用窗口或响应式断点的要求。提交摘要草稿、面板显隐、拖拽宽度、窄屏检查器与返回列表均保留现有行为。**图标与品牌资产仍使用现有 Alune 肖像图标**；图标重新设计由独立 Issue 负责。

## 1. 色彩设计

方向：低饱和月光蓝 + 带蓝相的中性色。月相可以用于启动/连接等待提示，不能替代 Git 状态文案。浅色是现有主题的换肤；深色复用同一 DOM 结构和布局。状态色独立于品牌色，不能把蓝色解释为“成功”。下表为建议 token，开发按实际 CSS 变量接入；十六进制是 sRGB。

| 新语义 | 浅色 | 深色 | 用途 |
| --- | --- | --- | --- |
| `surface` | `#F5F7FB` | `#151E30` | 主区域底色 |
| `surface-raised` | `#FFFFFF` | `#202C43` | 原有面板 / 工具栏 / 弹层 |
| `sidebar` | `#E9EFF9` | `#101A2D` | 原左侧仓库导航 |
| `code` | `#FBFCFE` | `#192438` | 原 Diff 背景 |
| `text` | `#1B2943` | `#E8EFFC` | 主体文本 |
| `text-muted` | `#526076` | `#B7C8EC` | 次要文本 |
| `line` | `#D8E0EE` | `#3B4A65` | 原分隔与可拖拽缝 |
| `primary` | `#415AB0` | `#AFC6FF` | 选中、链接、主按钮、焦点 |
| `primary-on` | `#FFFFFF` | `#151E30` | 主按钮文字 |
| `success` | `#0F6D56` | `#B0E5CC` | 连接/提交成功 |
| `warning` | `#995413` | `#FFD096` | 未提交、需注意 |
| `danger` | `#AD3B49` | `#FFB7C0` | 删除、失败 |
| `diff-add` | `#E9F7EF` | `#153328` | 新增行 |
| `diff-remove` | `#FCECEF` | `#431D27` | 删除行 |
| `diff-meta` | `#EAF0FC` | `#253654` | hunk 行 |

建议映射：旧 `--content` → `surface`，`--surface` → `surface-raised`，`--text` → `text`，`--text-muted` → `text-muted`，`--line` → `line`，`--blue` → `primary`，`--green/--orange/--red` → 独立语义色，`--diff-add/--diff-remove` → 对应 Diff token；`--sidebar-*` 与 `--nav-*` 要逐项映射，不能只改一个根变量。`settings.css` 和 `workspace-layout.css` 中局部硬编码色也需清查。迁移可先给旧变量绑定新值，再逐组件消除硬编码；**不改布局规则（display/grid/flex/width/height/padding/margin）**。

计算的文字对比度：浅色正文/底色 13.55:1、次级文字/底色 5.94:1、主按钮文字/底色 6.34:1；深色正文/底色 14.43:1、次级文字/底色 9.91:1、主按钮文字/底色 9.80:1。状态色和配套浅色底组合约 5.2:1 以上。实际界面还需测半透明叠层、禁用态、焦点和图标：正文目标 ≥4.5:1，控件边界与焦点 ≥3:1。Diff 保留 `+/-`、A/M/D/R、行号和“已暂存/未暂存”文字，不能只凭红绿辨识。

## 2. 动效设计

色彩替换不能引发布局重排；状态动画发生在**现有控件与已有通知区域**，不插入改变工作区尺寸的 banner。用已有等待图标、状态文字、通知和工具栏反馈；月相仅作为可选的启动/空状态装饰，不为其新建页面或改变品牌图标。

| 场景 | 参数与反馈 | 减少动态效果 |
| --- | --- | --- |
| Hover / pressed | 100ms，仅颜色/背景/边线；焦点环立即出现，不淡入 | 即时 |
| 标签/文件选中 | 160ms，仅背景与文字色；不移动标签或文件行 | 即时 |
| 左右面板开合 | 现有几何关系不变，显隐最多 220ms；拖拽过程中禁止缓动 | 即时 |
| 连接测试 | 复用原“测试连接”按钮 loading 与结果消息；待处理可用 1600ms 细轨道循环，结果返回立即停 | 静态符号 + “连接中” |
| 切仓/切分支/Diff 加载 | 原内容或既有占位保持尺寸；数据就绪时最多 160ms 淡入 | 即时 |
| 提交完成 | 原位置/原通知机制显示成功，120ms 淡入；绝不在请求成功前播放 | 静态结果 |
| 获取/拉取/推送 | 原按钮内 `获取中/拉取中/推送中` 和底部状态栏指示；超过 400ms 显示实际阶段，无进度百分比时不伪造 | 文本与真实状态保留 |
| 启动月相 | 仅首次启动的现有启动/空状态：280ms，-22° → 0°，播放一次 | 静态月牙 |

缓动：进入 `cubic-bezier(.2,0,0,1)`，退出 `cubic-bezier(.4,0,1,1)`；禁止动画化 Diff 行高、面板宽度拖拽值、整页模糊和大范围阴影。操作超过 10s 显示所处阶段；超过 30s 提供“仍在运行”和可用日志/取消入口（仅当实际能力存在）。系统 `prefers-reduced-motion` 优先；若应用内增加开关，与系统值取逻辑或，不能覆盖系统减弱设置。

## 3. 偏好、状态与开发落地

- 新装跟随系统；显式 `light/dark` 覆盖系统，启动前读取偏好以免闪屏。新增主题/动效偏好不清除既有布局、工作区排序、仓库、AI 配置和提交草稿。首版可仅跟随系统并延后应用内开关；不要为了设置入口修改工作区布局。
- 连接/同步/提交成功必须来自真实后端结果；动画不代表操作成功。失败保留原错误和重试/详情能力。读屏提示使用当前通知通道，不重复播报。
- 图标保留现有应用肖像与操作图标。品牌图标改造及启动页画面若牵涉独立图标 Issue，须另行审批，不作为本 Issue 验收前置。
- Phase A：颜色 token 和 light/dark 基础设施；Phase B：连接、仓库工具栏、Diff、改动/提交、同步的现有组件换肤；Phase C：现有设置、通知与文档截图。每一阶段做同尺寸截图对照：区域边界、控件坐标与操作顺序不变，只允许色值、状态动画和必要的主题选项变化。
- 验收矩阵：macOS/Windows/Linux × light/dark/system × OS 减少动态效果；窗口窄/宽、200% 缩放、键盘焦点、色盲、同步错误、长耗时 Git；大 Diff 滚动性能。性能与跨平台结果须实现后实测，设计稿不宣称已通过。

## 4. 画板索引与阅读方式

工作区浅色/深色使用**同一组件结构**，展示右侧改动栏与中间 Diff 对照；连接画板展示原页面加弹窗状态；设置画板展示原独立设置壳及在既有分类中添加外观偏好的方案。画板用演示内容表达主题色，不作为新增控件、尺寸或新交互流程的实现依据。若画板与产品源码有差异，以**现有产品组件结构 + 本文“变更边界”**为准。