@softize/opus 18.4.0 → 19.0.0

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

@@ -0,0 +1,250 @@
+## A coluna encaixada em um layout
+
+Use `Pane` para a coluna ou faixa que ocupa uma das posições de um [`Split`](/ui/split): a
+navegação à esquerda, o inspetor à direita, a lista que abre o detalhe ao lado. O `Split` decide a
+relação espacial e o redimensionamento; o `Pane` decide o que existe dentro da área recebida.
+
+No formato mais simples, o pane é uma caixa com recuo e o conteúdo é seu.
+
+```tsx preview
+render(
+  <div className="h-56 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="16rem" className="bg-muted/30">
+        <p className="text-sm text-muted-foreground">Navegação.</p>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conteúdo.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+## Cabeçalho, corpo e rodapé
+
+Quando a área precisa de regiões fixas e de um corpo que rola, componha os slots. `PaneHeader`
+nomeia a região, `PaneBody` ocupa o espaço restante e concentra a rolagem vertical, e `PaneFooter`
+mantém à vista o que não pode sair da tela.
+
+```tsx preview
+render(
+  <div className="h-72 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="18rem">
+        <PaneHeader>
+          <PaneMedia>
+            <MessagesSquare />
+          </PaneMedia>
+          <PaneTitle>Conversas</PaneTitle>
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
+              <SquarePen />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody className="space-y-1">
+          <p className="text-sm">Revisão do contrato</p>
+          <p className="text-sm text-muted-foreground">Importação de clientes</p>
+          <p className="text-sm text-muted-foreground">Fila de execuções</p>
+        </PaneBody>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Ver arquivadas</Button>
+        </PaneFooter>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+O cabeçalho reconhece quatro slots — `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions` —
+e monta a linha sozinho: mídia, título e descrição de um lado, ações no extremo oposto. A ordem em
+que os slots são escritos não altera a posição, e um nó que não seja um desses slots interrompe a
+renderização com um erro. Conteúdo livre vai para `PaneBody`.
+
+Título e descrição truncam quando a coluna encolhe, em vez de quebrar a altura da faixa.
+
+## Escolher entre seccionado e contínuo
+
+`layout` declara a anatomia da superfície inteira e fica no root; os slots leem esse valor e não o
+recebem. Cada valor é um pacote de recuo, ritmo vertical e divisores.
+
+| Aspecto | `sectioned` (padrão) | `continuous` |
+| --- | --- | --- |
+| Divisores | entre as regiões vizinhas | nenhum |
+| Faixa do cabeçalho | altura fixa de `3.75rem` | acompanha o conteúdo |
+| Ritmo vertical | regiões simétricas | o cabeçalho se aproxima do corpo |
+
+O padrão `sectioned` é o pane de operação: a faixa do cabeçalho tem a mesma altura da barra do
+[`PageShell`](/ui/page), então uma navegação lateral e o chrome da página se alinham na mesma
+linha. Use `continuous` quando o pane for um bloco de leitura contínuo, sem fronteiras a marcar.
+
+Os divisores são derivados da vizinhança: cada região desenha a linha quando há uma região do outro
+lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um rodapé produz uma
+linha só. A tela não escreve `border-b` nem `border-t`.
+
+## Recuo do pane e recuo das regiões
+
+`inset` é o respiro interno do pane sem slots: `md` por padrão, com `none`, `sm` e `lg`
+disponíveis. Quando `PaneHeader`, `PaneBody` ou `PaneFooter` são filhos **diretos** do pane, o recuo
+passa a ser de cada região e o `inset` vira `none` sozinho — é o que permite ao divisor alcançar a
+borda da coluna.
+
+O ajuste enxerga só o primeiro nível. Se os slots vierem dentro de outro componente — é o caso da
+`Sidebar`, que traz a superfície e o colapso —, o pane não sabe que eles existem: declare
+`inset="none"` você mesmo, ou a coluna ganha um recuo que empurra o divisor para dentro.
+
+## A matriz de layouts e slots
+
+As regiões são independentes e o recuo se ajusta a cada combinação, nos dois layouts.
+
+```tsx preview col
+render(
+  <div className="grid gap-4 md:grid-cols-2">
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneHeader>
+          <PaneTitle>Seccionado</PaneTitle>
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+              <Ellipsis />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Cabeçalho, corpo e rodapé.</p>
+        </PaneBody>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Configurações</Button>
+        </PaneFooter>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane layout="continuous" className="h-full">
+        <PaneHeader>
+          <PaneMedia>
+            <ChartNoAxesColumn />
+          </PaneMedia>
+          <PaneTitle>Contínuo com mídia</PaneTitle>
+          <PaneDescription>O espaço separa as regiões.</PaneDescription>
+        </PaneHeader>
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Sem rodapé e sem divisores.</p>
+        </PaneBody>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Só corpo: nenhuma fronteira a marcar.</p>
+        </PaneBody>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneHeader>
+          <PaneMedia context="primary">
+            <Folder />
+          </PaneMedia>
+          <PaneTitle>Sem corpo</PaneTitle>
+        </PaneHeader>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Ação persistente</Button>
+        </PaneFooter>
+      </Pane>
+    </div>
+  </div>,
+);
+```
+
+## Onde termina o Pane
+
+Três componentes dividem a responsabilidade de uma coluna, e trocá-los de papel é a origem mais
+comum de layout duplicado:
+
+| Componente | Responsabilidade |
+| --- | --- |
+| [`Split`](/ui/split) | Relação espacial entre as áreas e, com `resizable`, o arraste da fronteira. |
+| `Pane` | Tamanho recebido, recuo e as regiões internas: cabeçalho, corpo e rodapé. |
+| [`Sidebar`](/ui/sidebar) | Superfície da navegação lateral e o estado de colapso dos destinos. |
+
+Tamanho inicial, limites e persistência do layout são declarados no `Pane` e operados pelo `Split`
+— a [página do Split](/ui/split) trata deles. Uma `Sidebar` é composta dentro de um `Pane` e usa os
+mesmos slots para o próprio cabeçalho e rodapé; ela não tem regiões próprias.
+
+## Hierarquia do título
+
+`PaneTitle` é um heading. `level` escolhe a hierarquia do documento, de `1` a `6`, com `2` como
+padrão. O tamanho visual vem da família e do `layout`, não do nível, então corrigir a estrutura do
+documento não muda a aparência da faixa.
+
+## Propriedades de Pane
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `layout` | `'continuous' \| 'sectioned'` | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. |
+| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`, ou `'none'` com slots diretos | Respiro interno do pane sem slots; slots dentro de outro componente exigem declarar. |
+| `id` | `string` | | Identidade estável usada pelo layout redimensionável e persistido. |
+| `initialSize` | `number \| string` | | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
+| `minSize` / `maxSize` | `number \| string` | | Limites aplicados pelo `Split` quando ele é redimensionável. |
+| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
+| `className` | `string` | | Ajusta a coluna. |
+| `children` | `ReactNode` | | Conteúdo direto ou os slots estruturais. |
+
+## Propriedades de PaneHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Somente `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada. |
+| `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |
+
+## Propriedades de PaneMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'xs'` | Tamanho da moldura e do glifo na escala compartilhada. |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor. |
+| `variant` | `'subtle' \| 'outline'` | `'subtle'` | Usa preenchimento tonal ou acrescenta borda. |
+| `className` | `string` | | Ajusta a moldura sem substituir a escala. |
+| `asChild` | `boolean` | `false` | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+
+## Propriedades de PaneTitle
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `className` | `string` | | Ajusta o título, que trunca quando não cabe. |
+
+## Propriedades de PaneDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Frase curta de apoio sob o título; trunca quando não cabe. |
+| `className` | `string` | | Ajusta a descrição. |
+
+## Propriedades de PaneActions
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Controles no extremo oposto ao título. |
+| `className` | `string` | | Ajusta o agrupamento das ações. |
+
+## Propriedades de PaneBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
+| `className` | `string` | | Ajusta a região flexível e rolável. |
+
+`PaneContent` continua exportado como alias depreciado de `PaneBody` e sai em uma próxima versão
+maior. Código novo usa `PaneBody`.
+
+## Propriedades de PaneFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
+| `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |

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

@@ -1,8 +1,8 @@
 ## Navegação dentro de um layout
 
 Use `Sidebar` para apresentar navegação global ou contextual em uma coluna lateral. O componente
-organiza a superfície e compartilha o estado de colapso; posição e largura pertencem a um `Pane`
-dentro de `Split`.
+organiza a superfície e compartilha o estado de colapso; posição e largura pertencem a um
+[`Pane`](/ui/pane) dentro de [`Split`](/ui/split).
 
 O exemplo canônico mantém a largura inicial em `rem`, deixa a navegação rolar e preserva o
 cabeçalho e o rodapé nas extremidades.
@@ -13,8 +13,8 @@ render(
     <Split>
       <Pane initialSize="16rem" inset="none">
         <Sidebar className="w-full">
-          <PaneHeader className="px-4 py-3 text-sm font-semibold">
-            Projeto
+          <PaneHeader>
+            <PaneTitle>Projeto</PaneTitle>
           </PaneHeader>
           <PaneBody>
             <SidebarNav
@@ -50,22 +50,17 @@ divisória ao lado do handle.
 
 ## Anatomia e responsabilidades
 
-Cada parte possui uma responsabilidade única. Essa separação permite reutilizar os mesmos slots em
-uma sidebar fixa, redimensionável ou recolhida.
+A `Sidebar` não tem regiões próprias: o cabeçalho, o corpo rolável e o rodapé são os slots do
+`Pane` que a hospeda, com a anatomia e as propriedades descritas na
+[página da família](/ui/pane).
 
 | Parte | Responsabilidade |
 |---|---|
-| `Split` | Define a relação espacial e, opcionalmente, o redimensionamento. |
-| `Pane` | Define largura, limites e espaçamento interno da coluna. |
+| [`Split`](/ui/split) | Define a relação espacial e, opcionalmente, o redimensionamento. |
+| [`Pane`](/ui/pane) | Define largura e limites da coluna e estrutura suas regiões. |
 | `Sidebar` | Desenha a superfície lateral e fornece o estado de colapso. |
-| `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` | Apresenta e controla os destinos de navegação. |
 
-`PaneContent` continua exportado como alias depreciado de `PaneBody`. Código novo usa
-`PaneBody`.
-
 ## Escolher a navegação
 
 Use `SidebarNav` para grupos planos de destinos. Ele recebe dados e produz `SidebarItem` com a mesma
@@ -151,15 +146,17 @@ const [collapsed, setCollapsed] = useState(false)
 render(
   <div className="flex h-64 overflow-hidden rounded-lg border border-border">
     <Sidebar collapsed={collapsed}>
-      <PaneHeader className="flex h-12 items-center justify-center">
-        <Button
-          variant="ghost"
-          size="icon-sm"
-          aria-label={collapsed ? 'Expandir navegação' : 'Recolher navegação'}
-          onClick={() => setCollapsed((current) => !current)}
-        >
-          <PanelLeftClose className={collapsed ? 'rotate-180' : ''} />
-        </Button>
+      <PaneHeader>
+        <PaneActions>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label={collapsed ? 'Expandir navegação' : 'Recolher navegação'}
+            onClick={() => setCollapsed((current) => !current)}
+          >
+            <PanelLeftClose className={collapsed ? 'rotate-180' : ''} />
+          </Button>
+        </PaneActions>
       </PaneHeader>
       <PaneBody>
         <SidebarNav
@@ -241,26 +238,8 @@ O driver de drag-and-drop continua externo e fornece seus atributos por `dragPro
 | `className` | `string` | | Ajusta a raiz. A largura externa deve continuar pertencendo ao `Pane`. |
 | `children` | `ReactNode` | | Cabeçalho, corpo, rodapé ou uma navegação que gerencie a própria estrutura. |
 
-## Propriedades de PaneHeader
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
-| `children` | `ReactNode` | | Identidade, contexto ou ações apresentadas no topo. |
-
-## Propriedades de PaneBody
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a região flexível e rolável. |
-| `children` | `ReactNode` | | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
-
-## Propriedades de PaneFooter
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
-| `children` | `ReactNode` | | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
+`PaneHeader`, `PaneBody` e `PaneFooter` são os slots da família `Pane`; a referência deles está na
+[página do Pane](/ui/pane).
 
 ## Propriedades de SidebarNav
 

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

@@ -15,15 +15,19 @@ avatares e barras com dimensões próximas às linhas de texto esperadas.
 
 ## Card em carregamento
 
-O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para a tela não pular quando os dados chegarem.
+O esqueleto reproduz o layout final do card — título, conteúdo e ações — para a tela não pular
+quando os dados chegarem. O título entra pelo slot do cabeçalho com `asChild`, porque o
+`CardHeader` só aceita os próprios slots.
 
 ```tsx preview col
 <Card>
   <CardHeader>
-    <Skeleton className="h-5 w-40" />
-    <Skeleton className="h-4 w-56" />
+    <CardTitle asChild>
+      <Skeleton className="h-5 w-40" />
+    </CardTitle>
   </CardHeader>
   <CardBody className="space-y-2">
+    <Skeleton className="h-4 w-56" />
     <Skeleton className="h-4 w-full" />
     <Skeleton className="h-4 w-3/4" />
   </CardBody>

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

@@ -8,10 +8,10 @@ layout permanece estático.
 render(
   <div className="h-72 overflow-hidden rounded-lg border border-border">
     <Split resizable>
-      <Pane initialSize={30} minSize={20} inset="none" className="bg-muted/30">
-        <div className="p-4 text-sm">Navegação</div>
+      <Pane initialSize={30} minSize={20} className="bg-muted/30">
+        <p className="text-sm">Navegação</p>
       </Pane>
-      <Pane grow inset="lg">
+      <Pane grow>
         <p className="text-sm text-muted-foreground">
           Conteúdo. Arraste a divisória.
         </p>
@@ -21,26 +21,31 @@ render(
 );
 ```
 
-## Espaçamento interno
+O `Split` responde pela relação espacial e pelo arraste. O que existe dentro de cada área — o
+cabeçalho, o corpo rolável, o rodapé, o recuo e a escolha entre regiões seccionadas e contínuas —
+pertence ao [`Pane`](/ui/pane) e está documentado na página da família.
 
-`Pane` usa `inset="md"` por padrão. Use `none` para navegação e conteúdo que já controla o próprio
-espaçamento; `sm` e `lg` atendem outras densidades.
+## Tamanho de cada pane
 
-## Largura inicial
-
-Quando uma área precisa continuar legível em telas largas, use uma unidade absoluta para o tamanho inicial ou mínimo. Números continuam representando porcentagens; strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Prefira `rem` para acompanhar a escala tipográfica configurada pela aplicação.
+Cada `Pane` declara o próprio tamanho e o `Split` o aplica. Números representam porcentagens;
+strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Quando uma área precisa continuar legível em
+telas largas, use uma unidade absoluta no tamanho inicial ou mínimo, de preferência `rem`, para
+acompanhar a escala tipográfica configurada pela aplicação. `grow` entrega o espaço remanescente.
 
 ```tsx
 <Split resizable>
-  <Pane grow inset="none">
+  <Pane grow>
     <Main />
   </Pane>
-  <Pane initialSize="28rem" minSize="20rem" inset="none">
+  <Pane initialSize="28rem" minSize="20rem">
     <Inspector />
   </Pane>
 </Split>
 ```
 
+`minSize` e `maxSize` valem enquanto o `Split` é redimensionável; sem `resizable` eles não limitam
+nada.
+
 ## Persistência
 
 Um layout pode ser restaurado sem acoplar `Split` a um mecanismo específico de armazenamento. Dê um `id` estável a cada `Pane`, leia o valor salvo para formar `defaultLayout` e persista apenas mudanças concluídas pela pessoa.
@@ -135,16 +140,6 @@ render(<Example />);
 | `defaultLayout`   | `Record<string, number>`                  |                | Layout percentual restaurado, indexado pelos ids dos panes.             |
 | `onLayoutChanged` | `(layout, { isUserInteraction }) => void` |                | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
 
-## Propriedades de Pane
-
-| Propriedade           | Tipo                             | Padrão  | Descrição                                                                                 |
-| --------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
-| `id`                  | `string`                         |         | Identidade estável usada pelo layout redimensionável e persistido.                        |
-| `initialSize`         | `number \| string`               |         | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
-| `minSize` / `maxSize` | `number \| string`               |         | Limites quando o split é redimensionável.                                                 |
-| `grow`                | `boolean`                        | `false` | Ocupa o espaço remanescente no layout simples.                                            |
-| `inset`               | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`  | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio.             |
-
 ## Propriedades de SurfaceAssistant
 
 | Propriedade      | Tipo        | Padrão  | Descrição                                               |

package/src/ui/docs/registry.tsx

@@ -68,6 +68,7 @@ import chatMd from "./content/chat.md?raw";
 import checkboxMd from "./content/checkbox.md?raw";
 import collapsibleMd from "./content/collapsible.md?raw";
 import iconPickerMd from "./content/icon-picker.md?raw";
+import iconTileMd from "./content/icon-tile.md?raw";
 import commandMd from "./content/command.md?raw";
 import composerMd from "./content/composer.md?raw";
 import copyableMd from "./content/copyable.md?raw";
@@ -124,6 +125,7 @@ import actionSearchDialogMd from "./content/action-list-dialog.md?raw";
 import pageMd from "./content/page.md?raw";
 import presentationMd from "./content/presentation.md?raw";
 import contentMd from "./content/content.md?raw";
+import paneMd from "./content/pane.md?raw";
 import sidebarMd from "./content/sidebar.md?raw";
 import splitMd from "./content/split.md?raw";
 import routerMd from "./content/router.md?raw";
@@ -417,8 +419,13 @@ export const UI_SECTIONS: DocSection[] = [
         pages: [
           {
             slug: "split",
-            title: "Split & Pane",
-            render: pattern("Split & Pane", "split", splitMd),
+            title: "Split",
+            render: pattern("Split", "split", splitMd),
+          },
+          {
+            slug: "pane",
+            title: "Pane",
+            render: pattern("Pane", "pane", paneMd),
           },
           {
             slug: "sidebar",
@@ -697,6 +704,11 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Empty Value",
             render: comp("Empty Value", "empty-value", emptyValueMd),
           },
+          {
+            slug: "icon-tile",
+            title: "Icon Tile",
+            render: comp("Icon Tile", "icon-tile", iconTileMd),
+          },
           { slug: "item", title: "Item", render: comp("Item", "item", itemMd) },
           { slug: "kbd", title: "Kbd", render: comp("Kbd", "kbd", kbdMd) },
           {

package/src/ui/meta.ts

@@ -53,6 +53,12 @@ export const componentMeta = {
     whenToUse:
       "Sinal compacto de estado. `context` declara neutral/primary/info/success/warning/danger e `variant` escolhe solid/outline. Passe `label` quando a cor reforçar informação; sem label, o ponto é decorativo. Para texto visível, use Badge.",
   },
+  "icon-tile": {
+    name: "icon-tile",
+    ancestry: "opus",
+    whenToUse:
+      "Dê suporte visual não interativo a um ícone com tamanho, contexto, preenchimento e arredondamento consistentes. Componha-o nos slots que pedem a moldura; passe o ícone diretamente quando ela não for necessária. Para uma ação, use Button com tamanho de ícone.",
+  },
   detail: {
     name: "detail",
     ancestry: "opus",
@@ -117,7 +123,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "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. Em coleções, Content mantém título e criação junto do ActionList. Contadores pertencem a Content e não ao título da Page.",
+      'Estruture uma região com título e corpo. No caso comum, declare título, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `as="fieldset"` para agrupar campos sob uma legenda nativa e `frameVariant="legend"` somente quando essa legenda precisar integrar visualmente a borda. Componha ContentHeader apenas quando precisar controlar a anatomia.',
   },
   copyable: {
     name: "copyable",
@@ -279,7 +285,7 @@ export const componentMeta = {
     name: "field",
     ancestry: "shadcn",
     whenToUse:
-      "Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado; `responsive` continua aceito como alias da horizontal. Field cuida do layout; o formulário continua responsável por estado e validação.",
+      'Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado. FieldGroup organiza vários campos; quando o conjunto precisar de título, componha-o dentro de Content com `as="fieldset"`.',
   },
   "input-otp": {
     name: "input-otp",
@@ -321,13 +327,19 @@ export const componentMeta = {
     name: "split",
     ancestry: "opus",
     whenToUse:
-      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial e mínimo; a anatomia do pane tem página própria. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
   },
   sidebar: {
     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 e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios ficam em PaneHeader e PaneFooter.",
+      "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. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios são do Pane que a hospeda.",
+  },
+  pane: {
+    name: "pane",
+    ancestry: "opus",
+    whenToUse:
+      "Estruture a coluna ou faixa encaixada num Split: PaneHeader nomeia a região e leva mídia e ações, PaneBody rola e PaneFooter fixa o que precisa ficar à vista. `layout` escolhe entre regiões seccionadas, com divisores derivados da vizinhança, e o fluxo contínuo. O `inset` vale para o pane sem slots; com eles, o recuo é de cada região.",
   },
   "scroll-area": {
     name: "scroll-area",
@@ -382,7 +394,7 @@ export const componentMeta = {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. Em uma página, envolva a lista com Content para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Content para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",

package/src/ui/react.tsx

@@ -93,6 +93,7 @@ export type {
 export {
   Card,
   CardHeader,
+  CardMedia,
   CardTitle,
   CardDescription,
   CardAction,
@@ -132,7 +133,9 @@ export {
   DialogOverlay,
   DialogContent,
   DialogHeader,
+  DialogNavigation,
   DialogMedia,
+  DialogActions,
   DialogBody,
   DialogFooter,
   DialogTitle,
@@ -143,6 +146,10 @@ export type {
   DialogMode,
 } from "./components/primitives/dialog.tsx";
 
+// O pacote de anatomia que Card, Dialog, Drawer e Pane declaram no root (ADR 0023). As
+// tabelas e o contexto continuam internos; o consumidor escolhe entre os dois nomes.
+export type { SurfaceLayout } from "./components/patterns/surface-anatomy.ts";
+
 export {
   Menu,
   MenuTrigger,
@@ -270,10 +277,13 @@ export {
 } from "./components/primitives/collapsible.tsx";
 export {
   Drawer,
+  DrawerActions,
   DrawerClose,
   DrawerContent,
   DrawerFooter,
   DrawerHeader,
+  DrawerMedia,
+  DrawerNavigation,
   DrawerBody,
   DrawerTitle,
   DrawerTrigger,
@@ -298,6 +308,21 @@ export {
   FieldSet,
   FieldTitle,
 } from "./components/primitives/field.tsx";
+export type {
+  FieldSetProps,
+  FieldSetVariant,
+} from "./components/primitives/field.tsx";
+export {
+  IconTile,
+  iconTileVariants,
+  resolveIconTileStyle,
+} from "./components/primitives/icon-tile.tsx";
+export type {
+  IconTileContext,
+  IconTileProps,
+  IconTileSize,
+  IconTileVariant,
+} from "./components/primitives/icon-tile.tsx";
 export {
   InputGroup,
   InputGroupAddon,
@@ -471,6 +496,8 @@ export {
 export type {
   ContentProps,
   ContentHeaderProps,
+  ContentElement,
+  ContentFrameVariant,
   ContentHeaderLevel,
   ContentHeaderVariant,
 } from "./components/patterns/content-header.tsx";
@@ -505,7 +532,11 @@ export type {
 
 // Barra lateral composicional: header/conteúdo/footer e navegação, sem possuir o layout.
 export {
+  PaneActions,
+  PaneDescription,
   PaneHeader,
+  PaneMedia,
+  PaneTitle,
   PaneBody,
   PaneContent,
   PaneFooter,