@softize/opus 12.10.0 → 13.0.0

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>
@@ -17,26 +19,26 @@ A Table vem SEM borda externa — só as divisórias de linha (a última o Table
     <TableRow>
       <TableCell className="font-medium">Importar pedidos da transportadora</TableCell>
       <TableCell>developer</TableCell>
-      <TableCell><Badge variant="info">Em sessão</Badge></TableCell>
+      <TableCell><Badge context="info">Em sessão</Badge></TableCell>
       <TableCell className="text-right">42 min</TableCell>
     </TableRow>
     <TableRow>
       <TableCell className="font-medium">Revisar contrato de rastreio</TableCell>
       <TableCell>reviewer</TableCell>
-      <TableCell><Badge variant="warning">Aguardando revisor</Badge></TableCell>
+      <TableCell><Badge context="warning">Aguardando revisor</Badge></TableCell>
       <TableCell className="text-right">18 min</TableCell>
     </TableRow>
     <TableRow>
       <TableCell className="font-medium">Ajustar microcopy do painel</TableCell>
       <TableCell>designer</TableCell>
-      <TableCell><Badge variant="success">Concluída</Badge></TableCell>
+      <TableCell><Badge context="success">Concluída</Badge></TableCell>
       <TableCell className="text-right">7 min</TableCell>
     </TableRow>
   </TableBody>
 </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.
 
@@ -43,6 +43,34 @@ render(
 )
 ```
 
+## Famílias contextuais
+
+Os tokens `primary`, `secondary` e `destructive` acima permanecem fundações de superfície. A API
+dos componentes usa famílias contextuais para separar significado de tratamento visual: cada
+família oferece sólido, foreground, superfície sutil, ênfase e borda. Use as props `context` e
+`variant`; classes contextuais diretas ficam reservadas à implementação dos primitives.
+
+```tsx preview
+const CONTEXTS = ['neutral', 'primary', 'info', 'success', 'warning', 'danger']
+render(
+  <div className="grid w-full gap-2 sm:grid-cols-2 lg:grid-cols-3">
+    {CONTEXTS.map((context) => (
+      <div
+        key={context}
+        className="rounded-md border px-3 py-2 text-sm"
+        style={{
+          backgroundColor: `var(--context-${context}-subtle)`,
+          borderColor: `var(--context-${context}-border)`,
+          color: `var(--context-${context}-emphasis)`,
+        }}
+      >
+        {context}
+      </div>
+    ))}
+  </div>,
+)
+```
+
 ## Linhas e foco
 
 > Bordas e o anel de foco também são tokens — nada de cinza hardcoded. A aresta de superfície
@@ -142,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.
@@ -164,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. */

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

@@ -1,6 +1,8 @@
-## Básico
+## Informação complementar
 
-Texto auxiliar, nunca essencial — quem navega por toque não vê tooltip. Em botão só de ícone, o aria-label continua obrigatório.
+Use `Tooltip` para informação curta e complementar. Como a dica não está disponível em todas as
+formas de interação, ela não pode conter informação essencial. Botões somente com ícone continuam
+precisando de `aria-label`.
 
 ```tsx preview
 <Tooltip>
@@ -13,7 +15,7 @@ Texto auxiliar, nunca essencial — quem navega por toque não vê tooltip. Em b
 
 ## Lados
 
-side escolhe o lado preferido; o Radix inverte sozinho quando falta espaço.
+`side` define o lado preferido; o Radix reposiciona a dica quando não há espaço.
 
 ```tsx preview
 <Tooltip>
@@ -30,9 +32,10 @@ side escolhe o lado preferido; o Radix inverte sozinho quando falta espaço.
 </Tooltip>
 ```
 
-## Provider no root
+## Provider na raiz
 
-O TooltipProvider embrulha o app uma vez (delay compartilhado); cada Tooltip dispensa provider próprio. Este app já monta o seu no main.tsx.
+Monte um único `TooltipProvider` na raiz para compartilhar o atraso de exibição. Cada `Tooltip` não
+precisa de um provider próprio.
 
 ```tsx
 /* main.tsx do app — uma vez, no root. */
@@ -54,11 +57,16 @@ default nos formulários.
 </Tooltip>
 ```
 
-## Props
+## Propriedades de TooltipProvider
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `TooltipProvider.delayDuration` | `number` | `0` | Atraso (ms) até aparecer — compartilhado por todos os tooltips do app. |
-| `TooltipContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Lado preferido; inverte sozinho sem espaço (Radix). |
-| `TooltipContent.sideOffset` | `number` | `0` | Distância (px) entre gatilho e dica. |
-| `TooltipContent.className` | `string` | `max-w-sm text-pretty` | Permite substituir o limite e a distribuição de linha quando necessário. |
+| `delayDuration` | `number` | `0` | Atraso antes da exibição, compartilhado pelos tooltips do aplicativo. |
+
+## Propriedades de TooltipContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Lado preferido; o Radix reposiciona a dica quando não há espaço. |
+| `sideOffset` | `number` | `0` | Distância entre o gatilho e a dica. |
+| `className` | `string` | `max-w-sm text-pretty` | Classes para ajustar o limite e a distribuição do texto. |

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

@@ -1,8 +1,7 @@
-## Básico
+## Truncar somente quando necessário
 
-Trunca numa linha e mostra tooltip **só quando o texto realmente corta** (medição do
-overflow, re-medida em resize). Texto que cabe não ganha dica — diferente do `title`
-sempre presente, que vira ruído.
+Use `Truncate` para limitar um texto a uma linha e mostrar a dica somente quando houver transbordo.
+O componente mede novamente o conteúdo quando o tamanho muda. Se o texto couber, não cria tooltip.
 
 ```tsx preview
 <div className="w-48 rounded-md border p-2">
@@ -10,9 +9,9 @@ sempre presente, que vira ruído.
 </div>
 ```
 
-## Quando cabe, nada acontece
+## Texto sem transbordo
 
-O mesmo componente, com espaço de sobra: sem tooltip, sem atributo, só o texto.
+Quando há espaço suficiente, o componente mantém apenas o texto visível.
 
 ```tsx preview
 <div className="w-96 rounded-md border p-2">
@@ -48,8 +47,8 @@ const { ref, overflowing } = useOverflowing<HTMLSpanElement>(label)
 
 ## Conteúdo da dica
 
-`tooltip` sobrepõe o conteúdo mostrado no hover (default: os próprios children) — útil
-quando a dica precisa de mais contexto que o texto cortado.
+`tooltip` substitui o conteúdo da dica, cujo padrão são os próprios `children`. Use essa propriedade
+quando o texto completo ainda não oferecer contexto suficiente.
 
 ```tsx preview
 <div className="w-48 rounded-md border p-2">

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

@@ -4,21 +4,22 @@ title: Como consumir
 
 # Como consumir a UI
 
-A verdade visual da casa: os componentes do `@softize/opus/ui` renderizados com o nosso tema. O
-que você vê aqui é o que os apps entregam — a referência é esta doc, não o site do shadcn.
+Esta documentação é a referência visual e de uso de `@softize/opus/ui`. Os exemplos são renderizados
+com o tema e o contrato entregues aos aplicativos.
 
 ## Por que esta doc existe
 
-> O site do shadcn é catálogo do que existe lá; os exemplos de lá decoram composições que não
-> existem no nosso registry. A expectativa visual e de uso nasce aqui.
+O catálogo do shadcn documenta seu próprio código e pode mostrar composições que não fazem parte do
+Opus. Consulte estas páginas para conhecer os componentes, as variações e os comportamentos
+suportados pelo pacote.
 
-Cada página de componente mostra exemplos vivos por variante (renderizados com o tema da casa), o
-snippet de como se escreve e as props que importam. O texto de quando usar vem do próprio
-componente (o `meta` co-localizado na fonte) — a doc deriva, não duplica.
+Cada página combina exemplos vivos, código e uma referência de propriedades por componente. A
+orientação inicial vem de `componentMeta`, a mesma fonte usada pelo catálogo e pelas ferramentas.
 
 ## Como consumir
 
-> Um barrel só pra componentes e hooks; o tema entra por CSS. Nada de copiar componente pra dentro do app.
+Importe componentes e hooks de `@softize/opus/ui/react` e o tema por CSS. Não copie a implementação
+para o aplicativo quando a API pública já atender ao caso.
 
 ```tsx
 // Componentes e hooks — tudo do mesmo barrel.
@@ -36,5 +37,5 @@ import { Button, Dialog, useAction } from '@softize/opus/ui/react'
 - **Origem shadcn** — port curado do shadcn (Radix + cmdk). Toda divergência do upstream é
   DECLARADA no componente ou no tema — o que diverge sem declaração é drift e deve ser
   sincronizado (skill `build-opus-ui`).
-- **Nativo do Opus** — nasceu aqui (os patterns de action). Não tem upstream pra acompanhar; a
+- **Nativo do Opus** — nasceu aqui (os patterns de action). Não tem upstream para acompanhar; a
   referência é esta doc.