@softize/opus 23.0.0 → 24.0.0

package/CHANGELOG.md

@@ -7,6 +7,87 @@ 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.
 
+## 24.0.0 — 2026-10-01
+
+`ToggleGroup` passa a compartilhar a gramática estrutural de `ButtonGroup`: `mode` aceita
+`connected`, `spaced`, `divided` e o novo `segmented`; `distribution` aceita `content` e `equal`;
+`orientation`, `shape` e `framed` permanecem eixos independentes. A aparência segmentada mantém
+escolhas curtas numa superfície compartilhada e destaca o controle ativo dentro dela. Filtros
+`select` com `presentation: "toggle"` passam a usar esse modo; estado, URL, defaults e input da
+action não mudam.
+
+O tema passa a distinguir canvas, superfícies elevadas, controles e estados neutros com tokens
+opacos por papel. No tema claro, o canvas quase branco sustenta cards e popovers brancos; inputs,
+hover, seleção e pressão deixam de depender de alpha sobre a superfície ancestral. Os componentes
+usam os mesmos papéis nos dois temas, enquanto cada tema calibra somente os valores.
+
+A escala neutra passa a ser derivada de quatro eixos de aparência por modo — intensidade de cor,
+contraste, brilho das superfícies e contraste entre camadas —, cada um de 0 a 100, lidos de
+`--appearance-light-*` e `--appearance-dark-*` (ADR 0044). Com os eixos no preset, o tema é
+exatamente o calibrado; quem não personaliza não precisa mudar nada. Os limites impedem que um
+ajuste reduza a separação entre os papéis ou o contraste do texto sobre as superfícies em repouso
+abaixo do preset, e a intensidade tinge somente os neutros, no matiz de `--neutral-hue`. O novo
+módulo sem React `@softize/opus/ui/appearance`, também reexportado por `@softize/opus/ui` e
+`@softize/opus/ui/react`, publica tipos, presets e o helper que converte overrides parciais em
+custom properties. Reset é a remoção dos overrides pela aplicação; o Opus não publica componente
+de ajuste nem guarda a preferência. Um app que redeclara diretamente um token neutro continua
+funcionando, mas esse token deixa de acompanhar os eixos.
+
+No preset, seleção persistente também se afasta mais do hover transitório nos dois temas. Navegação
+ativa permanece reconhecível mesmo sem depender de texto em negrito, enquanto pressão conserva um
+degrau próprio além da seleção.
+
+`ToggleGroup mode="segmented"` usa `bg-card` no item ativo, e `Tabs framed` aproxima a linha dos
+triggers com inset próprio. `PageHeader`, `DialogHeader` e `DrawerHeader` aceitam navegação e ações
+sem título; `SurfaceHeader` aceita ações sem título. O título pode permanecer no conteúdo de modais
+por meio das novas `DialogIntro` e `DrawerIntro`. `DetailGroup` ganha `elevation` e passa a usar
+`raised` por padrão, inclusive em `plain`; declare `elevation="none"` quando o agrupamento tiver de
+permanecer no mesmo plano do pai.
+
+### Breaking
+
+`ToggleGroupItem` foi removido. Use `Toggle` como filho de `ToggleGroup` e informe `value`; fora do
+grupo, `Toggle` continua usando `pressed`, `defaultPressed` e `onPressedChange`. `spacing` também foi
+removido: use `mode="connected"` no lugar de zero e `mode="spaced"` no lugar de valores positivos.
+Não há aliases de compatibilidade porque o único consumidor é migrado atomicamente.
+
+`Content*` e `Card*` foram removidos da API pública. Use `Surface` e seus slots
+`SurfaceHeader`, `SurfaceMedia`, `SurfaceTitle`, `SurfaceDescription`, `SurfaceMeta`,
+`SurfaceActions`, `SurfaceBody` e `SurfaceFooter`. A raiz agora é `div` por padrão; declare
+`as="section"`, `as="article"` ou `as="fieldset"` quando o documento exigir essa semântica.
+`framed` acrescenta borda, `elevation="raised"` acrescenta o fundo elevado e
+`layout="sectioned"` cria as faixas com divisores. `frameVariant` não existe mais.
+
+`SurfaceMedia` reserva posição e não cria `IconTile`: componha o tile explicitamente quando o
+ícone precisar de moldura. O recuo estrutural de superfícies limitadas passa de `1.25rem` para
+`1rem`, títulos internos usam `text-sm` e conteúdos que já controlam o próprio recuo declaram
+`flush` em `SurfaceBody`. Essas mudanças são intencionais e não têm aliases de compatibilidade.
+
+`DialogMedia` e `DrawerMedia` seguem o mesmo contrato sem decoração de
+`SurfaceMedia`. As propriedades `size`, `context`, `variant` e `asChild` foram removidas desses
+slots: passe o glifo, a imagem ou a marca diretamente; quando precisar de moldura, componha
+`IconTile` com essas propriedades. `Dialog mode="alert"` também deixa de aumentar ou emoldurar a
+mídia automaticamente.
+
+Bodies estruturais passam a governar o ritmo entre seus filhos diretos com intervalo de `1.5rem`.
+O layout do pai decide o inset; no seccionado, Surface, Dialog e Drawer usam `1rem` lateral e
+`1.5rem` vertical. `DialogBody` e `DrawerBody` ganham `flush`, como `SurfaceBody`.
+Migração: remova `space-*`, `gap-*` e padding de `className` no body; use um wrapper para relações
+internas e `flush` somente quando o filho controlar o próprio inset. `opus check` cobra a regra.
+
+`Pane` passa a ser somente a unidade de dimensionamento de `Split`. As propriedades `inset` e
+`layout`, além de `PaneHeader`, `PaneBody`, `PaneContent`, `PaneFooter`, `PaneMedia`, `PaneTitle`,
+`PaneDescription` e `PaneActions`, foram removidas sem aliases. Migração: componha uma `Surface`
+dentro do pane quando precisar de anatomia visual; para navegação ou conteúdo especializado, deixe
+o próprio filho declarar organização e rolagem.
+
+### Novidades
+
+`DialogIntro` e `DrawerIntro` formalizam o título do conteúdo quando o header do modal é reservado
+a navegação, ações globais e fechamento. Cada intro exige o título da família e aceita
+`DialogIntroActions` ou `DrawerIntroActions`; no formato compacto, título e ações continuam no
+header. O body permanece dono do ritmo e da rolagem (ADR 0048).
+
 ## 23.0.0 — 2026-09-29
 
 Esta major conclui a separação entre contrato e dados de design, simplifica a hierarquia de

