@snksergio/design-system 0.61.0 → 0.62.0

package/dist-lib/ai/componentes/TabsNavigation.md

@@ -0,0 +1,152 @@
+# TabsNavigation
+
+<!-- ds:regras
+- aba de NAVEGADOR (sessão que abre/fecha: conversa, chamado, registro) → `<TabsNavigation>`; filtro de conteúdo dentro da tela → `tabs` do shadcn
+- `<TabsNavigation>` é SEMPRE controlado (`value` + `onValueChange`) e NÃO hospeda conteúdo — o painel pode morar fora, e aí a aba leva `panelId`
+- `surface` = a superfície do conteúdo ABAIXO da tira (`surface` num card, `canvas` na página). Errar quebra a união da aba ativa, que é o componente
+- `actions` na aba SUBSTITUI o `⋯`+`×` — é por ele que entram ✓/✗ de aceitar/recusar; sem `actions` e sem `onClose` a aba não tem ação
+-->
+
+Tira de abas de **navegação**, estilo navegador: cada aba é uma **sessão aberta** — com
+identidade, status e ações próprias — que o usuário abre, troca e fecha.
+
+## Quando usar
+
+| Situação | Componente |
+|---|---|
+| Conversas, chamados, registros abertos ao mesmo tempo; o usuário abre e fecha | **`TabsNavigation`** |
+| Alternar seções DENTRO de uma tela (Detalhes / Anexos / Histórico) | `tabs` (shadcn) |
+| Alternar visão de uma mesma lista (Tabela / Kanban) | `toggle-group` ou o `viewMode` do DataTable |
+
+Os dois convivem: uma aba de conversa pode conter um `Tabs` de Mensagens/Notas dentro.
+
+## Import
+
+```tsx
+import { TabsNavigation } from "@/components/ui/TabsNavigation";
+```
+
+## Exemplo mínimo
+
+```tsx
+const [ativa, setAtiva] = useState("c1");
+
+<TabsNavigation value={ativa} onValueChange={setAtiva} aria-label="Conversas abertas" onNewTab={abrir}>
+  <TabsNavigation.Tab
+    value="c1"
+    leading={<Avatar size="sm" colorHex="#2563EB">MS</Avatar>}
+    status="success"
+    badge={3}
+    onClose={() => fechar("c1")}
+  >
+    <TabsNavigation.Title>Maria Silva</TabsNavigation.Title>
+    <TabsNavigation.Subtitle>Fatura de julho</TabsNavigation.Subtitle>
+  </TabsNavigation.Tab>
+</TabsNavigation>
+```
+
+## O conteúdo mora onde você quiser
+
+O componente é a **tira**, não o roteador: ele diz qual aba está ativa e você troca o que
+quiser, onde quiser.
+
+```tsx
+{/* tira aqui… */}
+<TabsNavigation value={id} onValueChange={setId}>
+  <TabsNavigation.Tab value="c1" panelId="painel-detalhe">…</TabsNavigation.Tab>
+</TabsNavigation>
+
+{/* …e o conteúdo em outra coluna, outra rota, outro componente */}
+<section id="painel-detalhe">{conteudoDe(id)}</section>
+```
+
+- **Painel FORA** → `panelId` na aba (emite `aria-controls`).
+- **Painel DENTRO** → `<TabsNavigation.Panel value="c1">`, que faz o par `role="tabpanel"` +
+  `aria-labelledby` e renderiza só a ativa.
+- Sem nenhum dos dois o componente **não inventa** wiring — fica só `role="tab"` +
+  `aria-selected`, que é honesto.
+
+## Props — `TabsNavigation`
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `value` / `onValueChange` | `string` / `(v) => void` | — | sempre controlado |
+| `surface` | `surface \| canvas` | `surface` | superfície do **conteúdo abaixo** — a aba ativa é pintada com ela |
+| `density` | `comfortable \| compact` | `comfortable` | 48px com subtítulo · 40px sem |
+| `fill` | `boolean` | `false` | aba ocupa a faixa inteira; a tira perde a régua |
+| `actionsMode` | `hover \| persistent` | `hover` | ações reveladas no hover ou sempre visíveis |
+| `chrome` | `boolean` | `true` | pinta o fundo recuado da tira |
+| `onNewTab` | `() => void` | — | rende o `+` fora do trilho |
+| `aria-label` | `string` | — | rótulo do conjunto |
+
+## Props — `TabsNavigation.Tab`
+
+| Prop | Tipo | Descrição |
+|---|---|---|
+| `value` | `string` | volta em `onValueChange` |
+| `leading` | `ReactNode` | Avatar, `Icon`, imagem — qualquer nó |
+| `status` | `success \| warning \| danger \| info \| neutral \| ReactNode` | ponto pronto, ou o seu |
+| `badge` | `number \| ReactNode` | some na aba ativa |
+| `actions` | `ReactNode` | **substitui** as ações padrão |
+| `onClose` | `() => void` | sem `actions`, liga o `⋯` + `×` |
+| `menu` | `ReactNode` | itens extras do `⋯` |
+| `panelId` | `string` | id do container externo |
+| `actionsAlwaysVisible` | `boolean` | ações fixas só nesta aba |
+| `hoverCard` | `ReactNode` | resumo ao pousar o ponteiro (500ms); a aba ATIVA não mostra |
+
+Peças: `TabsNavigation.Title` · `TabsNavigation.Subtitle` (some sozinho em `compact`) · `TabsNavigation.Action`
+(botão de 24px, já com `stopPropagation`) · `TabsNavigation.Actions` (ações globais à direita) ·
+`TabsNavigation.Panel`.
+
+## Gotchas / cuidados
+
+- **`surface` é a cor do que está EMBAIXO, e é o erro clássico.** A aba ativa precisa ser a
+  mesma superfície do conteúdo — é isso que as une. Num card `surface`; se o conteúdo for a
+  página, `canvas`. Com o token errado a aba parece pousada em cima de outra coisa.
+- **`fill` troca o mecanismo da união, não só a altura.** No modo pousado a aba desce 1px e
+  apaga a régua; em `fill` a tira **não tem régua** e a união é por continuidade de cor.
+  Medido: manter o truque em `fill` deixava a aba 2px antes da régua — uma fresta, pior que
+  linha nenhuma.
+- **O fundo recuado usa dois tokens, um por modo** (`bg-emphasis` no claro, `bg-canvas` no
+  escuro) — medido: no claro `canvas` é branco igual à `surface` e `subtle` quase não se lê
+  contra a aba branca; no escuro `emphasis` é branco a 12% SOBRE o fundo, mais claro que a
+  superfície. Cada modo tem o seu token de recuo; não procure um único.
+- **⛔ Não envolva a tira num wrapper com padding.** O respiro do topo é do componente, e é
+  isso que a torna independente da superfície: quando o padding vinha de fora, aquela faixa
+  acima das abas ficava com a cor do container enquanto a tira ficava com o recuo — duas cores
+  na mesma banda, e a aba inativa parecia um botão de outra cor pousado num fundo diferente.
+  **A única coisa com fundo próprio é a aba ativa**, e ela é a superfície do conteúdo. Se o
+  container já pinta o recuo, desligue com `chrome={false}` em vez de compensar por fora.
+- **Ação que exige decisão não vai no hover.** `hover` é certo pra `⋯`/`×`; pra aceitar/recusar
+  um chamado use `actions` + `actionsAlwaysVisible` — o usuário precisa **ver** pra decidir, e
+  recusar por engano tem custo.
+- **As ações não reservam espaço** (coluna de grid `0fr → 1fr`): em repouso o título usa a aba
+  inteira. Se você passar `actions`, mantenha-as pequenas — a coluna abre por cima do título.
+- **`density="compact"` é escolha de conteúdo.** Sem subtítulo, duas conversas do mesmo cliente
+  ficam idênticas.
+- **As setas de overflow somem, não desabilitam.** Cada uma só existe enquanto houver o que
+  rolar naquele sentido; com a fila inteira visível não aparece nenhuma, e a lista `⌄` também
+  some. Botão apagado ocupa espaço e ainda lê como "tem algo aqui" — desabilitar faz sentido
+  quando a ação volta a valer no mesmo lugar, e aqui o gatilho é a largura da tira.
+- **Teclado:** ←/→/Home/End movem seleção e foco juntos; só a aba ativa fica na ordem de
+  tabulação. Não recrie isso por fora.
+- **jsdom não tem `ResizeObserver`** — o componente checa antes de instanciar, então ele não
+  derruba a suíte de quem consome. Em teste, os controles de overflow ficam ocultos (não há
+  medição de layout); teste o comportamento, não a seta.
+
+## Resumo em hover (`hoverCard`) e gesto de arrastar
+
+```tsx
+<TabsNavigation.Tab value="c1" hoverCard={<ResumoDoContato item={c} />}>…</TabsNavigation.Tab>
+```
+
+- **A aba ATIVA não mostra o resumo** — o conteúdo dela já está aberto na tela; um card por
+  cima seria ruído justamente pra quem está lendo aquilo.
+- **Abre com 500ms de espera.** Sem isso, percorrer a fila com o mouse dispararia o card de
+  todas as abas do caminho.
+- **Não coloque ação nem informação essencial ali** — hover não existe no toque.
+- **A tira rola arrastando** (mouse/pen, limiar de 6px, clique preservado). No celular não há
+  hook: o swipe nativo já faz melhor, com inércia.
+- **No celular as setas `‹ ›` somem** e ficam só o `+` e a lista `⌄`: medido em 375px, os três
+  controles comiam 204px e sobrava menos de meia aba visível. A aba também encolhe (168px em
+  vez de 228px) pra caber mais de uma na tela.

