xertica-ui 1.0.0 → 1.2.0

package/guidelines/Guidelines.md

@@ -1,61 +1,658 @@
-**Add your own guidelines here**
-<!--
+# Xertica UI - Project Guidelines
 
-System Guidelines
+## 📋 Visão Geral do Projeto
 
-Use this file to provide the AI with rules and guidelines you want it to follow.
-This template outlines a few examples of things you can add. You can add your own sections and format it to suit your needs
+O **Xertica UI** é um Design System completo construído com React e Tailwind CSS v4.0, seguindo uma arquitetura **CLI-first** (modelo shadcn/ui). O sistema está 100% pronto para publicação no NPM e todos os componentes são portáveis, independentes e reutilizáveis.
 
-TIP: More context isn't always better. It can confuse the LLM. Try and add the most important rules you need
+---
 
-# General guidelines
+## 🎨 Design System - Princípios Fundamentais
 
-Any general rules you want the AI to follow.
-For example:
+### Variáveis CSS Semânticas
 
-* Only use absolute positioning when necessary. Opt for responsive and well structured layouts that use flexbox and grid by default
-* Refactor code as you go to keep code clean
-* Keep file sizes small and put helper functions and components in their own files.
+**REGRA CRÍTICA**: Todos os componentes e páginas DEVEM usar exclusivamente as variáveis CSS definidas em `/styles/xertica/tokens.css`.
 
---------------
+#### Cores
+```css
+/* Sempre use as variáveis semânticas */
+var(--background)
+var(--foreground)
+var(--card)
+var(--card-foreground)
+var(--primary)
+var(--primary-foreground)
+var(--secondary)
+var(--secondary-foreground)
+var(--muted)
+var(--muted-foreground)
+var(--accent)
+var(--accent-foreground)
+var(--destructive)
+var(--destructive-foreground)
+var(--border)
+var(--input)
+var(--ring)
+var(--chart-1) até var(--chart-5)
+```
 
-# Design system guidelines
-Rules for how the AI should make generations look like your company's design system
+#### Espaçamentos
+```css
+/* Use os tokens de spacing */
+var(--spacing-xs)    /* 4px */
+var(--spacing-sm)    /* 8px */
+var(--spacing-md)    /* 16px */
+var(--spacing-lg)    /* 24px */
+var(--spacing-xl)    /* 32px */
+var(--spacing-2xl)   /* 48px */
+var(--spacing-3xl)   /* 64px */
+```
 
-Additionally, if you select a design system to use in the prompt box, you can reference
-your design system's components, tokens, variables and components.
-For example:
+#### Bordas e Raios
+```css
+var(--radius)        /* Border radius padrão */
+var(--radius-sm)     /* Border radius pequeno */
+var(--radius-lg)     /* Border radius grande */
+var(--radius-full)   /* Border radius circular */
+```
 
-* Use a base font-size of 14px
-* Date formats should always be in the format “Jun 10”
-* The bottom toolbar should only ever have a maximum of 4 items
-* Never use the floating action button with the bottom toolbar
-* Chips should always come in sets of 3 or more
-* Don't use a dropdown if there are 2 or fewer options
+#### Tipografia
 
-You can also create sub sections and add more specific details
-For example:
+**REGRA CRÍTICA**: Apenas a fonte **Roboto** pode ser utilizada (definida em `/styles/globals.css`).
 
+```css
+/* Importado no globals.css */
+@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700;800&display=swap');
 
-## Button
-The Button component is a fundamental interactive element in our design system, designed to trigger actions or navigate
-users through the application. It provides visual feedback and clear affordances to enhance user experience.
+/* Font weights disponíveis */
+font-weight: 400;  /* Regular */
+font-weight: 500;  /* Medium */
+font-weight: 600;  /* Semibold */
+font-weight: 700;  /* Bold */
+font-weight: 800;  /* Extra Bold */
+```
 
