@softize/opus 19.0.0 → 20.1.0

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

@@ -258,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">

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

@@ -3,52 +3,77 @@
 Use `Slider` para escolher um valor dentro de uma faixa. `defaultValue` recebe um array; `[n]`
 representa um único controle. `min`, `max` e `step` delimitam os valores disponíveis.
 
+Quem recebe o foco e anuncia o valor é o controle arrastável, chamado de thumb. Sem rótulo
+visível, passe `aria-label` ao `Slider`: ele repassa o nome ao thumb.
+
 ```tsx preview col
-<Slider defaultValue={[40]} min={0} max={100} step={5} />
+<Slider aria-label="Opacidade" defaultValue={[40]} min={0} max={100} step={5} />
 ```
 
 ## Controlado
 
 `onValueChange` recebe o array atualizado. Para um único controle, leia `value[0]`.
 
+Com um rótulo visível, ligue-o ao `Slider` por `aria-labelledby`. O `htmlFor` do `Label` não
+alcança o thumb, porque ele não é um campo nativo.
+
 ```tsx preview col
 const [parallelism, setParallelism] = useState([4])
 
 render(
-  <div role="group" aria-labelledby="parallelism-label" className="grid w-full gap-3">
+  <div className="grid w-full gap-3">
     <div className="flex items-center justify-between">
       <Label id="parallelism-label">Sessões em paralelo</Label>
       <span className="text-sm text-muted-foreground">{parallelism[0]}</span>
     </div>
-    <Slider value={parallelism} onValueChange={setParallelism} min={1} max={8} step={1} />
+    <Slider
+      aria-labelledby="parallelism-label"
+      value={parallelism}
+      onValueChange={setParallelism}
+      min={1}
+      max={8}
+      step={1}
+    />
   </div>,
 )
 ```
 
 ## Intervalo
 
-Dois números em `value` criam um intervalo selecionável entre dois controles.
+Dois números em `value` criam um intervalo selecionável entre dois thumbs, e cada um precisa de um
+nome próprio. Passe os nomes em `thumbLabels`, na ordem dos valores. Sem `thumbLabels`, o nome comum
+se compõe com a posição: com `aria-label`, “Custo, mínimo” e “Custo, máximo”; com
+`aria-labelledby`, o texto do rótulo seguido de “Mínimo” ou “Máximo”. Sem nome algum, o leitor de
+tela anuncia só “Mínimo” e “Máximo”, sem dizer do quê.
 
 ```tsx preview col
 const [budget, setBudget] = useState([20, 60])
 
 render(
-  <div role="group" aria-labelledby="budget-label" className="grid w-full gap-3">
+  <div className="grid w-full gap-3">
     <div className="flex items-center justify-between">
-      <Label id="budget-label">Custo estimado (US$)</Label>
+      <Label>Custo estimado (US$)</Label>
       <span className="text-sm text-muted-foreground">{budget[0]} – {budget[1]}</span>
     </div>
-    <Slider value={budget} onValueChange={setBudget} min={0} max={100} step={5} />
+    <Slider
+      thumbLabels={['Custo mínimo', 'Custo máximo']}
+      value={budget}
+      onValueChange={setBudget}
+      min={0}
+      max={100}
+      step={5}
+    />
   </div>,
 )
 ```
 
 ## Desabilitado
 
-disabled esmaece o trilho e o thumb e bloqueia o arraste — o valor fica congelado no defaultValue.
+`disabled` esmaece o trilho e o thumb e bloqueia o arraste. O valor fica congelado no
+`defaultValue`.
 
 ```tsx preview col
-<Slider defaultValue={[70]} min={0} max={100} disabled />
+<Slider aria-label="Opacidade" defaultValue={[70]} min={0} max={100} disabled />
 ```
 
 ## Propriedades de Slider
@@ -63,3 +88,6 @@ disabled esmaece o trilho e o thumb e bloqueia o arraste — o valor fica congel
 | `step` | `number` | `1` | Incremento entre valores possíveis. |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do trilho — vertical exige altura no container. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o arraste. |
