@softize/opus 13.1.0 → 15.0.0

package/src/ui/docs/content/action-list.md

@@ -7,6 +7,9 @@ os filtros aplicados permanecem visíveis como chips removíveis.
 
 A barra se adapta ao espaço disponível. A busca cede largura primeiro e filtros que deixam de caber
 migram para o modal; a linha só quebra quando nenhum controle restante puder ceder espaço.
+`toolbarActions` acrescenta ações do consumidor ao fim da barra. Recarregar e exibição formam um
+`ButtonGroup` espaçado; as ações do consumidor vêm depois, com um intervalo maior para preservar a
+hierarquia entre ferramentas e a ação principal.
 
 ```tsx preview col
 render(
@@ -18,6 +21,20 @@ render(
 )
 ```
 
+Uma ação icon-only mantém o nome no tooltip e no `aria-label`:
+
+```tsx
+<ActionList
+  action={workspaceList}
+  input={{}}
+  toolbarActions={
+    <Button context="primary" size="icon" aria-label="Novo workspace">
+      <Plus />
+    </Button>
+  }
+/>
+```
+
 ## Barra de filtros compartilhada
 
 `ActionFilterBar` expõe a mesma linguagem declarativa de busca, filtros e período para
@@ -235,6 +252,19 @@ render(
 )
 ```
 
+## Propriedades de ActionFilterBar
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `action` | `Pick<ListAction, 'filters' \| 'text' \| 'periods'>` | | Declara busca, filtros e períodos disponíveis. |
+| `state` | `ActionFilterState` | | Estado atual da barra. |
+| `onStateChange` | `(next) => void` | | Recebe o estado completo depois de cada alteração. |
+| `filterOptions` | `Record<string, SelectOption[]>` | | Fornece opções de runtime para filtros select e lookup. |
+| `onRefresh` | `() => Promise<void> \| void` | | Exibe a ação de recarregar e executa a consulta do consumidor. |
+| `refreshing` | `boolean` | `false` | Desabilita e anima a ação de recarregar durante a consulta. |
+| `controls` | `ReactNode` | | Controles auxiliares agrupados com recarregar em um `ButtonGroup` espaçado. |
+| `actions` | `ReactNode` | | Ações do consumidor exibidas depois do grupo de controles, com um intervalo maior. |
+
 ## Declaração na ListAction
 
 | Chave | O que declara |
@@ -267,6 +297,9 @@ chamar a action.
 | `rowId` | `(item) => string` | `item.id` | Identidade da linha para seleção. |
 | `pageSize` | `number` | `50` | Itens por página padrão (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição. |
 | `state / onStateChange` | `ActionListState / (next) => void` | interno | Estado da toolbar controlado — para quem embala sincronizar com a URL. |
-| `emptyMessage` | `string` | `'Nenhum resultado.'` | O texto do estado vazio. |
+| `emptyMessage` | `string` | `'Nenhum resultado.'` | Frase do estado vazio (o `Empty` do `DataState`). |
+| `errorMessage` | `string` | `'Não foi possível carregar.'` | Título do aviso de erro; a ação de tentar de novo refaz a consulta. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Nome acessível e tooltip da ação de recuperação. |
 | `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar para o detalhe) — só na tabela. |
-| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita) — apresentação de quem chama, como `cells`; cliques ali não disparam o `onRowClick`. |
+| `toolbarActions` | `ReactNode` | | Ações do consumidor no fim da barra, separadas do grupo de controles. |
+| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita), agrupadas automaticamente com intervalo compacto; cliques ali não disparam o `onRowClick`. |

package/src/ui/docs/content/action-trigger.md

