@softize/opus 23.0.0 → 24.0.1

package/docs/adr/0042-toggle-group-shares-the-grouped-control-grammar.md

@@ -0,0 +1,79 @@
+# ADR 0042 — ToggleGroup compartilha a gramática de controles agrupados
+
+- **Status:** aceita.
+- **Data:** 2026-09-30.
+- **Substitui parcialmente:** ADR 0040 quanto à composição e à anatomia pública de `ToggleGroup`.
+
+## Contexto
+
+`ButtonGroup` expressa a relação entre controles com `mode`, distribui largura com `distribution` e
+mantém orientação, forma e moldura como eixos independentes. `ToggleGroup` resolvia necessidades
+equivalentes por outra gramática: `spacing` controlava indiretamente se os itens pareciam conectados,
+e cada controle era exposto como `ToggleGroupItem`, embora o controle isolado se chamasse `Toggle`.
+
+Essa diferença ficou mais visível ao buscar uma apresentação segmentada para filtros. Criar
+`appearance="segmented"` repetiria o significado visual de `variant`; criar
+`variant="segmented"` misturaria o tratamento de cada controle com a relação entre os controles.
+Nenhuma opção aproveitaria a gramática que o catálogo já usa para grupos de botões.
+
+## Decisão
+
+`ToggleGroup` compartilha com `ButtonGroup` os eixos de composição:
+
+- `mode="connected" | "spaced" | "divided" | "segmented"` define a relação entre controles;
+- `distribution="content" | "equal"` preserva a largura dos rótulos ou reparte a largura disponível;
+- `orientation`, `shape` e `framed` mantêm seus significados estruturais;
+- `variant` e `size` continuam tratando cada `Toggle` e podem ser declarados no grupo para chegar
+  aos controles por contexto.
+
+`connected` substitui o `spacing={0}` implícito; `spaced` substitui valores positivos de `spacing`;
+`divided` insere divisores sem incluí-los na distribuição; `segmented` cria uma superfície
+compartilhada, destaca a seleção dentro dela e separa somente segmentos inativos vizinhos.
+`spacing` sai do contrato.
+
+A anatomia pública passa a usar `ToggleGroup + Toggle`, em paralelo a `ButtonGroup + Button`.
+Dentro do grupo, `Toggle` exige `value` e participa da seleção coordenada; fora dele, mantém
+`pressed`, `defaultPressed` e `onPressedChange`. `ToggleGroupItem` sai sem alias porque existe um
+único consumidor e a migração é atômica.
+
+Filtros `select` declarados com `presentation: "toggle"` usam `mode="segmented"`. A propriedade do
+filtro continua escolhendo entre `Select` e `ToggleGroup`; estado, URL, defaults e input da action
+não mudam.
+
+## Consequências
+
+- grupos de ações e grupos de seleção compartilham vocabulário para relação, distribuição e forma;
+- `segmented` fica no eixo que descreve a relação entre controles, sem criar um sinônimo de
+  `variant`;
+- a mesma unidade pública, `Toggle`, funciona isolada ou sob seleção coordenada;
+- a ausência de `value` em um `Toggle` dentro do grupo é recusada em runtime, pois JSX não permite
+  que o tipo do filho dependa estaticamente do pai;
+- consumidores migram `ToggleGroupItem` para `Toggle` e `spacing` para o `mode` correspondente;
+- filtros toggle mudam apenas de acabamento visual e preservam o contrato transportado.
+
+## Alternativas descartadas
+
+### `appearance="segmented"`
+
+Separaria a composição do grupo, mas criaria um eixo visual sinônimo de `variant` sem organizar as
+outras diferenças já existentes entre `ButtonGroup` e `ToggleGroup`.
+
+### `variant="segmented"`
+
+Seria curto, porém faria `variant` responder ao mesmo tempo pelo tratamento do controle e pela
+relação entre controles. Também deixaria `spacing` e `distribution` sem uma gramática comum.
+
+### Manter `ToggleGroupItem`
+
+Preservaria a exigência estática de `value`, mas manteria uma anatomia diferente de
+`ButtonGroup + Button` para conceitos equivalentes. A verificação em runtime é um custo localizado
+e produz uma mensagem direta no uso inválido.
+
+## Verificação
+
+- o tipo público de `ToggleGroup` oferece os quatro modos e as duas distribuições, sem `spacing`;
+- `ToggleGroupItem` deixa de ser exportado e os consumidores usam `Toggle`;
+- testes cobrem os modos, distribuição igual, orientação dos divisores e exigência de `value`;
+- testes do `ActionFilterBar` confirmam que `presentation: "toggle"` usa `mode="segmented"` sem
+  alterar o valor transportado;
+- documentação e metadata distinguem escolha com `ToggleGroup` de navegação com `Tabs`.

