# Circle 设计规范

Circle 工作台（桌面应用）与 circle-hub 控制台（浏览器）共用的设计规范。主题叫“石墨”，追求沉稳的仪器感：深色优先，同时提供浅色；界面靠中性灰分层，颜色只出现在需要注意的地方；数字和编号用等宽字体，文字用大家熟悉的说法。

两个产品的配色、字体、间距、组件和交互都按这里实现；与本规范冲突的旧样式一律改掉。

## 适用范围

| 产品 | 界面 | 实现位置 |
| --- | --- | --- |
| Circle 工作台 | 桌面应用里的会话、抽屉、设置与各页面 | Circle 仓库 `apps/workbench`、`apps/desktop`；颜色只来自 `src/ink/theme.ts` 的一张调色板 |
| circle-hub 控制台 | 浏览器里的知识库、工作流、任务、连接、记录、团队与设置 | circle-hub 仓库 `hub/server/console` |

Circle 的终端界面跟随用户终端自身的配色，只沿用标志色环，不在本规范内。

## 原则

1. **层次靠灰度，不靠边框。** 三级底色区分导航、主区和详情：`surface-0`、`surface-1`、`surface-2`。卡片套卡片、框套框是改版要去掉的头号问题。
2. **颜色有含义才出现。** 品牌色只用在标志和少数标识上，状态色只表示状态，其余一律中性灰。一个画面里的彩色元素越少，状态越醒目。
3. **先讲结论，再给来源。** 列表先给陈述和状态；来源、引文、版本记录放在详情里，需要时再看。
4. **文字说人话。** 用主流软件的通用说法，不出现系统内部概念、哈希、引用编号和版本号（见“文字”一节）。
5. **同一类东西长得一样、用起来一样。** 两个产品里，同一类元素只有一种外观和一套交互；新页面只组合本规范里的元素，不另造样式。

## 品牌

- **两个标志，同一组颜色。** Circle 的标志是色环：蓝 → 紫 → 红 → 橙，再回到蓝。circle-hub 的标志是“轨道”（所有者决定 82）：中心一点代表 Hub，外圈轨道上四颗卫星代表它服务的各个 Circle，卫星依次是蓝、紫、红、橙。两个文件都在“资源 › Logos”。
- **左上角**：工作台是色环加小写字标“circle”，后面是小号的“工作台”；控制台是轨道标志加小写字标“circle-hub”。
- **品牌色** `brand-blue`、`brand-violet`、`brand-red`、`brand-orange` 就是这四色，只作图形，不作文字颜色。
- 色环只出现在两处：Circle 的标志，以及 Circle 工作时输入区的外框（缓慢转动）。除此之外界面不用渐变。

## 主题

- 两套主题：`dark`（深色，石墨，默认）和 `light`（浅色）。所有颜色都定义在 `tokens.json` 中，按主题取值；组件只引用设定名，例如 `var(--surface-1)`，不写死颜色。
- 默认跟随系统；两个产品都提供“跟随系统 / 浅色 / 深色”三档切换。
- 两套主题的层级关系一致：深色主题越往上越亮；浅色主题的主区是纯白，导航与详情略灰。

## 颜色

**底色分层**（由下到上）：

| 设定 | 用在 |
| --- | --- |
| `surface-0` | 页面最底层和左侧导航 |
| `surface-1` | 主区：会话、列表、表格 |
| `surface-2` | 右侧详情与抽屉；主区里的用户消息、工具调用、计划等块 |
| `surface-3` | 浮层：对话框、菜单、提示，配合阴影 |
| `surface-sunken` | 输入框、Circle 的输入区、分段选择的底槽 |
| `surface-hover` / `surface-pressed` | 悬停、按下或已选中时叠加的一层 |

**线**：`line-hairline` 只用于装饰性的分隔线（分栏边、行间、来源块外框）；可交互控件的边框一律用 `line-control`，它与底色的对比不低于 3:1。

