主题视觉验收与踩坑手册

本文是主题系统与前端配色开发手册的实践配套，记录 New Steel 从设计、接入到全页面调优过程中真正暴露的问题。

它不要求所有主题长得一样，而是确保每套主题都满足同一组视觉关系：

• 页面画布、内容 Surface、嵌套区域和浮层层级清楚。
• Default、Hover、Selected、Active、Focus 不会互相混淆。
• 品牌色有识别度但不过量。
• 功能色和文字前景符合语义。
• 切换主题只改变视觉，不改变布局和行为。

审美基线

1. Surface 要稳定，强调色要克制

Light 中，独立卡片、公共页头、表格、历史消息区、Dialog 和工具执行区域通常需要稳定 Surface。不要让它们透出页面画布，也不要把全部区域机械染成主题色。

主题色优先用于：

• 主按钮、链接和可点击图标。
• 当前导航、Selected 和 Focus。
• 小面积身份、状态或强调标记。

主题色不应直接铺满：

• 大面积业务卡片 Hover。
• 整个表头或公共页头。
• 密集 Badge 列表。
• 普通正文和说明文字。

2. Hover 是反馈，不是换一个页面层级

Hover 应让用户知道“这里可交互”，但不能：

• 变得和 Selected 几乎一样。
• 变得接近页面画布，像卡片突然消失。
• 使用过重阴影，像 Popover。
• 改变尺寸、内边距、排列或文本换行。

中小面积导航、选项和表格行可以使用主题 Hover 背景；大卡片更适合保持 Surface，通过边框、轻阴影和小幅抬升反馈。

3. 默认状态保持安静

静态卡片默认使用中性边框。主题色边框只用于 Hover、Selected、Focus 或明确业务状态。

如果所有卡片默认都有彩色边框，页面会持续处于“已选择”或“需要注意”的视觉噪声中。MCP 卡片最终与 Skills 卡片统一：默认中性边框，Hover 才出现弱主题色边框。

4. 文字层级必须可读

• 主文字负责内容。
• Secondary 负责可连续阅读的说明。
• Muted 负责时间、ID 和元信息。
• Disabled 只负责真正不可用的控件。

不要把所有非标题文字都降成 Muted。视觉“轻”不等于可读性低。

5. 实底必须配套前景

蓝色、红色、绿色等实底上的文字和图标必须使用对应 Solid Foreground。尤其是危险按钮，Light/Dark 都需要单独确认；不能因为 Dark 的某个前景可用，就让 Light 出现红底黑字。

6. 默认主题是产品资产

新增主题不是重做全站。Classic 的原有观感必须通过安全默认 Token 保留。任何新语义角色都先定义 Classic 等价值，再提供新主题映射。

7. 配色不承担布局职责

主题语义类只负责颜色、边框和必要阴影。公共头“缺背景”时只补背景，不能同时增加 Padding、圆角、Overflow 或改变 CardContent 结构。

诊断问题时先记录四件事

每次开始排查前先记录：

1. 主题方案，例如 classic 或 new_steel。
2. 模式，例如 Light 或 Dark。
3. 路由和数据状态。
4. 交互状态，例如 Default、Hover、Selected、Disabled。

同一个组件在不同组合下可能走不同变量。没有这四项，“这里颜色不对”很容易被修成另一个范围的回归。

真实踩坑与正确处理

色板和前景

Surface 和透明背景

Hover、边框和阴影

Tabs、导航和图标

输入、共享组件和第三方控件

默认主题和维护方式

修复层级选择

禁止用以下方式绕过判断：

className={themePreset === "new_steel" ? "bg-white" : "bg-muted"}

也不要把主题 ID 包装成 Tailwind 自定义变体后散落到页面。它解决了眼前选择器，却把下一主题的遗漏变成必然。

页面验收矩阵

不要维护固定路由清单。先从当前源码盘点，再按页面类型抽取有代表性的真实数据：

rg --files frontend/app | rg '/page\.tsx$'

必查页面类型

• 登录页、首页、全局导航和用户设置。
• Agent 工作台、任务创建、临时对话。
• 历史消息、运行中会话、工具执行、产物和实时电脑区域。
• Skills、MCP、Plugins、定时任务、发布中心等能力页面。
• 管理后台的概览、表格、筛选、表单和详情。
• Agent、Conversation、Publish 等公开分享页。
• 具有真实 ID 的动态详情路由。
• 文档站本身。

必查表面

• Page、Card、Popover、Dialog、Sheet、Drawer。
• 公共页头、卡片头、表格头和表格正文。
• 历史消息区、工具步骤、输入输出载荷。
• 表单 Dialog Body、分组卡片、Input 和 Textarea。
• 空状态、加载骨架、错误提示和 Toast。

必查交互状态

• Primary：Default、Hover、Active、Focus、Disabled、Loading。
• Destructive：Default、Hover、Focus、Disabled。
• Card：Default、Hover、Selected、Disabled。
• Tabs：List、Inactive、Hover、Active、图标和 Badge。
• Table：Header、Row Hover、Selected、Empty、Loading。
• Success、Warning、Danger、Info：浅色和必要的实底状态。
• Sidebar：Default、Hover、Selected、Pressed、Focus。

必查模式和视口

新主题完整验收至少覆盖：

局部维护任务按用户指定范围执行，但必须确认未修改主题和模式没有被全局 Token 或共享组件意外影响。

稳定触发交互状态

无法稳定触发的状态标记“未覆盖”和原因，不能根据默认外观推断通过。

验收记录模板

每个问题至少记录：

现象：
主题 / 模式 / 路由 / 状态：
实际计算色：
期望语义角色：
修复层级：
回归范围：

通过标准

• 页面画布与独立 Surface 层级清楚，没有无意透底。
• Primary Default 没有误用 Hover 或 Active 色。
• 实底按钮、状态和图标使用正确前景。
• Hover、Selected、Active、Pressed 可以区分且不改变布局。
• 大卡片 Hover 不会铺满过强主题色，也不会融入页面画布。
• Tabs 在不同父背景上仍能区分 Inactive 和 Active，图标同步状态。
• 表头、卡片头、Dialog、工具卡片和历史消息区都有稳定表面。
• 文字层级清晰，重要说明没有被误降为 Muted。
• Classic 和未修改模式保持原有观感。
• 没有硬编码颜色、主题 ID 判断或局部主题补丁泄漏到业务组件。
• 状态同时包含文字、图标或可访问名称。
• 桌面和窄屏没有新增溢出、错位或操作不可见。

何时停止继续调色

满足以下条件时应停止局部微调，回到设计或语义层重新确认：

• 同一状态在三个以上页面需要不同临时色。
• 只有继续加入透明度或 color-mix(...) 才能勉强可见。
• Hover、Selected 和 Page Surface 已无法稳定区分。
• 为了配色开始修改布局。
• 修复当前主题必然破坏 Classic。
• 无法说明当前颜色代表的语义角色。

主题适配的目标不是让每个角落都带品牌色，而是让用户在长时间使用时感到稳定、清晰和舒适。