package/docs/adr/0043-neutral-surfaces-and-interactions-use-opaque-role-tokens.md

@@ -0,0 +1,73 @@
+# ADR 0043 — Superfícies e interações neutras usam tokens opacos por papel
+
+- **Status:** aceita.
+- **Data:** 2026-09-30.
+- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0042, quanto aos controles
+  segmentados.
+
+## Contexto
+
+O tema claro usava o mesmo branco em `background` e `card`, enquanto o escuro elevava cards sobre
+um canvas mais escuro. Estados neutros também eram construídos com combinações como `muted/30`,
+`muted/50`, `background/60`, `brightness` e correções `dark:` nos componentes.
+
+Uma cor translúcida não representa um resultado: ela depende da superfície que estiver atrás.
+Consequentemente, a mesma classe podia funcionar dentro de um card e desaparecer no canvas. Quem
+compunha uma tela no tema claro não conseguia presumir a hierarquia nem o comportamento no escuro;
+cada contexto precisava ser inspecionado.
+
+## Decisão
+
+O tema declara uma escala neutra opaca por papel:
+
+- `background` é o canvas da aplicação;
+- `card` e `popover` são superfícies elevadas;
+- `control` é a superfície de inputs e controles editáveis;
+- `interaction-hover`, `interaction-pressed` e `interaction-selected` são estados de interação.
+
+Os dois temas preservam a mesma ordem comportamental: superfície em repouso, hover, seleção e
+pressão ganham contraste progressivo. Os valores podem avançar em direções luminosas diferentes,
+mas o componente usa o mesmo token e a mesma classe nos dois temas. `accent` passa a apontar para
+`interaction-hover`, preservando a integração com primitives externas que esperam esse nome.
+
+Estados neutros essenciais não são obtidos com alpha sobre uma superfície desconhecida. Alpha
+continua permitido para decoração, feedback semântico colorido, overlays e efeitos cuja mistura é
+parte deliberada do resultado.
+
+No tema claro, cards e popovers permanecem brancos, enquanto o canvas recebe um cinza quase branco.
+No escuro, a hierarquia existente é preservada. A distinção entre superfícies não substitui borda,
+foco nem texto quando esses sinais forem necessários para identificar um controle.
+
+## Consequências
+
+- componentes deixam de carregar receitas `dark:` para estados neutros equivalentes;
+- mover um controle entre canvas, card e modal não muda a cor resultante de seu estado;
+- hover, pressed e selected deixam de disputar o significado de `muted`;
+- o tema pode ser calibrado sem editar cada primitive;
+- light e dark ainda exigem verificação visual, mas compartilham a mesma gramática e deixam de
+  depender da superfície ancestral para produzir seus estados essenciais.
+
+## Alternativas descartadas
+
+### Manter transparências e calibrar por componente
+
+Preservaria menos tokens, mas manteria o resultado dependente do ancestral e multiplicaria exceções
+por tema.
+
+### Tornar o card cinza sobre canvas branco
+
+Criaria contraste, porém inverteria a relação de elevação já consolidada no escuro e daria ao card
+um peso visual desnecessário. O canvas quase branco com superfícies brancas preserva a elevação sem
+transformar a aplicação numa coleção de blocos cinza.
+
+### Usar somente `accent` para todos os estados
+
+Reduziria o vocabulário, mas hover transitório, seleção persistente e pressão deixariam de ser
+distinguíveis e voltariam a depender de modifiers locais.
+
+## Verificação
+
+- o tema publica os quatro papéis opacos (`control` e os três estados de interação) nos dois temas;
+- primitives neutras usam os mesmos tokens em light e dark, sem receitas locais equivalentes;
+- testes cobrem a projeção dos tokens e os estados de tabela, toggle, menu e navegação lateral;
+- a aplicação consumidora é compilada e verificada em páginas com canvas, card, formulário e grid.

package/docs/adr/0044-neutral-appearance-derives-from-bounded-axes-per-mode.md

