# ApexUI — Design System & Framework de Desenvolvimento
## Documento de Briefing Completo do Projeto

> **Propósito deste documento:** Descrever em detalhe tudo que foi planejado, construído e desejado para o projeto ApexUI, servindo como referência completa para qualquer IA ou desenvolvedor que for dar continuidade ao trabalho.

---

## 1. VISÃO GERAL DO PROJETO

### O que é
Um **Design System corporativo completo** para servir de base padrão de desenvolvimento de sistemas web. O objetivo é ter um conjunto de componentes, telas, padrões visuais e estrutura de projeto prontos — e a partir daí desenvolver qualquer software em cima desse padrão sem começar do zero.

### Filosofia central
- **Não ser genérico.** Quando alguém abrir o sistema, não pode parecer "mais um sistema padrão". Tem que ter identidade visual própria, sofisticada e memorável.
- **Glassmorphism como diferencial.** Efeito de vidro/vitrificado em cards, modais, sidebar — camadas translúcidas com blur que dão profundidade.
- **Responsividade acima de tudo.** Cada componente, cada tela, cada grid deve funcionar perfeitamente em mobile, tablet e desktop. Isso é prioridade máxima, não opcional.
- **Modo claro E escuro**, com claro como padrão. Ambos com qualidade visual igual — nenhum modo pode parecer esquecido.

### Nome do projeto
**ApexUI** — identidade visual com logo "Apex**UI**" onde "UI" aparece em destaque com a cor accent do gradiente.

---

## 2. STACK TECNOLÓGICA

### Back-end
- **PHP** (já instalado no servidor)
- **Apache** (já instalado no servidor)
- **Laravel** — framework PHP principal
- **Composer** — gerenciador de pacotes PHP
- **MySQL ou PostgreSQL** — banco de dados (a definir por projeto)

### Front-end
- **React** — biblioteca de interface (via Inertia.js + Breeze no Laravel)
- **Tailwind CSS** — estilização utilitária (compilado via Vite, não CDN)
- **Vite** — bundler e servidor de desenvolvimento
- **Node.js v22 + npm** — runtime para compilar assets

### Ambiente
- **Ubuntu 24.04 LTS** — sistema operacional do servidor
- **Inertia.js** — ponte entre Laravel e React (SPA sem API separada)

### Instalação do projeto Laravel
```bash
composer create-project laravel/laravel meu-projeto
cd meu-projeto
composer require laravel/breeze --dev
php artisan breeze:install react
npm install
npm run dev  # Terminal 2
php artisan serve  # Terminal 1
```

---

## 3. DESIGN SYSTEM — IDENTIDADE VISUAL

### Paleta de Cores

#### Modo Claro (padrão)
| Papel | Valor | Uso |
|---|---|---|
| Primária | `#7c3aed` (Violet 600) | Botões principais, acentos, gradiente |
| Secundária | `#4f46e5` (Indigo 600) | Gradiente sidebar, fundos escuros |
| Sidebar | `linear-gradient(175deg, #2d1b6b, #3730a3, #1e3a5f)` | Fundo da sidebar no modo claro |
| Chart 1 | `#7c3aed` | Gráficos, sparklines |
| Chart 2 | `#06b6d4` (Cyan) | Gráficos secundários |
| Chart 3 | `#f59e0b` (Amber) | Gráficos terciários |
| Chart 4 | `#10b981` (Emerald) | Status positivo, gráficos |
| Background | `bg-slate-100` | Fundo geral da aplicação |
| Cards | `bg-white border border-slate-200` | Cards padrão |

#### Modo Escuro
| Papel | Valor | Uso |
|---|---|---|
| Primária | `#a78bfa` (Violet 400) | Acentos no dark |
| Sidebar | `linear-gradient(175deg, #1a0f3d, #1e1b4b, #0c1929)` | Fundo sidebar dark |
| Background | `#0f1117` | Fundo geral dark |
| Cards | `#1e2433/80` com backdrop-blur | Cards dark |
| Chart 1 | `#a78bfa` | Gráficos dark |
| Chart 2 | `#22d3ee` | Cyan ajustado para dark |
| Chart 3 | `#fbbf24` | Amber ajustado |
| Chart 4 | `#34d399` | Emerald ajustado |

### Tipografia
- **Fonte principal:** DM Sans (Google Fonts) — corporativa, moderna, não genérica
- **Fonte código:** DM Mono
- Pesos usados: 300, 400, 500, 600, 700
- Import: `@import url('https://fonts.googleapis.com/css2?family=DM+Sans:...')`

