@softize/opus 23.0.0 → 24.0.0

package/src/ui/docs/content/action-view.md

@@ -6,17 +6,27 @@ erro. O consumidor compõe somente o conteúdo disponível, aqui com [`Detail`](
 coleção, use [`ActionList`](/ui/action-list).
 
 ```tsx preview col
-const [id, setId] = useState('empresa-x')
+const [id, setId] = useState("empresa-x");
 
 render(
   <DocBrowserActionProvider>
     <div className="w-full space-y-3">
       <ButtonGroup mode="spaced">
-        <Button variant="outline" size="sm" onClick={() => setId('empresa-x')}>Empresa X</Button>
-        <Button variant="outline" size="sm" onClick={() => setId('empresa-y')}>Empresa Y</Button>
-        <Button variant="outline" size="sm" onClick={() => setId('sessao-fantasma')}>Inexistente (erro)</Button>
+        <Button variant="outline" size="sm" onClick={() => setId("empresa-x")}>
+          Empresa X
+        </Button>
+        <Button variant="outline" size="sm" onClick={() => setId("empresa-y")}>
+          Empresa Y
+        </Button>
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => setId("sessao-fantasma")}
+        >
+          Inexistente (erro)
+        </Button>
       </ButtonGroup>
-      <Card className="p-4">
+      <Surface framed elevation="raised" className="p-4">
         <ActionView action={docWorkspaceView} input={{ id }}>
           {(ws) => (
             <DetailGroup columns={3}>
@@ -24,15 +34,20 @@ render(
               <DetailField label="Cliente" value={ws.client} />
               <DetailField
                 label="Status"
-                value={<DictionaryValue dict={docWorkspaceStatus} value={ws.status} />}
+                value={
+                  <DictionaryValue
+                    dict={docWorkspaceStatus}
+                    value={ws.status}
+                  />
+                }
               />
             </DetailGroup>
           )}
         </ActionView>
-      </Card>
+      </Surface>
     </div>
   </DocBrowserActionProvider>,
-)
+);
 ```
 
 O handler da view deve devolver um valor. Uma consulta que resolve `undefined` é tratada como erro
@@ -47,13 +62,13 @@ mais de uma região da tela ou quando o carregamento precisa ser orquestrado por
 
 ## Propriedades de ActionView
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `action` | `ViewContract<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
-| `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
-| `children` | `(data: TData, refetch) => ReactNode` | | Obrigatório, salvo quando `render` é informado. Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
-| `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. Sem nenhum dos dois, o componente lança erro. |
-| `loading` | `ReactNode \| boolean` | `3 skeletons` | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega. |
-| `empty` | `ReactNode` | `emptyMessage` ou nada | Estado reservado a `data` indefinido. Como o react-query converte esse resultado em erro, ele não aparece na prática; devolva um valor ou o erro `not_found`. |
-| `emptyMessage` | `string` | | Atalho do vazio, sujeito à mesma limitação de `empty`: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida). |
-| `error` | `(err, retry) => ReactNode` | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |
+| Propriedade    | Tipo                                  | Padrão                                         | Descrição                                                                                                                                                                                                                                                                                            |
+| -------------- | ------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`       | `ViewContract<TInput, TData>`         |                                                | A ViewAction do Opus (kind view, 1 recurso).                                                                                                                                                                                                                                                         |
+| `input`        | `TInput`                              |                                                | Geralmente { id } — mudou, recarrega.                                                                                                                                                                                                                                                                |
+| `children`     | `(data: TData, refetch) => ReactNode` |                                                | Obrigatório, salvo quando `render` é informado. Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código.                                                                                                                                                     |
+| `render`       | `(data: TData, refetch) => ReactNode` |                                                | Alias de compatibilidade de `children`; `children` tem precedência. Sem nenhum dos dois, o componente lança erro.                                                                                                                                                                                    |
+| `loading`      | `ReactNode \| boolean`                | `3 skeletons`                                  | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega.                                                                                                                                                                                |
+| `empty`        | `ReactNode`                           | `emptyMessage` ou nada                         | Estado reservado a `data` indefinido. Como o react-query converte esse resultado em erro, ele não aparece na prática; devolva um valor ou o erro `not_found`.                                                                                                                                        |
+| `emptyMessage` | `string`                              |                                                | Atalho do vazio, sujeito à mesma limitação de `empty`: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida).                                                                                                                                                                      |
+| `error`        | `(err, retry) => ReactNode`           | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |

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

