DESIGN.md@web git:20261020.4242e6cA

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

# Web 设计规范

## 设计目标

Agent Muster 的界面围绕用户完成任务组织：选择项目、创建或继续会话、查看执行结果、管理 Agent、配置消息平台。每个页面都应让用户清楚知道当前状态、下一步操作和操作结果。

设计以目标为导向。先明确用户要完成什么，再决定展示哪些信息、提供哪些操作，以及如何安排布局。简洁不是单纯减少元素，而是减少理解、选择和操作的成本。

## 页面与操作

- 一个页面或工作区域应有明确的主要任务，主操作在视觉上优先，次要操作保持克制。
- 高频操作直接可达，低频操作按需展开，避免让用户经过无意义的中间步骤。
- 操作入口靠近其作用对象，按钮使用明确的动作名称，例如“创建会话”“保存配置”，避免“确定”“处理”等含糊文案。
- 必要信息优先呈现，高级配置、原始日志和详细参数按需展开。
- 保持已有操作位置、名称和行为的一致性，不为了视觉变化打断用户习惯。
- 删除等有明确损失的操作需要说明影响；普通、可逆操作避免反复确认。

## 信息展示

- 同一上下文中的同一数据原则上只展示一次，避免在标题、卡片、标签和摘要中重复堆叠。
- 只有当不同区域承担不同任务，且重复信息有助于识别对象或避免误操作时，才保留必要重复。例如侧栏用于定位会话，内容区用于确认当前会话。
- 每条信息都应帮助用户判断状态、选择行动或理解结果；无法说明用途的内容应删除。
- 不为填满页面添加统计卡片、介绍段落、装饰性图表或重复摘要。允许留白，不以内容数量衡量页面完整度。
- 只展示真实数据和真实状态，不编造示例记录、进度、统计或成功提示来填充界面。
- 列表展示识别与选择所需的信息，详情展示处理任务所需的信息。避免在列表中展开所有细节。
- 长路径、长文本可适当截断，但完整内容必须可以查看或复制；关键错误和操作结果不能因截断而无法理解。

## 交互反馈

- 点击后及时反馈操作状态，耗时操作展示加载状态，提交期间防止重复提交。
- 成功反馈与操作规模匹配：界面变化已足够说明结果时，不额外叠加提示。
- 错误信息说明发生了什么以及用户可以如何处理，保留已输入内容，避免让用户重新开始。
- 表单只要求完成当前任务必需的字段，明确必填项，在相关字段附近说明格式或校验问题。
- 选中、悬停、禁用和执行中状态应清晰区分；仅在明确要求时添加聚焦样式。禁用原因应在相关位置可理解。
- 空状态说明当前没有什么，并在有可执行下一步时提供对应入口；不添加无关教程或宣传内容。
- 实时输出更新时尊重用户当前阅读位置，避免滚动、刷新或弹层打断正在进行的操作。

## 视觉与布局

- 延续现有界面的中性色、系统字体、轻边框和紧凑布局，优先复用已有组件与样式。
- 通过字号、字重、间距和位置建立层级，避免依赖大量颜色、阴影或装饰。
- 颜色服务于状态和操作识别，同一语义使用一致颜色；状态不能只靠颜色表达。
- 相同类型的按钮、表单、列表和弹层保持一致的尺寸、间距与交互方式。
- 对话顶部及面板工具栏的操作使用图标按钮，统一为 32 × 32 像素点击区域、16 × 16 像素图标；默认无边框、透明背景，悬停时使用浅色背景反馈，展开状态保持清晰可辨。
- 图标按钮必须通过 `aria-label` 提供准确的功能名称；悬停或键盘聚焦时立即显示同名功能说明，不依赖浏览器原生 `title` 的延迟提示。说明不得遮挡按钮或接收指针事件，并保留柔和、可见的键盘焦点提示。
- 内容区优先服务于会话阅读和操作，不让导航、说明或装饰占据过多空间。
- 单窗、双栏和四宫格布局都应保留清晰的当前操作对象，避免用户混淆会话和操作目标。
- 窄窗口下按任务优先级调整布局，保证主要操作可达、内容可读，避免控件挤压、遮挡和整页横向滚动。

## 可访问性与文案

- 主要流程支持键盘操作，弹层关闭后焦点回到合理位置。
- 不设置全局 `--focus-ring` 变量或统一焦点样式。输入类元素（如 `input`、`textarea`、`select` 和可编辑区域）默认不添加焦点轮廓、阴影、边框或背景变化，其外层容器也不因输入元素聚焦而增加样式；仅在具体需求明确要求时添加。
- 图标按钮等本规范明确要求焦点提示的控件，按对应要求单独设置柔和、可见的 `:focus-visible` 样式，颜色与所在区域协调，不统一指定色值；鼠标点击不额外增加焦点框，避免黑色、深灰色或浏览器默认的黑边焦点样式。
- 图标按钮提供可理解的名称；触屏操作不能依赖悬停才能发现入口。
- 保证文字与背景有足够对比度，点击区域易于操作。
- 文案简短、具体，使用用户熟悉的术语，同一对象与状态保持统一称呼。
- 仅在帮助用户决策或解决问题时展示技术细节，不把内部实现直接转化为界面说明。

## 设计检查

新增或修改界面前后，检查以下问题：

1. 用户在这里要完成什么，主要操作是否明确？
2. 是否存在可省略的步骤、选择或确认？
3. 每条信息是否帮助用户行动，是否重复展示同一数据？
4. 是否有仅用于填充页面的内容、组件或装饰？
5. 加载、成功、失败和空状态是否清楚，下一步是否可理解？
6. 键盘、触屏和不同窗口布局下，受影响流程是否仍然顺畅？
7. 是否保持已有正确行为，并将改动限制在当前任务范围内？