@softize/opus 13.0.0 → 14.0.0

package/src/ui/docs/content/icon-picker.md

@@ -53,3 +53,14 @@ render(
   />,
 )
 ```
+
+## Propriedades de IconPicker
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Nome do ícone selecionado (chave da paleta); `''` é nenhum. |
+| `onChange` | `(name: string) => void` | | Recebe o nome escolhido. |
+| `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Paleta nome → componente. |
+| `placeholder` | `string` | `'Selecione um ícone…'` | Texto do gatilho sem seleção. |
+| `disabled` | `boolean` | | Desabilita o gatilho. |
+| `id`, `aria-invalid`, `aria-describedby` | | | Integração com `Field`/`ActionForm`: o gatilho recebe a identidade e o estado de erro do campo. |

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

@@ -166,7 +166,7 @@ Com `InputGroupTextarea`, um addon em `block-end` forma uma região de ações a
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | Tamanho do botão embutido; as variantes `icon-*` são quadradas. |
+| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | O subconjunto da escala única que cabe num campo (1.5 · 2 · 1.5 · 1.75rem); os `icon-*` são quadrados. |
 | `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | Contexto semântico herdado de Button. |
 | `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'` | Tratamento visual; use `solid` quando a ação precisar de ênfase. |
 

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

@@ -105,7 +105,7 @@ usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha: transparente, com borda ou levemente tingido. |
-| `size` | `'default' \| 'sm'` | `'default'` | O respiro interno; `sm` atende listas densas. |
+| `size` | `'default' \| 'sm'` | `'default'` | O respiro interno, com os nomes da escala única; `sm` atende listas densas. |
 | `asChild` | `boolean` | `false` | Funde o Item no filho para que a linha inteira assuma sua semântica. |
 
 ## Propriedades de ItemGroup

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

@@ -32,3 +32,10 @@ uma classe adicional.
   <Label htmlFor="archive-workspace">Arquivar o workspace</Label>
 </div>
 ```
+
+## Propriedades de Label
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `htmlFor` | `string` | | O `id` do controle rotulado; clicar no rótulo foca o controle. |
+| `className` | `string` | | Compõe sobre o estilo padrão; o rótulo esmaece com `peer-disabled` e dentro de `group[data-disabled]`. |

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

@@ -111,6 +111,12 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 | `context` | `'neutral' \| 'danger'` | `'neutral'` | `danger` sinaliza uma ação com consequência perigosa. |
 | `inset` | `boolean` | | Alinha um item sem ícone com os itens que possuem ícone. |
 
+## Propriedades de MenuGroup
+
+`MenuGroup` agrupa itens relacionados para leitores de tela (`role="group"`); combine com
+`MenuLabel` para nomear o grupo e `MenuSeparator` para separá-lo do próximo. Não tem props
+próprias além das de DOM.
+
 ## Propriedades de MenuContent
 
 | Propriedade | Tipo | Padrão | Descrição |

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

@@ -39,3 +39,16 @@ tecnologias assistivas. O contêiner da coleção continua responsável pela men
 ```tsx preview col
 <MetricCard loading />
 ```
+
+## Propriedades de MetricCard
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `ReactNode` | | O nome da medida. |
+| `value` | `ReactNode` | | O valor já formatado pelo consumidor. |
+| `loading` | `boolean` | `false` | Substitui rótulo e valor por skeletons e marca `aria-busy`. |
+| `labelAction` | `ReactNode` | | Controle ao lado do rótulo, como uma explicação em tooltip. |
+| `description` | `ReactNode` | | Contexto que explica recorte, proporção ou significado do valor. |
+| `icon` | `ReactNode` | | Ícone decorativo que identifica a natureza da medida. |
+| `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Contexto semântico do ícone; não altera a superfície do card. |
+| `action` | `ReactNode` | | Ação relacionada diretamente à medida. |

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

@@ -8,7 +8,9 @@ contexto. O container é centralizado e ocupa a largura disponível até `80rem`
 abaixo do cabeçalho permanece livre para tabelas, cards ou outras composições.
 
 A forma curta é o padrão para páginas comuns. Ela cria internamente `PageHeader` e `PageBody`;
