# awem Web UI 设计规范

- **状态**：v1.4（2026-10-27 总览改左树右表：左侧归属导航树 + 右侧全列表格；去除页内 Tab 与平铺/树形切换；所属项目/小队合并为一列；新增版本列；页面名保持「总览」，图表留二期），随 web/ 实施迭代。
- **定位**：[design.md](design.md) §9 定义页面结构与功能；本规范定义**视觉与交互**。两者冲突时以 design.md 为准，并按"先改文档、再改代码"的流程修订。
- **适用**：`web/` 下 React SPA（`go:embed` 内嵌，仅 127.0.0.1 本机访问）。

---

## 1. 设计原则

1. **信息密度优先**：这是运维工具，不是营销页。一屏看清全部执行器的双状态（本地进程 + 平台）。
2. **克制的色彩**：中性灰为底，唯一强调色；彩色只表达状态与可操作项，不做装饰。
3. **操作直达**：start/stop/restart 行内完成；破坏性操作（remove、stop 全部）必须显式确认。
4. **状态即事实**：本地状态与平台状态**并列展示、不合并**，视觉上能区分来源（design.md 决策 #9）。
5. **轻量快速**：SPA 体积小、首屏快；动画少而短，且尊重 `prefers-reduced-motion`。

## 2. 设计令牌（Design Tokens）

落地为 CSS 自定义属性，命名 `--awem-*`；`:root` 为浅色，`[data-theme="dark"]` 覆盖为深色。**组件只引用变量，不写死色值。**

### 2.1 中性色与强调色

| 令牌 | 浅色 | 深色 | 用途 |
|---|---|---|---|
| `--awem-bg` | `#ffffff` | `#0f1113` | 页面背景 |
| `--awem-bg-subtle` | `#f6f7f9` | `#16191d` | 卡片/面板背景 |
| `--awem-bg-muted` | `#eef0f3` | `#1e2227` | hover、填充、表头 |
| `--awem-fg` | `#1a1d21` | `#e6e8eb` | 正文 |
| `--awem-fg-secondary` | `#5a6169` | `#9aa1a9` | 次要文字 |
| `--awem-fg-faint` | `#8b9199` | `#6b727a` | 占位/禁用 |
| `--awem-border` | `#e2e5e9` | `#2a2f36` | 边框、分隔线 |
| `--awem-accent` | `#2563eb` | `#3b82f6` | 主按钮、链接、焦点环 |
| `--awem-accent-hover` | `#1d4ed8` | `#60a5fa` | accent 悬停 |

### 2.2 状态色（语义固定，不得挪作装饰）

| 语义 | 令牌 | 浅色 | 深色 | 用在 |
|---|---|---|---|---|
| 成功 / ONLINE | `--awem-success` | `#16a34a` | `#22c55e` | 本地"运行中"、平台 ONLINE |
| 忙碌 / BUSY | `--awem-busy` | `#2563eb` | `#3b82f6` | 平台 BUSY（与 accent 同色系，靠文字区分） |
| 停止 / OFFLINE | `--awem-off` | `#8b9199` | `#6b727a` | 本地"已停止"、平台 OFFLINE |
| 警告 / 漂移 | `--awem-warn` | `#d97706` | `#f59e0b` | 配置漂移黄标、崩溃重连中 |
| 错误 / 危险 | `--awem-danger` | `#dc2626` | `#ef4444` | 失败状态、破坏性操作按钮 |

状态一律"**圆点（8px）+ 文字**"双编码，不只用颜色（可访问性）。

### 2.3 字体与排版

| 令牌 | 值 | 用途 |
|---|---|---|
| `--awem-font-sans` | `-apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif` | 全局 UI |
| `--awem-font-mono` | `ui-monospace, "SF Mono", "Cascadia Mono", "JetBrains Mono", Consolas, Menlo, monospace` | 启动命令、token、executor-id、日志 |

- 字号阶梯：**12**（辅助/徽标）· **13**（表格、日志）· **14**（正文/表单）· **16**（小节标题）· **20**（页面标题）。
- 行高：正文 1.5；等宽日志 1.45。
- 数字与 ID 用等宽；正文不混用等宽字体。

### 2.4 间距、圆角、阴影、动效

- **间距**：4px 基准网格，只用 4 / 8 / 12 / 16 / 24 / 32 六档。
- **圆角**：控件 6px；卡片/面板 8px；徽标 pill（全圆角）。
- **阴影**：卡片**不用阴影**（用 1px 边框）；阴影仅给浮层（下拉、Dialog、Toast）：`0 4px 16px rgba(0,0,0,.12)`。
- **动效**：150–200ms `ease-out`，仅 hover 过渡、浮层出现、Toast 滑入；日志流滚动无动画。