### Glassmorphism — Padrão de Efeitos
```css
/* Glass padrão */
background: rgba(255,255,255,0.40);
backdrop-filter: blur(16px);
border: 1px solid rgba(255,255,255,0.60);

/* Glass forte (modais, overlays) */
background: rgba(255,255,255,0.60);
backdrop-filter: blur(24px);
border: 1px solid rgba(255,255,255,0.80);

/* Sidebar — glow no topo */
background: radial-gradient(ellipse at 50% -10%, rgba(167,139,250,0.35) 0%, transparent 70%);
```

### Borda e Arredondamento
- Cards: `rounded-2xl` (16px)
- Botões: `rounded-xl` (12px)
- Inputs: `rounded-xl` (12px)
- Badges: `rounded-full`
- Avatares/ícones pequenos: `rounded-lg` (8px)

### Sombras
- Cards padrão: `shadow-sm`
- Cards hover: `shadow-md`
- Modais: `shadow-2xl`
- Glow especial no logo: `box-shadow: 0 0 40px rgba(124,58,237,0.25)`

### Ícones
Todos construídos como componentes SVG inline (sem dependência externa). Stroke-based, strokeWidth 1.5, estilo corporativo profissional. Ícones disponíveis: Dashboard, Chart, Users, Settings, Bell, Search, Moon, Sun, TrendUp, TrendDown, Filter, Columns, Download, Eye, EyeOff, ChevronDown/Left/Right, Plus, Edit, Trash, MoreVertical, Package, DollarSign, Activity, Globe, Menu, X, Check, AlertCircle, Info, Star, Map, Layers, Zap, Lock.

---

## 4. ARQUIVO BASE — DesignSystem.jsx

### Localização no projeto Laravel
```
resources/
  js/
    Components/
      DesignSystem/
        DesignSystem.jsx     ← arquivo principal
        index.js             ← exports dos componentes
    Pages/
      Dashboard.jsx          ← usa os componentes
```

### Estrutura do arquivo atual
O arquivo `DesignSystem.jsx` é um **showcase completo** com todas as telas e componentes em um único arquivo React. Contém:

1. **Bloco de ícones SVG** — todos inline, sem dependência
2. **Componentes de gráficos** — SparkLine, BarChart, DonutChart, AreaChart
3. **THEME config** — objeto com todas as classes Tailwind para light e dark
4. **Componentes base** — Card, GlassCard, Badge, Btn, KPI
5. **Páginas completas** — DashboardPage, AnalyticsPage, DataGridPage, ComponentsPage, UsersPage, SettingsPage
6. **Layout principal** — sidebar, header, área de conteúdo

---

## 5. COMPONENTES IMPLEMENTADOS

### Layout
**Sidebar**
- Gradiente escuro violet → indigo → slate (mesmo no modo claro — isso é intencional)
- Largura: 240px expandida / 64px colapsada
- Botão de colapsar/expandir no rodapé
- Ícone + texto no modo expandido, só ícone no colapsado
- Item ativo com fundo `white/20` (glass) e ponto indicador
- Transição suave `cubic-bezier(.4,0,.2,1)`
- Glow roxo sutil no topo como efeito de luz

**Header**
- Sticky no topo, `z-20`
- Glassmorphism (`bg-white/85 backdrop-blur-xl`)
- Campo de busca global com ícone
- Botão de notificações com badge vermelho
- Toggle modo claro/escuro
- Avatar com inicial do usuário + dropdown

**Background (mesh gradient)**
- Radial gradients sobrepostos em 3 pontos (20%/50%, 80%/20%, 50%/80%)
- Cores muito sutis (3-6% opacidade) em violet, cyan e amber
- Cria profundidade sem poluir

### Componentes Atômicos

**Botões (Btn)**
Variantes: `primary` (gradiente), `secondary` (glass), `outline` (borda + glass), `ghost` (transparente), `danger` (vermelho)
Tamanhos: `sm`, `md`, `lg`
Suporte a ícone à esquerda via prop `icon`

**Badges**
Variantes: `green`, `red`, `amber`, `blue`, `violet`
Modo claro: fundo pastel + texto escuro + ring
Modo escuro: fundo 15% opacidade + texto claro + ring 30%

**Cards**
- `Card` — padrão com border, fundo branco/dark
- `GlassCard` — versão com glassmorphism forte

