管理界面设计依据

UG Admin 使用 UG UI 的公开组件、语义 Token 和密度配置。视觉调整先说明信息与操作的关系，再选择布局、表面和状态；不以临时 CSS 拼出另一套组件外观。基础尺寸、颜色、浮层和主题由 ../ug-ui/docs/DESIGN_SYSTEM_CONTRACT.md 维护；管理字段与行为见 基础管理合同。

参考与本地采用

设计先解决用户任务、信息和操作，再落到组件、尺寸和配色。UG 保留自己的组件、可访问性合同及 React/Vue 原生实现；参考来源不意味着引入其运行时。

官方依据	UG 采用的规则
RuoYi-Vue 官方说明	用户、角色、部门和字典的成熟管理流程与页面组合是主参考；固定具体前端版本，不混同 Vue2/Element UI 与 Vue3/Element Plus。
腾讯：如何搭建整体框架	先确定模块关系与导航，再选列表、表单和详情布局；壳层导航与页面任务各有职责。
腾讯：如何设计高频任务	明确筛选的生效时机，按操作频率区分常驻与选择后出现的批量动作，保持完整任务反馈。
Ant Design：数据列表	围绕扫读和查找组织列表，明确筛选、表格及批量操作之间的关系；选择表格或卡片取决于任务。
Ant Design：亲密性	同一字段的标签和控件紧邻，相关操作成组，组间距离大于组内距离。
Ant Design：字体	正文以易读且克制的字阶、字重组织；只强调重要信息，避免每行姓名都成为粗黑标题。
Element Plus：中文设计原则	基础控件与交互一致，信息让用户直接识别，操作反馈明确，允许取消与恢复。

RuoYi/Element 是管理操作与基础控件的主参考；TDesign/Ant 用于解释布局和信息组织，不能把几套模板的外观、间距和动作规则随意混拼。官方示例通过原站或原始截图查看，不用自制 HTML 近似图代替原版。UG 的列表直接衔接页签，保留用户选定的平面工作区；这不意味着所有内部留白归零或所有内容铺成相同强调程度。

中文经验文章可辅助查漏：《B端表格设计技巧大全》 分析数据过滤、操作与查看；《B端网页设计规范全方位汇总》 梳理栅格和间距。它们分别发布于 2023、2019 年，具体尺寸与经验结论要结合官方规范和实际任务判断，不当作强制标准。

先明确任务与视觉主次

用户管理的代表任务是：定位部门或输入条件 → 找到目标用户 → 查看身份和状态 → 修改资料或分配角色 → 保存并确认结果。布局、信息列和操作必须服务这条路径。

• 导航回答“在哪里”，筛选回答“看哪些人”，表格回答“他们是谁、什么状态”，操作回答“能对谁做什么”。每个区域先说明职责，再安排视觉强弱。
• 名称、账号、所属部门是身份信息；名称和账号的详情入口要统一且清楚。蓝色文字承诺可操作，点击结果必须符合文字含义，不能只为装饰给一整列上色。
• 字重以正文和轻强调为主，标题/分组才承担较强强调；正文、辅助信息和禁用态保持可读区分。统一不等于每行、每列同样醒目。
• 辅助图标要让用户识别用途。常用但含义不明确的动作优先显示文字；图标按钮需要可见提示和可访问名称，不能把 Tooltip 当作所有操作的唯一说明。
• 默认先展示高频条件；低频条件按需展开。统一控件高度、标签关系和间距，同类字段宽度一致；日期范围按完整内容单独预算，不为机械等宽压缩两个日期。
• 草稿与已生效条件要可区分。提交式与即时式筛选可以服务不同任务，但各自生效规则必须明确；组织范围、查询摘要、重置和批量操作不能让用户猜测当前作用对象。

工作区与层级

• 壳层导航、页面标签、查询、操作、数据和分页各有职责。活动标签与当前内容使用连续的表面，不让标签看起来浮在内容之上。
• 列表直接衔接壳层工作区，不在整页外再包 Card，不重复增加圆角、外框、阴影和四周边距。
• 普通内容面保持平面；明确需要突出的一张卡片使用公开 elevated 变体。短菜单/候选列表与模态弹窗使用各自共享浮层层级，业务不覆写阴影。
• 表面、文字、边界、选中及焦点由语义 Token 决定。主色表示当前入口、链接及主要动作；危险色用于危险操作与错误，状态色用于状态，不能把整行随意染色来制造层级。
• 暗色同时检查浮层表面、边界与文字对比；z-index 只决定遮挡顺序，不能代替可见层级。

信息与操作的布局

• 查询字段采用统一标签对齐、控件尺寸和有界宽度；宽屏增加可用空间，不无限拉长短字段。空间不足时整组换行，不拆散标签与控件。
• 主要创建动作清楚可见。选择、修改和删除遵循权限与当前选择状态；筛选条件放在查询摘要，不混入 CRUD 操作组。
• 刷新、列设置、搜索显隐与组织栏显隐属于辅助操作，保持相同命中尺寸、可访问名称和键盘焦点。
• 固定格式的排序值、状态、电话、日期和操作列使用内容预算；名称、账号、说明及权限等可变内容承接剩余宽度。隐藏列释放的空间优先用于有用信息，不撑大复选框、序号或短状态。
• 表格在自身区域滚动，分页保持可达；长文本允许按公开列规则省略或换行，不能撑宽整页。只有少量记录时保留真实空白，不造数据或装饰卡片填满页面。
• 组织树保持可读行高、层级缩进与独立展开入口。拖拽宽度、搜索及收起后的恢复入口持续可用。

