@snksergio/design-system 0.60.0 → 0.62.0

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

@@ -0,0 +1,47 @@
+# AlertModal — USAGE
+
+Modal de confirmação destrutiva com tone semântico (danger/warning/success/neutral).
+
+## Quando usar
+- Confirmar ação destrutiva (excluir, arquivar, revogar)
+- Pedir confirmação de decisão crítica antes de executar
+
+## Import
+```tsx
+import { AlertModal } from "@/components/ui/AlertModal";
+```
+
+## Props essenciais
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `open` | boolean | — | Controla visibilidade |
+| `onOpenChange` | (open: boolean) => void | — | Callback de fechamento |
+| `tone` | "default" \| "neutral" \| "danger" \| "warning" \| "success" | "default" | Cor semântica |
+| `title` | ReactNode | — | Título do modal |
+| `description` | ReactNode | — | Texto explicativo |
+| `confirmLabel` | ReactNode | "Confirmar" | Conteúdo do botão primary |
+| `cancelLabel` | ReactNode | "Cancelar" | Conteúdo do botão secondary |
+| `hideCancel` | boolean | false | Esconde o botão Cancel (modal de aviso só com OK) |
+| `hideClose` | boolean | false | Esconde o botão X de fechar no canto superior direito |
+| `onConfirm` | () => void | — | Ação ao confirmar |
+| `loading` | boolean | false | Trava interação durante async — **os 4 caminhos de dismiss**, inclusive ESC |
+| `icon` | ReactNode \| null | — | Ícone customizado; `null` esconde; omitir usa o default do tone |
+
+## Exemplo mínimo
+```tsx
+<AlertModal
+  open={confirmDelete}
+  onOpenChange={setConfirmDelete}
+  tone="danger"
+  title="Excluir cliente?"
+  description="Esta ação não pode ser desfeita"
+  onConfirm={handleDelete}
+/>
+```
+
+## Cuidados / Gotchas
+- Quando `loading=true`, modal **não fecha automaticamente** — consumer chama `onOpenChange(false)` após async terminar. Vale para **todos** os caminhos: Confirmar, Cancelar, X **e ESC**. O ESC era o que faltava (era o único que não passa por botão): num delete assíncrono ele fechava o modal com a requisição em voo, e o `onOpenChange` do consumidor era chamado. Consertado com `onEscapeKeyDown` + `preventDefault`, então nem o evento chega
+- `tone="danger"` aplica cor critical ao botão de confirm
+- `icon={null}` esconde o ícone; **omitir** a prop usa o ícone default do tone (`tone="default"` não tem ícone)
+- Pra forçar decisão explícita (sem escape pelo X), use `hideClose`; pra modal informativo só com OK, use `hideCancel`
+- Pra "alert" não-destrutivo, prefira `<Modal>` simples

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

