@softize/opus 12.9.0 → 12.11.0

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

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

@@ -4,12 +4,24 @@
 - Campos, labels, mensagens e invalidações pertencem ao contrato quando são parte da
   operação, não a uma tela isolada.
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
-- `Page` fornece o `<main>`, o container centralizado com teto padrão de `72rem` e o header
-  de página. Alterar `className` apenas quando a superfície tiver uma necessidade real de
-  largura; não reconstruir esse container em cada rota.
-- `ContentHeader` compartilha a composição de título, descrição, metadados e ações entre
-  páginas e seções. `variant` define o destaque visual; `level` preserva separadamente a
-  hierarquia semântica do heading.
+- `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
+  explícita é `Page > PageHeader (PageTitle, PageDescription, PageMeta, PageActions) + PageBody`;
+  `title`, `description`, `meta` e `actions` no próprio `Page` são a abreviação para o caso direto.
+  Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
+  real de largura; não reconstruir esse container em cada rota.
+- `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
+  forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
+  explícita, fica dentro de `PageBody`. O cabeçalho permanece visível. Estados de seção ou coleção
+  continuam em `DataState`, `ActionView`, `ActionList` ou `Alert`; não elevar uma falha parcial a
+  estado da página.
+- `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
+  ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
+  solto. `title`, `description`, `meta` e `actions` no `Content` são a abreviação para o caso
+  direto e não podem ser misturados ao header explícito. `level` preserva a hierarquia semântica
+  do heading.
+- Card, Drawer e Pane nomeiam a região principal como `CardBody`, `DrawerBody` e `PaneBody`.
+  `*Content` permanece reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma
+  estrutura, como `DialogContent`, `PopoverContent` e `TabsContent`.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
 - A fonte raiz pertence ao navegador e à aplicação. Medidas escaláveis usam `rem` ou a escala
   relativa do Tailwind; `px` fica restrito a hairlines e compensações ligadas a essas bordas.
@@ -55,18 +67,23 @@
   valor trunca no trigger e a opção inteira fica na lista. Não dimensionar filtro pelo conteúdo
   nem pela label; o modal usa `w-full`.
 - Catálogo e API efetivos vêm dos exports da versão instalada, não de memória ou exemplo antigo.
+- Em componentes semânticos, `context` responde por que há destaque e `variant` responde como ele
+  aparece. O vocabulário canônico é `neutral | primary | info | success | warning | danger`; as
+  variantes visuais são `solid | subtle | outline | ghost | link`, limitadas por componente.
+  `light`/`dark` são temas, `secondary` não substitui estado neutro e `destructive` é comportamento
+  de action projetado visualmente como `danger`.
 
 ## Dicionários e dimensões
 
 O dicionário declara o papel; a tela só escolhe onde o valor fica. Tabela de decisão aplicada
 por `DictionaryValue` e pelas colunas de `ActionList`:
 
-| Papel declarado | Exemplos | Forma | Variante | Ícone | Tooltip |
-|---|---|---|---|---|---|
-| `classification` | Tipo de cliente, categoria, natureza | Badge | `outline`; ignora `tone` | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
-| `status` | Aberto, resolvido, degradado | Badge | tonal pelo `tone`; `neutral` sem tom; nunca `outline` | idem | idem |
-| `stage` | Prospect, cliente; etapa do funil | Badge | igual a `status` | idem | idem |
-| `plain` ou ausente | Fonte, formato, período | Texto | — | idem | idem |
+| Papel declarado | Exemplos | Forma | Contexto | Variante | Ícone | Tooltip |
+|---|---|---|---|---|---|---|
+| `classification` | Tipo de cliente, categoria, natureza | Badge | `neutral` | `outline`; ignora `context` da entrada | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
+| `status` | Aberto, resolvido, degradado | Badge | pela entrada; `neutral` por padrão | `subtle`; nunca `outline` | idem | idem |
+| `stage` | Prospect, cliente; etapa do funil | Badge | igual a `status` | `subtle` | idem | idem |
+| `plain` ou ausente | Fonte, formato, período | Texto | — | — | idem | idem |
 
 Regras que não dependem da tabela:
 
@@ -88,7 +105,7 @@ export const customerKindDict = t.dict(
   { doc: 'Natureza da parte no cadastro global.', presentation: 'classification' },
 )
 export const customerStageDict = t.dict(
-  { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } },
+  { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } },
   { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
 )
 // contrato:
@@ -112,7 +129,7 @@ cells={{
   ),
   stage: (item) =>
     item.stage === 'customer'
-      ? <Badge variant="secondary">Cliente</Badge>
+      ? <Badge context="neutral" variant="solid">Cliente</Badge>
       : <Badge variant="outline">Prospect</Badge>,
 }}
 
@@ -124,7 +141,13 @@ cells={{
 
 // Tooltip que repete o rótulo; cor como único sinal.
 <Tooltip>
-  <TooltipTrigger><Dot variant="success" /></TooltipTrigger>
+  <TooltipTrigger><Dot context="success" /></TooltipTrigger>
   <TooltipContent>Cliente</TooltipContent>
 </Tooltip>
+
+// Contexto semântico usado como variante: a IA perdeu um eixo da API.
+<Badge variant="success">Concluído</Badge>
+
+// Risco comportamental usado como nome visual.
+<Button variant="destructive">Excluir</Button>
 ```