-### Usage
-Buttons should be used for important actions that users need to take, such as form submissions, confirming choices,
-or initiating processes. They communicate interactivity and should have clear, action-oriented labels.
+**NÃO use** classes Tailwind para font-size, font-weight ou line-height, **A MENOS** que o usuário solicite explicitamente.
 
-### Variants
-* Primary Button
-  * Purpose : Used for the main action in a section or page
-  * Visual Style : Bold, filled with the primary brand color
-  * Usage : One primary button per section to guide users toward the most important action
-* Secondary Button
-  * Purpose : Used for alternative or supporting actions
-  * Visual Style : Outlined with the primary color, transparent background
-  * Usage : Can appear alongside a primary button for less important actions
-* Tertiary Button
-  * Purpose : Used for the least important actions
-  * Visual Style : Text-only with no border, using primary color
-  * Usage : For actions that should be available but not emphasized
--->
+---
+
+## 🧩 Componentes do Design System
+
+### Localização
+Todos os componentes do Design System estão em `/components/ui/` (156 componentes disponíveis).
+
+### Regra de Ouro: REUTILIZE, NÃO RECRIE
+
+**SEMPRE**:
+1. ✅ Use componentes existentes em `/components/ui/`
+2. ✅ Consulte os componentes disponíveis antes de criar novos
+3. ✅ Combine componentes existentes para criar funcionalidades complexas
+4. ✅ Estenda componentes existentes com props adicionais se necessário
+
+**NUNCA**:
+1. ❌ Crie versões personalizadas de componentes que já existem
+2. ❌ Crie componentes inline que duplicam funcionalidades existentes
+3. ❌ Ignore os componentes do design system
+
+### Componentes Principais Disponíveis
+
+#### Layout & Estrutura
+- `Card`, `CardHeader`, `CardTitle`, `CardContent`, `CardFooter`
+- `Separator`
+- `ScrollArea`
+- `Sheet`
+- `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
+- `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
+- `Collapsible`
+- `Resizable`, `ResizablePanel`, `ResizablePanelGroup`, `ResizableHandle`
+
+#### Navegação
+- `Breadcrumb`
+- `NavigationMenu`
+- `Menubar`
+- `Sidebar` (componente especializado do Xertica)
+- `PageHeader` (componente especializado do Xertica)
+
+#### Formulários
+- `Input`
+- `Textarea`
+- `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`
+- `Checkbox`
+- `RadioGroup`, `RadioGroupItem`
+- `Switch`
+- `Slider`
+- `Calendar`
+- `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage`
+- `Label`
+- `InputOTP`
+- `FileUpload`
+- `Search`
+
+#### Botões & Ações
+- `Button` (variants: default, destructive, outline, secondary, ghost, link)
+- `Toggle`, `ToggleGroup`
+- `DropdownMenu`
+- `ContextMenu`
+
+#### Feedback
+- `Alert`, `AlertTitle`, `AlertDescription`
+- `AlertDialog`
+- `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`
+- `Drawer`
+- `toast` (Sonner)
+- `Progress`
+- `Skeleton`
+- `Badge`
+- `NotificationBadge`
+
+#### Dados & Visualização
+- `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableCell`
+- `Chart` (Recharts integration)
+- `StatsCard`
+- `Avatar`, `AvatarImage`, `AvatarFallback`
+- `Empty`
+- `Rating`
+- `Timeline`
+- `TreeView`
+
+#### Navegação & Tour
+- `Stepper`, `StepperItem`
+- `Pagination`
+- `Command`, `CommandInput`, `CommandList`, `CommandItem`, `CommandGroup`
+
+#### Overlays
+- `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`
+- `Popover`, `PopoverTrigger`, `PopoverContent`
+- `HoverCard`, `HoverCardTrigger`, `HoverCardContent`
+
+#### Especialidades Xertica
+- `Map`, `SimpleMap`, `RouteMap` (Google Maps integration)
+- `XerticaAssistant` (Assistente IA integrado)
+
+---
+
+## 🎯 Ícones
+
+**REGRA CRÍTICA**: Apenas ícones do **lucide-react** podem ser utilizados.
+
+```tsx
+import { Home, User, Settings, FileText, ChevronRight, Menu } from 'lucide-react';
+
+// Uso
+<Home className="w-5 h-5" />
+<Settings className="w-6 h-6 text-primary" />
+```
+
+**NÃO use**:
+- ❌ Font Awesome
+- ❌ Material Icons
+- ❌ SVGs customizados (a menos que absolutamente necessário)
+- ❌ Qualquer outra biblioteca de ícones
+
+---
+
+## 📄 Estrutura de Páginas
+
+### Anatomia de uma Página Padrão
+
+Todas as páginas devem seguir esta estrutura:
+
+```tsx
+import React from 'react';
+import { Card, CardContent, CardHeader, CardTitle } from './ui/card';
+import { Button } from './ui/button';
+import { ScrollArea } from './ui/scroll-area';
+import { ChevronRight, Menu, IconName } from 'lucide-react';
+import { useLocation, useNavigate } from 'react-router';
+import { getRouteByPath } from '../routes';
+import { ThemeToggle } from './ThemeToggle';
+import { LanguageSelector } from './LanguageSelector';
+
+interface PageContentProps {
+  sidebarExpanded: boolean;
+  assistenteExpanded?: boolean;
+  onToggleSidebar?: () => void;
+  onToggleAssistente?: () => void;
+}
+
+export function PageContent({ 
+  sidebarExpanded, 
+  assistenteExpanded = false, 
+  onToggleSidebar, 
+  onToggleAssistente 
+}: PageContentProps) {
+  const location = useLocation();
+  const navigate = useNavigate();
+  
+  const currentRoute = getRouteByPath(location.pathname);
+  const breadcrumbLabel = currentRoute?.label || 'Página';
+
+  return (
+    <div 
+      className={`flex-1 flex flex-col overflow-hidden transition-all duration-300 ${
+        sidebarExpanded ? 'md:pl-64' : 'md:pl-20'
+      } ${
+        assistenteExpanded ? 'md:pr-[420px]' : 'md:pr-20'
+      }`}
+    >
+      {/* Header fixo */}
+      <header className="bg-card shadow-sm border-b border-border px-[24px] py-[14px] flex-shrink-0">
+        <div className="flex items-center justify-between p-[0px]">
+          <div className="flex items-center gap-2 text-muted-foreground">
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={onToggleSidebar}
+              className="md:hidden mr-2 p-2"
+            >
+              <Menu className="w-5 h-5" />
+            </Button>
+            <span className="text-primary font-medium">Xertica.ai</span>
+            <ChevronRight className="w-4 h-4" />
+            <span className="text-foreground font-medium">{breadcrumbLabel}</span>
+          </div>
+          
+          <div className="flex items-center gap-3">
+            <LanguageSelector variant="minimal" showIcon={false} className="hidden sm:flex" />
+            <ThemeToggle className="hover:bg-accent" />
+          </div>
+        </div>
+      </header>
+
+      {/* Área de conteúdo */}
+      <main className="flex-1 overflow-hidden bg-muted">
+        <ScrollArea className="h-full">
+          <div className="p-2 sm:p-4 md:p-6">
+            <div className="max-w-6xl mx-auto space-y-8">
+              {/* Cabeçalho da página */}
+              <div className="space-y-2">
+                <h2>Título da Página</h2>
+                <p className="text-muted-foreground">
+                  Descrição da página
+                </p>
+              </div>
+
+              {/* Conteúdo principal */}
+              <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+                {/* Cards e conteúdo aqui */}
+              </div>
+            </div>
+          </div>
+        </ScrollArea>
+      </main>
+    </div>
+  );
+}
+```
+
+### Componentes Obrigatórios de uma Página
+
+1. **Header** com breadcrumb
+2. **Menu toggle** para mobile
+3. **ThemeToggle** e **LanguageSelector**
+4. **ScrollArea** para conteúdo scrollável
+5. **Responsividade** para sidebar e assistente
+6. **Espaçamento padronizado** (`p-2 sm:p-4 md:p-6`)
+7. **Container centralizado** (`max-w-6xl mx-auto`)
+
+---
+
+## 🗂️ Hierarquia e Navegação
+
+### Páginas Primárias (Top-Level)
+
+Quando criar uma **nova página primária**:
+
+#### 1. Criar o arquivo da página
+```
+/components/MinhaNovaPage.tsx
+/components/MinhaNovaContent.tsx
+```
+
+#### 2. Adicionar rota em `/routes.tsx`
+```tsx
+import { MinhaIcon } from 'lucide-react';
+
+export const routes: RouteConfig[] = [
+  {
+    path: '/home',
+    label: 'Home',
+    icon: Home,
+  },
+  {
+    path: '/minha-nova-pagina',
+    label: 'Minha Nova Página',
+    icon: MinhaIcon,
+  },
+  // ... outras rotas
+];
+```
+
+#### 3. Adicionar ao Sidebar (`/components/Sidebar.tsx`)
+O Sidebar lê automaticamente de `routes.tsx`, mas verifique se está sendo renderizado corretamente.
+
+#### 4. Adicionar card na Home (`/components/HomeContent.tsx`)
+```tsx
+<Card className="hover:shadow-xl transition-shadow duration-200 flex flex-col h-full">
+  <CardHeader>
+    <div className="flex items-center gap-3">
+      <div className="p-2 bg-[var(--chart-2)]/20 rounded-[var(--radius)]">
+        <MinhaIcon className="w-6 h-6 text-[var(--chart-2)]" />
+      </div>
+      <CardTitle className="text-sm">Minha Nova Página</CardTitle>
+    </div>
+  </CardHeader>
+  <CardContent className="flex-1">
+    <p className="text-muted-foreground">
+      Descrição da funcionalidade
+    </p>
+  </CardContent>
+  <CardFooter>
+    <Button 
+      variant="outline"
+      className="w-full"
+      onClick={() => navigate('/minha-nova-pagina')}
+    >
+      Acessar
+    </Button>
+  </CardFooter>
+</Card>
+```
+
+#### 5. Adicionar roteamento em `/App.tsx`
+```tsx
+import { MinhaNovaPage } from './components/MinhaNovaPage';
+
+// No componente App
+{location.pathname === '/minha-nova-pagina' && (
+  <MinhaNovaPage 
+    sidebarExpanded={sidebarExpanded}
+    assistenteExpanded={assistenteExpanded}
+    onToggleSidebar={toggleSidebar}
+    onToggleAssistente={toggleAssistente}
+  />
+)}
+```
+
+### Sub-Páginas (Nested Routes)
+
+Quando criar uma **sub-página**:
+
+#### 1. Estrutura de arquivos
+```
+/components/PaginaPrincipal.tsx
+/components/PaginaPrincipalContent.tsx
+/components/SubPagina.tsx (se necessário página separada)
+```
+
+#### 2. Adicionar ao routes.tsx com hierarquia
+```tsx
+export const routes: RouteConfig[] = [
+  {
+    path: '/pagina-principal',
+    label: 'Página Principal',
+    icon: MainIcon,
+    children: [
+      {
+        path: '/pagina-principal/sub-pagina',
+        label: 'Sub Página',
+        icon: SubIcon,
+      }
+    ]
+  },
+];
+```
+
+#### 3. Renderizar sub-navegação na página pai
+```tsx
+// Na PaginaPrincipalContent.tsx
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Visão Geral</TabsTrigger>
+    <TabsTrigger value="sub-pagina">Sub Página</TabsTrigger>
+  </TabsList>
+  
+  <TabsContent value="overview">
+    {/* Conteúdo principal */}
+  </TabsContent>
+  
+  <TabsContent value="sub-pagina">
+    {/* Conteúdo da sub-página */}
+  </TabsContent>
+</Tabs>
+```
+
+#### 4. Ou usar navegação tradicional
+```tsx
+<Button onClick={() => navigate('/pagina-principal/sub-pagina')}>
+  Ir para Sub Página
+</Button>
+```
+
+---
+
+## 🎨 Tailwind CSS v4.0
+
+### Uso Correto
+
+**SEMPRE**:
+- ✅ Use classes utilitárias do Tailwind
+- ✅ Use arbitrary values quando necessário: `bg-[var(--primary)]`
+- ✅ Use variáveis CSS: `text-[var(--foreground)]`
+- ✅ Use classes responsivas: `md:grid-cols-2 lg:grid-cols-3`
+
+**NUNCA**:
+- ❌ Crie classes CSS customizadas (exceto em casos extremos)
+- ❌ Use inline styles (use classes Tailwind)
+- ❌ Modifique `/styles/xertica/tokens.css` sem aprovação
+- ❌ Crie `tailwind.config.js` (estamos usando v4.0)
+
+### Classes Proibidas (a menos que solicitado)
+```css
+/* NÃO use sem solicitação explícita */
+text-xl, text-2xl, text-3xl      /* Font sizes */
+font-bold, font-semibold          /* Font weights */
+leading-tight, leading-relaxed    /* Line heights */
+```
+
+---
+
+## 📦 Bibliotecas e Imports
+
+### Bibliotecas Aprovadas
+
+#### Ícones (OBRIGATÓRIO)
+```tsx
+import { IconName } from 'lucide-react';
+```
+
+#### Gráficos
+```tsx
+import { ... } from 'recharts';
+```
+
+#### Animações
+```tsx
+import { motion } from 'motion/react'; // Nome atualizado (não Framer Motion)
+```
+
+#### Carrosséis
+```tsx
+import { ... } from 'react-slick';
+```
+
+#### Drag & Drop
+```tsx
+import { ... } from 'react-dnd';
+```
+
+#### Formulários
+```tsx
+import { ... } from 'react-hook-form@7.55.0'; // Versão específica obrigatória
+```
+
+#### Toast
+```tsx
+import { toast } from 'sonner@2.0.3'; // Versão específica obrigatória
+```
+
+### Bibliotecas Proibidas
+- ❌ `konva` / `react-konva` (não suportado)
+- ❌ `react-resizable` (use `re-resizable` ao invés)
+- ❌ Qualquer biblioteca de ícones além do `lucide-react`
+
+---
+
+## 🔄 Temas e Troca de Tema
+
+O sistema suporta troca de temas via atributo `data-theme` no root:
+
+```tsx
+// Uso do ThemeToggle
+import { ThemeToggle } from './ThemeToggle';
+
+<ThemeToggle />
+```
+
+Temas disponíveis são gerenciados em `/styles/xertica/theme-map.css`.
+
+---
+
+## 🌐 Internacionalização
+
+O sistema possui suporte a múltiplos idiomas:
+
+```tsx
+import { LanguageSelector } from './LanguageSelector';
+
+<LanguageSelector variant="minimal" showIcon={false} />
+```
+
+---
+
+## 📝 Boas Práticas Gerais
+
+### Estrutura de Arquivos
+```
+/components/
+  /ui/                  ← Componentes do Design System (NÃO MODIFICAR)
+  /examples/            ← Exemplos de uso
+  /media/               ← Componentes de mídia
+  MinhaPage.tsx         ← Página wrapper
+  MinhaPageContent.tsx  ← Conteúdo da página
+```
+
+### Nomenclatura
+- **Páginas**: `NomePage.tsx` e `NomePageContent.tsx`
+- **Componentes**: `PascalCase.tsx`
+- **Utilitários**: `camelCase.ts`
+- **Rotas**: `kebab-case` (`/minha-pagina`)
+
+### Imports
+```tsx
+// Componentes UI (sempre de /ui/)
+import { Button } from './ui/button';
+import { Card, CardHeader } from './ui/card';
+
+// Ícones (sempre lucide-react)
+import { Home, Settings } from 'lucide-react';
+
+// Contextos
+import { useTheme } from '../contexts/ThemeContext';
+
+// Router
+import { useNavigate, useLocation } from 'react-router';
+```
+
+### Responsividade
+Sempre use breakpoints mobile-first:
+```tsx
+className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3"
+className="p-2 sm:p-4 md:p-6"
+className="text-sm md:text-base"
+```
+
+### Acessibilidade
+- Use labels em inputs
+- Use aria-labels quando necessário
+- Mantenha contraste adequado (use variáveis do design system)
+- Suporte navegação por teclado
+
+---
+
+## 🚀 CLI-Ready e Portabilidade
+
+### Princípios CLI-First
+
+Todos os componentes devem:
+1. ✅ Ser independentes e não depender de CSS global oculto
+2. ✅ Usar apenas variáveis CSS semânticas de `tokens.css`
+3. ✅ Funcionar quando copiados para outro projeto
+4. ✅ Ter zero dependências de arquivos externos (exceto tokens.css)
+5. ✅ Ser publicáveis no NPM sem modificações
+
+### Overrides Opt-in
+
+Componentes podem ter overrides específicos usando atributos `data-*`:
+
+```tsx
+<div data-xertica-chat="true">
+  {/* Componente com estilo específico de chat */}
+</div>
+```
+
+Esses overrides são definidos em `/styles/xertica/app-overrides/`.
+
+---
+
+## ✅ Checklist: Antes de Criar Algo Novo
+
+Antes de criar qualquer componente ou página:
+
+- [ ] Consultei `/components/ui/` para ver se já existe?
+- [ ] Posso combinar componentes existentes ao invés de criar novo?
+- [ ] Estou usando APENAS variáveis CSS de `tokens.css`?
+- [ ] Estou usando APENAS ícones do `lucide-react`?
+- [ ] Estou usando a fonte Roboto (definida em globals.css)?
+- [ ] Segui a estrutura padrão de página (header, sidebar, conteúdo)?
+- [ ] Adicionei a rota em `routes.tsx`?
+- [ ] Adicionei card na Home (se página primária)?
+- [ ] Adicionei roteamento em `App.tsx`?
+- [ ] Testei responsividade (mobile, tablet, desktop)?
+- [ ] O componente é portável e CLI-ready?
+
+---
+
+## 🎓 Exemplos de Referência
+
+### Páginas Exemplo
+- `/components/HomePage.tsx` e `/components/HomeContent.tsx`
+- `/components/TemplatePage.tsx` e `/components/TemplateContent.tsx`
+- `/components/LoginPage.tsx`
+
+### Componentes Complexos
+- `/components/Sidebar.tsx` (navegação com subitens)
+- `/components/AssistenteXertica.tsx` (painel lateral)
+- `/components/ui/xertica-assistant.tsx` (componente especializado)
+
+### Uso de Componentes UI
+- `/components/examples/` (diversos exemplos de componentes)
+
+---
+
+## 📌 Notas Finais
+
+Este Design System foi construído para ser:
+- **Consistente**: Todos usam as mesmas variáveis e componentes
+- **Escalável**: Fácil adicionar novas páginas e funcionalidades
+- **Portável**: Componentes funcionam em qualquer projeto React
+- **Profissional**: Pronto para publicação no NPM
+- **Manutenível**: Estrutura clara e bem documentada
+
+**Lembre-se**: Quando em dúvida, consulte os componentes existentes e siga os padrões estabelecidos. A consistência é a chave para um Design System de sucesso.
+
+---
+
+**Última atualização**: Janeiro 2025
+**Versão**: 1.1.0
+**Arquitetura**: CLI-First (modelo shadcn/ui)
+**Status**: 100% CLI-Ready | Pronto para NPM