goodbuddy/DESIGN.md

# GoodBuddy 统一界面设计系统

## 1. 目的与适用范围

本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、知识库、智能心跳、任务与活动记录，以及后续新增的一级页面。

设计系统解决两类问题：

1. 统一跨页面的视觉语言、信息层级和交互反馈。
2. 保留不同工作场景所需的布局差异，不强行把阅读、工作台、仪表盘和数据视图做成同一种页面。

所有新界面必须优先使用本文定义的语义令牌、页面壳层和共享组件。现有界面迁移时应保持功能与数据语义不变，不以视觉统一为理由隐藏范围、状态或风险。

## 2. 核心原则

### 2.1 一致的语义，不要求相同的布局

- 相同含义使用相同的颜色、间距、控件和文案结构。
- 不同任务使用明确命名的页面壳层，不再为单个页面随意设置宽度。
- 页签只用于同级页面导航，分段控件只用于当前视图内的单选切换，筛选控件只改变当前数据集合。

### 2.2 范围始终可见

知识、任务、自动化和活动记录可能属于全局或某个项目。当前范围必须在页面标题区或对象标题旁持续显示，不能只通过入口位置、默认筛选或颜色暗示。

### 2.3 主任务优先

- 每个页面只保留一个视觉上最突出的主操作。
- 页面标题、范围、说明、主操作和导航按固定层级排列。
- 次要设置、筛选和批量操作不得与主任务争夺注意力。

### 2.4 状态明确且可恢复

- 加载、空内容、无结果、失败、只读和权限不足是不同状态，必须分别呈现。
- 可撤销操作优先提供撤销，不可撤销操作必须在执行前说明影响范围。
- 不依赖颜色单独表达状态或风险。

### 2.5 默认支持浅色与深色主题

组件不得直接使用原始颜色值。主题差异只在令牌层定义，业务组件仅引用语义令牌。

## 3. 设计令牌

令牌以 CSS 自定义属性实现。`:root` 提供浅色值，`[data-theme="dark"]` 覆盖深色值。组件样式不得新增只服务于单个页面的颜色、阴影、圆角或间距常量。

### 3.1 颜色令牌

| 令牌 | 用途 |
| --- | --- |
| `--surface-canvas` | 应用和页面底色 |
| `--surface-raised` | 卡片、面板、输入框和弹窗 |
| `--surface-subtle` | 次级区域和控件底色 |
| `--surface-muted` | 进度轨道和更弱的分隔表面 |
| `--text-primary` | 标题与主要正文 |
| `--text-secondary` | 辅助正文 |
| `--text-muted` | 占位、时间和弱提示 |
| `--text-on-accent` | 强调色或危险色表面上的文字 |
| `--border-default` | 常规边框 |
| `--border-control` | 输入框、分段控件等必须清晰可辨的控件边界 |
| `--border-subtle` | 区块分隔线 |
| `--accent`、`--accent-hover` | 强调文字、图标和交互反馈 |
| `--accent-solid`、`--accent-solid-hover` | 主按钮等需要反白文字的强调背景 |
| `--accent-selected`、`--accent-subtle` | 选中边框、选中背景和信息强调 |
| `--success`、`--success-subtle` | 成功状态 |
| `--warning` | 警告状态 |
| `--danger`、`--danger-strong` | 危险文本和状态 |
| `--danger-solid` | 最终确认按钮等需要反白文字的危险背景 |
| `--danger-border`、`--danger-subtle` | 危险入口和失败状态背景 |

浅色与深色具体值只在 `styles.css` 的主题根节点维护。状态组件必须同时显示文字或图标，不能仅靠颜色区分。

### 3.2 间距令牌

采用 4 像素基准：

| 令牌 | 值 | 典型用途 |
| --- | --- | --- |
| `--space-0` | `0` | 显式取消间距 |
| `--space-1` | `4px` | 图标内部微调 |
| `--space-2` | `8px` | 紧凑控件、图标与文字 |
| `--space-3` | `12px` | 表单字段内部、紧凑列表 |
| `--space-4` | `16px` | 默认组件间距 |
| `--space-6` | `24px` | 区块间距、窄屏页面内边距 |

使用规则：

