diff --git a/frontend/DESIGN_SYSTEM.md b/frontend/DESIGN_SYSTEM.md new file mode 100644 index 0000000..f169512 --- /dev/null +++ b/frontend/DESIGN_SYSTEM.md @@ -0,0 +1,66 @@ +# 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. diff --git a/frontend/FRONTEND.md b/frontend/FRONTEND.md index b893be4..25de6ce 100644 --- a/frontend/FRONTEND.md +++ b/frontend/FRONTEND.md @@ -409,3 +409,4 @@ podman run --name frontend --net host --env-file .env.local gohorse-frontend - [Backend](../backend/BACKEND.md) - [Backoffice](../backoffice/BACKOFFICE.md) - [Database Schema](../docs/DATABASE.md) +- [Design System](./DESIGN_SYSTEM.md)