+| `aria-label` | `string` | | Nome do thumb quando não há rótulo visível. Em intervalo, prefira `thumbLabels`. |
+| `aria-labelledby` | `string` | | `id` do rótulo visível que nomeia o thumb. |
+| `thumbLabels` | `readonly string[]` | | Um nome por thumb, na ordem de `value`. Prevalece sobre `aria-label` e `aria-labelledby`. |

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

@@ -3,7 +3,7 @@
 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.
+[`DataState`](/ui/data-state) e `PageState`) ou o texto ao lado.
 
 ```tsx preview
 <Spinner size="xs" />
@@ -14,7 +14,7 @@ de um `lg`. O ícone é decorativo; quem nomeia a espera é o contêiner (`role=
 
 ## No botão
 
-Durante uma ação, use `busy` no `Button` com um rótulo que descreva o andamento. O botão fica
+Durante uma ação, use `busy` no [`Button`](/ui/button) com um rótulo que descreva o andamento. O botão fica
 desabilitado e o spinner ocupa o lugar do ícone, no glifo do tamanho do botão.
 
 ```tsx preview
@@ -24,7 +24,8 @@ desabilitado e o spinner ocupa o lugar do ícone, no glifo do tamanho do botão.
 ## Em carga de conteúdo
 
 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.
+já monta esse contêiner. Quando o conteúdo tem forma conhecida, como uma lista ou um card, prefira
+[`Skeleton`](/ui/skeleton).
 
 ```tsx preview
 <div role="status" className="flex items-center gap-2 text-sm text-muted-foreground">

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

@@ -21,6 +21,19 @@ render(
 );
 ```
 
+Escreva cada `Pane` diretamente dentro do `Split`; um fragment pode agrupá-los, como em uma
+renderização condicional que devolve dois panes. O `Split` lê o tamanho de cada `Pane` antes de
+renderizá-lo, então não enxerga um `Pane` devolvido por outro componente: nesse caso, escreva o
+`Pane` no `Split` e passe o componente como filho dele. Qualquer outro filho interrompe a
+renderização com um erro que aponta o nó recebido, em vez de sumir da tela sem aviso.
+
+O [`opus check`](/docs/cli) antecipa esse erro com a regra `ui-structure-split`: ele aponta o filho
+direto de um `Split` que o código mostra não ser `Pane`, como um elemento HTML, um texto, outro
+componente do Opus ou um componente declarado no mesmo arquivo. Panes em fragment ou em condicional,
+espaços e comentários são aceitos. Expressões dinâmicas, como `{children}` ou `{items.map(...)}`, e
+componentes importados de outros módulos ficam fora do check; nesses casos, só o erro em runtime
+revela um filho inválido.
+
 O `Split` responde pela relação espacial e pelo arraste. O que existe dentro de cada área — o
 cabeçalho, o corpo rolável, o rodapé, o recuo e a escolha entre regiões seccionadas e contínuas —
 pertence ao [`Pane`](/ui/pane) e está documentado na página da família.
@@ -139,6 +152,9 @@ render(<Example />);
 | `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. |
+| `className`       | `string`                                  |                | Ajusta o contêiner do grupo.                                            |
+| `data-slot`       | `string`                                  | `'split'`      | Identificador semântico para testes e composição de patterns.          |
+| `children`        | `ReactNode`                               |                | Os `Pane`, diretos ou agrupados em fragment; outro filho gera erro.     |
 
 ## Propriedades de SurfaceAssistant
 
@@ -151,3 +167,6 @@ render(<Example />);
 | `initialSize`    | `PaneSize`  | `28rem` | Largura inicial do painel.                              |
 | `minSize`        | `PaneSize`  | `20rem` | Largura mínima durante o redimensionamento.             |
 | `maxSize`        | `PaneSize`  | `40rem` | Largura máxima durante o redimensionamento.             |
+| `className`      | `string`    |         | Ajusta o contêiner do split.                            |
+| `contentClassName` | `string`  |         | Ajusta a coluna do conteúdo principal.                  |
+| `assistantClassName` | `string` |        | Ajusta a coluna do painel de assistência.               |

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

@@ -4,8 +4,7 @@ title: Armazenamento
 
 # Armazenamento
 
