@softize/opus 18.4.0 → 19.0.0

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

@@ -1,6 +1,8 @@
-## Box simples
+## Caixa simples
 
-O uso mais comum: a superfície de conteúdo em repouso (`rounded-xl` + `border`), flat por padrão, com o padding pelo `className`. O Card não força flex/gap/padding — você compõe o miolo (sem brigar com `space-y`/`flex` seu). Quando a hierarquia realmente pedir elevação, declare a intensidade explicitamente, por exemplo `className="shadow-sm"`.
+O uso mais comum é a superfície em repouso: raio, borda e fundo, sem sombra. O `Card` não impõe
+flex, gap nem padding, então o miolo continua seu — inclusive o `space-y` ou o grid que a tela já
+usa. Nesse formato o recuo vem do `className`.
 
 ```tsx preview col
 <Card className="p-4">
@@ -8,9 +10,15 @@ O uso mais comum: a superfície de conteúdo em repouso (`rounded-xl` + `border`
 </Card>
 ```
 
-## Estruturado (header / conteúdo / rodapé)
+Quando a hierarquia realmente pedir elevação, declare a intensidade, por exemplo
+`className="shadow-sm"`.
 
-Para painel com estrutura: cada slot é dono do próprio padding (como o Dialog). CardTitle/CardDescription no header; CardFooter alinha as ações.
+## Cabeçalho, corpo e rodapé
+
+Quando o card tem estrutura, cada região vira um slot e traz o próprio recuo. `CardHeader`
+reconhece quatro slots — `CardMedia`, `CardTitle`, `CardDescription` e `CardAction` — 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.
 
 ```tsx preview col
 <Card>
@@ -21,55 +29,238 @@ Para painel com estrutura: cada slot é dono do próprio padding (como o Dialog)
   <CardBody>
     <p className="text-sm text-muted-foreground">Última sessão concluída há 2 horas.</p>
   </CardBody>
-  <CardFooter className="gap-2">
-    <Button size="sm">Abrir sessão</Button>
+  <CardFooter>
     <Button size="sm" variant="outline">Ver repositórios</Button>
+    <Button size="sm">Abrir sessão</Button>
   </CardFooter>
 </Card>
 ```
 
-## Com divisor
+O rodapé alinha as ações no fim da linha. Um nó que não seja um desses quatro slots dentro do
+`CardHeader` interrompe a renderização com um erro: a linha do cabeçalho pertence à família, e um
+`div` solto ali devolveria à tela a decisão de posicionamento. Conteúdo livre vai para `CardBody`.
+
+## Escolher entre contínuo e seccionado
 