**文字**分三级：`text-primary` 是正文；`text-secondary` 是次要文字；`text-tertiary` 用于说明行、时间、数量和表头，在所有底色上都不低于 4.5:1。不要再往下用更浅的灰。

**四个颜色在两个产品里的角色**：

| 颜色 | 设定 | Circle 工作台 | circle-hub 控制台 |
| --- | --- | --- | --- |
| 蓝 | `area-knowledge` | 当前选择、强调 | 知识库 |
| 紫 | `area-workflow` | 计划模式：输入区外框、模式文字、计划的当前步骤 | 工作流 |
| 橙 | `area-task` | 等待回应的提醒：输入区外框、提示条 | 任务 |
| 红 | `area-alert` | 失败、删除 | 告警，只用于需要处理的问题 |
| 中性灰 | `area-neutral` | — | 总览、连接、记录、团队、设置的导航圆点 |

深色主题下这四个设定直接取品牌色；浅色主题下加深到可以作文字（不低于 4.5:1）。控制台页面的根元素加 `area-knowledge`、`area-workflow` 或 `area-task` 类，组件通过 `--area` 自动取对应颜色。这些颜色不铺大面积底色，不用作按钮底色。

**状态色**只表示状态，每种都有“点、文字、底色”三件：

| 状态 | 设定 | 例子 |
| --- | --- | --- |
| 通过 | `status-pass*` | 已验证、已通过、已合并、已发布 |
| 失败 | `status-fail*` | 未通过、已拒收、已撤回、失败 |
| 注意 | `status-warn*` | 被取代、即将超额、等待回应 |
| 进行中 | `status-info*` | 运行中、等待判定中 |
| 待定 | `status-muted`（空心点） | 待验证、未检查、未知 |

通过和失败之间除了颜色，还靠文字区分，不能只靠红绿。

**图表色** `chart-1` 到 `chart-4`（蓝、琥珀、青、紫）是品牌色在图表里的版本：色相相近，亮度按深色、浅色底分别调过。四色按固定顺序使用，相邻两色在色盲模拟下仍能区分，与底色的对比都不低于 3:1。状态色不当作系列色用。

## 字体与排版

- **正文**用系统字体：macOS 上是苹方与 SF Pro，Windows 上是微软雅黑与 Segoe UI（`type.families.sans`）。中文由 `Circle CJK` 绘制：取系统自带的中文字体，缩到 92%，让中文与英文、数字在同一字号下看起来一样大。两个产品都不加载网络字体，也从不合成粗体。
- **表格里的数字列、计数、时间、快捷键、坐标轴刻度和代码**用系统等宽字体（`type.families.mono`），让同一列数字上下对齐。大号统计数字用正文字体半粗（`stat-value`），不用等宽。
- **字号阶梯**：统计数字 24，页面标题 22，详情标题 18，分区标题 15，正文 14，次要正文 13，说明 12，等宽小字 11（单位均为像素，详见“字体”一页）。一个画面里最多同时出现四档。
- Circle 工作台提供四档界面字号（小 13、默认 14、大 15、更大 17，代码各小一档），整套阶梯随之平移；控制台固定为默认档。
- 字重只用 400、500、600 三档，不用 700 以上的粗体。
- 行宽控制在 45–65 个汉字以内；标题避免孤字成行（`text-wrap: balance`）。
- 中文与英文、数字之间留一个空格，例如“近 30 天”“Circle 正在使用终端 2”；数字与单位之间也留一个空格，例如“1.2 GB”“3 次”。
- 层级路径用“ › ”连接，不显示斜线，例如“接口规范 › 认证”。

## 间距、圆角、细线与阴影