**KPI Cards**
- Label em caps + valor grande + sparkline integrada
- Indicador de variação com ícone de tendência (↑↓) + porcentagem colorida
- Ícone no canto com fundo colorido em 10% opacidade

### Gráficos (sem biblioteca externa)

Todos são SVG puro construídos via JavaScript:

**SparkLine** — linha com área preenchida abaixo, para KPI cards
**AreaChart** — gráfico de área com gradiente vertical, para análise de período
**BarChart** — barras agrupadas, para comparação por período
**DonutChart** — rosca com segmentos calculados matematicamente, para distribuição
**Heatmap** — grid de céluas coloridas por intensidade, para atividade por hora/dia

### Data Grid (Tabela Avançada)

Este é um dos componentes mais completos do sistema. Funcionalidades:

**Busca e Filtros**
- Campo de busca global que filtra em todos os campos simultaneamente
- Filtro por status com botões de seleção rápida (Todos / Ativo / Inativo / Pendente)
- Painel de filtros avançados expansível (perfil, range de score, data)
- Botão "Limpar filtros" para resetar tudo

**Controle de Colunas**
- Dropdown "Colunas" com lista de todas as colunas disponíveis
- Checkbox individual para mostrar/ocultar cada coluna
- Ícone de olho (Eye/EyeOff) por coluna
- As colunas visíveis são salvas em estado local

**Seleção de Linhas**
- Checkbox em cada linha para seleção individual
- Checkbox no cabeçalho para selecionar/deselecionar todas da página
- Quando há seleção: aparece botão de ação em lote (ex: excluir N selecionados)
- Linha selecionada muda de cor de fundo

**Ordenação**
- Clique no cabeçalho da coluna para ordenar
- Toggle entre crescente e decrescente
- Indicador visual (↑↓) na coluna ativa

**Ações por Linha**
- Três botões: Ver (olho) / Editar (lápis) / Excluir (lixeira)
- Cores: hover azul/amarelo/vermelho respectivamente
- Fundo glass nos botões

**Paginação**
- Controles de página com botões numerados
- Botões prev/next com disable automático
- Contador "Exibindo X–Y de Z"
- Configurável (padrão: 5 itens por página)

**Toolbar de Ações**
- Botão "Novo Registro" (primário)
- Botão "CSV" para exportação
- Botão "Filtros" que abre/fecha painel

**Progress Bar inline** (coluna Score)
- Barra de progresso dentro da célula
- Cor muda automaticamente por faixa (verde >85, amarelo >65, roxo abaixo)

### Componentes de Feedback

**Alerts inline** — 4 variantes (sucesso, erro, aviso, info) com ícone e texto
**Toast (notificação flutuante)** — aparece no canto superior direito com animação fade-in, some após 3 segundos
**Modal** — overlay com backdrop blur, animação fade-in, botões de cancelar/confirmar, fechamento por clique fora

### Formulários
- Input text com label + placeholder + foco com ring violet
- Select com chevron customizado
- Range slider (cor accent configurável)
- Toggle switch (on/off) com animação suave
- Todos com estados de foco estilizados

### Navegação
- Tabs com estilo pill (selecionado = gradiente, outros = glass)
- Breadcrumbs (estrutural, a implementar)

### Cards com Glassmorphism em Gradiente
Seção especial de showcase: cards com `bg-white/10 backdrop-blur-xl border border-white/20` sobre fundos com gradiente colorido — demonstra o efeito premium do glass sobre cor.

---

## 6. TELAS IMPLEMENTADAS

### Dashboard (página inicial)
**Seção 1 — KPIs:** 4 cards em grid 1→2→4 colunas (responsivo) com sparklines
- Receita Total, Usuários Ativos, Novos Pedidos, Satisfação

**Seção 2 — Gráficos:**
- Gráfico de área (receita mensal, 12 meses) com seletor de período (1M/3M/6M/1A)
- Gráfico donut (distribuição por produto) com legenda

**Seção 3 — Barras + Transações:**
- Gráfico de barras (vendas por dia da semana, agrupado)
- Lista de transações recentes com avatar, nome, descrição, valor e tempo

**Seção 4 — Banner de destaque:**
- Card com gradiente de fundo, padrão de pontos, texto e CTA
- Espaço para anunciar features novas do sistema

### Analytics
- Grid de 4 métricas com progress bars
- Dois gráficos de área lado a lado (sessões e conversões)
- Heatmap de atividade (7 dias × 24 horas) com escala de intensidade

### Data Grid
- Tabela completa (descrita na seção anterior)
- Dados de exemplo: usuários com nome, email, perfil, status, receita, data, score

