@softize/opus 22.2.0 → 24.0.0

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

@@ -15,19 +15,30 @@ exemplos leem as variáveis ao vivo; troque o tema do app e a página acompanha.
 
 ```tsx preview
 const SURFACES = [
-  ['background', 'foreground', 'O fundo da página e o texto padrão.'],
-  ['card', 'card-foreground', 'Superfície elevada (Card, painéis).'],
-  ['popover', 'popover-foreground', 'Superfície flutuante (menus, popovers, dialogs).'],
-  ['muted', 'muted-foreground', 'Fundo discreto e texto secundário.'],
-  ['accent', 'accent-foreground', 'Hover e seleção.'],
-  ['secondary', 'secondary-foreground', 'Ação secundária.'],
-  ['primary', 'primary-foreground', 'A ação principal — alto contraste.'],
-  ['destructive', 'destructive-foreground', 'Ação destrutiva e erro.'],
-]
+  ["background", "foreground", "O fundo da página e o texto padrão."],
+  ["card", "card-foreground", "Superfície elevada (Surface, painéis)."],
+  [
+    "popover",
+    "popover-foreground",
+    "Superfície flutuante (menus, popovers, dialogs).",
+  ],
+  ["muted", "muted-foreground", "Fundo discreto e texto secundário."],
+  [
+    "accent",
+    "accent-foreground",
+    "Alias de compatibilidade para hover neutro.",
+  ],
+  ["secondary", "secondary-foreground", "Ação secundária."],
+  ["primary", "primary-foreground", "A ação principal — alto contraste."],
+  ["destructive", "destructive-foreground", "Ação destrutiva e erro."],
+];
 render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
     {SURFACES.map(([token, fg, desc]) => (
-      <div key={token} className="flex items-center gap-4 border-b border-border px-4 py-3 last:border-b-0">
+      <div
+        key={token}
+        className="flex items-center gap-4 border-b border-border px-4 py-3 last:border-b-0"
+      >
         <div
           className="flex h-10 w-28 shrink-0 items-center justify-center rounded-md border border-border text-xs font-medium"
           style={{ backgroundColor: `var(--${token})`, color: `var(--${fg})` }}
@@ -35,15 +46,75 @@ render(
           Texto
         </div>
         <div className="min-w-0">
-          <div className="font-mono text-xs">--{token} · --{fg}</div>
+          <div className="font-mono text-xs">
+            --{token} · --{fg}
+          </div>
           <div className="text-xs text-muted-foreground">{desc}</div>
         </div>
       </div>
     ))}
   </div>,
-)
+);
 ```
 
