@softize/opus 26.0.0 → 26.2.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 26.2.0 — 2026-10-09
+
+Portais podem organizar capítulos em subgrupos e abrir ferramentas relacionadas sem substituir
+a página em leitura.
+
+- `DocGroup.groups` declara subgrupos opcionais. Navegação, busca, URLs diretas e sequência
+  editorial percorrem todos os níveis, com as páginas próprias antes dos subgrupos. A busca
+  preserva os ancestrais dos resultados; no modo inicialmente recolhido, restaura o estado
+  manual ao limpar. No modo expandido, os ancestrais da página ativa são reabertos. Ramos
+  vazios não aparecem, sem sugerir outro termo quando não há consulta.
+- `DocBrowser.sidebarLinks` preserva a navegação nativa para URLs HTTP(S) absolutas.
+- `SidebarItem` e `DocBrowser.sidebarLinks` aceitam `newTab`: o link abre em outra aba com
+  `noopener noreferrer` e informa a abertura no nome acessível. No portal, também exibe
+  um ícone de nova aba. A opção não intercepta a navegação nem chama `onClick`.
+
+As novas propriedades são opcionais. Consumidores sem subgrupos ou `newTab` mantêm seus
+contratos; não há migração obrigatória nesta versão.
+
+## 26.1.0 — 2026-10-09
+
+Subheadings descrevem a finalidade da superfície; orientações necessárias ficam visíveis no corpo
+ou junto ao campo (ADR 0059).
+
+- `Page` aceita `description`. `PageDescription`, `DialogDescription` e `DrawerDescription`
+  compõem o cabeçalho ou a introdução declarada da superfície.
+- `ActionFormDialog` e `ActionListDialog` recebem `description` para o cabeçalho. `intro` continua
+  no corpo, para regras e consequências da tarefa; ambos participam da descrição acessível.
+- `FieldSpec.hint` declara orientação visível abaixo do controle. `ActionFormField` associa hint
+  e erro por `aria-describedby`; `help` continua sendo a ajuda opcional junto à label.
+- Os textos dos campos resolvem `I18nRef` pelo texto padrão também nos renderizadores próprios.
+  O ícone de ajuda participa do Tab e abre por foco, sem tomar o foco inicial de outro controle
+  em Dialog e Drawer.
+- O inventário de copy, o validador estrutural, a skill de UI e os exemplos da documentação
+  reconhecem esses papéis sem proibir subheadings de maneira indiscriminada.
+
+**O que fazer:** rode `opus setup` e `opus copy`; revise a posição das orientações existentes.
+Renderizadores próprios de campos devem apresentar `hint` e associá-lo ao controle, preservando
+os erros. Nenhum texto migra automaticamente de `help` para `hint`.
+
 ## 26.0.0 — 2026-10-09
 
 A conversa com a IA pode levar imagens (ADR 0058). Uma mensagem passa a aceitar texto e imagem

package/bin/lib/check.mjs

@@ -152,6 +152,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageBody", new Set(["Page"])],
   ["PageFooter", new Set(["Page"])],
   ["PageTitle", new Set(["PageHeader"])],