-`border-b` no header / `border-t` no footer dão o divisor quando a estrutura pede separação visível. A aresta externa e os divisores internos usam o mesmo vocabulário de `border`.
+`layout` declara a anatomia da superfície inteira e fica no root. Não é uma borda ligada ou
+desligada: cada valor é um pacote de recuo, ritmo vertical, escala do título e divisores.
+
+| Aspecto | `continuous` (padrão) | `sectioned` |
+| --- | --- | --- |
+| Divisores | nenhum | entre as regiões vizinhas |
+| Ritmo vertical | o cabeçalho se aproxima do corpo; o espaço separa | regiões simétricas; o divisor separa |
+| Recuo lateral | mais folgado, para leitura | o mesmo das demais superfícies de operação |
+| Escala do título | um degrau acima | um degrau mais contida |
+
+Use `continuous` no card de leitura, que apresenta um assunto e termina. Use `sectioned` quando o
+card for uma superfície de operação — regiões com pesos diferentes, lista dentro do corpo, rodapé
+com ações — ou quando ele precisar conviver com um [`Dialog`](/ui/dialog), um
+[`Drawer`](/ui/drawer) ou um [`Pane`](/ui/pane) sem degrau visível entre eles.
 
 ```tsx preview col
-<Card>
-  <CardHeader className="border-b">
-    <CardTitle>Skill code-style</CardTitle>
-    <CardDescription>Padrão softize de código e microcopy.</CardDescription>
+render(
+  <div className="grid gap-4 md:grid-cols-2">
+    <Card>
+      <CardHeader>
+        <CardTitle>Contínuo</CardTitle>
+        <CardDescription>O espaço separa as regiões.</CardDescription>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">Um assunto, lido de cima a baixo.</p>
+      </CardBody>
+      <CardFooter>
+        <Button size="sm" variant="outline">Abrir</Button>
+      </CardFooter>
+    </Card>
+    <Card layout="sectioned">
+      <CardHeader>
+        <CardTitle>Seccionado</CardTitle>
+        <CardDescription>O divisor separa as regiões.</CardDescription>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">Regiões com pesos diferentes.</p>
+      </CardBody>
+      <CardFooter>
+        <Button size="sm" variant="outline">Abrir</Button>
+      </CardFooter>
+    </Card>
+  </div>,
+);
+```
+
+### Os divisores são derivados
+
+Em `sectioned`, cada região desenha a própria linha quando existe uma região vizinha do outro lado.
+Um cabeçalho sozinho não fecha nada, um rodapé que é a única região também não, e um cabeçalho
+seguido direto de um rodapé produz uma linha só, em vez de duas encostadas.
+
+A tela não escreve mais `border-b` no cabeçalho nem `border-t` no rodapé. A regra depende da
+presença das regiões irmãs, que o componente conhece e a tela não.
+
+## Mídia e ações no cabeçalho
+
+`CardMedia` abre a linha com a moldura de ícone da casa — o mesmo [`IconTile`](/ui/icon-tile), na
+escala `sm`, com `context` e `variant` para declarar o significado da cor. `CardAction` fica no
+extremo oposto ao título, sem precisar de classe de alinhamento.
+
+```tsx preview col
+<Card layout="sectioned">
+  <CardHeader>
+    <CardMedia context="primary">
+      <CarFront />
+    </CardMedia>
+    <CardTitle>Revisão dos 20.000 km</CardTitle>
+    <CardDescription>Agendada para 12 de maio, às 9h.</CardDescription>
+    <CardAction>
+      <Button size="sm" variant="outline">Reagendar</Button>
+    </CardAction>
   </CardHeader>
   <CardBody>
-    <p className="text-sm text-muted-foreground">Vinculada a 4 agentes neste workspace.</p>
+    <p className="text-sm text-muted-foreground">Consultor responsável: Marina Alves.</p>
   </CardBody>
-  <CardFooter className="justify-between border-t">
-    <Badge context="success">Publicada</Badge>
-    <Button size="sm" variant="outline">Editar skill</Button>
-  </CardFooter>
 </Card>
 ```
 
-## Ação no cabeçalho
+## Hierarquia do título
 
-`CardAction` é o slot de ação do header (um botão ou menu). Quem compõe posiciona — em geral um
-`CardHeader` em `flex-row` com o título de um lado e a ação do outro.
+`CardTitle` é um heading. `level` escolhe a hierarquia do documento, de `1` a `6`, com `3` como
+padrão — um card costuma ser uma seção dentro de uma página que já tem o `h1`. O tamanho visual não
+vem daí: ele é decidido pela família e pelo `layout`, então corrigir o nível para acertar a
+estrutura do documento não muda a aparência.
 
 ```tsx preview col
 <Card>
-  <CardHeader className="flex-row items-start justify-between">
-    <div>
-      <CardTitle>Empresa X</CardTitle>
-      <CardDescription>3 agentes vinculados.</CardDescription>
-    </div>
-    <CardAction>
-      <Button size="sm" variant="outline">Editar</Button>
-    </CardAction>
+  <CardHeader>
+    <CardTitle level={2}>Qualidade da base</CardTitle>
+    <CardDescription>O nível muda a semântica; a escala continua a do layout.</CardDescription>
   </CardHeader>
 </Card>
 ```
 