-portanto, não produz uma estrutura visual ou semântica diferente da forma explícita.
+portanto, não produz uma estrutura visual ou semântica diferente da forma explícita. O cabeçalho é a
+mesma anatomia de `Content` (título, contador, descrição e ações): o que muda entre os dois é o nível
+do heading e a hierarquia visual.
 
 `Page` é o esqueleto de páginas e recursos delimitados. Ele também pode ocupar o painel principal
 de um shell com sidebar; a navegação lateral não exige remover o teto nem reconstruir o cabeçalho.
@@ -41,6 +43,14 @@ render(
 )
 ```
 
+## Ações no chrome do shell
+
+Quando o shell reserva uma barra própria para contexto e ações, envolva sua região de conteúdo com
+`PageActionsTarget` e passe o elemento de destino em `target`. As ações declaradas em `Page`
+continuam pertencendo semanticamente ao cabeçalho da página, mas são projetadas nesse elemento.
+Com `target={null}`, elas permanecem na posição padrão; isso permite montar o alvo por `ref` sem
+uma renderização intermediária inconsistente.
+
 ## Composição explícita
 
 Use os slots quando a página precisar compor o header diretamente. Não misture propriedades da
@@ -82,8 +92,10 @@ altura e semântica acessível consistentes.
 </Page>
 ```
 
-`loading` centraliza o `Spinner`; `error` compõe `Alert`; `empty` compõe `Empty`; e `ready` entrega
-os filhos sem acrescentar uma superfície.
+`loading` centraliza o `Spinner` num contêiner `role="status"`; `error` compõe `Alert` com o botão
+de recuperação quando há `onRetry`; `empty` compõe `Empty`; e `ready` entrega os filhos sem
+acrescentar uma superfície. São as mesmas superfícies de `DataState`, na escala da página: `title`
+e `description` nomeiam a situação e, sem `title`, valem `errorMessage` e `emptyMessage`.
 
 ```tsx preview col
 <Page title="Relatórios">
@@ -118,5 +130,9 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | `title` | `ReactNode` | Texto seguro por estado | Situação reconhecível pela pessoa. |
 | `description` | `ReactNode` | | Impacto ou próximo passo aplicável. |
 | `icon` | `ReactNode` | Alerta no erro | Ícone decorativo do estado. |
-| `action` | `ReactNode` | | Recuperação, seleção ou criação aplicável. |
+| `action` | `ReactNode` | | Seleção ou criação aplicável ao estado. |
+| `emptyMessage` | `string` | `'Nada por aqui'` | Título do vazio quando `title` não é informado. |
+| `errorMessage` | `string` | `'Não foi possível carregar esta página'` | Título do erro quando `title` não é informado. |
+| `onRetry` | `() => void \| Promise<void>` | | Recuperação do erro: acrescenta o botão de tentar de novo ao lado de `action`. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botão de recuperação. |
 | `children` | `ReactNode` | | Conteúdo renderizado somente em `ready`. |

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

@@ -29,21 +29,21 @@ rodapé.
 
 ## Números longos
 
-A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, ajuste por
-`className` (`h-7 min-w-7 text-xs` nos números; `size-7` mais `iconClassName="size-3.5"` nas
-setas com `iconOnly`).
+A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, as setas e a
+elipse usam `size="icon-sm"` (o quadrado de 1.75rem da escala única, com o glifo de 0.875rem); os
+números, que não têm um degrau de 1.75rem na escala, ajustam por `className` (`h-7 min-w-7 text-xs`).
 
 ```tsx preview
 <Pagination>
   <PaginationContent className="gap-0.5">
     <PaginationItem>
-      <PaginationPrevious href="#" iconOnly className="size-7" iconClassName="size-3.5" />
+      <PaginationPrevious href="#" iconOnly size="icon-sm" />
     </PaginationItem>
     <PaginationItem>
       <PaginationLink href="#" page={1} className="h-7 min-w-7 text-xs" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationEllipsis className="size-7" />
+      <PaginationEllipsis size="icon-sm" />
     </PaginationItem>
     <PaginationItem>
       <PaginationLink href="#" page={5726} className="h-7 min-w-7 text-xs" />