package/registry/skills/model-opus-dictionary/SKILL.md

@@ -35,7 +35,8 @@ da mesma instância, sem catálogo repetido em enum, opção estática ou format
    - **status** — situação operacional que muda com o tempo;
    - **stage** — etapa de um ciclo ou funil;
    - **plain** — valor que só precisa ser legível (o mesmo efeito de omitir).
-   Por entrada, declarar `tone` somente em status e estágio, `icon` somente com nome existente no
+   Por entrada, declarar `context` somente em status e estágio, usando `neutral`, `info`, `success`,
+   `warning` ou `danger`; `icon` somente com nome existente no
    catálogo `iconPickerIcons`, e `description` somente quando acrescentar algo ao rótulo. `doc`
    continua sendo o entendimento de negócio para manifest e Lens; não é tooltip.
 4. Derivar o schema por `.zod()` e usá-lo em todo contrato que valide o código; não redeclarar a
@@ -68,7 +69,8 @@ contrato ou componente mapeado, regenerar com `opus copy` e executar os checks d
 - Não tratar metadata de dicionário como autorização ou invariante de integridade.
 - Não omitir `presentation` esperando que a tela deduza o papel pelo nome do dicionário; sem
   papel declarado, o valor é texto.
-- Não declarar `tone` em classificação, nem `icon` fora do catálogo, nem `description` que
+- Não declarar `context` em classificação, nem usar o alias legado `tone` em código novo, nem
+  `icon` fora do catálogo, nem `description` que
   repita o rótulo.
 
 ## Recursos

package/registry/skills/model-opus-dictionary/references/evaluations.md

@@ -11,8 +11,9 @@
   interface lê rótulos por `labelFor`/`metaFor`.
 - Execução de apresentação: dado um cadastro com “Pessoa física/Empresa” e “Prospect/Cliente”,
   declarar o primeiro como `classification` com ícones `user` e `building` do catálogo e o segundo
-  como `stage` com `tone` explícito, sem `description` que repita o rótulo; provar que o manifest
-  projeta `presentation` e que `t.dict` rejeita `presentation` ou `tone` fora do vocabulário.
-- Reprova: declarar `tone` em uma classificação, inventar `icon` fora do catálogo, copiar `doc`
+  como `stage` com `context` explícito, sem `description` que repita o rótulo; provar que o manifest
+  projeta `presentation` e `context` e que `t.dict` rejeita valores fora do vocabulário.
+- Reprova: declarar `context` em uma classificação, usar o alias legado `tone` em código novo,
+  inventar `icon` fora do catálogo, copiar `doc`
   para `description` ou deixar `presentation` ausente em um status esperando que a tela infira o
   badge.