### Components
- Showcase de todos os componentes do sistema
- Botões, badges, formulários, alerts, toasts, modal, tabs, glass cards

### Usuários
- Grid de cards de usuário (1→2→3 colunas)
- Cada card: avatar, nome, email, badges de perfil/status, métricas

### Configurações
- Lista de seções de configuração com ícone, título, descrição e chevron
- Estrutura: Perfil, Segurança, Notificações, Integrações, Faturamento, Avançado

---

## 7. RESPONSIVIDADE — REGRAS E PADRÕES

Esta é a **prioridade máxima** do projeto. Cada elemento deve ser construído mobile-first.

### Breakpoints Tailwind usados
- `sm:` — 640px+ (tablets pequenos)
- `md:` — 768px+ (tablets)
- `lg:` — 1024px+ (desktops)
- `xl:` — 1280px+ (telas grandes)

### Padrões de grid responsivo
```jsx
// KPI cards: 1 coluna no mobile, 2 no tablet, 4 no desktop
className="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-4 gap-4"

// Gráficos: empilhados no mobile, lado a lado no desktop
className="grid grid-cols-1 lg:grid-cols-3 gap-4"

// Tabela: scroll horizontal quando não couber
className="overflow-x-auto"

// Sidebar: escondida no mobile (hidden md:flex), visível no desktop
className="hidden md:flex"

// Textos e labels que somem em telas pequenas
className="hidden sm:block"
```

### Sidebar mobile
A sidebar não aparece no mobile (< 768px). O header tem um botão hamburguer que deve abrir um drawer lateral. O estado `mobileSidebar` já existe, mas o drawer mobile ainda precisa ser implementado.

### Tabela responsiva
Tabelas com muitas colunas usam `overflow-x-auto` com `min-w-max` na tabela interna para scroll horizontal. Em mobile, considerar view alternativa em cards.

---

## 8. PADRÕES DE CÓDIGO

### Estrutura de componente
```jsx
// Componente recebe sempre `t` (tema) e `dark` (boolean)
function MeuComponente({ t, dark }) {
  return (
    <div className={`${t.card} rounded-2xl p-5`}>
      <h3 className={`font-semibold ${t.text}`}>Título</h3>
      <p className={`text-sm ${t.textMuted}`}>Descrição</p>
    </div>
  );
}
```

### Sistema de tema
O arquivo usa um objeto `THEME` com dois modos. Todos os componentes recebem `t = THEME.light ou THEME.dark` e usam as classes de lá. Isso permite trocar o tema sem alterar componentes.

```js
// Propriedades do tema disponíveis:
t.bg          // fundo da aplicação
t.sidebar     // classes da sidebar
t.sidebarGradient // gradiente inline da sidebar
t.card        // fundo e borda dos cards
t.glass       // efeito glass padrão
t.glassStrong // efeito glass forte (modais)
t.text        // texto principal
t.textMuted   // texto secundário
t.textLight   // texto terciário / labels
t.header      // header
t.input       // inputs de formulário
t.tableRow    // hover de linha de tabela
t.tableHead   // cabeçalho de tabela
t.divider     // bordas divisórias
t.badge       // objeto com variantes de badge
t.menuActive  // item ativo no menu
t.menuHover   // hover de item do menu
t.menuDivider // divisória interna da sidebar
t.gradient    // gradiente "from-violet to-indigo"
t.accent      // cor accent em hex
t.chart1-4    // cores dos gráficos
```

### Scrollbar personalizada
```css
::-webkit-scrollbar { width: 4px; height: 4px; }
::-webkit-scrollbar-track { background: transparent; }
::-webkit-scrollbar-thumb { border-radius: 999px; }
```

### Animação de entrada de página
```css
.animate-fade-in { animation: fadeIn 0.4s ease; }
@keyframes fadeIn { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; } }
```

---

## 9. O QUE AINDA FALTA IMPLEMENTAR

### Alta prioridade
- [ ] **Drawer sidebar mobile** — o estado `mobileSidebar` existe mas o componente do drawer ainda não foi criado
- [ ] **Separar componentes** — dividir o DesignSystem.jsx monolítico em arquivos individuais (Card.jsx, DataTable.jsx, KpiCard.jsx, Sidebar.jsx, etc.)
- [ ] **Integração com Laravel/Inertia** — adaptar as páginas para usar os controllers e rotas do Laravel
- [ ] **Autenticação** — tela de Login, tela de Cadastro, tela de Recuperação de senha (todas no padrão visual do design system)

