布局与主题

目标：让新增页面自然融入现有后台，在深色、窄屏和不同布局下保持一致。

使用同一个布局状态

createUAdmin 通过 provider 将会话、导航、标签页和偏好交给 @uadmin/layout。演示的 apps/demo/src/layout/AppLayout.vue 只增补右上角操作，不再实现第二套侧栏。

import { usePrefsStore } from '@uadmin/app'

const prefs = usePrefsStore()
prefs.setThemeMode('dark')
prefs.setThemeMode('system')
prefs.setLayoutMode('compact')
prefs.setDirection('rtl')

主题模式支持 light、dark、system。resolvedTheme 始终是实际浅色或深色，系统主题变化时自动更新。布局偏好落在 uadmin_prefs，无需业务再次持久化。

页面先使用页面壳

<script setup lang="ts">
import { UPage } from '@uadmin/ui'
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
</script>

<template>
  <UPage :title="t('reports.title')">
    <slot />
  </UPage>
</template>

选择页面滚动还是内容区滚动时，参照 UPage 和演示同类页面。表格页、聊天页不必采用相同滚动结构，但标题、内容间距应复用既有能力。

语义颜色与覆盖顺序

优先复用组件和现有主题变量，如 --u-text、--u-text-muted、--u-surface、--u-border。新增局部样式使用 scoped，避免全局覆盖所有 .el-button 或 .el-table。

@uadmin/ui 加载 Element Plus 基础样式、暗色变量和主题桥接。不要在应用入口之后重复引入 Element Plus 全量样式；颜色错乱时先看样式顺序，而不是给页面添加更多 !important。

向顶栏贡献操作

业务模块的 slots['header.actions'] 可以提供组件，也可以提供 { component, order, perms }。布局使用 <UAdminSlot name="header.actions" />，内核按模块启用状态与权限筛选。

真实例子是 apps/demo/src/modules.ts 的 helpCenterModule，组件在 src/views/help-center/HelpHeaderButton.vue。需要跨页面的业务入口优先使用扩展点，页面私有按钮留在页面内。

样式验收

至少检查浅色、深色、窄屏、较长英文文案和键盘焦点。若页面横向溢出，先查固定宽度与表格容器；若主题切换只影响部分组件，检查是否绕过 usePrefsStore 或在页面中写死背景色。布局注入警告则按独立接入排查重复依赖。