@softize/opus 21.0.1 → 22.1.0

package/CHANGELOG.md

@@ -7,6 +7,77 @@ 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.
 
+## 22.1.0 — 2026-09-28
+
+Os dados do modo design saem do contrato (ADR 0037). No modo design, toda action passa a responder
+sem que o contrato declare nada: a resposta é gerada pelo `fake` a partir do `output`, a mesma
+requisição recebe a mesma resposta, uma `list` devolve três páginas do tamanho pedido em `limit` (20
+por padrão) pela paginação declarada, e a saída repete o `id` da entrada quando o schema aceita.
+Quando o design precisa de coerência, um cenário escrito com `defineDesignScenario`, do novo
+`@softize/opus/design`, responde no lugar da resposta gerada. O plugin encontra os cenários pela
+opção `scenarios` de `opusDesign()`, com caminhos ou globs; um cenário de action inexistente, ou
+dois cenários para a mesma action, impedem o runtime de design de subir, e o erro lista os nomes.
+
+`mockHandler` fica obsoleto. Ele ainda responde no modo design, abaixo do cenário e acima da
+resposta gerada, e sai na 23.0.0. Os tipos o marcam com `@deprecated`. O `opus check` passa a
+contar, numa linha de aviso que não reprova, quantas actions ainda o declaram. A sonda
+`/__opus/design` ganha `scenarios` e `generated`; `mocked` e `unmocked` mantêm o formato anterior.
+
+O template de `opus create` e as skills `create-opus-action` e `test-opus-action` deixam de ensinar
+`mockHandler`.
+
+**O que fazer:** nada é obrigatório nesta versão. Para migrar, apague os `mockHandler` dos
+contratos; se a resposta de algum importar para o design, transforme-a em cenário e aponte a opção
+`scenarios` do plugin para o lugar onde os cenários ficam. Testes que usavam `runAction` com
+`OPUS_MODE=design` para exercitar o mock devem testar a action ligada ao handler.
+
+## 22.0.0 — 2026-09-28
+
+As superfícies passam a usar uma introdução única e ganham composições explícitas para conteúdo
+seccionado, abas emolduradas e grupos de ações divididos. A mudança elimina wrappers e classes que
+os consumidores repetiam para montar essas formas, além de alinhar Drawer e Content ao raio
+estrutural vigente. É major porque remove `PageIntro`, muda a posição visual do cabeçalho nas páginas
+com `PageShell` e altera o acabamento padrão de Drawer, Tabs `line` e detalhes horizontais com
+divisórias.
+
+### Breaking
+
+**`PageIntro` foi removido.** `PageHeader` é a única introdução da página e reúne, nessa ordem,
+`PageNavigation`, `PageTitle` e `PageActions`. `PageShell` deixou de renderizar uma barra persistente:
+ele fornece navegação e ações contextuais ao header da página ativa. Migração: mova o título e o
+breadcrumb de `PageIntro` para `PageHeader`; remova imports de `PageIntro` e classes que compensavam
+a barra superior. `PageShell.headerClassName` também foi removida porque não existe mais uma barra
+própria para estilizar; remova a propriedade e, quando necessário, estilize o `PageHeader` da página.
+Um header sem conteúdo renderizável não cria região vazia.
+
+**Drawer usa moldura recuada.** `DrawerContent` passa a ter borda completa, `rounded-xl`, recorte e
+`0.25rem` de respiro em relação à viewport. Migração: remova classes locais de borda, raio, recorte e
+inset que reconstruíam essa moldura; preserve apenas dimensões deliberadas, como `max-w-*`.
+
+**`TabsList variant="line"` mudou de composição.** A linha-base respeita a largura recebida, a aba
+usa uma área interna da altura de Button com fundo somente no hover e o indicador ativo usa o
+contexto primário. `DialogBody` e `DrawerBody` não publicam mais `--opus-inline-gutter`. Migração:
+remova classes locais que estendiam a linha, simulavam o botão interno ou compensavam o gutter.
+
+**`DetailGroup` associa o tratamento tabular a `dividers`.** Em orientação horizontal, divisórias
+passam a aplicar padding por célula, fundo sutil nos rótulos e largura padrão de `8.5rem`, com ou sem
+moldura externa. `variant="framed"` sem divisórias deixa de alterar o fundo dos rótulos. Migração:
+declare `dividers` quando quiser a grade tabular; não use `framed` para escolher o tratamento interno.
+
+### Superfícies e controles
+
+- `Content` aceita `layout="continuous" | "sectioned"`. O layout seccionado exige `framed`, separa
+  o header com divisor e deixa o body sem recuo para tabelas, listas e grades que possuem células.
+  Molduras de Content usam `rounded-xl`, inclusive nos acabamentos `default` e `legend`.
+- `Tabs` aceita `framed`, que aplica borda, raio e recorte sem criar fundo próprio, e
+  `distribution="content" | "equal"`, que preserva a largura dos rótulos ou reparte igualmente a
+  largura disponível entre os gatilhos.
+- `ButtonGroup` aceita `framed` e `mode="divided"`; o modo insere divisores orientados entre os
+  controles sem incluí-los no cálculo de `distribution="equal"`.
+- `Button` aceita `context="warning"` em todas as variantes visuais.
+- O filtro composto de período do `ActionList` apresenta período antes do tipo de data, usa divisor
+  estrutural e aplica o foco ao grupo quando qualquer controle interno está aberto.
+
 ## 21.0.1 — 2026-09-26
 
 **Correção.** O `status()` do driver BullMQ podia devolver `status: 'done'` com `data: null` para um