@@ -0,0 +1,117 @@
+# AppShell — USAGE
+
+<!-- ds:regras
+- tem áreas separadas (Comercial, Financeiro…)? → `sidebar="menu"` + `contexts`. Não tem? → `"single"` + `categories`, sem `sidebarModules` nem `sidebarShowSearch`
+- NÃO passe `sidebarLogo`: o default é a marca iGreen. Só com marca própria pedida explicitamente
+- `sidebarTitle` = nome do projeto (vai à direita da logo) — pergunte, não invente
+-->
+
+Template de aplicação completo: MenuSidebar (rail + panel) + Header sticky + body com slot livre.
+
+## Quando usar
+- Páginas full-app (Showcases, CRUD, Chat, Dashboard)
+- Quando precisar de contexts (workspace switcher) + breadcrumb + user menu unificados
+
+## Import
+```tsx
+import { AppShell } from "@/components/ui/AppShell";
+```
+
+## Qual sidebar — `menu` (default) × `single`
+
+O shell monta **uma das duas** sidebars. O tipo é **união discriminada**: cada escolha exige
+o seu próprio conjunto de dados, e o TS cobra no editor.
+
+| `sidebar` | quando | exige |
+|---|---|---|
+| `"menu"` (default) | app com **áreas distintas** (Comercial, Financeiro…), cada uma com menu próprio | `contexts` |
+| `"single"` | **sistema único**, um menu só — busca opcional | `categories` + `sidebarLogo` + `sidebarTitle` |
+
+```tsx
+<AppShell
+  sidebar="single"
+  categories={CATEGORIES}
+  sidebarLogo={<MinhaLogo />}
+  sidebarTitle="Meu Sistema"
+  sidebarShowSearch
+  activeItemId={ativo}
+  onSidebarItemClick={setAtivo}
+  breadcrumb={[{ label: "Sistema" }]}
+>…</AppShell>
+```
+
+**O toggle do Header funciona nas duas sem você cabear nada.** O mapeamento interno difere
+porque os componentes modelam o estado de formas diferentes — `MenuSidebar` tem
+`panelCollapsed` + drawer no mobile; a single tem `expanded`, e no mobile o `expanded` **é** a
+visibilidade (expandida ocupa 100% da largura, recolhida some).
+
+⚠️ **`onSidebarItemClick` é separado do `onItemClick`**, e não é redundância: o `MenuSidebar`
+entrega o **item** (`SidebarMenuItem`), a single entrega o **`id`**. Mesmo nome faria você
+receber um tipo e escrever pro outro.
+
+⚠️ **Por que união e não props opcionais:** deixar `contexts` opcional trocaria erro de
+compilação por falha silenciosa — ausente com a sidebar de menu, o rail renderiza **vazio**,
+sem erro nenhum.
+
+## Props essenciais
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `sidebar` | `"menu" \| "single"` | `"menu"` | Qual menu lateral montar — ver a seção acima |
+| `fillHeight` | boolean | `false` | O shell obedece a altura do **pai** (`h-full`) em vez de 100vh. **Ligue quando embutir o shell em algo com altura** (layout com footer, aba, preview): sem isso ele transborda e o `overflow-hidden` do container corta o rodapé do body junto com o padding — o sintoma é "conteúdo colado na borda", e não é falta de padding. ⚠️ exige pai com altura |
+| `contexts` | SidebarContext[] | — | Lista de workspaces no rail (**só** com `sidebar="menu"`) |
+| `categories` | SingleMenuCategory[] | — | Categorias do menu (**só** com `sidebar="single"`) |
+| `sidebarLogo` | ReactNode | **marca iGreen** | Logo do header da sidebar single. **Omita** pra ficar com a marca — só passe se o app tem marca própria |
+| `sidebarTitle` | string | — | **Nome do projeto**, à direita da logo. Obrigatória de propósito: é o que o DS não adivinha |
+| `activeItemId` | string | — | Item ativo da single (a variante `menu` usa `activeItemHref`) |
+| `onSidebarItemClick` | (id: string) => void | — | Clique em item da single |
+| `sidebarModules` | SingleMenuModuleConfig[] | — | Módulos com menu próprio — o seletor troca o conjunto de categorias |
+| `sidebarShowSearch` | boolean | — | Busca no topo da sidebar (é um botão que abre command palette, não um input) |
+| `sidebarSearchPlaceholder` | string | — | Placeholder da busca **da sidebar** — distinto do `searchPlaceholder`, que é do Header |
+| `defaultActiveContextId` | string | primeiro do array | Workspace inicial (uncontrolled) |
+| `activeContextId` | string | — | Workspace ativo (controlled) |
+| `onContextChange` | (id: string) => void | — | Callback de troca de workspace |
+| `defaultActiveItemHref` | string | — | Item do panel ativo inicial (uncontrolled) |
+| `activeItemHref` | string | — | Item do panel ativo (controlled) |
+| `onItemClick` | (item, event?) => void | — | Clique em item do panel. **2º arg é o `MouseEvent`** |
+| `renderLink` | (props) => ReactNode | — | ⭐ **Integração com router** — troca o `<a>` interno pelo `<Link>`. Ver `MenuSidebar/USAGE.md` §Integração com router |
+| `brandHref` | string | `"/"` | Destino do brand no rail; `""` torna não-navegável |
+| `onBrandClick` | (e) => void | — | Clique no brand |
+| `breadcrumb` | HeaderBreadcrumbItem[] | — | Caminho atual exibido no Header |
+| `commandGroups` | HeaderCommandGroup[] | — | Command palette (⌘K) |
+| `notifications` | { items, onMarkAllRead, onViewAll } | — | Dropdown de notificações |
+| `messages` | { items, onNewMessage, onExpand, onViewAll } | — | Dropdown de mensagens |
+| `theme` | string | — | Tema atual (light/dark) |
+| `onThemeChange` | (id: string) => void | — | Callback de troca de tema |
+| `themeOptions` | HeaderThemeOption[] | — | Opções de tema disponíveis |
+| `headerRightSlot` | ReactNode | — | Slot extra no canto direito do Header |
+| `user` | AppShellUser | — | Avatar + user menu no rail bottom |
+| `layout` | string ("fluid" \| "compact") | comportamento "fluid" | Densidade do body (qualquer valor ≠ "compact" cai em fluid) |
+| `onLayoutChange` | (id: string) => void | — | Callback do switcher Fluido/Compacto do user menu |
+| `layoutOptions` | AppShellLayoutOption[] | — | Opções do switcher de layout |
+| `onSettings` | () => void | — | Ação "Configurações" do user menu (item escondido se omitido) |
+| `onLogout` | () => void | — | Ação "Sair" do user menu (item escondido se omitido) |
+| `menuCollapsed` | boolean | — | Sidebar colapsado (controlled) |
+| `defaultMenuCollapsed` | boolean | **responsivo** | Estado inicial do collapse (uncontrolled). Omitido: colapsado `<1536px`, expandido acima. Valor explícito vence — inclusive `false`. Só no mount, resize não re-colapsa |
+| `onMenuCollapseChange` | (collapsed: boolean) => void | — | Callback no toggle do collapse (persistir entre sessões) |
+
+## Exemplo mínimo
+```tsx
+<AppShell
+  contexts={APP_SHELL_CONTEXTS}
+  defaultActiveContextId="inbox"
+  breadcrumb={[{ label: "Clientes" }]}
+  theme={theme}
+  onThemeChange={setTheme}
+>
+  <YourPageContent />
+</AppShell>
+```
+
+## Cuidados / Gotchas
+- Body interno tem `gap-gp-4xl` (24px) fixo e padding **responsivo em 3 patamares**: 18px `<768`, **24px `768–1535` (notebook)**, 32px `≥1536`. Customize spacing dentro do `children`, não aqui
+- `contexts` mínimo 1; sem isso o rail fica vazio
+- Mobile: `mobileEdgeToEdge` remove padding do body
+- User menu (layout + tema + settings + logout) só renderiza quando `user` é passado; sem ele o rail mantém o avatar default
+- `layout` é controlled-only: sem `onLayoutChange` o switcher Fluido/Compacto do user menu não tem efeito — guarde o valor em state e devolva via `layout`
+- Pra navegação real, use `activeItemHref` + `onItemClick` (controlled) ligados ao router — os `default*` servem só pro modo uncontrolled/preview
+- ⚠️ **Com react-router (ou qualquer router de history), passe `renderLink`**: `renderLink={(p) => <Link {...p} to={p.href} />}`. Sem isso, `href` de path fazia o browser recarregar a página inteira a cada clique de menu — bug real reportado em 2026-08-08, corrigido na v0.38.0. Detalhe e as 5 exceções em `MenuSidebar/USAGE.md` §Integração com router

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

