架构概览

Raaghu 设计系统 - 架构概览

Raaghu 设计系统构建为一个 monorepo，包含多个协同工作的包，提供全面的 React 组件库。

@waiin/raaghu-react/
├── raaghu-elements/         # 原子级 UI 组件
├── raaghu-layouts/          # 布局组合
├── raaghu-pages/            # 页面解决方案
├── raaghu-react-themes/     # 主题系统
├── stories/                 # Storybook 文档
└── docs/                    # 架构文档
└── utils/                   # 其他工具

包结构

1. Raaghu 元素和组件 (raaghu-elements/ 和 raaghu-components/)

用途：原子级、可重用的 UI 组件

组件：基础组件包括：

• 表单控件：按钮、输入框、选择器、复选框、单选框等
• 显示：卡片、头像、徽章、标签、工具提示等
• 导航：标签页、面包屑、分页等
• 反馈：警告、模态框、提示条、对话框等
• 布局：盒子、容器、堆栈、网格等

结构：

rds-{component}/
├── rds-{component}.tsx       # React 组件
├── rds-{component}.scss      # 组件样式
└── rds-{component}.stories.tsx # Storybook 故事

2. Raaghu 布局 (raaghu-layouts/)

用途：组合多个元素的复杂布局组件

组件：

• rds-comp-app-shell：主应用外壳，包含头部、侧边栏、内容
• rds-comp-layout：基础页面布局结构

结构：

rds-comp-{layout}/
├── rds-comp-{layout}.tsx     # 布局组件
├── rds-comp-{layout}.css     # 布局样式
└── rds-comp-{layout}.stories.tsx # Storybook 故事

3. Raaghu 页面 (raaghu-pages/)

用途：完整的页面模板和示例

结构：

raaghu-pages/
├── src/                      # 页面组件
├── public/                   # 静态资源
├── package.json             # 页面特定依赖
└── vite.config.ts           # 构建配置

4. Raaghu React 主题 (raaghu-react-themes/)

用途：带有设计标记和配色方案的主题系统

主题：

• 浅色主题
• 深色主题

结构：

src/styles/
├── index.scss               # 主题入口文件
├── variables/
│   └── color-variables.scss # 设计标记
└── themes/
        ├── light.scss          # 浅色主题
        ├── dark.scss           # 深色主题

设计原则

1. 原子化设计方法

我们遵循 Brad Frost 的原子化设计原则：

• 原子：基础元素（按钮、输入框、图标）
• 分子：原子组合（搜索栏、卡片头部）
• 有机体：分子组合（头部、产品网格）
• 模板：布局结构（页面模板）
• 页面：模板的具体实例

2. 组件层次结构

页面 (raaghu-pages)
		↓
布局 (raaghu-layouts)
		↓
元素 (raaghu-elements)
		↓
主题 (raaghu-react-themes)

3. 关注点分离

• 结构：React 组件 (.tsx)
• 样式：SCSS 文件 (.scss/.css)
• 文档：Storybook 故事 (.stories.tsx)
• 逻辑：自定义钩子和工具
• 主题：集中化主题系统

技术栈

核心技术

• React 19.1.0：组件框架
• TypeScript 5.8.3：类型安全
• Material-UI 7.2.0：基础组件库
• SCSS/Sass：样式预处理器
• Vite 7.0.4：构建工具和开发服务器

开发工具

• Storybook 9.0.16：组件文档
• ESLint 9.30.1：代码检查
• Million.js 3.1.11：性能优化

构建系统

• Vite：快速构建工具，支持 HMR
• TypeScript 编译器：类型检查和编译
• PostCSS：CSS 处理
• Autoprefixer：浏览器兼容性

样式架构

BEM 方法论

我们使用带有 RDS 前缀的 BEM（块元素修饰符）：

.rds-{component}                    // 块
.rds-{component}__element          // 元素
.rds-{component}--modifier         // 修饰符
.rds-{component}__element--modifier // 元素修饰符

设计标记

集中化设计系统标记：

:root {
    // 颜色
    --rds-color-primary: #1976d2;
    --rds-color-secondary: #dc004e;

    // 间距
    --rds-spacing-xs: 4px;
    --rds-spacing-sm: 8px;
    --rds-spacing-md: 16px;

    // 排版
    --rds-font-family: 'Poppins', sans-serif;
    --rds-font-size-body: 14px;

    // 阴影
    --rds-elevation-1: 0 1px 3px rgba(0,0,0,0.12);
    --rds-elevation-2: 0 2px 4px rgba(0,0,0,0.1);
}

主题系统

三个内置主题，具有一致的标记映射：

1. 浅色主题：默认明亮界面
2. 深色主题：低光环境下的深色界面

组件标准

TypeScript 接口模式

export interface Rds{Component}Props extends BaseProps {
    // 组件特定属性
    variant?: 'primary' | 'secondary';
    size?: 'small' | 'medium' | 'large';
    disabled?: boolean;
    // ... 其他属性
}

组件结构模板

import React from 'react';
import './rds-{component}.scss';

export interface Rds{Component}Props {
    // 属性定义
}

const Rds{Component}: React.FC<Rds{Component}Props> = ({
    // 属性解构
    ...props
}) => {
    return (
        <div className="rds-{component}">
            {/* 组件 JSX */}
        </div>
    );
};

export default Rds{Component};

开发工作流

组件开发流程

1. 设置：在适当的包中创建组件目录
2. 实现：使用 TypeScript 构建 React 组件
3. 样式：使用 BEM 约定创建 SCSS 样式
4. 文档：编写 Storybook 故事
5. 导出：将组件添加到包索引

质量保证

测试类型	工具	目的
单元测试	Jest + React Testing Library	组件逻辑
视觉测试	Storybook	UI 一致性
集成测试	React Testing Library	组件交互
无障碍测试	axe-core	WCAG 合规性

性能与无障碍

优化特性

构建性能：

• ES 模块的 Tree shaking
• 大型组件的代码分割
• Million.js React 优化
• Vite 快速打包

运行时性能：

• 昂贵组件的 React.memo
• 大型数据集的虚拟化
• 防抖输入和高效的 CSS 选择器

无障碍性 (WCAG 2.1 AA)

核心要求：

• 完整的键盘导航
• 带有 ARIA 的屏幕阅读器支持
• 4.5:1 最小颜色对比度
• 具有焦点管理的语义化 HTML

版本策略

语义化版本控制： MAJOR.MINOR.PATCH

• 主版本：破坏性变更
• 次版本：新功能（向后兼容）
• 补丁版本：仅修复错误

迁移流程： 弃用警告 → 迁移指南 → 渐进式过渡 → 明确时间表

---