@softize/opus 12.10.0 → 13.0.0

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

@@ -1,79 +1,348 @@
-## Sidebar
+## Navegação dentro de um layout
 
-`Sidebar` é uma coluna de chrome e navegação. Ela não escolhe a posição: entra em qualquer `Pane` de um `Split`. A mesma forma serve para a sidebar global do app e a navegação interna de Configurações.
+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`.
+
+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.
 
 ```tsx preview
 render(
-  <div className="h-72 overflow-hidden rounded-lg border border-border">
-    <Split resizable>
-      <Pane initialSize={32} minSize={20} inset="none">
-        <Sidebar divider={false} className="w-full">
-          <PaneHeader className="px-4 py-3 text-sm font-semibold">Projeto</PaneHeader>
-          <PaneContent>
+  <div className="h-80 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="16rem" inset="none">
+        <Sidebar className="w-full">
+          <PaneHeader className="px-4 py-3 text-sm font-semibold">
+            Projeto
+          </PaneHeader>
+          <PaneBody>
             <SidebarNav
-              groups={[{ label: 'Design', items: [{ id: 'preview', label: 'Preview' }, { id: 'code', label: 'Código' }] }]}
-              activeId="preview"
+              groups={[
+                {
+                  label: 'Workspace',
+                  items: [
+                    { id: 'overview', label: 'Visão geral', icon: <LayoutDashboard /> },
+                    { id: 'sessions', label: 'Sessões', icon: <MessagesSquare /> },
+                  ],
+                },
+              ]}
+              activeId="overview"
               onSelect={() => {}}
             />
-          </PaneContent>
-          <PaneFooter><span className="text-xs text-muted-foreground">Configurações</span></PaneFooter>
+          </PaneBody>
+          <PaneFooter>
+            <SidebarItem label="Configurações" icon={<Settings />} onClick={() => {}} />
+          </PaneFooter>
         </Sidebar>
       </Pane>
-      <Pane grow inset="lg"><p className="text-sm text-muted-foreground">Conteúdo da tela.</p></Pane>
+      <Pane grow inset="lg">
+        <p className="text-sm text-muted-foreground">Conteúdo da página.</p>
+      </Pane>
     </Split>
   </div>,
 )
 ```
 
-## Colapso
-
-`collapsed` pertence à própria `Sidebar`; `SidebarItem`, `SidebarNav` e `ShellNav` adaptam-se automaticamente para botões `size-9` centralizados, ícones e tooltips. `PaneHeader`, `PaneContent` e `PaneFooter` são os slots do pane: a aplicação mantém a identidade e ações que lhe pertencem sem atribuí-las artificialmente à sidebar.
-
-`SidebarItem` também é a linha de árvores de navegação. `actions` e o controle formado por
-`onToggle`/`expanded` são irmãos do botão principal, portanto menus e chevrons não criam
-controles interativos aninhados. No modo recolhido, a linha conserva somente o destino com
-ícone e tooltip. No modo aberto, o chevron ocupa o lugar do ícone da pasta durante o hover da própria linha ou
-foco, e as ações ficam sobrepostas à extremidade direita: controles invisíveis não reduzem o
-espaço disponível para o rótulo. O foco comum no destino não mantém o chevron aberto;
-somente o foco visível no próprio controle o revela para navegação por teclado.
-As ações aparecem no hover da própria linha, no foco visível do próprio controle ou enquanto o menu está
-aberto; focar o destino da linha não revela as reticências.
-O rótulo que não cabe na linha desaparece num gradiente até a borda, em vez de terminar em
-reticências; a linha mede o próprio transbordo, então o rótulo que cabe inteiro fica intacto.
-O foco visível usa o mesmo anel do `Button` (`ring-2 ring-ring/50`), na linha aberta, no botão do
-rail recolhido e no chevron — sem ele a navegação por teclado cairia no anel padrão do navegador,
-que destoa do tema.
-Durante drag-and-drop, `dropPosition="before"` e `"after"` desenham uma linha sobreposta ao
-limite do item; `"inside"` realça a superfície da pasta. O indicador nunca reserva espaço.
-
-Árvores montadas por composição usam `SidebarGroupLabel` para os mesmos rótulos discretos
-que o `SidebarNav` desenha automaticamente. O heading permanece `text-sm`; hierarquia vem
-do peso médio e da cor atenuada, não de reduzir legibilidade.
+Use `resizable` no `Split` somente quando ajustar a largura fizer parte da tarefa. Nesse caso, o
+`Pane` também declara `minSize`, e `divider={false}` evita que `Sidebar` desenhe uma segunda
+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.
+
+| Parte | Responsabilidade |
+|---|---|
+| `Split` | Define a relação espacial e, opcionalmente, o redimensionamento. |
+| `Pane` | Define largura, limites e espaçamento interno da coluna. |
+| `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` ou `ShellNav` | 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`.
+
+## Escolher a navegação
+
+Use `SidebarNav` para grupos planos de destinos. Ele recebe dados e produz `SidebarItem` com a mesma
+semântica usada na composição manual.
+
+```tsx preview
+<div className="h-72 w-64 overflow-hidden rounded-lg border border-border">
+  <Sidebar className="w-full">
+    <PaneBody>
+      <SidebarNav
+        groups={[
+          {
+            label: 'Configurações',
+            items: [
+              { id: 'users', label: 'Usuários', icon: <Users /> },
+              { id: 'roles', label: 'Papéis', icon: <ShieldCheck /> },
+              { id: 'imports', label: 'Importações', icon: <Database /> },
+            ],
+          },
+        ]}
+        activeId="users"
+        onSelect={() => {}}
+      />
+    </PaneBody>
+  </Sidebar>
+</div>
+```
+
+## Compor uma árvore
+
+Uma árvore não pertence ao contrato de `SidebarNav`: profundidade, carregamento e expansão variam
+por produto. Componha cada nó com `SidebarItem`, envolva seus descendentes em `SidebarTreeGroup` e
+mantenha o estado no consumidor. O grupo aplica o recuo e desenha a guia vertical; o destino
+principal e o controle de expansão permanecem irmãos acessíveis.
+
+```tsx preview
+const [open, setOpen] = useState(true)
+
+render(
+  <div className="h-72 w-64 overflow-hidden rounded-lg border border-border">
+    <Sidebar className="w-full">
+      <PaneBody className="p-2">
+        <SidebarGroupLabel>Documentação</SidebarGroupLabel>
+        <SidebarItem
+          label="Componentes"
+          icon={<Folder />}
+          expanded={open}
+          onToggle={() => setOpen((current) => !current)}
+          onClick={() => setOpen((current) => !current)}
+        />
+        {open && (
+          <SidebarTreeGroup>
+            <SidebarItem label="Layout" icon={<Folder />} expanded onToggle={() => {}} onClick={() => {}} />
+            <SidebarTreeGroup>
+              <SidebarItem label="Sidebar" icon={<PanelLeft />} active onClick={() => {}} />
+              <SidebarItem label="Page" icon={<PanelsTopLeft />} onClick={() => {}} />
+            </SidebarTreeGroup>
+          </SidebarTreeGroup>
+        )}
+      </PaneBody>
+    </Sidebar>
+  </div>,
+)
+```
+
+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}>
-  <PaneHeader><MySidebarHeader onToggle={() => setCollapsed(!collapsed)} /></PaneHeader>
-  <PaneContent><SidebarNav groups={groups} activeId={active} onSelect={go} /></PaneContent>
-  <PaneFooter><UserMenu /></PaneFooter>
+  <ShellNav
+    heading={<ShellNavHeading title="Relatórios" action={<CreateReportButton />} />}
+    groups={reportGroups}
+    footer={settingsGroups}
+    activeId={activeId}
+    onSelect={navigateToReport}
+  />
 </Sidebar>
 ```
 
-## Navegação contextual
+## Recolher a coluna
 
-`SidebarNav` aceita grupos e subgrupos. Isso cobre tanto a navegação global quanto seções internas, como Configurações ou documentação, sem outro shell especializado.
+`collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem`, `SidebarNav` e `ShellNav` 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.
 
-```tsx
-<SidebarNav
-  groups={[
-    {
-      label: 'Configurações',
-      subgroups: [
-        { label: 'Acesso', items: [{ id: 'users', label: 'Usuários' }] },
-        { label: 'Dados', items: [{ id: 'imports', label: 'Importações' }] },
-      ],
-    },
-  ]}
-  activeId={active}
-  onSelect={go}
-/>
+```tsx preview
+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>
+      <PaneBody>
+        <SidebarNav
+          groups={[
+            {
+              items: [
+                { id: 'home', label: 'Início', icon: <House /> },
+                { id: 'reports', label: 'Relatórios', icon: <ChartNoAxesColumn /> },
+              ],
+            },
+          ]}
+          activeId="home"
+          onSelect={() => {}}
+        />
+      </PaneBody>
+    </Sidebar>
+    <div className="flex-1 p-4 text-sm text-muted-foreground">
+      O conteúdo ocupa o espaço liberado pela sidebar.
+    </div>
+  </div>,
+)
+```
+
+O consumidor controla o estado e decide onde colocar o gatilho. A transição de largura pertence à
+`Sidebar`; a aplicação não precisa trocar a árvore de componentes.
+
+## Itens com expansão e ações
+
+`SidebarItem` mantém o destino principal, a expansão e as ações como controles irmãos. Essa
+estrutura evita botões aninhados e permite que cada controle receba foco de forma independente.
+
+```tsx preview
+<div className="w-72 rounded-lg border border-border p-2">
+  <SidebarItem
+    label="Contratos"
+    icon={<Folder />}
+    expanded
+    onToggle={() => {}}
+    actions={
+      <Button variant="ghost" size="icon-xs" aria-label="Mais ações">
+        <Ellipsis />
+      </Button>
+    }
+    onClick={() => {}}
+  />
+  <SidebarItem
+    label="Criar workspace"
+    icon={<FilePlus2 />}
+    className="pl-6"
+    onClick={() => {}}
+  />
+</div>
 ```
