pendulum/web/src/assets/styles

样式指南文档

本文档详细说明了项目的样式系统，包括变量、混合器（mixins）和最佳实践。

目录结构

styles/
├── variables.scss  // 全局变量定义
├── mixins.scss    // 通用混合器
├── layout.scss    // 布局相关样式
└── README.md      // 本文档

颜色系统

主要颜色

• $primary-color: #0070D5 - 主题色，用于重要按钮、链接等
• $secondary-color: #0066ff - 次要主题色
• $success-color: #31D158 - 成功状态
• $warning-color: #faad14 - 警告状态
• $error-color: #f5222d - 错误状态

文本颜色

• $text-color: #000000 - 主要文本色
• $text-color-secondary: rgba(0, 0, 0, 0.65) - 次要文本色
• $text-color-light: #FFFFFF - 亮色文本
• $text-color-light-secondary: rgba(255, 255, 255, 0.8) - 次要亮色文本
• $text-primary: #333333 - 主要文本色（替代）
• $text-secondary: #666666 - 次要文本色（替代）
• $text-light: #999999 - 浅色文本

背景颜色

• $background-light: #FFFFFF - 亮色背景
• $background-primary: #ffffff - 主要背景色
• $background-gray: #F5F5F5 - 灰色背景
• $background-secondary: #f5f5f5 - 次要背景色
• $background-dark: #141414 - 深色背景

间距系统

使用一致的间距尺寸来保持界面的韵律感：

$spacing-xs: 4px    // 超小间距
$spacing-sm: 8px    // 小间距
$spacing-md: 16px   // 中等间距
$spacing-lg: 24px   // 大间距
$spacing-xl: 32px   // 超大间距
$spacing-xxl: 40px  // 特大间距
$spacing-xxxl: 60px // 超特大间距

布局尺寸

$header-height: 60px        // 头部高度
$footer-height: 60px        // 底部高度
$container-width: 1200px    // 容器最大宽度
$sidebar-width: 256px       // 侧边栏宽度
$content-max-width: 800px   // 内容最大宽度

字体系统

字体大小

$font-size-xs: 0.75rem    // 12px
$font-size-sm: 0.875rem   // 14px
$font-size-md: 1rem       // 16px
$font-size-lg: 1.25rem    // 20px
$font-size-xl: 1.5rem     // 24px
$font-size-xxl: 2rem      // 32px
$font-size-xxxl: 3rem     // 48px

字体粗细

$font-weight-normal: 400  // 常规
$font-weight-medium: 500  // 中等
$font-weight-bold: 600    // 粗体

响应式断点

$breakpoint-sm: 576px     // 小屏幕
$breakpoint-md: 768px     // 中等屏幕
$breakpoint-lg: 992px     // 大屏幕
$breakpoint-xl: 1200px    // 超大屏幕

Mixins 使用指南

弹性布局

@include flex-center {
  // 居中对齐的弹性布局
}

@include flex-between {
  // 两端对齐的弹性布局
}

@include flex-column {
  // 纵向弹性布局
}

响应式设计

@include mobile {
  // 移动端样式
}

@include tablet {
  // 平板样式
}

@include desktop {
  // 桌面端样式
}

文本处理

@include text-ellipsis {
  // 单行文本省略
}

@include multi-line-ellipsis($lines: 2) {
  // 多行文本省略
}

最佳实践

1. 变量使用规范

   • 始终使用变量而不是硬编码值
   • 使用 @use 导入变量：@use '@/assets/styles/variables' as v;
   • 使用命名空间访问变量：v.$primary-color

2. 混合器使用规范

   • 导入混合器：@use '@/assets/styles/mixins' as m;
   • 使用命名空间调用混合器：@include m.flex-center;

3. 组件样式规范

   .component {
    padding: v.$spacing-md;
    color: v.$text-primary;
   
    &__header {
      @include m.flex-between;
      margin-bottom: v.$spacing-sm;
    }
   
    &__content {
      font-size: v.$font-size-md;
    }
   }
   

4. 响应式开发

   .component {
    width: 100%;
   
    @include m.mobile {
      padding: v.$spacing-sm;
    }
   
    @include m.desktop {
      max-width: v.$container-width;
    }
   }
   

性能优化建议

1. 避免过深的选择器嵌套（不超过3层）
2. 合理使用 CSS 继承
3. 使用 CSS Grid 和 Flexbox 进行布局
4. 优先使用 class 选择器
5. 合理使用 CSS 变量实现主题切换

主题定制

项目支持亮色和暗色主题切换，使用相应的颜色变量：

.theme-dark {
  color: v.$text-color-light;
  background-color: v.$background-dark;
}

.theme-light {
  color: v.$text-color;
  background-color: v.$background-light;
}

组件示例

Section 组件

<style lang="scss" scoped>
@use '@/assets/styles/variables' as v;
@use '@/assets/styles/mixins' as m;

.section {
  padding: v.$spacing-xxxl 0;

  &.dark {
    color: v.$text-color-light;
  }

  .section-header {
    @include m.flex-column;
    max-width: v.$content-max-width;
  }
}
</style>

常见问题

1. 如何添加新的变量？

   • 在 variables.scss 中添加新变量
   • 确保变量名符合命名规范
   • 更新本文档

2. 如何创建新的 mixin？

   • 在 mixins.scss 中添加新的 mixin
   • 确保 mixin 足够通用
   • 添加相应的文档说明

3. 如何处理特定组件的样式？

   • 使用 scoped 样式
   • 遵循 BEM 命名规范
   • 复用现有的变量和 mixins