+### Controles e estados neutros
+
+Canvas, superfície elevada, controle e interação formam uma escala opaca. Um input não muda de
+tom ao sair do canvas e entrar num card, porque `control` representa o resultado final — não uma
+cor translúcida a ser misturada com o ancestral. Da mesma forma, hover, seleção e pressão usam
+papéis diferentes e preservam a mesma ordem comportamental nos dois temas.
+
+```tsx preview
+const NEUTRAL_STATES = [
+  ["control", "Controle em repouso."],
+  ["interaction-hover", "Resposta transitória ao apontador ou foco de item."],
+  ["interaction-selected", "Seleção ou expansão persistente."],
+  ["interaction-pressed", "Pressão transitória de um controle neutro."],
+];
+render(
+  <div className="grid w-full grid-cols-2 gap-2">
+    {NEUTRAL_STATES.map(([token, desc]) => (
+      <div
+        key={token}
+        className="rounded-md border border-border p-3"
+        style={{ backgroundColor: `var(--${token})` }}
+      >
+        <div className="font-mono text-xs">--{token}</div>
+        <div className="mt-1 text-xs text-muted-foreground">{desc}</div>
+      </div>
+    ))}
+  </div>,
+);
+```
+
+### Ajuste de aparência
+
+Os tokens neutros desta seção não são valores fixos: o tema os calcula a partir de quatro eixos,
+declarados separadamente para o modo claro e para o modo escuro. Com os eixos no preset, o
+resultado é o tema padrão. Uma aplicação que oferece preferências de aparência altera os eixos, e
+toda a escala — superfícies, estados, bordas e texto secundário — se move em conjunto, sem perder a
+ordem entre os papéis.
+
+| Eixo                    | Custom property (`light` ou `dark`)      | O que muda                                             | Preset claro | Preset escuro |
+| ----------------------- | ---------------------------------------- | ------------------------------------------------------ | ------------ | ------------- |
+| Intensidade de cor      | `--appearance-<modo>-color-intensity`    | Quanto do matiz `--neutral-hue` aparece nos neutros    | 0            | 0             |
+| Contraste               | `--appearance-<modo>-contrast`           | Distância de hover, seleção, pressão, `muted` e bordas | 0            | 0             |
+| Brilho das superfícies  | `--appearance-<modo>-surface-brightness` | Luminosidade do canvas e das superfícies               | 100          | 50            |
+| Contraste entre camadas | `--appearance-<modo>-layer-contrast`     | Distância entre canvas, controle e superfície elevada  | 0            | 0             |
+
+Cada eixo aceita um inteiro de 0 a 100. Os limites protegem o tema padrão: nenhum valor dessa faixa
+reduz a separação entre os papéis nem o contraste do texto sobre as superfícies em repouso abaixo do
+que o preset oferece. Por isso contraste e contraste entre camadas partem de zero e só aumentam, e o
+texto secundário acompanha as superfícies quando o brilho muda.
+
+A intensidade de cor tinge somente os neutros. `primary`, `destructive` e os contextos `info`,
+`success`, `warning` e `danger` mantêm as próprias cores. O matiz aplicado vem de `--neutral-hue`,
+que a aplicação define junto com a identidade.
+
+Os nomes, os presets e a conversão de valores em custom properties ficam em
+`@softize/opus/ui/appearance`. O passo a passo para aplicar e desfazer um ajuste está em
+[Customização](/ui/customization). A ADR 0044 registra a decisão e os limites.
+
 ## Famílias contextuais
 
 Os tokens `primary`, `secondary` e `destructive` acima permanecem fundações de superfície. A API
@@ -52,7 +123,7 @@ família oferece sólido, foreground, superfície sutil, ênfase e borda. Use as
 `variant`; classes contextuais diretas ficam reservadas à implementação dos primitives.
 
 ```tsx preview
-const CONTEXTS = ['neutral', 'primary', 'info', 'success', 'warning', 'danger']
+const CONTEXTS = ["neutral", "primary", "info", "success", "warning", "danger"];
 render(
   <div className="grid w-full grid-cols-3 gap-2">
     {CONTEXTS.map((context) => (
@@ -69,7 +140,7 @@ render(
       </div>
     ))}
   </div>,
-)
+);
 ```
 
 ## Linhas e foco