## 3. 布局

- 内容最大宽 1600px 居中，左右留白 24px；总览表格可占满该宽度
  （2026-10-27 由 1440px 调整：左树 280px + 间距 16px 后 1440px 放不下联动 11 列，
  表格出现横向滚动）。
- 总览为**左树右表**：左侧归属导航树（宽 280px）与右侧表格区同高——行容器 flex stretch
  拉高较矮一侧，且树卡片与表格卡片各自在容器内 `flex: 1` 撑满补齐（任一内容更高时，
  另一侧卡片背景同步到底边，不出现高度差）；两者各自按视口剩余高度限高、底边对齐；
  表格仅表体纵向滚动、表头吸顶；最小表体高 240px（视口过矮时允许页面滚动兜底）。
- 表格**默认不出现横向滚动条**：「名称」「所属小队」两列为可收缩列，宽度不足时
  溢出截断（`text-overflow: ellipsis`）并带 `title` 悬浮提示；仅极窄视口
  （表格可用宽 < 约 900px）才在容器内横向滚动兜底。
- 左树纵向超出时内部滚动；**横向永不出现滚动条**：节点名溢出截断（`text-overflow: ellipsis`）
  并带 `title` 悬浮提示；树节点悬浮/选中背景横向沾满整行（左右留卡片内边距 8px）。
- 详情页为**一屏左右分栏**（2026-10-27 起）：左列（弹性宽）从上到下 = 进程卡片 →
  运行时间带卡片 →（漂移明细卡，有条件的）→ 日志卡片（`flex:1` 填满左列剩余高度，
  日志框内部滚动）；右列编辑卡片固定宽 380px、表单单列排列，内容超高时卡片内部滚动。
  整页按视口剩余高度定高（JS 计算，下限 480px；视口过矮时允许页面滚动兜底）。
- 顶栏一行：左侧产品名 `awem`，右侧 daemon/平台连接状态点 + 设置入口。
- 页面骨架统一：**标题行（页面标题 + 主操作按钮）→ 内容区**。不加面包屑（页面仅一层）。
- 不做移动端适配，但宽度 ≤ 768px 时布局不得错乱（允许横向滚动表格）。

## 4. 组件规范

