CSS

Visão Geral

Este guia explica a arquitetura CSS/SCSS, organização de arquivos, convenções de nomenclatura, tokens de design e melhores práticas para construir componentes de UI sustentáveis e escaláveis no Raaghu Design System.

Estrutura de Organização de Arquivos

Estilos em Nível de Componente

Cada componente RDS segue uma estrutura rigorosa:

raaghu-elements/
├── rds-{component-name}/
│   ├── rds-{component-name}.tsx          # Componente React
│   ├── rds-{component-name}.stories.tsx  # Histórias do Storybook
│   └── rds-{component-name}.scss         # Estilos específicos do componente

Estilos em Nível de Layout

raaghu-layouts/
├── rds-comp-{layout-name}/
│   ├── rds-comp-{layout-name}.tsx
│   ├── rds-comp-{layout-name}.stories.tsx
│   └── rds-comp-{layout-name}.css        # Estilos específicos do layout

Estilos de Tema

raaghu-react-themes/
├── src/
│   └── styles/
│       ├── index.scss                    # Entrada principal do tema
│       ├── variables/
│       │   └── color-variables.scss      # Tokens de cor
│       └── themes/
│           ├── light.scss               # Tema claro
│           ├── dark.scss                # Tema escuro

Convenções de Nomenclatura

BEM (Block Element Modifier) com Prefixo RDS

.rds-{component-name} { }
.rds-{component-name}__element { }
.rds-{component-name}--modifier { }
.rds-{component-name}__element--modifier { }

Exemplos

.rds-button { }
.rds-button__icon { }
.rds-button--primary { }
.rds-button--large { }
.rds-card { }
.rds-card__header { }
.rds-card--elevation-2 { }

Padrões de Estrutura SCSS

Modelo SCSS de Componente

.rds-{component-name} {
  // Estilos base
  display: block;

  // Elementos
  &__element {
    // Estilos do elemento
  }

  // Modificadores
  &--variant {
    // Estilos da variante
  }

  // Estados
  &:hover { }
  &:focus { }
  &:disabled { }
}

Uso de Tokens de Design

Use propriedades personalizadas CSS para cores, espaçamento, tipografia e elevação:

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

Checklist de Implementação

• O componente possui um arquivo .scss correspondente
• O SCSS usa a nomenclatura BEM com o prefixo rds-
• Os estilos incluem todas as variantes e estados necessários
• Tokens de design são usados para cores e espaçamento
• Os estados de acessibilidade são estilizados
• O componente é exportado no index.ts do pacote

Acessibilidade e Desempenho

• Inclua estados de foco para elementos interativos
• Garanta contraste de cor suficiente
• Suporte a leitores de tela com a classe .sr-only
• Minimize conflitos de especificidade CSS
• Evite aninhamento profundo (máximo de 3 níveis)
• Use seletores eficientes

Melhores Práticas

1. Isolamento: Mantenha os estilos autocontidos por componente
2. Consistência: Use padrões de nomenclatura e espaçamento estabelecidos
3. Manutenibilidade: Documente estilos complexos, use nomes significativos
4. Performance: Remova CSS não utilizado, use tree-shaking, minifique para produção
5. Acessibilidade: Teste a navegação por teclado, contraste de cor e estados de foco

Ferramentas de Desenvolvimento

• SCSS IntelliSense
• Live Sass Compiler
• CSS Peek
• Prettier - Formatador de código

Configuração de Linting

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