@softize/opus 12.10.0 → 13.0.0

package/bin/lib/copy.mjs

@@ -71,10 +71,6 @@ const JSX_CHILD_ROLES = new Map([
   ['ActionFormCard', 'message'],
   ['ActionFormDialog', 'message'],
   ['AlertDescription', 'message'],
-  ['AlertDialogAction', 'button'],
-  ['AlertDialogCancel', 'button'],
-  ['AlertDialogDescription', 'dialog-body'],
-  ['AlertDialogTitle', 'title'],
   ['AlertTitle', 'title'],
   ['Badge', 'badge'],
   ['BreadcrumbLink', 'breadcrumb'],
@@ -84,6 +80,8 @@ const JSX_CHILD_ROLES = new Map([
   ['CardTitle', 'title'],
   ['CommandEmpty', 'empty-state'],
   ['CommandItem', 'menu-item'],
+  ['ContentDescription', 'description'],
+  ['ContentTitle', 'title'],
   ['DialogDescription', 'dialog-body'],
   ['DialogTitle', 'title'],
   ['DrawerDescription', 'dialog-body'],
@@ -104,6 +102,8 @@ const JSX_CHILD_ROLES = new Map([
   ['MenuRadioItem', 'menu-item'],
   ['PopoverDescription', 'description'],
   ['PopoverTitle', 'title'],
+  ['PageDescription', 'description'],
+  ['PageTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
   ['TabsTrigger', 'tab'],
@@ -130,6 +130,8 @@ const JSX_PROP_ROLES = new Map([
   ['ActionTrigger', new Map([['label', 'button']])],
   ['Alert', new Map([['title', 'title'], ['description', 'message']])],
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
+  ['Content', new Map([['title', 'title'], ['description', 'description']])],
+  ['ContentHeader', new Map([['title', 'title'], ['description', 'description']])],
   ['DataState', new Map([['emptyText', 'empty-state'], ['errorText', 'error']])],
   // A Dock nomeia a barra e cada ação por prop. Sem estas linhas, a copy sairia do inventário
   // exatamente quando uma superfície migra de <Button aria-label> para <DockAction label>.
@@ -138,6 +140,7 @@ const JSX_PROP_ROLES = new Map([
   ['Input', new Map([['placeholder', 'placeholder']])],
   ['InputGroupInput', new Map([['placeholder', 'placeholder']])],
   ['InputGroupTextarea', new Map([['placeholder', 'placeholder']])],
+  ['MetricCard', new Map([['label', 'label'], ['description', 'description']])],
   ['Page', new Map([['title', 'title'], ['description', 'description']])],
   ['Select', new Map([
     ['placeholder', 'placeholder'],
@@ -183,9 +186,12 @@ const JSX_PROP_CLASS = new Map([
   ['ActionTrigger', new Map([['label', 'className']])],
   ['Alert', new Map([['title', 'className'], ['description', 'className']])],
   ['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']])],
+  ['MetricCard', new Map([['label', 'className'], ['description', 'className']])],
   ['Page', new Map([['title', 'className'], ['description', 'className']])],
   ['Select', new Map([['placeholder', 'className']])],
   ['Textarea', new Map([['placeholder', 'className']])],
@@ -200,11 +206,12 @@ const JSX_PROP_STYLE = new Map([
   ['Input', new Map([['placeholder', 'style']])],
   ['InputGroupInput', new Map([['placeholder', 'style']])],
   ['InputGroupTextarea', new Map([['placeholder', 'style']])],
+  ['MetricCard', new Map([['label', 'style'], ['description', 'style']])],
   ['Textarea', new Map([['placeholder', 'style']])],
 ])
 
 const JSX_PORTAL_BOUNDARIES = new Set([
-  'AlertDialogContent', 'DialogContent', 'DrawerContent', 'MenuContent', 'MenuSubContent',
+  'DialogContent', 'DrawerContent', 'MenuContent', 'MenuSubContent',
   'PopoverContent', 'TooltipContent',
 ])
 

package/docs/adr/0003-dictionary-presentation-is-declared.md

@@ -3,6 +3,9 @@
 - Status: aceita
 - Data: 2026-09-02
 
+> A ADR 0006 substitui o nome `tone` por `context` para a família semântica e define sua migração
+> compatível. O princípio desta ADR — apresentação declarada e não inferida — permanece vigente.
+
 ## Contexto e forças
 
 `t.dict` declara vocabulário fechado uma única vez: código estável, rótulo, documentação de

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

@@ -0,0 +1,65 @@
+# ADR 0004 — O estado integral do conteúdo é composto dentro de Page
+
+## Contexto
+
+`Page` padroniza o `<main>`, o cabeçalho e o container de uma página. Hoje, consumidores que ainda
+não têm conteúdo para mostrar repetem spinners, alertas e vazios diretamente em `children`. Essas
+composições divergem visualmente e nem sempre distinguem carregamento, ausência e falha ou oferecem
+uma ação de recuperação.
+
+Ao mesmo tempo, uma página pode agregar várias fontes independentes. Fazer `Page` receber flags de
+carregamento ou erro faria o esqueleto decidir quando toda a página deve desaparecer por causa de
+uma única fonte.
+
+## Decisão
+
+`Page` continua presentacional e sem conhecimento de dados. O Opus fornece `PageState` como pattern
+composto para o estado integral da área de conteúdo. Na forma curta ele pode ser escrito como filho
+direto de `Page`, que materializa `PageBody`; na composição explícita, `PageState` fica dentro de
+`PageBody`. Ele é usado quando o conteúdo principal inteiro está carregando, falhou ou está vazio.
+
+`PageState`:
+
+- recebe um estado discriminado entre `loading`, `error`, `empty` e `ready`;
+- preserva o cabeçalho da página em todos os estados;
+- compõe `Spinner`, `Alert` e `Empty` em vez de recriar suas superfícies;
+- aceita título, descrição, ícone e ação contextual sem exibir erro técnico;
+- expõe `data-slot="page-state"` e `data-status` para testes e análise estrutural;
+- renderiza o conteúdo sem moldura adicional em `ready`.
+
+Estados parciais continuam pertencendo a `DataState`, `ActionView`, `ActionList` ou `Alert`, conforme
+a fronteira afetada. Uma coleção vazia continua dentro da estrutura da coleção; `Empty` representa
+uma região disponível, uma escolha pendente ou uma próxima ação.
+
+## Alternativas consideradas
+
+### Flags diretamente em Page
+
+Rejeitada porque mistura layout com aquisição de dados e torna ambígua a precedência entre várias
+fontes da mesma página.
+
+### Usar somente DataState
+
+Rejeitada como contrato único porque o modo bloco de `DataState` também atende seções menores e não
+expressa que o conteúdo principal inteiro está indisponível. `PageState` pode compartilhar as mesmas
+primitivas sem confundir as duas escalas.
+
+### Manter composições locais
+
+Rejeitada porque mantém diferenças de altura, borda, copy, recuperação e semântica acessível entre
+telas equivalentes.
+
+## Consequências
+
+- Consumidores ganham uma composição uniforme sem acoplar `Page` a hooks ou actions.
+- A copy específica do fluxo permanece no consumidor; defaults seguros cobrem usos simples.
+- Migrações precisam distinguir estado integral de estado parcial antes de substituir a composição.
+- O gate estrutural do consumidor deve impedir novos estados integrais montados manualmente.
+
+## Verificação
+
+- Testes do Opus cobrem os quatro estados, slots, precedência do conteúdo e ação contextual.
+- A documentação do catálogo demonstra o uso na forma curta e sua posição dentro de `PageBody` na
+  composição explícita.
+- Consumidores verificam `data-slot="page-state"` nos estados integrais e mantêm testes próprios para
+  recuperação e distinção entre erro e vazio.

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

@@ -0,0 +1,180 @@
+# ADR 0005 — Superfícies estruturais compartilham uma anatomia explícita
+
+- **Status:** aceita.
+- **Data:** 2026-09-04.
+
+## Contexto
+
+Os componentes estruturais da UI descrevem regiões equivalentes com APIs diferentes. `Dialog`
+expõe header, título, descrição, body e footer; `Card` chama o corpo de `Content`; e `Page`
+recebe título, descrição e ações somente por propriedades, sem expor seus elementos estruturais.
+`ContentHeader`, por sua vez, pode aparecer solto, embora seus nomes sugiram uma família `Content`.
+
+Essa variação obriga quem consome a biblioteca a reaprender a composição em cada superfície e
+impede que análise estática verifique relações como “um título pertence ao header da sua família”.
+Ao mesmo tempo, a forma curta de `Page` e `ContentHeader` atende bem ao caso comum e não precisa ser
+perdida para obter uma estrutura explícita.
+
+## Decisão
+
+As superfícies mantidas pela casa adotam a gramática `Root > Header + Body + Footer`, com
+`Title`, `Description`, `Meta` e `Actions` pertencendo ao `Header` da mesma família.
+
+- `Page` oferece `PageHeader`, `PageTitle`, `PageDescription`, `PageMeta`, `PageActions` e
+  `PageBody`.
+- `Content` representa uma região de conteúdo semanticamente nomeada e oferece `ContentHeader`,
+  `ContentTitle`, `ContentDescription`, `ContentMeta`, `ContentActions` e `ContentBody`.
+- `CardContent` passa a ter `CardBody` como nome canônico.
+- `Drawer` recebe `DrawerBody`.
+- `PaneContent` passa a ter `PaneBody` como nome canônico.
+- `Dialog` permanece como referência porque já possui `DialogHeader` e `DialogBody`.
+- `Alert` oferece `AlertMedia`, `AlertHeader`, `AlertTitle`, `AlertDescription` e
+  `AlertActions`; a forma curta por propriedades materializa esses mesmos slots.
+- `Empty` oferece `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription` e
+  `EmptyActions`. `EmptyContent` permaneceu como alias legado durante a versão 12 e foi removido na
+  versão 13.
+- `Item` oferece `ItemMedia`, `ItemHeader`, `ItemTitle`, `ItemDescription`, `ItemBody`,
+  `ItemActions` e `ItemFooter`. `ItemContent` permanece temporariamente como alias legado de
+  corpo, mas deixa de envolver título e descrição no código novo.
+
+`Page` e `Content` aceitam também uma forma curta com `title`, `description`, `meta` e `actions`.
+Essa forma é açúcar sintático: produz a mesma árvore semântica, os mesmos estilos e os mesmos
+`data-slot` da composição explícita. Um consumidor não pode misturar as duas formas na mesma raiz.
+
+`ContentHeader` deixa de ser uma região solta e passa a pertencer a `Content`. A forma histórica
+por propriedades continua disponível temporariamente dentro de `Content`, mas a composição
+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`.
+`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`.
+
+As superfícies modais centralizadas pertencem a uma única família pública, `Dialog`. O modo padrão
+permite tarefas e conteúdo dispensáveis; `mode="alert"` exige uma resposta explícita e seleciona
+internamente a primitiva que emite `role="alertdialog"`, prende o foco e impede o fechamento pelo
+clique externo. O comportamento determina o papel de acessibilidade: `role` não é usado como chave
+de configuração. A família pública `AlertDialog` deixa de existir, enquanto os métodos imperativos
+`dialog.alert`, `dialog.confirm`, `dialog.prompt` e `dialog.choose` usam `Dialog mode="alert"`.
+
+Os dois modos usam o fundo base e o texto de primeiro plano, delimitados por borda semântica, raio
+`xl` e elevação. A anatomia interna continua responsável pelo espaçamento de cabeçalho, corpo e
+rodapé. O fundo base preserva o contraste com faixas internas, enquanto a borda torna o limite do
+modal reconhecível mesmo quando a página usa o mesmo fundo. No modo de alerta, `DialogMedia`
+oferece a moldura quadrada de mídia e o header e o footer adotam a composição compacta da resposta.
+
+`Drawer` preserva a moldura externa ancorada à borda da janela, mas compartilha com `Dialog` as
+faixas internas: o header recebe divisor inferior, o footer recebe divisor superior sobre fundo
+sutil e o body mantém o mesmo alinhamento horizontal. Essa aproximação não adiciona raio nem borda
+ao lado preso à janela.
+
+Primitives comportamentais não escolhem a aparência do controle. `DialogClose` e `DrawerClose`
+aplicam fechamento ao filho; `Button` define contexto, variante, tamanho e o efeito do clique. Em
+`Dialog mode="alert"`, `DialogClose initialFocus` marca a saída segura sem dividir fechamentos entre
+action e cancel. `result` identifica uma resposta para `Dialog onResult` quando o consumidor precisa
+observá-la. A composição com `asChild` mantém o elemento interativo único e torna a mesma regra
+previsível em diálogos comuns, drawers e diálogos que exigem resposta.
+
+A API imperativa mantém contratos semânticos curtos para reconhecimento, confirmação binária e
+entrada textual. Para escolhas simples com mais resultados, `dialog.choose` recebe uma coleção de
+ações e devolve a união dos valores de `result`, ou `null` quando a superfície fecha sem escolha.
+A coleção exige um único `initialFocus` habilitado e resultados únicos. Composição JSX permanece
+para fluxos cujo carregamento, validação, erro ou estado controlado precisa existir dentro do modal.
+
+Nas superfícies horizontais, `Media` e `Header` formam a mesma linha estrutural. Quando `Media`
+desenha uma moldura para ícone ou imagem, ela mantém largura e altura iguais e fica alinhada ao
+topo. O conteúdo textual determina naturalmente a altura da linha sem transformar a mídia em um
+retângulo quando a descrição ocupa mais linhas.
+
+Nas superfícies de feedback, `Actions` se alinha ao fim lógico da área útil e permanece centralizado
+verticalmente na mesma linha do conteúdo. `Alert` e `Toast` compartilham essa posição; descrições
+longas ocupam o espaço restante e quebram linha sem deslocar as ações para o rodapé.
+
+## Consequências
+
+- A API comum fica previsível sem obrigar o caso simples a escrever todos os slots.
+- A forma explícita permite composição e extensão sem reconstruir o layout da biblioteca.
+- Em `Page` e `Content`, tipos separam as props das duas formas, contexto em runtime protege os
+  slots e `opus check` verifica a anatomia JSX completa. Nas famílias históricas, o lint reconhece
+  wrappers transparentes e render props: reprova uma família visivelmente errada sem proibir que
+  um slot seja encapsulado por um componente reutilizável.
+- Aliases históricos podem permanecer durante uma janela de migração e ser removidos numa versão
+  major; a versão 13 remove `EmptyContent` e mantém os demais aliases até uma decisão específica.
+- Consumidores precisam migrar `ContentHeader` solto para `Content` e podem migrar as demais formas
+  gradualmente enquanto os aliases existirem.
+- Alertas e itens simples ganham uma hierarquia igual sem perder suas semânticas distintas:
+  `Alert` comunica estado e `Item` representa uma entidade ou opção numa coleção.
+- Diálogos comuns e diálogos que exigem resposta compartilham nome, anatomia e moldura visual;
+  consumidores escolhem a diferença comportamental com `mode`, sem reconstruir a superfície.
+
+## Alternativas consideradas
+
+### Manter APIs diferentes por componente
+
+Preservaria compatibilidade total, mas manteria a carga cognitiva e impediria uma regra estrutural
+comum. Foi descartada porque as diferenças não representam comportamentos distintos.
+
+### Exigir somente composição explícita
+
+Produziria uma API uniforme, mas tornaria páginas e regiões simples desnecessariamente verbosas.
+Foi descartada porque shorthand e slots podem convergir para uma única implementação.
+
+### Renomear `ContentHeader` sem criar `Content`
+
+Nomes como `SectionHeader` pressupõem outro pai; nomes como `GenericHeader` descrevem ausência de
+semântica; e `HeadingBlock` abandona a gramática das demais famílias. Foi descartada em favor de
+dar a `ContentHeader` um pai estrutural real.
+
+### Manter `DialogContent` como card sem borda
+
+Preservaria a diferença histórica entre `Dialog` e o antigo `AlertDialog`, mas faria superfícies com a mesma
+função modal responderem a fundos e limites diferentes. Foi descartada porque essa diferença não
+representa comportamento distinto e pode reduzir a percepção do contorno sobre páginas com fundo
+semelhante.
+
+### Manter `AlertDialog` como família pública separada
+
+Espelharia diretamente as duas primitives do Radix, mas duplicaria nomes estruturais e faria a API
+pública expressar um detalhe de implementação. Foi descartada porque `mode="alert"` preserva a
+semântica e as garantias comportamentais sem obrigar quem consome a reaprender outra família.
+
+### Usar `role="alertdialog"` para selecionar o comportamento
+
+Seguiria a API de alguns design systems, mas transformaria um atributo de acessibilidade em chave de
+comportamento, algo que o restante do Opus não faz. Foi descartada para que o `mode` selecione as
+garantias e o componente derive o `role` correto.
+
+### Expor action e cancel como primitives distintos no diálogo de alerta
+
+Preservaria os nomes do Radix, mas apresentaria um fechamento como “action” embora cancelar também
+seja uma ação. Os dois caminhos fecham a superfície; a única diferença técnica relevante é o
+registro do destino inicial do foco. Foi descartada em favor de `DialogClose`, cuja propriedade
+`initialFocus` expressa essa diferença sem criar duas categorias públicas.
+
+### Exigir composição JSX para toda escolha com mais de duas ações
+
+Manteria a API imperativa menor, mas obrigaria cada consumidor a reconstruir fila, fechamento,
+foco seguro e resolução para uma escolha sem estado próprio. Foi descartada porque `dialog.choose`
+consegue preservar essas garantias e devolver um resultado tipado sem absorver formulários ou ações
+assíncronas que precisam manter o modal aberto.
+
+## Verificação
+
+- Testes de UI comparam DOM, acessibilidade e `data-slot` das formas curta e explícita.
+- Testes de runtime proíbem a mistura das formas e os slots de `Page`/`Content` usados fora da
+  família correspondente; essa relação entre elementos JSX não é representável somente pelo tipo
+  de `children` do React.
+- `opus check` reprova relações JSX estruturais inválidas nos consumidores.
+- Testes de layout verificam que `AlertMedia` e `ItemMedia` mantêm molduras quadradas alinhadas ao
+  topo, sem fixar a altura do conteúdo textual.
+- Testes de estrutura verificam que os dois modos de `DialogContent` usam fundo base, texto de
+  primeiro plano, borda semântica, raio e elevação, sem retornar ao fundo de card.
+- Testes do `Drawer` verificam divisores, fundo do footer e alinhamento de padding entre header,
+  body e footer.
+- Testes de estrutura verificam que `DialogClose` não materializa `Button`, usa `result` somente como
+  resposta e aplica `initialFocus` à primitive que registra a saída segura no modo de alerta.
+- Testes do host verificam inferência dos resultados de `dialog.choose`, foco seguro, defaults
+  visuais, escolha explícita, fechamento sem escolha e entradas inválidas.
+- Documentação e metadados apresentam a forma curta como caminho comum e a composição explícita
+  como caminho de extensão.

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

@@ -0,0 +1,182 @@
+# ADR 0006 — Contexto semântico precede variante visual
+
+- Status: aceita
+- Data: 2026-09-04
+
+## Contexto e forças
+
+Os componentes do Opus usam `variant` para eixos diferentes. Em Button, Badge, Alert e Dot, a
+prop mistura hierarquia (`default`, `secondary`), contexto semântico (`success`, `warning`,
+`destructive`) e tratamento visual (`outline`, `ghost`, `link`). Em Table, Detail, Tabs e Item,
+`variant` descreve apenas uma alternativa estrutural ou visual local (`plain`, `framed`, `line`).
+
+Ao mesmo tempo, entradas de `t.dict` usam `tone` para selecionar a família semântica de status e
+estágios. Essa família não coincide com os componentes: o estado vermelho é `danger` no dicionário,
+`destructive` em alguns primitives, e `MetricCard tone="warning"` atualmente usa tokens vermelhos.
+Um agente ou consumidor precisa conhecer cada exceção para obter a mesma linguagem visual.
+
+As forças em tensão são:
+
+- o significado precisa permanecer independente da forma concreta com que cada componente o
+  apresenta;
+- a API deve ser previsível entre primitives sem transformar todas as combinações em opções
+  válidas para todos os componentes;
+- `destructive` precisa continuar descrevendo o risco comportamental de uma ação, sem se tornar o
+  nome da família visual vermelha;
+- dicionários e componentes existentes precisam de uma migração explícita e verificável;
+- agentes precisam aprender a regra por contratos, documentação e avaliações, não por memória ou
+  inferência a partir de exemplos isolados;
+- light mode e dark mode são temas, não significados de produto.
+
+## Alternativas consideradas
+
+### Manter `tone` nos dicionários e `variant` nos componentes
+
+Preserva compatibilidade imediata, mas mantém dois nomes para o mesmo eixo e deixa `variant`
+misturar significado com apresentação. Cada novo componente precisaria repetir mapas locais.
+Rejeitada.
+
+### Copiar literalmente as variantes contextuais do Bootstrap
+
+O vocabulário `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light` e `dark` é
+conhecido e cobre grande parte dos casos. Porém, o Bootstrap chama de variante tanto o contexto
+quanto sua materialização (`btn-danger`, `btn-outline-danger`), mistura hierarquia com semântica e
+inclui `light`/`dark`, que pertencem ao tema. Copiar a API manteria a ambiguidade que queremos
+remover. Rejeitada como contrato literal e aceita como referência de vocabulário.
+
+### Declarar contexto e variante como eixos independentes
+
+`context` escolhe a família de tokens e responde por que existe o realce. `variant` escolhe como a
+família aparece naquele componente. Cada primitive aceita somente o subconjunto coerente com seu
+papel e fornece defaults. É uma mudança maior, mas torna combinações e exceções explícitas e permite
+que domínio, UI e agentes compartilhem o mesmo modelo. Aceita.
+
+## Decisão
+
+### Vocabulário contextual
+
+O Opus define o vocabulário canônico:
+
+```ts
+type UiContext =
+  | 'neutral'
+  | 'primary'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger'
+```
+
+- `neutral`: estado normal, inativo ou sem julgamento positivo/negativo;
+- `primary`: ação ou elemento de maior destaque no contexto atual;
+- `info`: informação ou processo em andamento sem alerta;
+- `success`: resultado positivo ou estado saudável;
+- `warning`: condição que pede atenção, mas não representa falha;
+- `danger`: falha, impedimento ou consequência perigosa.
+
+`secondary` não é contexto universal: ação secundária é hierarquia, enquanto estado neutro é
+semântica. `light` e `dark` permanecem modos de cor. Nenhum dos três entra em `UiContext`.
+
+Entradas de dicionário aceitam `DictContext`, o subconjunto sem `primary`, porque um estado de
+domínio não se torna a ação principal da interface. A metadata canônica passa de `tone` para
+`context`.
+
+### Variante visual
+
+Para componentes semânticos, `variant` descreve somente o tratamento visual:
+
+```ts
+type SemanticVariant = 'solid' | 'subtle' | 'outline' | 'ghost' | 'link'
+```
+
+Cada componente aceita apenas as variantes que consegue materializar com coerência. Os defaults
+iniciais são:
+
+| Componente | Contexto padrão | Variante padrão | Contextos permitidos |
+| --- | --- | --- | --- |
+| Button | `primary` | `solid` | `neutral`, `primary`, `danger` |
+| Badge | `neutral` | `subtle` | todos |
+| Alert | `neutral` | `subtle` | `neutral`, `info`, `success`, `warning`, `danger` |
+| Dot | `neutral` | `solid` | `neutral`, `primary`, `info`, `success`, `warning`, `danger` |
+| MetricCard | `neutral` | `subtle` no ícone | `neutral`, `info`, `success`, `warning`, `danger` |
+
+`solid`, `subtle` e `outline` podem compartilhar um contexto sem compartilhar classes. `ghost` e
+`link` ficam restritos a controles interativos. Cor e ícone continuam reforços: texto ou nome
+acessível comunica o significado.
+
+Componentes cuja `variant` é exclusivamente estrutural ou local, como `plain | framed` e
+`default | line`, podem mantê-la. Ao criar API nova, preferir uma prop específica quando o nome do
+eixo for mais claro (`frame`, `layout`, `appearance`); não renomear primitives existentes sem ganho
+observável.
+
+### Ações destrutivas
+
+`destructive` permanece em contratos de ação e confirmação para declarar risco, confirmação e
+comportamento. A projeção visual desse risco usa `context="danger"`. Portanto, `destructive` não é
+um `UiContext` nem uma variante visual canônica.
+
+### Compatibilidade
+
+A migração ocorre em uma janela explícita:
+
+1. componentes e `t.dict` passam a aceitar a API canônica e os nomes antigos como aliases
+   depreciados;
+2. informar os dois eixos antigo e novo ao mesmo tempo é inválido quando houver ambiguidade;
+3. renderers normalizam aliases antes de escolher tokens;
+4. manifest, documentação e exemplos gerados projetam somente `context` como forma canônica;
+5. consumidores são migrados e um gate impede novos usos semânticos de `tone` e de variantes como
+   `success`, `warning`, `danger` ou `destructive`;
+6. os aliases são removidos somente em uma versão major posterior, depois de o inventário chegar a
+   zero.
+
+Usos locais de `tone` que não representam contexto semântico não são convertidos automaticamente.
+Por exemplo, relações de diagrama com valores `optional`, `same` e `return` devem receber um nome
+de domínio como `kind` ou `relation`, não `UiContext`.
+
+## Orientação para agentes
+
+A regra precisa alcançar uma IA por fontes complementares e verificáveis:
+
+1. **Contrato compilável:** `UiContext`, `DictContext` e os tipos de props limitam as combinações
+   possíveis e são a fonte primária.
+2. **Catálogo do Opus:** documentação e metadata de cada componente explicam contexto, variante,
+   defaults e exceções com exemplos canônicos.
+3. **Skills:** `build-opus-ui` ensina a matriz `context × variant`; `model-opus-dictionary` exige
+   `context` em status e estágios e proíbe inferência pela chave ou pelo nome do dicionário.
+4. **Avaliações:** casos positivos, negativos e de execução reprovam `variant="success"`,
+   `tone="warning"` sem compatibilidade justificada, `destructive` como cor e comunicação somente
+   por cor.
+5. **Instrução permanente:** a instrução materializada do Opus resume a regra e encaminha às
+   skills; não replica toda a tabela.
+6. **Gate estático:** o check do Opus detecta novas ocorrências legadas fora de arquivos de
+   compatibilidade, testes de migração e exemplos negativos explicitamente marcados.
+7. **Materialização:** mudanças no registry são propagadas por `opus setup`; o projeto consumidor
+   valida que `.agents` e os adapters suportados não divergiram da versão declarada.
+
+Essa redundância é intencional: tipos impedem combinações inválidas no código, documentação apoia
+decisões humanas, skills orientam o fluxo e o gate detecta regressão mesmo quando uma instrução não
+for consultada.
+
+## Consequências
+
+- Primitives semânticos passam a compartilhar um vocabulário e tokens contextuais.
+- Defaults podem variar por componente, mas a mesma palavra nunca muda de significado.
+- A API fica mais explícita em chamadas que precisam dos dois eixos.
+- A transição aumenta temporariamente tipos, testes e normalização por causa dos aliases.
+- Temas precisam oferecer tokens de superfície, borda, texto de ênfase e sólido para cada contexto,
+  em light e dark mode.
+- Consumidores com classes Tailwind semânticas literais não são automaticamente corretos; a
+  migração precisa classificar se representam contexto, visualização de dados ou linguagem própria
+  de um diagrama.
+
+## Verificação
+
+- testes puros cobrem o vocabulário, aliases e combinações inválidas;
+- testes de cada primitive cobrem a matriz aceita e seus defaults;
+- testes de `t.dict`, descriptor e manifest comprovam `context` e a compatibilidade de leitura;
+- testes de renderização provam que `DictionaryValue` usa `context` sem a tela escolher classes;
+- avaliações das skills cobrem seleção, execução correta e exemplos que devem ser recusados;
+- o validador de skills passa no registry e nas cópias materializadas;
+- o gate estático reprova novas variantes semânticas e novos `tone` públicos;
+- `opus check`, testes, typecheck, build, `opus copy --check` e gates do consumidor permanecem
+  verdes.

package/docs/adr/0007-toast-actions-form-an-ordered-collection.md

@@ -0,0 +1,63 @@
+# ADR 0007 — Ações de Toast formam uma coleção ordenada
+
+- Status: aceita
+- Data: 2026-09-05
+
+## Contexto
+
+O Opus exportava diretamente a API do Sonner, que distingue uma ação principal (`action`) de uma
+ação especializada de cancelamento (`cancel`). Essa divisão expõe uma decisão da dependência na API
+da casa e força uma semântica que não existe em toda notificação. Os demais componentes do Opus
+tratam ações como uma região ordenada, enquanto contexto e variante descrevem a hierarquia visual.
+
+A compatibilidade importa porque consumidores da versão 12 já podem usar os campos do Sonner. Ao
+mesmo tempo, manter os dois formatos indefinidamente deixaria a API ambígua e impediria que o Opus
+controlasse composição, estilos e comportamento de forma consistente.
+
+## Decisão
+
+O contrato canônico de Toast passa a aceitar `actions`, uma coleção ordenada de `ToastAction`.
+Cada entrada declara `label`, `onClick` e, quando necessário, `context`, `variant`, `disabled` e uma
+chave React. As ações são renderizadas com `Button size="sm"`: a última usa `primary + solid` por
+padrão e as anteriores usam `neutral + ghost`.
+
+Depois do handler, o Toast fecha, salvo quando o evento chama `preventDefault()`. `actions` não
+pode ser combinado com os campos antigos `action` ou `cancel`.
+
+`action` e `cancel` permaneceram aceitos e marcados como obsoletos durante a versão 12. A versão 13
+remove esses campos e a estilização de compatibilidade. Os consumidores dependem do contrato do
+Opus, sem expor a divisão especializada do Sonner.
+
+## Consequências
+
+- Uma notificação pode ter zero, uma ou mais ações sem inventar um papel de cancelamento.
+- A ordem da coleção comunica hierarquia e mantém o destaque principal no final, como nas demais
+  regiões de ação.
+- Consumidores da versão 12 tiveram uma janela de migração antes da remoção dos campos obsoletos.
+- `toast.promise` continua seguindo o contrato próprio do Sonner nesta etapa; a coleção canônica se
+  aplica aos disparos simples e tipados por estado.
+
+## Alternativas consideradas
+
+### Manter `action` e `cancel`
+
+Preservaria a API da dependência, mas manteria uma distinção semântica artificial e impediria uma
+composição uniforme. Foi descartada como contrato canônico.
+
+### Remover os campos antigos imediatamente
+
+Produziria uma API menor, mas quebraria consumidores dentro da mesma versão principal. Foi
+descartada em favor de uma janela explícita de migração.
+
+### Aceitar somente elementos React prontos
+
+Daria liberdade total de composição, mas transferiria geometria, hierarquia e fechamento para cada
+consumidor. Foi descartada porque ações declarativas cobrem o fluxo comum sem impedir personalização
+por contexto e variante.
+
+## Verificação
+
+- Testes de DOM verificam que `actions` produz uma região única com `Button` do Opus.
+- Testes de interação verificam ordem, defaults visuais, execução e fechamento.
+- Testes de contrato reprovam a mistura de `actions` com `action` ou `cancel`.
+- Documentação e metadata apresentam somente `actions` como caminho canônico.

package/docs/adr/0008-hierarchical-navigation-is-composed-at-the-consumer-boundary.md

@@ -0,0 +1,71 @@
+# ADR 0008 — Navegação hierárquica é composta na fronteira do consumidor
+
+- **Status:** aceita.
+- **Data:** 2026-09-06.
+
+## Contexto
+
+`SidebarNav` oferece `groups`, `items` e `subgroups`. O terceiro nível foi introduzido para
+preservar a estrutura seção → grupo → página do `DocBrowser`, mas não possui outro consumidor no
+Opus nem nos aplicativos conhecidos. A API geral passou a carregar uma topologia rígida criada por
+uma única tela.
+
+Ao mesmo tempo, `SidebarItem` já representa os comportamentos necessários para árvores: um destino
+principal, um controle irmão de expansão por `onToggle` e `expanded`, ações por item e indicadores
+de drop. O estado da árvore e a origem de seus nós variam por consumidor. Porém, o recuo e a guia
+vertical que comunicam descendência se repetiam nos aplicativos como a mesma combinação de classes,
+embora sejam parte da linguagem visual da sidebar.
+
+## Decisão
+
+`SidebarNav` mantém somente a estrutura plana `groups → items`. `SidebarNavSubgroup` e a
+propriedade `subgroups` deixam a API pública.
+
+Hierarquias são compostas pelo consumidor com `SidebarGroupLabel`, `SidebarItem` e
+`SidebarTreeGroup`. O consumidor controla expansão, ordem, profundidade e carregamento dos nós;
+`SidebarTreeGroup` aplica a guia e o recuo dos descendentes, enquanto `SidebarItem` mantém a
+apresentação e a acessibilidade de cada linha.
+
+O `DocBrowser` materializa sua árvore própria a partir de `DocSection[]`. Seções aparecem como
+rótulos, grupos nomeados viram nós expansíveis e páginas viram folhas. Grupos começam abertos para
+preservar a descoberta atual, podem ser recolhidos e voltam a abrir quando passam a conter a página
+ativa.
+
+## Consequências
+
+- A API geral deixa de prometer uma árvore limitada a exatamente três níveis.
+- A documentação continua preservando seção, grupo e página sem usar um contrato específico no
+  componente compartilhado.
+- Outros consumidores podem montar árvores rasas, recursivas, assíncronas ou arrastáveis com os
+  mesmos elementos, sem novas propriedades na `SidebarNav` nem classes locais para a guia.
+- Remover `SidebarNavSubgroup` e `subgroups` é uma mudança incompatível e exige uma versão major na
+  próxima publicação do pacote.
+- `DocBrowser` passa a possuir o estado de expansão de seus grupos.
+
+## Alternativas consideradas
+
+### Manter `subgroups`
+
+Preservaria compatibilidade, mas manteria na API geral uma topologia usada somente pela
+documentação. Foi descartada porque a composição existente já cobre o comportamento sem acoplar o
+componente à estrutura de uma tela.
+
+### Substituir por uma árvore recursiva em `SidebarNav`
+
+Aceitar `children` recursivos permitiria profundidade arbitrária, mas também exigiria que o
+componente decidisse expansão, carregamento, seleção e semântica de pastas para todos os produtos.
+Foi descartada até que consumidores independentes revelem um contrato comum.
+
+### Achatar a documentação
+
+Converter grupos em uma lista única simplificaria o renderer, mas perderia a classificação que
+também é produzida por pastas e pelo frontmatter das docs de projetos. Foi descartada porque a
+hierarquia tem significado para descoberta e localização.
+
+## Verificação
+
+- Um teste de API impede que `SidebarNavSubgroup` volte a ser exportado.
+- Testes de `SidebarNav` cobrem grupos planos, seleção e omissão de grupos vazios.
+- Um teste de `SidebarTreeGroup` protege a guia, o recuo e o espaçamento entre descendentes.
+- Testes de `DocBrowser` cobrem os três níveis, expansão e reabertura do grupo da página ativa.
+- A documentação do Sidebar demonstra árvore com `SidebarTreeGroup` e não menciona `subgroups`.

package/docs/radius-scale.md

@@ -27,7 +27,7 @@ voltaria a acoplar forma e tipo de componente, problema removido na versão 10.0
   token semântico por componente.
 - Superfícies aninhadas evitam moldura dupla e normalmente usam um degrau menor que o contêiner.
   Elementos conectados removem os raios nas arestas internas.
-- Card, Dialog e AlertDialog permanecem em `xl`. Molduras estruturais com cantos, como a tabela
+- Card e os dois modos de Dialog permanecem em `xl`. Molduras estruturais com cantos, como a tabela
   standalone, permanecem em `lg`; Page, Split e Sidebar não ganham uma moldura por essa regra.
 - Calendar e Command preservam a geometria embutível. Um consumidor standalone pode ajustar o
   contêiner por `className` quando a composição pedir mais presença.