package/registry/templates/app/src/App.tsx

@@ -26,7 +26,7 @@ export function App(): React.ReactElement {
             {items.map((t) => (
               <li key={t.id} className="flex items-center justify-between gap-2 text-sm">
                 <span>{t.title}</span>
-                <Badge variant={t.done ? 'default' : 'secondary'}>{t.done ? 'Feita' : 'Aberta'}</Badge>
+                <Badge context={t.done ? 'success' : 'neutral'}>{t.done ? 'Feita' : 'Aberta'}</Badge>
               </li>
             ))}
           </ul>

package/src/core/dictionary.ts

@@ -8,14 +8,20 @@
 
 import { getLogicalType } from './logical-type.ts'
 import type { LogicalTypeMeta } from './types.ts'
+import {
+  DICT_CONTEXTS,
+  isDictContext,
+  type DictContext,
+} from './ui-context.ts'
 
 /** Papel de apresentação declarado no nível do dicionário. */
 export const DICT_PRESENTATIONS = ['classification', 'status', 'stage', 'plain'] as const
 export type DictPresentation = (typeof DICT_PRESENTATIONS)[number]
 
-/** Tom explícito de uma entrada — honrado apenas por status e estágios. */
-export const DICT_TONES = ['neutral', 'info', 'success', 'warning', 'danger'] as const
-export type DictTone = (typeof DICT_TONES)[number]
+/** @deprecated Use `DICT_CONTEXTS` (ADR 0006). */
+export const DICT_TONES = DICT_CONTEXTS
+/** @deprecated Use `DictContext` (ADR 0006). */
+export type DictTone = DictContext
 
 /**
  * Meta de cada chave de um dict. `label` obrigatório; resto livre.
@@ -24,7 +30,7 @@ export type DictTone = (typeof DICT_TONES)[number]
  *   entra/sai) — a fonte rica de consulta rápida; flui pro manifest/Lens e NÃO vira tooltip.
  * - `description` é o texto curto voltado à pessoa: aparece no tooltip do `DictionaryValue`
  *   e como apoio de opção. Não repetir o rótulo — descrição igual ao rótulo não renderiza.
- * - `tone` é o tom tonal do badge de status/estágio; classificação ignora.
+ * - `context` é o contexto semântico do status/estágio; classificação ignora.
  * - `icon` é o identificador estável do catálogo de ícones do Opus (`iconPickerIcons`);
  *   nome fora do catálogo não renderiza ícone.
  * - `color` permanece metadata livre (lida pela Lens); o renderer não a interpreta.
@@ -33,7 +39,9 @@ export interface DictEntryMeta {
   label: string
   doc?: string
   description?: string
-  tone?: DictTone
+  context?: DictContext
+  /** @deprecated Use `context`. Compatibilidade temporária da ADR 0006. */
+  tone?: DictContext
   icon?: string
   color?: string
   order?: number
@@ -44,8 +52,16 @@ export function isDictPresentation(value: unknown): value is DictPresentation {
   return typeof value === 'string' && (DICT_PRESENTATIONS as readonly string[]).includes(value)
 }
 
-export function isDictTone(value: unknown): value is DictTone {
-  return typeof value === 'string' && (DICT_TONES as readonly string[]).includes(value)
+/** @deprecated Use `isDictContext` (ADR 0006). */
+export const isDictTone = isDictContext
+
+/** Normaliza a metadata canônica e seu alias temporário. */
+export function dictionaryEntryContext(entry: DictEntryMeta): DictContext | undefined {
+  return isDictContext(entry.context)
+    ? entry.context
+    : isDictContext(entry.tone)
+      ? entry.tone
+      : undefined
 }
 
 /** Forma normalizada de um dicionário, independente de onde a meta foi lida. */
@@ -92,7 +108,11 @@ export interface DictionaryValuePresentation {
   /** False quando o valor não está no dicionário. */
   known: boolean
   presentation: DictPresentation
-  /** `null` = texto; `'outline'` = classificação; tom = badge tonal de status/estágio. */
+  /** Contexto semântico; `null` quando a apresentação é texto. */
+  context: DictContext | null
+  /** Tratamento visual; `null` quando a apresentação é texto. */
+  variant: 'subtle' | 'outline' | null
+  /** @deprecated Use `context` e `variant`. */
   badge: 'outline' | DictTone | null
   /** Identificador do catálogo, só quando declarado na entrada. */
   icon: string | null
@@ -115,8 +135,8 @@ export function dictionaryDescription(label: string, description: unknown): stri
  * Aplica a tabela de decisão da ADR 0003:
  *
  * | papel            | forma | variante                  |
- * | classification   | badge | outline (ignora `tone`)   |
- * | status / stage   | badge | tonal: `tone` ?? neutral  |
+ * | classification   | badge | neutral + outline            |
+ * | status / stage   | badge | `context` + subtle           |
  * | plain / ausente  | texto | —                         |
  *
  * Ícone só quando declarado; tooltip só quando `description` acrescenta. Valor fora do
@@ -132,20 +152,38 @@ export function presentDictionaryValue(
     ? descriptor.entries[value]
     : undefined
   if (entry === undefined || typeof entry.label !== 'string') {
-    return { value, label: value, known: false, presentation, badge: null, icon: null, description: null }
+    return {
+      value,
+      label: value,
+      known: false,
+      presentation,
+      context: null,
+      variant: null,
+      badge: null,
+      icon: null,
+      description: null,
+    }
   }
-  const badge: DictionaryValuePresentation['badge'] =
+  const context: DictionaryValuePresentation['context'] =
+    presentation === 'classification'
+      ? 'neutral'
+      : presentation === 'status' || presentation === 'stage'
+        ? (dictionaryEntryContext(entry) ?? 'neutral')
+        : null
+  const variant: DictionaryValuePresentation['variant'] =
     presentation === 'classification'
       ? 'outline'
       : presentation === 'status' || presentation === 'stage'
-        ? (isDictTone(entry.tone) ? entry.tone : 'neutral')
+        ? 'subtle'
         : null
   return {
     value,
     label: entry.label,
     known: true,
     presentation,
-    badge,
+    context,
+    variant,
+    badge: variant === 'outline' ? 'outline' : context,
     icon: typeof entry.icon === 'string' && entry.icon.length > 0 ? entry.icon : null,
     description: dictionaryDescription(entry.label, entry.description),
   }

package/src/core/index.ts

@@ -138,12 +138,22 @@ export { normalizeTraceContext } from './trace.ts'
 // `@softize/opus/schema` re-exporta os dois pra manter a API de sempre.
 export { attachLogicalType, getLogicalType } from './logical-type.ts'
 
+// — Contextos semânticos de UI (ADR 0006) ————————————————————————————————————
+export {
+  UI_CONTEXTS,
+  DICT_CONTEXTS,
+  isUiContext,
+  isDictContext,
+} from './ui-context.ts'
+export type { UiContext, DictContext } from './ui-context.ts'
+
 // — Dicionários (apresentação declarada — ADR 0003) ————————————————————————————
 export {
   DICT_PRESENTATIONS,
   DICT_TONES,
   isDictPresentation,
   isDictTone,
+  dictionaryEntryContext,
   dictionaryDescriptor,
   dictionaryDescription,
   presentDictionaryValue,

package/src/core/ui-context.ts

@@ -0,0 +1,29 @@
+/**
+ * Famílias semânticas compartilhadas entre contratos e UI (ADR 0006).
+ *
+ * Contexto responde por que um realce existe; cada componente decide como materializá-lo.
+ * Tema (light/dark), geometria e variante visual são eixos independentes.
+ */
+export const UI_CONTEXTS = [
+  'neutral',
+  'primary',
+  'info',
+  'success',
+  'warning',
+  'danger',
+] as const
+
+export type UiContext = (typeof UI_CONTEXTS)[number]
+
+/** Contextos válidos para estados e estágios de domínio. */
+export const DICT_CONTEXTS = ['neutral', 'info', 'success', 'warning', 'danger'] as const
+
+export type DictContext = (typeof DICT_CONTEXTS)[number]
+
+export function isUiContext(value: unknown): value is UiContext {
+  return typeof value === 'string' && (UI_CONTEXTS as readonly string[]).includes(value)
+}
+
+export function isDictContext(value: unknown): value is DictContext {
+  return typeof value === 'string' && (DICT_CONTEXTS as readonly string[]).includes(value)
+}

package/src/schema/drivers/zod.ts

@@ -36,6 +36,7 @@ import {
   type DictEntryMeta,
   type DictPresentation,
 } from '../../core/dictionary.ts'
+import { DICT_CONTEXTS, isDictContext } from '../../core/ui-context.ts'
 import {
   formatDatetime,
   formatDate,
@@ -656,7 +657,8 @@ function isLogicalType(value: unknown): value is LogicalType<unknown> {
 /**
  * Meta de cada chave de um dict — o tipo mora no core (`@softize/opus/core`, ADR 0003) e é
  * reexportado aqui pra manter a API: `label` obrigatório, `doc` (negócio, manifest/Lens),
- * `description` (tooltip), `tone` (badge tonal de status/estágio), `icon` (catálogo).
+ * `description` (tooltip), `context` (contexto semântico de status/estágio), `icon` (catálogo).
+ * `tone` permanece como alias temporário de compatibilidade.
  */
 export type { DictEntryMeta }
 
@@ -680,7 +682,7 @@ export interface DictType<K extends string, M extends DictEntryMeta> {
    */
   labelFor(key: K, locale?: string): string
   /** Meta completa da chave (label + extras). */
-  metaFor(key: K): M
+  metaFor(key: K): Readonly<M>
   /** Lista pronta pra `<Select options={...} />`: `{ value, ...meta }`. */
   options(): DictOption<K, M>[]
   /** True se `key` está no dict. */
@@ -707,7 +709,7 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
   opts?: DictOpts,
 ): DictType<Extract<keyof M, string>, M[keyof M]> => {
   type K = Extract<keyof M, string>
-  const keys = Object.keys(entries) as K[]
+  const keys = Object.freeze(Object.keys(entries)) as readonly K[]
   if (keys.length === 0) {
     throw new Error('t.dict precisa de pelo menos uma entrada')
   }
@@ -716,29 +718,42 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
       `t.dict: presentation "${String(opts.presentation)}" inválida; use ${DICT_PRESENTATIONS.join(' | ')}`,
     )
   }
-  const tonal = opts?.presentation === 'status' || opts?.presentation === 'stage'
+  const contextual = opts?.presentation === 'status' || opts?.presentation === 'stage'
   for (const key of keys) {
-    const tone = (entries[key] as DictEntryMeta).tone
-    if (tone === undefined) continue
-    if (!isDictTone(tone)) {
-      throw new Error(`t.dict: tone "${String(tone)}" inválido em "${key}"; use ${DICT_TONES.join(' | ')}`)
+    const entry = entries[key] as DictEntryMeta
+    if (entry.context !== undefined && entry.tone !== undefined) {
+      throw new Error(`t.dict: use context ou tone em "${key}", nunca os dois`)
     }
-    if (!tonal) {
+    const context = entry.context ?? entry.tone
+    if (context === undefined) continue
+    const legacy = entry.context === undefined
+    if (!(legacy ? isDictTone(context) : isDictContext(context))) {
+      const values = legacy ? DICT_TONES : DICT_CONTEXTS
+      const field = legacy ? 'tone' : 'context'
+      throw new Error(`t.dict: ${field} "${String(context)}" inválido em "${key}"; use ${values.join(' | ')}`)
+    }
+    if (!contextual) {
       throw new Error(
-        `t.dict: tone em "${key}" exige presentation "status" ou "stage" (classificação usa outline; plain é texto)`,
+        `t.dict: ${legacy ? 'tone' : 'context'} em "${key}" exige presentation "status" ou "stage" (classificação usa outline; plain é texto)`,
       )
     }
   }
+  // O dicionário é declarativo: mantém um snapshot próprio e imutável para que `metaFor`,
+  // a metadata do schema e mutações posteriores no objeto de entrada não alterem a copy
+  // ou a apresentação que foram inventariadas no código-fonte.
+  const stableEntries = Object.freeze(
+    Object.fromEntries(keys.map((key) => [key, Object.freeze({ ...entries[key] })])),
+  ) as unknown as Readonly<M>
   const zodSchema = z.enum(keys as [K, ...K[]])
-  const meta: LogicalTypeMeta = {
+  const meta: LogicalTypeMeta = Object.freeze({
     logicalType: 'dict',
-    params: {
+    params: Object.freeze({
       keys,
-      entries,
+      entries: stableEntries,
       ...(opts?.doc !== undefined ? { doc: opts.doc } : {}),
       ...(opts?.presentation !== undefined ? { presentation: opts.presentation } : {}),
-    },
-  }
+    }),
+  })
   attachLogicalType(zodSchema as unknown as object, meta)
 
   return {
@@ -749,16 +764,16 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
     keys: () => [...keys],
     labelFor: (key, _locale) => {
       // _locale reservado pra i18n futuro; no v1 sempre retorna o label cru.
-      return (entries[key] as M[keyof M]).label
+      return (stableEntries[key] as M[keyof M]).label
     },
-    metaFor: (key) => entries[key] as M[keyof M],
+    metaFor: (key) => stableEntries[key] as M[keyof M],
     options: () =>
       keys.map((k) => ({
-        ...(entries[k] as M[keyof M]),
+        ...(stableEntries[k] as M[keyof M]),
         value: k,
       })) as DictOption<K, M[keyof M]>[],
     has: (key: string): key is K =>
-      Object.prototype.hasOwnProperty.call(entries, key),
+      Object.prototype.hasOwnProperty.call(stableEntries, key),
   }
 }
 

package/src/ui/components/patterns/action-form-card.tsx

@@ -6,22 +6,24 @@
  */
 import {
   Card,
-  CardContent,
+  CardBody,
   CardDescription,
   CardFooter,
   CardHeader,
   CardTitle,
-} from '../primitives/card.tsx'
-import { ActionForm, type ActionFormProps } from './form.tsx'
+} from "../primitives/card.tsx";
+import { ActionForm, type ActionFormProps } from "./form.tsx";
 
-export interface ActionFormCardProps<TInput extends Record<string, unknown>, TData>
-  extends Omit<ActionFormProps<TInput, TData>, 'body' | 'footer'> {
+export interface ActionFormCardProps<
+  TInput extends Record<string, unknown>,
+  TData,
+> extends Omit<ActionFormProps<TInput, TData>, "body" | "footer"> {
   /** Título do header do card. Sem ele, o card começa direto no conteúdo. */
-  title?: string
+  title?: string;
   /** Subtítulo opcional, abaixo do título. */
-  description?: string
+  description?: string;
   /** Classes do Card (a superfície). `className` vai pro <form>. */
-  cardClassName?: string
+  cardClassName?: string;
 }
 
 export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
@@ -35,14 +37,18 @@ export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
       {(title !== undefined || description !== undefined) && (
         <CardHeader>
           {title !== undefined && <CardTitle>{title}</CardTitle>}
-          {description !== undefined && <CardDescription>{description}</CardDescription>}
+          {description !== undefined && (
+            <CardDescription>{description}</CardDescription>
+          )}
         </CardHeader>
       )}
       <ActionForm
         {...rest}
-        body={(fields) => <CardContent>{fields}</CardContent>}
-        footer={(actions) => <CardFooter className="justify-end">{actions}</CardFooter>}
+        body={(fields) => <CardBody>{fields}</CardBody>}
+        footer={(actions) => (
+          <CardFooter className="justify-end">{actions}</CardFooter>
+        )}
       />
     </Card>
-  )
+  );
 }