package/dist-lib/ai/componentes/Toast.md

@@ -0,0 +1,49 @@
+# Toast — USAGE
+
+**O que é:** card de notificação consistente sobre o Sonner. _Categoria: Feedback._
+Consome o Sonner via `toast.custom` → mantém **nativo**: agrupamento, empilhamento,
+slide, swipe-to-dismiss e posições. Só troca o conteúdo por um card do DS.
+
+**Quando usar:** feedback de ação (salvar, excluir, erro), avisos e convites com
+título + subtexto + ações. Pra toast cru sem card, use o Sonner direto.
+
+## Setup (1×)
+`<Toaster />` no root (de `@/components/shadcn/sonner`) — já segue o tema do DS.
+
+## Disparar
+```tsx
+import { toast } from "@/components/ui/Toast";
+
+toast.success({ title: "Alterações salvas", description: "Perfil atualizado." });
+toast.error({ title: "Falha no upload", action: { label: "Tentar de novo", tone: "danger" } });
+toast({ title: "3 mensagens novas", icon: <Mail />, meta: "agora", action: { label: "Ver" } });
+```
+
+## Props (do card)
+| Prop | Tipo | Nota |
+|---|---|---|
+| `title` | ReactNode | obrigatório |
+| `description` | ReactNode | subtexto (fg-muted) |
+| `status` | `default\|info\|success\|warning\|danger` | muda **só** o icon-chip; via `toast.success/.error/.warning/.info` |
+| `icon` | ReactNode | override do ícone do chip |
+| `meta` | ReactNode | texto curto à direita do título (ex.: "agora") |
+| `action` | `{ label, onClick, tone?, iconLeft?, iconRight? }` | sozinho = inline à direita |
+| `cancel` | `{ label, onClick }` | com `action` → rodapé (cancel ↔ action) |
+| `onClose` | `() => void` | mostra o X e dá dismiss |
+| `duration`/`position`/`id` | — | passthrough nativo do Sonner |
+
+`tone` do action: `brand` (default) · `neutral` · `danger`.
+
+## Status (cor)
+Só o **icon-chip** muda: bg fraco (`bg-{status}-muted`) + ícone forte (`fg-{status}`).
+A superfície do card é sempre neutra (`bg-surface`). Decisão de design: o feedback
+vem do ícone, não de tingir o toast inteiro.
+
+## Passthrough nativo
+`toast.promise(...)`, `toast.dismiss(id)`, `toast.loading(...)`, `toast.custom(...)`
+seguem disponíveis pelo mesmo `toast`.
+
+## Gotchas
+- Precisa do `<Toaster />` montado 1× (senão nada aparece).
+- `action` sozinho fica inline no header; pra 2 botões em rodapé, passe `cancel` também.
+- Pra conteúdo 100% livre (progress bar, avatar grande), use `toast.custom((id) => <…/>)`.