+Use `asChild` quando o heading precisar vir de outro componente, como um link.
+
+## A matriz de slots
+
+As regiões são independentes: o cabeçalho existe sem corpo, o corpo existe sem cabeçalho e o rodapé
+entra apenas quando há ações persistentes. O recuo e os divisores se ajustam a cada combinação, nos
+dois layouts.
+
+```tsx preview col
+render(
+  <div className="grid gap-4 md:grid-cols-2">
+    <Card>
+      <CardHeader>
+        <CardMedia>
+          <UserRound />
+        </CardMedia>
+        <CardTitle>Contínuo com mídia</CardTitle>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">
+          Sem rodapé, o corpo reassume o respiro de baixo.
+        </p>
+      </CardBody>
+    </Card>
+    <Card>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">
+          Só corpo: o card vira uma caixa com o recuo da família.
+        </p>
+      </CardBody>
+    </Card>
+    <Card layout="sectioned">
+      <CardHeader>
+        <CardTitle>Seccionado sem corpo</CardTitle>
+        <CardAction>
+          <Button size="sm" variant="ghost">Editar</Button>
+        </CardAction>
+      </CardHeader>
+      <CardFooter>
+        <Button size="sm">Salvar</Button>
+      </CardFooter>
+    </Card>
+    <Card layout="sectioned">
+      <CardHeader>
+        <CardMedia context="success">
+          <ShieldCheck />
+        </CardMedia>
+        <CardTitle>Seccionado completo</CardTitle>
+        <CardDescription>Cabeçalho, corpo e rodapé.</CardDescription>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">Cada fronteira ganha uma linha.</p>
+      </CardBody>
+      <CardFooter>
+        <Button size="sm" variant="outline">Descartar</Button>
+        <Button size="sm">Publicar</Button>
+      </CardFooter>
+    </Card>
+  </div>,
+);
+```
+
 ## Propriedades de Card
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `asChild` | `boolean` | `false` | Renderiza o filho com a superfície do Card (ex.: um `<button>` clicável inteiro). |
-| `className` | `string` | | Compõe sobre a superfície; os slots (`CardHeader`, `CardBody`, `CardFooter`, `CardAction`) são donos do próprio padding. `CardContent` é alias depreciado de `CardBody`. |
+| `layout` | `'continuous' \| 'sectioned'` | `'continuous'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. |
+| `asChild` | `boolean` | `false` | Renderiza o filho com a superfície do Card, por exemplo um `<button>` clicável inteiro. |
+| `className` | `string` | | Compõe sobre a superfície. Sem slots, é aqui que entra o recuo da caixa. |
+
+As demais propriedades são as propriedades nativas de `div`.
+
+## Propriedades de CardHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Somente `CardMedia`, `CardTitle`, `CardDescription` e `CardAction`, no máximo um de cada. |
+| `className` | `string` | | Ajusta a faixa superior sobre o recuo do layout. |
+
+## Propriedades de CardMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'sm'` | Tamanho da moldura e do glifo na escala compartilhada dos controles. |
+| `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 CardTitle
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `asChild` | `boolean` | `false` | Usa o filho como heading, preservando a escala do título. |
+| `className` | `string` | | Ajusta o título. |
+
+## Propriedades de CardDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Frase de apoio sob o título, dentro do cabeçalho. |
+| `className` | `string` | | Ajusta a descrição. |
+
+## Propriedades de CardAction
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Controles no extremo oposto ao título, como um botão ou um menu. |
+| `className` | `string` | | Ajusta o agrupamento das ações. |
+
+## Propriedades de CardBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Conteúdo principal do card. |
+| `className` | `string` | | Ajusta a região sobre o recuo do layout. |
+
+`CardContent` continua exportado como alias depreciado de `CardBody` e sai em uma próxima versão
+maior. Código novo usa `CardBody`.
+
+## Propriedades de CardFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Ações persistentes, alinhadas no fim da linha. |
+| `className` | `string` | | Ajusta o rodapé, inclusive a distribuição das ações. |

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

@@ -4,6 +4,12 @@ Use `Content` para dar título e estrutura a uma região dentro de `PageBody`, `
 `DialogBody` ou outra superfície. Ele renderiza uma `section` ligada ao próprio título e mantém o
 espaçamento entre header e body. `ContentHeader` pertence sempre a essa estrutura; não o use solto.
 