- 同一组件内部优先使用 `8px`、`12px`、`16px`。
- 同一区块内组件之间优先使用 `16px` 或 `24px`。
- 页面级区块之间优先使用 `32px` 或 `40px`。
- 不新增 `14px`、`18px`、`22px` 等非令牌间距。

### 3.3 字体令牌

界面字体使用系统无衬线字体栈，代码、标识符和原始日志使用等宽字体栈。

| 令牌 | 字号 / 行高 | 字重 | 用途 |
| --- | --- | --- | --- |
| `--font-caption` | `10px` | 时间、短标签和紧凑元数据 |
| `--font-body` | `12px` | 默认界面正文 |
| `--font-section-title` | `14px` | 卡片和区块标题 |
| `--font-page-title` | `24px` | 一级页面标题 |

连续阅读内容使用 `13px` 至 `14px`，持久辅助信息不得小于 `10px`。页面内不得通过同时放大字号、加粗和使用强调色制造多个同级主标题。

### 3.4 圆角、阴影与层级

| 令牌 | 值 | 用途 |
| --- | --- | --- |
| `--radius-control` | `8px` | 输入框、按钮、菜单项 |
| `--radius-card` | `12px` | 卡片和面板 |
| `--shadow-card` | 主题定义 | 卡片和选中分段控件 |
| `--shadow-dialog` | 主题定义 | 对话框和浮层 |

普通卡片通过表面色和边框区分，不默认添加阴影。阴影只表示真实的浮层关系。不允许页面自行创建高于 `--z-dialog` 的层级。

### 3.5 动效令牌

- `--motion-fast: 120ms`：悬停、按压、焦点反馈。
- `--motion-normal: 180ms`：菜单、折叠区域、轻量视图切换。
- `--motion-slow: 240ms`：对话框和抽屉。
- 默认缓动使用 `ease-out`，退出可使用 `ease-in`。
- 在 `prefers-reduced-motion: reduce` 下移除非必要位移和缩放，仅保留即时状态切换。

## 4. 页面壳层

所有一级页面使用 `PageShell`。壳层负责水平居中、最大宽度、响应式内边距、页面背景和滚动边界，业务页面不得再次设置独立的整体最大宽度。

| 变体 | 最大内容宽度 | 适用场景 | 页面映射 |
| --- | --- | --- | --- |
| `reading` | `820px` | 连续阅读、单列编辑、对话撰写 | 聊天正文与输入区 |
| `standard` | `960px` | 常规列表、设置、表单与任务管理 | 最近对话、任务 |
| `dashboard` | `1040px` | 指标、卡片网格、宽表格与审计数据 | 智能心跳、活动记录 |
| `master-detail` | 可用空间内流式铺开 | 左侧选择、右侧编辑或预览 | 知识库 |

共同规则：

- 宽度计算统一为 `min(100%, 变体最大宽度)`。
- 页面左右内边距在常规桌面窗口为 `32px`，中等窗口为 `24px`，窄窗口为 `16px`。
- 页面顶部和底部内边距默认为 `32px`。
- `master-detail` 的左栏建议为 `280px` 至 `360px`，右栏占剩余空间。分隔线和滚动容器属于壳层，不由内容卡片模拟。
- 聊天输入区可以粘附在 `reading` 壳层底部，但消息内容和输入区必须共享同一阅读宽度。
- 宽表格可在 `dashboard` 内容区内部横向滚动，不得撑宽整个应用窗口。

## 5. 信息层级

一级页面按以下顺序组织：

1. `PageHeader`
2. `PageTabs`，仅在存在同级子页面时出现
3. 页面级状态或重要提示
4. 筛选与批量操作工具栏
5. 主内容
6. 与主内容就近关联的分页或加载状态

一个页面只能有一个可见的一级标题。卡片标题不得重复页面标题。面包屑只在层级超过两级且返回关系无法通过侧栏或主从布局表达时使用。

### 5.1 PageHeader

`PageHeader` 统一接收以下内容：

- `title`：必填，简短名词或任务名称。
- `description`：可选，一行说明当前页面能做什么，不重复标题。
- `scope`：涉及范围的数据页面必填，使用 `ScopeBadge`。
- `primaryAction`：可选，页面唯一主操作。
- `secondaryActions`：可选，最多两个直接显示，其余进入更多菜单。
- `status`：可选，用于只读、同步中、连接异常等页面级状态。

