# CLAUDE.md — Site Institucional Omni Arquivo lido automaticamente pelo Claude Code em toda sessão. Contém todas as regras obrigatórias de desenvolvimento deste projeto. --- ## ⚑ Fontes oficiais e protocolo (LER PRIMEIRO) O projeto tem **fontes oficiais complementares**. Antes de criar ou modificar interface, consultar o que se aplica (não precisa reler tudo em toda tarefa): 1. **Figma** (`fileKey lCboMncjYTlvrgqifU4Y76`, via MCP) — layouts, medidas, componentes, specs visuais. 2. **[`design system.md`](design%20system.md)** — regras, decisões, padrões e convenções do projeto (base oficial consolidada em 2026-08-04). 3. **[`docs/origin/conceito-diretzes-visuais.md`](docs/origin/conceito-diretzes-visuais.md)** — diretrizes de conceito: componentes CMS-first, Home (Hero, Facilidades, Soluções, Vídeo, App, Agentes, Notícias), tom de voz, resiliência de conteúdo. 4. **[`docs/origin/release-notes.md`](docs/origin/release-notes.md)** — grid Web, dois layouts (Web/Mobile), breakpoint `720px`, contratos CMS das dobras da Home (campos e coleções). 5. **CMS (NeoCMS):** índice em [`docs/specs/cms/000-index.md`](docs/specs/cms/000-index.md). Spec aprofundada de auth: [`docs/specs/cms/001-admin.md`](docs/specs/cms/001-admin.md). ### NeoCMS — toda área editável (sempre) Ao implementar **qualquer** área gerenciável no Filament (página, globais, layout, entidade): 1. **Seeder** com o conteúdo **igual ao que o front já exibe hoje** (`data/`, `constants.ts`, `content.ts`, nav/footer). Não inventar copy. 2. **Não integrar o front** nesta fase: o site segue hardcoded; o CMS grava e a seed popula. Ligar Inertia/controllers ao banco só quando o time pedir. 3. **Testes obrigatórios** (Pest): seeder, permissão de acesso, save. Sem isso a área não está feita. Detalhe da regra: [`.cursor/rules/neocms-areas-editaveis.mdc`](.cursor/rules/neocms-areas-editaveis.mdc). **Regras invioláveis:** - Toda página/componente novo segue **exatamente** o `design system.md`. Ao reeditar a Home ou páginas existentes, aplicar as mesmas regras (consistência visual, estrutural e de experiência). - As regras do `design system.md` estão **congeladas**: não alterar nenhuma sem solicitação explícita do time. - **Divergência entre Figma, `design system.md` e os briefs em `docs/origin/`:** NÃO supor nem alterar a implementação por conta própria. **Identificar a inconsistência e pedir orientação** antes de prosseguir. ### Briefs de origem — o que extrair sem reler o arquivo inteiro Consultar o markdown completo quando a tarefa for Home, CMS de dobra, grid ou responsividade. Fora isso, valem estas regras: - O site **não é página estática**: componentes recebem conteúdo (props/CMS). Evitar editorial hardcoded e seções que só funcionam com N cards fixos — preferir coleção `0..N`. - **Dois layouts, não fluido:** Web (desktop / notebook / tablet paisagem) e Mobile. Corte principal em **`720px`**. Não inventar layouts intermediários (1200, 1024, 768…) só para “reorganizar”. - Grid Web de referência: viewport **1440×900**, **12 colunas**, margens **140px**, gutter **40px**. - Hero e “Baixe o App”: o CMS prevê **mídia desktop e mídia mobile** distintas; o front escolhe pela experiência ativa. - Imagem/vídeo: o componente define proporção (`object-fit`, aspect-ratio); o arquivo enviado pelo CMS não dita o layout. Vídeo institucional **sem tipografia gravada** no arquivo. - Agentes (Home): manter o conceito **mapa do Brasil + dois agentes** (homem e mulher), mesmo se as fotos mudarem no CMS. - Critério se houver mais de um jeito válido: fidelidade ao layout → Design System → reuso → flexibilidade CMS → responsividade → acessibilidade → manutenção. --- ## Stack obrigatória | Tecnologia | Função | Versão | |---|---|---| | Laravel | Framework PHP | ^11.x | | Inertia.js | Bridge Laravel ↔ React (sem API REST) | ^2.x | | React + TypeScript | Front-end | ^19.x / ^5.x | | Tailwind CSS | Estilização via tokens | ^4.x | | shadcn/ui | Componentes UI base | latest | | Vite | Build | ^6.x | | Filament | Painel admin / CMS | ^3.x | | MySQL | Banco de dados | 8.x | **Nunca trocar tecnologia da stack sem decisão explícita do time.** --- ## Figma — referências MCP ### Design System (fonte da verdade para visual) - **Figma — arquivo único:** `fileKey=lCboMncjYTlvrgqifU4Y76` (nome "Untitled"). Contém as duas composições como canvases separados: - **Desktop:** canvas "Desktop" (`0:1`) → frame "Linha criativa" `1:688` (1440px). Link: `https://www.figma.com/design/lCboMncjYTlvrgqifU4Y76/Untitled?node-id=0-1` - **Mobile:** canvas "Mobile" (`1:6232`) → frame "Linha criativa" `1:6682` (393px). Link: `https://www.figma.com/design/lCboMncjYTlvrgqifU4Y76/Untitled?node-id=1-6232` - ⚠️ A listagem de páginas do MCP (`get_metadata` sem nodeId) só retorna "Desktop" — o canvas Mobile existe mesmo assim; acessar direto por `1:6232`. - Tokens **validados via MCP** (variáveis do Figma) e aplicados em `resources/css/app.css`. - **Extração de apoio:** [`docs/DESIGN-SYSTEM-OMNI.md`](docs/DESIGN-SYSTEM-OMNI.md) — cobre Desktop **e Mobile** com specs detalhados. ### ⚠️ Desktop e Mobile são layouts separados — seguir AMBOS à risca O Figma tem composições próprias por breakpoint (ex.: `Header` vs `Header / Mobile`, `Carrossel` vs `Carrossel / Mobile`). **Não** tratar como um único componente com media queries simples: implementar cada experiência conforme seu próprio design. O corte entre Web e Mobile é **`720px`** — detalhe em [`docs/origin/release-notes.md`](docs/origin/release-notes.md). Diferenças confirmadas no DS (exemplos): títulos de seção usam Heading Medium 27px no desktop e Heading Small 23px no mobile; carrosséis usam dots no desktop e "Progress Bar" no mobile; os cards Glass encolhem no mobile (os demais cards não); "Ver mais" é botão outline no desktop e link sublinhado no mobile; footer muda de grid (desktop) para coluna única (mobile). Sempre conferir os dois no DS/Figma antes de implementar uma seção. ### Wireframe (fonte da verdade para estrutura) - **URL:** `https://www.figma.com/design/NHchcsqwzjotWVANCXImkk/Wireframe` - Usar **exclusivamente a página "Wireframe v2"** — ignorar outras páginas do arquivo. - Usar para: estrutura de seções, ordem de conteúdo e layout de cada página do site. ### Regra de precedência Em caso de divergência entre wireframe e design system, o **design system prevalece**. Ao citar componentes nas instruções, usar o **nome exato do Figma** (ex.: `Button/Primary/Default`). --- ## Ritual obrigatório antes de qualquer implementação frontend ### Antes de criar qualquer componente ou página: 1. Consultar o **Design System no Figma via MCP** — ler o componente pelo nome exato. 2. Verificar se já existe em `resources/js/components/ui/` — reutilizar antes de criar. 3. Usar os **tokens** definidos em `resources/css/app.css` e `tailwind.config.ts` — nunca hex inline. 4. Seguir a estrutura de features descrita neste documento. ### Ao criar uma nova página (passo a passo obrigatório): ``` 1. Ler o wireframe da página no Figma via MCP (página "Wireframe v2") 2. Ler os componentes referenciados na página no Design System via MCP 3. Verificar quais componentes já existem em resources/js/components/ui/ e features/ 4. Montar a página compondo componentes existentes — não recriar o que já existe 5. Criar apenas o que for genuinamente novo, seguindo a estrutura de features/ 6. Pages/.tsx deve ser apenas wrapper Inertia — lógica e seções ficam na feature ``` --- ## Estrutura de pastas (padrão único) ``` resources/js/ components/ ui/ # apenas componentes globais reutilizados em 2+ features Button.tsx Card.tsx SectionTitle.tsx Eyebrow.tsx ArrowButton.tsx features/ / # ex.: home, about, investors, contact Page.tsx # orquestra a página (seções + dados + layout da feature) sections/ components/ # componentes locais da feature data/ assets.ts # URLs/paths centralizados hooks/ types.ts enums.ts constants.ts index.ts # barrel opcional — só se reduzir ruído de imports lib/ motion/ variants.ts # fadeUp, stagger, viewport, etc. compartilhados Pages/ *.tsx # fino: apenas Inertia + import de + props ``` --- ## Páginas do projeto | Página | Arquivo Inertia | Feature | |---|---|---| | Home | `Pages/Home.tsx` | `features/home/` | | Financiamento de Carro | `Pages/FinanciamentoCarro.tsx` | `features/financiamento-carro/` | | Financiamento de Moto | `Pages/FinanciamentoMoto.tsx` | `features/financiamento-moto/` | | Financiamento de Caminhão | `Pages/FinanciamentoCaminhao.tsx` | `features/financiamento-caminhao/` | | Empréstimo com Garantia de Veículo | `Pages/EmprestimoGarantia.tsx` | `features/emprestimo-garantia/` | | Programa Elas | `Pages/ProgramaElas.tsx` | `features/programa-elas/` | | Renova Omni | `Pages/RenovaOmni.tsx` | `features/renova-omni/` | | Negocia Omni | `Pages/NegociaOmni.tsx` | `features/negocia-omni/` | | Omni Empresas | `Pages/OmniEmpresas.tsx` | `features/omni-empresas/` | | Segurança | `Pages/Seguranca.tsx` | `features/seguranca/` | | Atendimento | `Pages/Atendimento.tsx` | `features/atendimento/` | | FAQ | `Pages/Faq.tsx` | `features/faq/` | | Agentes Omni | `Pages/AgentesOmni.tsx` | `features/agentes-omni/` | | Validador de Boletos | `Pages/ValidadorBoletos.tsx` | `features/validador-boletos/` | | SuperApp Omni | `Pages/SuperappOmni.tsx` | `features/superapp-omni/` | | Instituto Omni | `Pages/InstitutoOmni.tsx` | `features/instituto-omni/` | | Blog (listagem) | `Pages/Blog/Index.tsx` | `features/blog/` | | Blog (artigo) | `Pages/Blog/Show.tsx` | `features/blog/` | | A Omni | `Pages/AOmni.tsx` | `features/a-omni/` | | 404 | `Pages/NotFound.tsx` | `features/not-found/` | --- ## Convenção de nomes | Alvo | Convenção | Exemplo | |---|---|---| | Pasta de feature | `lowercase` com hífen | `financiamento-carro`, `renova-omni`, `blog` | | Arquivo de componente | `PascalCase.tsx` | `HeroSection.tsx`, `SimuladorForm.tsx` | | Hook | `use` + PascalCase em arquivo camelCase | `useSimulador.ts`, `useBlogCarrossel.ts` | | Tipos / interfaces | `PascalCase` | `FinanciamentoSettings`, `BlogArtigo` | | Enums ou unions nomeadas | `PascalCase` | `ProdutoTipo`, `FinanciamentoSectionId` | | Constantes | `UPPER_SNAKE_CASE` | `DEFAULT_SIMULADOR_SETTINGS`, `FAQ_ITEMS` | | Dados serializáveis | `camelCase` claro | `blogArtigos`, `faqItems`, `agentesAssets` | Evitar nomes genéricos (`data.ts`, `utils.ts`) sem prefixo de feature ou caso de uso. --- ## Regras de arquitetura 1. **`Pages/*.tsx` é fino** — não conter tipos grandes, arrays com JSX, nem lógica pesada. Apenas import do `` e passagem de props Inertia. 2. **Separação de contratos** — `types.ts`, `enums.ts`, `constants.ts` ficam fora de `Pages/`, dentro da feature. 3. **Dados serializáveis** — listas em `data/*.ts` como estruturas serializáveis. **Nunca** embutir JSX em arrays de conteúdo. 4. **Assets centralizados** — criar `data/assets.ts` por feature. Não espalhar `const img = '/images/...'` nas páginas. 5. **Animações** — variantes repetidas em `lib/motion/variants.ts`. Lógica específica (scroll, autoplay) em `hooks/` da feature. 6. **UI global** — `components/ui/` somente para o que for reutilizado com critério em 2+ features. Não criar "super-componentes" com dezenas de props. 7. **Componentes locais primeiro** — começar local na feature; promover para `components/ui/` apenas quando houver reuso real comprovado. --- ## Design system — tokens e estilo ### Regras absolutas (nunca violar) - **Nunca** usar hex inline no JSX (`text-[#FF0000]`, `style={{ color: '#...' }}`). - **Nunca** definir `fontFamily` espalhado no JSX (`font-['Nome']`, `style={{ fontFamily: '...' }}`). - Tipografia **sempre** via classe Tailwind derivada do tema — uma única configuração em `tailwind.config.ts`. - Cores e espaçamentos **sempre** via tokens semânticos (`text-brand-warm`, `bg-brand-orange`, etc.). - Dúvida sobre um token? Consultar `resources/css/app.css` antes de qualquer outra coisa. ### Tokens de referência > Atualizar com tokens reais após primeira leitura do Figma via MCP na sessão de setup. - Tokens de cor, tipografia e espaçamento devem estar em `resources/css/app.css` com `@theme`. - Classes semânticas derivadas devem estar configuradas em `tailwind.config.ts`. - Alterar o token em um lugar deve refletir no projeto inteiro. --- ## Separação de types, enums e contratos - `types.ts` — interfaces/types de props, DTOs e contratos externos. - `enums.ts` — enums ou union types para estados, variantes e categorias. - `constants.ts` — arrays fixos, labels, limites e defaults. - Preferir `type` para composição e unions; `interface` para objetos de contrato extensível. - Quebrar tipos grandes por seção/domínio (ex.: `HomeSettingsHero`, `HomeSettingsDifferentials`). - Manter tipos próximos da feature que consome — não centralizar tudo em um único arquivo global. --- ## Animações - Centralizar variantes em `lib/motion/variants.ts` (`fadeUp`, `fadeIn`, `stagger`, `viewport`, etc.). - Comportamentos específicos (scroll, autoplay) em `hooks/` da feature. - Reduz duplicação e padroniza timing/transições no projeto. --- ## O que nunca fazer - Criar hex inline ou `style` de cor/fonte no JSX. - Criar componentes globais sem reuso comprovado em 2+ features. - Colocar lógica pesada, tipos ou arrays grandes dentro de `Pages/*.tsx`. - Recriar um componente que já existe em `components/ui/`. - Aplicar visual sem consultar o Figma via MCP primeiro. - Embutir JSX em arrays de dados de conteúdo. - Espalhar `const img = '/images/...'` nas páginas — usar `data/assets.ts`. - Criar estruturas paralelas sem justificativa técnica registrada no PR. --- ## Plano de execução (fases) ### Fase 1 — Fundação - Consolidar convenções de pastas e nomes. - Criar `lib/motion/variants.ts` com variantes de animação compartilhadas. - Configurar tokens em `resources/css/app.css` e `tailwind.config.ts` com base no Design System do Figma. ### Fase 2 — Componentes base - Ler página de componentes do Design System via MCP. - Implementar `components/ui/` com os componentes globais (Button, Card, SectionTitle, etc.). - Garantir que cada componente reflita exatamente os tokens e variantes do Figma. ### Fase 3 — Páginas (uma por vez) - Para cada página da tabela acima, seguir o ritual obrigatório de nova página. - Extrair `features//` com sections, components, data, hooks, types, enums, constants. - `Pages/*.tsx` deve terminar cada fase sendo apenas wrapper. ### Fase 4 — Convergência de tokens - Substituir qualquer padrão de cor/tipo repetido por tokens semânticos. - Garantir fontes apenas via configuração global — sem dispersão no JSX. ### Fase 5 — Hardening - Limpeza de imports mortos. - Consistência final de tokens e naming entre features. - Checagem de regressão visual e build limpo. --- ## Critérios de aceite (Definition of Done) - [ ] Nenhuma página monolítica — responsabilidades separadas na estrutura de feature. - [ ] `types`, `enums`, `constants` fora de `Pages/*.tsx`. - [ ] Dados sem JSX embutido. - [ ] Tokens semânticos no lugar de hex inline em todo o projeto. - [ ] Hooks de comportamento separados da renderização. - [ ] `components/ui/` somente com reuso comprovado entre 2+ features. - [ ] Tipografia centralizada no tema Tailwind, sem dispersão no JSX. - [ ] Todo componente novo consultou o Figma via MCP antes de ser criado. - [ ] `Pages/*.tsx` são apenas wrappers Inertia. - [ ] Área nova no NeoCMS: seeder com o conteúdo atual da feature + testes Pest; front ainda não lê o CMS.