### Média prioridade
- [ ] **Breadcrumbs** — componente de navegação hierárquica no header/topo das páginas
- [ ] **Notificações dropdown** — painel ao clicar no sino com lista de notificações
- [ ] **Avatar dropdown** — menu ao clicar no avatar com perfil/configurações/logout
- [ ] **Paginação server-side** — integração da paginação do DataGrid com Laravel Pagination
- [ ] **Formulário completo** — página de criação/edição com todos os tipos de input
- [ ] **Tela de erro** — 404, 403, 500 no padrão visual

### Baixa prioridade / Melhorias visuais
- [ ] **Mais tipos de gráfico** — linha múltipla, radar, funil
- [ ] **Dark mode persistence** — salvar preferência no localStorage
- [ ] **Skeleton loading** — placeholders animados enquanto dados carregam
- [ ] **Drag-and-drop colunas** — reordenar colunas na tabela arrastando
- [ ] **Exportação real** — integrar botões CSV/Excel com backend
- [ ] **Tema de cores configurável** — trocar a cor primária (violet) por outras opções

---

## 10. COMO TRABALHAR COM ESTE PROJETO

### Fluxo de desenvolvimento recomendado

**1. Setup inicial (uma vez)**
```bash
# No servidor Ubuntu 24.04
sudo apt install -y nodejs php-mbstring php-xml php-bcmath php-curl php-zip php-mysql
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt install -y nodejs
curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer

composer create-project laravel/laravel apexui
cd apexui
composer require laravel/breeze --dev
php artisan breeze:install react
npm install
```

**2. Colocar o DesignSystem.jsx**
```
resources/js/Pages/DesignSystem.jsx
```

**3. Rodar o projeto**
```bash
# Terminal 1
php artisan serve

# Terminal 2
npm run dev
```

**4. Para cada nova feature:**
- Criar rota no `routes/web.php`
- Criar controller em `app/Http/Controllers/`
- Criar Page em `resources/js/Pages/`
- Reutilizar componentes do design system

### Como pedir melhorias para uma IA

Ao passar este documento para outra IA, incluir sempre:
1. Este arquivo de briefing completo
2. O arquivo `DesignSystem.jsx` atual
3. A descrição específica do que quer implementar

**Exemplos de prompts eficazes:**
- *"Com base no briefing e no DesignSystem.jsx, implemente o drawer de sidebar para mobile com animação slide-in da esquerda"*
- *"Separe o DesignSystem.jsx em componentes individuais mantendo o mesmo sistema de tema `t`"*
- *"Crie a tela de Login no padrão visual do ApexUI com glassmorphism, campos de email e senha, botão de entrar com gradiente"*
- *"Adicione ao DataGrid a funcionalidade de drag-and-drop para reordenar colunas"*

---

## 11. DECISÕES DE DESIGN TOMADAS

| Decisão | Motivo |
|---|---|
| Sidebar com gradiente escuro no modo claro | Evitar o visual "brancão", dar identidade forte, separar visualmente da área de conteúdo |
| Sem biblioteca de componentes externa (Shadcn, MUI, etc.) | Controle total sobre o visual, zero dependências de UI |
| Ícones SVG inline sem lib | Performance, sem dependência, customizáveis por prop |
| Gráficos sem Recharts/Chart.js | Zero dependência, controle total do visual |
| DM Sans como fonte | Corporativa mas com personalidade, diferente do genérico Inter/Roboto |
| Gradiente violet → indigo como primária | Sofisticado, não é o roxo barato comum, tem profundidade |
| Glassmorphism como padrão de destaque | Diferencia do "sistema padrão", cria profundidade sem poluição visual |
| Tailwind com Vite (não CDN) | CDN não compila classes arbitrárias, Vite garante compilação completa |

---

## 12. REFERÊNCIAS TÉCNICAS

### Documentação
- Laravel: https://laravel.com/docs
- Inertia.js: https://inertiajs.com
- React: https://react.dev
- Tailwind CSS: https://tailwindcss.com/docs
- Vite: https://vitejs.dev

### Versões recomendadas
- PHP: 8.2+
- Node.js: 22 LTS
- Laravel: 11.x
- React: 18.x
- Tailwind: 3.x

---

*Documento gerado em: Abril 2025*
*Projeto: ApexUI Design System*
*Stack: Laravel + React + Tailwind + Inertia.js*
*Ambiente: Ubuntu 24.04 LTS + Apache + PHP*