---
name: admin-theme-consistency
description: MallBase Vben Admin 主题与 Modal 表单一致性规则；开发后台页面、组件样式、弹窗表单或明暗色适配时使用。
---

# Vben 规则：后台主题与 Modal 表单一致性

## 适用范围

`frontend/admin/apps/web-antd` 后台页面、表单、弹窗、上传与富文本相关 UI。

## 强制规则

1. 禁止写死浅色背景（如 `#fff`、`#f5f5f5`）作为页面主容器颜色。
2. 优先使用主题变量：`hsl(var(--background))`、`hsl(var(--card))`、`hsl(var(--popover))`、`hsl(var(--border))`、`hsl(var(--foreground))`。
3. 组件样式改动必须同时验证浅色和深色模式，不允许只修一种主题。
4. 富文本、上传预览、表单校验提示等嵌入式区域必须跟随主题。
5. 第三方组件样式通过受控容器 class 或 CSS 变量桥接，不做无边界全局覆盖。
6. Modal 表单优先复用同模块、同类型页面的布局；水平或垂直布局应由字段密度、弹窗宽度和响应式需求决定。
7. 标签宽度在表单级统一配置，但 `100px` 不是全局硬编码；仅在相邻实现和字段文案都适合时使用，窄弹窗或长标签应采用响应式配置或垂直布局。
8. 表单间距使用项目现有样式体系统一控制，禁止把 `pt-4`、`mt-4` 等单一 class 当成所有弹窗的强制模板。

## 推荐做法

1. 页面容器使用统一语义 class 承接主题变量，避免每页重复写样式。
2. 状态色优先走设计系统 token，不自行定义一套颜色。
3. 深色模式下，边框优先提升对比度而非提升纯亮度。
4. 新增或编辑弹窗先检查同模块现有 Modal，复用其宽度、label 布局、校验提示和按钮顺序。
5. 内容可能超出视口时，为 Modal 主体设置受控滚动区域，避免操作按钮被挤出可视范围。

## 自检清单

- [ ] 深色模式下无明显白底区域（页面、卡片、弹窗、上传区、编辑器）。
- [ ] 表单输入、错误提示、禁用态在浅色和深色都可读。
- [ ] 上传组件（图片/视频/文件）列表与预览区域跟随主题。
- [ ] Modal 的布局与同模块页面一致，标签不截断，窄屏下无横向溢出。
- [ ] 改动后手动检查受影响页面的浅色、深色和典型弹窗状态。