@softize/opus 12.10.0 → 12.11.0

package/src/ui/components/primitives/metric-card.tsx

@@ -0,0 +1,133 @@
+import * as React from 'react'
+import type { UiContext } from '../../../core/ui-context.ts'
+import { cn } from '../../lib/cn.ts'
+import { Card } from './card.tsx'
+import { Skeleton } from './skeleton.tsx'
+
+/** @deprecated Use `MetricCardContext`. */
+export type MetricCardTone = 'default' | 'warning'
+export type MetricCardContext = Exclude<UiContext, 'primary'>
+
+const iconContextClasses: Record<MetricCardContext, string> = {
+  neutral: 'bg-context-neutral-subtle text-context-neutral-emphasis',
+  info: 'bg-context-info-subtle text-context-info-emphasis',
+  success: 'bg-context-success-subtle text-context-success-emphasis',
+  warning: 'bg-context-warning-subtle text-context-warning-emphasis',
+  danger: 'bg-context-danger-subtle text-context-danger-emphasis',
+}
+
+interface MetricCardBaseProps extends Omit<React.ComponentProps<typeof Card>, 'children'> {
+  /** Controle complementar exibido ao lado do rótulo, como uma explicação em tooltip. */
+  labelAction?: React.ReactNode
+  /** Contexto que explica recorte, proporção ou significado do valor. */
+  description?: React.ReactNode
+  /** Ícone decorativo que identifica a natureza da medida. */
+  icon?: React.ReactNode
+  /** Contexto semântico do ícone; não altera a superfície do card. */
+  context?: MetricCardContext
+  /** @deprecated Use `context`. Compatibilidade temporária da ADR 0006. */
+  tone?: MetricCardTone
+  /** Ação relacionada diretamente à medida. */
+  action?: React.ReactNode
+}
+
+export type MetricCardProps = MetricCardBaseProps &
+  (
+    | {
+        /** Nome curto da medida apresentada. */
+        label: React.ReactNode
+        /** Valor já formatado pelo consumidor. */
+        value: React.ReactNode
+        loading?: false
+      }
+    | {
+        /** O rótulo pode ser omitido porque o placeholder ocupa toda a composição. */
+        label?: React.ReactNode
+        /** O valor ainda não está disponível durante o carregamento. */
+        value?: React.ReactNode
+        /** Substitui o conteúdo por placeholders preservando a geometria do card. */
+        loading: true
+      }
+  )
+
+/**
+ * MetricCard apresenta uma medida resumida. Formatação, cálculo e carregamento dos dados
+ * continuam sob responsabilidade do consumidor; o componente padroniza apenas a composição.
+ */
+export function MetricCard({
+  label,
+  labelAction,
+  value,
+  description,
+  icon,
+  context,
+  tone,
+  action,
+  loading = false,
+  className,
+  ...props
+}: MetricCardProps): React.ReactElement {
+  if (context !== undefined && tone !== undefined) {
+    throw new Error('MetricCard não permite combinar context com tone legado.')
+  }
+  const hasIcon = icon !== undefined && icon !== null
+  const resolvedContext = context ?? (tone === 'warning' ? 'warning' : 'neutral')
+
+  return (
+    <Card
+      data-slot="metric-card"
+      aria-busy={loading || undefined}
+      className={cn('min-w-0 p-4', className)}
+      {...props}
+    >
+      {loading ? (
+        <div className="space-y-3">
+          <Skeleton className="h-4 w-28" />
+          <Skeleton className="h-8 w-20" />
+          <Skeleton className="h-3 w-full" />
+        </div>
+      ) : (
+        <>
+          <div className="flex items-start justify-between gap-3">
+            <div className="flex min-w-0 items-center gap-1.5">
+              <div data-slot="metric-card-label" className="min-w-0 truncate text-sm font-medium text-muted-foreground">
+                {label}
+              </div>
+              {labelAction !== undefined && (
+                <div data-slot="metric-card-label-action" className="shrink-0">
+                  {labelAction}
+                </div>
+              )}
+            </div>
+            {hasIcon && (
+              <span
+                data-slot="metric-card-icon"
+                data-context={resolvedContext}
+                aria-hidden="true"
+                className={cn(
+                  'flex size-8 shrink-0 items-center justify-center rounded-md [&_svg]:size-4',
+                  iconContextClasses[resolvedContext],
+                )}
+              >
+                {icon}
+              </span>
+            )}
+          </div>
+          <div data-slot="metric-card-value" className="mt-3 text-2xl font-semibold tracking-tight tabular-nums">
+            {value}
+          </div>
+          {description !== undefined && (
+            <div data-slot="metric-card-description" className="mt-1 text-xs text-muted-foreground">
+              {description}
+            </div>
+          )}
+          {action !== undefined && (
+            <div data-slot="metric-card-action" className="mt-3">
+              {action}
+            </div>
+          )}
+        </>
+      )}
+    </Card>
+  )
+}