@@ -0,0 +1,133 @@
+# ADR 0044 — A aparência neutra deriva de quatro eixos limitados por modo
+
+- **Status:** aceita.
+- **Data:** 2026-09-30.
+- **Relacionadas:** ADR 0043, quanto aos papéis opacos que esta decisão passa a derivar; ADR 0006,
+  quanto aos contextos semânticos, que permanecem fora da derivação.
+
+## Contexto
+
+Pessoas diferentes leem melhor com aparências diferentes: mais separação entre as camadas, estados
+mais marcados, um claro menos ofuscante, um escuro mais profundo ou neutros levemente tingidos pela
+cor do produto. Até aqui, atender a um desses pedidos exigia que a aplicação sobrescrevesse, token
+a token, a escala neutra da ADR 0043.
+
+Sobrescrever tokens soltos tem dois problemas. O primeiro é a coerência: a escala tem ordem —
+canvas, controle, superfície elevada, hover, seleção, pressão, borda — e mover um valor sem mover os
+vizinhos apaga a distinção entre dois papéis. O segundo é a leitura: escurecer uma superfície
+clara ou clarear uma superfície escura reduz o contraste do texto, e nada avisava a aplicação de
+que o ajuste tinha passado do ponto.
+
+## Decisão
+
+O tema deriva a escala neutra de quatro eixos. Cada eixo é um inteiro de 0 a 100, declarado
+separadamente para o modo claro e para o modo escuro:
+
+| Eixo                | O que muda                                                                        | Preset claro | Preset escuro |
+| ------------------- | --------------------------------------------------------------------------------- | ------------ | ------------- |
+| `colorIntensity`    | Saturação dos neutros no matiz `--neutral-hue`                                    | 0            | 0             |
+| `contrast`          | Distância de hover, seleção, pressão, `muted` e bordas até a superfície de origem | 0            | 0             |
+| `surfaceBrightness` | Luminosidade do canvas e das superfícies                                          | 100          | 50            |
+| `layerContrast`     | Distância entre canvas, controle e superfície elevada                             | 0            | 0             |
+
+As entradas são custom properties por modo — `--appearance-light-*` e `--appearance-dark-*`. `:root`
+declara os presets dos dois modos e usa as entradas claras; `.dark` troca para as escuras. Assim, a
+aplicação pode gravar os dois conjuntos no mesmo elemento, e alternar o tema não exige reaplicar
+nada.
+
+Com os eixos no preset, a derivação reproduz exatamente os valores calibrados pela ADR 0043. Quem
+não personaliza não percebe diferença.
+
+### Limites
+
+Os limites de cada eixo protegem o tema calibrado. Em qualquer combinação de 0 a 100, nos dois
+modos e para qualquer `--neutral-hue`:
+
+- a separação entre papéis nunca fica abaixo da separação do preset. Por isso `contrast` e
+  `layerContrast` têm o preset em zero e só ampliam distâncias;
+- o texto secundário (`muted-foreground`) mantém, sobre canvas, superfície elevada, controle e
+  `muted`, no mínimo o contraste que tem no preset. Para isso ele escurece no claro e clareia no
+  escuro conforme as superfícies se aproximam dele, e recebe apenas uma fração da saturação;
+- o texto principal (`foreground`) mantém contraste de pelo menos 7:1 sobre superfícies em repouso
+  e 4,5:1 sobre estados de interação;
+- toda luminosidade derivada permanece entre 0 e 100, e cada uma varia em um único sentido ao longo
+  de cada eixo.
+
+No claro, a superfície elevada do preset já é branca, então `surfaceBrightness` parte de 100 e só
+diminui. No escuro, o preset fica em 50: valores menores levam o canvas até o preto, e valores
+maiores produzem um escuro mais suave.
+
+### O que a intensidade tinge
+
+`colorIntensity` satura somente os tokens neutros: superfícies, estados, bordas, `ring` e textos
+neutros. `primary`, `destructive` e os contextos `info`, `success`, `warning` e `danger` não
+participam. `--neutral-hue` é identidade da aplicação, e não um eixo: a aplicação escolhe o matiz
+uma vez, e a pessoa escolhe apenas o quanto dele aparece.
+
+### API pública
+
+`@softize/opus/ui/appearance` é um módulo sem React, reexportado por `@softize/opus/ui` e por
+`@softize/opus/ui/react`. Ele publica:
+
+- os tipos `AppearanceMode`, `AppearanceAxis`, `AppearanceSettings` e `AppearanceOverrides`;
+- `appearanceModes`, `appearanceAxes`, `APPEARANCE_MIN`, `APPEARANCE_MAX` e `appearancePresets`;
+- `appearanceCustomProperty`, que devolve o nome da custom property de um eixo em um modo;
+- `normalizeAppearanceValue` e `resolveAppearance`, para tratar valores lidos de persistência;
+- `appearanceCustomProperties`, que converte overrides parciais no mapa de custom properties do
+  modo, com `null` nos eixos sem override;
+- `applyAppearanceCustomProperties`, que grava esse mapa em um alvo de estilo e remove as
+  propriedades marcadas com `null`.
+
+### Reset, persistência e interface
+
+O Opus não guarda estado de aparência e não publica componente de ajuste. Voltar ao padrão é
+remover os overrides: sem a propriedade, o cascade devolve o preset do tema ou o valor que o CSS
+da aplicação tiver declarado. Onde persistir a preferência e como apresentar os controles são
+decisões da aplicação consumidora.
+
+## Consequências
+
+- a aplicação personaliza a escala neutra por quatro números por modo, sem redeclarar tokens;
+- os papéis da ADR 0043 continuam opacos e com a mesma ordem em qualquer ajuste;
+- uma aplicação que redeclara diretamente um token neutro, como `--background`, continua
+  funcionando, mas esse token deixa de acompanhar os eixos;
+- `muted-foreground` deixa de ser um literal e passa a acompanhar as superfícies; no preset, o
+  valor é o mesmo de antes;
+- o preset em zero impede reduzir contraste abaixo do tema calibrado. Um pedido real por uma
+  aparência mais plana exige recalibrar o tema, e não ampliar a faixa do eixo.
+
+## Alternativas descartadas
+
+### Presets no meio da faixa, com redução permitida
+
+Deixaria cada controle simétrico, mas metade da faixa produziria separações menores que as do tema
+calibrado: camadas que se fundem e estados que deixam de se distinguir. O ajuste passaria a poder
+piorar a interface que ele existe para adaptar.
+
+### Um único conjunto de eixos para os dois modos
+
+Reduziria as entradas à metade, mas os modos têm presets e direções diferentes: o brilho máximo do
+claro é o ponto de partida, e o do escuro é um extremo. A preferência de uma pessoa no claro também
+não prediz a do escuro.
+
+### Tingir todos os tokens, inclusive primary e contextos
+
+Misturaria preferência pessoal com identidade e significado. A cor da marca e os contextos
+semânticos precisam permanecer reconhecíveis em qualquer ajuste.
+
+### Publicar o componente de ajuste e o reset no Opus
+
+Obrigaria o Opus a decidir persistência, escopo da preferência e texto de interface, que variam por
+produto. O helper cobre a parte comum — nomes, limites e conversão —, e a aplicação compõe a tela
+com os primitives existentes.
+
+## Verificação
+
+- `tests/ui/appearance-tuning.test.ts` avalia as declarações de `theme.css` e cobre: paridade do
+  preset com os valores calibrados nos dois modos, igualdade entre os presets do módulo e os do
+  tema, monotonicidade de cada luminosidade em cada eixo e os limites de separação e de contraste
+  de texto em toda a grade de eixos e em vários matizes;
+- `tests/ui/neutral-state-tokens.test.ts` garante que os tokens neutros derivados permanecem
+  opacos nos dois temas;
+- a aplicação consumidora verifica visualmente os extremos de cada eixo em páginas com canvas,
+  card, formulário e grid, nos dois modos.

