@softize/opus 19.0.0 → 20.0.0

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

@@ -1,6 +1,6 @@
 Use `DetailGroup` para organizar dados somente leitura como pares de rótulo e valor.
 `DetailField` representa cada par e aceita conteúdo React em `label` e `value`. Para entrada e
-validação, use `Field`.
+validação, use [`Field`](/ui/field).
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -27,7 +27,8 @@ validação, use `Field`.
 
 `null`, `undefined`, string vazia ou só com espaços mostram um travessão; a leitura assistiva
 recebe “Não informado”. Uma string em `empty` troca esse significado no domínio, enquanto um nó
-React substitui a apresentação. `0` e `false` seguem como valores. Ver `EmptyValue`.
+React substitui a apresentação. `0` e `false` seguem como valores. A regra é a mesma de
+[`EmptyValue`](/ui/empty-value).
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -64,15 +65,21 @@ começam depois da mesma coluna de rótulo, com largura padrão de `7rem` em gru
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica a moldura canônica ao conjunto, com fundo transparente; na orientação horizontal, a coluna de rótulos recebe fundo sutil. |
-| `dividers` | `boolean` | `false` | Hairlines somente entre os campos, sem exigir moldura externa. |
+| `dividers` | `boolean` | `false` | Linhas finas somente entre os campos, sem exigir moldura externa. |
 | `columns` | `1 \| 2 \| 3 \| 4 \| 'auto'` | `1` | Número fixo de colunas ou distribuição automática por largura mínima. |
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chave sobre o valor ou ao lado dele em cada campo. |
 
+O grupo renderiza uma lista de definições (`<dl>`); os demais atributos, como `className`, vão para
+ela.
+
 ## Propriedades de DetailField
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `label` | `ReactNode` | | A chave do par. |
-| `value` | `ReactNode` | | O valor; `null`, `undefined` e string vazia renderizam a ausência, `0` e `false` seguem como valores. |
+| `label` | `ReactNode` | obrigatório | A chave do par. |
+| `value` | `ReactNode` | obrigatório | O valor; `null`, `undefined` e string vazia renderizam a ausência, `0` e `false` seguem como valores. |
 | `icon` | `ReactNode` | | Ícone decorativo antes do par chave/valor. |
 | `empty` | `ReactNode` | `“Não informado”` | Uma string dá significado acessível ao travessão; um nó próprio substitui a apresentação. |
+
+Os demais atributos, como `className`, vão para o contêiner do par. `DetailField` não aceita
+`children`: o conteúdo entra por `value`.

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

@@ -10,7 +10,8 @@ contexto da página. A forma escolhida depende do tipo de interrupção:
 | Pedir reconhecimento, confirmação binária ou uma string sem montar a superfície. | Use `dialog.alert`, `dialog.confirm` ou `dialog.prompt`. |
 | Escolher entre vários resultados simples.                                        | Use `dialog.choose`.                                     |
 
-Para conteúdo ancorado e não modal, use `Popover`. Para uma lista de ações, use `Menu`.
+Para conteúdo ancorado e não modal, use [`Popover`](/ui/popover). Para uma lista de ações, use
+[`Menu`](/ui/menu).
 
 ## Compor uma tarefa modal
 
@@ -118,13 +119,13 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
   <DialogContent>
     <DialogHeader>
       <DialogNavigation>
-        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DialogNavigation>
       <DialogTitle>Evento 4821</DialogTitle>
       <DialogActions>
