前端设计基线
概览
本页将 https://shadcnuikit.com/dashboard/ 固化为本仓库未来前端工作的默认视觉参考。
这里固化的是一套设计语言与页面模式，不是对外部站点的逐像素复制。目标是让项目内的管理后台、控制台、配置页、运营页，以及其它偏工具型前端入口，长期保持一致的结构、密度与视觉气质。
参考来源
- 主参考站点：
https://shadcnuikit.com/dashboard/ - 参考快照日期：
2026-03-19 - 固化方式：
- 仓库级规则：根目录
AGENTS.md admin-frontend子项目规则：admin-frontend/AGENTS.md- 正式文档：当前页面
适用范围
以下场景默认直接采用本基线：
- 管理后台
- 运维控制台
- Agent 配置与调试页面
- 数据看板
- 评测、知识库、MCP、对话审查等高信息密度页面
以下场景可以裁剪布局，但仍应继承本基线的视觉语言：
- 对话页
- 嵌入式工具页
- 辅助工作台
不在本基线之内的场景：
- 明确的营销官网
- 活动落地页
- 品牌宣传页
核心设计原则
1. 控制台优先，而不是营销页优先
默认把页面做成可操作、可扫描、可管理的工作台。页面应服务于配置、监控、编辑、筛选、对比和排障，而不是服务于宣传叙事。
2. 信息密度高，但秩序必须更高
允许页面同时出现统计卡片、筛选器、表格、图表、状态徽标和详情区，但必须通过统一的间距、边框、标题层级和卡片分组建立秩序。
3. 中性、克制、专业
优先使用浅灰背景、白色 surface、细边框、轻阴影和低饱和强调色。大部分层级应来自：
- 空间分隔
- 文字粗细与字号
- surface 对比
- 边框与分组
不应依赖夸张渐变、大面积品牌色或重装饰。
4. 页面结构先统一，再做局部创新
新页面应先套用共享布局原语，再讨论局部视觉升级。不要为单个页面重新发明一套 shell、header、drawer 或 card 系统。
页面结构模式
默认页面骨架应接近以下结构：
- 左侧持久导航
- 顶部或页内标题区
- 多 surface 的主内容区
- 右侧辅助信息区或 overlay 流程
推荐的内容编排方式：
- 标题区：标题、副标题、状态、主操作、二级操作
- 第一屏：关键指标卡片、摘要状态、全局筛选
- 主体区：表格、图表、活动流、配置分组
- 详情编辑：优先使用 drawer 或 dialog
视觉语言
背景与 Surface
| 元素 | 推荐方向 |
|---|---|
| 页面背景 | 浅灰或近白背景，避免纯黑或大面积高饱和色 |
| 内容卡片 | 白色或近白 surface，边框清晰，阴影轻 |
| 分组容器 | 通过 surface 与边框建立层级，不依赖复杂纹理 |
| Overlay | 采用 drawer、dialog 等明确层级，不做悬浮碎片化面板 |
颜色
| 类型 | 规则 |
|---|---|
| 主色 | 用于主按钮、关键状态或少量强调 |
| 中性色 | 作为页面主体，优先承担大部分视觉面积 |
| 状态色 | 仅用于 success、warning、danger、info 等语义表达 |
| 禁止项 | 避免每个页面单独引入一套品牌色或渐变体系 |
字体与层级
- 优先使用现代无衬线字体体系。
- 当前仓库已出现的
Geist、Manrope、Plus Jakarta Sans可以作为优先选择。 - 页面标题、区块标题、正文、辅助说明要有稳定层级，不要在不同页面频繁改字号体系。
圆角与阴影
- 圆角保持小到中等，强调“精致控制台”，不要过大。
- 阴影应轻，主要用来区分层级，不用来制造戏剧化漂浮感。
组件模式
以下组件模式应优先复用和组合：
- 指标卡片
- 数据表格
- 状态徽标与标签
- Tabs
- 筛选器栏
- Drawer / Dialog
- 表单分组
- 活动流与事件列表
推荐做法：
- 主操作放在页面标题区或卡片标题区。
- 表单按任务分组，不用超长无分隔大表单。
- 表格行操作清晰、固定、可预测。
- 状态标签语义明确，颜色服务于状态而不是装饰。
注册表页面模式
对 Agents、Knowledge Sources、MCP Servers 这类“资源注册表”页面，推荐采用同一套结构：
- 页面标题区
- 首屏摘要卡
- 过滤与统计卡
- 主注册表内容
- 右侧辅助 rail
- create 或 edit drawer
页面行为规则：
- 主列表或主卡片网格始终保持稳定，不因 create 或 edit 打开而跳动。
- create、edit、test 等高密度交互进入 drawer，而不是回插到页面流中。
- rail 用于最近更新、策略分布、操作提示、快捷入口等辅助信息。
- 摘要卡回答“总量、活跃量、健康度、覆盖度”这类一眼要看到的问题。
如果一个页面同时承担“浏览”和“创建”两件事，优先保证浏览面稳定，再用 overlay 承接创建流程。
队列与治理页面模式
对 Conversations、Scheduled Tasks、Document Recognition 这类“队列 / 处置”页面，以及 Administrators、Audit Logs、System Settings 这类“治理 / 策略”页面，推荐采用更明确的控制台工作面：
- 页面 masthead
- 首屏 stat strip
- 固定 toolbar
- 稳定 primary data region
- 右侧 posture / policy rail
页面行为规则：
- 队列页优先回答“现在谁需要处理”“压力在哪”“哪些对象正在被人工接管”。
- 治理页优先回答“谁有权限”“哪些事件异常”“当前是否允许写入与变更”。
- toolbar 承载 search、quick filters、mode 切换，不要把筛选器散落进多个卡片。
- 主数据区应保持稳定：事件流、注册表表格、设置表格不要因说明文案或辅助信息跳动。
- rail 用于放 posture、policy、write safety、最近异常、操作说明等辅助信息，而不是替代主内容。
- challenge 验证、敏感编辑、配置写入等高密度动作进入 dialog / drawer，不回插到主页面流。
详情工作区页面模式
对 Evaluation Dataset Detail、未来的 Knowledge Source Detail、Agent Detail 这类“实体详情 + 高频操作”页面，推荐采用另一套稳定结构：
- 页面标题区与状态徽标
- 首屏摘要卡
- 主详情快照卡
- recent runs / preview / history 等稳定主内容
- 右侧 readiness rail 或操作提示 rail
- import / freeze / launch / test 等 drawer
页面行为规则：
- 主详情信息、近期运行记录、预览表格应保持在主内容区，不因操作面板打开而跳动。
- import、freeze、launch、test 等高密度操作进入 drawer，而不是插回主页面流。
- 摘要卡应优先回答“当前是不是可运行”“最近运行状态如何”“这个实体现在处于什么生命周期阶段”。
- rail 用于 readiness checklist、最近活动、操作约束、流程说明等辅助信息。
- destructive action 可以保留在 header，但不应破坏主内容稳定性。
双前端协作模式
当一个能力同时包含“高频操作工作台”和“运营监控控制台”时，默认采用双前端分工，而不是把所有行为都塞进 Admin：
demo-frontend或专用工作台承载主交互流程admin-frontend承载概览、筛选、队列、详情和跳转
适用判断：
- 如果页面包含密集字段编辑、逐项审核、源文档对照、bbox 联动等高操作成本行为，应优先放在专用工作台。
- 如果页面目标是总览健康度、排队情况、异常定位、运营分发，则应保留在 Admin 控制面。
单证识别页面作为参考案例
Document Recognition 是当前仓库的标准案例：
- Demo 端提供 drag/drop、paste、图片/PDF 输入、源文档预览、字段审核与修正
- Admin 端提供 KPI cards、筛选 toolbar、run queue、detail rail，以及跳转到 Demo 审核
这类页面的设计规则：
- Admin 页面先回答“量、状态、异常、谁需要处理”
- 主操作动作放在 Demo 工作台，而不是在 Admin 表格中内嵌复杂编辑器
- Admin 详情区优先做只读摘要、问题列表、最近审核信息与跳转动作
- 如果用户需要连续处理多字段或对照源文档，应离开 Admin，进入专用工作台
与现有实现的对应关系
admin-frontend 已经有与本基线相兼容的布局原语，后续页面应优先沿用：
| 现有原语 | 作用 |
|---|---|
AdminShell |
控制视口、导航区和主内容滚动归属 |
AdminPageFrame |
统一 header、primary、rail、overlay 槽位 |
AdminPageHeader |
统一标题、副标题和操作区 |
AdminSurfaceCard |
统一主内容卡片 |
AdminDrawer |
承载 create、edit、test 等高密度流程 |
admin-frontend/studio 当前将这套基线进一步固化为 Studio 侧共享原语：
| Studio 原语 | 作用 |
|---|---|
StudioMasthead |
统一页面标题区、副标题、状态徽标与顶层摘要 |
StudioStatGrid |
统一首屏指标带，不让每页重新发明 KPI 排布 |
StudioToolbar |
统一 search / filter / mode / summary 的固定工具条 |
StudioDataLayout |
统一 primary data region 与 right rail 的双栏关系 |
StudioPanel |
统一白色 surface、标题、说明与内部内容分组 |
实现原则：
- 能复用共享原语时，不新增 page-only 顶层布局。
- 能扩展现有 CSS token 时，不新增随机局部 token。
- 页面视觉升级优先落在共享组件和 token，而不是只修单页。
多前端挂载约束
后续如果需要新增第二套或第三套 Admin 前端，默认遵守以下规则：
- Studio 作为主 Admin shell 固定占用根路径
/。 - 新增 Admin 前端一律使用独立子应用目录，例如
admin-frontend/ops-console/。 - 新增 Admin 前端一律挂在独立子路径，例如
/ops/、/console/，不要再次争用根路径/。 - 共享认证、API 契约、类型和领域逻辑继续沉淀在
admin-frontend/shared/。 - 不要把“切换谁占根路径”当成普通前端调整；这属于路由契约迁移，会同时影响构建、Nginx、E2E、本地运行时和文档。
禁止项
以下模式默认视为偏离基线：
- 把后台页面做成官网 hero 风格
- 使用夸张玻璃拟态、重 blur、重阴影
- 大面积高饱和渐变作为主背景
- 每个页面单独发明一套 header、toolbar、card 样式
- 把 create 或 edit 大表单直接塞回主页面流顶部
- 用装饰性图形替代真实信息层级
实施检查清单
提交前至少检查以下问题：
- 这个页面看起来像控制台，而不是落地页吗？
- 是否优先复用了共享布局原语？
- 主要层级是否来自 spacing、border、surface，而不是装饰噪音？
- 主操作是否放在稳定位置？
- 高密度表单是否进入 drawer 或 dialog？
- 是否引入了新的视觉 token？如果有，是否值得抽到共享层？
- 若基线被扩展或修改，是否同步更新了本文档与相关
AGENTS.md？