+
+Quando o rótulo não cabe, ele termina em um gradiente. As ações aparecem ao passar o ponteiro, ao
+receber foco visível ou enquanto um menu permanece aberto; como são sobrepostas, não reduzem o
+espaço disponível para o texto.
+
+Para árvores arrastáveis, `dropPosition` comunica o destino visual sem reservar espaço:
+`before` e `after` desenham uma linha na fronteira, enquanto `inside` realça a superfície do item.
+O driver de drag-and-drop continua externo e fornece seus atributos por `dragProps`.
+
+## Acessibilidade
+
+- `activeId` resulta em `aria-current="page"` no destino atual.
+- `navLabel` nomeia a landmark de navegação.
+- O controle de expansão informa `aria-expanded` e recebe um rótulo baseado no item.
+- Itens desabilitados continuam visíveis, mas não respondem à interação.
+- O foco visível usa o anel semântico do tema no destino, nas ações e no controle de expansão.
+- No modo recolhido, o tooltip preserva o nome que deixou de aparecer visualmente.
+
+## Propriedades de Sidebar
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `collapsed` | `boolean` | `false` | Recolhe a coluna e publica esse estado para as navegações descendentes. |
+| `divider` | `boolean` | `true` | Desenha a borda na lateral. Desative quando o `Split` já fornecer o handle. |
+| `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é. |
+
+## Propriedades de SidebarNav
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `groups` | `SidebarNavGroup[]` | | Grupos e itens apresentados na ordem recebida. Grupos vazios são omitidos. |
+| `activeId` | `string` | | Identificador do destino atual. |
+| `onSelect` | `(id: string) => void` | | Recebe o identificador selecionado; roteamento permanece com o consumidor. |
+| `navLabel` | `string` | `'Navegação'` | Nome acessível da landmark `nav`. |
+| `className` | `string` | | Ajusta a raiz da navegação. |
+
+### Estrutura de SidebarNavGroup
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `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.
+
+## Propriedades de SidebarItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `string` | | Nome visível do destino e conteúdo do tooltip no modo recolhido. |
+| `icon` | `ReactNode` | | Ícone apresentado antes do rótulo e preservado no modo recolhido. |
+| `badge` | `ReactNode` | | Informação curta no fim da linha, como contagem ou estado. |
+| `active` | `boolean` | `false` | Destaca o destino e aplica `aria-current="page"`. |
+| `disabled` | `boolean` | `false` | Mantém o item visível sem permitir interação. |
+| `actions` | `ReactNode` | | Controles relacionados exibidos no fim da linha. |
+| `onToggle` | `() => void` | | Adiciona o controle independente de expansão. |
+| `expanded` | `boolean` | `false` | Define o estado acessível e a rotação do controle de expansão. |
+| `dropPosition` | `'before' \| 'inside' \| 'after'` | | Indica visualmente onde um item arrastado será solto. |
+| `dragProps` | `HTMLAttributes<HTMLDivElement>` | | Encaminha atributos fornecidos pelo driver de drag-and-drop para a linha. |
+| `tooltipHint` | `ReactNode` | | Acrescenta contexto ao tooltip do modo recolhido. |
+| `className` | `string` | | Ajusta a linha nos estados aberto e recolhido. |
+| `onClick` | `() => void` | | Executa a navegação principal do item. |
+
+## Propriedades de SidebarGroupLabel
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta o rótulo discreto do grupo. |
+| `children` | `ReactNode` | | Nome do conjunto de destinos. |
+
+## Propriedades de SidebarTreeGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `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

