Architecture Overview

The Raaghu Design System is built as a monorepo containing multiple packages that work together to provide a comprehensive React component library.

@waiin/raaghu-react/
├── raaghu-elements/         # Atomic UI components
├── raaghu-layouts/          # Layout compositions
├── raaghu-pages/            # Page Solution
├── raaghu-react-themes/     # Theme system
├── stories/                 # Storybook documentation
└── docs/                    # Architecture documentation
└── utils/                   # Other Tools

Package Structure

1. Raaghu Elements and Components (raaghu-elements/ and raaghu-components/)

Purpose: Atomic, reusable UI components

Components: Base components including:

• Form Controls: button, input, select, checkbox, radio, etc.
• Display: card, avatar, badge, chip, tooltip, etc.
• Navigation: tabs, breadcrumbs, pagination, etc.
• Feedback: alert, modal, snackbar, dialog, etc.
• Layout: box, container, stack, grid, etc.

Structure:

rds-{component}/
├── rds-{component}.tsx       # React component
├── rds-{component}.scss      # Component styles
└── rds-{component}.stories.tsx # Storybook stories

2. Raaghu Layouts (raaghu-layouts/)

Purpose: Complex layout components that compose multiple elements

Components:

• rds-comp-app-shell: Main application shell with header, sidebar, content
• rds-comp-layout: Base page layout structure

Structure:

rds-comp-{layout}/
├── rds-comp-{layout}.tsx     # Layout component
├── rds-comp-{layout}.css     # Layout styles
└── rds-comp-{layout}.stories.tsx # Storybook stories

3. Raaghu Pages (raaghu-pages/)

Purpose: Complete page templates and examples

Structure:

raaghu-pages/
├── src/                      # Page components
├── public/                   # Static assets
├── package.json             # Page-specific dependencies
└── vite.config.ts           # Build configuration

4. Raaghu React Themes (raaghu-react-themes/)

Purpose: Theme system with design tokens and color schemes

Themes:

• Light theme
• Dark theme

Structure:

src/styles/
├── index.scss               # Main theme entry
├── variables/
│   └── color-variables.scss # Design tokens
└── themes/
		├── light.scss          # Light theme
		├── dark.scss           # Dark theme

Design Principles

1. Atomic Design Methodology

We follow Brad Frost's Atomic Design principles:

• Atoms: Basic elements (button, input, icon)
• Molecules: Groups of atoms (search bar, card header)
• Organisms: Groups of molecules (header, product grid)
• Templates: Layout structures (page templates)
• Pages: Specific instances of templates

2. Component Hierarchy

Pages (raaghu-pages)
		↓
Layouts (raaghu-layouts)
		↓
Elements (raaghu-elements)
		↓
Themes (raaghu-react-themes)

3. Separation of Concerns

• Structure: React components (.tsx)
• Styling: SCSS files (.scss/.css)
• Documentation: Storybook stories (.stories.tsx)
• Logic: Custom hooks and utilities
• Theming: Centralized theme system

Technology Stack

Core Technologies

• React 19.1.0: Component framework
• TypeScript 5.8.3: Type safety
• Material-UI 7.2.0: Base component library
• SCSS/Sass: Styling preprocessor
• Vite 7.0.4: Build tool and dev server

Development Tools

• Storybook 9.0.16: Component documentation
• ESLint 9.30.1: Code linting
• Million.js 3.1.11: Performance optimization

Build System

• Vite: Fast build tool with HMR
• TypeScript Compiler: Type checking and compilation
• PostCSS: CSS processing
• Autoprefixer: Browser compatibility

Styling Architecture

BEM Methodology

We use BEM (Block Element Modifier) with RDS prefixes:

.rds-{component}                    // Block
.rds-{component}__element          // Element
.rds-{component}--modifier         // Modifier
.rds-{component}__element--modifier // Element modifier

Design Tokens

Centralized design system tokens:

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

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

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

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

Theme System

Three built-in themes with consistent token mapping:

1. Light Theme: Default bright interface
2. Dark Theme: Dark interface for low-light environments

Component Standards

TypeScript Interface Pattern

export interface Rds{Component}Props extends BaseProps {
	// Component-specific props
	variant?: 'primary' | 'secondary';
	size?: 'small' | 'medium' | 'large';
	disabled?: boolean;
	// ... other props
}

Component Structure Template

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

export interface Rds{Component}Props {
	// Props definition
}

const Rds{Component}: React.FC<Rds{Component}Props> = ({
	// Props destructuring
	...props
}) => {
	return (
		<div className="rds-{component}">
			{/* Component JSX */}
		</div>
	);
};

export default Rds{Component};

Development Workflow

Component Development Process

1. Setup: Create component directory in appropriate package
2. Implementation: Build React component with TypeScript
3. Styling: Create SCSS styles using BEM conventions
4. Documentation: Write Storybook stories
5. Export: Add component to package index

Quality Assurance

Test Type	Tools	Purpose
Unit	Jest + React Testing Library	Component logic
Visual	Storybook	UI consistency
Integration	React Testing Library	Component interactions
Accessibility	axe-core	WCAG compliance

Performance & Accessibility

Optimization Features

Build Performance:

• Tree shaking with ES modules
• Code splitting for large components
• Million.js React optimization
• Vite fast bundling

Runtime Performance:

• React.memo for expensive components
• Virtualization for large datasets
• Debounced inputs and efficient CSS selectors

Accessibility (WCAG 2.1 AA)

Core Requirements:

• Full keyboard navigation
• Screen reader support with ARIA
• 4.5:1 minimum color contrast
• Semantic HTML with focus management

Versioning Strategy

Semantic Versioning: MAJOR.MINOR.PATCH

• Major: Breaking changes
• Minor: New features (backward compatible)
• Patch: Bug fixes only

Migration Process: Deprecation warnings → Migration guides → Gradual transition → Clear timelines

---