@softize/opus 23.0.0 → 24.0.1

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

@@ -14,18 +14,14 @@ inicial no modo não controlado; o conteúdo pode ser texto ou ícone.
 Use `pressed` e `onPressedChange` quando o estado pertencer ao consumidor.
 
 ```tsx preview
-const [readOnly, setReadOnly] = useState(true)
+const [readOnly, setReadOnly] = useState(true);
 
 render(
-  <Toggle
-    variant="outline"
-    pressed={readOnly}
-    onPressedChange={setReadOnly}
-  >
+  <Toggle variant="outline" pressed={readOnly} onPressedChange={setReadOnly}>
     <Eye />
     Somente leitura
   </Toggle>,
-)
+);
 ```
 
 ## Variantes e tamanhos
@@ -64,15 +60,15 @@ borda e usa um fundo sutil distinto dela no estado ativo. `size` ajusta a altura
 
 ## Propriedades de Toggle
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `pressed` | `boolean` | | Estado no modo controlado. Use com `onPressedChange`. |
-| `onPressedChange` | `(pressed: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
-| `defaultPressed` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `variant` | `'default' \| 'outline'` | `'default'` | `default` não tem borda e só ganha fundo quando ativo; `outline` mantém a borda. |
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
-| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades. |
-| `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |
+| Propriedade       | Tipo                         | Padrão      | Descrição                                                                                                        |
+| ----------------- | ---------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `pressed`         | `boolean`                    |             | Estado no modo controlado. Use com `onPressedChange`.                                                            |
+| `onPressedChange` | `(pressed: boolean) => void` |             | Chamado a cada alternância, com o novo estado.                                                                   |
+| `defaultPressed`  | `boolean`                    | `false`     | Estado inicial no modo não controlado.                                                                           |
+| `variant`         | `'default' \| 'outline'`     | `'default'` | `default` não tem borda e só ganha fundo quando ativo; `outline` mantém a borda.                                 |
+| `size`            | `'sm' \| 'default' \| 'lg'`  | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
+| `shape`           | `'default' \| 'pill'`        | `'default'` | Geometria do controle; `pill` arredonda as extremidades.                                                         |
+| `disabled`        | `boolean`                    | `false`     | Esmaece e bloqueia o clique, preservando o estado visual.                                                        |
 
 ## ToggleGroup
 
@@ -82,101 +78,157 @@ relacionados. `type="single"` mantém um item ativo; `type="multiple"` aceita v
 ### Escolha única
 
 ```tsx preview
-const [view, setView] = useState('sessions')
+const [view, setView] = useState("sessions");
 
 render(
-  <ToggleGroup type="single" value={view} onValueChange={(v) => v && setView(v)}>
-    <ToggleGroupItem value="overview">Visão geral</ToggleGroupItem>
-    <ToggleGroupItem value="sessions">Sessões</ToggleGroupItem>
-    <ToggleGroupItem value="skills">Habilidades</ToggleGroupItem>
+  <ToggleGroup
+    type="single"
+    value={view}
+    onValueChange={(v) => v && setView(v)}
+  >
+    <Toggle value="overview">Visão geral</Toggle>
+    <Toggle value="sessions">Sessões</Toggle>
+    <Toggle value="skills">Habilidades</Toggle>
   </ToggleGroup>,
-)
+);
 ```
 
 ### Escolha múltipla
 
 ```tsx preview
-const [marks, setMarks] = useState(['bold'])
+const [marks, setMarks] = useState(["bold"]);
 
 render(
   <ToggleGroup type="multiple" value={marks} onValueChange={setMarks}>
-    <ToggleGroupItem value="bold" aria-label="Negrito"><Bold /></ToggleGroupItem>
-    <ToggleGroupItem value="italic" aria-label="Itálico"><Italic /></ToggleGroupItem>
-    <ToggleGroupItem value="underline" aria-label="Sublinhado"><Underline /></ToggleGroupItem>
+    <Toggle value="bold" aria-label="Negrito">
+      <Bold />
+    </Toggle>
+    <Toggle value="italic" aria-label="Itálico">
+      <Italic />
+    </Toggle>
+    <Toggle value="underline" aria-label="Sublinhado">
+      <Underline />
+    </Toggle>
   </ToggleGroup>,
-)
+);
 ```
 
 ### Itens só com ícone e tooltip
 
 Quando o item mostra somente um ícone, mantenha o `aria-label` e acrescente uma dica visual. Envolva o