package/dist-lib/ai/componentes/_primitivos.md

@@ -0,0 +1,74 @@
+# Shadcn — USAGE (índice de gotchas)
+
+Atalho IA pros primitivos shadcn tokenizados. **Não há USAGE.md por arquivo**
+aqui (a API é a do shadcn/Radix, padrão e conhecida) — a doc viva por componente
+é o **showcase** (`#/<nome>`, em https://igreen-desingsystem-admin.vercel.app). Este índice lista **só o que NÃO é óbvio**: setup
+obrigatório, dependências extras e pegadinhas DS. Componente que não aparece na
+tabela = API shadcn padrão, sem gotcha → use direto e veja o showcase.
+
+> Regra de manutenção — **só pra quem desenvolve o DS** (consumindo, ignore): ao
+> **adicionar/editar** um shadcn, só crie/edite uma linha aqui **se houver gotcha real**
+> (setup, dep, receita, acessibilidade). Sem gotcha → não escrever nada (evita inchar o
+> arquivo e estourar tokens). Detalhe em `.claude/skills/ds-dev/impl-shadcn.md`.
+
+| Componente | Gotcha (o não-óbvio) |
+|---|---|
+| `sonner` | Monte `<Toaster/>` **1× no root**. Toast neutro (surface); status só troca o ícone. Self-contained (segue `.dark`, sem next-themes). **Pra card ergonômico (title/description/action/status), use o composto `ui/Toast`** — não estilizar status no Sonner. |
+| `tooltip` | `<Tooltip>` já embrulha o próprio Provider — **não** precisa de um no root. `delayDuration` default = **0** (instantâneo); sobrescreva com `<Tooltip delayDuration={400}>`. ⚠️ Até 2026-08-24 esta linha dizia 200ms e o componente não passava nada, valendo o default do Radix (**700**). |
+| `select` | **Nunca `<SelectItem value="">`.** `""` é a sentinela de "nada selecionado" do Radix (`shouldShowPlaceholder`): o rótulo da opção nunca aparece, e o item **lança** no 2.2.6 ("must have a value prop that is not an empty string") — erro que o 2.3.1 **removeu**, trocando quebra alta por silêncio. **E o valor controlado é ECOADO de volta**: dentro de um `<form>` o `SelectBubbleInput` faz `select.value = <valor>` e dispara `change`; sem `<option>` correspondente o DOM recusa e o eco volta `onValueChange("")` — apagando um valor que ninguém tocou. Morde sempre que as opções chegam DEPOIS do valor (lista assíncrona, ou opções derivadas do próprio formulário). **O `ui/FormField/FormFieldSelect` já trata os dois** (sentinela interna + guarda do eco, com testes em `valor-orfao.test.tsx`) — prefira-o a montar o primitivo na unha. |
+| `hover-card` | `openDelay` default = 200ms. Segue a receita flutuante (L-040). |
+| `context-menu`, `menubar`, `navigation-menu` | Superfície flutuante segue a **receita única** (L-040) — não reverter pros defaults shadcn. |
+| `card` | **`CardHeader` usa `gap-gp-2xs` (2px), não os 6px do shadcn upstream** — título e subtítulo de card são uma unidade de leitura, não dois blocos. Divergência **deliberada** (2026-08-19): ao re-sincronizar o primitivo, não reverter (mesma classe de cuidado da L-040). **`size`** (`sm`/`md`/`lg` = 16/20/24px) escala o padding de TODAS as partes — declare **só no `<Card>`**, chega em Header/Content/Footer por contexto; repetir nas partes é o erro que deixa uma seção com densidade diferente. **`md` (20px) é o default e antes era 24** — card que dependia dos 24 passa `size="lg"`. Não existe 18px na escala de `pad`, então `sm` é 16. Tokens: `p-pad-card-sm|md|lg` — ⚠️ `p-pad-card-base` continua existindo como **alias de `md`** (era 24 até 2026-08-19, virou 20): nada quebra, mas quem já consumia `base` recebe o novo valor. Não usar em código novo. **Subtítulo** (`CardDescription`) é `text-caption-md` (12/400), não `body-md` (14) — entre os dois presets de 12px, `caption-md` mantém o peso 400 e o `body-xs` (12/500) exigiria `font-normal` por cima. **`CardHeader variant="banded"`** = faixa `bg-bg-subtle` + `border-b border-border-subtle`, encostada nas bordas (cancela o `py` do Card com `-mt-*` e usa `rounded-t-*`, não `overflow-hidden` no Card — clipar quebraria o que precisa vazar); ⚠️ **Ação à direita na faixa exige `className="flex …"`, não `flex-row`**: o `CardHeader` é `grid` por padrão e `flex-row` **não troca o display** — os filhos continuam empilhando (o botão cai embaixo do título). Com `flex`, o tailwind-merge substitui o `grid` porque estão no mesmo grupo. ⚠️ No **dark** o `bg-subtle` é 1% de branco sobre surface 0.225: faixa muito discreta **de propósito** — se precisar de presença, `bg-muted` é 3× e no light é idêntico. O `Card` carrega o padding **vertical** e cada parte o **horizontal**, então parte full-bleed (tabela encostando nas bordas) é só zerar o `px` dela. |
+| `carousel` | Usa o **DS `Button`** interno (não o button shadcn). Dep extra: `embla-carousel-react`. `<CarouselDots />` = indicador de posição clicável: um ponto por **parada** (`scrollSnapList`), não por slide — com vários slides visíveis ou `slidesToScroll` os números divergem. Some sozinho quando há 1 parada. |
+| `input-otp` | Dep extra: `input-otp`. **Irmão do `Input`**: mesmos `size` (`xxs`/`xs`/`sm`/`md` → form-xs/sm/md/lg) e `state` (default/error/warning/success), mesma superfície, foco por **borda verde + `shadow-sh-ring`** (não `ring-4`). `variant`: `connected` (default) · `outlined` · `filled` · `underline`. Declare no `<InputOTP>` — os slots herdam por contexto; repetir a prop em cada slot é o erro que deixa um slot de tamanho diferente no meio da fileira. |
+| `drawer` | Dep extra: `vaul`. Mobile dentro de overlay z-50 → wrapper a **z-60** (L-030). |
+| `tabs` | **Duas props no `<Tabs>`, propagadas por contexto — NÃO em List/Trigger.** `variant`: `"segmented"` (default, pill) = trocar conteúdo DENTRO de uma superfície (card, bloco, `Panel`, `FloatingPanel`, `Modal`, drawer) · `"line"` (underline) = navegar seções de uma PÁGINA, ou 2º nível abaixo de um segmented; nunca empilhe a mesma variante em dois níveis. **`fullWidth`**: abas ocupam a largura e se distribuem — use em superfície compacta (`Panel` 560px, `FloatingPanel` 320–720 e redimensionável, `Modal` até `lg`, card, bloco); **não** use em toolbar (o `DataTable` usa hug de propósito), página livre ou `Modal` `xl` (1100px). ⛔ Não escreva `w-full` no List nem `flex-1` nos triggers na mão: `w-full` só no List estica o container e agrupa as abas na esquerda — era o defeito de 6 dos 7 usos manuais do próprio DS. |
+| `alert-dialog` | **ESC FECHA**, ao contrário do que o comentário do componente afirmava (medido no browser). Só o clique fora é bloqueado. Decisão inescapável exige `onEscapeKeyDown={(e) => e.preventDefault()}` — é o que o `ui/AlertModal` faz enquanto `loading`, porque o ESC é o único caminho de dismiss que não passa por um botão e escapava dos `disabled`. Header é **centralizado** (o do Dialog é à esquerda) e o Footer é `col-reverse` no mobile — ação em cima. No `sm+` o Footer **estica os filhos** (`sm:[&>*]:flex-1`): os botões dividem a largura toda, e você **não** precisa de `fullWidth` neles. Antes não esticava, e botão sem `fullWidth` ficava na largura do texto encostado à esquerda — o oposto do desenho; o `AlertModal` compensava passando `fullWidth` em cada Button. Pra confirmação comum use o composto **`ui/AlertModal`**, que já monta tom + ícone + botões. |
+| `input` | **`type="file"`** tem 2 desvios tratados por variante de atributo (`[&[type=file]]:…`): o UA aplica `align-items: baseline` e o conteúdo sobe na caixa de 40px → forçado `items-center`; e o texto do input vinha em `fg-default`, destoando do `placeholder:text-fg-muted` de todo input do DS → forçado `text-fg-muted`. **Efeito colateral aceito:** o CSS não distingue "vazio" de "arquivo escolhido" num file input, então o **nome do arquivo também fica muted**. Pra UX de upload de verdade (nome em destaque, remover, drag-and-drop) use o composto **`ui/FileUploadField`**, não o `<Input type="file">` cru. |
+
+**Padrão sem gotcha** (use direto, doc no showcase): `accordion`, `alert`,
+`aspect-ratio`, `badge`, `breadcrumb`, `button`, `calendar`, `checkbox`,
+`collapsible`, `command`, `dialog`, `dropdown-menu`, `label`, `popover`,
+`progress`, `radio-group`, `scroll-area`, `separator`, `sheet`,
+`skeleton`, `slider`, `switch`, `table`, `textarea`, `toggle`,
+`toggle-group`, `combobox`.
+
+> ⚠️ Id daqui **não pode** estar na tabela acima. `input` e `select` estavam nos dois
+> (corrigido em 2026-09-15) — quem lesse só esta lista usava direto um `select` cuja
+> sentinela `value=""` apaga valor em silêncio.
+
+## Payload de injeção (lido pelo hook, não por você)
+
+Os blocos abaixo são o que o `protect-ds.mjs` imprime quando a IA **escreve** aquele
+primitivo. A tabela acima é a doc completa; aqui vai só o que decide, curto de propósito —
+a célula do `tabs` tem 816 chars e não cabe num aviso. Primitivo sem bloco = silêncio.
+
+<!-- ds:regras tabs
+- `variant` default (segmented) dentro de superfície (card, bloco, Panel, Modal, drawer); `line` só pra seção de página
+- `fullWidth` em superfície compacta; ⛔ nunca `w-full` no List nem `flex-1` no trigger na mão
+-->
+
+<!-- ds:regras drawer
+- é bottom-sheet (vaul): mobile ou gesto de arrastar. Detalhe lateral em desktop → `Panel` (bloqueia) ou `FloatingPanel` (coexiste com a lista)
+- painel de DETALHE → siga o bloco `dsgreen-paneldetail-1` (o **padrão**). `-2` (tarefa com abas) e `-3` (com tabela) só se o usuário citar o ID
+-->
+
+<!-- ds:regras select
+- ⛔ nunca `<SelectItem value="">` — é a sentinela do Radix e apaga valor em silêncio
+- em form, prefira `FormFieldSelect` (já trata a sentinela e o eco do valor)
+-->
+
+<!-- ds:regras card
+- `size` (`sm`/`md`/`lg`) declare SÓ no `<Card>` — Header/Content/Footer herdam por contexto; repetir nas partes é o que deixa uma seção com densidade diferente
+- `CardHeader variant="banded"` com ação à direita pede `className="flex …"`, NUNCA `flex-row`: o header é `grid` e `flex-row` não troca o display — o botão cai embaixo do título
+-->
+
+<!-- ds:regras alert-dialog
+- confirmação comum → use o composto `ui/AlertModal` (já monta tom + ícone + botões); o primitivo cru só pra caso fora do padrão
+- ⚠️ ESC FECHA (só o clique fora é bloqueado). Decisão inescapável exige `onEscapeKeyDown={(e) => e.preventDefault()}`
+-->
+
+<!-- ds:regras sonner
+- `<Toaster/>` **1× no root**, senão o toast não aparece e não há erro
+- card ergonômico (title/description/action) → use o composto `ui/Toast`
+-->

package/dist-lib/ai/componentes/avatar-ig.md

@@ -0,0 +1,181 @@
+# Avatar
+
+<!-- ds:regras
+- vários avatares juntos → `<AvatarGroup>`, nunca `-ml-*` + `ring` na mão: ele resolve sobreposição por tamanho, cor do anel e excedente
+- `<AvatarGroup surface="...">` = a superfície ATRÁS do grupo (`table` numa linha de tabela). Errar isso põe um halo claro em volta de cada avatar
+- `max` + `total`: o `+N` conta pelo `total` (o do servidor), senão uma lista paginada mostra `+0` tendo 40 pessoas
+- `colorHex` escolhe a cor do texto por contraste WCAG (L-027) — nunca `text-white` na unha
+- foto de pessoa → `<Avatar src="…">` com as iniciais em `children` (são o fallback da URL que falha), nunca `<img>` solto nem o compound do shadcn dentro do grupo
+-->
+
+Circular badge displaying user initials. Supports semantic colors and per-person hex overrides.
+Para **vários avatares juntos**, use `AvatarGroup` (seção no fim).
+
+## Basic usage
+
+```tsx
+import { Avatar } from "@/components/ui/avatar-ig";
+
+// Semantic color (default: muted)
+<Avatar size="md" color="brand">MS</Avatar>
+
+// Person-specific hex color
+<Avatar size="sm" colorHex="#8754ec">CO</Avatar>
+
+// Foto — as iniciais continuam sendo o FALLBACK
+<Avatar size="lg" src="/fotos/maria.jpg" aria-label="Maria Silva">MS</Avatar>
+```
+
+## Foto (`src`, v0.53.0+)
+
+A imagem cobre o círculo (`object-cover`, sem distorcer) e escala pelos mesmos `size` das
+iniciais — inclusive dentro do `AvatarGroup`, que propaga o tamanho por contexto.
+
+- **Mantenha as iniciais em `children`.** Elas são o fallback quando a URL falha; sem elas,
+  uma foto quebrada deixa um buraco na fila. O fallback herda a cor (`color`/`colorHex`).
+- **Trocar a `src` depois de uma falha tenta de novo** — o componente guarda *qual* URL
+  falhou, não um booleano.
+- **Não há prop `alt`.** A imagem interna é `alt=""` e o nome mora no `aria-label` do avatar;
+  dois rótulos no mesmo elemento fazem o leitor de tela anunciar a pessoa duas vezes.
+- **Quando usar o compound do shadcn** (`avatar`, com `AvatarImage`/`AvatarFallback`): quando
+  o fallback não é iniciais (ícone, skeleton) ou você precisa do estado de carregamento. Pra
+  foto de pessoa no DS — e sempre dentro de `AvatarGroup` — o certo é este.
+
+## Sizes
+
+| Size | Pixels | Typography preset |
+|------|--------|-------------------|
+| `xs` | 20px   | caption-sm (11px) |
+| `sm` | 24px   | caption-sm (11px) |
+| `md` | 28px   | caption-sm (11px) |
+| `lg` | 32px   | body-sm font-normal (13px) |
+| `xl` | 40px   | body-md font-medium (14px) |
+
+## Colors
+
+| Color      | Background         | Foreground          |
+|------------|--------------------|--------------------|
+| `brand`    | `bg-bg-brand`      | `fg-on-brand`      |
+| `success`  | `bg-bg-success`    | `fg-on-success`    |
+| `warning`  | `bg-bg-warning`    | `fg-on-warning`    |
+| `critical` | `bg-bg-danger`     | `fg-on-danger`     |
+| `info`     | `bg-bg-info`       | `fg-on-info`       |
+| `muted`    | `bg-bg-muted`      | `fg-muted`         |
+
+## colorHex override + auto contrast (v0.7.1+)
+
+When `colorHex` is provided (string starting with `#`), the background is set
+via inline style and **a cor de texto é escolhida automaticamente** pra ter
+o maior contraste WCAG entre `white` ou `black`. O prop `color` é ignorado.
+
+| Hex bg               | Texto auto-pickado | Motivo (WCAG ratio)                    |
+|----------------------|--------------------|----------------------------------------|
+| `#FAE128` (BB)       | `black`            | white 1.29 vs black 16.3 → preto vence |
+| `#820AD1` (Nubank)   | `white`            | white 6.2 vs black 3.4 → branco vence  |
+| `#EC7000` (Itaú)     | `black`            | white 2.7 vs black 7.8 → preto vence   |
+| `#CC092F` (Bradesco) | `white`            | white 6.5 vs black 3.2 → branco vence  |
+| `#FFFFFF`            | `black`            | óbvio                                   |
+| `#000000`            | `white`            | óbvio                                   |
+
+A escolha vem de `getContrastTextColor()` em `@/utils/color-contrast.ts`
+(WCAG 2.x relative luminance + contrast ratio).
+
+```tsx
+<Avatar colorHex="#FAE128">BB</Avatar>      // texto preto auto
+<Avatar colorHex="#820AD1">NU</Avatar>      // texto branco auto
+```
+
+**Override manual:** se precisar forçar uma cor específica (caso raro de
+brand guideline), passe via `className`:
+
+```tsx
+<Avatar colorHex="#FAE128" className="text-white">BB</Avatar>
+// (não recomendado — quebra WCAG AA)
+```
+
+## Accessibility
+
+- With `aria-label`: renders `role="img"` (semantic avatar).
+- Without `aria-label`: renders `aria-hidden="true"` (decorative).
+
+```tsx
+// Semantic — standalone avatar with meaning
+<Avatar aria-label="Maria Silva">MS</Avatar>
+
+// Decorative — inside a card/cell that already provides context
+<Avatar colorHex="#8754ec">CO</Avatar>
+```
+
+## Props
+
+| Prop         | Type                                                        | Default   |
+|--------------|-------------------------------------------------------------|-----------|
+| `size`       | `"xs" \| "sm" \| "md" \| "lg" \| "xl"`                     | `"md"`    |
+| `color`      | `"brand" \| "success" \| "warning" \| "critical" \| "info" \| "muted"` | `"muted"` |
+| `colorHex`   | `string` (hex starting with `#`)                            | —         |
+| `src`        | `string` — foto; URL que falha volta pras iniciais           | —         |
+| `children`   | `ReactNode` (initials) — também o fallback da foto           | —         |
+| `className`  | `string`                                                    | —         |
+| `aria-label` | `string`                                                    | —         |
+
+---
+
+# AvatarGroup
+
+Pilha de avatares sobrepostos, com `size` propagado e excedente resumido em `+N`.
+
+## Quando usar
+
+Conjunto de pessoas onde **o grupo importa mais que cada uma**: responsáveis de uma tarefa,
+participantes, membros de um time. Para 2 avatares que devem ser lidos individualmente, use
+`flex gap-gp-sm` comum — a sobreposição comunica "muitos".
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `size` | `xs \| sm \| md \| lg \| xl` | `md` | **propagado por contexto** a todos os filhos |
+| `max` | `number` | — | acima disso, corta e mostra `+N` |
+| `total` | `number` | nº de filhos | contagem REAL, pro `+N` refletir o servidor |
+| `surface` | `surface \| canvas \| subtle \| muted \| table` | `surface` | superfície **atrás** do grupo — define a cor do anel |
+| `aria-label` | `string` | — | rótulo do grupo, ex.: `"12 responsáveis"` |
+
+## Exemplo
+
+```tsx
+import { Avatar, AvatarGroup } from "@/components/ui/avatar-ig";
+
+{/* foto e iniciais misturadas: o size vem do container, ninguém sai de escala */}
+<AvatarGroup size="sm" max={3} total={12} aria-label="12 responsáveis">
+  <Avatar src="/fotos/ana.jpg" aria-label="Ana">AN</Avatar>
+  <Avatar src="/fotos/bruno.jpg" aria-label="Bruno">BR</Avatar>
+  <Avatar colorHex="#7C3AED" aria-label="Júlia">JS</Avatar>
+  <Avatar colorHex="#0891B2" aria-label="Tiago">TK</Avatar>
+</AvatarGroup>
+```
+
+## Gotchas / cuidados
+
+- **`surface` é a cor do que está ATRÁS, e é o erro clássico.** O anel separa um avatar do
+  outro pintando a cor da superfície de trás; com o token errado ele deixa de separar e vira um
+  halo. Sobre `bg-bg-muted` ou `bg-bg-canvas`, declare o token correspondente.
+  ⚠️ **`table` e `surface` resolvem pro mesmo valor hoje** — `oklch(1 0 0)` no claro e
+  `oklch(0.225 0 0)` no escuro (medido). Dentro de tabela a escolha é **semântica**, não
+  visual: declare `table` mesmo assim, pra que a pilha continue certa se um dia os dois
+  divergirem, sem ninguém ter que caçar o call site.
+- **`total` não é opcional quando a lista é paginada.** Sem ele o `+N` conta só o que foi
+  renderizado — 4 filhos com `max={2}` mostram `+2`, mesmo que existam 40 pessoas.
+- **`size` no filho vence o do grupo.** É escape hatch pra destacar um avatar; sem passar nada,
+  todos herdam o do grupo.
+- **A sobreposição escala com o tamanho** (~25% do diâmetro): `xs` desloca 4px e `xl` desloca
+  10px. Não é constante de propósito — 6px num avatar de 20px é 30% de sobreposição e num de
+  40px é 15%, que são arranjos visuais diferentes.
+- **O primeiro fica por cima** (z-index decrescente), invertendo o empilhamento natural do DOM.
+  A leitura é da esquerda pra direita e o primeiro é o principal.
+- **O grupo fala, os avatares calam.** O container é `role="group"` com `aria-label`; o `+N` é
+  `aria-hidden` porque a contagem real já está no rótulo. Sem o `aria-label`, o leitor de tela
+  lê N nomes soltos sem dizer que são um conjunto.
+- **Foto e iniciais convivem na mesma pilha.** A foto obedece ao mesmo `size` de contexto, e o
+  anel importa mais com foto: sem ele, duas fotos escuras encostadas viram uma mancha só.
+- **O anel mora no wrapper, não no `Avatar`.** `ring` acompanha o `border-radius` do elemento —
+  num wrapper quadrado traçaria um quadrado. `Avatar` fora de grupo continua sem anel.

package/dist-lib/ai/componentes/indice.json

@@ -0,0 +1,49 @@
+{
+  "AlertModal": "componentes/AlertModal.md",
+  "AppShell": "componentes/AppShell.md",
+  "avatar-ig": "componentes/avatar-ig.md",
+  "Breadcrumb": "componentes/Breadcrumb.md",
+  "Button": "componentes/Button.md",
+  "ButtonGroup": "componentes/ButtonGroup.md",
+  "CardCheckbox": "componentes/CardCheckbox.md",
+  "CardOption": "componentes/CardOption.md",
+  "Chart": "componentes/Chart.md",
+  "Chip": "componentes/Chip.md",
+  "ChoroplethMap": "componentes/ChoroplethMap.md",
+  "ColorPicker": "componentes/ColorPicker.md",
+  "Combobox": "componentes/Combobox.md",
+  "ConversationListItem": "componentes/ConversationListItem.md",
+  "DataList": "componentes/DataList.md",
+  "DataTable": "componentes/DataTable.md",
+  "DatePicker": "componentes/DatePicker.md",
+  "DateSeparatorChip": "componentes/DateSeparatorChip.md",
+  "EmptyState": "componentes/EmptyState.md",
+  "FileUploadField": "componentes/FileUploadField.md",
+  "FloatingPanel": "componentes/FloatingPanel.md",
+  "FooterTable": "componentes/FooterTable.md",
+  "FormField": "componentes/FormField.md",
+  "Gantt": "componentes/Gantt.md",
+  "Header": "componentes/Header.md",
+  "Icon": "componentes/Icon.md",
+  "Kanban": "componentes/Kanban.md",
+  "Kpi": "componentes/Kpi.md",
+  "List": "componentes/List.md",
+  "MarkdownText": "componentes/MarkdownText.md",
+  "MenuSidebar": "componentes/MenuSidebar.md",
+  "MessageAck": "componentes/MessageAck.md",
+  "MessageBubble": "componentes/MessageBubble.md",
+  "MessageComposer": "componentes/MessageComposer.md",
+  "MessageVariablesPicker": "componentes/MessageVariablesPicker.md",
+  "Modal": "componentes/Modal.md",
+  "MonthYearPicker": "componentes/MonthYearPicker.md",
+  "PageHeader": "componentes/PageHeader.md",
+  "Panel": "componentes/Panel.md",
+  "Scheduler": "componentes/Scheduler.md",
+  "ScreenLoader": "componentes/ScreenLoader.md",
+  "SingleMenuSidebar": "componentes/SingleMenuSidebar.md",
+  "Spinner": "componentes/Spinner.md",
+  "Table": "componentes/Table.md",
+  "TableToolbar": "componentes/TableToolbar.md",
+  "TabsNavigation": "componentes/TabsNavigation.md",
+  "Toast": "componentes/Toast.md"
+}