布局、主题与配置

项目的视觉系统不是由单个颜色变量组成，而是由系统配置、Pinia 用户设置、主题定制器、CSS Token 和 Element Plus 主题共同驱动。修改主题时应先判断属于“默认配置”“用户运行时偏好”还是“底层设计 Token”。

配置入口

文件	适合修改的内容
`src/config/index.ts`	系统名称、商业入口、可选布局、主题列表和主色
`src/config/setting.ts`	默认布局、主题、圆角、标签页和功能开关
`src/config/modules/theme-studio`	主题预设、基础色板、图表色板和定制状态
`src/store/modules/setting.ts`	运行时设置状态、切换方法和持久化
`src/assets/styles/core/tailwind.css`	Tailwind 与项目颜色 Token
`src/assets/styles/core/app.scss`	应用级基础样式和容器规则
`src/assets/styles/core/el-ui.scss`	Element Plus 主题覆盖

布局模式

src/config/index.ts 当前提供：

布局	枚举	特点
双列菜单	`DUAL_MENU`	一级与二级菜单分栏，适合模块较多的系统
左侧菜单	`LEFT`	经典中后台布局
顶部菜单	`TOP`	横向导航，适合一级模块较少的系统
混合菜单	`TOP_LEFT`	顶部一级菜单 + 左侧子菜单
悬浮菜单	`HOVER_MENU`	左侧入口悬浮展开子菜单
侧边栏	`SIDEBAR`	更紧凑的侧边导航方式

默认布局在 src/config/setting.ts：

export const SETTING_DEFAULT_CONFIG = {
  menuType: MenuTypeEnum.DUAL_MENU,
  menuOpenWidth: 220,
  menuOpen: true,
  dualMenuShowText: false,
  dualMenuAutoHide: false,
  // ...
}

修改默认值只影响首次进入或清理设置后的状态。已经使用过系统的浏览器可能仍从 Pinia 持久化恢复旧设置。

主题模式

系统支持：

亮色主题。
暗色主题。
跟随系统。
多组系统主色。
边框模式与阴影模式。
运行时圆角调整。
基础色板、语义色和图表色定制。

默认主色是 #377DFF。主题切换会同时影响项目 Token、Tailwind 颜色和 Element Plus 变量，业务页面不需要分别维护两套色值。

Token 层级

主题变量大致分为三层：

text

原始主题值 --theme-*
  -> 模式派生值 --default-* / --art-*
  -> Tailwind 主题颜色 --color-*

业务页面优先使用：

项目已有 art-* 容器类。
var(--art-*) 语义变量。
已映射到主题的 Tailwind 类。
Element Plus 组件的主题属性。

不要直接在页面写：

css

.panel {
  background: #fff;
  color: #111;
}

这会在暗色主题下失效。应使用语义 Token：

css

.panel {
  color: var(--art-text-gray-900);
  background: var(--art-surface-bg);
  border: 1px solid var(--art-surface-border);
}

容器层级

项目提供不同密度的容器：

类名	适合场景
`art-card`	页面级主要区域、仪表盘大区块
`art-card-sm`	标准业务卡片
`art-card-xs`	搜索栏、小型信息块和紧凑面板
`art-table-card`	全高列表页的表格宿主
`art-surface-muted`	卡片内部的弱层级区域

不要把页面每一层都做成独立卡片，也不要在卡片内继续嵌套多层卡片。先通过留白、标题和分隔线建立层级，只有独立交互单元才需要容器边界。

运行时设置与持久化

settingStore 会持久化用户的布局、主题、菜单颜色、圆角、标签页、容器宽度和界面开关。常见设置包括：

menuType
systemThemeMode
systemThemeColor
boxBorderMode
customRadius
containerWidth
showWorkTab
showCrumbs
showLanguage
pageTransition
tabStyle

主题设置面板和主题定制器都提供“复制配置”能力，可把当前运行效果转换为 SETTING_DEFAULT_CONFIG，再放回源码作为客户默认值。复制后仍要人工检查品牌色、对比度和移动端布局。

修改默认主题的推荐流程

在运行时设置面板中调整布局、主色、圆角和表面模式。
同时检查亮色、暗色和自动模式。
在主题定制器中检查语义色和图表色。
使用复制配置功能生成默认值。
更新 src/config/setting.ts。
清理当前浏览器的应用命名空间存储或使用重置功能。
重新验证登录页、仪表盘、列表、弹窗、下拉菜单和移动端。

品牌与站点信息

系统名称基础值位于 src/config/index.ts，站点名称、Logo、登录欢迎语等公共信息由 siteSettingsStore 读取。当前默认数据位于：

text

src/mock/system/site-setting.ts
src/mock/system/site-setting-admin.ts

如果客户需要后台动态管理站点配置，应把 siteSettingsStore 的数据来源迁移到真实 API。不要在多个登录页或布局组件中分别硬编码客户名称。

交付客户项目前还要检查：

commercial.enabled
commercial.userMenuEnabled
侧边栏商业授权入口
供应商文档和社区链接

是否保留由授权和交付约定决定。

国际化

界面文案放在 src/locales。路由标题推荐使用语言 key：

meta: {
  title: 'menus.customer.list'
}

新增页面时同步维护中英文 key，并检查：

菜单标题。
页面标题。
搜索字段与按钮。
空状态与错误提示。
Element Plus 语言切换。

不要把客户可配置文案全部写进语言包。产品固定文案属于 i18n，客户运行时可编辑的站点文案属于站点配置。

语言优先级、语言包维护和 Element Plus 文案处理见国际化与通用配置。

常见问题

修改默认主题后没有生效

浏览器仍恢复了旧的 setting Store。使用设置面板重置，或按应用命名空间清理对应存储，不要直接执行 localStorage.clear()。

暗色模式出现白色区域

检查页面是否硬编码 #fff、white 或只定义亮色背景。优先替换为项目表面 Token。

Element Plus 与页面主色不一致

确认使用的是项目统一主题入口，不要在单个页面重新导入 Element Plus 默认 CSS 或创建第二套 SCSS 变量。

移动端菜单遮挡内容

检查是否绕过现有布局组件直接设置菜单宽度、定位或页面高度。响应式菜单行为由布局 Hooks 和菜单组件统一处理。

布局、主题与配置 ​

配置入口 ​

布局模式 ​

主题模式 ​

Token 层级 ​

容器层级 ​

运行时设置与持久化 ​

修改默认主题的推荐流程 ​

品牌与站点信息 ​

国际化 ​

常见问题 ​

修改默认主题后没有生效 ​

暗色模式出现白色区域 ​

Element Plus 与页面主色不一致 ​

移动端菜单遮挡内容 ​