@softize/opus 12.10.0 → 12.11.0

package/bin/lib/copy.mjs

@@ -84,6 +84,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 +106,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 +134,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 +144,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 +190,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,6 +210,7 @@ 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']])],
 ])
 

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,97 @@
+# 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.
+- `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`.
+`EmptyContent` e `CarouselContent` também permanecem porque não representam o body de uma
+superfície estrutural.
+
+Nas superfícies horizontais, `Media` e `Header` formam a mesma linha estrutural. A região visual
+de `Media` tem largura estável e se estende pela altura útil do header, mantendo seu conteúdo
+centralizado. Assim, título e descrição de uma linha não deixam uma sobra inferior ao lado da
+moldura; conteúdo textual maior continua determinando naturalmente a altura da linha.
+
+## 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 permanecem durante a versão 12 e podem ser removidos numa versão major.
+- 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.
+
+## 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.
+
+## 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` se estendem pela linha do header e
+  centralizam o ícone, sem fixar a altura do conteúdo textual.
+- 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.10.0",
+  "version": "12.11.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/instructions/opus.md

@@ -15,6 +15,11 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
 - Manter contrato compartilhável separado de banco, segredo e driver server-only; usar
   `defineContract` com `bindAction` quando cliente e servidor consomem a mesma action.
 - Não duplicar schemas, tipos de transporte, validação ou fetch que o contrato já fornece.