| 组件 | 规范 |
|---|---|
| 按钮 | primary（accent 填充）、secondary（描边）、danger（仅破坏性操作）、ghost（行内图标按钮）。高 32px（紧凑）/ 36px（表单） |
| 状态徽标 | 8px 圆点 + 13px 文字；漂移用 warn 色 pill 徽标（文案"漂移"），挂在执行器名称旁 |
| 表格 | 总览用表格不用卡片列表；行高 44px；表头 12px 次要色；行内操作按钮 hover 显现、焦点显现；总览列表表体视口自适应限高、表头 sticky 吸顶（见 §3） |
| 查询条件行 | 总览表格上方、工具行上方、滚动容器之外；名称（文本，去首尾空格、不区分大小写、匹配平台显示名或执行器标识任一）、本地进程（自定义 Select 下拉，含已知状态与数据中出现的未知状态）、重置；条件 AND、输入即筛选；筛选变化清空已选；无命中保留筛选行与表头并显示「没有匹配的执行器」「清除筛选」；≤768px 可换行。项目/小队归属过滤由左侧导航树承担，不进查询条件行 |
| 下拉选择（Select） | 自绘触发按钮 + 弹层，**不用原生 `<select>`**（弹框样式不可控）：触发按钮同输入框外观（36px/筛选行 32px、1px 边框、控件圆角），右侧 chevron；弹层为卡片（`--awem-bg` + 1px border + 控件圆角 + 浮层阴影 `--awem-shadow-float`），贴触发按钮下沿 4px、宽至少与按钮同宽；选项高 32px，hover/键盘高亮 muted 底，选中项 accent 色 + 左侧对勾；键盘 Enter/Space/↑/↓ 打开，打开后 ↑/↓ 移动高亮、Enter 选中、Esc/Tab/点击外部关闭（焦点不离开触发按钮） |
| 批量选择 | 表格首列为复选框（表头全选/半选、行选择），复选框带 aria-label 且可键盘操作；部分选中时表头呈 indeterminate，点击半选表头即全选 |
| 批量操作条 | 并入总览工具行左侧（2026-10-25 起，不再独立成行）：无选中时左侧显示「共 N 个执行器」提示，有选中时原位切换为批量操作条——「已选 N 项」+ 启动（secondary）、停止（secondary）、删除（danger）、取消选择（ghost）；工具行高锁定 32px（`min-height`），批量条出现/消失不得引起表格位移；批量执行期间整体与行内操作一并禁用 |
| 表单 | label 在输入框上方，间距 8px；敏感字段（MCP 令牌、执行器 token）默认掩码 + 眼睛切换 |
| Dialog | 仅用于破坏性确认与编辑；Esc 可关；确认按钮写具体动作（"停止全部执行器"），不写"确定" |
| Toast | 右下角，3s 自动消失；成功用中性色，失败用 danger；失败文案给出下一步 |
| 空状态 | 一句话说明 + 一个主按钮（如"添加第一个执行器"），居中，不堆插画 |
| 加载 | 局部骨架屏或 spinner；禁止整屏白屏等待 |
| 导航树（总览左侧） | 归属导航：全部执行器 → 项目 → 小队（含虚拟「未分配小队」）→ 「未归属」固定排最后；项目/小队按中文排序；节点高 36px，项目带 chevron 展开/收起（`aria-expanded`，默认全展开，折叠状态记忆在会话内）；节点含名称与右侧徽标 `在线数/成员数`（如 `3/4`，在线=平台 ONLINE 或 BUSY；未归属显示 `—/成员数`）；选中节点 muted 底 + 左 2px accent 边条（`aria-current`），悬浮/选中背景横向沾满整行；点击节点过滤右侧表格（多小队执行器按标识去重），切换节点清空已选；节点随轮询失效（项目/小队消失或无归属数据）时回退「全部执行器」；无归属数据时整树隐藏、表格占满 |
| 时间带（Timeline） | 单行状态区间条，高 20px，横轴时间；区间色仅用状态令牌：running=`--awem-success`、backoff=`--awem-warn`、stopped=`--awem-off`、无数据=透明底 + `--awem-border` 斜纹；崩溃为 danger 色 ✕ 标记叠在区间边界；hover/键盘聚焦出 tooltip（状态 + 起止时刻，等宽 12px，本地时区）；点击 ✕ 穿透定位日志；条下方 12px secondary 标注数据起点（如「数据自 2026-10-25 14:00 起，events.log 滚动范围」），无事件时显示「暂无事件数据」；定位失败时提示无法精确定位并加载最近可用历史页 |
| 图表（SVG 手绘） | 不引入图表库，SVG 手写；颜色只用 `--awem-*` 令牌；坐标轴与刻度文字 12px `--awem-fg-secondary`，网格线 `--awem-border`；禁渐变/阴影/3D；hover 数值 tooltip 用浮层阴影；尊重 `prefers-reduced-motion`（无进入动画） |
| 指标卡 | 面板底（`--awem-bg-subtle` + 1px border，无阴影）；数值 20px 等宽，标签 12px secondary；一排最多 4 个 |

## 5. 页面级要点（结构以 design.md §9 为准）

- **总览页**（默认首页，页面名保持「总览」）：标题行 = 页面标题「总览」+ 主操作「添加执行器」；
  无页内 Tab（2026-10-27 起去除，单状态左树右表，URL 不写 hash）。
  - 标题行下方为**左树右表**：左侧归属导航树（280px，规范见 §4「导航树」），右侧为筛选行 +
    工具行 + 表格。沿用原总览表格全部规范（双状态列、批量操作条、漂移黄标不变）；
    工具行常驻（列表非空即渲染），左侧「共 N 个执行器」提示 ⇄ 批量操作条原位切换；
    表体最大高度随视口自适应（仅表体纵向滚动、表头吸顶），筛选行与工具行位于滚动容器之外；
    表格上方为名称/本地进程两项查询条件（客户端 AND 筛选；无命中保留筛选行与表头并显示清除筛选）；
    树选择与查询条件 AND 叠加，树本身不被筛选裁剪（始终展示全量归属结构）。
  - **图表（二期）**：顶部一排指标卡（执行器总数 / 在线率 / 24h 崩溃 / 漂移数）；
    其下为可用率条形图（按项目/小队分组）与崩溃趋势柱状图、双状态分布环；
    右上角时间窗口切换（24h / 7d，segmented）；页面底部 12px secondary 文案标注数据起点
    （如「数据自 2026-10-25 14:00 起，events.log 滚动范围」）。
  - 平台未配置或全无归属数据时：左树隐藏，表格占满整行。
