@softize/opus 13.1.0 → 15.0.0

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

@@ -1,20 +1,22 @@
 ## Esqueleto de página
 
-Use `Page` para manter título, contexto, ações e conteúdo no mesmo ritmo visual nas telas do
-back-office. Em larguras amplas, as ações ficam no extremo oposto e acompanham a base do conjunto
-formado pelo título e pela descrição; em larguras estreitas, passam para uma linha abaixo do
-contexto. O container é centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). Use
-`className` somente quando a composição pedir explicitamente outro teto ou largura total. A área
-abaixo do cabeçalho permanece livre para tabelas, cards ou outras composições.
+Use `Page` para manter navegação contextual, título, ações e conteúdo na mesma anatomia. O
+`PageHeader` padrão acompanha o conteúdo dentro do container; `variant="bar"` transforma o mesmo
+cabeçalho em uma faixa compacta no topo. Não monte um chrome paralelo para repetir essas regiões.
+
+Em larguras amplas, as ações ficam no extremo oposto e acompanham a base do título e da descrição;
+em larguras estreitas, passam para uma linha abaixo. O container é centralizado e ocupa a largura
+disponível até `80rem` (`max-w-7xl`). Use `className` somente quando a composição pedir outro teto
+ou largura total.
 
 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 base estrutural de `Content`, mas reconhece somente título, descrição e ações. Contadores e
+outros indicadores pertencem ao conteúdo que os explica.
 
-`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.
-Uma navegação contextual para outra página pode ocupar `actions`, e tabs ficam reservados a
+`Page` também pode ocupar o painel principal de um shell com sidebar. Tabs ficam reservados a
 recortes da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell
-próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes da superfície.
+próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes.
 
 Estados integrais de carregamento, falha ou ausência são compostos no body com `PageState`,
 detalhado abaixo. `Page` não recebe flags de dados: uma página pode agregar fontes independentes e
@@ -25,7 +27,6 @@ render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
     <Page
       title="Workspaces"
-      count={3}
       description="Ambientes compartilhados pela equipe."
       actions={
         <Button>
@@ -38,16 +39,58 @@ render(
       </div>
     </Page>
   </div>,
-)
+);
 ```
 
-## Ações no chrome do shell
+## Retorno para a página pai
+
+Use `PageBack` em uma subpágina simples. O destino é explícito para continuar correto após refresh ou
+acesso por link direto; não derive esse retorno do histórico do navegador. No header padrão, o
+controle aparece acima do título com ícone e rótulo.
 
-Quando o shell reserva uma barra própria para contexto e ações, envolva sua região de conteúdo com
-`PageActionsTarget` e passe o elemento de destino em `target`. As ações declaradas em `Page`
-continuam pertencendo semanticamente ao cabeçalho da página, mas são projetadas nesse elemento.
-Com `target={null}`, elas permanecem na posição padrão; isso permite montar o alvo por `ref` sem
-uma renderização intermediária inconsistente.
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageBack href="/customers">Clientes</PageBack>
+    <PageTitle>Qualidade da base</PageTitle>
+    <PageDescription>Revise conflitos e canais de contato.</PageDescription>
+  </PageHeader>
+  <PageBody>Conteúdo da análise.</PageBody>
+</Page>
+```
+
+Não combine `PageBack` com breadcrumb. Use o retorno para um único pai conhecido. Quando houver
+mais de um ancestral relevante, envolva o `Breadcrumb` em `PageNavigation`; ele ocupa a mesma
+posição introdutória sem transformar a trilha em ação.
+
+## Cabeçalho em barra
+
+Use `variant="bar"` quando título, retorno e ações precisarem formar uma faixa compacta e persistente
+no topo da página. `Page` estende a borda por toda a largura e mantém o conteúdo da barra alinhado ao
+mesmo teto do body. Nesse modo, `PageBack` vira icon-only e recebe tooltip e nome acessível “Voltar
+para {destino}”. Mantenha também as ações compactas: use `sm` em botões com texto e `icon-sm` em
+botões que exibem somente um ícone.
+
+```tsx preview col
+<Page className="max-w-none">
+  <PageHeader variant="bar">
+    <PageBack href="/customers">Clientes</PageBack>
+    <PageTitle>Qualidade da base</PageTitle>
+    <PageActions>
+      <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+        <Ellipsis />
+      </Button>
+    </PageActions>
+  </PageHeader>
+  <PageBody>Conteúdo da análise.</PageBody>
+</Page>
+```
+
+Uma página comum não ganha a barra apenas por estar dentro de um shell. Escolha essa variante quando
+a faixa acrescentar contexto ou ações persistentes; sem isso, mantenha o header padrão.
+
+`PageActionsTarget` continua disponível para um workspace imersivo que já possua um chrome próprio.
+Ele projeta somente `PageActions` no elemento informado; não cria uma segunda região de cabeçalho.
 
 ## Composição explícita
 
@@ -59,9 +102,12 @@ render(
   <Page>
     <PageHeader>
       <PageTitle>Workspaces</PageTitle>
-      <PageMeta>3</PageMeta>
       <PageDescription>Ambientes compartilhados pela equipe.</PageDescription>
-      <PageActions><Button><Plus /> Novo workspace</Button></PageActions>
+      <PageActions>
+        <Button>
+          <Plus /> Novo workspace
+        </Button>
+      </PageActions>
     </PageHeader>
     <PageBody>
       <div className="rounded-lg border border-dashed border-border p-10 text-center">
@@ -69,15 +115,18 @@ render(
       </div>
     </PageBody>
   </Page>,
-)
+);
 ```
 
 ## Estados integrais
 
 Use `PageState` quando carregamento, falha ou ausência substituírem todo o conteúdo principal. Na
 forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