@@ -52,7 +52,7 @@ setas com `iconOnly`).
       <PaginationLink href="#" page={5727} isActive className="h-7 min-w-7 text-xs" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationNext href="#" iconOnly className="size-7" iconClassName="size-3.5" />
+      <PaginationNext href="#" iconOnly size="icon-sm" />
     </PaginationItem>
   </PaginationContent>
 </Pagination>
@@ -61,7 +61,8 @@ setas com `iconOnly`).
 ## Com elipse
 
 `PaginationEllipsis` marca, de forma decorativa e com `aria-hidden`, uma sequência de páginas que
-não cabe na barra.
+não cabe na barra. `size` aceita os quadrados da escala (`icon-xs`, `icon-sm`, `icon`, `icon-lg`) para
+parear com as setas.
 
 ```tsx preview
 <Pagination>
@@ -130,7 +131,7 @@ render(
 | `page` | `number` | | Número usado como conteúdo, quando `children` não é informado, e no nome acessível “Página N”. |
 | `isActive` | `boolean` | `false` | Marca a página atual com `aria-current="page"` e tratamento `outline`. |
 | `href` | `string` | | Renderiza um `<a>`. Sem `href`, o componente usa `<button>` e aceita `onClick` e `disabled`. |
-| `size` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | Escala herdada de `Button`. A largura mínima cresce para acomodar números longos. |
+| `size` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. A largura mínima cresce para acomodar números longos; os `icon-*` são quadrados. |
 
 ## Propriedades de PaginationPrevious e PaginationNext
 
@@ -138,4 +139,5 @@ render(
 |---|---|---|---|
 | `label` | `string` | `'Página anterior'` ou `'Próxima página'` | Nome acessível e texto visível da ação. |
 | `iconOnly` | `boolean` | `false` | Exibe somente a seta; `label` continua disponível para leitura assistiva. |
-| `iconClassName` | `string` | | Classes aplicadas ao ícone da seta. |
+| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. |
+| `iconClassName` | `string` | | Classes aplicadas ao ícone da seta, quando o glifo da escala não servir. |

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

@@ -49,6 +49,12 @@ detalhes.
 | `open` | `boolean` | | Estado no modo controlado. |
 | `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado para permitir abertura ou fechamento por código. |
 
+## Propriedades de PopoverAnchor
+
+`PopoverAnchor` posiciona o painel em relação a um elemento que não é o gatilho — útil quando o
+clique acontece num item de linha, mas o painel deve alinhar-se ao contêiner. Aceita `asChild` para
+não introduzir um nó extra; sem ele, o `PopoverTrigger` é a âncora.
+
 ## Propriedades de PopoverContent
 
 | Propriedade | Tipo | Padrão | Descrição |

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

@@ -40,25 +40,21 @@ render(
 )
 ```
 
-## Altura e cor
+## Altura e contexto
 
-className compõe sobre o padrão: ajuste a altura no Progress e tinja o preenchimento mirando o slot do indicador (&_[data-slot=progress-indicator]) para sinalizar bom/atenção.
+`context` diz o que o andamento comunica — `success` para meta atingida, `warning` ou `danger`
+para atenção — e tinge trilha e preenchimento com a família semântica. `className` compõe sobre o
+padrão para ajustar a altura.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-4">
   <div className="space-y-1.5">
     <span className="text-sm">Cobertura de testes</span>
-    <Progress
-      value={92}
-      className="h-1.5 [&_[data-slot=progress-indicator]]:bg-emerald-500"
-    />
+    <Progress value={92} context="success" className="h-1.5" />
   </div>
   <div className="space-y-1.5">
     <span className="text-sm">Skills cobertas pelo revisor</span>
-    <Progress
-      value={45}
-      className="h-3 [&_[data-slot=progress-indicator]]:bg-amber-500"
-    />
+    <Progress value={45} context="warning" className="h-3" />
   </div>
 </div>
 ```
@@ -68,4 +64,5 @@ className compõe sobre o padrão: ajuste a altura no Progress e tinja o preench
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `number \| null` | | O progresso de 0 a 100. O preenchimento anima a cada mudança; null/ausente deixa a barra vazia. |
-| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3) ou tinja o indicador via [&_[data-slot=progress-indicator]]:bg-*. |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | O que o andamento comunica; tinge trilha e preenchimento pela família `--context-*`. |
+| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3). |

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

