Yuxi 产品体验与界面设计规范实战指南：从 Token 体系到 Agent 协作开发

Yuxi 产品体验与界面设计规范实战指南从 Token 体系到 Agent 协作开发【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi本文基于 Yuxi 仓库 docs/develop-guides/design.md 整理面向产品、设计、前端开发者与 AI coding agent完整梳理 Yuxi 的产品体验与界面设计规范产品判断原则、颜色与 Token 体系、字体层级、组件样式、布局间距、深浅色模式、响应式行为与设计交付审阅流程并结合 web/src/assets/css/base.css、web/src/assets/css/base.dark.css、web/src/assets/css/main.css 等源码给出可直接落地的实现参考。读完本文你可以理解 Yuxi 的界面设计决策依据掌握基于现有 token 与组件模式进行新页面、新组件开发的标准流程并能为 AI agent 提供可执行的 UI 开发提示词。0. 产品判断先于界面实现Yuxi 是知识库、知识图谱与 Agent 开发平台界面服务于长时间阅读、配置、调试和数据管理。设计规范的第一条原则是界面不是接口字段的可视化投影。动手画界面之前先回答五个问题目标用户这个界面给谁用主要任务用户在这里要完成什么需要做出的判断用户要基于哪些信息做决策成功与异常状态任务成功、失败、部分成功分别如何呈现哪些信息只是实现细节内部 ID、枚举值、环境变量属于实现细节不该占据界面主体。由此衍生出几条硬性检查标准每个可见元素必须帮助用户识别、选择、判断状态、执行操作或恢复错误否则删除默认用用户语言描述用途、差异和影响内部 ID、枚举和环境变量只在复制、对接或排障时按需展示不同概念不能因为数据结构相同就放进同一列表。不使用服务自动选择这类通常属于策略不是资源项应放在选择器或策略区不能伪装成普通资源项一个页面或分区只解决一个主要问题高级和低频配置使用渐进披露progressive disclosure接口返回了其他后台都有看起来更丰富都不是展示理由。这一原则直接决定了 Yuxi 的信息架构风格摘要层按名称 → 用途或关键差异 → 需关注状态 → 操作组织而不是机械罗列名称、ID、类型和全部状态见设计文档列表、状态与操作一节。1. 视觉气质克制、清晰、工程化Yuxi 的界面设计面向知识库、知识图谱与 Agent 开发视觉上必须保持克制、清晰、工程化不做营销页式装饰。四条核心原则功能优先视觉层级帮助用户理解任务、状态和下一步操作不为装饰牺牲信息密度一致优先相似功能使用相同布局、颜色、状态和交互反馈轻量优先用背景、边框、字号和留白建立层级避免重阴影、夸张渐变和非功能性动效可维护优先新增样式必须基于现有 token 和组件模式不为单次需求引入新的设计体系。2. 颜色与 Token 体系颜色必须优先使用 web/src/assets/css/base.css浅色模式 token和 web/src/assets/css/base.dark.css暗色模式 token中定义的 CSS 变量。组件中不应随意新增硬编码色值确需新增全局色值时先补充 token 并说明用途。2.1 主色表达当前选择、主要操作、关键入口--main-*与--main-color用于品牌主色与关键交互。从 base.css 可以看到完整刻度Token使用场景--main-color主按钮、选中态、重点链接、关键图标基准值var(--main-700)即#046a82--main-700/--main-600/--main-500主色文字、hover、active、强调状态--main-50/--main-30/--main-10主色浅背景、选中行背景、轻量提示背景规范强调主色只用于表达当前选择、主要操作、关键入口不要把主色当作普通装饰色铺在卡片或大面积背景上。2.2 辅助色暖金色系点缀--second-*是暖金色辅助色系基准--second-500为#c9983c刻度与--main-*对齐--second-color为语义入口var(--second-600)。辅助色只用于少量点缀徽标、装饰性视觉元素不能替代主色表达交互状态也不与语义色混用。2.3 中性色默认界面骨架--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在 base.css 中映射为--gray-1000、--dark-70、--dark-50。组件内优先选语义变量需要更细层级时再使用--gray-*。2.4 语义色只用于状态和反馈Token 组使用场景--color-success-*成功、已完成、连接正常--color-error-*错误、危险操作、删除、失败--color-warning-*警告、待处理、需要注意但未失败--color-info-*信息提示、说明性状态--color-accent-*少量辅助强调不能替代主色以 base.css 为例五档色阶从-10极浅到-900最深例如--color-success-50: #e6f7e6、--color-success-700: #389e0d暗色模式在 base.dark.css 中反转刻度如--color-success-50: #162312、--color-success-700: #73d13d。状态标签建议使用浅背景 深文字例如background: var(--color-success-50); color: var(--color-success-700);。注意不要只依靠颜色传达状态必要时配合文字或图标。2.5 图表色与暗色模式图表和统计可视化优先使用--chart-palette-*浅色 10 色在 base.css暗色变体在 base.dark.css。不要复用错误色、警告色做普通图表分类避免与状态反馈混淆。Yuxi 通过:root.dark覆盖同名 token 实现暗色模式。新增 UI 必须使用 CSS 变量禁止固定浅色值并检查浅色、暗色两套表现背景、卡片、输入框不出现纯白硬编码导致的暗色穿帮文本和边框在暗色模式下仍有足够对比度hover、focus、disabled、selected、error 等状态在暗色模式下可辨认图表、代码块和第三方组件需要显式传入 theme 时使用useThemeStore()的现有模式。主题切换的底层实现在 web/src/stores/theme.js通过updateDocumentTheme()给document.documentElement添加/移除darkclass同时把 Ant Design Vue 的theme.darkAlgorithm传入currentTheme并在 web/src/App.vue 通过a-config-provider :themethemeStore.currentTheme全局应用。3. 字体与文本层级全局字体栈定义在 web/src/assets/css/main.css-apple-system, BlinkMacSystemFont, Noto Sans SC, Roboto, HarmonyOS Sans SC, Segoe UI, Helvetica Neue, Arial, sans-serif。新增组件不要私自引入新字体代码、命令、路径和技术标识可使用 monospace优先复用现有mono-font或系统 monospace 栈。建议层级角色建议样式使用场景页面标题20-24px600页面主标题、弹窗主标题分组标题16-18px600卡片标题、表单分组标题正文14-15px400常规说明、列表内容辅助说明12-13px400helper text、元信息、时间、统计说明标签/状态12px500tag、chip、状态徽标代码/路径12-14pxmonospace文件路径、命令、代码片段文本规范标题要短优先描述对象不写营销式口号按钮文案使用明确动作如保存配置重新检测删除文件危险操作必须让文案直接表达后果如删除知识库不使用 placeholder 替代表单 labelplaceholder 只做输入示例不使用负字距或按视口宽度缩放字体避免宽屏和小屏出现不可控排版。4. 组件样式4.1 技术栈约束包管理器pnpm图标库优先使用lucide/vue样式语言LESS颜色变量使用base.css/base.dark.css中的 CSS 变量UI 基础复用 Ant Design Vue 和项目现有组件模式避免为单次需求封装新组件体系4.2 按钮按钮应按操作优先级区分类型使用场景样式规则主按钮页面主操作、确认提交使用主色背景或 Ant Design primary不在同一区域放多个主按钮次按钮返回、取消、普通操作使用中性边框和浅背景hover 只增强边框或背景文本/链接按钮表格行内操作、轻量入口保持轻量不扩大视觉权重危险按钮删除、撤销、清空等不可逆操作使用 error 语义色并配合确认弹窗或明确文案图标按钮工具栏、折叠、刷新、复制使用lucide-icon-btn保证图标与文本居中交互状态约束hover 可以改变background、border-color、color不要位移或放大focus 必须可见不能移除键盘焦点样式disabled 使用弱化文本和背景不绑定 hover 强反馈loading 应保留按钮宽度避免布局跳动。lucide-icon-btn在 main.css 中实现为display: inline-flex; align-items: center; justify-content: center; gap: 6px;并兼容.ant-btn见 main.css。它在仓库中有 30 处组件使用如 BasicSettingsSection.vue、SettingsModal.vue、McpEnvEditor.vue 等是图标按钮的标准模式。4.3 输入框与表单表单用于配置和管理任务优先保证可读性和错误可恢复输入框背景使用--gray-0或 Ant Design 默认容器色边框使用--gray-150/--gray-200focus 使用主色或框架默认 focus ringlabel 必须稳定显示helper text 放在输入框下方错误信息使用--color-error-*并写清楚修复方式多字段表单按逻辑分组避免把无关设置塞进同一行参数名称应说明业务含义和单位非显然参数补充调整影响、推荐范围或示例只允许用户修改真正属于业务配置的值。官方端点、内部枚举和部署参数由系统管理不伪装成普通输入项。4.4 卡片、列表与表格Yuxi 的信息界面以配置卡片、列表和表格为主默认使用轻量分层普通卡片background: var(--gray-0); border: 1px solid var(--gray-150); border-radius: 8px;次级区域可使用var(--gray-10)/var(--gray-25)做轻背景点击态列表行hover 只改变背景或边框不使用transform表格行内操作保持紧凑避免每行出现多个高权重按钮空状态要说明当前没有什么和下一步可以做什么不要只显示图标。阴影只用于真实浮层弹窗、抽屉、下拉菜单、tooltip。普通卡片和列表不要用阴影制造装饰性层级。例如 BasicSettingsSection.vue 中卡片使用border: 1px solid var(--gray-150); background: var(--gray-0);hover 仅增强到var(--gray-100)边框。列表、状态与操作的组织规则摘要层按名称 → 用途或关键差异 → 需关注状态 → 操作组织内部 ID 默认隐藏确需展示时放入详情使用 monospace 和明确标签或复制入口一个状态只保留一种主要表达开关已表达启用状态时不再增加绿色点和已启用文字正常状态保持安静只突出异常和需要行动的状态颜色不能作为唯一信息载体开关默认表示立即生效需要统一保存时明确显示未保存状态不混用两种提交模型同类行共享稳定的展开、文本、状态和操作列图标使用固定盒、统一gap和line-height配置列表优先使用一个列表容器和轻分割线避免每行形成厚重卡片展开内容与触发行保持连续至少在真实页面的目标宽度、1024px、768px 和 375px 检查对齐、长文本和溢出。4.5 状态标签状态标签使用语义色浅背景 深文字状态推荐 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 圆角999px但不要把 pill 形状扩散到所有按钮和卡片。4.6 图标常规图标尺寸使用 16px、18px 或 20px图标颜色默认继承文本色需要强调时使用语义 token图标按钮添加lucide-icon-btn避免图标与文本或按钮中心线错位不为同一概念混用多个图标相同操作在不同页面保持一致。5. 布局与间距间距以 4px / 8px 为基础节奏场景建议值图标与文本间距6px / 8px表单项内部间距6px / 8px卡片内部 padding16px / 20px / 24px列表行间距8px / 12px页面主要区块间距24px / 32px弹窗内容区间距16px / 24px布局原则配置型页面保持适度信息密度不做大面积营销式留白相邻操作靠近对应内容页面级操作放在标题区或工具栏一组按钮中主操作在视觉上最明确取消/返回等次操作弱化宽屏下限制正文行长避免说明文字横跨整个页面小屏下优先纵向堆叠避免强行压缩表格和表单字段。6. 深度与层级背景 边框的轻量体系层级处理方式使用场景页面背景var(--gray-0)或布局已有背景主页面次级背景var(--gray-10)/var(--gray-25)分区、弱提示、列表 hover卡片边界1px solid var(--gray-150)8px 圆角配置卡片、内容块浮层框架默认阴影或轻量--shadow-*弹窗、抽屉、dropdown、tooltip焦点主色 outline / Ant Design focus ring键盘可达控件不要在普通内容卡片上使用重阴影。只有当元素真实覆盖其他内容、需要表达浮层关系时才允许使用阴影。--shadow-*体系在 base.css 中定义为 0~5 六档透明度递进暗色模式在 base.dark.css 中反转。7. Do / Dont 速查Do使用base.css和base.dark.css中的 token为新增交互补齐 hover、focus、disabled、loading、empty、error 等必要状态用背景、边框、字号、间距建立层级保持浅色和暗色模式一致可用复用lucide/vue、Ant Design Vue 和项目已有组件模式在复杂配置区保留简短说明帮助用户理解设置影响。Dont不要在 hover 时使用位移、放大、旋转等装饰性 transform不要使用浓重阴影装饰普通卡片不要使用夸张渐变或大面积高饱和背景不要把语义色用于纯装饰不要新增一次性 helper、样式体系或无复用价值的抽象不要硬编码浅色模式色值导致暗色模式失效不要在同一区域放置多个同等视觉权重的主操作。8. 响应式行为响应式设计以功能不丢失、信息不挤压为优先小屏下表单字段纵向排列按钮组可换行侧栏、抽屉和弹窗要保证最小宽度内内容可读表格在小屏下允许横向滚动不要把关键字段压缩到不可读图标按钮和主要操作需要保持可点击区域移动端目标尺寸尽量不小于 40px长文本使用省略号时应提供 tooltip、title 或详情入口查看完整内容图谱、图表、代码块等宽内容应保留横向滚动或自适应缩放策略。从 base.css 可以看到响应式 token 的实际做法--page-padding在 767px 以下从 18px 调整为 14px通过媒体查询覆盖 token而不是到处写死间距。9. 设计交付与审阅流程UI/UX 质量不能只由构建通过和没有溢出证明。交付前按三层审阅产品层每个元素是否有价值概念是否符合用户心智是否暴露无用实现细节交互层操作是否可发现生效时机是否明确失败能否恢复状态是否一致视觉层层级、对齐、间距、文字、图标、颜色和响应式是否精确一致。UI 修改必须提供真实运行页面截图覆盖核心状态和至少一个边界状态。使用真实数据检查长名称、加载、错误、空状态、浅色/暗色和关键响应式宽度未验证内容在交付说明中列出。10. Agent Prompt Guide让 AI agent 产出合规 UIAI agent 修改或生成 Yuxi UI 时优先按本规范执行。以下内容可直接用于提示词或作为开发者的审查清单。Quick Reference速查页面背景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卡片 padding16px/20px/24px普通 hover只改变背景、边框或文字颜色Example Prompts可直接复用实现配置卡片实现一个 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 接口、组件位置、样式语言符合前端开发规范已在真实页面和关键响应式宽度截图验收而不只依赖构建通过。参考资料docs/develop-guides/design.md本文档依据的产品体验与界面设计规范原文web/src/assets/css/base.css浅色模式 token主色、辅助色、中性色、语义色、图表色、阴影web/src/assets/css/base.dark.css暗色模式 token:root.dark同名覆盖web/src/assets/css/main.css全局字体、布局基础样式和lucide-icon-btn工具类web/src/stores/theme.js主题切换 store控制:root.dark与 Ant Design 主题算法web/src/App.vue全局a-config-provider :themethemeStore.currentTheme应用主题组件示例BasicSettingsSection.vue、SettingsModal.vue、McpEnvEditor.vue。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考