布局规则：

- 标题和范围徽标在同一信息组中，范围不得放入更多菜单。
- 主操作位于标题区右侧，窄窗口下换行到标题下方并保持靠左。
- 不在内容卡片中再次渲染同名标题。
- 标题区默认不粘附。只有主内容长且页面级操作需要持续可用时才启用粘附。

## 6. 共享组件

### 6.1 PageTabs

用于同一一级页面内的同级内容面板，例如心跳的“成长概览”和“心跳计划”。

- 使用 `tablist`、`tab` 和 `tabpanel` 语义，当前项使用 `aria-selected="true"`。
- 一级页面之间的导航由应用主导航承担，不复用 `PageTabs`。
- 标签保持短名词，不显示句号，不用页签承载开关或过滤条件。
- 项目过多时优先重组信息架构，不把一级页签做成多行。

### 6.2 SegmentedControl

用于当前页面内互斥的视图或状态切换，例如“列表 / 网格”或少量单选状态。

- 选项数量为 2 至 4 个。
- 使用带 `aria-pressed` 的按钮组语义，支持方向键切换。
- 不能用于多选筛选、页面导航或执行即时命令。
- 控件宽度由内容决定，除移动窄屏外不默认等分整行。

### 6.3 筛选工具栏

筛选不创建第五种类似页签的视觉控件：

- 2 至 4 个互斥状态可使用 `SegmentedControl`。
- 多维条件使用统一尺寸的选择框、搜索框和复选菜单。
- 已生效条件以文字和值明确展示，并提供“清除筛选”。
- 无匹配结果使用“无结果”状态，不能显示为首次使用的空状态。
- 筛选条件改变数据范围时，结果数量或当前条件必须可见。

### 6.4 ScopeBadge

`ScopeBadge` 表达对象或页面数据的归属范围：

- 全局范围显示“全局”，并配合通用范围图标。
- 项目范围显示“项目：项目名称”，不得只显示项目名称。
- 未知或已失效范围显示“范围不可用”，并提供修复入口或只读说明。
- 徽标始终包含文字，不以颜色作为唯一差异。
- 可切换范围时，徽标作为范围选择器的触发器，并提供明确的展开状态和键盘操作。
- 不可切换范围时，徽标为只读状态，不显示下拉箭头。

创建新对象时必须在提交按钮附近再次显示目标范围。跨范围移动属于显式操作，需要说明原范围、目标范围和对关联数据的影响。

### 6.5 EmptyState

`EmptyState` 统一包含：

- 能说明状态的图标或简洁插图。
- 一句标题。
- 一至两句原因或下一步说明。
- 最多一个主操作和一个次操作。

必须区分：

| 状态 | 标题示例 | 操作原则 |
| --- | --- | --- |
| 首次为空 | “还没有知识条目” | 提供创建或导入 |
| 筛选无结果 | “没有符合条件的结果” | 提供清除筛选 |
| 搜索无结果 | “未找到相关内容” | 建议修改关键词 |
| 加载失败 | “内容加载失败” | 提供重试并保留错误上下文 |
| 无权限或只读 | “当前范围不可编辑” | 说明原因和可行路径 |

空状态不得使用孤立的短句或仅显示图标。加载中不得先闪现空状态。

### 6.6 危险操作

共享危险操作样式包含：

- `danger-ghost`：列表行、菜单和工具栏中的删除入口。
- `danger-solid`：确认对话框中的最终危险操作。
- `danger-zone`：设置页中集中展示的高影响操作区域。

普通页面不得用实心红色按钮与主操作并列。危险入口必须使用具体动词和对象，例如“删除知识条目”，避免只写“确定”。

### 6.7 数据表格与活动列表

- 表头、单元格、空值、状态和行操作使用统一对齐规则。
- 文本默认左对齐，数值右对齐，状态与短标签可居中。
- 时间显示使用一致格式，并在需要时通过工具提示提供完整时间和时区。
- 行操作默认放在行末。高频安全操作可直接显示，低频或危险操作进入更多菜单。
- 活动记录必须保留操作者、动作、对象、范围、结果和时间等审计语义，不用纯图标代替关键字段。
- 表格密度可以选择“默认”或“紧凑”，但同一页面不得混用。