-        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+        <Button variant="ghost" size="icon" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DialogActions>
@@ -136,9 +137,82 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
 </Dialog>
 ```
 
+Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
+[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
+quadrado `icon-sm` (1.75rem) por padrão.
+
 O cabeçalho não recebe descrição: um modal já é a superfície de uma tarefa, e o contexto que ajuda a
 decidir aparece no começo do corpo, como texto ou `Alert`.
 
+## Identificar a tarefa com um ícone
+
+Use `DialogMedia` quando um ícone ajuda a reconhecer a tarefa antes da leitura do título. No modo
+padrão, ele abre a linha do cabeçalho com a mesma moldura de [`IconTile`](/ui/icon-tile) das demais
+superfícies. No `mode="alert"`, a moldura cresce e fica centralizada acima do título, porque ali o
+ícone é o principal sinal de reconhecimento da resposta.
+
+```tsx preview
+render(
+  <div className="flex flex-wrap gap-3">
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline">Compartilhar contrato</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogMedia>
+            <Share2 />
+          </DialogMedia>
+          <DialogTitle>Compartilhar contrato</DialogTitle>
+        </DialogHeader>
+        <DialogBody className="space-y-2">
+          <Label htmlFor="share-email">E-mail</Label>
+          <Input id="share-email" placeholder="nome@empresa.com.br" />
+        </DialogBody>
+        <DialogFooter>
+          <ButtonGroup mode="spaced">
+            <DialogClose asChild>
+              <Button variant="ghost">Cancelar</Button>
+            </DialogClose>
+            <Button>Compartilhar</Button>
+          </ButtonGroup>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+    <Dialog mode="alert">
+      <DialogTrigger asChild>
+        <Button variant="outline">Revogar acesso</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogMedia context="danger">
+            <ShieldOff />
+          </DialogMedia>
+          <DialogTitle>Revogar acesso de Marina?</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          <p className="text-sm text-muted-foreground">
+            Ela deixa de ver o contrato imediatamente.
+          </p>
+        </DialogBody>
+        <DialogFooter>
+          <ButtonGroup mode="spaced" distribution="equal">
+            <DialogClose initialFocus asChild>
+              <Button variant="outline">Cancelar</Button>
+            </DialogClose>
+            <DialogClose asChild>
+              <Button context="danger">Revogar acesso</Button>
+            </DialogClose>
+          </ButtonGroup>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  </div>,
+);
+```
+
+Na API imperativa, a opção `media` recebe o ícone e o apresenta na mesma moldura do alerta.
+
 ## Pedir uma resposta pela API imperativa
 
 Use `dialog.alert`, `dialog.confirm`, `dialog.prompt` e `dialog.choose` quando a resposta couber em
@@ -169,12 +243,13 @@ function Demo() {
         size="sm"
         onClick={async () => {
           const accepted = await dialog.confirm({
-            title: "Excluir sessão?",
-            body: "O worktree e o preview desta sessão serão removidos.",
+            title: "Excluir rascunho?",
+            body: "O rascunho e os comentários dele serão removidos.",
+            media: <Trash2 />,
             action: "Excluir",
             context: "danger",
           });
-          setResult(accepted ? "Sessão excluída." : "Sessão mantida.");
+          setResult(accepted ? "Rascunho excluído." : "Rascunho mantido.");
         }}
       >
         Confirmar exclusão
@@ -184,14 +259,14 @@ function Demo() {
         size="sm"
         onClick={async () => {
           const name = await dialog.prompt({
-            title: "Renomear snapshot",
+            title: "Renomear versão",
             action: "Renomear",
             placeholder: "Ex.: versão final",
           });
           setResult(name === null ? "Nome mantido." : `Novo nome: ${name}`);
         }}
       >
-        Renomear snapshot
+        Renomear versão
       </Button>
       <Button
         variant="outline"
@@ -229,7 +304,8 @@ render(<Demo />);
 `dialog.prompt` devolve `Promise<string | null>` e `dialog.choose` infere a união dos resultados
 declarados, acrescida de `null`. Fechar ou cancelar resolve a resposta negativa de cada operação,
 em vez de deixar a promise pendente. No aviso com uma ação, o botão ocupa toda a largura do rodapé;
-confirmações e prompts distribuem confirmar e cancelar em duas colunas.
+confirmações e prompts distribuem confirmar e cancelar em duas colunas. O `dialog.choose` usa uma
+superfície mais larga, de `32rem`, para que as ações caibam lado a lado.
 
 Em `dialog.choose`, declare pelo menos uma ação e marque exatamente uma ação habilitada com
 `initialFocus`. Essa ação representa a saída segura. Os valores de `result` precisam ser únicos.
@@ -238,7 +314,7 @@ neutro e variante outline. Defina `context` ou `variant` na própria ação para
 
 ### Montar o host
 
-Monte um `DialogHost` no shell do aplicativo, ao lado do `Toaster`:
+Monte um `DialogHost` no shell do aplicativo, ao lado do [`Toaster`](/ui/toast):
 
 ```tsx
 <>
