DESIGN

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

版本：v2 · 仅视觉皮肤与状态动效。依据 Issue #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 对照；连接画板展示原页面加弹窗状态；设置画板展示原独立设置壳及在既有分类中添加外观偏好的方案。画板用演示内容表达主题色，不作为新增控件、尺寸或新交互流程的实现依据。若画板与产品源码有差异，以**现有产品组件结构 + 本文“变更边界”**为准。