@softize/opus 19.0.0 → 20.1.0

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

@@ -10,12 +10,13 @@ superfície, e a escolha entre regiões seccionadas e contínuas pertence a quem
 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:
+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>}
   >
@@ -30,21 +31,15 @@ render(
 
 Use `framed` quando título e corpo precisarem formar uma única região delimitada. A moldura pertence
 ao `Content`; componentes internos, como `DetailGroup`, continuam responsáveis somente pelo layout
-e pela semântica dos próprios dados.
+e pela semântica dos próprios dados. Por padrão, a borda permanece contínua e o header fica dentro
+do recuo da região.
 
 ```tsx preview col
 render(
   <Content
     framed
-    title={
-      <span className="flex items-center gap-2">
-        <UserRound
-          className="size-4 text-muted-foreground"
-          aria-hidden="true"
-        />
-        Cliente
-      </span>
-    }
+    title="Cliente"
+    media={<UserRound aria-hidden="true" />}
   >
     <DetailGroup columns={2}>
       <DetailField label="Nome" value="Carla Souza" />
@@ -54,16 +49,66 @@ render(
 );
 ```
 
+## Header integrado à moldura
+
+Quando uma região compacta precisar integrar visualmente o header à borda, use
+`frameVariant="legend"`. O acabamento não muda a semântica: uma região de leitura continua sendo
+uma `section`, o título continua sendo um heading e descrição, contador e ações permanecem
+disponíveis.
+
+```tsx preview col
+render(
+  <Content
+    framed
+    frameVariant="legend"
+    title="Veículo"
+    media={<CarFront aria-hidden="true" />}
+  >
+    <DetailGroup columns={2}>
+      <DetailField label="Placa" value="ABC1D23" />
+      <DetailField label="Modelo" value="Corolla XEi" />
+    </DetailGroup>
+  </Content>,
+);
+```
+
+Para interromper a borda, o header pinta o título e as ações com o fundo da superfície que hospeda o
+`Content`, lido da variável CSS `--surface-background`. `Card`, `Dialog` e `Drawer` já a declaram
+com o fundo que pintam; fora deles, vale `--background`. Uma superfície com fundo próprio, como um
+`Card` com `bg-*`, um `Popover` ou um contêiner da aplicação, precisa declarar a variável com o
+mesmo fundo. Sem isso, a faixa atrás do título aparece com a cor da página.
+
+```tsx preview col
+render(
+  <Card className="bg-muted [--surface-background:var(--muted)]">
+    <CardBody>
+      <Content framed frameVariant="legend" title="Veículo">
+        <DetailGroup columns={2}>
+          <DetailField label="Placa" value="ABC1D23" />
+          <DetailField label="Modelo" value="Corolla XEi" />
+        </DetailGroup>
+      </Content>
+    </CardBody>
+  </Card>,
+);
+```
+
 ## Grupo de campos
 
 Quando a região nomear um conjunto de campos relacionados, use `as="fieldset"`. O `Content`
 renderiza o título como `legend`, preserva as props nativas do `fieldset` e mantém o mesmo contrato
 de título e corpo. Essa escolha altera somente a semântica e o comportamento nativo; com `framed`,
-a moldura permanece contínua. Nesse modo, contador, descrição e ações não entram na legenda.
+a moldura permanece contínua. A mídia usa a mesma apresentação da `section`; contador, descrição e
+ações não entram na legenda.
 
 ```tsx preview col
 render(
-  <Content as="fieldset" framed title="Proprietário">
+  <Content
+    as="fieldset"
+    framed
+    title="Proprietário"
+    media={<UserRound aria-hidden="true" />}
+  >
     <FieldGroup>
       <Field>
         <FieldLabel htmlFor="owner-name">Nome</FieldLabel>
@@ -78,8 +123,9 @@ render(
 );
 ```
 
-Quando a legenda precisar integrar visualmente a borda, declare essa escolha separadamente. Use
-`frameVariant="legend"` em agrupamentos compactos, como as seções de filtros avançados.
+O mesmo acabamento pode integrar a legenda nativa à borda. Declare `frameVariant="legend"` em
+agrupamentos compactos, como as seções de filtros avançados; `as="fieldset"` continua sendo a
+decisão semântica, e não uma forma de obter esse desenho.
 
 ```tsx preview col
 render(
@@ -103,13 +149,16 @@ render(
 
 Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
 `ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
-uma descrição, um contador (`ContentMeta`) e uma região de ações. O contador é próprio de
-`Content`; `PageHeader` reconhece somente navegação, título e ações.
+uma mídia (`ContentMedia`), uma descrição, um contador (`ContentMeta`) e uma região de ações. O
+contador é próprio de `Content`; `PageHeader` reconhece somente navegação, título e ações.
 
 ```tsx preview col
 render(
   <Content level={2}>
     <ContentHeader>
+      <ContentMedia>
+        <Monitor aria-hidden="true" />
+      </ContentMedia>
       <ContentTitle>Dispositivos conectados</ContentTitle>
       <ContentMeta>3</ContentMeta>
       <ContentDescription>Sessões com acesso à sua conta.</ContentDescription>
@@ -132,28 +181,71 @@ 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
 
 | Propriedade    | Tipo                         | Padrão      | Descrição                                                                                                               |
 | -------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
 | `title`        | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                                      |
+| `media`        | `ReactNode`                  |             | Forma curta: ícone ou imagem que identifica a região antes do título.                                                   |
 | `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.    |
+| `frameVariant` | `'default' \| 'legend'`      | `'default'` | Mantém a borda contínua ou integra visualmente o header à moldura. Não altera o elemento nem sua 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 de uma `section`, `ContentHeader` recebe `ContentMedia`, `ContentTitle`,
+`ContentMeta`, `ContentDescription` e `ContentActions`. Em `fieldset`, recebe `ContentMedia` e
+`ContentTitle`, preservando a apresentação enquanto a legenda continua nomeando somente o grupo de
+campos. `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level` próprios — a
+hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.
+
+## Propriedades de ContentMedia
+
+| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                                                                                   |
+| ----------- | ------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'xs'`      | Tamanho da moldura e do glifo na escala compartilhada dos controles.                                                        |
+| `context`   | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor.                                                                                               |
+| `variant`   | `'subtle' \| 'outline'`                                                   | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                                                                                |
+| `className` | `string`                                                                 |             | Ajusta a moldura sem substituir a escala.                                                                                   |
+| `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. |
+
+`ContentMedia` já é a moldura. Passe só o glifo e escolha `size`, `context` e `variant` no slot. Um
+`IconTile` passado em `media` ou dentro de `ContentMedia` não vira moldura dentro de moldura: o slot
+assume o lugar dele e herda o que ele declara. `media` com `null` ou `false` não desenha nada.
 
-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`
-próprios — a hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.
+Em `fieldset`, a mídia é sempre decorativa: o `Content` a esconde da árvore de acessibilidade para
+que o grupo seja anunciado apenas pelo título.

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.

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

@@ -1,36 +1,51 @@
+---
+title: Evolução contínua
+---
+
 # Evolução contínua
 
-O Opus cresce por **reincidência, nunca por especulação**. Quando o mesmo comportamento genérico reaparece em mais de um projeto, ele vira candidato a peça do Opus — e o projeto troca a implementação local pelo import. Estilo e conveniência não entram; comportamento que se repete, sim.
+Use este fluxo quando o seu projeto precisar de algo que o Opus ainda não oferece ou encontrar um
+defeito nele. O Opus incorpora um comportamento quando ele se repete em mais de um projeto; então o
+projeto troca a implementação local pelo import. Preferência de estilo e conveniência isolada não
+são motivo para incorporar uma peça.
 
-## Onde você aponta
+## Registrar um apontamento
 
-Cada apontamento vira uma Issue no repositório do Opus. Antes de abrir, procure uma Issue existente para o mesmo comportamento e comente nela. Dois tipos:
+Cada apontamento vira uma Issue em
+[github.com/softize-dev/opus](https://github.com/softize-dev/opus/issues). Antes de abrir uma nova,
+procure uma Issue sobre o mesmo comportamento e comente nela. Há dois tipos:
 
-- **`enhancement`** — código genérico que o Opus deveria ganhar (serviria a qualquer projeto). Antes de apontar, confira o que o Opus já tem (o inventário de componentes, os exports, esta doc): se já existe, use.
-- **`bug`** — um defeito ou limitação no próprio Opus, achado usando-o.
+- **`enhancement`:** código genérico que serviria a qualquer projeto. Antes de apontar, confira se o
+  Opus já oferece o recurso no inventário de componentes, nos exports ou nesta documentação; se
+  oferecer, use-o.
+- **`bug`:** defeito ou limitação do próprio Opus, encontrado durante o uso.
 
-Descreva cada apontamento com estes campos — um exemplo de cada tipo:
+Descreva cada apontamento com estes campos, como nos exemplos:
 
 ```text
 {"type": "enhancement", "behavior": "o comportamento em uma frase.", "file": "src/onde-vive.ts", "kind": "ui|sdk|driver|infra"}
-{"type": "bug", "behavior": "o que quebra ou falta.", "file": "onde se manifesta.", "note": "repro + o workaround aplicado."}
+{"type": "bug", "behavior": "o que quebra ou falta.", "file": "onde se manifesta.", "note": "como reproduzir e o contorno aplicado."}
 ```
 
-## Não trave esperando
+O pacote não coleta apontamentos do seu projeto automaticamente.
 
-O ponto do ciclo é **não bloquear a entrega**. Bateu em um gap ou em um bug do Opus:
+## Seguir sem esperar a correção
 
-1. **Contorne local** — componha um wrapper no seu projeto. O Opus entrega _source_, então dá para embrulhar qualquer superfície dele. Nunca edite `node_modules` (some no próximo install).
-2. **Entregue** a feature com o workaround.
-3. **Aponte** na Issue e siga em frente.
+Uma lacuna ou um defeito do Opus não precisa bloquear a entrega:
 
-O "depois" — o conserto no Opus — corre em paralelo. Ele não segura o seu trabalho; o único custo de demorar é o workaround viver um pouco mais.
+1. **Contorne no projeto:** componha um wrapper local. O Opus é distribuído como código-fonte, então
+   qualquer superfície dele pode ser envolvida. Não edite `node_modules`, porque a alteração se
+   perde na próxima instalação.
+2. **Entregue** a funcionalidade com o contorno.
+3. **Registre** o apontamento na Issue.
 
-## Como fecha
+A correção no Opus acontece em paralelo. Enquanto ela não sai, o contorno continua no projeto.
 
-A triagem acontece em uma **Issue em [github.com/softize-dev/opus](https://github.com/softize-dev/opus/issues)**; procure uma existente antes de abrir. O pacote não coleta apontamentos do seu projeto por conta própria. O desfecho depende do tipo:
+## Como o apontamento termina
 
-- **Enhancement** aceito (com reincidência) → implementado no Opus → sai em um _bump_ → seu projeto [atualiza o Opus](upgrading) e troca o workaround pelo import.
-- **Bug** → vira _fix_ + entrada no `CHANGELOG` → no _bump_, o workaround sai.
+- Um **enhancement** aceito é implementado no Opus e publicado em uma nova versão. Ao
+  [atualizar o Opus](/docs/upgrading), o projeto troca o contorno pelo import.
+- Um **bug** vira uma correção com entrada no `CHANGELOG`; na atualização, o contorno sai.
 
-A régua e a decisão ficam com quem mantém o Opus — hoje, a **Softize**. O registro curado das promoções vive no `PROMOTED.md` do pacote.
+A decisão sobre o que entra no Opus fica com a Softize, que mantém o pacote. O registro das peças
+incorporadas está no `PROMOTED.md` do pacote.