@softize/opus 27.1.0 → 29.0.0

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

@@ -1,21 +1,23 @@
 ## Esqueleto de página
 
-Use `Page` para manter cabeçalho, estado e conteúdo na mesma anatomia. `PageHeader` é a única
-introdução estrutural: reúne navegação contextual opcional, título, orientação opcional e ações. 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.
+Use `Page` para manter cabeçalho, estado e conteúdo na mesma anatomia. `PageHeader` recebe navegação e ações da superfície;
+`PageIntro` abre o corpo com título e orientação. Na composição compacta, o título fica no header e a intro é omitida. O conteúdo interno do body é
+centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). O header e o viewport
+de rolagem ocupam toda a largura do painel.
 
-A forma curta é o padrão para páginas comuns e cria `PageHeader` e `PageBody`. A forma explícita
-exige exatamente um heading principal. Use `PageTitle` no cabeçalho, `Surface level={1}` no body,
+A forma curta é o padrão para páginas comuns e cria `PageIntro` dentro de `PageBody` e um `PageHeader` quando existem controles. A forma explícita
+exige exatamente um heading principal. Use `PageTitle` na intro ou no cabeçalho, `Surface level={1}` no body,
 ou deixe um `PageState` ativo assumir esse papel. O cabeçalho pode ser omitido quando o próprio
 conteúdo nomeia a página. Contadores e outros indicadores pertencem ao conteúdo que os explica.
 
-A `Page` é contínua por definição e não há divisores entre suas regiões. O `layout` da `Page` não
-é a anatomia de superfície de
-[`Surface`](/ui/surface), [`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer) e [`Pane`](/ui/pane) — aqui ele
-decide a ocupação de altura. `flow`, o padrão, deixa a página crescer e a rolagem acontecer na
-janela; `fill` limita a página à altura do shell para que uma região interna, como uma tabela longa
-ou um split, assuma a rolagem.
+Use `surfaceLayout="sectioned"` (padrão) para separar as regiões por bordas ou
+`surfaceLayout="continuous"` para uma superfície contínua. O `layout` decide a ocupação de altura:
+`flow`, o padrão, mantém a rolagem vertical em `PageBody`; `fill` permite que uma região interna,
+como uma tabela longa ou um split, assuma a rolagem. Header e footer ficam fora desse viewport.
+
+Nos botões da barra superior, declare `size="sm"` para texto e `size="icon-sm"` para ícones.
+`PageHeader` reserva uma linha mínima de `2rem`, mesmo sem ações; conteúdo maior pode expandi-la.
+`PageBack` já usa `icon-sm`. A mesma escala vale para ações nos headers de Dialog, Drawer e Surface, inclusive criação de coleções.
 
 `PageShell` não inclui sidebar nem inventa breadcrumb. Ele ocupa o painel principal já delimitado e
 entrega ao `PageHeader` descendente a navegação e as ações conhecidas pela aplicação, sem criar uma
@@ -31,7 +33,11 @@ render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
     <Page
       title="Workspaces"
-      actions={<Button variant="outline">Exportar</Button>}
+      actions={
+        <Button variant="outline" size="sm">
+          Exportar
+        </Button>
+      }
     >
       <div className="rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
         O conteúdo da página (tabela, cards, grid…).
@@ -43,13 +49,16 @@ render(
 
 ## Orientar sobre a finalidade
 
-Use `description` na forma curta ou `PageDescription` em `PageHeader` quando uma frase breve
+Use `description` na forma curta ou `PageDescription` junto ao título em `PageIntro` ou `PageHeader` quando uma frase breve
 ajudar a reconhecer a finalidade da página. Omita texto que só repita o título. Regras de negócio,
 limites e consequências ficam nos campos, ações ou corpo em que são necessários. Pular o
 subheading não deve comprometer a decisão nem a conclusão correta da tarefa.
 
 ```tsx
-<Page title="Conhecimento" description="Consulte os materiais de apoio da sua área.">
+<Page
+  title="Conhecimento"
+  description="Consulte os materiais de apoio da sua área."
+>
   <KnowledgeList />
 </Page>
 ```
@@ -65,9 +74,13 @@ da linha do título como ícone; o nome acessível e a dica nativa do navegador
 <Page>
   <PageHeader>
     <PageBack href="/customers">Clientes</PageBack>
-    <PageTitle>Qualidade da base</PageTitle>
   </PageHeader>
-  <PageBody>Conteúdo da análise.</PageBody>
+  <PageBody>
+    <PageIntro>
+      <PageTitle>Qualidade da base</PageTitle>
+    </PageIntro>
+    Conteúdo da análise.
+  </PageBody>
 </Page>
 ```
 
@@ -89,9 +102,13 @@ ocupa a mesma posição introdutória sem transformar a trilha em ação.
         </BreadcrumbList>
       </Breadcrumb>
     </PageNavigation>
-    <PageTitle>Carla Souza</PageTitle>
   </PageHeader>
-  <PageBody>Dados do cliente.</PageBody>
+  <PageBody>
+    <PageIntro>
+      <PageTitle>Carla Souza</PageTitle>
+    </PageIntro>
+    Dados do cliente.
+  </PageBody>
 </Page>
 ```
 
@@ -99,7 +116,7 @@ ocupa a mesma posição introdutória sem transformar a trilha em ação.
 
 Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece ações globais ou uma
 introdução. Não crie um cabeçalho paralelo no layout nem esconda slots de `Page` com CSS. O Opus compõe a
-navegação e as ações do shell no `PageHeader` rolável da página ativa.
+navegação e as ações do shell no `PageHeader` estável da página ativa.
 
 ```tsx preview col
 <PageShell
@@ -113,7 +130,14 @@ navegação e as ações do shell no `PageHeader` rolável da página ativa.
     </Breadcrumb>
   }
 >