-explícita, coloque-o dentro de `PageBody`. O cabeçalho continua visível e o estado recebe composição,
-altura e semântica acessível consistentes.
+explícita, coloque-o sozinho dentro de `PageBody`. Enquanto `status` for `loading`, `error` ou
+`empty`, `Page` oculta o cabeçalho e o estado ocupa a altura disponível. O título do estado assume o
+heading principal. Esse registro também funciona quando um componente intermediário decide qual
+`PageState` renderizar. Em `ready`, o cabeçalho e o conteúdo voltam à composição normal. O cabeçalho some inteiro, incluindo o `PageBack`: uma subpágina que dependa desse retorno
+oferece a saída pelo `action` do próprio `PageState` (ADR 0004, adendo).
 
 ```tsx preview col
 <Page title="Relatório">
@@ -85,13 +134,18 @@ altura e semântica acessível consistentes.
     status="error"
     title="Não foi possível carregar o relatório"
     description="Tente novamente. Se o problema continuar, volte mais tarde."
-    action={<Button>Tentar novamente</Button>}
+    onRetry={() => {}}
+    retryLabel="Tentar novamente"
   />
 </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` usa a mesma anatomia visual
+centralizada dos outros estados, conserva `role="alert"` e oferece uma ação `outline` textual quando
+há `onRetry`; `empty` centraliza `Empty` sem moldura; e `ready` entrega os filhos sem
+acrescentar uma superfície. A moldura tracejada continua reservada ao `Empty` usado diretamente para
+representar uma região disponível para criar ou vincular. `title` e `description` nomeiam a situação
+e, sem `title`, valem `errorMessage` e `emptyMessage`.
 
 ```tsx preview col
 <Page title="Relatórios">
@@ -111,20 +165,89 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade   | Tipo        | Padrão      | Descrição                                                                                       |
 | ------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
-| `title`       | `string`    |             | O h1 da página.                                                                                 |
-| `count`       | `number`    |             | Total de itens ao lado do título (mono, esmaecido).                                             |
+| `title`       | `ReactNode` |             | O h1 da página.                                                                                 |
 | `description` | `ReactNode` |             | Linha de contexto sob o título (ex.: "N no total · X ativos").                                  |
 | `actions`     | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho; em telas estreitas, ficam abaixo do contexto. |
 | `className`   | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`    | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
 
