更新 wiki

2026-07-17 17:17:22 +08:00
parent 1da6d72544
commit d292c23dc0
159 changed files with 2918 additions and 2735 deletions
@@ -0,0 +1,60 @@
+---
+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/dark.json
+    - frontend/src/styles/css/reset.css
+    - frontend/src/styles/css/global.css
+---
+
+## 样式系统概览
+
+本项目前端采用 **UnoCSS + NaiveUI** 的原子化 CSS 方案，结合运行时主题变量实现动态换肤。整体风格源自 SoybeanAdmin 模板，通过设计令牌（Design Tokens）统一管理色彩、圆角、阴影等视觉规范。
+
+## 核心架构
+
+### 1. 原子化样式引擎：UnoCSS
+- 使用 `presetWind3`（Tailwind v3 兼容预设）提供基础原子类
+- 自定义 `@sa/uno-preset` 包定义项目级快捷类（如 `flex-center`、`absolute-lt`、`ellipsis-text`）
+- 启用 `transformerDirectives` 和 `transformerVariantGroup` 支持 `@apply` 与类分组语法
+- 根配置位于 `frontend/uno.config.ts`
+
+### 2. 组件库：Naive UI
+- 作为主要 UI 组件来源，配合 `tailwind-merge` 处理样式冲突
+- 通过 Pinia store 管理主题状态，与 UnoCSS 变量联动
+
+### 3. 主题系统
+- **运行时主题变量**：`src/theme/vars.ts` 生成 CSS 变量映射（如 `--primary-color`、`--container-bg-color`），覆盖 UnoCSS 主题
+- **主题设置**：`src/theme/settings.ts` 定义默认主题色（`#646cff`）、圆角（6px）、布局模式等
+- **预设主题**：`src/theme/preset/*.json` 提供 light/dark/compact/azir 等多套预设，支持运行时切换
+- **暗色模式**：通过 `class` 策略（`dark: 'class'`）在 `<html>` 上切换，而非媒体查询
+
+### 4. 全局样式组织
+- `src/styles/css/global.css`：统一引入 reset、nprogress、transition 样式
+- `src/styles/css/reset.css`：基于 Tailwind 官方 base 的完整浏览器重置
+- `src/styles/scss/`：仅保留滚动条等少量 SCSS，主体样式走 UnoCSS
+- 组件内样式优先使用 UnoCSS 原子类，必要时用 `<style scoped>` 补充
+
+## 关键文件
+- `frontend/uno.config.ts` — UnoCSS 主配置
+- `frontend/packages/uno-preset/src/index.ts` — 自定义快捷类预设
+- `frontend/src/theme/vars.ts` — CSS 变量令牌生成器
+- `frontend/src/theme/settings.ts` — 默认主题设置
+- `frontend/src/theme/preset/*.json` — 主题预设文件
+- `frontend/src/styles/css/reset.css` — 浏览器样式重置
+- `frontend/src/styles/css/global.css` — 全局样式入口
+
+## 开发者约定
+1. **优先使用 UnoCSS 原子类**，避免手写 CSS；仅在无法表达时写 `<style scoped>`
+2. **颜色必须通过 CSS 变量**（如 `text-primary`、`bg-container`），禁止硬编码色值
+3. **新增主题色**需同步更新 `settings.ts` 中的 `otherColor` 及 `vars.ts` 的调色板生成逻辑
+4. **暗色适配**通过 `dark:` 前缀类或 `class` 切换，不使用 `prefers-color-scheme`
+5. **响应式断点**遵循 UnoCSS 默认（sm/md/lg/xl），不自行扩展断点
+6. **图标统一使用 @iconify/vue**，尺寸通过 `icon-*` 字号类控制