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

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).
Reutilize variantes existentes
- Exemplo: Button com variant e size ao invés de criar novo estilo local.
Mantenha escala de espaçamento/radius
- Aproveite spacing e radius definidos no tema (--radius-*) para evitar UI inconsistente.
Priorize acessibilidade dos componentes base
- Dialog, Select, Dropdown, Tabs etc. devem vir dos componentes ui/ já integrados com Radix.
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.

2.8 KiB Raw Blame History