+- Em UI semântica, declarar primeiro `context` (`neutral`, `primary`, `info`, `success`, `warning`
+  ou `danger`) e usar `variant` somente para o tratamento visual (`solid`, `subtle`, `outline`,
+  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` e variantes
+  semânticas antigas são apenas compatibilidade de migração. `destructive` permanece uma
+  propriedade comportamental de actions e se projeta visualmente como `danger`.
 - Declarar datasets persistentes com `defineSeed` + `bindSeed`, registrá-los em `opus.config.ts`
   e operá-los por `opus seed`; não criar comandos de seed paralelos nem reset implícito.
 - Regenerar o inventário com `opus copy` quando mudar copy em contrato ou componente Opus

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

@@ -19,46 +19,54 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    mensagem de vocabulário fechado vêm do dicionário do domínio (`labelFor`/`metaFor`); ao
    encontrar catálogo repetido à mão ou vocabulário ainda sem dicionário, carregar
    `$model-opus-dictionary`.
-3. Apresentar valor de dicionário por `DictionaryValue` ou pela coluna de `ActionList`, que
+3. Em componentes semânticos, declarar `context` antes de escolher `variant`: `context` comunica
+   `neutral`, `primary`, `info`, `success`, `warning` ou `danger`; `variant` descreve somente o
+   tratamento `solid`, `subtle`, `outline`, `ghost` ou `link`, conforme o subconjunto aceito pelo
+   componente. Não usar `variant="success"`, `variant="destructive"` nem `tone` em código novo.
+   `destructive` permanece metadata comportamental de action e se projeta como `context="danger"`.
+4. Apresentar valor de dicionário por `DictionaryValue` ou pela coluna de `ActionList`, que
    aplicam o papel declarado em `presentation` (classificação em badge `outline`, status e estágio
-   em badge tonal, `plain` em texto). Não escolher badge, tom ou ícone pelo nome do dicionário:
+   em badge `context + subtle`, `plain` em texto). Não escolher badge, contexto ou ícone pelo nome do dicionário:
    dicionário sem papel declarado renderiza texto e pede classificação por
    `$model-opus-dictionary` antes de qualquer destaque visual. Sobrepor os defaults só com motivo
    explícito nas props do renderer.
-4. Dar a cada dimensão independente usada para comparação ou filtro um campo, coluna ou espaço
+5. Dar a cada dimensão independente usada para comparação ou filtro um campo, coluna ou espaço
    identificável próprio, com rótulo. Hierarquia tipográfica (texto secundário sob um nome) não
    pode fazer uma dimensão parecer explicação de outra. Cor e ícone reforçam; o texto do valor
    permanece sempre presente.
-5. Deixar ausência, paginação e largura de filtro com o pattern: célula e `DetailField` já
+6. Deixar ausência, paginação e largura de filtro com o pattern: célula e `DetailField` já
    representam valor ausente (`EmptyValue`, `empty` para o significado do domínio); listas
    paginam pela primitiva `Pagination`; selects inline de filtro têm largura fixa. Não reescrever
    esses defaults na tela.
-6. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
+7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh.
-7. Compor páginas com `Page` e seu teto centralizado padrão de `72rem`. Usar
-   `ContentHeader` em seções que precisam da mesma estrutura de título, descrição,
-   metadados e ações; ajustar `level` pela hierarquia semântica, não pelo destaque visual.
-8. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
+8. Compor superfícies pela gramática estrutural do catálogo: `Page` contém `PageHeader` e
+   `PageBody`; `Content` contém `ContentHeader` e `ContentBody`; Card, Drawer e Pane usam seus
+   respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` ou `Content` com
+   `title`, `description`, `meta` e `actions`; não misturá-la com o header explícito. 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`.
+9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
-9. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
+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.
-10. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
-11. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
+11. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
+12. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
    `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da
    igualdade atual com `--foreground`, porque o app pode sobrescrever cada par.
-12. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
+13. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
    `rounded-xs` a `rounded-2xl` já expressam a forma. Escolher o degrau pela escala visual:
    detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
    molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação
    orienta o default, não cria uma restrição semântica. Em aninhamento, evitar moldura dupla e
    reduzir o raio interno; em grupos conectados, remover os raios das arestas internas. Tamanho
    e forma permanecem eixos separados; usar `shape="pill"` quando a pílula for intencional.
-13. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
+14. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
     moldura tracejada, de um resultado vazio dentro de uma estrutura existente, que preserva
     a moldura sólida dessa estrutura.
-14. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+15. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
 
 ## Verificação
 
@@ -76,8 +84,11 @@ Inspecionar visualmente a rota real e validar navegação por URL quando aplicá
 - Não criar fetch, schema ou tipo paralelo ao contrato.
 - Não copiar componente da lib para customizar sem antes verificar extensão/composição.
 - Não forçar modal roteável quando o estado é efêmero e sem valor de navegação.
-- Não inferir apresentação de dicionário: nem badge para todo valor, nem tom ou ícone
+- Não inferir apresentação de dicionário: nem badge para todo valor, nem contexto ou ícone
   inventados, nem tooltip que repete o rótulo.
+- Não usar nomes de compatibilidade (`tone`, `variant="success"`, `variant="destructive"`) em
+  código novo; consultar a página “Contexto & Variante” do catálogo quando a combinação não estiver
+  clara.
 - Não repetir fallback de ausência, paginador ou largura de filtro que o pattern já resolve.
 
 ## Recursos

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -3,11 +3,14 @@
 - Dispara: “Monte a tela de edição usando a form action do Opus.”
 - Não dispara: “Ajuste o CSS de um e-mail estático.”
 - Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.
-- Execução estrutural: montar uma página de relatório com `Page`, `ContentHeader` em uma seção,
-  `ActionFilterBar` separado do renderer, `ItemGroup` para uma coleção secundária e um
-  `ActionFormDialog`; provar teto padrão de `72rem`, hierarquia por `level`, vazio estrutural
-  sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento inferido e cancelamento
-  `ghost` no modal.
+- Execução estrutural: montar uma página de relatório com `Page > PageHeader + PageBody`, uma seção
+  `Content > ContentHeader + ContentBody`, `ActionFilterBar` separado do renderer, `ItemGroup` para
+  uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
+  `level`, vazio estrutural sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento
+  inferido e cancelamento `ghost` no modal.
+- Execução abreviada: montar outra página com `<Page title description actions>` e uma seção com
+  `<Content title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
+  rejeita a mistura entre props abreviadas e headers explícitos.
 - Execução de forma: compor uma tabela dentro de Card sem moldura duplicada, manter a moldura
   estrutural standalone em `rounded-lg` e os controles internos em `rounded-md`.
 - Reprova: criar uma casca `bg-card` que herda o texto global ou introduzir `rounded-widget`
@@ -17,11 +20,19 @@
 - Reprova: reconstruir manualmente o container de página, usar `Empty` tracejado como vazio de
   tabela, alinhar toda coluna numérica à direita por inferência ou destacar “Cancelar” como ação
   primária em modal.
+- Reprova: deixar `ContentHeader` fora de `Content`, omitir `PageBody`/`ContentBody` na composição
+  explícita, usar `CardContent`/`PaneContent` em código novo ou tratar `DialogContent` como Body.
 - Execução de dicionários: montar a lista de clientes com “Pessoa física/Empresa” e
   “Prospect/Cliente”; provar que o tipo ocupa a coluna “Tipo” como classificação (badge `outline`
   com os ícones declarados `user` e `building`), que o estágio ocupa a coluna “Estágio” como badge
   tonal sem `outline`, que nenhuma das duas usa `cells`, que o texto do valor está presente e que
   não há tooltip em “Pessoa física/Empresa” quando a descrição não acrescenta ao rótulo.
+- Execução de contexto: montar ações, badges, alertas e indicadores com o mesmo estado `warning`;
+  exigir `context="warning"`, variantes visuais coerentes por componente e tokens da mesma família.
+  Uma exclusão continua `destructive` no contrato, mas usa `context="danger"` na projeção visual.
+- Reprova: usar `tone` em componente novo, `variant="success"`, `variant="warning"` ou
+  `variant="destructive"`; usar `light`/`dark` como contexto; ou tratar `secondary` como sinônimo
+  de estado neutro.
 - Reprova: envolver todo valor de dicionário em badge sem papel declarado, ou escolher a variante
   pelo nome do dicionário.
 - Reprova: colocar duas dimensões independentes na mesma célula sem identificação, como o tipo em