@softize/opus 18.5.0 → 20.0.0

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

@@ -1,38 +1,44 @@
 ## Seção recolhível
 
-CollapsibleTrigger alterna o CollapsibleContent — o Trigger já é o <button>. defaultOpen deixa o estado com o componente.
+Use `Collapsible` para esconder um bloco secundário atrás de um gatilho, mantendo o restante da
+tela visível. `CollapsibleTrigger` já renderiza um `<button>` e alterna o `CollapsibleContent`.
+Sem `open`, o componente guarda o próprio estado; `defaultOpen` apenas define se ele começa aberto.
 
 ```tsx preview col
 <Collapsible defaultOpen className="w-full max-w-sm space-y-2">
-  <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted">
-    Repositórios do workspace
-    <ChevronsUpDown className="h-4 w-4 text-muted-foreground" />
+  <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted [&[data-state=open]>svg]:rotate-180">
+    Serviços incluídos na revisão
+    <ChevronDown className="size-4 text-muted-foreground transition-transform" />
   </CollapsibleTrigger>
   <CollapsibleContent className="space-y-1 px-3 text-sm text-muted-foreground">
-    <p>empresa-x-api</p>
-    <p>empresa-x-web</p>
-    <p>empresa-x-infra</p>
+    <p>Troca de óleo</p>
+    <p>Filtro de ar</p>
+    <p>Alinhamento</p>
   </CollapsibleContent>
 </Collapsible>
 ```
 
+O gatilho recebe `data-state="open"` ou `data-state="closed"`. O seletor
+`[&[data-state=open]>svg]:rotate-180` usa esse atributo para girar o ícone sem estado próprio.
+
 ## Controlado
 
-open + onOpenChange põem o estado nas suas mãos — dá para refletir no gatilho (aqui o chevron gira) ou guardar a preferência.
+Use `open` e `onOpenChange` quando outra parte da tela precisar conhecer o estado, por exemplo para
+trocar o texto do gatilho ou guardar a preferência da pessoa.
 
 ```tsx preview col
 const [open, setOpen] = useState(false)
 
 render(
   <Collapsible open={open} onOpenChange={setOpen} className="w-full max-w-sm space-y-2">
-    <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted">
-      Skills do agente developer
-      <ChevronDown className={open ? 'h-4 w-4 rotate-180 transition-transform' : 'h-4 w-4 transition-transform'} />
+    <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted [&[data-state=open]>svg]:rotate-180">
+      {open ? 'Ocultar peças utilizadas' : 'Mostrar peças utilizadas'}
+      <ChevronDown className="size-4 text-muted-foreground transition-transform" />
     </CollapsibleTrigger>
     <CollapsibleContent className="space-y-1 px-3 text-sm text-muted-foreground">
-      <p>clean-code</p>
-      <p>code-style</p>
-      <p>ddd</p>
+      <p>Filtro de óleo</p>
+      <p>Pastilhas de freio</p>
+      <p>Velas de ignição</p>
     </CollapsibleContent>
   </Collapsible>,
 )
@@ -40,16 +46,17 @@ render(
 
 ## Desabilitado
 
-disabled no Collapsible trava o gatilho — a seção fica fixa no estado atual (aqui, fechada).
+Use `disabled` no `Collapsible` quando a seção não puder mudar de estado por enquanto. O gatilho
+fica desabilitado e a seção permanece como está; no exemplo, fechada.
 
 ```tsx preview col
 <Collapsible disabled className="w-full max-w-sm space-y-2">
   <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium disabled:cursor-not-allowed disabled:opacity-50">
-    Sessões arquivadas
-    <ChevronsUpDown className="h-4 w-4 text-muted-foreground" />
+    Revisões anteriores
+    <ChevronDown className="size-4 text-muted-foreground" />
   </CollapsibleTrigger>
   <CollapsibleContent className="px-3 text-sm text-muted-foreground">