-  <Page title="Clientes" actions={<Button variant="outline">Exportar</Button>}>
+  <Page
+    title="Clientes"
+    actions={
+      <Button variant="outline" size="sm">
+        Exportar
+      </Button>
+    }
+  >
     Conteúdo da listagem.
   </Page>
 </PageShell>
@@ -122,7 +146,7 @@ navegação e as ações do shell no `PageHeader` rolável da página ativa.
 Durante `PageState`, o cabeçalho inteiro desaparece e o título do estado assume o heading principal.
 Se uma ação não puder ser executada sem o conteúdo, a própria rota deve omiti-la naquele estado.
 
-Na composição explícita, combine navegação, título e ações no mesmo cabeçalho:
+Na composição explícita, separe navegação e ações da superfície do título no corpo:
 
 ```tsx preview col
 <PageShell
@@ -138,12 +162,16 @@ Na composição explícita, combine navegação, título e ações no mesmo cabe
 >
   <Page>
     <PageHeader>
-      <PageTitle>Clientes</PageTitle>
       <PageActions>
-        <Button>Exportar</Button>
+        <Button size="sm">Exportar</Button>
       </PageActions>
     </PageHeader>
-    <PageBody>Conteúdo da listagem.</PageBody>
+    <PageBody>
+      <PageIntro>
+        <PageTitle>Clientes</PageTitle>
+      </PageIntro>
+      Conteúdo da listagem.
+    </PageBody>
   </Page>
 </PageShell>
 ```
