449 lines
36 KiB
Markdown
449 lines
36 KiB
Markdown
# AgentDock 视觉规范 v1.2（赛博风 · 终版，施工唯一依据）
|
||
|
||
适用范围：AgentDock 第一版全部界面（Tauri 2 + React，Windows / Ubuntu，简体中文）。
|
||
本规范是施工员写样式、总工验收的唯一品味依据。未覆盖到的新场景，按「视觉方向」一节的原则推演，不要自创风格。
|
||
|
||
**v1.2 修订说明**：老板已对 v3 样图拍板「通过」，本版把 v3 上按老板意见做的 4 处改动合入规范，为**施工开工的最终依据**。与 v1.1 的差异在 §0 总览逐条映射，并在对应节开头用【v1.2】标注；未标注的条文沿用 v1.1（含其【v1.1】标注）不变。施工对照基准 = 本规范 + v3 样图（HEL-107 附件 `overview3.png`）。
|
||
|
||
## 0. v1.2 变更总览（老板拍板 → 条文映射）
|
||
|
||
| v3 已通过的改动 | 覆盖 v1.1 条文 | v1.2 条文 |
|
||
|---|---|---|
|
||
| ① 侧边栏选中态：废止嵌入 3px 指示条，改为左缘生长的青色渐变 + 1px 青色内描边，一种形态语言 | §3.0 侧边栏选中态 | §3.0【v1.2 重写】 |
|
||
| ② 「提示」级由中性冷灰空心点改为紫色实心点，语义升级为「紫 = 需要留意（提示 / 待授权）」 | §2.1 `--ad-note`、§3.5 提示级 | §2.1、§3.5【v1.2 修订】 |
|
||
| ③ 待授权 KPI 卡数字与顶部色条改紫色；色彩语义表定稿为六色；CLI 状态网格「待授权」角标与「未授权」空心点同步改紫 | §3.1.1 KPI 卡、§3.1.4 状态网格、§3.2、§3.3 | §2.1、§3.1.1、§3.1.4、§3.2、§3.3【v1.2 修订】 |
|
||
| ④ 主按钮 hover 微光扩散：`brightness(1.08)` + 双层扩散辉光，按下收回 | §2.6 悬浮/按下参数 | §2.6【v1.2 修订】 |
|
||
| ⑤ 验收对照同步更新（选中态形态语言、紫色语义红线） | §9 | §9【v1.2 修订】 |
|
||
|
||
---
|
||
|
||
## 1. 视觉方向（一句话）
|
||
|
||
**「深夜运维舱」：像一台运行良好的未来机器——深空蓝黑打底，霓虹青做交互指引，品红只点在关键状态上；光效和动效全部服务于「状态可读」，信息区永远干净克制。**
|
||
|
||
三条不可违反的原则：
|
||
|
||
1. **炫在框架，不在内容**。辉光、网格、扫描线只出现在背景、边框、导航、状态指示上；正文、表单、诊断文本区域保持高对比、零装饰。
|
||
2. **光即语义**。霓虹色不是装饰色：青 = 可交互/主操作，品红 = 可更新/重要提醒，绿 = 正常，黄 = 警告，红 = 错误，【v1.2】紫 = 需要留意（提示 / 待授权）。用户看到颜色就能猜到含义，不许混用。
|
||
3. **普通人友好**。所有动效可降级、可关闭；任何承载信息的文字对比度不低于 WCAG AA（正文 4.5:1，大字 3:1）。
|
||
|
||
【v1.1 新增第四条，v1.2 不变】
|
||
|
||
4. **密度优先**。总览页是信息密度最高的页面，首屏任何区域不允许出现超 15% 的无效空白；「留白高级」在本产品不成立，空 = 内容没做完。
|
||
|
||
---
|
||
|
||
## 2. 设计 Token 全套
|
||
|
||
统一用 CSS 变量命名，前缀 `--ad-`。以下值直接可用，施工员不得自行调参。
|
||
|
||
### 2.1 配色
|
||
|
||
【v1.2 修订：废止 `--ad-note` 中性冷灰，「提示 / 待授权」统一升级为紫色 `--ad-attention`；色彩语义表定稿为六色。其余沿用 v1.1】
|
||
|
||
**底色（深空阶梯，由深到浅）：**
|
||
|
||
| Token | 色值 | 用途 |
|
||
|---|---|---|
|
||
| `--ad-bg-0` | `#070B14` | 应用窗口底色 |
|
||
| `--ad-bg-1` | `#0D1420` | 面板、卡片底色（实际卡片表面用 §3.1 的径向渐变面） |
|
||
| `--ad-bg-2` | `#131C2E` | 浮层、弹窗、下拉、mono chip 底 |
|
||
| `--ad-bg-3` | `#1A2438` | 悬浮态、按下态的填充 |
|
||
| `--ad-border` | `#22304A` | 常规 1px 分隔线 |
|
||
| `--ad-border-bright` | `#35507A` | 悬浮/选中的边框 |
|
||
|
||
**霓虹强调色（全系统只有这两个霓虹色）：**
|
||
|
||
| Token | 色值 | 用途 |
|
||
|---|---|---|
|
||
| `--ad-primary` | `#00E5FF` | 主操作、链接、聚焦、选中态（青） |
|
||
| `--ad-primary-hover` | `#4DEFFF` | 主操作悬浮 |
|
||
| `--ad-primary-pressed` | `#00B4CC` | 主操作按下 |
|
||
| `--ad-primary-dim` | `rgba(0,229,255,0.12)` | 选中项底、标签底 |
|
||
| `--ad-accent` | `#FF4DDB` | 可更新标记、重要提醒（品红，克制使用） |
|
||
| `--ad-accent-dim` | `rgba(255,77,219,0.12)` | 品红标签底 |
|
||
|
||
**状态色（诊断四级 + 通用语义，必须分明，不许互相借用）：**
|
||
|
||
| Token | 色值 | 语义 |
|
||
|---|---|---|
|
||
| `--ad-success` | `#2EE6A8` | 正常 / 已安装 / 已授权 / 已自动修复 |
|
||
| `--ad-attention` | `#A78BFA` | **需要留意：「提示」级 + 「待授权 / 未授权」**（v1.2 新增，紫；实心点、不发光、不呼吸） |
|
||
| `--ad-warning` | `#FFB020` | 警告 / 需要你注意的异常 |
|
||
| `--ad-danger` | `#FF4D5E` | 错误 / 需要你处理 / 高危操作（卸载并删除配置等） |
|
||
|
||
每个状态色配对应的 12% 透明度底色：`--ad-success-dim` / `--ad-attention-dim`（`rgba(167,139,250,0.12)`）/ `--ad-warning-dim` / `--ad-danger-dim`，用于状态标签、诊断条目背景。
|
||
|
||
**完整色彩语义表（v1.2 定稿，六色，全系统唯一标准）：**
|
||
|
||
| 语义 | 颜色 | 形态 |
|
||
|---|---|---|
|
||
| 可交互 / 主操作 / 选中 / 已安装 | 青 `--ad-primary` | 实心渐变按钮、描边、链接、聚焦辉光、状态点、角标 |
|
||
| 需要留意（提示 / 待授权 / 未授权） | 紫 `--ad-attention` | **实心圆点**、ⓘ 图标、待授权角标、未授权空心圈（仅圈形描边用紫，见 §3.1.4），**不发光、不呼吸** |
|
||
| 可更新 / 重要提醒 | 品红 `--ad-accent` | 角标、数字、更新按钮（唯一允许品红做按钮的场景） |
|
||
| 警告 / 需要你注意 | 黄 `--ad-warning` | 状态点、⚠ 图标、警告 chip，允许呼吸 |
|
||
| 错误 / 需要你处理 | 红 `--ad-danger` | 状态点、✕ 图标、危险描边，允许呼吸 |
|
||
| 正常 / 已授权 / 已修复 | 绿 `--ad-success` | 状态点、✓ 图标、chips |
|
||
|
||
**状态色贯穿规则（强制）**：状态色不许只停在装饰条/色点上——凡是表达该状态的**数字、关键文字、图标**必须同色。例：环境异常卡的数字 `1` 必须是 `--ad-warning` 黄，待授权卡的数字必须是 `--ad-attention` 紫，不是白色数字配彩色装饰条。
|
||
|
||
**红色使用红线（强制）**：红只留给「需要你处理」的未解决项。已自愈/已自动修复的条目一律用绿 + 灰化文字 + 「已自动修复」标签（见 §3.1），禁止挂红点。
|
||
|
||
**紫色使用规则（v1.2 新增）**：紫介于「正常」与「警告」之间，表达「现在不用处理，但需要你留意」——诊断「提示」级、待授权/未授权状态专用。紫色任何形态**不发光、不呼吸**（避免与警告/错误的动态信号混淆）；诊断列表中「提示」级用紫色**实心**点（v1.1 的中性空心点废止）。
|
||
|
||
**已删除**：`--ad-info` `#4DA3FF` 及 `--ad-info-dim`（蓝色退出系统，界面任何位置出现蓝色 = 不合格）；`--ad-note` `#8E9BB0` 及 `--ad-note-dim`（v1.2 起由 `--ad-attention` 取代）。
|
||
|
||
**文字：**
|
||
|
||
| Token | 色值 | 用途 |
|
||
|---|---|---|
|
||
| `--ad-text-1` | `#E8EEF7` | 主文案 |
|
||
| `--ad-text-2` | `#9AA8BD` | 次要说明（对 `--ad-bg-1` 对比度约 6.9:1，是承载信息的最低允许色） |
|
||
| `--ad-text-3` | `#5E6E87` | 仅占位、禁用、纯装饰（对比度约 3.3:1，**禁止承载信息**） |
|
||
|
||
**对比度三件套之一**：任何承载信息的文字（含次要说明、时间戳、安全承诺文案）对比度 ≥ 4.5:1，即最低用 `--ad-text-2`；`--ad-text-3` 只允许出现在禁用态与占位符。安全承诺、授权提示这类建立信任的文字尤其不许压暗。
|
||
|
||
### 2.2 字体
|
||
|
||
【v1.2 不变】
|
||
|
||
```css
|
||
--ad-font-ui: "PingFang SC", "Microsoft YaHei UI", "Microsoft YaHei",
|
||
"Noto Sans CJK SC", "Source Han Sans SC", system-ui, sans-serif;
|
||
--ad-font-mono: "Cascadia Code", "JetBrains Mono", Consolas,
|
||
"Noto Sans Mono CJK SC", monospace;
|
||
```
|
||
|
||
- 等宽字体只用于：命令、路径、版本号、日志/终端输出、API Key 掩码、文件名。路径里的中文允许回落到 UI 字体，不用强求等宽。
|
||
- **Mono chip**（对比度三件套之二）：正文/列表中内联出现的文件名、版本号、命令，一律套 mono chip：`--ad-font-mono` 12px、`--ad-bg-2` 底、1px `--ad-border` 描边、`--ad-radius-s`、内边距 `1px 6px`，文字色 `--ad-text-1`。例：`settings.json`、`v0.22.0`、`20.x`。
|
||
- 字阶（字号 / 行高 / 字重）：
|
||
|
||
| Token | 规格 | 用途 |
|
||
|---|---|---|
|
||
| `--ad-text-xs` | 12px / 18px / 400 | 标签、辅助说明、时间戳 |
|
||
| `--ad-text-s` | 13px / 20px / 400 | 表格次级信息、卡片描述 |
|
||
| `--ad-text-m` | 14px / 22px / 400 | 正文、表单、按钮（基准字号） |
|
||
| `--ad-text-l` | 16px / 24px / 500 | 卡片标题、分组标题 |
|
||
| `--ad-text-xl` | 20px / 28px / 600 | 页面标题 |
|
||
| `--ad-text-num` | 28px / 36px / 600 | 仪表盘大数字（UI 字体，不用等宽） |
|
||
|
||
不加任何外联 Web 字体（离线可用、安装包不膨胀）。
|
||
|
||
### 2.3 间距、圆角、描边
|
||
|
||
【v1.2 不变】
|
||
|
||
- 间距 4px 基数：`--ad-space-1: 4px` `-2: 8px` `-3: 12px` `-4: 16px` `-5: 20px` `-6: 24px` `-8: 32px` `-10: 40px`
|
||
- 圆角：`--ad-radius-s: 4px`（标签、小按钮、chip）`--ad-radius-m: 8px`（卡片、输入框、弹窗）`--ad-radius-l: 12px`（主面板）。**赛博感靠小圆角 + 发光描边，不做大圆角。**
|
||
- 可选切角：仅仪表盘 KPI 卡、CLI 详情页头卡允许用 `clip-path` 切一个 8px 的右上斜角，制造硬核感；低性能档一律退回直角，见第 5 节。
|
||
- 描边统一 1px；选中/聚焦的「发光描边」= 1px 实色 + 外辉光，不允许加粗到 2px（会跳动）。
|
||
|
||
### 2.4 阴影与辉光
|
||
|
||
【v1.2 微调：不发光对象表述对齐紫色新语义；主按钮 hover 辉光参数见 §2.6】
|
||
|
||
```css
|
||
--ad-shadow-panel: 0 8px 24px rgba(0, 0, 0, 0.45);
|
||
--ad-shadow-pop: 0 12px 40px rgba(0, 0, 0, 0.6);
|
||
--ad-glow-primary: 0 0 12px rgba(0, 229, 255, 0.35), 0 0 32px rgba(0, 229, 255, 0.12);
|
||
--ad-glow-accent: 0 0 12px rgba(255, 77, 219, 0.35);
|
||
--ad-glow-warning: 0 0 10px rgba(255, 176, 32, 0.28); /* 仅警告 chip / 警告状态灯 */
|
||
--ad-glow-danger: 0 0 12px rgba(255, 77, 94, 0.35);
|
||
```
|
||
|
||
辉光只给：主按钮、选中导航项、聚焦输入框、需处理状态指示灯、可更新角标、环境警告 chip。**列表里每一行都发光 = 全部不发光，禁止。**「需要留意」级（`--ad-attention` 紫）任何形态不发光。
|
||
|
||
### 2.5 动效曲线与时长
|
||
|
||
【v1.2 不变】
|
||
|
||
```css
|
||
--ad-ease-out: cubic-bezier(0.16, 1, 0.3, 1); /* 进场、浮现，主力曲线 */
|
||
--ad-ease-inout: cubic-bezier(0.65, 0, 0.35, 1); /* 展开收起、位移、呼吸 */
|
||
--ad-ease-linear: linear; /* 仅环境循环动画 */
|
||
--ad-dur-micro: 120ms; /* 按下、勾选 */
|
||
--ad-dur-fast: 200ms; /* 悬浮、淡入淡出 */
|
||
--ad-dur-med: 320ms; /* 面板展开、页面切换 */
|
||
--ad-dur-slow: 600ms; /* 仅入场编排，一次性 */
|
||
```
|
||
|
||
### 2.6 主按钮规格
|
||
|
||
【v1.2 修订：老板裁定大面积青保留为风格选择，但 hover 必须用扩散光消化高饱和——悬浮辉光由单层升级为双层扩散，按下收回；其余沿用 v1.1】
|
||
|
||
```css
|
||
/* 主按钮（添加 CLI、安装 等主操作） */
|
||
--ad-btn-primary-bg: linear-gradient(180deg, #33D9EE 0%, #06BCD9 55%, #049EBB 100%);
|
||
--ad-btn-primary-text: #03252E;
|
||
--ad-btn-primary-inner: inset 0 1px 0 rgba(255, 255, 255, 0.30),
|
||
inset 0 -1px 0 rgba(2, 20, 26, 0.35);
|
||
--ad-btn-primary-glow: 0 0 10px rgba(0, 229, 255, 0.22);
|
||
/* v1.2 新增：hover 双层扩散辉光 */
|
||
--ad-btn-primary-glow-hover: 0 0 14px rgba(0, 229, 255, 0.30),
|
||
0 0 36px rgba(0, 229, 255, 0.12);
|
||
```
|
||
|
||
- 结构：高 36px，`--ad-radius-s`，`--ad-btn-primary-bg` 内渐变 + `--ad-btn-primary-inner` 内高光/内阴影 + 常驻 `--ad-btn-primary-glow` 弱辉光，字 14px / 500 / `--ad-btn-primary-text`。
|
||
- 悬浮（v1.2 定稿）：`filter: brightness(1.08)` + 辉光扩为双层 `--ad-btn-primary-glow-hover`（内层 14px 聚焦、外层 36px 弥散），200ms `--ad-ease-out`。原理：用向外扩散的柔光消化大面积高饱和青在悬浮时的刺眼感，而不是再提亮本体。
|
||
- 按下：`filter: brightness(0.94)`，辉光收回（消失），120ms。
|
||
- 荧光感控制：`#00E5FF` 只用于描边、图标、文字、辉光这类「线」与「点」，实心填充一律用上面的降明度内渐变。
|
||
- 品红更新按钮同理：`linear-gradient(180deg, #F26AD9 0%, #D633B8 55%, #B5209C 100%)`，内高光/内阴影同构，常驻辉光用 `--ad-glow-accent` 半强度；悬浮辉光同样按「半径放大、透明度分层」扩散（`0 0 14px rgba(255,77,219,0.30), 0 0 36px rgba(255,77,219,0.12)`）。
|
||
|
||
---
|
||
|
||
## 3. 关键页面布局与组件样式
|
||
|
||
### 3.0 整体框架
|
||
|
||
【v1.2 修订：侧边栏选中态重写（废止嵌入指示条，改左缘生长渐变 + 内描边一体形态）；背景网格、导航图标、引擎状态区、Header 分组沿用 v1.1】
|
||
|
||
整体框架：**左侧竖导航 + 顶栏 + 内容区**。
|
||
|
||
**背景网格（要么可见要么不做，禁止两头不占）：**
|
||
|
||
- 规格：1px 线、40px 间距、颜色 `rgba(0,229,255,0.05)`（透明度固定 5%，允许区间 3–6%，施工员取 5% 不许再调）；
|
||
- **边缘羽化**：整体罩一层径向遮罩 `mask-image: radial-gradient(120% 90% at 50% 40%, #000 30%, transparent 75%)`，中心可见、向四边淡出至 0；
|
||
- 中高档附 60s 缓慢漂移（见 §4.8），低档静态；
|
||
- 若实现后静态截图下网格仍不可见，宁可删掉网格也不许留在「若隐若现」区间。
|
||
|
||
**侧边栏：**
|
||
|
||
- 宽 232px，收起后 64px（只留图标）。
|
||
- **选中态（v1.2 定稿，废止 v1.1「圆角背景块 + 嵌入 3px 指示条」方案——老板两轮审图判定指示条与圆角背景是两张皮）**：选中项 = 一个圆角背景块，**无独立指示条**，整个选中态只有一种形态语言：
|
||
- 背景：`linear-gradient(90deg, rgba(0,229,255,0.30), rgba(0,229,255,0.12) 45%, rgba(0,229,255,0.05))`——一层从块左缘「生长」的青色渐变，左浓右淡，到右缘几乎消隐；
|
||
- 内描边：`inset 0 0 0 1px rgba(0,229,255,0.38)`，与背景块同圆角；
|
||
- 块规格：`--ad-radius-m`、左右内边距 12px、块左右各留 8px 外边距（不贴窗口边缘）；
|
||
- 图标与文字变 `--ad-primary`；
|
||
- 不额外加辉光（渐变 + 内描边已足够表达选中，再叠光则脏）。
|
||
- 收起态（64px 图标栏）：同一套渐变 + 内描边作用于 40px 见方图标块，形态语言不变。
|
||
- 定义 token：`--ad-nav-selected-bg`（上述渐变）、`--ad-nav-selected-border`（上述内描边）。
|
||
- 导航图标：5 个一级导航统一 20px 显示尺寸、**1.5px 描边**、圆角端点线性风格（§7），粗细不一致的图标混用前必须调 stroke 到 1.5px 观感。
|
||
- 底部引擎状态区：独立区块高 48px，顶部 1px `--ad-border` 分隔线，内边距 `0 16px`；内容 = 8px 状态灯（运行中=绿静态、异常=黄呼吸，规则见 §4.5）+ 「本地引擎 · 运行中」`--ad-text-s` / `--ad-text-2` + 版本号 mono chip（如 `v1.0.0`）。收起态只留状态灯居中。
|
||
|
||
**顶栏（Header）：**
|
||
|
||
- 高 56px，左起：当前页标题（`--ad-text-xl`）。
|
||
- 右侧状态区分组：搜索框与环境警告 chip 为一组，间距 `--ad-space-3`（12px），组内基线对齐，与页面标题拉开间距。
|
||
- 搜索框限宽：标准断点固定宽 320px，紧凑断点收缩为 36px 图标按钮、点击展开。聚焦 = 边框变青 + `--ad-glow-primary`。
|
||
- **环境警告 chip**：高 28px、`--ad-radius-s`、1px `rgba(255,176,32,0.5)` 描边、`--ad-warning-dim` 底；内容 = 6px 黄点（异常存在时按 §4.5 呼吸）+ 「N 项环境警告」`--ad-text-s` / `--ad-warning` + 12px chevron-down。悬浮：描边转实色 `--ad-warning` + `--ad-glow-warning` + 手型指针，200ms；点击展开警告明细下拉。无警告时整颗 chip 不渲染，不留占位。
|
||
|
||
**内容区：** 最大宽 1440px 居中，左右留白 `--ad-space-8`。
|
||
|
||
### 3.1 总览（仪表盘)
|
||
|
||
【v1.2 修订：KPI 卡「待授权」数字与色条改紫；CLI 状态网格「待授权」角标与「未授权」点改紫；其余布局与规则沿用 v1.1】
|
||
|
||
**布局（自上而下三段，首屏必须填满）：**
|
||
|
||
1. KPI 卡一排 4 张：已安装 / 待授权 / 可更新 / 环境异常。
|
||
2. 中段：左 2/3「最近诊断结果」列表，右 1/3「快速操作」卡。
|
||
3. **下段（必选模块）：「CLI 状态」网格通栏**，已收录 CLI 以状态块平铺（见 §3.1.4）。后续迭代可在其下再接「资源占用」「活动流」模块，规则同本页组件语言；首屏任何纵向区间无效空白 ≤ 15%。
|
||
|
||
**3.1.1 KPI 卡：**
|
||
|
||
- 卡片表面（悬浮玻璃板）：底为径向渐变面 `radial-gradient(120% 100% at 50% 0%, #16233A 0%, #0D1420 60%)` + 上缘 1px 高光 `inset 0 1px 0 rgba(255,255,255,0.06)` + `--ad-shadow-panel`；与页面背景明度差必须拉开，验收时卡片边界在静态截图下清晰可辨。
|
||
- `--ad-radius-l`、右上 8px 切角（可选，低档退回直角）。
|
||
- **顶部色条贯通整宽**（废止半拉子短条；也不许做左侧短装饰条）：2px 高、与卡片同宽，颜色按卡语义【v1.2 定稿】：已安装=青、**待授权=紫 `--ad-attention`**（v1.1 的中性 `--ad-border-bright` 废止）、可更新=品红、异常=黄；**数值为 0 时色条降为 `--ad-border` 灰**。
|
||
- 大数字 `--ad-text-num`，**数字随状态色贯穿**【v1.2 定稿】：已安装=青、**待授权=紫 `--ad-attention`**（v1.1 的中性白废止——待授权是「需要留意」的待办，按六色语义表归紫色，不再是「不色」）、可更新=品红、环境异常=黄；数值为 0 时数字回 `--ad-text-1`。
|
||
- 副标题统一「对象点名」句式（强制）：不解释、不形容，直接点出对象名，超过 3 个用「A · B · C 等 N 个」。例：待授权 → `Kimi CLI · Warp Agent`；环境异常 → `Node.js 20.x`（版本号套 mono chip）；已安装 → `最新安装 · Qwen Code`；可更新 → `Qwen Code · Goose · Aider`。
|
||
- 悬浮：整体抬升 2px + 顶部色条辉光，200ms `--ad-ease-out`，不打断数据。
|
||
|
||
**3.1.2 最近诊断列表（五条硬规则）：**
|
||
|
||
1. **时间格式（三件套之三，全应用统一）**：<1 分钟显示「刚刚」；<1 小时显示「N 分钟前」；<24 小时显示「N 小时前」；≥24 小时一律绝对时间「M月D日 HH:mm」（跨年开始带年「YYYY年M月D日」）；悬浮显示完整绝对时间 tooltip。禁止相对/绝对混排无规则出现。
|
||
2. **mono chip**：条目内的文件名、版本号、命令一律按 §2.2 套 mono chip。
|
||
3. **对比度**：结论文字最低 `--ad-text-2`，时间戳最低 `--ad-text-2`，任何承载信息的文字不低于 4.5:1。
|
||
4. **红色只留「需要你处理」**：已自动修复的条目 = 绿点 + 文字灰化（`--ad-text-2`）+ 右侧「已自动修复」标签（绿字、1px `rgba(46,230,168,0.4)` 描边、`--ad-success-dim` 底、高 20px）；未解决错误才用红点 + `--ad-text-1` 文字。【v1.2】「提示」级用 `--ad-attention` **紫色实心圆点**（v1.1 的中性空心点废止），不发光、不呼吸。
|
||
5. **「查看全部」**：`--ad-text-s` 青字 + 14px chevron-right 图标，悬浮文字变 `--ad-primary-hover`、chevron 右移 2px，200ms。
|
||
|
||
行结构不变：级别点 + CLI 名 + 一句话结论 + 右侧时间，行高 48px，整行可点击进诊断详情。
|
||
|
||
**3.1.3 快速操作卡：**
|
||
|
||
- 结构自上而下：主按钮「添加 CLI」（§2.6 规格，+ 图标）→ 次按钮「立即诊断」→ 次按钮「创建备份」→「最近安装」迷你列表 → 安全承诺行。密度必须与左侧诊断列表视觉平衡，不允许一侧拥挤一侧空荡。
|
||
- 图标语义（定死）：「立即诊断」用 pulse/scan 类图标（心电脉冲或扫描线），不许用公文包等无关图标；「添加 CLI」用标准加号图标，全应用加号统一同一枚；「创建备份」用下载/存档类图标。
|
||
- 按钮内图标 16px，与文字间距统一 `--ad-space-2`（8px），三个按钮对齐方式一致（统一居中）。
|
||
- 「最近安装」列表：分组标题 `--ad-text-xs` / `--ad-text-3`（此为唯一允许的 `--ad-text-3` 分组标签用法，下同不例）+ 最多 3 条，每条 = 16px CLI 图标 + 名称 `--ad-text-s` + 右侧相对时间 `--ad-text-xs` / `--ad-text-2`。
|
||
- 安全承诺行：12px 锁图标 + 「所有操作在本地完成，密钥只存系统保险柜，不上传。」，`--ad-text-xs` 但文字色**最低 `--ad-text-2`**（建立信任的文案不许压暗）。
|
||
|
||
**3.1.4 CLI 状态网格：**
|
||
|
||
- 容器：通栏面板，标题「CLI 状态」+ 右侧「管理全部 N 个」青字 + chevron-right。
|
||
- 网格：`repeat(auto-fill, minmax(280px, 1fr))`，间距 `--ad-space-4`；各断点列数见 §6。
|
||
- 状态块结构（自上而下）：
|
||
- 第一行：左 32px CLI 图标（单色剪影，无品牌彩色，无厂商图标时用双字母单色头像，`--ad-bg-2` 底 + 1px `--ad-border`）+ 名称 `--ad-text-m` / `--ad-text-1`；右侧**状态角标**（高 22px、`--ad-radius-s`、`--ad-text-xs`）。
|
||
- 第二行：版本号 mono chip（未安装显示 `—` 不套 chip）。
|
||
- 第三行（授权行）：8px 授权状态点 + 授权状态文案 `--ad-text-xs` + `·` + 最近检测时间。
|
||
- 状态角标规则【v1.2 修订】：已安装 = 青字 + 1px `rgba(0,229,255,0.4)` 描边 + `--ad-primary-dim` 底；可更新 = 品红字 + 1px `rgba(255,77,219,0.5)` 描边 + `--ad-accent-dim` 底 + 弱 `--ad-glow-accent`；**待授权 = 紫字 `--ad-attention` + 1px `rgba(167,139,250,0.5)` 描边 + `--ad-attention-dim` 底**（v1.1 的中性方案废止，紫色不发光）；未安装 = `--ad-text-3` 字 + `--ad-border` 描边。
|
||
- 授权状态点规则【v1.2 修订】：已授权 = 绿实心点（静态，不呼吸）；**未授权 = 紫色空心圈（1.5px `--ad-attention` 描边）**+ 文案「未授权 · 点击去授权」，悬浮整行变青可点击（v1.1 的中性空心圈废止）；授权可能过期 = 黄点 + 按 §4.5 呼吸；未检测/未知 = `--ad-text-3` 灰实心点 + 文案给出下一步（如「未检测 · 可一键安装」）。
|
||
- 块体样式：`--ad-bg-1` 底、1px `--ad-border`、`--ad-radius-m`、内边距 `--ad-space-4`；悬浮边框变 `--ad-border-bright`，200ms；不发光、不放大。
|
||
- 排序：需要你处理的排最前（可更新 > 待授权 > 未安装 > 已安装），同级按最近检测时间倒序。
|
||
|
||
### 3.2 CLI 目录（卡片列表）
|
||
|
||
【v1.2 微调：状态角标颜色对齐六色语义表】
|
||
|
||
- 顶部工具条：搜索框（320px 限宽、青聚焦辉光）+ 平台筛选（Windows / Linux 胶囊按钮）+ 状态筛选（全部/已安装/未安装/可更新）。
|
||
- 卡片网格：`repeat(auto-fill, minmax(280px, 1fr))`，间距 `--ad-space-4`。
|
||
- 卡片结构：左上图标 40px + 中文名（`--ad-text-l`）+ 厂商小字；中间两行简介（超出省略）；底部状态角标 + 平台图标 + 适配器版本 mono chip。
|
||
- 状态角标样式：与 §3.1.4 状态角标规则完全一致（已安装=青、可更新=品红 + 弱辉光、**待授权=紫**、未安装=灰）。
|
||
- 悬浮：卡片边框从 `--ad-border` 过渡到 `--ad-primary` 并带弱辉光，200ms；不做放大（网格会抖）。
|
||
|
||
### 3.3 CLI 详情页
|
||
|
||
【v1.2 微调：授权状态灯「未授权」改紫】
|
||
|
||
- 头卡：左 56px 图标 + 名称 + 厂商 + 版本/路径（等宽、`--ad-text-2`）；右侧主操作按钮区。主操作按状态变化：未安装=「安装」（§2.6 主按钮）、已安装=「打开配置」（青描边）、可更新=「更新到 x.y.z」（§2.6 品红按钮，全应用唯一允许品红做按钮的地方）。卸载永远是文字按钮 + 悬停变红，藏进「更多」。
|
||
- 授权状态灯：头卡内一颗 10px 圆点 + 中文状态（已授权/未授权/授权可能过期/未知）：已授权=绿（静态）、**未授权=紫 `--ad-attention`（静态）**、可能过期=黄（呼吸）、未知=`--ad-text-3` 灰。
|
||
- 下方标签页：概览 / 配置 / 中文文档 / 诊断。标签选中 = 底部 2px 青条 + 青色文字，切换 200ms。
|
||
- 中文文档区按普通阅读排版：正文 `--ad-text-m`，最大行宽 720px，禁止在正文区加任何光效。
|
||
|
||
### 3.4 配置表单（含敏感字段）
|
||
|
||
【v1.2 不变】
|
||
|
||
- 单列布局，最大宽 640px；标签在上（`--ad-text-s`，`--ad-text-2`）、控件在下，字段间距 `--ad-space-5`。必填项标签后加青色 `*`；每项下方一行中文用途说明（`--ad-text-xs` / `--ad-text-2`）。
|
||
- 输入框：`--ad-bg-0` 底、1px `--ad-border`、`--ad-radius-m`、高 36px、内边距 `0 12px`。聚焦 = 边框变 `--ad-primary` + `--ad-glow-primary`，120ms。
|
||
- **敏感字段（API Key 等）**：密码框 + 右侧「眼睛」显隐切换；已存入系统密钥库时输入框左侧显示 12px 锁形图标 + 说明「已加密保存于系统密钥库」（`--ad-text-2`）。显示掩码时一律用 `●` 不用 `*`。
|
||
- 校验：错误时边框变 `--ad-danger` + 下方一行中文错误说明，不弹 toast；保存按钮常驻底部吸底条，保存成功给一次性青色对勾动画（见 §4.6）。
|
||
- 「保存来源 / 最近修改 / 备份状态」放表单页脚，`--ad-text-xs` / `--ad-text-2`。
|
||
|
||
### 3.5 诊断结果页
|
||
|
||
【v1.2 修订：「提示」级由中性冷灰改紫 `--ad-attention`，形态仍为空心 ⓘ 图标（靠形态而非颜色区分色弱用户），色条同紫、不发光】
|
||
|
||
顶部一颗大状态灯 + 汇总句（如「发现 1 个错误、2 个提示」），下方按级别分组列出检查项。
|
||
|
||
- 每个检查项 = 左侧 3px 级别色条 + 级别图标（正常 ✓ 实心 / 提示 ⓘ 空心 / 警告 ⚠ / 错误 ✕）+ 标题 + 中文解释 + 「推荐修复」按钮（警告/错误才显示）。
|
||
- 级别色严格用 §2.1 状态色：**正常=绿、提示=紫 `--ad-attention`、警告=黄、错误=红**，配合不同图标与实心/空心形态，色弱用户也能分辨。「提示」级色条与图标不发光。
|
||
- 原始证据（命令输出、路径、错误码）：等宽字体、`--ad-bg-0` 底、默认折叠，点击展开 320ms `--ad-ease-inout`。允许 1px 青色行号槽，但不发光。
|
||
- 高危修复按钮（覆盖配置等）：`--ad-danger` 描边，点击后二次确认弹窗，弹窗标题栏左侧红色辉光点。
|
||
|
||
### 3.6 通用组件速查
|
||
|
||
【v1.2 微调：新增侧边栏选中态条目，指向 §3.0】
|
||
|
||
| 组件 | 规格 |
|
||
|---|---|
|
||
| 主按钮 | 见 §2.6：降明度内渐变 + 内高光 + 常驻弱辉光；hover 双层扩散辉光 |
|
||
| 次按钮 | 透明底 + 1px `--ad-border-bright` + `--ad-text-1`；悬浮边框变青 |
|
||
| 危险按钮 | `--ad-danger` 描边 + 红字；确认后才实心 |
|
||
| 侧边栏选中态 | 见 §3.0：左缘生长青渐变 + 1px 青色内描边，无独立指示条 |
|
||
| 环境警告 chip | 见 §3.0：黄描边 + 黄点 + chevron，悬浮带 `--ad-glow-warning`，可点击 |
|
||
| Mono chip | 见 §2.2：文件名/版本号/命令的内联等宽 chip |
|
||
| 弹窗 | `--ad-bg-2` 底、`--ad-radius-l`、`--ad-shadow-pop`、遮罩 `rgba(4,7,13,0.7)` |
|
||
| Toast | 右下角滑入，底 `--ad-bg-2` + 左侧 3px 状态色条，4s 自动消失，错误 Toast 常驻需手关 |
|
||
| 空状态 | 线性插画（见 §7）+ 一句中文引导 + 主按钮；**总览页不允许出现空状态式大留白，用 §3.1 模块填满** |
|
||
|
||
---
|
||
|
||
## 4. 动效规范
|
||
|
||
【v1.2 不变（紫色不呼吸的规则已在 §2.1 / §4.5 内体现）】
|
||
|
||
通则：**所有动效只动 `transform` 和 `opacity`**（辉光强弱可用 `box-shadow` 过渡，但仅限单个聚焦元素）；任何循环动画在低配档必须可停。`prefers-reduced-motion: reduce` 时全局只保留透明度渐变，时长压到 100ms。
|
||
|
||
**§4.0 动效启用前提**：排版三件套（时间格式、mono chip、对比度）与密度、色彩未达标前，任何动效装饰不进入验收——基础不修，动效越炫越显糙。验收顺序固定为：① 密度 → ② 色彩 → ③ 排版三件套 → ④ 形态语言（渐变条/选中态）→ ⑤ 动效。
|
||
|
||
| # | 动效 | 触发条件 | 时长 | 缓动 | 可否打断 |
|
||
|---|---|---|---|---|---|
|
||
| 4.1 | 按钮/卡片悬浮辉光渐入 | hover | 200ms | `--ad-ease-out` | 可（鼠标移出即反向） |
|
||
| 4.2 | 页面切换 | 路由变化 | 320ms，新页 `translateY(8px)+淡入`，旧页只淡出 | `--ad-ease-out` | 可，立即跳到目标页 |
|
||
| 4.3 | 面板/折叠区展开（诊断证据、高级选项） | 点击 | 320ms | `--ad-ease-inout` | 可 |
|
||
| 4.4 | 仪表盘 KPI 数字滚动 | 数据首次加载 | 600ms，一次性，不循环 | `--ad-ease-out` | 不可（太短，直接播完） |
|
||
| 4.5 | **状态点呼吸** | **仅「需要处理」的项呼吸：警告（黄）、错误（红）、授权可能过期（黄）。绿/正常/提示（紫）/待授权（紫）一律静态** | 2400ms | `--ad-ease-inout`，**透明度 1 ↔ 0.4（下限 40%，再低像灭了，禁止）** | 状态恢复即停 |
|
||
| 4.6 | 保存成功对勾 | 配置保存成功 | 400ms 描边绘制 + 200ms 青辉光脉冲一次 | `--ad-ease-out` | 不可 |
|
||
| 4.7 | 安装/诊断进行中 | 任务运行 | 进度条用确定值；不确定时用 1.6s 青色流光扫过（linear infinite） | `--ad-ease-linear` | 任务结束即停 |
|
||
| 4.8 | 背景网格漂移 | 常驻氛围 | 60s 一周 | linear | 降档即停 |
|
||
| 4.9 | Toast 滑入滑出 | 出现/消失 | 200ms / 200ms | `--ad-ease-out` | 鼠标悬停暂停计时 |
|
||
|
||
**§4.5 补充规则**：
|
||
|
||
1. 全应用所有呼吸点**同频同相位**——用同一个全局动画时钟（同一个 CSS animation 名 + 同步起始），禁止各组件各自起动画导致此起彼伏。
|
||
2. 呼吸只动透明度（1 ↔ 0.4），不动尺寸、不动辉光半径。
|
||
3. 同屏呼吸点超过 3 个时，只保留级别最高的 3 个呼吸，其余静态（错误 > 警告）。
|
||
4. 低档：呼吸全部停用，改静态点 + 图标区分（§5）。
|
||
|
||
明确禁止的动效：元素无限弹跳、文字逐字打印、hover 缩放超过 1.02、列表项 stagger 超过 5 个。
|
||
|
||
---
|
||
|
||
## 5. 性能降级策略（高特效项目必备）
|
||
|
||
【v1.2 不变】
|
||
|
||
**三档：高 / 中 / 低。默认「自动」：按运行表现动态降档，用户可在设置页手动锁档。**
|
||
|
||
| 特效 | 高档 | 中档 | 低档 |
|
||
|---|---|---|---|
|
||
| 背景氛围 | Canvas 粒子星网（≤60 粒子）+ 网格漂移 | 纯 CSS 渐变 + 可见网格（5% + 羽化） | 静态渐变图，网格可留静态，无动画 |
|
||
| 辉光 | 多层 `box-shadow` 全量 | 只保留单层、半径减半 | 全部移除，改 1px 亮色边框 |
|
||
| 切角 clip-path | 启用 | 启用 | 禁用（直角） |
|
||
| 页面/面板动效 | 全量 | 时长 ×0.7 | 只留 100ms 淡入淡出 |
|
||
| 循环动画（呼吸、流光） | 启用（按 §4.5 仅异常呼吸） | 只保留任务进行中的流光 | 全部停用，改静态图标 |
|
||
| 数字滚动 | 启用 | 启用 | 直接显示终值 |
|
||
|
||
**自动降档规则（施工员照此实现）：**
|
||
|
||
1. 启动时 `prefers-reduced-motion` 或 `navigator.hardwareConcurrency ≤ 4` → 直接进低档。
|
||
2. 运行中用 `requestAnimationFrame` 采样：连续 3 秒平均帧率 < 45fps → 降一档并记住；低于 30fps → 直接低档。
|
||
3. 降档只降不升（防抖动），重启后重新评估。
|
||
4. 设置页提供「界面特效：自动 / 高 / 中 / 低」四选一，手动选择覆盖自动。
|
||
|
||
---
|
||
|
||
## 6. 窗口尺寸响应
|
||
|
||
【v1.2 不变】
|
||
|
||
桌面窗口，最小 **960 × 600**，不设上限。三个断点：
|
||
|
||
| 断点 | 宽度 | 布局变化 |
|
||
|---|---|---|
|
||
| 紧凑 | 960–1199px | 左导航收起为 64px 图标栏；KPI 卡 2×2；诊断列表与快速操作上下堆叠（诊断在上）；CLI 状态网格 2 列；详情页头卡操作按钮折成两行；配置表单仍单列 |
|
||
| 标准 | 1200–1599px | 完整 232px 导航；KPI 一排 4 张；诊断 + 快速操作左右 2:1；CLI 状态网格 3 列；目录卡片 3 列左右 |
|
||
| 宽阔 | ≥1600px | 内容区锁 1440px 居中，多余空间留黑，不拉伸卡片；CLI 状态网格 4 列；诊断页可「结果列表 + 证据」左右双栏 |
|
||
|
||
窗口高度 < 700px 时：顶栏从 56px 压到 44px，KPI 卡大数字从 28px 降到 22px，CLI 状态网格允许纵向滚动但模块不许删除，不允许出现内容被裁切。
|
||
|
||
---
|
||
|
||
## 7. 图标与插画方向
|
||
|
||
【v1.2 微调：「提示」图标颜色改紫】
|
||
|
||
- **图标**：线性风格，统一 24px viewBox、**1.5px 描边**、圆角端点；颜色默认 `--ad-text-2`，选中/激活态变 `--ad-primary`。状态图标（诊断四级、授权灯）用实心填充 + 状态色（「提示」用空心 ⓘ + `--ad-attention` 紫）。CLI 厂商图标一律单色剪影，不上品牌彩色，hover 时叠加青色光晕。
|
||
- **语义图标（定死）**：诊断/扫描类动作用 pulse/scan 图标；「添加」全应用统一同一枚加号图标；「查看全部/展开」统一 chevron 系列，不许混用 `›` 字符与箭头图形。
|
||
- **插画**：只出现在空状态和引导页。等距线框风格（1px 线、`--ad-border-bright` 色）+ 一到两处霓虹青/品红渐变点缀，内容画「终端窗口、线缆、集装箱」这类 Dock 意象，不画人物、不画卡通。
|
||
- 图标库选型由施工员定（任何成熟线性库均可），但描边粗细必须统一为 1.5px 观感，混用前调 stroke。
|
||
|
||
---
|
||
|
||
## 8. 需要总工确认的技术可行性点
|
||
|
||
【v1.2 不变，沿用 v1.0/v1.1 四条（结论已在 HEL-102 由总工给出，若与本规范条文有出入以总工结论为准）】
|
||
|
||
1. **背景氛围层**：计划用 Canvas 2D（≤60 粒子 + 网格）而非 WebGL；若总工想要 WebGL 着色器光效，需评估 Tauri 在 WebView2（Windows）与 WebKitGTK（Ubuntu）下的功耗与兼容性，确认后我再补高档的视觉参数。
|
||
2. **`backdrop-filter` 毛玻璃**：弹窗遮罩想做轻微毛玻璃，WebKitGTK 老版本支持不稳定，需确认目标 WebKitGTK 版本；不支持则退化为纯半透明遮罩（本规范默认值即按退化方案给的）。
|
||
3. **辉光 `box-shadow` 多层过渡**：逐帧过渡多层阴影在低端机可能引起重绘开销，§5 已按「低档移除」兜底；若总工有更省的实现（如预渲染光晕贴图），以技术方案为准，视觉等效即可。
|
||
4. **CJK 字体渲染**：Ubuntu 上 `Noto Sans CJK SC` 依赖系统安装，需确认安装包是否内置兜底字体或声明依赖；不内置则字重 600 可能退化为合成加粗，验收时以实际渲染为准。
|
||
|
||
---
|
||
|
||
## 9. 验收对照（给总工）
|
||
|
||
【v1.2 修订：形态语言行更新为「无独立指示条」的选中态标准；色彩行补紫色语义红线】
|
||
|
||
验收顺序固定（老板优先级）：**① 密度 → ② 色彩 → ③ 排版三件套 → ④ 形态语言 → ⑤ 动效**。前一项不达标，后一项不看。
|
||
|
||
- **密度**：总览首屏任何纵向区间无效空白 ≤ 15%；下半屏必须有 CLI 状态网格（或同级信息模块）= 合格底线。
|
||
- **色彩**：所有颜色只能来自 §2 Token；界面出现蓝色 = 不合格；状态色未贯穿到数字/关键文字 = 不合格；红色挂在已自愈条目上 = 不合格；【v1.2】「提示 / 待授权 / 未授权」未用 `--ad-attention` 紫、或紫色元素发光/呼吸 = 不合格。
|
||
- **排版三件套**：时间格式违反 §3.1.2 规则、版本号/文件名未套 mono chip、承载信息文字对比度 < 4.5:1，任一 = 不合格。
|
||
- **形态语言**：KPI 色条未贯通整宽、侧边栏选中态出现独立指示条（或任何与圆角背景块两张皮的第二形态）、选中态不是 §3.0 的「左缘生长渐变 + 内描边」、导航图标粗细不一，任一 = 不合格。
|
||
- **动效**：呼吸点不同频同相位、透明度下限低于 40%、正常态绿点或紫色提示/待授权点呼吸，任一 = 不合格；主按钮 hover 未用 §2.6 双层扩散辉光 = 不合格。
|
||
- 其余沿用：正文与表单区零光效；低档模式下无循环动画、无辉光、无粒子且信息完整性不变。
|
||
|
||
---
|
||
|
||
**v1.2 为施工开工的唯一视觉依据。** v3 样图（`overview3.png`）与本规范条文冲突时，以本规范条文为准；规范未覆盖处，参照 v3 样图并按 §1 原则推演。
|