-    <p>Nada para mostrar enquanto o workspace está em sincronização.</p>
+    <p>O histórico fica disponível depois da sincronização com a concessionária.</p>
   </CollapsibleContent>
 </Collapsible>
 ```
@@ -61,4 +68,21 @@ disabled no Collapsible trava o gatilho — a seção fica fixa no estado atual
 | `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
 | `open` | `boolean` | | Estado no modo controlado. Use com `onOpenChange`. |
 | `onOpenChange` | `(open: boolean) => void` | | Chamado a cada abertura ou fechamento. |
-| `disabled` | `boolean` | `false` | Bloqueia o gatilho e mantém a seção no estado atual. |
+| `disabled` | `boolean` | `false` | Desabilita o gatilho e mantém a seção no estado atual. |
+| `className` | `string` | | Ajusta o contêiner. |
+
+## Propriedades de CollapsibleTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Usa o filho como gatilho, como um `Button`, sem criar outro `<button>`. |
+| `className` | `string` | | Ajusta o gatilho. O estado chega em `data-state`. |
+| `children` | `ReactNode` | | Rótulo do gatilho e, quando houver, o ícone de estado. |
+
+## Propriedades de CollapsibleContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `forceMount` | `boolean` | `false` | Mantém o conteúdo montado mesmo fechado, por exemplo para animá-lo por CSS. |
+| `className` | `string` | | Ajusta a região recolhível. |
+| `children` | `ReactNode` | | Conteúdo exibido quando a seção está aberta. |

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

@@ -1,7 +1,9 @@
 ## Lista filtrável inline
 
-Digite para filtrar uma coleção com navegação por teclado, grupos e estado vazio. Command é a base
-do Select pesquisável; para uma escolha em formulário, use Select.
+Use `Command` quando a pessoa precisar encontrar um item ou uma ação digitando parte do nome e
+escolher pelo teclado. A lista filtra enquanto a busca muda, organiza os itens em grupos e mostra
+um estado vazio quando nada corresponde. `Command` também é a base do `Select` pesquisável; para
+escolher um valor em um formulário, use [`Select`](/ui/select).
 
 ```tsx preview
 <Command className="max-w-sm rounded-lg border border-border">
@@ -14,26 +16,38 @@ do Select pesquisável; para uma escolha em formulário, use Select.
     </CommandGroup>
     <CommandSeparator />
     <CommandGroup heading="Ações">
-      <CommandItem><Plus /> Nova sessão <CommandShortcut>⌘N</CommandShortcut></CommandItem>
+      <CommandItem><Plus /> Criar sessão <CommandShortcut>⌘N</CommandShortcut></CommandItem>
       <CommandItem><Play /> Iniciar ambiente</CommandItem>
     </CommandGroup>
   </CommandList>
 </Command>
 ```
 
-## Palette modal (CommandDialog)
+## Paleta de comandos em modal
 