@@ -248,8 +324,8 @@ Monte um `DialogHost` no shell do aplicativo, ao lado do `Toaster`:
 </>
 ```
 
-Sem o host, a chamada lança um erro imediatamente. Solicitações concorrentes entram em uma fila e
-aparecem uma por vez, preservando a resposta de cada `await`.
+Sem o host, a promise é rejeitada imediatamente com um erro. Solicitações concorrentes entram em
+uma fila e aparecem uma por vez, preservando a resposta de cada `await`.
 
 ### Adicionar contexto relevante
 
@@ -259,21 +335,21 @@ texto, um `Alert` ou uma composição própria:
 
 ```tsx
 const accepted = await dialog.confirm({
-  title: "Encerrar três sessões?",
+  title: "Revogar três acessos?",
   body: (
     <Alert
       context="warning"
-      description="Os agentes vinculados serão interrompidos."
+      description="As pessoas convidadas deixam de ver o contrato imediatamente."
     />
   ),
-  action: "Encerrar sessões",
+  action: "Revogar acessos",
 });
 ```
 
-Use `ActionTrigger` quando a confirmação já pertencer ao contrato de uma action. Use
-`ActionFormDialog` para formulários com validação ou vários campos. `dialog.prompt` atende somente
-uma string livre. Componha `Dialog` quando uma ação precisar manter a superfície
-aberta para exibir carregamento, validação ou falha antes do fechamento.
+Use [`ActionTrigger`](/ui/action-trigger) quando a confirmação já pertencer ao contrato de uma
+action. Use [`ActionFormDialog`](/ui/action-form-dialog) para formulários com validação ou vários
+campos. `dialog.prompt` atende somente uma string livre. Componha `Dialog` quando uma ação precisar
+manter a superfície aberta para exibir carregamento, validação ou falha antes do fechamento.
 
 ## Compor uma resposta personalizada
 
@@ -282,6 +358,10 @@ com o clique externo. Prefira a API imperativa quando a resposta couber em `aler
 `prompt` ou `choose`. Componha o componente quando a resposta depender de estado próprio ou de um
 layout específico.
 
+O alerta tem `20rem` de largura máxima, suficiente para duas ações lado a lado. Com três ações,
+amplie a superfície com `className="max-w-lg"` em `DialogContent`, a mesma largura que o
+`dialog.choose` usa; sem isso, os rótulos não cabem no rodapé.
+
 ```tsx preview
 function ResponseDialogDemo() {
   const [result, setResult] = useState("Nenhuma resposta.");
@@ -292,7 +372,7 @@ function ResponseDialogDemo() {
         <DialogTrigger asChild>
           <Button variant="outline">Fechar editor</Button>
         </DialogTrigger>
-        <DialogContent>
+        <DialogContent className="max-w-lg">
           <DialogHeader>
             <DialogTitle>Fechar editor?</DialogTitle>
           </DialogHeader>
@@ -328,13 +408,16 @@ render(<ResponseDialogDemo />);
 contexto, variante e tamanho pertencem ao botão. `result` identifica a resposta entregue a
 `Dialog onResult`. Marque com `initialFocus` a saída segura — normalmente `Cancelar`; em um aviso
 com uma única ação, marque essa ação. Para uma confirmação destrutiva, use `context="danger"` no
-botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Encerrar sessões`.
+botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Arquivar contratos`.
 
 ## Acessibilidade
 
 - `DialogTitle` nomeia a superfície para tecnologias assistivas. Quando um texto conciso do corpo
   também precisar descrevê-la, relacione seu `id` por `aria-describedby` em `DialogContent`.
 - O modo padrão permite fechamento externo; `mode="alert"` exige uma resposta explícita.
+- Enquanto uma operação não puder ser interrompida, `closeDisabled` em `DialogContent` impede que o
+  botão de fechar, Esc e o clique externo fechem a superfície. As ações que você compõe com
+  `DialogClose` continuam ativas; desabilite-as pelo mesmo estado da operação.
 - O comportamento selecionado por `mode` determina o papel de acessibilidade; `role` não configura
   o comportamento.
 - O foco permanece dentro do diálogo aberto e retorna ao gatilho após o fechamento.
@@ -363,10 +446,10 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 | Propriedade       | Tipo        | Padrão | Descrição                                                                                                 |
 | ----------------- | ----------- | ------ | --------------------------------------------------------------------------------------------------------- |
 | `showCloseButton` | `boolean`   | `true` | No modo padrão, inclui a ação de fechamento no header; o modo de alerta exige uma resposta identificável. |
-| `closeDisabled`   | `boolean`   | `false` | Mantém a ação visível e impede o fechamento enquanto a tarefa está bloqueada.                            |
+| `closeDisabled`   | `boolean`   | `false` | Mantém o botão de fechar visível e desabilitado e impede que Esc e o clique externo fechem a superfície. Handlers como `onEscapeKeyDown` e `onPointerDownOutside` continuam sendo chamados antes do bloqueio. |
 | `closeSize`       | `"xs" \| "sm"` | `"sm"` | Define o tamanho da ação circular de fechar.                                                  |
 | `layout`          | `'continuous' \| 'sectioned'` | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. Ignorado em `mode="alert"`. |
-| `className`       | `string`    |        | Ajusta a superfície.                                                                                      |
+| `className`       | `string`    |        | Ajusta a superfície. A largura máxima é `32rem` no modo padrão e `20rem` no alerta; amplie o alerta com `max-w-lg` quando o rodapé tiver três ações. |
 | `children`        | `ReactNode` |        | Cabeçalho, corpo, rodapé ou conteúdo próprio.                                                             |
 
 ## Propriedades de DialogHeader
@@ -409,7 +492,7 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 | Propriedade | Tipo        | Padrão | Descrição                            |
 | ----------- | ----------- | ------ | ------------------------------------ |
 | `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `h2` da primitiva | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
