@softize/opus 22.2.0 → 24.0.0

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.

package/docs/adr/0047-pane-is-only-a-split-layout-unit.md

@@ -0,0 +1,71 @@
+# ADR 0047 — Pane é somente uma unidade de layout do Split
+
+- **Status:** aceita.
+- **Data:** 2026-10-01.
+- **Substitui:** a anatomia visual de Pane definida pela ADR 0023.
+- **Complementa:** ADR 0045, quanto ao uso de `Surface` para regiões visuais.
+
+## Contexto
+
+`Pane` nasceu como filho dimensionável de `Split`, mas passou a acumular uma segunda função:
+oferecia header, body, footer, título, mídia, ações, divisores, inset e ritmo visual. Essa anatomia
+duplicava `Surface` e fazia a aparência de uma coluna depender do componente que deveria apenas
+distribuir espaço.
+
+A duplicação ficou visível quando uma mesma região precisou funcionar em página, drawer e split.
+Alterar o ritmo de todos os bodies incluiu `PaneBody`, embora a decisão vigente já fosse deixar a
+superfície visual a cargo de `Surface` ou de um pattern especializado, como `Sidebar`.
+
+## Decisão
+
+`Pane` representa exclusivamente uma unidade espacial aceita por `Split`. Sua API pública mantém:
+
+- `id`, para identidade e persistência do layout;
+- `initialSize`, `minSize` e `maxSize`, para dimensionamento;
+- `grow`, para ocupar o espaço remanescente;
+- `className` e `children`, para o contêiner de layout.
+
+`Pane` não aplica inset, fundo, borda, raio, divisor, orientação interna, rolagem nem anatomia de
+conteúdo. As propriedades `inset` e `layout` são removidas.
+
+Os slots `PaneHeader`, `PaneBody`, `PaneContent`, `PaneFooter`, `PaneMedia`, `PaneTitle`,
+`PaneDescription` e `PaneActions` também são removidos, sem aliases de compatibilidade. O único
+consumidor é migrado atomicamente:
+
+- regiões visuais usam `Surface` e seus slots;
+- barras laterais podem usar a anatomia própria de `Sidebar` ou conteúdo nativo;
+- rolagem e organização interna pertencem ao filho inserido no pane.
+
+## Consequências
+
+- `Pane` e `Split` passam a ter uma única responsabilidade observável: distribuir espaço.
+- `Surface` volta a ser a fonte única da anatomia visual compartilhada.
+- Uma região que precise de rolagem deve declará-la no seu conteúdo ou na superfície interna.
+- Consumidores antigos deixam de compilar até substituir os slots e remover `inset`/`layout`.
+- O checker orienta a migração de símbolos e propriedades removidos.
+
+## Alternativas descartadas
+
+### Manter apenas PaneBody
+
+Ainda deixaria `Pane` responsável por rolagem e ritmo, criando uma anatomia parcial concorrente com
+`SurfaceBody` e com o conteúdo especializado.
+
+### Manter os slots como aliases de Surface
+
+Preservaria dois vocabulários para a mesma estrutura e permitiria que novas telas voltassem a
+escolher a família errada. Como há um único consumidor migrado junto, a compatibilidade não traz
+benefício proporcional.
+
+### Incorporar a superfície visual ao Split
+
+Misturaria distribuição espacial com apresentação e impediria panes deliberadamente invisíveis.
+
+## Verificação
+
+- a API pública exporta apenas `Pane`, `PaneProps` e `PaneSize` dessa família;
+- `Pane` não contém tokens de padding, borda, fundo, raio, overflow ou anatomia flex interna;
+- `Split` continua aceitando somente `Pane` como filho e preserva dimensionamento e resize;
+- `opus check` reprova símbolos antigos e as propriedades removidas;
+- busca nos consumidores não encontra nenhum slot `Pane*`, `inset` ou `layout` aplicado a `Pane`;
+- testes renderizados cobrem split fixo, redimensionável e superfícies migradas.

package/docs/adr/0048-modal-intro-separates-content-from-chrome.md

