@softize/opus 20.0.0 → 20.1.0

package/CHANGELOG.md

@@ -7,6 +7,52 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 20.1.0 — 2026-09-26
+
+`Content` ganha um slot de mídia e passa a aceitar a moldura integrada ao header também em regiões
+de leitura. Quem não usa as novas props mantém a mesma aparência: `frameVariant="default"` continua
+sendo o padrão, com a borda contínua em `section` e em `fieldset`. Alguns pontos podem pedir ajuste
+sem interromper a aplicação:
+
+- a `legend` de todo `Content as="fieldset"` passa a envolver o título nos wrappers do header
+  (`legend > span[data-slot=content-heading] > …`): um seletor como
+  `legend > [data-slot=content-title]` deixa de casar; use `legend [data-slot=content-title]`;
+- um `ContentHeader` de fieldset com slot inválido lança outra mensagem: “ContentHeader de fieldset
+  aceita somente ContentMedia e ContentTitle; contador, descrição e ações ficam fora da legenda.”
+  Atualize testes que conferem o texto;
+- com `frameVariant="legend"` dentro de uma superfície com fundo próprio, como um `Card` com `bg-*`
+  ou um `Popover`, declare `--surface-background` com esse fundo na superfície (veja **Cor da
+  superfície**);
+- em `advancedFilters.sectionIcons`, um glifo solto ganha a moldura padrão, e testes que buscavam
+  `[data-slot="content-title-icon"]` devem buscar `[data-slot="content-media"]`.
+
+Em detalhe:
+
+- **Mídia no header.** `ContentHeader` aceita `ContentMedia`, e a forma curta de `Content` ganha
+  `media`. O slot já é a moldura de `IconTile`, com a mesma escala e posição em `section` e em
+  `fieldset`: passe só o glifo e escolha `size`, `context` e `variant` no slot. Se você colocava um
+  `IconTile` dentro de `title`, mova-o para `media`; o slot o adota e herda o que ele declara, sem
+  desenhar moldura dentro de moldura. `media` com `null` ou `false` não desenha nada. Em `fieldset`,
+  a mídia é decorativa e não entra no nome do grupo.
+- **Moldura integrada em `section`.** `frameVariant="legend"` deixa de exigir `as="fieldset"`. Em
+  uma `section`, o título continua sendo um heading no nível declarado, e contador, descrição e
+  ações continuam disponíveis; nenhuma `legend` é emitida. Use `as="fieldset"` só para grupos de
+  campos: a `legend` aceita a mídia e o título, e contador, descrição e ações continuam fora dela
+  (ADR 0025).
+- **Cor da superfície.** Para interromper a borda, o header pinta o título e as ações com a
+  variável `--surface-background`. `Card`, `Dialog` e `Drawer` a declaram com o fundo que pintam,
+  então a linha não reaparece atrás do título quando há um `CardBody`, um `DrawerBody` ou outro
+  wrapper transparente no caminho. Fora delas, vale `--background`.
+- **Filtros avançados.** Os ícones de `advancedFilters.sectionIcons` passam a ocupar o
+  `ContentMedia` de cada seção: um glifo solto ganha a moldura padrão, em vez do ícone esmaecido sem
+  moldura, e um `IconTile` é adotado pelo slot com o que declara. Um ícone `null` não desenha
+  moldura.
+
+A página de `Content` mostra a mídia, os dois acabamentos da moldura e a declaração de
+`--surface-background`. A ADR 0025 registra que o acabamento da moldura não altera a semântica; a
+ADR 0023 ganha a emenda do slot de mídia de `Content`, e as ADRs 0020 e 0021, emendas que apontam
+para a 0025.
+
 ## 20.0.0 — 2026-09-26
 
 Esta versão corrige componentes que falhavam em acessibilidade ou em layout, leva o `fill` da

package/docs/adr/0020-icon-tiles-are-explicitly-composed.md

@@ -24,6 +24,14 @@ a mesma base visual porque essas variantes já prometem a moldura.
 `IconTile` é somente apresentação. Quando o ícone aciona algo, deve-se usar `Button` com tamanho
 de ícone e nome acessível.
 
+### Emenda de 2026-09-26 — slots de mídia das superfícies
+
+Os slots de mídia da anatomia de superfícies (ADR 0023), como `CardMedia` e `ContentMedia`, não são
+slots genéricos: assim como `ItemMedia variant="icon"`, eles já prometem a moldura, e o consumidor
+passa só o glifo. `ContentMedia` adota um `IconTile` recebido como filho em vez de desenhar uma
+moldura dentro da outra (ADR 0025). Slots genéricos, como `FieldLegend.icon`, continuam como esta
+ADR descreve.
+
 ## Consequências
 
 - A presença da moldura deixa de ser uma regra implícita da legenda.

package/docs/adr/0021-content-carries-structure-and-semantic-element.md