@@ -79,15 +150,21 @@ render(
 
 ```tsx preview
 const LINES = [
-  ['border', 'Bordas de contêineres (cards, tabelas, separadores).'],
-  ['input', 'Borda e fundo sutil de campos de formulário.'],
-  ['ring', 'O anel de foco (focus-visible).'],
-]
+  ["border", "Bordas de contêineres (cards, tabelas, separadores)."],
+  ["input", "Borda de campos de formulário; o fundo usa control."],
+  ["ring", "O anel de foco (focus-visible)."],
+];
 render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
     {LINES.map(([token, desc]) => (
-      <div key={token} className="flex items-center gap-4 border-b border-border px-4 py-3 last:border-b-0">
-        <div className="h-10 w-28 shrink-0 rounded-md border-2" style={{ borderColor: `var(--${token})` }} />
+      <div
+        key={token}
+        className="flex items-center gap-4 border-b border-border px-4 py-3 last:border-b-0"
+      >
+        <div
+          className="h-10 w-28 shrink-0 rounded-md border-2"
+          style={{ borderColor: `var(--${token})` }}
+        />
         <div className="min-w-0">
           <div className="font-mono text-xs">--{token}</div>
           <div className="text-xs text-muted-foreground">{desc}</div>
@@ -95,7 +172,7 @@ render(
       </div>
     ))}
   </div>,
-)
+);
 ```
 
 ## Escala de elevação
@@ -107,16 +184,19 @@ render(
 
 ```tsx preview
 const LEVELS = [
-  ['sm', 'Superfície em repouso.'],
-  ['md', 'Flutuante intermediário.'],
-  ['lg', 'Modal ou destaque forte.'],
-]
+  ["sm", "Superfície em repouso."],
+  ["md", "Flutuante intermediário."],
+  ["lg", "Modal ou destaque forte."],
+];
 render(
   <div className="flex flex-wrap gap-8 py-4">
     {LEVELS.map(([level, desc]) => (
       <div key={level} className="flex flex-col items-center gap-3">
         <div
-          className={'flex h-24 w-40 items-center justify-center rounded-xl border border-border bg-card text-xs text-card-foreground shadow-' + level}
+          className={
+            "flex h-24 w-40 items-center justify-center rounded-xl border border-border bg-card text-xs text-card-foreground shadow-" +
+            level
+          }
         >
           Texto
         </div>
@@ -127,7 +207,7 @@ render(
       </div>
     ))}
   </div>,
-)
+);
 ```
 
 ## Escala relativa
@@ -172,7 +252,7 @@ render(
       </p>
     </div>
   </div>,
-)
+);
 ```
 
 Alterar `font-size` em `html` permanece válido quando a aplicação quer recalibrar **toda** a
@@ -190,15 +270,17 @@ o mecanismo para fazer `text-sm` se chamar `text-base`.
 render(
   <div className="flex flex-wrap gap-4">
     {[
-      ['rounded-xs', 'radius − 0.375rem'],
-      ['rounded-sm', 'radius − 0.25rem'],
-      ['rounded-md', 'radius − 0.125rem'],
-      ['rounded-lg', 'radius (0.75rem)'],
-      ['rounded-xl', 'radius + 0.25rem'],
-      ['rounded-2xl', 'radius + 0.5rem'],
+      ["rounded-xs", "radius − 0.375rem"],
+      ["rounded-sm", "radius − 0.25rem"],
+      ["rounded-md", "radius − 0.125rem"],
+      ["rounded-lg", "radius (0.75rem)"],
+      ["rounded-xl", "radius + 0.25rem"],
+      ["rounded-2xl", "radius + 0.5rem"],
     ].map(([cls, calc]) => (
       <div key={cls} className="flex items-center gap-3">
-        <div className={'h-12 w-12 border-2 border-foreground/30 bg-muted ' + cls} />
+        <div
+          className={"h-12 w-12 border-2 border-foreground/30 bg-muted " + cls}
+        />
         <div>
           <div className="font-mono text-xs">{cls}</div>
           <div className="text-xs text-muted-foreground">{calc}</div>
@@ -206,7 +288,7 @@ render(
       </div>
     ))}
   </div>,
-)
+);
 ```
 
 ## Divergências declaradas vs shadcn
@@ -214,10 +296,12 @@ render(
 > Qualquer diferença em relação ao shadcn que não esteja declarada aqui (e no `theme.css`) é uma
 > divergência a sincronizar, conforme a skill `build-opus-ui`.
 
-1. Formato HSL nos tokens (o upstream migrou para oklch), escolhido pela legibilidade; os valores
-   acompanham o upstream, só o formato difere.
-2. Elevação no tema escuro: `--card` e `--popover` ficam acima de `--background` (`10%` contra `3.9%`
-   de luminosidade), para que dialog e card se destaquem de fato da página.
+1. Formato HSL nos tokens (o upstream migrou para oklch), escolhido pela legibilidade.
+2. Hierarquia opaca de superfícies e estados nos dois temas: canvas, card/popover, controle, hover,
+   seleção e pressão têm papéis próprios. No light, o canvas quase branco sustenta superfícies
+   brancas; no dark, cards e popovers permanecem acima do canvas. A ADR 0043 registra os valores e
+   as restrições de composição. A escala neutra é derivada dos eixos de aparência (ADR 0044); no
+   preset, os valores são os calibrados.
 3. Radius mapeado (`xs` a `2xl`) preservando o sentido pré-v4 dos utilitários `rounded-*`. Esse
    trecho derivado permanece monotônico quando a base muda; aplicações que também usam `3xl`
    precisam revisar a transição para esse degrau nativo ao customizar `--radius`.

package/src/ui/docs/registry.tsx

@@ -61,7 +61,6 @@ import dockMd from "./content/dock.md?raw";
 import breadcrumbMd from "./content/breadcrumb.md?raw";
 import buttonMd from "./content/button.md?raw";
 import calendarMd from "./content/calendar.md?raw";
-import cardMd from "./content/card.md?raw";
 import metricCardMd from "./content/metric-card.md?raw";
 import carouselMd from "./content/carousel.md?raw";
 import askMd from "./content/ask.md?raw";
@@ -125,7 +124,7 @@ import actionTriggerMd from "./content/action-trigger.md?raw";
 import actionSearchDialogMd from "./content/action-list-dialog.md?raw";
 import pageMd from "./content/page.md?raw";
 import presentationMd from "./content/presentation.md?raw";
-import contentMd from "./content/content.md?raw";
+import surfaceMd from "./content/surface.md?raw";
 import paneMd from "./content/pane.md?raw";
 import sidebarMd from "./content/sidebar.md?raw";
 import splitMd from "./content/split.md?raw";
@@ -454,9 +453,9 @@ export const UI_SECTIONS: DocSection[] = [
             ),
           },
           {
-            slug: "content",
-            title: "Content",
-            render: pattern("Content", "content", contentMd),
+            slug: "surface",
+            title: "Surface",
+            render: pattern("Surface", "surface", surfaceMd),
           },
           {
             slug: "accordion",
@@ -468,7 +467,6 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Aspect Ratio",
             render: comp("Aspect Ratio", "aspect-ratio", aspectRatioMd),
           },
-          { slug: "card", title: "Card", render: comp("Card", "card", cardMd) },
           {
             slug: "metric-card",
             title: "Metric Card",

package/src/ui/drivers/react.tsx

@@ -51,11 +51,12 @@ import { objectSchemaShape } from '../lib/object-schema.ts'
 
 /**
  * Dicionário estrutural pro resolvedor de `options: { kind: 'dictionary', ref }`:
- * qualquer coisa com `options()` → `{ value, label }`. O `DictType` do `t.dict`
- * satisfaz direto — sem este driver importar o driver de schema.
+ * qualquer coisa com `options()` → `{ value, label, icon? }`. O `DictType` do `t.dict`
+ * satisfaz direto — sem este driver importar o driver de schema. A metadata opcional
+ * continua sendo declarada pelo dicionário; o provider não inventa apresentação.
  */
 export interface DictLike {
-  options(): Array<{ value: string; label: string }>
+  options(): Array<{ value: string; label: string; icon?: string }>
 }
 
 interface OpusContextValue {

package/src/ui/index.ts

@@ -5,7 +5,10 @@
  * Aqui ficam apenas types/contratos compartilhados.
  */
 
-import type { ActionError, Paginated } from '../core/index.ts'
+import type { ActionError, Paginated } from "../core/index.ts";
+
+// Personalização de aparência (ADR 0044): sem React, também disponível em `./ui/appearance`.
+export * from "./appearance.ts";
 
 /**
  * Metadado de descoberta de um componente — cada componente co-localiza um `meta`
@@ -13,18 +16,18 @@ import type { ActionError, Paginated } from '../core/index.ts'
  */
 export interface ComponentMeta {
   /** Nome canônico (kebab), ex.: 'button', 'dropdown-menu'. */
-  name: string
+  name: string;
   /** Origem: descendente do shadcn (forkado) ou nativo do Opus. */
-  ancestry: 'shadcn' | 'opus'
+  ancestry: "shadcn" | "opus";
   /** Quando usar / quando não — guia o agente de design a escolher certo. */
-  whenToUse: string
+  whenToUse: string;
   /** Aviso de retirada no catálogo, com o caminho de migração. */
   deprecated?: {
     /** Alternativa recomendada; aceita `código` inline como `whenToUse`. */
-    alternative: string
+    alternative: string;
     /** Versão em que a retirada começou, quando houver. */
-    since?: string
-  }
+    since?: string;
+  };
 }
 
 /**
@@ -32,23 +35,23 @@ export interface ComponentMeta {
  * shape derivado disto.
  */
 export interface ActionState<TData> {
-  data: TData | undefined
-  error: ActionError | undefined
-  isIdle: boolean
-  isLoading: boolean
-  isSuccess: boolean
-  isError: boolean
+  data: TData | undefined;
+  error: ActionError | undefined;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
 }
 
 export interface ListState<TItem> {
-  items: TItem[]
-  cursor: { next: string | null; prev?: string | null }
-  total: number | undefined
-  error: ActionError | undefined
-  isIdle: boolean
-  isLoading: boolean
-  isSuccess: boolean
-  isError: boolean
+  items: TItem[];
+  cursor: { next: string | null; prev?: string | null };
+  total: number | undefined;
+  error: ActionError | undefined;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
 }
 
 /**
@@ -62,7 +65,7 @@ export function idleAction<T>(): ActionState<T> {
     isLoading: false,
     isSuccess: false,
     isError: false,
-  }
+  };
 }
 
 export function idleLookup<T>(): ListState<T> {
@@ -75,7 +78,7 @@ export function idleLookup<T>(): ListState<T> {
     isLoading: false,
     isSuccess: false,
     isError: false,
-  }
+  };
 }
 
 /**
@@ -83,10 +86,10 @@ export function idleLookup<T>(): ListState<T> {
  */
 export function isPaginated(value: unknown): value is Paginated<unknown> {
   return (
-    typeof value === 'object' &&
+    typeof value === "object" &&
     value !== null &&
-    'items' in value &&
+    "items" in value &&
     Array.isArray((value as { items: unknown }).items) &&
-    'cursor' in value
-  )
+    "cursor" in value
+  );
 }

package/src/ui/meta.ts

@@ -11,11 +11,11 @@ import type { ComponentMeta } from "./index.ts";
 
 /** Todos os metas, chaveados pelo nome canônico (kebab). Fonte única — zero duplicação. */
 export const componentMeta = {
-  content: {
-    name: "content",
+  surface: {
+    name: "surface",
     ancestry: "opus",
     whenToUse:
-      "Organize uma região nomeada dentro de uma página ou de outra superfície. Use as propriedades de Content no caso comum e componha seus slots quando precisar controlar a estrutura. Numa página centrada em uma coleção, `level={1}` faz do Content o heading principal; nas demais, ele vem de PageTitle.",
+      'Delimite e nomeie um trecho da tela: uma região da página, um grupo de campos, um registro, um item de grade ou um bloco clicável. `as` escolhe o elemento (`div`, `section`, `article` ou `fieldset`) e `asChild` entrega a superfície a um botão ou link. `framed` acrescenta a moldura, `elevation="raised"` dá fundo próprio e `layout` escolhe entre ritmo contínuo e faixas com divisores. No caso comum, declare `title`, `description`, `count`, `actions` e `media` na própria Surface; componha SurfaceHeader, SurfaceBody e SurfaceFooter quando precisar controlar a estrutura. Numa página centrada em uma coleção, `level={1}` faz da Surface o heading principal; nas demais, ele vem de PageTitle. Para um modal use Dialog, para um painel lateral use Drawer e para uma coluna de layout use Pane.',
   },
   ask: {
     name: "ask",
@@ -77,17 +77,11 @@ export const componentMeta = {
     whenToUse:
       "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala compartilhada (`xs`…`lg` e os quadrados `icon-*`); `icon` recebe um nó e `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup conectado, espaçado ou dividido.",
   },
-  card: {
-    name: "card",
-    ancestry: "shadcn",
-    whenToUse:
-      "Agrupe conteúdo relacionado em uma superfície delimitada. Use Card diretamente para um bloco simples ou componha cabeçalho, corpo e rodapé quando houver hierarquia e ações. CardContent permanece apenas como alias temporário de compatibilidade.",
-  },
   "metric-card": {
     name: "metric-card",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma medida resumida, como um total ou uma contagem, com rótulo, valor em destaque e descrição opcional. O consumidor calcula e formata os valores. Use `secondaryMetric` para uma segunda leitura da mesma dimensão, exibida como lâmina posterior com rótulo próprio; `context` realça somente o ícone, `action` acrescenta uma ação diretamente relacionada e `loading` substitui rótulo e valor durante a carga. Com `onActivate`, `active` e `activationLabel`, informados juntos, o card vira um controle que aplica o recorte que a medida resume e expõe o estado por `aria-pressed`. Para conteúdo geral ou estrutura livre, use Card.",
+      "Apresente uma medida resumida, como um total ou uma contagem, com rótulo, valor em destaque e descrição opcional. O consumidor calcula e formata os valores. Use `secondaryMetric` para uma segunda leitura da mesma dimensão, exibida como lâmina posterior com rótulo próprio; `context` realça somente o ícone, `action` acrescenta uma ação diretamente relacionada e `loading` substitui rótulo e valor durante a carga. Com `onActivate`, `active` e `activationLabel`, informados juntos, o card vira um controle que aplica o recorte que a medida resume e expõe o estado por `aria-pressed`. Para conteúdo geral ou estrutura livre, use Surface.",
   },
   chat: {
     name: "chat",
@@ -119,12 +113,6 @@ export const componentMeta = {
     whenToUse:
       "Receba texto para envio sem montar uma conversa completa. Enter envia, Shift+Enter quebra a linha e `actions` acrescenta uma faixa para seletores relacionados. O componente é controlado; use Chat quando também precisar de mensagens e estado da conversa.",
   },
-  "content-header": {
-    name: "content-header",
-    ancestry: "opus",
-    whenToUse:
-      'Estruture uma região com título e corpo. No caso comum, declare título, mídia, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `layout="sectioned"` quando o filho controlar o recuo do body, `frameVariant="legend"` para integrar visualmente o header à borda e `as="fieldset"` somente para agrupar campos sob uma legenda nativa. Componha ContentHeader apenas quando precisar controlar a anatomia.',
-  },
   copyable: {
     name: "copyable",
     ancestry: "opus",
@@ -177,7 +165,7 @@ export const componentMeta = {
     name: "separator",
     ancestry: "shadcn",
     whenToUse:
-      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Card, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões com `layout="sectioned"`.',
+      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Surface, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões com `layout="sectioned"`.',
   },
   skeleton: {
     name: "skeleton",
@@ -201,7 +189,7 @@ export const componentMeta = {
     name: "tabs",
     ancestry: "shadcn",
     whenToUse:
-      'Alterne entre painéis relacionados no mesmo nível de navegação. Cada TabsTrigger aponta para um TabsContent pelo mesmo `value`; TabsList controla o tratamento visual e Tabs define orientação, escala, distribuição e moldura. Use `distribution="equal"` para repartir a largura entre seções equivalentes e `framed` para delimitar o conjunto sem criar uma nova superfície.',
+      "Navegue entre painéis relacionados no mesmo nível. Cada TabsListItem aponta para um TabsPanel pelo mesmo `value`; TabsList usa uma linha para indicar a aba ativa, enquanto Tabs define orientação, escala, distribuição e moldura. Use ToggleGroup para escolher valores sem navegar entre painéis.",
   },
   textarea: {
     name: "textarea",
@@ -285,7 +273,7 @@ export const componentMeta = {
     name: "field",
     ancestry: "shadcn",
     whenToUse:
-      'Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado. FieldGroup organiza vários campos; quando o conjunto precisar de título, componha-o dentro de Content com `as="fieldset"`.',
+      'Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado. FieldGroup organiza vários campos; quando o conjunto precisar de título, componha-o dentro de Surface com `as="fieldset"`.',
   },
   "input-otp": {
     name: "input-otp",
@@ -327,19 +315,19 @@ export const componentMeta = {
     name: "split",
     ancestry: "opus",
     whenToUse:
-      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial e mínimo; a anatomia do pane tem página própria. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara apenas dimensão e crescimento; o filho compõe apresentação e rolagem. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
   },
   sidebar: {
     name: "sidebar",
     ancestry: "opus",
     whenToUse:
-      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios são do Pane que a hospeda.",
+      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a coluna e o colapso. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; quando precisar de header, body ou footer visuais, envolva a Sidebar com Surface.",
   },
   pane: {
     name: "pane",
     ancestry: "opus",
     whenToUse:
-      "Estruture a coluna ou faixa encaixada em um Split. PaneHeader nomeia a região e acomoda mídia e ações; ao lado desses slots, também aceita conteúdo livre, como uma busca ou a marca de uma barra lateral. PaneBody rola e PaneFooter mantém à vista o que não pode sair da tela. `layout` escolhe entre regiões seccionadas, com divisores derivados da vizinhança, e o fluxo contínuo. `inset` vale para o pane sem slots; com eles, o recuo pertence a cada região.",
+      "Declare o tamanho de uma região dentro de Split. Pane cuida somente de dimensão, limites e crescimento; o filho decide superfície, organização e rolagem. Use Surface quando a região precisar de header, body, footer, borda ou elevação, e Sidebar quando ela for uma navegação lateral.",
   },
   "scroll-area": {
     name: "scroll-area",
@@ -363,7 +351,7 @@ export const componentMeta = {
     name: "toggle",
     ancestry: "shadcn",
     whenToUse:
-      "Alterne um estado diretamente no contexto atual. ToggleGroup reúne escolhas únicas ou múltiplas e compartilha aparência e escala entre os itens. Para um valor booleano com rótulo em formulário, prefira Switch ou Checkbox.",
+      'Alterne um estado diretamente no contexto atual. ToggleGroup reúne escolhas únicas ou múltiplas com a mesma gramática estrutural de ButtonGroup; `mode="segmented"` mantém alternativas curtas visíveis numa superfície compartilhada, enquanto `variant` trata cada Toggle. Para navegar entre painéis, use Tabs.',
   },
 
   confirm: {
@@ -388,13 +376,13 @@ export const componentMeta = {
     name: "action-form-card",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma FormAction como seção delimitada da página. ActionFormCard combina a estrutura do Card com o comportamento de ActionForm. Para um modal, use ActionFormDialog; sem superfície adicional, use ActionForm.",
+      "Apresente uma FormAction como seção delimitada da página. ActionFormCard combina a estrutura de uma Surface elevada com o comportamento de ActionForm. Para um modal, use ActionFormDialog; sem superfície adicional, use ActionForm.",
   },
   "action-list": {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Content para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Surface para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",
@@ -412,13 +400,13 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "Estruture uma página com cabeçalho, estado e conteúdo na mesma anatomia. Page renderiza o `<main>` com um container centralizado de até 80rem (`max-w-7xl`); PageHeader reúne navegação contextual opcional, título e ações, enquanto PageBody recebe o conteúdo. PageShell pode fornecer navegação e ações conhecidas pela aplicação sem criar uma barra visual. Uma região interna pode fornecer o heading principal com Content. PageActionsTarget fica restrito a workspaces imersivos. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência, por isso informações indispensáveis entram no corpo, como Alert ou texto. Para uma falha parcial, mantenha o estado na seção com DataState; para uma região disponível para criação ou vínculo, use Empty.",
+      "Estruture uma página com cabeçalho, estado e conteúdo na mesma anatomia. Page renderiza o `<main>` com um container centralizado de até 80rem (`max-w-7xl`); PageHeader reúne navegação contextual opcional, título e ações, enquanto PageBody recebe o conteúdo. PageShell pode fornecer navegação e ações conhecidas pela aplicação sem criar uma barra visual. Uma região interna pode fornecer o heading principal com `Surface level={1}`. PageActionsTarget fica restrito a workspaces imersivos. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência, por isso informações indispensáveis entram no corpo, como Alert ou texto. Para uma falha parcial, mantenha o estado na seção com DataState; para uma região disponível para criação ou vínculo, use Empty.",
   },
   presentation: {
     name: "presentation",
     ancestry: "opus",
     whenToUse:
-      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. Em Page de listagem, Content mantém título e ações junto do ActionList; modais usam o header da superfície. Route pode declarar URL, surface e origem do registro para deep links. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector abre um snapshot isolado, enquanto a Lens apresenta o inventário estático projetado no manifest.",
+      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. Em Page de listagem, Surface mantém título e ações junto do ActionList; modais usam o header da superfície. Route pode declarar URL, surface e origem do registro para deep links. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector abre um snapshot isolado, enquanto a Lens apresenta o inventário estático projetado no manifest.",
   },
   router: {
     name: "router",