| name | AI Toolbox Design System | ||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| version | 0.1 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| status | agent-readable-draft | ||||||||||||||||||||||||||||||||||||||||||||||||||
| colors |
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| typography |
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| spacing |
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| rounded |
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| components |
|
DESIGN.md 是给 AI coding agents 和开发者阅读的视觉设计系统文档。它描述 AI Toolbox 的产品调性、设计 token、布局密度、组件形态和常见 Do / Don't。
本文件不是应用运行时资源。除非某个任务明确要求建立运行时设计 token 管线,否则不要把它接入构建、主题切换、备份、同步或用户配置读写流程。
AI Toolbox 是面向长期使用的桌面端配置工作台。界面应当安静、克制、高信息密度、可靠、易扫描,服务于反复管理 Coding CLI、模型供应商、Gateway、会话、Skills、MCP、WSL/SSH、备份和图片渠道。
它不是营销站、落地页或展示型产品。不要为业务工作台创建 hero 区、大幅装饰背景、宣传式卡片组、插画主导布局或过度戏剧化的视觉效果。
- 运行时主题颜色来自
web/App.css中的 CSS 变量和web/app/providers.tsx中的 Ant Design token。 - 亮色、暗色和 system theme 都由现有主题系统处理;新 UI 默认复用这些变量。
- frontmatter 只保留可被
@google/design.mdlint 识别的核心颜色快照和组件 token;业务实现仍必须使用对应 CSS 变量和 Ant Design token,不要把这些快照硬编码进组件。 AGENTS.md负责工程规则、模块边界、数据语义和验证要求;本文件负责视觉调性、设计 token、组件形态和界面密度。- 如果本文件与更近作用域的模块级
AGENTS.md冲突,模块级文档的行为语义优先;颜色、密度、圆角、层级和组件视觉默认继续遵循本文件。
- 修改前端可见 UI 前,agent 必须先完整阅读本文件,再阅读目标模块的
AGENTS.md和相关代码。 - UI 方案需要明确落到本文件的调性、布局密度、token、组件形态和 Do / Don't,不要只写“沿用现有风格”。
- 修改本文件后运行
pnpm design:lint。该命令使用 Google@google/design.mdCLI 校验DESIGN.md的格式和可识别设计 token。 - 仅修改业务 UI 代码时,不强制运行
pnpm design:lint;但仍必须按本文件做亮色、暗色、长文本、空态、加载态和交互状态自查。
- 优先清晰和可维护,而不是新奇视觉。
- 优先紧凑但可读,而不是稀疏留白。
- 优先状态可扫读,而不是状态强打断。
- 优先一致组件语言,而不是每个模块重新发明一套样式。
- 优先真实数据和真实空态,而不是伪造图表、占位指标或装饰性内容。
避免单一色相铺满页面、装饰性渐变球、玻璃拟态背景、过大的圆角、嵌套卡片和与当前产品气质不一致的品牌化营销布局。
所有可见 UI 颜色必须使用现有 CSS 变量或 Ant Design token。不要在业务组件里硬编码只适用于亮色或暗色的颜色。
主色只用于少量关键位置:
- 主按钮和主操作。
- 选中态、焦点态和当前导航。
- 需要明确强调的链接或状态。
状态色必须表达真实语义:
success:已连接、已启用、健康、完成、安全恢复。warning:降级、部分成功、等待、冷却中、需要关注。error:失败、阻塞、危险操作、不可用、无效输入。
不要用状态色做大面积装饰背景。状态色背景应低饱和,正文和边框必须保持足够对比度。
工作台界面使用紧凑文字层级。页面标题通常接近 Ant Design Typography.Title level={4} 的大小。
推荐层级:
- 页面标题:
20px / 600 - 分区标题:
14px / 600 - 正文:
13px / 400 - 辅助文字:
10px / 400
不要在仪表盘、卡片、弹窗、侧栏、表格和设置面板里使用 hero 级字号。长标签优先换行或压缩布局,不要让文字覆盖邻近内容。
AI Toolbox 的核心页面应当像工作台,而不是内容网站。
优先使用:
- 表格:请求记录、统计、历史、定价、可比较记录。
- 紧凑列表或卡片:供应商、Skills、MCP、分组管理项。
- 横向表单行:弹窗和设置分区里的常规字段。
- 分栏工作台:会话详情、主从视图、列表加详情。
不要把卡片放进卡片。页面分区应是自然布局或全宽区域;卡片只用于重复项、弹窗分区和真正需要框定的工具表面。
固定格式 UI 必须有稳定尺寸。工具栏、图标按钮、计数器、标签、卡片标题、表格单元格和加载态不应因为 hover、动态内容或文字长度导致布局跳动。
浏览长列表时,页面级工具栏应冻结在固定顶栏正下方,使用 position: sticky 和内容区 top: 0,并带不透明背景。--content-top-offset 只负责 main 的顶部留白,不要再写进 sticky top。冻结范围只属于当前分区或当前页;分区滚出视口后必须自动解冻。不要用 position: fixed 把工具栏钉死在窗口上,也不要让嵌套 Collapse、弹窗或抽屉里的工具栏再叠一层冻结栏。
默认使用 Ant Design Modal 原生 chrome。不要重度覆盖 .ant-modal-content、.ant-modal-header、.ant-modal-footer 或 .ant-modal-close。
antd Modal 内容区本身已自带内边距(非 wireframe 模式下由 .ant-modal-content 的 contentPadding 承担,.ant-modal-body 默认无额外 padding)。不要在 styles.body / .ant-modal-body 上再叠加一层 padding,也不要给弹窗内容外层容器重复加 padding——否则会形成双重内边距,让预览编辑器、表格等内容间距过大。同理,自身已带 padding 的容器(如 Card、编辑器、section card)内部不要再套一层带 padding 的包装。需要微调内容间距时,优先使用内容自身或子元素的 margin。
普通弹窗只做必要 body padding 调整。高弹窗依赖 web/App.css 中的全局 viewport-safe modal 规则,不要重新添加一次性的 top 偏移或 max-height hack。
弹窗内普通分区使用 section card:
.sectionCard {
border: 1px solid var(--color-border);
border-radius: 16px;
background: var(--color-bg-elevated);
padding: 18px;
box-shadow: none;
}可折叠弹窗分区必须看起来像一个完整 section,而不是多个嵌套卡片。折叠内容不能只通过 opacity、max-height 或 overflow 隐藏后仍保留可聚焦控件。
弹窗表单默认优先横向布局:左侧 label,右侧输入或值。
紧凑字段行推荐:
.formFieldRow {
display: grid;
grid-template-columns: 108px minmax(0, 1fr);
gap: 12px;
align-items: center;
}窄视口可以堆叠为单列。只有单字段快速输入、超长 label 或非常窄的容器才优先使用垂直布局。
保存 optional 字段时,UI 不应因为视觉简化把“用户清空字段”和“字段缺失”混为一谈;具体数据语义继续遵守 AGENTS.md 和模块文档。
Provider、配置、Skills、MCP 和管理卡片应保持一致结构:
- 头部紧凑。
- 标题在前。
- metadata 紧跟标题,不要被推到最右侧形成大空隙。
- 状态和主操作容易扫读。
- 重复卡片默认使用
var(--color-border-card)和var(--shadow-card-sm)。
选中或已应用状态可以使用 var(--ant-color-primary) 强调边框。Gateway 主供应商或 failover 状态可以使用语义状态色,但必须代表真实状态。
不要把普通卡片边框改成 var(--color-border-card-subtle);它对高频管理页面过弱,容易失去层级。
请求、统计、定价、历史和诊断列表应保持高密度表格或类表格布局。
列表只展示摘要。大块 request body、response body、headers、完整 JSON、attempt 明细和 trace 详情应放在详情弹窗或详情面板中。
空态必须表达真实情况。没有数据就显示空态,不要造假数据填图表或列表。
Skills 和 MCP 管理页面需要容纳几百项。设计时必须考虑性能、扫描效率和批量操作。
优先使用:
- 轻量原生控件和共享 management 组件。
- 搜索、分组、筛选、选择模式和批量操作。
- 虚拟滚动或稳定网格尺寸。
- 高密度卡片和清晰 metadata。
避免在高频列表控件中过度使用重型 Ant Design 组合件。复杂弹窗、表单和表格可以继续使用 Ant Design。
Gateway 是运维型工作台,不是装饰性报表。
使用紧凑 Tab、状态 badge、高密度表格和明确的错误/健康文案。failover、usage-log-recorded 等后台事件只应静默刷新数据,不应弹全局 notification 打断用户。
Gateway 辅助说明文字统一使用 font-size: 10px 和 var(--color-text-tertiary)。
会话详情是 workbench。使用结构化导航、紧凑消息渲染、清晰工具块、搜索和滚动定位。
普通 user/assistant 文本应保持轻量。tool、thinking、system、summary、image、unknown 等块可以使用紧凑 renderer card。
不要把每条消息都渲染成大型编号日志卡片。不要把工具卡片包在普通文本气泡里。
高信息密度不等于把按钮压扁。普通文字操作默认使用 30–32px 高度,文字 12–13px,行高 18–20px;上下保留约 5px 的可见留白,左右内边距 10–12px,图标与文字间距 6px。优先使用 Ant Design 默认尺寸,再按页面密度微调字体;不要把 size="small" 当作所有业务操作的默认值。
size="small"仅用于确实受表格行高或密集工具栏约束的操作。若 24px 按钮承载 14px 文字、导致字形接近上下边框,应增高按钮或缩小字体,不能只把文字塞进既有高度。- “添加规则”“添加条目”等次级操作默认按内容宽度展示、靠近所属列表;不要因为父容器是纵向 flex 就拉伸为整行细长边框按钮。只有真正需要整行点击的选择项、移动端主操作等场景才使用全宽按钮。
- “管理规则”“查看详情”等分区入口优先使用小图标配文字的轻量按钮,保留 hover、键盘 focus 和 disabled 状态;不必全部包成普通灰边框按钮。
- 删除、更多等图标操作保持 28–32px 的稳定命中区域。hover 不改变宽高、padding 或字重,避免布局跳动。
- 圆角、颜色、边框和交互状态继续复用现有主题 token,不增加装饰性渐变或阴影。不要为单个页面覆盖整站 Ant Design 按钮样式。
局部普通操作按钮可使用以下尺寸基线,按钮颜色和状态继续交给现有主题:
.actionButton {
display: inline-flex;
align-self: flex-start;
align-items: center;
justify-content: center;
gap: 6px;
min-height: 32px;
padding: 5px 12px;
border-radius: 6px;
font-size: 12px;
line-height: 20px;
}固定选项的下拉框必须容纳最长选项文字、箭头和内边距,例如“正则表达式”不能显示成“正则表…”。优先给控件足够的最小宽度,窄窗口再换行排列;省略号只用于长度不可预测的数据值,并提供完整内容的查看方式。
同一字段的标题与辅助说明放在同一文字组,内部使用 2–4px 间距;字段组之间才使用 8–12px 间距。不要将说明拆成独立布局行后重复叠加 section gap,造成标题和说明脱离。
操作区下方的说明属于独立内容组,与上方按钮或工具栏保留 8–12px 的外部间距,默认使用 12px。按钮内部 padding 不能替代这段间距;也不能套用标题与副标题之间的 2–4px。尤其要检查 Tabs 内容末尾的按钮与 Tabs 外说明,二者不在同一个 gap 容器内时需显式设置间距,不能让说明紧贴按钮边框。
验收除检查“不溢出”外,还要在真实父级设置分区或工具栏中检查按钮文字留白、固定标签完整显示、内容宽度按钮、亮暗主题和窄窗口;孤立组件截图不能代替真实容器检查。
常见操作使用 lucide-react 图标:保存、下载、刷新、搜索、关闭、复制、展开、收起、设置、撤销、重做等。
图标按钮需要可理解的 tooltip。只有在命令不清晰或危险操作时才使用文字按钮补充语义。
不要为常见工具操作手写 SVG。
亮色、暗色和 system theme 下都必须可读。重要状态不能只靠颜色表达。
焦点态必须可见。不要移除 outline,除非提供同等清晰的 token-based focus style。
折叠内容里的交互控件不能在隐藏状态继续被键盘聚焦。
长文本、长模型名、长路径、长供应商名和长错误信息必须在容器内稳定处理,不能覆盖相邻内容。
- 使用
var(--color-*)和 Ant Design token。 - 使用 CSS Modules + Less。
- 使用紧凑、稳定、可扫读的布局。
- 让 metadata 靠近标题。
- 弹窗表单默认横向布局。
- 同时检查亮色和暗色主题。
- 用真实空态表达无数据。
- UI 文案保持短、准、操作性强。
- 不要在 feature 样式里硬编码浅色或暗色颜色。
- 不要为工作台页面做 landing page 或 hero 区。
- 不要使用装饰性渐变球、bokeh、玻璃拟态背景。
- 不要卡片套卡片。
- 不要用过大的圆角和松散留白稀释信息密度。
- 不要为单个页面引入一套新的视觉系统。
- 不要为了局部差异新增全局 Ant Design 配置。
- 不要让文字重叠、关键状态被截断或动态内容导致布局跳动。