DESIGN.md · git:20261111.6a9adf3 · 2026-11-11 · sha256 61e1a9c08641fa2b

DESIGN.md git:20261111.6a9adf3A

Immutable. This exact content never changes and is served at /api/v1/blob/61e1a9c08641fa2b.

---
name: doops-console-design
scope: web-console
owner: doops-maintainers
updated: 2026-11-11
---

# DoOps 控制台 UI 规范

面向运维人员和平台管理员,以选择目标、检查资源、执行任务和核对结果为主要路径。
沿用深色底和青绿色主色;主题值以 `app/globals.css` 为准。

## 布局与密度

- 控制台工作区铺满可用宽度,页面内容和工具栏使用 16px 内边距;不要再给控制台外层添加居中的最大宽度。
- 桌面顶栏的目标选择和功能入口相邻,账号操作靠右;概览双栏按内容自然高度排列,集群数量增加时不要拉长当前机器卡片。
- 公开首页、案例和部署文档使用现有 `max-w-6xl`。登录卡片、弹窗和 Markdown 阅读区可独立限宽。
- 页面内间距用 4px 倍数,工具栏控件间距 8px,卡片间距 12/16px,主要区域间距 24px。
- 页面标题 20/24px;区域标题 14/16px;正文 14px;辅助信息、工具栏和表格操作 12px。
- 工具栏可换行,表格在自身容器内横向滚动;禁止用页面裁切隐藏溢出。
- 640px 以下,顶栏导航独占一行;目标选择器的弹出列表不能被顶栏滚动容器裁切。

## 语义颜色和几何

| 用途 | 令牌 / 规则 |
| --- | --- |
| 页面、卡片、输入背景 | `background`、`card`、`muted`,不另写色值 |
| 主要操作、当前选择、焦点 | `primary`、`primary-foreground`、`ring` |
| 成功 | `success`、`success-bg`,同时显示文字或图标 |
| 运行中、忙碌、结果未知 | `warning`,不能当作错误 |
| 失败、拒绝、危险操作 | `destructive`、`destructive-foreground` |
| AI 组件错误和反馈背景 | `danger` 映射 `destructive`;反馈背景由主站令牌混合生成 |
| 控件圆角 | `radius-md`,随现有根圆角计算;卡片、弹窗使用 `rounded-xl` |
| 阴影 | 内容卡片以边框区分;浮层沿用现有阴影,不新增效果 |

共享 Agent UI 样式先加载,主站样式后加载。DoOps 的主题令牌是唯一配色来源。

## 共用控件

通用控件统一从 `components/ui.tsx` 导入 `Button`、`Input`、`Select`、`Textarea`、`SegmentedControl` 和 `PageTabs`。
控件样式位于 `app/globals.css` 的 components 层;页面仅补充布局和业务状态。
`Button` 用 `variant`、`size` 和 `icon` 表达外观;表单控件用 `scale` 表达尺寸。
分段选择以 `value`、`options`、`onChange` 控制;页面标签用 `items`、`value`、`onChange`,统一生成选中语义属性。

| 场景 | 使用方式 | 桌面尺寸 |
| --- | --- | --- |
| 表单或主要操作 | `btn` / `btn btn-primary` | 最小高 36px,14px 字体 |
| 工具栏、行内操作 | `btn btn-sm`,主要操作加 `btn-primary` | 最小高 32px,12px 字体 |
| 轻量操作 | `btn btn-ghost`,紧凑处加 `btn-sm` | 同对应尺寸 |
| 图标按钮 | `btn btn-icon`,紧凑处加 `btn-sm` | 36/32px 方形;必须有可访问名称 |
| 最终危险确认 | `btn btn-danger` | 不用于普通导航、停止观察或忙碌状态 |
| 输入框、下拉框 | `input`,工具栏用 `input input-sm` | 最小高 36/32px;编辑器保留自身高度 |
| 页面导航 | `page-tab` + `aria-current="page"` | 最小高 44px,当前页下划线 |
| 模式和范围选择 | `segmented` 容器、`segment-option` + `aria-pressed` | 选项最小高 30px |
| 错误、成功提示 | `status-error` / `status-success` | 同样的边框、内边距与正文尺寸 |

触摸设备上的按钮、模式选项和单行输入最小高 44px。列表、文件树、卡片入口保留各自的布局,不套用普通按钮尺寸。
不要通过复制长段 utility 类重新定义一套按钮或输入框。

## 状态与交互

- 主操作用实色,次操作用边框,辅助操作用 ghost;危险确认使用错误色并保留现有确认流程。
- 禁用状态降低到 50% 不透明度,显示禁止光标,并在逻辑上阻止操作;运行中需保留文字反馈。
- 所有共用控件都有可见键盘焦点。选择状态由语义属性与同一套样式共同驱动。
- 错误提示使用 `role="alert"`,说明失败和下一步;成功信息不能覆盖未完成或结果未知的操作。
- 减少动态效果的系统设置下,控件不播放颜色过渡。加载图标沿用现有语义与状态。
- AI 工具调用只在会话列表显示一份;独立交互回执保留在轨迹中,详见 `backend/docs/DOOPS_WEBUI.md`。

## 验收

修改控件后,使用浏览器验证登录校验、导航切换、目标选择、表单/弹窗及主要成功和失败状态。
核对 2048px 宽屏、1440px 桌面和 390px 窄屏;宽屏正文左右保持 16px 边距,触摸尺寸、焦点、选中、加载、禁用、空态、错误态均可辨认;
记录截图、console 和网络错误,运行 TypeScript、生产构建及 diff 检查。合成数据验收与真实 Gateway/线上验收分别记录。