产品体验与界面设计规范
本文档定义 ARS 的产品体验与界面设计规范，适用于需求设计、交互方案、视觉设计、web/src 下的新页面、新组件和现有 UI 调整。它同时面向产品、设计、人类开发者和 AI coding agent：开始实现前先说明用户目标、信息层级和交互语义，再复用现有组件、CSS 变量和交互模式。
0. 产品判断先于界面实现
界面不是接口字段的可视化投影。设计前先明确：目标用户、主要任务、需要做出的判断、成功与异常状态，以及哪些信息只是实现细节。
- 每个可见元素必须帮助用户识别、选择、判断状态、执行操作或恢复错误；否则删除。
- 默认使用用户语言描述用途、差异和影响。内部 ID、枚举和环境变量只在复制、对接或排障时按需展示。
- 不同概念不能因为数据结构相同就放进同一列表。“不使用服务”“自动选择”等通常是策略，不是资源项。
- 一个页面或分区只解决一个主要问题；高级和低频配置使用渐进披露。
- “接口返回了”“其他后台都有”“看起来更丰富”不能成为展示理由。
1. 视觉气质
ARS 是知识库、知识图谱与 Agent 开发平台，界面应保持克制、清晰、工程化。设计服务于长时间阅读、配置、调试和数据管理，不做营销页式装饰。
核心原则：
- 功能优先：视觉层级帮助用户理解任务、状态和下一步操作，不为装饰牺牲信息密度。
- 一致优先：相似功能使用相同布局、颜色、状态和交互反馈。
- 轻量优先：用背景、边框、字号和留白建立层级，避免重阴影、夸张渐变和非功能性动效。
- 可维护优先：新增样式必须基于现有 token 和组件模式，不为单次需求引入新的设计体系。
2. 颜色与 Token
颜色必须优先使用 CSS 变量：未迁移页面用 web/src/styles/tokens.css（:root 是亮色值，.dark 覆盖同名 token，由 web/src/index.css 的 @theme inline 映射为 Tailwind 工具类，组件里写 bg-color-bg-1、text-color-text-2 这类语义类名），迁移到 Yuxi 基座的页面用 web/src/styles/yuxi-tokens.css 的 --main-*、--gray-*、--color-*。不要在组件中新增硬编码色值；确需新增全局色值时，先补充 token 并说明用途。web/scripts/check-design-tokens.mjs 禁止硬编码 HEX、非 var() 的 rgb()/hsl() 与 Tailwind 默认调色板类。
主色
--primary-1 到 --primary-7 是品牌主色刻度，1 最浅、7 最深：
主色只用于表达「当前选择、主要操作、关键入口」。不要把主色当作普通装饰色铺在卡片或大面积背景上。
中性色
--color-bg-*、--color-text-*、--color-border-*、--color-fill-* 是默认界面骨架，刻度数字越大表示层级越靠前或越深：
组件内优先选语义变量；需要更细层级时再使用数字更大的刻度。同一层级不要混用 --color-bg-* 与 --color-fill-*。
语义色
语义色只用于状态和反馈，不用于装饰。每个族同样是 1 到 7 的刻度（1 最浅、7 最深）：
状态标签建议使用浅背景 + 深文字，例如 background: var(--success-1); color: var(--success-7);。不要只依靠颜色传达状态，必要时配合文字或图标。
图表色
图表和统计可视化使用 --data-1 到 --data-20。不要复用错误色、警告色做普通图表分类，避免与状态反馈混淆。
暗色模式
ARS 通过 html.dark 覆盖同名 token，切换入口是 web/src/components/ui/DayNightSwitcher。新增 UI 必须使用 CSS 变量，禁止固定浅色值，并检查浅色、暗色两套表现。
新增组件时至少检查：
- 背景、卡片、输入框不出现纯白硬编码导致的暗色穿帮。
- 文本和边框在暗色模式下仍有足够对比度。
- hover、focus、disabled、selected、error 等状态在暗色模式下可辨认。
- 图表、代码块和第三方组件需要显式传入 theme 时，读取
html.dark或复用同一份 token。
3. 字体与文本层级
全局字体栈定义在 web/src/index.css（--font-sans 与 --font-mono），等宽字体由 @fontsource-variable/jetbrains-mono 自托管。新增组件不要私自引入新字体。代码、命令、路径和技术标识使用等宽字体栈。
建议层级：
文本规范：
- 标题要短，优先描述对象，不写营销式口号。
- 按钮文案使用明确动作，如“保存配置”“重新检测”“删除文件”。
- 危险操作必须让文案直接表达后果，如“删除知识库”。
- 不使用 placeholder 替代表单 label；placeholder 只做输入示例。
- 不使用负字距或按视口宽度缩放字体，避免宽屏和小屏出现不可控排版。
4. 组件样式
技术栈约束
- 框架：React 19 + Vite
- 包管理器：
pnpm - 图标库：
lucide-react - UI 基础：antd 5 组件，主题由
web/src/app/theme/antd-provider.tsx提供，全局覆盖写在web/src/styles/antd-overrides.css，页面私有的.ant-*覆盖写在页面 CSS Modules 的:global()里。web/src/shared/ui下的 shadcn/ui 组件处于滚动收缩期：只减不增，最后一个使用者消失后删除 - 样式语言：页面样式用 CSS Modules 与原生 CSS；Tailwind CSS 4 保留给布局与间距工具类，主题配置在
web/src/index.css，层叠顺序由该文件顶部的@layer声明拥有 - 颜色变量：迁移期有两套来源——
web/src/styles/yuxi-tokens.css（正在迁移到的 Yuxi 色板：--main-*、--second-*、--gray-*、--color-*）与web/src/styles/tokens.css（未迁移页面仍在用的旧色板），两者都由pnpm run check:tokens强制 - 图表：统计图表用
echarts（按需注册，只在消费它的路由分包里），关系图谱用@antv/g6；两者都不认var(--x)，配色从 token 解析成具体色值后再进画布，主题切换时重建实例
按钮
按钮应按操作优先级区分：
交互状态：
- hover 可以改变
background、border-color、color，不要位移或放大。 - focus 必须可见，不能移除键盘焦点样式。
- disabled 使用弱化文本和背景，不绑定 hover 强反馈。
- loading 应保留按钮宽度，避免布局跳动。
输入框与表单
表单用于配置和管理任务，优先保证可读性和错误可恢复：
- 输入框背景使用
--color-bg-1。 - 边框使用
--color-border-2，focus 使用主色或组件默认 focus ring。 - label 必须稳定显示，helper text 放在输入框下方。
- 错误信息使用
--danger-*，并写清楚修复方式。 - 多字段表单按逻辑分组，避免把无关设置塞进同一行。
- 参数名称应说明业务含义和单位；非显然参数补充调整影响、推荐范围或示例。
- 只允许用户修改真正属于业务配置的值。官方端点、内部枚举和部署参数由系统管理，不伪装成普通输入项。
卡片、列表与表格
ARS 的信息界面以配置卡片、列表和表格为主，默认使用轻量分层：
- 普通卡片：
background: var(--color-bg-1); border: 1px solid var(--color-border-1); border-radius: 8px; - 次级区域：可使用
var(--color-bg-2)/var(--color-bg-3)做轻背景。 - 点击态列表行：hover 只改变背景或边框，不使用
transform。 - 表格行内操作保持紧凑，避免每行出现多个高权重按钮。
- 空状态要说明“当前没有什么”和“下一步可以做什么”，不要只显示图标。
阴影只用于真实浮层，如弹窗、抽屉、下拉菜单、tooltip。普通卡片和列表不要用阴影制造装饰性层级。
列表、状态与操作
- 摘要层按“名称 → 用途或关键差异 → 需关注状态 → 操作”组织，不机械展示名称、ID、类型和全部状态。
- 内部 ID 默认隐藏；确需展示时放入详情，使用 monospace 和明确标签或复制入口。
- 一个状态只保留一种主要表达。开关已经表达启用状态时，不再增加绿色点和“已启用”文字。
- 正常状态保持安静，只突出异常和需要行动的状态；颜色不能作为唯一信息载体。
- “不启用”“自动”“沿用默认”等策略放在选择器或策略区，不伪装成普通资源项。
- 开关默认表示立即生效。需要统一保存时，应明确显示未保存状态，不能混用两种提交模型。
- 同类行共享稳定的展开、文本、状态和操作列。图标使用固定盒、统一
gap和line-height，右侧操作保持同一边界。 - 配置列表优先使用一个列表容器和轻分割线，避免每行形成厚重卡片；展开内容与触发行保持连续。
- 至少在真实页面的目标宽度、1024px、768px 和 375px 检查对齐、长文本和溢出。
状态标签
状态标签使用语义色浅背景 + 深文字：
标签可以使用 pill 圆角，但不要把 pill 形状扩散到所有按钮和卡片。
图标
- 常规图标尺寸使用 16px、18px 或 20px。
- 图标颜色默认继承文本色；需要强调时使用语义 token。
- 图标按钮使用
Button的size="icon"，图标与按钮的中心线由组件保证。 - 不为同一概念混用多个图标；相同操作在不同页面保持一致。
5. 布局与间距
间距以 4px / 8px 为基础节奏：
布局原则：
- 配置型页面保持适度信息密度，不做大面积营销式留白。
- 相邻操作靠近对应内容，页面级操作放在标题区或工具栏。
- 一组按钮中主操作在视觉上最明确，取消/返回等次操作弱化。
- 宽屏下限制正文行长，避免说明文字横跨整个页面。
- 小屏下优先纵向堆叠，避免强行压缩表格和表单字段。
6. 深度与层级
ARS 默认采用“背景 + 边框”的轻量层级：
不要在普通内容卡片上使用重阴影。只有当元素真实覆盖其他内容、需要表达浮层关系时，才允许使用阴影。
7. Do / Don't
Do
- 使用
web/src/styles/tokens.css中的 token。 - 为新增交互补齐 hover、focus、disabled、loading、empty、error 等必要状态。
- 用背景、边框、字号、间距建立层级。
- 保持浅色和暗色模式一致可用。
- 复用
lucide-react与web/src/components/ui已有组件模式。 - 在复杂配置区保留简短说明，帮助用户理解设置影响。
Don't
- 不要在 hover 时使用位移、放大、旋转等装饰性 transform。
- 不要使用浓重阴影装饰普通卡片。
- 不要使用夸张渐变或大面积高饱和背景。
- 不要把语义色用于纯装饰。
- 不要新增一次性 helper、样式体系或无复用价值的抽象。
- 不要硬编码浅色模式色值导致暗色模式失效。
- 不要在同一区域放置多个同等视觉权重的主操作。
8. 响应式行为
响应式设计以“功能不丢失、信息不挤压”为优先：
- 小屏下表单字段纵向排列，按钮组可换行。
- 侧栏、抽屉和弹窗要保证最小宽度内内容可读。
- 表格在小屏下允许横向滚动；不要把关键字段压缩到不可读。
- 图标按钮和主要操作需要保持可点击区域，移动端目标尺寸尽量不小于 40px。
- 长文本使用省略号时，应提供 tooltip、title 或详情入口查看完整内容。
- 图谱、图表、代码块等宽内容应保留横向滚动或自适应缩放策略。
9. 设计交付与审阅流程
UI/UX 质量不能只由构建通过和没有溢出证明。交付前按三层审阅：
- 产品层：每个元素是否有价值，概念是否符合用户心智，是否暴露无用实现细节。
- 交互层：操作是否可发现，生效时机是否明确，失败能否恢复，状态是否一致。
- 视觉层：层级、对齐、间距、文字、图标、颜色和响应式是否精确一致。
UI 修改必须提供真实运行页面截图，覆盖核心状态和至少一个边界状态。使用真实数据检查长名称、加载、错误、空状态、浅色/暗色和关键响应式宽度；未验证内容在交付说明中列出。
10. Agent Prompt Guide
AI agent 修改或生成 ARS UI 时，优先按这一节执行。
Quick Reference
- 页面背景：
var(--color-bg-1) - 次级背景：
var(--color-bg-2)/var(--color-bg-3) - 主要文本：
var(--color-text-1) - 次级文本：
var(--color-text-3) - 边框：
var(--color-border-1)/var(--color-border-2) - 主色：
var(--primary-6) - 卡片圆角：
8px - 小控件圆角：
4px/6px - 状态标签圆角：
999px - 常规图标尺寸：
16px/18px/20px - 卡片 padding：
16px/20px/24px - 普通 hover：只改变背景、边框或文字颜色
Example Prompts
实现配置卡片：
实现工具栏按钮：
实现状态标签：
实现检查清单
- 已说明用户任务、信息层级和提交模型。
- 没有平铺无用字段、重复状态或伪装成资源的策略项。
- 名称和描述使用用户语言，内部 ID 仅按需展示。
- 图标、文字、输入框和操作列已完成视觉对齐检查。
- 使用现有 CSS 变量，没有新增随意硬编码色值。
- 浅色和暗色模式都检查过。
- hover、focus、disabled、loading、empty、error 状态符合场景。
- 没有使用 hover 位移、放大、旋转或装饰性动画。
- 普通卡片没有使用重阴影。
- 图标来自
lucide-react，尺寸和对齐符合现有模式。 - API 接口、组件位置、样式语言符合前端开发规范。
- 已在真实页面和关键响应式宽度截图验收，而不只依赖构建通过。
参考资料
web/src/styles/yuxi-tokens.css：Yuxi 色板（--main-*/--second-*/--gray-*/--color-*）web/src/styles/tokens.css：未迁移页面仍在用的旧色板（:root/.dark）web/src/styles/antd-overrides.css：antd 的全局.ant-*覆盖web/src/index.css：层叠顺序声明、Tailwind 主题映射、字体栈与全局基础样式web/src/shared/ui：shadcn/ui 组件源码（滚动收缩中）- Awesome DESIGN.md：面向 AI agent 的
DESIGN.md样例集合