## 7. 交互状态

所有可交互组件必须实现：

- 默认：文本、边框和背景层级清晰。
- 悬停：提供轻量背景或边框反馈，不改变布局。
- 按下：反馈比悬停更强，持续时间使用 `--motion-fast`。
- 键盘焦点：显示至少 `2px` 的高对比焦点环，不被容器裁切。
- 选中：同时使用背景、边框、图标或字重中的至少两种信号。
- 禁用：降低强调度，同时保留可读标签，并通过说明或工具提示解释原因。
- 加载：防止重复提交，保留原按钮宽度并显示进行中标签。
- 错误：就近显示可执行的错误说明，不只弹出短暂通知。

异步提交成功后更新内容并提供明确反馈。失败时保留用户输入和筛选上下文。

## 8. 范围与数据语义

### 8.1 页面范围

- 页面范围决定当前列表、搜索、创建和批量操作针对的数据集合。
- 页面标题区必须持续显示当前范围。
- 搜索框占位文案应反映范围，例如“搜索当前项目的知识”。
- 切换范围后清理不再有效的选择项，并明确提示数据集合已变化。

### 8.2 对象范围

- 详情页或主从布局的右侧面板显示所选对象自身的范围。
- 当页面范围与对象范围不一致时，必须显示解释，不得静默混合。
- 全局对象可被项目引用时，应分别表达“归属范围”和“当前引用关系”。

### 8.3 操作范围

批量操作、导入、删除、移动和自动化运行前，界面必须明确：

1. 将影响哪些对象。
2. 对象属于全局还是某个项目。
3. 操作是否可撤销。
4. 是否影响关联任务、知识引用或历史记录。

## 9. 破坏性操作政策

### 9.1 风险等级

| 等级 | 示例 | 要求 |
| --- | --- | --- |
| 低 | 移除可立即恢复的筛选、取消未保存草稿 | 通常无需确认，必要时提供撤销 |
| 中 | 删除单个可恢复对象、停止正在运行的任务 | 显式确认或操作后撤销，说明直接影响 |
| 高 | 永久删除、批量删除、清空历史、删除被引用对象 | 必须使用确认对话框，说明范围、数量和不可逆性 |

### 9.2 确认对话框

- 标题包含具体动作和对象，例如“永久删除 12 条活动记录？”
- 正文说明范围、关联影响和恢复可能性。
- 取消按钮在前，危险按钮在后。初始焦点放在取消按钮。
- 最终按钮使用 `danger-solid`，标签重复具体动作。
- 仅对高影响且不可恢复的操作要求输入对象名称或确认短语，避免把摩擦用于所有删除。
- 提交期间锁定重复操作。失败后保持对话框打开并显示可处理的错误信息。

### 9.3 撤销与反馈

- 可恢复删除优先在操作后显示带“撤销”的持久通知。
- 撤销窗口结束前，不把操作描述为“永久删除”。
- 删除成功后更新列表、选中项和计数。主从布局中被删除对象的详情面板应回到明确的未选择状态。
- 审计记录不得因普通对象删除而被静默移除。

## 10. 深色主题

- 深色主题通过语义令牌替换实现，不在组件中使用主题条件分支选择原始颜色。
- 表面层级主要依靠亮度和边框区分，避免大面积纯黑与高亮白形成刺眼对比。
- 输入框、代码块、表格悬停、选中行、弹窗遮罩和滚动条必须分别检查深色值。
- 图片、图表和状态色在深色背景下保持可读。图表系列不能只靠色相区分，还应使用形状、线型或标签。
- 焦点环、危险文本和弱文本在两种主题下都满足对比度要求。
- 原生控件和滚动条声明正确的 `color-scheme`。
- 主题切换不得导致布局、边框宽度或字号变化。

## 11. 无障碍

### 11.1 键盘与焦点

