@softize/opus 22.2.0 → 24.0.0

package/bin/lib/copy.mjs

@@ -94,12 +94,8 @@ const JSX_CHILD_ROLES = new Map([
   ['BreadcrumbLink', 'breadcrumb'],
   ['BreadcrumbPage', 'breadcrumb'],
   ['Button', 'button'],
-  ['CardDescription', 'description'],
-  ['CardTitle', 'title'],
   ['CommandEmpty', 'empty-state'],
   ['CommandItem', 'menu-item'],
-  ['ContentDescription', 'description'],
-  ['ContentTitle', 'title'],
   ['DialogDescription', 'dialog-body'],
   ['DialogTitle', 'title'],
   ['DrawerDescription', 'dialog-body'],
@@ -124,11 +120,11 @@ const JSX_CHILD_ROLES = new Map([
   // comando. Classificado como `button`, a política universal cobraria verbo de ação.
   ['PageBack', 'breadcrumb'],
   ['PageTitle', 'title'],
-  ['PaneDescription', 'description'],
-  ['PaneTitle', 'title'],
+  ['SurfaceDescription', 'description'],
+  ['SurfaceTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
-  ['TabsTrigger', 'tab'],
+  ['TabsListItem', 'tab'],
   // A Base não tem papel `tooltip`. O tooltip nomeia um controle icon-only, logo é um
   // fragmento (sem ponto final), não uma frase; `label` é o papel que reflete isso.
   ['TooltipContent', 'label'],
@@ -222,20 +218,6 @@ const JSX_PROP_ROLES = new Map([
     ]),
   ],
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
-  [
-    'Content',
-    new Map([
-      ['title', 'title'],
-      ['description', 'description'],
-    ]),
-  ],
-  [
-    'ContentHeader',
-    new Map([
-      ['title', 'title'],
-      ['description', 'description'],
-    ]),
-  ],
   [
     'DataState',
     new Map([
@@ -290,6 +272,13 @@ const JSX_PROP_ROLES = new Map([
       ['emptyText', 'empty-state'],
     ]),
   ],
+  [
+    'Surface',
+    new Map([
+      ['title', 'title'],
+      ['description', 'description'],
+    ]),
+  ],
   ['Textarea', new Map([['placeholder', 'placeholder']])],
 ])
 
@@ -363,20 +352,6 @@ const JSX_PROP_CLASS = new Map([
     ]),
   ],
   ['CommandInput', new Map([['placeholder', 'className']])],
-  [
-    'Content',
-    new Map([
-      ['title', 'className'],
-      ['description', 'className'],
-    ]),
-  ],
-  [
-    'ContentHeader',
-    new Map([
-      ['title', 'className'],
-      ['description', 'className'],
-    ]),
-  ],
   ['Input', new Map([['placeholder', 'className']])],
   ['InputGroupInput', new Map([['placeholder', 'className']])],
   ['InputGroupTextarea', new Map([['placeholder', 'className']])],
@@ -394,6 +369,13 @@ const JSX_PROP_CLASS = new Map([
     ]),
   ],
   ['Select', new Map([['placeholder', 'className']])],
+  [
+    'Surface',
+    new Map([
+      ['title', 'className'],
+      ['description', 'className'],
+    ]),
+  ],
   ['Textarea', new Map([['placeholder', 'className']])],
 ])
 

package/bin/lib/gen-runner.mjs

