@softize/opus 18.5.0 → 19.0.0

package/src/ui/components/primitives/metric-card.tsx

@@ -42,7 +42,25 @@ interface MetricCardBaseProps extends Omit<React.ComponentProps<typeof Card>, 'c
   secondaryMetric?: MetricCardSecondaryMetric
 }
 
+type MetricCardActivationProps =
+  | {
+      /** Indica se a medida controla o recorte atualmente aplicado. */
+      active: boolean
+      /** Ativa a medida como recorte ou seleção. */
+      onActivate: () => void
+      /** Nome acessível da ativação, como “Filtrar por Agendados”. */
+      activationLabel: string
+      /** Use `onActivate`; o clique genérico conflita com os controles internos do card. */
+      onClick?: never
+    }
+  | {
+      active?: never
+      onActivate?: never
+      activationLabel?: never
+    }
+
 export type MetricCardProps = MetricCardBaseProps &
+  MetricCardActivationProps &
   (
     | {
         /** Nome curto da medida apresentada. */
@@ -75,6 +93,9 @@ export function MetricCard({
   tone,
   action,
   secondaryMetric,
+  active,
+  onActivate,
+  activationLabel,
   loading = false,
   className,
   ...props
@@ -84,6 +105,7 @@ export function MetricCard({
   }
   const hasIcon = icon !== undefined && icon !== null
   const resolvedContext = context ?? (tone === 'warning' ? 'warning' : 'neutral')
+  const interactive = onActivate !== undefined
 
   const primaryCard = (
     <Card
@@ -92,9 +114,9 @@ export function MetricCard({
       className={cn(
         'min-w-0 p-4',
         secondaryMetric !== undefined && 'relative z-10',
-        secondaryMetric === undefined && className,
+        secondaryMetric === undefined && !interactive && className,
       )}
-      {...(secondaryMetric === undefined ? props : {})}
+      {...(secondaryMetric === undefined && !interactive ? props : {})}
     >
       {loading ? (
         <div className="space-y-3">
@@ -106,7 +128,10 @@ export function MetricCard({
         <>
           <div className="flex items-start justify-between gap-3">
             <div className="flex min-w-0 items-center gap-1.5">
-              <div data-slot="metric-card-label" className="min-w-0 truncate text-sm font-medium text-muted-foreground">
+              <div
+                data-slot="metric-card-label"
+                className="min-w-0 truncate text-sm font-medium text-muted-foreground"
+              >
                 {label}
               </div>
               {labelAction !== undefined && (
@@ -129,7 +154,10 @@ export function MetricCard({
               </span>
             )}
           </div>
-          <div data-slot="metric-card-value" className="mt-3 text-2xl font-semibold tracking-tight tabular-nums">
+          <div
+            data-slot="metric-card-value"
+            className="mt-3 text-2xl font-semibold tracking-tight tabular-nums"
+          >
             {value}
           </div>
           {description !== undefined && (
@@ -147,46 +175,77 @@ export function MetricCard({
     </Card>
   )
 
-  if (secondaryMetric === undefined) return primaryCard
-
-  return (
-    <div
-      {...props}
-      data-slot="metric-card-stack"
-      aria-busy={loading || undefined}
-      className={cn('relative isolate min-w-0', className)}
-    >
-      {primaryCard}
-      <Card
-        data-slot="metric-card-secondary"
-        className="relative z-0 -mt-8 flex w-full min-w-0 items-center gap-1.5 bg-[color-mix(in_oklab,var(--card)_88%,black)] px-4 pt-9 pb-1"
+  const metric =
+    secondaryMetric === undefined ? (
+      primaryCard
+    ) : (
+      <div
+        {...(!interactive ? props : {})}
+        data-slot="metric-card-stack"
+        aria-busy={loading || undefined}
+        className={cn('relative isolate min-w-0', !interactive && className)}
       >
-        {loading ? (
-          <Skeleton className="h-5 w-full" />
-        ) : (
-          <>
-            <div
-              data-slot="metric-card-secondary-value"
-              className="shrink-0 text-xs font-medium text-muted-foreground tabular-nums"
-            >
-              {secondaryMetric.value}
-            </div>
-            <div className="flex min-w-0 items-center gap-1.5">
+        {primaryCard}
+        <Card
+          data-slot="metric-card-secondary"
+          className="relative z-0 -mt-8 flex w-full min-w-0 items-center gap-1.5 bg-[color-mix(in_oklab,var(--card)_88%,black)] px-4 pt-9 pb-1"
+        >
+          {loading ? (
+            <Skeleton className="h-5 w-full" />
+          ) : (
+            <>
               <div
-                data-slot="metric-card-secondary-label"
-                className="min-w-0 truncate text-xs font-medium text-muted-foreground"
+                data-slot="metric-card-secondary-value"
+                className="shrink-0 text-xs font-medium text-muted-foreground tabular-nums"
               >
-                {secondaryMetric.label}
+                {secondaryMetric.value}
               </div>
-              {secondaryMetric.labelAction !== undefined && (
-                <div data-slot="metric-card-secondary-label-action" className="shrink-0">
-                  {secondaryMetric.labelAction}
+              <div className="flex min-w-0 items-center gap-1.5">
+                <div
+                  data-slot="metric-card-secondary-label"
+                  className="min-w-0 truncate text-xs font-medium text-muted-foreground"
+                >
+                  {secondaryMetric.label}
                 </div>
-              )}
-            </div>
-          </>
-        )}
-      </Card>
+                {secondaryMetric.labelAction !== undefined && (
+                  <div data-slot="metric-card-secondary-label-action" className="shrink-0">
+                    {secondaryMetric.labelAction}
+                  </div>
+                )}
+              </div>
+            </>
+          )}
+        </Card>
+      </div>
+    )
+
+  if (!interactive) return metric
+
+  return (
+    <div
+      {...props}
+      data-slot="metric-card-activation"
+      data-active={active}
+      className={cn(
+        // Ativa = a borda na cor primária, e só. Anel somaria uma segunda linha de
+        // outra cor à borda e, pintado para fora, sumiria no primeiro ancestral com
+        // `overflow-hidden`.
+        'relative isolate min-w-0 data-[active=true]:[&_[data-slot=metric-card]]:border-primary',
+        className,
+      )}
+    >
+      <button
+        type="button"
+        data-slot="metric-card-activation-control"
+        className="peer absolute inset-0 z-0 cursor-pointer rounded-xl outline-none"
+        aria-label={activationLabel}
+        aria-pressed={active}
+        disabled={loading}
+        onClick={onActivate}
+      />
+      <div className="pointer-events-none relative z-10 h-full [&>[data-slot=metric-card]]:h-full [&_[data-slot=metric-card]]:transition-colors [&_[data-slot=metric-card-action]]:pointer-events-auto [&_[data-slot=metric-card-label-action]]:pointer-events-auto [&_[data-slot=metric-card-secondary-label-action]]:pointer-events-auto peer-hover:[&_[data-slot=metric-card]]:border-foreground/40 peer-focus-visible:[&_[data-slot=metric-card]]:ring-2 peer-focus-visible:[&_[data-slot=metric-card]]:ring-inset peer-focus-visible:[&_[data-slot=metric-card]]:ring-ring">
+        {metric}
+      </div>
     </div>
   )
 }

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

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