跳到主要内容
版本：1.3.2

CSS

概述​

本指南解释了 Raaghu 设计系统中用于构建可维护和可扩展 UI 组件的 CSS/SCSS 架构、文件组织、命名约定、设计令牌和最佳实践。

文件组织结构​

组件级样式​

每个 RDS 组件都遵循严格的结构：

raaghu-elements/
├── rds-{component-name}/
│   ├── rds-{component-name}.tsx          # React 组件
│   ├── rds-{component-name}.stories.tsx  # Storybook 故事
│   └── rds-{component-name}.scss         # 组件特定样式

布局级样式​

raaghu-layouts/
├── rds-comp-{layout-name}/
│   ├── rds-comp-{layout-name}.tsx
│   ├── rds-comp-{layout-name}.stories.tsx
│   └── rds-comp-{layout-name}.css        # 布局特定样式

主题样式​

raaghu-react-themes/
├── src/
│   └── styles/
│       ├── index.scss                    # 主主题入口
│       ├── variables/
│       │   └── color-variables.scss      # 颜色令牌
│       └── themes/
│           ├── light.scss               # 浅色主题
│           ├── dark.scss                # 深色主题

命名约定​

带 RDS 前缀的 BEM（块元素修饰符）​

.rds-{component-name} { }
.rds-{component-name}__element { }
.rds-{component-name}--modifier { }
.rds-{component-name}__element--modifier { }
示例​
.rds-button { }
.rds-button__icon { }
.rds-button--primary { }
.rds-button--large { }
.rds-card { }
.rds-card__header { }
.rds-card--elevation-2 { }

SCSS 结构标准​

组件 SCSS 模板​

.rds-{component-name} {
  // 基础样式
  display: block;

  // 元素
  &__element {
    // 元素样式
  }

  // 修饰符
  &--variant {
    // 变体样式
  }

  // 状态
  &:hover { }
  &:focus { }
  &:disabled { }
}

设计令牌使用​

使用 CSS 自定义属性来处理颜色、间距、排版和阴影：

background-color: var(--rds-color-primary);
padding: var(--rds-spacing-md);
border-radius: var(--rds-border-radius);
box-shadow: var(--rds-elevation-2);

实施清单​

  • 组件有对应的 .scss 文件
  • SCSS 使用带 rds- 前缀的 BEM 命名
  • 样式包含所有必要的变体和状态
  • 颜色和间距使用设计令牌
  • 无障碍状态已设置样式
  • 组件在包的 index.ts 中导出

无障碍性和性能​

  • 为交互元素包含焦点状态
  • 确保足够的颜色对比度
  • 使用 .sr-only 类支持屏幕阅读器
  • 最小化 CSS 特异性冲突
  • 避免深度嵌套（最多 3 层）
  • 使用高效选择器

最佳实践​

  1. 隔离： 保持每个组件的样式自包含
  2. 一致性： 使用已建立的命名和间距模式
  3. 可维护性： 记录复杂样式，使用有意义的名称
  4. 性能： 清除未使用的 CSS，使用 tree-shaking，生产环境压缩
  5. 无障碍性： 测试键盘导航、颜色对比度和焦点状态

开发工具​

  • SCSS IntelliSense
  • Live Sass Compiler
  • CSS Peek
  • Prettier - 代码格式化工具

代码检查配置​

{
  "extends": ["stylelint-config-standard-scss"],
  "rules": {
    "selector-class-pattern": "^rds-[a-z]([a-z0-9-]+)?(__([a-z0-9]+-?)+)?(--([a-z0-9]+-?)+)?$"
  }
}