@softize/opus 18.5.0 → 20.0.0

package/src/ui/docs/content/scroll-area.md

@@ -1,26 +1,28 @@
 ## Lista de altura fixa
 
-Dê a altura ao ScrollArea (h-48) e ponha o conteúdo dentro — a barra vertical já vem por padrão, sem precisar de ScrollBar.
+Use `ScrollArea` quando um bloco precisa manter a própria altura e rolar o conteúdo que passar dela.
+Dê a altura ao `ScrollArea`, como `h-48`, e coloque o conteúdo dentro. A barra vertical já vem
+incluída; não é preciso acrescentar `ScrollBar`.
 
 ```tsx preview col
-const sessions = [
-  { id: 'empresa-x-1842', title: 'Migrar billing para o novo schema', agent: 'developer' },
-  { id: 'empresa-x-1839', title: 'Revisar handoff do checkout', agent: 'reviewer' },
-  { id: 'empresa-x-1835', title: 'Redesenhar o painel de rotas', agent: 'designer' },
-  { id: 'empresa-x-1830', title: 'Corrigir flaky no teste de webhook', agent: 'developer' },
-  { id: 'empresa-x-1827', title: 'Vincular skill clean-code ao agente', agent: 'reviewer' },
-  { id: 'empresa-x-1821', title: 'Subir preview do worktree', agent: 'developer' },
-  { id: 'empresa-x-1818', title: 'Ajustar copy do empty state', agent: 'designer' },
-  { id: 'empresa-x-1814', title: 'Rodar opus check no monorepo', agent: 'reviewer' },
+const orders = [
+  { id: 'OS-1842', title: 'Revisão dos 20.000 km', vehicle: 'ABC-1D23' },
+  { id: 'OS-1839', title: 'Troca das pastilhas de freio', vehicle: 'BRA-2E19' },
+  { id: 'OS-1835', title: 'Alinhamento e balanceamento', vehicle: 'RIO-4F56' },
+  { id: 'OS-1830', title: 'Diagnóstico de ruído na suspensão', vehicle: 'SPO-7G88' },
+  { id: 'OS-1827', title: 'Troca de óleo e filtro', vehicle: 'ABC-1D23' },
+  { id: 'OS-1821', title: 'Substituição da bateria', vehicle: 'CWB-3H45' },
+  { id: 'OS-1818', title: 'Higienização do ar-condicionado', vehicle: 'BRA-2E19' },
+  { id: 'OS-1814', title: 'Revisão dos 40.000 km', vehicle: 'POA-9J12' },
 ]
 
 render(
   <ScrollArea className="h-48 w-full rounded-md border border-border">
     <div className="p-3">
-      {sessions.map((s) => (
-        <div key={s.id} className="rounded-md px-2 py-1.5 text-sm hover:bg-muted">
-          <p className="font-medium">{s.title}</p>
-          <p className="text-xs text-muted-foreground">{s.id} · {s.agent}</p>
+      {orders.map((order) => (
+        <div key={order.id} className="rounded-md px-2 py-1.5 text-sm hover:bg-muted">
+          <p className="font-medium">{order.title}</p>
+          <p className="text-xs text-muted-foreground">{order.id} · {order.vehicle}</p>
         </div>
       ))}
     </div>
@@ -30,17 +32,18 @@ render(
 
 ## Trilho horizontal
 
-Para rolar na horizontal, acrescente <ScrollBar orientation="horizontal" /> como filho e deixe o conteúdo em uma linha que não quebra (flex + w-max).
+Para rolar na horizontal, acrescente `<ScrollBar orientation="horizontal" />` como filho e mantenha
+o conteúdo em uma linha que não quebra, com `flex` e `w-max`.
 
 ```tsx preview col
