# 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