- **间距**以 4 为单位：4、8、12、16、20、24、32、40。同一组元素之间用 8，区块内段落之间用 16，详情的分区之间用 20–24。
- **圆角**：输入框、按钮、列表行和工具调用用 8；来源块、表格外框、提示、用户消息、计划和输入区用 10；对话框用 14；状态标签和筛选标签用胶囊形。Circle 工作台现有的 7px 统一改为 8px。
- **阴影**只给浮层：`shadow-popover` 用于菜单、提示和消息，`shadow-dialog` 用于对话框。页面内的面板和块都不用阴影。

## 图标

两个产品都用 Lucide 线性图标（工作台已在使用；控制台内联同一套图标的 SVG），常用尺寸 14 与 16，颜色跟随文字（`currentColor`）。只有确实帮助识别时才放图标；不用表情符号，不用彩色插画。只有图标的按钮必须有 `aria-label`，同时配悬停提示。

## 动效

| 时长 | 用在 |
| --- | --- |
| `--dur-fast` 120ms | 悬停、按下、选中的颜色变化 |
| `--dur-base` 180ms | 对话框、提示出现，筛选结果切换，输入区外框变色 |
| `--dur-slow` 240ms | 面板滑入（窄屏下的详情、抽屉） |

- 出现用 `--ease-enter`：位移不超过 6px，缩放不超过 1.5%；消失用 `--ease-exit`，时长取出现的三分之二。
- 只给状态变化加动效；数字不做滚动计数，图表不做逐条生长动画。
- 唯一的装饰性动效是 Circle 工作时输入区外框的色环，3.6 秒转一圈。
- 系统开启“减少动态效果”时，动效全部关闭，色环静止，只保留颜色变化。

## 页面结构

**两个产品用同一个三栏框架**（见组件 AppShell、WorkbenchShell）：

| 栏 | 宽度 | 底色 | Circle 工作台 | circle-hub 控制台 |
| --- | --- | --- | --- | --- |
| 导航 | `nav-width` 232px | `surface-0` | 标志、工作区、新会话、会话列表、平台与 Circle 各页面入口 | 标志、搜索、八个区域；当前区域展开出范围与文件夹 |
| 主区 | 自适应 | `surface-1` | 会话：标题、消息、工具调用、计划、请求、输入区、状态行 | 页头、工具栏、列表或表格 |
| 详情 | `inspector-width` 380px | `surface-2` | 抽屉：文件、改动、任务、网页等标签页 | 选中对象的信息、来源、分享、使用情况与操作 |

- 屏宽小于 1180px 时，详情或抽屉不再常驻：控制台点行进入详情页，工作台把抽屉收起为按钮。
- 屏宽小于 760px 时，导航收为页首一行（控制台）或收起为按钮（工作台）。
- 详情栏没有选中对象时显示该区域的概况，不留空白。

**Circle 工作台的会话**（见组件 WorkbenchShell、Composer）：

- 用户消息是靠右的 `surface-2` 圆角块；Circle 的回复直接排在底色上，不加框。
- 思考用次要文字，前面标“思考”；工具调用是 `surface-2` 的单行，写动作、对象和用时；计划是 `surface-2` 的块，当前步骤用紫色圆点；等待处理的请求是一条细线框的提示条。
- 输入区：凹下的底色加控件线；默认、计划模式（紫色外框）、工作中（色环外框转动）、等待回应（橙色外框）四种状态。
- 输入区下方是等宽小字的状态行（用量、上下文），再下方是后台任务列表。

**circle-hub 控制台的页头**：位置（面包屑）在最上，然后是标题与事实行，操作按钮放在标题右侧，主操作在最右，最多一个主按钮。

## 元素分类

| 类别 | 组件 | 用在 |
| --- | --- | --- |
| 框架 | AppShell、WorkbenchShell、Sidebar、PageHeader、Inspector | 每个页面的骨架 |
| 操作 | Button | 提交、确认、打开对话框 |
| 输入 | Input（含搜索、文本框）、FilterChip（筛选标签、分段选择）、Composer | 搜索、筛选、表单、与 Circle 对话 |
| 数据 | ListRow、Table、Badge（状态标签、计数、类型标签）、SourceBlock、Stat、Chart | 列表、表格、状态、来源与引文、统计 |
| 浮层 | Dialog、Tooltip | 需要确认或填写的操作、补充说明 |
| 反馈 | Toast、EmptyState | 操作结果、没有内容时 |