@@ -0,0 +1,187 @@
+# Breadcrumb
+
+<!-- ds:regras
+- o caminho e o seletor vêm do MESMO item: `import { Breadcrumb, BreadcrumbItem, BreadcrumbSwitcher } from "@/components/ui/Breadcrumb"`
+- página de DETALHE (ficha de cliente, UC, contrato, chamado) → o item do registro no breadcrumb é `<BreadcrumbSwitcher>`, não texto: quem está numa ficha quer pular pra outra, não voltar à lista
+- é controlado e **não navega**: `onValueChange` devolve o `value` e quem decide rota/fetch é você
+- no `Header`, o item vira seletor com os TRÊS juntos — `switcher` + `value` + `onValueChange`; faltando um, fica texto
+- escolher valor de FORMULÁRIO não é isto: é `combobox` (o trigger dele tem cara de campo de propósito)
+-->
+
+Caminho de navegação — e a variação em que **o item troca o registro aberto**.
+
+Os primitivos (`Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`,
+`BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`) e o `BreadcrumbSwitcher` saem
+do mesmo lugar: são a mesma peça, com e sem troca.
+
+## BreadcrumbSwitcher
+
+O item do caminho que **troca o registro aberto**: o nome do que está aberto vira gatilho e
+abre uma lista com busca. É o seletor de repositório do GitHub aplicado a cliente, UC,
+contrato — qualquer coisa de que existam muitos.
+
+## Quando usar
+
+| Situação | Componente |
+|---|---|
+| Página de detalhe de UM registro entre muitos parecidos | **`BreadcrumbSwitcher`** |
+| Navegar entre seções fixas do caminho | `BreadcrumbLink` (o breadcrumb normal) |
+| Escolher um valor num formulário | `combobox` |
+| Trocar entre sessões abertas ao mesmo tempo | `tabs-navigation` |
+
+## Os dois modos
+
+```tsx
+// 1) pronto — dados entram, cadeia sai (95% das telas)
+<Breadcrumb items={[
+  { label: "Clientes", href: "/clientes" },
+  { label: cliente.nome },                 // sem href = página atual
+]} />
+
+// 2) composição — pra interpor algo ou estilizar item a item
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem><BreadcrumbLink href="/clientes">Clientes</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><Chip size="sm">homologação</Chip></BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+| Prop da raiz | | |
+|---|---|---|
+| `items` | `BreadcrumbItemData[]` | sem ele, renderiza `children` no primitivo |
+| `size` | `sm` | `md` | `sm` = 13px na cadeia e 16px em item único (é o do `Header`); `md` = 14px (o do primitivo) |
+| `separator` | `ReactNode` | default `ChevronRight` de 14px |
+
+## Import
+
+```tsx
+import { Breadcrumb, BreadcrumbItem, BreadcrumbSwitcher } from "@/components/ui/Breadcrumb";
+```
+
+## Exemplo mínimo
+
+```tsx
+<BreadcrumbItem>
+  <BreadcrumbSwitcher
+    value={clienteId}
+    onValueChange={abrirCliente}
+    options={clientes}            // { value, label, leading?, description?, keywords?, group? }
+    title="Trocar cliente"
+    searchPlaceholder="Buscar por nome ou documento…"
+    aria-label="Trocar cliente"
+  />
+</BreadcrumbItem>
+```
+
+## No `Header`
+
+O item do breadcrumb do `Header` vira seletor sozinho:
+
+```tsx
+<Header
+  breadcrumb={[
+    { label: "Clientes", href: "/clientes" },
+    {
+      label: cliente.nome,
+      switcher: clientes,
+      value: cliente.id,
+      onValueChange: abrirCliente,
+      switcherTitle: "Trocar cliente",
+    },
+  ]}
+/>
+```
+
+Precisa dos **três** (`switcher` + `value` + `onValueChange`). Faltando um, o item renderiza
+como texto normal. No celular, onde a cadeia colapsa e sobra só o último item, o seletor
+continua ali.
+
+## Props
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `value` / `onValueChange` | `string` / `(v: string) => void` | — (controlado) |
+| `options` | `BreadcrumbSwitcherOption[]` | — |
+| `placeholder` | `ReactNode` — quando o `value` não está na lista | o próprio `value` |
+| `title` | `ReactNode` — cabeçalho do dropdown | — |
+| `searchPlaceholder` | `string` | `"Buscar…"` |
+| `emptyMessage` | `ReactNode` | `"Nada encontrado."` |
+| `footer` | `ReactNode` — fora da área que rola | — |
+| `open` / `onOpenChange` | abertura controlada | — |
+| `align` | `start \| center \| end` | `"start"` |
+| `aria-label` | `string` | `"Trocar registro aberto"` |
+
+`BreadcrumbSwitcherOption`: `{ value, label, leading?, description?, keywords?, group? }`.
+
+## `trailing` — conteúdo livre depois do rótulo
+
+Qualquer item do modo `items={...}` (e do `breadcrumb` do `Header`) aceita
+`trailing?: ReactNode` — o que vier ali entra no mesmo `<li>`, depois do rótulo
+ou do gatilho:
+
+```tsx
+<Breadcrumb
+  items={[
+    { label: "Clientes", href: "/clientes" },
+    {
+      label: cliente.nome,
+      switcher: CLIENTES, value: id, onValueChange: setId,
+      trailing: (
+        <Chip size="sm" variant="soft" color={cliente.statusCor}>
+          {cliente.status}
+        </Chip>
+      ),
+    },
+  ]}
+/>
+```
+
+O slot **não sabe** que o caso de origem foi status: aceita qualquer nó e qualquer
+montagem. E vale pros quatro tipos de item — seletor, link, página atual e texto
+inerte —, não só pro seletor.
+
+⚠️ **Ele é IRMÃO do gatilho, não filho.** É o que torna "qualquer componente"
+verdade: `<button>` dentro de `<button>` é HTML inválido e quebra clique e foco,
+então chip clicável, link ou botão só funcionam porque o slot é externo. A
+consequência é de desenho, não acidente — **clicar no `trailing` não abre a
+lista**, e é o certo: status não é a affordance de "trocar registro".
+
+No **modo composição** você não precisa dele: `BreadcrumbItem` é
+`inline-flex items-center gap-gp-sm`, então basta escrever o nó ao lado.
+
+```tsx
+<BreadcrumbItem>
+  <BreadcrumbSwitcher … />
+  <Chip size="sm" variant="soft" color="success">Ativo</Chip>
+</BreadcrumbItem>
+```
+
+## Gotchas / cuidados
+
+- **Ele não navega.** `onValueChange` devolve o valor; rota, fetch e estado são seus. É o que
+  faz o mesmo componente servir pro app com router e pro painel que só troca estado local.
+- **`keywords` é pra o que o usuário sabe de cor e a tela não mostra** — CPF/CNPJ, código
+  interno, apelido. A busca filtra por `label` + `keywords`, e o `value` já entra
+  automaticamente.
+- **A busca é local E fuzzy.** O `Command` filtra por subsequência com score, não por prefixo:
+  procurar um CPF pode trazer junto um CNPJ que compartilha dígitos, com score menor. O certo
+  vem em primeiro; não prometa "resultado único" na sua tela. E acima de ~1.000 registros,
+  pagine ou busque no servidor antes de montar `options`.
+- **A opção do registro aberto sai com `data-atual`** no DOM — use isso pra estilizar ou
+  testar. O `data-selected` do cmdk é outra coisa (o item ativo do teclado), e "tem svg" não
+  serve de sinal porque `leading` também é svg.
+- **Grupos saem na ordem de `options`**, não alfabética — “Recentes” antes de “Todos” é
+  informação, não acaso.
+- **Passe `aria-label` com o nome do domínio** (“Trocar cliente”). O default genérico funciona,
+  mas quem ouve a tela merece o termo certo.
+- **Use `placeholder` quando a lista chega assíncrona**: sem ele, enquanto as opções não
+  carregam, o caminho mostra o `value` cru (um id), que lê como bug.
+- **Item único é TÍTULO, não caminho.** Com um item só e `size="sm"`, ele sobe pra 16px/600 —
+  uma cadeia de um elemento é o nome da tela. É o comportamento que o `Header` sempre teve.
+- **O `href` do ÚLTIMO item é ignorado**: página atual não navega pra si. E o atual é um
+  `BreadcrumbPage`, que o shadcn expõe como `role="link" aria-disabled aria-current="page"` —
+  se você testar "não é link" por `getByRole("link")`, vai achar que quebrou.
+- **Não empilhe com um link no mesmo item.** Se o item tem `switcher`, o clique abre a lista —
+  um `href` ali seria uma segunda intenção que nunca dispara.

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

@@ -0,0 +1,116 @@
+# Button
+
+Componente interativo para ações. Suporta 5 cores, 4 variantes e 10 tamanhos (5 com label + 5 icon-only).
+
+## Variantes
+
+| color + variant    | Quando usar |
+|--------------------|-------------|
+| primary + filled   | Ação principal da tela, CTA — único por contexto |
+| primary + outline  | Ação secundária com destaque de marca |
+| primary + soft     | Ação com peso visual reduzido, fundo tonal |
+| primary + ghost    | Ação terciária, sem peso visual |
+| secondary + filled | Ação de destaque sem conotação de marca (settings, filtros) |
+| secondary + outline| Ação neutra com borda — uso geral |
+| secondary + soft   | Ação neutra com fundo sutil |
+| secondary + ghost  | Ação neutra sem peso visual |
+| critical + filled  | Ação destrutiva ou irreversível (deletar, remover) |
+| critical + outline | Ação destrutiva com menos peso |
+| critical + soft    | Ação destrutiva em contexto de lista |
+| critical + ghost   | Ação destrutiva terciária |
+| success + filled   | Confirmação positiva, ação concluída com sucesso |
+| success + outline  | Feedback positivo com menos peso |
+| success + soft     | Feedback positivo em contexto de lista |
+| success + ghost    | Feedback positivo terciário |
+| warning + filled   | Ação que requer atenção ou cautela |
+| warning + outline  | Alerta com menos peso visual |
+| warning + soft     | Alerta em contexto de lista |
+| warning + ghost    | Alerta terciário |
+
+## Tamanhos
+
+| size | Height | Uso |
+|------|--------|-----|
+| `2xs` | 28px (`formHeight.xs`) | Toolbars compactas, inline actions |
+| `xs` | 32px (`formHeight.sm`) | Formulários densos, filtros |
+| `sm` | 36px (`formHeight.md`) | Padrão desktop |
+| `md` | 40px (`formHeight.lg`) | Padrão mobile / CTA — touch-friendly |
+| `lg` | 44px (`formHeight.xl`) | WCAG touch target (44px) |
+| `icon-2xs` | 28×28px (quadrado) | Icon button — toolbars compactas |
+| `icon-xs` | 32×32px (quadrado) | Icon button — formulários densos |
+| `icon-sm` | 36×36px (quadrado) | Icon button — padrão desktop |
+| `icon-md` | 40×40px (quadrado) | Icon button — padrão mobile |
+| `icon-lg` | 44×44px (quadrado) | Icon button — WCAG touch target |
+
+Icon sizes são quadrados (width = height) com `p-0` — usar só com ícone, sem label.
+Para WCAG touch target (44px), usar `size="lg"` (`min-h-form-xl`).
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `color` | `"primary" \| "secondary" \| "critical" \| "success" \| "warning"` | `"primary"` | Cor/intenção semântica |
+| `variant` | `"filled" \| "outline" \| "soft" \| "ghost"` | `"filled"` | Estilo visual |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "icon-2xs" \| "icon-xs" \| "icon-sm" \| "icon-md" \| "icon-lg"` | `"md"` | Tamanho (prefixo `icon-` = quadrado, icon-only) |
+| `shape` | `"rounded" \| "pill"` | `"rounded"` | Forma — `pill` força `rounded-full` (override do radius da size) |
+| `fullWidth` | `boolean` | `false` | Ocupa 100% da largura do container |
+| `disabled` | `boolean` | `false` | Estado desabilitado |
+| `loading` | `boolean` | `false` | Mostra spinner e desabilita |
+| `iconLeft` | `ReactNode` | — | Ícone antes do texto |
+| `iconRight` | `ReactNode` | — | Ícone após o texto |
+| `className` | `string` | — | Override de classes (tw-merge resolve conflitos) |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Tipo HTML — default "button" para evitar submit acidental |
+
+## Fazer / Não fazer
+
+- Usar `color="critical"` para ações destrutivas (deletar, remover)
+- Usar `variant="ghost"` para ações de baixa prioridade
+- Usar `fullWidth` para CTAs em mobile ou modais
+- Máximo 1 botão `filled` por grupo de ações
+- Padrão de grupo: 1 filled + 1 ghost (ou outline)
+- Não usar `filled` para cancelar — usar `ghost`
+- Não usar `disabled` para esconder funcionalidade — apenas quando ação não está disponível
+- Não misturar `primary` e `critical` filled no mesmo grupo
+
+## Exemplo de uso
+
+```tsx
+import { Button } from "@/components/ui/Button";
+
+// Ação principal
+<Button color="primary" variant="filled">
+  Salvar
+</Button>
+
+// Ação secundária
+<Button color="primary" variant="ghost">
+  Cancelar
+</Button>
+
+// Ação destrutiva
+<Button color="critical" variant="filled" iconLeft={<TrashIcon />}>
+  Excluir
+</Button>
+
+// Ação neutra com loading
+<Button color="secondary" variant="outline" loading>
+  Processando...
+</Button>
+
+// Grupo de ações (padrão)
+<div className="flex gap-gp-md">
+  <Button color="primary" variant="ghost">Cancelar</Button>
+  <Button color="primary" variant="filled">Confirmar</Button>
+</div>
+
+// Botão full-width
+<Button color="primary" variant="filled" fullWidth>
+  Botão full-width
+</Button>
+```
+
+## Fonte de verdade
+
+- Estilos: `button.styles.ts` (tv())
+- Lógica: `button.tsx`
+- Tipos: `button.types.ts`

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

