@softize/opus 18.5.0 → 20.0.0

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
 
@@ -54,6 +55,164 @@ decide a distribuição nem a aparência dos botões.
 `DialogClose` encerra o modal sem exigir estado controlado. Use `open` e `onOpenChange` quando outra
 parte da interface também precisar controlar a abertura.
 
+## Regiões separadas ou contínuas
+
+`layout` declara a anatomia da superfície inteira e fica em `DialogContent`; os slots leem esse
+valor e não o recebem. O padrão é `sectioned`: as regiões têm o mesmo recuo, o rodapé ganha uma
+faixa sutil e as fronteiras entre regiões vizinhas ganham um divisor. É o modal de tarefa, com
+cabeçalho, conteúdo e ações claramente separados.
+
+Use `layout="continuous"` para uma superfície curta, em que o espaço basta para separar as regiões
+e a linha seria um ruído — um aviso de uma frase, uma escolha rápida.
+
+```tsx preview
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Publicar contrato</Button>
+  </DialogTrigger>
+  <DialogContent layout="continuous">
+    <DialogHeader>
+      <DialogTitle>Publicar contrato</DialogTitle>
+    </DialogHeader>
+    <DialogBody>
+      <p className="text-sm text-muted-foreground">
+        A versão publicada passa a valer para todos os consumidores.
+      </p>
+    </DialogBody>
+    <DialogFooter>
+      <ButtonGroup mode="spaced">
+        <DialogClose asChild>
+          <Button variant="ghost">Cancelar</Button>
+        </DialogClose>
+        <Button>Publicar</Button>
+      </ButtonGroup>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Os divisores do modo seccionado são derivados da vizinhança: cada região desenha a linha quando há
+uma região do outro lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um
+rodapé produz uma linha só. A tela não escreve `border-b` nem `border-t`.
+
+A faixa sutil do rodapé é a mesma no `Dialog` e no [`Drawer`](/ui/drawer): as duas famílias
+compartilham a anatomia, e um fluxo que troca de superfície não muda de aparência no meio.
+
+`mode="alert"` mantém a composição centrada da resposta obrigatória e não usa `layout`.
+
+## Ações e navegação no cabeçalho
+
+O cabeçalho reconhece quatro slots — `DialogNavigation`, `DialogMedia`, `DialogTitle` e
+`DialogActions` — e posiciona cada um: a navegação abre a linha, o título ocupa a folga, as ações
+vão para o extremo oposto e o botão de fechar entra depois delas. Um nó que não seja um desses
+slots interrompe a renderização com um erro; contexto e conteúdo pertencem ao `DialogBody`.
+
+Use `DialogActions` para uma ação da tela que precisa ficar à vista sem competir com o rodapé, como
+abrir um assistente ou alternar um modo de visualização. Use `DialogNavigation` para o retorno de um
+fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
+
+```tsx preview
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Revisar evento</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogNavigation>
+        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+          <ArrowLeft />
+        </Button>
+      </DialogNavigation>
+      <DialogTitle>Evento 4821</DialogTitle>
+      <DialogActions>
+        <Button variant="ghost" size="icon" aria-label="Mais ações">
+          <Ellipsis />
+        </Button>
+      </DialogActions>
+    </DialogHeader>
+    <DialogBody>
+      <p className="text-sm text-muted-foreground">Detalhe do evento selecionado.</p>
+    </DialogBody>
+  </DialogContent>
+</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
@@ -84,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
@@ -99,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"
@@ -144,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.
@@ -153,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
 <>
@@ -163,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
 
@@ -174,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
 
@@ -197,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.");
@@ -207,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>
@@ -243,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.
@@ -278,17 +446,32 @@ 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.                                                  |
-| `className`       | `string`    |        | Ajusta a superfície.                                                                                      |
+| `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. 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
 
 | Propriedade | Tipo        | Padrão | Descrição                                                  |
 | ----------- | ----------- | ------ | ---------------------------------------------------------- |
-| `className` | `string`    |        | Ajusta a faixa superior.                                   |
-| `children`  | `ReactNode` |        | Título e ações opcionais; o close padrão entra por último. |
+| `className` | `string`    |        | Ajusta a faixa superior sobre o recuo do layout.           |
+| `children`  | `ReactNode` |        | Somente `DialogNavigation`, `DialogMedia`, `DialogTitle` e `DialogActions`, no máximo um de cada; o fechamento padrão entra depois deles. |
+
+## Propriedades de DialogNavigation
+
+| Propriedade | Tipo        | Padrão | Descrição                                                      |
+| ----------- | ----------- | ------ | -------------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a região introdutória da linha.                         |
+| `children`  | `ReactNode` |        | Retorno de um fluxo modal encadeado, antes do título.          |
+
+## Propriedades de DialogActions
+
+| Propriedade | Tipo        | Padrão | Descrição                                                          |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------ |
+| `className` | `string`    |        | Ajusta o agrupamento das ações.                                    |
+| `children`  | `ReactNode` |        | Ações da tela no cabeçalho, antes do botão de fechar.              |
 
 ## Propriedades de DialogBody
 
@@ -308,15 +491,23 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 
 | Propriedade | Tipo        | Padrão | Descrição                            |
 | ----------- | ----------- | ------ | ------------------------------------ |
-| `className` | `string`    |        | Ajusta o título.                     |
+| `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. 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
 
-| Propriedade | Tipo        | Padrão | Descrição                                 |
-| ----------- | ----------- | ------ | ----------------------------------------- |
-| `className` | `string`    |        | Ajusta a moldura quadrada da mídia.       |
-| `children`  | `ReactNode` |        | Ícone que reforça o contexto da resposta. |
+A moldura vem do `IconTile`, como nas demais famílias. No `mode="alert"` ela cresce e centraliza:
+ali a mídia não acompanha uma linha de título, ela é o que faz a pessoa reconhecer a resposta.
+
+| Propriedade | Tipo                                                        | Padrão    | Descrição                                          |
+| ----------- | ----------------------------------------------------------- | --------- | -------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                          | `sm`      | Escala da moldura; no alerta vale a moldura maior. |
+| `context`   | `UiContext`                                                  | `neutral` | Cor semântica da moldura.                          |
+| `variant`   | `'subtle' \| 'outline'`                                      | `subtle`  | Tratamento visual da moldura.                      |
+| `className` | `string`                                                     |           | Ajustes pontuais da moldura.                       |
+| `children`  | `ReactNode`                                                  |           | Ícone que reforça o contexto da resposta.          |
+| `asChild` | `boolean` | `false` | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
 
 ## Propriedades de DialogClose
 

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
+```