## 同类元素的交互规则

- **选择**：列表和表格一次只选中一行。点行即选中，同时右侧详情更新，网址里记住选中对象，刷新和分享链接都能回到同一状态。选中行用区域色淡底加细描边。
- **多选**：只有能批量操作的列表才有勾选框；勾选后在列表顶部出现批量操作条，写明“已选 3 条”和可做的操作；不能操作的行，勾选框置灰并在悬停提示里说明原因。
- **悬停**：行、导航项和按钮悬停时叠加 `surface-hover`；补充说明放在悬停提示里，不常驻在页面上。
- **悬停、选中和按下时的文字与边框**：叠加 `surface-hover` 或 `surface-pressed` 后，`text-tertiary` 在部分底色上会低于 4.5:1，`line-control` 会低于 3:1。所以悬停或选中的行里，说明文字改用 `text-secondary`；按下或选中的控件，边框改用 `focus-ring`。
- **键盘**：所有可交互元素都能用 Tab 到达，焦点环统一为 2px `focus-ring`。列表里用 ↑↓ 移动选中，Enter 打开，Esc 关闭对话框或退出详情；全局用 ⌘K / Ctrl K 打开搜索。
- **加载**：按钮提交时显示转圈并禁止重复提交；列表加载时保留原有布局，用占位行，不整页闪白；超过 10 秒的操作给出“等待××中”的状态。
- **空状态**：说清楚这里会出现什么，以及怎样得到第一条内容，附一个主操作；不写“暂无数据”。
- **出错**：写明出了什么问题、怎样处理，不道歉，不显示错误码以外的内部信息。表单错误写在对应字段下方。
- **确认**：会影响他人或无法撤销的操作（分享到团队、撤回、停用、收回分享、删除）先进入确认或预检，写明后果，确认按钮的文字就是动作本身，例如“确认分享到团队”。可撤销的操作不弹确认，完成后用消息提示，并在提示里提供“撤销”。
- **结果**：操作成功用消息提示，3 秒后消失；失败的提示不自动消失，并写明处理办法。

## 表格、列表与图表

- **列表还是表格**：以阅读为主、每行信息少于四项时用列表（ListRow）；需要按列比较、排序或扫数字时用表格（Table）。同一个页面只选一种。
- **表格**：文字列左对齐，数字列右对齐并用等宽数字；表头用 `label` 样式；可排序的列在表头标出方向；时间列不折行；宽表格在自身区域内横向滚动，页面本身不横向滚动。
- **数字**：千位加分隔符（48,000）；大小用 KB、MB、GB，保留一位小数；时间按“今天 10:24 / 昨天 / 10-30 / 2025-12-01”逐级简化，悬停时显示完整时间。

**图表**

- **先判断要不要画图。** 只有一个数时用统计数字（Stat），不画图；比较数量用柱状图，看趋势用折线图，一个整体的组成用细的分段条。不用饼图、环形图和双纵轴。
- **颜色按用途取。**
  - 单系列：用本页区域对应的图表色（`--area-chart`：知识库 `chart-1`、任务 `chart-2`、工作流 `chart-4`），不画图例，由标题说明画的是什么；
  - 多系列：按固定顺序取 `chart-1` 到 `chart-4`，筛选后剩下的系列不换色；超过四个系列合并为“其他”或改用表格；
  - 表示通过、未通过的系列用状态色并配文字；同一张图里状态色和系列色不混用。
