基线：v0.1.74，2026-10-03。本文记录已经确定的视觉方向、交互规则和实现入口，供后续界面迭代使用。具体数值以对应源码为准；调整设计时同步更新本文。
黑白石墨色、紧凑布局、轻量玻璃材质。参考 shadcn/ui 的简洁层级，以及 Apple Liquid Glass 的透明层次和边缘高光。重点是看清账号、额度与下一步操作，装饰保持克制。
- 白色承载内容，深灰渐变突出当前身份和主要操作。
- 用字号、间距、边框和明暗区分层级，避免大面积高饱和配色与厚重阴影。
- 主窗口、额度浮窗、自动切换倒计时共用视觉语言。
- 账号列表优先提高可见条数，避免无意义留白和操作按钮过早换行。
- 玻璃效果是 Electron 应用内的 CSS 材质模拟，不等同于系统原生 Liquid Glass，也不模糊桌面或其他应用。
共享变量位于 src/ui/theme.css。新增样式优先复用变量。
| 用途 | 变量 | 当前值 |
|---|---|---|
| 主要文字 | --ink |
#18181b |
| 辅助文字 | --muted |
#71717a |
| 窗口背景 | --paper |
#f5f5f5 |
| 内容表面 | --surface / --surface-strong |
#fff |
| 次级控件底色 | --soft |
#f4f4f5 |
| 普通 / 弱边框 | --line / --line-soft |
#dedee2 / #e8e8eb |
| 强调色 | --accent |
#27272a |
| 主操作渐变 | --accent-gradient |
160°，#454549 → #27272a → #18181b |
| 额度条 | --meter-gradient |
90°，#27272a → #71717a |
| 预估额度条 | --meter-estimated |
灰色斜纹，配合预估文字 |
| 危险操作 | --danger |
#b42318，配浅红背景 |
优先使用系统字体：macOS 的系统字体、Windows 的 Segoe UI，中文使用平台字体回退。普通内容不加载远程字体；额度、倒计时等数字使用等宽数字排布，减少跳动。
浮窗标题层级固定为 产品名 > 账号 > 版本号：当前分别为 15px/650、12px/500、10px/400。版本号弱化显示，但检查更新入口仍可点击并可用键盘聚焦。
浮窗“主窗口”和“重启 Codex”按钮最小高度为 36px，操作区不参与纵向压缩；账号列表按钮保持 32px，保留列表的紧凑密度。
浮窗额度卡片底部共用一条分隔线，更新状态与重置次数保持单行，使用 11px 字号、16px 行高和 6px 顶部内边距。例如“缓存 00:40”与“重置 1 次 · 缓存”；完整更新时间保留在悬停提示中。窄窗口中的长状态文字省略，不另起一行。
压缩浮窗顶部内容时，同步调整主进程的窗口高度预算，避免省下的高度变成账号列表底部空白。当前单行页脚对应 WIDGET_BASE_HEIGHT = 415，每增加一个账号保留 49px；最小高度容纳两行账号，已保存的窗口高度受账号数量及屏幕可用高度共同限制。
主窗口默认 1040 × 720，最小 860 × 620，单位为 Electron 逻辑像素。
| 组件 | 当前布局基准 |
|---|---|
| 账号列表 | 全宽展示，align-content: start，卡片间距 8px |
| 账号卡片 | 内边距 12px 14px，身份 / 两个额度摘要 / 操作三列 |
| 账号名称 | 15px/600，单行省略；悬停可查看完整名称 |
| 账号辅助信息 | 11px，行间距 2px，长邮箱省略并提供完整提示 |
| 当前账号标识 | 11px 小胶囊，保持可见，不随名称一起压缩 |
| 详情与操作按钮 | 最小高度 32px，文字 12px，圆角 8px |
| 操作区域 | 详情 / 切换 / 更多；需要重新登录时替换主操作，当前账号不重复显示已启用按钮 |
常态卡片高度约 85px，按内容自然排布，不固定死高度；展开详情时正常增高。860px、900px、1040px 宽度下账号信息、额度与操作保持同一行，640px 及以下额度换到第二行。
首页仅保留当前登录、自动切换状态、已保存账号与添加入口。备注和登录方式放入“添加账号”弹窗；导入、导出放入列表“更多”。路径、策略、数据说明、诊断、关于与唯一检查更新入口放入“设置”。普通登录成功或取消使用短提示，等待登录和异常状态在首页可见。
账号列表直接显示额度摘要与在线 / 缓存 / 暂无数据状态；详细时间、凭证续期信息和重置记录放入详情。重命名、正常账号的重新登录、删除放入账号“更多”。菜单支持键盘焦点、Esc 和外部点击关闭；删除当前账号的确认明确说明退出登录和重启，默认聚焦取消。
长文本用省略与提示解决，不挤掉操作按钮，也不让“重新登录”等短按钮文字换行。增加按钮时需重新验证最窄窗口，不能直接继续堆列。
Windows 使用 32px 自定义标题区域和原生窗口控制按钮，标题栏与页面背景均为 #f5f5f5，图标为黑白版本。保留拖动、最小化、最大化和关闭能力；macOS 保留原生标题栏。自定义标题栏样式只在 Windows 启用。
用量页“本次使用／本机全部”位于本地用量区域，仅影响日志统计，不清空或改变当前账号额度。范围文字明确最近切换边界或包含不同账号。统计细目与扫描记录默认折叠，日志不完整时单独提醒。切换栏与刷新按钮共用 38px 高度，刷新中不改变外部尺寸。全部账号额度总览采用五行结构：账号标题、更新状态、会话额度、周额度、重置次数。通过 CSS subgrid 对齐同一排卡片的各行；无记录显示 -- 和“暂无数据”，不显示成已耗尽。
总览底部同一行左侧显示重置次数，右侧显示“到期 MM/DD”；日期保持完整，左侧长说明省略并保留悬停全文。订阅日期的悬停提示包含年份、时间与快照核验时间；缺失显示“到期 未知”，快照日期已过显示“到期 待更新”，不据此判定账号失效。
额度说明保留比例、重置时间与预估标记，不显示消耗速度评价或提前耗尽判断。
用量摘要下方直接展示全部账号额度总览，不再显示按项目、按模型的统计面板。
额度文案使用“在线”“缓存”“预估”“暂无数据”，不用“在线旧快照”等内部术语。重置次数显示“重置 2 次”，缓存追加“· 缓存”；详细更新时间、过期记录和失败原因放在悬停提示中。同一位置不重复来源、时间或预估说明；已过重置时间显示“待更新”，不提前宣称额度已恢复。
材质规则位于 src/ui/glass.css，主要用于顶部操作区、分段导航、按钮、提示浮层、设置面板和弹窗。主内容卡片保持清晰，避免所有区域都强模糊。
- 标准玻璃底色为白色 0.76 alpha，边缘白色 0.92 alpha；模糊为
blur(20px) saturate(1.15)。 - 提示、设置与账号额度浮层提高底色至 0.88 alpha；导航模糊为 12px，确认弹窗的遮罩模糊为 5px。
- 深色主按钮保留石墨渐变与轻微内侧亮边。跟随鼠标的高光只落在边缘，不覆盖文字。
- 圆角按层级递增：紧凑按钮 8–10px、内容卡片约 12–13px、主要容器和弹窗约 16–18px。
浮窗滑块名称为 背景不透明度，范围 0–100%，默认 98%。0% 表示常态背景完全透明，100% 表示窗口背景不透明。
widget.js 同时设置 --widget-alpha 和 --panel-alpha。外框、额度卡片、账号区域、装饰高光、边框和阴影都必须使用这些变量，不能再为其中一层写死背景 alpha。设置通过本机 localStorage 的 codex-auth-widget-opacity 保存，重新打开后恢复，包括 0%。
这里调整各背景层的强度，不对整个窗口或容器设置统一 opacity。文字、按钮、设置面板保留可读性与操作能力；多层叠加后的像素 alpha 不必等于滑块百分比，但 0% 时上述常态底色必须清空。系统减少透明度或高对比度设置优先于滑块，使用实色表面。
动效服务于状态变化和操作反馈。采用短促、柔和的进入与按压反馈，不使用持续闪光、自动漂浮或循环呼吸动画。
| 场景 | 当前参考 |
|---|---|
| 按钮按压 | 主窗口缩放至 0.98，浮窗与取消按钮缩放至 0.96 |
| 弹窗、设置与详情出现 | 约 180–240ms，少量位移与淡入 |
| 额度条变化 | 400ms 平滑宽度过渡 |
| 高光淡出 | 180ms |
| 表面进入曲线 | --ease-out: cubic-bezier(0.22, 1, 0.36, 1) |
| 按压曲线 | --ease-press: cubic-bezier(0.2, 0.8, 0.2, 1) |
src/ui/glass.js 通过事件委托与单个待执行的 requestAnimationFrame 合并指针更新。鼠标静止后不继续调度动画；指针离开、按下、滚动、窗口隐藏或失焦时清除高光。拖动、触摸、禁用控件不触发跟随效果。
浮窗顶部的置顶、设置和隐藏按钮不启用鼠标跟随高光，悬停时不出现白色描边；保留原有背景反馈和键盘焦点提示。
浮窗“钉住”同时置顶并锁定窗口位置：禁用标题栏拖动、边缘调整和贴边收起，取消后恢复；账号点击、排序与其他按钮照常可用。未钉住时图钉倾斜 45°，钉住后转正并保留深色选中背景，旋转过渡为 200ms；系统减少动态效果时直接切换。
装饰伪元素设置 pointer-events: none，不得挡住点击、账号拖动或窗口拖动区域。新增高光目标时同时检查定位方式，避免 position: relative 改变原有固定定位。
- 主操作使用深色按钮，次级操作使用浅色表面，删除等危险操作保留红色。禁用态禁止按压反馈，并与可用态明确区分。
- 策略开关保留真实表单控件与键盘操作，视觉上采用小型滑动开关。文案为“切换后重启 Codex”“额度用尽时自动切换”“自动使用重置卡”。
- 技术说明按需展开。重启、向原任务发送继续指令、消耗重置卡等后果在对应操作旁可见；不支持的平台与开关依赖有明确说明。自动切换正常时只显示短状态，等待、执行与异常时显示具体原因。
- 检查更新使用简短状态和版本信息，仅在有新版本时展示下载相关入口，避免重复解释。
- 更新结果、更新失败和覆盖凭证确认使用统一的应用消息弹窗：共享石墨配色、16px 圆角和 36px 按钮；主窗口提示宽 380px、标题 18px，浮窗提示不超过浮窗宽度及 304px、标题 16px。弹窗使用实色底，不加外部阴影或透明留边，标题及空白区域可拖动。主操作放在右侧；关闭和 Esc 等同取消，凭证覆盖默认聚焦取消。文件选择器及应用初始化失败的兜底提示保留系统界面。
- 倒计时卡片保持紧凑，突出倒计时与取消操作。卡片可拖动并记忆位置，取消按钮必须保持
no-drag，默认靠额度浮窗左下侧显示。 - 键盘焦点使用清晰的外轮廓。尊重
prefers-reduced-motion、prefers-reduced-transparency、prefers-contrast与forced-colors，减少动态效果时停用跟随高光，减少透明度时使用实色。 - 实际额度和预估额度通过文字与纹理共同区分；未知数据保留未知状态，不能为了视觉完整显示成 0。
应用内和桌面资源共用黑白源素材。打包输出仍保留历史 codex-color.* 文件名，不代表继续使用旧蓝紫色图标；不要只替换界面图标而漏掉任务栏、托盘和安装包。
| 职责 | 文件 |
|---|---|
| 共享配色、字体、基础动效与可访问性 | theme.css |
| 玻璃材质与背景透明度联动 | glass.css |
| 指针高光与调度 | glass.js |
| 主窗口布局与账号卡片 | styles.css、app.js |
| 额度浮窗与透明度持久化 | widget.css、widget.js |
| 自动切换倒计时外观 | recovery-countdown.css |
| Windows 标题栏窗口选项 | main.js 的 createWindow() |
| 平台标识桥接 | preload.js 的 platform |
| 应用内 / 无背景图标源文件 | codex-monochrome.svg、codex-monochrome-no-bg.svg |
| 安装包与托盘图标生成 | generate-icon.js |
| Windows 安装向导侧栏 | generate-installer-sidebar.ps1 |
三个页面按 theme.css → 页面自身 CSS → glass.css 加载样式。共享规则放入共享文件，页面特有规则留在页面样式中。界面调整不应顺带改动凭证、账号切换、额度判断或任务恢复逻辑。
按实际改动选择对应检查，不为纯文档改动运行完整构建。
- 布局：查看 860px、900px、1040px 等主窗口宽度，确认无横向溢出、按钮断行或卡片被说明栏拉高；测试长邮箱、空列表和展开详情。
- 主面板：
npm run panel:validate使用模拟账号与隔离的 Electron 配置，覆盖布局、菜单与焦点、添加和迁移入口、删除取消、设置保存失败回滚、平台限制、异常提醒和用量范围；不会读取真实凭据或执行真实切换。 - 浮窗：验证 0%、50%、100% 的底色联动，0% 时文字和设置仍可操作，重新打开后保留设置；同时检查系统减少透明度的覆盖行为。
- 动效：验证悬停、点击、拖动和禁用态，以及窗口隐藏、失焦和减少动态效果后的停止行为。调度检查使用
npm run glass:validate。 - 标题栏与弹窗：检查窗口控制按钮、拖动区、键盘焦点、倒计时取消和弹窗内容可读性。
- 图标：改变源素材或生成脚本后运行
npm run icon:validate，覆盖 100% / 200% 缩放、全部 ICO 尺寸和黑白配色；发布前核验安装包中的实际资源。 - 测试环境：模拟页面也需包含初始化依赖，例如标题栏使用的
document.documentElement.classList；不要为了让测试通过而移除生产交互。
本基线已在 Windows 上验证窗口与透明度表现，GitHub 的 Windows、macOS 构建通过。macOS 界面仍需实机检查，构建成功不代表原生窗口交互已完整验证。