package/bin/cli.mjs

@@ -40,7 +40,15 @@ async function cmdCheck(dir) {
     for (const error of materialization.errors) log('error', `✗ opus check: ${error}`)
     process.exit(1)
   }
-  const { files, actions, contracts, findings, hasMarker } = await scanDir(root)
+  const { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker } = await scanDir(root)
+  // Aviso de migração, não violação: uma linha só, para não poluir o gate a cada execução.
+  if (deprecatedMockHandlers > 0) {
+    log(
+      'warn',
+      `⚠ opus check: ${deprecatedMockHandlers} action(s) ainda declaram \`mockHandler\`, que sai na próxima major. ` +
+        'No modo design, a action sem mock já responde com dado gerado; use `defineDesignScenario` quando o design precisar de um cenário (ADR 0037).',
+    )
+  }
 
   if (actions === 0 && findings.length === 0) {
     const verdict = emptyScanVerdict({ hasMarker, contracts })

package/bin/lib/check.mjs

@@ -121,13 +121,12 @@ const UI_SURFACE_PAIRS = new Map([
 // locais homônimos.
 const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
-  ["PageIntro", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
   ["PageFooter", new Set(["Page"])],
-  ["PageTitle", new Set(["PageHeader", "PageIntro"])],
+  ["PageTitle", new Set(["PageHeader"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
-  ["PageActions", new Set(["PageHeader", "PageIntro"])],
+  ["PageActions", new Set(["PageHeader"])],
   ["ContentHeader", new Set(["Content"])],
   ["ContentBody", new Set(["Content"])],
   ["ContentTitle", new Set(["ContentHeader"])],
@@ -191,11 +190,9 @@ const UI_STRUCTURAL_ROOTS = new Map([
     "Page",
     {
       header: "PageHeader",
-      alternateHeader: "PageIntro",
       body: "PageBody",
       footer: "PageFooter",
       headerRequired: false,
-      allowBothHeaders: true,
       shorthand: new Set(["title", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
@@ -219,7 +216,6 @@ const UI_STRUCTURAL_ROOTS = new Map([
 
 const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageHeader",
-  "PageIntro",
   "PageBody",
   "PageFooter",
   "PageTitle",
@@ -241,7 +237,7 @@ const UI_REMOVED_PROPS = new Map([
   [
     "PageHeader",
     new Map([
-      ["variant", "use `PageShell` para a barra persistente da página"],
+      ["variant", "o cabeçalho da página tem uma única apresentação rolável"],
     ]),
   ],
   [
@@ -265,6 +261,7 @@ const UI_REMOVED_PROPS = new Map([
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
+  ["PageIntro", "use `PageHeader` como a única introdução estrutural"],
   ["PageDescription", "mova contexto relevante para o início de `PageBody`"],
   [
     "DialogDescription",
@@ -289,14 +286,6 @@ const UI_STRUCTURAL_HEADERS = new Map([
       titleRequired: false,
     },
   ],
-  [
-    "PageIntro",
-    {
-      title: "PageTitle",
-      optional: new Set(["PageActions"]),
-      shorthand: new Set(),
-    },
-  ],
   [
     "ContentHeader",
     {
@@ -653,6 +642,8 @@ export function checkProject(sources) {
   const productDeclarations = [];
   const entityNames = new Set();
   const actionNames = new Set();
+  // `mockHandler` obsoleto (ADR 0037): contado, não reprovado — a minor ainda o aceita.
+  let deprecatedMockHandlers = 0;
 
   for (const { file, text } of sources) {
     const declarations = parseDataProducts(file, text);
@@ -677,6 +668,7 @@ export function checkProject(sources) {
         if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
+      if (item.keys.includes("mockHandler")) deprecatedMockHandlers += 1;
     }
   }
 
@@ -782,6 +774,7 @@ export function checkProject(sources) {
     actions,
     contracts,
     dataProducts: productDeclarations.length,
+    deprecatedMockHandlers,
     findings,
   };
 }
@@ -1118,11 +1111,14 @@ const jsxSpaceEntities = {
  * As demais entidades nomeadas ficam como estão: nenhuma delas vira espaço em branco.
  */
 function decodeJsxSpaceEntities(raw) {
-  return raw.replace(/&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g, (entity, dec, hex, name) => {
-    if (name !== undefined) return jsxSpaceEntities[name] ?? entity;
-    const code = dec !== undefined ? Number(dec) : Number.parseInt(hex, 16);
-    return code <= 0x10ffff ? String.fromCodePoint(code) : entity;
-  });
+  return raw.replace(
+    /&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g,
+    (entity, dec, hex, name) => {
+      if (name !== undefined) return jsxSpaceEntities[name] ?? entity;
+      const code = dec !== undefined ? Number(dec) : Number.parseInt(hex, 16);
+      return code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+    },
+  );
 }
 
 /**
@@ -1176,7 +1172,10 @@ function invalidSplitChildren(split, imports, localComponents) {
       return text(node.text, node);
     }
     if (ts.isNumericLiteral(node)) {
-      invalid.push({ label: `o número ${node.text}`, position: node.getStart() });
+      invalid.push({
+        label: `o número ${node.text}`,
+        position: node.getStart(),
+      });
       return;
     }
     if (
@@ -1206,7 +1205,8 @@ function invalidSplitChildren(split, imports, localComponents) {
       for (const nested of node.children) child(nested);
       return;
     }
-    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) element(node);
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node))
+      element(node);
   };
   for (const node of split.children) child(node);
   return invalid;
@@ -1215,7 +1215,8 @@ function invalidSplitChildren(split, imports, localComponents) {
 function directImportedJsxChildren(node, imports) {
   if (!ts.isJsxElement(node)) return [];
   return node.children.flatMap((child) => {
-    if (!ts.isJsxElement(child) && !ts.isJsxSelfClosingElement(child)) return [];
+    if (!ts.isJsxElement(child) && !ts.isJsxSelfClosingElement(child))
+      return [];
     const local = jsxLocalName(child);
     const imported = local === null ? undefined : imports.get(local);
     return imported === undefined ? [] : [{ node: child, component: imported }];
@@ -1224,7 +1225,8 @@ function directImportedJsxChildren(node, imports) {
 
 function jsxNumericAttribute(node, name) {
   const attribute = jsxAttribute(jsxOpening(node), name);
-  if (attribute === undefined || attribute.initializer === undefined) return null;
+  if (attribute === undefined || attribute.initializer === undefined)
+    return null;
   if (
     ts.isJsxExpression(attribute.initializer) &&
     attribute.initializer.expression !== undefined &&
@@ -1243,7 +1245,7 @@ function countPageHeadingSources(page, imports) {
   let count = 0;
   let states = 0;
   for (const child of directImportedJsxChildren(page, imports)) {
-    if (child.component === "PageHeader" || child.component === "PageIntro") {
+    if (child.component === "PageHeader") {
       count += directImportedJsxChildren(child.node, imports).filter(
         (entry) => entry.component === "PageTitle",
       ).length;
@@ -1271,7 +1273,8 @@ function countPageHeadingSources(page, imports) {
 
 function pageBodyHasOpaqueDescendant(page, imports) {
   for (const child of directImportedJsxChildren(page, imports)) {
-    if (child.component !== "PageBody" || !ts.isJsxElement(child.node)) continue;
+    if (child.component !== "PageBody" || !ts.isJsxElement(child.node))
+      continue;
     let opaque = false;
     const visit = (node) => {
       if (opaque) return;
@@ -1323,7 +1326,11 @@ export function checkUiStructure(file, text) {
       const local = jsxLocalName(node);
       const component = local === null ? null : imports.get(local);
       if (component === "Split" && ts.isJsxElement(node)) {
-        for (const child of invalidSplitChildren(node, imports, localComponents)) {
+        for (const child of invalidSplitChildren(
+          node,
+          imports,
+          localComponents,
+        )) {
           findings.push({
             rule: "ui-structure-split",
             level: "error",
@@ -1552,7 +1559,7 @@ export function checkUiStructure(file, text) {
               add(
                 node,
                 component,
-                "Page explícito exige exatamente um heading principal em PageHeader, PageIntro, Content level={1} ou PageState dentro de PageBody.",
+                "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState dentro de PageBody.",
               );
             }
           }
@@ -1918,7 +1925,7 @@ async function walkUiFiles(dir, acc = []) {
   return acc;
 }
 
-/** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
+/** Escaneia um diretório → { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker }.
  *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
 export async function scanDir(rootDir) {
   rootDir = canonicalProjectDirectory(rootDir);
@@ -1948,6 +1955,7 @@ export async function scanDir(rootDir) {
     actions: checked.actions,
     contracts: checked.contracts,
     dataProducts: checked.dataProducts,
+    deprecatedMockHandlers: checked.deprecatedMockHandlers,
     findings: [...checked.findings, ...uiFindings],
     hasMarker,
   };

package/docs/adr/0004-page-content-state-is-composed.md

@@ -8,8 +8,9 @@
 > restaurá-lo em `ready`. A lista de responsabilidades abaixo já descreve o comportamento novo; o
 > adendo no fim deste arquivo registra o motivo, a alternativa descartada e o que se perde.
 >
-> **Atualização (2026-09-10).** Dentro de `PageShell`, o estado integral oculta somente
-> `PageIntro`. A barra pertence à moldura persistente e continua visível (ADR 0011).
+> **Atualização (2026-09-10, superada em 2026-09-28).** A ADR 0011 preservava a barra do
+> `PageShell` e ocultava somente `PageIntro`. A ADR 0029 removeu as duas regiões: `PageHeader` é a
+> única introdução e o estado integral a substitui por inteiro, dentro ou fora de `PageShell`.
 
 ## Contexto
 

package/docs/adr/0005-structural-surfaces-share-an-explicit-anatomy.md

@@ -13,6 +13,9 @@
 > **Atualização (2026-09-16).** O corpo abaixo descreve a anatomia da época em que foi escrito, não a
 > vigente: a apresentação `bar` da ADR 0010 saiu com a ADR 0011, e nenhum header estrutural carrega
 > mais descrição (ADRs 0018 e 0014). A anatomia atual está na documentação de cada família.
+>
+> **Atualização (2026-09-28).** A ADR 0033 substitui a decisão de prender a moldura externa do
+> Drawer à viewport: o painel agora usa moldura completa e recuada.
 
 ## Contexto
 

package/docs/adr/0006-semantic-context-precedes-visual-variant.md

@@ -44,6 +44,13 @@ quanto sua materialização (`btn-danger`, `btn-outline-danger`), mistura hierar
 inclui `light`/`dark`, que pertencem ao tema. Copiar a API manteria a ambiguidade que queremos
 remover. Rejeitada como contrato literal e aceita como referência de vocabulário.
 
+### Representar ações de cautela como neutras, perigosas ou com classes locais
+
+Uma ação pode pedir atenção sem ser destrutiva, como registrar uma tentativa sem sucesso. Tratá-la
+como `neutral` apaga essa diferença; tratá-la como `danger` exagera o risco; aplicar tokens de
+`warning` por `className` cria uma variante clandestina fora do contrato e não alcança tipos,
+documentação nem componentes que reutilizam `ButtonContext`. Rejeitada.
+
 ### Declarar contexto e variante como eixos independentes
 
 `context` escolhe a família de tokens e responde por que existe o realce. `variant` escolhe como a
@@ -59,12 +66,7 @@ O Opus define o vocabulário canônico:
 
 ```ts
 type UiContext =
-  | 'neutral'
-  | 'primary'
-  | 'info'
-  | 'success'
-  | 'warning'
-  | 'danger'
+  "neutral" | "primary" | "info" | "success" | "warning" | "danger";
 ```
 
 - `neutral`: estado normal, inativo ou sem julgamento positivo/negativo;
@@ -86,24 +88,29 @@ domínio não se torna a ação principal da interface. A metadata canônica pas
 Para componentes semânticos, `variant` descreve somente o tratamento visual:
 
 ```ts
-type SemanticVariant = 'solid' | 'subtle' | 'outline' | 'ghost' | 'link'
+type SemanticVariant = "solid" | "subtle" | "outline" | "ghost" | "link";
 ```
 
 Cada componente aceita apenas as variantes que consegue materializar com coerência. Os defaults
 iniciais são:
 
-| Componente | Contexto padrão | Variante padrão | Contextos permitidos |
-| --- | --- | --- | --- |
-| Button | `primary` | `solid` | `neutral`, `primary`, `danger` |
-| Badge | `neutral` | `subtle` | todos |
-| Alert | `neutral` | `subtle` | `neutral`, `info`, `success`, `warning`, `danger` |
-| Dot | `neutral` | `solid` | `neutral`, `primary`, `info`, `success`, `warning`, `danger` |
-| MetricCard | `neutral` | `subtle` no ícone | `neutral`, `info`, `success`, `warning`, `danger` |
+| Componente | Contexto padrão | Variante padrão   | Contextos permitidos                                         |
+| ---------- | --------------- | ----------------- | ------------------------------------------------------------ |
+| Button     | `primary`       | `solid`           | `neutral`, `primary`, `warning`, `danger`                    |
+| Badge      | `neutral`       | `subtle`          | todos                                                        |
+| Alert      | `neutral`       | `subtle`          | `neutral`, `info`, `success`, `warning`, `danger`            |
+| Dot        | `neutral`       | `solid`           | `neutral`, `primary`, `info`, `success`, `warning`, `danger` |
+| MetricCard | `neutral`       | `subtle` no ícone | `neutral`, `info`, `success`, `warning`, `danger`            |
 
 `solid`, `subtle` e `outline` podem compartilhar um contexto sem compartilhar classes. `ghost` e
 `link` ficam restritos a controles interativos. Cor e ícone continuam reforços: texto ou nome
 acessível comunica o significado.
 
+`warning` em `Button` representa uma ação de cautela não destrutiva: a pessoa pode prosseguir, mas
+o efeito merece atenção. `danger` permanece reservado a risco ou consequência perigosa. `info` e
+`success` continuam fora do subconjunto do botão até existir uma necessidade de ação observável;
+estado informativo ou resultado positivo, isoladamente, não justificam colorir um controle.
+
 Componentes cuja `variant` é exclusivamente estrutural ou local, como `plain | framed` e
 `default | line`, podem mantê-la. Ao criar API nova, preferir uma prop específica quando o nome do
 eixo for mais claro (`frame`, `layout`, `appearance`); não renomear primitives existentes sem ganho
@@ -161,6 +168,8 @@ for consultada.
 
 - Primitives semânticos passam a compartilhar um vocabulário e tokens contextuais.
 - Defaults podem variar por componente, mas a mesma palavra nunca muda de significado.
+- Ações de cautela não destrutivas usam os tokens canônicos de `warning`, sem classes locais nem
+  reclassificação como `danger`.
 - A API fica mais explícita em chamadas que precisam dos dois eixos.
 - A transição aumenta temporariamente tipos, testes e normalização por causa dos aliases.
 - Temas precisam oferecer tokens de superfície, borda, texto de ênfase e sólido para cada contexto,

package/docs/adr/0011-page-shell-coordinates-persistent-page-chrome.md

@@ -12,6 +12,11 @@
 > `PageHeader`, `PageIntro` e `PageFooter` como opcionais e exige exatamente um heading principal —
 > `PageTitle`, `Content level={1}` ou um `PageState` ativo. As frases abaixo que pedem `PageIntro`
 > "sem `PageHeader`" descrevem a regra da 17.2 e não valem mais.
+>
+> **Atualização (2026-09-27).** A padronização posterior do chrome estrutural levou a barra do
+> `PageShell` dos `3rem` originais para `3.75rem`. A presença persistente da barra continua sendo a
+> decisão arquitetural desta ADR; sua medida pertence ao contrato vigente do componente, registrado
+> na documentação e nos testes do Opus, e não deve ser redefinida localmente pelo consumidor.
 
 ## Contexto
 

package/docs/adr/0013-presentation-is-a-portable-action-oriented-artifact.md

@@ -7,6 +7,9 @@
 > materializa título e comandos de header no `Content` que envolve o `ActionList`. Dialog e Drawer
 > continuam materializando esses elementos no header da superfície.
 >
+> **Atualização (2026-09-28).** A ADR 0029 removeu `PageIntro` e a barra persistente de
+> `PageShell`. As passagens abaixo sobre a anatomia de Page já refletem a introdução única.
+>
 > Uma Presentation pode declarar uma `route` absoluta com parâmetros. Nessa forma, URL, surface e
 > origem do registro passam a integrar o artefato; o adaptador da aplicação apenas conecta a spec ao
 > router hospedeiro.
@@ -29,10 +32,10 @@ que aparece. `Surface` escolhe `page`, `dialog` ou `drawer` no momento da render
 
 A anatomia portátil é `Header + Body + Footer?`, mas cada surface materializa seu header de acordo
 com o espaço disponível. Dialog e Drawer organizam horizontalmente
-`Navigation? + Title + Actions? + Close` e mantêm as ações de conclusão no footer. Em Page
-hospedada por `PageShell`, a barra persistente reúne navegação e ações; o título inicia o conteúdo
-em `PageIntro`, sem repetir a página atual ao lado do breadcrumb. Fora do shell, a Page materializa
-seu header completo no próprio container.
+`Navigation? + Title + Actions? + Close` e mantêm as ações de conclusão no footer. Em Page,
+`PageHeader` reúne navegação contextual, título e ações numa única introdução rolável. Quando a
+listagem fornece o heading principal por `Content level={1}`, o mesmo header pode conter somente a
+navegação ou as ações fornecidas pelo `PageShell`, sem criar uma segunda região visual.
 
 Uma action assume um de dois papéis:
 

package/docs/adr/0016-list-collection-header-belongs-to-content.md

@@ -4,6 +4,10 @@
 - **Data:** 2026-09-13.
 - **Revisa:** ADRs 0011 e 0013.
 
+> **Atualização (2026-09-28).** A ADR 0029 removeu `PageIntro` e a barra persistente de
+> `PageShell`. As regras abaixo preservam `Content` como dono do cabeçalho da coleção e usam
+> `PageHeader` como a única introdução da página.
+
 ## Contexto
 
 Páginas centradas em uma coleção colocavam o título no `PageIntro`, a criação na barra do
@@ -23,11 +27,12 @@ as ações da coleção, como criar um item. `ActionList` continua responsável
 atualização, visualização, resultados, estados e paginação. `toolbarActions` fica reservado a
 operações ligadas ao recorte corrente da lista, não ao comando primário de criar.
 
-`PageHeader` representa o chrome da página: navegação e ações globais. Dentro de `PageShell`,
-esses slots são projetados na barra; `PageIntro` permanece opcional para uma introdução própria da
-página. Uma `Page` explícita mantém exatamente um heading principal: `PageTitle` em header/intro,
-`Content level={1}` ou um `PageState` ativo no body. Quando `Content` fornece esse heading, a Page
-pode conter somente `PageBody`.
+`PageHeader` é a única introdução da página e reúne navegação contextual, título e ações globais.
+Dentro de `PageShell`, navegação e ações fornecidas pelo shell são compostas nesse mesmo header,
+sem barra persistente. Uma `Page` explícita mantém exatamente um heading principal: `PageTitle` em
+`PageHeader`, `Content level={1}` ou um `PageState` ativo no body. Quando `Content` fornece esse
+heading, a Page pode conter somente `PageBody`; se `PageShell` acrescentar navegação ou ações,
+`Page` materializa automaticamente o `PageHeader` que as recebe.
 
 Na `Presentation`, uma action `list` exibida como Page materializa o título e os comandos de header
 no `Content` que envolve o `ActionList`. Em Dialog e Drawer, o título e esses comandos continuam no
@@ -72,9 +77,9 @@ responsabilidades locais. Foi descartada para coleções; ações realmente glob
 
 ## Verificação
 
-- testes de `Page` cobrem `PageHeader + PageIntro + PageBody` e `PageBody` sem header;
+- testes de `Page` cobrem `PageHeader + PageBody` e `PageBody` sem header;
 - `opus check` aceita essa gramática e continua rejeitando slots duplicados ou fora da família;
-- testes de `Presentation` confirmam que Page de listagem usa `Content` e mantém a barra sem a ação
-  da coleção;
+- testes de `Presentation` confirmam que Page de listagem usa `Content` e mantém a introdução sem a
+  ação da coleção;
 - a documentação de `ActionList` recomenda `Content` e reserva `toolbarActions` ao recorte atual;
 - consumidores validam visualmente o título e a criação junto da listagem.

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

@@ -3,6 +3,7 @@
 - **Status:** aceita.
 - **Data:** 2026-09-23.
 - **Complementa:** ADRs 0005, 0014, 0018, 0019 e 0021.
+- **Superada em parte por:** ADR 0030, que permite anatomia seccionada em `Content` com moldura.
 
 ## Contexto
 
@@ -78,13 +79,13 @@ diferentes para coisas diferentes e permanecem assim.
 
 `continuous` e `sectioned` não são a ausência e a presença de uma borda. Cada um é um pacote:
 
-| Aspecto | `continuous` | `sectioned` |
-| --- | --- | --- |
-| Divisores | nenhum | entre regiões adjacentes presentes |
-| Ritmo vertical | header aproxima-se do corpo; o espaço separa | regiões simétricas; o divisor separa |
-| Escala do título | a da família | a da família, um degrau mais contida quando a família tem duas |
-| Fundo do footer | igual ao da superfície | sutil, quando a família declara |
-| Alinhamento horizontal | idêntico entre header, body e footer | idêntico entre header, body e footer |
+| Aspecto                | `continuous`                                 | `sectioned`                                                    |
+| ---------------------- | -------------------------------------------- | -------------------------------------------------------------- |
+| Divisores              | nenhum                                       | entre regiões adjacentes presentes                             |
+| Ritmo vertical         | header aproxima-se do corpo; o espaço separa | regiões simétricas; o divisor separa                           |
+| Escala do título       | a da família                                 | a da família, um degrau mais contida quando a família tem duas |
+| Fundo do footer        | igual ao da superfície                       | sutil, quando a família declara                                |
+| Alinhamento horizontal | idêntico entre header, body e footer         | idêntico entre header, body e footer                           |
 
 O alinhamento horizontal é invariante dos dois layouts: o recuo lateral de header, body e footer de
 uma mesma superfície é sempre o mesmo valor. É o que a suíte transversal verifica.
@@ -102,15 +103,15 @@ A recomendação de escrever `border-b` e `border-t` no Card sai da documentaç
 Os defaults preservam o que cada família já entrega hoje, exceto onde o comportamento atual é o
 defeito que esta decisão corrige:
 
-| Família | Default | Por quê |
-| --- | --- | --- |
-| `Card` | `continuous` | é o que a família entrega hoje: sem divisores, ritmo assimétrico |
-| `Dialog` (default) | `sectioned` | já tem divisores e faixas; o default nomeia o que existe |
-| `Dialog` (`mode="alert"`) | composição própria | a resposta obrigatória mantém sua anatomia centrada |
-| `Drawer` | `sectioned` | idem Dialog |
-| `Pane` | `sectioned` | header e footer já têm divisor |
-| `Content` | contínuo, sem opção | região semântica dentro de outra superfície |
-| `Page` | contínuo, sem opção | a separação do chrome pertence ao shell |
+| Família                   | Default             | Por quê                                                          |
+| ------------------------- | ------------------- | ---------------------------------------------------------------- |
+| `Card`                    | `continuous`        | é o que a família entrega hoje: sem divisores, ritmo assimétrico |
+| `Dialog` (default)        | `sectioned`         | já tem divisores e faixas; o default nomeia o que existe         |
+| `Dialog` (`mode="alert"`) | composição própria  | a resposta obrigatória mantém sua anatomia centrada              |
+| `Drawer`                  | `sectioned`         | idem Dialog                                                      |
+| `Pane`                    | `sectioned`         | header e footer já têm divisor                                   |
+| `Content`                 | contínuo, sem opção | região semântica dentro de outra superfície                      |
+| `Page`                    | contínuo, sem opção | a separação do chrome pertence ao shell                          |
 
 Nenhum default muda de valor efetivo com esta ADR. O que muda é que o valor passa a ter nome,
 implementação única e teste.
@@ -127,7 +128,7 @@ A migração foi decidida sobre 374 usos reais das seis famílias na plataforma.
   `p-5`, `px-3 py-2`). O root do Card continua sem padding próprio: quem não usa slots continua
   decidindo. O padding pertence aos slots, como hoje.
 - **Os dois `PaneHeader` do produto escrevem quase a mesma linha** (`flex h-[3.75rem] items-center
-  … p-3 … border-b-0`) em contextos diferentes. É a prova de que padding e divisor pertencem à
+… p-3 … border-b-0`) em contextos diferentes. É a prova de que padding e divisor pertencem à
   primitiva.
 - **Um comentário no código do login documenta o defeito**: o `py-3` do `CardBody` "conta com um
   CardFooter, que o login não tem". O ritmo do layout contínuo precisa reagir à ausência do rodapé.
@@ -141,15 +142,15 @@ A migração foi decidida sobre 374 usos reais das seis famílias na plataforma.
 A anatomia é comum; o conjunto de slots continua sendo decisão de cada família, porque decisões
 anteriores já os delimitaram:
 
-| Slot | Card | Content | Page | Dialog | Drawer | Pane |
-| --- | --- | --- | --- | --- | --- | --- |
-| 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 |
-| Actions | sim | sim | sim | sim | sim | sim |
-| Body | sim | sim | sim | sim | sim | sim |
-| Footer | sim | não | sim | sim | sim | sim |
+| Slot        | Card | Content              | Page           | Dialog              | Drawer         | Pane |
+| ----------- | ---- | -------------------- | -------------- | ------------------- | -------------- | ---- |
+| 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  |
+| Actions     | sim  | sim                  | sim            | sim                 | sim            | sim  |
+| Body        | sim  | sim                  | sim            | sim                 | sim            | sim  |
+| Footer      | sim  | não                  | sim            | sim                 | sim            | sim  |
 
 As ADRs 0009, 0014 e 0018 não são reabertas: Page, Dialog e Drawer continuam sem descrição no
 header, e Page continua sem contador. `Dialog`, `Drawer` e `Pane` ganham o slot de ações que hoje

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

@@ -3,6 +3,7 @@
 - **Status:** aceita.
 - **Data:** 2026-09-25.
 - **Complementa:** ADRs 0021 e 0023.
+- **Complementada por:** ADR 0030, que separa o `layout` da região do acabamento `frameVariant`.
 
 ## Contexto