@softize/opus 12.10.0 → 13.0.0

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

@@ -4,8 +4,8 @@ title: Filas
 
 # Filas
 
-Action pesada não segura o request: marcada como background, ela é enfileirada e processada
-fora da linha, e o cliente acompanha por um handle. O contrato é o `QueueAdapter`.
+Use uma action em background quando a operação não puder manter a requisição aberta. O
+`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhamento pelo cliente.
 
 ## O contrato
 
@@ -44,7 +44,7 @@ const queue = bullmqQueue({ queue: new Queue('opus', { connection: { host: 'loca
 ```
 
 Redis-backed (durável, entre-processos, retries). Peers opcionais (`bullmq`, `ioredis`) só
-pra quem usa o driver.
+para quem usa o driver.
 
 ## No runtime
 
@@ -82,7 +82,7 @@ Multiplicador exponencial diferente de 2 ou `maxMs` exige `backoffStrategy` cust
 é rejeitado pelo driver em vez de ser silenciosamente ignorado. `timeout` permanece no
 envelope para o worker aplicar, pois não é uma opção de execução do `Queue.add`.
 
-## Limites (por enquanto)
+## Limites atuais
 
-Driver hoje: `bullmq` (Redis). In-memory pra dev e outros backends (SQS, pg-boss…) entram
+Driver hoje: `bullmq` (Redis). In-memory para dev e outros backends (SQS, pg-boss…) entram
 por reincidência.

package/src/ui/docs/content/radio-group.md

@@ -1,6 +1,8 @@
-## Básico
+## Escolha única
 
-Cada RadioGroupItem tem um value; o item escolhido é o value do RadioGroup. defaultValue deixa o estado com o componente. Pareie cada item com um Label (htmlFor↔id).
+Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Cada
+`RadioGroupItem` declara um `value` e deve estar associado a um `Label`. `defaultValue` define a
+opção inicial no modo não controlado.
 
 ```tsx preview col-start
 <RadioGroup defaultValue="balanced">
@@ -21,7 +23,7 @@ Cada RadioGroupItem tem um value; o item escolhido é o value do RadioGroup. def
 
 ## Controlado
 
-value + onValueChange no RadioGroup levam o estado pra fora — o padrão pra escolher quem recebe o handoff de uma task.
+Use `value` e `onValueChange` quando outro estado da aplicação também precisar acompanhar a escolha.
 
 ```tsx preview col-start
 const [agent, setAgent] = useState('reviewer')
@@ -46,7 +48,8 @@ render(
 
 ## Item desabilitado
 
-disabled num RadioGroupItem esmaece e tira a opção da escolha; o Label em par esmaece junto (peer-disabled). Pra bloquear o grupo inteiro, ponha disabled no RadioGroup.
+`disabled` em `RadioGroupItem` bloqueia somente aquela opção e atualiza o `Label` associado. Para
+bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 
 ```tsx preview col-start
 <RadioGroup defaultValue="empresa-x-web">
@@ -65,13 +68,18 @@ disabled num RadioGroupItem esmaece e tira a opção da escolha; o Label em par
 </RadioGroup>
 ```
 
-## Props
+## Propriedades de RadioGroup
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value (RadioGroup)` | `string` | | A opção escolhida, no modo controlado — pareie com onValueChange. |
-| `onValueChange (RadioGroup)` | `(value: string) => void` | | Chamado quando o usuário escolhe outra opção. |
-| `defaultValue (RadioGroup)` | `string` | | A opção inicial no modo não controlado. |
-| `disabled (RadioGroup)` | `boolean` | `false` | Bloqueia e esmaece o grupo inteiro. |
-| `value (RadioGroupItem)` | `string` | | O valor que este item representa — vira o value do grupo quando escolhido. |
-| `disabled (RadioGroupItem)` | `boolean` | `false` | Esmaece e tira só este item da escolha — o Label em par esmaece junto. |
+| `value` | `string` | | Opção escolhida no modo controlado. Use com `onValueChange`. |
+| `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa escolhe outra opção. |
+| `defaultValue` | `string` | | Opção inicial no modo não controlado. |
+| `disabled` | `boolean` | `false` | Desabilita todo o grupo. |
+
+## Propriedades de RadioGroupItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Valor que o item atribui ao grupo quando selecionado. |
+| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` associado acompanha o estado. |

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

@@ -1,6 +1,8 @@
-## O pathname É o estado
+## A URL como estado
 
-Roteamento history-based, sem dependência: `pushState` + `popstate` + `useSyncExternalStore`. Páginas orientadas a URL — deep-link, reload e o botão voltar funcionam de graça, porque não há um segundo lugar guardando "onde estou".
+Use o router do Opus em aplicações pequenas que precisam reagir à URL sem uma tabela de rotas.
+`pushState`, `popstate` e `useSyncExternalStore` preservam links diretos, recarregamento e o botão
+Voltar sem manter uma segunda cópia do destino atual.
 
 ```tsx
 import { navigate, useSegments } from '@softize/opus/ui/react'
@@ -12,9 +14,10 @@ function App() {
 }
 ```
 
-## O escopo é pequeno de propósito
+## Limite do router
 
-Não há tabela de rotas, `<Route>`, params tipados nem carregamento de dados. Isto é a **leitura reativa da URL + um `navigate`** — quem decide o que renderizar é o app, com `if`/`switch` sobre os segmentos.
+O router oferece leitura reativa da URL e `navigate`; o aplicativo decide o que renderizar. Ele não
+inclui tabela de rotas, parâmetros tipados nem carregamento de dados.
 
 A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:postId`), params tipados ou data loaders, o caso pede uma biblioteca de rotas, não isto. Um app de back-office com uma dúzia de destinos quase nunca precisa.
 