-const skills = ['implement-opus-change', 'create-opus-action', 'test-opus-action', 'build-opus-ui', 'upgrade-opus']
+const services = ['Troca de óleo', 'Filtro de ar', 'Alinhamento', 'Balanceamento', 'Pastilhas de freio', 'Velas de ignição']
 
 render(
   <ScrollArea className="w-full rounded-md border border-border whitespace-nowrap">
     <div className="flex w-max gap-2 p-3">
-      {skills.map((skill) => (
-        <span key={skill} className="rounded-md border border-border bg-muted px-3 py-1.5 text-sm">
-          {skill}
+      {services.map((service) => (
+        <span key={service} className="rounded-md border border-border bg-muted px-3 py-1.5 text-sm">
+          {service}
         </span>
       ))}
     </div>
@@ -49,28 +52,30 @@ render(
 )
 ```
 
-## Painel com divisórias
+## Histórico com divisórias
 
-O conteúdo é livre: aqui o log do agente, com Separator entre as linhas. A barra só aparece quando o conteúdo passa da altura.
+O conteúdo interno é livre. Neste exemplo, o histórico de uma ordem de serviço usa `Separator`
+entre as linhas. A barra só aparece quando o conteúdo passa da altura e o ponteiro está sobre a
+área; para mantê-la sempre visível, passe `type="always"`.
 
 ```tsx preview col
-const log = [
-  '12:04 developer clonou o worktree de empresa-x-api',
-  '12:05 developer rodou pnpm install',
-  '12:07 developer abriu a sessão empresa-x-1842',
-  '12:11 developer aplicou o diff no schema de billing',
-  '12:14 reviewer foi acionado no handoff',
-  '12:16 reviewer apontou 2 ajustes de microcopy',
-  '12:19 developer corrigiu a microcopy',
-  '12:22 opus check passou em todos os pacotes',
-  '12:24 reviewer aprovou o handoff',
+const history = [
+  '08:02 Veículo recebido na oficina',
+  '08:15 Checklist de entrada concluído',
+  '08:40 Diagnóstico iniciado',
+  '09:10 Orçamento enviado ao cliente',
+  '09:32 Orçamento aprovado',
+  '10:05 Peças separadas no estoque',
+  '11:20 Serviço concluído',
+  '11:45 Teste de rodagem aprovado',
+  '12:00 Veículo liberado para retirada',
 ]
 
 render(
   <ScrollArea className="h-40 w-full rounded-md border border-border">
     <div className="p-3 text-sm">
-      {log.map((line, i) => (
-        <div key={i}>
+      {history.map((line, i) => (
+        <div key={line}>
           {i > 0 && <Separator className="my-1.5" />}
           <p className="text-muted-foreground">{line}</p>
         </div>
@@ -84,11 +89,13 @@ render(
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `className` | `string` | | Classes que definem as dimensões da janela rolável. Sem uma dimensão limitada, não há conteúdo a recortar. |
-| `children` | `React.ReactNode` | | Conteúdo da janela, incluindo uma `ScrollBar` horizontal quando necessária. |
+| `className` | `string` | | Define as dimensões da janela rolável. Sem uma dimensão limitada, não há conteúdo a recortar. |
+| `type` | `'hover' \| 'scroll' \| 'auto' \| 'always'` | `'hover'` | Quando a barra aparece: sob o ponteiro, durante a rolagem, sempre que houver excedente ou sempre. |
+| `children` | `ReactNode` | | Conteúdo da janela, incluindo uma `ScrollBar` horizontal quando necessária. |
 
 ## Propriedades de ScrollBar
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Direção da barra. A barra vertical já faz parte de `ScrollArea`. |
+| `className` | `string` | | Ajusta o trilho da barra. |

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

@@ -1,7 +1,9 @@
 ## Escolha em lista
 
-Use `Select` para escolhas em lista. Declare as opções como dados em `options`; `label` é usado no
-campo, na busca e na leitura assistiva. Associe `id` ao `htmlFor` de `Label` em formulários.
+Use `Select` quando a pessoa precisar escolher um valor em uma lista que não cabe, inteira, na tela.
+Para poucas opções que devem ficar visíveis ao mesmo tempo, use [`RadioGroup`](/ui/radio-group).
+Declare as opções como dados em `options`; `label` é usado no campo, na busca e na leitura
+assistiva. Associe `id` ao `htmlFor` de `Label` em formulários.
 
 ```tsx preview col md
 const [role, setRole] = useState('')
@@ -16,7 +18,7 @@ render(
       placeholder="Selecione o papel"
       options={[
         { value: 'designer', label: 'Designer' },
-        { value: 'developer', label: 'Developer' },
+        { value: 'developer', label: 'Desenvolvedor' },
         { value: 'reviewer', label: 'Revisor' },
       ]}
     />
@@ -24,9 +26,10 @@ render(
 )
 ```
 
-O gatilho respeita a largura definida pelo contexto. Ao abrir, a lista usa essa largura como mínimo
-e pode crescer até `32rem` para preservar rótulos maiores sem alterar o layout do formulário ou da
-toolbar. Rótulos que ultrapassarem esse limite continuam truncados como proteção de layout.
+O gatilho respeita a largura definida pelo contexto. Na variante padrão, a lista aberta usa essa
+largura como mínimo e pode crescer até `32rem` para mostrar rótulos maiores sem alterar o layout do
+formulário ou da toolbar. Nas variantes `outline` e `ghost`, a lista tem largura própria, entre
+`14rem` e `20rem`. Rótulos que ultrapassarem o limite são truncados.
 
 ## Lista pesquisável
 
@@ -67,7 +70,7 @@ const [skills, setSkills] = useState<string[]>(['clean-code'])
 
 render(
   <div className="grid gap-2">
-    <Label htmlFor="agent-skills">Skills do agente</Label>
+    <Label htmlFor="agent-skills">Habilidades do agente</Label>
     <Select
       multiple
       searchable
@@ -128,7 +131,7 @@ render(
     options={[
       { value: 'joao', label: 'João Campos', group: 'Membros' },
       { value: 'rafa', label: 'Rafa', group: 'Membros' },
-      { value: 'developer', label: 'Developer', group: 'Agentes' },
+      { value: 'developer', label: 'Desenvolvedor', group: 'Agentes' },
       { value: 'reviewer', label: 'Revisor', group: 'Agentes' },
     ]}
   />,
@@ -144,7 +147,7 @@ Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com deb
 const ASSIGNEES = [
   { value: 'joao', label: 'João Campos', hint: 'humano' },
   { value: 'designer', label: 'Designer', hint: 'IA' },
-  { value: 'developer', label: 'Developer', hint: 'IA' },
+  { value: 'developer', label: 'Desenvolvedor', hint: 'IA' },
   { value: 'reviewer', label: 'Revisor', hint: 'IA' },
 ]
 
@@ -188,7 +191,7 @@ render(
     onChange={setTask}
     placeholder="Vincular tarefa"
     options={[
-      { value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' },
+      { value: 'gra-2', label: 'Nova tela de anotações', hint: 'GRA-2' },
       { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
     ]}
   />,
@@ -210,7 +213,7 @@ render(
       icon={<Ticket />}
       value={a}
       onChange={setA}
-      options={[{ value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' }]}
+      options={[{ value: 'gra-2', label: 'Nova tela de anotações', hint: 'GRA-2' }]}
     />
     <Button size="sm" variant="outline">Filtrar</Button>
   </div>,
@@ -220,7 +223,8 @@ render(
 ## Limpar a seleção
 
 `clearable` acrescenta uma ação que limpa o valor sem abrir a lista. No modo simples, o valor volta
-a vazio; no múltiplo, volta a `[]`. Os filtros de `ActionList` já habilitam esse comportamento.
+a vazio; no múltiplo, volta a `[]`. Os filtros de [`ActionList`](/ui/action-list) já habilitam
+esse comportamento.
 
 ```tsx preview col md
 function Demo() {
@@ -260,12 +264,12 @@ render(
     options={[
       {
         value: 'developer',
-        label: 'Developer',
+        label: 'Desenvolvedor',
         content: (
           <span className="flex items-center gap-2">
             <Bot className="size-4 text-muted-foreground" />
             <span>
-              Developer <span className="text-muted-foreground">· implementa</span>
+              Desenvolvedor <span className="text-muted-foreground">· implementa</span>
             </span>
           </span>
         ),
@@ -289,21 +293,22 @@ render(
 
 ## Select na barra do Composer
 
-Use `variant="ghost"` para integrar o seletor à barra de ações de `Composer`. `triggerLabel` pode
-encurtar somente o texto do gatilho; a lista continua exibindo o `label` completo.
+Use `variant="ghost"` para integrar o seletor à barra de ações de [`Composer`](/ui/composer).
+`triggerLabel` pode encurtar somente o texto do gatilho; a lista continua exibindo o `label`
+completo.
 
 ```tsx preview col-start
-const [task, setTask] = useState('GB-42')
+const [order, setOrder] = useState('OS-1842')
 
 render(
   <Select
     variant="ghost"
-    value={task}
-    onChange={setTask}
+    value={order}
+    onChange={setOrder}
     options={[
-      { value: '', label: 'Sem task' },
-      { value: 'GB-42', label: 'Trocar o FAB por botão no header', hint: 'GB-42', triggerLabel: 'GB-42' },
-      { value: 'GB-51', label: 'Anexo no composer de criação', hint: 'GB-51', triggerLabel: 'GB-51' },
+      { value: '', label: 'Sem ordem de serviço' },
+      { value: 'OS-1842', label: 'Revisão dos 20.000 km', hint: 'OS-1842', triggerLabel: 'OS-1842' },
+      { value: 'OS-1839', label: 'Troca das pastilhas de freio', hint: 'OS-1839', triggerLabel: 'OS-1839' },
     ]}
   />,
 )
@@ -324,7 +329,7 @@ render(
     onChange={setTask}
     className="w-72"
     options={[
-      { value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' },
+      { value: 'gra-2', label: 'Nova tela de anotações', hint: 'GRA-2' },
       { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
     ]}
     trailing={
@@ -336,26 +341,66 @@ render(
 )
 ```
 
+## Estados
+
+`disabled` esmaece o controle e impede a abertura da lista. `aria-invalid` aplica o contexto de
+erro; associe a mensagem por `aria-describedby`.
+
+```tsx preview col md
+const [unit, setUnit] = useState('')
+
+render(
+  <div className="grid gap-4">
+    <Field data-invalid="true">
+      <FieldLabel htmlFor="unit">Unidade</FieldLabel>
+      <Select
+        id="unit"
+        value={unit}
+        onChange={setUnit}
+        placeholder="Selecione a unidade"
+        aria-invalid
+        aria-describedby="unit-error"
+        options={[
+          { value: 'centro', label: 'Centro' },
+          { value: 'norte', label: 'Zona Norte' },
+        ]}
+      />
+      <FieldError id="unit-error">Escolha a unidade responsável.</FieldError>
+    </Field>
+    <Field data-disabled="true">
+      <FieldLabel htmlFor="region">Região</FieldLabel>
+      <Select
+        id="region"
+        value="sudeste"
+        onChange={() => undefined}
+        disabled
+        options={[{ value: 'sudeste', label: 'Sudeste' }]}
+      />
+    </Field>
+  </div>,
+)
+```
+
 ## Propriedades de Select
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `options` | `SelectOption[]` | | As opções: `{ value, label, hint?, content?, triggerLabel?, group?, disabled? }`. |
 | `value` | `string \| string[]` | | O selecionado: string no single, string[] no multiple. |
-| `onChange` | `(value: string) => void \| (value: string[]) => void` | | Chamado ao escolher (e ao remover chip, no multiple) — a assinatura segue o modo. |
+| `onChange` | `((value: string) => void) \| ((value: string[]) => void)` | | Chamado ao escolher (e ao remover chip, no multiple) — a assinatura segue o modo. |
 | `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, seleção múltipla e variantes visuais (o browser é quem desenha a lista). |
 | `searchable` | `boolean` | `false` | Acrescenta uma linha de busca no topo da lista, que filtra as opções enquanto a pessoa digita. O gatilho continua exibindo a escolha. |
-| `multiple` | `boolean` | `false` | Chips removíveis, lista que permanece aberta e Selecionar tudo. |
-| `variant` | `'default' \| 'outline' \| 'ghost'` | `'default'` | `outline` = compacto com borda; `ghost` = compacto sem borda nem fundo, para barra do composer. |
-| `placeholder` | `string` | `'Selecione…'` | Texto do campo vazio. |
+| `multiple` | `boolean` | `false` | Seleção de vários valores: chips removíveis, lista que permanece aberta e a opção “Selecionar tudo”. |
+| `variant` | `'default' \| 'outline' \| 'ghost'` | `'default'` | `outline` é compacto e mantém a borda; `ghost` é compacto, sem borda nem fundo, para a barra do `Composer`. |
+| `placeholder` | `string` | `'Selecione…'`; sem padrão com `native` | Texto do campo vazio. Com `native`, só existe quando declarado e vira uma opção desabilitada no início da lista. |
 | `searchPlaceholder` | `string` | `'Buscar…'` | Placeholder da linha de busca dentro da lista. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
-| `onSearch` | `(query: string) => void` | | Busca server-side (debounced, ao abrir e ao digitar): desliga o filtro do cmdk — o pai atualiza `options`. |
-| `loading` | `boolean` | | Mostra Buscando… enquanto o fetch corre (use com `onSearch`). |
-| `clearable` | `boolean` | `false` | X no controle quando há seleção — limpa em um clique. |
-| `icon` | `React.ReactNode` | | Ícone leading DENTRO do controle (decorativo) — herda `size-4` e o tom muted. |
-| `trailing` | `React.ReactNode` | | Ação custom no FIM do controle (antes do chevron) — o clique não abre a lista. |
-| `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) para toolbar densa. |
+| `onSearch` | `(query: string) => void` | | Busca no servidor, chamada ao abrir a lista e depois de uma breve pausa na digitação. Desliga o filtro local; o consumidor atualiza `options` com a resposta. |
+| `loading` | `boolean` | | Mostra “Buscando…” enquanto a consulta de `onSearch` está em andamento. |
+| `clearable` | `boolean` | `false` | Mostra, quando há seleção, uma ação que limpa o valor sem abrir a lista. |
+| `icon` | `React.ReactNode` | | Ícone decorativo no início do controle, em `1rem` e no tom atenuado. |
+| `trailing` | `React.ReactNode` | | Ação própria no fim do controle, antes do chevron; interagir com ela não abre a lista. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura na escala dos controles: `default` (`2.25rem`, a de `Input` e `Button`) ou `sm` (`2rem`) para toolbars densas. |
 | `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades e preserva a variante visual. |
 | `disabled` | `boolean` | `false` | Esmaece e trava o controle. |
 | `id` | `string` | | Vai para o campo — para parear com o `htmlFor` do Label. |

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

@@ -41,10 +41,29 @@ aceita o subconjunto coerente com seu papel.
 </div>
 ```
 
+## Controles sem contexto
+
+Alguns controles também têm `variant`, mas não têm `context`. Neles, `variant` não está ligado a um
+significado: descreve o formato do próprio controle.
+
+O par `context` + `variant` vale para componentes que comunicam significado, como
+[`Button`](/ui/button), [`Badge`](/ui/badge), [`Alert`](/ui/alert), [`Dot`](/ui/dot) e
+[`IconTile`](/ui/icon-tile). Os controles abaixo não aceitam `context`:
+
+| Componente | Valores | O que muda |
+| --- | --- | --- |
+| [`Select`](/ui/select) | `default`, `outline`, `ghost` | `default` é o campo completo; `outline` é compacto com borda, e `ghost`, compacto sem borda nem fundo. |
+| [`Toggle`](/ui/toggle) | `default`, `outline` | `default` não tem borda nem fundo em repouso; o fundo aparece no hover e quando ativo. `outline` acrescenta a borda. |
+| [`TabsList`](/ui/tabs) | `default`, `line` | `default` agrupa as abas em uma superfície preenchida; `line` usa uma linha-base e marca nela a aba ativa. |
+
+O mesmo nome pode aparecer nos dois grupos. Num `Badge`, `outline` é um tratamento do significado
+declarado em `context`; num `Select`, é apenas o formato compacto com borda.
+
 ## Dicionários
 
-Status e estágios declaram `context` na entrada. A tela usa `DictionaryValue` ou `ActionList` e não
-escolhe a aparência novamente.
+Status e estágios declaram `context` na entrada. A tela usa
+[`DictionaryValue`](/ui/dictionary-value) ou [`ActionList`](/ui/action-list) e não escolhe a
+aparência novamente.
 
 ```ts
 const status = t.dict(

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

@@ -1,27 +1,32 @@
 ## Separar blocos empilhados
 
-Use a orientação horizontal entre blocos empilhados. A linha ocupa toda a largura disponível.
+Use `Separator` para marcar a fronteira entre blocos de conteúdo que não pertencem a uma superfície
+com regiões. A orientação horizontal fica entre blocos empilhados e ocupa toda a largura disponível.
 
 ```tsx preview col
 <div>
-  <h4 className="text-sm font-medium">Empresa X</h4>
-  <p className="text-sm text-muted-foreground">Workspace do cliente Empresa X.</p>
+  <h4 className="text-sm font-medium">Oficina Centro</h4>
+  <p className="text-sm text-muted-foreground">Rua das Flores, 120.</p>
 </div>
 <Separator />
-<p className="text-sm text-muted-foreground">Última sessão há 2 horas.</p>
+<p className="text-sm text-muted-foreground">Próximo horário livre hoje, às 14h.</p>
 ```
 
+Não use `Separator` entre cabeçalho, corpo e rodapé de [`Card`](/ui/card), [`Dialog`](/ui/dialog) ou
+[`Drawer`](/ui/drawer). Nessas superfícies, os divisores são derivados das regiões presentes: use
+`layout="sectioned"` no componente raiz.
+
 ## Vertical
 
 Use a orientação vertical entre itens lado a lado. A linha herda a altura do contêiner.
 
 ```tsx preview
 <div className="flex h-4 items-center gap-3 text-sm">
-  <span>2 repositórios</span>
+  <span>4 boxes</span>
   <Separator orientation="vertical" />
-  <span>3 agentes</span>
+  <span>2 consultores</span>
   <Separator orientation="vertical" />
-  <span>6 skills</span>
+  <span>6 revisões hoje</span>
 </div>
 ```
 
@@ -29,5 +34,6 @@ Use a orientação vertical entre itens lado a lado. A linha herda a altura do c
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da linha. Vertical precisa de altura vinda do contêiner. |
-| `decorative` | `boolean` | `true` | Decorativa some da árvore de acessibilidade. Use false quando a divisão é semântica. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da linha. A vertical precisa de altura vinda do contêiner. |
+| `decorative` | `boolean` | `true` | Uma linha decorativa fica fora da árvore de acessibilidade. Use `false` quando a divisão tiver significado e precisar ser anunciada. |
+| `className` | `string` | | Ajusta a linha, como o espaçamento ao redor. |

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

@@ -1,8 +1,8 @@
 ## Navegação dentro de um layout
 
 Use `Sidebar` para apresentar navegação global ou contextual em uma coluna lateral. O componente
-organiza a superfície e compartilha o estado de colapso; posição e largura pertencem a um `Pane`
-dentro de `Split`.
+organiza a superfície e compartilha o estado de colapso; posição e largura pertencem a um
+[`Pane`](/ui/pane) dentro de [`Split`](/ui/split).
 
 O exemplo canônico mantém a largura inicial em `rem`, deixa a navegação rolar e preserva o
 cabeçalho e o rodapé nas extremidades.
@@ -13,8 +13,8 @@ render(
     <Split>
       <Pane initialSize="16rem" inset="none">
         <Sidebar className="w-full">
-          <PaneHeader className="px-4 py-3 text-sm font-semibold">
-            Projeto
+          <PaneHeader>
+            <PaneTitle>Projeto</PaneTitle>
           </PaneHeader>
           <PaneBody>
             <SidebarNav
@@ -50,22 +50,17 @@ divisória ao lado do handle.
 
 ## Anatomia e responsabilidades
 
-Cada parte possui uma responsabilidade única. Essa separação permite reutilizar os mesmos slots em
-uma sidebar fixa, redimensionável ou recolhida.
+A `Sidebar` não tem regiões próprias: o cabeçalho, o corpo rolável e o rodapé são os slots do
+`Pane` que a hospeda, com a anatomia e as propriedades descritas na
+[página da família](/ui/pane).
 
 | Parte | Responsabilidade |
 |---|---|
-| `Split` | Define a relação espacial e, opcionalmente, o redimensionamento. |
-| `Pane` | Define largura, limites e espaçamento interno da coluna. |
+| [`Split`](/ui/split) | Define a relação espacial e, opcionalmente, o redimensionamento. |
+| [`Pane`](/ui/pane) | Define largura e limites da coluna e estrutura suas regiões. |
 | `Sidebar` | Desenha a superfície lateral e fornece o estado de colapso. |
-| `PaneHeader` | Mantém identidade, contexto ou ações no topo. |
-| `PaneBody` | Ocupa o espaço restante e concentra a rolagem vertical. |
-| `PaneFooter` | Mantém ações persistentes no rodapé. |
 | `SidebarNav` | Apresenta e controla os destinos de navegação. |
 
-`PaneContent` continua exportado como alias depreciado de `PaneBody`. Código novo usa
-`PaneBody`.
-
 ## Escolher a navegação
 
 Use `SidebarNav` para grupos planos de destinos. Ele recebe dados e produz `SidebarItem` com a mesma
@@ -151,15 +146,17 @@ const [collapsed, setCollapsed] = useState(false)
 render(
   <div className="flex h-64 overflow-hidden rounded-lg border border-border">
     <Sidebar collapsed={collapsed}>
-      <PaneHeader className="flex h-12 items-center justify-center">
-        <Button
-          variant="ghost"
-          size="icon-sm"
-          aria-label={collapsed ? 'Expandir navegação' : 'Recolher navegação'}
-          onClick={() => setCollapsed((current) => !current)}
-        >
-          <PanelLeftClose className={collapsed ? 'rotate-180' : ''} />
-        </Button>
+      <PaneHeader>
+        <PaneActions>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label={collapsed ? 'Expandir navegação' : 'Recolher navegação'}
+            onClick={() => setCollapsed((current) => !current)}
+          >
+            <PanelLeftClose className={collapsed ? 'rotate-180' : ''} />
+          </Button>
+        </PaneActions>
       </PaneHeader>
       <PaneBody>
         <SidebarNav
@@ -241,26 +238,8 @@ O driver de drag-and-drop continua externo e fornece seus atributos por `dragPro
 | `className` | `string` | | Ajusta a raiz. A largura externa deve continuar pertencendo ao `Pane`. |
 | `children` | `ReactNode` | | Cabeçalho, corpo, rodapé ou uma navegação que gerencie a própria estrutura. |
 
-## Propriedades de PaneHeader
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
-| `children` | `ReactNode` | | Identidade, contexto ou ações apresentadas no topo. |
-
-## Propriedades de PaneBody
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a região flexível e rolável. |
-| `children` | `ReactNode` | | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
-
-## Propriedades de PaneFooter
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
-| `children` | `ReactNode` | | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
+`PaneHeader`, `PaneBody` e `PaneFooter` são os slots da família `Pane`; a referência deles está na
+[página do Pane](/ui/pane).
 
 ## Propriedades de SidebarNav
 
@@ -279,8 +258,9 @@ O driver de drag-and-drop continua externo e fornece seus atributos por `dragPro
 | `label` | `string` | Rótulo opcional do grupo. Rótulos vazios não reservam espaço. |
 | `items` | `SidebarNavItem[]` | Itens diretos do grupo. |
 
-`SidebarNavItem` acrescenta `id` às propriedades de `SidebarItem`. Para mais níveis, componha
-`SidebarItem` e `SidebarTreeGroup` diretamente.
+`SidebarNavItem` recebe as propriedades de `SidebarItem`, exceto `active` e `onClick`, e acrescenta
+`id`. O destaque vem de `activeId` e a seleção chega por `onSelect`, ambos no `SidebarNav`. Para mais
+níveis, componha `SidebarItem` e `SidebarTreeGroup` diretamente.
 
 ## Propriedades de SidebarItem
 

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

@@ -1,7 +1,12 @@
 ## Linha de lista com avatar
 
 Use `Skeleton` para preservar a forma do conteúdo durante o carregamento. Combine círculos para
-avatares e barras com dimensões próximas às linhas de texto esperadas.
+avatares e barras com dimensões próximas às linhas de texto esperadas. Quando a forma do conteúdo
+não é conhecida, use [`Spinner`](/ui/spinner); para os estados completos de uma consulta, incluindo
+erro e vazio, use [`DataState`](/ui/data-state).
+
+O `Skeleton` é só visual e não anuncia a espera. Quando a região inteira estiver carregando, marque
+o contêiner com `role="status"` e um nome, como `aria-label="Carregando sessões"`.
 
 ```tsx preview col
 <div className="flex items-center gap-3">
@@ -15,15 +20,19 @@ avatares e barras com dimensões próximas às linhas de texto esperadas.
 
 ## Card em carregamento
 
-O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para a tela não pular quando os dados chegarem.
+O esqueleto reproduz o layout final do card — título, conteúdo e ações — para a tela não pular
+quando os dados chegarem. O título entra pelo slot do cabeçalho com `asChild`, porque o
+`CardHeader` só aceita os próprios slots.
 
 ```tsx preview col
 <Card>
   <CardHeader>
-    <Skeleton className="h-5 w-40" />
-    <Skeleton className="h-4 w-56" />
+    <CardTitle asChild>
+      <Skeleton className="h-5 w-40" />
+    </CardTitle>
   </CardHeader>
   <CardBody className="space-y-2">
+    <Skeleton className="h-4 w-56" />
     <Skeleton className="h-4 w-full" />
     <Skeleton className="h-4 w-3/4" />
   </CardBody>