package/src/ui/components/primitives/table.tsx

@@ -78,7 +78,7 @@ function TableHead({ className, ...props }: React.ComponentProps<"th">) {
     <th
       data-slot="table-head"
       className={cn(
-        "h-10 px-2 text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
+        "h-10 px-3 text-left align-middle font-medium whitespace-nowrap text-muted-foreground [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
         className
       )}
       {...props}
@@ -91,7 +91,7 @@ function TableCell({ className, ...props }: React.ComponentProps<"td">) {
     <td
       data-slot="table-cell"
       className={cn(
-        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
+        "px-3 py-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
         className
       )}
       {...props}

package/src/ui/docs/DocBrowser.tsx

@@ -15,7 +15,7 @@
 import { useEffect } from 'react'
 import { DOC_SECTIONS, type DocSection, type DocEntry } from './registry'
 import { Pane, Split } from '../components/patterns/split.tsx'
-import { PaneContent, Sidebar, SidebarNav, type SidebarNavGroup } from '../components/patterns/sidebar.tsx'
+import { PaneBody, Sidebar, SidebarNav, type SidebarNavGroup } from '../components/patterns/sidebar.tsx'
 import { navigate, usePathname } from '../router.ts'
 
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
@@ -95,14 +95,14 @@ export function DocBrowser({
     <Split className="h-full">
       <Pane inset="none" className="w-56">
         <Sidebar className="w-full">
-          <PaneContent>
+          <PaneBody>
             <SidebarNav
               groups={navGroups}
               activeId={page?.slug}
               navLabel="Navegação da documentação"
               onSelect={(slug) => go(`${basePath}/${slug}`)}
             />
-          </PaneContent>
+          </PaneBody>
         </Sidebar>
       </Pane>
       <Pane key={page?.slug} grow inset="none" className="overflow-y-auto">

package/src/ui/docs/changelog.tsx

@@ -54,7 +54,7 @@ export function ChangelogView({ source }: { source: string }): React.ReactElemen
             <div className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
               <h2 className="text-xl font-semibold tracking-tight">{v.version}</h2>
               {v.date !== undefined && <span className="text-sm text-muted-foreground">{v.date}</span>}
-              {v.breaking !== undefined && <Badge variant="destructive">Breaking</Badge>}
+              {v.breaking !== undefined && <Badge context="danger" variant="solid">Breaking</Badge>}
             </div>
             {v.body.length > 0 && (
               <div className="mt-3">

package/src/ui/docs/content/action-form-card.md

@@ -20,5 +20,5 @@ faixa de modal). Pra estruturar uma seção da página como painel. O título é
 |---|---|---|---|
 | `title` | `string` | | Título do header (com divisor embaixo). Sem ele, o card começa direto no corpo. |
 | `description` | `string` | | Subtítulo opcional, abaixo do título. |
-| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | `— (iguais ao ActionForm)` | | O resto é o ActionForm — o card injeta o conteúdo (CardContent) e o rodapé (CardFooter) por baixo. |
+| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | `— (iguais ao ActionForm)` | | O resto é o ActionForm — o card injeta o corpo (CardBody) e o rodapé (CardFooter) por baixo. |
 | `cardClassName` | `string` | | Classes da SUPERFÍCIE do card (ex.: largura). `className` vai pro `<form>`. |

package/src/ui/docs/content/alert-dialog.md

@@ -38,15 +38,15 @@ Dialog, **não fecha clicando fora** — exige uma escolha.
 ## A estrutura e o botão destrutivo
 
 `AlertDialogHeader` (media/título/descrição) + `AlertDialogFooter` (as ações).
-`variant="destructive"` no `AlertDialogAction` (ele herda variant/size do Button) pinta o
-confirmar de vermelho. Uma confirmação destrutiva **binária** é só
-`dialog.confirm({ variant: 'destructive' })` — o exemplo abaixo é só pra mostrar a
-composição e onde o `variant` entra:
+`context="danger"` no `AlertDialogAction` (ele herda contexto, variante e tamanho do Button)
+comunica que a confirmação é perigosa. Uma confirmação destrutiva **binária** é só
+`dialog.confirm({ context: 'danger' })` — o exemplo abaixo é só para mostrar a composição e
+onde o `context` entra:
 
 ```tsx preview
 <AlertDialog>
   <AlertDialogTrigger asChild>
-    <Button variant="destructive">Excluir repositório</Button>
+    <Button context="danger">Excluir repositório</Button>
   </AlertDialogTrigger>
   <AlertDialogContent>
     <AlertDialogHeader>
@@ -57,7 +57,7 @@ composição e onde o `variant` entra:
     </AlertDialogHeader>
     <AlertDialogFooter>
       <AlertDialogCancel>Cancelar</AlertDialogCancel>
-      <AlertDialogAction variant="destructive">Excluir</AlertDialogAction>
+      <AlertDialogAction context="danger">Excluir</AlertDialogAction>
     </AlertDialogFooter>
   </AlertDialogContent>
 </AlertDialog>
@@ -69,5 +69,5 @@ composição e onde o `variant` entra:
 |---|---|---|---|
 | `open` (AlertDialog) | `boolean` | | Estado de aberto no modo controlado — pareie com onOpenChange. No padrão, o Trigger cuida disso. |
 | `onOpenChange` (AlertDialog) | `(open: boolean) => void` | | Chamado quando o diálogo abre ou fecha (Trigger, Cancel, Action ou Esc). |
-| `variant` (AlertDialogAction) | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Intenção do botão de confirmar (herdada do Button) — destructive pra ação perigosa. |
-| `variant` (AlertDialogCancel) | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'ghost'` | Intenção do botão de cancelar (herdada do Button). |
+| `context` (Action/Cancel) | `'neutral' \| 'primary' \| 'danger'` | `primary` / `neutral` | Significado semântico herdado do Button. |
+| `variant` (Action/Cancel) | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `solid` / `ghost` | Tratamento visual herdado do Button. |

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

@@ -5,19 +5,19 @@ Quase todo alert é ícone + título + uma frase — então isso é UMA linha: `
 ```tsx preview col
 <Alert icon={<Info />} title="Opus 2.8.0" description="Este workspace usa a versão pinada em opus.json." />
 <Alert
-  variant="destructive"
+  context="danger"
   icon={<CircleAlert />}
   title="Sessão encerrada"
   description="O agente parou antes de concluir. Veja o detalhe no log da sessão."
 />
 <Alert
-  variant="success"
+  context="success"
   icon={<CircleCheck />}
   title="Skill publicada"
   description="Os agentes do workspace já enxergam a nova versão."
 />
 <Alert
-  variant="warning"
+  context="warning"
   icon={<CircleAlert />}
   title="Revisão necessária"
   description="Confira os dados antes de continuar."
@@ -26,51 +26,75 @@ Quase todo alert é ícone + título + uma frase — então isso é UMA linha: `
 
 ## Só a frase
 
-Título é opcional — o aviso de uma linha dispensa. `destructive` e `success` mantêm superfície tonalizada + borda (divergência da casa: o shadcn rebaixou destructive pra `bg-card`, nós preservamos o realce).
+Título é opcional — o aviso de uma linha dispensa. O contexto continua visível por superfície,
+borda e texto; o conteúdo comunica o significado sem depender somente da cor.
 
 ```tsx preview col
 <Alert description="Nenhuma sessão aberta neste repositório." />
-<Alert variant="success" icon={<CircleCheck />} description="Workspace Empresa X sincronizado." />
+<Alert context="success" icon={<CircleCheck />} description="Workspace Empresa X sincronizado." />
 ```
 
-## Ícone é opcional
+## Mídia é opcional
 
-Sem `icon` o alert é bloco comum; com ele, vira grid de duas colunas e o conteúdo se alinha ao lado. O ícone da prop recebe o slot `alert-icon` e um realce tonal coerente com a variante. A composição legada com um SVG direto continua abrindo a coluna do ícone. Texto solto como filho também vale (`<Alert>Sincronizado.</Alert>`) — cai no slot de descrição sozinho.
+Sem `icon` o alert mantém somente a coluna de texto. Com ele, a forma curta materializa
+`AlertMedia` à esquerda e `AlertHeader` à direita. A mídia tem largura estável e acompanha a
+altura útil do header; com título e descrição de uma linha, a moldura termina junto do texto,
+sem sobra inferior. Texto solto como filho também vale (`<Alert>Sincronizado.</Alert>`) e se torna
+uma descrição.
 
 ```tsx preview col
 <Alert title="Sem provider próprio" description="As conversas usam o padrão do sistema." />
-<Alert variant="success">Workspace Empresa X sincronizado.</Alert>
+<Alert context="success">Workspace Empresa X sincronizado.</Alert>
 ```
 
 ## Composição (conteúdo rico)
 
-Quando a descrição tem mais que uma frase — parágrafos, lista, um botão — componha: `AlertTitle` e `AlertDescription` seguem exportados, e o espaço entre BLOCOS filhos vem de graça.
+Quando a mensagem precisa de conteúdo rico, componha os slots da família. `AlertMedia`,
+`AlertHeader` e `AlertActions` são filhos diretos de `Alert`; `AlertTitle` e
+`AlertDescription` pertencem ao header.
 
 ```tsx preview col
-<Alert variant="destructive" icon={<CircleAlert />}>
-  <AlertTitle>Não deu pra publicar</AlertTitle>
-  <AlertDescription>
-    <p>O registry recusou a versão 3.0.0 — ela já existe.</p>
-    <p>Suba o patch e tente de novo.</p>
-  </AlertDescription>
+<Alert context="danger">
+  <AlertMedia>
+    <CircleAlert />
+  </AlertMedia>
+  <AlertHeader>
+    <AlertTitle>Não deu pra publicar</AlertTitle>
+    <AlertDescription>
+      <p>O registry recusou a versão 3.0.0 — ela já existe.</p>
+      <p>Suba o patch e tente de novo.</p>
+    </AlertDescription>
+  </AlertHeader>
+  <AlertActions>
+    <Button size="sm" variant="outline">
+      Tentar novamente
+    </Button>
+  </AlertActions>
 </Alert>
 ```
 
 Os dois modos convivem: com `title`/`description` preenchidos, `children` entra DEPOIS da frase — é onde vai a ação.
 
 ```tsx preview col
-<Alert icon={<CircleAlert />} title="Sessão presa" description="O ambiente não subiu no tempo esperado.">
-  <Button size="sm" variant="outline">Reiniciar</Button>
+<Alert
+  icon={<CircleAlert />}
+  title="Sessão presa"
+  description="O ambiente não subiu no tempo esperado."
+>
+  <Button size="sm" variant="outline">
+    Reiniciar
+  </Button>
 </Alert>
 ```
 
 ## Props
 
-| Prop | Tipo | Default | Descrição |
-|---|---|---|---|
-| `title` | `React.ReactNode` | | Título do alert (a forma curta). Não é o atributo `title` do HTML — esse é tooltip nativo, banido na casa, e o componente não o aceita. |
-| `description` | `React.ReactNode` | | A frase. Sozinha, dispensa título. |
-| `icon` | `React.ReactNode` | | Ícone à esquerda; liga o layout de duas colunas e recebe realce tonal no slot `alert-icon`. Decorativo — quem nomeia é o título. |
-| `variant` | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | O tom da mensagem e do realce do ícone. |
-| `children` | `React.ReactNode` | | Composição (`AlertTitle`/`AlertDescription`), texto cru, ou — junto da forma curta — o que vem depois da frase. |
-| `style` | `React.CSSProperties` | | Ajuste excepcional das medidas internas; com `icon`, pode sobrescrever as colunas e os espaçamentos padrão. |
+| Prop          | Tipo                                                        | Default     | Descrição                                                                                                                               |
+| ------------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `React.ReactNode`                                           |             | Título do alert (a forma curta). Não é o atributo `title` do HTML — esse é tooltip nativo, banido na casa, e o componente não o aceita. |
+| `description` | `React.ReactNode`                                           |             | A frase. Sozinha, dispensa título.                                                                                                      |
+| `icon`        | `React.ReactNode`                                           |             | Ícone à esquerda; materializa `AlertMedia` com realce tonal. Decorativo — quem nomeia é o título.                                       |
+| `context`     | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado da mensagem e do realce do ícone.                                                                                         |
+| `variant`     | `'subtle' \| 'outline'`                                     | `'subtle'`  | O tratamento visual aplicado ao contexto.                                                                                               |
+| `children`    | `React.ReactNode`                                           |             | Composição explícita, texto cru ou, junto da forma curta, ações exibidas após a mensagem.                                               |
+| `style`       | `React.CSSProperties`                                       |             | Ajuste excepcional da raiz; medidas escaláveis usam `rem`.                                                                              |

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

@@ -1,27 +1,25 @@
-## Intenção
+## Contexto e variante
 
-As quatro variantes do shadcn: categoria, papel, alerta. Badge é não-interativo — pra clique, use
-Button.
+Badge é não-interativo — para clique, use Button. `context` comunica o significado; `variant`
+escolhe entre preenchimento sólido, superfície sutil ou contorno.
 
 ```tsx preview
-<Badge>Agente</Badge>
-<Badge variant="secondary">Skill</Badge>
-<Badge variant="outline">Monorepo</Badge>
-<Badge variant="destructive">Arquivado</Badge>
+<Badge context="neutral">Agente</Badge>
+<Badge context="neutral" variant="outline">Monorepo</Badge>
+<Badge context="danger" variant="solid">Arquivado</Badge>
 ```
 
-## Tons de status da casa
+## Contextos de status
 
-success/warning/info/danger (fill tingido + borda translúcida) — convenção da casa pra estado
-semântico, igual ao KindBadge do Maestro. Não-interativos. `danger` é o tom tonal da família;
-`destructive` continua sólido, pra alerta e ação. Valor de dicionário com papel declarado usa
-`DictionaryValue`, que escolhe o tom pela metadata em vez de repetir esta escolha em cada tela.
+`success`, `warning`, `info` e `danger` usam `subtle` por padrão. Valor de dicionário com papel
+declarado usa `DictionaryValue`, que escolhe o contexto pela metadata em vez de repetir esta
+decisão em cada tela.
 
 ```tsx preview
-<Badge variant="success">Ativa</Badge>
-<Badge variant="warning">Aguardando revisor</Badge>
-<Badge variant="info">Em sessão</Badge>
-<Badge variant="danger">Bloqueada</Badge>
+<Badge context="success">Ativa</Badge>
+<Badge context="warning">Aguardando revisor</Badge>
+<Badge context="info">Em sessão</Badge>
+<Badge context="danger">Bloqueada</Badge>
 ```
 
 ## Com ícone
@@ -29,7 +27,7 @@ semântico, igual ao KindBadge do Maestro. Não-interativos. `danger` é o tom t
 Um svg filho ganha size-3 automaticamente — bom pra reforçar o estado sem crescer o rótulo.
 
 ```tsx preview
-<Badge variant="success"><CircleCheck /> Regressão verde</Badge>
+<Badge context="success"><CircleCheck /> Regressão verde</Badge>
 ```
 
 ## Como link (asChild)
@@ -38,7 +36,7 @@ asChild renderiza o filho (Radix Slot) — um `<a>` com cara de badge, com hover
 variantes.
 
 ```tsx preview
-<Badge asChild variant="secondary">
+<Badge asChild context="neutral" variant="solid">
   <a href="#" onClick={(e) => e.preventDefault()}>Empresa X</a>
 </Badge>
 ```
@@ -47,5 +45,6 @@ variantes.
 
 | Prop | Tipo | Default | Descrição |
 |---|---|---|---|
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning' \| 'info' \| 'danger'` | `'default'` | Intenção (default/secondary/destructive/outline) ou tom de status da casa (success/warning/info/danger). |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado ou destaque contextual. |
+| `variant` | `'solid' \| 'subtle' \| 'outline'` | `'subtle'` | O tratamento visual aplicado ao contexto. |
 | `asChild` | `boolean` | `false` | Renderiza como o filho (Radix Slot) em vez de `<span>` — ex.: um `<a>` com cara de badge. |

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

@@ -1,15 +1,17 @@
-## Variantes
+## Contexto e variante
 
-variant é intenção, não decoração: default pra ação principal (uma por tela), destructive só
-quando destrói de verdade.
+`context` declara a hierarquia ou o risco da ação; `variant` escolhe o tratamento visual. Use
+`primary` para a ação principal, `neutral` para ações de apoio e `danger` quando a ação tiver uma
+consequência perigosa. `default`, `secondary` e `destructive` permanecem apenas como aliases de
+compatibilidade.
 
 ```tsx preview
 <Button>Criar workspace</Button>
-<Button variant="secondary">Duplicar</Button>
-<Button variant="outline">Ver prévia</Button>
-<Button variant="ghost">Cancelar</Button>
-<Button variant="destructive">Excluir</Button>
-<Button variant="link">Ver documentação</Button>
+<Button context="neutral" variant="solid">Duplicar</Button>
+<Button context="neutral" variant="outline">Ver prévia</Button>
+<Button context="neutral" variant="ghost">Cancelar</Button>
+<Button context="danger" variant="solid">Excluir</Button>
+<Button context="primary" variant="link">Ver documentação</Button>
 ```
 
 ## Tamanhos
@@ -53,7 +55,8 @@ buttonVariants serve pro caso sem filho único.
 
 | Prop | Tipo | Default | Descrição |
 |---|---|---|---|
-| `variant` | `'default' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link'` | `'default'` | A intenção da ação — define cor e peso visual. |
+| `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | A hierarquia ou o risco comunicado pela ação. |
+| `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'solid'` | O tratamento visual aplicado ao contexto. |
 | `size` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | O tamanho. Os icon* são quadrados (2.25/2/1.5rem) para botões só de ícone, com `aria-label`. |
 | `asChild` | `boolean` | `false` | Renderiza como o filho (Radix Slot) em vez de `<button>` — pra âncoras e afins. |
 | `busy` | `boolean` | `false` | Ação em andamento (depois do clique): mostra Spinner + desabilita. Não é "carregando" de conteúdo (que é Spinner/Skeleton num nível de página). |

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

@@ -18,9 +18,9 @@ Pra painel com estrutura: cada slot é dono do próprio padding (como o Dialog).
     <CardTitle>Empresa X</CardTitle>
     <CardDescription>2 repositórios · 3 agentes vinculados.</CardDescription>
   </CardHeader>
-  <CardContent>
+  <CardBody>
     <p className="text-sm text-muted-foreground">Última sessão concluída há 2 horas.</p>
-  </CardContent>
+  </CardBody>
   <CardFooter className="gap-2">
     <Button size="sm">Abrir sessão</Button>
     <Button size="sm" variant="outline">Ver repositórios</Button>
@@ -38,11 +38,11 @@ Pra painel com estrutura: cada slot é dono do próprio padding (como o Dialog).
     <CardTitle>Skill code-style</CardTitle>
     <CardDescription>Padrão softize de código e microcopy.</CardDescription>
   </CardHeader>
-  <CardContent>
+  <CardBody>
     <p className="text-sm text-muted-foreground">Vinculada a 4 agentes neste workspace.</p>
-  </CardContent>
+  </CardBody>
   <CardFooter className="justify-between border-t">
-    <Badge variant="success">Publicada</Badge>
+    <Badge context="success">Publicada</Badge>
     <Button size="sm" variant="outline">Editar skill</Button>
   </CardFooter>
 </Card>

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

@@ -0,0 +1,44 @@
+## Região de conteúdo
+
+Use `Content` para dar título e estrutura a uma região dentro de `PageBody`, `CardBody`,
+`DialogBody` ou outra superfície. Ele renderiza uma `section` ligada ao próprio título e mantém o
+espaçamento entre header e body. `ContentHeader` pertence sempre a essa estrutura; não o use solto.
+
+No caso comum, prefira o shorthand:
+
+```tsx preview col
+render(
+  <Content
+    title="Dispositivos conectados"
+    description="Sessões com acesso à sua conta."
+    actions={<Button variant="outline">Encerrar outras sessões</Button>}
+  >
+    <div className="rounded-lg border border-border p-4">MacBook Pro · ativo agora</div>
+  </Content>,
+)
+```
+
+## Composição explícita
+
+Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
+`ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
+uma descrição, um metadado e uma região de ações.
+
+```tsx preview col
+render(
+  <Content level={2}>
+    <ContentHeader>
+      <ContentTitle>Dispositivos conectados</ContentTitle>
+      <ContentMeta>3</ContentMeta>
+      <ContentDescription>Sessões com acesso à sua conta.</ContentDescription>
+      <ContentActions><Button variant="outline">Atualizar</Button></ContentActions>
+    </ContentHeader>
+    <ContentBody>
+      <div className="rounded-lg border border-border p-4">MacBook Pro · ativo agora</div>
+    </ContentBody>
+  </Content>,
+)
+```
+
+As duas formas geram os mesmos elementos, estilos e `data-slot`. `opus check` reprova slots fora
+do pai correto, filhos estruturais indiretos e a mistura de shorthand com composição explícita.

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

@@ -59,7 +59,7 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 // Slots: só o que a tela pede.
 <Card>
   <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
-  <CardContent>…</CardContent>
+  <CardBody>…</CardBody>
 </Card>
 
 // asChild: o filho VIRA o botão (sem forkar estilo).
@@ -110,7 +110,7 @@ const [open, setOpen] = useState(false)
 > do botão, a seta do tooltip — é identidade da casa, igual em todo projeto.
 
 ```tsx preview
-<Badge variant="success">Cabe nas alavancas</Badge>
+<Badge context="success">Cabe nas alavancas</Badge>
 ```
 
 Se uma necessidade real não cabe nas alavancas (tokens · className · slots/asChild · props ·

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

@@ -9,7 +9,7 @@ para entrada e validação; use DetailField quando a pessoa apenas consulta um v
     label="Estágio"
     value={
       <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="prospect"
       />
     }
@@ -39,7 +39,10 @@ significado no domínio. `0` e `false` seguem como valores. Ver `EmptyValue`.
 
 `variant="framed"` adiciona a superfície e a borda externa. `dividers` desenha apenas as
 divisórias internas; as duas opções são independentes e podem ser combinadas. `orientation`
-define se a chave fica sobre o valor ou ao lado dele.
+define se a chave fica sobre o valor ou ao lado dele. Na orientação horizontal, todos os valores
+começam depois da mesma coluna de rótulo, com largura padrão de `7rem`. Quando a superfície exigir
+mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
+`className="[--detail-label-width:9rem]"`.
 
 ```tsx preview col
 <DetailGroup columns={2} orientation="horizontal" variant="framed" dividers>

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

@@ -33,7 +33,7 @@ showCloseButton={false} esconde o X: o usuário decide pelos botões — pra con
 ```tsx preview
 <Dialog>
   <DialogTrigger asChild>
-    <Button variant="destructive">Excluir sessão</Button>
+    <Button context="danger">Excluir sessão</Button>
   </DialogTrigger>
   <DialogContent showCloseButton={false}>
     <DialogHeader>
@@ -45,7 +45,7 @@ showCloseButton={false} esconde o X: o usuário decide pelos botões — pra con
         <Button variant="ghost" size="sm">Cancelar</Button>
       </DialogClose>
       <DialogClose asChild>
-        <Button variant="destructive" size="sm">Excluir</Button>
+        <Button context="danger" size="sm">Excluir</Button>
       </DialogClose>
     </DialogFooter>
   </DialogContent>