# Guia de Estilo Visual – GestorEasy

Este guia define padrões visuais e de interação a serem seguidos em todas as views do sistema, garantindo consistência, usabilidade e acessibilidade.

## Layout e Estrutura
- Todas as páginas autenticadas devem ser renderizadas com `View::renderWithLayout` usando `views/_layout.php`.
- O layout injeta o conteúdo dentro de `<main><div class="container">…</div></main>`. As views não devem incluir wrappers adicionais como `<main class="wrap">`.
- Utilize blocos `card` para organizar conteúdo: títulos, filtros, tabelas e formulários.
- Títulos principais com `<h1>`; subtítulos/áreas com `<h2>`/`<h3>` conforme necessidade.

## Tipografia e Cores
- Tipografia padrão: sistema (`-apple-system`, `Segoe UI`, `Roboto`, etc.).
- Tema claro/escuro controlado via `data-theme` no `html`, alternado pelo botão no header.
- Paleta principal (tokenizada no `theme.css`):
  - Ação primária: laranja (`var(--color-orange)`)
  - Destaque/links: oliva (`var(--color-olive)`)
  - Fundos: `var(--color-white)` e variações claras
  - Bordas: `var(--border-muted)`

## Espaçamentos e Alinhamentos
- Use espaçamentos compactos e consistentes:
  - `card`: `padding: 1.5rem; margin-bottom: 1rem`
  - `form-group`: `margin-bottom: 1rem`
- Alinhamentos em cabeçalhos/linhas de ação com `display:flex; gap:0.5rem; align-items:center;`.
- Evite margens superiores em títulos dentro do primeiro `card`.

## Componentes de Interface
- Botões
  - Primário: `.btn` (laranja)
  - Secundário: `.btn.btn-secondary` (cinza)
  - Perigo: `.btn.btn-danger`
  - Alternar tema: `#themeToggle` (controlado pelo layout)
- Inputs
  - Estruture inputs com `.form-group` + `label` + controle (`input`, `select`, `textarea`).
  - Realce de foco via tokens do tema (bordas/box-shadow verdes/oliva).
- Tabelas
  - Classe `.table` obrigatória; cabeçalho com `<th>` e conteúdo com `<td>`.
  - Linhas hover com fundo leve; use responsividade (`.table-responsive`) quando necessário.
- Alertas
  - Sucesso: `.alert.alert-success`
  - Erro: `.alert.alert-error`

## Header e Menus
- O header e menus são definidos pelo layout e não devem ser duplicados nas views.
- Itens de menu com `dropdown` e `dropdown-item`; ícones são injetados automaticamente.
- Controle de acesso: use `data-required-perm`/`data-required-role` nos itens quando aplicável.
- O item ativo é marcado automaticamente com base no `pathname` da rota.

## Formulários de Cadastros
- Reaproveitar `views/cadastros/entity.php` com campos dinâmicos por entidade.
- Máscaras e validações básicas de CPF/CNPJ/telefone aplicadas no frontend.
- Seleção de empresas carregada dinamicamente quando aplicável.
- Ações no modal: `Salvar` (primário) e `Cancelar` (secundário).

## Verificações de Conformidade
- O layout executa um validador leve em `DOMContentLoaded` (não intrusivo) que verifica:
  - Presença do container principal
  - Uso de `.card` para conteúdo
  - Botões com classe `.btn`
  - Tabelas com classe `.table`
  - Título presente (`h1/h2`)
- Ative um banner de avisos de UI (ambiente de desenvolvimento) com `localStorage.setItem('ui_check_banner','1')`.

## Diretrizes de Desenvolvimento
- Sempre usar `renderWithLayout` nas views autenticadas.
- Evitar CSS inline; preferir classes de tema/utilitários.
- Manter scripts específicos da página dentro da view; utilitários globais no layout.
- Para novas páginas, siga o padrão de estrutura: título → filtros/ações → listagem/formulário → feedback.

## Manutenção
- Ajustes de menus e permissões em `views/_layout.php`.
- Campos e regras de entidades em `modules/Cadastros/Controllers/CadastrosController.php` e `views/cadastros/entity.php`.
- Tema e tokens em `public/css/theme.css`.

---
Este guia deve ser revisado e expandido conforme evoluírem os componentes e necessidades do sistema.