@@ -1,6 +1,7 @@
 ## Linha de lista com avatar
 
-O skeleton imita a forma do conteúdo: círculo pro avatar (rounded-full), barras com a largura aproximada do texto.
+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.
 
 ```tsx preview col
 <div className="flex items-center gap-3">
@@ -14,7 +15,7 @@ O skeleton imita a forma do conteúdo: círculo pro avatar (rounded-full), barra
 
 ## Card em carregamento
 
-O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — pra tela não pular quando os dados chegarem.
+O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para tela não pular quando os dados chegarem.
 
 ```tsx preview col
 <Card>
@@ -22,10 +23,10 @@ O esqueleto reproduz o layout final do card — título, descrição, conteúdo
     <Skeleton className="h-5 w-40" />
     <Skeleton className="h-4 w-56" />
   </CardHeader>
-  <CardContent className="space-y-2">
+  <CardBody className="space-y-2">
     <Skeleton className="h-4 w-full" />
     <Skeleton className="h-4 w-3/4" />
-  </CardContent>
+  </CardBody>
   <CardFooter className="gap-2">
     <Skeleton className="h-8 w-28" />
     <Skeleton className="h-8 w-24" />

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

@@ -1,6 +1,7 @@
-## Básico
+## Um valor na faixa
 
-defaultValue é um array — [n] pra um thumb. min, max e step delimitam a faixa; aqui de 0 a 100 em passos de 5.
+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.
 
 ```tsx preview col
 <Slider defaultValue={[40]} min={0} max={100} step={5} />
@@ -8,7 +9,7 @@ defaultValue é um array — [n] pra um thumb. min, max e step delimitam a faixa
 
 ## Controlado
 
-onValueChange recebe o array atualizado — leia value[0] pra um thumb. Bom pra mostrar o valor escolhido ao lado do rótulo.
+`onValueChange` recebe o array atualizado. Para um único controle, leia `value[0]`.
 
 ```tsx preview col
 const [parallelism, setParallelism] = useState([4])