@@ -157,12 +185,17 @@ forma curta com `PageHeader` ou `PageBody`.
 render(
   <Page>
     <PageHeader>
-      <PageTitle>Workspaces</PageTitle>
       <PageActions>
-        <Button variant="outline">Exportar</Button>
+        <Button variant="outline" size="sm">
+          Exportar
+        </Button>
       </PageActions>
     </PageHeader>
     <PageBody>
+      <PageIntro>
+        <PageTitle>Workspaces</PageTitle>
+      </PageIntro>
+
       <div className="rounded-lg border border-dashed border-border p-10 text-center">
         O conteúdo da página.
       </div>
@@ -185,10 +218,12 @@ no fim da linha.
 
 ```tsx preview col
 <Page>
-  <PageHeader>
-    <PageTitle>Importar clientes</PageTitle>
-  </PageHeader>
-  <PageBody>Revise os 128 registros antes de confirmar.</PageBody>
+  <PageBody>
+    <PageIntro>
+      <PageTitle>Importar clientes</PageTitle>
+    </PageIntro>
+    Revise os 128 registros antes de confirmar.
+  </PageBody>
   <PageFooter>
     <ButtonGroup mode="spaced">
       <Button variant="ghost">Cancelar</Button>
@@ -209,10 +244,11 @@ rolagem, como o `PageBody` do exemplo.
 render(
   <div className="h-72 overflow-hidden rounded-lg border border-border">
     <Page layout="fill">
-      <PageHeader>
-        <PageTitle>Ordens de serviço</PageTitle>
-      </PageHeader>
       <PageBody className="min-h-0 flex-1 overflow-y-auto">
+        <PageIntro>
+          <PageTitle>Ordens de serviço</PageTitle>
+        </PageIntro>
+
         <div className="space-y-2">
           {[
             "OS-1842",
@@ -263,7 +299,11 @@ function Example() {
       <PageActionsTarget target={target}>
         <Page
           title="Clientes"
-          actions={<Button variant="outline">Exportar</Button>}
+          actions={
+            <Button variant="outline" size="sm">
+              Exportar
+            </Button>
+          }
         >
           Conteúdo da listagem.
         </Page>
@@ -322,31 +362,35 @@ estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui
 
 ## Propriedades de Page
 
-| Propriedade | Tipo                       | Padrão      | Descrição                                                                                                                                                          |
-| ----------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `description` | `ReactNode` | | Orientação opcional sob o título na forma curta. |
-| `title`     | `ReactNode`                |             | O h1 da página.                                                                                                                                                    |
-| `actions`   | `ReactNode`                |             | Ações contextuais no extremo oposto do cabeçalho.                                                                                                                  |
-| `layout`    | `'flow' \| 'fill'`         | `'flow'`    | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role e leva essa altura até uma `ActionList` composta em `PageBody`. |
-| `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.                                                                                                             |
-| demais      | Atributos de `HTMLElement` |             | Atributos nativos repassados ao elemento `main`, como `id` ou `aria-label`. `className` vai para o container interno.                                              |
+| Propriedade   | Tipo                       | Padrão      | Descrição                                                                                                                                                          |
+| ------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `description` | `ReactNode`                |             | Orientação opcional sob o título na forma curta.                                                                                                                   |
+| `title`       | `ReactNode`                |             | O h1 da página.                                                                                                                                                    |
+| `actions`     | `ReactNode`                |             | Ações contextuais no extremo oposto do cabeçalho.                                                                                                                  |
+| `layout`      | `'flow' \| 'fill'`         | `'flow'`    | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role e leva essa altura até uma `ActionList` composta em `PageBody`. |
+| `className`   | `string`                   |             | Classes do container externo. Para largura interna, use `contentClassName`.                                                                                        |
+| `children`    | `ReactNode`                |             | O body da página — espaçamento e diagramação são seus.                                                                                                             |
+| demais        | Atributos de `HTMLElement` |             | Atributos nativos repassados ao elemento `main`, como `id` ou `aria-label`. `className` vai para a moldura da página.                                              |
 
 ## Propriedades de PageShell
 
-| Propriedade  | Tipo                          | Descrição                                                                  |
-| ------------ | ----------------------------- | -------------------------------------------------------------------------- |
-| `navigation` | `ReactNode`                   | Navegação contextual composta acima do título no `PageHeader` descendente. |
-| `actions`    | `ReactNode`                   | Ações conhecidas pelo shell, antes das ações declaradas pela `Page`.       |
-| `children`   | `ReactNode`                   | Rota que renderiza uma `Page` descendente.                                 |
-| `className`  | `string`                      | Classes adicionais da moldura.                                             |
-| demais       | Atributos de `HTMLDivElement` | Atributos nativos repassados à moldura.                                    |
+| Propriedade  | Tipo                          | Descrição                                                                                  |
+| ------------ | ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `navigation` | `ReactNode`                   | Navegação contextual composta na linha de controles do header no `PageHeader` descendente. |
+| `actions`    | `ReactNode`                   | Ações conhecidas pelo shell, antes das ações declaradas pela `Page`.                       |
+| `children`   | `ReactNode`                   | Rota que renderiza uma `Page` descendente.                                                 |
+| `className`  | `string`                      | Classes adicionais da moldura.                                                             |
+| demais       | Atributos de `HTMLDivElement` | Atributos nativos repassados à moldura.                                                    |
+
+`surfaceLayout?: 'sectioned' | 'continuous'` escolhe os divisores; o padrão é `sectioned`.
+`contentClassName?: string` configura largura e alinhamento do conteúdo. O ritmo e os recuos
+continuam sob responsabilidade do body; não use essa prop para substituir padding ou gap.
 
 ## Propriedades de PageHeader
 
 | Propriedade | Tipo                          | Descrição                                                                |
 | ----------- | ----------------------------- | ------------------------------------------------------------------------ |
-| `className` | `string`                      | Classes adicionais do cabeçalho rolável.                                 |
+| `className` | `string`                      | Classes adicionais do cabeçalho estável.                                 |
 | `children`  | `ReactNode`                   | `PageBack` ou `PageNavigation`, um `PageTitle` opcional e `PageActions`. |
 | demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao cabeçalho.                               |
 
@@ -370,11 +414,11 @@ estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui
 
 ## Propriedades de PageTitle
 
-| Propriedade | Tipo                              | Descrição                                |
-| ----------- | --------------------------------- | ---------------------------------------- |
-| `children`  | `ReactNode`                       | Título principal `h1` de `PageHeader`.   |
-| `className` | `string`                          | Classes adicionais do título.            |
-| demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading. |
+| Propriedade | Tipo                              | Descrição                                             |
+| ----------- | --------------------------------- | ----------------------------------------------------- |
+| `children`  | `ReactNode`                       | Título principal `h1` na intro ou no header compacto. |
+| `className` | `string`                          | Classes adicionais do título.                         |
+| demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.              |
 
 ## Propriedades de PageActions
 
@@ -394,14 +438,15 @@ estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui
 
 ## Propriedades de PageBody
 
-`PageBody` separa seus blocos diretos por `1.5rem`; o inset da página continua pertencendo a
-`Page`. Uma grade, lista compacta ou linha horizontal fica dentro de um wrapper próprio.
+`contentClassName?: string` configura largura e alinhamento do container interno.
 
-| Propriedade | Tipo                          | Descrição                                                 |
-| ----------- | ----------------------------- | --------------------------------------------------------- |
-| `children`  | `ReactNode`                   | Blocos principais, separados pelo ritmo estrutural.       |
-| `className` | `string`                      | Classes de ocupação, overflow, alinhamento ou tipografia. |
-| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container.                |
+`PageBody` separa seus blocos diretos por `1rem` e fornece os recuos internos. Uma grade, lista compacta ou linha horizontal fica dentro de um wrapper próprio.
+
+| Propriedade | Tipo                          | Descrição                                           |
+| ----------- | ----------------------------- | --------------------------------------------------- |
+| `children`  | `ReactNode`                   | Blocos principais, separados pelo ritmo estrutural. |
+| `className` | `string`                      | Classes do viewport: ocupação e overflow.           |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container.          |
 
 Em uma `Page` com `layout="fill"`, o `PageBody` vira coluna flexível sozinho quando contém uma `ActionList` que
 ocupa a altura.
@@ -431,8 +476,63 @@ ocupa a altura.
 
 ## Propriedades de PageDescription
 
-| Propriedade | Tipo | Padrão | Descrição |
-| --- | --- | --- | --- |
-| `children` | `ReactNode` | | Orientação breve e opcional; filho direto de `PageHeader`. |
-| `className` | `string` | | Ajusta a apresentação do parágrafo. |
-| `…props` | `HTMLAttributes<HTMLParagraphElement>` | | Atributos nativos. |
+| Propriedade | Tipo                                   | Padrão | Descrição                                                                 |
+| ----------- | -------------------------------------- | ------ | ------------------------------------------------------------------------- |
+| `children`  | `ReactNode`                            |        | Orientação breve e opcional; filho direto da intro ou do header compacto. |
+| `className` | `string`                               |        | Ajusta a apresentação do parágrafo.                                       |
+| `…props`    | `HTMLAttributes<HTMLParagraphElement>` |        | Atributos nativos.                                                        |
+
+## Composição compacta
+
+Quando o cabeçalho também identifica o conteúdo, mantenha o título nele e omita a intro.
+Não declare o mesmo título nas duas regiões.
+
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageTitle>Preferências</PageTitle>
+  </PageHeader>
+  <PageBody>Configurações da conta.</PageBody>
+</Page>
+```
+
+## Propriedades de PageIntro
+
+Aceita atributos HTML de `div` e exige um `PageTitle`. Recebe opcionalmente `PageDescription` e
+`PageIntroActions`. Deve abrir o `PageBody`; navegação e ações da superfície ficam no header.
+
+| Propriedade | Tipo                          | Descrição                                                                |
+| ----------- | ----------------------------- | ------------------------------------------------------------------------ |
+| `children`  | `ReactNode`                   | Um `PageTitle` e, opcionalmente, `PageDescription` e `PageIntroActions`. |
+| `className` | `string`                      | Classes adicionais da introdução.                                        |
+| demais      | Atributos de `HTMLDivElement` | Repassados à região introdutória.                                        |
+
+## Propriedades de PageIntroActions
+
+Agrupa ações locais do conteúdo no extremo oposto ao título da intro.
+
+| Propriedade | Tipo                          | Descrição                                       |
+| ----------- | ----------------------------- | ----------------------------------------------- |
+| `children`  | `ReactNode`                   | Controles relacionados ao conteúdo apresentado. |
+| `className` | `string`                      | Classes adicionais do agrupamento.              |
+| demais      | Atributos de `HTMLDivElement` | Repassados ao agrupamento.                      |
+
+O header ocupa toda a largura disponível. O limite de 80rem e o recuo pertencem ao conteúdo
+interno do Body; o viewport ocupa a largura da página para manter sua barra de rolagem na extremidade.
+
+### Divisão visual das regiões
+
+Use `surfaceLayout="sectioned"` (padrão) para separar header, body e footer com divisores.
+Use `surfaceLayout="continuous"` para uma composição sem divisores. O header vazio continua
+omitido. Essa escolha é independente de `layout="flow" | "fill"`, que controla a altura e a rolagem.
+
+## Largura e rolagem
+
+`Page` e `PageBody` aceitam `contentClassName` para o container interno de leitura.
+Use `contentClassName="max-w-none"` para largura total ou `max-w-5xl` para uma leitura
+mais estreita, mantendo o header e a barra de rolagem na extremidade. `className` em Page
+controla a moldura externa; em PageBody, controla o viewport.
+
+PageShell permite rolagem de contingência quando a rota renderiza um fallback ou um
+wrapper sem altura definida. Para manter o header fixo, a rota deve preservar a cadeia
+flexível de altura até Page. Uma Page diretamente no shell já segue esse contrato.

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

@@ -33,9 +33,8 @@ a largura cresce quando o número precisa de mais espaço.
 ## Números longos
 
 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 ícone de `0.875rem`. Os
-números não têm um degrau textual de `1.75rem` na escala e, por isso, recebem a mesma medida por
-`className`, como no exemplo.
+elipse usam `size="icon-sm"`, o quadrado de `2rem` da escala única, com ícone de `0.875rem`. Os
+números usam `size="sm"`, com a mesma altura e largura mínima, crescendo para acomodar os dígitos.
 
 ```tsx preview
 <Pagination>
@@ -44,16 +43,16 @@ números não têm um degrau textual de `1.75rem` na escala e, por isso, recebem
       <PaginationPrevious href="#" iconOnly size="icon-sm" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#" page={1} className="h-7 min-w-7 text-xs" />
+      <PaginationLink href="#" page={1} size="sm" className="text-xs" />
     </PaginationItem>
     <PaginationItem>
       <PaginationEllipsis size="icon-sm" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#" page={5726} className="h-7 min-w-7 text-xs" />
+      <PaginationLink href="#" page={5726} size="sm" className="text-xs" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#" page={5727} isActive className="h-7 min-w-7 text-xs" />
+      <PaginationLink href="#" page={5727} isActive size="sm" className="text-xs" />
     </PaginationItem>
     <PaginationItem>
       <PaginationNext href="#" iconOnly size="icon-sm" />
@@ -135,7 +134,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` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. Os `icon-*` são quadrados. Nos tamanhos textuais, a altura fica fixa em 2.25rem com largura mínima quadrada que cresce para números longos, então `size="sm"` não reduz a altura; para uma barra mais baixa, use um `icon-*` ou ajuste por `className` (ex.: `h-7 min-w-7 text-xs`). |
+| `size` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. Os `icon-*` são quadrados; os tamanhos textuais preservam a mesma altura, com largura mínima quadrada que cresce para números longos. |
 
 ## Propriedades de PaginationPrevious e PaginationNext
 
@@ -143,7 +142,7 @@ 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. |
-| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. Sem `iconOnly`, a altura permanece 2.25rem em qualquer tamanho textual, como em `PaginationLink`. |
+| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. Com ou sem `iconOnly`, a altura acompanha o tamanho escolhido, como em `PaginationLink`. |
 | `iconClassName` | `string` | | Classes aplicadas ao ícone da seta, quando o glifo da escala não servir. |
 
 ## Propriedades de PaginationEllipsis

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

@@ -89,14 +89,15 @@ fundo sustenta o modal, mas não é uma etapa para onde voltar. Formulários mod
 rodapé pelo conteúdo, com `Cancelar` em `ghost` e a ação principal sólida.
 
 Dentro de [`PageShell`](/ui/page), a superfície `page` usa a anatomia real da aplicação. O
-`PageHeader` reúne a navegação contextual, o título e as ações globais; o corpo vai para `PageBody`,
-com `PageFooter` quando há ações de rodapé.
+`PageHeader` reúne navegação e ações globais; o título abre o corpo na intro, e `PageFooter`
+recebe ações de rodapé. Comandos textuais nos headers de todas as superfícies usam `sm`; retorno e assistente
+usam `icon-sm`. O rodapé preserva `default`.
 
 Uma Presentation de listagem exibida como página muda essa distribuição para manter a criação perto
 da coleção. O `PageBody` recebe um [`Surface`](/ui/surface) com a
 [`ActionList`](/ui/action-list), e o cabeçalho desse `Surface` recebe o título e os comandos
 declarados com `placement: "header"`, no extremo oposto ao título. Os comandos de cabeçalho usam o
-tamanho `default` e permanecem textuais, mesmo quando a action declara um ícone: o que abre outra
+tamanho `sm` e permanecem textuais, mesmo quando a action declara um ícone: o que abre outra
 Presentation é um `Button` sólido, e uma action `simple` vira um
 [`ActionTrigger`](/ui/action-trigger) `ghost`. O rótulo vem do `label` da action, como `Criar workspace`.
 

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

@@ -59,11 +59,11 @@ const runtime = createRuntime({
   queue,
 })
 
-export const relatorioGerar = bindAction(relatorioGerarContract, {
+export const reportGenerate = bindAction(reportGenerateContract, {
   background: { enabled: true, retry: { attempts: 3 }, progress: true },
   handler: async (ctx, input, loaded, progress) => {
     await progress?.report({ percent: 50, message: 'Consultando dados' })
-    return gerarRelatorio(input)
+    return generateReport(input)
   },
 })
 ```

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

@@ -76,5 +76,5 @@ o erro de uso.
 
 `navigate` espera um caminho da própria origem e não valida destinos. Quando o destino vem de fora,
 como o `?redirect=` de um pós-login, valide-o antes de navegar: resolva com
-`new URL(valor, origin)` e compare o `origin` do resultado, em vez de conferir apenas o prefixo do
+`new URL(target, origin)` e compare o `origin` do resultado, em vez de conferir apenas o prefixo do
 texto.

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

@@ -47,26 +47,26 @@ Declare o schedule com `defineSchedule` e registre-o no domínio, ao lado da act
 
 ```ts
 import { createRuntime, defineDomain, defineSchedule } from '@softize/opus/core'
-import { caixaFechar } from './caixa-fechar.ts' // a action 'caixa.fechar', preparada abaixo
+import { ledgerClose } from './ledger-close.ts' // a action 'ledger.close', preparada abaixo
 
-const fecharDia = defineSchedule({
-  name: 'caixa.fechar-dia',
-  action: 'caixa.fechar',
+const closeDay = defineSchedule({
+  name: 'ledger.close-day',
+  action: 'ledger.close',
   cron: '0 23 * * *',
   timezone: 'America/Sao_Paulo',
 })
 
-export const caixaDomain = defineDomain({
-  name: 'caixa',
-  actions: { caixaFechar },
-  schedules: [fecharDia],
+export const ledgerDomain = defineDomain({
+  name: 'ledger',
+  actions: { ledgerClose },
+  schedules: [closeDay],
 })
 
 const runtime = createRuntime({
   // …server/data…
   scheduler,
 })
-runtime.register([caixaDomain])
+runtime.register([ledgerDomain])
 await runtime.start()
 ```
 
@@ -91,18 +91,18 @@ recusa o sistema até que o contrato dela aceite essa execução com `automatabl
 ```ts
 import { defineContract, isSystemActor } from '@softize/opus/core'
 
-export const caixaFecharContract = defineContract({
-  name: 'caixa.fechar',
+export const ledgerCloseContract = defineContract({
+  name: 'ledger.close',
   kind: 'simple',
   input: z.object({}),
-  output: z.object({ fechados: z.number() }),
+  output: z.object({ closedEntries: z.number() }),
   automatable: true,
 })
 
-export const caixaFechar = bindAction(caixaFecharContract, {
+export const ledgerClose = bindAction(ledgerCloseContract, {
   // O sistema não tem permissões: aceite-o de forma explícita ao lado da regra das pessoas.
-  authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar'),
-  handler: async (ctx) => ({ fechados: await caixa.fecharDia() }),
+  authorize: (ctx) => isSystemActor(ctx) || ctx.can('ledger:close'),
+  handler: async (ctx) => ({ closedEntries: await ledger.closeDay() }),
 })
 ```
 

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

@@ -16,7 +16,7 @@ render(
     title="Dispositivos conectados"
     count={3}
     description="Sessões com acesso à sua conta."
-    actions={<Button variant="outline">Encerrar outras sessões</Button>}
+    actions={<Button variant="outline" size="sm">Encerrar outras sessões</Button>}
   >
     <p className="text-sm text-muted-foreground">MacBook Pro · ativo agora</p>
   </Surface>,
@@ -50,7 +50,10 @@ Três propriedades independentes definem a aparência:
 - `layout` escolhe entre o ritmo contínuo e as faixas com divisores.
 
 Uma superfície com moldura ou com fundo passa a aplicar o recuo de `1rem` nas suas regiões; você não
-escreve classes de padding no header, no corpo ou no rodapé.
+escreve classes de padding no header, no corpo ou no rodapé. O header delimitado usa
+`1rem` em todos os lados e linha mínima de `2rem`, como Page, Dialog e Drawer.
+Declare `sm` para botões textuais e `icon-sm` para ícones; Pane usa a mesma geometria
+quando hospeda Surface. Seções sem moldura e legendas recortadas não ganham padding de barra.
 
 ```tsx preview col
 render(
@@ -400,7 +403,7 @@ render(
     as="section"
     level={1}
     title="Clientes"
-    actions={<Button>Criar cliente</Button>}
+    actions={<Button size="sm">Criar cliente</Button>}
   >
     <p className="text-sm text-muted-foreground">
       A lista de clientes ocupa o corpo.
@@ -409,7 +412,7 @@ render(
 );
 ```
 
-A criação usa um `Button` textual na variante padrão e no tamanho `default`, sem ícone, nomeado
+A criação usa um `Button` textual na variante padrão e no tamanho `sm`, sem ícone, nomeado
 `Criar {recurso}`; o diálogo aberto por ele repete esse título, e a edição usa `Editar {recurso}`.
 
 Em uma [`Page`](/ui/page) com `layout="fill"`, a coleção ocupa a altura da página e rola só os
@@ -495,7 +498,7 @@ As demais propriedades são as nativas do elemento escolhido em `as`.
 
 ## Propriedades de SurfaceBody
 
-Os filhos diretos recebem o ritmo estrutural de `1.5rem`. O layout da `Surface` decide o inset;
+Os filhos diretos recebem o ritmo estrutural de `1rem`. O layout da `Surface` decide o inset;
 um wrapper filho declara relações locais mais compactas.
 
 | Propriedade | Tipo        | Padrão  | Descrição                                                              |

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

@@ -38,25 +38,30 @@ mostrar somente o ícone, declare `aria-label` para preservar seu nome acessíve
 </Tabs>
 ```
 
+A barra e o painel ficam separados por `1rem`. O painel organiza seus blocos diretos com
+o mesmo intervalo. Sem moldura, não há padding inferior: o hospedeiro fornece o recuo externo.
+Não adicione margem ou padding para repetir esses intervalos.
+
 ## Emoldurar abas e painéis
 
 Use `framed` quando a navegação e seus painéis precisarem formar um único bloco. A propriedade
 reúne borda, raio e recorte no próprio `Tabs`, mas não aplica fundo: o bloco herda a
 superfície em que foi composto. Por isso, não envolva `Tabs` em um `Surface` somente para obter essa
-moldura.
+moldura. O painel horizontal recebe `1rem` nas laterais e embaixo; o intervalo da barra
+fornece o espaço superior. Na orientação vertical, a moldura recebe `1rem` ao redor da composição.
 
 ```tsx preview col
-<Tabs defaultValue="overview" framed className="gap-0">
+<Tabs defaultValue="overview" framed>
   <TabsList>
     <TabsListItem value="overview">Visão geral</TabsListItem>
     <TabsListItem value="history">Histórico</TabsListItem>
   </TabsList>
-  <TabsPanel value="overview" className="p-4">
+  <TabsPanel value="overview">
     <p className="text-sm text-muted-foreground">
       Resumo do workspace Empresa X.
     </p>
   </TabsPanel>
-  <TabsPanel value="history" className="p-4">
+  <TabsPanel value="history">
     <p className="text-sm text-muted-foreground">
       Alterações recentes do workspace.
     </p>
@@ -196,3 +201,6 @@ do gatilho.
 | ------------ | -------- | ------ | ----------------------------------------------------------------------- |
 | `value`      | `string` |        | Identificador do painel, igual ao `value` do `TabsListItem` que o abre. |
 | `forceMount` | `true`   |        | Mantém o painel montado mesmo quando outra aba está ativa.              |
+
+Painéis com `forceMount` continuam montados quando inativos, mas ficam ocultos. Isso preserva
+o estado de editores sem exibir simultaneamente o conteúdo de abas diferentes.