xertica-ui 2.4.0 → 2.4.1

package/docs/components/stats-card.md

@@ -29,7 +29,9 @@ Built on top of `<Card>`. Use it for dashboard stat widgets where a consistent m
 | `description` | `string`                            | No       | Additional supplementary text below the value                                                             |
 | `trend`       | `{ value: number; label?: string }` | No       | Trend object. `value` is a number (positive = up, negative = down). `label` overrides `description` text. |
 | `icon`        | `ReactNode`                         | No       | Icon from `lucide-react`                                                                                  |
-| `className`   | `string`                            | No       | Additional CSS classes                                                                                    |
+| `iconColor`   | `string`                            | No       | Tailwind class for the icon text/foreground color (defaults to `text-muted-foreground`)                   |
+| `iconBg`      | `string`                            | No       | Tailwind class for the icon background color (defaults to `bg-muted`)                                     |
+| `className`   | `string`                            | No       | Additional CSS classes |
 
 ### trend
 
@@ -59,6 +61,22 @@ import { DollarSign } from 'lucide-react';
 />;
 ```
 
+### Custom Icon Colors
+
+```tsx
+import { StatsCard } from 'xertica-ui/ui';
+import { Users } from 'lucide-react';
+
+<StatsCard
+  title="Active Users"
+  value="2,350"
+  trend={{ value: 8.2, label: 'new this week' }}
+  icon={<Users className="size-5" />}
+  iconBg="bg-primary/10"
+  iconColor="text-primary"
+/>;
+```
+
 ### Negative Trend
 
 ```tsx
@@ -108,7 +126,7 @@ import { DollarSign } from 'lucide-react';
 - `trend.value` is a **numeric percentage** (e.g., `20.1` for +20.1%) — the component displays `Math.abs(value)%` automatically.
 - Do NOT pre-format the trend value as a string — pass the raw number.
 - `value` IS pre-formatted as a display string: `"$45,231"`, `"3.6%"`, `"2,350"`.
-- Icons render inside a muted rounded background — use `size-5` for the icon.
+- Icons render inside a rounded background. By default, background is `bg-muted` and color is `text-muted-foreground`, but they can be customized using `iconBg` and `iconColor` props. Use `size-5` for the icon.
 - Always use in a 4-column responsive grid for dashboard overviews.
 - `trend.label` takes precedence over `description` for below-value text.
 

package/docs/doc-audit.md