- **首次 token 输入**：居中窄卡片（360px），一个输入框 + 一个按钮，无其他元素。
- **总览列序**（2026-10-27 起）：选择 | 名称 | 所属小队 | 版本 | 本地进程 | 连接 | 平台 | 模型 | 自启 | 重启 | 操作。
  平台联动启用（任一行有平台数据）才渲染「所属小队」列，未联动整体隐藏；「所属小队」单元格双行：
  主行小队顿号拼接串（`squad_names` 兜底拼接），副行 12px 次要色显示所属项目（仿名称列双行）；
  单条缺归属显示 `—`。「版本」列为 `parsed.runtime_version`（等宽字体，title 提示 `autowonder@<版本>`），
  解析缺失显示 `—`；版本列不受联动开关影响，始终渲染。名称单元格双行：联动时主行显示平台侧执行器
  中文名（链接，title 提示所属数字工人），副行 12px 等宽显示标识名；未联动时单行等宽标识名。
  「名称」「所属小队」两列为可收缩列：可用宽不足时溢出截断（ellipsis）并带 `title` 提示，
  表格默认不出现横向滚动条（见 §3）。
- **总览批量操作**：选中行后工具行左侧原位切换为批量操作条（已选 N 项 / 启动 / 停止 / 删除 / 取消选择），批量动作
  串行调用单条 API；启动无确认，停止与删除须确认，删除确认标题与按钮写「删除 N 个执行器」；
  选择按执行器标识名跨 5s 轮询保持，消失的行自动移出、新行默认不选中；切换树节点或筛选变化清空已选。
  删除含运行中项时整批阻止并提示先停止；部分失败时成功项取消勾选、失败项保留勾选，
  Toast 汇总成功/失败数量与失败原因。
- **详情**：标题行 = 平台中文名（页面标题样式，数字工人不同名时括注）+ 右侧等宽标识名（hint 样式）；
  无平台数据时标题回退为等宽标识名；主体为**一屏左右分栏**（结构见 §3）：
  左列从上到下 = 进程卡片（本地/平台双状态、所属项目/小队、pid/uptime/重启、漂移 pill）→
  **运行时间带**卡片（默认 24h 窗口，随日志分页不变）→（有漂移时）漂移明细卡 →
  日志卡片（填满左列剩余高度，日志框内部滚动）；右列为**编辑**卡片（固定 380px，
  表单字段单列从上到下，卡片超高时内部滚动，保存按钮在卡片末尾）。
  时间带下方 12px secondary 标注数据起点，完全无事件时显示「暂无事件数据」；崩溃标记点击后，
  日志查看器定位到该时刻前最后一页历史日志并自动暂停跟随；事件缺少定位信息或对应文件已清理时，
  加载最近可用历史页并提示无法精确定位；
  **日志查看器无论明暗主题都用暗底**（`#0d1117`）、等宽 13px；渲染 ANSI 颜色；"跟随滚动"开关默认开，
  用户向上滚动后自动暂停跟随，回到底部恢复；历史日志向上翻页加载。日志容器隔离滚动链
  （`overscroll-behavior: contain`）：日志到顶/底继续滚轮不带动详情页，页面纵向滚动条不因日志滚动出现或闪现。
- **添加/导入**：粘贴区为大号等宽 textarea；解析预览中高亮 `token` / `executor-id` / `model`（accent 底纹）；保存前可逐字段修正。
- **设置**：分组表单（平台联动 / 日志 / 外观），外观组含主题切换（跟随系统 / 浅色 / 深色）。

## 6. 文案与可访问性

- v1 全中文，文案走语言包（design.md D5）；按钮以动词开头（"添加执行器"）。
- 错误文案 = 发生了什么 + 怎么办（例："daemon 未运行且自动拉起失败：…请执行 `awem service install`"）。
- 对比度满足 WCAG AA（正文 ≥ 4.5:1）；所有功能可键盘到达；焦点环为 2px accent outline，不得 `outline: none`。

## 7. 实现约定

1. 主题：默认跟随系统，设置页可手动覆盖，选择存 localStorage；切换不刷新页面。
2. 不强制组件库；若引入，必须可 tree-shake 且样式可覆盖到本规范。图标统一用线性图标集（如 lucide）。
3. **新增状态语义、新组件、新令牌时，先更新本规范，再写代码**（与仓库"先改文档"约定一致）。