-`ToggleGroupItem` em `TooltipTrigger asChild`: o item preserva o estado selecionado e seus atributos,
+`Toggle` em `TooltipTrigger asChild`: o controle preserva o estado selecionado e seus atributos,
 e a dica aparece sem criar outro botão. O `TooltipProvider` da raiz do aplicativo continua necessário.
 
 ```tsx preview
-const [align, setAlign] = useState('left')
+const [align, setAlign] = useState("left");
 
 render(
-  <ToggleGroup type="single" value={align} onValueChange={(v) => v && setAlign(v)}>
+  <ToggleGroup
+    type="single"
+    value={align}
+    onValueChange={(v) => v && setAlign(v)}
+  >
     <Tooltip>
       <TooltipTrigger asChild>
-        <ToggleGroupItem value="left" aria-label="Alinhar à esquerda"><AlignLeft /></ToggleGroupItem>
+        <Toggle value="left" aria-label="Alinhar à esquerda">
+          <AlignLeft />
+        </Toggle>
       </TooltipTrigger>
       <TooltipContent>Alinhar à esquerda</TooltipContent>
     </Tooltip>
     <Tooltip>
       <TooltipTrigger asChild>
-        <ToggleGroupItem value="center" aria-label="Centralizar"><AlignCenter /></ToggleGroupItem>
+        <Toggle value="center" aria-label="Centralizar">
+          <AlignCenter />
+        </Toggle>
       </TooltipTrigger>
       <TooltipContent>Centralizar</TooltipContent>
     </Tooltip>
     <Tooltip>
       <TooltipTrigger asChild>
-        <ToggleGroupItem value="right" aria-label="Alinhar à direita"><AlignRight /></ToggleGroupItem>
+        <Toggle value="right" aria-label="Alinhar à direita">
+          <AlignRight />
+        </Toggle>
       </TooltipTrigger>
       <TooltipContent>Alinhar à direita</TooltipContent>
     </Tooltip>
   </ToggleGroup>,
-)
+);
+```
+
+### Relação entre os controles
+
+`mode` segue a mesma gramática de `ButtonGroup`. `connected`, o padrão, une os controles e remove
+bordas internas duplicadas; `spaced` preserva cada controle com um pequeno intervalo; `divided`
+acrescenta divisores entre eles. `variant`, `size` e `shape` definidos no grupo chegam aos controles
+por contexto.
+
+```tsx preview
+<ToggleGroup type="single" variant="outline" defaultValue="call">
+  <Toggle value="call">
+    <Phone /> Telefone
+  </Toggle>
+  <Toggle value="email">
+    <Mail /> E-mail
+  </Toggle>
+  <Toggle value="whatsapp">
+    <MessageCircle /> WhatsApp
+  </Toggle>
+</ToggleGroup>
 ```
 
-### Grupo conectado com borda
+Use `mode="spaced"` quando cada controle precisar preservar sua própria borda e seu próprio raio.
+Use `mode="divided"` quando a separação também precisar ficar explícita por divisores.
 
-`variant`, `size` e `shape` definidos no grupo chegam aos itens por contexto. `spacing` separa os
-itens. Use `variant="outline"` com `spacing={0}` para formar um controle conectado com contorno
-único. A borda pertence aos itens: o grupo remove as bordas internas duplicadas, arredonda apenas
-as extremidades e preserva o contorno quando um item está ativo.
+### Aparência segmentada
+
+Use `mode="segmented"` para escolhas curtas que precisam permanecer visíveis dentro de uma
+superfície compartilhada. O item ativo usa o mesmo fundo de uma superfície elevada; os demais
+permanecem no fundo do grupo. Segmentos inativos vizinhos recebem um divisor sutil; o divisor
+desaparece dos dois lados da seleção. Essa aparência escolhe um valor no contexto atual: para
+navegar entre painéis, use Tabs.
 
 ```tsx preview
-<ToggleGroup type="single" variant="outline" spacing={0} defaultValue="call">
-  <ToggleGroupItem value="call"><Phone /> Telefone</ToggleGroupItem>
-  <ToggleGroupItem value="email"><Mail /> E-mail</ToggleGroupItem>
-  <ToggleGroupItem value="whatsapp"><MessageCircle /> WhatsApp</ToggleGroupItem>
+<ToggleGroup type="single" mode="segmented" defaultValue="sessions">
+  <Toggle value="overview">
+    <LayoutGrid /> Visão geral
+  </Toggle>
+  <Toggle value="sessions">
+    <History /> Sessões
+  </Toggle>
+  <Toggle value="skills">
+    <Settings /> Habilidades
+  </Toggle>
 </ToggleGroup>
 ```
 