@@ -37,9 +37,10 @@ confirm: {
 
 ## Ação somente com ícone
 
-Com `icon`, o botão exibe somente o ícone e usa `label`, ou `action.label`, no tooltip e no nome
-acessível. O clique não aciona o item clicável ao redor. `itemLabel` identifica o registro na
-mensagem de confirmação.
+Com `icon`, o botão exibe somente o ícone no quadrado `icon-xs` da escala (1.5rem, a ação que mora
+dentro de uma linha ou card) e usa `label`, ou `action.label`, no tooltip e no nome acessível. Uma
+composição que peça mais presença, como a barra do `PageHeader`, declara `size="icon-sm"`. O clique
+não aciona o item clicável ao redor. `itemLabel` identifica o registro na mensagem de confirmação.
 
 ```tsx
 <ActionTrigger
@@ -83,4 +84,4 @@ um atalho, um arrastar, um item de menu.
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
 | `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza para o item. |
 | `itemLabel` | `string` | | Nome do alvo na pergunta (sai entre aspas, em destaque, antes da mensagem do contrato). |
-| `className` | `string` | | Classes do botão (ex.: apertar o tamanho em uma linha densa). |
+| `className` | `string` | | Classes do botão. O tamanho vem de `size` (escala única); com `icon`, o default é `icon-xs`. |

package/src/ui/docs/content/action-view.md

@@ -21,7 +21,7 @@ render(
             <div className="space-y-1.5">
               <div className="flex items-center gap-2">
                 <h3 className="text-sm font-semibold">{ws.name}</h3>
-                <Badge variant={ws.status === 'active' ? 'success' : 'warning'}>{ws.status}</Badge>
+                <Badge context={ws.status === 'active' ? 'success' : 'warning'}>{ws.status}</Badge>
               </div>
               <p className="text-sm text-muted-foreground">
                 Cliente {ws.client} · {ws.agents} agentes vinculados.
@@ -50,5 +50,6 @@ mais de uma região da tela ou quando o carregamento precisa ser orquestrado por
 | `children` | `(data: TData, refetch) => ReactNode` | | Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
 | `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. |
 | `loading` | `ReactNode \| boolean` | `3 skeletons` | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega. |
-| `empty` | `ReactNode` | `nada` | Sobrescreve o estado vazio (200 sem dado). |
+| `empty` | `ReactNode` | `emptyMessage` ou nada | Sobrescreve o estado vazio (200 sem dado). |
+| `emptyMessage` | `string` | | Atalho do vazio: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida). |
 | `error` | `(err, retry) => ReactNode` | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |

package/src/ui/docs/content/alert.md

@@ -54,6 +54,11 @@ Quando a mensagem precisa de conteúdo rico, componha os slots da família. `Ale
 `AlertDescription` pertencem ao header. As ações ficam no fim lógico da superfície e centralizadas
 verticalmente na mesma linha do conteúdo — a mesma posição usada pelas ações do Toast.
 
+Use `ghost` como tratamento padrão para ações dentro do alert: a mensagem já fornece a superfície e
+o botão não precisa desenhar outra moldura. Mantenha texto quando a ação expressa um resultado
+específico. Para tentar novamente, recarregar ou repetir a operação descrita pelo aviso, prefira um
+botão só com ícone, nome acessível e tooltip.
+
 ```tsx preview col
 <Alert context="danger">
   <AlertMedia>
@@ -67,9 +72,16 @@ verticalmente na mesma linha do conteúdo — a mesma posição usada pelas aç
     </AlertDescription>
   </AlertHeader>
   <AlertActions>
-    <Button size="sm">
-      Tentar novamente
-    </Button>
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="ghost" size="icon" aria-label="Tentar novamente">
+            <RefreshCw />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>Tentar novamente</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
   </AlertActions>
 </Alert>
 ```
@@ -83,7 +95,7 @@ ação.
   title="Sessão presa"
   description="O ambiente não subiu no tempo esperado."
 >
-  <Button size="sm">
+  <Button variant="ghost">
     Reiniciar
   </Button>
 </Alert>

package/src/ui/docs/content/avatar.md

@@ -28,10 +28,14 @@ para agente.
 
 ## Tamanhos
 
-size sm/default/lg — o fallback acompanha o tamanho. sm para listas densas, lg para cabeçalho de
-workspace.
+`size` usa a escala única dos controles: o avatar de uma linha mede o mesmo que o controle ao lado
+(`sm` 2rem, `default` 2.25rem, `lg` 2.5rem); `xs` (1.5rem) é a lista densa. O fallback e o selo
+acompanham o tamanho.
 
 ```tsx preview
+<Avatar size="xs">
+  <AvatarFallback>AL</AvatarFallback>
+</Avatar>
 <Avatar size="sm">
   <AvatarFallback>AL</AvatarFallback>
 </Avatar>
@@ -86,7 +90,7 @@ excedente — os membros do workspace Empresa X.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato; o fallback e o selo acompanham a escala. |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato na escala única dos controles (1.5 · 2 · 2.25 · 2.5rem); o fallback e o selo acompanham. |
 
 ## Propriedades de AvatarImage
 

package/src/ui/docs/content/button.md

@@ -2,8 +2,7 @@
 
 `context` declara a hierarquia ou o risco da ação; `variant` escolhe o tratamento visual. Use
 `primary` para a ação principal, `neutral` para ações de apoio e `danger` quando a ação tiver uma
-consequência perigosa. `default`, `secondary` e `destructive` permanecem apenas como aliases de
-compatibilidade.
+consequência perigosa.
 
 ```tsx preview
 <Button>Criar workspace</Button>
@@ -16,28 +15,45 @@ compatibilidade.
 
 ## Tamanhos
 
-O tamanho icon exige `aria-label`, porque não há texto visível. Os botões só-ícone vêm em três tamanhos: `icon` (2.25rem), `icon-sm` (2rem, para uma fileira densa como o cabeçalho) e `icon-xs` (1.5rem, para uma ação dentro de um campo, como o `trailing` de Input ou Select).
+`size` usa a escala única dos controles: o mesmo nome tem a mesma medida em `Button`, `Select`,
+`Tabs`, `Toggle`, `Switch`, `Avatar`, `Spinner` e nos botões embutidos. Os tamanhos de texto dão a
+altura da linha; os `icon-*` são quadrados para botões só de ícone, que exigem `aria-label` porque não
+há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em `xs` e `sm`, 1rem em
+`default`, 1.25rem em `lg`), a menos que o ícone traga um `size-*` próprio.
+
+| Nome | Medida | Uso |
+|---|---|---|
+| `xs` | 1.5rem | Ação dentro de um campo (`InputGroupButton`). |
+| `sm` | 2rem | Toolbar e cabeçalho densos, ao lado de `Select` e `Tabs` `sm`. |
+| `default` | 2.25rem | A linha padrão, a mesma de `Input`. |
+| `lg` | 2.5rem | Chamada principal com mais área de toque. |
+| `icon-xs` | 1.5rem | Ação só de ícone dentro de um campo ou de uma linha densa; é o quadrado de `ActionTrigger` com `icon`. |
+| `icon-sm` | 1.75rem | Ação só de ícone em composições compactas que precisam de mais presença; também é o quadrado das setas do pager de `ActionList`. |
+| `icon` | 2.25rem | Ação só de ícone na linha padrão. |
+| `icon-lg` | 2.5rem | Ação só de ícone ao lado de um `lg`. |
 
 ```tsx preview
+<Button size="xs">Mínimo</Button>
 <Button size="sm">Pequeno</Button>
 <Button>Padrão</Button>
 <Button size="lg">Grande</Button>
-<Button size="icon" aria-label="Novo"><Plus /></Button>
-<Button size="icon-sm" variant="ghost" aria-label="Novo"><Plus /></Button>
 <Button size="icon-xs" variant="ghost" aria-label="Novo"><Plus /></Button>
+<Button size="icon-sm" variant="ghost" aria-label="Novo"><Plus /></Button>
+<Button size="icon" aria-label="Novo"><Plus /></Button>
+<Button size="icon-lg" aria-label="Novo"><Plus /></Button>
 ```
 
 ## Estados
 
-busy = ação em andamento (DEPOIS do clique): o Spinner e o disabled vêm do botão. Com icon, o
-Spinner TROCA o ícone (não soma). Não confunda com carregar conteúdo (ANTES) — isso é Spinner
-centralizado/Skeleton em um nível de página.
+busy = ação em andamento (DEPOIS do clique): o Spinner e o disabled vêm do botão. `icon` recebe o
+elemento do ícone e o dimensiona pelo `size`; com icon, o Spinner TROCA o ícone (não soma). Não
+confunda com carregar conteúdo (ANTES) — isso é `DataState` ou `Skeleton` em um nível de página.
 
 ```tsx preview
 <Button disabled>Desabilitado</Button>
 <Button busy>Salvando…</Button>
-<Button icon={Plus}>Novo</Button>
-<Button icon={Plus} busy>Novo</Button>
+<Button icon={<Plus />}>Novo</Button>
+<Button icon={<Plus />} busy>Novo</Button>
 ```
 
 ## Como outro elemento (asChild)
@@ -57,16 +73,16 @@ buttonVariants serve para o caso sem filho único.
 |---|---|---|---|
 | `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | A hierarquia ou o risco comunicado pela ação. |
 | `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'solid'` | O tratamento visual aplicado ao contexto. |
-| `size` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | O tamanho. Os icon* são quadrados (2.25/2/1.5rem) para botões só de ícone, com `aria-label`. |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'default'` | A medida na escala única dos controles (tabela acima). Os `icon-*` são quadrados para botões só de ícone, com `aria-label`. |
 | `asChild` | `boolean` | `false` | Renderiza como o filho (Radix Slot) em vez de `<button>` — para âncoras e afins. |
 | `busy` | `boolean` | `false` | Ação em andamento (depois do clique): mostra Spinner + desabilita. Não é "carregando" de conteúdo (que é Spinner/Skeleton em um nível de página). |
-| `icon` | `React.ElementType` | | Ícone à esquerda (ex.: icon={Plus}). No busy é trocado pelo Spinner — não soma. |
+| `icon` | `React.ReactNode` | | Ícone à esquerda, como nó (ex.: `icon={<Plus />}`); o glifo segue o `size`. No busy é trocado pelo Spinner — não soma. |
 
 ## ButtonGroup
 
-Use `ButtonGroup` quando ações relacionadas precisarem formar um bloco contínuo. As bordas internas
-colapsam e somente as pontas externas permanecem arredondadas. Mantenha a mesma variante nos filhos
-para preservar a unidade visual.
+Use `ButtonGroup` para manter ações relacionadas juntas. No modo `connected`, que permanece como
+padrão, as bordas internas colapsam e somente as pontas externas ficam arredondadas. Mantenha a
+mesma variante nos filhos para preservar a unidade visual.
 
 ```tsx preview
 <ButtonGroup>
@@ -76,6 +92,20 @@ para preservar a unidade visual.
 </ButtonGroup>
 ```
 
+### Ações espaçadas
+
+Use `mode="spaced"` quando os controles pertencem ao mesmo conjunto, mas cada um precisa preservar
+sua própria forma e superfície de hover. O grupo aplica o intervalo compacto de `0.25rem` sem
+conectar bordas. Esse modo atende ações icon-only em barras e linhas de listagem.
+
+```tsx preview
+<ButtonGroup mode="spaced">
+  <Button variant="ghost" size="icon" aria-label="Recarregar"><RotateCw /></Button>
+  <Button variant="ghost" size="icon" aria-label="Exibição"><SlidersHorizontal /></Button>
+  <Button context="primary" size="icon" aria-label="Novo item"><Plus /></Button>
+</ButtonGroup>
+```
+
 ### Ação dividida
 
 Combine a ação principal, um separador e um botão de ícone quando o mesmo comando oferecer
@@ -83,7 +113,7 @@ variações.
 
 ```tsx preview
 <ButtonGroup>
-  <Button icon={Play}>Rodar agente developer</Button>
+  <Button icon={<Play />}>Rodar agente developer</Button>
   <ButtonGroupSeparator />
   <Button size="icon" aria-label="Mais opções">
     <ChevronDown />
@@ -102,7 +132,7 @@ semântica de outro elemento, como `label`.
     <GitBranch />
     empresa-x-api
   </ButtonGroupText>
-  <Button variant="outline" icon={RotateCw}>Sincronizar</Button>
+  <Button variant="outline" icon={<RotateCw />}>Sincronizar</Button>
 </ButtonGroup>
 ```
 
@@ -123,6 +153,7 @@ semântica de outro elemento, como `label`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do bloco e do colapso das bordas. |
+| `mode` | `'connected' \| 'spaced'` | `'connected'` | Conecta as bordas dos controles ou preserva cada controle com intervalo compacto. |
 | `shape` | `'default' \| 'pill'` | `'default'` | Geometria das extremidades externas do grupo. |
 
 ### Propriedades de ButtonGroupSeparator

package/src/ui/docs/content/communication.md

@@ -50,6 +50,42 @@ frase. Não copie as regras da Base para cá.
 | placeholder de campo ou busca | `placeholder` |
 | `Select.emptyText` e grupos de opção | `empty-state` e `heading` |
 | confirmação local do `ActionTrigger` | `title`, `dialog-body` e `button` |
+| `dialog.alert/confirm/prompt/choose` — `title`, `description`/`body`, `action`/`cancel`, `actions[].label` | `title`, `dialog-body`, `button` (e `placeholder` no `prompt`) |
+| filhos de `TooltipContent` | `label` |
+| `LabelHelp.help` | `helper-text` |
+| `emptyMessage`, `errorMessage`, `retryLabel` de `DataState`, `PageState`, `ActionList`, `ActionListDialog` e `ActionView` | `empty-state`, `error`, `button` |
+
+O tooltip entra como `label` porque nomeia um controle icon-only: é um fragmento curto, sem
+ponto final, e a Base não define um papel próprio para tooltip. Texto de ajuda que precisa de
+frase completa pertence ao `help` de um campo (contrato ou `LabelHelp`), não ao tooltip.
+
+## Alcance do inventário além das props
+
+Quem vê o gate reprovar ou precisa de uma dispensa deve saber o que o extrator alcança sem
+declaração adicional:
+
+- **Diálogos imperativos.** `dialog.confirm({ title, description, action })` e as demais
+  respostas (`alert`, `prompt`, `choose`) entram no inventário como se fossem props de um
+  `ActionFormDialog`; o campo do diagnóstico é `dialog.confirm().title`,
+  `dialog.choose().actions[0].label` etc. Constantes locais resolvem normalmente. Uma função
+  que devolve template (`description: describe(nome)`) gera o diagnóstico `content` habitual e
+  se declara em `copy.dynamic` como `message-template`. Opções construídas em tempo de execução
+  ou mutadas depois de declaradas reprovam como estrutura, porque nenhum texto pode ser
+  atribuído a elas.
+- **`LabelHelp` como filho.** `<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>` inventaria
+  `Nome` como label e a ajuda como helper-text; o ícone não torna o label opaco. Um wrapper
+  local com o mesmo nome continua opaco, porque o extrator não infere o que ele renderiza.
+- **Rótulos em array literal local.** Quando um componente mapeado lê `item.label` (ou a chave
+  destruturada) dentro de `map`, `forEach`, `filter` ou `for…of` sobre um array literal do
+  mesmo arquivo, cada literal do array vira um texto na linha em que foi escrito, em vez de um
+  diagnóstico sobre a prop. `filter`, `slice`, `toSorted` e `toReversed` podem ficar entre o
+  array e a iteração. O limite é deliberado: o array precisa ser literal e declarado no mesmo
+  arquivo; o elemento só pode ser lido (`item.chave`), nunca passado adiante, espalhado ou
+  atribuído; o callback não pode receber o próprio array como terceiro parâmetro; e nenhum
+  elemento pode ter a chave dinâmica. Arrays importados, derivados por spread ou por
+  concatenação continuam gerando o diagnóstico da prop.
+- **Elementos JSX genéricos.** `<ActionList<Input, Row> emptyMessage="…">` extrai igual a
+  `<ActionList emptyMessage="…">`.
 
 Copy visual e nome acessível são superfícies cumulativas. Um `aria-label` estático nomeia
 um controle icon-only, mas não torna aceitável nem invisível ao gate um texto visual opaco.

package/src/ui/docs/content/content.md

@@ -22,7 +22,8 @@ render(
 
 Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
 `ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
-uma descrição, um metadado e uma região de ações.
+uma descrição, um contador (`ContentMeta`) e uma região de ações. O contador é próprio de
+`Content`; `PageHeader` reconhece somente título, descrição e ações.
 
 ```tsx preview col
 render(
@@ -48,12 +49,12 @@ do pai correto, filhos estruturais indiretos e a mistura de shorthand com compos
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `title` | `ReactNode` | | Forma curta: título da região (vira o heading ligado à `section`). |
-| `meta` | `ReactNode` | | Forma curta: complemento ao lado do título, como uma contagem. |
+| `count` | `number` | | Forma curta: total de itens ao lado do título da região. |
 | `description` | `ReactNode` | | Forma curta: frase de apoio sob o título. |
 | `actions` | `ReactNode` | | Forma curta: ações alinhadas à direita do header. |
 | `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | herdado | Nível semântico do heading, independente do destaque visual. |
-| `variant` | `'page' \| 'section'` | `'section'` | Hierarquia visual; `page` permanece só por compatibilidade da série 12. |
+| `variant` | `'page' \| 'section'` | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície. |
 
 Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e
 `ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`
-próprios — a hierarquia é declarada em `Content`.
+próprios — a hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.

package/src/ui/docs/content/data-state.md

@@ -1,19 +1,21 @@
 ## Estados
 
-Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta. O
-carregamento usa `Spinner`; o vazio preserva uma moldura sólida; e o erro apresenta uma mensagem
-segura, sem expor detalhes técnicos. Para uma ação em andamento depois do clique, use `busy` em
-`Button`.
+Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta. As
+superfícies são as mesmas de `PageState`, na escala de uma seção: o carregamento é um contêiner
+`role="status"` com o `Spinner`; o vazio compõe `Empty` com moldura sólida e `emptyMessage` como
+título; o erro é um `Alert` de contexto `danger` com uma mensagem segura, sem expor detalhes
+técnicos, e uma ação `ghost` só com ícone quando há `onRetry`. `retryLabel` fornece o nome acessível
+e o tooltip dessa ação. Para uma ação em andamento depois do clique, use `busy` em `Button`.
 
 ```tsx preview col
 <div className="w-full space-y-3">
   <DataState loading>
     <div />
   </DataState>
-  <DataState empty emptyText="Nenhum papel.">
+  <DataState empty emptyMessage="Nenhum papel.">
     <div />
   </DataState>
-  <DataState error={{ message: 'detalhe técnico fica no console' }}>
+  <DataState error={{ message: 'detalhe técnico fica no console' }} onRetry={() => undefined}>
     <div />
   </DataState>
 </div>
@@ -22,13 +24,13 @@ segura, sem expor detalhes técnicos. Para uma ação em andamento depois do cli
 ## Dentro de uma tabela
 
 Em uma tabela já emoldurada, passe `colSpan` para ocupar uma linha inteira dentro de `<tbody>`. A
-tabela continua responsável pela borda, evitando uma segunda moldura no estado vazio. Para uma
-região disponível para criação ou vínculo, use `Empty`.
+tabela continua responsável pela borda: o `Empty` dentro dela vem sem moldura. Para uma região
+disponível para criação ou vínculo, use `Empty` diretamente, com a moldura tracejada.
 
 ```tsx preview col
 <table className="w-full overflow-hidden rounded-lg border border-border text-sm">
   <tbody>
-    <DataState empty emptyText="Nenhum usuário." colSpan={3}>
+    <DataState empty emptyMessage="Nenhum usuário." colSpan={3}>
       <tr>
         <td />
       </tr>
@@ -42,8 +44,10 @@ região disponível para criação ou vínculo, use `Empty`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `loading` | `boolean` | | Carregando (antes do conteúdo) — mostra o Spinner centralizado. |
-| `empty` | `boolean` | | Sem itens — mostra o emptyText. |
-| `emptyText` | `string` | | Texto do vazio (pt-BR, ex.: "Nenhum papel."). |
-| `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica não vai para tela (use errorText). |
-| `errorText` | `string` | `'Não foi possível carregar.'` | Aviso de erro, orientado ao usuário. |
+| `empty` | `boolean` | | Sem itens — compõe `Empty` com o `emptyMessage`. |
+| `emptyMessage` | `string` | `'Nada por aqui.'` | Frase do vazio (ex.: "Nenhum papel."). |
+| `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica não vai para tela (use `errorMessage`). |
+| `errorMessage` | `string` | `'Não foi possível carregar.'` | Título do aviso de erro, orientado à pessoa. |
+| `onRetry` | `() => void \| Promise<void>` | | Recuperação: mostra a ação de tentar de novo somente com ícone no estado de erro. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Nome acessível e tooltip da ação de recuperação. |
 | `colSpan` | `number` | | Em tabela: renderiza o estado como `<tr><td colSpan>` (cabe direto no tbody). |

package/src/ui/docs/content/dialog.md

@@ -305,7 +305,7 @@ avançada; ele recebe `children` e `container` conforme o portal do Radix.
 ## Propriedades de DialogHost
 
 `DialogHost` não recebe propriedades. Monte uma instância no shell para atender toda a API
-imperativa. `ConfirmHost` permanece como alias de migração.
+imperativa.
 
 ## Opções de dialog.alert
 
@@ -363,6 +363,3 @@ imperativa. `ConfirmHost` permanece como alias de migração.
 | `context` | `ButtonContext` | Última ação: `primary`; demais: `neutral` | Define o significado semântico. |
 | `variant` | `ButtonVariant` | Última ação: `solid`; demais: `ghost` | Define o tratamento visual. |
 | `disabled` | `boolean` | `false` | Impede a escolha desta ação. |
-
-`confirm()` e `ConfirmHost` continuam disponíveis apenas como aliases de migração para
-`dialog.confirm()` e `DialogHost`.

package/src/ui/docs/content/input.md

@@ -166,7 +166,7 @@ Com `InputGroupTextarea`, um addon em `block-end` forma uma região de ações a
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | Tamanho do botão embutido; as variantes `icon-*` são quadradas. |
+| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | O subconjunto da escala única que cabe num campo (1.5 · 2 · 1.5 · 1.75rem); os `icon-*` são quadrados. |
 | `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | Contexto semântico herdado de Button. |
 | `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'` | Tratamento visual; use `solid` quando a ação precisar de ênfase. |
 

package/src/ui/docs/content/item.md

@@ -105,7 +105,7 @@ usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha: transparente, com borda ou levemente tingido. |
-| `size` | `'default' \| 'sm'` | `'default'` | O respiro interno; `sm` atende listas densas. |
+| `size` | `'default' \| 'sm'` | `'default'` | O respiro interno, com os nomes da escala única; `sm` atende listas densas. |
 | `asChild` | `boolean` | `false` | Funde o Item no filho para que a linha inteira assuma sua semântica. |
 
 ## Propriedades de ItemGroup