@softize/opus 12.10.0 → 13.0.0

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

@@ -1,6 +1,7 @@
-## Básico
+## Uma tecla
 
-Uma tecla por Kbd. É só visual — quem escuta o atalho é o seu handler, não o componente.
+Use um `Kbd` para representar cada tecla. O componente apresenta o atalho; a captura do teclado
+continua no handler do aplicativo.
 
 ```tsx preview
 <Kbd>Esc</Kbd>
@@ -8,7 +9,7 @@ Uma tecla por Kbd. É só visual — quem escuta o atalho é o seu handler, não
 
 ## Combinação
 
-Envolva as teclas num KbdGroup e ponha o conector (+) como texto entre elas — o padrão pra paleta de comandos do Maestro.
+Agrupe as teclas com `KbdGroup` e use `+` como texto entre elas.
 
 ```tsx preview
 <KbdGroup>
@@ -20,7 +21,8 @@ Envolva as teclas num KbdGroup e ponha o conector (+) como texto entre elas —
 
 ## Com ícone
 
-Um ícone (lucide) como filho do Kbd ganha size-3 automático — bom pra ⌘ e Enter, onde o glifo lê melhor que a letra.
+Um ícone Lucide recebe automaticamente a escala do componente. Use-o quando o símbolo for mais
+reconhecível que o nome da tecla.
 
 ```tsx preview col-start
 <KbdGroup>
@@ -35,7 +37,8 @@ Um ícone (lucide) como filho do Kbd ganha size-3 automático — bom pra ⌘ e
 
 ## No tooltip
 
-Dentro de um TooltipContent o Kbd inverte o tom sozinho (fundo claro sobre o balão escuro) — anuncie o atalho da ação ao passar o mouse.
+Dentro de `TooltipContent`, o componente ajusta o contraste automaticamente. O tooltip deve nomear a
+ação antes de informar seu atalho.
 
 ```tsx preview
 <Tooltip>