@@ -40,7 +40,7 @@ render(
       id="issue"
       value={issue}
       onChange={setIssue}
-      placeholder="Buscar issue…"
+      placeholder="Buscar item…"
       options={[
         { value: '412', label: 'Ajustar microcopy do handoff', hint: 'SOF-412' },
         { value: '418', label: 'Preview da sessão cai após deploy', hint: 'SOF-418' },
@@ -69,7 +69,7 @@ render(
       id="agent-skills"
       value={skills}
       onChange={setSkills}
-      placeholder="Adicionar skill…"
+      placeholder="Adicionar habilidade…"
       options={[
         { value: 'clean-code', label: 'clean-code' },
         { value: 'code-style', label: 'code-style' },
@@ -181,7 +181,7 @@ render(
     icon={<Ticket />}
     value={task}
     onChange={setTask}
-    placeholder="Vincular task"
+    placeholder="Vincular tarefa"
     options={[
       { value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' },
       { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
@@ -227,8 +227,8 @@ function Demo() {
       value={values}
       onChange={setValues}
       options={[
-        { value: 'developer', label: 'Developer' },
-        { value: 'reviewer', label: 'Reviewer' },
+        { value: 'developer', label: 'Desenvolvedor' },
+        { value: 'reviewer', label: 'Revisor' },
         { value: 'designer', label: 'Designer' },
       ]}
       placeholder="Papéis…"

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

@@ -1,8 +1,8 @@
 ---
-title: Contexto & Variante
+title: Contexto e variante
 ---
 
-# Contexto & Variante
+# Contexto e variante
 
 Componentes semânticos separam significado de aparência. `context` responde por que o elemento
 recebe destaque; `variant` escolhe como esse significado aparece. Essa ordem evita que nomes como
@@ -59,5 +59,6 @@ const status = t.dict(
 
 ## Compatibilidade
 
-`tone` em dicionários e variantes semânticas antigas continuam aceitos durante a migração. Código
-novo usa `context`; não misture o contrato antigo e o novo na mesma ocorrência.
+`tone` em dicionários continua aceito durante a migração; código novo usa `context`. As variantes
+semânticas antigas dos componentes (`default`, `secondary`, `destructive`, `success`, `warning`,
+`info`) saíram na 14.0.0: `variant` só descreve tratamento visual e o significado é sempre `context`.

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

@@ -61,7 +61,7 @@ uma sidebar fixa, redimensionável ou recolhida.
 | `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` ou `ShellNav` | Apresenta e controla os destinos de navegação. |
+| `SidebarNav` | Apresenta e controla os destinos de navegação. |
 
 `PaneContent` permanece como alias temporário de `PaneBody` durante a versão 12. Código novo usa
 `PaneBody`.
@@ -134,28 +134,16 @@ render(
 Esse é o padrão usado pelo `DocBrowser`: seções são rótulos, grupos nomeados são nós expansíveis e
 páginas são folhas. Um grupo começa aberto e volta a abrir quando contém a página ativa.
 
-Use `ShellNav` para uma navegação plana que precisa de cabeçalho próprio e grupos ancorados no
-rodapé. Ele gerencia a rolagem internamente e se adapta quando estiver dentro de uma `Sidebar`
-recolhida.
-
-```tsx
-<Sidebar collapsed={collapsed}>
-  <ShellNav
-    heading={<ShellNavHeading title="Relatórios" action={<CreateReportButton />} />}
-    groups={reportGroups}
-    footer={settingsGroups}
-    activeId={activeId}
-    onSelect={navigateToReport}
-  />
-</Sidebar>
-```
-
 ## Recolher a coluna
 
-`collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem`, `SidebarNav` e `ShellNav` mantêm
+`collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem` e `SidebarNav` mantêm
 somente os ícones e expõem os rótulos em tooltips. Por isso, todo destino que aparece no modo
 recolhido precisa de um ícone reconhecível e de um `label` completo.
 
+O slot de ícone do `SidebarItem` ocupa `1rem` nos dois estados e normaliza SVGs para essa medida.
+O consumidor escolhe o símbolo e sua cor sem precisar repetir largura ou altura em ícones SVG.
+Outros tipos de `ReactNode` continuam responsáveis pelas próprias dimensões.
+
 ```tsx preview
 const [collapsed, setCollapsed] = useState(false)
 
@@ -216,12 +204,13 @@ estrutura evita botões aninhados e permite que cada controle receba foco de for
     }
     onClick={() => {}}
   />
-  <SidebarItem
-    label="Criar workspace"
-    icon={<FilePlus2 />}
-    className="pl-6"
-    onClick={() => {}}
-  />
+  <SidebarTreeGroup>
+    <SidebarItem
+      label="Criar workspace"
+      icon={<FilePlus2 />}
+      onClick={() => {}}
+    />
+  </SidebarTreeGroup>
 </div>
 ```
 
@@ -323,26 +312,3 @@ O driver de drag-and-drop continua externo e fornece seus atributos por `dragPro
 |---|---|---|---|
 | `className` | `string` | | Ajusta o grupo sem substituir o recuo, o espaçamento e a guia vertical padrão. |
 | `children` | `ReactNode` | | Itens ou grupos que descendem do nó anterior. |
-
-## Propriedades de ShellNav
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `groups` | `ShellNavGroup[]` | | Grupos planos exibidos na região rolável. Grupos vazios são omitidos. |
-| `activeId` | `string` | | Identificador do destino atual. |
-| `onSelect` | `(id: string) => void` | | Recebe o identificador selecionado. |
-| `heading` | `ReactNode` | | Conteúdo fixo acima da navegação; fica oculto no modo recolhido. |
-| `footer` | `ShellNavGroup[]` | | Grupos ancorados abaixo da região rolável. |
-| `navLabel` | `string` | `'Navegação'` | Nome acessível da landmark `nav`. |
-| `className` | `string` | | Ajusta a coluna da navegação. A largura vem do contêiner. |
-
-Cada `ShellNavGroup` recebe `label` opcional e `items`. Um `ShellNavItem` declara `id`, `label`,
-`icon`, `badge` e `disabled`.
-
-## Propriedades de ShellNavHeading
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `title` | `ReactNode` | | Título da navegação. |
-| `action` | `ReactNode` | | Ação relacionada apresentada no extremo oposto. |
-| `className` | `string` | | Ajusta a faixa de cabeçalho. |

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

@@ -33,3 +33,9 @@ O esqueleto reproduz o layout final do card — título, descrição, conteúdo
   </CardFooter>
 </Card>
 ```
+
+## Propriedades de Skeleton
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Dá forma ao placeholder (`h-4 w-40`, `size-10 rounded-full`); o componente só traz o pulso e o fundo. |

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

@@ -1,9 +1,12 @@
 ## Carregamento sem progresso conhecido
 
-Use `Spinner` quando a duração ou o progresso da espera não forem conhecidos. `sm` atende ações
-compactas; `lg`, estados mais amplos. O componente já possui o nome acessível “Carregando”.
+Use `Spinner` quando a duração ou o progresso da espera não forem conhecidos. `size` usa os nomes da
+escala dos controles e mede o glifo do controle homônimo: `sm` é o ícone de um `Button` `sm`, `lg` o
+de um `lg`. O ícone é decorativo; quem nomeia a espera é o contêiner (`role="status"`, como fazem
+`DataState` e `PageState`) ou o texto ao lado.
 
 ```tsx preview
+<Spinner size="xs" />
 <Spinner size="sm" />
 <Spinner />
 <Spinner size="lg" />
@@ -20,11 +23,11 @@ andamento.
 
 ## Em carga de conteúdo
 
-Espera curta sem forma definida. Quando o conteúdo tem forma conhecida (lista, card), prefira
-Skeleton.
+Espera curta sem forma definida; o contêiner nomeia o estado. Para uma consulta inteira, `DataState`
+já monta esse contêiner. Quando o conteúdo tem forma conhecida (lista, card), prefira Skeleton.
 
 ```tsx preview
-<div className="flex items-center gap-2 text-sm text-muted-foreground">
+<div role="status" className="flex items-center gap-2 text-sm text-muted-foreground">
   <Spinner />
   <span>Carregando sessões…</span>
 </div>
@@ -34,4 +37,4 @@ Skeleton.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | O tamanho — sm para dentro de botão, lg para estados de página. |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | O glifo do controle homônimo na escala única (0.875 · 0.875 · 1 · 1.25rem). |

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

@@ -74,3 +74,24 @@ const defaultLayout = readLayout('workspace-layout')
 ```
 
 Em aplicações renderizadas no servidor, leia o armazenamento somente no cliente. `onLayoutChanged` também permite usar `sessionStorage` ou uma camada própria quando o layout precisa acompanhar outro escopo.
+
+## Propriedades de Split
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Sentido em que os panes se alinham. |
+| `resizable` | `boolean` | `false` | Cada fronteira ganha um separador acessível e arrastável. |
+| `handle` | `boolean` | `false` | Mostra a alça visual no separador. |
+| `id` | `string` | | Identidade estável do grupo redimensionável. |
+| `defaultLayout` | `Record<string, number>` | | Layout percentual restaurado, indexado pelos ids dos panes. |
+| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` | | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
+
+## Propriedades de Pane
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `id` | `string` | | Identidade estável usada pelo layout redimensionável e persistido. |
+| `initialSize` | `number \| string` | | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
+| `minSize` / `maxSize` | `number \| string` | | Limites quando o split é redimensionável. |
+| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
+| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio. |

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

@@ -66,5 +66,5 @@ disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em p
 | `checked` | `boolean` | | O estado, no modo controlado — parear com onCheckedChange. |
 | `onCheckedChange` | `(checked: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave — sm para densidade em linha de lista. |
+| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave, com os nomes da escala única — sm para densidade em linha de lista. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |

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

@@ -92,7 +92,7 @@ lateral do gatilho.
 | `defaultValue` | `string` | | Aba inicial no modo não controlado. |
 | `value` | `string` | | Aba ativa no modo controlado. Use com `onValueChange`. |
 | `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outra aba. |
-| `size` | `'default' \| 'sm'` | `'default'` | Escala de altura compartilhada com `TabsList`. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura da lista na escala única dos controles (2.25 e 2rem), aplicada em `TabsList`. |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas. |
 
 ## Propriedades de TabsList

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

@@ -29,3 +29,10 @@ Associe `htmlFor` no `Label` ao `id` do campo para manter o rótulo acessível.
 <Textarea aria-invalid placeholder="Conte o contexto da mudança." />
 <Textarea disabled defaultValue="Sessão encerrada — o brief não pode mais ser editado." />
 ```
+
+## Propriedades de Textarea
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `…props` | `ComponentProps<'textarea'>` | | Todos os atributos nativos (`value`, `defaultValue`, `rows`, `disabled`, `aria-invalid`…). A altura acompanha o conteúdo (`field-sizing-content`) a partir de `min-h-16`. |
+| `className` | `string` | | Compõe sobre o estilo padrão. |

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

@@ -70,7 +70,7 @@ disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
 | `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 (fundo só quando ativo); outline carrega a borda. |
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura do botão — sm para toolbar densa, lg para alvo mais confortável. |
+| `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. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |
 
 ## ToggleGroup

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

@@ -1,8 +1,8 @@
 ---
-title: Tokens & Tema
+title: Tokens e tema
 ---
 
-# Tokens & Tema
+# Tokens e tema
 
 O tema canônico vive no Opus (`theme.css`): tokens com a cor inteira na var, mapeados para o
 Tailwind via `@theme inline`. Os swatches abaixo leem as vars **ao vivo** — troque o tema do app
@@ -73,8 +73,8 @@ render(
 
 ## Linhas e foco
 
-> Bordas e o anel de foco também são tokens — nada de cinza hardcoded. A aresta de superfície
-> elevada (`--edge`) mora na seção Elevação por papel.
+> Bordas e o anel de foco também são tokens — nada de cinza hardcoded. Superfícies elevadas usam
+> a mesma `border-border`; o que muda entre elas é a sombra, descrita na seção Escala de elevação.
 
 ```tsx preview
 const LINES = [

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

@@ -60,3 +60,11 @@ quando o texto completo ainda não oferecer contexto suficiente.
 
 Requer `TooltipProvider` na raiz (o esqueleto do `opus create` já monta). Largura vem do
 container ou de `className` (`max-w-*`) — o span é `block truncate`.
+
+## Propriedades de Truncate
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `tooltip` | `ReactNode` | os próprios `children` | Conteúdo da dica quando o texto transborda. |
+| `fade` | `boolean` | `false` | Sinaliza o corte esmaecendo o fim da linha, no lugar das reticências. |
+| `className` | `string` | | Largura (`max-w-*`) e demais ajustes; o span é `block truncate`. |

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

@@ -30,6 +30,20 @@ import { Button, Dialog, useAction } from '@softize/opus/ui/react'
 @source '../node_modules/@softize/opus/src/ui';
 ```
 
+## Prebundle do Vite
+
+A entrada `@softize/opus/ui/react` é um `.tsx`, e o prebundle do Vite só considera entradas
+`.js`/`.ts`. Sem ajuste, o dev server avisa `Cannot optimize dependency` e serve a árvore do Opus
+arquivo a arquivo na carga fria. Há duas saídas, cada uma com um custo conhecido:
+
+- `optimizeDeps.include: ['@softize/opus/ui/react']` com `extensions: ['.tsx']` pré-empacota o
+  Opus, mas pode duplicar `@tanstack/react-query` quando o app também o importa direto (dois
+  `QueryClient`, hooks fora do provider).
+- `optimizeDeps.exclude: ['@softize/opus/ui/react']` evita a duplicação e infla a carga fria.
+
+Escolha pelo sintoma que aparece no seu app e registre a decisão no `vite.config.ts`. A saída
+definitiva (entrada `.ts` no pacote) está no radar do Opus.
+
 ## Origem e anti-drift
 
 > Cada componente declara de onde veio — e a regra de sincronização vem junto.

package/src/ui/docs/doc-client.tsx

@@ -8,7 +8,7 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { z } from 'zod'
 import { attachLogicalType, defineContract, error } from '../../core/index.ts'
 import type { ActionDef, ActionResult, ClientAdapter, LogicalTypeMeta, Paginated } from '../../core/index.ts'
-import { TbdlibProvider } from '../react.tsx'
+import { OpusProvider } from '../react.tsx'
 
 // — Dados enlatados (domínio da casa) —
 export interface DocBrowserWorkspace {
@@ -37,7 +37,7 @@ export const docWorkspaceStatus: LogicalTypeMeta = {
     keys: [...STATUS],
     entries: {
       active: { label: 'Ativo', context: 'success', description: 'Agentes em operação para o cliente.' },
-      onboarding: { label: 'Onboarding', context: 'warning' },
+      onboarding: { label: 'Em integração', context: 'warning' },
       paused: { label: 'Pausado' },
     },
     presentation: 'status',
@@ -59,7 +59,7 @@ export const docWorkspaceCreate = defineContract({
   }),
   output: z.object({ id: z.string() }),
   fields: {
-    name: { label: 'Nome', placeholder: 'Ex.: Empresa X', hint: 'Digite "Softize" pra ver o erro de servidor.' },
+    name: { label: 'Nome', placeholder: 'Ex.: Empresa X', help: 'Digite “Softize” para ver o erro de servidor.' },
     status: { label: 'Status' },
     contact: { label: 'Contato', placeholder: 'email@cliente.com' },
     notes: { label: 'Observações', placeholder: 'Contexto do onboarding…' },
@@ -100,7 +100,7 @@ export const docWorkspaceList = defineContract({
         kind: 'static',
         items: [
           { value: 'active', label: 'Ativo' },
-          { value: 'onboarding', label: 'Onboarding' },
+          { value: 'onboarding', label: 'Em integração' },
           { value: 'paused', label: 'Pausado' },
         ],
       },
@@ -225,7 +225,7 @@ const queryClient = new QueryClient()
 export function DocBrowserActionProvider({ children }: { children: React.ReactNode }): React.ReactElement {
   return (
     <QueryClientProvider client={queryClient}>
-      <TbdlibProvider client={docClient}>{children}</TbdlibProvider>
+      <OpusProvider client={docClient}>{children}</OpusProvider>
     </QueryClientProvider>
   )
 }