@@ -0,0 +1,34 @@
+# ADR 0048 — A intro do modal separa conteúdo e chrome
+
+- **Status:** aceita.
+- **Data:** 2026-10-01.
+- **Complementa:** ADR 0018, quanto à separação entre nome e contexto; ADR 0023, quanto à anatomia
+  de Dialog e Drawer; ADR 0046, quanto ao ritmo governado pelo body.
+
+## Contexto
+
+Dialog e Drawer podem ter uma barra persistente com navegação, ação global e fechamento. Nessa
+composição, colocar o título do recurso na barra mistura chrome e conteúdo; colocá-lo solto no body
+preserva o desenho, mas viola a anatomia pública e não nomeia a relação entre título e ações locais.
+
+## Decisão
+
+`DialogIntro` e `DrawerIntro` são o primeiro bloco opcional de seus respectivos bodies. Cada intro
+exige o título da família e aceita `DialogIntroActions` ou `DrawerIntroActions`. O título usa a
+escala principal da composição; o body continua responsável por inset, ritmo e rolagem.
+
+As ações do header continuam sendo chrome da superfície. As ações da intro se relacionam ao título
+e ao conteúdo. No formato compacto, título e ações permanecem no header e a intro é omitida.
+
+## Consequências
+
+- o mesmo conteúdo funciona em layout contínuo ou seccionado sem título órfão;
+- o fechamento e a navegação podem permanecer estáveis enquanto a intro rola com o conteúdo;
+- o checker exige intro dentro do body, título dentro de header ou intro e ações no slot correto;
+- exemplos e consumidores deixam de reconstruir a linha com `div` e classes locais.
+
+## Verificação
+
+- testes renderizados cobrem os dois modais e a escala do título;
+- `opus check` aceita as composições canônicas e reprova intro órfã ou sem título;
+- a documentação mostra as formas com intro e compacta.

package/docs/code-style.md

@@ -115,7 +115,7 @@ O extrator cobre três superfícies, sem heurística de nome:
    reprovam em vez de serem executadas e o dicionário mantém um snapshot imutável das entradas;
 3. texto estático em filhos e props de uma allowlist de componentes importados diretamente
    de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogBody`,
-   `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
+   `FieldLabel`, `TabsListItem`, `Page`, `Input` e `DataState`. Alias e namespace de import
    continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores
    `!uppercase`/`uppercase!` e classes em descendentes são projetados na superfície que
    realmente herda o CSS. Props específicas também respeitam a implementação: por exemplo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "22.2.0",
+  "version": "24.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -205,6 +205,10 @@
       "types": "./src/ui/meta.ts",
       "default": "./src/ui/meta.ts"
     },
+    "./ui/appearance": {
+      "types": "./src/ui/appearance.ts",
+      "default": "./src/ui/appearance.ts"
+    },
     "./ui/docs": {
       "types": "./src/ui/docs/index.ts",
       "default": "./src/ui/docs/index.ts"

package/registry/skills/build-opus-ui/SKILL.md

@@ -46,26 +46,26 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 8. Compor superfícies pela gramática estrutural do catálogo: `PageHeader` é a única introdução
    estrutural e reúne navegação contextual opcional, título e ações; `PageBody` contém o conteúdo.
    Na composição explícita, declare exatamente um heading principal com `PageTitle` no header,
-   `Content level={1}` ou um `PageState` ativo no body. `PageShell` pode fornecer navegação e ações
-   conhecidas pela aplicação, mas não cria uma barra visual. `Content` contém `ContentHeader` e `ContentBody`; Card,
-   Drawer e Pane usam seus
-   respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` (`title`,
-   `actions`) ou de `Content` (`title`, `description`, `actions` e `count`); não misturá-la com o
+   `Surface level={1}` ou um `PageState` ativo no body. `PageShell` pode fornecer navegação e ações
+   conhecidas pela aplicação, mas não cria uma barra visual. `Surface` contém `SurfaceHeader` e
+   `SurfaceBody`; Drawer e Pane usam seus respectivos `*Body`. Para o caso direto, usar a sintaxe
+   abreviada de `Page` (`title`, `actions`) ou de `Surface` (`title`, `description`, `actions` e
+   `count`); não misturá-la com o
    header explícito. O título da página não carrega contador. Ajustar o
    nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
    centralizado padrão de `80rem`.
-   Em `Content framed`, usar `layout="sectioned"` quando o filho direto já controlar o recuo do
-   body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir divisor, padding ou
-   recorte por classes no consumidor. `frameVariant="legend"` continua sendo um acabamento da
-   borda contínua e não combina com o layout seccionado.
+   Em `Surface framed`, usar `layout="sectioned"` e `SurfaceBody flush` quando o filho direto já
+   controlar o recuo do body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir
+   divisor, padding ou recorte por classes no consumidor. Em grupos de formulário,
+   `as="fieldset"` transforma o header em `legend` nativa sem variante visual paralela.
 9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
 10. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
     responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
     relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
     com justificativa e cobertura explícitas.
-11. Em uma página centrada em coleção, compor `Content + ActionList`: título e criação ficam em
-    extremos opostos do `ContentHeader`; a criação usa botão textual `default`, sem ícone, com
+11. Em uma página centrada em coleção, compor `Surface + ActionList`: título e criação ficam em
+    extremos opostos do `SurfaceHeader`; a criação usa botão textual `default`, sem ícone, com
     `Criar recurso`. Busca, filtros, atualização, estados e paginação permanecem no `ActionList`.
     Reservar `toolbarActions` a operações ligadas ao recorte atual.
 12. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.