@@ -1,244 +1,244 @@
-# Xertica UI — Auditoria de Documentação
-
-> **Status (2026-05-21):** ⚠️ **SUPERSEDED** — este relatório data de 2026-05-19 e a maioria dos itens TODO foi resolvida nas auditorias posteriores. Itens marcados ❌ ou listados como "Sem Doc" nas tabelas abaixo **podem já estar concluídos**.
->
-> Antes de seguir qualquer recomendação aqui, verifique se a documentação correspondente já existe em `docs/components/`. A inventário real abaixo foi atualizado para refletir o estado em 2026-05-21:
->
-> | Categoria                                       | Total                 | Com Doc                                    | Sem Doc |
-> | ----------------------------------------------- | --------------------- | ------------------------------------------ | ------- |
-> | Componentes UI (`components/ui/`)               | 65                    | 65                                         | 0       |
-> | Componentes Assistant (`components/assistant/`) | 5                     | 5                                          | 0       |
-> | Componentes Brand (`components/brand/`)         | 7                     | 7                                          | 0       |
-> | Componentes Layout (`components/layout/`)       | 2                     | 2                                          | 0       |
-> | Componentes Media (`components/media/`)         | 3                     | 3                                          | 0       |
-> | Componentes Blocks (`components/blocks/`)       | 6 cards + 6 skeletons | card-patterns.md (cobre cards + skeletons) | 0       |
-> | Páginas (`components/pages/`)                   | 8                     | pages.md (cobertura agregada)              | 0       |
-> | Hooks/Contextos                                 | 9 hooks               | hooks.md (cobertura agregada)              | 0       |
-> | Utilitários (`components/figma/`)               | 1                     | image-with-fallback.md                     | 0       |
->
-> **Lacunas ainda em aberto (verificar antes de fechar):**
->
-> - Storybook `.mdx` para os 6 card skeletons (existe `.md`, mas não `.mdx`)
-> - `lib/query-client.ts` — singleton não documentado externamente (intencionalmente interno)
->
-> **Última auditoria completa:** ver mensagem do agente em 2026-05-21 que cobriu i18n flexibilidade, skeletons, queryKey language-aware, e correções em `hooks.md`, `branding.md`, `card-patterns.md`, `language-selector.md`, `architecture.md`, `getting-started.md`, `state-management.md`, `components.json`.
-
----
-
-## Resumo Executivo (histórico, possivelmente desatualizado)
-
-| Categoria                                       | Total no Código | Com Doc               | Sem Doc |
-| ----------------------------------------------- | --------------- | --------------------- | ------- |
-| Componentes UI (`components/ui/`)               | 65              | 65                    | 0       |
-| Componentes Assistant (`components/assistant/`) | 5               | 2                     | **3**   |
-| Componentes Brand (`components/brand/`)         | 7               | 6                     | **1**   |
-| Componentes Layout (`components/layout/`)       | 2               | 2                     | 0       |
-| Componentes Media (`components/media/`)         | 3               | 3                     | 0       |
-| Componentes Blocks (`components/blocks/`)       | 6 cards         | 1 doc (card-patterns) | 0       |
-| Páginas (`components/pages/`)                   | 8               | 0                     | **8**   |
-| Hooks/Contextos (`components/hooks/`)           | 6 hooks         | 1 (use-mobile)        | **5**   |
-| Utilitários (`components/figma/`)               | 1               | 0                     | **1**   |
-
----
-
-## 1. Componentes SEM Documentação
-
-### 1.1 Componentes Assistant — Sem doc própria
-
-O [`docs/llms.md`](./llms.md) menciona estes três como _"in Storybook"_, mas não há arquivo `.md` em `docs/components/`:
-
-| Componente          | Arquivo                                    | Importação             | Status     |
-| ------------------- | ------------------------------------------ | ---------------------- | ---------- |
-| `CodeBlock`         | `components/assistant/code-block/`         | `xertica-ui/assistant` | ❌ Sem doc |
-| `ModernChatInput`   | `components/assistant/modern-chat-input/`  | `xertica-ui/assistant` | ❌ Sem doc |
-| `FormattedDocument` | `components/assistant/formatted-document/` | `xertica-ui/assistant` | ❌ Sem doc |
-
-**Impacto:** Agentes de IA não conseguem usar esses componentes corretamente sem prop tables e exemplos.
-
----
-
-### 1.2 Componente Brand — Sem doc
-
-| Componente | Arquivo                      | Status                                      |
-| ---------- | ---------------------------- | ------------------------------------------- |
-| `Branding` | `components/brand/branding/` | ❌ Sem doc (apenas `.mdx` e `.stories.tsx`) |
-
----
-
-### 1.3 Hook `useMapLayers` — Sem doc
-
-O hook [`useMapLayers`](../components/ui/map-layers/map-layers.tsx) é exportado publicamente via `xertica-ui/ui` mas não tem documentação em `docs/components/`. Está relacionado ao sistema de mapas mas não aparece no catálogo do [`docs/llms.md`](./llms.md).
-
----
-
-### 1.4 Utilitário `ImageWithFallback` — Sem doc
-
-| Componente          | Arquivo                                  | Status     |
-| ------------------- | ---------------------------------------- | ---------- |
-| `ImageWithFallback` | `components/figma/ImageWithFallback.tsx` | ❌ Sem doc |
-
-Exportado publicamente via `xertica-ui` mas sem documentação.
-
----
-
-### 1.5 Páginas — Completamente sem documentação
-
-Nenhuma das 8 páginas-template tem documentação em `docs/`:
-
-| Página               | Arquivo                                  |
-| -------------------- | ---------------------------------------- |
-| `LoginPage`          | `components/pages/login-page/`           |
-| `ForgotPasswordPage` | `components/pages/forgot-password-page/` |
-| `ResetPasswordPage`  | `components/pages/reset-password-page/`  |
-| `VerifyEmailPage`    | `components/pages/verify-email-page/`    |
-| `HomePage`           | `components/pages/home-page/`            |
-| `HomeContent`        | `components/pages/home-content/`         |
-| `TemplatePage`       | `components/pages/template-page/`        |
-| `TemplateContent`    | `components/pages/template-content/`     |
-
-**Impacto:** Desenvolvedores e agentes de IA não sabem que essas páginas existem, quais props aceitam, ou como customizá-las. O [`docs/llms.md`](./llms.md) menciona "8 Page Templates" nas estatísticas mas não lista nenhuma delas no catálogo.
-
----
-
-### 1.6 Hooks/Contextos — Sem documentação
-
-O subpath `xertica-ui/hooks` exporta 6 hooks mas apenas `useMobile` tem doc:
-
-| Hook                        | Contexto             | Status                                                                          |
-| --------------------------- | -------------------- | ------------------------------------------------------------------------------- |
-| `useLayout`                 | `LayoutContext`      | ✅ Documentado em [`docs/layout.md`](./layout.md)                               |
-| `useMobile` / `useIsMobile` | `use-mobile`         | ✅ Documentado em [`docs/components/use-mobile.md`](./components/use-mobile.md) |
-| `useTheme`                  | `ThemeContext`       | ❌ Sem doc                                                                      |
-| `useLanguage`               | `LanguageContext`    | ❌ Sem doc                                                                      |
-| `useBrandColors`            | `BrandColorsContext` | ❌ Sem doc                                                                      |
-| `useAssistente`             | `AssistenteContext`  | ❌ Sem doc                                                                      |
-| `useApiKey`                 | `ApiKeyContext`      | ❌ Sem doc                                                                      |
-
-**Impacto:** Agentes de IA não sabem como acessar o tema atual, idioma, cores da marca ou estado do assistente programaticamente.
-
----
-
-## 2. Problemas de Qualidade nos Docs Existentes
-
-### 2.1 `docs/architecture.md` — Título incorreto
-
-O arquivo [`docs/architecture.md`](./architecture.md) tem como título `# Xertica UI — Documentation Audit Report` (linha 1), mas deveria ser `# Xertica UI — Architecture`. Isso confunde agentes de IA que buscam documentação de arquitetura.
-
----
-
-### 2.2 `docs/components/assistant-chart.md` — Doc muito rasa
-
-O doc do [`AssistantChart`](./components/assistant-chart.md) tem apenas 47 linhas e contém uma regra problemática:
-
-> _"Data Format: Ensure your data objects contain keys that match the `dataKey` set in the internal implementation (currently `month`, `desktop`, and `mobile`)."_
-
-Isso sugere que o componente só aceita dados com essas chaves específicas, o que é enganoso. Faltam:
-
-- Explicação de como usar `dataKey` customizado
-- Exemplos com dados reais de negócio
-- Seção "When to Use / When NOT to Use"
-
----
-
-### 2.3 `docs/llms.md` — Estatísticas desatualizadas e catálogo incompleto
-
-- **Linha 6:** `Total Components: 97` — o número real é maior (inclui páginas, hooks adicionais, `useMapLayers`, etc.)
-- **Seção AI Features:** `CodeBlock`, `ModernChatInput`, `FormattedDocument` listados como _"in Storybook"_ sem link de doc — isso instrui agentes a não usá-los quando na verdade são componentes públicos
-- **Seção Pages:** não existe no catálogo — as 8 páginas-template são invisíveis para agentes de IA
-- **Seção Hooks:** `useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey` não estão listados
-
----
-
-### 2.4 `docs/components/floating-media-wrapper.md` — Doc incompleta
-
-O arquivo tem apenas 64 linhas e está truncado — a seção "Related Components" (linha 60) não tem conteúdo.
-
----
-
-### 2.5 `docs/components/xertica-provider.md` — Seção "AI Rules" incompleta
-
-O arquivo tem 65 linhas e a seção `## AI Rules` (linha 60) está vazia/truncada.
-
----
-
-## 3. Padrões (Patterns) Faltando
-
-Os 5 padrões existentes cobrem casos básicos, mas faltam padrões para fluxos muito comuns:
-
-| Padrão Faltando              | Descrição                                                                        |
-| ---------------------------- | -------------------------------------------------------------------------------- |
-| **Wizard / Multi-step Form** | Formulário com `Stepper` + validação por etapa + `useStepper`                    |
-| **Detail Page**              | Página de detalhe de registro com `PageHeader` + back button + seções com `Card` |
-| **Settings Page**            | Página de configurações com `Tabs` + seções de formulário + `Switch`             |
-| **Empty + Loading States**   | Padrão completo de `Skeleton` → `Empty` → dados com `Table`                      |
-| **File Upload Form**         | Formulário com `FileUpload` integrado ao `react-hook-form`                       |
-
----
-
-## 4. Docs Gerais — Pontos de Melhoria
-
-### 4.1 `docs/getting-started.md` — Falta seção de troubleshooting
-
-Não há seção de problemas comuns (ex: componentes sem estilo = CSS não importado, erros de TypeScript com subpath imports, etc.).
-
-### 4.2 `docs/installation.md` — Falta menção ao `moduleResolution`
-
-O arquivo [`docs/architecture.md`](./architecture.md) menciona que TypeScript precisa de `"moduleResolution": "bundler"` para subpath exports, mas [`docs/installation.md`](./installation.md) não menciona isso — é um erro de configuração muito comum.
-
-### 4.3 `docs/ai-usage.md` — Falta regra sobre páginas-template
-
-Não há instrução para agentes de IA sobre quando usar as páginas-template (`LoginPage`, `TemplatePage`, etc.) vs. compor do zero.
-
----
-
-## 5. Priorização das Lacunas
-
-### 🔴 Alta Prioridade (impacto direto em agentes de IA e desenvolvedores)
-
-1. **Criar `docs/components/code-block.md`** — componente usado internamente e externamente
-2. **Criar `docs/components/modern-chat-input.md`** — componente de input do assistente
-3. **Criar `docs/components/formatted-document.md`** — componente de documento do assistente
-4. **Criar `docs/components/pages.md`** (ou docs individuais) — 8 páginas-template completamente invisíveis
-5. **Criar `docs/components/hooks.md`** — documentar `useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey`
-6. **Atualizar `docs/llms.md`** — corrigir estatísticas, adicionar páginas e hooks ao catálogo, adicionar links para docs dos componentes assistant
-
-### 🟡 Média Prioridade (melhoria de qualidade)
-
-7. **Corrigir título de `docs/architecture.md`**
-8. **Expandir `docs/components/assistant-chart.md`** — remover restrição enganosa de dataKey
-9. **Completar `docs/components/floating-media-wrapper.md`** — seção "Related Components"
-10. **Completar `docs/components/xertica-provider.md`** — seção "AI Rules"
-11. **Criar `docs/components/map-layers.md`** — documentar `useMapLayers`
-12. **Adicionar `"moduleResolution": "bundler"` em `docs/installation.md`**
-
-### 🟢 Baixa Prioridade (melhorias incrementais)
-
-13. **Criar padrão `docs/patterns/wizard.md`** — multi-step form com Stepper
-14. **Criar padrão `docs/patterns/detail-page.md`** — página de detalhe
-15. **Criar padrão `docs/patterns/settings.md`** — página de configurações
-16. **Adicionar seção de troubleshooting em `docs/getting-started.md`**
-17. **Criar `docs/components/image-with-fallback.md`** — utilitário de imagem
-18. **Criar `docs/components/branding.md`** — componente de branding
-
----
-
-## 6. Checklist de Ações
-
-- [ ] `docs/components/code-block.md` — criar
-- [ ] `docs/components/modern-chat-input.md` — criar
-- [ ] `docs/components/formatted-document.md` — criar
-- [ ] `docs/components/pages.md` — criar (ou 8 docs individuais)
-- [ ] `docs/components/hooks.md` — criar (useTheme, useLanguage, useBrandColors, useAssistente, useApiKey)
-- [ ] `docs/llms.md` — atualizar estatísticas + adicionar páginas + hooks + links dos assistant components
-- [ ] `docs/architecture.md` — corrigir título (linha 1)
-- [ ] `docs/components/assistant-chart.md` — expandir e corrigir regra de dataKey
-- [ ] `docs/components/floating-media-wrapper.md` — completar seção "Related Components"
-- [ ] `docs/components/xertica-provider.md` — completar seção "AI Rules"
-- [ ] `docs/components/map-layers.md` — criar
-- [ ] `docs/installation.md` — adicionar requisito de `moduleResolution`
-- [ ] `docs/patterns/wizard.md` — criar
-- [ ] `docs/patterns/detail-page.md` — criar
-- [ ] `docs/patterns/settings.md` — criar
-- [ ] `docs/getting-started.md` — adicionar seção de troubleshooting
-- [ ] `docs/components/image-with-fallback.md` — criar
-- [ ] `docs/components/branding.md` — criar
+# Xertica UI — Auditoria de Documentação
+
+> **Status (2026-05-21):** ⚠️ **SUPERSEDED** — este relatório data de 2026-05-19 e a maioria dos itens TODO foi resolvida nas auditorias posteriores. Itens marcados ❌ ou listados como "Sem Doc" nas tabelas abaixo **podem já estar concluídos**.
+>
+> Antes de seguir qualquer recomendação aqui, verifique se a documentação correspondente já existe em `docs/components/`. A inventário real abaixo foi atualizado para refletir o estado em 2026-05-21:
+>
+> | Categoria                                       | Total                 | Com Doc                                    | Sem Doc |
+> | ----------------------------------------------- | --------------------- | ------------------------------------------ | ------- |
+> | Componentes UI (`components/ui/`)               | 65                    | 65                                         | 0       |
+> | Componentes Assistant (`components/assistant/`) | 5                     | 5                                          | 0       |
+> | Componentes Brand (`components/brand/`)         | 7                     | 7                                          | 0       |
+> | Componentes Layout (`components/layout/`)       | 2                     | 2                                          | 0       |
+> | Componentes Media (`components/media/`)         | 3                     | 3                                          | 0       |
+> | Componentes Blocks (`components/blocks/`)       | 6 cards + 6 skeletons | card-patterns.md (cobre cards + skeletons) | 0       |
+> | Páginas (`components/pages/`)                   | 8                     | pages.md (cobertura agregada)              | 0       |
+> | Hooks/Contextos                                 | 9 hooks               | hooks.md (cobertura agregada)              | 0       |
+> | Utilitários (`components/figma/`)               | 1                     | image-with-fallback.md                     | 0       |
+>
+> **Lacunas ainda em aberto (verificar antes de fechar):**
+>
+> - Storybook `.mdx` para os 6 card skeletons (existe `.md`, mas não `.mdx`)
+> - `lib/query-client.ts` — singleton não documentado externamente (intencionalmente interno)
+>
+> **Última auditoria completa:** ver mensagem do agente em 2026-05-21 que cobriu i18n flexibilidade, skeletons, queryKey language-aware, e correções em `hooks.md`, `branding.md`, `card-patterns.md`, `language-selector.md`, `architecture.md`, `getting-started.md`, `state-management.md`, `components.json`.
+
+---
+
+## Resumo Executivo (histórico, possivelmente desatualizado)
+
+| Categoria                                       | Total no Código | Com Doc               | Sem Doc |
+| ----------------------------------------------- | --------------- | --------------------- | ------- |
+| Componentes UI (`components/ui/`)               | 65              | 65                    | 0       |
+| Componentes Assistant (`components/assistant/`) | 5               | 2                     | **3**   |
+| Componentes Brand (`components/brand/`)         | 7               | 6                     | **1**   |
+| Componentes Layout (`components/layout/`)       | 2               | 2                     | 0       |
+| Componentes Media (`components/media/`)         | 3               | 3                     | 0       |
+| Componentes Blocks (`components/blocks/`)       | 6 cards         | 1 doc (card-patterns) | 0       |
+| Páginas (`components/pages/`)                   | 8               | 0                     | **8**   |
+| Hooks/Contextos (`components/hooks/`)           | 6 hooks         | 1 (use-mobile)        | **5**   |
+| Utilitários (`components/figma/`)               | 1               | 0                     | **1**   |
+
+---
+
+## 1. Componentes SEM Documentação
+
+### 1.1 Componentes Assistant — Sem doc própria
+
+O [`docs/llms.md`](./llms.md) menciona estes três como _"in Storybook"_, mas não há arquivo `.md` em `docs/components/`:
+
+| Componente          | Arquivo                                    | Importação             | Status     |
+| ------------------- | ------------------------------------------ | ---------------------- | ---------- |
+| `CodeBlock`         | `components/assistant/code-block/`         | `xertica-ui/assistant` | ❌ Sem doc |
+| `ModernChatInput`   | `components/assistant/modern-chat-input/`  | `xertica-ui/assistant` | ❌ Sem doc |
+| `FormattedDocument` | `components/assistant/formatted-document/` | `xertica-ui/assistant` | ❌ Sem doc |
+
+**Impacto:** Agentes de IA não conseguem usar esses componentes corretamente sem prop tables e exemplos.
+
+---
+
+### 1.2 Componente Brand — Sem doc
+
+| Componente | Arquivo                      | Status                                      |
+| ---------- | ---------------------------- | ------------------------------------------- |
+| `Branding` | `components/brand/branding/` | ❌ Sem doc (apenas `.mdx` e `.stories.tsx`) |
+
+---
+
+### 1.3 Hook `useMapLayers` — Sem doc
+
+O hook [`useMapLayers`](../components/ui/map-layers/map-layers.tsx) é exportado publicamente via `xertica-ui/ui` mas não tem documentação em `docs/components/`. Está relacionado ao sistema de mapas mas não aparece no catálogo do [`docs/llms.md`](./llms.md).
+
+---
+
+### 1.4 Utilitário `ImageWithFallback` — Sem doc
+
+| Componente          | Arquivo                                  | Status     |
+| ------------------- | ---------------------------------------- | ---------- |
+| `ImageWithFallback` | `components/figma/ImageWithFallback.tsx` | ❌ Sem doc |
+
+Exportado publicamente via `xertica-ui` mas sem documentação.
+
+---
+
+### 1.5 Páginas — Completamente sem documentação
+
+Nenhuma das 8 páginas-template tem documentação em `docs/`:
+
+| Página               | Arquivo                                  |
+| -------------------- | ---------------------------------------- |
+| `LoginPage`          | `components/pages/login-page/`           |
+| `ForgotPasswordPage` | `components/pages/forgot-password-page/` |
+| `ResetPasswordPage`  | `components/pages/reset-password-page/`  |
+| `VerifyEmailPage`    | `components/pages/verify-email-page/`    |
+| `HomePage`           | `components/pages/home-page/`            |
+| `HomeContent`        | `components/pages/home-content/`         |
+| `TemplatePage`       | `components/pages/template-page/`        |
+| `TemplateContent`    | `components/pages/template-content/`     |
+
+**Impacto:** Desenvolvedores e agentes de IA não sabem que essas páginas existem, quais props aceitam, ou como customizá-las. O [`docs/llms.md`](./llms.md) menciona "8 Page Templates" nas estatísticas mas não lista nenhuma delas no catálogo.
+
+---
+
+### 1.6 Hooks/Contextos — Sem documentação
+
+O subpath `xertica-ui/hooks` exporta 6 hooks mas apenas `useMobile` tem doc:
+
+| Hook                        | Contexto             | Status                                                                          |
+| --------------------------- | -------------------- | ------------------------------------------------------------------------------- |
+| `useLayout`                 | `LayoutContext`      | ✅ Documentado em [`docs/layout.md`](./layout.md)                               |
+| `useMobile` / `useIsMobile` | `use-mobile`         | ✅ Documentado em [`docs/components/use-mobile.md`](./components/use-mobile.md) |
+| `useTheme`                  | `ThemeContext`       | ❌ Sem doc                                                                      |
+| `useLanguage`               | `LanguageContext`    | ❌ Sem doc                                                                      |
+| `useBrandColors`            | `BrandColorsContext` | ❌ Sem doc                                                                      |
+| `useAssistente`             | `AssistenteContext`  | ❌ Sem doc                                                                      |
+| `useApiKey`                 | `ApiKeyContext`      | ❌ Sem doc                                                                      |
+
+**Impacto:** Agentes de IA não sabem como acessar o tema atual, idioma, cores da marca ou estado do assistente programaticamente.
+
+---
+
+## 2. Problemas de Qualidade nos Docs Existentes
+
+### 2.1 `docs/architecture.md` — Título incorreto
+
+O arquivo [`docs/architecture.md`](./architecture.md) tem como título `# Xertica UI — Documentation Audit Report` (linha 1), mas deveria ser `# Xertica UI — Architecture`. Isso confunde agentes de IA que buscam documentação de arquitetura.
+
+---
+
+### 2.2 `docs/components/assistant-chart.md` — Doc muito rasa
+
+O doc do [`AssistantChart`](./components/assistant-chart.md) tem apenas 47 linhas e contém uma regra problemática:
+
+> _"Data Format: Ensure your data objects contain keys that match the `dataKey` set in the internal implementation (currently `month`, `desktop`, and `mobile`)."_
+
+Isso sugere que o componente só aceita dados com essas chaves específicas, o que é enganoso. Faltam:
+
+- Explicação de como usar `dataKey` customizado
+- Exemplos com dados reais de negócio
+- Seção "When to Use / When NOT to Use"
+
+---
+
+### 2.3 `docs/llms.md` — Estatísticas desatualizadas e catálogo incompleto
+
+- **Linha 6:** `Total Components: 97` — o número real é maior (inclui páginas, hooks adicionais, `useMapLayers`, etc.)
+- **Seção AI Features:** `CodeBlock`, `ModernChatInput`, `FormattedDocument` listados como _"in Storybook"_ sem link de doc — isso instrui agentes a não usá-los quando na verdade são componentes públicos
+- **Seção Pages:** não existe no catálogo — as 8 páginas-template são invisíveis para agentes de IA
+- **Seção Hooks:** `useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey` não estão listados
+
+---
+
+### 2.4 `docs/components/floating-media-wrapper.md` — Doc incompleta
+
+O arquivo tem apenas 64 linhas e está truncado — a seção "Related Components" (linha 60) não tem conteúdo.
+
+---
+
+### 2.5 `docs/components/xertica-provider.md` — Seção "AI Rules" incompleta
+
+O arquivo tem 65 linhas e a seção `## AI Rules` (linha 60) está vazia/truncada.
+
+---
+
+## 3. Padrões (Patterns) Faltando
+
+Os 5 padrões existentes cobrem casos básicos, mas faltam padrões para fluxos muito comuns:
+
+| Padrão Faltando              | Descrição                                                                        |
+| ---------------------------- | -------------------------------------------------------------------------------- |
+| **Wizard / Multi-step Form** | Formulário com `Stepper` + validação por etapa + `useStepper`                    |
+| **Detail Page**              | Página de detalhe de registro com `PageHeader` + back button + seções com `Card` |
+| **Settings Page**            | Página de configurações com `Tabs` + seções de formulário + `Switch`             |
+| **Empty + Loading States**   | Padrão completo de `Skeleton` → `Empty` → dados com `Table`                      |
+| **File Upload Form**         | Formulário com `FileUpload` integrado ao `react-hook-form`                       |
+
+---
+
+## 4. Docs Gerais — Pontos de Melhoria
+
+### 4.1 `docs/getting-started.md` — Falta seção de troubleshooting
+
+Não há seção de problemas comuns (ex: componentes sem estilo = CSS não importado, erros de TypeScript com subpath imports, etc.).
+
+### 4.2 `docs/installation.md` — Falta menção ao `moduleResolution`
+
+O arquivo [`docs/architecture.md`](./architecture.md) menciona que TypeScript precisa de `"moduleResolution": "bundler"` para subpath exports, mas [`docs/installation.md`](./installation.md) não menciona isso — é um erro de configuração muito comum.
+
+### 4.3 `docs/ai-usage.md` — Falta regra sobre páginas-template
+
+Não há instrução para agentes de IA sobre quando usar as páginas-template (`LoginPage`, `TemplatePage`, etc.) vs. compor do zero.
+
+---
+
+## 5. Priorização das Lacunas
+
+### 🔴 Alta Prioridade (impacto direto em agentes de IA e desenvolvedores)
+
+1. **Criar `docs/components/code-block.md`** — componente usado internamente e externamente
+2. **Criar `docs/components/modern-chat-input.md`** — componente de input do assistente
+3. **Criar `docs/components/formatted-document.md`** — componente de documento do assistente
+4. **Criar `docs/components/pages.md`** (ou docs individuais) — 8 páginas-template completamente invisíveis
+5. **Criar `docs/components/hooks.md`** — documentar `useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey`
+6. **Atualizar `docs/llms.md`** — corrigir estatísticas, adicionar páginas e hooks ao catálogo, adicionar links para docs dos componentes assistant
+
+### 🟡 Média Prioridade (melhoria de qualidade)
+
+7. **Corrigir título de `docs/architecture.md`**
+8. **Expandir `docs/components/assistant-chart.md`** — remover restrição enganosa de dataKey
+9. **Completar `docs/components/floating-media-wrapper.md`** — seção "Related Components"
+10. **Completar `docs/components/xertica-provider.md`** — seção "AI Rules"
+11. **Criar `docs/components/map-layers.md`** — documentar `useMapLayers`
+12. **Adicionar `"moduleResolution": "bundler"` em `docs/installation.md`**
+
+### 🟢 Baixa Prioridade (melhorias incrementais)
+
+13. **Criar padrão `docs/patterns/wizard.md`** — multi-step form com Stepper
+14. **Criar padrão `docs/patterns/detail-page.md`** — página de detalhe
+15. **Criar padrão `docs/patterns/settings.md`** — página de configurações
+16. **Adicionar seção de troubleshooting em `docs/getting-started.md`**
+17. **Criar `docs/components/image-with-fallback.md`** — utilitário de imagem
+18. **Criar `docs/components/branding.md`** — componente de branding
+
+---
+
+## 6. Checklist de Ações
+
+- [ ] `docs/components/code-block.md` — criar
+- [ ] `docs/components/modern-chat-input.md` — criar
+- [ ] `docs/components/formatted-document.md` — criar
+- [ ] `docs/components/pages.md` — criar (ou 8 docs individuais)
+- [ ] `docs/components/hooks.md` — criar (useTheme, useLanguage, useBrandColors, useAssistente, useApiKey)
+- [ ] `docs/llms.md` — atualizar estatísticas + adicionar páginas + hooks + links dos assistant components
+- [ ] `docs/architecture.md` — corrigir título (linha 1)
+- [ ] `docs/components/assistant-chart.md` — expandir e corrigir regra de dataKey
+- [ ] `docs/components/floating-media-wrapper.md` — completar seção "Related Components"
+- [ ] `docs/components/xertica-provider.md` — completar seção "AI Rules"
+- [ ] `docs/components/map-layers.md` — criar
+- [ ] `docs/installation.md` — adicionar requisito de `moduleResolution`
+- [ ] `docs/patterns/wizard.md` — criar
+- [ ] `docs/patterns/detail-page.md` — criar
+- [ ] `docs/patterns/settings.md` — criar
+- [ ] `docs/getting-started.md` — adicionar seção de troubleshooting
+- [ ] `docs/components/image-with-fallback.md` — criar
+- [ ] `docs/components/branding.md` — criar