@softize/opus 12.9.0 → 12.11.0

package/bin/lib/copy.mjs

@@ -1,7 +1,7 @@
 /**
- * Inventário semântico de copy dos contratos Opus.
+ * Inventário semântico de copy dos contratos e dicionários Opus.
  *
- * O Opus conhece o papel dos textos declarados em defineAction/defineContract;
+ * O Opus conhece o papel dos textos declarados em defineAction/defineContract e t.dict;
  * a @softize/base continua dona da política e da validação editorial. Este módulo
  * apenas projeta o protocolo JSON v2 sem executar código do consumidor.
  */
@@ -61,6 +61,7 @@ const COPY_ROLES = new Set([
 const AUDIT_REFERENCE = /^(?:https?:\/\/\S+|[a-z][a-z0-9-]*:\S+|(?:[A-Za-z0-9._-]+\/)+[A-Za-z0-9._#/-]+|[A-Za-z0-9._-]+\.(?:md|json|ya?ml)(?:#[^\s]+)?)$/u
 const CONTRACT_MODULES = new Set(['@softize/opus', '@softize/opus/core'])
 const CONTRACT_FACTORIES = new Set(['defineAction', 'defineContract'])
+const SCHEMA_ZOD_MODULES = new Set(['@softize/opus/schema/zod'])
 const ACTION_BINDING_KEYS = new Set(['authorize', 'background', 'emits', 'handler', 'idempotency', 'loads'])
 
 // Somente exports Opus cujo papel textual é estável por contrato do componente.
@@ -83,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'],
@@ -103,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'],
@@ -129,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>.
@@ -137,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'],
@@ -182,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']])],
@@ -199,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']])],
 ])
 
@@ -397,6 +409,18 @@ function knownContractFactory(call, checker) {
   return name !== null && CONTRACT_FACTORIES.has(name)
 }
 
+function knownDictionaryFactory(call, checker) {
+  const expression = resolveBinding(call.expression, checker)
+  if (!ts.isPropertyAccessExpression(expression) && !ts.isElementAccessExpression(expression)) return false
+  const member = ts.isPropertyAccessExpression(expression)
+    ? expression.name.text
+    : expression.argumentExpression === undefined
+      ? null
+      : staticText(expression.argumentExpression, checker)?.text ?? null
+  return member === 'dict' &&
+    importedMemberName(expression.expression, checker, (module) => SCHEMA_ZOD_MODULES.has(module)) === 't'
+}
+
 function knownBindAction(call, checker) {
   return importedMemberName(call.expression, checker, (module) => CONTRACT_MODULES.has(module)) === 'bindAction'
 }
@@ -512,7 +536,10 @@ function stableExpressionUse(node, checker, mode, stack) {
     ts.isSpreadAssignment(parent) || ts.isSpreadElement(parent) || ts.isArrayLiteralExpression(parent)
   ) return consumerMode === 'aggregate' && stableComposition(carrier, checker, stack)
   if (ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === carrier)) {
-    if (consumerMode === 'aggregate') return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
+    if (consumerMode === 'aggregate') {
+      if (knownDictionaryFactory(parent, checker)) return true
+      return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
+    }
     if (
       consumerMode === 'factory-result' && parent.arguments[0] === carrier &&
       knownBindAction(parent, checker) && safeBindActionBinding(parent, checker)
@@ -865,14 +892,15 @@ function diagnostic(file, sourceFile, node, field, category = 'content') {
 /**
  * Extrai as superfícies humanas de um source isolado.
  *
- * O retorno distingue arquivo sem contrato de contrato sem copy. Essa diferença é
- * necessária para hashear todo contrato e detectar a adição posterior de um texto.
+ * O retorno distingue arquivo sem superfície Opus de contrato sem copy. Essa diferença é
+ * necessária para hashear todo contrato ou dicionário e detectar a adição posterior de texto.
  */
 export function extractCopyFromSource(file, sourceText) {
   const { sourceFile, checker } = parseSource(file, sourceText)
   const entries = []
   const diagnostics = []
   let hasContract = false
+  let hasDictionary = false
   const hasUiImport = sourceFile.statements.some(
     (statement) =>
       ts.isImportDeclaration(statement) &&
@@ -999,6 +1027,42 @@ export function extractCopyFromSource(file, sourceText) {
     nestedObject(object, 'errors', (error, prefix) => addProperty(error, 'description', 'error', prefix))
   }
 
+  function extractDictionary(call) {
+    const entriesNode = call.arguments[0]
+    const entries = resolveBinding(entriesNode, checker)
+    if (!ts.isObjectLiteralExpression(entries)) {
+      diagnostics.push(diagnostic(file, sourceFile, entriesNode, 't.dict entries', 'structure'))
+      return
+    }
+
+    const listed = properties(entries, sourceFile, checker)
+    for (const opaque of listed.opaque) {
+      diagnostics.push(diagnostic(file, sourceFile, opaque, 't.dict entries', 'structure'))
+    }
+    for (const [key, entry] of listed.items) {
+      const valueNode = propertyValue(entry)
+      const value = resolveBinding(valueNode, checker)
+      if (!ts.isObjectLiteralExpression(value)) {
+        diagnostics.push(diagnostic(file, sourceFile, valueNode, `t.dict.${key}`, 'structure'))
+        continue
+      }
+      addProperty(value, 'label', 'label', `t.dict.${key}.`)
+      addProperty(value, 'description', 'description', `t.dict.${key}.`)
+      addProperty(value, 'doc', 'description', `t.dict.${key}.`)
+    }
+
+    if (call.arguments.length < 2) return
+    const optionsNode = call.arguments[1]
+    const options = resolveBinding(optionsNode, checker)
+    if (ts.isIdentifier(options) && options.text === 'undefined') {
+      const symbol = checker.getSymbolAtLocation(options)
+      const shadowed = symbol?.declarations?.some((declaration) => declaration.getSourceFile() === sourceFile) ?? false
+      if (!shadowed) return
+    }
+    if (ts.isObjectLiteralExpression(options)) addProperty(options, 'doc', 'description', 't.dict.options.')
+    else diagnostics.push(diagnostic(file, sourceFile, optionsNode, 't.dict options', 'structure'))
+  }
+
   function importedMember(node, modulePredicate) {
     return importedMemberName(node, checker, modulePredicate)
   }
@@ -1790,12 +1854,16 @@ export function extractCopyFromSource(file, sourceText) {
         else diagnostics.push(diagnostic(file, sourceFile, node.arguments[0], `${factory}(...)`, 'structure'))
       }
     }
+    if (ts.isCallExpression(node) && knownDictionaryFactory(node, checker) && node.arguments.length > 0) {
+      hasDictionary = true
+      extractDictionary(node)
+    }
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) extractJsx(node)
     ts.forEachChild(node, visit)
   }
   visit(sourceFile)
 
-  return { hasContract, hasCopySurface: hasContract || hasUiImport, entries, diagnostics }
+  return { hasContract, hasCopySurface: hasContract || hasDictionary || hasUiImport, entries, diagnostics }
 }
 
 function globRegex(pattern) {

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/docs/code-style.md

@@ -92,16 +92,20 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 | `Select.emptyText`, `Select.searchPlaceholder` | `empty-state`, `placeholder` |
 | `Select.options[].hint/triggerLabel/group` | `label`, `label`, `heading` |
 | `ActionTrigger.confirm.*` | papel correspondente do diálogo |
+| `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário | `label`, `description` |
 
 ## Cobertura e significado do gate verde
 
-O extrator cobre duas superfícies, sem heurística de nome:
+O extrator cobre três superfícies, sem heurística de nome:
 
 1. propriedades estáticas de `defineAction` e `defineContract` descritas acima, somente
    quando a factory resolve por símbolo a um import de `@softize/opus` ou
    `@softize/opus/core`; alias, namespace e destructuring `const` de namespace funcionam,
    homônimo local não é contrato;
-2. texto estático em filhos e props de uma allowlist de componentes importados diretamente
+2. `label`, `description` e `doc` estáticos de `t.dict` importado de
+   `@softize/opus/schema/zod`; metadata livre não é classificada por nome, declarações dinâmicas
+   reprovam em vez de serem executadas e o dicionário mantém um snapshot imutável das entradas;
+3. texto estático em filhos e props de uma allowlist de componentes importados diretamente
    de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogDescription`,
    `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
    continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.9.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