MianyVue/CSS_THEME_GUIDE.md

CSS主题系统使用指南

概述

本项目采用统一的CSS主题系统，通过CSS变量实现一致的视觉效果和便捷的主题管理。所有颜色、尺寸、间距等样式值都通过预定义的CSS变量进行管理，确保代码的一致性和可维护性。

🎯 核心原则

✅ 正确做法

/* 使用CSS变量 */
padding: var(--spacing-md);
font-size: var(--font-size-base);
border-radius: var(--size-border-radius);
color: var(--color-text-primary);

❌ 禁止做法

/* 硬编码值 - 严禁使用 */
padding: 12px;
font-size: 14px;
border-radius: 8px;
color: #ffffff;

🎨 变量分类系统

1. 尺寸变量 (--size-*)

/* 常用固定尺寸 */
--size-1: 1px;     /* 边框、分割线 */
--size-2: 2px;     /* 小装饰 */
--size-4: 4px;     /* 小圆角 */
--size-6: 6px;     /* 按钮圆角 */
--size-8: 8px;     /* 标准圆角 */
--size-12: 12px;   /* 卡片圆角 */
--size-16: 16px;   /* 图标尺寸 */
--size-24: 24px;   /* 大图标 */
--size-32: 32px;   /* 按钮高度 */
--size-40: 40px;   /* 操作按钮 */
--size-48: 48px;   /* 头像尺寸 */
--size-60: 60px;   /* 头部高度 */

2. 间距变量 (--spacing-*)

/* 间距系统 */
--spacing-xxs: 2px;  /* 微小间距 */
--spacing-xs: 4px;   /* 极小间距 */
--spacing-sm: 8px;   /* 小间距 */
--spacing-md: 12px;  /* 中等间距 */
--spacing-lg: 16px;  /* 大间距 */
--spacing-xl: 20px;  /* 超大间距 */
--spacing-2xl: 24px; /* 卡片间距 */
--spacing-3xl: 32px; /* 区域间距 */
--spacing-4xl: 40px; /* 大区域间距 */
--spacing-5xl: 48px; /* 页面间距 */
--spacing-6xl: 60px; /* 头部间距 */

3. 字体变量 (--font-size-*)

/* 字体大小系统 */
--font-size-xs: 12px;    /* 辅助文字 */
--font-size-sm: 13px;    /* 小文字 */
--font-size-base: 14px;  /* 基础文字 */
--font-size-md: 15px;    /* 中等文字 */
--font-size-lg: 16px;    /* 大文字 */
--font-size-xl: 18px;    /* 标题文字 */
--font-size-2xl: 20px;   /* 副标题 */
--font-size-3xl: 24px;   /* 主标题 */

4. 图标变量 (--icon-size-*)

/* 图标尺寸系统 */
--icon-size-xs: 12px;  /* 状态图标 */
--icon-size-sm: 14px;  /* 小图标 */
--icon-size-md: 16px;  /* 标准图标 */
--icon-size-lg: 20px;  /* 大图标 */
--icon-size-xl: 24px;  /* 超大图标 */
--icon-size-2xl: 28px; /* 装饰图标 */
--icon-size-3xl: 32px; /* 特大图标 */

5. 颜色变量 (--color-*)

/* 文字颜色 */
--color-text-primary: /* 主要文字 */
--color-text-secondary: /* 次要文字 */
--color-text-tertiary: /* 辅助文字 */
--color-text-error: /* 错误文字 */

/* 背景颜色 */
--color-bg-primary: /* 主背景 */
--color-bg-secondary: /* 次背景 */
--color-bg-card: /* 卡片背景 */
--color-bg-hover: /* 悬停背景 */

/* 边框颜色 */
--color-border-primary: /* 主边框 */
--color-border-secondary: /* 次边框 */
--color-border-active: /* 激活边框 */

6. CAD软件主题色

/* Creo主题 */
--color-primary: /* 蓝色主题 */

/* PDMS主题 */
--color-pdms: /* 橙色主题 */
--color-pdms-gradient: /* 橙色渐变 */

/* Revit主题 */
--color-revit: /* 绿色主题 */
--color-revit-gradient: /* 绿色渐变 */

/* 复杂度分析主题 */
--color-complexity: /* 分析橙色 */
--color-complexity-high: /* 高复杂度红色 */
--color-complexity-low: /* 低复杂度绿色 */

🛠️ 使用示例

按钮样式

.custom-button {
  padding: var(--spacing-md) var(--spacing-lg);
  font-size: var(--font-size-base);
  border-radius: var(--size-border-radius-button);
  border: var(--border-width-thin) solid var(--color-border-primary);
  gap: var(--spacing-sm);
}

卡片样式

.card-component {
  padding: var(--spacing-xl);
  margin-bottom: var(--spacing-2xl);
  border-radius: var(--size-border-radius-card);
  border: var(--border-width-thin) solid var(--color-border-primary);
  background: var(--color-bg-card);
}

文字样式

.title {
  font-size: var(--font-size-2xl);
  color: var(--color-text-primary);
  margin-bottom: var(--spacing-lg);
}

.subtitle {
  font-size: var(--font-size-base);
  color: var(--color-text-secondary);
}

响应式断点

@media (max-width: var(--breakpoint-tablet)) {
  .responsive-element {
    padding: var(--spacing-sm);
    font-size: var(--font-size-sm);
  }
}

🔧 变量映射表

常用硬编码值对应的变量

硬编码值	对应变量	用途
1px	var(--size-1)	边框
2px	var(--size-2)	小装饰
4px	var(--spacing-xs)	微间距
6px	var(--size-6)	按钮圆角
8px	var(--spacing-sm)	小间距
10px	var(--size-10)	内边距
12px	var(--spacing-md)	标准间距
14px	var(--font-size-base)	基础字体
16px	var(--spacing-lg)	大间距
20px	var(--spacing-xl)	超大间距
24px	var(--spacing-2xl)	卡片间距
768px	var(--breakpoint-tablet)	平板断点

📋 开发检查清单

开发前检查

• 确认所需尺寸在变量系统中是否已存在
• 如需新尺寸，先在theme.css中添加变量
• 确认变量命名符合语义化原则

代码审查检查

• 没有使用任何硬编码的px、rem、em值
• 所有颜色都使用CSS变量
• 响应式断点使用变量
• 间距、字体、圆角都使用对应变量

测试检查

• 组件在不同主题下显示正常
• 响应式布局工作正常
• 所有交互状态（hover、active、focus）正常

🚨 常见问题

Q: 需要的尺寸在变量中找不到怎么办？

A: 在src/assets/styles/theme.css中添加新变量，命名要语义化。

Q: 特殊组件需要特定尺寸怎么办？

A: 在theme.css中的"组件特定"区域添加专用变量。

Q: 如何确保主题切换正常？

A: 所有样式都使用CSS变量，确保亮暗主题切换时自动更新。

Q: 媒体查询也要使用变量吗？

A: 是的，使用var(--breakpoint-*)系列变量。

🎯 最佳实践

1. 语义化命名：变量名要明确表达用途
2. 分层设计：区分基础变量和语义变量
3. 一致性原则：同类元素使用相同变量
4. 可维护性：修改主题只需调整变量文件
5. 文档更新：新增变量要及时更新文档

🔄 持续改进

• 定期审查未使用的变量
• 根据设计需求扩展变量系统
• 收集开发反馈，优化变量分类
• 保持变量系统的简洁性和易用性

---

记住：统一的主题系统是项目可维护性的关键！严格遵循变量使用规范。