--- kind: frontend_style name: 基于 UnoCSS + NaiveUI 的主题化样式体系 category: frontend_style scope: - '**' source_files: - frontend/uno.config.ts - frontend/packages/uno-preset/src/index.ts - frontend/src/theme/vars.ts - frontend/src/theme/settings.ts - frontend/src/theme/preset/default.json - frontend/src/theme/preset/dark.json - frontend/src/styles/css/reset.css - frontend/src/styles/scss/scrollbar.scss --- ## 系统概述 前端采用 **UnoCSS**（原子化 CSS）+ **Naive UI** 组件库的混合方案，配合自研 `@sa/uno-preset` 预设与 JSON 主题预设文件，实现可配置、可切换的多主题中后台风格。 ## 核心架构 - **原子化样式层**：通过 `unocss` + `presetWind3` 提供 Tailwind 兼容类名；自定义 `presetSoybeanAdmin` 在 `packages/uno-preset/src/index.ts` 中集中定义 `flex-*`、`absolute-*`、`fixed-*` 等常用快捷类。 - **设计令牌层**：`src/theme/vars.ts` 将颜色、阴影映射为 CSS 变量（如 `--primary-color`、`--header-box-shadow`），由 `themeSettings` 与 `src/theme/preset/*.json` 驱动注入。 - **主题预设层**：`src/theme/preset/{default,dark,azir,compact}.json` 以 JSON 描述主题色板、圆角、布局模式、Header/Sider/Tab/Footer 尺寸等，运行时由 `theme-drawer` 动态切换。 - **全局样式层**：`src/styles/css/reset.css` 提供浏览器默认样式重置；`global.css` 统一 `html/body/#app` 高度与基础文本色；`src/styles/scss/global.scss` 引入滚动条 mixin，支持暗色覆盖。 ## 关键文件 - `frontend/uno.config.ts` — UnoCSS 入口，合并 `themeVars`、注册 `presetWind3({ dark: 'class' })` 与 `presetSoybeanAdmin`、启用 `transformerDirectives` / `transformerVariantGroup` - `frontend/packages/uno-preset/src/index.ts` — 项目级快捷类集合（flex/absolute/fixed/ellipsis 等） - `frontend/src/theme/vars.ts` — 生成 `colors.*`、`boxShadow.*` 的 CSS 变量映射表 - `frontend/src/theme/settings.ts` — 默认主题设置（主色、圆角、布局模式、各区域尺寸、light/dark tokens） - `frontend/src/theme/preset/*.json` — 可插拔主题预设（default/dark/azir/compact） - `frontend/src/styles/css/reset.css` — 跨浏览器 reset 基线 - `frontend/src/styles/scss/scrollbar.scss` — 带暗色覆盖的滚动条 mixin - `frontend/package.json` — 依赖声明（naive-ui、unocss、sass、tailwind-merge 等） ## 约定与规则 1. **优先使用 UnoCSS 原子类**：布局用 `flex-center`、`absolute-lt` 等 preset 快捷类，避免手写 flex/position 代码。 2. **主题色通过 CSS 变量消费**：组件内直接引用 `var(--primary-color)` 或 Uno 类 `text-primary`，禁止硬编码十六进制色值。 3. **暗色模式以 class 切换**：Uno 配置 `dark: 'class'`，通过给 `` 添加 `.dark` 类触发，所有样式需遵循此约定。 4. **新增主题走 preset JSON**：在 `src/theme/preset/` 下新建 JSON 文件，保持与 `default.json` 一致的字段结构，再通过 theme drawer 加载。 5. **全局样式分层**：reset 放 `css/reset.css`，业务通用样式放 `scss/global.scss`，页面级样式尽量拆到组件 SCSS 文件中，避免污染全局。 6. **滚动条统一使用 mixin**：需要自定义滚动条时引入 `@forward 'scrollbar'` 并使用 `$size/$color` 参数，确保暗色自动适配。