223 lines
9.4 KiB
Markdown
223 lines
9.4 KiB
Markdown
# 主题系统
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [index.html](file://index.html)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向“有维项目”的主题系统设计，聚焦于CSS自定义属性（CSS变量）的架构与使用、主色调系统（紫色系、绿色系、蓝色系）、渐变色彩理念与实现、阴影系统与视觉层次、颜色变量的组织与语义化命名、主题定制与动态切换方案、以及无障碍与可访问性优化建议。文档同时提供面向设计师与开发者的使用指南与扩展方案。
|
||
|
||
## 项目结构
|
||
本项目采用单页应用结构，主题系统集中于页面头部的样式块中，通过CSS变量在全局生效，并在各组件类名中按需引用。页面包含登录页、仪表盘页、AI智能体页等，主题变量贯穿所有页面与组件。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Root[":root<br/>CSS变量定义"] --> Body[":root 下的 body"]
|
||
Root --> LoginPage[".login-page"]
|
||
Root --> Dashboard[".dashboard-page"]
|
||
Root --> AIPage[".ai-page"]
|
||
Root --> Components["通用组件类名<br/>如 .user-menu/.stat-card/.ai-card 等"]
|
||
Components --> VarRef["var(--xxx) 引用"]
|
||
```
|
||
|
||
图表来源
|
||
- [index.html](file://index.html)
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
## 核心组件
|
||
- CSS变量层：在页面根节点集中定义主色、辅助色、文本色、背景色、边框色、渐变与阴影等变量，统一主题语义。
|
||
- 组件层：各页面与组件类名直接引用变量，形成一致的视觉风格与交互反馈。
|
||
- 动态行为层：脚本负责页面切换、菜单开关、表单交互、聊天窗口等，但未涉及主题变量的动态切换。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
## 架构总览
|
||
主题系统采用“变量集中定义 + 类名按需引用”的架构，确保：
|
||
- 变量集中管理，便于统一修改与扩展；
|
||
- 组件解耦，通过变量引用实现主题一致性；
|
||
- 渐进增强，可在不破坏现有结构的前提下引入新变量或新组件。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "变量层"
|
||
V1["主色系<br/>--primary-color/--primary-light/--primary-dark"]
|
||
V2["辅助色系<br/>--secondary-color/--accent-color"]
|
||
V3["文本与背景<br/>--text-primary/--text-secondary/--bg-color/--card-bg"]
|
||
V4["边框与分隔<br/>--border-color"]
|
||
V5["渐变<br/>--gradient-1/--gradient-2"]
|
||
V6["阴影<br/>--shadow-sm/--shadow-md/--shadow-lg/--shadow-xl"]
|
||
end
|
||
subgraph "组件层"
|
||
C1[".login-page/.login-form-container"]
|
||
C2[".dashboard-page/.navbar/.tab-nav"]
|
||
C3[".ai-page/.ai-card/.chat-modal"]
|
||
C4["通用组件<br/>.user-menu/.stat-card/.membership-card 等"]
|
||
end
|
||
V1 --> C1
|
||
V1 --> C2
|
||
V1 --> C3
|
||
V1 --> C4
|
||
V2 --> C1
|
||
V2 --> C2
|
||
V2 --> C3
|
||
V2 --> C4
|
||
V3 --> C1
|
||
V3 --> C2
|
||
V3 --> C3
|
||
V3 --> C4
|
||
V4 --> C1
|
||
V4 --> C2
|
||
V4 --> C3
|
||
V4 --> C4
|
||
V5 --> C1
|
||
V5 --> C2
|
||
V5 --> C3
|
||
V5 --> C4
|
||
V6 --> C1
|
||
V6 --> C2
|
||
V6 --> C3
|
||
V6 --> C4
|
||
```
|
||
|
||
图表来源
|
||
- [index.html](file://index.html)
|
||
|
||
## 详细组件分析
|
||
|
||
### CSS变量与命名规范
|
||
- 命名采用语义化前缀：主色、辅助色、文本、背景、边框、渐变、阴影等，便于识别与维护。
|
||
- 颜色变量按系列分组：主色系（主色、浅主色、深主色）、辅助色系（二级色、强调色）、文本与背景、边框色。
|
||
- 渐变变量采用序号区分用途；阴影变量按层级递增，体现视觉深度。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
### 主色调系统：紫色系、绿色系、蓝色系
|
||
- 紫色系：用于品牌主色与强调，如登录页背景、导航高亮、统计图标等。
|
||
- 绿色系：用于积极与成功的状态，如课程图标、功能特性图标、按钮强调等。
|
||
- 蓝色系：用于信息与辅助功能，如AI卡片、聊天区域等。
|
||
- 使用模式：主色用于重要交互与高亮；浅主色用于悬停与焦点；深主色用于强调与选中态；二级色用于次要状态；强调色用于特殊提示。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
### 渐变色彩设计理念与实现
|
||
- 设计理念：渐变用于强化品牌主色与营造科技感，常用于登录背景、按钮、头像、聊天区域等。
|
||
- 实现方式：通过CSS变量定义线性渐变，组件中直接引用变量，保证一致性与可替换性。
|
||
- 视觉效果：渐变在不同组件中呈现不同的强调程度，既保持统一又避免单调。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
### 阴影系统：多层级阴影、投影深度与视觉层次
|
||
- 层级划分：sm/md/lg/xl四个层级，分别对应轻微浮层、卡片、面板、模态框等不同视觉深度。
|
||
- 应用策略：导航栏、卡片、菜单、模态框等根据层级选择合适阴影，形成清晰的视觉层次。
|
||
- 交互反馈：按钮悬停、卡片悬浮等过渡动效配合阴影变化，增强可用性。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
### 颜色变量的组织结构、语义化命名与维护策略
|
||
- 组织结构：将颜色变量按功能域分组，减少跨域依赖，降低维护成本。
|
||
- 语义化命名：以功能与用途命名，如主色、文本、背景、边框、渐变、阴影等，避免仅以颜色直译命名。
|
||
- 维护策略：新增变量遵循命名规范；变更主色时，通过修改根节点变量即可全局生效；对组件进行主题适配时，优先使用变量而非硬编码颜色。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
### 主题定制、动态主题切换与用户偏好保存
|
||
- 当前实现：页面通过CSS变量实现静态主题，未包含JavaScript动态切换与用户偏好持久化。
|
||
- 实现建议（概念性方案）：
|
||
- 在根节点增加主题类或自定义属性，通过脚本切换；
|
||
- 将用户偏好的主题值存储在本地存储中，页面加载时恢复；
|
||
- 提供主题选择器，支持明暗/多色系切换；
|
||
- 为关键变量提供映射表，便于批量替换。
|
||
- 注意事项：动态切换时需同步更新渐变、阴影与边框变量，确保视觉一致性。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始"]) --> Detect["检测用户偏好"]
|
||
Detect --> HasPref{"存在偏好？"}
|
||
HasPref --> |是| Apply["应用偏好主题"]
|
||
HasPref --> |否| Default["应用默认主题"]
|
||
Apply --> UpdateRoot["更新根节点变量/类"]
|
||
Default --> UpdateRoot
|
||
UpdateRoot --> Persist["持久化用户偏好"]
|
||
Persist --> End(["结束"])
|
||
```
|
||
|
||
图表来源
|
||
- [index.html](file://index.html)
|
||
|
||
### 无障碍与可访问性优化
|
||
- 色彩对比度：确保文本与背景、按钮与背景、图标与背景之间满足对比度要求，提升阅读与操作体验。
|
||
- 交互可见性：为焦点状态、悬停状态、选中状态提供明确的视觉反馈，避免仅依赖颜色区分。
|
||
- 渐变与对比：渐变背景上的文字与图标需额外注意对比度，必要时添加遮罩或调整透明度。
|
||
- 低对比度模式：可提供低对比度或高对比度主题选项，满足不同用户需求。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
## 依赖关系分析
|
||
- 变量依赖：组件类名普遍依赖根节点变量，形成强关联；变量变更直接影响多个组件外观。
|
||
- 组件耦合：组件间通过变量解耦，避免硬编码颜色导致的重复修改。
|
||
- 外部依赖：项目未引入外部UI库或主题框架，主题系统完全由原生CSS变量实现。
|
||
|
||
```mermaid
|
||
graph LR
|
||
Var["CSS变量"] --> Comp1[".login-page/.login-form-container"]
|
||
Var --> Comp2[".dashboard-page/.navbar/.tab-nav"]
|
||
Var --> Comp3[".ai-page/.ai-card/.chat-modal"]
|
||
Var --> Comp4["通用组件类名"]
|
||
```
|
||
|
||
图表来源
|
||
- [index.html](file://index.html)
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
## 性能考量
|
||
- CSS变量的优势：集中管理、运行时替换成本低、体积小、兼容性良好。
|
||
- 渐变与阴影：合理使用渐变与阴影可提升视觉层次，但需避免过度叠加导致渲染压力。
|
||
- 组件数量与复杂度：组件数量较多时，建议拆分变量定义与组件样式，便于按需加载与缓存。
|
||
|
||
## 故障排查指南
|
||
- 变量未生效：检查变量是否在根节点定义且拼写正确；确认组件类名是否正确引用变量。
|
||
- 渐变显示异常：检查渐变参数与颜色值是否符合语法；确认容器尺寸与背景覆盖范围。
|
||
- 阴影层级错位：核对阴影变量层级与组件层级是否匹配；检查z-index与定位上下文。
|
||
- 无障碍问题：使用对比度检测工具验证文本与背景的对比度；测试键盘导航与焦点可见性。
|
||
|
||
章节来源
|
||
- [index.html](file://index.html)
|
||
|
||
## 结论
|
||
本主题系统以CSS变量为核心，实现了主色调、渐变与阴影的统一管理，具备良好的可维护性与扩展性。建议后续引入动态主题切换与用户偏好持久化机制，并完善无障碍与对比度优化，以进一步提升用户体验与可访问性。
|
||
|
||
## 附录
|
||
- 变量清单（示例）
|
||
- 主色系：--primary-color、--primary-light、--primary-dark
|
||
- 辅助色系：--secondary-color、--accent-color
|
||
- 文本与背景：--text-primary、--text-secondary、--bg-color、--card-bg
|
||
- 边框与分隔：--border-color
|
||
- 渐变：--gradient-1、--gradient-2
|
||
- 阴影：--shadow-sm、--shadow-md、--shadow-lg、--shadow-xl
|
||
|
||
章节来源
|
||
- [index.html](file://index.html) |