@softize/opus 23.0.0 → 24.0.1

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`.
@@ -104,8 +109,10 @@ compartilham a anatomia, e um fluxo que troca de superfície não muda de aparê
 
 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`.
+vão para o extremo oposto e o botão de fechar entra depois delas. A navegação fica a `0.5rem` do
+título, ou da mídia que o antecede, para se ler junto dele; as ações mantêm a distância maior da
+família. 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
@@ -131,7 +138,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 +156,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 +170,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 +198,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 +226,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 +261,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 +463,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 cabeçalho; 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 +510,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 +554,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 +563,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 +574,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 +587,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 +600,34 @@ 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 cabeçalho 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`. Para
+comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).

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

@@ -18,9 +18,11 @@ cantos, em qualquer valor de `side`.
     <DrawerHeader>
       <DrawerTitle>ABC-1D23</DrawerTitle>
     </DrawerHeader>
-    <DrawerBody className="space-y-1 text-sm text-muted-foreground">
-      <p>Corolla XEi 2022 · 38.400 km</p>
-      <p>Última revisão em 12 de maio.</p>
+    <DrawerBody className="text-sm text-muted-foreground">
+      <div className="space-y-1">
+        <p>Corolla XEi 2022 · 38.400 km</p>
+        <p>Última revisão em 12 de maio.</p>
+      </div>
     </DrawerBody>
   </DrawerContent>
 </Drawer>
@@ -42,9 +44,11 @@ neutra e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
     <DrawerHeader>
       <DrawerTitle>Editar veículo</DrawerTitle>
     </DrawerHeader>
-    <DrawerBody className="space-y-2">
-      <Label htmlFor="vehicle-owner">Responsável</Label>
-      <Input id="vehicle-owner" defaultValue="Marina Alves" />
+    <DrawerBody>
+      <div className="space-y-2">
+        <Label htmlFor="vehicle-owner">Responsável</Label>
+        <Input id="vehicle-owner" defaultValue="Marina Alves" />
+      </div>
     </DrawerBody>
     <DrawerFooter>
       <ButtonGroup mode="spaced">
@@ -98,13 +102,14 @@ rodapé produz uma linha só. A tela não escreve `border-b` nem `border-t`.
 
 O cabeçalho reconhece quatro slots — `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e
 `DrawerActions` — e posiciona cada um: a navegação abre a linha, a mídia vem antes do título, 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 `DrawerBody`.
+título ocupa a folga, as ações vão para o extremo oposto e o botão de fechar entra depois delas. A
+navegação fica a `0.5rem` do título, ou da mídia que o antecede, para se ler junto dele; as ações
+mantêm a distância maior da família. Um nó que não seja um desses slots interrompe a renderização
+com um erro; contexto e conteúdo pertencem ao `DrawerBody`.
 
-`DrawerMedia` é a moldura de ícone do Opus — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
-identificar o tipo do recurso aberto. `DrawerNavigation` carrega o retorno de um fluxo encadeado,
-em que o painel permanece aberto e troca de etapa.
+`DrawerMedia` reserva o espaço que identifica o tipo do recurso aberto, sem acrescentar moldura.
+Componha [`IconTile`](/ui/icon-tile) quando ela ajudar na hierarquia. `DrawerNavigation` carrega o
+retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa.
 
 ```tsx preview
 <Drawer>
@@ -118,8 +123,10 @@ em que o painel permanece aberto e troca de etapa.
           <ArrowLeft />
         </Button>
       </DrawerNavigation>
-      <DrawerMedia context="primary">
-        <CarFront />
+      <DrawerMedia>
+        <IconTile size="sm" context="primary">
+          <CarFront />
+        </IconTile>
       </DrawerMedia>
       <DrawerTitle>ABC-1D23</DrawerTitle>
       <DrawerActions>
@@ -210,13 +217,10 @@ de continuar, use [`Dialog mode="alert"`](/ui/dialog), que não fecha pelo cliqu
 
 ## Propriedades de DrawerMedia
 
-| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                                                                                  |
-| ----------- | ------------------------------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'sm'`      | Tamanho da moldura e do glifo na escala compartilhada.                                                                     |
-| `context`   | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor.                                                                                              |
-| `variant`   | `'subtle' \| 'outline'`                                                  | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                                                                               |
-| `className` | `string`                                                                 |             | Ajusta a moldura sem substituir a escala.                                                                                  |
-| `asChild`   | `boolean`                                                                | `false`     | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+| 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 DrawerNavigation
 
@@ -244,7 +248,14 @@ de continuar, use [`Dialog mode="alert"`](/ui/dialog), que não fecha pelo cliqu
 
 `DrawerBody` aceita os atributos de `HTMLDivElement` e ocupa a região flexível e rolável entre
 `DrawerHeader` e `DrawerFooter`. O cabeçalho nomeia o painel; contexto relevante entra no começo
-do corpo como texto ou `Alert`.
+do corpo como texto ou `Alert`. Seus filhos diretos recebem o ritmo estrutural; use `flush` quando
+o conteúdo controlar o próprio inset e um wrapper filho para relações internas mais compactas.
+
+| Propriedade | Tipo        | Padrão  | Descrição                                                  |
+| ----------- | ----------- | ------- | ---------------------------------------------------------- |
+| `flush`     | `boolean`   | `false` | Remove o inset para conteúdo que controla o próprio recuo. |
+| `className` | `string`    |         | Ajusta ocupação, overflow, alinhamento ou tipografia.      |
+| `children`  | `ReactNode` |         | Blocos principais do painel.                               |
 
 ## Propriedades de DrawerFooter
 
@@ -252,3 +263,38 @@ do corpo como texto ou `Alert`.
 | ----------- | ----------- | ------ | ------------------------------------------------------------- |
 | `className` | `string`    |        | Ajusta a faixa do rodapé, inclusive a distribuição das ações. |
 | `children`  | `ReactNode` |        | Ações persistentes, normalmente dentro de um `ButtonGroup`.   |
+
+## Intro separada do chrome
+
+Quando o cabeçalho contém apenas o recolhimento, ações globais e o fechamento, use `DrawerIntro`
+como primeiro bloco de `DrawerBody`. Ele exige um `DrawerTitle` e aceita `DrawerIntroActions`.
+Assim o título acompanha o conteúdo rolável enquanto o chrome permanece estável.
+
+```tsx
+<Drawer>
+  <DrawerContent showCloseButton={false}>
+    <DrawerHeader>
+      <DrawerNavigation>
+        <DrawerClose asChild>
+          <Button>Recolher</Button>
+        </DrawerClose>
+      </DrawerNavigation>
+      <DrawerActions>
+        <Button variant="ghost">Conversa</Button>
+      </DrawerActions>
+    </DrawerHeader>
+    <DrawerBody>
+      <DrawerIntro>
+        <DrawerTitle>Editar evento</DrawerTitle>
+        <DrawerIntroActions>
+          <Button variant="outline">Revisar</Button>
+        </DrawerIntroActions>
+      </DrawerIntro>
+      <form>…</form>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+No formato compacto, mantenha `DrawerTitle` e `DrawerActions` no próprio `DrawerHeader`. Para
+comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).