@@ -30,6 +30,13 @@ uma `section`. A escolha de `fieldset` não define o acabamento visual: quando `
 presente, a moldura é contínua por padrão. Os filtros avançados preservam a legenda integrada à
 borda declarando `frameVariant="legend"`.
 
+### Emenda de 2026-09-26 — o acabamento `legend` também vale para `section`
+
+A ADR 0025 estende `frameVariant="legend"` a `Content as="section"`, para que regiões de leitura
+integrem o header à moldura sem declarar semântica de formulário, e permite `ContentMedia` na
+legenda de um `fieldset`. A regra desta ADR se mantém: `as` escolhe o elemento e a semântica, e
+`frameVariant` escolhe só o acabamento. Na legenda, contador, descrição e ações continuam inválidos.
+
 ## Consequências
 
 - A mesma API nomeia e delimita regiões de leitura e grupos de formulário.

package/docs/adr/0023-surfaces-share-one-anatomy-and-two-layouts.md

@@ -143,7 +143,7 @@ anteriores já os delimitaram:
 
 | Slot | Card | Content | Page | Dialog | Drawer | Pane |
 | --- | --- | --- | --- | --- | --- | --- |
-| Media | sim | não | não | sim (`DialogMedia`) | sim | sim |
+| Media | sim | sim (`ContentMedia`) | não | sim (`DialogMedia`) | sim | sim |
 | Title | sim | sim | sim | sim | sim | sim |
 | Description | sim | sim | não (ADR 0014) | não (ADR 0018) | não (ADR 0018) | não |
 | Meta | não | sim (contador) | não (ADR 0009) | não | não | não |
@@ -163,6 +163,19 @@ de um cabeçalho remontam a linha com `span`, incluindo o ícone dentro do texto
 `Content` permanece sem footer: é uma região nomeada dentro de outra superfície, e um rodapé
 pertence à superfície que a hospeda.
 
+#### Emenda de 2026-09-25 — Content também expõe mídia
+
+A aplicação posterior da anatomia à tela do Evento mostrou que regiões de leitura podem precisar
+da mesma identificação visual que um Card sem deixarem de ser `Content`. Sem um slot próprio, a
+documentação e os consumidores voltavam a inserir o ícone dentro de `ContentTitle`, repetindo o
+desvio que motivou esta ADR.
+
+`ContentHeader` passa a aceitar `ContentMedia`, e o shorthand expõe `media`. A mídia usa a mesma
+moldura de `IconTile` das demais famílias e integra o grupo visual do título. Esse contrato vale
+tanto para `section` quanto para `fieldset`: `as` troca o elemento e a semântica, não a apresentação
+de mídia e título. Na `legend`, contador, descrição e ações continuam indisponíveis porque não
+nomeiam o grupo de campos.
+
 ### 7. Título: hierarquia e tamanho são independentes
 
 O nível semântico vem de `level` (`1`–`6`) ou de `asChild`, e nunca do tamanho visual. O tamanho vem

package/docs/adr/0025-content-frame-treatment-does-not-change-semantics.md

@@ -0,0 +1,134 @@
+# ADR 0025 — O acabamento da moldura de Content não altera sua semântica
+
+- **Status:** aceita.
+- **Data:** 2026-09-25.
+- **Complementa:** ADRs 0021 e 0023.
+
+## Contexto
+
+`Content` separa o elemento semântico (`section` ou `fieldset`) da presença da moldura. Porém, o
+acabamento `frameVariant="legend"`, que integra visualmente o título à borda, só está disponível
+quando a raiz é um `fieldset`.
+
+Essa restrição leva regiões somente de leitura a escolherem `fieldset` apenas para obter o
+acabamento visual. É o caso de grupos de detalhes como Cliente e Veículo: eles formam seções
+nomeadas com `DetailGroup`, não conjuntos de controles de formulário. A aparência desejada se
+parece com uma legenda, mas não transforma o título em uma `legend` semântica.
+
+As forças em tensão são:
+
+- preservar `fieldset` e `legend` exclusivamente para grupos de campos relacionados;
+- oferecer a mesma linguagem visual a regiões de leitura;
+- manter título, mídia, descrição, contador e ações compatíveis com a anatomia normal de `Content`;
+- não criar outra família pública apenas para desenhar uma borda interrompida.
+
+## Decisão
+
+`frameVariant="legend"` passa a ser aceito tanto por `Content as="section"` quanto por
+`Content as="fieldset"`. A propriedade escolhe somente o acabamento da moldura; `as` continua
+sendo a única propriedade que determina o elemento e sua semântica.
+
+Em uma `section`, o título permanece um heading no nível declarado, o header continua aceitando
+`ContentMedia`, `ContentMeta`, `ContentDescription` e `ContentActions`, e a borda é visualmente
+interrompida ao redor das regiões do header que a ocupam. Nenhum elemento `legend` é emitido.
+
+Em um `fieldset`, o título continua sendo a `legend` nativa e pode ser precedido pelo mesmo
+`ContentMedia` usado em uma `section`. A mídia é decorativa e acompanha o nome do grupo; contador,
+descrição e ações continuam fora da legenda. `as` altera a semântica, não a apresentação do par
+mídia + título nem o comportamento nativo de formulários.
+
+O nome `legend` descreve o acabamento visual existente e não cria um terceiro valor incompatível
+para o mesmo desenho. A documentação deve apresentar primeiro a escolha semântica e depois o
+acabamento, deixando explícito que uma região de leitura permanece `section`.
+
+Para interromper a linha sem depender da transparência dos wrappers intermediários, Card, Dialog e
+Drawer declaram `--surface-background` com o token que já usam (`--background` ou `--card`). As
+regiões do header que cruzam a borda usam essa cor; quando não houver uma superfície declarada,
+`Content` usa `--background` como fallback. O nome segue o papel da variável, como os demais
+contratos CSS locais, sem prefixo de pacote. Uma superfície com fundo próprio que não seja uma
+dessas três, como um `Card` com `bg-*`, um `Popover` ou um contêiner da aplicação, declara a mesma
+variável com o fundo que pinta.
+
+### Relação com a ADR 0020
+
+A ADR 0020 mantém genéricos os slots de ícone, como `FieldLegend.icon`: o consumidor passa o glifo
+quando quer só o ícone e compõe `IconTile` quando quer a moldura. `ContentMedia` não é um slot
+genérico; é o slot de mídia da anatomia de superfícies (ADR 0023), que já promete a moldura, como
+`CardMedia` e `ItemMedia variant="icon"`. Por isso a mídia de `Content` sempre desenha a moldura, e
+`asChild` continua sendo a saída para uma marca com visual próprio.
+
+Consumidores que já compunham `IconTile` antes deste slot existir não devem ganhar moldura dentro de
+moldura. `ContentMedia` adota um `IconTile` recebido como filho: o slot assume o lugar dele e herda
+`size`, `context`, `variant` e as demais props declaradas nele. `media` com `null` ou `false` é
+tratado como ausência, e nenhuma moldura vazia é desenhada. Os ícones de
+`advancedFilters.sectionIcons` da `ActionList` passam pelo mesmo slot, sem normalização própria.
+
+## Consequências
+
+- Regiões de leitura podem integrar o header à moldura sem declarar semântica de formulário.
+- A composição `Content + DetailGroup` preserva `section`, heading, mídia, descrição, contador e
+  ações.
+- Grupos de campos continuam usando `fieldset` e `legend` quando essa relação existe no conteúdo.
+- Filtros e regiões de leitura usam o mesmo slot, escala e alinhamento para mídia e título.
+- O default permanece `frameVariant="default"`; quem não usa as novas props não muda visualmente.
+- `advancedFilters.sectionIcons` muda: um glifo solto, antes exibido sem moldura, passa a ocupar o
+  `ContentMedia` e ganha a moldura padrão. Um `IconTile` continua com a aparência que declara.
+- A `legend` de todo `Content as="fieldset"` passa a envolver título e mídia nos wrappers do
+  `SurfaceHeader` (`legend > span[data-slot=content-heading] > …`). Seletores que dependiam do
+  título como filho direto da `legend` precisam ser ajustados.
+- O acabamento precisa funcionar sobre as superfícies canônicas sem o consumidor reconstruir a
+  borda ou posicionar o header por classes próprias.
+- Wrappers transparentes entre a superfície e `Content` não deixam a borda aparecer atrás do grupo
+  de heading ou das ações, porque a cor vem da variável declarada pela superfície e não do pai.
+- Superfícies com fundo próprio fora de Card, Dialog e Drawer ficam responsáveis por declarar
+  `--surface-background`; sem isso, a faixa atrás do header usa `--background`.
+
+## Alternativas consideradas
+
+### Usar `fieldset` também para detalhes somente de leitura
+
+Reaproveitaria a implementação atual, mas atribuiria semântica de grupo de formulário a uma lista
+de definições. Foi descartada porque a escolha do elemento passaria a ser governada pela aparência.
+
+### Criar outro componente de painel
+
+Separaria esse desenho de `Content`, mas duplicaria a anatomia de região nomeada e voltaria a exigir
+uma decisão entre estruturas equivalentes. Foi descartada porque `Content` já é responsável pelo
+header, corpo e moldura da região.
+
+### Criar um novo valor visual com o mesmo desenho
+
+Um nome como `notched` evitaria a associação com a `legend`, mas criaria dois valores para o mesmo
+acabamento e uma migração sem ganho observável. Foi descartado porque o contrato já afirma que
+`frameVariant` não altera a semântica.
+
+### Herdar o background do pai imediato
+
+Manteria a implementação restrita a `Content`, mas `background-color: inherit` recebe
+`transparent` quando `DrawerBody`, `CardBody` ou outro wrapper não pinta o próprio fundo. Foi
+descartado porque o acabamento depende da superfície que efetivamente pinta, não do pai estrutural
+mais próximo.
+
+### Redesenhar a borda em segmentos
+
+Evitaria cobrir a linha com uma cor, mas exigiria derivar segmentos antes, entre e depois de título,
+descrição e ações com larguras dinâmicas. Foi descartado porque duplicaria no CSS a anatomia que o
+header já organiza.
+
+## Verificação
+
+- Testes de UI confirmam que `Content as="section"` com `frameVariant="legend"` mantém `section`,
+  heading e todos os slots do header.
+- Testes confirmam que o mesmo acabamento em `fieldset` continua emitindo `legend` e restringindo
+  seus slots.
+- Testes confirmam que o default continua usando a moldura contínua nos dois elementos.
+- Testes confirmam que Card, Dialog e Drawer declaram `--surface-background` e que o grupo de
+  heading e as ações do header usam essa variável, com `--background` como fallback. A herança da
+  variável através de wrappers transparentes é comportamento do CSS, não é provada pela happy-dom e
+  depende de conferência visual no catálogo, onde a página de `Content` a demonstra sobre um `Card`.
+- Testes confirmam que um `IconTile` passado como mídia é adotado pelo slot, que `null` e `false`
+  não desenham mídia e que um glifo solto em `sectionIcons` ganha a moldura.
+- Um teste confirma que `Page layout="fill"` leva a altura até a `ActionList` através de um
+  `Content` com `frameVariant="legend"` (ADR 0024).
+- A documentação demonstra `Content + DetailGroup` no acabamento `legend` sem usar `fieldset` e
+  mantém `Content as="fieldset" + FieldGroup` para grupos de controles.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "20.0.0",
+  "version": "20.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/patterns/content-header.tsx

@@ -10,9 +10,14 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import { IconTile, type IconTileProps } from "../primitives/icon-tile.tsx";
 import { fillRegionClassName, useFillRegion } from "./fill-region.ts";
 import { headingTags } from "./heading-level.ts";
 import { usePageHeadingPresence } from "./page-heading-context.tsx";
+import {
+  SurfaceMedia,
+  type SurfaceMediaProps,
+} from "./surface-media.tsx";
 import {
   SurfaceHeader,
   surfaceHeaderClasses,
@@ -59,7 +64,8 @@ interface ContentSectionBaseProps
     Omit<ComponentProps<"section">, "children" | "title"> {
   /** Elemento semântico da região. */
   as?: "section";
-  frameVariant?: "default";
+  /** Tratamento visual da moldura: contínua (default) ou integrada ao header. */
+  frameVariant?: ContentFrameVariant;
   /** Nível semântico do heading, independente de seu destaque visual. */
   level?: ContentHeaderLevel;
 }
@@ -78,6 +84,8 @@ interface ContentFieldsetBaseProps
 
 interface ContentSectionShorthandProps extends ContentSectionBaseProps {
   title: ReactNode;
+  /** Ícone ou imagem que identifica a região, antes do título. */
+  media?: ReactNode;
   /** Total de itens ao lado do título da seção. A página não carrega contador (ADR 0009). */
   count?: number;
   description?: ReactNode;
@@ -87,6 +95,8 @@ interface ContentSectionShorthandProps extends ContentSectionBaseProps {
 
 interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
   title: ReactNode;
+  /** Ícone ou imagem decorativa que acompanha o título dentro da legenda. */
+  media?: ReactNode;
   count?: never;
   description?: never;
   actions?: never;
@@ -95,6 +105,7 @@ interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
 
 interface ContentComposedProps {
   title?: never;
+  media?: never;
   count?: never;
   description?: never;
   actions?: never;
@@ -111,6 +122,7 @@ export type ContentProps =
 export function Content({
   as = "section",
   title,
+  media,
   count,
   description,
   actions,
@@ -164,6 +176,7 @@ export function Content({
   const anatomy = shorthand ? (
     <>
       <ContentHeader>
+        {hasContentMedia(media) && <ContentMedia>{media}</ContentMedia>}
         <ContentTitle>{title}</ContentTitle>
         {count !== undefined && <ContentMeta>{count}</ContentMeta>}
         {description !== undefined && (
@@ -214,7 +227,12 @@ export function Content({
           aria-labelledby={ariaLabelledBy}
           className={cn(
             "space-y-3",
-            framed && "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "default" &&
+              "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "legend" &&
+              "rounded-lg border border-border px-4 pb-4",
             fill.filling && fillRegionClassName,
             className,
           )}
@@ -244,20 +262,15 @@ export function ContentHeader({
     "Content",
   );
   if (content.element === "fieldset") {
-    const nodes = Children.toArray(children);
-    if (
-      nodes.length !== 1 ||
-      !isValidElement(nodes[0]) ||
-      nodes[0].type !== ContentTitle
-    ) {
-      throw new Error(
-        "ContentHeader de fieldset exige somente um ContentTitle; contador, descrição e ações ficam fora da legenda.",
-      );
-    }
     return (
       <ContentHeaderContext.Provider value={content}>
-        <legend
-          data-slot="content-header"
+        <SurfaceHeader
+          as="legend"
+          name="ContentHeader"
+          slot="content"
+          slots={{ media: ContentMedia, title: ContentTitle }}
+          mediaPlacement="heading"
+          invalidMessage="ContentHeader de fieldset aceita somente ContentMedia e ContentTitle; contador, descrição e ações ficam fora da legenda."
           className={cn(
             content.framed &&
               content.frameVariant === "default" &&
@@ -270,7 +283,7 @@ export function ContentHeader({
           {...props}
         >
           {children}
-        </legend>
+        </SurfaceHeader>
       </ContentHeaderContext.Provider>
     );
   }
@@ -280,12 +293,25 @@ export function ContentHeader({
         name="ContentHeader"
         slot="content"
         slots={{
+          media: ContentMedia,
           title: ContentTitle,
           count: ContentMeta,
           description: ContentDescription,
           actions: ContentActions,
         }}
+        mediaPlacement="heading"
         className={cn(
+          content.framed &&
+            content.frameVariant === "legend" &&
+            "flex items-center [&>[data-slot=content-actions]]:-mr-2 [&>[data-slot=content-actions]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-actions]]:px-2 [&>[data-slot=content-heading]]:-ml-2 [&>[data-slot=content-heading]]:w-fit [&>[data-slot=content-heading]]:max-w-full [&>[data-slot=content-heading]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-heading]]:px-2",
+          content.framed &&
+            content.frameVariant === "legend" &&
+            content.variant === "section" &&
+            "-mt-4 min-h-8",
+          content.framed &&
+            content.frameVariant === "legend" &&
+            content.variant === "page" &&
+            "-mt-5 min-h-10",
           content.variant === "page" &&
             "flex-row items-center justify-start gap-3",
           className,
@@ -298,6 +324,59 @@ export function ContentHeader({
   );
 }
 
+/** `null`, `false` e `undefined` não desenham mídia: uma moldura vazia não identifica nada. */
+function hasContentMedia(media: ReactNode): boolean {
+  return media !== undefined && media !== null && media !== false;
+}
+
+/**
+ * Um `IconTile` recebido como filho não vira uma segunda moldura: o slot assume o lugar dele e
+ * herda o que ele declara (`size`, `context`, `variant`, demais props), somando as classes.
+ */
+function adoptIconTile(props: SurfaceMediaProps): SurfaceMediaProps {
+  const { children, asChild, className } = props;
+  if (asChild) return props;
+  // `toArray`, não `only`: um array com um único item (de um `map`/`filter`) é válido aqui.
+  const nodes = Children.toArray(children);
+  if (nodes.length !== 1) return props;
+  const child = nodes[0];
+  if (!isValidElement<IconTileProps>(child) || child.type !== IconTile) {
+    return props;
+  }
+  // `null` em size/context/variant significa "use o padrão" no IconTile: fica o do slot.
+  const declared = Object.fromEntries(
+    Object.entries(child.props).filter(([, value]) => value != null),
+  ) as SurfaceMediaProps;
+  return {
+    ...props,
+    ...declared,
+    className: cn(className, declared.className),
+    children: declared.children,
+  };
+}
+
+/** Moldura de ícone ou imagem que identifica a região nomeada. */
+export function ContentMedia({
+  size = "xs",
+  ...rest
+}: SurfaceMediaProps): ReactElement {
+  const context = requiredContext(
+    useContext(ContentHeaderContext),
+    "ContentMedia",
+    "ContentHeader",
+  );
+  const props = adoptIconTile({ size, ...rest });
+  return (
+    <SurfaceMedia
+      slot="content-media"
+      {...props}
+      aria-hidden={
+        context.element === "fieldset" ? true : props["aria-hidden"]
+      }
+    />
+  );
+}
+
 export function ContentTitle({
   className,
   id,

package/src/ui/components/patterns/list.tsx

@@ -1218,20 +1218,8 @@ function AdvancedFiltersDialog({
                 frameVariant={
                   sectionVariant === "framed" ? "legend" : "default"
                 }
-                title={
-                  <span className="flex items-center gap-2">
-                    {sectionIcons?.[section] !== undefined && (
-                      <span
-                        data-slot="content-title-icon"
-                        aria-hidden="true"
-                        className="inline-flex shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4"
-                      >
-                        {sectionIcons[section]}
-                      </span>
-                    )}
-                    {section}
-                  </span>
-                }
+                title={section}
+                media={sectionIcons?.[section]}
               >
                 <FieldGroup className={cn("grid gap-4", gridColumns)}>
                   {entries.map(field)}

package/src/ui/components/patterns/surface-header.tsx

@@ -45,10 +45,12 @@ interface SurfaceHeaderSlots {
   title: ElementType;
   count?: ElementType;
   description?: ElementType;
-  actions: ElementType;
+  actions?: ElementType;
 }
 
 export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** Elemento estrutural; `legend` preserva a mesma anatomia com wrappers phrasing. */
+  as?: "div" | "legend";
   /** Nome do componente público, para as mensagens de erro (`PageHeader`, `ContentHeader`). */
   name: string;
   /** Prefixo dos `data-slot` (`page` → `page-header`, `page-heading`). */
@@ -57,6 +59,8 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
   slots: SurfaceHeaderSlots;
   /** Posição de um slot introdutório opcional, antes da linha ou dentro dela. */
   leadingPlacement?: "above" | "inline";
+  /** Mantém a mídia na linha geral ou a agrupa com o heading. */
+  mediaPlacement?: "row" | "heading";
   /** Classes de um container interno quando a moldura precisa ocupar toda a largura. */
   contentClassName?: string;
   /** Permite uma superfície composta apenas pelas regiões leading/actions. */
@@ -71,6 +75,11 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
    * NOMEIAM algo (Card, Dialog, Drawer, Page, Content) continuam estritas.
    */
   allowFreeContent?: boolean;
+  /**
+   * Mensagem própria para uma composição inválida, quando a regra do header não cabe na
+   * mensagem genérica (a legenda de um fieldset aceita menos slots que o header comum).
+   */
+  invalidMessage?: string;
 }
 
 /** Expande fragments de primeiro nível: o shorthand monta os slots dentro de um `<>`. */
@@ -83,19 +92,23 @@ function flatten(children: ReactNode): ReactNode[] {
 }
 
 export function SurfaceHeader({
+  as: Root = "div",
   name,
   slot,
   slots,
   leadingPlacement = "above",
+  mediaPlacement = "row",
   contentClassName,
   titleRequired = true,
   rowClassName,
   trailing,
   allowFreeContent = false,
+  invalidMessage,
   className,
   children,
   ...props
 }: SurfaceHeaderProps): ReactElement {
+  const Wrapper = Root === "legend" ? "span" : "div";
   const nodes = flatten(children);
   const of = (type: ElementType) =>
     nodes.filter((node) => isValidElement(node) && node.type === type);
@@ -111,7 +124,8 @@ export function SurfaceHeader({
   const counts = slots.count === undefined ? [] : of(slots.count);
   const descriptions =
     slots.description === undefined ? [] : of(slots.description);
-  const actionSlots = of(slots.actions);
+  const actionSlots =
+    slots.actions === undefined ? [] : of(slots.actions);
   const slotTypes = [
     ...leadingTypes,
     slots.media,
@@ -167,6 +181,7 @@ export function SurfaceHeader({
         isValidElement(node) ? [node.type as ElementType] : [],
       ),
     );
+    if (invalidMessage !== undefined) throw new Error(invalidMessage);
     throw new Error(
       distinctLeading.size > 1
         ? `${name} aceita ${[...distinctLeading].map(label).join(" ou ")} na região introdutória, nunca os dois na mesma superfície.`
@@ -174,24 +189,42 @@ export function SurfaceHeader({
     );
   }
 
+  const titleLine = titles.length + counts.length > 0 && (
+    <Wrapper className="flex items-baseline gap-2">
+      {titles}
+      {counts}
+    </Wrapper>
+  );
   const heading = titles.length +
     counts.length +
     descriptions.length +
-    free.length >
+    free.length +
+    (mediaPlacement === "heading" ? medias.length : 0) >
     0 && (
-    <div
+    <Wrapper
       data-slot={`${slot}-heading`}
       className={cn("min-w-0", leadingPlacement === "inline" && "flex-1")}
     >
-      {titles.length + counts.length > 0 && (
-        <div className="flex items-baseline gap-2">
-          {titles}
-          {counts}
-        </div>
+      {mediaPlacement === "heading" && medias.length > 0 ? (
+        <Wrapper
+          data-slot={`${slot}-heading-row`}
+          className="flex items-center gap-2"
+        >
+          {medias}
+          <Wrapper data-slot={`${slot}-heading-content`} className="min-w-0">
+            {titleLine}
+            {descriptions}
+            {free}
+          </Wrapper>
+        </Wrapper>
+      ) : (
+        <>
+          {titleLine}
+          {descriptions}
+          {free}
+        </>
       )}
-      {descriptions}
-      {free}
-    </div>
+    </Wrapper>
   );
   // A região introdutória carrega o mesmo `data-slot` nas duas apresentações: seletor de teste
   // ou de CSS que funcione no header padrão precisa funcionar na barra.
@@ -200,14 +233,14 @@ export function SurfaceHeader({
       {leadingPlacement === "inline" && leading.length > 0 && (
         // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
         // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
-        <div
+        <Wrapper
           data-slot={`${slot}-navigation`}
           className={cn("flex min-w-0 items-center", !heading && "flex-1")}
         >
           {leading}
-        </div>
+        </Wrapper>
       )}
-      {medias}
+      {mediaPlacement === "row" && medias}
       {heading}
       {actionSlots}
       {trailing}
@@ -215,15 +248,15 @@ export function SurfaceHeader({
   );
   const layout =
     leadingPlacement === "inline" ? (
-      <div className={cn("flex min-w-0 items-center gap-3", rowClassName)}>
+      <Wrapper className={cn("flex min-w-0 items-center gap-3", rowClassName)}>
         {row}
-      </div>
+      </Wrapper>
     ) : leading.length > 0 ? (
       <>
-        <div data-slot={`${slot}-navigation`} className="mb-4">
+        <Wrapper data-slot={`${slot}-navigation`} className="mb-4">
           {leading}
-        </div>
-        <div
+        </Wrapper>
+        <Wrapper
           data-slot={`${slot}-header-row`}
           className={cn(
             actionSlots.length > 0 &&
@@ -232,7 +265,7 @@ export function SurfaceHeader({
         >
           {heading}
           {actionSlots}
-        </div>
+        </Wrapper>
       </>
     ) : (
       <>
@@ -242,7 +275,7 @@ export function SurfaceHeader({
     );
 
   return (
-    <div
+    <Root
       data-slot={`${slot}-header`}
       className={cn(
         contentClassName === undefined &&
@@ -257,10 +290,10 @@ export function SurfaceHeader({
       {contentClassName === undefined ? (
         layout
       ) : (
-        <div data-slot={`${slot}-header-content`} className={contentClassName}>
+        <Wrapper data-slot={`${slot}-header-content`} className={contentClassName}>
           {layout}
-        </div>
+        </Wrapper>
       )}
-    </div>
+    </Root>
   );
 }

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

@@ -52,7 +52,7 @@ export function Card({
         data-slot="card"
         data-layout={layout}
         className={cn(
-          "rounded-xl border border-border bg-card text-card-foreground",
+          "rounded-xl border border-border bg-card text-card-foreground [--surface-background:var(--card)]",
           // Seccionado: o divisor encosta na borda, então o raio precisa recortar.
           layout === "sectioned" && "overflow-hidden",
           className,

package/src/ui/components/primitives/dialog.tsx

@@ -230,7 +230,7 @@ export function DialogContent({
   const { mode } = useDialogContext();
   const showClose = showCloseButton ?? mode !== "alert";
   const contentClasses =
-    "fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] overflow-clip rounded-xl border border-transparent bg-background text-foreground shadow-xl duration-200 outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:border-border/70";
+    "fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] overflow-clip rounded-xl border border-transparent bg-background text-foreground shadow-xl duration-200 outline-none [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:border-border/70";
 
   if (mode === "alert") {
     return (

package/src/ui/components/primitives/drawer.tsx

@@ -117,7 +117,7 @@ function DrawerContent({
         data-slot="drawer-content"
         data-layout={layout}
         className={cn(
-          "fixed z-50 flex flex-col bg-background shadow-lg transition ease-in-out data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
+          "fixed z-50 flex flex-col bg-background shadow-lg transition ease-in-out [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
           side === "right" &&
             "inset-y-0 right-0 h-full w-3/4 max-w-sm border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right",
           side === "left" &&

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

@@ -96,10 +96,11 @@ apresentação para o consumidor, como cards de status acima da lista. No modal,
 `section` formam um grupo, e `advancedFilters.columns` distribui os grupos em até três colunas.
 Use `advancedFilters.sectionIcons` quando os grupos representarem dimensões recorrentes; a chave é
 o mesmo rótulo de `section`, e cada grupo usa `Content as="fieldset"` para manter uma legenda
-nativa. Quando os grupos precisarem de limites mais explícitos,
-`advancedFilters.sectionVariant: 'framed'` envolve cada seção e pede ao `Content` o acabamento
-`frameVariant="legend"`, integrando visualmente a legenda à borda sem atribuir esse design à
-semântica de `fieldset`.
+nativa. O ícone ocupa a mídia do grupo, antes do título, e recebe a moldura padrão: passe só o
+glifo. Um `IconTile` é adotado pela mídia com o que declara, e um ícone `null` não desenha nada.
+Quando os grupos precisarem de limites mais explícitos, `advancedFilters.sectionVariant: 'framed'`
+envolve cada seção e pede ao `Content` o acabamento `frameVariant="legend"`, integrando visualmente
+a legenda à borda sem atribuir esse design à semântica de `fieldset`.
 Um filtro `select` pode declarar `searchable: true` quando a lista fechada for longa; a opção geral
 continua disponível e participa da busca. Campos de data avançados usam calendário. A antiga `advanced: true` continua aceita durante a
 migração e equivale a `placement: 'advanced'`.
@@ -138,8 +139,8 @@ filters: {
     columns: 2,
     sectionVariant: 'framed',
     sectionIcons: {
-      Relacionamento: <IconTile size="xs"><UserRound /></IconTile>,
-      Datas: <IconTile size="xs"><CalendarDays /></IconTile>,
+      Relacionamento: <UserRound />,
+      Datas: <CalendarDays />,
     },
   }}
 />

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

@@ -31,21 +31,15 @@ render(
 
 Use `framed` quando título e corpo precisarem formar uma única região delimitada. A moldura pertence
 ao `Content`; componentes internos, como `DetailGroup`, continuam responsáveis somente pelo layout
-e pela semântica dos próprios dados.
+e pela semântica dos próprios dados. Por padrão, a borda permanece contínua e o header fica dentro
+do recuo da região.
 
 ```tsx preview col
 render(
   <Content
     framed
-    title={
-      <span className="flex items-center gap-2">
-        <UserRound
-          className="size-4 text-muted-foreground"
-          aria-hidden="true"
-        />
-        Cliente
-      </span>
-    }
+    title="Cliente"
+    media={<UserRound aria-hidden="true" />}
   >
     <DetailGroup columns={2}>
       <DetailField label="Nome" value="Carla Souza" />
@@ -55,16 +49,66 @@ render(
 );
 ```
 
+## Header integrado à moldura
+
+Quando uma região compacta precisar integrar visualmente o header à borda, use
+`frameVariant="legend"`. O acabamento não muda a semântica: uma região de leitura continua sendo
+uma `section`, o título continua sendo um heading e descrição, contador e ações permanecem
+disponíveis.
+
+```tsx preview col
+render(
+  <Content
+    framed
+    frameVariant="legend"
+    title="Veículo"
+    media={<CarFront aria-hidden="true" />}
+  >
+    <DetailGroup columns={2}>
+      <DetailField label="Placa" value="ABC1D23" />
+      <DetailField label="Modelo" value="Corolla XEi" />
+    </DetailGroup>
+  </Content>,
+);
+```
+
+Para interromper a borda, o header pinta o título e as ações com o fundo da superfície que hospeda o
+`Content`, lido da variável CSS `--surface-background`. `Card`, `Dialog` e `Drawer` já a declaram
+com o fundo que pintam; fora deles, vale `--background`. Uma superfície com fundo próprio, como um
+`Card` com `bg-*`, um `Popover` ou um contêiner da aplicação, precisa declarar a variável com o
+mesmo fundo. Sem isso, a faixa atrás do título aparece com a cor da página.
+
+```tsx preview col
+render(
+  <Card className="bg-muted [--surface-background:var(--muted)]">
+    <CardBody>
+      <Content framed frameVariant="legend" title="Veículo">
+        <DetailGroup columns={2}>
+          <DetailField label="Placa" value="ABC1D23" />
+          <DetailField label="Modelo" value="Corolla XEi" />
+        </DetailGroup>
+      </Content>
+    </CardBody>
+  </Card>,
+);
+```
+
 ## Grupo de campos
 
 Quando a região nomear um conjunto de campos relacionados, use `as="fieldset"`. O `Content`
 renderiza o título como `legend`, preserva as props nativas do `fieldset` e mantém o mesmo contrato
 de título e corpo. Essa escolha altera somente a semântica e o comportamento nativo; com `framed`,
-a moldura permanece contínua. Nesse modo, contador, descrição e ações não entram na legenda.
+a moldura permanece contínua. A mídia usa a mesma apresentação da `section`; contador, descrição e
+ações não entram na legenda.
 
 ```tsx preview col
 render(
-  <Content as="fieldset" framed title="Proprietário">
+  <Content
+    as="fieldset"
+    framed
+    title="Proprietário"
+    media={<UserRound aria-hidden="true" />}
+  >
     <FieldGroup>
       <Field>
         <FieldLabel htmlFor="owner-name">Nome</FieldLabel>
@@ -79,8 +123,9 @@ render(
 );
 ```
 
-Quando a legenda precisar integrar visualmente a borda, declare essa escolha separadamente. Use
-`frameVariant="legend"` em agrupamentos compactos, como as seções de filtros avançados.
+O mesmo acabamento pode integrar a legenda nativa à borda. Declare `frameVariant="legend"` em
+agrupamentos compactos, como as seções de filtros avançados; `as="fieldset"` continua sendo a
+decisão semântica, e não uma forma de obter esse desenho.
 
 ```tsx preview col
 render(
@@ -104,13 +149,16 @@ render(
 
 Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
 `ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
-uma descrição, um contador (`ContentMeta`) e uma região de ações. O contador é próprio de
-`Content`; `PageHeader` reconhece somente navegação, título e ações.
+uma mídia (`ContentMedia`), uma descrição, um contador (`ContentMeta`) e uma região de ações. O
+contador é próprio de `Content`; `PageHeader` reconhece somente navegação, título e ações.
 
 ```tsx preview col
 render(
   <Content level={2}>
     <ContentHeader>
+      <ContentMedia>
+        <Monitor aria-hidden="true" />
+      </ContentMedia>
       <ContentTitle>Dispositivos conectados</ContentTitle>
       <ContentMeta>3</ContentMeta>
       <ContentDescription>Sessões com acesso à sua conta.</ContentDescription>
@@ -166,6 +214,7 @@ classes adicionais; um `Content` irmão, sem lista, mantém a altura do próprio
 | Propriedade    | Tipo                         | Padrão      | Descrição                                                                                                               |
 | -------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
 | `title`        | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                                      |
+| `media`        | `ReactNode`                  |             | Forma curta: ícone ou imagem que identifica a região antes do título.                                                   |
 | `count`        | `number`                     |             | Forma curta: total de itens ao lado do título da região.                                                                |
 | `description`  | `ReactNode`                  |             | Forma curta: frase de apoio sob o título.                                                                               |
 | `actions`      | `ReactNode`                  |             | Forma curta: ações sobre a região inteira, no extremo oposto ao título.                                                 |
@@ -173,11 +222,30 @@ classes adicionais; um `Content` irmão, sem lista, mantém a altura do próprio
 | `variant`      | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície.                |
 | `as`           | `'section' \| 'fieldset'`    | `'section'` | Usa uma região com heading ou um grupo de campos cujo título é a legenda nativa.                                        |
 | `framed`       | `boolean`                    | `false`     | Envolve o header e o body com a moldura estrutural da região.                                                           |
-| `frameVariant` | `'default' \| 'legend'`      | `'default'` | Em `fieldset` com moldura, mantém a borda contínua ou integra visualmente a legenda à borda. Não altera a semântica.    |
+| `frameVariant` | `'default' \| 'legend'`      | `'default'` | Mantém a borda contínua ou integra visualmente o header à moldura. Não altera o elemento nem sua semântica.             |
 | `children`     | `ReactNode`                  |             | Corpo da região na forma curta, ou `ContentHeader` e `ContentBody` na composição explícita.                             |
 
 As demais propriedades são as nativas de `section` ou, com `as="fieldset"`, de `fieldset`.
 
-Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e
-`ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`
-próprios — a hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.
+Na composição explícita de uma `section`, `ContentHeader` recebe `ContentMedia`, `ContentTitle`,
+`ContentMeta`, `ContentDescription` e `ContentActions`. Em `fieldset`, recebe `ContentMedia` e
+`ContentTitle`, preservando a apresentação enquanto a legenda continua nomeando somente o grupo de
+campos. `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level` próprios — a
+hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.
+
+## Propriedades de ContentMedia
+
+| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                                                                                   |
+| ----------- | ------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'xs'`      | 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. |
+
+`ContentMedia` já é a moldura. Passe só o glifo e escolha `size`, `context` e `variant` no slot. Um
+`IconTile` passado em `media` ou dentro de `ContentMedia` não vira moldura dentro de moldura: o slot
+assume o lugar dele e herda o que ele declara. `media` com `null` ou `false` não desenha nada.
+
+Em `fieldset`, a mídia é sempre decorativa: o `Content` a esconde da árvore de acessibilidade para
+que o grupo seja anunciado apenas pelo título.

package/src/ui/docs/content/icon-tile.md

@@ -13,24 +13,24 @@ com tamanho de ícone e um nome acessível.
 O tamanho controla a caixa e o glifo pela escala compartilhada dos controles. Um ícone que declara
 uma classe `size-*` preserva a própria medida.
 
-## Em uma legenda
+## Em slots de ícone e de mídia
 
-Slots de ícone não criam a moldura automaticamente. Componha `IconTile` somente quando ela fizer
-sentido para a superfície, como na legenda de um [`Content`](/ui/content) emoldurado.
+Slots genéricos de ícone, como `FieldLegend.icon`, não criam a moldura: passe o glifo quando quiser
+só o ícone e componha `IconTile` quando a moldura reforçar a hierarquia.
+
+Os slots de mídia das superfícies já são um `IconTile`: `CardMedia`, `ContentMedia`, `DialogMedia`,
+`DrawerMedia` e `PaneMedia` desenham a moldura sozinhos. Passe só o glifo e escolha `size`,
+`context` e `variant` no próprio slot. Em [`Content`](/ui/content), um `IconTile` passado em
+`media` é adotado pelo slot, que herda o que ele declara, em vez de desenhar uma moldura dentro da
+outra.
 
 ```tsx preview col md
 <Content
   as="fieldset"
   framed
   frameVariant="legend"
-  title={
-    <span className="flex items-center gap-2">
-      <IconTile size="xs">
-        <CarFront />
-      </IconTile>
-      Veículo
-    </span>
-  }
+  title="Veículo"
+  media={<CarFront aria-hidden="true" />}
 >
   <FieldGroup>
     <Field>

package/src/ui/meta.ts

@@ -123,7 +123,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      'Estruture uma região com título e corpo. No caso comum, declare título, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `as="fieldset"` para agrupar campos sob uma legenda nativa e `frameVariant="legend"` somente quando essa legenda precisar integrar visualmente a borda. Componha ContentHeader apenas quando precisar controlar a anatomia.',
+      'Estruture uma região com título e corpo. No caso comum, declare título, mídia, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `frameVariant="legend"` para integrar visualmente o header à borda e `as="fieldset"` somente para agrupar campos sob uma legenda nativa. Componha ContentHeader apenas quando precisar controlar a anatomia.',
   },
   copyable: {
     name: "copyable",

package/src/ui/react.tsx

@@ -487,6 +487,7 @@ export type {
 export {
   Content,
   ContentHeader,
+  ContentMedia,
   ContentTitle,
   ContentDescription,
   ContentMeta,