+O `Content` é contínuo por definição e não expõe `layout`: ele é uma região nomeada dentro de outra
+superfície, e a escolha entre regiões seccionadas e contínuas pertence a quem a hospeda — o
+[`Card`](/ui/card), o [`Dialog`](/ui/dialog), o [`Drawer`](/ui/drawer) ou o [`Pane`](/ui/pane).
+Quando a própria região precisar de uma fronteira visível, use `framed`, descrito adiante. Pelo
+mesmo motivo o `Content` não tem rodapé: um rodapé pertence à superfície que a hospeda.
+
 No caso comum, prefira o shorthand:
 
 ```tsx preview col
@@ -20,6 +26,79 @@ render(
 );
 ```
 
+## Região com moldura
+
+Use `framed` quando título e corpo precisarem formar uma única região delimitada. A moldura pertence
+ao `Content`; componentes internos, como `DetailGroup`, continuam responsáveis somente pelo layout
+e pela semântica dos próprios dados.
+
+```tsx preview col
+render(
+  <Content
+    framed
+    title={
+      <span className="flex items-center gap-2">
+        <UserRound
+          className="size-4 text-muted-foreground"
+          aria-hidden="true"
+        />
+        Cliente
+      </span>
+    }
+  >
+    <DetailGroup columns={2}>
+      <DetailField label="Nome" value="Carla Souza" />
+      <DetailField label="Telefone" value="+55 11 97333-4455" />
+    </DetailGroup>
+  </Content>,
+);
+```
+
+## Grupo de campos
+
+Quando a região nomear um conjunto de campos relacionados, use `as="fieldset"`. O `Content`
+renderiza o título como `legend`, preserva as props nativas do `fieldset` e mantém o mesmo contrato
+de título e corpo. Essa escolha altera somente a semântica e o comportamento nativo; com `framed`,
+a moldura permanece contínua. Nesse modo, contador, descrição e ações não entram na legenda.
+
+```tsx preview col
+render(
+  <Content as="fieldset" framed title="Proprietário">
+    <FieldGroup>
+      <Field>
+        <FieldLabel htmlFor="owner-name">Nome</FieldLabel>
+        <Input id="owner-name" />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="owner-document">CPF/CNPJ</FieldLabel>
+        <Input id="owner-document" />
+      </Field>
+    </FieldGroup>
+  </Content>,
+);
+```
+
+Quando a legenda precisar integrar visualmente a borda, declare essa escolha separadamente. Use
+`frameVariant="legend"` em agrupamentos compactos, como as seções de filtros avançados.
+
+```tsx preview col
+render(
+  <Content
+    as="fieldset"
+    framed
+    frameVariant="legend"
+    title="Dados do veículo"
+  >
+    <FieldGroup>
+      <Field>
+        <FieldLabel htmlFor="vehicle-plate">Placa</FieldLabel>
+        <Input id="vehicle-plate" />
+      </Field>
+    </FieldGroup>
+  </Content>,
+);
+```
+
 ## Composição explícita
 
 Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
@@ -63,14 +142,17 @@ gatilho repete esse título e a edição usa `Editar recurso`.
 
 ## Propriedades de Content
 
-| Propriedade   | Tipo                         | Padrão      | Descrição                                                                                                |
-| ------------- | ---------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
-| `title`       | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                       |
-| `count`       | `number`                     |             | Forma curta: total de itens ao lado do título da região.                                                 |
-| `description` | `ReactNode`                  |             | Forma curta: frase de apoio sob o título.                                                                |
-| `actions`     | `ReactNode`                  |             | Forma curta: ações sobre a região inteira; em `page`, ficam no extremo oposto ao título.                 |
-| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2`         | Nível semântico do heading, independente do destaque visual.                                             |
-| `variant`     | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície. |
+| Propriedade    | Tipo                         | Padrão      | Descrição                                                                                                               |
+| -------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                                      |
+| `count`        | `number`                     |             | Forma curta: total de itens ao lado do título da região.                                                                |
+| `description`  | `ReactNode`                  |             | Forma curta: frase de apoio sob o título.                                                                               |
+| `actions`      | `ReactNode`                  |             | Forma curta: ações sobre a região inteira; em `page`, ficam no extremo oposto ao título.                                |
+| `level`        | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2`         | Nível semântico do heading, independente do destaque visual.                                                            |
+| `variant`      | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície.                |
+| `as`           | `'section' \| 'fieldset'`    | `'section'` | Usa uma região com heading ou um grupo de campos cujo título é a legenda nativa.                                        |
+| `framed`       | `boolean`                    | `false`     | Envolve o header e o body com a moldura estrutural da região.                                                           |
+| `frameVariant` | `'default' \| 'legend'`      | `'default'` | Em `fieldset` com moldura, mantém a borda contínua ou integra visualmente a legenda à borda. Não altera a semântica.    |
 
 Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e
 `ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`

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