@@ -27,13 +30,15 @@ A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:post
 | `useSearchParams()` | A querystring reativa — o lar natural do estado interno de uma seção (qual relatório está aberto, o recorte de uma lista). |
 | `navigate(path, opts?)` | `pushState` + notifica. `{ replace: true }` troca a entrada corrente. |
 
-## Dois detalhes que custaram caro nas cópias à mão
+## Comportamentos preservados
 
 **Destino igual é no-op.** `navigate` resolve o destino com `new URL` e compara o `href` inteiro — não faz nada se você já está exatamente lá. Sem isso, clicar duas vezes no mesmo item do menu empilha entradas idênticas e o botão "voltar" não sai do lugar.
 
 Comparar strings cruas parece bastar e não basta, em duas frentes. O **hash**: estando em `/a#secao`, `navigate('/a')` pareceria destino repetido e a âncora nunca sairia da URL. E o **encoding**: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então a comparação crua nunca casa e cada clique empilha — bem no caso pt-BR, e no ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
 
-**A notificação é um evento, não uma lista.** `pushState` não dispara `popstate`, então `navigate` dispara — e é `window.dispatchEvent`, não um `Set` de assinantes em escopo de módulo. A diferença aparece nas bordas: código que ainda escuta `popstate` na unha continua acompanhando, e duas cópias do pacote no `node_modules` continuam se enxergando. Uma lista privada mora numa instância do bundle; o `window` é um só.
+**A notificação usa um evento do navegador.** Como `pushState` não dispara `popstate`, `navigate`
+emite o evento explicitamente. Isso mantém listeners existentes e cópias diferentes do pacote
+sincronizados pela mesma janela.
 
 **`useSyncExternalStore`, não `useState`.** Ler `window.location` dentro de `useState`/`useEffect` sofre *tearing* no modo concurrent: dois componentes podem renderizar o mesmo commit com URLs diferentes. As cópias que este módulo substituiu faziam isso.
 

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

@@ -4,9 +4,8 @@ title: Agendador
 
 # Agendador
 
-Rodar uma action no tempo — cron ou intervalo. Você declara o schedule (qual action, quando)
-e o runtime dispara na hora, com provenance `schedule` (rastreável no audit como qualquer
-execução). O contrato é o `SchedulerAdapter`.
+Use um schedule para executar uma action por cron ou intervalo. O `SchedulerAdapter` registra o
+agendamento e o runtime executa a action com provenance `schedule`, preservando sua rastreabilidade.
 
 ## O contrato
 