@@ -466,6 +466,8 @@ function serializeFilters(filters) {
       placeholder: spec.placeholder ?? null,
       type: spec.type ?? null,
       multiple: spec.multiple === true,
+      presentation: spec.presentation ?? null,
+      allowEmpty: spec.allowEmpty ?? null,
       mode: spec.mode ?? null,
       operators: Array.isArray(spec.operators) ? spec.operators : null,
       path: spec.path ?? null,

package/bin/lib/gen-stubs.mjs

@@ -182,7 +182,9 @@ function stripNullsFromFields(record) {
     for (const [k, v] of Object.entries(spec)) {
       if (v === null || v === undefined) continue
       if (k === 'hasShowWhen' || k === 'hasRequireWhen') continue
-      if (typeof v === 'boolean' && v === false) continue
+      // `false` costuma ser o default implícito e não precisa viajar. `allowEmpty` é a
+      // exceção: seu default é aceitar vazio, então `false` altera o comportamento.
+      if (typeof v === 'boolean' && v === false && k !== 'allowEmpty') continue
       clean[k] = v
     }
     out[name] = clean

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

@@ -62,7 +62,7 @@ por propriedades continua disponível temporariamente dentro de `Content`, mas a
 explícita usa os slots da família.
 
 `Content` técnico mantém seu nome quando representa o contêiner montado por uma primitiva ou um
-painel controlado, como `DialogContent`, `PopoverContent`, `TabsContent` e `AccordionContent`.
+painel controlado, como `DialogContent`, `PopoverContent`, `TabsPanel` e `AccordionContent`.
 `CarouselContent` também permanece porque representa o trilho técnico da primitiva, não o body de
 uma superfície estrutural. No `Empty`, a antiga região `EmptyContent` não é um body: como contém
 somente comandos, seu nome canônico passa a ser `EmptyActions`.

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

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

package/docs/adr/0032-tab-baseline-respects-the-container-inset.md

@@ -2,7 +2,8 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionada:** ADR 0023, quanto ao alinhamento horizontal dentro de superfícies.
+- **Relacionadas:** ADR 0023, quanto ao alinhamento horizontal dentro de superfícies; ADR 0040,
+  que torna a linha a única apresentação de `TabsList`.
 
 ## Contexto
 
@@ -23,14 +24,16 @@ continua pertencendo à anatomia da superfície, e Tabs apenas ocupa a largura q
 
 ### Emenda de 2026-09-28 — a aba combina uma área de botão e o indicador
 
-Na variante horizontal `line`, o gatilho mantém duas camadas: uma área interna com os estados
-interativos e a mesma altura de um Button do tamanho correspondente, e o indicador ancorado na
-linha-base da lista. A área interna permanece transparente e recebe fundo apenas no hover; a aba
-ativa se distingue pelo indicador primário. Um respiro de `0.375rem` separa as duas camadas no uso
-comum; dentro de `Tabs framed`, ele aumenta para `0.5rem` e acompanha o padding superior da moldura.
+Na apresentação horizontal que então se chamava `line`, o gatilho mantém duas camadas: uma área
+interna com os estados interativos e a mesma altura de um Button do tamanho correspondente, e o
+indicador ancorado na linha-base da lista. A área interna permanece transparente e recebe fundo
+apenas no hover; a aba ativa se distingue pelo indicador primário. Um respiro de `0.375rem` separa
+as duas camadas no uso comum; dentro de `Tabs framed`, ele aumenta para `0.5rem` e acompanha o
+padding superior da moldura.
 
-Essa apresentação pertence ao Opus: consumidores escolhem `variant="line"` e não repetem classes
-de fundo, raio, padding ou interação para obter o estado selecionado.
+Essa apresentação pertence ao Opus: consumidores não repetem classes de fundo, raio, padding ou
+interação para obter o estado selecionado. Desde a ADR 0040, a linha é a única apresentação de
+`TabsList` e `variant` não faz mais parte da API.
 
 ## Consequências
 
@@ -38,7 +41,7 @@ de fundo, raio, padding ou interação para obter o estado selecionado.
 - A seleção permanece indicada pela linha inferior, sem manter um segundo fundo persistente.
 - Drawer e Dialog não mantêm uma integração implícita com Tabs.
 - Um consumidor que realmente precise de uma linha até as bordas deve compor essa apresentação de
-  forma explícita, pois ela não é mais o comportamento padrão da variante `line`.
+  forma explícita, pois ela não faz parte do comportamento canônico de `TabsList`.
 
 ## Alternativas descartadas
 
@@ -54,6 +57,7 @@ sem consumidor conhecido. A composição explícita é suficiente caso essa nece
 
 ## Verificação
 
-O teste da variante `line` verifica que a linha usa `inset-inline: 0`, inclusive quando Tabs está
-dentro de `DrawerBody`. O mesmo teste verifica a separação estrutural entre a superfície interna e
-o indicador da aba ativa. A documentação viva demonstra a variante com os limites do contêiner.
+O teste da apresentação horizontal verifica que a linha usa `inset-inline: 0`, inclusive quando
+Tabs está dentro de `DrawerBody`. O mesmo teste verifica a separação estrutural entre a superfície
+interna e o indicador da aba ativa. A documentação viva demonstra a linha com os limites do
+contêiner.

package/docs/adr/0034-tabs-can-own-a-frame-without-owning-a-surface.md

@@ -2,7 +2,8 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0032, quanto à linha-base das abas.
+- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0032, quanto à linha-base das
+  abas; ADR 0040, que substitui a escolha de variante em `TabsList`.
 
 ## Contexto
 
@@ -23,9 +24,10 @@ Quando ativa, `framed` aplica ao root a moldura estrutural canônica para esse b
 `rounded-xl` e recorte do conteúdo. Ela não aplica token de fundo nem de foreground. O conjunto
 herda a superfície do contêiner em que foi composto.
 
-Essa propriedade não altera a apresentação de `TabsList`, a seleção, o tamanho nem a orientação. O
-consumidor continua escolhendo esses comportamentos nas APIs existentes, inclusive
-`TabsList variant="line"`.
+Essa propriedade não altera a apresentação de `TabsList`, a seleção, o tamanho nem a orientação. À
+época desta decisão, o consumidor ainda escolhia a apresentação com `TabsList variant="line"`.
+Essa parte foi substituída pela ADR 0040, que tornou a linha a única apresentação; a independência
+entre moldura e apresentação permanece válida.
 
 ## Consequências
 
@@ -33,8 +35,8 @@ consumidor continua escolhendo esses comportamentos nas APIs existentes, inclusi
 - Em Drawer, Dialog ou Pane, a moldura acompanha o fundo da superfície externa nos temas claro e
   escuro.
 - `Card` continua correto quando as abas realmente precisarem de uma superfície semântica própria.
-- `framed` permanece independente de `TabsList variant`, que descreve apenas a apresentação da
-  lista.
+- `framed` permanece independente da apresentação de `TabsList`; desde a ADR 0040, a lista usa
+  somente a linha de navegação e não aceita `variant`.
 
 ## Alternativas descartadas
 

package/docs/adr/0036-tabs-declares-trigger-distribution.md

@@ -2,7 +2,9 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionadas:** ADR 0032, quanto à composição da variante `line`; ADR 0034, quanto à moldura de Tabs; ADR 0035, quanto ao eixo de distribuição em grupos de controles.
+- **Relacionadas:** ADR 0032, quanto à composição da linha; ADR 0034, quanto à moldura de Tabs; ADR
+  0035, quanto ao eixo de distribuição em grupos de controles; ADR 0040, que substitui a escolha de
+  variante em `TabsList`.
 
 ## Contexto
 
@@ -11,10 +13,11 @@ entre os gatilhos. A view de Evento usa quatro abas no cabeçalho de um bloco em
 derivadas do texto deixam esse cabeçalho visualmente desequilibrado, embora todas as seções tenham o
 mesmo nível.
 
-Hoje, a variante horizontal `line` força cada gatilho a usar a largura do próprio conteúdo. Um
-consumidor que precise de larguras iguais teria de sobrescrever o `flex` interno ou reconstruir a
-lista com grid, duplicando uma decisão que já existe em `ButtonGroup` como
-`distribution="content" | "equal"`.
+Na API vigente quando esta decisão foi registrada, a variante horizontal `line` forçava cada
+gatilho a usar a largura do próprio conteúdo. Um consumidor que precisasse de larguras iguais teria
+de sobrescrever o `flex` interno ou reconstruir a lista com grid, duplicando uma decisão que já
+existia em `ButtonGroup` como `distribution="content" | "equal"`. A ADR 0040 depois tornou a linha
+a única apresentação e removeu `variant`, sem alterar o problema de distribuição resolvido aqui.
 
 ## Decisão
 
@@ -30,9 +33,9 @@ largura nem o layout dos painéis de conteúdo.
 ## Consequências
 
 - Consumidores escolhem a mesma linguagem de distribuição usada por `ButtonGroup`.
-- `TabsList variant="line"` continua responsável pela linha e pelos estados visuais; não recebe
-  classes de layout no consumidor.
-- A view de Evento declara `distribution="equal"` no `Tabs` sem alterar cada `TabsTrigger`.
+- `TabsList` continua responsável pela linha e pelos estados visuais; desde a ADR 0040, não aceita
+  `variant` nem recebe classes de layout no consumidor.
+- A view de Evento declara `distribution="equal"` no `Tabs` sem alterar cada `TabsListItem`.
 - Usos existentes preservam a distribuição pelo conteúdo.
 
 ## Alternativas descartadas

package/docs/adr/0037-design-data-lives-outside-the-contract.md

@@ -1,6 +1,6 @@
 # ADR 0037 — Dados do modo design ficam fora do contrato
 
-- **Status:** aceita; a primeira etapa saiu na 22.1.0, e a remoção fica para a 23.0.0.
+- **Status:** aceita; transição concluída na 23.0.0.
 - **Data:** 2026-09-28.
 - **Relacionadas:** ADR 0002 (seeds estruturados).
 

package/docs/adr/0038-content-level-defines-primary-presentation.md

@@ -0,0 +1,62 @@
+# ADR 0038 — O nível do Content define sua apresentação principal
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Complementa:** ADRs 0016, 0021, 0023 e 0029.
+
+## Contexto
+
+`Content` aceitava duas declarações independentes para a mesma hierarquia: `level={1}` fazia da
+região o heading principal da `Page`, enquanto `variant="page"` escolhia a escala visual desse
+mesmo papel. Todos os consumidores válidos precisavam repetir as duas propriedades, e o contrato
+também permitia combinações contraditórias como um heading principal com aparência de seção.
+
+A duplicação ainda produzia ritmos diferentes entre páginas equivalentes. Quando `PageHeader`
+fornecia o heading, `Page` separava introdução e corpo por `1.5rem`; quando `Content` fornecia o
+heading principal, a raiz mantinha os `0.75rem` próprios de uma seção interna.
+
+## Decisão
+
+`Content` deixa de expor `variant`. O nível semântico passa a selecionar a única apresentação
+válida para esse componente:
+
+- `level={1}` identifica o conteúdo principal, usa a escala de `PageHeader` e separa header e body
+  por `1.5rem` no layout contínuo;
+- níveis de 2 a 6 identificam seções internas e preservam a escala e o intervalo de `0.75rem`;
+- `fieldset` permanece uma seção interna: sua legenda não participa da hierarquia de headings.
+
+`Page` continua sendo a superfície estrutural, e `heading: "content"` continua declarando na
+`Presentation` quem possui o heading principal. A decisão não transforma `Content` em `Page`; ela
+remove uma escolha visual que não tinha significado independente dentro de `Content`.
+
+## Consequências
+
+- combinações contraditórias deixam de ser representáveis;
+- consumidores removem `variant="page"` e preservam `level={1}`;
+- o ritmo do conteúdo principal fica igual ao de páginas cujo heading pertence a `PageHeader`;
+- a remoção da propriedade é incompatível e exige migração coordenada dos consumidores;
+- a escala interna continua centralizada em `SurfaceHeader`, sem duplicação no consumidor.
+
+## Alternativas descartadas
+
+### Manter variant e corrigir somente o espaço
+
+Corrigiria o sintoma visual, mas preservaria a duplicação e os estados inválidos no contrato.
+
+### Renomear variant para role
+
+Tornaria a intenção mais explícita, porém continuaria exigindo duas propriedades para declarar o
+mesmo papel e permitiria que elas divergissem.
+
+### Derivar a apresentação da presença em Page
+
+Acoplaria `Content` ao local de renderização. O heading principal já é declarado diretamente por
+`level={1}` e pode ser validado por `Page` sem outro contexto implícito.
+
+## Verificação
+
+- testes de `Content` confirmam escala e intervalo de página no nível 1 e de seção nos demais;
+- tipos e exemplos públicos não aceitam mais `variant` em `Content`;
+- testes de `Page`, `Presentation` e preenchimento preservam `Content level={1}` como heading
+  principal;
+- consumidores compilam sem `variant="page"`.

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

@@ -0,0 +1,62 @@
+# ADR 0039 — A apresentação do filtro é independente de seu tipo
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Complementa:** ADR 0019.
+
+## Contexto
+
+`FilterSpec` declara o significado e o transporte de cada filtro, mas a interface apresentava todo
+filtro `select` com o mesmo controle. Escolhas únicas, curtas e mutuamente exclusivas — como um
+canal com três opções — continuavam escondidas em um menu mesmo quando a comparação direta entre
+as alternativas era mais útil.
+
+Transformar `toggle` em um novo `type` misturaria apresentação com valor: tanto o menu quanto o
+grupo produzem a mesma string, ocupam o mesmo campo no estado navegável e chegam sem mudança à
+action.
+
+## Decisão
+
+`FilterSpec` passa a aceitar `presentation: "select" | "toggle"`. A ausência da propriedade
+preserva `select` como apresentação padrão.
+
+`toggle` aplica-se a filtros `type: "select"` de escolha única e usa as mesmas opções, valor de
+repouso, regra de vazio, dependências e atualização de estado do controle padrão. A apresentação
+mostra todas as opções em um `ToggleGroup`; a composição visual vigente é definida pela ADR 0042.
+O controle não permite desmarcar a opção ativa quando o filtro não aceita vazio. Quando a opção vem
+de um dicionário e sua entrada declara um ícone do catálogo, o grupo apresenta ícone e rótulo juntos.
+
+O tipo do filtro continua descrevendo o valor e sua operação. A apresentação escolhe somente o
+controle usado para editá-lo.
+
+## Consequências
+
+- contratos podem expor escolhas pequenas e fechadas sem reconstruir a barra no consumidor;
+- URL, input da action, defaults e handlers permanecem inalterados;
+- filtros existentes continuam usando `Select` sem migração;
+- `toggle` não se aplica a seleção múltipla, lookup, texto, número ou data;
+- conjuntos extensos ou pesquisáveis continuam usando `Select`.
+
+## Alternativas descartadas
+
+### Criar `type: "toggle"`
+
+Duplicaria a semântica de `select` e exigiria que serialização, validação e adaptadores conhecessem
+um tipo cujo valor não mudou.
+
+### Compor o ToggleGroup em cada página
+
+Preservaria o contrato incompleto e duplicaria a sincronização entre controle, URL, default e input
+efetivo da action.
+
+### Trocar automaticamente selects com poucas opções
+
+Quantidade de opções não determina a melhor apresentação. O contrato precisa declarar a intenção,
+sem uma heurística visual invisível.
+
+## Verificação
+
+- teste do `ActionFilterBar` confirma que `presentation: "toggle"` renderiza todas as opções e
+  atualiza o mesmo campo de filtro;
+- teste de regressão confirma que um `select` sem apresentação continua usando `Select`;
+- typecheck impede valores de apresentação fora do vocabulário público.

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

@@ -0,0 +1,59 @@
+# ADR 0040 — Tabs usa uma única apresentação de navegação
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Substitui parcialmente:** ADR 0032, ADR 0034 e ADR 0036 quanto à escolha de variante em `TabsList`.
+
+## Contexto
+
+`TabsList` oferecia uma superfície preenchida e uma variante com linha. A superfície preenchida
+ficava visualmente próxima de um controle segmentado, embora `Tabs` represente navegação entre
+painéis e um `ToggleGroup` represente escolha de valores. A mesma aparência para comportamentos
+diferentes dificultava escolher o componente correto e levou filtros a serem descritos como tabs.
+
+## Decisão
+
+`TabsList` usa somente a linha de navegação e deixa de aceitar `variant`. Cada `TabsListItem`
+continua associado a um `TabsPanel` pelo mesmo valor. Orientação, tamanho, distribuição e moldura
+permanecem propriedades independentes do conjunto.
+
+A anatomia pública nomeia a posição de cada parte: `TabsListItem` pertence a `TabsList`, enquanto
+`TabsPanel` identifica o painel associado. Os nomes anteriores, `TabsTrigger` e `TabsContent`, não
+são mantidos como aliases porque há um único consumidor e a migração é atômica.
+
+Escolhas únicas ou múltiplas que alteram um valor no contexto atual usam `ToggleGroup`. A composição
+visual vigente do grupo é definida pela ADR 0042.
+
+## Consequências
+
+- Tabs mantém uma identidade visual única e vinculada à navegação entre painéis.
+- Filtros e escolhas de formulário não usam semântica de tabs para obter uma aparência compacta.
+- Consumidores removem `variant="line"`; não há substituição para a antiga superfície preenchida.
+- Consumidores renomeiam `TabsTrigger` para `TabsListItem` e `TabsContent` para `TabsPanel`.
+- A documentação de ToggleGroup explicita seus modos de composição.
+
+## Alternativas descartadas
+
+### Manter duas variantes em TabsList
+
+Preservaria flexibilidade visual, mas manteria a ambiguidade entre navegação e escolha de valor.
+
+### Compartilhar uma apresentação segmentada entre Tabs e ToggleGroup
+
+Permitiria a mesma aparência com semânticas distintas, mas não resolveria a dificuldade de leitura
+observada no produto. A linha torna a navegação reconhecível sem depender do contexto ao redor.
+
+### Preservar Trigger e Content como nomes públicos
+
+Manteria proximidade com a primitiva subjacente, mas nomearia mecanismo e conteúdo genérico em vez
+da anatomia exposta ao consumidor. `ListItem` e `Panel` deixam a composição legível no JSX.
+
+## Verificação
+
+- o tipo público de `TabsList` não aceita `variant`;
+- a exportação pública oferece `TabsListItem` e `TabsPanel`, sem aliases para os nomes anteriores;
+- testes da primitiva confirmam a linha-base, o indicador ativo e a distribuição;
+- testes do `ActionFilterBar` confirmam que `presentation: "toggle"` usa seleção exclusiva sem
+  alterar o estado transportado para a action;
+- a documentação de Tabs não oferece apresentação preenchida e a de ToggleGroup demonstra seus
+  modos próprios de escolha.

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.