# 设计文档：Nexus 后台全面美化重构

**日期**: 2026-05-31
**状态**: 实施中
**依据**: HyperUI / Flowbite / daisyUI / Meraki UI / Monaco Editor 深度调研

## 一、设计决策

### 配色方案：基于 HyperUI 全局色值映射

| 用途 | 亮色 (Light) | 暗色 (dark:) |
|------|-------------|-------------|
| 页面背景 | `bg-gray-50` | `dark:bg-gray-950` |
| 卡片/面板 | `bg-white` | `dark:bg-gray-900` |
| 菜单/下拉 | `bg-white` | `dark:bg-gray-800` |
| 主文本 | `text-gray-900` | `dark:text-white` |
| 次文本 | `text-gray-700` | `dark:text-gray-200` |
| 弱文本 | `text-gray-500` | `dark:text-gray-400` |
| 主边框 | `border-gray-200` | `dark:border-gray-700` |
| 次边框/输入框 | `border-gray-300` | `dark:border-gray-600` |
| hover 背景 | `hover:bg-gray-50` | `dark:hover:bg-gray-700` |
| 活跃菜单项 | `bg-gray-100 text-gray-700` | `dark:bg-gray-800 dark:text-gray-200` |
| 主按钮 | `bg-blue-600 text-white` | `dark:bg-blue-300 dark:text-gray-900` |
| 成功 | `bg-green-100 text-green-600` | `dark:bg-green-700 dark:text-green-50` |
| 危险 | `text-red-700` | `dark:text-red-600` |
| 品牌色 | 保持 oklch brand 不变 |

### 暗色模式实现

- **机制**: Tailwind v4 原生 `dark:` 前缀
- **激活**: `.dark` class on `<html>` 元素
- **FOUC 防护**: `<head>` 中同步 `theme-init.js` 从 localStorage 读取
- **持久化**: MySQL `settings` 表 `key='theme'`
- **移除**: 旧 CSS 变量方案 (`bg-[var(--bg-page)]` 等)

### Monaco Editor 主题

- **暗色**: 自定义 `nexus-dark`（Catppuccin Mocha 色系: `#1E1E2E` 背景）
- **亮色**: 自定义 `nexus-light`（VS Code 经典色系: `#FFFFFF` 背景）
- **字体**: `Fira Code`, `JetBrains Mono`, `Cascadia Code` + fontLigatures

## 二、Class 替换映射（核心）

### CSS 变量 → Tailwind dark: 前缀

| 旧 (CSS 变量) | 新 (dark: 前缀) |
|---------------|----------------|
| `bg-[var(--bg-page)]` | `bg-gray-50 dark:bg-gray-950` |
| `bg-[var(--bg-card)]` | `bg-white dark:bg-gray-900` |
| `bg-[var(--bg-surface)]` | `bg-gray-100 dark:bg-gray-800` |
| `border-[var(--border)]` | `border-gray-200 dark:border-gray-700` |
| `border-[var(--border-input)]` | `border-gray-300 dark:border-gray-600` |
| `text-[var(--text-primary)]` | `text-gray-900 dark:text-white` |
| `text-[var(--text-secondary)]` | `text-gray-500 dark:text-gray-400` |
| `text-[var(--text-muted)]` | `text-gray-400 dark:text-gray-500` |
| `text-[var(--text-dim)]` | `text-gray-300 dark:text-gray-600` |

### 保留不变的 class

- `text-white`, `text-red-*`, `text-green-*`, `text-brand-*`
- `bg-brand`, `bg-brand-dark`, `hover:bg-brand-dark`
- `hover:bg-slate-700`, `hover:bg-slate-800`（按钮 hover 不变）
- `bg-slate-700`（按钮背景不改）
- 所有带 opacity 的：`bg-slate-800/50` 等

## 三、修改范围

| 文件 | 改动 |
|------|------|
| `web/app/vendor/theme.css` | 重写：`@variant dark` 配置 |
| `web/app/vendor/theme-init.js` | FOUC 防护脚本 |
| `web/app/layout.js` | 主题系统改用 `.dark` class |
| `server/api/settings.py` | 白名单已有 theme |
| 15 个 HTML 文件 | class 替换 + theme-init.js 引入 |
| `web/app/files.html` | Monaco 自定义主题 |

## 四、Monaco 自定义主题

### nexus-dark（暗色）
- 背景: `#1E1E2E`（Catppuccin Mocha base）
- 前景: `#CDD6F4`
- 行号: `#585B70`
- 行高亮: `#313244`
- 选中: `#45475A`
- 关键字: `#C586C0`（紫色）
- 字符串: `#CE9178`（橙色）
- 函数: `#DCDCAA`（黄色）
- 类型: `#4EC9B0`（青色）
- 变量: `#9CDCFE`（蓝色）

### nexus-light（亮色）
- 背景: `#FFFFFF`
- 前景: `#1E1E1E`
- 行号: `#237893`
- 行高亮: `#F5F5F5`
- 选中: `#ADD6FF`
- VS Code 经典语法配色