- **标记**：柱宽不超过 24px，顶端 4px 圆角、底端贴着基线；相邻的柱之间留 2px 底色间隙；折线 2px、圆头；端点圆点直径 8px，外圈 2px 底色描边；面积只用 10% 的淡色。
- **坐标**：网格只画横线，1px 实线，用 `chart-grid`；刻度取整（0、10、20），用 `chart-axis` 等宽小字。
- **标注**：两个及以上系列一定有图例（柱用小方块，线用短横线），四个以内再在线尾直接标名称；只标关键的数（最新值、最大值），不在每个点上标数字；文字一律用文字色，不用系列色。
- **悬停**：图表默认可悬停。折线图用竖向参考线对齐最近的日期，提示里列出该日期所有系列的值；柱状图的每根柱子都是悬停目标，范围比柱子本身宽。提示里数值在前、名称在后；键盘聚焦时显示同样的提示。
- **表格视图**：每张图下方都有“以表格查看”，展开后是同一份数据的表格；悬停提示里的值在表格里都能找到。
- **筛选**：时间范围（近 7 / 14 / 30 天）放在页头下方的一行里，同时作用于本页所有图表、统计数字和表格；重新加载时图表保留原图并变淡，不闪白、不出现骨架屏。
- **统计数字**：用正文字体（`stat-value`），可配一条迷你柱状图，当前时段用区域图表色，其余用 `chart-grid`；写清统计的时段，例如“近 30 天被引用”。

## 文字

两个产品的中文界面用同一套写法；Circle 终端里的英文不在此列，只有“知识与同步的说法”一表同时列出终端的用词。

- 用主流软件的说法；不用系统内部的概念、代号、哈希、引用编号和版本号。
- 不用“你、他”作主语，状态写成事实，例如“已分享给李四、王五”“3 个请求等待处理”。
- 等待别人或外部条件的状态写成“等待××中”，例如“等待判定中”“等待回应中”“等待运行时重启中”；产品自己正在执行的动作写成“正在××”，例如“正在读取 1 个文件”“正在运行 2 条命令”。
- 说明性的文字放在悬停提示里；页面只常驻事实：数量、时间、状态。
- 按钮写动作：“新建”“新会话”“分享…”“分享到团队…”。带省略号表示会打开对话框，不带的直接执行。

**用词对照**（左边的写法不再出现在界面上）：

| 不用 | 改用 |
| --- | --- |
| 共享给我的 | 与我共享 |
| 个人（作为范围） | 我的 |
| 出处、依据 | 来源 |
| 可见范围、授权 | 分享、已分享给…、仅自己可见、全员可见 |
| 提交共享 | 分享到团队 |
| 添加条目 | 新建 |
| 已核验 / 未核验 | 已验证 / 待验证 |
| 历史、修订引文 | 版本记录、更新了来源 |
| 目录 | 文件夹 |
| 种类 | 类型 |
| 继承自上级 | 同文件夹设置 |
| {n} 个请求等待你处理 | {n} 个请求等待处理 |
| Circle 已把它交给你 | 等待回应中 |
| `src:9f2c…`、`tree:7a1b…`、v3 | 错误码对照表.xlsx · 第 12–14 行、打开原文、查看 |

**知识与同步的说法**（控制台、工作台和 Circle 终端共用；终端一列是英文小写）：

| 概念 | 控制台、工作台 | 终端 | 不用 |
| --- | --- | --- | --- |
| 对端 | 同步服务器；有名字时显示连接名，例如“团队服务器” | `sync server`，有名字时显示连接名 | Hub（Circle 里） |
| 模式 | 同步到服务器 / 仅保存在本机 | `synced` / `local only` | 同步到 Hub |
| 范围 | 我的 / 团队 / 与我共享 | `mine` / `team` / `shared` | 个人、共享给我的 |
| 状态 | 已验证 / 待验证 / 有冲突 / 已停用 / 已撤回 / 被取代 | `verified` / `unverified` / `conflict` / `disabled` / `withdrawn` / `superseded` | 已核验、失效 |
| 谁改的 | 张三 · Cursor · 11-03 14:20 更新；客户端没报名字时写“客户端” | `zhang · cursor · 11-03 14:20` | 提交人 usr_…、会话号 |
| 会话载入 | 本会话已加载 / 部分加载 / 未加载 | `loaded` / `partly loaded` / `not loaded` | — |
| 被拒 | 服务器拒绝了：{服务器给的说明}。{修正办法} | `refused: {detail}` | 写死的“到 Hub 控制台…” |
| 部分结果 | 显示 100 / 共 342 | `100 of 342` | 只显示前 100、不说明 |