package/docs/adr/0045-surface-replaces-content-and-card.md

@@ -0,0 +1,230 @@
+# ADR 0045 — Surface substitui Content e Card
+
+> **Atualização em 2026-10-01:** a ADR 0046 atribui ao body o ritmo entre filhos diretos, amplia o
+> respiro vertical e estende `flush` a Dialog e Drawer; as passagens abaixo sobre recuo permanecem
+> históricas quando divergirem dessa regra. A ADR 0047 remove a anatomia visual de `Pane`, portanto
+> a afirmação abaixo de que ele manteria slots próprios descreve apenas o estado anterior.
+
+- **Status:** aceita.
+- **Data:** 2026-09-30.
+- **Sucede:** ADR 0021, quanto à família que reúne estrutura e elemento semântico; ADR 0023, quanto
+  às seis fachadas públicas, à recusa de uma superfície genérica pública e à mídia com moldura em
+  `Card` e `Content`; ADR 0025, quanto a `frameVariant`; ADR 0030, quanto ao body sem recuo como
+  parte indivisível do layout seccionado; ADR 0020, na emenda de 2026-09-26 sobre os slots de mídia
+  de `Card` e `Content`.
+- **Preserva:** ADR 0016 (o cabeçalho da coleção pertence à região que a nomeia), ADR 0024 (a altura
+  se propaga por contexto) e ADR 0038 (o nível 1 define a apresentação principal), agora sob o nome
+  `Surface`.
+- **Não altera:** `Page`, `Dialog`, `Drawer` e `Pane`, que mantêm famílias, slots e mídia próprios.
+
+## Contexto
+
+Quem monta uma tela precisa delimitar e nomear um trecho dela: uma seção da página, um grupo de
+campos, um registro, um item de uma grade ou um bloco clicável. Até a série 23, essa necessidade se
+dividia entre duas famílias públicas:
+
+- `Content` entregava a região nomeada: `section` ou `fieldset`, heading com nível, contador,
+  `aria-labelledby`, moldura opcional e a propagação de altura até a `ActionList`;
+- `Card` entregava a superfície elevada: fundo próprio, rodapé, `asChild` para um bloco clicável e
+  a caixa simples com filhos livres.
+
+As duas cresceram uma em direção à outra. `Content` ganhou moldura (ADR 0021), mídia (ADR 0023,
+emenda), acabamento de legenda (ADR 0025) e layout seccionado (ADR 0030). `Card` ganhou heading com
+nível, layout e divisores derivados (ADR 0023). O resultado são duas famílias com dezessete exports,
+que respondem à mesma pergunta com respostas diferentes:
+
+- o mesmo desenho — moldura, header com mídia e título, body — tem dois recuos (`1rem` e `1.25rem`),
+  duas escalas de título e duas posições de mídia, conforme o nome do componente escolhido;
+- um registro que precisa de `section` e de rodapé não cabe em nenhuma das duas: `Content` não tem
+  footer e `Card` não tem elemento semântico;
+- a escolha entre as famílias é feita pela aparência (“tem fundo?”), e não pela semântica, o que a
+  ADR 0025 já havia identificado como defeito ao separar `fieldset` do acabamento de legenda;
+- a mídia desenhava `IconTile` por conta própria e, para não produzir moldura dentro de moldura,
+  inspecionava o filho e adotava as props dele. Avatar, imagem e logotipo precisavam de `asChild`
+  para escapar de uma moldura que não pediram.
+
+A ADR 0023 descartou um `<Surface>` público porque ele “apagaria a semântica de cada família”. A
+evidência posterior mostrou o oposto para este par: a semântica de `Content` e `Card` já não vinha
+do nome, e sim de `as`, `level`, `framed` e da presença de fundo. Para `Dialog`, `Drawer`, `Pane` e
+`Page`, o argumento continua válido — o nome carrega comportamento (foco, portal, redimensionamento,
+chrome de página) — e esta decisão não os alcança.
+
+As forças em tensão:
+
+- **Uma gramática × dois contratos preservados.** A região de página e a entidade elevada precisam
+  continuar possíveis, com acessibilidade e ocupação de altura intactas.
+- **Eixos independentes × pacotes validados.** Moldura, fundo e anatomia são decisões separadas, mas
+  recuo, ritmo e divisores continuam sendo pacotes que o consumidor não remonta por classes.
+- **Migração atômica × compatibilidade.** Manter aliases prolongaria a dupla resposta que motiva a
+  decisão.
+
+## Decisão
+
+### 1. Uma família pública
+
+`Surface` substitui integralmente `Content` e `Card`. A família é:
+
+`Surface`, `SurfaceHeader`, `SurfaceBody`, `SurfaceFooter`, `SurfaceTitle`, `SurfaceDescription`,
+`SurfaceMedia`, `SurfaceMeta` e `SurfaceActions`.
+
+`Content*`, `Card*`, seus tipos, arquivos, metadata e páginas de documentação deixam de existir, sem
+aliases e sem período de depreciação. `MetricCard` e `ActionFormCard` permanecem como patterns
+especializados e compõem `Surface` internamente.
+
+A infraestrutura interna que `Page`, `Dialog`, `Drawer` e `Pane` compartilham muda de nome para
+liberar o vocabulário público: `StructuralHeader` e `StructuralMedia`. Ela continua fora da API.
+
+### 2. A semântica vem do elemento, não do nome
+
+`as` escolhe o elemento: `div` (default), `section`, `article` ou `fieldset`. `asChild` entrega a
+superfície ao filho — um `button` ou um link — e é mutuamente exclusivo com `as`.
+
+- `section` e `article` com header recebem `aria-labelledby` apontando para o título, salvo quando
+  `aria-label` é informado.
+- `fieldset` transforma o header em `legend` nativa. A legenda aceita somente mídia e título;
+  contador, descrição e ações não nomeiam o grupo de campos. A mídia da legenda é decorativa.
+- `div` e `asChild` não recebem nome acessível implícito: um `div` não é uma região.
+
+`level` (1 a 6, default 2) pertence à raiz e escolhe a tag do título. O nível 1 mantém a
+apresentação principal da página (ADR 0038); os demais usam a escala de seção. Nenhum layout altera
+a escala do título.
+
+### 3. Três eixos visuais independentes
+
+| Propriedade | Valores                   | Default      | Decide                                                       |
+| ----------- | ------------------------- | ------------ | ------------------------------------------------------------ |
+| `framed`    | `boolean`                 | `false`      | Borda, raio (`rounded-xl`) e recorte do conteúdo seccionado. |
+| `elevation` | `none`, `raised`          | `none`       | Fundo próprio e altura própria.                              |
+| `layout`    | `continuous`, `sectioned` | `continuous` | Ritmo contínuo ou faixas com divisores derivados.            |
+
+`elevation="raised"` pinta o par `bg-card text-card-foreground` e declara
+`--surface-background: var(--card)`. `elevation="none"` não pinta fundo, não usa alpha e não
+redeclara a variável: a superfície mostra o fundo de quem a hospeda, e `--surface-background`
+continua valendo o da superfície elevada, do `Dialog` ou do `Drawer` mais próximo, com `--background`
+como fallback na página. Um descendente que precise de uma cor opaca igual ao fundo visível lê
+`var(--surface-background, var(--background))` em qualquer nível de aninhamento.
+
+Uma superfície é **delimitada** quando tem moldura ou elevação. Dessa condição derivam o recuo e o
+ritmo, que o consumidor não escreve:
+
+- **Sem delimitação**, as regiões não têm recuo: a superfície flui alinhada ao hospedeiro, com
+  `0.75rem` entre header e body (`1.5rem` no nível 1).
+- **Delimitada e contínua**, header, body e footer compartilham `1rem` de recuo lateral e `0.75rem`
+  de intervalo; a última região fecha com o mesmo respiro do topo.
+- **Delimitada e seccionada**, header e footer são faixas, o body recua `1rem` e os divisores nascem
+  da vizinhança entre as regiões (ADR 0023, §4). `layout="sectioned"` exige uma superfície
+  delimitada.
+
+Existe uma medida só. O recuo de `1.25rem` e o título um degrau maior do antigo `Card` contínuo
+saem: eram diferenças atribuídas ao nome do componente.
+
+`elevation="raised"` também encerra a cadeia de ocupação de altura (ADR 0024): uma superfície
+elevada decide a própria altura. Sem elevação, `Surface` e `SurfaceBody` repassam a altura de
+`Page layout="fill"` até a `ActionList`, como `Content` fazia.
+
+### 4. Três formas de compor
+
+1. **Caixa simples.** Sem título e sem slots estruturais, os filhos são livres e a raiz não aplica
+   recuo nem ritmo; o consumidor declara o que a caixa precisa.
+2. **Forma curta.** `title`, `description`, `count`, `actions` e `media` declaram o header. Os filhos
+   viram o body; quando a superfície precisa de rodapé ou de um body com propriedades, os filhos são
+   `SurfaceBody` e `SurfaceFooter` explícitos.
+3. **Composição explícita.** `SurfaceHeader`, `SurfaceBody` e `SurfaceFooter` como filhos diretos,
+   no máximo um de cada. Cada região é opcional.
+
+A presença de um slot estrutural direto ativa a validação: slots estruturais não se misturam com
+filhos livres, não se repetem, e a forma curta não convive com `SurfaceHeader`. `SurfaceHeader`
+exige um `SurfaceTitle` e aceita no máximo um de cada slot restante. As formas curta e explícita
+produzem os mesmos elementos e `data-slot`.
+
+`SurfaceFooter` vale para qualquer superfície, inclusive uma região de página sem moldura.
+
+`SurfaceBody` aceita `flush` para entregar a largura inteira a um filho que já controla o próprio
+recuo, como `DetailGroup` com divisores, lista ou tabela. É a única propriedade de recuo da família
+e existe porque `className` não remove o respiro condicional da última região.
+
+### 5. Moldura de fieldset
+
+`frameVariant` deixa de existir. Em um `fieldset` com moldura e layout contínuo, a `legend` nativa
+ocupa a borda, como o navegador já faz; não há acabamento equivalente para `section`. No layout
+seccionado, a legenda é a faixa do header, dentro da moldura.
+
+### 6. Mídia é um slot, não uma moldura
+
+`SurfaceMedia` é somente estrutura e layout: reserva a posição que abre a linha do header e
+centraliza o conteúdo. Não cria `IconTile`, não aceita `size`, `context` ou `variant` e não
+inspeciona o filho. A moldura é composição explícita — `SurfaceMedia` contendo `IconTile` —, e
+`Avatar`, `img` ou um glifo entram diretamente. Isso devolve aos slots de mídia desta família a
+regra original da ADR 0020.
+
+## Consequências
+
+- A escolha passa a ser feita por pergunta: qual elemento, tem moldura, tem fundo, qual anatomia.
+  Combinações antes impossíveis, como `article` elevado com rodapé ou região de página com footer,
+  tornam-se diretas.
+- Dezessete exports públicos dão lugar a nove; duas páginas de documentação, a uma.
+- Toda tela que usa `Content` ou `Card` precisa migrar na mesma versão. O `opus check` reprova os
+  nomes removidos com a indicação do substituto.
+- `Content` tinha `section` como default; `Surface` tem `div`. A migração de uma região nomeada
+  declara `as="section"` para preservar a região e o `aria-labelledby`.
+- Cards contínuos ficam `0.25rem` mais compactos e com título em `text-sm`; regiões seccionadas
+  ganham recuo no body e passam a declarar `flush` quando o filho controla o recuo.
+- Regiões `section` que usavam `frameVariant="legend"` perdem o header sobre a borda e passam à
+  moldura contínua ou seccionada.
+- Mídias que dependiam da moldura automática passam a compor `IconTile`.
+- A exigência de exatamente um header e um body de `Content` é relaxada: cada região é opcional.
+- A decisão é de difícil reversão depois que os consumidores migrarem; por isso a release só ocorre
+  após a migração do consumidor, os gates e a revisão do candidato.
+
+## Alternativas consideradas
+
+### Manter Content e Card
+
+Preserva todos os consumidores, mas mantém duas respostas para o mesmo desenho e a escolha por
+aparência. Cada capacidade nova continuaria sendo implementada duas vezes ou faltando em um dos
+lados, como footer em `Content` e elemento semântico em `Card`.
+
+### Surface como fundação e Content/Card como aliases
+
+Reduziria o custo imediato da migração. Foi descartada porque os aliases perpetuariam dois
+vocabulários na documentação, nas skills e no lint, e porque os defaults diferentes de cada alias
+esconderiam justamente os eixos que a decisão torna explícitos.
+
+### Unificar apenas a implementação interna
+
+É o que a ADR 0023 fez. Removeu a duplicação de classes, mas não a duplicação de decisão: o
+consumidor continuou escolhendo entre dois nomes para a mesma estrutura.
+
+### Deixar `elevation="none"` transparente por classe ou alpha
+
+Um `bg-transparent` ou um fundo com alpha faria a cor final depender de cada ancestral
+intermediário, o que a ADR 0043 removeu do tema. Não pintar nada e manter a variável herdada
+produz o mesmo resultado visual sem criar um token dependente do contexto.
+
+### Manter a moldura automática na mídia
+
+Pouparia a composição de `IconTile` no caso do ícone. Foi descartada porque obrigava o slot a
+inspecionar o filho, a repetir as props visuais de outro componente e a oferecer `asChild` como
+saída para todo conteúdo que não fosse um glifo.
+
+### Derivar o body sem recuo do layout seccionado
+
+Era a regra da ADR 0030 para `Content`, e o oposto da regra da ADR 0023 para `Card`. Escolher uma
+delas por default implícito quebraria a outra metade dos usos; `flush` declara a intenção no slot
+a que ela pertence.
+
+## Verificação
+
+- Testes de `Surface` cobrem as três formas de composição, a equivalência entre forma curta e
+  explícita, `as` e `asChild`, `aria-labelledby`, nível do heading, `fieldset` e `legend`, os eixos
+  `framed`, `elevation` e `layout`, footer, `flush`, mídia sem moldura implícita e as combinações
+  inválidas.
+- A suíte transversal de anatomia percorre `Surface`, `Dialog`, `Drawer` e `Pane` e mantém os
+  invariantes de recuo lateral, divisores derivados e escala do título.
+- Os testes de ocupação de altura confirmam a cadeia `Page › PageBody › Surface › SurfaceBody ›
+ActionList` e a interrupção por `elevation="raised"`.
+- Um teste de API pública reprova qualquer export `Card*` ou `Content*` — exceto `MetricCard` e
+  `ActionFormCard` — e a exportação da infraestrutura interna.
+- `opus check` reprova os componentes removidos, slots fora do pai e a mistura de formas.
+- A documentação tem uma página canônica, `surface`; os endereços `card` e `content` redirecionam
+  para ela.