+## Propriedades de PageHeader
+
+| Propriedade | Tipo                   | Padrão      | Descrição                                                        |
+| ----------- | ---------------------- | ----------- | ---------------------------------------------------------------- |
+| `variant`   | `'default' \| 'bar'`  | `'default'` | Apresentação no container ou como faixa compacta no topo.        |
+| `className` | `string`               |             | Classes adicionais da região externa do cabeçalho.               |
+| `children`  | `ReactNode`            |             | Um `PageTitle` e, opcionalmente, `PageBack` ou `PageNavigation`, descrição e ações. |
+
+## Propriedades de PageBack
+
+| Propriedade  | Tipo                         | Padrão                    | Descrição                                                               |
+| ------------ | ---------------------------- | ------------------------- | ----------------------------------------------------------------------- |
+| `href`       | `string`                     | obrigatório               | Destino explícito da página pai. Sem ele o retorno não é tabulável nem tem nome acessível. |
+| `children`   | `ReactNode`                  |                           | Nome visível do destino no header padrão e conteúdo do tooltip na barra. |
+| `aria-label` | `string`                     | `Voltar para {children}`  | Nome acessível; informe-o quando `children` não for texto simples.       |
+| `onClick`    | `MouseEventHandler<HTMLAnchorElement>` |             | Integração opcional com o roteador do consumidor, junto do `href`, nunca no lugar dele. |
+| `className`  | `string`                     |                           | Classes adicionais do link renderizado como botão `ghost`.              |
+
+## Propriedades de PageNavigation
+
+| Propriedade | Tipo                          | Descrição                                       |
+| ----------- | ----------------------------- | ----------------------------------------------- |
+| `children`  | `ReactNode`                   | Trilha estrutural, normalmente um `Breadcrumb`. |
+| `className` | `string`                      | Classes adicionais do container introdutório.   |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container.       |
+
+## Propriedades de PageTitle
+
+| Propriedade | Tipo                              | Descrição                                              |
+| ----------- | --------------------------------- | ------------------------------------------------------ |
+| `children`  | `ReactNode`                       | Título principal `h1`; compacto na variante `bar`.     |
+| `className` | `string`                          | Classes adicionais do título.                          |
+| demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.                |
+
+## Propriedades de PageDescription
+
+| Propriedade | Tipo                                | Descrição                                |
+| ----------- | ----------------------------------- | ---------------------------------------- |
+| `children`  | `ReactNode`                         | Contexto apresentado abaixo do título.   |
+| `className` | `string`                            | Classes adicionais da descrição.         |
+| demais      | Atributos de `HTMLParagraphElement` | Atributos nativos repassados ao parágrafo. |
+
+## Propriedades de PageActions
+
+| Propriedade | Tipo                           | Descrição                                    |
+| ----------- | ------------------------------ | -------------------------------------------- |
+| `children`  | `ReactNode`                    | Ações no extremo oposto do cabeçalho.        |
+| `className` | `string`                       | Classes adicionais da região de ações.       |
+| demais      | Atributos de `HTMLDivElement`  | Atributos nativos repassados ao container.    |
+
+## Propriedades de PageBody
+
+| Propriedade | Tipo                          | Descrição                                             |
+| ----------- | ----------------------------- | ----------------------------------------------------- |
+| `children`  | `ReactNode`                   | Conteúdo principal; recebe o container na barra.      |
+| `className` | `string`                      | Classes adicionais da região principal.               |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container.             |
+
+## Propriedades de PageActionsTarget
+
+| Propriedade | Tipo                 | Descrição                                                               |
+| ----------- | -------------------- | ----------------------------------------------------------------------- |
+| `target`    | `HTMLElement \| null` | Destino externo das ações; `null` mantém as ações no header.           |
+| `children`  | `ReactNode`          | Árvore de página que poderá declarar `PageActions`.                     |
+
 ## Propriedades de PageState
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `status` | `'loading' \| 'error' \| 'empty' \| 'ready'` | | Estado integral do conteúdo. |
-| `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. |
-| `children` | `ReactNode` | | Conteúdo renderizado somente em `ready`. |
+| Propriedade    | Tipo                                         | Padrão                                    | Descrição                                                                                       |
+| -------------- | -------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `status`       | `'loading' \| 'error' \| 'empty' \| 'ready'` |                                           | Estado integral do conteúdo.                                                                    |
+| `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`                                  |                                           | 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 um botão `outline` textual ao lado de `action`.                 |
+| `retryLabel`   | `string`                                     | `'Tentar de novo'`                        | Texto do botão de recuperação.                                                                  |
+| `children`     | `ReactNode`                                  |                                           | Conteúdo renderizado somente em `ready`.                                                        |
+| `className`    | `string`                                     |                                           | Classes da superfície de estado.                                                                |

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. |

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

@@ -1,9 +1,12 @@
 ## Carregamento sem progresso conhecido
 
-Use `Spinner` quando a duração ou o progresso da espera não forem conhecidos. `sm` atende ações
-compactas; `lg`, estados mais amplos. O componente já possui o nome acessível “Carregando”.
+Use `Spinner` quando a duração ou o progresso da espera não forem conhecidos. `size` usa os nomes da
+escala dos controles e mede o glifo do controle homônimo: `sm` é o ícone de um `Button` `sm`, `lg` o
+de um `lg`. O ícone é decorativo; quem nomeia a espera é o contêiner (`role="status"`, como fazem
+`DataState` e `PageState`) ou o texto ao lado.
 
 ```tsx preview
