# Xertica UI — Base de Conhecimento Completa > **Propósito deste documento:** esta é uma fonte de conhecimento única e exaustiva sobre a biblioteca **xertica-ui**, preparada para alimentar o **Knowledge Base do FDM** (Xertica Agent Engine). O objetivo é permitir que um assistente de IA responda com precisão qualquer dúvida sobre a xertica-ui — instalação, arquitetura, componentes, padrões de página, temas/branding, CLI, internacionalização, gerenciamento de estado, o assistente de IA embutido e as regras de uso obrigatórias para agentes de IA que geram código com esta biblioteca. **Biblioteca documentada:** `xertica-ui` v3.0.1 — design system React enterprise construído sobre **Tailwind CSS v4**, **Radix UI** e **Lucide Icons**, com uma camada de documentação "AI-first" (arquivos `llms.txt`, `llms-compact.txt`, `llms-full.txt`, `components.json`, `docs/decision-tree.md`) pensada para consumo por agentes de IA. **Como este documento foi construído:** consolidação de toda a documentação oficial do pacote (`docs/*.md`, `docs/components/*.md`, `docs/patterns/*.md`, `guidelines/Guidelines.md`, `guideline.md`, `README.md`, `package.json`) cruzada com leitura direta do código-fonte para confirmar comportamentos, detectar funcionalidades não documentadas e sinalizar divergências entre documentos. Onde a documentação e o código-fonte divergem, isso é explicitado na Seção 17 ("Divergências Conhecidas") em vez de escolhido silenciosamente. --- ## Sumário 1. [Visão Geral e Posicionamento](#1-visão-geral-e-posicionamento) 2. [Instalação e Configuração](#2-instalação-e-configuração) 3. [Arquitetura — FSD + FDA](#3-arquitetura-fsd--fda) 4. [Sistema de Layout](#4-sistema-de-layout) 5. [Gerenciamento de Estado](#5-gerenciamento-de-estado) 6. [Internacionalização (i18n)](#6-internacionalização-i18n) 7. [Sizing de Formulários](#7-sizing-de-formulários) 8. [Branding, Temas e Identidade Visual](#8-branding-temas-e-identidade-visual) 9. [Assistente de IA (XerticaAssistant)](#9-assistente-de-ia-xerticaassistant) 10. [CLI — `npx xertica-ui`](#10-cli--npx-xertica-ui) 11. [MCP — Model Context Protocol](#11-mcp--model-context-protocol) 12. [Guidelines e Regras Não-Negociáveis para IA](#12-guidelines-e-regras-não-negociáveis-para-ia) 13. [Uso por Agentes de IA — Protocolo de Consulta](#13-uso-por-agentes-de-ia--protocolo-de-consulta) 14. [Árvore de Decisão de Componentes](#14-árvore-de-decisão-de-componentes) 15. [Padrões de Página (Page Patterns)](#15-padrões-de-página-page-patterns) 16. [Referência Completa de Componentes (A–Z)](#16-referência-completa-de-componentes-az) 17. [Divergências Conhecidas e Notas de Precisão](#17-divergências-conhecidas-e-notas-de-precisão) --- --- ## 1. Visão Geral e Posicionamento ### Pitch > "Enterprise-grade React design system built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction." ### Principais diferenciais - **AI-first single source of truth**: `llms.txt`, `llms-compact.txt`, `llms-full.txt` e `docs/llms.md` como entry points dedicados para agentes de IA. - **CLI de scaffolding** (`npx xertica-ui@latest init`) que gera app completo com roteamento, layout e arquitetura FSD/FDA pré-configurados, incluindo modo monolíngue transparente e feature flags persistidas (`.xertica.json`, `.languages.json`). - **10 temas de cor embutidos**, selecionáveis no `init` ou via `npx xertica-ui update` → *Theme only*: | Tema | ID | Primary | Sidebar | Dark bg | |---|---|---|---|---| | Xertica Classic (default) | `xertica-original` | `#2C275B` | `#2C275B` | `#05050d` | | Xertica (identidade "serigrafia") | `xertica` | `#1E1E1E` | `#1E1E1E` | `#141311` | | Zinc | `zinc` | `#18181B` | `#18181B` | `#05050d` | | Slate | `slate` | `#0F172A` | `#0F172A` | `#05050d` | | Blue | `blue` | `#2563EB` | `#1E3A8A` | `#03050f` | | Violet | `violet` | `#7C3AED` | `#4C1D95` | `#07040f` | | Rose | `rose` | `#BE123C` | `#881337` | `#0f0305` | | Emerald | `emerald` | `#047857` | `#064E3B` | `#030f08` | | Amber | `amber` | `#B45309` | `#78350F` | `#0f0a03` | | Orange | `orange` | `#C2410C` | `#7C2D12` | `#0f0703` | O tema **`xertica`** tem identidade visual própria ("serigrafia"): botões pill-shaped (`--radius-button: 9999px`) com stroke visível em toda variante filled; accent geral (`--primary`) é Negro Xertica (`#1E1E1E`, `#F2EDD8` no dark); amarelo (`#FAF338`) fica restrito a apenas dois controles — `Button` variante `default` e o estado marcado do `Switch` — via `--button-primary-bg`/`--button-primary-foreground`; `secondary` button é preto; fundo de página é off-white quente (`#FFFEF8`) com cards em branco puro. Cada tema controla: `--primary` e `--sidebar` (light+dark), `--chart-1..5`, `--gradient-diagonal`, e (só no dark mode) `--background`/`--card`/`--popover`/`--muted`/`--accent`/`--border`/`--input`. Superfícies do modo claro permanecem sempre branco/zinc, exceto quando o tema define `backgroundLight` (só `xertica` faz isso). `--radius-button`/stroke/cores de `secondary` só mudam quando o tema define `buttonRadius`/`buttonStroke*`/`buttonSecondary*` (também só `xertica`). - Token `--mobile-content-padding` (default `1.25rem`) controla padding horizontal em telas < 768px. - **Contrato de independência de componente**: `xertica-ui/style.css` é o único import global obrigatório; componentes públicos são desenhados para funcionar isoladamente sem exigir `` para a maioria das primitivas (o provider é uma conveniência recomendada, não um requisito universal). Componentes com configuração externa inevitável (ex.: Google Maps) devem renderizar um estado de configuração/erro em vez de derrubar a app. > **Divergência de escala:** o README anuncia "**100+** Components" no título do catálogo, enquanto a contagem auditada em `docs/llms.md` é **84**. Ver nota na Seção 8. ### Stack tecnológica | Tecnologia | Versão | |---|---| | React | 18.3 | | TypeScript | 5.7 | | Tailwind CSS | 4.0 | | Vite | 6.0 | | Radix UI | Latest | | Lucide React | 0.469+ | | Vitest | 4.1 | ### Scripts principais `npm run dev` roda o scaffold `templates/` com o design system em live source (via alias de monorepo) — o mesmo app que um consumidor de `npx xertica-ui init` recebe; `npm run dev:pages` roda o harness raiz para o showcase standalone de `xertica-ui/pages`; `build`, `storybook`, `test` (Vitest), `type-check`. Nota: `templates/` tem dependências próprias — requer `npm install` dentro de `templates/` antes do primeiro `dev`. ### Licença Proprietária — Xertica.ai Team. ### Links relevantes - [`llms.txt`](./llms.txt) · [`llms-compact.txt`](./llms-compact.txt) · [`llms-full.txt`](./llms-full.txt) — entry points para agentes de IA - [`docs/llms.md`](./docs/llms.md) — índice mestre de documentação --- ## 2. Instalação e Configuração Xertica UI é um design system React enterprise-grade construído sobre **Tailwind CSS v4**, **Radix UI** e **Lucide Icons**, com uma camada de documentação "AI-first" pensada para composição precisa por LLMs e agentes autônomos. Cobre desde primitivas de UI até templates de página completos (login, dashboard, CRUD), assistente de IA embutido e integração com Google Maps. ### Requisitos e dependências - Node.js >= 18 - React >= 18 (stack de referência usa **React 18.3**) - Projeto Vite, Next.js ou CRA - **Peer dependencies obrigatórias** (não instaladas automaticamente em `npm install xertica-ui`): `react@^18`, `react-dom@^18`, `react-router-dom@^7` Pacotes recomendados (não são peer deps, mas esperados em projetos com arquitetura `features/`): | Pacote | Versão | Papel | |---|---|---| | `@tanstack/react-query` | `^5.x` | Server state | | `zustand` | `^5.x` | Client UI state | | `i18next` | `^26.x` | Motor de i18n | | `react-i18next` | `^17.x` | Binding React do i18next | ### Duas formas de instalar **A) CLI (recomendado para projeto novo)** ```bash npx xertica-ui@latest init ``` > Sempre use `@latest` — sem essa flag, o `npx` pode rodar uma versão local em cache em vez de buscar a mais recente do registry. Prompts interativos: | Prompt | Opções | |---|---| | Páginas a incluir | Login, Home, Template (multi-select) | | Idiomas suportados | pt-BR, English, Español (multi-select, mínimo 1) | | Tema de cor padrão | Xertica, Xertica Classic, Slate, Zinc, Blue, Violet, Rose, Emerald, Amber, Orange | | Habilitar dark mode? | sim (padrão) / não | | Incluir AI Assistant? | sim (padrão) / não | | Instalar dependências | sim / não | O `init`: cria a estrutura FSD/FDA, instala dependências, configura Tailwind v4, injeta `tokens.css`, copia **apenas as pastas de locale** dos idiomas escolhidos, escafolda condicionalmente o assistente (`AssistantPage`, `features/assistant/`) e persiste as escolhas em `src/locales/.languages.json` (`{ version: 1, codes: [...] }`) e `.xertica.json` (`{ version: 1, hasAssistant, disableDarkMode }`). **B) Instalação manual em projeto existente** ```bash npm install xertica-ui ``` 1. Importar CSS (deve vir **antes** dos seus próprios estilos): ```tsx import 'xertica-ui/style.css'; ``` 2. Configurar Tailwind para escanear a lib: ```js // tailwind.config.js export default { content: ['./src/**/*.{ts,tsx}', './node_modules/xertica-ui/**/*.{js,ts,jsx,tsx}'], }; ``` 3. Montar o *provider stack* completo na raiz. ### Provider stack (ordem importa) ```tsx import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { XerticaProvider } from 'xertica-ui/brand'; import { BrowserRouter as Router } from 'react-router-dom'; import { AuthProvider } from './app/context/AuthContext'; import { AppErrorBoundary, PageErrorBoundary } from './shared/error-boundary'; import 'xertica-ui/style.css'; const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 1, refetchOnWindowFocus: false } }, }); function App() { return ( ); } ``` Razão de cada camada, de fora para dentro: 1. `AppErrorBoundary` — captura qualquer crash, inclusive falha de providers 2. `QueryClientProvider` — habilita React Query para toda a árvore 3. `XerticaProvider` — tema, layout, toasts, tooltips, maps, contexto do assistente 4. `Router` — precisa vir antes de `AuthProvider` (usa `useNavigate`) 5. `AuthProvider` — sessão e guards de navegação 6. `PageErrorBoundary` — isola erros por página; o chrome do app continua vivo `XerticaProvider` inicializa internamente: sistema de tema (dark/light + injeção de tokens), toasts (Sonner via portal), `TooltipProvider` (Radix), `LayoutContext`, contexto do AI Assistant, `LanguageContext` (pt-BR/en/es por padrão) e o loader lazy do Google Maps. Seu único prop documentado é `children: ReactNode` (obrigatório). ### `useAuth()` / Route Guards `AuthContext` expõe `user: AuthUser | null`, `isLoading: boolean`, `login(email, password) => boolean`, `logout() => void`. `ProtectedRoute`/`GuestRoute` (gerados pela CLI em `AuthGuard.tsx`) sempre checam `isLoading` antes de redirecionar, para evitar *flash redirects* durante a hidratação do `localStorage`. ### CSS crítico — `@theme inline` O `src/styles/index.css` do consumidor deve seguir esta ordem exata: ```css @import 'xertica-ui/style.css'; /* 1. estilos compilados da lib */ @import './xertica/tokens.css'; /* 2. seus tokens de tema */ @source '../node_modules/xertica-ui'; /* 3. Tailwind escaneia a lib */ @theme inline { /* 4. MUST be `inline`, not plain @theme */ --color-primary: var(--primary); --color-destructive: var(--destructive); } ``` `@theme {}` puro compila os tokens de cor **estaticamente** no build, usando os valores default da lib; `@theme inline` preserva as referências `var()`, permitindo que `tokens.css` sobrescreva em runtime. Essa é a causa mais comum de "cores de tema não aplicam". ### Scripts do projeto escafoldado ```bash npm run dev / build / type-check / lint / lint:fix / format / format:check / check ``` ### Troubleshooting rápido | Sintoma | Causa | Fix | |---|---|---| | Componentes transparentes/sem estilo | Falta `import 'xertica-ui/style.css'` | Importar no entry, antes dos estilos próprios | | Dark mode não aplica | Falta classe `dark` no `` ou `@theme` sem `inline` | Usar `` ou corrigir CSS | | Erros de TS em subpath imports | `moduleResolution: "node"` | Trocar para `"bundler"`, `"node16"` ou `"nodenext"` | | Toasts não aparecem | Falta `` (que injeta ``) | Envolver a app; ou adicionar `` manualmente | | Dialogs/Modals não aparecem | Falta `` (contexto de portal/Tooltip) | Envolver a app na raiz | | `useLayout()` lança "must be used within LayoutProvider" | Componente fora de `` | Garantir ancestralidade; usar `useOptionalLayout()` se o componente pode existir fora (ex.: Storybook) | | Sidebar sobrepõe conteúdo | Área de conteúdo não lê `sidebarWidth` | Aplicar `sidebarWidth`/`sidebarExpanded` como `paddingLeft` | | Assistente de IA não responde (modo real) | Chave Gemini ausente/inválida | `initialGeminiApiKey` no provider, `useApiKey()`, ou `demoMode={true}` para testes | --- --- ## 3. Arquitetura — FSD + FDA ### 2.1 Domínios de componentes (dentro do pacote) | Domínio | Path | Conteúdo | |---|---|---| | `ui` | `components/ui/[name]/` | Primitivas do design system (Button, Card, Calendar, Chart...) | | `layout` | `components/layout/` | Sidebar, Header, SidebarPrimitive | | `blocks` | `components/blocks/` | Componentes compostos de alto nível a partir de `ui/` | | `assistant` | `components/assistant/` | XerticaAssistant, MarkdownMessage, CodeBlock etc. | | `brand` | `components/brand/` | XerticaLogo, ThemeToggle, LanguageSelector, XerticaProvider | | `pages` | `components/pages/` | LoginPage, HomePage, TemplatePage etc. | | `shared` | `components/shared/` | utils.ts, use-mobile.ts, layout-constants.ts, error-boundary.tsx, error-fallbacks.tsx | Cada domínio de componente tem um par de arquivo espelho em `docs/components/`. O pacote npm **inclui o código-fonte** (`components/`, `contexts/`, `hooks/`, `lib/`, `i18n.ts`, `locales/` — via campo `files` do `package.json`), justamente para que agentes de IA possam inspecionar implementação, stories e docs direto em `node_modules/xertica-ui/` — essa é a decisão de design "AI-first" central da lib. ### 2.2 Subpath exports ``` xertica-ui → components/index.ts (barrel completo) xertica-ui/ui → todas as primitivas de UI xertica-ui/blocks → padrões compostos (ActivityCard, ProjectCard...) xertica-ui/layout → Sidebar, Header xertica-ui/brand → XerticaProvider, XerticaLogo, ThemeToggle, LanguageSelector... xertica-ui/assistant → XerticaAssistant, MarkdownMessage, CodeBlock... xertica-ui/media → VideoPlayer, AudioPlayer, FloatingMediaWrapper xertica-ui/hooks → useLayout, useTheme, useLanguage, useBrandColors, useAssistente, useApiKey xertica-ui/pages → HomePage, TemplatePage (templates prontos) xertica-ui/style.css → folha de estilos compilada ``` > **Divergência de fontes:** `docs/architecture.md` (auditado em 2026-05-20) lista apenas **7** subpaths e não menciona `xertica-ui/pages`. O `README.md` raiz (mais recente, versão 3.0.1) já documenta e usa `xertica-ui/pages` ativamente (`import { TemplatePage } from 'xertica-ui/pages'`), inclusive alertando que `HomePage`/`TemplatePage` chamam `useAuth()` internamente e exigem `` como ancestral. Trate o README como fonte mais atual quanto ao número de subpaths. Cada subpath expõe `types` (`.d.ts`), `import` (ESM) e `require` (CJS/UMD). TypeScript exige `"moduleResolution": "bundler"` (ou `node16`/`nodenext`). ### 2.3 Estrutura FSD/FDA no projeto consumidor (gerado pela CLI) ``` src/ app/ ← BrowserRouter, XerticaProvider, AuthGuard, AppLayout shared/ config/ ← navigation.ts (definição de rotas) lib/ ← auth.ts (helpers de localStorage) types/ ← auth.ts (interface User) features/ auth/ui/ ← LoginContent, ForgotPasswordContent, VerifyEmailContent, ResetPasswordContent home/ data/mock.ts ← tipos + fetch tipado + factory functions (ex: getMockRichSuggestions()) hooks/ ← useFeatureCards() — queryKey language-aware store/ ← dashboardStore.ts (Zustand) ui/ ← HomeContent template/ui/ ← TemplateContent, FormTemplate assistant/ ← AssistantConfig + useAssistantConfig() (só quando o Assistant é incluído) pages/ ← wrappers finos: LoginPage, HomePage, TemplatePage, AssistantPage... styles/ ← index.css, xertica/tokens.css i18n.ts ← gerado pela CLI — imports/resources só dos idiomas selecionados locales/ / ← ver seção i18n .languages.json ``` **Regra de import entre camadas:** cada `feature` só importa de `shared/` ou de seu próprio domínio; `pages/` apenas compõe `features/` (nunca contém lógica de negócio própria). Cada slice `features//` segue a convenção: ``` features// ├── data/mock.ts ← tipos + dados mock + async fetch*() (ponto de troca p/ API real) ├── hooks/use.ts ← useQuery envolvendo o fetch, com queryKey language-aware ├── store/Store.ts ← Zustand, só se houver estado de UI client-side compartilhado ├── ui/Content.tsx └── index.ts ← barrel ``` > **Nota fonte-vs-template:** no código-fonte da própria lib, `features/home/hooks/` inclui `useDashboardStats.ts` e `useTeamMembers.ts`, usados apenas pelo showcase interno (`TemplateContent.tsx`). Esses dois hooks **não** são gerados no template escafoldado — projetos consumidores que precisarem deles devem criar seus próprios seguindo o mesmo padrão. ### 2.4 Padrão Headless UI (3 camadas de composabilidade) **Tier 1 — Monolítico (drop-in):** ```tsx ``` **Tier 2 — Compound Components (controle estrutural):** ```tsx } /> ``` **Tier 3 — Hooks Headless (controle total, zero UI):** | Hook | Import | Descrição | |---|---|---| | `useSidebar` | `xertica-ui/layout` | Expansão, overflow, estado de navegação | | `useAssistant` | `xertica-ui/assistant` | Estado completo: mensagens, conversas, handlers | | `useRichTextEditor` | `xertica-ui/ui` | Formatação, busca, gerenciamento de links | ```tsx const { expanded, toggleExpanded, navigationGroups } = useSidebar({ defaultExpanded: true }); const { mensagens, mensagem, setMensagem, handleEnviarMensagem } = useAssistant({ demoMode: true }); ``` Princípios de design: (1) o hook detém todo o estado — nada fica no componente apresentacional; (2) retrocompatível — Tier 1 nunca muda; (3) fonte única de verdade é o hook; (4) todos os handlers usam `useCallback`; (5) TypeScript-first com `Props`/`Return` explícitos para cada hook. ### 2.5 Notas internas de refatoração (`architecture-improvements.md`) Este documento (PT-BR, análise de Maio/2026) é uma **auditoria de qualidade do código-fonte da própria biblioteca** — não afeta como consumidores usam a lib, mas é útil contexto de "por quê" e "débito técnico conhecido": - **✅ Resolvido (v2.2.0):** `ThemeToggle` bypassava `ThemeContext` manipulando `classList` direto; corrigido, e o bug de `disableDarkMode` hard-coded em `templates/src/app/App.tsx`/`bin/language-config.ts` (que tornava `toggleTheme()` um no-op) também foi corrigido. - **✅ Resolvido (v2.1.9):** mock assíncrono via `setTimeout` foi extraído para o padrão *swap point* em `features/*/data/mock.ts` (ver Seção 4). - **Pendente (crítico):** tipos duplicados entre `contexts/AssistenteContext.tsx` (`Message`, `Conversa`, `SearchResult`...) e `components/assistant/xertica-assistant/xertica-assistant.tsx` (`Message` com campos diferentes, `Conversation` em vez de `Conversa`) — solução proposta: `types.ts` compartilhado. - **Pendente (alto):** detecção de mobile duplicada via `window.innerWidth < 768` em 4+ arquivos (`use-assistant.ts`, `use-sidebar.ts`, `AudioPlayer.tsx`, `LayoutContext.tsx`) em vez de reutilizar o hook `useIsMobile()` já existente (`components/shared/use-mobile.ts`, baseado em `matchMedia`); `AudioPlayer.tsx` (663 linhas) sem hook headless; `xertica-assistant.tsx` com **1573 linhas** aguardando decomposição em subcomponentes (`AssistantMessageList`, `AssistantHistoryTab` etc.). - **Pendente (médio/baixo):** `sidebar.tsx` com 1089 linhas; atalhos de teclado e persistência em cookie misturados dentro de `LayoutContext`; `hexToRgb` inline em `BrandColorsContext`; tooltips duplicados (`SidebarTooltipContent` ≈ `AssistantTooltipContent`); alturas hardcoded em `use-sidebar.ts`. - **Padrões de referência positivos**, citados como modelo a seguir: `useRichTextEditor` e `useTreeView` (este último com navegação por teclado WAI-ARIA no hook, não no componente). --- --- ## 4. Sistema de Layout O layout é um shell de três colunas gerenciado globalmente por `LayoutContext` (injetado por ``, incluído dentro de `` — nunca instanciado diretamente): ``` ┌──────────────┬─────────────────────────┬──────────────┐ │ Sidebar │ Main Content Area │ AI Panel │ │ (collapsed: │ paddingLeft = sidebar │ (assistant, │ │ 80px) │ (Header no topo) │ opcional) │ │ (expanded: │ │ │ │ sidebarWidth)│ │ │ └──────────────┴─────────────────────────┴──────────────┘ ``` Sidebar e AI Panel são **mutuamente exclusivos** — abrir um fecha o outro. Em mobile, a sidebar sobrepõe o conteúdo (overlay) em vez de empurrá-lo; o `Header` fornece o trigger de toggle. ### `useLayout()` — API completa ```tsx import { useLayout } from 'xertica-ui/hooks'; const { sidebarExpanded, // boolean, default false, persistido em cookie `sidebar_state` setSidebarExpanded, // (v: boolean) => void toggleSidebar, // () => void — fecha o assistente automaticamente sidebarWidth, // number, default 320 (px) — só afeta o estado expandido setSidebarWidth, // (width: number) => void assistenteExpanded, // boolean, default false setAssistenteExpanded, // (v: boolean) => void toggleAssistente, // () => void — fecha a sidebar automaticamente toggleAssistenteWithTab, // (tab: string) => void — abre o assistente numa aba específica isMobile, // boolean, default false — viewport < 768px } = useLayout(); ``` - O estado colapsado é **sempre 80px fixo** — nunca deve mudar. - Atalho global: `Ctrl+B` (Windows/Linux) ou `Cmd+B` (macOS) alterna a sidebar. - A `Sidebar` funciona de forma autônoma mesmo sem `LayoutProvider`, mas perde sincronização com outros componentes layout-aware. - Para componentes que podem existir fora do provider (ex.: Storybook), usar `useOptionalLayout()`, que retorna `null` em vez de lançar erro: ```tsx import { useOptionalLayout } from 'xertica-ui/hooks'; const layout = useOptionalLayout(); const sidebarWidth = layout?.sidebarWidth ?? 0; ``` ### Padrão de uso — conteúdo reagindo ao layout ```tsx function PageContent({ children }) { const { sidebarExpanded, sidebarWidth } = useLayout(); return (
{children}
); } ``` ### Regras para IA - Nunca usar `useState` para controlar sidebar/assistente — sempre `useLayout()`. - Nunca hardcodar `pl-64` ou `padding-left: 280px` — sempre ler `sidebarWidth`. - Usar `toggleSidebar()` / `toggleAssistente()` (não `setSidebarExpanded(true)` direto) em ações do usuário, pois os toggles cuidam da exclusão mútua. > **Divergência:** o `README.md` raiz mostra o exemplo `const { sidebarWidth, isSidebarOpen, toggleSidebar } = useLayout();` — mas `isSidebarOpen` **não existe** na tabela de propriedades documentada em `docs/layout.md` nem no exemplo de `docs/getting-started.md` (ambos usam `sidebarExpanded`). Trate `docs/layout.md` como fonte autoritativa para os nomes exatos de propriedades; o snippet do README parece impreciso/desatualizado nesse ponto específico. --- --- ## 5. Gerenciamento de Estado Estratégia em camadas: | Camada | Ferramenta | Responsabilidade | |---|---|---| | Server state | TanStack React Query v5 | Fetch, cache, refetch em background, loading/error | | Client UI state | Zustand v5 | Filtros, toggles, controles de formulário, aba selecionada | | Auth state | `AuthContext` | Sessão do usuário, login, logout | | Layout state | `LayoutContext` / `useLayout()` | Largura/estado da sidebar, assistente | | Local component state | `useState` | Estado efêmero (diálogos, edição inline) | ### Adicionando uma nova feature 1. `features//data/mock.ts` com tipos e funções `fetch*` mock 2. `features//hooks/use.ts` envolvendo o fetch em `useQuery` 3. `features//store/Store.ts` para estado de UI client-side 4. Re-exportar em `features//index.ts` 5. Consumir via hook no componente ### React Query — hook language-aware ```ts // features/home/hooks/useTeamMembers.ts import { useQuery } from '@tanstack/react-query'; import { useLanguage } from 'xertica-ui/hooks'; import { fetchTeamMembers, type TeamMember } from '../data/mock'; export function useTeamMembers() { const { language } = useLanguage(); return useQuery({ queryKey: ['home', 'team-members', language], // language como 3º elemento queryFn: fetchTeamMembers, staleTime: 2 * 60 * 1000, }); } ``` > Não exportar uma constante `*_KEY` a nível de módulo — a key inclui `language`, disponível só em tempo de chamada do hook. **Referência de `staleTime`:** `useFeatureCards` → 10 min; `useAssistantConfig` → 30 min. (Hooks internos do showcase, não gerados no template: `useDashboardStats` → 5 min, `useTeamMembers` → 2 min.) ### Trocando mock por API real Apenas a função `fetch*` em `data/mock.ts` muda — hook, componente e contrato de tipo permanecem intactos: ```ts // antes (mock) export async function fetchTeamMembers(): Promise { await new Promise(resolve => setTimeout(resolve, 250)); return MOCK_TEAM_MEMBERS; } // depois (API real) export async function fetchTeamMembers(): Promise { const res = await fetch('/api/team/members'); if (!res.ok) throw new Error('Failed to fetch team members'); return res.json(); } ``` ### Zustand ```ts // features/home/store/dashboardStore.ts import { create } from 'zustand'; interface DashboardStore { activeTab: string; setActiveTab: (tab: string) => void; progress: number; setProgress: (value: number) => void; } export const useDashboardStore = create(set => ({ activeTab: 'overview', setActiveTab: tab => set({ activeTab: tab }), progress: 45, setProgress: value => set({ progress: value }), })); ``` Consumir sempre com seletor: `useDashboardStore(s => s.progress)`, nunca `const store = useDashboardStore()` inteiro (evita re-renders desnecessários). | Usar `useState` | Usar Zustand | |---|---| | Diálogo aberto/fechado | Aba de filtro ativa | | Valor de input de rename | Slider compartilhado entre seções | | Hover | Switch habilitado | | Toggle de componente único | Estado que precisa sobreviver ao unmount | ### AuthContext `AuthProvider` deve ficar **dentro** de `` (usa `useNavigate`). `isLoading` deve sempre ser checado nos route guards antes de ler `user`, para evitar *flash redirects* durante a hidratação do `localStorage`. ### Árvore de decisão ``` Precisa de dado de servidor/função assíncrona? └─ SIM → React Query (useQuery em features/*/hooks/) └─ Mock? → usar fetch de features/*/data/mock.ts └─ API real? → trocar só o corpo do fetch Estado é browser-only? └─ Compartilhado entre componentes → Zustand (features/*/store/) └─ Usado por um único componente → useState Autenticação/usuário atual? → useAuth() de AuthContext Largura da sidebar/painel do assistente? → useLayout() de xertica-ui/hooks ``` ### Regras para IA - Nunca hardcodar mock arrays em componentes — sempre em `features/*/data/mock.ts`. - Nunca chamar `fetch` direto num componente — sempre via hook de React Query. - Nunca usar `useState([]) + useEffect(fetch)` — usar `useQuery`. - `QueryClientProvider` fica **fora** de `XerticaProvider`. - `AuthProvider` fica **dentro** de ``. - Sempre definir `staleTime` adequado — nunca deixar no default `0`. - Zustand sempre com seletor. --- --- ## 6. Internacionalização (i18n) Baseado em **`i18next`** + **`react-i18next`**. O `LanguageSelector` está diretamente ligado ao `i18next`: trocar idioma atualiza todo `useTranslation()` e invalida o cache do React Query (para que strings vindas de "API"/mock também atualizem). ### Estrutura de locales — uma pasta por idioma, dividida por categoria ``` src/locales/ ├── .languages.json ← seleção gerenciada pela CLI ({ version: 1, codes: [...] }) ├── pt-BR/ ← default e fallback │ ├── common.json, nav.json, errors.json, languageSelector.json, themeToggle.json │ ├── pages/ → home.json, templates.json, login.json, forgotPassword.json, │ │ resetPassword.json, verifyEmail.json, loginTemplate.json, │ │ formTemplate.json, dashboardTemplate.json, crudTemplate.json │ └── components/ → assistant.json, sidebar.json, media.json, projectCard.json, │ profileCard.json, notificationCard.json, activityCard.json, │ stats.json, team.json ├── en/ ← mesma estrutura └── es/ ← mesma estrutura ``` Cada JSON contém apenas as chaves da sua categoria, sem chave de wrapper no topo — todos os arquivos sob `locales//` são descobertos automaticamente por `import.meta.glob` em `i18n.ts` (adicionar um novo JSON não exige tocar em `i18n.ts`). > **Divergência:** o `README.md` raiz mostra uma árvore de locales **plana** (`locales/pt-BR.json`, `en.json`, `es.json`), enquanto `docs/i18n.md` (e `docs/architecture.md`, `docs/installation.md`) documentam a estrutura atual em **pastas por idioma com subcategorias**, explicitando que arquivos `.json` planos são um formato **legado (pré-2.2.0)**, removidos automaticamente na sincronização. Como o pacote está na v3.0.1, `docs/i18n.md` é a fonte correta e atual; o exemplo do README está desatualizado. ### Bootstrap (`src/i18n.ts`) Usa `import.meta.glob(..., { eager: true, import: 'default' })` por idioma, mescla os chunks descartando o prefixo de pasta (`pages/`, `components/`) e mantém apenas o nome-base do arquivo como chave de topo. Há um **guard crítico** contra dupla inicialização do singleton do `i18next` (compartilhado/hoisted entre app e `xertica-ui` via `node_modules`): se `i18n.isInitialized`, usa `addResourceBundle(lang, 'translation', resources, true, false)` em vez de `i18n.init()`, que substituiria todo o resource store. Esse guard é gerado automaticamente pela CLI. ```ts const savedLanguage = localStorage.getItem('xertica_language') ?? 'pt-BR'; if (!i18n.isInitialized) { i18n.use(initReactI18next).init({ resources: { 'pt-BR': { translation: ptBR }, en: { translation: en }, es: { translation: es } }, lng: savedLanguage, fallbackLng: 'pt-BR', interpolation: { escapeValue: false }, }); } else { for (const [lang, resources] of Object.entries(defaultResourcesByLang)) { i18n.addResourceBundle(lang, 'translation', resources, true, false); } } ``` `main.tsx` deve importar `'./i18n'` **antes** de qualquer componente. ### Uso em componentes ```tsx import { useTranslation } from 'react-i18next'; function HomeContent() { const { t } = useTranslation(); return