package/bin/cli.mjs

@@ -433,6 +433,8 @@ Regras da UI (@softize/opus/ui):
   ui-structure-split      — filho direto de Split que não é Pane (elemento HTML, texto,
                             outro componente Opus ou componente do próprio arquivo); o
                             Split lança erro ao renderizá-lo
+  ui-structure-body-rhythm — padding, gap ou space aplicado diretamente a um Body;
+                             use o ritmo nativo, flush ou um wrapper filho
   ui-semantic-api         — API semântica: \`context\` + \`variant\`; reprova aliases de
                             migração e \`tone\` em novos dicionários
   removed-ui-token        — token público removido (ring-edge, shadow-card…) com a

package/bin/lib/check.mjs

@@ -128,40 +128,34 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
-  ["ContentHeader", new Set(["Content"])],
-  ["ContentBody", new Set(["Content"])],
-  ["ContentTitle", new Set(["ContentHeader"])],
-  ["ContentDescription", new Set(["ContentHeader"])],
-  ["ContentMeta", new Set(["ContentHeader"])],
-  ["ContentActions", new Set(["ContentHeader"])],
-  ["CardHeader", new Set(["Card"])],
-  ["CardBody", new Set(["Card"])],
-  ["CardFooter", new Set(["Card"])],
-  ["CardMedia", new Set(["CardHeader"])],
-  ["CardTitle", new Set(["CardHeader"])],
-  ["CardDescription", new Set(["CardHeader"])],
-  ["CardAction", new Set(["CardHeader"])],
+  // As regiões de Surface não são estritas: com `asChild`, elas ficam dentro do elemento que
+  // recebe a superfície (ADR 0045). Os slots do header são filhos diretos dele.
+  ["SurfaceHeader", new Set(["Surface"])],
+  ["SurfaceBody", new Set(["Surface"])],
+  ["SurfaceFooter", new Set(["Surface"])],
+  ["SurfaceMedia", new Set(["SurfaceHeader"])],
+  ["SurfaceTitle", new Set(["SurfaceHeader"])],
+  ["SurfaceDescription", new Set(["SurfaceHeader"])],
+  ["SurfaceMeta", new Set(["SurfaceHeader"])],
+  ["SurfaceActions", new Set(["SurfaceHeader"])],
   ["DialogHeader", new Set(["DialogContent"])],
   ["DialogBody", new Set(["DialogContent"])],
   ["DialogFooter", new Set(["DialogContent"])],
+  ["DialogIntro", new Set(["DialogBody"])],
+  ["DialogIntroActions", new Set(["DialogIntro"])],
   ["DialogNavigation", new Set(["DialogHeader"])],
   ["DialogMedia", new Set(["DialogHeader"])],
-  ["DialogTitle", new Set(["DialogHeader"])],
+  ["DialogTitle", new Set(["DialogHeader", "DialogIntro"])],
   ["DialogActions", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
   ["DrawerBody", new Set(["DrawerContent"])],
   ["DrawerFooter", new Set(["DrawerContent"])],
+  ["DrawerIntro", new Set(["DrawerBody"])],
+  ["DrawerIntroActions", new Set(["DrawerIntro"])],
   ["DrawerNavigation", new Set(["DrawerHeader"])],
   ["DrawerMedia", new Set(["DrawerHeader"])],
-  ["DrawerTitle", new Set(["DrawerHeader"])],
+  ["DrawerTitle", new Set(["DrawerHeader", "DrawerIntro"])],
   ["DrawerActions", new Set(["DrawerHeader"])],
-  ["PaneHeader", new Set(["Pane", "Sidebar"])],
-  ["PaneBody", new Set(["Pane", "Sidebar"])],
-  ["PaneFooter", new Set(["Pane", "Sidebar"])],
-  ["PaneMedia", new Set(["PaneHeader"])],
-  ["PaneTitle", new Set(["PaneHeader"])],
-  ["PaneDescription", new Set(["PaneHeader"])],
-  ["PaneActions", new Set(["PaneHeader"])],
   ["AlertMedia", new Set(["Alert"])],
   ["AlertHeader", new Set(["Alert"])],
   ["AlertActions", new Set(["Alert"])],
@@ -205,12 +199,15 @@ const UI_STRUCTURAL_ROOTS = new Map([
     },
   ],
   [
-    "Content",
+    "Surface",
     {
-      header: "ContentHeader",
-      body: "ContentBody",
-      shorthand: new Set(["title", "description", "count", "actions"]),
-      removed: new Map([["meta", "use `count`"]]),
+      header: "SurfaceHeader",
+      body: "SurfaceBody",
+      footer: "SurfaceFooter",
+      // Cada região é opcional, a forma curta convive com SurfaceBody e SurfaceFooter, e sem
+      // região nenhuma a Surface é uma caixa de filhos livres (ADR 0045).
+      flexible: true,
+      shorthand: new Set(["title", "media", "description", "count", "actions"]),
     },
   ],
 ]);
@@ -223,18 +220,61 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageBack",
   "PageNavigation",
   "PageActions",
-  "ContentHeader",
-  "ContentBody",
-  "ContentTitle",
-  "ContentDescription",
-  "ContentMeta",
-  "ContentActions",
+  "SurfaceMedia",
+  "SurfaceTitle",
+  "SurfaceDescription",
+  "SurfaceMeta",
+  "SurfaceActions",
   "AlertMedia",
   "AlertHeader",
   "AlertActions",
 ]);
 
+// O body público é a única fonte de inset e ritmo estrutural (ADR 0046). Classes de
+// ocupação, overflow, alinhamento e tipografia continuam livres; relações locais usam
+// um wrapper filho e full bleed usa a prop `flush` das famílias que a oferecem.
+const UI_STRUCTURAL_BODIES = new Set([
+  "SurfaceBody",
+  "DialogBody",
+  "DrawerBody",
+  "PageBody",
+]);
+
+const UI_BODY_RHYTHM_CLASS =
+  /(?:^|:)(?:!?-?)(?:space-[xy]|gap(?:-[xy])?|p|px|py|pt|pr|pb|pl|ps|pe)-/;
+
+const UI_FLUSH_BODIES = new Set(["SurfaceBody", "DialogBody", "DrawerBody"]);
+
 const UI_REMOVED_PROPS = new Map([
+  [
+    "Pane",
+    new Map([
+      ["inset", "mova o recuo para o conteúdo ou para uma `Surface` filha"],
+      ["layout", "use `Surface` para anatomia visual contínua ou seccionada"],
+    ]),
+  ],
+  [
+    "Surface",
+    new Map([["meta", "use `count` para o total ao lado do título"]]),
+  ],
+  [
+    "DialogMedia",
+    new Map([
+      ["size", "dimensione o nó filho"],
+      ["context", "declare o contexto no `IconTile` filho"],
+      ["variant", "declare a variante no `IconTile` filho"],
+      ["asChild", "passe o nó diretamente como filho"],
+    ]),
+  ],
+  [
+    "DrawerMedia",
+    new Map([
+      ["size", "dimensione o nó filho"],
+      ["context", "declare o contexto no `IconTile` filho"],
+      ["variant", "declare a variante no `IconTile` filho"],
+      ["asChild", "passe o nó diretamente como filho"],
+    ]),
+  ],
   [
     "PageHeader",
     new Map([
@@ -262,6 +302,14 @@ const UI_REMOVED_PROPS = new Map([
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
+  ["PaneHeader", "use `SurfaceHeader` dentro de uma `Surface`"],
+  ["PaneBody", "use `SurfaceBody` ou um contêiner próprio do conteúdo"],
+  ["PaneContent", "use `SurfaceBody` ou um contêiner próprio do conteúdo"],
+  ["PaneFooter", "use `SurfaceFooter` dentro de uma `Surface`"],
+  ["PaneMedia", "use `SurfaceMedia` dentro de `SurfaceHeader`"],
+  ["PaneTitle", "use `SurfaceTitle` dentro de `SurfaceHeader`"],
+  ["PaneDescription", "use `SurfaceDescription` dentro de `SurfaceHeader`"],
+  ["PaneActions", "use `SurfaceActions` dentro de `SurfaceHeader`"],
   ["PageIntro", "use `PageHeader` como a única introdução estrutural"],
   ["PageDescription", "mova contexto relevante para o início de `PageBody`"],
   [
@@ -272,11 +320,54 @@ const UI_REMOVED_COMPONENTS = new Map([
     "DrawerDescription",
     "mova contexto relevante para o início de `DrawerBody`",
   ],
+  // Content e Card deram lugar a Surface (ADR 0045).
+  [
+    "Content",
+    'use `Surface as="section"`, ou `as="fieldset"` para um grupo de campos',
+  ],
+  ["ContentHeader", "use `SurfaceHeader`"],
+  [
+    "ContentMedia",
+    "use `SurfaceMedia` e componha `IconTile` quando quiser a moldura",
+  ],
+  ["ContentTitle", "use `SurfaceTitle`"],
+  ["ContentDescription", "use `SurfaceDescription`"],
+  ["ContentMeta", "use `SurfaceMeta`"],
+  ["ContentActions", "use `SurfaceActions`"],
+  ["ContentBody", "use `SurfaceBody`"],
+  ["Card", 'use `Surface framed elevation="raised"`'],
+  ["CardHeader", "use `SurfaceHeader`"],
+  [
+    "CardMedia",
+    "use `SurfaceMedia` e componha `IconTile` quando quiser a moldura",
+  ],
+  ["CardTitle", "use `SurfaceTitle` e declare `level` em `Surface`"],
+  ["CardDescription", "use `SurfaceDescription`"],
+  ["CardAction", "use `SurfaceActions`"],
+  ["CardBody", "use `SurfaceBody`"],
+  ["CardContent", "use `SurfaceBody`"],
+  ["CardFooter", "use `SurfaceFooter`"],
 ]);
 
 const UI_STRUCTURAL_CONTAINERS = new Set(["PageShell"]);
 
 const UI_STRUCTURAL_HEADERS = new Map([
+  [
+    "DialogIntro",
+    {
+      title: "DialogTitle",
+      optional: new Set(["DialogIntroActions"]),
+      shorthand: new Set(),
+    },
+  ],
+  [
+    "DrawerIntro",
+    {
+      title: "DrawerTitle",
+      optional: new Set(["DrawerIntroActions"]),
+      shorthand: new Set(),
+    },
+  ],
   [
     "PageHeader",
     {
@@ -288,15 +379,19 @@ const UI_STRUCTURAL_HEADERS = new Map([
     },
   ],
   [
-    "ContentHeader",
+    "SurfaceHeader",
     {
-      title: "ContentTitle",
+      title: "SurfaceTitle",
       optional: new Set([
-        "ContentDescription",
-        "ContentMeta",
-        "ContentActions",
+        "SurfaceMedia",
+        "SurfaceDescription",
+        "SurfaceMeta",
+        "SurfaceActions",
       ]),
-      shorthand: new Set(["title", "description", "meta", "actions"]),
+      shorthand: new Set(),
+      // Slots condicionais (`{cond && <SurfaceActions />}`) são composição legítima; o runtime
+      // valida o que de fato foi renderizado.
+      allowOpaque: true,
     },
   ],
   [
@@ -1085,6 +1180,57 @@ function directStructuralChildren(node, imports) {
   return { names, hasOpaque };
 }
 
+function countImportedJsxDescendants(node, imports, component) {
+  const boundary =
+    component === "DialogTitle"
+      ? "DialogContent"
+      : component === "DrawerTitle"
+        ? "DrawerContent"
+        : undefined;
+  const count = (child, root = false) => {
+    if (
+      !root &&
+      (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child))
+    ) {
+      const local = jsxLocalName(child);
+      const imported = local === null ? undefined : imports.get(local);
+      if (imported === boundary) return 0;
+      if (imported === component) return 1;
+    }
+    if (ts.isConditionalExpression(child)) {
+      return (
+        count(child.condition) +
+        Math.max(count(child.whenTrue), count(child.whenFalse))
+      );
+    }
+    let total = 0;
+    ts.forEachChild(child, (descendant) => {
+      total += count(descendant);
+    });
+    return total;
+  };
+  return count(node, true);
+}
+
+/**
+ * Diz se o JSX literal prova um filho livre ao lado das regiões: texto, elemento HTML ou outro
+ * componente do Opus. Expressões e componentes de outros módulos ficam de fora, porque só o
+ * runtime sabe o que eles renderizam.
+ */
+function hasLiteralFreeChild(node, imports, regionNames) {
+  if (!ts.isJsxElement(node)) return false;
+  return node.children.some((child) => {
+    if (ts.isJsxText(child)) return child.text.trim() !== "";
+    if (!ts.isJsxElement(child) && !ts.isJsxSelfClosingElement(child))
+      return false;
+    const local = jsxLocalName(child);
+    if (local === null) return false;
+    const imported = imports.get(local);
+    if (imported !== undefined) return !regionNames.includes(imported);
+    return /^[a-z]/.test(local);
+  });
+}
+
 /**
  * Componentes declarados no próprio arquivo (função, classe ou arrow/function atribuída).
  * Um deles nunca é o `Pane` do Opus, então o `Split` recusaria o elemento mesmo que o
@@ -1270,7 +1416,7 @@ function countPageHeadingSources(page, imports) {
         const local = jsxLocalName(node);
         if (
           local !== null &&
-          ((imports.get(local) === "Content" &&
+          ((imports.get(local) === "Surface" &&
             jsxNumericAttribute(node, "level") === 1) ||
             imports.get(local) === "PageState")
         ) {
@@ -1410,6 +1556,36 @@ export function checkUiStructure(file, text) {
         }
       }
 
+      if (component !== null && UI_STRUCTURAL_BODIES.has(component)) {
+        const overridden = jsxStringAttributeValues(
+          jsxOpening(node),
+          "className",
+        )
+          .flatMap((value) => value.trim().split(/\s+/))
+          .filter((token) => UI_BODY_RHYTHM_CLASS.test(token));
+        if (overridden.length > 0) {
+          add(
+            node,
+            component,
+            `${component} já governa inset e ritmo: remova ${[...new Set(overridden)].map((token) => `\`${token}\``).join(", ")}; ${UI_FLUSH_BODIES.has(component) ? "use `flush` para full bleed ou " : "use "}um wrapper filho para relações internas.`,
+            "ui-structure-body-rhythm",
+          );
+        }
+      }
+
+      if (component === "DialogContent" || component === "DrawerContent") {
+        const title =
+          component === "DialogContent" ? "DialogTitle" : "DrawerTitle";
+        if (countImportedJsxDescendants(node, imports, title) > 1) {
+          add(
+            node,
+            component,
+            `${component} aceita um único ${title}: mantenha o título no header ou na intro, nunca nos dois.`,
+            "ui-structure-duplicate-title",
+          );
+        }
+      }
+
       const header =
         component === null ? undefined : UI_STRUCTURAL_HEADERS.get(component);
       if (header !== undefined) {
@@ -1514,7 +1690,30 @@ export function checkUiStructure(file, text) {
         // some aqui.
         // Com filhos estruturais, o que as regras de forma acham é defeito independente: misturar
         // shorthand com slots, ou um filho inesperado, não some quando a prop sai.
-        if (removedProp && !structural) {
+        if (root.flexible) {
+          const regionNames = [root.header, root.body, root.footer];
+          const regions = children.names.filter((name) =>
+            regionNames.includes(name),
+          );
+          if (shorthand && regions.includes(root.header)) {
+            add(
+              node,
+              component,
+              `${component} não permite misturar a forma curta com ${root.header} explícito.`,
+              "ui-structure-mode",
+            );
+          } else if (
+            regions.length > 0 &&
+            (new Set(regions).size !== regions.length ||
+              hasLiteralFreeChild(node, imports, regionNames))
+          ) {
+            add(
+              node,
+              component,
+              `${component} com slots estruturais aceita no máximo um ${root.header}, um ${root.body} e um ${root.footer} como filhos diretos e não os mistura com filhos livres: envolva o conteúdo em ${root.body}.`,
+            );
+          }
+        } else if (removedProp && !structural) {
           // Nada a acrescentar; os filhos seguem sendo visitados no fim de `visit`.
         } else if (shorthand && structural) {
           add(
@@ -1573,7 +1772,7 @@ export function checkUiStructure(file, text) {
               add(
                 node,
                 component,
-                "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState dentro de PageBody.",
+                "Page explícito exige exatamente um heading principal em PageHeader, Surface level={1} ou PageState dentro de PageBody.",
               );
             }
           }

package/bin/lib/copy.mjs

@@ -94,12 +94,8 @@ const JSX_CHILD_ROLES = new Map([
   ['BreadcrumbLink', 'breadcrumb'],
   ['BreadcrumbPage', 'breadcrumb'],
   ['Button', 'button'],
-  ['CardDescription', 'description'],
-  ['CardTitle', 'title'],
   ['CommandEmpty', 'empty-state'],
   ['CommandItem', 'menu-item'],
-  ['ContentDescription', 'description'],
-  ['ContentTitle', 'title'],
   ['DialogDescription', 'dialog-body'],
   ['DialogTitle', 'title'],
   ['DrawerDescription', 'dialog-body'],
@@ -124,8 +120,8 @@ const JSX_CHILD_ROLES = new Map([
   // comando. Classificado como `button`, a política universal cobraria verbo de ação.
   ['PageBack', 'breadcrumb'],
   ['PageTitle', 'title'],
-  ['PaneDescription', 'description'],
-  ['PaneTitle', 'title'],
+  ['SurfaceDescription', 'description'],
+  ['SurfaceTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
   ['TabsListItem', 'tab'],
@@ -222,20 +218,6 @@ const JSX_PROP_ROLES = new Map([
     ]),
   ],
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
-  [
-    'Content',
-    new Map([
-      ['title', 'title'],
-      ['description', 'description'],
-    ]),
-  ],
-  [
-    'ContentHeader',
-    new Map([
-      ['title', 'title'],
-      ['description', 'description'],
-    ]),
-  ],
   [
     'DataState',
     new Map([
@@ -290,6 +272,13 @@ const JSX_PROP_ROLES = new Map([
       ['emptyText', 'empty-state'],
     ]),
   ],
+  [
+    'Surface',
+    new Map([
+      ['title', 'title'],
+      ['description', 'description'],
+    ]),
+  ],
   ['Textarea', new Map([['placeholder', 'placeholder']])],
 ])
 
@@ -363,20 +352,6 @@ const JSX_PROP_CLASS = new Map([
     ]),
   ],
   ['CommandInput', new Map([['placeholder', 'className']])],
-  [
-    'Content',
-    new Map([
-      ['title', 'className'],
-      ['description', 'className'],
-    ]),
-  ],
-  [
-    'ContentHeader',
-    new Map([
-      ['title', 'className'],
-      ['description', 'className'],
-    ]),
-  ],
   ['Input', new Map([['placeholder', 'className']])],
   ['InputGroupInput', new Map([['placeholder', 'className']])],
   ['InputGroupTextarea', new Map([['placeholder', 'className']])],
@@ -394,6 +369,13 @@ const JSX_PROP_CLASS = new Map([
     ]),
   ],
   ['Select', new Map([['placeholder', 'className']])],
+  [
+    'Surface',
+    new Map([
+      ['title', 'className'],
+      ['description', 'className'],
+    ]),
+  ],
   ['Textarea', new Map([['placeholder', 'className']])],
 ])
 

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

@@ -1,5 +1,11 @@
 # ADR 0023 — Superfícies compartilham uma anatomia e dois layouts
 
+> **Atualização em 2026-10-01:** a ADR 0046 torna o body responsável pelo ritmo entre seus filhos
+> diretos e dá ao conteúdo um respiro vertical maior que o das faixas; “regiões simétricas” abaixo
+> descreve a implementação original. A ADR 0047 também remove `Pane` desta família: ele passa a ser
+> somente a unidade de layout de `Split`, enquanto `Surface`, `Dialog` e `Drawer` preservam a
+> anatomia.
+
 - **Status:** aceita.
 - **Data:** 2026-09-23.
 - **Complementa:** ADRs 0005, 0014, 0018, 0019 e 0021.

package/docs/adr/0039-filter-presentation-is-independent-from-filter-type.md

@@ -22,9 +22,9 @@ preserva `select` como apresentação padrão.
 
 `toggle` aplica-se a filtros `type: "select"` de escolha única e usa as mesmas opções, valor de
 repouso, regra de vazio, dependências e atualização de estado do controle padrão. A apresentação
-mostra todas as opções em um `ToggleGroup` conectado e não permite desmarcar a opção ativa quando o
-filtro não aceita vazio. Quando a opção vem de um dicionário e sua entrada declara um ícone do
-catálogo, o grupo apresenta ícone e rótulo juntos.
+mostra todas as opções em um `ToggleGroup`; a composição visual vigente é definida pela ADR 0042.
+O controle não permite desmarcar a opção ativa quando o filtro não aceita vazio. Quando a opção vem
+de um dicionário e sua entrada declara um ícone do catálogo, o grupo apresenta ícone e rótulo juntos.
 
 O tipo do filtro continua descrevendo o valor e sua operação. A apresentação escolhe somente o
 controle usado para editá-lo.

package/docs/adr/0040-tabs-use-a-single-navigation-presentation.md

@@ -21,9 +21,8 @@ A anatomia pública nomeia a posição de cada parte: `TabsListItem` pertence a
 `TabsPanel` identifica o painel associado. Os nomes anteriores, `TabsTrigger` e `TabsContent`, não
 são mantidos como aliases porque há um único consumidor e a migração é atômica.
 
-Escolhas únicas ou múltiplas que alteram um valor no contexto atual usam `ToggleGroup`. Quando o
-grupo precisa de um contorno conectado, o consumidor declara `variant="outline"` com `spacing={0}`;
-a borda pertence aos itens e as arestas internas duplicadas são removidas pela primitiva.
+Escolhas únicas ou múltiplas que alteram um valor no contexto atual usam `ToggleGroup`. A composição
+visual vigente do grupo é definida pela ADR 0042.
 
 ## Consequências
 
@@ -31,7 +30,7 @@ a borda pertence aos itens e as arestas internas duplicadas são removidas pela
 - Filtros e escolhas de formulário não usam semântica de tabs para obter uma aparência compacta.
 - Consumidores removem `variant="line"`; não há substituição para a antiga superfície preenchida.
 - Consumidores renomeiam `TabsTrigger` para `TabsListItem` e `TabsContent` para `TabsPanel`.
-- A documentação de ToggleGroup explicita como formar o contorno conectado.
+- A documentação de ToggleGroup explicita seus modos de composição.
 
 ## Alternativas descartadas
 
@@ -56,5 +55,5 @@ da anatomia exposta ao consumidor. `ListItem` e `Panel` deixam a composição le
 - testes da primitiva confirmam a linha-base, o indicador ativo e a distribuição;
 - testes do `ActionFilterBar` confirmam que `presentation: "toggle"` usa seleção exclusiva sem
   alterar o estado transportado para a action;
-- a documentação de Tabs não oferece apresentação preenchida e a de ToggleGroup demonstra o grupo
-  conectado com borda.
+- a documentação de Tabs não oferece apresentação preenchida e a de ToggleGroup demonstra seus
+  modos próprios de escolha.