本文档定义 Yuxi 的产品体验与界面设计规范，适用于需求设计、交互方案、视觉设计、frontend/src 下的新页面、新组件和现有 UI 调整。它同时面向产品、设计、人类开发者和 AI coding agent：开始实现前先说明用户目标、信息层级和交互语义，再复用现有组件、CSS 变量和交互模式。
界面不是接口字段的可视化投影。设计前先明确：目标用户、主要任务、需要做出的判断、成功与异常状态，以及哪些信息只是实现细节。
- 每个可见元素必须帮助用户识别、选择、判断状态、执行操作或恢复错误；否则删除。
- 默认使用用户语言描述用途、差异和影响。内部 ID、枚举和环境变量只在复制、对接或排障时按需展示。
- 不同概念不能因为数据结构相同就放进同一列表。“不使用服务”“自动选择”等通常是策略，不是资源项。
- 一个页面或分区只解决一个主要问题；高级和低频配置使用渐进披露。
- “接口返回了”“其他后台都有”“看起来更丰富”不能成为展示理由。
Yuxi 是知识库、知识图谱与 Agent 开发平台，界面应保持克制、清晰、工程化。设计服务于长时间阅读、配置、调试和数据管理，不做营销页式装饰。
核心原则：
- 功能优先：视觉层级帮助用户理解任务、状态和下一步操作，不为装饰牺牲信息密度。
- 一致优先：相似功能使用相同布局、颜色、状态和交互反馈。
- 轻量优先：用背景、边框、字号和留白建立层级，避免重阴影、夸张渐变和非功能性动效。
- 可维护优先：新增样式必须基于现有 token 和组件模式，不为单次需求引入新的设计体系。
颜色必须优先使用 frontend/src/assets/css/base.css 和 frontend/src/assets/css/base.dark.css 中定义的 CSS 变量。不要在组件中随意新增硬编码色值；确需新增全局色值时，先补充 token 并说明用途。
--main-* 和 --main-color 用于品牌主色与关键交互：
| Token | 使用场景 |
|---|---|
--main-color |
主按钮、选中态、重点链接、关键图标 |
--main-700 / --main-600 / --main-500 |
主色文字、hover、active、强调状态 |
--main-50 / --main-30 / --main-10 |
主色浅背景、选中行背景、轻量提示背景 |
主色只用于表达“当前选择、主要操作、关键入口”。不要把主色当作普通装饰色铺在卡片或大面积背景上。
--second-* 是暖金色辅助色系（基准 --second-500），刻度与 --main-* 对齐，--second-color 为语义入口。辅助色只用于少量点缀（徽标、装饰性视觉元素），不能替代主色表达交互状态，也不与语义色混用。
--gray-* 是默认界面骨架，用于背景、文本、边框和分割线：
| Token | 使用场景 |
|---|---|
--gray-0 |
页面和卡片主背景 |
--gray-10 / --gray-25 / --gray-50 |
次级背景、hover 背景、弱分区背景 |
--gray-100 / --gray-150 / --gray-200 |
分割线、输入框边框、卡片边框 |
--gray-900 / --gray-1000 |
标题和主要正文 |
--gray-600 / --gray-500 / --gray-400 |
辅助说明、占位文本、禁用文本 |
文本也可以使用 Ant Design 兼容语义变量：--color-text、--color-text-secondary、--color-text-tertiary。组件内优先选语义变量；需要更细层级时再使用 --gray-*。
语义色只用于状态和反馈，不用于装饰：
| Token 组 | 使用场景 |
|---|---|
--color-success-* |
成功、已完成、连接正常 |
--color-error-* |
错误、危险操作、删除、失败 |
--color-warning-* |
警告、待处理、需要注意但未失败 |
--color-info-* |
信息提示、说明性状态 |
--color-accent-* |
少量辅助强调，不能替代主色 |
状态标签建议使用浅背景 + 深文字，例如 background: var(--color-success-50); color: var(--color-success-700);。不要只依靠颜色传达状态，必要时配合文字或图标。
图表和统计可视化优先使用 --chart-palette-*。不要复用错误色、警告色做普通图表分类，避免与状态反馈混淆。
Yuxi 通过 :root.dark 覆盖同名 token。新增 UI 必须使用 CSS 变量，禁止固定浅色值，并检查浅色、暗色两套表现。
新增组件时至少检查：
- 背景、卡片、输入框不出现纯白硬编码导致的暗色穿帮。
- 文本和边框在暗色模式下仍有足够对比度。
- hover、focus、disabled、selected、error 等状态在暗色模式下可辨认。
- 图表、代码块和第三方组件需要显式传入 theme 时，使用
useThemeStore()的现有模式。
全局字体栈由 frontend/src/assets/css/base.css 的 --font-family 定义，main.css 与 Ant Design token 共同消费，新增组件不要私自引入新字体。代码、命令、路径和技术标识可使用 monospace，优先复用现有 @mono-font 或系统 monospace 栈。
建议层级：
| 角色 | 建议样式 | 使用场景 |
|---|---|---|
| 页面标题 | 20-24px，600 | 页面主标题、弹窗主标题 |
| 分组标题 | 16-18px，600 | 卡片标题、表单分组标题 |
| 正文 | 14-15px，400 | 常规说明、列表内容 |
| 辅助说明 | 12-13px，400 | helper text、元信息、时间、统计说明 |
| 标签/状态 | 12px，500 | tag、chip、状态徽标 |
| 代码/路径 | 12-14px，monospace | 文件路径、命令、代码片段 |
文本规范：
- 标题要短，优先描述对象，不写营销式口号。
- 按钮文案使用明确动作，如“保存配置”“重新检测”“删除文件”。
- 危险操作必须让文案直接表达后果，如“删除知识库”。
- 不使用 placeholder 替代表单 label；placeholder 只做输入示例。
- 不使用负字距或按视口宽度缩放字体，避免宽屏和小屏出现不可控排版。
- 包管理器：
pnpm - 图标库：优先使用
@lucide/vue - 样式语言：LESS
- 颜色变量：使用
base.css/base.dark.css中的 CSS 变量 - UI 基础：复用 Ant Design Vue 和项目现有组件模式，避免为单次需求封装新组件体系
CSS 色板拥有颜色、字体和浮层阴影，shared/model/theme.js 读取当前主题的实际 CSS 色值并装配 Ant Design token。主题切换先更新根节点的 dark 类，再重新装配控件主题；需要参与颜色派生的 token 使用实际色值。按钮、表单、选择器、标签和普通弹窗的通用外观由主题与 assets/css/antd.less 统一维护。
主题选择为 light、dark、auto，默认浅色，以 localStorage 的 theme 保存选择。auto 实时跟随浏览器 prefers-color-scheme，isDark 提供实际明暗状态。用户菜单与 Dashboard 按浅色 → 深色 → 自动 → 浅色轮换并显示当前模式；用户菜单点击主题保持展开，其他操作与点击外部关闭。
当前 Ant Design Vue 4.2.6 将根 Provider 的设计 token 提供给静态 message、notification 和 Modal.confirm，这些反馈沿用同一主题入口。静态调用的其他上下文与组件树分离，不能据此假设它们获取业务注入。调用方保留反馈内容、时长、操作回调和显式定制；基础外观不逐页重复定义，升级组件库时验证静态反馈的主题切换。
a-select 的下拉选项通过 components.Select 统一使用中性背景：controlItemBgActive 映射 --gray-100，controlItemBgHover 映射 --gray-50。选中与悬停保持不同明度，深浅主题沿用同名 CSS 色板；不在业务页覆盖下拉选项背景。
a-alert 的四种状态共用当前主题的浅中性背景与柔和边框，以语义色图标区分成功、信息、警告和错误。背景、边框、图标颜色和圆角由 Alert 组件 token 维护，说明文字由共享样式维护；保留 banner、关闭按钮、操作与内容 slot 的原有行为。
现有 a-empty 标签与 ConfigProvider 的 renderEmpty 复用 shared/ui/AntEmpty.js，只替换默认图像，保留原有说明、自定义图像、显式隐藏配置及操作 slot。菜单空状态采用紧凑间距；需要标题、解释和下一步操作的业务引导使用 ResourceEmptyState。
管理页的行内操作、刷新按钮和旋转状态复用 assets/css/management-controls.less 的明确样式类。局部样式继续拥有尺寸、业务布局、自绘标题、定高面板及透明标题选择器等真实差异。共享规则接管外观时同步删除对应局部定义，不以追加全局覆盖保留两个可编辑事实源。
设置面板的分区标题、说明、页头操作、表单行、服务卡片和管理表格复用 assets/css/settings.less，由全局样式入口一次加载。组件使用明确的 settings-* 类，设置弹窗只拥有导航与内容区布局，不通过后代通用类覆盖面板外观。分区使用 settings-section-block 表达间距，不根据标题在 DOM 中是否为首个子节点推断层级；账户资料、沙盒状态与表格业务列保留局部布局。
按钮应按操作优先级区分：
| 类型 | 使用场景 | 样式规则 |
|---|---|---|
| 主按钮 | 页面主操作、确认提交 | 使用主色背景或 Ant Design primary，不在同一区域放多个主按钮 |
| 次按钮 | 返回、取消、普通操作 | 使用中性边框和浅背景，hover 只增强边框或背景 |
| 文本/链接按钮 | 表格行内操作、轻量入口 | 保持轻量，不扩大视觉权重 |
| 危险按钮 | 删除、撤销、清空等不可逆操作 | 使用 error 语义色，并配合确认弹窗或明确文案 |
| 图标按钮 | 工具栏、折叠、刷新、复制 | Ant 按钮使用 #icon 插槽；原生按钮使用 lucide-icon-btn |
Ant 按钮的图标与文字由 assets/css/antd.less 统一居中排列，默认间距 8px；Lucide、Ant 原生图标和 loading 图标共用此布局，不在业务组件重复添加对齐、gap 或图标 margin。图标默认沿用文字字号，显式 size 保持生效。纯图标按钮提供 aria-label，与可见文字相邻的装饰图标使用 aria-hidden="true"。
交互状态：
- hover 可以改变
background、border-color、color，不要位移或放大。 - focus 必须可见，不能移除键盘焦点样式。
- disabled 使用弱化文本和背景，不绑定 hover 强反馈。
- loading 应保留按钮宽度，避免布局跳动。
表单用于配置和管理任务，优先保证可读性和错误可恢复：
- 输入框背景使用
--gray-0或 Ant Design 默认容器色。 - 边框使用
--gray-150/--gray-200，focus 使用主色或框架默认 focus ring。 - label 必须稳定显示，helper text 放在输入框下方。
- 错误信息使用
--color-error-*，并写清楚修复方式。 - 多字段表单按逻辑分组，避免把无关设置塞进同一行。
- 参数名称应说明业务含义和单位；非显然参数补充调整影响、推荐范围或示例。
- 只允许用户修改真正属于业务配置的值。官方端点、内部枚举和部署参数由系统管理，不伪装成普通输入项。
Yuxi 的信息界面以配置卡片、列表和表格为主，默认使用轻量分层：
- 普通卡片：
background: var(--gray-0); border: 1px solid var(--gray-150); border-radius: 8px; - 次级区域：可使用
var(--gray-10)/var(--gray-25)做轻背景。 - 点击态列表行：hover 只改变背景或边框，不使用
transform。 - 表格行内操作保持紧凑，避免每行出现多个高权重按钮。
- 空状态要说明“当前没有什么”和“下一步可以做什么”，不要只显示图标。
阴影只用于真实浮层，如弹窗、抽屉、下拉菜单、tooltip。普通卡片和列表不要用阴影制造装饰性层级。
- 摘要层按“名称 → 用途或关键差异 → 需关注状态 → 操作”组织，不机械展示名称、ID、类型和全部状态。
- 内部 ID 默认隐藏；确需展示时放入详情，使用 monospace 和明确标签或复制入口。
- 一个状态只保留一种主要表达。开关已经表达启用状态时，不再增加绿色点和“已启用”文字。
- 正常状态保持安静，只突出异常和需要行动的状态；颜色不能作为唯一信息载体。
- “不启用”“自动”“沿用默认”等策略放在选择器或策略区，不伪装成普通资源项。
- 开关默认表示立即生效。需要统一保存时，应明确显示未保存状态，不能混用两种提交模型。
- 同类行共享稳定的展开、文本、状态和操作列。图标使用固定盒、统一
gap和line-height，右侧操作保持同一边界。 - 配置列表优先使用一个列表容器和轻分割线，避免每行形成厚重卡片；展开内容与触发行保持连续。
- 至少在真实页面的目标宽度、1024px 和 768px 检查对齐、长文本和溢出。
状态标签使用语义色浅背景 + 深文字：
| 状态 | 推荐 token |
|---|---|
| 成功/正常 | --color-success-50 + --color-success-700 |
| 失败/错误 | --color-error-50 + --color-error-700 |
| 警告/待处理 | --color-warning-50 + --color-warning-900 |
| 信息/运行中 | --color-info-50 + --color-info-700 |
| 普通/未知 | --gray-100 + --gray-600 |
标签可以使用 pill 圆角，但不要把 pill 形状扩散到所有按钮和卡片。
- 常规图标尺寸使用 16px、18px 或 20px。
- 图标颜色默认继承文本色；需要强调时使用语义 token。
- 图标按钮添加
lucide-icon-btn，避免图标与文本或按钮中心线错位。 - 不为同一概念混用多个图标；相同操作在不同页面保持一致。
间距以 4px / 8px 为基础节奏：
| 场景 | 建议值 |
|---|---|
| 图标与文本间距 | 6px / 8px |
| 表单项内部间距 | 6px / 8px |
| 卡片内部 padding | 16px / 20px / 24px |
| 列表行间距 | 8px / 12px |
| 页面主要区块间距 | 24px / 32px |
| 弹窗内容区间距 | 16px / 24px |
布局原则：
- 配置型页面保持适度信息密度，不做大面积营销式留白。
- 相邻操作靠近对应内容，页面级操作放在标题区或工具栏。
- 一组按钮中主操作在视觉上最明确，取消/返回等次操作弱化。
- 宽屏下限制正文行长，避免说明文字横跨整个页面。
- 小屏下优先纵向堆叠，避免强行压缩表格和表单字段。
Yuxi 默认采用“背景 + 边框”的轻量层级：
| 层级 | 处理方式 | 使用场景 |
|---|---|---|
| 页面背景 | var(--gray-0) 或布局已有背景 |
主页面 |
| 次级背景 | var(--gray-10) / var(--gray-25) |
分区、弱提示、列表 hover |
| 卡片边界 | 1px solid var(--gray-150)，8px 圆角 |
配置卡片、内容块 |
| 浮层 | 框架默认阴影或轻量 --shadow-* |
弹窗、抽屉、dropdown、tooltip |
| 焦点 | 主色 outline / Ant Design focus ring | 键盘可达控件 |
不要在普通内容卡片上使用重阴影。只有当元素真实覆盖其他内容、需要表达浮层关系时，才允许使用阴影。
- 使用
base.css和base.dark.css中的 token。 - 为新增交互补齐 hover、focus、disabled、loading、empty、error 等必要状态。
- 用背景、边框、字号、间距建立层级。
- 保持浅色和暗色模式一致可用。
- 复用
@lucide/vue、Ant Design Vue 和项目已有组件模式。 - 在复杂配置区保留简短说明，帮助用户理解设置影响。
- 不要在 hover 时使用位移、放大、旋转等装饰性 transform。
- 不要使用浓重阴影装饰普通卡片。
- 不要使用夸张渐变或大面积高饱和背景。
- 不要把语义色用于纯装饰。
- 不要新增一次性 helper、样式体系或无复用价值的抽象。
- 不要硬编码浅色模式色值导致暗色模式失效。
- 不要在同一区域放置多个同等视觉权重的主操作。
前端最小适配视口宽度为 768px（CSS 像素），响应式设计与验收范围为 768px 及以上。无需手机端适配，768px 以下不列入适配与验收要求。本规范中的“小屏”指支持范围内的较窄视口。
支持范围内以“功能不丢失、信息不挤压”为优先：
- 小屏下表单字段纵向排列，按钮组可换行。
- 侧栏、抽屉和弹窗要保证最小宽度内内容可读。
- 表格在小屏下允许横向滚动；不要把关键字段压缩到不可读。
- 图标按钮和主要操作需要保持清晰、易点击的操作区域。
- 长文本使用省略号时，应提供 tooltip、title 或详情入口查看完整内容。
- 图谱、图表、代码块等宽内容应保留横向滚动或自适应缩放策略。
UI/UX 质量不能只由构建通过和没有溢出证明。交付前按三层审阅：
- 产品层：每个元素是否有价值，概念是否符合用户心智，是否暴露无用实现细节。
- 交互层：操作是否可发现，生效时机是否明确，失败能否恢复，状态是否一致。
- 视觉层：层级、对齐、间距、文字、图标、颜色和响应式是否精确一致。
UI 修改必须提供真实运行页面截图，覆盖核心状态和至少一个边界状态。使用真实数据检查长名称、加载、错误、空状态、浅色/暗色和关键响应式宽度；未验证内容在交付说明中列出。
AI agent 修改或生成 Yuxi UI 时，优先按这一节执行。
- 页面背景：
var(--gray-0) - 次级背景：
var(--gray-10)/var(--gray-25) - 主要文本：
var(--color-text)或var(--gray-900) - 次级文本：
var(--color-text-secondary)或var(--gray-600) - 边框：
var(--gray-150)/var(--gray-200) - 主色：
var(--main-color) - 卡片圆角：
8px - 小控件圆角：
4px/6px - 状态标签圆角：
999px - 常规图标尺寸：
16px/18px/20px - 卡片 padding：
16px/20px/24px - 普通 hover：只改变背景、边框或文字颜色
实现配置卡片：
实现一个 Yuxi 风格的配置卡片：背景使用 var(--gray-0)，边框 1px solid var(--gray-150)，圆角 8px，不加阴影。标题使用 var(--color-text)，说明文字使用 var(--color-text-secondary)。hover 只轻微改变边框或背景，不使用 transform。
实现工具栏按钮：
实现一个工具栏按钮：优先使用 @lucide/vue 图标，图标尺寸 16px，按钮添加 lucide-icon-btn。默认使用中性色，hover 时使用 var(--main-color) 或 var(--main-10) 强化，不位移、不放大。
实现状态标签：
实现状态标签：成功使用 var(--color-success-50) 背景和 var(--color-success-700) 文字；错误使用 var(--color-error-50) 背景和 var(--color-error-700) 文字；警告使用 var(--color-warning-50) 背景和 var(--color-warning-900) 文字。圆角使用 999px，文字保持 12px。
- 已说明用户任务、信息层级和提交模型。
- 没有平铺无用字段、重复状态或伪装成资源的策略项。
- 名称和描述使用用户语言，内部 ID 仅按需展示。
- 图标、文字、输入框和操作列已完成视觉对齐检查。
- 使用现有 CSS 变量，没有新增随意硬编码色值。
- 浅色和暗色模式都检查过。
- hover、focus、disabled、loading、empty、error 状态符合场景。
- 没有使用 hover 位移、放大、旋转或装饰性动画。
- 普通卡片没有使用重阴影。
- 图标来自
@lucide/vue，尺寸和对齐符合现有模式。 - API 接口、组件位置、样式语言符合前端开发规范。
- 已在真实页面和关键响应式宽度截图验收，而不只依赖构建通过。
frontend/src/assets/css/base.css：浅色模式 tokenfrontend/src/assets/css/base.dark.css：暗色模式 tokenfrontend/src/assets/css/main.css：全局字体、布局基础样式和lucide-icon-btn- Awesome DESIGN.md：面向 AI agent 的
DESIGN.md样例集合
Agent 与 User 使用共享 FallbackAvatar。调用方传入 kind、稳定实体 seed、自定义图片 src 与展示尺寸；自定义图片优先。Agent 默认 Clay，User 默认 Glyphs。生成器随前端本地交付，不请求外部头像 API，Gaze 保持透明背景。
组件支持 style 为 glyphs、clay、shape-grid、gaze；preset 默认为 default，也支持 studio、heritage、soft，每套色卡都有日间与夜间版本。明暗共用主体色，底纸与墨色可独立调整；default 保留各风格上游主体与对比色，夜间仅调整 Glyphs 与 Clay 的底纸，Shape Grid 保留彩色背景。dark 为 on、off、auto，auto 跟随 Yuxi 的主题 Store；circle、square、rounded 分别提供圆形、直角方形和圆角方形。颜色配置由 共享色卡 拥有，几何与表情随稳定 seed 固定。
图片加载或本地生成失败时，Agent 使用 Lucide Bot、User 使用 Lucide User，浅色背景 token 在深浅主题下保持相同。组件通过 fallback 事件提供 image 或 generation 原因。图片地址改变后重新加载；网络恢复只重试失败图片。装饰头像传 decorative，独立头像使用 alt 或 name 提供可访问名称。
Glyphs 使用 Matt Houser 原作的 CC BY 4.0 授权，组件保留 SVG 署名与许可元数据，应用配色、夜间底纸及画布裁切适配；发布包含 头像第三方声明。Clay、Shape Grid、Gaze 美术为 CC0 1.0，DiceBear 核心为 MIT。固定依赖与色卡更新需要核验输出和许可。
知识库、Skill 和工具的图标色由 shared/lib/extensionIconColor.js 按稳定资源身份从预设色卡中选择；浅色底使用当前主题背景混色。知识库使用 kb_id，Skill 使用 slug，图标与颜色在目录卡片和 @ 候选中保持一致。飞书使用本地品牌图标。