Merge pull request #45 from rede5/codex/create-design-system-for-repository

docs(frontend): add DESIGN_SYSTEM.md and link from FRONTEND.md

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.

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)