package/docs/adr/0046-structural-body-owns-content-rhythm.md

@@ -0,0 +1,103 @@
+# ADR 0046 — O body estrutural governa o ritmo do conteúdo
+
+> **Atualização em 2026-10-01:** a ADR 0047 remove `PaneBody` da API. O ritmo definido aqui vale
+> para `SurfaceBody`, `DialogBody`, `DrawerBody` e `PageBody`.
+
+- **Status:** aceita.
+- **Data:** 2026-10-01.
+- **Complementa:** ADR 0023, quanto à anatomia compartilhada das superfícies, e ADR 0045, quanto
+  ao recuo derivado de `Surface`.
+- **Altera:** a liberdade anterior de sobrescrever recuo e ritmo diretamente em `*Body` por
+  `className`.
+
+## Contexto
+
+`SurfaceBody`, `DialogBody`, `DrawerBody`, `PaneBody` e `PageBody` definiam a região, mas deixavam o
+intervalo entre seus filhos para cada consumidor. Na prática, telas equivalentes passaram a usar
+`space-y-3`, `space-y-4`, `space-y-5`, `space-y-6`, `gap-4` ou nenhum ritmo. O mesmo título inserido
+no início de um drawer tinha `1rem` acima, herdado do body, e `1.5rem` abaixo, escrito pela tela.
+
+O defeito não é uma margem isolada: o pai já conhece se a superfície é contínua ou seccionada,
+delimitada ou fluida, mas essa informação parava antes de decidir o ritmo do conteúdo. Corrigir
+cada tela mantém várias fontes de verdade e permite que a divergência reapareça.
+
+Ao mesmo tempo, nem todo descendente deve usar o ritmo estrutural. Uma grade, uma linha horizontal
+ou um grupo compacto tem relações internas próprias. O body precisa governar seus filhos diretos
+sem impedir que um desses filhos organize o próprio interior.
+
+## Decisão
+
+### 1. O body é uma pilha estrutural
+
+Todo body público compõe seus filhos diretos em coluna com intervalo de `1.5rem`. Esse é o ritmo
+entre blocos da superfície: intro, resumo, ações, navegação e conteúdo. Um bloco que precise de
+outro ritmo o declara num wrapper interno; ele não transforma o body inteiro em grid, linha ou
+pilha compacta.
+
+`PageBody` recebe o mesmo ritmo. O inset da página continua na raiz `Page`, pois `flow` e `fill`
+descrevem ocupação de altura, não a anatomia `continuous`/`sectioned`.
+
+### 2. O pai decide o inset
+
+`Surface`, `DialogContent` e `DrawerContent` entregam seu layout por contexto. O body deriva
+dele o recuo:
+
+- no layout `sectioned` de Surface, Dialog e Drawer, o corpo usa `1rem` nas laterais e `1.5rem` em
+  cima e embaixo;
+- no layout `continuous`, o intervalo entre regiões adjacentes soma `1.5rem`; quando o body abre a
+  superfície, seu respiro superior também é `1.5rem`.
+
+Header e footer permanecem faixas compactas. A simetria relevante deixa de ser “todas as regiões
+têm o mesmo padding vertical” e passa a ser “o conteúdo tem o mesmo respiro antes, entre e depois
+dos seus blocos”. O alinhamento lateral entre regiões continua invariável.
+
+### 3. Full bleed é explícito
+
+`flush` remove o inset do body sem remover seu papel estrutural. `SurfaceBody` preserva a API já
+existente; Dialog e Drawer passam a oferecer a mesma saída. É o caso de listas, tabelas ou
+navegações que controlam o próprio recuo.
+
+### 4. Classes não reescrevem a anatomia
+
+`opus check` reprova classes estáticas de padding, `gap-*` e `space-*` aplicadas diretamente aos
+bodies públicos. A correção é uma destas:
+
+- remover a classe e aceitar o ritmo estrutural;
+- usar `flush` quando o filho controla o inset inteiro;
+- mover grid, linha ou ritmo compacto para um wrapper filho.
+
+Classes de ocupação, overflow, alinhamento e tipografia continuam permitidas. O diagnóstico é
+restrito aos componentes importados da API pública do Opus, sem atribuir a regra a homônimos locais.
+
+## Consequências
+
+- Introduções e blocos irmãos mantêm o mesmo ritmo em páginas, superfícies, dialogs e drawers.
+- Alterar a densidade estrutural volta a ter uma única fonte na anatomia do Opus.
+- Alguns wrappers internos passam a ser necessários, mas agora expressam uma relação local real.
+- Consumidores precisam remover overrides existentes no mesmo upgrade; a mudança é incompatível e
+  integra a major 24 ainda não publicada.
+- `flush` deixa de ser uma particularidade de Surface e vira o escape comum para full bleed.
+
+## Alternativas descartadas
+
+### Corrigir somente o intro do drawer
+
+Resolveria o exemplo observado, mas manteria os demais bodies com ritmos divergentes e faria a
+próxima composição repetir a decisão.
+
+### Criar uma prop `gap` no body
+
+Transformaria uma invariância estrutural em escolha de cada tela. Grupos compactos já podem usar
+um wrapper próprio, sem ampliar a API.
+
+### Proibir qualquer `className` no body
+
+Impediria necessidades legítimas de altura, overflow, alinhamento e tipografia. O lint se limita
+às classes que reescrevem inset e ritmo.
+
+## Verificação
+
+- testes transversais comparam o ritmo e o inset dos bodies por família e layout;
+- testes de `flush` confirmam a remoção do inset sem remover o gap estrutural;
+- testes do `opus check` cobrem padding, gap e space, além de classes permitidas;
+- o único consumidor remove overrides diretos e seus testes verificam as composições migradas.