# Design System (Frontend)

Este documento consolida os padrões visuais e de código do frontend para reduzir regressões de UI quando novas telas/componentes forem criados por pessoas ou por IA.

## Stack de UI adotada

- **Next.js + React + Tailwind CSS v4**
- **shadcn/ui** como base dos componentes de interface (`src/components/ui/*`)
- **Radix UI** por baixo dos componentes shadcn
- **Utilitário `cn()`** para composição de classes

## Fonte da verdade de estilos

### 1) Tokens globais

- Arquivo: `src/app/globals.css`
- O tema usa variáveis CSS (`--primary`, `--background`, `--border`, etc.) mapeadas para Tailwind via `@theme inline`.
- Qualquer mudança de cor/radius/tema deve ocorrer primeiro aqui, evitando hardcode espalhado.

### 2) Primitivos de UI

- Arquivos: `src/components/ui/*.tsx`
- Botões, inputs, cards, dialogs e outros elementos base devem ser consumidos destes componentes.
- Evite reimplementar botão/input “na mão” quando já existir equivalente em `ui/`.

### 3) Componentes de feature

- Arquivos: `src/components/*.tsx` e `src/app/**/page.tsx`
- Componentes de negócio devem compor os primitivos, mantendo consistência visual e de acessibilidade.

## Regras práticas para não quebrar design

1. **Use tokens, não hex direto**
   - Prefira classes semânticas como `bg-primary`, `text-muted-foreground`, `border-border`.
   - Use cor hardcoded apenas quando houver justificativa forte (ex.: branding externo).

2. **Reutilize variantes existentes**
   - Exemplo: `Button` com `variant` e `size` ao invés de criar novo estilo local.

3. **Mantenha escala de espaçamento/radius**
   - Aproveite spacing e radius definidos no tema (`--radius-*`) para evitar UI inconsistente.

4. **Priorize acessibilidade dos componentes base**
   - Dialog, Select, Dropdown, Tabs etc. devem vir dos componentes `ui/` já integrados com Radix.

5. **Dark mode via variáveis**
   - Não criar “tema paralelo” por componente.
   - Ajustes de tema devem respeitar `:root` e `.dark` em `globals.css`.

## Checklist rápido para PRs de UI

- [ ] Reutiliza componentes de `src/components/ui` quando possível?
- [ ] Evita hardcode de cores fora dos tokens globais?
- [ ] Mantém padrões de layout/spacing já existentes na tela?
- [ ] Mantém textos preparados para i18n quando aplicável?
- [ ] Inclui testes/snapshot quando houver comportamento crítico?

## Como evoluir o design system daqui pra frente

- Criar uma pasta de documentação visual (ex.: Storybook ou docs de componentes) como próxima etapa.
- Formalizar tokens de tipografia e espaçamento em uma tabela única.
- Padronizar estados (`loading`, `empty`, `error`) em componentes reutilizáveis.

---

Se você estiver usando IA para gerar UI, use este arquivo como referência obrigatória antes de criar novos componentes.