@softize/opus 12.11.0 → 13.0.0

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). |

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

@@ -1,6 +1,8 @@
 ## Tabela de domínio
 
-A Table vem SEM borda externa — só as divisórias de linha (a última o TableBody zera). Coluna numérica alinha à direita (text-right no TableHead E no TableCell). A TableCaption fica embaixo (caption-bottom) e descreve a tabela.
+Use `Table` para dados organizados em linhas e colunas. A variante padrão não possui borda externa;
+`TableBody` mantém somente as divisórias internas. Aplique `text-right` ao cabeçalho e às células
+quando o domínio pedir alinhamento numérico. `TableCaption` descreve a tabela abaixo do conteúdo.
 
 ```tsx preview col
 <Table>
@@ -36,7 +38,7 @@ A Table vem SEM borda externa — só as divisórias de linha (a última o Table
 </Table>
 ```
 
-## Moldura (o datagrid da casa)
+## Tabela emoldurada
 
 A variante `framed` aplica no próprio contêiner a borda externa, os cantos arredondados, o
 scroll horizontal contido e o fundo discreto do cabeçalho. A última linha já vem sem divisória,
@@ -69,7 +71,8 @@ pesquisáveis derivadas de actions `kind: 'list'`.
 
 ## Com rodapé (TableFooter)
 
-TableFooter fecha a tabela com a linha de agregação — fundo muted e peso de fonte já vêm prontos.
+Use `TableFooter` para totais ou outras agregações. O componente aplica fundo muted e peso de fonte
+adequados a essa região.
 
 ```tsx preview col
 <Table>
@@ -101,3 +104,10 @@ TableFooter fecha a tabela com a linha de agregação — fundo muted e peso de
   </TableFooter>
 </Table>
 ```
+
+## Propriedades de Table
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'plain' \| 'framed'` | `'plain'` | Escolhe entre a estrutura sem moldura externa e o contêiner emoldurado. |
+| `className` | `string` | | Classes aplicadas ao elemento `table`. |

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

@@ -1,6 +1,8 @@
-## Padrão (pill)
+## Alternar painéis relacionados
 
-O value do TabsTrigger pareia com o do TabsContent. defaultValue deixa o estado com o componente; pra controlar, use value + onValueChange.
+Use `Tabs` para alternar painéis relacionados no mesmo contexto. O `value` de cada `TabsTrigger`
+corresponde ao `TabsContent` que ele abre. `defaultValue` define a aba inicial no modo não
+controlado.
 
 ```tsx preview col
 <Tabs defaultValue="sessions">
@@ -23,7 +25,8 @@ O value do TabsTrigger pareia com o do TabsContent. defaultValue deixa o estado
 
 ## Variante line
 
-variant=line na TabsList: fundo transparente, o ativo é marcado pelo traço embaixo — bom pra cabeçalho de página, onde o pill pesaria.
+Use `variant="line"` em `TabsList` quando a lista precisar se integrar a uma borda, como em um
+cabeçalho. A aba ativa é marcada por uma linha em vez de uma superfície preenchida.
 
 ```tsx preview col
 <Tabs defaultValue="agents">
@@ -46,7 +49,8 @@ variant=line na TabsList: fundo transparente, o ativo é marcado pelo traço emb
 
 ## Vertical
 
-orientation=vertical no Tabs: a lista vira coluna e o traço da variante line migra pra lateral direita do trigger.
+Com `orientation="vertical"`, a lista forma uma coluna e a marca da variante `line` passa para a
+lateral do gatilho.
 
 ```tsx preview col
 <Tabs defaultValue="prompt" orientation="vertical">
@@ -67,7 +71,7 @@ orientation=vertical no Tabs: a lista vira coluna e o traço da variante line mi
 </Tabs>
 ```
 
-## Densidade (size)
+## Tamanho
 
 `size="sm"` no `Tabs` reduz a lista de `h-9` (2.25rem) para `h-8` (2rem). É o par do `sm` de Button e Select para uma fileira densa, como uma toolbar ou um cabeçalho, em que o segmento não deve ficar mais alto que os elementos vizinhos.
 
@@ -81,14 +85,24 @@ orientation=vertical no Tabs: a lista vira coluna e o traço da variante line mi
 </Tabs>
 ```
 