@@ -0,0 +1,162 @@
+# ButtonGroup — Guia de uso
+
+Componente composto **split button** — um botão principal + um chevron lateral compacto pra ações secundárias. Pattern típico: ação default + dropdown de variantes.
+
+> Não confundir com **toolbar/segmented control**. ButtonGroup hoje cobre **split button (2 slots)**. Pra agrupar 3+ botões em "linked toolbar" (Day/Week/Month), criar componente próprio futuro.
+
+---
+
+## Imports
+
+```tsx
+import { ButtonGroup } from "@/components/ui/ButtonGroup";
+```
+
+---
+
+## Quick start
+
+```tsx
+<ButtonGroup color="primary" variant="filled" size="md">
+  <ButtonGroup.Primary onClick={handlePrimary} iconLeft={<Save />}>
+    Salvar
+  </ButtonGroup.Primary>
+  <ButtonGroup.Chevron
+    onClick={openDropdown}
+    aria-label="Mais opções de salvamento"
+  />
+</ButtonGroup>
+```
+
+Visual:
+
+```
+┌────────────┬──┐
+│ 💾 Salvar  │ ⌄│
+└────────────┴──┘
+```
+
+---
+
+## Props
+
+### `<ButtonGroup>` (wrapper)
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `color` | `"primary" \| "secondary" \| "critical" \| "success" \| "warning"` | `"primary"` | Cor herdada do `<Button>`. Propaga aos slots via context. |
+| `variant` | `"filled" \| "outline" \| "soft" \| "ghost"` | `"filled"` | Estilo visual. Propaga aos slots. |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg"` | `"md"` | Altura. Propaga aos slots. **Icon sizes (`icon-*`) não suportados** — o Chevron já é icon-only quadrado, com dimensão derivada da size do group. |
+| `disabled` | `boolean` | `false` | Desabilita os 2 slots simultaneamente. Override individual permitido. |
+| `children` | `ReactNode` | — | `<ButtonGroup.Primary>` + `<ButtonGroup.Chevron>` |
+| `className` | `string` | — | Override do wrapper externo. |
+
+### `<ButtonGroup.Primary>` (slot principal)
+
+Aceita **todas as props do `<Button>`** exceto `shape` e `fullWidth`. Color/variant/size vêm do group por context — pode dar override passando explicitamente.
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `onClick` | `(e) => void` | — | Handler da ação principal. |
+| `iconLeft` / `iconRight` | `ReactNode` | — | Ícone inline. |
+| `loading` | `boolean` | `false` | Mostra spinner + desabilita. |
+| `disabled` | `boolean` | herda do group | Override individual. |
+| `color`/`variant`/`size` | — | herda do group | Override individual permitido. |
+
+### `<ButtonGroup.Chevron>` (slot secundário)
+
+Icon button **quadrado** (width = height) — espelha a size do Primary, como um "split" da mesma proporção: `2xs`→28×28, `xs`→32×32, `sm`→36×36, `md`→40×40 (`size-form-lg`), `lg`→44×44. Mesma dimensão de um icon button `icon-*` equivalente do Button. Renderiza `<ChevronDown />` por default.
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `onClick` | `(e) => void` | — | Handler do toggle (geralmente abre dropdown). |
+| `aria-label` | `string` | **obrigatório** | Descrição pro leitor de tela (icon-only). |
+| `icon` | `ReactNode` | `<ChevronDown />` | Customize se precisar (ex: `<MoreVertical />` pra kebab). |
+| `disabled` | `boolean` | herda do group | Override individual. |
+| `color`/`variant`/`size` | — | herda do group | Override permitido. |
+
+---
+
+## Exemplos
+
+### 1. Split button com dropdown
+
+```tsx
+import { useState } from "react";
+import { ButtonGroup } from "@/components/ui/ButtonGroup";
+import { Popover, PopoverTrigger, PopoverContent } from "@/components/shadcn/popover";
+
+function SaveSplit() {
+  const [open, setOpen] = useState(false);
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <ButtonGroup variant="filled">
+        <ButtonGroup.Primary onClick={() => save()}>
+          Salvar
+        </ButtonGroup.Primary>
+        <PopoverTrigger asChild>
+          <ButtonGroup.Chevron aria-label="Opções de salvamento" />
+        </PopoverTrigger>
+      </ButtonGroup>
+      <PopoverContent align="end">
+        <button onClick={() => saveAndClose()}>Salvar e fechar</button>
+        <button onClick={() => saveAsTemplate()}>Salvar como template</button>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+### 2. Variants
+
+```tsx
+{/* Outline secondary (estilo "Follow" do print) */}
+<ButtonGroup color="secondary" variant="outline" size="sm">
+  <ButtonGroup.Primary onClick={follow}>Follow</ButtonGroup.Primary>
+  <ButtonGroup.Chevron onClick={openMenu} aria-label="Mais ações" />
+</ButtonGroup>
+
+{/* Critical filled */}
+<ButtonGroup color="critical" variant="filled">
+  <ButtonGroup.Primary onClick={deleteItem}>Deletar</ButtonGroup.Primary>
+  <ButtonGroup.Chevron onClick={openMenu} aria-label="Outras opções de deletar" />
+</ButtonGroup>
+
+{/* Override individual: primary=brand, chevron=secondary */}
+<ButtonGroup variant="filled">
+  <ButtonGroup.Primary color="primary">Salvar</ButtonGroup.Primary>
+  <ButtonGroup.Chevron color="secondary" aria-label="Mais" />
+</ButtonGroup>
+```
+
+### 3. Disabled / loading
+
+```tsx
+{/* Group inteiro desabilitado */}
+<ButtonGroup disabled>
+  <ButtonGroup.Primary>Salvar</ButtonGroup.Primary>
+  <ButtonGroup.Chevron aria-label="..." />
+</ButtonGroup>
+
+{/* Só o primary disabled (chevron continua clicável) */}
+<ButtonGroup>
+  <ButtonGroup.Primary disabled>Salvar</ButtonGroup.Primary>
+  <ButtonGroup.Chevron aria-label="Outras opções" />
+</ButtonGroup>
+
+{/* Loading no primary */}
+<ButtonGroup>
+  <ButtonGroup.Primary loading>Salvando</ButtonGroup.Primary>
+  <ButtonGroup.Chevron aria-label="..." disabled />
+</ButtonGroup>
+```
+
+---
+
+## Gotchas
+
+- **`aria-label` é obrigatório** no `<ButtonGroup.Chevron>` — TypeScript reclama se omitir. Icon-only sem label viola WCAG 4.1.2.
+- **`shape="pill"` não funciona** com ButtonGroup — radius interno é forçado retangular pra encostar os 2 slots. Pra pill, use `<Button>` standalone.
+- **Icon sizes (`icon-*`)** não suportadas no group — o Chevron já é quadrado com dimensão derivada da size do group. Se quiser group "icon-only", use 2 `<Button>` standalone.
+- **Border duplicado entre slots** — colapsado via `-ml-px` no Chevron. Funciona em filled/soft/ghost. Em **outline**, o efeito visual pode ter 1px de overlap; teste no contexto antes de promover.
+- **Override de `size` em slot individual** quebra alinhamento vertical — passe `size` só no group, não nos slots.