@softize/opus 12.9.0 → 12.11.0

package/src/ui/docs/content/dictionary-value.md

@@ -9,11 +9,11 @@ aplica os defaults da apresentação declarada. O rótulo está sempre presente
   value="pj"
 />
 <DictionaryValue
-  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
   value="customer"
 />
 <DictionaryValue
-  dict={{ keys: ['open', 'blocked'], entries: { open: { label: 'Aberto', tone: 'warning', icon: 'clock', description: 'Aguarda uma decisão da Fonte.' }, blocked: { label: 'Bloqueado', tone: 'danger' } }, presentation: 'status' }}
+  dict={{ keys: ['open', 'blocked'], entries: { open: { label: 'Aberto', context: 'warning', icon: 'clock', description: 'Aguarda uma decisão da Fonte.' }, blocked: { label: 'Bloqueado', context: 'danger' } }, presentation: 'status' }}
   value="open"
 />
 <DictionaryValue
@@ -39,23 +39,23 @@ export const customerKindDict = t.dict(
 export const customerStageDict = t.dict(
   {
     prospect: { label: 'Prospect', description: 'Relacionamento ainda em prospecção.' },
-    customer: { label: 'Cliente', tone: 'success' },
+    customer: { label: 'Cliente', context: 'success' },
   },
   { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
 )
 ```
 
-| Papel | Quando | Forma | Variante |
+| Papel | Quando | Forma | Contexto e variante |
 |---|---|---|---|
-| `classification` | Tipo, categoria, natureza — uma dimensão estável de comparação. | Badge | `outline`; ignora `tone`. |
-| `status` | Situação operacional que muda com o tempo. | Badge | Tonal pelo `tone` da entrada; `neutral` sem tom. Nunca `outline`. |
+| `classification` | Tipo, categoria, natureza — uma dimensão estável de comparação. | Badge | `neutral` + `outline`; ignora `context`. |
+| `status` | Situação operacional que muda com o tempo. | Badge | Contexto declarado pela entrada + `subtle`; `neutral` quando ausente. |
 | `stage` | Etapa de um ciclo ou funil. | Badge | Igual a `status`. |
 | `plain` ou ausente | Valor que só precisa ser legível. | Texto | — |
 
-## Por entrada: tom, ícone e descrição
+## Por entrada: contexto, ícone e descrição
 
-- `tone` (`neutral` · `info` · `success` · `warning` · `danger`) só existe em status e estágio;
-  `t.dict` rejeita o tom em classificação e em `plain`.
+- `context` (`neutral` · `info` · `success` · `warning` · `danger`) só existe em status e estágio;
+  `t.dict` rejeita o contexto em classificação e em `plain`.
 - `icon` é um nome do catálogo do Opus (`iconPickerIcons`). Nome fora do catálogo não renderiza
   ícone; o renderer não inventa. Vocabulário próprio entra por `icons`.
 - `description` é o texto curto para a pessoa e aparece em tooltip focável. Descrição igual ao
@@ -79,7 +79,7 @@ Os defaults vêm do dicionário; a tela sobrepõe só quando tem um motivo, e so
 
 ```tsx preview
 <DictionaryValue
-  dict={{ keys: ['customer'], entries: { customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+  dict={{ keys: ['customer'], entries: { customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
   value="customer"
   presentation="plain"
 />
@@ -113,6 +113,7 @@ uma sob a outra como texto secundário.
 | `dict` | `DictType \| LogicalTypeMeta \| DictionaryDescriptor` | — | O dicionário (`t.dict`), a meta lida do schema ou um descritor normalizado. |
 | `value` | `string \| null \| undefined` | — | O código. Vazio renderiza `fallback`. |
 | `presentation` | `'classification' \| 'status' \| 'stage' \| 'plain'` | do dicionário | Sobrepõe o papel só nesta ocorrência. |
+| `context` | contexto de `Badge` | pelo dicionário | Sobrepõe o significado semântico e promove texto a badge. |
 | `variant` | variante de `Badge` | pelo papel | Sobrepõe a variante e promove texto a badge. |
 | `icon` | `boolean \| ReactNode` | `true` | `false` esconde o ícone declarado; um nó substitui. |
 | `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Catálogo nome → componente. |

package/src/ui/docs/content/dot.md

@@ -1,16 +1,16 @@
 # Dot
 
-Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `variant`
-seleciona somente a intenção semântica. Quando a cor carrega significado, `label` fornece o nome
+Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `context`
+seleciona o significado e `variant` escolhe ponto sólido ou contornado. Quando a cor reforça significado, `label` fornece o nome
 acessível. Sem `label`, o ponto é decorativo.
 
 ```tsx preview
 <div className="flex items-center gap-4">
-  <Dot variant="success" label="Ativo" />
-  <Dot variant="warning" label="Atenção" />
-  <Dot variant="destructive" label="Falhou" />
-  <Dot variant="info" label="Publicado" />
-  <Dot variant="secondary" aria-hidden />
+  <Dot context="success" label="Ativo" />
+  <Dot context="warning" label="Atenção" />
+  <Dot context="danger" label="Falhou" />
+  <Dot context="info" label="Publicado" />
+  <Dot context="neutral" aria-hidden />
 </div>
 ```
 

package/src/ui/docs/content/drawer.md

@@ -14,7 +14,9 @@ side='right' desliza da borda direita. ESC, clique no overlay e o X fecham — s
       <DrawerTitle>criarTicket</DrawerTitle>
       <DrawerDescription>Ação · domínio Suporte</DrawerDescription>
     </DrawerHeader>
-    <div className="px-4 text-sm text-muted-foreground">Campos, entrada/saída, arquivo…</div>
+    <DrawerBody className="text-sm text-muted-foreground">
+      Campos, entrada/saída, arquivo…
+    </DrawerBody>
   </DrawerContent>
 </Drawer>
 ```
@@ -32,10 +34,10 @@ side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; Dr
     <DrawerHeader>
       <DrawerTitle>Editar workspace</DrawerTitle>
     </DrawerHeader>
-    <div className="space-y-2 px-4">
+    <DrawerBody className="space-y-2">
       <Label htmlFor="ws-nome">Nome</Label>
       <Input id="ws-nome" defaultValue="Empresa X" />
-    </div>
+    </DrawerBody>
     <DrawerFooter>
       <DrawerClose asChild>
         <Button variant="ghost" size="sm">Cancelar</Button>
@@ -52,4 +54,5 @@ side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; Dr
 |---|---|---|---|
 | `DrawerContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel desliza. |
 | `DrawerContent.showCloseButton` | `boolean` | `true` | Mostra o X de fechar no canto. Desligue pra painel que exige ação explícita. |
+| `DrawerBody` | `HTMLAttributes<HTMLDivElement>` | Região flexível e rolável | Corpo principal entre header e footer. |
 | `Drawer.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra abrir/fechar por código (ex.: detalhe de um item selecionado). |

package/src/ui/docs/content/field.md

@@ -1,6 +1,6 @@
 ## Campo vertical
 
-A composição base: FieldLabel (htmlFor↔id), o controle e FieldDescription como ajuda — empilhados, com o respiro do Field.
+A composição base: FieldLabel (htmlFor↔id), o controle e FieldDescription como ajuda — empilhados, com o respiro do Field. O rótulo usa a mesma hierarquia compacta de `DetailField`; quando o campo é inválido, muda explicitamente para o tom destrutivo.
 
 ```tsx preview col md
 <Field>

package/src/ui/docs/content/input-group.md

@@ -60,7 +60,7 @@ Com InputGroupTextarea a moldura cresce; align=block-end empilha um rodapé de a
       <Sparkles />
       Título gerado pela IA
     </InputGroupText>
-    <InputGroupButton size="sm" variant="default" className="ml-auto" aria-label="Enviar brief">
+    <InputGroupButton size="sm" context="primary" variant="solid" className="ml-auto" aria-label="Enviar brief">
       Enviar
       <ArrowUp />
     </InputGroupButton>
@@ -74,5 +74,6 @@ Com InputGroupTextarea a moldura cresce; align=block-end empilha um rodapé de a
 |---|---|---|---|
 | `align` (InputGroupAddon) | `'inline-start' \| 'inline-end' \| 'block-start' \| 'block-end'` | `'inline-start'` | Onde o addon ancora: inline nas laterais; block empilha (vira coluna) acima ou abaixo — block exige a moldura alta de um InputGroupTextarea. |
 | `size` (InputGroupButton) | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | Tamanho do botão embutido. As variantes icon-* são quadradas, pra um botão só de ícone. |
-| `variant` (InputGroupButton) | `'default' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link'` | `'ghost'` | Intenção do botão (herda do Button). O padrão ghost some na moldura; use default pra a ação primária. |
+| `context` (InputGroupButton) | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | Significado semântico herdado do Button. |
+| `variant` (InputGroupButton) | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'` | Tratamento visual herdado do Button. O padrão ghost some na moldura; use `solid` para dar ênfase à ação. |
 | `placeholder / defaultValue / value` (InputGroupInput, InputGroupTextarea) | `string` | | Props nativas do <input>/<textarea> repassadas ao controle. Controle como faria com Input/Textarea (value + onChange). |

package/src/ui/docs/content/item.md

@@ -1,18 +1,24 @@
 ## Básico
 
-A composição completa: ItemMedia à esquerda, ItemContent (ItemTitle + ItemDescription) ocupando o meio e ItemActions à direita. variant=outline desenha a borda.
+A composição completa usa `ItemMedia` à esquerda, `ItemHeader` (`ItemTitle` +
+`ItemDescription`) no meio e `ItemActions` à direita. A mídia acompanha a altura útil do header,
+mantendo ícone, imagem ou avatar centralizado. `variant="outline"` desenha a borda.
 
 ```tsx preview col
 <Item variant="outline">
   <ItemMedia variant="icon">
     <FolderGit2 />
   </ItemMedia>
-  <ItemContent>
+  <ItemHeader>
     <ItemTitle>empresa-x-api</ItemTitle>
-    <ItemDescription>Repositório do backend do workspace Empresa X.</ItemDescription>
-  </ItemContent>
+    <ItemDescription>
+      Repositório do backend do workspace Empresa X.
+    </ItemDescription>
+  </ItemHeader>
   <ItemActions>
-    <Button size="sm" variant="outline">Abrir</Button>
+    <Button size="sm" variant="outline">
+      Abrir
+    </Button>
   </ItemActions>
 </Item>
 ```
@@ -27,12 +33,12 @@ A composição completa: ItemMedia à esquerda, ItemContent (ItemTitle + ItemDes
     <ItemMedia variant="icon">
       <GitBranch />
     </ItemMedia>
-    <ItemContent>
+    <ItemHeader>
       <ItemTitle>empresa-x-web</ItemTitle>
       <ItemDescription>Front do workspace Empresa X.</ItemDescription>
-    </ItemContent>
+    </ItemHeader>
     <ItemActions>
-      <Badge variant="success">sincronizado</Badge>
+      <Badge context="success">Sincronizado</Badge>
     </ItemActions>
   </Item>
   <ItemSeparator />
@@ -40,12 +46,12 @@ A composição completa: ItemMedia à esquerda, ItemContent (ItemTitle + ItemDes
     <ItemMedia variant="icon">
       <GitBranch />
     </ItemMedia>
-    <ItemContent>
+    <ItemHeader>
       <ItemTitle>empresa-x-api</ItemTitle>
       <ItemDescription>Backend do workspace Empresa X.</ItemDescription>
-    </ItemContent>
+    </ItemHeader>
     <ItemActions>
-      <Badge variant="warning">3 sessões</Badge>
+      <Badge context="warning">3 sessões</Badge>
     </ItemActions>
   </Item>
 </ItemGroup>
@@ -63,10 +69,12 @@ asChild funde o Item num <a> — a linha inteira vira alvo (hover no fundo). siz
         <AvatarFallback>AL</AvatarFallback>
       </Avatar>
     </ItemMedia>
-    <ItemContent>
+    <ItemHeader>
       <ItemTitle>Empresa X</ItemTitle>
-      <ItemDescription>Workspace com 2 repositórios e 3 agentes.</ItemDescription>
-    </ItemContent>
+      <ItemDescription>
+        Workspace com 2 repositórios e 3 agentes.
+      </ItemDescription>
+    </ItemHeader>
     <ItemActions>
       <ChevronRight className="size-4 text-muted-foreground" />
     </ItemActions>
@@ -74,12 +82,30 @@ asChild funde o Item num <a> — a linha inteira vira alvo (hover no fundo). siz
 </Item>
 ```
 
+## Corpo complementar
+
+Use `ItemBody` quando a linha também apresenta um valor ou controle que não pertence ao título,
+à descrição nem às ações.
+
+```tsx preview col
+<Item variant="outline">
+  <ItemHeader>
+    <ItemTitle>Nome</ItemTitle>
+    <ItemDescription>Como você aparece para as outras pessoas.</ItemDescription>
+  </ItemHeader>
+  <ItemBody>João</ItemBody>
+</Item>
+```
+
+`ItemContent` permanece exportado somente para compatibilidade durante a versão 12. Código novo
+usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
+
 ## Props
 
-| Prop | Tipo | Default | Descrição |
-|---|---|---|---|
-| `variant` (ItemGroup) | `'plain' \| 'framed'` | `'plain'` | `framed` aplica moldura e superfície; `plain` mantém a composição livre. Os divisores são explícitos nos dois modos. |
-| `variant` (Item) | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha — default transparente, outline com borda, muted levemente tingido. |
-| `size` (Item) | `'default' \| 'sm'` | `'default'` | O respiro interno — sm aperta o padding pra listas densas. |
-| `asChild` (Item) | `boolean` | `false` | Funde o Item no filho (ex.: <a> ou <button>) — a linha inteira vira o alvo. |
-| `variant` (ItemMedia) | `'default' \| 'icon' \| 'image'` | `'default'` | A moldura da mídia — icon dá caixa quadrada com borda; image recorta a imagem; default sem moldura. |
+| Prop                  | Tipo                                | Default     | Descrição                                                                                                                               |
+| --------------------- | ----------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant` (ItemGroup) | `'plain' \| 'framed'`               | `'plain'`   | `framed` aplica moldura e superfície; `plain` mantém a composição livre. Os divisores são explícitos nos dois modos.                    |
+| `variant` (Item)      | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha — default transparente, outline com borda, muted levemente tingido.                                                    |
+| `size` (Item)         | `'default' \| 'sm'`                 | `'default'` | O respiro interno — sm aperta o padding pra listas densas.                                                                              |
+| `asChild` (Item)      | `boolean`                           | `false`     | Funde o Item no filho (ex.: <a> ou <button>) — a linha inteira vira o alvo.                                                             |
+| `variant` (ItemMedia) | `'default' \| 'icon' \| 'image'`    | `'default'` | A moldura da mídia — `icon` tem largura estável e acompanha a altura do header; `image` recorta a imagem; `default` não adiciona fundo. |

package/src/ui/docs/content/menu.md

@@ -1,6 +1,7 @@
 ## Menu de ações
 
-Ícone à esquerda, atalho à direita (MenuShortcut), separador antes da zona perigosa e variant destructive na ação que destrói.
+Ícone à esquerda, atalho à direita (MenuShortcut), separador antes da zona perigosa e
+`context="danger"` na ação que destrói.
 
 ```tsx preview
 <Menu>
@@ -11,7 +12,7 @@
     <MenuItem><Pencil /> Editar <MenuShortcut>⌘E</MenuShortcut></MenuItem>
     <MenuItem><Copy /> Duplicar</MenuItem>
     <MenuSeparator />
-    <MenuItem variant="destructive"><Trash2 /> Excluir</MenuItem>
+    <MenuItem context="danger"><Trash2 /> Excluir</MenuItem>
   </MenuContent>
 </Menu>
 ```
@@ -44,7 +45,7 @@ render(
         <MenuItem><Pencil /> Renomear</MenuItem>
         <MenuItem><Copy /> Duplicar</MenuItem>
         <MenuSeparator />
-        <MenuItem variant="destructive"><Trash2 /> Excluir</MenuItem>
+        <MenuItem context="danger"><Trash2 /> Excluir</MenuItem>
       </MenuContent>
     </Menu>
   </div>,
@@ -107,7 +108,7 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 
 | Prop | Tipo | Default | Descrição |
 |---|---|---|---|
-| `MenuItem.variant` | `'default' \| 'destructive'` | `'default'` | destructive tonaliza texto e foco em vermelho — só pra ação que destrói. |
+| `MenuItem.context` | `'neutral' \| 'danger'` | `'neutral'` | `danger` sinaliza uma consequência perigosa. |
 | `MenuItem.inset` | `boolean` | | Recuo à esquerda pra alinhar item sem ícone com os que têm. |
 | `MenuContent.align / sideOffset` | `'start' \| 'center' \| 'end' / number` | `'center' / 4` | Alinhamento e distância em relação ao gatilho (Radix). |
 | `MenuCheckboxItem.checked / onCheckedChange` | `boolean / (checked: boolean) => void` | | Estado do liga/desliga — controlado pelo consumidor. |

package/src/ui/docs/content/metric-card.md

@@ -0,0 +1,41 @@
+MetricCard apresenta uma medida resumida com hierarquia e espaçamento consistentes. Passe o
+valor já calculado e formatado; busca de dados, recorte e regras de negócio permanecem no
+consumidor.
+
+```tsx preview col
+<MetricCard
+  label="Total de cadastros"
+  value="286.317"
+  description="Prospects e clientes no cadastro global."
+/>
+```
+
+## Com ícone e ação
+
+O ícone identifica visualmente a natureza da medida e é decorativo. `context="warning"` realça
+somente o ícone; a superfície continua neutra. Use `action` apenas para uma ação diretamente
+relacionada à medida. Um controle que explica o rótulo, como um tooltip, pertence a `labelAction`.
+
+```tsx preview col
+<MetricCard
+  label="Credencial"
+  value="Ausente"
+  description="Reconecte para autorizar novamente o acesso."
+  icon={<KeyRound />}
+  context="warning"
+  action={
+    <Button size="sm" variant="outline">
+      Reconectar
+    </Button>
+  }
+/>
+```
+
+## Carregamento
+
+`loading` preserva a geometria do card com placeholders e marca a superfície como ocupada para
+tecnologias assistivas. O contêiner da coleção continua responsável pela mensagem de carregamento.
+
+```tsx preview col
+<MetricCard loading />
+```

package/src/ui/docs/content/page-state.md

@@ -0,0 +1,45 @@
+## Estado integral da página
+
+Use `PageState` quando carregamento, falha ou ausência substituírem todo o conteúdo principal. Na
+forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
+explícita, coloque-o dentro de `PageBody`. O cabeçalho continua visível e o estado recebe composição,
+altura e semântica acessível consistentes.
+
+```tsx preview col
+<Page title="Relatório">
+  <PageState
+    status="error"
+    title="Não foi possível carregar o relatório"
+    description="Tente novamente. Se o problema continuar, volte mais tarde."
+    action={<Button variant="outline">Tentar novamente</Button>}
+  />
+</Page>
+```
+
+`loading` centraliza o `Spinner`; `error` compõe `Alert`; `empty` compõe `Empty`; e `ready` entrega
+os filhos sem acrescentar uma superfície.
+
+```tsx preview col
+<Page title="Relatórios">
+  <PageState
+    status="empty"
+    title="Nenhum relatório"
+    description="Crie o primeiro relatório para começar."
+    action={<Button>Novo relatório</Button>}
+  />
+</Page>
+```
+
+Não use `PageState` para uma falha parcial. Se outra parte da página continua utilizável, mantenha o
+estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert`.
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `status` | `'loading' \| 'error' \| 'empty' \| 'ready'` | | Estado integral do conteúdo. |
+| `title` | `ReactNode` | Texto seguro por estado | Situação reconhecível pela pessoa. |
+| `description` | `ReactNode` | | Impacto ou próximo passo aplicável. |
+| `icon` | `ReactNode` | Alerta no erro | Ícone decorativo do estado. |
+| `action` | `ReactNode` | | Recuperação, seleção ou criação aplicável. |
+| `children` | `ReactNode` | | Conteúdo renderizado somente em `ready`. |

package/src/ui/docs/content/page.md

@@ -1,11 +1,26 @@
 ## Esqueleto de página
 
 Use `Page` para manter título, contexto, ações e conteúdo no mesmo ritmo visual nas telas do
-back-office. As ações ficam à direita e acompanham a base do conjunto formado pelo título e pela
-descrição. O container é centralizado e ocupa a largura disponível até `72rem` (`max-w-6xl`). Use
+back-office. Em larguras amplas, as ações ficam no extremo oposto e acompanham a base do conjunto
+formado pelo título e pela descrição; em larguras estreitas, passam para uma linha abaixo do
+contexto. O container é centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). Use
 `className` somente quando a composição pedir explicitamente outro teto ou largura total. A área
 abaixo do cabeçalho permanece livre para tabelas, cards ou outras composições.
 
+A forma curta é o padrão para páginas comuns. Ela cria internamente `PageHeader` e `PageBody`;
+portanto, não produz uma estrutura visual ou semântica diferente da forma explícita.
+
+`Page` é o esqueleto de páginas e recursos delimitados. Ele também pode ocupar o painel principal
+de um shell com sidebar; a navegação lateral não exige remover o teto nem reconstruir o cabeçalho.
+Uma navegação contextual para outra página pode ocupar `actions`, e tabs ficam reservados a
+recortes da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell
+próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes da superfície.
+
+Quando carregamento, falha ou ausência substituírem toda a área de conteúdo, use `PageState`. Na
+forma curta ele pode ser escrito como filho direto, pois `Page` cria o `PageBody`; na composição
+explícita, coloque-o dentro de `PageBody`. `Page` não recebe flags de dados: uma página pode agregar
+fontes independentes e uma falha parcial não deve ocultar as demais seções.
+
 ```tsx preview col
 render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
@@ -27,13 +42,36 @@ render(
 )
 ```
 
+## Composição explícita
+
+Use os slots quando a página precisar compor o header diretamente. Não misture propriedades da
+forma curta com `PageHeader` ou `PageBody`.
+
+```tsx preview col
+render(
+  <Page>
+    <PageHeader>
+      <PageTitle>Workspaces</PageTitle>
+      <PageMeta>3</PageMeta>
+      <PageDescription>Ambientes compartilhados pela equipe.</PageDescription>
+      <PageActions><Button><Plus /> Novo workspace</Button></PageActions>
+    </PageHeader>
+    <PageBody>
+      <div className="rounded-lg border border-dashed border-border p-10 text-center">
+        O conteúdo da página.
+      </div>
+    </PageBody>
+  </Page>,
+)
+```
+
 ## Props
 
-| Prop | Tipo | Default | Descrição |
-|---|---|---|---|
-| `title` | `string` | | O h1 da página. |
-| `count` | `number` | | Total de itens ao lado do título (mono, esmaecido). |
-| `description` | `ReactNode` | | Linha de contexto sob o título (ex.: "N no total · X ativos"). |
-| `actions` | `ReactNode` | | Ações à direita do cabeçalho, alinhadas à base do título e da descrição. |
-| `className` | `string` | `max-w-6xl` | Classes do container para substituir o teto padrão de `72rem`. |
-| `children` | `ReactNode` | | O conteúdo — espaçamento e diagramação são seus. |
+| Prop          | Tipo        | Default     | Descrição                                                                                       |
+| ------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
+| `title`       | `string`    |             | O h1 da página.                                                                                 |
+| `count`       | `number`    |             | Total de itens ao lado do título (mono, esmaecido).                                             |
+| `description` | `ReactNode` |             | Linha de contexto sob o título (ex.: "N no total · X ativos").                                  |
+| `actions`     | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho; em telas estreitas, ficam abaixo do contexto. |
+| `className`   | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
+| `children`    | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |

package/src/ui/docs/content/semantic-context.md

@@ -0,0 +1,63 @@
+---
+title: Contexto & Variante
+---
+
+# Contexto & Variante
+
+Componentes semânticos separam significado de aparência. `context` responde por que o elemento
+recebe destaque; `variant` escolhe como esse significado aparece. Essa ordem evita que nomes como
+`success`, `warning` ou `danger` sejam tratados como decoração local.
+
+## Contextos
+
+| Contexto | Uso |
+| --- | --- |
+| `neutral` | Estado normal, inativo ou sem julgamento positivo ou 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 ainda não é uma falha. |
+| `danger` | Falha, impedimento ou consequência perigosa. |
+
+`light` e `dark` são temas, não contextos. `secondary` descreve hierarquia de ação em APIs antigas;
+um estado sem destaque usa `neutral`. `destructive` continua sendo uma propriedade comportamental
+de actions e confirmações; sua projeção visual usa `danger`.
+
+## Variantes
+
+`solid`, `subtle`, `outline`, `ghost` e `link` descrevem somente tratamento visual. Cada componente
+aceita o subconjunto coerente com seu papel.
+
+```tsx preview col
+<div className="flex flex-wrap gap-2">
+  <Badge context="success" variant="solid">Concluído</Badge>
+  <Badge context="success" variant="subtle">Concluído</Badge>
+  <Badge context="success" variant="outline">Concluído</Badge>
+</div>
+<div className="flex flex-wrap gap-2">
+  <Button context="primary" variant="solid">Salvar</Button>
+  <Button context="neutral" variant="outline">Voltar</Button>
+  <Button context="danger" variant="ghost">Excluir</Button>
+</div>
+```
+
+## Dicionários
+
+Status e estágios declaram `context` na entrada. A tela usa `DictionaryValue` ou `ActionList` e não
+escolhe a aparência novamente.
+
+```ts
+const status = t.dict(
+  {
+    running: { label: 'Em andamento', context: 'info' },
+    completed: { label: 'Concluído', context: 'success' },
+    failed: { label: 'Falhou', context: 'danger' },
+  },
+  { presentation: 'status' },
+)
+```
+
+## Compatibilidade
+
+`tone` em dicionários e variantes semânticas antigas continuam aceitos durante a migração. Código
+novo usa `context`; não misture o contrato antigo e o novo na mesma ocorrência.

package/src/ui/docs/content/sidebar.md

@@ -9,13 +9,13 @@ render(
       <Pane initialSize={32} minSize={20} inset="none">
         <Sidebar divider={false} className="w-full">
           <PaneHeader className="px-4 py-3 text-sm font-semibold">Projeto</PaneHeader>
-          <PaneContent>
+          <PaneBody>
             <SidebarNav
               groups={[{ label: 'Design', items: [{ id: 'preview', label: 'Preview' }, { id: 'code', label: 'Código' }] }]}
               activeId="preview"
               onSelect={() => {}}
             />
-          </PaneContent>
+          </PaneBody>
           <PaneFooter><span className="text-xs text-muted-foreground">Configurações</span></PaneFooter>
         </Sidebar>
       </Pane>
@@ -27,7 +27,7 @@ render(
 
 ## Colapso
 
-`collapsed` pertence à própria `Sidebar`; `SidebarItem`, `SidebarNav` e `ShellNav` adaptam-se automaticamente para botões `size-9` centralizados, ícones e tooltips. `PaneHeader`, `PaneContent` e `PaneFooter` são os slots do pane: a aplicação mantém a identidade e ações que lhe pertencem sem atribuí-las artificialmente à sidebar.
+`collapsed` pertence à própria `Sidebar`; `SidebarItem`, `SidebarNav` e `ShellNav` adaptam-se automaticamente para botões `size-9` centralizados, ícones e tooltips. `PaneHeader`, `PaneBody` e `PaneFooter` são os slots do pane: a aplicação mantém a identidade e ações que lhe pertencem sem atribuí-las artificialmente à sidebar.
 
 `SidebarItem` também é a linha de árvores de navegação. `actions` e o controle formado por
 `onToggle`/`expanded` são irmãos do botão principal, portanto menus e chevrons não criam
@@ -53,7 +53,7 @@ do peso médio e da cor atenuada, não de reduzir legibilidade.
 ```tsx
 <Sidebar collapsed={collapsed}>
   <PaneHeader><MySidebarHeader onToggle={() => setCollapsed(!collapsed)} /></PaneHeader>
-  <PaneContent><SidebarNav groups={groups} activeId={active} onSelect={go} /></PaneContent>
+  <PaneBody><SidebarNav groups={groups} activeId={active} onSelect={go} /></PaneBody>
   <PaneFooter><UserMenu /></PaneFooter>
 </Sidebar>
 ```

package/src/ui/docs/content/skeleton.md

@@ -22,10 +22,10 @@ O esqueleto reproduz o layout final do card — título, descrição, conteúdo
     <Skeleton className="h-5 w-40" />
     <Skeleton className="h-4 w-56" />
   </CardHeader>
-  <CardContent className="space-y-2">
+  <CardBody className="space-y-2">
     <Skeleton className="h-4 w-full" />
     <Skeleton className="h-4 w-3/4" />
-  </CardContent>
+  </CardBody>
   <CardFooter className="gap-2">
     <Skeleton className="h-8 w-28" />
     <Skeleton className="h-8 w-24" />

package/src/ui/docs/content/table.md

@@ -17,19 +17,19 @@ A Table vem SEM borda externa — só as divisórias de linha (a última o Table
     <TableRow>
       <TableCell className="font-medium">Importar pedidos da transportadora</TableCell>
       <TableCell>developer</TableCell>
-      <TableCell><Badge variant="info">Em sessão</Badge></TableCell>
+      <TableCell><Badge context="info">Em sessão</Badge></TableCell>
       <TableCell className="text-right">42 min</TableCell>
     </TableRow>
     <TableRow>
       <TableCell className="font-medium">Revisar contrato de rastreio</TableCell>
       <TableCell>reviewer</TableCell>
-      <TableCell><Badge variant="warning">Aguardando revisor</Badge></TableCell>
+      <TableCell><Badge context="warning">Aguardando revisor</Badge></TableCell>
       <TableCell className="text-right">18 min</TableCell>
     </TableRow>
     <TableRow>
       <TableCell className="font-medium">Ajustar microcopy do painel</TableCell>
       <TableCell>designer</TableCell>
-      <TableCell><Badge variant="success">Concluída</Badge></TableCell>
+      <TableCell><Badge context="success">Concluída</Badge></TableCell>
       <TableCell className="text-right">7 min</TableCell>
     </TableRow>
   </TableBody>

package/src/ui/docs/content/tokens.md

@@ -43,6 +43,34 @@ render(
 )
 ```
 
+## Famílias contextuais
+
+Os tokens `primary`, `secondary` e `destructive` acima permanecem fundações de superfície. A API
+dos componentes usa famílias contextuais para separar significado de tratamento visual: cada
+família oferece sólido, foreground, superfície sutil, ênfase e borda. Use as props `context` e
+`variant`; classes contextuais diretas ficam reservadas à implementação dos primitives.
+
+```tsx preview
+const CONTEXTS = ['neutral', 'primary', 'info', 'success', 'warning', 'danger']
+render(
+  <div className="grid w-full gap-2 sm:grid-cols-2 lg:grid-cols-3">
+    {CONTEXTS.map((context) => (
+      <div
+        key={context}
+        className="rounded-md border px-3 py-2 text-sm"
+        style={{
+          backgroundColor: `var(--context-${context}-subtle)`,
+          borderColor: `var(--context-${context}-border)`,
+          color: `var(--context-${context}-emphasis)`,
+        }}
+      >
+        {context}
+      </div>
+    ))}
+  </div>,
+)
+```
+
 ## Linhas e foco
 
 > Bordas e o anel de foco também são tokens — nada de cinza hardcoded. A aresta de superfície