-| `className` | `string`    |        | Ajusta o título, que trunca quando não cabe na linha. |
+| `className` | `string`    |        | Ajusta o título. No modo padrão, ele trunca quando não cabe na linha; no alerta, fica centralizado e pode ocupar mais de uma linha. |
 | `children`  | `ReactNode` |        | Nome da tarefa ou do conteúdo modal. |
 
 ## Propriedades de DialogMedia

package/src/ui/docs/content/dictionary-value.md

@@ -1,6 +1,6 @@
 Use `DictionaryValue` para apresentar um valor de `t.dict` de acordo com o papel declarado pelo
-próprio dicionário. A tela fornece o dicionário e o código; o componente escolhe texto, badge e ícone
-sem perder o rótulo visível.
+próprio dicionário. A tela fornece o dicionário e o código; o componente escolhe texto,
+[`Badge`](/ui/badge) e ícone sem perder o rótulo visível.
 
 ```tsx preview
 <DictionaryValue
@@ -56,7 +56,7 @@ export const customerStageDict = t.dict(
 - `context` (`neutral` · `info` · `success` · `warning` · `danger`) só existe em status e estágio;
   `t.dict` rejeita o contexto em classificação e em `plain`.
 - `icon` é um nome do catálogo do Opus (`iconPickerIcons`). Nome fora do catálogo não renderiza
-  ícone; o renderer não inventa. Vocabulário próprio entra por `icons`.
+  ícone; o componente não escolhe um substituto. Vocabulário próprio entra por `icons`.
 - `description` é o texto curto para a pessoa e aparece em tooltip focável. Descrição igual ao
   rótulo não vira tooltip. `doc` é o entendimento de negócio para manifest e Lens; não aparece.
 
@@ -100,7 +100,7 @@ Valor fora do dicionário aparece como texto com o próprio código, marcado com
 
 ## Em ActionList
 
-Coluna cujo campo do schema de saída é um `t.dict().zod()` já renderiza `DictionaryValue` com o
+Em [`ActionList`](/ui/action-list), a coluna cujo campo do schema de saída é um `t.dict().zod()` já renderiza `DictionaryValue` com o
 papel declarado, sem `cells`. Quando o campo de saída é uma string comum, a coluna nomeia o
 dicionário registrado no provider: `{ key: 'source', label: 'Fonte', dictionary: 'customerSource' }`.
 Dimensões independentes (tipo e estágio, por exemplo) ficam em colunas distintas; não empilhar

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

@@ -1,7 +1,7 @@
-Ferramentas ancoradas à superfície de trabalho. Um canvas ou um editor raramente comporta mais
-uma faixa de chrome no topo: a trilha da aplicação já ocupa esse papel, e um segundo cabeçalho
-empilha duas faixas com a mesma função. A Dock coloca as ações sobre a própria superfície,
-agrupadas e sempre alcançáveis.
+Use `Dock` para as ferramentas de uma superfície de trabalho, como um canvas ou um editor. Essas
+telas raramente comportam mais uma barra no topo: a navegação da aplicação já ocupa esse lugar, e
+um segundo cabeçalho empilharia duas faixas com a mesma função. A Dock coloca as ações sobre a
+própria superfície, agrupadas e sempre alcançáveis.
 
 ```tsx preview
 <div className="relative h-40 w-full rounded-lg border border-border bg-muted/20">