-O Command embrulhado em um Dialog mantém um header compacto com título e close. A descrição
-permanece disponível para tecnologias assistivas. O atalho ⌘K (keydown no app) só troca o open —
-o conteúdo é o mesmo do inline.
+`CommandDialog` apresenta a mesma lista dentro de um [`Dialog`](/ui/dialog), com um cabeçalho
+compacto que mostra o título e o botão de fechar. A descrição fica disponível somente para
+tecnologias assistivas. O componente não registra atalho de teclado: para abrir a paleta com
+⌘K, o aplicativo escuta o evento e altera `open`, como no exemplo.
 
 ```tsx preview
 const [open, setOpen] = useState(false)
 
+useEffect(() => {
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (event.key.toLowerCase() === 'k' && (event.metaKey || event.ctrlKey)) {
+      event.preventDefault()
+      setOpen((current) => !current)
+    }
+  }
+  document.addEventListener('keydown', onKeyDown)
+  return () => document.removeEventListener('keydown', onKeyDown)
+}, [])
+
 render(
   <>
     <Button variant="outline" onClick={() => setOpen(true)}>
-      Abrir palette <CommandShortcut>⌘K</CommandShortcut>
+      Abrir paleta <CommandShortcut>⌘K</CommandShortcut>
     </Button>
     <CommandDialog open={open} onOpenChange={setOpen}>
       <CommandInput placeholder="Buscar comando…" />
@@ -80,6 +94,7 @@ render(
 | `title` | `string` | `'Paleta de comandos'` | Título exibido no header compacto; também nomeia o diálogo para tecnologias assistivas. |
 | `description` | `string` | `'Busque um comando para executar…'` | Descrição disponível somente para tecnologias assistivas. |
 | `showCloseButton` | `boolean` | `true` | Exibe o botão de fechamento. |
+| `className` | `string` | | Classes do conteúdo do diálogo, como a largura. |
 
 ## Propriedades de CommandItem
 
@@ -96,3 +111,10 @@ render(
 |---|---|---|---|
 | `heading` | `React.ReactNode` | | Título exibido acima dos itens do grupo. |
 | `value` | `string` | | Identificador do grupo; obrigatório e único quando não há `heading`. |
+
+`CommandList` limita a altura a `18.75rem` e rola o excedente; `CommandEmpty` aparece somente quando
+nenhum item corresponde à busca; `CommandSeparator` divide grupos; e `CommandShortcut` mostra, à
+direita do item, a combinação de teclas que o aplicativo associou à ação. Esses componentes não têm
+propriedades próprias além das props nativas do elemento que renderizam; `className` soma classes
+ao estilo padrão de cada um. O atalho exibido por `CommandShortcut` é apenas informativo:
+registrar o evento continua com o aplicativo.

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

@@ -1,6 +1,14 @@
 ## Envio de texto
 
-A caixa de escrever da casa: textarea em uma pílula elevada (`rounded-xl` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/ui/chat) extraído — use sozinho quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse dono consuma **↑/↓**; sem eles, as setas mantêm o comportamento nativo da textarea.
+Use `Composer` quando a tela precisar receber um texto para envio sem apresentar uma conversa, como
+a descrição que abre uma nova sessão de trabalho. É a mesma caixa de escrita do [Chat](/ui/chat):
+um campo que cresce com o texto, com o botão de enviar dentro da moldura. **Enter** envia e
+**Shift+Enter** quebra a linha.
+
+O componente é controlado: `value` e `onChange` pertencem a quem o compõe, que também limpa o texto
+depois do envio. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse
+dono use **↑** e **↓** para navegar por um histórico próprio; sem eles, as setas mantêm o
+comportamento nativo do campo.
 
 ```tsx preview col
 const [text, setText] = React.useState('')
@@ -15,9 +23,15 @@ render(
 )
 ```
 
-## Com seletores (barra de ações)
+## Com seletores na barra de ações
+
+Com `actions`, o composer passa a ter duas linhas: o campo em cima e, embaixo, uma barra com os
+seletores à esquerda e o botão de enviar à direita. Use ali escolhas que definem o destino do texto,
+como o aplicativo, a tarefa ou o agente. Mantenha os controles discretos, como um `Button` `ghost` ou
+um [`Select`](/ui/select) `variant="ghost"`: a barra acompanha o texto e não é um formulário.
 
-Passe `actions` e o composer vira **duas linhas**: textarea em cima, uma barra limpa embaixo com os seletores à ESQUERDA e o enviar à direita. Estilize os controles como discretos (ghost, sem borda) — a barra não é um formulário. É onde o Maestro prende **app + task** e a GB, o **agente**. O `submitDisabled` trava o enviar além de vazio/busy (ex.: falta escolher o app), sem esconder a barra.
+`submitDisabled` impede o envio enquanto falta uma condição além do texto, como escolher o
+aplicativo, sem esconder a barra.
 
 ```tsx preview col
 const [text, setText] = React.useState('')