-## Props
+## Propriedades de Tabs
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `defaultValue (Tabs)` | `string` | | A aba inicial no modo não-controlado. |
-| `value (Tabs)` | `string` | | A aba ativa no modo controlado — pareie com onValueChange. |
-| `onValueChange (Tabs)` | `(value: string) => void` | | Chamado quando o usuário troca de aba. |
-| `size (Tabs)` | `'default' \| 'sm'` | `'default'` | Altura da lista: default (h-9) ou sm (h-8), o par do sm de Button/Select. Flui pra TabsList por contexto. |
-| `orientation (Tabs)` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas — vertical vira coluna lateral. |
-| `variant (TabsList)` | `'default' \| 'line'` | `'default'` | default é o pill (fundo muted); line é a barra sublinhada, sem fundo. |
-| `value (TabsTrigger/TabsContent)` | `string` | | Identificador que pareia o trigger com o painel correspondente. |
+| `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`. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas. |
+
+## Propriedades de TabsList
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'default' \| 'line'` | `'default'` | `default` usa uma superfície preenchida; `line` marca a aba ativa junto à borda. |
+
+## Propriedades de TabsTrigger e TabsContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Identificador que associa o gatilho ao painel correspondente. |

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

@@ -4,16 +4,14 @@ title: Testes de action
 
 # Testes de action
 
-A unidade natural de teste no Opus é a **action** — o contrato: input → output/erro,
-bordas do schema, autorização fail-closed. `@softize/opus/testing` roda esse contrato
-em unidade, sem montar runtime nem mockar contexto à mão.
+Teste cada action pela fronteira do contrato: entrada, saída ou erro, limites do schema e
+autorização. `@softize/opus/testing` executa esse fluxo em unidade sem montar o runtime completo.
 
-## runAction — o contrato em unidade
+## Executar o contrato em unidade
 
-O harness executa o **mesmo pipeline do runtime**: valida o input → cobra o gate
-`public` → avalia o `authorize` (string DSL ou closure, semântica idêntica) → roda o
-handler → valida o output. Falha estoura o mesmo `ActionError` tipado do runtime
-(`validation.invalid_input`, `auth.unauthenticated`, `auth.forbidden`…).
+`runAction` valida a entrada, aplica o gate `public`, avalia `authorize`, executa o handler e valida
+a saída. Falhas usam o mesmo `ActionError` tipado do runtime, como `validation.invalid_input`,
+`auth.unauthenticated` e `auth.forbidden`.
 
 ```ts
 import { runAction } from '@softize/opus/testing'