@@ -54,6 +54,91 @@ decide a distribuição nem a aparência dos botões.
 `DialogClose` encerra o modal sem exigir estado controlado. Use `open` e `onOpenChange` quando outra
 parte da interface também precisar controlar a abertura.
 
+## Regiões separadas ou contínuas
+
+`layout` declara a anatomia da superfície inteira e fica em `DialogContent`; os slots leem esse
+valor e não o recebem. O padrão é `sectioned`: as regiões têm o mesmo recuo, o rodapé ganha uma
+faixa sutil e as fronteiras entre regiões vizinhas ganham um divisor. É o modal de tarefa, com
+cabeçalho, conteúdo e ações claramente separados.
+
+Use `layout="continuous"` para uma superfície curta, em que o espaço basta para separar as regiões
+e a linha seria um ruído — um aviso de uma frase, uma escolha rápida.
+
+```tsx preview
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Publicar contrato</Button>
+  </DialogTrigger>
+  <DialogContent layout="continuous">
+    <DialogHeader>
+      <DialogTitle>Publicar contrato</DialogTitle>
+    </DialogHeader>
+    <DialogBody>
+      <p className="text-sm text-muted-foreground">
+        A versão publicada passa a valer para todos os consumidores.
+      </p>
+    </DialogBody>
+    <DialogFooter>
+      <ButtonGroup mode="spaced">
+        <DialogClose asChild>
+          <Button variant="ghost">Cancelar</Button>
+        </DialogClose>
+        <Button>Publicar</Button>
+      </ButtonGroup>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Os divisores do modo seccionado 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`.
+
+A faixa sutil do rodapé é a mesma no `Dialog` e no [`Drawer`](/ui/drawer): as duas famílias
+compartilham a anatomia, e um fluxo que troca de superfície não muda de aparência no meio.
+
+`mode="alert"` mantém a composição centrada da resposta obrigatória e não usa `layout`.
+
+## Ações e navegação no cabeçalho
+
+O cabeçalho reconhece quatro slots — `DialogNavigation`, `DialogMedia`, `DialogTitle` e
+`DialogActions` — e posiciona cada um: a navegação abre a linha, o título ocupa a folga, as ações
+vão para o extremo oposto e o botão de fechar entra depois delas. Um nó que não seja um desses
+slots interrompe a renderização com um erro; contexto e conteúdo pertencem ao `DialogBody`.
+
+Use `DialogActions` para uma ação da tela que precisa ficar à vista sem competir com o rodapé, como
+abrir um assistente ou alternar um modo de visualização. Use `DialogNavigation` para o retorno de um
+fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
+
+```tsx preview
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Revisar evento</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogNavigation>
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
+          <ArrowLeft />
+        </Button>
+      </DialogNavigation>
+      <DialogTitle>Evento 4821</DialogTitle>
+      <DialogActions>
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+          <Ellipsis />
+        </Button>
+      </DialogActions>
+    </DialogHeader>
+    <DialogBody>
+      <p className="text-sm text-muted-foreground">Detalhe do evento selecionado.</p>
+    </DialogBody>
+  </DialogContent>
+</Dialog>
+```
+
+O cabeçalho não recebe descrição: um modal já é a superfície de uma tarefa, e o contexto que ajuda a
+decidir aparece no começo do corpo, como texto ou `Alert`.
+
 ## Pedir uma resposta pela API imperativa
 
 Use `dialog.alert`, `dialog.confirm`, `dialog.prompt` e `dialog.choose` quando a resposta couber em
