feat: add full project - backend, frontend, docker, specs and configs

specs/008-light-theme/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: light-theme
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-04-13
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Especificação atende todos os critérios para seguir para o planejamento.

specs/008-light-theme/plan.md

@@ -0,0 +1,60 @@
+# Plano de Implementação — Feature 008: Light Theme
+
+## Objetivo
+Implementar tema claro global, alternância dark/light, tokens de cor, guidelines e integração com Tailwind. Atualizar ou criar design.md com guidelines e tokens para futuras implementações.
+
+## Escopo
+- Suporte a tema claro e escuro (dark/light) global
+- Alternância de tema (toggle) no Navbar/Admin
+- Tokens de cor theme-aware (bg, text, border, accent, muted, etc)
+- Guidelines e exemplos em design.md
+- Integração com Tailwind CSS (estratégia 'class')
+- Refatoração dos principais componentes/páginas para tokens theme-aware
+- Testes de acessibilidade (contraste, foco, etc)
+- Documentação para devs
+
+---
+
+## 1. Atualização do Tailwind para Suporte a Temas
+- [ ] Configurar `tailwind.config.ts` para estratégia `darkMode: 'class'`
+- [ ] Definir tokens de cor para ambos temas (light/dark) via `extend.colors` e CSS custom properties
+- [ ] Garantir que tokens sejam facilmente consumidos via classes utilitárias e/ou `@apply`
+
+## 2. Tokens de Cor e Guidelines
+- [ ] Mapear tokens: bg, text, border, accent, muted, hover, etc para ambos temas
+- [ ] Documentar tokens e exemplos de uso em `DESIGN.md`
+- [ ] Adicionar recomendações de contraste e fallback seguro
+
+## 3. ThemeProvider/Contexto
+- [ ] Criar contexto React para alternância de tema (`ThemeProvider`)
+- [ ] Implementar persistência da escolha (localStorage)
+- [ ] Sincronizar com `prefers-color-scheme` do SO
+- [ ] Garantir SSR/hidratação sem "flash" de tema incorreto
+
+## 4. Toggle de Tema
+- [ ] Adicionar toggle (ícone sol/lua) no Navbar e painel admin
+- [ ] Garantir acessibilidade do toggle (foco, aria-label, contraste)
+
+## 5. Refatoração de Componentes
+- [ ] Refatorar principais componentes/páginas para usar tokens e classes theme-aware
+- [ ] Garantir que todos respeitem o tema ativo
+
+## 6. Testes de Acessibilidade
+- [ ] Testar contraste mínimo AA+ em todos os estados
+- [ ] Garantir foco visível e navegação por teclado
+- [ ] Validar ausência de "flash" de tema incorreto
+
+## 7. Documentação
+- [ ] Atualizar/criar seção de guidelines de tema em `DESIGN.md`
+- [ ] Exemplos de uso de tokens, recomendações de contraste, como estender o tema
+- [ ] Passos para devs integrarem novos componentes ao sistema de temas
+
+---
+
+## Critérios de Aceite
+- Alternância de tema funcional e persistente
+- Contraste AA+ garantido
+- Documentação clara para devs
+- Nenhum componente com cor ilegível ao alternar tema
+- Preferência do SO respeitada na primeira visita
+- Sem "flash" de tema incorreto em SSR/hidratação

specs/008-light-theme/spec.md

@@ -0,0 +1,61 @@
+# Especificação da Feature: Light Theme
+
+## Visão Geral
+
+Permitir alternância entre tema escuro (Linear dark) e tema claro em todo o sistema (frontend React e páginas administrativas), promovendo acessibilidade, preferência visual e consistência de design. O tema claro deve ser moderno, acessível (contraste AA+), fácil de alternar e documentado para uso futuro.
+
+## Atores
+- Usuário final (clientes, visitantes)
+- Administrador do sistema
+
+## Cenários de Usuário & Testes
+- Usuário acessa o sistema e visualiza o tema de acordo com a preferência do sistema operacional ("prefers-color-scheme")
+- Usuário alterna manualmente entre tema claro e escuro via toggle global (ícone sol/lua no Navbar e painel admin)
+- Preferência de tema é persistida (localStorage) e respeitada em visitas futuras
+- Todas as páginas, componentes e formulários refletem corretamente o tema selecionado
+- Em SSR/hidratação, o tema correto é aplicado sem "flash" de tema incorreto
+- Contraste mínimo AA+ garantido em todos os estados (normal, hover, disabled)
+- Novos componentes podem adotar tokens de cor documentados
+
+## Requisitos Funcionais
+1. Implementar paleta de cores clara (backgrounds, textos, bordas, acentos, hover, muted, etc) consistente e acessível
+2. Adicionar alternância global de tema (toggle) visível no Navbar e painel admin, com ícone sol/lua
+3. Persistir escolha do usuário em localStorage e sincronizar com prefers-color-scheme do SO
+4. Configurar Tailwind CSS para suportar dark/light usando a estratégia 'class'
+5. Garantir que todos os componentes, páginas e formulários respeitem o tema ativo
+6. Documentar tokens de cor (nomes, exemplos, guidelines de uso e contraste)
+7. Garantir fallback seguro para SSR/hidratação e acessibilidade (contraste mínimo, foco visível)
+
+## Critérios de Sucesso
+- Usuário pode alternar entre temas e a escolha é lembrada em visitas futuras
+- Tema claro apresenta contraste AA+ em todos os elementos
+- Nenhum componente exibe cores erradas ou ilegíveis ao alternar tema
+- Preferência do SO é respeitada na primeira visita
+- Documentação de tokens e guidelines disponível para desenvolvedores
+- Não há "flash" de tema incorreto em SSR/hidratação
+
+## Entidades/Objetos-Chave
+- Tokens de cor: bg, text, border, accent, muted, hover, etc
+- Preferência de tema: 'light', 'dark', 'system'
+- Componente de alternância (toggle)
+
+## Restrições & Assunções
+- Tema escuro (Linear dark) já está implementado
+- Tema claro deve ser consistente com o dark, mas otimizado para acessibilidade
+- Persistência via localStorage; fallback para prefers-color-scheme
+- Tailwind já instalado; estratégia 'class' será usada
+- SSR pode ser relevante para futuras versões/admin
+
+## Edge Cases
+- SSR/hidratação: evitar "flash" de tema incorreto
+- Usuário sem suporte a localStorage: fallback para sistema
+- Contraste mínimo em todos os estados (hover, disabled, etc)
+- Acessibilidade: foco visível, sem dependência exclusiva de cor
+
+## Documentação
+- Listar tokens de cor, exemplos de uso e guidelines para novos componentes
+- Instruções para desenvolvedores sobre como aplicar tokens e garantir contraste
+
+---
+
+*Esta especificação não inclui detalhes de implementação, frameworks ou código. Foco em valor ao usuário, acessibilidade e consistência visual.*