横向排布与表格可视空间

• 默认先利用当前内容容器的横向空间：同组短字段、状态、数量与操作能清楚排在一行就排一行，不因为代码里分了组件或区域就各占一整行。壳层侧栏、组织树和抽屉占用后的实际宽度才是依据，不能只看屏幕分辨率。
• 查询标签与控件保持一组，查询、重置等动作优先同行；CRUD 主动作与刷新、列设置等辅助动作可在同一栏左右分组。需要不同语义分组不等于必须拆成多条横栏；条件摘要与选中数量仅在有内容时出现，不留空白行。
• 控件按内容设置合理且有上下限的宽度，短状态不占大段空白；日期范围、长值与必要提示要有足够空间。先检查不必要的 width: 100%、整行占位和过大间距，再决定换行；不为对齐而强制所有字段等宽。
• 表格页把主要可视高度留给数据，减少重复标题、说明、套层留白和无意义的上下堆叠；表格使用公开填充能力承接剩余高度，分页可达。不要用固定的大块空白、随意压缩行高或隐藏必需信息换取表面紧凑。
• 确实放不下时按字段或操作组自然换行；低频条件可按任务需要折叠，并保留发现入口和已生效状态。窄屏也先判断真实空间，不机械地把所有元素改成整行。长说明、错误反馈、复杂编辑和阅读正文可以独占一行；不得靠极小字号、缩小命中区域、全局禁止换行或整页横滚硬塞。
• 开发前明确主内容、常驻操作和可换行组；交付前按实际影响核对是否仍有“有横向余量却多占一行”、空白栏和重复说明，以及表格是否得到剩余空间。

验收方法

视觉方向先在真实用户管理页收敛，再同步到角色、部门和字典，不在方向未清楚时同时扩展全部页面。先比较官方参考与实际页面的阅读顺序、分组、字重、配色和操作含义，再用几何检查定位具体偏差。

独立检查者除相关行为外，还要回答：是否容易找到目标用户和主要操作；是否看得出当前部门与生效条件；能否理解名称/账号点击结果及图标用途；新增、编辑、详情的字段顺序是否一致；弹窗与列表的注意力层级是否清楚。给出实际截图和判断依据，不能只报告断言通过或 P1/P2 数量。

按改动选择受影响的 React/Vue 页面和状态；亮暗、窄宽、长文字、较多记录、键盘和错误是覆盖维度，不要求每次间距微调重跑全部组合。定向与完整验证的选择见 完成检查。

自动化负责防回归，实际任务检查负责发现体验问题，用户反馈决定视觉方向是否合适。技术回归通过不能写成用户已经认可设计；用户否定视觉时重新审视基准与方案，不用旧测试结果反驳。独立实际检查在代表方案收敛后进行，不重复作者的全量构建和测试。

手机端形态约定

三档视口的形态由 packages/admin-core/src/config/viewport.ts 与 table-mode.ts 决定，页面不得自行判断屏幕：

区域	手机（< 48rem）	平板 / 桌面
列表数据	卡片（.admin-record-card），强调列取描述里的 primary	表格
表格形态切换	默认卡片，可切横向滚动（resolveAdminTableMode）	横向滚动
列表筛选	收起，靠搜索区内的「更多筛选」展开	常驻，工具栏「更多筛选」控制高级条件
详情 / 编辑	抽屉整屏（UGDrawer 内置 48rem 以下整屏）	侧边抽屉，按 size 限宽
批量操作条	吸底并留出 safe-area-inset-bottom	常规流式
触控目标	不小于 44×44 像素（卡片操作区最小高度已约束）	常规尺寸
部门树	保持树形表格与横滚，不做卡片化（层级比卡片更重要）	树形表格

新增页面时按此表选择形态；断点写法见开发指南「响应式断点」，门禁 check:responsive 会拦截裸写数值。

样式边界与语义变量

• 后台所有类名限定在 admin- 命名空间，避免污染宿主页面；check:styles 强制。
• 业务样式只引用 --admin-* 语义变量；UG UI 的原始 token 只在 packages/admin-core/src/styles/tokens.css 映射一次。
• 消费方要调整尺寸、圆角、配色或触控目标时，覆盖 --admin-* 即可，不必覆盖具体组件选择器：

:root {
  --admin-gap: 1.25rem;
  --admin-accent: hsl(212 92% 45%);
  --admin-touch-target: 3rem;
}

卡片形态的覆盖范围

窄屏默认卡片，宽屏保持表格，由 resolveAdminTableMode 按“框架默认 → 项目配置 → 页面配置”解析。当前覆盖：

页面	卡片内容	说明
用户列表	主列 + 邮箱 + 状态 + 行操作	双端
部门列表	名称（按层级缩进）+ 负责人 + 状态 + 编辑	双端，树形用缩进表达
字典类型 / 字典条目	名称 + 编码/条目值 + 行操作	双端，共用一个资源页组件

新增列表页沿用 RecordCardList（React 在 src/app/RecordCardList.tsx，Vue 在 src/app/RecordCardList.vue），不要另写一套卡片结构。