docs/DESIGN_SYSTEM.md

# Design System - RAG Template

Sistema de design minimalista e profissional para o RAG Template.

---

## Princípios de Design

1. **Minimalismo**: Remover tudo que não é essencial
2. **Legibilidade**: Tipografia clara e hierarquia visual
3. **Consistência**: Padrões visuais uniformes
4. **Acessibilidade**: Alto contraste e design inclusivo
5. **Performance**: CSS otimizado e carregamento rápido

---

## Paleta de Cores

### Cores Principais

```css
--color-primary: #ffbe00        /* Amarelo - Destaque e ações */
--color-bg-primary: #ffffff     /* Branco - Fundo principal */
--color-bg-secondary: #f8f9fa   /* Cinza claro - Fundo secundário */
--color-text-primary: #000000   /* Preto - Texto principal */
--color-text-secondary: #6c757d /* Cinza - Texto auxiliar */
--color-border: #dee2e6         /* Cinza claro - Bordas */
```

### Uso das Cores

**Amarelo (#ffbe00)**
- Botões primários (CTA)
- Highlights e destaques
- Underline de tab ativa
- Estados de hover importantes

**Branco (#ffffff)**
- Fundo principal do app
- Cards e containers
- Inputs e formulários

**Cinza Claro (#f8f9fa)**
- Fundo de headers de tabelas
- Backgrounds alternativos
- States de hover sutis

**Preto (#000000)**
- Texto principal
- Headers e títulos
- Labels e descrições

**Cinza (#6c757d)**
- Texto secundário
- Placeholders
- Ícones inativos

---

## Tipografia

### Fonte

**Família**: [Inter](https://fonts.google.com/specimen/Inter)
- Moderna, legível e profissional
- Ótima para interfaces digitais
- Suporte completo a português

### Pesos Utilizados

```css
300 - Light      /* Texto leve (raramente usado) */
400 - Regular    /* Texto padrão */
500 - Medium     /* Botões e labels */
600 - Semibold   /* Headers e títulos */
700 - Bold       /* Títulos principais */
```

### Hierarquia Tipográfica

```css
h1: 2rem (32px)     - Título principal
h2: 1.5rem (24px)   - Seções principais
h3: 1.25rem (20px)  - Subsções
p:  0.95rem (15px)  - Texto padrão
```

### Letter Spacing

```css
h1, h2, h3: -0.02em  /* Mais compacto e moderno */
p, span:    normal   /* Padrão para legibilidade */
```

---

## Componentes

### Botões

**Primário**
```css
Background: #ffbe00
Color: #000000
Border: none
Border-radius: 6px
Font-weight: 500
Transition: all 0.2s ease

Hover:
  Background: #e6aa00
  Transform: translateY(-1px)
  Box-shadow: 0 4px 12px rgba(255, 190, 0, 0.3)
```

**Secundário**
```css
Background: #f8f9fa
Color: #000000
Border: 1px solid #dee2e6
Border-radius: 6px
Font-weight: 500

Hover:
  Background: #e9ecef
  Border-color: #6c757d
```

### Inputs

```css
Border: 1px solid #dee2e6
Border-radius: 6px
Background: #ffffff
Color: #000000
Padding: 0.5rem 0.75rem

Focus:
  Border-color: #ffbe00
  Box-shadow: 0 0 0 3px rgba(255, 190, 0, 0.1)
```

### Tabs

```css
/* Inativa */
Color: #6c757d
Background: transparent
Border-bottom: 2px solid transparent

/* Ativa */
Color: #000000
Border-bottom: 2px solid #ffbe00
Background: transparent

/* Hover (inativa) */
Color: #000000
Background: #f8f9fa
```

### Cards

```css
Background: #ffffff
Border: 1px solid #dee2e6
Border-radius: 8px
Padding: 1.5rem
```

### Tabelas

```css
/* Header */
Background: #f8f9fa
Color: #000000
Font-weight: 600
Border-bottom: 2px solid #dee2e6

/* Células */
Color: #000000
Border-bottom: 1px solid #dee2e6
Padding: 0.75rem

/* Hover de linhas */
Background: #f8f9fa
```

---

## Espaçamento

### Sistema de Espaçamento (rem)

```css
0.25rem = 4px   /* Muito pequeno */
0.5rem  = 8px   /* Pequeno */
0.75rem = 12px  /* Médio-pequeno */
1rem    = 16px  /* Padrão */
1.5rem  = 24px  /* Médio */
2rem    = 32px  /* Grande */
3rem    = 48px  /* Muito grande */
```

### Uso

- **Padding interno**: 0.5rem - 1.5rem
- **Margin entre elementos**: 1rem - 2rem
- **Gap em grids**: 1rem - 1.5rem

---

## Bordas e Sombras

### Border Radius

```css
4px  - Elementos pequenos (badges, tags)
6px  - Padrão (botões, inputs)
8px  - Cards e containers
12px - Elementos grandes
```

### Box Shadow

```css
/* Hover suave */
0 2px 8px rgba(0, 0, 0, 0.1)

/* Destaque */
0 4px 12px rgba(255, 190, 0, 0.3)

/* Focus */
0 0 0 3px rgba(255, 190, 0, 0.1)
```

---

## Transições

### Padrão

```css
transition: all 0.2s ease;
```

### Hover Effects

- **Botões**: Transform + shadow
- **Links**: Color change
- **Cards**: Shadow increase

---

## Scrollbar

### Customização

```css
Width: 8px
Height: 8px

Track: #f8f9fa
Thumb: #6c757d
Thumb (hover): #000000
Border-radius: 4px
```

---

## Responsividade

### Breakpoints

```css
Mobile:  < 768px
Tablet:  768px - 1024px
Desktop: > 1024px
```

### Mobile Adaptations

```css
@media (max-width: 768px) {
  /* Container padding reduzido */
  .gradio-container {
    padding: 1rem;
  }

  /* Títulos menores */
  h1 { font-size: 1.5rem; }
  h2 { font-size: 1.25rem; }

  /* Botões full-width */
  button { width: 100%; }
}
```

---

## Acessibilidade

### Contraste

Todos os pares de cores atendem WCAG AA:
- Preto sobre branco: 21:1 (AAA)
- Preto sobre amarelo: 10.4:1 (AA)
- Cinza sobre branco: 4.6:1 (AA)

### Focus States

- Outline amarelo visível em todos elementos focáveis
- Tab navigation funcional
- Skip links para navegação por teclado

### Semântica

- Headers hierárquicos (h1 → h2 → h3)
- Labels associados a inputs
- Alt text em imagens (quando aplicável)
- ARIA labels quando necessário

---

## Estados

### Success

```css
Color: #198754 (verde)
Uso: Mensagens de sucesso, confirmações
```

### Warning

```css
Color: #fd7e14 (laranja)
Uso: Avisos, atenção necessária
```

### Error

```css
Color: #dc3545 (vermelho)
Uso: Erros, falhas, validações
```

---

## Ícones e Símbolos

### Diretrizes

- **NÃO usar emojis** (design profissional)
- Usar ícones SVG quando necessário
- Preferir texto claro a ícones ambíguos
- Manter consistência no estilo de ícones

---

## Loading States

### Spinner

```css
Border: 2px solid #f8f9fa
Border-top: 2px solid #ffbe00
Border-radius: 50%
Animation: spin 1s linear infinite
```

---

## Boas Práticas

### DO ✓

- Use espaçamento consistente
- Mantenha hierarquia visual clara
- Priorize legibilidade sobre estilo
- Teste em diferentes tamanhos de tela
- Valide contraste de cores

### DON'T ✗

- Não use emojis
- Não use mais de 3 cores primárias
- Não abuse de animações
- Não use fontes exóticas
- Não ignore acessibilidade

---

## Implementação

### Arquivo CSS

Todos os estilos estão centralizados em:
```
ui/custom_css.py
```

### Aplicação

```python
from ui.custom_css import CUSTOM_CSS

with gr.Blocks(css=CUSTOM_CSS) as demo:
    # ...
```

### Classes Utilitárias

```python
# Mensagens de sucesso
gr.Markdown("Sucesso!", elem_classes=["success"])

# Mensagens de erro
gr.Markdown("Erro!", elem_classes=["error"])

# Botões primários
gr.Button("Ação", elem_classes=["primary-button"])
```

---

## Manutenção

### Atualizações de Cores

Para mudar o amarelo de destaque:
1. Edite `--color-primary` em `custom_css.py`
2. Teste contraste em https://webaim.org/resources/contrastchecker/
3. Valide em todos os componentes

### Adicionar Novos Componentes

1. Siga padrões existentes
2. Use variáveis CSS
3. Documente uso e variações
4. Teste responsividade

---

**Design atualizado**: Janeiro 2026
**Versão**: 1.1.0