- 所有交互均可通过键盘完成。
- 焦点顺序与视觉顺序一致，打开弹窗后焦点进入弹窗，关闭后返回触发元素。
- 页面导航链接按正常 Tab 顺序操作。同页签组和单选组使用方向键，菜单使用上下方向键和 Escape。
- 不给不可交互容器添加焦点，不用 `div` 模拟按钮而缺少按钮语义。

### 11.2 语义与标签

- 图标按钮必须有可访问名称，并在视觉上提供工具提示。
- 表单控件有持久标签，不能只使用占位文案。
- 状态变化使用适当的实时区域，但避免对频繁日志逐条播报。
- 错误信息与对应字段建立程序化关联。
- 表格使用正确的表头关系，复杂审计记录在窄屏下仍保持字段标签。

### 11.3 对比度与触控目标

- 正文与背景对比度至少为 `4.5:1`，大号文本至少为 `3:1`。
- 控件边界、焦点和关键图形对比度至少为 `3:1`。
- 常规交互目标建议至少 `32px × 32px`。紧凑表格可使用 `28px` 高度，但相邻目标之间必须有足够间隔。
- 文字缩放至 `200%` 时，核心操作、范围信息和错误提示不能被裁切。

## 12. 响应式与窗口规则

GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证任务连续性，不简单隐藏信息。

### 12.1 宽窗口，`1200px` 及以上

- 使用各 `PageShell` 的完整最大宽度。
- `dashboard` 可使用 3 至 4 列卡片。
- `master-detail` 保持双栏，详情区获得主要空间。

### 12.2 中等窗口，`960px` 至 `1199px`

- 页面左右内边距为 `24px`。
- 仪表盘降为 2 列。
- 主从布局缩小左栏，但不得低于 `280px`。
- 表格优先收起低优先级列到详情或行展开区，不隐藏范围、状态和时间。

### 12.3 窄窗口，`720px` 至 `959px`

- `PageHeader` 的操作区换行。
- `master-detail` 变为单面板导航。进入详情后提供明确返回列表的按钮。
- 仪表盘使用单列或 2 列，取决于卡片最小宽度。
- `PageTabs` 可单行横向滚动，不换成下拉菜单。
- 宽表格在自身容器内横向滚动，并固定关键标识列时确保键盘可达。

### 12.4 极窄窗口，小于 `720px`

- 页面左右内边距为 `16px`。
- 标题、范围徽标和操作纵向排列，但范围不得隐藏。
- 主操作可以占满可用宽度，次操作进入更多菜单。
- 分段控件可等分整行，筛选工具栏改为可展开区域。
- 聊天输入区保持可见，并考虑窗口安全边距。
- 对话框使用接近全宽的布局，仍保留 `16px` 外边距。

## 13. 页面应用规范

### 13.1 聊天

- 使用 `reading` 壳层，消息流与输入区共享宽度。
- 对话标题和当前项目范围位于 `PageHeader` 或对话上下文区，不在消息流中重复。
- 模式、模型或工具权限属于上下文控制，不与页面导航页签混用。
- 空对话展示可执行的起始建议，发送失败保留输入并提供重试。

### 13.2 最近对话

- 使用 `standard` 壳层和统一 `PageHeader`。
- 搜索、范围和时间筛选位于筛选工具栏。
- 行项目统一显示标题、范围、最近更新时间和必要状态。
- 删除入口使用 `danger-ghost`，并按数据可恢复性执行确认或撤销策略。

### 13.3 知识库

- 使用 `master-detail` 壳层。
- 左侧负责范围、搜索、筛选和条目选择，右侧负责详情、编辑和预览。
- 两侧均只使用语义颜色令牌，禁止内联浅色背景或边框。
- 选中条目后持续显示对象范围。没有选中项与知识库为空必须使用不同状态。
- 窄窗口切换为单面板导航，不把双栏压缩到不可读。

### 13.4 智能心跳

- 使用 `dashboard` 壳层。
- 顶部先呈现运行状态、当前范围和主操作，再呈现指标和配置。
- 状态卡片使用统一状态令牌，不只依赖颜色。
- 运行历史与配置使用明确区块，不以多套相似页签混合导航、开关和筛选。

### 13.5 任务与活动