+<Spinner size="xs" />
 <Spinner size="sm" />
 <Spinner />
 <Spinner size="lg" />
@@ -20,11 +23,11 @@ andamento.
 
 ## Em carga de conteúdo
 
-Espera curta sem forma definida. Quando o conteúdo tem forma conhecida (lista, card), prefira
-Skeleton.
+Espera curta sem forma definida; o contêiner nomeia o estado. Para uma consulta inteira, `DataState`
+já monta esse contêiner. Quando o conteúdo tem forma conhecida (lista, card), prefira Skeleton.
 
 ```tsx preview
-<div className="flex items-center gap-2 text-sm text-muted-foreground">
+<div role="status" className="flex items-center gap-2 text-sm text-muted-foreground">
   <Spinner />
   <span>Carregando sessões…</span>
 </div>
@@ -34,4 +37,4 @@ Skeleton.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | O tamanho — sm para dentro de botão, lg para estados de página. |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | O glifo do controle homônimo na escala única (0.875 · 0.875 · 1 · 1.25rem). |

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

@@ -66,5 +66,5 @@ disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em p
 | `checked` | `boolean` | | O estado, no modo controlado — parear com onCheckedChange. |
 | `onCheckedChange` | `(checked: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave — sm para densidade em linha de lista. |
+| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave, com os nomes da escala única — sm para densidade em linha de lista. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |

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

@@ -92,7 +92,7 @@ lateral do gatilho.
 | `defaultValue` | `string` | | Aba inicial no modo não controlado. |
 | `value` | `string` | | Aba ativa no modo controlado. Use com `onValueChange`. |
 | `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outra aba. |
-| `size` | `'default' \| 'sm'` | `'default'` | Escala de altura compartilhada com `TabsList`. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura da lista na escala única dos controles (2.25 e 2rem), aplicada em `TabsList`. |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas. |
 
 ## Propriedades de TabsList

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

@@ -70,7 +70,7 @@ disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
 | `onPressedChange` | `(pressed: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultPressed` | `boolean` | `false` | Estado inicial no modo não controlado. |
 | `variant` | `'default' \| 'outline'` | `'default'` | default não tem borda (fundo só quando ativo); outline carrega a borda. |
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura do botão — sm para toolbar densa, lg para alvo mais confortável. |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |
 
 ## ToggleGroup

package/src/ui/drivers/react.tsx

@@ -2,7 +2,7 @@
  * @softize/opus/ui/react — React driver
  *
  * Hooks + Provider pra invocar actions client-side.
- *   - `OpusProvider` — injeta ClientAdapter no contexto (`TbdlibProvider` é alias em retirada)
+ *   - `OpusProvider` — injeta ClientAdapter no contexto
  *   - `useAction(action)` — invoca actions simple/form/view
  *   - `useLookupAction(action)` — variante pra search (output Paginated)
  *
@@ -83,11 +83,6 @@ export function OpusProvider({
   return <OpusContext.Provider value={value}>{children}</OpusContext.Provider>
 }
 
-/** @deprecated Renomeado para `OpusProvider`; o alias segue até a próxima série. */
-export const TbdlibProvider = OpusProvider
-/** @deprecated Use `OpusProviderProps`. */
-export type TbdlibProviderProps = OpusProviderProps
-
 function useClient(): ClientAdapter {
   const ctx = useContext(OpusContext)
   if (ctx === null) {

package/src/ui/meta.ts

@@ -27,7 +27,7 @@ export const componentMeta = {
     name: "alert",
     ancestry: "opus",
     whenToUse:
-      "Aviso inline no fluxo da página — `context` declara neutral/info/success/warning/danger e `variant` escolhe subtle/outline (ADR 0006). Forma curta: `<Alert title description icon context />`; para conteúdo rico, componha AlertMedia + AlertHeader (AlertTitle e AlertDescription) + AlertActions. A mídia mantém uma moldura tonal quadrada, mesmo com descrição multilinha. O texto comunica o significado sem depender só da cor. Para interromper cobrando decisão, use `dialog.confirm()`; para recado passageiro, `toast`.",
+      "Aviso inline no fluxo da página — `context` declara neutral/info/success/warning/danger e `variant` escolhe subtle/outline (ADR 0006). Forma curta: `<Alert title description icon context />`; para conteúdo rico, componha AlertMedia + AlertHeader (AlertTitle e AlertDescription) + AlertActions. Ações usam Button ghost como ponto de partida; tentativas repetidas podem usar somente o ícone, com nome acessível e tooltip. A mídia mantém uma moldura tonal quadrada, mesmo com descrição multilinha. O texto comunica o significado sem depender só da cor. Para interromper cobrando decisão, use `dialog.confirm()`; para recado passageiro, `toast`.",
   },
   badge: {
     name: "badge",
@@ -69,7 +69,7 @@ export const componentMeta = {
     name: "button",
     ancestry: "shadcn",
     whenToUse:
-      "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala; `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup.",
+      "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala compartilhada (`xs`…`lg` e os quadrados `icon-*`); `icon` recebe um nó e `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup conectado ou espaçado.",
   },
   card: {
     name: "card",
@@ -117,7 +117,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "Estruture o cabeçalho de um Content com título, descrição, metadados e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia.",
+      "Estruture uma região de conteúdo com título, contador, descrição e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia. Contadores pertencem a Content e não ao título da Page.",
   },
   copyable: {
     name: "copyable",
@@ -129,7 +129,7 @@ export const componentMeta = {
     name: "dialog",
     ancestry: "opus",
     whenToUse:
-      "Abra conteúdo ou uma tarefa em uma janela modal com foco contido. Use o modo padrão quando a superfície puder ser dispensada e `mode=\"alert\"` quando exigir resposta explícita. Para o caso imperativo comum, use `dialog.alert`, `dialog.confirm`, `dialog.prompt` ou `dialog.choose`. Distribua conteúdo próprio entre cabeçalho, corpo rolável e rodapé de ações.",
+      'Abra conteúdo ou uma tarefa em uma janela modal com foco contido. Use o modo padrão quando a superfície puder ser dispensada e `mode="alert"` quando exigir resposta explícita. Para o caso imperativo comum, use `dialog.alert`, `dialog.confirm`, `dialog.prompt` ou `dialog.choose`. Distribua conteúdo próprio entre cabeçalho, corpo rolável e rodapé de ações.',
   },
   input: {
     name: "input",
@@ -183,7 +183,7 @@ export const componentMeta = {
     name: "spinner",
     ancestry: "shadcn",
     whenToUse:
-      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. Para reservar a forma do conteúdo, use Skeleton.",
+      'Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. O ícone é decorativo: o contêiner (`role="status"`) ou o texto ao lado nomeia a espera. Para reservar a forma do conteúdo, use Skeleton.',
   },
   table: {
     name: "table",
@@ -327,7 +327,7 @@ export const componentMeta = {
     name: "sidebar",
     ancestry: "opus",
     whenToUse:
-      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos, componha árvores com SidebarItem e SidebarTreeGroup e use ShellNav quando a navegação precisar de cabeçalho e rodapé próprios.",
+      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios ficam em PaneHeader e PaneFooter.",
   },
   "scroll-area": {
     name: "scroll-area",
@@ -400,7 +400,7 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand com title, description, count e actions cria a mesma anatomia de PageHeader(PageTitle/PageDescription/PageMeta/PageActions) + PageBody disponível na forma explícita. PageActionsTarget projeta as ações no chrome reservado pelo shell sem retirar sua declaração da Page. `className` substitui o teto quando a composição pede outra largura. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState. Para listagem em modal, ActionListDialog.",
+      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand cobre título, descrição e ações; a forma explícita acrescenta PageBack para retorno simples ou PageNavigation para uma trilha e permite `PageHeader variant=\"bar\"` quando a mesma anatomia precisar virar uma faixa compacta. No header padrão, PageBack fica acima do título; na barra, vira icon-only com tooltip. PageActionsTarget fica restrito a workspaces imersivos com chrome próprio. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState: ele oculta o header e ocupa a área disponível, centralizado e sem moldura. Para uma região disponível à criação ou vínculo, use Empty.",
   },
   router: {
     name: "router",
@@ -412,7 +412,7 @@ export const componentMeta = {
     name: "data-state",
     ancestry: "opus",
     whenToUse:
-      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
+      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona com as mesmas superfícies de PageState: `emptyMessage` compõe Empty com moldura sólida, o erro é um Alert com `onRetry` e `retryLabel`. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
   },
   "action-list-dialog": {
     name: "action-list-dialog",