- Circle 里不出现 Hub 字样；控制台是 Hub 自己的界面，可以写 circle-hub。
- 连上来的程序照实写它报的名字，没报名字的写“客户端”，不默认写成 Circle。名字来自 MCP 握手 `initialize` 的 `clientInfo`、OAuth 动态注册的 `client_name` 或管理员签发令牌时写的标签；三者都是声明，界面上不加标注，来源写在技术详情里。
- 哈希、引用编号和内部账号号不出现在屏幕上，放进可以复制的“技术详情”。
- 服务器给的说明（同步接口的 `detail`、MCP 回答里的修正）原样显示，不改写，也不另编一套。

控制台的界面用语写在 Hub 模型的“界面用语”里，由合约生成；工作台的界面用语写在 `apps/workbench/src/i18n/zh-CN`。两边都不在组件里手写中文。

## 在两个产品中实现

**circle-hub 控制台**

- 控制台由服务器渲染、不依赖前端框架：由 `tokens.json` 生成 CSS 自定义属性，按 `components/bundle.css` 的类名写页面，现有的 `hub/server/console/style.ts` 整体换成这里的设定与组件样式。
- 对话框沿用无脚本的 `:target` 做法；悬停提示同时保留 `title` 属性，读屏软件可读。
- 字体只用系统字体与 `Circle CJK` 的本地字形（`local()`），不打包、不下载字体文件，遵守控制台现有的内容安全策略。
- 每个页面在根元素上标明区域，并用同一套三栏框架；改版后逐页截图，与组件预览对照，桌面和窄屏都要核对。

**Circle 工作台**

- 颜色仍然只来自一张调色板（`src/ink/theme.ts`）：把深浅两套底色与文字色换成本规范的值，再由 `apps/workbench/src/theme.ts` 按下表导出工作台的设定，不另建第二张颜色表：

| 工作台设定 | 本规范 |
| --- | --- |
| `--sidebar` | `surface-0` |
| `--bg` | `surface-1` |
| `--drawer`、`--surface` | `surface-2` |
| `--hover` / `--active` | `surface-hover` / `surface-pressed` |
| `--border` | `line-hairline`（装饰）、`line-control`（控件） |
| `--fg` / `--secondary` / `--muted` | `text-primary` / `text-secondary` / `text-tertiary` |
| `--accent` | `area-knowledge` |
| `--violet` | `area-workflow`；输入区外框用 `brand-violet` |
| `--attention` | `area-task`；输入区外框用 `brand-orange` |
| `--negative` / `--positive` | `status-fail` / `status-pass` |
| `--logo-gradient` | `brand-blue` → `brand-violet` → `brand-red` → `brand-orange` |

- `--radius` 由 7px 改为 8px；用户消息、计划和输入区用 10px。
- 终端标签页（xterm）的配色继续由调色板推导，不在本规范内单独定义。
- 用词按“文字”一节逐条改写 `zh-CN` 词典，并用工作台已有的截图检查核对两套主题。

---

本文是 Circle 与 circle-hub 共用的设计规范，按 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.zh-hans) 授权：引用、借鉴须署名 Circle 与 qingshanfeihu 并注明原始出处链接。标志文件不在授权范围内。见[设计规范索引](../README.md)。