@@ -280,6 +365,7 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 | `showCloseButton` | `boolean`   | `true` | No modo padrão, inclui a ação de fechamento no header; o modo de alerta exige uma resposta identificável. |
 | `closeDisabled`   | `boolean`   | `false` | Mantém a ação visível e impede o fechamento enquanto a tarefa está bloqueada.                            |
 | `closeSize`       | `"xs" \| "sm"` | `"sm"` | Define o tamanho da ação circular de fechar.                                                  |
+| `layout`          | `'continuous' \| 'sectioned'` | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. Ignorado em `mode="alert"`. |
 | `className`       | `string`    |        | Ajusta a superfície.                                                                                      |
 | `children`        | `ReactNode` |        | Cabeçalho, corpo, rodapé ou conteúdo próprio.                                                             |
 
@@ -287,8 +373,22 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 
 | Propriedade | Tipo        | Padrão | Descrição                                                  |
 | ----------- | ----------- | ------ | ---------------------------------------------------------- |
-| `className` | `string`    |        | Ajusta a faixa superior.                                   |
-| `children`  | `ReactNode` |        | Título e ações opcionais; o close padrão entra por último. |
+| `className` | `string`    |        | Ajusta a faixa superior sobre o recuo do layout.           |
+| `children`  | `ReactNode` |        | Somente `DialogNavigation`, `DialogMedia`, `DialogTitle` e `DialogActions`, no máximo um de cada; o fechamento padrão entra depois deles. |
+
+## Propriedades de DialogNavigation
+
+| Propriedade | Tipo        | Padrão | Descrição                                                      |
+| ----------- | ----------- | ------ | -------------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a região introdutória da linha.                         |
+| `children`  | `ReactNode` |        | Retorno de um fluxo modal encadeado, antes do título.          |
+
+## Propriedades de DialogActions
+
+| Propriedade | Tipo        | Padrão | Descrição                                                          |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------ |
+| `className` | `string`    |        | Ajusta o agrupamento das ações.                                    |
+| `children`  | `ReactNode` |        | Ações da tela no cabeçalho, antes do botão de fechar.              |
 
 ## Propriedades de DialogBody
 
@@ -308,15 +408,23 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 
 | Propriedade | Tipo        | Padrão | Descrição                            |
 | ----------- | ----------- | ------ | ------------------------------------ |
-| `className` | `string`    |        | Ajusta o título.                     |
+| `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `h2` da primitiva | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `className` | `string`    |        | Ajusta o título, que trunca quando não cabe na linha. |
 | `children`  | `ReactNode` |        | Nome da tarefa ou do conteúdo modal. |
 
 ## Propriedades de DialogMedia
 
-| Propriedade | Tipo        | Padrão | Descrição                                 |
-| ----------- | ----------- | ------ | ----------------------------------------- |
-| `className` | `string`    |        | Ajusta a moldura quadrada da mídia.       |
-| `children`  | `ReactNode` |        | Ícone que reforça o contexto da resposta. |
+A moldura vem do `IconTile`, como nas demais famílias. No `mode="alert"` ela cresce e centraliza:
+ali a mídia não acompanha uma linha de título, ela é o que faz a pessoa reconhecer a resposta.
+
+| Propriedade | Tipo                                                        | Padrão    | Descrição                                          |
+| ----------- | ----------------------------------------------------------- | --------- | -------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                          | `sm`      | Escala da moldura; no alerta vale a moldura maior. |
+| `context`   | `UiContext`                                                  | `neutral` | Cor semântica da moldura.                          |
+| `variant`   | `'subtle' \| 'outline'`                                      | `subtle`  | Tratamento visual da moldura.                      |
+| `className` | `string`                                                     |           | Ajustes pontuais da moldura.                       |
+| `children`  | `ReactNode`                                                  |           | Ícone que reforça o contexto da resposta.          |
+| `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 DialogClose