aiDoc/frontend-backend/theme-classnames.md
本文件是项目「主题化 UnoCSS 类名」的唯一参考。凡在 .vue / core/componentLibrary 里写颜色、
背景、描边、阴影，优先用这里的语义 token 类名，不要再散写 bg-white dark:bg-slate-900、
text-gray-500 dark:text-gray-400 这类明暗成对的裸色阶。
--container-bg-color），:root 存亮色值、
html.dark 存暗色值。写一次 bg-container，明暗自动切换——不需要再写 dark: 变体。@simple-prism/core）在 theme/token.js
的 generateTheme 里按当前主色实时求解；用户换主题色 / 换预设时，这些类名的取色一起变。theme/token.js，页面只引用语义名，改配色不用全站搜替换。落地链路：
token.js生成 hex →shared.js转成r g b裸通道写入--x-color变量 →vars.js声明token → rgb(var(--x-color))映射 → UnoCSS 据此生成bg-/text-/border-原子类。
每个语义色各有 11 阶（50 100 200 300 400 500 600 700 800 900 950），另有一个不带阶号的
「裸名」等于该色的 500 阶。
| 类名 | 取色来源 | 明暗表现 | 推荐场景 |
|---|---|---|---|
bg-primary / text-primary / border-primary | 主色种子色（= primary-500） | Prism 把品牌色钉在 500，明暗两态一致，与 --el-color-primary 同源 | 主按钮、选中态、强调色、菜单项高亮实底 |
bg-primary-50 … bg-primary-950 | Prism 明/暗两套 scales.primary 的对应阶 | 同一阶号在亮/暗下各取「该模式的正确色」，不是简单反色 | 需要浅底/深底层次时（如 hover 浅底 primary-50、描边 primary-600） |
*-info *-success *-warning *-error 同上 | 各语义 scales[name] | 同上 | info=信息蓝、success=成功绿、warning=警告黄、error=危险红（删除/登出/校验错） |
要点：
info 默认可「跟随主色」（外观设置里 信息色跟随主色），开启后 info 系列 = primary 系列。50 近乎白、950 近乎黑；暗色场景由暗色 scale 保证观感一致。error（text-error / bg-error / bg-error/10），不要写裸 text-red-500。这一组来自 Prism 的 neutral 色阶（镜像色阶，同一阶号在明暗各给正确色），在 token.js
的 pickSurface 里挑选。只有亮色 container 是字面纯白（neutral 最浅阶仍偏灰，抬升表面需纯白纸感）。
| 类名 | 取色来源（亮 / 暗） | 明暗表现 | 推荐场景 |
|---|---|---|---|
bg-container | 亮=纯白 #fff / 暗=neutral 50（最深面） | 抬升的「纸面」 | 卡片、侧栏、抽屉、下拉浮层等浮在页面之上的容器底 |
bg-layout / bg-main | 亮=neutral 50 / 暗=neutral 100 | 比 container 低一层的画布 | 整体页面背景、内容区画布（bg-main 是 bg-layout 的别名） |
bg-muted | neutral 100 | 弱化底 | 分段控件槽、次级区块底色（注意亮色≈slate-50，白底上对比很弱，见下方「叠加高亮」例外） |
border-border | neutral 200 | 描边色 | 卡片/输入框/分隔线的边框（border-border、bg-border 做 1px 分隔） |
bg-control-track | neutral 300 | 控件未激活轨道 | 开关关闭态、滑块未填充轨道 |
text-base-text | neutral textContrast（APCA 高对比求解） | 主文本，明暗都保证达标对比 | 正文、标题、主要文字 |
text-muted-foreground | neutral text（APCA 低对比求解） | 次文本，比主文本弱 | 辅助说明、时间、占位、次级标签 |
层次关系（从下到上）：layout/main（画布） → muted（弱化块） → container（抬升卡片/浮层）。
一句话选择：页面底用 bg-main，卡片/浮层用 bg-container，主文字 text-base-text，次文字 text-muted-foreground，边框 border-border。
| 类名 | 取色来源 | 说明 |
|---|---|---|
text-active / shadow-active | --primary-color（= 主色 500） | 主色别名，语义偏「激活/高亮」，如链接 hover hover:text-active |
nprogress（bg-nprogress） | 主色 500 | 顶部加载进度条专用 |
border-table-border | --el-border-color-lighter | 表格线，桥接 Element Plus 变量 |
来自 theme/settings.js 的 tokens.light/dark.boxShadow（与颜色无关，明暗两套值）。
| 类名 | 场景 |
|---|---|
shadow-header | 顶栏底部投影 |
shadow-sider | 侧栏 / 浮层投影（下拉菜单面板也用它盖过 EP 浮层） |
shadow-tab | 标签栏投影 |
shadow-card | 卡片投影 |
gva-*）定义在 uno.config.js，把常用的 token 串固化下来，避免复制粘贴：
| 快捷类 | 等价内容 / 用途 |
|---|---|
gva-surface | p-4 my-2 bg-container text-base-text——业务卡片盒子的统一表面 |
gva-tool-btn | 顶栏工具图标按钮（36px 扁平点击区，hover 叠加灰底） |
gva-menu-item | 顶栏用户菜单项（图标+文案，hover / 键盘聚焦 / 展开高亮） |
gva-menu-item-danger | 菜单项危险态（退出登录等，text-error + 红色淡底） |
gva-menu-sep | 菜单分隔线（0.5px bg-border） |
gva-menu-label | 菜单内不可交互的身份信息 label |
bg-muted顶栏工具按钮、菜单项的 hover / 高亮底色刻意用 hover:bg-black/10 dark:hover:bg-white/10
（半透明黑/白叠加），这是唯一推荐写 dark: 变体的场景。原因：muted 亮色值≈slate-50，
与白色顶栏/面板几乎同色，hover 底看不出来；而黑/白叠加与底色无关，明暗两态都清晰可见。
同理，data-[highlighted]:bg-primary（下拉菜单项高亮）走主色实底 + 白字，是 reka 组件高亮的既定做法。
bg-white dark:bg-slate-900、text-gray-500 dark:text-gray-400 这类裸色阶成对写法。dark: 颜色变体去覆盖 token——token 自带明暗；只有「半透明叠加高亮」例外。theme/token.js（取色）+ theme/vars.js（声明映射），不要在页面里硬编码。