@@ -52,11 +55,16 @@ Dentro de um TooltipContent o Kbd inverte o tom sozinho (fundo claro sobre o bal
 </Tooltip>
 ```
 
-## Props
+## Propriedades de Kbd
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `children (Kbd)` | `React.ReactNode` | | A tecla — texto (Esc, ⌘, K) ou um ícone lucide, que recebe size-3 automático. |
-| `className (Kbd)` | `string` | | Classes extras na tecla, mescladas com cn — pra ajustar tamanho ou cor pontualmente. |
-| `children (KbdGroup)` | `React.ReactNode` | | As teclas do combo, mais o conector (ex.: "+") como texto entre elas. |
-| `className (KbdGroup)` | `string` | | Classes extras no agrupador (inline-flex + gap-1), mescladas com cn. |
+| `children` | `React.ReactNode` | | Texto ou ícone que representa a tecla. Ícones Lucide recebem a escala visual do componente. |
+| `className` | `string` | | Classes adicionais aplicadas à tecla. |
+
+## Propriedades de KbdGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `React.ReactNode` | | Teclas da combinação e conectores, como `+`, entre elas. |
+| `className` | `string` | | Classes adicionais aplicadas ao agrupador. |

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

@@ -1,6 +1,6 @@
 ## Com campo de texto
 
-htmlFor aponta pro id do controle — clicar no rótulo foca o campo.
+Associe `htmlFor` ao `id` do controle para que clicar no rótulo mova o foco para o campo.
 
 ```tsx preview col md
 <div className="grid gap-2">
@@ -11,7 +11,8 @@ htmlFor aponta pro id do controle — clicar no rótulo foca o campo.
 
 ## Com Checkbox
 
-O Label já é flex com gap — controle inline entra sem wrapper extra; clicar no texto alterna a caixa.
+`Label` já organiza controles inline com espaçamento. Ao associá-lo ao `Checkbox`, clicar no texto
+também alterna a seleção.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -22,7 +23,8 @@ O Label já é flex com gap — controle inline entra sem wrapper extra; clicar
 
 ## Par desabilitado
 
-Controle disabled esmaece o rótulo junto (peer-disabled) — o par inteiro comunica o estado, sem classe manual.
+Quando o controle está desabilitado, o rótulo associado acompanha o tratamento visual sem exigir
+uma classe adicional.
 
 ```tsx preview
 <div className="flex items-center gap-2">

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

@@ -4,9 +4,9 @@ title: Log
 
 # Log
 
-Log estruturado que chega no handler já com contexto (per-request, per-action) via
-`ctx.log`. O contrato é o `LoggerAdapter` — a mesma interface `Logger` que o core usa por
-dentro, então o seu log e o do runtime saem no mesmo lugar, no mesmo formato.
+Use `ctx.log` para registrar eventos estruturados com o contexto da requisição e da action. O
+`LoggerAdapter` também recebe os registros internos do runtime, mantendo aplicação e Opus no mesmo
+destino e formato.
 
 ## O contrato
 
@@ -49,7 +49,7 @@ handler: async (ctx, input) => {
 }
 ```
 
-## Limites (por enquanto)
+## Limites atuais
 
 Superfície mínima de níveis + `child`. Sem sampling nem transports próprios — isso mora no
 `pino` que você passa. Drivers hoje: `pino`; outros entram por reincidência.

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

@@ -1,13 +1,14 @@
 ## Fonte e resultado
 
-Uso: <Markdown content={fonte} />. No palco, o resultado; no bloco abaixo, a fonte markdown que o produziu. O componente recebe só content: string.
+Passe o texto em `content`. O exemplo mostra primeiro o resultado renderizado e, depois, o Markdown
+que o produziu.
 
 ```tsx preview col 2xl
 const sample = [
   '# Markdown na Softize',
   '',
   'Renderiza **doc técnica** e mensagem de chat — `SKILL.md`, síntese de papel, resposta de agente.',
-  'O motor é o markdown-it, o MESMO que renderiza estas páginas.',
+  'O motor é o markdown-it, o mesmo que renderiza estas páginas.',
   '',
   '## Sintaxe coberta',
   '',
@@ -18,7 +19,7 @@ const sample = [
   '1. Primeiro passo',
   '2. Segundo passo',
   '',
-  '> Citação calma, pro tom certo.',
+  '> Citação calma, para o tom certo.',
   '',
   '---',
   '',
@@ -33,9 +34,9 @@ render(<Markdown content={sample} />)
 ```
 
 
-## Props
+## Propriedades de Markdown
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `content` | `string` | | O markdown cru (CommonMark + tabela GFM, via markdown-it). HTML no fonte é **escapado**, não interpretado — por isso serve pra texto vindo de gente ou de modelo. |
+| `content` | `string` | | O markdown cru (CommonMark + tabela GFM, via markdown-it). HTML no fonte é **escapado**, não interpretado — por isso serve para texto vindo de gente ou de modelo. |
 | `className` | `string` | | Classes do wrapper. |

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

@@ -4,10 +4,9 @@ title: MCP
 
 # MCP
 
-Expõe as actions `ai:enabled` do runtime como **tools MCP** — a porta pra uma IA de **fora**
-(Claude Desktop, o agente de um parceiro, um hub próprio) alcançar o app pelo protocolo. É o
-mesmo bridge do agente co-locado (`runtime.aiTools`) e a mesma execução (`runtime.execute`,
-como o usuário resolvido). O MCP é só o transporte.
+Use o servidor MCP para disponibilizar actions `ai:enabled` a agentes que executam fora da
+aplicação. A chamada continua passando por `runtime.execute`, com a mesma validação, autorização e
+auditoria; o MCP fornece apenas o transporte.
 
 ## Montar
 
@@ -22,23 +21,22 @@ const server = createOpusMcpServer(runtime, {
   resolveContext: async (extra) => auth.resolveFromMcp(extra),
 })
 
-await server.connect(new StdioServerTransport()) // local; HTTP/SSE pra remoto
+await server.connect(new StdioServerTransport()) // local; HTTP/SSE para remoto
 ```
 
 `ListTools` devolve as actions `ai:enabled` (nome + descrição + JSON Schema do input);
 `CallTool` executa a action pelo `runtime.execute` — validação, auth (`ctx.can`) e audit,
 tudo igual a uma chamada normal. Read-only? Marque só actions de leitura com `ai:enabled`.
 
-## Interno × MCP
+## Escolher entre integração interna e MCP
 
-- **Monolito / chat co-locado:** não precisa de MCP — `runtime.aiFor(base).run()` chama as
-  actions direto, in-process (ver o recurso **IA generativa**).
-- **IA por fora / ecossistema:** o agente vive num serviço próprio e alcança N apps pela
-  mesma porta MCP. É aqui que ele se paga.
+- **Agente dentro da aplicação:** use `runtime.aiFor(base).run()` para chamar as actions no mesmo
+  processo.
+- **Agente em outro serviço:** use MCP para oferecer a mesma coleção de ferramentas por uma
+  interface interoperável.
 
-Mesmas tools, transportes diferentes.
+## Limites atuais
 
-## Limites (por enquanto)
-
-Você monta o transporte (stdio/HTTP) — o server é agnóstico. A confirmação de action
-`destructive` sobre MCP (elicitation) entra quando um caso real cobrar; comece read-only.
+O consumidor escolhe e monta o transporte, como stdio ou HTTP. A confirmação de actions destrutivas
+ainda não faz parte desta integração; até que esse fluxo exista, exponha somente operações de
+leitura.

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

@@ -1,6 +1,7 @@
 ## Menu de ações
 
-Ícone à esquerda, atalho à direita (MenuShortcut), separador antes da zona perigosa e variant destructive na ação que destrói.
+Use `Menu` para reunir ações relacionadas em um painel ancorado. `MenuShortcut` posiciona o atalho à
+direita; separe ações perigosas e declare `context="danger"` nelas.
 
 ```tsx preview
 <Menu>
@@ -11,16 +12,15 @@
     <MenuItem><Pencil /> Editar <MenuShortcut>⌘E</MenuShortcut></MenuItem>
     <MenuItem><Copy /> Duplicar</MenuItem>
     <MenuSeparator />
-    <MenuItem variant="destructive"><Trash2 /> Excluir</MenuItem>
+    <MenuItem context="danger"><Trash2 /> Excluir</MenuItem>
   </MenuContent>
 </Menu>
 ```
 
-## Contexto: clique direito
+## Abrir pelo menu de contexto
 
-O papel do ContextMenu (aposentado na 5.0.0) com o MESMO componente — só muda o
-gatilho: controlado, ancorado no ponteiro. `onContextMenu` guarda a posição e abre;
-um gatilho invisível `position: fixed` naquele ponto ancora o conteúdo.
+Para abrir pelo clique direito, controle o estado do menu e use a posição do ponteiro como âncora.
+Esse padrão substitui o antigo `ContextMenu` sem introduzir outra família de componentes.
 
 ```tsx preview
 const [pos, setPos] = useState(null)
@@ -44,16 +44,17 @@ render(
         <MenuItem><Pencil /> Renomear</MenuItem>
         <MenuItem><Copy /> Duplicar</MenuItem>
         <MenuSeparator />
-        <MenuItem variant="destructive"><Trash2 /> Excluir</MenuItem>
+        <MenuItem context="danger"><Trash2 /> Excluir</MenuItem>
       </MenuContent>
     </Menu>
   </div>,
 )
 ```
 
-## Seleção: checkbox e radio
+## Seleção por checkbox ou radio
 
-CheckboxItem pra liga/desliga, RadioGroup pra escolha exclusiva — estado fica no consumidor (controlado).
+Use `MenuCheckboxItem` para opções independentes e `MenuRadioGroup` para escolhas mutuamente
+exclusivas. O consumidor controla o estado nos dois casos.
 
 ```tsx preview
 const [showArchived, setShowArchived] = useState(false)
@@ -92,7 +93,7 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
   <MenuContent align="start">
     <MenuItem><ExternalLink /> Abrir preview</MenuItem>
     <MenuSub>
-      <MenuSubTrigger><ArrowDownAZ /> Mover pra</MenuSubTrigger>
+      <MenuSubTrigger><ArrowDownAZ /> Mover para</MenuSubTrigger>
       <MenuSubContent>
         <MenuItem>Empresa X</MenuItem>
         <MenuItem>Softize</MenuItem>
@@ -103,12 +104,30 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 </Menu>
 ```
 
-## Props
+## Propriedades de MenuItem
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `MenuItem.variant` | `'default' \| 'destructive'` | `'default'` | destructive tonaliza texto e foco em vermelho — só pra ação que destrói. |
-| `MenuItem.inset` | `boolean` | | Recuo à esquerda pra alinhar item sem ícone com os que têm. |
-| `MenuContent.align / sideOffset` | `'start' \| 'center' \| 'end' / number` | `'center' / 4` | Alinhamento e distância em relação ao gatilho (Radix). |
-| `MenuCheckboxItem.checked / onCheckedChange` | `boolean / (checked: boolean) => void` | | Estado do liga/desliga — controlado pelo consumidor. |
-| `MenuRadioGroup.value / onValueChange` | `string / (value: string) => void` | | Escolha exclusiva entre os MenuRadioItem filhos. |
+| `context` | `'neutral' \| 'danger'` | `'neutral'` | `danger` sinaliza uma ação com consequência perigosa. |
+| `inset` | `boolean` | | Alinha um item sem ícone com os itens que possuem ícone. |
+
+## Propriedades de MenuContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
+| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+
+## Propriedades de MenuCheckboxItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `checked` | `boolean` | | Estado controlado do item. |
+| `onCheckedChange` | `(checked: boolean) => void` | | Chamado quando a pessoa alterna o item. |
+
+## Propriedades de MenuRadioGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Valor selecionado no grupo. |
+| `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outro `MenuRadioItem`. |

package/src/ui/docs/content/metric-card.md

@@ -0,0 +1,41 @@
+MetricCard apresenta uma medida resumida com hierarquia e espaçamento consistentes. Passe o
+valor já calculado e formatado; busca de dados, recorte e regras de negócio permanecem no
+consumidor.
+
+```tsx preview col
+<MetricCard
+  label="Total de cadastros"
+  value="286.317"
+  description="Prospects e clientes no cadastro global."
+/>
+```
+
+## Com ícone e ação
+
+O ícone identifica visualmente a natureza da medida e é decorativo. `context="warning"` realça
+somente o ícone; a superfície continua neutra. Use `action` apenas para uma ação diretamente
+relacionada à medida. Um controle que explica o rótulo, como um tooltip, pertence a `labelAction`.
+
+```tsx preview col
+<MetricCard
+  label="Credencial"
+  value="Ausente"
+  description="Reconecte para autorizar novamente o acesso."
+  icon={<KeyRound />}
+  context="warning"
+  action={
+    <Button size="sm" variant="outline">
+      Reconectar
+    </Button>
+  }
+/>
+```
+
+## Carregamento
+
+`loading` preserva a geometria do card com placeholders e marca a superfície como ocupada para
+tecnologias assistivas. O contêiner da coleção continua responsável pela mensagem de carregamento.
+
+```tsx preview col
+<MetricCard loading />
+```

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

@@ -4,8 +4,8 @@ title: Observabilidade
 
 # Observabilidade
 
-O core expõe uma porta vendor-neutral; o driver OpenTelemetry cria spans ativos para actions
-e reactions sem escolher backend, exporter ou Collector.
+Use `ObservabilityAdapter` para envolver actions e reactions em spans sem acoplar o core a um
+fornecedor. O driver OpenTelemetry deixa backend, exporter e Collector sob controle do aplicativo.
 
 ## Driver OpenTelemetry
 

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

@@ -1,11 +1,25 @@
 ## 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. As ações ficam à direita e acompanham a base do conjunto formado pelo título e pela
-descrição. O container é centralizado e ocupa a largura disponível até `72rem` (`max-w-6xl`). Use
+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.
 
+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.
+
+`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
+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.
+
+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
+uma falha parcial não deve ocultar as demais seções.
+
 ```tsx preview col
 render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
@@ -27,13 +41,82 @@ render(
 )
 ```
 
-## Props
+## Composição explícita
+
+Use os slots quando a página precisar compor o header diretamente. Não misture propriedades da
+forma curta com `PageHeader` ou `PageBody`.
+
+```tsx preview col
+render(
+  <Page>
+    <PageHeader>
+      <PageTitle>Workspaces</PageTitle>
+      <PageMeta>3</PageMeta>
+      <PageDescription>Ambientes compartilhados pela equipe.</PageDescription>
+      <PageActions><Button><Plus /> Novo workspace</Button></PageActions>
+    </PageHeader>
+    <PageBody>
+      <div className="rounded-lg border border-dashed border-border p-10 text-center">
+        O conteúdo da página.
+      </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.
+
+```tsx preview col
+<Page title="Relatório">
+  <PageState
+    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>}
+  />
+</Page>
+```
+
+`loading` centraliza o `Spinner`; `error` compõe `Alert`; `empty` compõe `Empty`; e `ready` entrega
+os filhos sem acrescentar uma superfície.
+
+```tsx preview col
+<Page title="Relatórios">
+  <PageState
+    status="empty"
+    title="Nenhum relatório"
+    description="Crie o primeiro relatório para começar."
+    action={<Button>Novo relatório</Button>}
+  />
+</Page>
+```
+
+Não use `PageState` para uma falha parcial. Se outra parte da página continua utilizável, mantenha o
+estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert`.
+
+## Propriedades de Page
+
+| 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).                                             |
+| `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 PageState
 
-| Prop | Tipo | Default | Descrição |
+| 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). |
-| `description` | `ReactNode` | | Linha de contexto sob o título (ex.: "N no total · X ativos"). |
-| `actions` | `ReactNode` | | Ações à direita do cabeçalho, alinhadas à base do título e da descrição. |
-| `className` | `string` | `max-w-6xl` | Classes do container para substituir o teto padrão de `72rem`. |
-| `children` | `ReactNode` | | O conteúdo — espaçamento e diagramação são seus. |
+| `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`. |

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

@@ -1,10 +1,9 @@
-## Básico
+## Navegação entre páginas
 
-É composição: Pagination embrulha PaginationContent, e cada PaginationItem segura um link. `page`
-dá o número e o nome acessível (“Página N”); `isActive` marca a página atual (vira outline). Cada
-número tem altura fixa e largura mínima quadrada que cresce com os dígitos — 5726 e 5727 nunca se
-colam. As setas seguem quadradas e já falam pt-BR; `label` localiza, `iconOnly` deixa só a seta.
-É o único paginador da casa: `ActionList` compõe esta primitiva no rodapé, na escala densa.
+Componha `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
+número e o nome acessível; `isActive` identifica a página atual. Os controles mantêm altura fixa e
+a largura cresce quando o número precisa de mais espaço. `ActionList` usa esta mesma primitiva no
+rodapé.
 
 ```tsx preview
 <Pagination>
@@ -30,7 +29,7 @@ colam. As setas seguem quadradas e já falam pt-BR; `label` localiza, `iconOnly`
 
 ## Números longos
 
-A largura mínima é quadrada; o número manda no resto. Na escala densa de um rodapé, ajuste por
+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`).
 
@@ -61,7 +60,8 @@ setas com `iconOnly`).
 
 ## Com elipse
 
-PaginationEllipsis é o atalho decorativo (aria-hidden) entre blocos de páginas distantes — útil quando a lista de sessões do workspace tem páginas demais pra caber na barra.
+`PaginationEllipsis` marca, de forma decorativa e com `aria-hidden`, uma sequência de páginas que
+não cabe na barra.
 
 ```tsx preview
 <Pagination>
@@ -123,14 +123,19 @@ render(
 )
 ```
 
-## Props
+## Propriedades de PaginationLink
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `page (PaginationLink)` | `number` | | Número da página: vira o conteúdo (quando não há `children`) e o nome acessível “Página N”. |
-| `isActive (PaginationLink)` | `boolean` | `false` | Marca a página atual: vira outline e ganha aria-current="page". Os demais ficam ghost. |
-| `href (PaginationLink)` | `string` | | Com `href` o link é um `<a>`; sem `href` é um `<button>` controlado por `onClick`, com `disabled`. |
-| `size (PaginationLink)` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | Escala do Button. Números usam `default` (largura mínima quadrada que cresce); as setas com `iconOnly` usam `icon`. |
-| `label (Previous/Next)` | `string` | `'Página anterior'` / `'Próxima página'` | Nome acessível e texto visível das setas. |
-| `iconOnly (Previous/Next)` | `boolean` | `false` | Só a seta, quadrada (`size="icon"`); o `label` continua como nome acessível. |
-| `iconClassName (Previous/Next)` | `string` | | Classe do svg da seta, para a escala densa (`size-3.5`). |
+| `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. |
+
+## Propriedades de PaginationPrevious e PaginationNext
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `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. |

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

@@ -1,6 +1,8 @@
-## Estrutura
+## Painel ancorado
 
-PopoverHeader agrupa título e descrição; o corpo é livre (form curto, detalhes). Superfície bg-popover — a elevação da casa.
+Use `Popover` para apresentar conteúdo livre junto a um gatilho, sem abrir um modal.
+`PopoverHeader` agrupa título e descrição; o restante do painel aceita formulários curtos ou
+detalhes.
 
 ```tsx preview
 <Popover>
@@ -23,7 +25,7 @@ PopoverHeader agrupa título e descrição; o corpo é livre (form curto, detalh
 
 ## Alinhamento
 
-align posiciona o painel em relação ao gatilho; sideOffset afasta. O padrão (center) serve pra quase tudo.
+`align` posiciona o painel em relação ao gatilho e `sideOffset` define a distância entre eles.
 
 ```tsx preview
 <Popover>
@@ -40,10 +42,16 @@ align posiciona o painel em relação ao gatilho; sideOffset afasta. O padrão (
 </Popover>
 ```
 
-## Props
+## Propriedades de Popover
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `PopoverContent.align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
-| `PopoverContent.sideOffset` | `number` | `4` | Distância (px) entre gatilho e painel. |
-| `Popover.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra fechar por código depois de salvar. |
+| `open` | `boolean` | | Estado no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado para permitir abertura ou fechamento por código. |
+
+## Propriedades de PopoverContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
+| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |

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

@@ -1,6 +1,7 @@
-## Básico
+## Progresso determinado
 
-value vai de 0 a 100 — o preenchimento anima a cada mudança. Sem value (ou null) a barra fica vazia.
+Use `Progress` quando a tarefa informar uma porcentagem de conclusão. `value` aceita valores de 0 a
+100 e anima o preenchimento a cada mudança. Sem valor, a barra permanece vazia.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-2">
@@ -14,7 +15,8 @@ value vai de 0 a 100 — o preenchimento anima a cada mudança. Sem value (ou nu
 
 ## Controlado
 
-Guarde o value no estado e atualize conforme a tarefa avança — aqui cada clique soma um passo na sincronização do workspace Empresa X.
+Controle `value` externamente quando o progresso acompanhar uma tarefa em andamento. No exemplo,
+cada clique avança uma etapa da sincronização.
 
 ```tsx preview col
 const [step, setStep] = useState(40)
@@ -61,9 +63,9 @@ className compõe sobre o padrão: ajuste a altura no Progress e tinja o preench
 </div>
 ```
 
-## Props
+## Propriedades de Progress
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `number \| null` | | O progresso de 0 a 100. O preenchimento anima a cada mudança; null/ausente deixa a barra vazia. |
 | `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3) ou tinja o indicador via [&_[data-slot=progress-indicator]]:bg-*. |