@@ -23,8 +23,8 @@ agrupadas e sempre alcançáveis.
 
 O contêiner precisa ser `relative` — a Dock se ancora nele, não na janela. `position` escolhe a
 aresta: `bottom` (centro), `bottom-left` e `bottom-right`. Uma superfície pode ter mais de uma
-barra quando os papéis são distintos, como ferramentas ao centro e controles de viewport à
-esquerda.
+barra quando os papéis são distintos, como ferramentas ao centro e controles de visualização à
+direita.
 
 ## Grupos e divisórias
 
@@ -44,10 +44,43 @@ Mensagem de sucesso é transitória por natureza — some depois de confirmar
 permanece até o estado mudar. Essa decisão é da aplicação, que conhece o ciclo; o componente
 apenas reserva o lugar.
 
-`actions` recebe o que o recurso aberto permite fazer — em geral o mesmo menu que a linha dele
-tem na navegação. Assim a superfície deixa de ser o único lugar onde renomear ou excluir não
-alcançam o item que está na tela. Apenas o texto é região viva: anunciar o menu a cada mudança de
-estado seria ruído para quem usa leitor de tela.
+`actions` recebe o que o recurso aberto permite fazer — em geral o mesmo [`Menu`](/ui/menu) que a
+linha dele tem na navegação. Assim, renomear ou excluir também alcançam o item que está na tela.
+Apenas o texto é região viva: anunciar o menu a cada mudança de estado seria ruído para quem usa
+leitor de tela.
+
+No exemplo, o estado de falha fica no canto superior esquerdo com o menu do recurso, e os controles
+de visualização ficam no canto inferior direito.
+
+```tsx preview
+<div className="relative h-40 w-full rounded-lg border border-border bg-muted/20">
+  <SurfaceStatus
+    position="top-left"
+    context="danger"
+    actions={
+      <Menu>
+        <MenuTrigger asChild>
+          <Button variant="ghost" size="icon" aria-label="Ações do fluxo"><MoreHorizontal /></Button>
+        </MenuTrigger>
+        <MenuContent align="start">
+          <MenuItem><Pencil /> Renomear</MenuItem>
+          <MenuSeparator />
+          <MenuItem context="danger"><Trash2 /> Excluir</MenuItem>
+        </MenuContent>
+      </Menu>
+    }
+  >
+    Falha ao salvar
+  </SurfaceStatus>
+  <Dock label="Controles de visualização" position="bottom-right">
+    <DockGroup>
+      <DockAction icon={<ZoomOut />} label="Afastar" onClick={() => {}} />
+      <DockAction icon={<ZoomIn />} label="Aproximar" onClick={() => {}} />
+      <DockAction icon={<Maximize />} label="Ajustar à tela" onClick={() => {}} />
+    </DockGroup>
+  </Dock>
+</div>
+```
 
 ## Modo e execução
 
@@ -57,36 +90,36 @@ o rótulo, que também é o nome acessível.
 
 ## Teclado
 
-A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às pontas. Cada ação nomeia-se
-por tooltip, então `<TooltipProvider>` precisa existir na raiz do app — o esqueleto do `opus create`
-já monta.
+A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às pontas. Cada ação exibe o nome em um
+[tooltip](/ui/tooltip), então `<TooltipProvider>` precisa existir na raiz do app — o projeto criado
+por `opus create` já o monta.
 
 ## Propriedades de Dock
 
 | Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
 | `position` | `'bottom' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Aresta do contêiner onde a barra se ancora. |
-| `label` | `string` | | Nome acessível da barra. |
-| `children` | `ReactNode` | | Os grupos de ações, em `DockGroup`. |
+| `label` | `string` | obrigatório | Nome acessível da barra. |
+| `children` | `ReactNode` | obrigatório | Os grupos de ações, em `DockGroup`. |
 | `className` | `string` | | Classes adicionais da barra. |
 
 ## Propriedades de DockGroup
 
 | Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
-| `children` | `ReactNode` | | As ações do grupo, em `DockAction`. A divisória antes do grupo é aplicada automaticamente, exceto no primeiro. |
+| `children` | `ReactNode` | obrigatório | As ações do grupo, em `DockAction`. A divisória antes do grupo é aplicada automaticamente, exceto no primeiro. |
 | `className` | `string` | | Classes adicionais do grupo. |
 
 ## Propriedades de DockAction
 
 | Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
-| `icon` | `ReactNode` | | Ícone exibido no botão. |
-| `label` | `string` | | Nome da ação; vira o nome acessível e o tooltip quando não há `hint`. |
+| `icon` | `ReactNode` | obrigatório | Ícone exibido no botão. |
+| `label` | `string` | obrigatório | Nome da ação; vira o nome acessível e o tooltip quando não há `hint`. |
 | `pressed` | `boolean` | | Presente quando a ação liga um modo: aplica o preenchimento e expõe `aria-pressed`. Ausente quando a ação apenas executa. |
 | `disabled` | `boolean` | `false` | Desabilita a ação e a tira da navegação por setas. |
 | `hint` | `ReactNode` | `label` | Conteúdo do tooltip quando ele precisa dizer mais que o rótulo. |
-| `onClick` | `() => void` | | Executa a ação ou alterna o modo. |
+| `onClick` | `() => void` | obrigatório | Executa a ação ou alterna o modo. |
 | `className` | `string` | | Classes adicionais do botão. |
 
 ## Propriedades de SurfaceStatus
@@ -96,3 +129,5 @@ já monta.
 | `position` | `'top-right' \| 'top-left'` | `'top-right'` | Canto da superfície onde o estado se ancora. |
 | `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O que o estado comunica; tinge borda e texto pela família semântica. |
 | `actions` | `ReactNode` | | Ações do recurso aberto, fora da região viva. |
