349 lines
15 KiB
Markdown
349 lines
15 KiB
Markdown
# CSS变量系统
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [index.html](file://index.html)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件系统性梳理有维项目的CSS变量体系，聚焦于:root中定义的主色调与辅助色彩变量、背景与文本颜色变量、边框与阴影变量、渐变色变量的设计理念与使用场景，并结合实际样式代码说明变量在不同组件中的引用方式、变量继承机制以及主题定制方法。同时提供变量命名规范、颜色搭配原则、阴影层级规范与响应式断点变量的最佳实践，帮助开发者高效、一致地进行样式开发与主题定制。
|
||
|
||
## 项目结构
|
||
本项目采用单页HTML结构，所有样式内联在HTML文件的`<style>`标签中，变量集中定义在`:root`作用域，供全局样式引用。整体结构清晰，便于统一维护与主题切换。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Root[":root 定义<br/>CSS自定义属性"] --> Body[":root 下的样式规则"]
|
||
Body --> LoginPage["登录页面样式"]
|
||
Body --> Dashboard["仪表盘页面样式"]
|
||
Body --> AIPage["AI智能体页面样式"]
|
||
Body --> ChatModal["AI对话弹窗样式"]
|
||
Body --> Responsive["响应式断点样式"]
|
||
```
|
||
|
||
图表来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:33-1451](file://index.html#L33-L1451)
|
||
|
||
章节来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:33-1451](file://index.html#L33-L1451)
|
||
|
||
## 核心组件
|
||
本节对:root中定义的CSS变量进行逐项解析，说明其设计理念、典型使用场景及在各组件中的引用方式。
|
||
|
||
- 主色调与辅助色彩变量
|
||
- --primary-color：主品牌色，用于强调、按钮、选中态、焦点态等关键交互元素。
|
||
- --primary-light：主色浅色版本，用于悬停、弱化强调等。
|
||
- --primary-dark：主色深色版本，用于深色背景或强调对比。
|
||
- --secondary-color：辅助品牌色，用于次要功能、图标、强调信息等。
|
||
- --accent-color：强调色，用于提示性信息、装饰性元素。
|
||
- 背景与文本颜色变量
|
||
- --bg-color：页面背景色，用于页面容器、卡片背景等。
|
||
- --card-bg：卡片背景色，用于卡片、面板等容器背景。
|
||
- --text-primary：主要文本色，用于标题、正文等高对比度文本。
|
||
- --text-secondary：次要文本色，用于说明文字、辅助信息。
|
||
- 边框与阴影变量
|
||
- --border-color：边框颜色，用于表单、分隔线、容器边框等。
|
||
- --shadow-sm：小阴影，用于轻量卡片、按钮等。
|
||
- --shadow-md：中阴影，用于卡片、面板等。
|
||
- --shadow-lg：大阴影，用于悬浮、重要卡片等。
|
||
- --shadow-xl：超大阴影，用于重要弹层、导航栏等。
|
||
- 渐变色变量
|
||
- --gradient-1：主渐变，用于按钮、徽标、强调区域等。
|
||
- --gradient-2：辅助渐变，用于头像、图标等。
|
||
|
||
变量在组件中的典型引用方式示例（以路径标注代替具体代码）：
|
||
- 登录页面容器与按钮：[index.html:167-176](file://index.html#L167-L176)、[index.html:346-362](file://index.html#L346-L362)
|
||
- 导航栏与卡片：[index.html:421-424](file://index.html#L421-L424)、[index.html:594-605](file://index.html#L594-L605)
|
||
- 表单与输入框：[index.html:294-318](file://index.html#L294-L318)
|
||
- 用户菜单与下拉：[index.html:106-126](file://index.html#L106-L126)
|
||
- AI对话弹窗与消息气泡：[index.html:1082-1264](file://index.html#L1082-L1264)
|
||
|
||
章节来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:167-176](file://index.html#L167-L176)
|
||
- [index.html:346-362](file://index.html#L346-L362)
|
||
- [index.html:421-424](file://index.html#L421-L424)
|
||
- [index.html:594-605](file://index.html#L594-L605)
|
||
- [index.html:294-318](file://index.html#L294-L318)
|
||
- [index.html:106-126](file://index.html#L106-L126)
|
||
- [index.html:1082-1264](file://index.html#L1082-L1264)
|
||
|
||
## 架构总览
|
||
CSS变量系统采用“集中定义、全局引用”的架构。:root中定义的变量作为设计令牌，贯穿登录页、仪表盘、AI智能体页、对话弹窗等所有页面组件；组件内部通过var()函数引用变量，实现主题一致性与动态切换能力。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "设计令牌层"
|
||
V1["主色调变量<br/>--primary-color, --primary-light, --primary-dark"]
|
||
V2["辅助色彩变量<br/>--secondary-color, --accent-color"]
|
||
V3["背景与文本变量<br/>--bg-color, --card-bg, --text-primary, --text-secondary"]
|
||
V4["边框与阴影变量<br/>--border-color, --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl"]
|
||
V5["渐变色变量<br/>--gradient-1, --gradient-2"]
|
||
end
|
||
subgraph "样式应用层"
|
||
S1["登录页样式"]
|
||
S2["仪表盘样式"]
|
||
S3["AI智能体页样式"]
|
||
S4["对话弹窗样式"]
|
||
end
|
||
V1 --> S1
|
||
V2 --> S1
|
||
V3 --> S1
|
||
V4 --> S1
|
||
V5 --> S1
|
||
V1 --> S2
|
||
V2 --> S2
|
||
V3 --> S2
|
||
V4 --> S2
|
||
V5 --> S2
|
||
V1 --> S3
|
||
V2 --> S3
|
||
V3 --> S3
|
||
V4 --> S3
|
||
V5 --> S3
|
||
V1 --> S4
|
||
V2 --> S4
|
||
V3 --> S4
|
||
V4 --> S4
|
||
V5 --> S4
|
||
```
|
||
|
||
图表来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:167-176](file://index.html#L167-L176)
|
||
- [index.html:421-424](file://index.html#L421-L424)
|
||
- [index.html:1082-1264](file://index.html#L1082-L1264)
|
||
|
||
## 详细组件分析
|
||
|
||
### 主色调与辅助色彩变量
|
||
- 设计理念
|
||
- 主色调用于强化品牌识别与关键交互反馈，辅助色用于次要功能与信息层次区分。
|
||
- 通过主色的浅色与深色变体，形成基础的强调与对比层次。
|
||
- 使用场景
|
||
- 强调按钮、选中状态、链接、徽标、进度条等。
|
||
- 次要功能如“记住我”复选框、分隔线、弱化文本等。
|
||
- 变量继承机制
|
||
- 变量在:root定义后，全局生效；组件通过var()引用，遵循CSS层叠规则，可在局部覆盖。
|
||
- 主题定制建议
|
||
- 修改--primary-color即可统一调整主强调色系；若需深浅对比，同步调整--primary-light与--primary-dark。
|
||
- 辅助色--secondary-color与--accent-color用于差异化表达，避免与主色冲突。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始主题定制"]) --> ChoosePrimary["选择主色调 --primary-color"]
|
||
ChoosePrimary --> AdjustLightDark["调整浅色/深色变体<br/>--primary-light / --primary-dark"]
|
||
AdjustLightDark --> ApplySecondary["选择辅助色<br/>--secondary-color / --accent-color"]
|
||
ApplySecondary --> TestComponents["在组件中测试引用<br/>var(--primary-color) 等"]
|
||
TestComponents --> Iterate{"是否满足视觉层次？"}
|
||
Iterate --> |否| AdjustSecondary["微调辅助色/对比度"]
|
||
AdjustSecondary --> TestComponents
|
||
Iterate --> |是| Done(["完成"])
|
||
```
|
||
|
||
图表来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:334-338](file://index.html#L334-L338)
|
||
- [index.html:346-362](file://index.html#L346-L362)
|
||
|
||
章节来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:334-338](file://index.html#L334-L338)
|
||
- [index.html:346-362](file://index.html#L346-L362)
|
||
|
||
### 背景与文本颜色变量
|
||
- 设计理念
|
||
- --bg-color用于页面级背景，--card-bg用于卡片与容器背景，确保内容区与页面区的层次区分。
|
||
- --text-primary与--text-secondary分别用于高对比度文本与辅助信息，保证可读性。
|
||
- 使用场景
|
||
- 页面容器背景、卡片背景、表单背景、文本颜色等。
|
||
- 变量继承机制
|
||
- 在:root定义后，组件通过var()引用，可在局部通过!important或更具体的选择器覆盖。
|
||
- 主题定制建议
|
||
- 浅色主题：--bg-color与--card-bg保持浅色；--text-primary保持深色。
|
||
- 深色主题：可将--bg-color与--card-bg设为深色，--text-primary设为浅色，注意对比度不低于WCAG AA标准。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
DefineBG["定义页面背景 --bg-color"] --> DefineCard["定义卡片背景 --card-bg"]
|
||
DefineCard --> DefineText["定义文本色 --text-primary / --text-secondary"]
|
||
DefineText --> ApplyInComponents["在组件中引用<br/>var(--bg-color) / var(--text-primary)"]
|
||
ApplyInComponents --> VerifyContrast["验证对比度与可读性"]
|
||
VerifyContrast --> AdjustColors{"对比度不足？"}
|
||
AdjustColors --> |是| IncreaseContrast["提高对比度或调整颜色"]
|
||
IncreaseContrast --> VerifyContrast
|
||
AdjustColors --> |否| Done(["完成"])
|
||
```
|
||
|
||
图表来源
|
||
- [index.html:20-23](file://index.html#L20-L23)
|
||
- [index.html:33-38](file://index.html#L33-L38)
|
||
- [index.html:421-424](file://index.html#L421-L424)
|
||
|
||
章节来源
|
||
- [index.html:20-23](file://index.html#L20-L23)
|
||
- [index.html:33-38](file://index.html#L33-L38)
|
||
- [index.html:421-424](file://index.html#L421-L424)
|
||
|
||
### 边框与阴影变量
|
||
- 设计理念
|
||
- 边框颜色--border-color用于统一容器与表单的边界风格。
|
||
- 阴影变量按层级划分，从--shadow-sm到--shadow-xl，形成清晰的层级感。
|
||
- 使用场景
|
||
- 表单边框、卡片阴影、导航栏阴影、弹窗阴影等。
|
||
- 变量继承机制
|
||
- 通过var()在组件中直接引用，保持全局一致性。
|
||
- 主题定制建议
|
||
- 浅色主题：使用较柔和的阴影值；深色主题：可适当加深阴影以增强层次。
|
||
- 避免过度使用阴影导致视觉拥堵，建议按功能重要性递增使用阴影层级。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始阴影层级规划"]) --> ChooseBase["选择基础阴影 --shadow-sm / --shadow-md"]
|
||
ChooseBase --> ChooseLarge["选择较大阴影 --shadow-lg / --shadow-xl"]
|
||
ChooseLarge --> ApplyInComponents["在组件中引用<br/>var(--shadow-sm) / var(--shadow-lg)"]
|
||
ApplyInComponents --> TestDepth["测试层级深度与视觉效果"]
|
||
TestDepth --> AdjustDepth{"层级是否清晰？"}
|
||
AdjustDepth --> |否| ReorderShadows["调整阴影层级顺序"]
|
||
ReorderShadows --> TestDepth
|
||
AdjustDepth --> |是| Done(["完成"])
|
||
```
|
||
|
||
图表来源
|
||
- [index.html:24-30](file://index.html#L24-L30)
|
||
- [index.html:432](file://index.html#L432)
|
||
- [index.html:598](file://index.html#L598)
|
||
|
||
章节来源
|
||
- [index.html:24-30](file://index.html#L24-L30)
|
||
- [index.html:432](file://index.html#L432)
|
||
- [index.html:598](file://index.html#L598)
|
||
|
||
### 渐变色变量
|
||
- 设计理念
|
||
- --gradient-1与--gradient-2作为品牌强调色的渐变表达，用于按钮、徽标、头像等强调区域。
|
||
- 使用场景
|
||
- 登录按钮、卡片按钮、头像背景、徽标等。
|
||
- 变量继承机制
|
||
- 通过var(--gradient-1/2)在组件中引用，保持品牌一致性。
|
||
- 主题定制建议
|
||
- 渐变方向与色彩组合应与主色调协调；避免在大面积背景中使用强对比渐变，以免影响文本可读性。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始渐变色规划"]) --> DefineGradients["定义主/辅渐变<br/>--gradient-1 / --gradient-2"]
|
||
DefineGradients --> ApplyInComponents["在组件中引用<br/>var(--gradient-1) / var(--gradient-2)"]
|
||
ApplyInComponents --> TestReadability["测试文本与背景对比度"]
|
||
TestReadability --> AdjustGradient{"对比度不足？"}
|
||
AdjustGradient --> |是| ModifyGradient["调整渐变色彩或方向"]
|
||
ModifyGradient --> TestReadability
|
||
AdjustGradient --> |否| Done(["完成"])
|
||
```
|
||
|
||
图表来源
|
||
- [index.html:25-26](file://index.html#L25-L26)
|
||
- [index.html:167-176](file://index.html#L167-L176)
|
||
- [index.html:514-522](file://index.html#L514-L522)
|
||
|
||
章节来源
|
||
- [index.html:25-26](file://index.html#L25-L26)
|
||
- [index.html:167-176](file://index.html#L167-L176)
|
||
- [index.html:514-522](file://index.html#L514-L522)
|
||
|
||
## 依赖关系分析
|
||
CSS变量系统与组件样式的依赖关系如下：
|
||
|
||
```mermaid
|
||
graph TB
|
||
Root[":root 变量"] --> Login["登录页样式"]
|
||
Root --> Dashboard["仪表盘样式"]
|
||
Root --> AI["AI智能体页样式"]
|
||
Root --> Chat["对话弹窗样式"]
|
||
Login --> VarPrimary["var(--primary-color)"]
|
||
Login --> VarBg["var(--bg-color)"]
|
||
Login --> VarText["var(--text-primary)"]
|
||
Login --> VarBorder["var(--border-color)"]
|
||
Login --> VarShadow["var(--shadow-xl)"]
|
||
Login --> VarGradient["var(--gradient-1)"]
|
||
Dashboard --> VarPrimary
|
||
Dashboard --> VarBg
|
||
Dashboard --> VarText
|
||
Dashboard --> VarBorder
|
||
Dashboard --> VarShadow
|
||
Dashboard --> VarGradient
|
||
AI --> VarPrimary
|
||
AI --> VarBg
|
||
AI --> VarText
|
||
AI --> VarBorder
|
||
AI --> VarShadow
|
||
AI --> VarGradient
|
||
Chat --> VarPrimary
|
||
Chat --> VarBg
|
||
Chat --> VarText
|
||
Chat --> VarBorder
|
||
Chat --> VarShadow
|
||
Chat --> VarGradient
|
||
```
|
||
|
||
图表来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:167-176](file://index.html#L167-L176)
|
||
- [index.html:421-424](file://index.html#L421-L424)
|
||
- [index.html:1082-1264](file://index.html#L1082-L1264)
|
||
|
||
章节来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:167-176](file://index.html#L167-L176)
|
||
- [index.html:421-424](file://index.html#L421-L424)
|
||
- [index.html:1082-1264](file://index.html#L1082-L1264)
|
||
|
||
## 性能考虑
|
||
- 变量复用减少重复样式，降低CSS体积与维护成本。
|
||
- 合理使用阴影层级，避免过多复杂阴影导致渲染性能下降。
|
||
- 渐变色在移动端可能带来额外渲染开销，建议在低端设备上适度简化。
|
||
|
||
## 故障排除指南
|
||
- 变量未生效
|
||
- 检查:root中变量是否正确声明且无拼写错误。
|
||
- 确认组件中使用var()语法正确，且未被更高优先级的选择器覆盖。
|
||
- 对比度不足
|
||
- 使用--text-primary与--bg-color组合时，确保对比度符合可访问性标准。
|
||
- 阴影层级混乱
|
||
- 统一使用预定义阴影变量，避免在同一层级重复定义新阴影值。
|
||
- 渐变色影响可读性
|
||
- 在渐变背景上的文本建议添加背景遮罩或调整透明度，确保文本清晰可读。
|
||
|
||
章节来源
|
||
- [index.html:14-31](file://index.html#L14-L31)
|
||
- [index.html:33-38](file://index.html#L33-L38)
|
||
- [index.html:432](file://index.html#L432)
|
||
- [index.html:514-522](file://index.html#L514-L522)
|
||
|
||
## 结论
|
||
有维项目的CSS变量系统以:root为中心，围绕主色调、辅助色、背景与文本、边框与阴影、渐变色五大维度构建了统一的设计令牌。通过var()在组件中的集中引用，实现了主题一致性与可维护性。建议在主题定制时遵循颜色搭配原则与阴影层级规范，确保视觉层次清晰、对比度充足、性能稳定。
|
||
|
||
## 附录
|
||
- 变量命名规范
|
||
- 使用语义化命名，如--primary-color、--text-primary、--shadow-md等。
|
||
- 保持命名简洁、一致，避免缩写导致歧义。
|
||
- 颜色搭配原则
|
||
- 主色与辅助色应与品牌一致，避免过多颜色造成视觉混乱。
|
||
- 文本与背景对比度应满足可访问性要求。
|
||
- 阴影层级规范
|
||
- 从--shadow-sm到--shadow-xl按功能重要性递增使用，避免滥用。
|
||
- 响应式断点变量
|
||
- 项目中已提供@media断点（如1200px、768px），建议在此基础上扩展自定义断点变量，如--breakpoint-mobile、--breakpoint-tablet等，便于跨组件统一使用。 |