+  ["PageDescription", new Set(["PageHeader"])],
   ["PageBack", new Set(["PageHeader"])],
   ["PageNavigation", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
@@ -173,6 +174,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DialogNavigation", new Set(["DialogHeader"])],
   ["DialogMedia", new Set(["DialogHeader"])],
   ["DialogTitle", new Set(["DialogHeader", "DialogIntro"])],
+  ["DialogDescription", new Set(["DialogHeader", "DialogIntro"])],
   ["DialogActions", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
   ["DrawerBody", new Set(["DrawerContent"])],
@@ -182,6 +184,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DrawerNavigation", new Set(["DrawerHeader"])],
   ["DrawerMedia", new Set(["DrawerHeader"])],
   ["DrawerTitle", new Set(["DrawerHeader", "DrawerIntro"])],
+  ["DrawerDescription", new Set(["DrawerHeader", "DrawerIntro"])],
   ["DrawerActions", new Set(["DrawerHeader"])],
   ["AlertMedia", new Set(["Alert"])],
   ["AlertHeader", new Set(["Alert"])],
@@ -215,13 +218,12 @@ const UI_STRUCTURAL_ROOTS = new Map([
       body: "PageBody",
       footer: "PageFooter",
       headerRequired: false,
-      shorthand: new Set(["title", "actions"]),
+      shorthand: new Set(["title", "description", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
       // prop removida é cobrada aqui, nas duas formas de composição.
       removed: new Map([
         ["count", "o total pertence ao conteúdo que o explica"],
-        ["description", "mova contexto relevante para o início do body"],
       ]),
     },
   ],
@@ -244,6 +246,7 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageBody",
   "PageFooter",
   "PageTitle",
+  "PageDescription",
   "PageBack",
   "PageNavigation",
   "PageActions",
@@ -308,24 +311,7 @@ const UI_REMOVED_PROPS = new Map([
       ["variant", "o cabeçalho da página tem uma única apresentação rolável"],
     ]),
   ],
-  [
-    "ActionFormDialog",
-    new Map([
-      [
-        "description",
-        "use `intro` somente para contexto relevante no início do corpo",
-      ],
-    ]),
-  ],
-  [
-    "ActionListDialog",
-    new Map([
-      [
-        "description",
-        "use `intro` somente para contexto relevante no início do corpo",
-      ],
-    ]),
-  ],
+
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
@@ -338,15 +324,6 @@ const UI_REMOVED_COMPONENTS = new Map([
   ["PaneDescription", "use `SurfaceDescription` dentro de `SurfaceHeader`"],
   ["PaneActions", "use `SurfaceActions` dentro de `SurfaceHeader`"],
   ["PageIntro", "use `PageHeader` como a única introdução estrutural"],
-  ["PageDescription", "mova contexto relevante para o início de `PageBody`"],
-  [
-    "DialogDescription",
-    "mova contexto relevante para o início de `DialogBody`",
-  ],
-  [
-    "DrawerDescription",
-    "mova contexto relevante para o início de `DrawerBody`",
-  ],
   // Content e Card deram lugar a Surface (ADR 0045).
   [
     "Content",
@@ -383,7 +360,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "DialogIntro",
     {
       title: "DialogTitle",
-      optional: new Set(["DialogIntroActions"]),
+      optional: new Set(["DialogIntroActions", "DialogDescription"]),
       shorthand: new Set(),
     },
   ],
@@ -391,7 +368,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "DrawerIntro",
     {
       title: "DrawerTitle",
-      optional: new Set(["DrawerIntroActions"]),
+      optional: new Set(["DrawerIntroActions", "DrawerDescription"]),
       shorthand: new Set(),
     },
   ],
@@ -399,7 +376,7 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageHeader",
     {
       title: "PageTitle",
-      optional: new Set(["PageBack", "PageNavigation", "PageActions"]),
+      optional: new Set(["PageBack", "PageNavigation", "PageActions", "PageDescription"]),
       exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
       titleRequired: false,

package/bin/lib/copy.mjs

@@ -99,9 +99,9 @@ const JSX_CHILD_ROLES = new Map([
   ['Button', 'button'],
   ['CommandEmpty', 'empty-state'],
   ['CommandItem', 'menu-item'],
-  ['DialogDescription', 'dialog-body'],
+  ['DialogDescription', 'description'],
   ['DialogTitle', 'title'],
-  ['DrawerDescription', 'dialog-body'],
+  ['DrawerDescription', 'description'],
   ['DrawerTitle', 'title'],
   ['EmptyDescription', 'empty-state'],
   ['EmptyTitle', 'title'],
@@ -123,6 +123,7 @@ const JSX_CHILD_ROLES = new Map([
   // comando. Classificado como `button`, a política universal cobraria verbo de ação.
   ['PageBack', 'breadcrumb'],
   ['PageTitle', 'title'],
+  ['PageDescription', 'description'],
   ['SurfaceDescription', 'description'],
   ['SurfaceTitle', 'title'],
   ['TableCaption', 'description'],
@@ -182,7 +183,7 @@ const JSX_PROP_ROLES = new Map([
     'ActionFormDialog',
     new Map([
       ['title', 'title'],
-      ['description', 'dialog-body'],
+      ['description', 'description'],
       ['intro', 'dialog-body'],
       ['submitLabel', 'button'],
       ['cancelLabel', 'button'],
@@ -202,7 +203,7 @@ const JSX_PROP_ROLES = new Map([
     'ActionListDialog',
     new Map([
       ['title', 'title'],
-      ['description', 'dialog-body'],
+      ['description', 'description'],
       ['intro', 'dialog-body'],
       ['emptyMessage', 'empty-state'],
       ['errorMessage', 'error'],
@@ -255,6 +256,7 @@ const JSX_PROP_ROLES = new Map([
     'Page',
     new Map([
       ['title', 'title'],
+      ['description', 'description'],
     ]),
   ],
   [
@@ -1503,6 +1505,7 @@ export function extractCopyFromSource(file, sourceText) {
     addProperty(object, 'label', 'label', prefix)
     addProperty(object, 'placeholder', 'placeholder', prefix)
     addProperty(object, 'help', 'helper-text', prefix)
+    addProperty(object, 'hint', 'helper-text', prefix)
     nestedObject(object, 'options', optionItems, prefix)
   }
 

package/docs/adr/0014-structural-headers-do-not-carry-description.md

@@ -1,6 +1,6 @@
 # ADR 0014 — Headers estruturais não carregam descrição
 
-- **Status:** aceita.
+- **Status:** substituída pela ADR 0059 (subheading opcional para orientação).
 - **Data:** 2026-09-11.
 - **Complementa:** ADRs 0005, 0011 e 0018.
 

package/docs/adr/0018-modal-header-only-names-the-surface.md

@@ -3,7 +3,7 @@
 > Publicada originalmente com o número 0012, que colidia com a ADR de Produtos de Dados do mesmo
 > dia. Renumerada em 2026-09-16; o conteúdo não mudou.
 
-- **Status:** aceita.
+- **Status:** parcialmente substituída pela ADR 0059 (subheading opcional no cabeçalho).
 - **Data:** 2026-09-11.
 
 ## Contexto

package/docs/adr/0023-surfaces-share-one-anatomy-and-two-layouts.md

@@ -158,6 +158,10 @@ anteriores já os delimitaram:
 | Body        | sim  | sim                  | sim            | sim                 | sim            | sim  |
 | Footer      | sim  | não                  | sim            | sim                 | sim            | sim  |
 
+> **Atualização (2026-10-09):** a ADR 0059 substitui a restrição de descrição abaixo. Page, Dialog
+> e Drawer passam a aceitar subheading opcional de orientação; regras necessárias ficam no corpo
+> ou junto dos controles. A tabela registra a decisão original desta ADR.
+
 As ADRs 0009, 0014 e 0018 não são reabertas: Page, Dialog e Drawer continuam sem descrição no
 header, e Page continua sem contador. `Dialog`, `Drawer` e `Pane` ganham o slot de ações que hoje
 não têm — a ausência obrigava a injetar nós soltos ao lado do título, e o `Studio` a manter três

package/docs/adr/0057-doc-browser-permite-busca-no-chrome-do-consumidor.md

@@ -39,6 +39,19 @@ de ADRs ou versões.
 
 ### Hierarquia e leitura
 
+> **Emenda — 2026-10-08, protótipo local:** `DocGroup.groups` permite subgrupos
+> opcionais. Um assunto como Integrações pode pertencer a Domínios e ainda reunir
+> páginas por sistema. A navegação, a busca, a seleção direta e a sequência de
+> leitura percorrem os mesmos grupos aninhados. Páginas próprias aparecem antes
+> dos subgrupos; ramos sem resultados somem da busca, sem perder a abertura manual.
+> O contrato anterior continua válido quando `groups` é omitido. Uma árvore paralela
+> no host e rótulos artificiais para simular profundidade foram descartados por
+> duplicar comportamento ou perder a hierarquia. Testes de links diretos, busca,
+> grupos vazios, rótulos repetidos e continuidade verificam a extensão.
+
+> **Consolidação — 2026-10-09:** a extensão de subgrupos compõe o candidato da versão
+> 26.2.0, sobre a base 26.1.0. Publicação e adoção permanecem etapas separadas.
+
 `sidebarSize` configura a largura inicial usando o `PaneSize` do `Split`. A omissão preserva
 `14rem`. `sidebarInitiallyCollapsed` permite começar com seções e grupos nomeados recolhidos,
 inclusive quando a pessoa abre uma página por URL direta. A busca revela os resultados
@@ -52,6 +65,16 @@ Esses destinos usam `SidebarItem.href`, não uma cópia do estilo da linha. A ex
 botão quando `href` é omitido, o foco nos dois modos e a abertura nativa em outra aba. Quando há
 `onClick`, somente a navegação simples é interceptada; o host mantém a decisão de roteamento.
 
+> **Emenda — 2026-10-09:** destinos HTTP(S) absolutos em `sidebarLinks` usam a navegação
+> nativa, pois podem apontar para outra aplicação. `newTab` é opcional em `SidebarItem`
+> e `sidebarLinks`: com `href`, declara `target="_blank"`, `rel="noopener noreferrer"`
+> e a abertura no nome acessível, sem chamar `onClick`. Sem `href`, não muda o botão.
+> O portal acrescenta o ícone pelo slot `badge` do item canônico. Interceptar esses
+> destinos no roteador ou copiar a linha no host foi descartado: o primeiro impede
+> a navegação entre aplicações e o segundo duplica foco, acessibilidade e composição.
+> Testes verificam links internos e absolutos, modificadores, nome acessível, ícone
+> nos dois modos iniciais do portal e comportamento do item aberto ou recolhido.
+
 O modo opcional `editorial` acrescenta contexto, sumário dos headings realmente renderizados e
 links de continuidade segundo a ordem declarada. `additionalPages` preserva URLs de páginas fora
 da árvore e da sequência. O renderer de exemplos aceita `codeCollapsible={false}` quando ocultar
@@ -143,6 +166,10 @@ e separa a consulta documental da consulta local.
 
 - Testes de `DocBrowser`: busca local e externa, vazio, largura configurável, lateral opcional,
   persistência de grupos, expansão temporária, conteúdo do host, redirects e leitura editorial.
+- Regressões da extensão: espaçamento dos grupos sem rótulo em diferentes níveis, acervo vazio
+  sem consulta, modificadores em links absolutos e ícone de nova aba nos dois modos iniciais.
+- Testes de `SidebarItem`: nova aba com modificadores, botão habilitado sem `href`, estado
+  desabilitado e preservação do badge textual no nome acessível do item aberto.
 - Testes de `DocHeader`: slots, atributos nativos e composição com ou sem busca e navegação.
 - Testes de `DocCatalog`: busca local controlada, independência do topo, ausência de controles de
   coleção, texto integral das versões, incompatibilidades e abertura nativa em outra aba.

package/docs/adr/0059-subheadings-orient-without-carrying-business-rules.md

@@ -0,0 +1,51 @@
+# ADR 0059 — Subheadings orientam sem carregar regras de negócio
+
+- **Status:** aceita para implementação local; publicação pendente.
+- **Data:** 2026-10-09.
+- **Substitui:** ADR 0014.
+- **Substitui parcialmente:** ADRs 0018 e 0023, quanto à proibição de descrição no cabeçalho.
+
+## Contexto
+
+A proibição de descrições nos cabeçalhos evitou texto de preenchimento, mas também deslocou
+orientações úteis para o corpo. A distinção necessária é semântica: uma frase que apresenta a
+finalidade da superfície pode ser ignorada sem comprometer a tarefa; uma regra ou consequência
+necessária à decisão precisa estar visível no ponto em que será usada.
+
+## Decisão
+
+Page, Surface (inclusive os usos antes atendidos por Content e Card), Dialog e Drawer aceitam um
+subheading opcional sob o título. A API usa `description` e os slots `PageDescription`,
+`SurfaceDescription`, `DialogDescription` e `DrawerDescription`. Não há texto padrão nem obrigação
+de preencher esse espaço. Frases que apenas repetem o título são omitidas.
+
+“Escolha onde a pasta ‘Produtos’ e suas subpastas aparecem.” orienta a tarefa e pode ocupar esse
+slot. “O motivo define se a observação é obrigatória e qual pendência será criada.” comunica regras:
+as condições precisam acompanhar os respectivos campos, ações ou conteúdo. O tamanho da frase não
+altera essa classificação. A pergunta de revisão é: ao pular o subheading, a pessoa ainda consegue
+decidir e concluir corretamente?
+
+`ActionFormDialog` e `ActionListDialog` separam `description`, orientação no cabeçalho, de `intro`,
+contexto necessário no corpo. Quando ambos existem, a descrição acessível relaciona ambos os IDs.
+Nas composições diretas, o consumidor mantém controle explícito de `aria-describedby`.
+A API imperativa de decisões permanece com `body`: confirmações devem apresentar seus efeitos no
+conteúdo da decisão. Fieldsets mantêm somente nome e mídia na legenda.
+
+## Alternativas e consequências
+
+Manter a proibição exigiria recriar subheadings no consumidor. Mover toda descrição para o
+cabeçalho esconderia regras em uma região visual secundária. A escolha preserva os textos
+necessários no corpo e permite orientação breve com a anatomia compartilhada.
+
+As APIs são aditivas; `intro` existente não muda de lugar. A classificação semântica exige revisão
+contextual de copy e não pode ser provada por uma busca de palavras ou limite de caracteres.
+`FieldSpec.hint` mantém visível a orientação necessária junto ao controle; `help` oferece detalhe
+complementar no ícone. Ambos podem coexistir sem repetir texto. Hint e erro participam da descrição
+acessível do controle. A escolha depende da necessidade para decidir, não do tamanho da frase.
+A Base mantém o princípio de comunicação; o Opus mantém componentes, documentação e extração.
+
+## Verificação
+
+Testar composição, omissão, coexistência com `intro`, associação acessível e extração de copy.
+O checker deve aceitar os novos slots em seus pais e continuar rejeitando anatomias inválidas.
+Validar no consumidor os exemplos de organização de pastas e configuração de motivos de perda.

package/docs/adr/README.md

@@ -10,3 +10,5 @@ entender por que uma restrição existe ou como ela evoluiu.
 
 Uma ADR preserva seu contexto histórico mesmo quando é substituída. O comportamento vigente deve
 estar documentado na superfície correspondente, sem exigir a reconstrução dessa sequência.
+
+- [ADR 0059 — Subheadings orientam sem carregar regras de negócio](0059-subheadings-orient-without-carrying-business-rules.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "26.0.0",
+  "version": "26.2.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -66,3 +66,11 @@
   sobreporem.
 - Reprova: dimensionar select inline de filtro pelo conteúdo ou pela label (`min-w-*` solto,
   largura calculada), em vez da largura fixa do pattern.
+
+## Orientação, hint e help
+
+Construir um formulário com orientação breve no cabeçalho, regra de seleção vazia e explicação
+complementar do termo. Esperado: `description` orienta a finalidade, `hint` mantém visível o efeito
+de deixar vazio e `help` oferece somente o detalhe opcional. `intro` continua no corpo quando a
+regra afeta vários campos. Reprovar regra obrigatória somente em subheading ou tooltip, repetição
+da label, duplicação entre hint/help e perda de `aria-describedby` quando aparece um erro.

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -10,11 +10,11 @@
 - `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
   explícita exige `PageBody`, exatamente um heading principal e aceita `PageHeader` e `PageFooter`.
   Declare esse heading com `PageTitle` no header, `Surface level={1}` ou um `PageState` ativo no
-  body. `PageHeader` é a única introdução estrutural e reúne navegação, título e ações. `title` e `actions` no
-  próprio `Page` são a abreviação para o caso direto.
+  body. `PageHeader` é a única introdução estrutural e reúne navegação, título, `PageDescription`
+  opcional e ações. `title`, `description` e `actions` no próprio `Page` abreviam o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
   real de largura; não reconstruir esse container em cada rota.
-- `PageHeader` declara navegação contextual, título e ações. Em uma subpágina simples, `PageBack`
+- `PageHeader` declara navegação contextual, título, subheading opcional e ações. Em uma subpágina simples, `PageBack`
   recebe o destino pai explícito e aparece acima da linha do título como controle somente com
   ícone. Para mais de um ancestral relevante, use
   `Breadcrumb` dentro de `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome
@@ -92,7 +92,9 @@ SurfaceTitle, SurfaceDescription, SurfaceMeta, SurfaceActions) + SurfaceBody + S
   cancelamento a `outline`.
 - Cabeçalhos de `Dialog` e `Drawer` nomeiam a superfície com o título e organizam suas ações. O close
   padrão é o `CloseButton` (`neutral`, `subtle`, pílula) no final do header, sem posição flutuante
-  alternativa. Não preencher uma segunda linha por hábito. Consequência, restrição ou instrução que
+  alternativa. `PageDescription`, `SurfaceDescription`, `DialogDescription` e `DrawerDescription`
+  orientam brevemente sobre a finalidade; wrappers usam `description`. Omitir repetição do título.
+  Pular esse subheading não pode comprometer a decisão. Consequência, restrição ou instrução que
   realmente mude a tarefa entra no início de `DialogBody`/`DrawerBody`, como texto ou `Alert`;
   wrappers usam `intro` e a API imperativa usa `body`. Relacione texto conciso por
   `aria-describedby` somente quando ele também precisar descrever a superfície para tecnologias
@@ -219,3 +221,11 @@ cells={{
 // Risco comportamental usado como nome visual.
 <Button variant="destructive">Excluir</Button>
 ```
+
+## Orientação de campo
+
+Usar `FieldSpec.hint` para condição, formato ou consequência necessários à escolha, sempre visível
+abaixo do controle. Reservar `FieldSpec.help` ao ícone com detalhe complementar sob demanda.
+Omitir repetição da label; combinar ambos somente com funções distintas. Regra de vários campos
+pertence ao corpo ou ao grupo. Em composição manual, `FieldDescription` e erro entram juntos no
+`aria-describedby` do controle.

package/src/core/types.ts

@@ -618,8 +618,9 @@ export type FieldWidget = BuiltInFieldWidget | (string & { readonly __opusCustom
 export interface FieldSpec {
   label: I18nRef
   placeholder?: I18nRef
-  /** Ajuda junto à label (ícone ⓘ + tooltip): critério, efeito ou limitação que a label não
-   *  diz. Ajuda que só repete a label deve ser omitida. */
+  /** Orientação necessária para preencher ou prever o efeito da escolha, sempre visível. */
+  hint?: I18nRef
+  /** Explicação complementar sob demanda junto à label; não recebe regras indispensáveis. */
   help?: I18nRef
 
   default?: unknown

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -19,6 +19,7 @@ import {
   DialogContent,
   DialogHeader,
   DialogTitle,
+  DialogDescription,
 } from '../primitives/dialog.tsx'
 import { ActionList } from './list.tsx'
 import type { ListAction } from '../../../core/index.ts'
@@ -34,6 +35,8 @@ export interface ActionListDialogProps<
   open: boolean
   onOpenChange: (open: boolean) => void
   title: string
+  /** Orientação opcional sobre a finalidade; regras e consequências pertencem a intro ou aos campos. */
+  description?: ReactNode
   /** Conteúdo relevante apresentado antes da lista, como texto ou Alert. */
   intro?: ReactNode
   /** Nota à esquerda da linha de ações (contexto curto). O total já mora no rodapé. */
@@ -63,6 +66,7 @@ export function ActionListDialog<
   open,
   onOpenChange,
   title,
+  description,
   intro,
   note,
   actions,
@@ -75,19 +79,22 @@ export function ActionListDialog<
   children,
 }: ActionListDialogProps<TItem, TInput>): React.ReactElement {
   const introId = useId()
+  const descriptionId = useId()
+  const describedBy =
+    [description == null ? null : descriptionId, intro == null ? null : introId]
+      .filter(Boolean)
+      .join(' ') || undefined
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent
-        className={cn('max-w-3xl', className)}
-        aria-describedby={intro === undefined ? undefined : introId}
-      >
+      <DialogContent className={cn('max-w-3xl', className)} aria-describedby={describedBy}>
         <DialogHeader>
           <DialogTitle>{title}</DialogTitle>
+          {description != null && (
+            <DialogDescription id={descriptionId}>{description}</DialogDescription>
+          )}
         </DialogHeader>
         <DialogBody>
-          {intro !== undefined && (
-            <div id={introId}>{intro}</div>
-          )}
+          {intro != null && <div id={introId}>{intro}</div>}
           {(note !== undefined || actions !== undefined) && (
             <div
               data-slot="action-list-dialog-toolbar"

package/src/ui/components/patterns/form-dialog.tsx

@@ -16,6 +16,7 @@ import {
   DialogFooter,
   DialogHeader,
   DialogTitle,
+  DialogDescription,
 } from "../primitives/dialog.tsx";
 import { ActionForm, type ActionFormProps } from "./form.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
@@ -27,6 +28,8 @@ export interface ActionFormDialogProps<
   open: boolean;
   onOpenChange: (open: boolean) => void;
   title: string;
+  /** Orientação opcional sobre a finalidade; regras e consequências pertencem a intro ou aos campos. */
+  description?: ReactNode;
   /** Conteúdo relevante apresentado antes dos campos, como texto ou Alert. */
   intro?: ReactNode;
   /** Distribui as ações pela largura disponível somente quando as decisões pedem peso equivalente. */
@@ -40,6 +43,7 @@ export function ActionFormDialog<
   open,
   onOpenChange,
   title,
+  description,
   intro,
   onSuccess,
   onCancel,
@@ -48,15 +52,23 @@ export function ActionFormDialog<
   ...rest
 }: ActionFormDialogProps<TInput, TData>) {
   const introId = useId();
+  const descriptionId = useId();
+  const describedBy =
+    [description == null ? null : descriptionId, intro == null ? null : introId]
+      .filter(Boolean)
+      .join(" ") || undefined;
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       {/* Header e rodapé FIXOS, só o CORPO (campos) scrolla — o "X" não rola junto e
           forms longos não estouram a viewport. O content já é coluna flex com teto. */}
-      <DialogContent
-        aria-describedby={intro === undefined ? undefined : introId}
-      >
+      <DialogContent aria-describedby={describedBy}>
         <DialogHeader>
           <DialogTitle>{title}</DialogTitle>
+          {description != null && (
+            <DialogDescription id={descriptionId}>
+              {description}
+            </DialogDescription>
+          )}
         </DialogHeader>
         <ActionForm
           {...rest}
@@ -65,9 +77,7 @@ export function ActionFormDialog<
           // faixa da casa — fonte única). Os botões seguem dentro do <form> do ActionForm.
           body={(fields) => (
             <DialogBody>
-              {intro !== undefined && (
-                <div id={introId}>{intro}</div>
-              )}
+              {intro != null && <div id={introId}>{intro}</div>}
               {fields}
             </DialogBody>
           )}
@@ -84,7 +94,8 @@ export function ActionFormDialog<
           }}
           onCancel={onCancel ?? (() => onOpenChange(false))}
           cancelVariant={
-            cancelVariant ?? (footerDistribution === "equal" ? "outline" : "ghost")
+            cancelVariant ??
+            (footerDistribution === "equal" ? "outline" : "ghost")
           }
         />
       </DialogContent>

package/src/ui/components/patterns/form.tsx

@@ -4,7 +4,7 @@
  * Dois modos, um motor:
  * - AUTO (sem children): monta TODOS os campos na ordem do contrato — zero JSX de campo.
  * - COMPOSIÇÃO (com children): você diagrama; <ActionFormField name /> coloca cada campo
- *   (label/help/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
+ *   (label/hint/help/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
  *   JSX ({cond && <ActionFormField/>}); opções de runtime entram por prop no campo. O
  *   FieldGroup canônico permanece nos dois modos; grids e seções entram como filhos explícitos.
  *
@@ -54,6 +54,7 @@ import { ToggleGroup } from "../primitives/toggle-group.tsx";
 import {
   Field,
   FieldError,
+  FieldDescription,
   FieldGroup,
   FieldLabel,
 } from "../primitives/field.tsx";
@@ -137,7 +138,9 @@ function inferFieldKind(schema: ZodTypeAny): FieldKind {
 interface FieldSpec {
   label?: string;
   placeholder?: string;
-  /** Ajuda na label: ícone ⓘ + tooltip no hover. */
+  /** Orientação necessária sempre visível abaixo do controle. */
+  hint?: string;
+  /** Detalhe complementar no ícone junto à label, disponível por hover ou foco. */
   help?: string;
   /** Override explícito do tipo de campo, quando o auto-detect do Zod não basta.
    *  Honra 'textarea' (string sem max), 'code' (textarea monoespaçada, ex.: SKILL.md),
@@ -206,9 +209,8 @@ function dictMetaOptions(schema: ZodTypeAny): SelectOption[] | undefined {
  * lugar (`<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>`) e o `opus copy` inventarie
  * o texto de `help` como helper-text.
  *
- * `tabIndex={-1}`: fica FORA do autofocus do diálogo (senão o modal foca no ícone ao abrir e
- * o tooltip vem aberto); abre só no hover. preventDefault: clicar o ícone não dispara o label
- * (não foca o input / não toggla).
+ * O botão participa do Tab e abre por foco ou hover. Dialog e Drawer preservam o foco
+ * inicial no controle, sem remover a ajuda da navegação por teclado. Clicar não ativa a label.
  */
 export function LabelHelp({
   help,
@@ -222,7 +224,8 @@ export function LabelHelp({
         <TooltipTrigger asChild>
           <button
             type="button"
-            tabIndex={-1}
+            data-slot="label-help"
+            tabIndex={0}
             aria-label="Ajuda"
             onClick={(e) => {
               // Clicar o ícone não ativa o label (não foca/toggla o campo).
@@ -344,7 +347,8 @@ export function ActionFormField({
   const errorMessage =
     typeof fieldError?.message === "string" ? fieldError.message : undefined;
   const errorId = errorMessage !== undefined ? `${name}-error` : undefined;
-  const describedBy = errorId;
+  const hintId = spec.hint?.trim() ? `${name}-hint` : undefined;
+  const describedBy = [hintId, errorId].filter(Boolean).join(" ") || undefined;
   useEffect(() => {
     if (errorMessage === undefined) return;
     const control = document.getElementById(name);
@@ -430,6 +434,9 @@ export function ActionFormField({
           </span>
           <LabelHelp help={spec.help} />
         </FieldLabel>
+        {hintId !== undefined && (
+          <FieldDescription id={hintId}>{spec.hint}</FieldDescription>
+        )}
         {errorMessage !== undefined && (
           <FieldError id={errorId}>{errorMessage}</FieldError>
         )}
@@ -683,6 +690,9 @@ export function ActionFormField({
         />
       )}
 
+      {hintId !== undefined && (
+        <FieldDescription id={hintId}>{spec.hint}</FieldDescription>
+      )}
       {errorMessage !== undefined && (
         <FieldError id={errorId}>{errorMessage}</FieldError>
       )}
@@ -774,7 +784,25 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
     string,
     ZodTypeAny | undefined
   >;
-  const fields = action.fields as Record<string, FieldSpec>;
+  // O contexto entrega texto resolvido também aos renderizadores de campo do consumidor.
+  const fields: Record<string, FieldSpec> = Object.fromEntries(
+    Object.entries(action.fields ?? {}).map(([name, declared]) => {
+      const spec = declared as FieldSpec;
+      return [
+        name,
+        {
+          ...spec,
+          label: msgText(spec.label, name),
+          placeholder:
+            spec.placeholder === undefined
+              ? undefined
+              : msgText(spec.placeholder, ""),
+          hint: spec.hint === undefined ? undefined : msgText(spec.hint, ""),
+          help: spec.help === undefined ? undefined : msgText(spec.help, ""),
+        },
+      ];
+    }),
+  );
 
   // Corpo e rodapé como SLOTS: por padrão renderizam inline; o ActionFormDialog injeta
   // DialogBody/DialogFooter (fonte única do scroll e da faixa). Os botões ficam DENTRO do