@@ -55,11 +69,12 @@ render(
 |---|---|---|---|
 | `value` | `string` | | Texto controlado; o dono do estado é quem compõe. |
 | `onChange` | `(value: string) => void` | | Recebe cada alteração do texto. |
-| `onSubmit` | `() => void` | | Enter (sem Shift) ou o botão enviar; só dispara quando dá para enviar. |
+| `onSubmit` | `() => void` | | Chamado por Enter (sem Shift) ou pelo botão de enviar, somente quando há texto e nem `busy` nem `submitDisabled` estão ativos. |
 | `onHistoryPrevious` / `onHistoryNext` | `() => boolean` | | Navegação por ↑/↓ no histórico do dono; retorne `true` quando a tecla foi consumida. |
-| `busy` | `boolean` | `false` | Trava o composer enquanto o turno corre; o enviar vira spinner. |
-| `submitDisabled` | `boolean` | `false` | Gate extra de envio além de vazio e `busy` (ex.: falta escolher o app). |
+| `busy` | `boolean` | `false` | Bloqueia o envio enquanto a operação anterior corre e troca o ícone de enviar por um spinner. O campo continua editável. |
+| `submitDisabled` | `boolean` | `false` | Bloqueia o envio por uma condição do consumidor, como um seletor ainda sem escolha. |
 | `placeholder` | `string` | `'Escreva uma mensagem…'` | Texto de orientação do campo. |
-| `rows` | `number` | `1` | Linhas iniciais do textarea; ele cresce com o conteúdo. |
+| `rows` | `number` | `1` | Linhas iniciais do campo, que cresce com o conteúdo até `10rem`. |
 | `autoFocus` | `boolean` | | Foca o campo ao montar. |
-| `actions` | `ReactNode` | | Controles discretos à esquerda do enviar; presente, o composer vira duas linhas. |
+| `actions` | `ReactNode` | | Controles discretos à esquerda do botão de enviar; com eles, o composer passa a ter duas linhas. |
+| `className` | `string` | | Classes aplicadas à moldura do composer. |

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

@@ -4,12 +4,19 @@ Use `Content` para dar título e estrutura a uma região dentro de `PageBody`, `
 `DialogBody` ou outra superfície. Ele renderiza uma `section` ligada ao próprio título e mantém o
 espaçamento entre header e body. `ContentHeader` pertence sempre a essa estrutura; não o use solto.
 
-No caso comum, prefira o shorthand:
+O `Content` é contínuo por definição e não expõe `layout`: ele é uma região nomeada dentro de outra
+superfície, e a escolha entre regiões seccionadas e contínuas pertence a quem a hospeda — o
+[`Card`](/ui/card), o [`Dialog`](/ui/dialog), o [`Drawer`](/ui/drawer) ou o [`Pane`](/ui/pane).
+Quando a própria região precisar de uma fronteira visível, use `framed`, descrito adiante. Pelo
+mesmo motivo o `Content` não tem rodapé: um rodapé pertence à superfície que a hospeda.
+
+No caso comum, prefira o shorthand. `count` mostra o total de itens ao lado do título:
 
 ```tsx preview col
 render(
   <Content
     title="Dispositivos conectados"
+    count={3}
     description="Sessões com acesso à sua conta."
     actions={<Button variant="outline">Encerrar outras sessões</Button>}
   >
@@ -126,13 +133,33 @@ do pai correto, filhos estruturais indiretos e a mistura de shorthand com compos
 ## Coleção nomeada
 
 Quando a região principal da página é uma coleção, `Content` nomeia e governa essa coleção, enquanto
-`ActionList` executa a consulta. Coloque criar, importar e outras ações sobre o conjunto completo em
+[`ActionList`](/ui/action-list) executa a consulta. Coloque criar, importar e outras ações sobre o conjunto completo em
 `ContentActions`. Busca, filtros, atualização e operações dependentes do recorte atual permanecem na
 toolbar da lista. Essa divisão aproxima cada comando do objeto que ele afeta sem criar uma família
-paralela de componentes `List*`. Na variante `page`, as ações ficam no extremo oposto ao título. A
-criação usa um `Button` textual na variante padrão (`solid`) e no tamanho `default`, sem ícone,
-nomeado `Criar recurso`; o diálogo aberto pelo
-gatilho repete esse título e a edição usa `Editar recurso`.
+paralela de componentes `List*`.
+
+Quando a coleção é o assunto da página, use `variant="page"` com `level={1}`: o `Content` assume a
+escala do cabeçalho de [`Page`](/ui/page) e passa a ser o heading principal. As ações ficam no
+extremo oposto ao título, como em qualquer variante.
+
+```tsx preview col
+render(
+  <Content level={1} variant="page" title="Clientes" actions={<Button>Criar cliente</Button>}>
+    <div className="rounded-lg border border-border p-4 text-sm text-muted-foreground">
+      A lista de clientes ocupa o corpo.
+    </div>
+  </Content>,
+);
+```
+
+A criação usa um `Button` textual na variante padrão (`solid`) e no tamanho `default`, sem ícone,
+nomeado `Criar {recurso}` (por exemplo, `Criar cliente`); o diálogo aberto pelo gatilho repete esse
+título, e a edição usa `Editar {recurso}`.
+
+Em uma [`Page`](/ui/page) com `layout="fill"`, a coleção pode ocupar a altura da página e rolar só os
+resultados. `Content` e `ContentBody` repassam a altura até a [`ActionList`](/ui/action-list) sem
+classes adicionais; um `Content` irmão, sem lista, mantém a altura do próprio conteúdo. A seção
+“Ocupar a altura disponível” da `ActionList` mostra a composição completa.
 
 ## Propriedades de Content
 
@@ -141,12 +168,15 @@ gatilho repete esse título e a edição usa `Editar recurso`.
 | `title`        | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                                      |
 | `count`        | `number`                     |             | Forma curta: total de itens ao lado do título da região.                                                                |
 | `description`  | `ReactNode`                  |             | Forma curta: frase de apoio sob o título.                                                                               |
-| `actions`      | `ReactNode`                  |             | Forma curta: ações sobre a região inteira; em `page`, ficam no extremo oposto ao título.                                |
+| `actions`      | `ReactNode`                  |             | Forma curta: ações sobre a região inteira, no extremo oposto ao título.                                                 |
 | `level`        | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2`         | Nível semântico do heading, independente do destaque visual.                                                            |
 | `variant`      | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície.                |
 | `as`           | `'section' \| 'fieldset'`    | `'section'` | Usa uma região com heading ou um grupo de campos cujo título é a legenda nativa.                                        |
 | `framed`       | `boolean`                    | `false`     | Envolve o header e o body com a moldura estrutural da região.                                                           |
 | `frameVariant` | `'default' \| 'legend'`      | `'default'` | Em `fieldset` com moldura, mantém a borda contínua ou integra visualmente a legenda à borda. Não altera a semântica.    |
+| `children`     | `ReactNode`                  |             | Corpo da região na forma curta, ou `ContentHeader` e `ContentBody` na composição explícita.                             |
+
+As demais propriedades são as nativas de `section` ou, com `as="fieldset"`, de `fieldset`.
 
 Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e
 `ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`

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

@@ -1,6 +1,9 @@
 ## Copiar por ícone
 
-Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5s. Bom para toolbar ou célula estreita, ao lado de um ID/token/slug.
+Use `Copyable` para que a pessoa copie um valor exato com um clique, como um identificador, uma
+chave ou um endereço. Sem filhos, ele é um botão só com ícone: copia `value` e troca o ícone por um
+check durante 1,5 segundo. Essa forma cabe em barras de ferramentas e células estreitas, ao lado do
+valor exibido.
 
 ```tsx preview
 <Copyable value="opus_sk_1a2b3c4d5e6f" className="text-muted-foreground hover:text-foreground" />
@@ -8,7 +11,8 @@ Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5
 
 ## Com rótulo
 
-Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar no conjunto copia. Componha o chrome (borda, mono) por fora, via `className`.
+Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar no conjunto copia. Borda,
+fonte monoespaçada e demais detalhes visuais entram por `className`.
 
 ```tsx preview
 <Copyable
@@ -19,21 +23,48 @@ Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar n
 </Copyable>
 ```
 
+## Nome acessível
+
+Com rótulo visível, o nome do botão é o próprio texto dos filhos. Quem usa comando de voz aciona o
+botão dizendo o que vê, e o nome não muda durante a confirmação. Sem filhos, o botão se chama
+“Copiar” e, durante a confirmação, “Copiado”.
+
+A confirmação também é anunciada por leitores de tela: uma região de status, invisível na tela e
+fora do botão, diz “Copiado” sem interromper a leitura em andamento.
+
+Quando houver mais de um botão só com ícone na mesma tela, passe `aria-label` para distinguir o que
+cada um copia, como “Copiar o ID do pedido”. Com rótulo visível, o `aria-label` raramente é
+necessário; se usá-lo, comece pelo texto que a pessoa vê. Um `aria-label` próprio substitui os nomes
+padrão, inclusive o “Copiado”, e o anúncio da confirmação continua.
+
 ## Duração do feedback
 
-`feedbackMs` ajusta por quanto tempo a confirmação aparece; o padrão é 1500 milissegundos. Se a
-área de transferência não estiver disponível, a ação não produz efeito.
+`feedbackMs` ajusta por quanto tempo a confirmação aparece; o padrão é 1500 milissegundos.
 
 ```tsx preview
-<Copyable value="copiado devagar" feedbackMs={3000} className="text-muted-foreground hover:text-foreground">
-  copiar (3s)
+<Copyable
+  value="https://opus.softize.dev/w/empresa-x"
+  feedbackMs={3000}
+  className="text-muted-foreground hover:text-foreground"
+>
+  Copiar link
 </Copyable>
 ```
 
+A confirmação só aparece depois que a área de transferência aceita o texto. Se ela não estiver
+disponível, como em uma página sem HTTPS, ou recusar a escrita, o ícone não muda.
+
 ## Propriedades de Copyable
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `string` | | O texto que vai para a área de transferência no clique. |
+| `value` | `string` | obrigatório | O texto que vai para a área de transferência no clique. |
 | `feedbackMs` | `number` | `1500` | Duração do estado “copiado”, em milissegundos. |
-| `children` | `ReactNode` | | Rótulo ao lado do ícone; sem ele, o controle é só o ícone com nome acessível. |
+| `children` | `ReactNode` | | Rótulo visível ao lado do ícone. Quando presente, é o nome acessível do botão. |
+| `aria-label` | `string` | sem filhos, `'Copiar'`, ou `'Copiado'` durante a confirmação | Nome acessível do botão. Substitui o nome vindo dos filhos e os nomes padrão. |
+
+Os demais atributos vão para o elemento `button`. Um `onClick` próprio roda antes da cópia. O
+botão é o único elemento que o Copyable coloca no contêiner: a região de status fica no fim do
+`body`, visível apenas para leitores de tela, e é uma só para todos os Copyable da página. Ela
+aparece com o primeiro Copyable montado e sai com o último, então uma tabela com um botão de copiar
+por linha não multiplica regiões.

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

@@ -4,15 +4,16 @@ title: Customização
 
 # Customização
 
-Cinco alavancas, do global ao pontual — e um limite de propósito. O caminho previsto é compor
-e configurar, nunca forkar componente: o que não cabe nas alavancas evolui no Opus (com
-divergência declarada), para valer para casa toda.
+Quando a aplicação precisa de outra marca, outra largura ou outro comportamento, o Opus oferece
+cinco alavancas, da mais global à mais pontual. Todas partem de compor e configurar os componentes
+existentes; nenhuma exige copiar um componente para dentro do projeto e mantê-lo à parte. O que não
+couber nelas evolui no próprio Opus, para valer em todos os projetos.
 
 ## 1 · Identidade por tokens
 
-> O jeito canônico de vestir a marca. Sobrescreva as vars no `:root` depois de importar o
-> `theme.css` — todos os componentes acompanham, sem forkar nada. Dark incluso (a classe `.dark`
-> re-declara as vars).
+Para aplicar a marca, sobrescreva as variáveis CSS em `:root` depois de importar `theme.css`. Todos
+os componentes acompanham a mudança, e o tema escuro também: a classe `.dark` redeclara as mesmas
+variáveis.
 
 ```css
 /* index.css do app — depois do import do tema. */
@@ -26,27 +27,20 @@ divergência declarada), para valer para casa toda.
 ```
 
 O Opus deriva de `rounded-xs` a `rounded-2xl` dessa base. Assim, a marca muda a presença dos
-cantos sem substituir as utilities escolhidas pelos componentes nem criar tokens por papel.
+cantos sem substituir as utilities escolhidas pelos componentes nem criar tokens por papel. A lista
+completa de variáveis está em [Tokens](/ui/tokens).
 
 O tema não define `font-size` em `html`: a fonte raiz pertence ao navegador e à aplicação.
 Quando o produto precisa de outra densidade, declare essa escolha no CSS do app. Por exemplo,
-`html { font-size: 93.75%; }` conserva a proporção que uma raiz de 15 teria sobre a base usual
-de 16, sem transformar esse valor em uma regra da biblioteca.
-
-## Layout desktop
-
-O Opus oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
-Classes de tamanho, como `size="sm"`, escolhem a densidade do componente; não representam
-breakpoints. Overflow e limites contra a janela continuam protegendo o conteúdo.
-
-Não adicione uma adaptação isolada por viewport ou container em `className`. Uma futura
-responsividade precisa começar pelo shell e formar um contrato comum para navegação, splits,
-tabelas e componentes.
+`html { font-size: 93.75%; }` reduz a raiz a 15/16 da fonte que o navegador oferece, e tudo que o
+Opus mede em `rem` acompanha a proporção. O valor continua sendo uma escolha do app, não uma regra
+da biblioteca.
 
 ## 2 · className em tudo
 
-> Todo componente termina em `cn(base, className)` com tailwind-merge: o utilitário do consumidor
-> vence o conflito. Para layout local (largura, margem, grid) — não para repintar o visual da casa.
+Todo componente aceita `className` e o combina com as próprias classes por tailwind-merge: quando
+duas classes disputam a mesma propriedade, a do consumidor vence. Use essa alavanca para o layout
+local, como largura, margem e grid, e não para repintar o visual dos componentes.
 
 ```tsx
 <Button className="w-full">Continuar</Button>
@@ -56,73 +50,88 @@ tabelas e componentes.
 
 ## 3 · Recomposição estrutural
 
-> Os componentes são explodidos em slots. `asChild` (Radix Slot) renderiza como outro elemento
-> mantendo estilo e comportamento; os `*Variants` aplicam a cara da casa em um elemento arbitrário.
+Os componentes são divididos em partes nomeadas, como `CardHeader` e `CardBody`, e a tela usa só as
+que precisa. `asChild` faz o filho assumir o estilo e o comportamento do componente, e as funções
+`*Variants` aplicam o visual de um componente a um elemento qualquer.
 
 ```tsx preview
 <Button asChild variant="outline">
-  <a href="#" onClick={(e) => e.preventDefault()}>Âncora com cara de botão</a>
+  <a href="#" onClick={(e) => e.preventDefault()}>Link com aparência de botão</a>
 </Button>
 ```
 
 ```tsx
-// Slots: só o que a tela pede.
+// Partes: só o que a tela pede.
 <Card>
   <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
   <CardBody>…</CardBody>
 </Card>
 
-// asChild: o filho VIRA o botão (sem forkar estilo).
+// asChild: o link assume o estilo e o comportamento do botão.
 <Button asChild><a href="/docs">Abrir documentação</a></Button>
 
-// buttonVariants: a cara da casa em um elemento qualquer.
+// buttonVariants: o visual do botão em outro elemento.
 <a className={buttonVariants({ variant: 'outline' })}>Link estilizado</a>
 ```
 
 ## 4 · Comportamento por props
 
-> Modo controlado em tudo que abre ou seleciona (`open`/`onOpenChange`, `value`/`onValueChange`),
-> posicionamento (`align`/`side`/`sideOffset`), `showCloseButton`, `delayDuration`… A orquestração
-> é do implementador; o visual continua o da casa.
+Tudo o que abre ou seleciona aceita modo controlado (`open` e `onOpenChange`, `value` e
+`onValueChange`). Posicionamento (`align`, `side`, `sideOffset`) e tempos (`delayDuration`) também
+são props. A orquestração fica com a aplicação; o visual continua o dos componentes.
 
 ```tsx
 const [open, setOpen] = useState(false)
 
 <Dialog open={open} onOpenChange={setOpen}>…</Dialog>
-<DialogContent showCloseButton={false} />     {/* modal que exige ação */}
+<Dialog mode="alert">…</Dialog>                {/* exige uma resposta explícita */}
 <PopoverContent align="start" sideOffset={8} />
 <TooltipProvider delayDuration={200}>…
 ```
 
+Para exigir uma resposta, use `Dialog mode="alert"`: ele não fecha pelo clique externo e não mostra
+o botão de fechar. Apenas esconder o botão com `showCloseButton={false}` não impede o fechamento por
+Esc nem pelo clique externo. Veja [Dialog](/ui/dialog).
+
 ## 5 · Nos patterns, o contrato é a customização
 
-> Os patterns (ActionForm/Search/View/Trigger): o spec dirige. `fields`/`widget`/`showWhen`/
-> `fieldOptions` no form, `columns` no search, render prop no view. O caminho previsto é a feature
-> EMBRULHAR o pattern — nunca forkar.
+Nos patterns — [`ActionForm`](/ui/action-form), [`ActionList`](/ui/action-list),
+[`ActionView`](/ui/action-view) e [`ActionTrigger`](/ui/action-trigger) —, o contrato da action
+determina campos, colunas e estados. A tela ajusta o que é dela: `fieldOptions` no formulário,
+`columns` na lista, a função de render no `ActionView`. Para ir além, envolva o pattern em um
+componente da feature em vez de copiá-lo.
 
 ```tsx
-// O form NASCE do contrato; a tela só ajusta o que é seu.
+// O formulário vem do contrato; a tela só fornece as opções que conhece.
 <ActionForm
   action={workspaceCreateContract}
-  fieldOptions={{ skillIds: skillsDoWorkspace }}
+  fieldOptions={{ ownerId: workspaceMembers }}
   onSuccess={(d) => navigate(`/workspaces/${d.id}`)}
 />
 
-// O search recebe as colunas; a célula é render livre.
+// A lista recebe as colunas; a célula é render livre.
 <ActionList action={listAction} input={{ q }} columns={[
   { key: 'name', header: 'Workspace', cell: (w) => w.name },
 ]} />
 ```
 
-## O limite — de propósito
+## Largura mínima e densidade
 
-> O look curado não é customizável no app: rodapé-faixa do dialog, elevação no dark, `active:brightness-90`
-> do botão, a seta do tooltip — é identidade da casa, igual em todo projeto.
+O Opus oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
+Props de tamanho, como `size="sm"`, escolhem a densidade do componente; não representam
+breakpoints. Overflow e limites contra a janela continuam protegendo o conteúdo.
 
-```tsx preview
-<Badge context="success">Cabe nas alavancas</Badge>
-```
+Não adicione em `className` uma adaptação isolada por viewport ou container. Uma responsividade
+futura precisa começar pelo shell e formar um contrato comum para navegação, splits, tabelas e
+componentes.
+
+## O que fica fora das alavancas
+
+Alguns detalhes fazem parte da identidade visual do Opus e são iguais em todo projeto: a faixa do
+rodapé do dialog, a elevação no tema escuro, o escurecimento do botão ao ser pressionado
+(`active:brightness-90`) e a seta do tooltip. Eles não são configuráveis pela aplicação.
 
-Se uma necessidade real não cabe nas alavancas (tokens · className · slots/asChild · props ·
-contrato), o movimento não é dialeto local: é evoluir o componente **no Opus**, com a divergência
-declarada (skill `build-opus-ui`) — assim a mudança vale para casa toda, e esta doc passa a mostrá-la.
+Se uma necessidade real não cabe nas alavancas (tokens, `className`, partes e `asChild`, props e
+contrato), não crie uma variação local. Proponha a evolução do componente no Opus, com a
+divergência declarada conforme a skill `build-opus-ui`; assim a mudança vale para todos os projetos
+e passa a aparecer nesta documentação.