+| `children` | `ReactNode` | | O texto do estado, anunciado pela região viva a cada mudança. |
+| `className` | `string` | | Classes adicionais do contêiner. |

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

@@ -1,6 +1,7 @@
 Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `context`
-seleciona o significado e `variant` escolhe ponto sólido ou contornado. Quando a cor reforça significado, `label` fornece o nome
-acessível. Sem `label`, o ponto é decorativo.
+seleciona o significado e `variant` escolhe ponto sólido ou contornado. Quando a cor reforça
+significado, `label` fornece o nome acessível. Sem `label`, o ponto é decorativo e fica oculto dos
+leitores de tela.
 
 ```tsx preview
 <div className="flex items-center gap-4">
@@ -8,11 +9,25 @@ acessível. Sem `label`, o ponto é decorativo.
   <Dot context="warning" label="Atenção" />
   <Dot context="danger" label="Falhou" />
   <Dot context="info" label="Publicado" />
-  <Dot context="neutral" aria-hidden />
+  <Dot context="neutral" />
 </div>
 ```
 
-Use `Badge` quando o estado precisar permanecer legível sem depender do contexto ao redor.
+Use [`Badge`](/ui/badge) quando o estado precisar permanecer legível sem depender do contexto ao
+redor.
+
+## Ponto contornado
+
+`variant="outline"` desenha só o contorno. Ele diferencia dois estados que compartilham o mesmo
+`context`, como uma execução agendada e uma em andamento. O `label` continua nomeando cada estado.
+
+```tsx preview
+<div className="flex items-center gap-4 text-sm">
+  <span className="flex items-center gap-2"><Dot context="success" label="Em execução" /> developer</span>
+  <span className="flex items-center gap-2"><Dot context="success" variant="outline" label="Agendado" /> reviewer</span>
+  <span className="flex items-center gap-2"><Dot context="neutral" variant="outline" label="Inativo" /> designer</span>
+</div>
+```
 
 ## Propriedades de Dot
 
@@ -20,4 +35,19 @@ Use `Badge` quando o estado precisar permanecer legível sem depender do context
 |---|---|---|---|
 | `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado da cor. |
 | `variant` | `'solid' \| 'outline'` | `'solid'` | Ponto preenchido ou só contornado. |
-| `label` | `string` | | Nome acessível quando a cor comunica estado; sem ele o ponto é decorativo (`aria-hidden`). |
+| `label` | `string` | | Nome acessível quando a cor comunica estado; o ponto passa a ser exposto como imagem com esse nome. Sem ele, o ponto é decorativo (`aria-hidden`). |
+
+Os demais atributos vão para o elemento `span`.
+
+## Função dotVariants
+
+`dotVariants({ context, variant })` retorna as classes do ponto para um elemento que não é
+renderizado pelo `Dot`. Os padrões são os mesmos do componente: `neutral` e `solid`. Sem o
+componente, o elemento não recebe `label` nem `aria-hidden`; trate a acessibilidade nele.
+
+```ts
+function dotVariants(options?: {
+  context?: DotContext | null
+  variant?: DotVariant | null
+}): string
+```