{t('home.welcome')}

; } ``` Interpolação: `t('team.showing', { count: 5, total: 127 })` a partir de `"Exibindo {{count}} de {{total}} usuários"`. ### Fluxo de troca de idioma `LanguageSelector` → `setLanguage(lang)` em `LanguageContext` → grava em `localStorage` (`xertica_language`) → `i18n.changeLanguage(lang)` → todos os `useTranslation()` re-renderizam → `queryClient.invalidateQueries()` é chamado (backstop defensivo). ### Namespaces de tradução Um único namespace `translation`; cada chave de topo mapeia para um arquivo JSON: arquivos raiz (`common`, `nav`, `errors`, `languageSelector`, `themeToggle`), arquivos de página (`pages/.json` → `home`, `templates`, `login`, `forgotPassword`, `resetPassword`, `verifyEmail`, `loginTemplate`, `formTemplate`, `dashboardTemplate`, `crudTemplate`) e arquivos de componente (`components/.json` → `assistant`, `sidebar`, `media`, `projectCard`, `profileCard`, `notificationCard`, `activityCard`, `stats`, `team`). ### Mock data + factory functions (regra crítica) Funções de fetch usam `i18n.t()` (a **instância**, não o hook) porque rodam fora do ciclo React (dentro de `queryFn`): ```ts // ✅ correto — função, avaliada a cada chamada export function getMockRichSuggestions(): Suggestion[] { return [{ id: 'rich-1', text: i18n.t('assistant.richSuggestions.viewPerformance') }]; } // ❌ errado — const congela no idioma do momento do module load export const MOCK_RICH_SUGGESTIONS = [{ id: 'rich-1', text: i18n.t('...') }]; ``` ### `queryKey` language-aware ```ts export function useFeatureCards() { const { language } = useLanguage(); return useQuery({ queryKey: ['home', 'feature-cards', language], queryFn: fetchFeatureCards, staleTime: 10 * 60 * 1000, }); } ``` Trocar de `pt-BR` → `en` gera uma nova `queryKey` → cache miss → refetch com `i18n.t()` já em inglês; voltar para `pt-BR` é cache hit instantâneo. ### Configuração de idiomas disponíveis (runtime) O conjunto de idiomas é **configurável em runtime** via prop `availableLanguages` em `` (a lib expõe `DEFAULT_LANGUAGES` com pt-BR/en/es): ```tsx // Monolíngue // Defaults + idioma customizado ``` Modo monolíngue: `LanguageSelector` renderiza `null` automaticamente (`isMonolingual === true`); force-exibir com ``. Registro imperativo alternativo: `registerLanguageResource('fr', fr)`. `LanguageDefinition`: ```ts interface LanguageDefinition { code: string; // BCP-47, usado em localStorage e i18n.changeLanguage() label: string; // label completo no dropdown shortLabel?: string; // ex: "PT" — default code.slice(0,2).toUpperCase() resources?: Record; // registrado automaticamente se presente } ``` `useLanguage()` retorna: `language`, `setLanguage`, `availableLanguages`, `isMonolingual`. Via CLI: `npx xertica-ui update` → **Languages** recalcula o diff, copia/remove pastas de locale, regenera `App.tsx`/`i18n.ts`, atualiza `.languages.json` (e migra arquivos `.json` planos legados, se encontrados). ### Regras para IA - Sempre importar `'./i18n'` em `main.tsx` antes de qualquer componente. - `t()` dentro de componentes/hooks; `i18n.t()` fora do ciclo React. - Sempre incluir `language` na `queryKey` de hooks com strings traduzidas. - Fallback traduzido: sempre factory function, nunca `const` congelada. - Nunca modificar `DEFAULT_LANGUAGES` diretamente — usar `availableLanguages`. - `Language` é tipado como `string` (não union estrita) para suportar locais adicionados em runtime. - `useLanguage` é exportado de `xertica-ui/hooks` e do root `xertica-ui`, **não** de `xertica-ui/brand` (que exporta só `LanguageSelector` e o tipo `Language`). --- --- ## 7. Sizing de Formulários Escala padronizada de 3 níveis — `"sm" | "md" | "lg"` — aplicada a todos os componentes de formulário. ### Inputs de texto (baseados em altura) | Size | Altura | Padding | Font | Componentes | |---|---|---|---|---| | `sm` | `h-8` (32px) | `px-2 py-1` | `text-sm` | Input, SelectTrigger, Search, InputOTPSlot | | **`md`** (default) | **`h-10` (40px)** | **`px-3 py-2`** | **`text-base`** | todos | | `lg` | `h-12` (48px) | `px-4 py-3` | `text-base` | Input, SelectTrigger, Search, InputOTPSlot | `Textarea` usa só padding/font (altura controlada por `rows`, não por `size`). ### Toggles (baseados em indicador) | Size | Checkbox | RadioGroupItem | Switch Track | Switch Thumb | |---|---|---|---|---| | `sm` | 14px | 16px | 28×14px | 12px | | **`md`** | **16px** | **20px** | **32×18px** | **16px** | | `lg` | 20px | 24px | 40×22px | 20px | `Label`: `sm` → `text-xs`, `md` → `text-sm` (default), `lg` → `text-base` — deve sempre casar com o size do input associado. ### Componentes com prop `size` `Input`, `SelectTrigger`, `Textarea`, `Search`, `InputOTPSlot`, `Checkbox`, `RadioGroupItem`, `Switch`, `Label` — todos `"sm" | "md" | "lg"`, default `"md"`. ### Caso especial: `Button` `Button` usa escala **própria**: `"default" | "sm" | "lg" | "icon"` (default `"default"` = h-9, `sm` = h-8, `lg` = h-10, `icon` = size-9). Nunca passar `"md"` para `Button`. `Slider` e `FileUpload` não têm prop `size` (track-based / drop-zone). ### Regras para IA - Usar o **mesmo `size`** em todos os elementos de uma mesma linha de formulário. - `md` é o default — nunca declarar `size="md"` explicitamente. - `sm` para UIs densas (filtros de tabela, busca em toolbar); `lg` para forms de destaque (login, primeiro contato). - `Label` deve casar o size do `Input` correspondente. --- --- ## 8. Branding, Temas e Identidade Visual ### Visão geral dos componentes de marca Todos exportados de `xertica-ui/brand` (`components/brand/index.ts` reexporta `xertica-provider`, `isotype`, `xertica-logo`, `xertica-xlogo`, `xertica-orbe`, `theme-toggle`, `language-selector`): | Componente | Propósito | |---|---| | `XerticaProvider` | Provider raiz de tema, idioma, cores de marca, layout, assistente, API keys, Maps, tooltips e toasts | | `ThemeToggle` | Botão de alternância claro/escuro | | `LanguageSelector` | Dropdown de idioma (pt-BR / en / es, extensível em runtime) | | `XerticaLogo` | Logotipo horizontal completo (SVG, usa `currentColor`) | | `XerticaXLogo` | Variante compacta "X" (usa `currentColor`) — obrigatória quando a Sidebar está colapsada (80px) | | `XerticaOrbe` | Marca animada (Lottie) do núcleo do assistente de IA | | `Isotype` / `IsotypeMini` / `IsotypeFrames` / `IsotypeTwist` / `IsotypeDiagonal` | Família de "isotipos" da marca (grades/formas geométricas com cores fixas) | ### `XerticaProvider` — props reais do código-fonte **Atenção a uma divergência de documentação**: `docs/components/branding.md` e `docs/components/xertica-provider.md` descrevem props diferentes entre si e diferentes do código-fonte atual (`components/brand/xertica-provider/XerticaProvider.tsx`). A assinatura real, verificada em `XerticaProviderProps`, é: ```tsx interface XerticaProviderProps { children: React.ReactNode; apiKey?: string; // Gemini/AI key, repassada para ApiKeyProvider googleMapsApiKey?: string; defaultBrandTheme?: string; // legado — usado como fallback de defaultColorTheme defaultColorTheme?: string; // id de um ColorTheme (ex.: 'xertica-original', 'blue', 'rose'...) primaryColor?: string; // cor hex — gera um tema 'custom' on-the-fly useCustomTokens?: boolean; // default false — pula a injeção de tokens em runtime disableDarkMode?: boolean; // default false availableLanguages?: LanguageDefinition[]; defaultLanguage?: Language; } ``` Internamente (`XerticaProvider.tsx`), `defaultColorTheme || defaultBrandTheme` é passado como `defaultTheme` ao `BrandColorsProvider`. A árvore de providers montada é: `ThemeProvider` → `BrandColorsProvider` → `LanguageProvider` → `ApiKeyProvider` → `GoogleMapsLoaderProvider` → `AssistenteProvider` → `LayoutProvider` → `TooltipProvider` → `{children}` + `Toaster`. ### 1. Lista completa e exata de `defaultColorTheme` Definida em `contexts/theme-data.ts` (array `colorThemes: ColorTheme[]`), consumida por `BrandColorsProvider` (`contexts/BrandColorsContext.tsx`). São **exatamente 10 temas registrados**, nesta ordem: | `id` | `name` | Observação | |---|---|---| | `xertica-original` | Xertica Classic | **Default** (`BrandColorsProvider`: `defaultTheme || 'xertica-original'`) — identidade clássica, gradiente `#FDB0F2→#72CDFD` | | `xertica` | Xertica | Nova identidade (papel quente `#FFFEF8`, "Negro Xertica" `#1E1E1E`, botões pill com stroke, amarelo `#FAF338` restrito ao botão primário/Switch); **sem gradientes** — `gradientStart`/`gradientEnd` apontam para o mesmo valor sólido | | `zinc` | Zinc | Escala de cinza | | `slate` | Slate | Azul acinzentado | | `blue` | Blue | Azul corporativo | | `violet` | Violet | Roxo vibrante | | `rose` | Rose | Rosa/vermelho | | `emerald` | Emerald | Verde | | `amber` | Amber | Âmbar | | `orange` | Orange | Laranja | Adicionalmente existe um pseudo-tema **`'custom'`**, não presente no array `colorThemes` — é atribuído automaticamente a `currentTheme` quando a prop `primaryColor` é passada ao `XerticaProvider`/`BrandColorsProvider` (`contexts/BrandColorsContext.tsx:31-35`): a paleta é derivada de `colorThemes[0].colors` (isto é, `xertica-original`) com `primary`, `primaryDarkMode`, `sidebarLight`, `sidebarDark` e `chart1` sobrescritos pela cor informada. **Confirmação direta à pergunta do CHANGELOG**: sim, `'xertica'` é um `id` de tema **distinto** de `'xertica-original'`. O tema clássico manteve o `id` antigo por compatibilidade (`CHANGELOG.md:173`: "o `id` não foi alterado, então projetos scaffolded e chamadas `setTheme('xertica-original')` continuam funcionando sem mudanças"). ### 2. Regra exata da substituição pelo Isotype `currentTheme` é exposto pelo hook `useBrandColors()` (`contexts/BrandColorsContext.tsx`), que lê o estado interno do `BrandColorsProvider` (o mesmo `id` de tema listado acima, ou `'custom'`). A regra confirmada em código — **`currentTheme === 'xertica'`** (comparação estrita com o novo tema, não com `'xertica-original'`) — aparece em 5 pontos: ```tsx // components/brand/xertica-orbe/XerticaOrbe.tsx:30-31 // "Exclusively on the `xertica` theme, this renders the `IsotypeFrames` brand // mark instead of the animated orb — never make this swap theme-reactive for any other theme." const { currentTheme } = useBrandColors(); const isXerticaTheme = currentTheme === 'xertica'; // ...mais adiante (linha 1873): if (isXerticaTheme) { return ; } ``` ```tsx // components/pages/login-page/LoginPage.tsx:126-127 return currentTheme === 'xertica' ? ( {content} ) : ( /* AuthPageShell com imageSrc/gradiente original */ ); ``` O mesmo padrão (`currentTheme === 'xertica' ? : ...`) se repete em `components/pages/forgot-password-page/ForgotPasswordPage.tsx:95-96`, `components/pages/reset-password-page/ResetPasswordPage.tsx:153-154` e `components/pages/verify-email-page/VerifyEmailPage.tsx:105-106`. Todas as 4 telas de auth usam `IsotypeTwist variant="magenta-blue"` via `AuthPageShell` (`components/blocks/auth/AuthPageShell.tsx:4,43`) quando `leftPanel="isotype"`. Isso corrige explicitamente um bug histórico documentado no CHANGELOG (`CHANGELOG.md:47`): antes, o isotipo aparecia em qualquer tema; a correção amarrou a troca a `currentTheme === 'xertica'` lido via `useBrandColors()`. ### 3. Variantes da família Isotype Todos em `components/brand/isotype/`, cores fixas (`ISOTYPE_COLORS` em `patterns.ts`) — **nunca reagem a tokens de tema**, pois são marca, não UI: ```ts // patterns.ts purple: '#5A4A96', blue: '#1899AF', magenta: '#C45BAA', yellow: '#FAF338', green: '#2E8B5A', red: '#DE5B48', brown: '#2A2415' ``` | Componente | Forma | Prop de variante | Valores | Default | |---|---|---|---|---| | `Isotype` | Grade 4×4 (16 células) | `pattern: IsotypePatternId` | `'core'` (único registrado) | `'core'` | | `IsotypeMini` | Grade 3×3 (9 células) | `pattern: IsotypeMiniPatternId` | `'core'` (único registrado) | `'core'` | | `IsotypeFrames` | 2 quadrados vazados sobrepostos, `mix-blend-mode: multiply` | `variant: IsotypeFrameVariantId` | `'blue-magenta'` → `['blue','magenta']`; `'blue-yellow'` → `['blue','yellow']` | `'blue-magenta'` | | `IsotypeTwist` | 2 formas-fita angulares sobrepostas, `mix-blend-mode: multiply` | `variant: IsotypeTwistVariantId` | `'magenta-blue'` → `['magenta','blue']`; `'blue-red'` → `['blue','red']` | `'magenta-blue'` | | `IsotypeDiagonal` | Composição única fixa (corte diagonal), sem prop de variante | — | — | — | `Isotype`/`IsotypeMini` aceitam ainda `variantSeed?: number` — um PRNG determinístico (`mulberry32`) que zera exatamente **uma** célula extra do padrão base para variação decorativa; marcas canônicas (Hero, nav) devem omitir essa prop e usar o padrão puro. Nos pares Frames/Twist, a cor "de trás" (`back`) é pintada primeiro e a "da frente" (`front`) domina o blend de interseção — a cor resultante da mistura nunca é hardcoded, é efeito do `mix-blend-mode`. ### 4. Sistema de tokens CSS e dark mode Arquivos-fonte: `styles/xertica/tokens.css` (valores), `styles/xertica/theme-map.css` (`@theme inline` do Tailwind v4, mapeia `--color-*` para os tokens), `styles/xertica/base.css` (`@import 'tailwindcss'`, `@custom-variant dark`, utilities). **Mecanismo de dark mode**: classe `.dark` em ``, definida por `@custom-variant dark (&:is(.dark *));` (`styles/xertica/base.css:8`). Quem manipula essa classe é `ThemeProvider`/`useTheme()` (`contexts/ThemeContext.tsx`): - Estado inicial: `disableDarkMode` → força `'light'`; senão `defaultTheme` prop; senão `localStorage['xertica-theme']`; senão `window.matchMedia('(prefers-color-scheme: dark)')`; senão `'light'`. - A cada mudança, `root.classList.remove('light','dark')` e adiciona a classe correspondente, persistindo em `localStorage` (chave `xertica-theme`). - Um listener de `prefers-color-scheme` só é ativado se não houver preferência salva. `tokens.css` também define um seletor alternativo `:root[data-mode='dark'], .dark { ... }` (linha 157), mas nenhum código no repositório escreve `data-mode` — na prática só a classe `.dark` é usada. **Discrepância de precisão encontrada**: `docs/components/theme-toggle.md` afirma que `ThemeToggle` é "self-contained... does not require any context provider" e manipula `document.documentElement.classList` diretamente. O código-fonte real (`components/brand/theme-toggle/ThemeToggle.tsx`) **contradiz isso**: o componente chama `useTheme()` de `contexts/ThemeContext.tsx`, cujo hook lança `throw new Error('useTheme must be used within a ThemeProvider')` se não houver `ThemeProvider` (que só existe dentro de `XerticaProvider` ou usado isoladamente) acima na árvore. Ou seja, **`ThemeToggle` na prática exige um `ThemeProvider`** — a doc está desatualizada nesse ponto. **Principais tokens** (`styles/xertica/tokens.css`, tema `default`, formato `rgba(...)`): ```css :root, :root[data-theme='default'] { --xertica-primary: rgba(44,39,91,1); --background: rgba(255,255,255,1); --foreground: rgba(9,9,11,1); --card: rgba(255,255,255,1); --popover: rgba(255,255,255,1); --primary: var(--xertica-primary); --primary-foreground: rgba(250,250,250,1); --secondary: rgba(244,244,245,1); --muted: rgba(244,244,245,1); --accent: rgba(244,244,245,1); --destructive: rgba(220,38,38,1); --success/--info/--warning: ... --border/--input/--ring: ... --sidebar: rgba(44,39,91,1); --sidebar-foreground: rgba(250,250,250,1); --sidebar-primary/-accent/-border/-ring: ... --chart-1 .. --chart-8: /* paleta vibrante de 8 cores */ --gradient-diagonal: linear-gradient(135deg,#fdb0f2 0%,#72cdfd 100%); --radius: 6px; --radius-button: 12px; --radius-card: 12px; --button-stroke-width: 0px; --button-stroke-color: transparent; --button-secondary-bg / --button-primary-bg / *-foreground: ... } :root[data-mode='dark'], .dark { /* mesmas chaves, valores escuros */ } ``` (Nota: `docs/components/branding.md` mostra um exemplo simplificado em HSL/rem — o arquivo real gerado usa `rgba()` e `--radius: 6px`, não `0.5rem`; trate o doc como ilustrativo, não literal.) `@theme inline` em `theme-map.css` remapeia cada token para o namespace do Tailwind v4 (`--color-primary: var(--primary)`, `--radius-lg: calc(var(--radius) + 6px)` etc.), habilitando utilitários como `bg-primary`, `text-sidebar-foreground`, `rounded-lg`. **Aplicação em runtime por tema selecionado**: `BrandColorsProvider` (`contexts/BrandColorsContext.tsx`) não troca arquivos CSS — ele calcula, a cada mudança de `currentTheme`/modo claro-escuro, um conjunto de declarações e as aplica de duas formas: (1) tokens "primários" (`--primary`, `--ring`, `--chart-*`, `--sidebar-*`, `--radius`, `--gradient-diagonal` etc.) via `root.style.setProperty(...)` (inline style em ``, máxima especificidade); (2) tokens de "superfície"/botão que variam por modo (`--background`, `--card`, `--muted`, `--border`, `--button-*`) via uma tag `