- 任务使用 `standard` 壳层，活动记录使用 `dashboard` 壳层。
- “任务 / 活动”作为同级页面时使用 `PageTabs`。
- 任务状态筛选使用 `SegmentedControl` 或筛选工具栏，不再模拟页签。
- 活动记录保留审计字段和范围，支持独立容器横向滚动。
- 批量停止、删除和清空历史遵循破坏性操作政策。

## 14. 文案规则

- 使用简体中文，动词直接、对象明确。
- 页面标题使用名词，例如“知识库”“智能心跳”“活动记录”。
- 按钮使用“动词 + 对象”，例如“新建任务”“导入知识”“停止运行”。
- 状态文案描述事实，例如“正在同步”“上次运行失败”，不使用含糊的“异常”。
- 错误提示包含发生了什么、用户可以做什么。保留必要的错误上下文，但不得暴露凭据、授权头、私人文档或未脱敏的提供商响应。
- 同一概念固定使用一个名称，不交替使用“项目空间”“工作区”“范围”等近义词。产品内统一使用“范围”表达全局与项目归属。

## 15. 迁移检查清单

### 15.1 基础层

- [ ] 建立浅色与深色语义颜色令牌，移除业务组件中的原始颜色值。
- [ ] 建立间距、字体、圆角、阴影、层级和动效令牌。
- [ ] 为主题切换、减少动态效果和原生控件设置全局规则。
- [ ] 建立组件交互状态和焦点环基线。

### 15.2 页面壳层与层级

- [ ] 实现 `PageShell` 的 `reading`、`standard`、`dashboard`、`master-detail` 变体。
- [ ] 按页面映射替换 `820px`、`900px`、`1040px` 和全宽等分散宽度声明。
- [ ] 每个一级页面只保留一个 `PageHeader` 和一个一级标题。
- [ ] 移除内容卡片中与页面标题重复的标题。

### 15.3 共享组件

- [ ] 实现并迁移 `PageHeader`。
- [ ] 使用 `PageTabs` 统一同级页面导航。
- [ ] 使用 `SegmentedControl` 统一少量互斥视图和状态切换。
- [ ] 建立统一筛选工具栏，移除以页签样式伪装的筛选。
- [ ] 实现 `ScopeBadge` 并覆盖全局、项目、失效和可切换状态。
- [ ] 实现 `EmptyState` 的首次为空、无结果、失败和只读变体。
- [ ] 实现 `danger-ghost`、`danger-solid` 和 `danger-zone`。

### 15.4 页面迁移

- [ ] 聊天迁移到 `reading`，统一消息流与输入区宽度。
- [ ] 最近对话迁移到 `standard`，统一搜索、范围、时间和删除行为。
- [ ] 知识库迁移到 `master-detail`，清除内联浅色样式并补齐窄窗口单面板流程。
- [ ] 智能心跳迁移到 `dashboard`，统一状态卡片、配置和运行历史层级。
- [ ] 任务迁移到 `standard`，活动记录迁移到 `dashboard`，统一导航、筛选和表格行为。

### 15.5 验收

- [ ] 在浅色与深色主题下检查所有页面、弹窗、菜单、输入框、表格和空状态。
- [ ] 在大于等于 `1200px`、`960px`、`720px` 和小于 `720px` 的窗口宽度检查布局。
- [ ] 仅使用键盘完成导航、筛选、创建、编辑、确认和取消。
- [ ] 验证焦点恢复、可访问名称、表单错误关联和实时状态播报。
- [ ] 验证页面范围、对象范围和操作范围在关键流程中始终可见。
- [ ] 验证删除、批量操作、停止运行和清空历史符合风险等级策略。
- [ ] 验证加载中、首次为空、筛选无结果、搜索无结果、失败和只读状态不会互相混用。

## 16. 完成标准

一个页面只有在满足以下条件时才视为完成迁移：

1. 使用明确的 `PageShell` 变体，没有页面专属整体宽度。
2. 使用统一标题层级、共享导航和筛选控件。
3. 所有颜色、间距、字体、圆角和阴影来自令牌。
4. 全局或项目范围在浏览、创建、编辑和危险操作中均可见。
5. 浅色、深色、键盘和各窗口宽度下均可完成核心任务。
6. 空状态、错误状态和危险操作符合本文规则。