-Use um valor maior que zero quando cada item precisar preservar sua própria borda e seu próprio
-raio, sem formar um bloco contínuo.
+`mode` trata a relação visual entre os controles. `variant` continua tratando cada `Toggle`; por
+isso, a composição segmentada recomendada usa a variante padrão. O recuo fica dentro da altura da
+escala de controles: o conjunto mantém `2rem`, `2.25rem` ou `2.5rem` conforme `size`.
+
+### Distribuição e moldura
+
+`distribution="content"`, o padrão, preserva a largura dos rótulos. Use `equal` para dividir toda a
+largura disponível igualmente entre os controles. `framed` acrescenta borda e recuo estrutural sem
+mudar o modo de agrupamento.
 
 ### Propriedades de ToggleGroup
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `type` | `'single' \| 'multiple'` | | Define seleção única (`string`) ou múltipla (`string[]`). |
-| `value` | `string \| string[]` | | Seleção controlada; o tipo acompanha `type`. |
-| `onValueChange` | `(value: string \| string[]) => void` | | Informa a nova seleção. No modo single, uma string vazia representa nenhum item ativo. |
-| `defaultValue` | `string \| string[]` | | Seleção inicial no modo não controlado. |
-| `variant` | `'default' \| 'outline'` | `'default'` | Tratamento visual repassado aos itens. `outline` aplica borda a cada item. |
-| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Tamanho repassado aos itens. |
-| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do grupo e de suas extremidades. |
-| `spacing` | `number` | `0` | Distância entre os itens em unidades de spacing. Com zero, remove bordas internas duplicadas e conecta o grupo. |
-
-### Propriedades de ToggleGroupItem
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `value` | `string` | | Identificador que entra no valor do grupo quando o item é ativado. |
-| `disabled` | `boolean` | `false` | Bloqueia somente este item e preserva seu estado visual. |
-| `variant` | `'default' \| 'outline'` | `'default'` | Tratamento do item quando o grupo não declara `variant`; o valor do grupo prevalece. |
-| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Tamanho do item quando o grupo não declara `size`; o valor do grupo prevalece. |
-| `shape` | `'default' \| 'pill'` | shape do grupo | Geometria deste item; quando informada, prevalece sobre a do grupo. |
+| Propriedade     | Tipo                                                  | Padrão         | Descrição                                                                                             |
+| --------------- | ----------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
+| `type`          | `'single' \| 'multiple'`                              |                | Define seleção única (`string`) ou múltipla (`string[]`).                                             |
+| `value`         | `string \| string[]`                                  |                | Seleção controlada; o tipo acompanha `type`.                                                          |
+| `onValueChange` | `(value: string \| string[]) => void`                 |                | Informa a nova seleção. No modo single, uma string vazia representa nenhum item ativo.                |
+| `defaultValue`  | `string \| string[]`                                  |                | Seleção inicial no modo não controlado.                                                               |
+| `variant`       | `'default' \| 'outline'`                              | `'default'`    | Tratamento visual repassado aos itens. `outline` aplica borda a cada item.                            |
+| `size`          | `'default' \| 'sm' \| 'lg'`                           | `'default'`    | Tamanho repassado aos itens.                                                                          |
+| `shape`         | `'default' \| 'pill'`                                 | `'default'`    | Geometria do grupo e de suas extremidades.                                                            |
+| `mode`          | `'connected' \| 'spaced' \| 'divided' \| 'segmented'` | `'connected'`  | Define como os controles se relacionam; `segmented` cria uma superfície compartilhada para a seleção. |
+| `distribution`  | `'content' \| 'equal'`                                | `'content'`    | Preserva a largura dos rótulos ou reparte igualmente a largura disponível.                            |
+| `orientation`   | `'horizontal' \| 'vertical'`                          | `'horizontal'` | Organiza os controles e os divisores no eixo indicado.                                                |
+| `framed`        | `boolean`                                             | `false`        | Acrescenta borda, raio e recuo ao grupo sem alterar o modo.                                           |
+
+Dentro de `ToggleGroup`, cada `Toggle` exige `value`. O grupo controla o estado selecionado; props
+standalone como `pressed` e `onPressedChange` não participam dessa composição. `disabled`, `variant`,
+No grupo, `variant` e `size` pertencem ao conjunto e chegam a todos os controles. `shape` no item
+pode declarar uma pílula local dentro do grupo.

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

@@ -49,6 +49,7 @@ import tokensMd from "./content/tokens.md?raw";
 import semanticContextMd from "./content/semantic-context.md?raw";
 import communicationMd from "./content/communication.md?raw";
 import customizationMd from "./content/customization.md?raw";
+import compositionsMd from "./content/compositions.md?raw";
 
 // — Componentes —
 import accordionMd from "./content/accordion.md?raw";
@@ -61,7 +62,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 +125,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";
@@ -396,6 +396,11 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Comunicação",
             render: doc(communicationMd),
           },
+          {
+            slug: "compositions",
+            title: "Composições",
+            render: doc(compositionsMd),
+          },
           {
             slug: "customization",
             title: "Customização",
@@ -454,9 +459,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 +473,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",