Visão Geral da Arquitetura

O Raaghu Design System é construído como um monorepo contendo múltiplos pacotes que trabalham juntos para fornecer uma biblioteca abrangente de componentes React.

@waiin/raaghu-react/
├── raaghu-elements/         # Componentes de UI atômicos
├── raaghu-layouts/          # Composições de layout
├── raaghu-pages/            # Soluções de páginas
├── raaghu-react-themes/     # Sistema de temas
├── stories/                 # Documentação no Storybook
└── docs/                    # Documentação de arquitetura
└── utils/                   # Outras ferramentas

Estrutura de Pacotes

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

Propósito: Componentes de UI atômicos e reutilizáveis

Componentes: Componentes básicos incluindo:

• Controles de Formulário: botão, input, select, checkbox, radio, etc.
• Exibição: card, avatar, badge, chip, tooltip, etc.
• Navegação: tabs, breadcrumbs, paginação, etc.
• Feedback: alert, modal, snackbar, dialog, etc.
• Layout: box, container, stack, grid, etc.

Estrutura:

rds-{component}/
├── rds-{component}.tsx       # Componente React
├── rds-{component}.scss      # Estilos do componente
└── rds-{component}.stories.tsx # Histórias do Storybook

2. Raaghu Layouts (raaghu-layouts/)

Propósito: Componentes de layout complexos que compõem múltiplos elementos

Componentes:

• rds-comp-app-shell: Estrutura principal da aplicação com cabeçalho, barra lateral, conteúdo
• rds-comp-layout: Estrutura base de layout de página

Estrutura:

rds-comp-{layout}/
├── rds-comp-{layout}.tsx     # Componente de layout
├── rds-comp-{layout}.css     # Estilos do layout
└── rds-comp-{layout}.stories.tsx # Histórias do Storybook

3. Raaghu Pages (raaghu-pages/)

Propósito: Templates de páginas completas e exemplos

Estrutura:

raaghu-pages/
├── src/                      # Componentes de página
├── public/                   # Recursos estáticos
├── package.json              # Dependências específicas da página
└── vite.config.ts            # Configuração de build

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

Propósito: Sistema de temas com tokens de design e esquemas de cores

Temas:

• Tema claro
• Tema escuro

Estrutura:

src/styles/
├── index.scss               # Entrada principal de temas
├── variables/
│   └── color-variables.scss # Tokens de design
└── themes/
		├── light.scss          # Tema claro
		├── dark.scss           # Tema escuro

Princípios de Design

1. Metodologia de Design Atômico

Seguimos os princípios de Atomic Design de Brad Frost:

• Átomos: Elementos básicos (botão, input, ícone)
• Moléculas: Grupos de átomos (barra de busca, cabeçalho de card)
• Organismos: Grupos de moléculas (cabeçalho, grid de produtos)
• Templates: Estruturas de layout (templates de páginas)
• Páginas: Instâncias específicas de templates

2. Hierarquia de Componentes

Páginas (raaghu-pages)
		↓
Layouts (raaghu-layouts)
		↓
Elementos (raaghu-elements)
		↓
Temas (raaghu-react-themes)

3. Separação de Responsabilidades

• Estrutura: Componentes React (.tsx)
• Estilos: Arquivos SCSS (.scss/.css)
• Documentação: Histórias no Storybook (.stories.tsx)
• Lógica: Hooks customizados e utilitários
• Temas: Sistema centralizado de temas

Stack Tecnológico

Tecnologias Principais

• React 19.1.0: Framework de componentes
• TypeScript 5.8.3: Tipagem estática
• Material-UI 7.2.0: Biblioteca base de componentes
• SCSS/Sass: Pré-processador de estilos
• Vite 7.0.4: Ferramenta de build e servidor de desenvolvimento

Ferramentas de Desenvolvimento

• Storybook 9.0.16: Documentação de componentes
• ESLint 9.30.1: Linter de código
• Million.js 3.1.11: Otimização de performance

Sistema de Build

• Vite: Build rápido com HMR
• TypeScript Compiler: Checagem e compilação de tipos
• PostCSS: Processamento de CSS
• Autoprefixer: Compatibilidade entre navegadores

Arquitetura de Estilos

Metodologia BEM

Utilizamos BEM (Block Element Modifier) com prefixos RDS:

.rds-{component}                    // Bloco
.rds-{component}__element           // Elemento
.rds-{component}--modifier          // Modificador
.rds-{component}__element--modifier // Modificador de elemento

Tokens de Design

Tokens centralizados do sistema de design:

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

	// Espaçamento
	--rds-spacing-xs: 4px;
	--rds-spacing-sm: 8px;
	--rds-spacing-md: 16px;

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

	// Elevação
	--rds-elevation-1: 0 1px 3px rgba(0,0,0,0.12);
	--rds-elevation-2: 0 2px 4px rgba(0,0,0,0.1);
}

Sistema de Temas

Três temas embutidos com mapeamento consistente de tokens:

1. Tema Claro: Interface padrão clara
2. Tema Escuro: Interface escura para ambientes de baixa luz

Padrões de Componentes

Padrão de Interface TypeScript

export interface Rds{Component}Props extends BaseProps {
	// Propriedades específicas do componente
	variant?: 'primary' | 'secondary';
	size?: 'small' | 'medium' | 'large';
	disabled?: boolean;
	// ... outras props
}

Template de Estrutura de Componente

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

export interface Rds{Component}Props {
	// Definição de props
}

const Rds{Component}: React.FC<Rds{Component}Props> = ({
	// Desestruturação de props
	...props
}) => {
	return (
		<div className="rds-{component}">
			{/* JSX do componente */}
		</div>
	);
};

export default Rds{Component};

Fluxo de Desenvolvimento

Processo de Desenvolvimento de Componentes

1. Configuração: Criar diretório do componente no pacote apropriado
2. Implementação: Construir componente React com TypeScript
3. Estilização: Criar estilos SCSS usando convenções BEM
4. Documentação: Escrever histórias no Storybook
5. Exportação: Adicionar componente ao índice do pacote

Garantia de Qualidade

Tipo de Teste	Ferramentas	Propósito
Unitário	Jest + React Testing Library	Lógica do componente
Visual	Storybook	Consistência visual
Integração	React Testing Library	Interações de componentes
Acessibilidade	axe-core	Conformidade WCAG

Desempenho e Acessibilidade

Recursos de Otimização

Performance de Build:

• Tree shaking com módulos ES
• Code splitting para grandes componentes
• Otimização React com Million.js
• Build rápido com Vite

Performance em Runtime:

• React.memo para componentes pesados
• Virtualização para grandes datasets
• Inputs com debounce e seletores CSS eficientes

Acessibilidade (WCAG 2.1 AA)

Requisitos principais:

• Navegação completa por teclado
• Suporte a leitores de tela com ARIA
• Contraste mínimo de 4.5:1
• HTML semântico com gerenciamento de foco

Estratégia de Versionamento

Versionamento Semântico: MAJOR.MINOR.PATCH

• Major: Mudanças incompatíveis
• Minor: Novas funcionalidades (retrocompatíveis)
• Patch: Apenas correções de bugs

Processo de Migração: Avisos de depreciação → Guias de migração → Transição gradual → Prazos claros

---