specs/008-light-theme/tasks.md

@@ -0,0 +1,89 @@
+---
+description: "Tasks para a feature 008 - Light Theme"
+---
+
+# Tasks: Light Theme (008)
+
+**Input**: Design documents de `/specs/008-light-theme/`
+**Prerequisites**: plan.md (required), spec.md (required)
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Inicialização e configuração base para suporte a temas
+
+- [ ] T001 Atualizar Tailwind para `darkMode: 'class'` em frontend/tailwind.config.ts
+- [ ] T002 [P] Adicionar dependências/utilitários necessários para alternância de tema em frontend/package.json
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Definir tokens, guidelines e base para alternância
+
+- [ ] T003 Definir tokens de cor (bg, text, border, accent, muted, hover, etc) para ambos temas em frontend/tailwind.config.ts
+- [ ] T004 [P] Documentar tokens, exemplos e recomendações de contraste em DESIGN.md
+- [ ] T005 [P] Garantir tokens disponíveis via classes utilitárias e/ou @apply em frontend/src/index.css
+
+---
+
+## Phase 3: User Story 1 (P1) — Alternância global, persistência, SSR, documentação
+
+- [ ] T006 [US1] Criar ThemeProvider/contexto React para alternância de tema em frontend/src/contexts/ThemeContext.tsx
+- [ ] T007 [P] [US1] Implementar persistência da escolha do tema (localStorage) e sincronização com prefers-color-scheme em ThemeProvider
+- [ ] T008 [P] [US1] Garantir SSR/hidratação sem "flash" de tema incorreto em frontend/src/main.tsx e ThemeProvider
+- [ ] T009 [US1] Adicionar toggle de tema (ícone sol/lua) no Navbar em frontend/src/components/Navbar.tsx
+- [ ] T010 [P] [US1] Adicionar toggle de tema no painel admin em frontend/src/layouts/ClientLayout.tsx
+- [ ] T011 [P] [US1] Garantir acessibilidade do toggle (foco, aria-label, contraste) em ambos componentes
+- [ ] T012 [US1] Atualizar/criar seção de guidelines de tema em DESIGN.md (exemplos, recomendações, como estender)
+
+---
+
+## Phase 4: User Story 2 (P2) — Refatoração de componentes/páginas
+
+- [ ] T013 [US2] Refatorar principais componentes para usar tokens e classes theme-aware em frontend/src/components/
+- [ ] T014 [P] [US2] Refatorar principais páginas para usar tokens e classes theme-aware em frontend/src/pages/
+- [ ] T015 [P] [US2] Garantir que todos respeitem o tema ativo (testar alternância)
+
+---
+
+## Phase 5: User Story 3 (P3) — Testes de acessibilidade e documentação para devs
+
+- [ ] T016 [US3] Testar contraste mínimo AA+ em todos os estados (normal, hover, disabled) nos principais componentes/páginas
+- [ ] T017 [P] [US3] Garantir foco visível e navegação por teclado nos toggles e componentes principais
+- [ ] T018 [P] [US3] Validar ausência de "flash" de tema incorreto em SSR/hidratação
+- [ ] T019 [US3] Documentar para devs: exemplos de uso de tokens, recomendações de contraste, como estender o tema e integrar novos componentes em DESIGN.md
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+- [ ] T020 Revisar documentação e exemplos em DESIGN.md
+- [ ] T021 [P] Revisar todos os componentes para garantir consistência visual e acessibilidade
+
+---
+
+## Dependencies
+
+- Phase 1 → Phase 2 → Phase 3 (US1) → Phase 4 (US2) → Phase 5 (US3) → Phase 6
+- Tasks marcadas com [P] podem ser executadas em paralelo dentro da mesma fase
+
+## Parallel Execution Examples
+
+- T002 e T003 podem rodar em paralelo
+- T007, T008, T010, T011 podem rodar em paralelo após T006
+- T014 e T015 podem rodar em paralelo após T013
+- T017 e T018 podem rodar em paralelo após T016
+
+## Independent Test Criteria
+
+- US1: Alternância funcional, persistência, sem flash, documentação clara
+- US2: Todos componentes/páginas respeitam tema ativo
+- US3: Contraste AA+, foco visível, documentação para devs
+
+## MVP Scope
+
+- Fase 3 (US1): Alternância global, persistência, SSR/hidratação, documentação inicial
+
+## Formato Validado
+
+- Todos os tasks seguem o formato checklist: checkbox, ID, [P] se paralelizável, [USx] se de user story, caminho de arquivo