@@ -43,7 +43,7 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 Escolha o tamanho pela região, não pela importância visual: `variant` e `context` resolvem a
 hierarquia da ação. Headers de Page, a criação no cabeçalho de uma coleção e footers de
 [`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) usam `default`; a criação de uma coleção é um botão textual, sem
-ícone, como mostra [`Content`](/ui/content). Operações densas de toolbar ou de seção usam `sm`;
+ícone, como mostra [`Surface`](/ui/surface). Operações densas de toolbar ou de seção usam `sm`;
 ações dentro de linha ou célula usam `xs` ou `icon-xs`. Assim a mesma decisão mantém a mesma altura
 mesmo quando uma superfície troca uma ação secundária por uma primária.
 

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

@@ -42,7 +42,7 @@ frase. Não copie as regras da Base para cá.
 | Superfície Opus                                                                                                           | Papel enviado à Base                                           |
 | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | `label`, botão de confirmação e filhos de `Button`                                                                        | `button`                                                       |
-| `title`, `CardTitle`, `DialogTitle`                                                                                       | `title`                                                        |
+| `title`, `SurfaceTitle`, `DialogTitle`                                                                                    | `title`                                                        |
 | `description`, `hint`, `help`                                                                                             | `description` ou `helper-text`                                 |
 | `messages.success` e `messages.error`                                                                                     | `success` e `error`                                            |
 | `confirm.message`, `dialog.*().body` e texto relevante no `DialogBody`                                                    | `dialog-body`                                                  |

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

@@ -17,12 +17,12 @@ variáveis.
 
 ```css
 /* index.css do app — depois do import do tema. */
-@import '@softize/opus/ui/theme.css';
+@import "@softize/opus/ui/theme.css";
 
 :root {
   --primary: hsl(262 83% 58%); /* A cor da marca do projeto. */
   --ring: hsl(262 83% 58%);
-  --radius: 0.5rem;            /* Uma base menor deixa toda a escala mais contida. */
+  --radius: 0.5rem; /* Uma base menor deixa toda a escala mais contida. */
 }
 ```
 
@@ -36,6 +36,55 @@ Quando o produto precisa de outra densidade, declare essa escolha no CSS do app.
 Opus mede em `rem` acompanha a proporção. O valor continua sendo uma escolha do app, não uma regra
 da biblioteca.
 
+### Ajuste de aparência dos neutros
+
+Quando a aplicação quer neutros levemente tingidos pela marca, camadas mais separadas ou um escuro
+mais profundo — como padrão do produto ou como preferência de cada pessoa —, ela não precisa
+redeclarar `--background`, `--card` e os demais tokens neutros. O tema calcula essa escala a partir
+de quatro eixos por modo, e basta alterar os eixos. Cada um aceita um inteiro de 0 a 100; a tabela
+com o efeito e o preset de cada eixo está em [Tokens](/ui/tokens).
+
+Para definir o padrão do produto, declare os eixos no CSS do app. Os eixos do modo claro e os do
+modo escuro ficam juntos em `:root`; o tema usa o conjunto do modo ativo.
+
+```css
+:root {
+  --neutral-hue: 262; /* O matiz da marca nos neutros. */
+  --appearance-light-color-intensity: 40;
+  --appearance-dark-color-intensity: 60;
+  --appearance-dark-surface-brightness: 30; /* Um escuro mais profundo que o preset. */
+}
+```
+
+Para aplicar a preferência de uma pessoa, use o helper de `@softize/opus/ui/appearance`. Ele
+arredonda e limita os valores, grava os eixos informados e remove os demais. Guardar a preferência
+e desenhar a tela de ajuste são responsabilidades da aplicação.
+
+```ts
+import { applyAppearanceCustomProperties } from "@softize/opus/ui/appearance";
+
+const style = document.documentElement.style;
+
+// Aplica somente os eixos informados; os demais continuam no padrão.
+applyAppearanceCustomProperties(style, "light", { layerContrast: 60 });
+applyAppearanceCustomProperties(style, "dark", {
+  contrast: 40,
+  surfaceBrightness: 20,
+});
+
+// Voltar ao padrão é aplicar sem overrides: as propriedades são removidas.
+applyAppearanceCustomProperties(style, "dark");
+```
+
+O Opus não oferece um componente de reset. Sem o override, vale o que o CSS do app declarou ou,
+na falta disso, o preset do tema. Em renderização no servidor, `appearanceCustomProperties` devolve
+o mesmo mapa sem tocar no DOM, para a aplicação escrever os eixos no HTML inicial.
+
+Nenhum valor de 0 a 100 deixa a interface menos legível que o tema padrão: a separação entre os
+papéis e o contraste do texto sobre as superfícies em repouso nunca ficam abaixo do preset. Um
+token neutro redeclarado diretamente pelo app, como `--background`, deixa de acompanhar os eixos e
+fica fora dessa proteção.
+
 ## 2 · className em tudo
 
 Todo componente aceita `className` e o combina com as próprias classes por tailwind-merge: quando
@@ -44,28 +93,30 @@ local, como largura, margem e grid, e não para repintar o visual dos componente
 
 ```tsx
 <Button className="w-full">Continuar</Button>
-<Card className="max-w-sm" />
+<Surface framed elevation="raised" className="max-w-sm" />
 <DialogContent className="max-w-2xl" />
 ```
 
 ## 3 · Recomposição estrutural
 
-Os componentes são divididos em partes nomeadas, como `CardHeader` e `CardBody`, e a tela usa só as
+Os componentes são divididos em partes nomeadas, como `SurfaceHeader` e `SurfaceBody`, e a tela usa só as
 que precisa. `asChild` faz o filho assumir o estilo e o comportamento do componente, e as funções
 `*Variants` aplicam o visual de um componente a um elemento qualquer.
 
 ```tsx preview
 <Button asChild variant="outline">
-  <a href="#" onClick={(e) => e.preventDefault()}>Link com aparência de botão</a>
+  <a href="#" onClick={(e) => e.preventDefault()}>
+    Link com aparência de botão
+  </a>
 </Button>
 ```
 
 ```tsx
 // Partes: só o que a tela pede.
-<Card>
-  <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
-  <CardBody>…</CardBody>
-</Card>
+<Surface framed elevation="raised">
+  <SurfaceHeader><SurfaceTitle>Workspace</SurfaceTitle></SurfaceHeader>
+  <SurfaceBody>…</SurfaceBody>
+</Surface>
 
 // asChild: o link assume o estilo e o comportamento do botão.
 <Button asChild><a href="/docs">Abrir documentação</a></Button>
@@ -128,8 +179,10 @@ componentes.
 ## O que fica fora das alavancas
 
 Alguns detalhes fazem parte da identidade visual do Opus e são iguais em todo projeto: a faixa do
-rodapé do dialog, a elevação no tema escuro, o escurecimento do botão ao ser pressionado
-(`active:brightness-90`) e a seta do tooltip. Eles não são configuráveis pela aplicação.
+rodapé do dialog, a ordem entre canvas, controle, superfície elevada e estados neutros, o
+escurecimento de botões sólidos ao serem pressionados e a seta do tooltip. Eles não são
+configuráveis pela aplicação. O ajuste de aparência muda a distância entre os papéis neutros, mas
+não a ordem entre eles.
 
 Se uma necessidade real não cabe nas alavancas (tokens, `className`, partes e `asChild`, props e
 contrato), não crie uma variação local. Proponha a evolução do componente no Opus, com a

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

@@ -44,12 +44,13 @@ React substitui a apresentação. `0` e `false` seguem como valores. A regra é
 </DetailGroup>
 ```
 
-## Moldura e divisórias internas
+## Elevação, moldura e divisórias internas
 
-`variant="framed"` adiciona somente a borda externa, sem preencher o fundo. `dividers` desenha as
-divisórias internas; na orientação horizontal, também forma a grade tabular com fundo sutil e
-padding próprio na coluna de rótulos. As duas opções são independentes e podem ser combinadas.
-`orientation` define se a chave fica sobre o valor ou ao lado dele.
+Por padrão, o grupo usa o mesmo fundo de uma superfície elevada. Use `elevation="none"` quando ele
+precisar se integrar ao fundo do hospedeiro. `variant="framed"` adiciona somente a borda externa.
+`dividers` desenha as divisórias internas; na orientação horizontal, também forma a grade tabular
+com fundo sutil e padding próprio na coluna de rótulos. As opções são independentes e podem ser
+combinadas. `orientation` define se a chave fica sobre o valor ou ao lado dele.
 
 Na orientação horizontal, todos os valores começam depois da mesma coluna de rótulo, com largura
 padrão de `7rem` em grupos simples e `8.5rem` quando `dividers` está ativo. Quando a superfície
@@ -73,7 +74,8 @@ exigir mais espaço para os rótulos, ajuste a variável no grupo, por exemplo c
 
 | Propriedade   | Tipo                         | Padrão       | Descrição                                                                                                 |
 | ------------- | ---------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
-| `variant`     | `'plain' \| 'framed'`        | `'plain'`    | `framed` aplica somente a moldura canônica ao conjunto, com fundo transparente.                           |
+| `variant`     | `'plain' \| 'framed'`        | `'plain'`    | `framed` aplica somente a moldura canônica ao conjunto.                                                   |
+| `elevation`   | `'none' \| 'raised'`         | `'raised'`   | `raised` usa o fundo de superfície elevada; `none` herda o fundo do hospedeiro.                           |
 | `dividers`    | `boolean`                    | `false`      | Linhas finas entre os campos; na orientação horizontal, aplica fundo sutil e padding próprio aos rótulos. |
 | `columns`     | `1 \| 2 \| 3 \| 4 \| 'auto'` | `1`          | Número fixo de colunas ou distribuição automática por largura mínima.                                     |
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chave sobre o valor ou ao lado dele em cada campo.                                                        |

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

@@ -29,9 +29,11 @@ distinta da página.
     <DialogHeader>
       <DialogTitle>Criar workspace</DialogTitle>
     </DialogHeader>
-    <DialogBody className="space-y-2">
-      <Label htmlFor="workspace-name">Nome</Label>
-      <Input id="workspace-name" placeholder="Ex.: Empresa X" />
+    <DialogBody>
+      <div className="space-y-2">
+        <Label htmlFor="workspace-name">Nome</Label>
+        <Input id="workspace-name" placeholder="Ex.: Empresa X" />
+      </div>
     </DialogBody>
     <DialogFooter>
       <ButtonGroup mode="spaced">
@@ -46,6 +48,9 @@ distinta da página.
 ```
 
 O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
+Seus filhos diretos recebem o ritmo estrutural de `1.5rem`. Um grupo compacto, uma grade ou uma
+linha declara a própria relação em um wrapper filho; `flush` fica reservado ao conteúdo que
+controla todo o inset.
 O backdrop escurece a página sem aplicar desfoque.
 O fechamento do cabeçalho usa uma ação circular neutra e sutil. `closeSize` escolhe entre `xs` e
 `sm`; o padrão é `sm`.
@@ -131,7 +136,9 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
       </DialogActions>
     </DialogHeader>
     <DialogBody>
-      <p className="text-sm text-muted-foreground">Detalhe do evento selecionado.</p>
+      <p className="text-sm text-muted-foreground">
+        Detalhe do evento selecionado.
+      </p>
     </DialogBody>
   </DialogContent>
 </Dialog>
@@ -147,9 +154,9 @@ decidir aparece no começo do corpo, como texto ou `Alert`.
 ## Identificar a tarefa com um ícone
 
 Use `DialogMedia` quando um ícone ajuda a reconhecer a tarefa antes da leitura do título. No modo
-padrão, ele abre a linha do cabeçalho com a mesma moldura de [`IconTile`](/ui/icon-tile) das demais
-superfícies. No `mode="alert"`, a moldura cresce e fica centralizada acima do título, porque ali o
-ícone é o principal sinal de reconhecimento da resposta.
+padrão, ele apenas reserva e alinha o espaço antes do título. Componha [`IconTile`](/ui/icon-tile)
+explicitamente quando o ícone precisar de moldura; passe o glifo diretamente quando não precisar.
+O mesmo contrato vale no `mode="alert"`: a mídia não ganha tamanho, fundo ou borda automaticamente.
 
 ```tsx preview
 render(
@@ -161,13 +168,17 @@ render(
       <DialogContent>
         <DialogHeader>
           <DialogMedia>
-            <Share2 />
+            <IconTile size="sm">
+              <Share2 />
+            </IconTile>
           </DialogMedia>
           <DialogTitle>Compartilhar contrato</DialogTitle>
         </DialogHeader>
-        <DialogBody className="space-y-2">
-          <Label htmlFor="share-email">E-mail</Label>
-          <Input id="share-email" placeholder="nome@empresa.com.br" />
+        <DialogBody>
+          <div className="space-y-2">
+            <Label htmlFor="share-email">E-mail</Label>
+            <Input id="share-email" placeholder="nome@empresa.com.br" />
+          </div>
         </DialogBody>
         <DialogFooter>
           <ButtonGroup mode="spaced">
@@ -185,8 +196,10 @@ render(
       </DialogTrigger>
       <DialogContent>
         <DialogHeader>
-          <DialogMedia context="danger">
-            <ShieldOff />
+          <DialogMedia>
+            <IconTile size="lg" context="danger">
+              <ShieldOff />
+            </IconTile>
           </DialogMedia>
           <DialogTitle>Revogar acesso de Marina?</DialogTitle>
         </DialogHeader>
@@ -211,7 +224,8 @@ render(
 );
 ```
 
-Na API imperativa, a opção `media` recebe o ícone e o apresenta na mesma moldura do alerta.
+Na API imperativa, a opção `media` preserva o nó recebido. Passe um `IconTile` quando quiser
+moldura.
 
 ## Pedir uma resposta pela API imperativa
 
@@ -245,7 +259,11 @@ function Demo() {
           const accepted = await dialog.confirm({
             title: "Excluir rascunho?",
             body: "O rascunho e os comentários dele serão removidos.",
-            media: <Trash2 />,
+            media: (
+              <IconTile context="danger">
+                <Trash2 />
+              </IconTile>
+            ),
             action: "Excluir",
             context: "danger",
           });
@@ -443,42 +461,43 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Arqu
 
 ## Propriedades de DialogContent
 
-| Propriedade       | Tipo        | Padrão | Descrição                                                                                                 |
-| ----------------- | ----------- | ------ | --------------------------------------------------------------------------------------------------------- |
-| `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 o botão de fechar visível e desabilitado e impede que Esc e o clique externo fechem a superfície. Handlers como `onEscapeKeyDown` e `onPointerDownOutside` continuam sendo chamados antes do bloqueio. |
-| `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. A largura máxima é `32rem` no modo padrão e `20rem` no alerta; amplie o alerta com `max-w-lg` quando o rodapé tiver três ações. |
-| `children`        | `ReactNode` |        | Cabeçalho, corpo, rodapé ou conteúdo próprio.                                                             |
+| Propriedade       | Tipo                          | Padrão        | Descrição                                                                                                                                                                                                     |
+| ----------------- | ----------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 o botão de fechar visível e desabilitado e impede que Esc e o clique externo fechem a superfície. Handlers como `onEscapeKeyDown` e `onPointerDownOutside` continuam sendo chamados antes do bloqueio. |
+| `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. A largura máxima é `32rem` no modo padrão e `20rem` no alerta; amplie o alerta com `max-w-lg` quando o rodapé tiver três ações.                                                          |
+| `children`        | `ReactNode`                   |               | Cabeçalho, corpo, rodapé ou conteúdo próprio.                                                                                                                                                                 |
 
 ## Propriedades de DialogHeader
 
-| Propriedade | Tipo        | Padrão | Descrição                                                  |
-| ----------- | ----------- | ------ | ---------------------------------------------------------- |
-| `className` | `string`    |        | Ajusta a faixa superior sobre o recuo do layout.           |
+| Propriedade | Tipo        | Padrão | Descrição                                                                                                                                 |
+| ----------- | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.          |
+| 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.              |
+| 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
 
-| Propriedade | Tipo        | Padrão | Descrição                                                              |
-| ----------- | ----------- | ------ | ---------------------------------------------------------------------- |
-| `className` | `string`    |        | Ajusta o corpo rolável do modo padrão ou o conteúdo próprio do alerta. |
-| `children`  | `ReactNode` |        | Conteúdo principal da tarefa.                                          |
+| Propriedade | Tipo        | Padrão  | Descrição                                                              |
+| ----------- | ----------- | ------- | ---------------------------------------------------------------------- |
+| `flush`     | `boolean`   | `false` | Remove o inset para conteúdo que controla o próprio recuo.             |
+| `className` | `string`    |         | Ajusta o corpo rolável do modo padrão ou o conteúdo próprio do alerta. |
+| `children`  | `ReactNode` |         | Conteúdo principal da tarefa.                                          |
 
 ## Propriedades de DialogFooter
 
@@ -489,25 +508,18 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Arqu
 
 ## Propriedades de DialogTitle
 
-| Propriedade | Tipo        | Padrão | Descrição                            |
-| ----------- | ----------- | ------ | ------------------------------------ |
-| `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. No modo padrão, ele trunca quando não cabe na linha; no alerta, fica centralizado e pode ocupar mais de uma linha. |
-| `children`  | `ReactNode` |        | Nome da tarefa ou do conteúdo modal. |
+| Propriedade | Tipo                         | Padrão            | Descrição                                                                                                                           |
+| ----------- | ---------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `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. No modo padrão, ele trunca quando não cabe na linha; no alerta, fica centralizado e pode ocupar mais de uma linha. |
+| `children`  | `ReactNode`                  |                   | Nome da tarefa ou do conteúdo modal.                                                                                                |
 
 ## Propriedades de DialogMedia
 
-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. |
+| Propriedade | Tipo        | Padrão | Descrição                                                               |
+| ----------- | ----------- | ------ | ----------------------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta o alinhamento do slot.                                           |
+| `children`  | `ReactNode` |        | `IconTile`, marca, imagem ou glifo. O slot não acrescenta apresentação. |
 
 ## Propriedades de DialogClose
 
@@ -540,7 +552,7 @@ imperativa.
 | -------- | ----------- | ------ | ------------------------------------------------ |
 | `title`  | `ReactNode` |        | Nomeia o aviso que exige reconhecimento.         |
 | `body`   | `ReactNode` |        | Apresenta contexto relevante no início do corpo. |
-| `media`  | `ReactNode` |        | Exibe um ícone na moldura de `DialogMedia`.      |
+| `media`  | `ReactNode` |        | Exibe o nó recebido em `DialogMedia`.            |
 | `action` | `string`    | `'OK'` | Define o rótulo de reconhecimento.               |
 
 ## Opções de dialog.confirm
@@ -549,7 +561,7 @@ imperativa.
 | --------- | ----------------------- | ------------- | ------------------------------------------------------------------- |
 | `title`   | `ReactNode`             |               | Nomeia a decisão.                                                   |
 | `body`    | `ReactNode`             |               | Apresenta a consequência ou outro contexto necessário para decidir. |
-| `media`   | `ReactNode`             |               | Exibe um ícone na moldura de `DialogMedia`.                         |
+| `media`   | `ReactNode`             |               | Exibe o nó recebido em `DialogMedia`.                               |
 | `action`  | `string`                | `'Confirmar'` | Define o rótulo do resultado afirmativo.                            |
 | `cancel`  | `string`                | `'Cancelar'`  | Define o rótulo da resposta negativa.                               |
 | `context` | `'primary' \| 'danger'` | `'primary'`   | Define o contexto da ação afirmativa.                               |
@@ -560,7 +572,7 @@ imperativa.
 | -------------- | ----------------------- | ------------- | ------------------------------------------------------------------ |
 | `title`        | `ReactNode`             |               | Nomeia a informação solicitada.                                    |
 | `body`         | `ReactNode`             |               | Explica como a informação será usada quando isso mudar a resposta. |
-| `media`        | `ReactNode`             |               | Exibe um ícone na moldura de `DialogMedia`.                        |
+| `media`        | `ReactNode`             |               | Exibe o nó recebido em `DialogMedia`.                              |
 | `action`       | `string`                | `'Confirmar'` | Define o rótulo do resultado afirmativo.                           |
 | `cancel`       | `string`                | `'Cancelar'`  | Define o rótulo da resposta negativa.                              |
 | `context`      | `'primary' \| 'danger'` | `'primary'`   | Define o contexto da ação afirmativa.                              |
@@ -573,7 +585,7 @@ imperativa.
 | --------- | ------------------------- | ------ | ------------------------------------------------ |
 | `title`   | `ReactNode`               |        | Nomeia a escolha.                                |
 | `body`    | `ReactNode`               |        | Apresenta o contexto necessário antes das ações. |
-| `media`   | `ReactNode`               |        | Exibe um ícone na moldura de `DialogMedia`.      |
+| `media`   | `ReactNode`               |        | Exibe o nó recebido em `DialogMedia`.            |
 | `actions` | `readonly DialogChoice[]` |        | Declara os resultados disponíveis.               |
 
 ## Propriedades de DialogChoice
@@ -586,3 +598,33 @@ imperativa.
 | `context`      | `ButtonContext` | Última ação: `primary`; demais: `neutral` | Define o significado semântico.                       |
 | `variant`      | `ButtonVariant` | Última ação: `solid`; demais: `outline`   | Define o tratamento visual.                           |
 | `disabled`     | `boolean`       | `false`                                   | Impede a escolha desta ação.                          |
+
+## Intro separada do chrome
+
+Quando o header contém apenas navegação, ações globais e o fechamento, coloque o título do
+conteúdo no primeiro bloco de `DialogBody`. `DialogIntro` exige um `DialogTitle` e aceita um
+`DialogIntroActions`; o body continua responsável pelo espaço antes, entre e depois dos blocos.
+
+```tsx
+<Dialog>
+  <DialogContent>
+    <DialogHeader>
+      <DialogActions>
+        <Button variant="ghost">Ajuda</Button>
+      </DialogActions>
+    </DialogHeader>
+    <DialogBody>
+      <DialogIntro>
+        <DialogTitle>Editar evento</DialogTitle>
+        <DialogIntroActions>
+          <Button variant="outline">Revisar</Button>
+        </DialogIntroActions>
+      </DialogIntro>
+      <form>…</form>
+    </DialogBody>
+    <DialogFooter>…</DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+No formato compacto, mantenha `DialogTitle` e `DialogActions` no próprio `DialogHeader`.