@softize/opus 13.1.0 → 14.0.0

package/src/ui/components/primitives/tabs.tsx

@@ -3,11 +3,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { Tabs as TabsPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { controlHeight, type ControlSize } from './control.ts'
 
 // Divergência da casa (ejetado): o Tabs ganhou `size` — Button e Select têm `sm`, o Tabs
 // não tinha, e uma fileira densa ficava com o segmento 0.25rem mais alto
-// que os irmãos. O tamanho flui pra TabsList via contexto (a altura é dela).
-type TabsSize = "default" | "sm"
+// que os irmãos. O tamanho flui pra TabsList via contexto (a altura é dela) e a medida é a
+// da escala de control.ts.
+type TabsSize = Extract<ControlSize, "default" | "sm">
 const TabsSizeContext = React.createContext<TabsSize>("default")
 
 function Tabs({
@@ -64,7 +66,7 @@ function TabsList({
       data-slot="tabs-list"
       data-variant={variant}
       data-size={size}
-      className={cn(tabsListVariants({ variant }), size === "sm" ? "h-8" : "h-9", className)}
+      className={cn(tabsListVariants({ variant }), controlHeight[size], className)}
       {...props}
     />
   )

package/src/ui/components/primitives/toggle.tsx

@@ -3,9 +3,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { Toggle as TogglePrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { controlHeight, focusRing } from './control.ts'
 
 const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground dark:aria-invalid:ring-context-danger/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  [
+    "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground dark:aria-invalid:ring-context-danger/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+    focusRing,
+  ],
   {
     variants: {
       variant: {
@@ -13,10 +17,11 @@ const toggleVariants = cva(
         outline:
           "border border-input bg-transparent hover:bg-accent hover:text-accent-foreground",
       },
+      // Alturas da escala de control.ts (`sm` = o mesmo h-8 de Button e Select).
       size: {
-        default: "h-9 min-w-9 px-2",
-        sm: "h-8 min-w-8 px-1.5",
-        lg: "h-10 min-w-10 px-2.5",
+        default: `${controlHeight.default} min-w-9 px-2`,
+        sm: `${controlHeight.sm} min-w-8 px-1.5`,
+        lg: `${controlHeight.lg} min-w-10 px-2.5`,
       },
       shape: {
         default: '',

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

@@ -88,6 +88,32 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | `options` | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum. |
 | `className` | `string` | Classes do invólucro (ex.: `col-span-2` em uma grid). |
 
+## Ajuda na label
+
+`FieldSpec.help` aparece como um ícone junto à label, com o texto num tooltip. Escreva ali o
+critério, o efeito ou a limitação que a label não diz; ajuda que só repete a label deve ser omitida.
+Não existe texto auxiliar sob o campo: quem precisa de uma frase permanente abaixo do controle usa
+`FieldDescription` na composição própria.
+
+`LabelHelp` é esse mesmo ícone, exportado para um formulário sem contrato mostrar a ajuda no mesmo
+lugar:
+
+```tsx preview col md
+<Field>
+  <FieldLabel htmlFor="staff" className="items-center gap-1.5">
+    <span>Staff</span>
+    <LabelHelp help="Tem acesso ao back-office e a todos os workspaces." />
+  </FieldLabel>
+  <Input id="staff" placeholder="Empresa X" />
+</Field>
+```
+
+### Propriedades de LabelHelp
+
+| Propriedade | Tipo | Descrição |
+|---|---|---|
+| `help` | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
+
 ## Origem das opções de seleção
 
 As opções seguem esta precedência: `options` no campo, `fieldOptions` no formulário, `options` no

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

@@ -23,7 +23,7 @@ render(
           <Plus /> Workspace
         </Button>
       }
-      emptyText="Nenhum workspace."
+      emptyMessage="Nenhum workspace."
     >
       {(workspaces) => (
         <div className="space-y-2">
@@ -69,5 +69,5 @@ corpo do modal.
 | `actions` | `ReactNode` | | Ação à direita da toolbar — em geral o botão de criar. |
 | `empty` | `(items) => boolean` | `items.length === 0` | Sobrepõe o vazio derivado. |
 | `loading` | `boolean` | | Carga extra agregada à do fetch (query irmã). |
-| `emptyText / errorText` | `string` | | Textos dos estados (DataState). |
+| `emptyMessage / errorMessage / retryLabel` | `string` | | Textos dos estados, repassados ao `ActionList` (e dele ao `DataState`). |
 | `className` | `string` | `sm:max-w-3xl` | Largura do DialogContent. |

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

@@ -267,6 +267,8 @@ 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; o botão de tentar de novo refaz a consulta. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botã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`. |

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

@@ -37,9 +37,9 @@ 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-sm` da escala (1.75rem, a ação que mora
+dentro de uma linha ou card) 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.
 
 ```tsx
 <ActionTrigger
@@ -83,4 +83,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` é sempre `icon-sm`. |

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/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, como o `trailing` de Input ou Select. |
+| `icon-sm` | 1.75rem | Ação só de ícone dentro de uma linha ou card; é o quadrado de `ActionTrigger` com `icon` e 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,10 +73,10 @@ 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
 
@@ -83,7 +99,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 +118,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>
 ```
 

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 — a mesma anatomia de `PageHeader`,
+com os mesmos slots e o mesmo layout; só o nível do heading e a hierarquia visual mudam.
 
 ```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 — o mesmo `count` de `Page`. |
 | `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 o botão de recuperação quando há `onRetry`. 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 o botão de tentar de novo no estado de erro. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botã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

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

@@ -8,7 +8,9 @@ contexto. O container é centralizado e ocupa a largura disponível até `80rem`
 abaixo do cabeçalho permanece livre para tabelas, cards ou outras composições.
 
 A forma curta é o padrão para páginas comuns. Ela cria internamente `PageHeader` e `PageBody`;
-portanto, não produz uma estrutura visual ou semântica diferente da forma explícita.
+portanto, não produz uma estrutura visual ou semântica diferente da forma explícita. O cabeçalho é a
+mesma anatomia de `Content` (título, contador, descrição e ações): o que muda entre os dois é o nível
+do heading e a hierarquia visual.
 
 `Page` é o esqueleto de páginas e recursos delimitados. Ele também pode ocupar o painel principal
 de um shell com sidebar; a navegação lateral não exige remover o teto nem reconstruir o cabeçalho.
@@ -90,8 +92,10 @@ altura e semântica acessível consistentes.
 </Page>
 ```
 
-`loading` centraliza o `Spinner`; `error` compõe `Alert`; `empty` compõe `Empty`; e `ready` entrega
-os filhos sem acrescentar uma superfície.
+`loading` centraliza o `Spinner` num contêiner `role="status"`; `error` compõe `Alert` com o botão
+de recuperação quando há `onRetry`; `empty` compõe `Empty`; e `ready` entrega os filhos sem
+acrescentar uma superfície. São as mesmas superfícies de `DataState`, na escala da página: `title`
+e `description` nomeiam a situação e, sem `title`, valem `errorMessage` e `emptyMessage`.
 
 ```tsx preview col
 <Page title="Relatórios">
@@ -126,5 +130,9 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | `title` | `ReactNode` | Texto seguro por estado | Situação reconhecível pela pessoa. |
 | `description` | `ReactNode` | | Impacto ou próximo passo aplicável. |
 | `icon` | `ReactNode` | Alerta no erro | Ícone decorativo do estado. |
-| `action` | `ReactNode` | | Recuperação, seleção ou criação aplicável. |
+| `action` | `ReactNode` | | Seleção ou criação aplicável ao estado. |
+| `emptyMessage` | `string` | `'Nada por aqui'` | Título do vazio quando `title` não é informado. |
+| `errorMessage` | `string` | `'Não foi possível carregar esta página'` | Título do erro quando `title` não é informado. |
+| `onRetry` | `() => void \| Promise<void>` | | Recuperação do erro: acrescenta o botão de tentar de novo ao lado de `action`. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botão de recuperação. |
 | `children` | `ReactNode` | | Conteúdo renderizado somente em `ready`. |

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

@@ -29,21 +29,21 @@ rodapé.
 
 ## Números longos
 
-A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, ajuste por
-`className` (`h-7 min-w-7 text-xs` nos números; `size-7` mais `iconClassName="size-3.5"` nas
-setas com `iconOnly`).
+A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, as setas e a
+elipse usam `size="icon-sm"` (o quadrado de 1.75rem da escala única, com o glifo de 0.875rem); os
+números, que não têm um degrau de 1.75rem na escala, ajustam por `className` (`h-7 min-w-7 text-xs`).
 
 ```tsx preview
 <Pagination>
   <PaginationContent className="gap-0.5">
     <PaginationItem>
-      <PaginationPrevious href="#" iconOnly className="size-7" iconClassName="size-3.5" />
+      <PaginationPrevious href="#" iconOnly size="icon-sm" />
     </PaginationItem>
     <PaginationItem>
       <PaginationLink href="#" page={1} className="h-7 min-w-7 text-xs" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationEllipsis className="size-7" />
+      <PaginationEllipsis size="icon-sm" />
     </PaginationItem>
     <PaginationItem>
       <PaginationLink href="#" page={5726} className="h-7 min-w-7 text-xs" />
@@ -52,7 +52,7 @@ setas com `iconOnly`).
       <PaginationLink href="#" page={5727} isActive className="h-7 min-w-7 text-xs" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationNext href="#" iconOnly className="size-7" iconClassName="size-3.5" />
+      <PaginationNext href="#" iconOnly size="icon-sm" />
     </PaginationItem>
   </PaginationContent>
 </Pagination>
@@ -61,7 +61,8 @@ setas com `iconOnly`).
 ## Com elipse
 
 `PaginationEllipsis` marca, de forma decorativa e com `aria-hidden`, uma sequência de páginas que
-não cabe na barra.
+não cabe na barra. `size` aceita os quadrados da escala (`icon-xs`, `icon-sm`, `icon`, `icon-lg`) para
+parear com as setas.
 
 ```tsx preview
 <Pagination>
@@ -130,7 +131,7 @@ render(
 | `page` | `number` | | Número usado como conteúdo, quando `children` não é informado, e no nome acessível “Página N”. |
 | `isActive` | `boolean` | `false` | Marca a página atual com `aria-current="page"` e tratamento `outline`. |
 | `href` | `string` | | Renderiza um `<a>`. Sem `href`, o componente usa `<button>` e aceita `onClick` e `disabled`. |
-| `size` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | Escala herdada de `Button`. A largura mínima cresce para acomodar números longos. |
+| `size` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. A largura mínima cresce para acomodar números longos; os `icon-*` são quadrados. |
 
 ## Propriedades de PaginationPrevious e PaginationNext
 
@@ -138,4 +139,5 @@ render(
 |---|---|---|---|
 | `label` | `string` | `'Página anterior'` ou `'Próxima página'` | Nome acessível e texto visível da ação. |
 | `iconOnly` | `boolean` | `false` | Exibe somente a seta; `label` continua disponível para leitura assistiva. |
-| `iconClassName` | `string` | | Classes aplicadas ao ícone da seta. |
+| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. |
+| `iconClassName` | `string` | | Classes aplicadas ao ícone da seta, quando o glifo da escala não servir. |

package/src/ui/docs/content/semantic-context.md

@@ -59,5 +59,6 @@ const status = t.dict(
 
 ## Compatibilidade
 
-`tone` em dicionários e variantes semânticas antigas continuam aceitos durante a migração. Código
-novo usa `context`; não misture o contrato antigo e o novo na mesma ocorrência.
+`tone` em dicionários continua aceito durante a migração; código novo usa `context`. As variantes
+semânticas antigas dos componentes (`default`, `secondary`, `destructive`, `success`, `warning`,
+`info`) saíram na 14.0.0: `variant` só descreve tratamento visual e o significado é sempre `context`.

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

@@ -61,7 +61,7 @@ uma sidebar fixa, redimensionável ou recolhida.
 | `PaneHeader` | Mantém identidade, contexto ou ações no topo. |
 | `PaneBody` | Ocupa o espaço restante e concentra a rolagem vertical. |
 | `PaneFooter` | Mantém ações persistentes no rodapé. |
-| `SidebarNav` ou `ShellNav` | Apresenta e controla os destinos de navegação. |
+| `SidebarNav` | Apresenta e controla os destinos de navegação. |
 
 `PaneContent` permanece como alias temporário de `PaneBody` durante a versão 12. Código novo usa
 `PaneBody`.
@@ -134,26 +134,9 @@ render(
 Esse é o padrão usado pelo `DocBrowser`: seções são rótulos, grupos nomeados são nós expansíveis e
 páginas são folhas. Um grupo começa aberto e volta a abrir quando contém a página ativa.
 
-`ShellNav` continua disponível para uma navegação plana com cabeçalho próprio e grupos ancorados no
-rodapé, mas está descontinuado: código novo usa `SidebarNav`, que cobre o mesmo caso integrado à
-`Sidebar`. Ele gerencia a rolagem internamente e se adapta quando estiver dentro de uma `Sidebar`
-recolhida.
-
-```tsx
-<Sidebar collapsed={collapsed}>
-  <ShellNav
-    heading={<ShellNavHeading title="Relatórios" action={<CreateReportButton />} />}
-    groups={reportGroups}
-    footer={settingsGroups}
-    activeId={activeId}
-    onSelect={navigateToReport}
-  />
-</Sidebar>
-```
-
 ## Recolher a coluna
 
-`collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem`, `SidebarNav` e `ShellNav` mantêm
+`collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem` e `SidebarNav` mantêm
 somente os ícones e expõem os rótulos em tooltips. Por isso, todo destino que aparece no modo
 recolhido precisa de um ícone reconhecível e de um `label` completo.
 
@@ -329,26 +312,3 @@ O driver de drag-and-drop continua externo e fornece seus atributos por `dragPro
 |---|---|---|---|
 | `className` | `string` | | Ajusta o grupo sem substituir o recuo, o espaçamento e a guia vertical padrão. |
 | `children` | `ReactNode` | | Itens ou grupos que descendem do nó anterior. |
-
-## Propriedades de ShellNav
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `groups` | `ShellNavGroup[]` | | Grupos planos exibidos na região rolável. Grupos vazios são omitidos. |
-| `activeId` | `string` | | Identificador do destino atual. |
-| `onSelect` | `(id: string) => void` | | Recebe o identificador selecionado. |
-| `heading` | `ReactNode` | | Conteúdo fixo acima da navegação; fica oculto no modo recolhido. |
-| `footer` | `ShellNavGroup[]` | | Grupos ancorados abaixo da região rolável. |
-| `navLabel` | `string` | `'Navegação'` | Nome acessível da landmark `nav`. |
-| `className` | `string` | | Ajusta a coluna da navegação. A largura vem do contêiner. |
-
-Cada `ShellNavGroup` recebe `label` opcional e `items`. Um `ShellNavItem` declara `id`, `label`,
-`icon`, `badge` e `disabled`.
-
-## Propriedades de ShellNavHeading
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `title` | `ReactNode` | | Título da navegação. |
-| `action` | `ReactNode` | | Ação relacionada apresentada no extremo oposto. |
-| `className` | `string` | | Ajusta a faixa de cabeçalho. |