-> **Experimental.** Superfície mínima, sem consumidor interno ainda — cresce por
-> reincidência de caso real, não por especulação.
+> **Experimental.** A superfície é mínima e cresce conforme casos reais a exigem.
 
 Use `StorageAdapter` para upload, download, remoção e geração de URL de arquivos. A chave é um
 caminho lógico, como `clientes/123/contrato.pdf`; cada driver decide onde o conteúdo é armazenado.
@@ -31,10 +30,11 @@ import { fsStorage } from '@softize/opus/storage/fs'
 import { s3Storage } from '@softize/opus/storage/s3'
 import { S3Client } from '@aws-sdk/client-s3'
 
-// Dev / single-host: arquivos sob um root local; url() exige baseUrl (o app serve o root).
+// Desenvolvimento ou um único host: arquivos num diretório local; url() exige baseUrl,
+// e o app serve esse diretório.
 const dev = fsStorage({ root: './var/arquivos', baseUrl: 'http://localhost:5173/arquivos' })
 
-// Produção: S3 e compatíveis (MinIO, R2…). O client é seu — região/endpoint/credencial.
+// Produção: S3 e compatíveis (MinIO, R2…). O app cria o client com região, endpoint e credenciais.
 const prod = s3Storage({
   client: new S3Client({ region: 'us-east-1' }),
   bucket: 'meu-app',
@@ -42,8 +42,8 @@ const prod = s3Storage({
 })
 ```
 
-Os peers do S3 são **opcionais** (`@aws-sdk/client-s3`; `s3-request-presigner` para o
-`url()`): quem não usa o driver não os instala — importados sob demanda.
+`@aws-sdk/client-s3` e, para `url()`, `@aws-sdk/s3-request-presigner` são dependências opcionais,
+carregadas só quando o driver é usado.
 
 ## No runtime
 
@@ -62,6 +62,5 @@ handler: async (ctx, input) => {
 
 ## Limites atuais
 
-Bytes em memória (`Uint8Array`), sem streams — arquivo gigante ainda não é o caso;
-sem `list`, sem metadata rica. Cada um entra quando um projeto real cobrar — é a
-régua do Opus: comportamento vira peça na reincidência.
+O conteúdo trafega inteiro em memória, como `Uint8Array`, sem streams; arquivos muito grandes ainda
+não são suportados. Também não há `list` nem metadados além de `contentType`.

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

@@ -1,7 +1,8 @@
 ## Alternar uma preferência
 
-Use `Switch` para uma preferência booleana que entra em vigor imediatamente. Associe o controle a
-`Label`; `defaultChecked` define o estado inicial no modo não controlado.
+Use `Switch` para uma preferência booleana que entra em vigor imediatamente. Quando a escolha só vale
+ao salvar um formulário, use [`Checkbox`](/ui/checkbox). Associe o controle a um [`Label`](/ui/label);
+`defaultChecked` define o estado inicial no modo não controlado.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -31,7 +32,8 @@ render(
 
 ## Tamanho sm
 
-Use `size="sm"` em linhas de lista e outras composições compactas.
+Use `size="sm"` em linhas de lista e outras composições compactas. O tamanho segue o degrau do ícone
+na escala dos controles, e não a altura da linha: a chave `sm` acompanha o ícone de um botão `sm`.
 
 ```tsx preview col-start
 <div className="flex items-center gap-2">
@@ -46,7 +48,8 @@ Use `size="sm"` em linhas de lista e outras composições compactas.
 
 ## Desabilitado
 
-disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em par esmaece junto (peer-disabled).
+`disabled` esmaece e bloqueia a chave, ligada ou desligada. O `Label` escrito logo depois da chave,
+no mesmo contêiner, esmaece junto.
 
 ```tsx preview col-start
 <div className="flex items-center gap-2">
@@ -63,8 +66,8 @@ disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em p
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `checked` | `boolean` | | O estado, no modo controlado — parear com onCheckedChange. |
+| `checked` | `boolean` | | Estado no modo controlado. Use 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, 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). |
+| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave, com os nomes da escala única; `sm` para linhas de lista densas. |
+| `disabled` | `boolean` | `false` | Esmaece e bloqueia a chave; o `Label` irmão posterior esmaece junto. |