---
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/线上验收分别记录。