@@ -26,7 +27,7 @@ render(
 
 ## Intervalo
 
-value com dois números rende dois thumbs e a faixa fica entre eles — o jeito de filtrar por um intervalo, como o custo estimado de uma task.
+Dois números em `value` criam um intervalo selecionável entre dois controles.
 
 ```tsx preview col
 const [budget, setBudget] = useState([20, 60])
@@ -50,11 +51,11 @@ disabled esmaece o trilho e o thumb e bloqueia o arraste — o valor fica congel
 <Slider defaultValue={[70]} min={0} max={100} disabled />
 ```
 
-## Props
+## Propriedades de Slider
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `number[]` | | O valor no modo controlado — [n] pra um thumb, [a, b] pra um intervalo. Pareie com onValueChange. |
+| `value` | `number[]` | | O valor no modo controlado — [n] para um thumb, [a, b] para um intervalo. Pareie com onValueChange. |
 | `onValueChange` | `(value: number[]) => void` | | Chamado a cada arraste, com o array atualizado. |
 | `defaultValue` | `number[]` | | Valor inicial no modo não controlado. |
 | `min` | `number` | `0` | Limite inferior da faixa. |

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

@@ -1,7 +1,7 @@
-## Tamanhos
+## Carregamento sem progresso conhecido
 
-Divergência da casa: o shadcn atual só tem size-4 fixo; mantivemos sm/default/lg pra cobrir botão
-(sm) e estados maiores (lg). O aria-label Carregando já vem embutido.
+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”.
 
 ```tsx preview
 <Spinner size="sm" />
@@ -11,8 +11,8 @@ Divergência da casa: o shadcn atual só tem size-4 fixo; mantivemos sm/default/
 
 ## No botão
 
-Ação em andamento: disabled + Spinner sm + verbo no gerúndio — substitui o Loader2Icon inline
-repetido.
+Durante uma ação, combine o spinner compacto com o estado desabilitado e um rótulo que descreva o
+andamento.
 
 ```tsx preview
 <Button disabled><Spinner size="sm" /> Publicando…</Button>
@@ -30,8 +30,8 @@ Skeleton.
 </div>
 ```
 
-## Props
+## Propriedades de Spinner
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | O tamanho — sm pra dentro de botão, lg pra estados de página. |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | O tamanho — sm para dentro de botão, lg para estados de página. |

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

@@ -1,6 +1,8 @@
-## Split & Pane
+## Dividir uma área
 
-`Split` organiza áreas lado a lado ou uma sobre a outra. A ordem dos `Pane` define a posição de cada área. Sem `resizable`, o layout usa flex; com essa opção, a pessoa também pode ajustar as divisórias com ponteiro ou teclado.
+Use `Split` para organizar áreas lado a lado ou empilhadas. A ordem dos `Pane` define a posição. Com
+`resizable`, a pessoa pode ajustar as divisórias por ponteiro ou teclado; sem essa propriedade, o
+layout permanece estático.
 
 ```tsx preview
 render(
@@ -17,11 +19,12 @@ render(
 )
 ```
 
-## Inset
+## Espaçamento interno
 
-O `Pane` traz `inset="md"` por default. Use `none` para chrome, navegação e conteúdo que já possui padding próprio; `sm` e `lg` atendem densidades comuns. `className` sempre pode ajustar o caso específico.
+`Pane` usa `inset="md"` por padrão. Use `none` para navegação e conteúdo que já controla o próprio
+espaçamento; `sm` e `lg` atendem outras densidades.
 
-## Rail
+## Largura inicial
 
 Quando uma área precisa continuar legível em telas largas, use uma unidade absoluta para o tamanho inicial ou mínimo. Números continuam representando porcentagens; strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Prefira `rem` para acompanhar a escala tipográfica configurada pela aplicação.
 

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

@@ -7,10 +7,8 @@ title: Armazenamento
 > **Experimental.** Superfície mínima, sem consumidor interno ainda — cresce por
 > reincidência de caso real, não por especulação.
 
-Upload, download, remoção e URL de acesso — o que backoffice precisa de arquivos
-(anexo de nota, foto de produto, contrato). O contrato é um adapter do core
-(`StorageAdapter`): a key é um **caminho lógico** (`clientes/123/contrato.pdf`) e o
-driver resolve onde ela mora.
+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.
 
 ## O contrato
 
@@ -23,8 +21,8 @@ interface StorageAdapter {
 }
 ```
 
-Keys passam pela mesma régua em todo driver (`normalizeKey`): relativas, sem `..`,
-sem `\` — traversal é barrado no contrato, não em cada driver.
+`normalizeKey` aplica a mesma validação a todos os drivers: chaves são relativas e não aceitam
+`..` nem `\`. Assim, tentativas de escapar do diretório são bloqueadas antes do armazenamento.
 
 ## Drivers
 
@@ -44,7 +42,7 @@ const prod = s3Storage({
 })
 ```
 
-Os peers do S3 são **opcionais** (`@aws-sdk/client-s3`; `s3-request-presigner` pro
+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.
 
 ## No runtime
@@ -62,7 +60,7 @@ handler: async (ctx, input) => {
 }
 ```
 
-## Limites (por enquanto)
+## 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

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

@@ -1,6 +1,7 @@
-## Básico
+## Alternar uma preferência
 
-Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a chave. defaultChecked pro modo não controlado.
+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.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -11,7 +12,7 @@ Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a chave. defa
 
 ## Controlado
 
-onCheckedChange recebe um boolean — pareie com checked pra guardar o estado no componente que decide.
+Use `checked` e `onCheckedChange` quando o estado pertencer ao consumidor.
 
 ```tsx preview
 const [autoReview, setAutoReview] = useState(true)
@@ -30,7 +31,7 @@ render(
 
 ## Tamanho sm
 
-size=sm encolhe a chave — pra densidade em linha de lista, como cada repositório do workspace.
+Use `size="sm"` em linhas de lista e outras composições compactas.
 
 ```tsx preview col-start
 <div className="flex items-center gap-2">
@@ -58,12 +59,12 @@ disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em p
 </div>
 ```
 
-## Props
+## Propriedades de Switch
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `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 pra densidade em linha de lista. |
+| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave — sm para densidade em linha de lista. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |