@softize/opus 19.0.0 → 20.1.0

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

@@ -1,8 +1,12 @@
 ## Tabela de domínio
 
-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.
+Use `Table` para dados organizados em linhas e colunas que a tela já tem em mãos. Para uma coleção
+pesquisável, paginada e carregada por uma action `kind: 'list'`, use [`ActionList`](/ui/action-list),
+que monta a tabela, os filtros e os estados de carregamento, erro e vazio.
+
+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>
@@ -40,10 +44,8 @@ quando o domínio pedir alinhamento numérico. `TableCaption` descreve a tabela
 
 ## 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,
-então o quadro fecha limpo. O ActionList continua sendo o pattern indicado para coleções
-pesquisáveis derivadas de actions `kind: 'list'`.
+A variante `framed` aplica a borda externa e os cantos arredondados no contêiner da tabela e dá
+ao cabeçalho um fundo discreto. A última linha já vem sem divisória, então o quadro fecha limpo.
 
 ```tsx preview col
 <Table variant="framed">
@@ -105,9 +107,45 @@ adequados a essa região.
 </Table>
 ```
 
+## Contêiner e rolagem
+
+`Table` renderiza um contêiner em volta do elemento `<table>`. É nele que ficam a moldura da
+variante `framed` e a rolagem horizontal: quando as colunas não cabem, o contêiner rola e a página
+mantém a largura. Por isso há duas props de classe. `className` vai para o `<table>`;
+`containerClassName` vai para o contêiner, onde entram limites de altura, rolagem vertical ou
+ajustes da moldura.
+
+```tsx preview col
+<Table variant="framed" containerClassName="max-h-40 overflow-y-auto">
+  <TableHeader>
+    <TableRow>
+      <TableHead>Agente</TableHead>
+      <TableHead className="text-right">Sessões</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow><TableCell className="font-medium">developer</TableCell><TableCell className="text-right">42</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">reviewer</TableCell><TableCell className="text-right">18</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">designer</TableCell><TableCell className="text-right">7</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">planner</TableCell><TableCell className="text-right">5</TableCell></TableRow>
+    <TableRow><TableCell className="font-medium">tester</TableCell><TableCell className="text-right">3</TableCell></TableRow>
+  </TableBody>
+</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`. |
+| `containerClassName` | `string` | | Classes do contêiner que envolve o `<table>` e responde pela rolagem horizontal e pela moldura. |
+| `className` | `string` | | Classes aplicadas ao elemento `<table>`. |
+
+Os demais atributos vão para o elemento `<table>`.
+
+## Propriedades das partes da tabela
+
+`TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell` e `TableCaption`
+não têm props próprias. Cada um aceita as props nativas do elemento que renderiza — `<thead>`,
+`<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>` e `<caption>` —, como `className`, `colSpan` ou
+`scope`. Para marcar uma linha selecionada, passe `data-state="selected"` ao `TableRow`.

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

@@ -82,7 +82,9 @@ Com `orientation="vertical"`, a lista forma uma coluna. O exemplo usa a variante
 
 ## 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.
+`size="sm"` no `Tabs` reduz a altura da lista de `2.25rem` para `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.
 
 ```tsx preview col
 <Tabs defaultValue="preview" size="sm">
@@ -110,9 +112,17 @@ Com `orientation="vertical"`, a lista forma uma coluna. O exemplo usa a variante
 |---|---|---|---|
 | `variant` | `'default' \| 'line'` | `'default'` | `default` usa uma superfície preenchida; `line` cria uma linha-base horizontal de largura total e marca nela a aba ativa. |
 
-## Propriedades de TabsTrigger e TabsContent
+## Propriedades de TabsTrigger
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `string` | | Identificador que associa o gatilho ao painel correspondente. |
-| `icon` | `ReactNode` | | Ícone decorativo antes do rótulo; SVGs usam `1rem`. |
+| `value` | `string` | | Identificador que associa o gatilho ao `TabsContent` correspondente. |
+| `icon` | `ReactNode` | | Ícone decorativo antes do rótulo, em `1rem`. Em uma aba sem texto, declare também `aria-label`. |
+| `disabled` | `boolean` | `false` | Impede a seleção da aba. |
+
+## Propriedades de TabsContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Identificador do painel, igual ao `value` do `TabsTrigger` que o abre. |
+| `forceMount` | `true` | | Mantém o painel montado mesmo quando outra aba está ativa. |

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

@@ -5,31 +5,35 @@ title: Testes de action
 # Testes de action
 
 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.
+autorização. `@softize/opus/testing` executa esse fluxo em unidade, sem montar o runtime completo.
 
-## Executar o contrato em unidade
+## Executar a action em unidade
 
-`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`.
+`runAction` segue a ordem do runtime: valida a entrada, exige usuário quando a action não é
+`public`, avalia `authorize`, executa o handler e valida a saída. Em `list`, a validação da saída é
+pulada, porque o schema descreve o item e o handler devolve a página. Falhas usam o mesmo
+`ActionError` tipado do runtime, como `validation.invalid_input`, `auth.unauthenticated` e
+`auth.forbidden`.
+
+Passe a action ligada ao handler, produzida por `bindAction`. O contrato puro não tem handler e só
+executa em modo design, descrito abaixo.
 
 ```ts
 import { runAction } from '@softize/opus/testing'
-import { taskList } from './list.ts'
+import { taskListImpl } from './list.ts'
 
-it('lista as fixtures com o shape do contrato', async () => {
-  const { output } = await runAction(taskList, {}, { user: { id: 'u1' } })
+it('lista as tarefas com o formato do contrato', async () => {
+  const { output } = await runAction(taskListImpl, {}, { user: { id: 'u1' } })
   expect(output.total).toBe(2)
 })
 
-it('sem usuário, barra: a action não é pública', async () => {
-  await expect(runAction(taskList, {})).rejects.toMatchObject({ code: 'auth.unauthenticated' })
+it('exige usuário, porque a action não é pública', async () => {
+  await expect(runAction(taskListImpl, {})).rejects.toMatchObject({ code: 'auth.unauthenticated' })
 })
 ```
 
-O terceiro argumento configura o contexto e substitui os loaders (que não rodam em
-unidade): `{ user, tenantId, can, db, storage, ai, loaded, meta }`. O `authorize` vê
-o `loaded` como no runtime:
+Os loaders não rodam em unidade. Para testar uma autorização que depende de dados carregados,
+entregue o resultado pronto em `loaded`; o `authorize` o recebe como no runtime:
 
 ```ts
 it('só a dona edita', async () => {
@@ -41,20 +45,63 @@ it('só a dona edita', async () => {
 })
 ```
 
-## Contexto observável
+## Configurar o contexto
+
+O terceiro argumento de `runAction` monta o contexto recebido pelo handler. Todas as opções são
+opcionais.
+
+| Opção | Efeito |
+| --- | --- |
+| `user`, `tenantId` | Identidade do chamador. Sem `user`, actions que não são `public` falham com `auth.unauthenticated`. |
+| `can` | Resposta de `ctx.can`. Padrão: permite tudo. |
+| `db` | Valor entregue em `ctx.db`. |
+| `storage`, `cache` | Adapters entregues em `ctx.storage` e `ctx.cache`; padrão `null`. |
+| `ai` | Adapter de IA entregue em `ctx.ai`. Sem runtime, `run` e `runStream` não recebem tools. |
+| `meta`, `trace` | Valores de `ctx.meta` e `ctx.trace`. |
+| `loaded` | Substitui os loaders e chega ao `authorize` e ao handler. |
+
+`requires` é declarativo também no harness: nada o executa. Um handler que chama `ctx.can` recebe a
+resposta da opção `can`.
 
-`runAction` (e `testContext`, para quem quer só o ctx) devolve os efeitos capturados —
-o teste afirma o que importa:
+## Observar efeitos
+
+`runAction` devolve, além de `output`, os efeitos capturados: `emitted` guarda cada `ctx.emit` e
+`logged`, cada linha de `ctx.log`, na ordem em que ocorreram. `testContext` devolve o mesmo
+contexto sem executar uma action.
 
 ```ts
 const { output, emitted, logged } = await runAction(taskDone, { id: '1' }, { user })
 expect(emitted).toEqual([{ event: 'task.done', data: { id: '1' } }])
 ```
 
+## Testar em modo design
+
+Com `OPUS_MODE=design`, `runAction` executa o `mockHandler` quando ele existe, como o runtime do
+modo design. Nesse modo, o contrato puro também é testável. Fora dele, um contrato sem handler falha
+com `testing.no_handler`.
+
+```ts
+import { afterEach, it } from 'vitest'
+import { runAction } from '@softize/opus/testing'
+import { Task, taskList } from './list.ts'
+
+afterEach(() => {
+  // A variável vale para o processo inteiro; limpe para não afetar outros testes.
+  delete process.env['OPUS_MODE']
+})
+
+it('o mock devolve itens válidos para o schema', async () => {
+  process.env['OPUS_MODE'] = 'design'
+  const { output } = await runAction(taskList, {}, { user: { id: 'u1' } })
+  // `list` não valida a saída no pipeline: confira item a item.
+  for (const item of output.items) expect(Task.safeParse(item).success).toBe(true)
+})
+```
+
 ## memStorage
 
-`StorageAdapter` em memória com a mesma régua de key dos drivers reais — para handler
-que anexa arquivo:
+Para um handler que grava arquivos, `memStorage` oferece um `StorageAdapter` em memória com a mesma
+validação de chave dos drivers reais:
 
 ```ts
 import { memStorage, runAction } from '@softize/opus/testing'
@@ -64,26 +111,24 @@ await runAction(notaAnexar, { id: '9' }, { user, storage })
 expect(storage.keys()).toEqual(['notas/9.pdf'])
 ```
 
-## fake — fixtures do schema
+## fake — dados gerados pelo schema
 
-`fake(schema)` / `fakeMany(schema, n)` geram dado sintético **determinístico** que satisfaz o
-schema zod — matéria-prima do `mockHandler` (modo design) e de fixtures de teste. Semeado
-(mesma `seed` → mesma saída, sem `Math.random`), com heurística por check do zod (email, uuid,
-url, datetime) e por nome de campo (email, id, `*At`→data, telefone, cpf/cnpj, nome…), sabor pt-BR.
+`fake(schema)` e `fakeMany(schema, n)` geram dados sintéticos determinísticos que satisfazem o
+schema zod. Servem ao `mockHandler` do modo design e a fixtures de teste. A mesma `seed` produz a
+mesma saída, sem `Math.random`. Os valores seguem as validações do zod (email, uuid, url, datetime)
+e o nome do campo (email, id, `*At` como data, telefone, CPF/CNPJ, nome…), com conteúdo em pt-BR.
 
 ```ts
 import { entityRowSchema } from '@softize/opus/schema'
 import { fake, fakeMany } from '@softize/opus/testing'
 
-const eventRowSchema = entityRowSchema(EventEntity) // schema da linha da entidade
-const one = fake(eventRowSchema) // 1 evento válido (safeParse passa)
-const many = fakeMany(eventRowSchema, 20) // 20, estáveis entre execuções
-fake(schema, { seed: 7 }) // seed própria
+const eventRowSchema = entityRowSchema(EventEntity) // schema de uma linha da entidade
+const one = fake(eventRowSchema) // um evento válido
+const many = fakeMany(eventRowSchema, 20) // 20 eventos, estáveis entre execuções
+const seeded = fake(eventRowSchema, { seed: 7 }) // outra seed, outra sequência
 ```
 
 ## 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.
-`requires` é declarativo no protocolo (o runtime não o executa) — no harness idem;
-handler que chama `ctx.can` responde ao `can` das options.
+O harness não executa loaders reais, audit, reactions encadeadas nem o servidor. Para o fluxo
+completo, escreva um teste de integração com `createRuntime`.

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

@@ -1,7 +1,8 @@
 ## Texto com várias linhas
 
-Use `Textarea` para texto livre com várias linhas. O campo cresce com o conteúdo a partir de sua
-altura mínima.
+Use `Textarea` para texto livre com várias linhas, como uma descrição ou um contexto. O campo cresce
+com o conteúdo a partir da altura mínima de `4rem`; para uma caixa de envio com botão integrado,
+use [`Composer`](/ui/composer).
 
 ```tsx preview col md
 <Textarea placeholder="Descreva o que o agente deve fazer nesta sessão." />
@@ -34,5 +35,5 @@ Associe `htmlFor` no `Label` ao `id` do campo para manter o rótulo acessível.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `…props` | `ComponentProps<'textarea'>` | | Todos os atributos nativos (`value`, `defaultValue`, `rows`, `disabled`, `aria-invalid`…). A altura acompanha o conteúdo (`field-sizing-content`) a partir de `min-h-16`. |
-| `className` | `string` | | Compõe sobre o estilo padrão. |
+| `…props` | `ComponentProps<'textarea'>` | | Todos os atributos nativos (`value`, `defaultValue`, `rows`, `disabled`, `aria-invalid`…). A altura acompanha o conteúdo a partir do mínimo de `4rem`. |
+| `className` | `string` | | Classes somadas ao estilo padrão, como uma altura máxima. |

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

@@ -1,16 +1,19 @@
 ## Notificação temporária
 
-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. Corpo e padding seguem os mesmos `0.875rem` e `0.75rem` do Alert; os defaults
-internos do Sonner não definem a densidade da casa.
+Use `toast` para informar o resultado temporário de uma ação sem interromper o fluxo. A notificação
+some sozinha, então não use toast para algo que a pessoa precisa ler ou resolver depois; nesse caso,
+mantenha a mensagem na página com [`Alert`](/ui/alert).
+
+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. Corpo e padding seguem os mesmos `0.875rem` e `0.75rem` do
+`Alert`.
 
 ```tsx preview
 <Button variant="outline" onClick={() => toast.success('Workspace criado')}>Sucesso</Button>
 <Button
   variant="outline"
-  onClick={() => toast.error('Falha no push', { description: 'O Multica não respondeu — tente de novo.' })}
+  onClick={() => toast.error('Falha no push', { description: 'O repositório remoto não respondeu. Tente de novo.' })}
 >
   Erro
 </Button>
@@ -52,7 +55,7 @@ oferecer uma ação.
   variant="outline"
   onClick={() =>
     toast.promise(new Promise((resolve) => setTimeout(resolve, 1800)), {
-      loading: 'Publicando no Multica…',
+      loading: 'Publicando agentes…',
       success: 'Agentes publicados',
       error: 'Falha ao publicar',
     })
@@ -62,6 +65,28 @@ oferecer uma ação.
 </Button>
 ```
 
+## Carregamento e mensagens neutras
+
+`toast.message`, como `toast`, exibe uma notificação sem ícone de tipo. `toast.loading` mostra o
+indicador de progresso e não expira sozinho: guarde o identificador que ele retorna e passe-o em
+`id` para trocar a mesma notificação pelo resultado. `toast.dismiss(id)` fecha uma notificação; sem argumento, fecha todas.
+
+```tsx preview
+<Button
+  variant="outline"
+  onClick={() => {
+    const id = toast.loading('Sincronizando workspace…')
+    setTimeout(() => toast.success('Workspace sincronizado', { id }), 1800)
+  }}
+>
+  Carregamento
+</Button>
+<Button variant="outline" onClick={() => toast.message('Rascunho salvo neste navegador')}>
+  Neutra
+</Button>
+<Button variant="ghost" onClick={() => toast.dismiss()}>Fechar todas</Button>
+```
+
 ## Toaster na raiz
 
 Monte um único `Toaster` na raiz do aplicativo. O tema vem da propriedade `theme`, cujo padrão é
@@ -80,11 +105,27 @@ Monte um único `Toaster` na raiz do aplicativo. O tema vem da propriedade `them
 | `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. |
 
+## Funções de toast
+
+As funções de notificação (`toast` e suas variantes de contexto, `message` e `loading`) recebem o
+título e as opções e retornam o identificador da notificação. `toast.promise` e `toast.dismiss` têm
+assinaturas próprias, indicadas na tabela.
+
+| Função | Descrição |
+|---|---|
+| `toast(title, options?)` | Notificação padrão, sem ícone de tipo. |
+| `toast.success`, `toast.info`, `toast.warning`, `toast.error` | Notificação com o ícone e a cor do contexto correspondente. |
+| `toast.message(title, options?)` | Equivale a `toast(title, options?)`: notificação sem ícone de tipo. |
+| `toast.loading(title, options?)` | Notificação com indicador de progresso que não expira sozinha. |
+| `toast.promise(promise, { loading, success, error })` | Acompanha a promessa e atualiza a mesma notificação. Não aceita `actions`. |
+| `toast.dismiss(id?)` | Fecha a notificação indicada ou, sem argumento, todas. |
+
 ## Opções de toast
 
 | Opção | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `description` | `React.ReactNode` | | Complemento exibido abaixo do título. |
+| `id` | `string \| number` | gerado | Identificador da notificação. Passe o de uma notificação existente para substituí-la, como depois de `toast.loading`. |
 | `actions` | `ToastAction[]` | | Coleção ordenada de ações; a última recebe destaque primário por padrão. |
 | `duration` | `number` | `4000` | Tempo de permanência da notificação, em milissegundos. O `Toaster` pode mudar o padrão, e `toast.loading` não expira sozinho. |
 

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

@@ -50,7 +50,7 @@ borda. `size` ajusta a altura.
 
 ## Desabilitado
 
-disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
+`disabled` esmaece o toggle e bloqueia o clique. O estado pressionado continua visível.
 
 ```tsx preview
 <Toggle disabled aria-label="Negrito">
@@ -66,10 +66,10 @@ disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `pressed` | `boolean` | | O estado ligado/desligado no modo controlado — parear com onPressedChange. |
+| `pressed` | `boolean` | | Estado no modo controlado. Use 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. |
+| `variant` | `'default' \| 'outline'` | `'default'` | `default` não tem borda e só ganha fundo quando ativo; `outline` mantém a borda. |
 | `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
 | `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |

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

@@ -4,9 +4,10 @@ title: Tokens e tema
 
 # Tokens e tema
 
-O tema canônico vive no Opus (`theme.css`): tokens com a cor inteira na var, mapeados para o
-Tailwind via `@theme inline`. Os swatches abaixo leem as vars **ao vivo** — troque o tema do app
-e a página acompanha.
+Use esta página para escolher a cor, a borda, a sombra, o texto ou o raio certo em uma tela e para
+saber quais variáveis sobrescrever ao aplicar a marca do projeto. Os tokens ficam em `theme.css`:
+cada variável guarda a cor inteira e é mapeada para as classes do Tailwind por `@theme inline`. Os
+exemplos leem as variáveis ao vivo; troque o tema do app e a página acompanha.
 
 ## Superfícies e intenções
 
@@ -210,24 +211,20 @@ render(
 
 ## Divergências declaradas vs shadcn
 
-> A regra anti-drift: o que não está declarado aqui (e no `theme.css`) é drift e deve ser
-> sincronizado — skill `build-opus-ui`.
+> Qualquer diferença em relação ao shadcn que não esteja declarada aqui (e no `theme.css`) é uma
+> divergência a sincronizar, conforme a skill `build-opus-ui`.
 
-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.
+1. Formato HSL nos tokens (o upstream migrou para oklch), escolhido pela legibilidade; os valores
+   acompanham o upstream, só o formato difere.
+2. Elevação no tema escuro: `--card` e `--popover` ficam acima de `--background` (`10%` contra `3.9%`
+   de luminosidade), para que dialog e card se destaquem de fato da página.
 3. Radius mapeado (`xs` a `2xl`) preservando o sentido pré-v4 dos utilitários `rounded-*`. Esse
    trecho derivado permanece monotônico quando a base muda; aplicações que também usam `3xl`
    precisam revisar a transição para esse degrau nativo ao customizar `--radius`.
-
 4. Escala `shadow-*` recomposta em duas camadas claras e difusas — preserva os degraus do
-   Tailwind e troca somente o peso visual. Os aliases antigos por papel foram removidos;
-   componentes e consumidores usam diretamente a escala.
-
-5. Bordas mais leves no light: `--border`/`--input` em 92.5% (upstream 89.8%) — par do canvas
+   Tailwind e troca somente o peso visual. Componentes e consumidores usam diretamente a escala.
+5. Bordas mais leves no tema claro: `--border`/`--input` em `92.5%` (upstream `89.8%`) — par do canvas
    quase-branco do body; superfícies elevadas usam essa mesma borda real.
-
 6. Radius base em `0.75rem` — superfícies principais ganham cantos mais presentes sem aproximar
    controles compactos de modais. A decisão detalhada acompanha o pacote em
    `docs/radius-scale.md`, com os defaults, o comportamento de superfícies aninhadas e as
@@ -235,14 +232,6 @@ render(
 
 ## Identidade por app
 
-> 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. */
-@import '@softize/opus/ui/theme.css';
-
-:root {
-  --primary: hsl(262 83% 58%); /* A cor da marca do projeto. */
-  --ring: hsl(262 83% 58%);
-}
-```
+O tema do Opus é a base, e cada app sobrescreve as variáveis para ter a própria identidade sem
+copiar componentes. O passo a passo, com o exemplo de CSS, está em
+[Customização](/ui/customization).

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

@@ -2,7 +2,8 @@
 
 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`.
+precisando de `aria-label`. Para conteúdo que a pessoa precisa ler ou usar, como um formulário
+curto, use [`Popover`](/ui/popover).
 
 ```tsx preview
 <Tooltip>
@@ -62,7 +63,22 @@ default nos formulários.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `delayDuration` | `number` | `0` | Atraso antes da exibição, compartilhado pelos tooltips do aplicativo. |
+| `delayDuration` | `number` | `0` | Atraso antes da exibição, em milissegundos, compartilhado pelos tooltips do aplicativo. |
+
+## Propriedades de Tooltip
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Estado da dica no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando a dica abre ou fecha. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
+| `delayDuration` | `number` | valor do `TooltipProvider` | Atraso antes da exibição desta dica, em milissegundos; substitui o do provider. |
+
+## Propriedades de TooltipTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Faz do filho (por exemplo, um `Button`) o gatilho, em vez de renderizar outro `<button>`. |
 
 ## Propriedades de TooltipContent
 

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

@@ -1,7 +1,8 @@
 ## Truncar somente quando necessário
 
 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.
+O componente mede novamente o conteúdo quando o tamanho muda. Se o texto couber, não cria
+[tooltip](/ui/tooltip).
 
 ```tsx preview
 <div className="w-48 rounded-md border p-2">
@@ -34,8 +35,20 @@ escondido.
 Uma composição que precisa do esmaecimento sem o tooltip aplica a utilitária `truncate-fade`,
 que cobre o último `1.5rem` da caixa, e decide quando ligá-la com o hook `useOverflowing` — a
 mesma medição que este componente usa. A máscara pressupõe corte real: em texto que cabe
-inteiro, ela esmaeceria o fim de uma palavra visível. É assim que o rótulo do `SidebarItem`
-funciona.
+inteiro, ela esmaeceria o fim de uma palavra visível. É assim que o rótulo do `SidebarItem`, da
+[`Sidebar`](/ui/sidebar), funciona.
+
+```ts
+function useOverflowing<T extends HTMLElement>(content?: React.ReactNode): {
+  ref: React.RefObject<T | null>
+  overflowing: boolean
+}
+```
+
+Ligue `ref` ao elemento de uma linha que pode ser cortado. `overflowing` fica `true` quando o
+conteúdo é mais largo que a caixa. A medida é refeita quando a caixa muda de tamanho e quando
+`content` muda; passe nele o texto exibido, porque a troca de texto sem mudança de tamanho não é
+percebida de outra forma.
 
 ```tsx
 const { ref, overflowing } = useOverflowing<HTMLSpanElement>(label)
@@ -58,9 +71,26 @@ quando o texto completo ainda não oferecer contexto suficiente.
 </div>
 ```
 
-Requer `TooltipProvider` na raiz (o esqueleto do `opus create` já monta). Largura vem do
-container ou de `className` (`max-w-*`) — o span é `block` e corta em reticências (`truncate`); com
-`fade`, esmaece o fim da linha em vez das reticências.
+Requer `TooltipProvider` na raiz; o projeto criado por `opus create` já o monta. A largura vem do
+contêiner ou de `className` (`max-w-*`): o `span` é `block` e corta em reticências (`truncate`);
+com `fade`, esmaece o fim da linha em vez das reticências.
+
+## Acesso pelo teclado
+
+A dica abre quando o ponteiro passa sobre o texto ou quando o texto recebe o foco. Com o texto
+cortado, `Truncate` entra na ordem de tabulação e mostra o anel de foco dos controles, então quem
+navega pelo teclado alcança a dica com Tab. Sem corte, o texto fica fora da ordem de tabulação,
+porque não há nada escondido para revelar.
+
+Dentro de um link ou botão, o próprio controle já recebe o foco. Passe `tabIndex={-1}` ao
+`Truncate` para não criar uma segunda parada de tabulação no mesmo item. Nesse caso, a dica deixa de
+abrir pelo teclado: dê ao controle o nome completo, com `aria-label`, ou mostre o texto completo em
+outro lugar visível.
+
+Leitores de tela leem o texto completo do elemento, mesmo cortado na tela; o conteúdo próprio
+passado em `tooltip` só é anunciado enquanto a dica está aberta. Quando o texto completo for
+necessário para a tarefa, mostre-o também em um lugar que não dependa da dica, como o detalhe do
+registro.
 
 ## Propriedades de Truncate