@@ -45,7 +43,7 @@ it('só a dona edita', async () => {
 
 ## Contexto observável
 
-`runAction` (e `testContext`, pra quem quer só o ctx) devolve os efeitos capturados —
+`runAction` (e `testContext`, para quem quer só o ctx) devolve os efeitos capturados —
 o teste afirma o que importa:
 
 ```ts
@@ -55,7 +53,7 @@ expect(emitted).toEqual([{ event: 'task.done', data: { id: '1' } }])
 
 ## memStorage
 
-`StorageAdapter` em memória com a mesma régua de key dos drivers reais — pra handler
+`StorageAdapter` em memória com a mesma régua de key dos drivers reais — para handler
 que anexa arquivo:
 
 ```ts
@@ -81,7 +79,7 @@ const many = fakeMany(EventEntity.zod(), 20) // 20, estáveis entre execuções
 fake(schema, { seed: 7 }) // seed própria
 ```
 
-## O que fica de fora
+## Limites do teste de unidade
 
 De propósito — é harness de **unidade**: loaders reais (passe `loaded` pronto), audit,
 reactions em cadeia e o servidor. Fluxo completo é teste de integração com o runtime.

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

@@ -1,6 +1,7 @@
-## Básico
+## Texto com várias linhas
 
-Cresce com o conteúdo a partir da altura mínima (field-sizing-content) — digite e veja.
+Use `Textarea` para texto livre com várias linhas. O campo cresce com o conteúdo a partir de sua
+altura mínima.
 
 ```tsx preview col md
 <Textarea placeholder="Descreva o que o agente deve fazer nesta sessão." />
@@ -8,7 +9,7 @@ Cresce com o conteúdo a partir da altura mínima (field-sizing-content) — dig
 
 ## Com Label
 
-O mesmo par htmlFor↔id dos outros campos — o overview do handoff é o caso típico.
+Associe `htmlFor` no `Label` ao `id` do campo para manter o rótulo acessível.
 
 ```tsx preview col md
 <div className="grid gap-2">
@@ -22,7 +23,7 @@ O mesmo par htmlFor↔id dos outros campos — o overview do handoff é o caso t
 
 ## Estados
 
-aria-invalid pinta borda e anel destructive; disabled esmaece e bloqueia a edição.
+`aria-invalid` comunica e apresenta o estado inválido; `disabled` bloqueia a edição.
 
 ```tsx preview col md
 <Textarea aria-invalid placeholder="Conte o contexto da mudança." />

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

@@ -1,6 +1,9 @@
-## Tipos
+## Notificação temporária
 
-Cada tipo já vem com o ícone lucide do Opus. O título é label (sem ponto); a description, frase (com ponto).
+Use `toast` para informar o resultado temporário de uma ação sem interromper o fluxo. Cada tipo usa o
+ícone correspondente do Opus. Escreva o título como rótulo, sem ponto final, e a descrição como uma
+frase. A moldura do ícone permanece quadrada e alinhada à primeira linha mesmo quando a descrição
+ocupa várias linhas.
 
 ```tsx preview
 <Button variant="outline" onClick={() => toast.success('Workspace criado')}>Sucesso</Button>
@@ -13,22 +16,34 @@ Cada tipo já vem com o ícone lucide do Opus. O título é label (sem ponto); a
 <Button variant="outline" onClick={() => toast.info('Base atualizada')}>Info</Button>
 <Button
   variant="outline"
-  onClick={() => toast.warning('Preview parado', { description: 'Inicie o ambiente pra ver a sessão.' })}
+  onClick={() => toast.warning('Preview parado', { description: 'Inicie o ambiente para ver a sessão.' })}
 >
   Aviso
 </Button>
 ```
 
-## Ação e progresso
+## Ações e progresso
 
-action põe um botão no toast (ex.: desfazer); toast.promise acompanha uma operação — loading vira sucesso ou erro sozinho.
+`actions` recebe uma coleção ordenada de ações compactas. A última ação ganha destaque primário por
+padrão; as anteriores usam tratamento neutro e podem declarar `context` e `variant` quando a
+hierarquia precisar ser diferente. A região fica alinhada ao fim lógico da superfície, no mesmo
+canto usado pelas ações do Alert. O clique fecha o toast, salvo quando o handler chama
+`event.preventDefault()`.
+
+Na versão 13, `actions` substitui os campos `action` e `cancel` da versão 12. Migre cada controle
+para uma entrada da coleção e preserve a ordem visual desejada.
+
+`toast.promise` acompanha uma promessa e atualiza a mesma notificação nos estados de carregamento,
+sucesso ou erro.
 
 ```tsx preview
 <Button
   variant="outline"
   onClick={() =>
     toast('Sessão arquivada', {
-      action: { label: 'Desfazer', onClick: () => toast.success('Sessão restaurada') },
+      actions: [
+        { label: 'Desfazer', onClick: () => toast.success('Sessão restaurada') },
+      ],
     })
   }
 >
@@ -48,9 +63,10 @@ action põe um botão no toast (ex.: desfazer); toast.promise acompanha uma oper
 </Button>
 ```
 
-## Toaster no root
+## Toaster na raiz
 
-Monte uma vez, fora do App. Divergência declarada: sem next-themes — o tema vem por prop (default 'system'); a elevação dark usa bg-popover.
+Monte um único `Toaster` na raiz do aplicativo. O tema vem da propriedade `theme`, cujo padrão é
+`system`; não há dependência de `next-themes`.
 
 ```tsx
 /* main.tsx do app — uma vez. */
@@ -58,10 +74,28 @@ Monte uma vez, fora do App. Divergência declarada: sem next-themes — o tema v
 <Toaster />
 ```
 
-## Props
+## Propriedades de Toaster
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Define o tema das notificações; sem `next-themes`, a escolha pertence ao aplicativo. |
+| `position` | `'bottom-right' \| 'top-center' \| …` | `'bottom-right'` | Região da tela onde as notificações aparecem. |
+
+## Opções de toast
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `description` | `React.ReactNode` | | Complemento exibido abaixo do título. |
+| `actions` | `ToastAction[]` | | Coleção ordenada de ações; a última recebe destaque primário por padrão. |
+| `duration` | `number` | do Sonner | Tempo de permanência da notificação. |
+
+## Propriedades de ToastAction
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `Toaster.theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Força o tema dos toasts — sem next-themes, a escolha é do app. |
-| `Toaster.position` | `'bottom-right' \| 'top-center' \| …` | `'bottom-right'` | Canto onde os toasts aparecem (sonner). |
-| `toast(title, opts)` | `{ description?, action?, duration?, … }` | | A API de disparo (sonner): descrição, botão de ação e duração por toast. |
+| `label` | `React.ReactNode` | obrigatório | Conteúdo visível da ação. |
+| `onClick` | `(event: React.MouseEvent<HTMLButtonElement>) => void` | obrigatório | Executa a ação. Chame `event.preventDefault()` para manter o toast aberto. |
+| `context` | `ButtonContext` | última: `'primary'`; anteriores: `'neutral'` | Define a intenção semântica do botão. |
+| `variant` | `ButtonVariant` | última: `'solid'`; anteriores: `'ghost'` | Define o tratamento visual do botão. |
+| `disabled` | `boolean` | `false` | Impede a interação com a ação. |
+| `key` | `React.Key` | posição na coleção | Mantém a identidade da ação entre renderizações. |

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

@@ -1,6 +1,7 @@
-## Básico
+## Alternar um estado
 
-Um botão que lembra se está ligado. defaultPressed deixa o estado com o componente; o filho costuma ser um ícone.
+Use `Toggle` para uma ação que alterna entre ligada e desligada. `defaultPressed` define o estado
+inicial no modo não controlado; o conteúdo pode ser texto ou ícone.
 
 ```tsx preview
 <Toggle defaultPressed aria-label="Negrito">
@@ -10,7 +11,7 @@ Um botão que lembra se está ligado. defaultPressed deixa o estado com o compon
 
 ## Controlado
 
-pressed + onPressedChange tiram o estado do componente — o booleano fica no seu store. Bom pra alternar o modo somente-leitura de uma sessão.
+Use `pressed` e `onPressedChange` quando o estado pertencer ao consumidor.
 
 ```tsx preview
 const [readOnly, setReadOnly] = useState(true)
@@ -29,7 +30,8 @@ render(
 
 ## Variantes e tamanhos
 
-variant default não tem borda (o fundo só aparece ativo); outline carrega a borda. size sm/default/lg ajusta a altura.
+Na variante `default`, o fundo aparece somente quando o controle está ativo; `outline` mantém a
+borda. `size` ajusta a altura.
 
 ```tsx preview
 <Toggle aria-label="Quebra de linha">
@@ -60,13 +62,79 @@ disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
 </Toggle>
 ```
 
-## Props
+## Propriedades de Toggle
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `pressed` | `boolean` | | O estado ligado/desligado no modo controlado — parear com onPressedChange. |
 | `onPressedChange` | `(pressed: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultPressed` | `boolean` | `false` | Estado inicial no modo não controlado. |
 | `variant` | `'default' \| 'outline'` | `'default'` | default não tem borda (fundo só quando ativo); outline carrega a borda. |
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura do botão — sm pra toolbar densa, lg pra alvo mais confortável. |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura do botão — sm para toolbar densa, lg para alvo mais confortável. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |
+
+## ToggleGroup
+
+Use `ToggleGroup` quando vários toggles formarem uma única escolha ou uma coleção de estados
+relacionados. `type="single"` mantém um item ativo; `type="multiple"` aceita vários.
+
+### Escolha única
+
+```tsx preview
+const [view, setView] = useState('sessions')
+
+render(
+  <ToggleGroup type="single" value={view} onValueChange={(v) => v && setView(v)}>
+    <ToggleGroupItem value="overview">Visão geral</ToggleGroupItem>
+    <ToggleGroupItem value="sessions">Sessões</ToggleGroupItem>
+    <ToggleGroupItem value="skills">Habilidades</ToggleGroupItem>
+  </ToggleGroup>,
+)
+```
+
+### Escolha múltipla
+
+```tsx preview
+const [marks, setMarks] = useState(['bold'])
+
+render(
+  <ToggleGroup type="multiple" value={marks} onValueChange={setMarks}>
+    <ToggleGroupItem value="bold" aria-label="Negrito"><Bold /></ToggleGroupItem>
+    <ToggleGroupItem value="italic" aria-label="Itálico"><Italic /></ToggleGroupItem>
+    <ToggleGroupItem value="underline" aria-label="Sublinhado"><Underline /></ToggleGroupItem>
+  </ToggleGroup>,
+)
+```
+
+### Variante e espaçamento
+
+`variant`, `size` e `shape` definidos no grupo chegam aos itens por contexto. `spacing` separa os
+itens; com zero, eles formam um bloco contínuo.
+
+```tsx preview
+<ToggleGroup type="single" variant="outline" spacing={2} defaultValue="developer">
+  <ToggleGroupItem value="developer">developer</ToggleGroupItem>
+  <ToggleGroupItem value="reviewer">reviewer</ToggleGroupItem>
+  <ToggleGroupItem value="designer">designer</ToggleGroupItem>
+</ToggleGroup>
+```
+
+### Propriedades de ToggleGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `type` | `'single' \| 'multiple'` | | Define seleção única (`string`) ou múltipla (`string[]`). |
+| `value` | `string \| string[]` | | Seleção controlada; o tipo acompanha `type`. |
+| `onValueChange` | `(value: string \| string[]) => void` | | Informa a nova seleção. No modo single, uma string vazia representa nenhum item ativo. |
+| `defaultValue` | `string \| string[]` | | Seleção inicial no modo não controlado. |
+| `variant` | `'default' \| 'outline'` | `'default'` | Tratamento visual repassado aos itens. |
+| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Tamanho repassado aos itens. |
+| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do grupo e de suas extremidades. |
+| `spacing` | `number` | `0` | Distância entre os itens em unidades de spacing. |
+
+### Propriedades de ToggleGroupItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Identificador que entra no valor do grupo quando o item é ativado. |
+| `disabled` | `boolean` | `false` | Bloqueia somente este item e preserva seu estado visual. |

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

@@ -4,7 +4,7 @@ title: Tokens & Tema
 
 # Tokens & Tema
 
-O tema canônico vive no Opus (`theme.css`): tokens com a cor inteira na var, mapeados pro
+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
 e a página acompanha.
 
@@ -170,7 +170,7 @@ render(
 > A regra anti-drift: o que não está declarado aqui (e no `theme.css`) é drift e deve ser
 > sincronizado — skill `build-opus-ui`.
 
-1. Formato HSL nos tokens (o upstream migrou pra oklch) — legibilidade e ferramentas nossas; os
+1. Formato HSL nos tokens (o upstream migrou para oklch) — legibilidade e ferramentas nossas; os
    valores acompanham o upstream, só o formato difere.
 2. Elevação no dark: `--card`/`--popover` ficam ACIMA de `--background` (10% vs 3.9%) — identidade
    da casa; dialog e card "sobem" da página de verdade.
@@ -192,7 +192,7 @@ render(
 
 ## Identidade por app
 
-> O tema do Opus é a base; cada app sobrescreve as vars pra ter a própria identidade sem forkar componente.
+> O tema do Opus é a base; cada app sobrescreve as vars para ter a própria identidade sem forkar componente.
 
 ```css
 /* index.css do app — depois do import do tema. */