@@ -59,8 +58,8 @@ const runtime = createRuntime({
 O runtime registra os schedules do domínio no `start()` e chama a action quando o tempo bate
 — nada de disparar no handler.
 
-## Limites (por enquanto)
+## Limites atuais
 
-Driver hoje: `node-cron` (in-process — some se o processo cair; num cluster, cada nó
+Driver hoje: `node-cron` (in-process — some se o processo cair; em um cluster, cada nó
 dispararia). Backends duráveis/distribuídos (BullMQ repeatable, Temporal…) entram por
 reincidência.

package/src/ui/docs/content/scroll-area.md

@@ -4,7 +4,7 @@ Dê a altura ao ScrollArea (h-48) e ponha o conteúdo dentro — a barra vertica
 
 ```tsx preview col
 const sessions = [
-  { id: 'empresa-x-1842', title: 'Migrar billing pro novo schema', agent: 'developer' },
+  { id: 'empresa-x-1842', title: 'Migrar billing para o novo schema', agent: 'developer' },
   { id: 'empresa-x-1839', title: 'Revisar handoff do checkout', agent: 'reviewer' },
   { id: 'empresa-x-1835', title: 'Redesenhar o painel de rotas', agent: 'designer' },
   { id: 'empresa-x-1830', title: 'Corrigir flaky no teste de webhook', agent: 'developer' },
@@ -30,7 +30,7 @@ render(
 
 ## Trilho horizontal
 
-Pra rolar na horizontal, acrescente <ScrollBar orientation="horizontal" /> como filho e deixe o conteúdo numa linha que não quebra (flex + w-max).
+Para rolar na horizontal, acrescente <ScrollBar orientation="horizontal" /> como filho e deixe o conteúdo em uma linha que não quebra (flex + w-max).
 
 ```tsx preview col
 const skills = ['implement-opus-change', 'create-opus-action', 'test-opus-action', 'build-opus-ui', 'upgrade-opus']
@@ -80,10 +80,15 @@ render(
 )
 ```
 
-## Props
+## Propriedades de ScrollArea
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `className (ScrollArea)` | `string` | | Onde a altura (h-48) ou a largura mora — é o que define a janela rolável. Sem dimensão, não há o que rolar. |
-| `children (ScrollArea)` | `React.ReactNode` | | O conteúdo da janela. Inclua um <ScrollBar orientation="horizontal" /> entre os filhos pra habilitar a rolagem lateral. |
-| `orientation (ScrollBar)` | `'vertical' \| 'horizontal'` | `'vertical'` | A direção da barra. A vertical já vem embutida; adicione a horizontal só quando precisar. |
+| `className` | `string` | | Classes que definem as dimensões da janela rolável. Sem uma dimensão limitada, não há conteúdo a recortar. |
+| `children` | `React.ReactNode` | | Conteúdo da janela, incluindo uma `ScrollBar` horizontal quando necessária. |
+
+## Propriedades de ScrollBar
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Direção da barra. A barra vertical já faz parte de `ScrollArea`. |

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

@@ -1,6 +1,7 @@
-## Básico
+## Escolha em lista
 
-Um componente para toda escolha em lista. As opções são DADO (`options`), não JSX: `{ value, label }` — o `label` é o que o campo mostra, o que a busca casa e o que o leitor de tela lê. O `id` pareia com o `htmlFor` do Label.
+Use `Select` para escolhas em lista. Declare as opções como dados em `options`; `label` é usado no
+campo, na busca e na leitura assistiva. Associe `id` ao `htmlFor` de `Label` em formulários.
 
 ```tsx preview col md
 const [role, setRole] = useState('')
@@ -23,9 +24,10 @@ render(
 )
 ```
 
-## Com busca (searchable)
+## Lista pesquisável
 
-`searchable` transforma o próprio campo na busca: digitou, a lista filtra embaixo (fuzzy do cmdk, casando label, hint e value). É o que resolve a **achabilidade** — a régua é essa, não performance: 200 itens sem busca é embaçado, achar é rolar até cansar.
+Use `searchable` quando a quantidade ou os rótulos dificultarem encontrar uma opção. O próprio
+campo passa a filtrar `label`, `hint` e `value` com a busca do cmdk.
 
 ```tsx preview col md
 const [issue, setIssue] = useState('')
@@ -49,9 +51,11 @@ render(
 )
 ```
 
-## Múltiplo (chips)
+## Seleção múltipla
 
-`multiple` muda o contrato (`value` e `onChange` viram `string[]`): os escolhidos viram chips removíveis e a lista fica aberta pra seleção em sequência. Com a busca vazia, o topo do dropdown oferece Selecionar tudo / Limpar seleção (só no modo client — com filtro ativo ou `onSearch`, "tudo" seria ambíguo).
+Com `multiple`, `value` e `onChange` usam `string[]`. As opções escolhidas aparecem como chips
+removíveis e a lista permanece aberta para escolhas sucessivas. “Selecionar tudo” fica disponível
+somente quando todas as opções estão carregadas localmente e a busca está vazia.
 
 ```tsx preview col md
 const [skills, setSkills] = useState<string[]>(['clean-code'])
@@ -77,9 +81,10 @@ render(
 )
 ```
 
-## Nativo (native)
+## Controle nativo
 
-`native` renderiza o `<select>` do sistema (só com a seta restilizada — a nativa cola na borda e ignora o tema). Ganha o picker do próprio SO: roda de scroll no iOS, teclado do Android, zero JS. Use em **lista curta e sabida** (2–8 itens que a pessoa já conhece: Sim/Não, prioridade, ambiente). Item rico, busca ou multi não existem aqui — pra isso, o modo default.
+Use `native` para uma lista curta e conhecida, como prioridade ou ambiente. O sistema operacional
+controla a interação do `<select>`. Busca, seleção múltipla e conteúdo rico exigem o modo padrão.
 
 ```tsx preview col md
 const [env, setEnv] = useState('preview')
@@ -104,7 +109,8 @@ render(
 
 ## Grupos
 
-`group` na opção agrupa a lista — bloco nomeado nos dois modos (`<optgroup>` no nativo, heading no custom). Pra listas com origens distintas (membros × agentes).
+`group` reúne opções sob um título nos dois modos. Use grupos quando a lista combinar conjuntos com
+origens ou papéis distintos.
 
 ```tsx preview col md
 const [reviewer, setReviewer] = useState('')
@@ -124,9 +130,10 @@ render(
 )
 ```
 
-## Busca server-side
+## Busca no servidor
 
-Com `onSearch` o filtro do cmdk desliga: o pai busca (debounced, ao abrir e ao digitar) e devolve `options`; `loading` mostra Buscando… enquanto o fetch corre. Implica campo buscável (não precisa repetir `searchable`).
+Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Atualize
+`options` com a resposta e use `loading` durante a consulta. Esse modo já habilita o campo de busca.
 
 ```tsx preview col md
 const ASSIGNEES = [
@@ -163,7 +170,8 @@ render(
 
 ## Ícone dentro do campo
 
-`icon` põe o ícone DENTRO do controle, antes do texto (e dos chips, no multi) — identifica o campo numa barra de filtros. Ícone AO LADO do campo é o antipadrão: desalinha na quebra de linha e some no responsivo. Vale nos dois modos.
+`icon` posiciona um ícone decorativo antes do texto ou dos chips. Use-o para reforçar a identidade do
+campo sem criar um elemento separado ao lado do controle.
 
 ```tsx preview col-start
 const [task, setTask] = useState('')
@@ -182,9 +190,10 @@ render(
 )
 ```
 
-## Densidade (size)
+## Tamanho
 
-O controle segue a altura do design system: default é h-9 (a mesma do Input e do Button) e `size="sm"` dá h-8 pra barra de filtros/toolbar densa.
+O tamanho padrão acompanha `Input` e `Button`. Use `size="sm"` em barras de filtros e outras
+composições densas.
 
 ```tsx preview col-start
 const [a, setA] = useState('gra-2')
@@ -203,9 +212,10 @@ render(
 )
 ```
 
-## Limpar (clearable)
+## Limpar a seleção
 
-`clearable` põe o X no controle quando há seleção — limpa num clique (single volta a vazio, multi a `[]`), sem abrir a lista. Bom pra filtro, onde "sem valor" é um estado de uso frequente; os filtros do ActionList já vêm assim.
+`clearable` acrescenta uma ação que limpa o valor sem abrir a lista. No modo simples, o valor volta
+a vazio; no múltiplo, volta a `[]`. Os filtros de `ActionList` já habilitam esse comportamento.
 
 ```tsx preview col md
 function Demo() {
@@ -229,9 +239,10 @@ function Demo() {
 render(<Demo />)
 ```
 
-## Item rico (content)
+## Conteúdo rico nas opções
 
-`label` é sempre string (é o que o campo mostra e a busca casa); `content` é o render RICO do item na lista — ícone, avatar, duas linhas. Assim o item pode ser elaborado sem estragar busca nem a11y.
+Mantenha `label` como string para busca e leitura assistiva. Use `content` para acrescentar ícone,
+avatar ou texto complementar à opção apresentada na lista.
 
 ```tsx preview col md
 const [agent, setAgent] = useState('developer')
@@ -271,9 +282,10 @@ render(
 )
 ```
 
-## Barra do composer (variant ghost)
+## Select na barra do Composer
 
-`variant="ghost"` tira moldura e padding: o seletor discreto que vive na barra de ações do Composer/Chat (app, task, agente), à esquerda do enviar. `triggerLabel` na opção encurta o gatilho quando o rótulo da lista é longo (o título inteiro fica só na lista).
+Use `variant="ghost"` para integrar o seletor à barra de ações de `Composer`. `triggerLabel` pode
+encurtar somente o texto do gatilho; a lista continua exibindo o `label` completo.
 
 ```tsx preview col-start
 const [task, setTask] = useState('GB-42')
@@ -292,9 +304,10 @@ render(
 )
 ```
 
-## Ação no fim do campo (trailing)
+## Ação no fim do campo
 
-`trailing` põe uma ação custom DENTRO do controle, no fim (antes do chevron) — um botão que age sobre o valor escolhido, sem virar um irmão solto ao lado do campo. O clique no trailing **não** abre a lista (o slot para a propagação).
+`trailing` posiciona uma ação relacionada ao valor antes do chevron. Interagir com essa região não
+abre a lista.
 
 ```tsx preview col-start
 const [task, setTask] = useState('gra-2')
@@ -318,9 +331,9 @@ render(
 )
 ```
 
-## Props
+## Propriedades de Select
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `options` | `SelectOption[]` | | As opções: `{ value, label, hint?, content?, triggerLabel?, group?, disabled? }`. |
 | `value` | `string \| string[]` | | O selecionado: string no single, string[] no multiple. |
@@ -328,16 +341,16 @@ render(
 | `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, multi e ghost (o browser é quem desenha a lista). |
 | `searchable` | `boolean` | `false` | O campo vira busca: filtra a lista enquanto digita. |
 | `multiple` | `boolean` | `false` | Chips removíveis, lista que permanece aberta e Selecionar tudo. |
-| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost` = sem moldura, pra barra do composer. |
+| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost` = sem moldura, para barra do composer. |
 | `placeholder` | `string` | `'Selecione…'` | Texto do campo vazio. |
-| `searchPlaceholder` | `string` | | Placeholder enquanto busca; cai pro `placeholder` se ausente. |
+| `searchPlaceholder` | `string` | | Placeholder enquanto busca; cai para o `placeholder` se ausente. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
 | `onSearch` | `(query: string) => void` | | Busca server-side (debounced, ao abrir e ao digitar): desliga o filtro do cmdk — o pai atualiza `options`. |
 | `loading` | `boolean` | | Mostra Buscando… enquanto o fetch corre (use com `onSearch`). |
-| `clearable` | `boolean` | `false` | X no controle quando há seleção — limpa num clique. |
+| `clearable` | `boolean` | `false` | X no controle quando há seleção — limpa em um clique. |
 | `icon` | `React.ReactNode` | | Ícone leading DENTRO do controle (decorativo) — herda `size-4` e o tom muted. |
 | `trailing` | `React.ReactNode` | | Ação custom no FIM do controle (antes do chevron) — o clique não abre a lista. |
-| `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) pra toolbar densa. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) para toolbar densa. |
 | `disabled` | `boolean` | `false` | Esmaece e trava o controle. |
-| `id` | `string` | | Vai pro campo — pra parear com o `htmlFor` do Label. |
+| `id` | `string` | | Vai para o campo — para parear com o `htmlFor` do Label. |
 | `className` | `string` | | Classes da raiz do controle, incluindo campo, ícones e ações, em todos os modos. |

package/src/ui/docs/content/semantic-context.md

@@ -0,0 +1,63 @@
+---
+title: Contexto & Variante
+---
+
+# Contexto & Variante
+
+Componentes semânticos separam significado de aparência. `context` responde por que o elemento
+recebe destaque; `variant` escolhe como esse significado aparece. Essa ordem evita que nomes como
+`success`, `warning` ou `danger` sejam tratados como decoração local.
+
+## Contextos
+
+| Contexto | Uso |
+| --- | --- |
+| `neutral` | Estado normal, inativo ou sem julgamento positivo ou negativo. |
+| `primary` | Ação ou elemento de maior destaque no contexto atual. |
+| `info` | Informação ou processo em andamento sem alerta. |
+| `success` | Resultado positivo ou estado saudável. |
+| `warning` | Condição que pede atenção, mas ainda não é uma falha. |
+| `danger` | Falha, impedimento ou consequência perigosa. |
+
+`light` e `dark` são temas, não contextos. `secondary` descreve hierarquia de ação em APIs antigas;
+um estado sem destaque usa `neutral`. `destructive` continua sendo uma propriedade comportamental
+de actions e confirmações; sua projeção visual usa `danger`.
+
+## Variantes
+
+`solid`, `subtle`, `outline`, `ghost` e `link` descrevem somente tratamento visual. Cada componente
+aceita o subconjunto coerente com seu papel.
+
+```tsx preview col
+<div className="flex flex-wrap gap-2">
+  <Badge context="success" variant="solid">Concluído</Badge>
+  <Badge context="success" variant="subtle">Concluído</Badge>
+  <Badge context="success" variant="outline">Concluído</Badge>
+</div>
+<div className="flex flex-wrap gap-2">
+  <Button context="primary" variant="solid">Salvar</Button>
+  <Button context="neutral" variant="outline">Voltar</Button>
+  <Button context="danger" variant="ghost">Excluir</Button>
+</div>
+```
+
+## Dicionários
+
+Status e estágios declaram `context` na entrada. A tela usa `DictionaryValue` ou `ActionList` e não
+escolhe a aparência novamente.
+
+```ts
+const status = t.dict(
+  {
+    running: { label: 'Em andamento', context: 'info' },
+    completed: { label: 'Concluído', context: 'success' },
+    failed: { label: 'Falhou', context: 'danger' },
+  },
+  { presentation: 'status' },
+)
+```
+
+## Compatibilidade
+
+`tone` em dicionários e variantes semânticas antigas continuam aceitos durante a migração. Código
+novo usa `context`; não misture o contrato antigo e o novo na mesma ocorrência.

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

@@ -1,6 +1,6 @@
-## Horizontal
+## Separar blocos empilhados
 
-Divide blocos empilhados — ocupa a largura toda do contêiner.
+Use a orientação horizontal entre blocos empilhados. A linha ocupa toda a largura disponível.
 
 ```tsx preview col
 <div>
@@ -13,7 +13,7 @@ Divide blocos empilhados — ocupa a largura toda do contêiner.
 
 ## Vertical
 
-Entre itens de uma linha. O vertical herda a altura do contêiner — dê altura à linha (ex.: h-4 no flex).
+Use a orientação vertical entre itens lado a lado. A linha herda a altura do contêiner.
 
 ```tsx preview
 <div className="flex h-4 items-center gap-3 text-sm">
@@ -25,9 +25,9 @@ Entre itens de uma linha. O vertical herda a altura do contêiner — dê altura
 </div>
 ```
 
-## Props
+## Propriedades de Separator
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da linha. Vertical precisa de altura vinda do contêiner. |
 | `decorative` | `boolean` | `true` | Decorativa some da árvore de acessibilidade. Use false quando a divisão é semântica. |