@softize/opus 26.0.0 → 26.1.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ 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.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/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.1.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

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

@@ -147,6 +147,8 @@ interface PageBaseProps extends Omit<
 
 interface PageShorthandProps extends PageBaseProps {
   title: ReactNode;
+  /** Orientação opcional sobre a finalidade da página; regras pertencem ao corpo. */
+  description?: ReactNode;
   actions?: ReactNode;
   children: ReactNode;
 }
@@ -224,6 +226,7 @@ function hasOpaquePageBodyContent(node: ReactNode): boolean {
 
 export function Page({
   title,
+  description,
   actions,
   layout = "flow",
   className,
@@ -343,6 +346,9 @@ export function Page({
     <>
       <PageHeader>
         <PageTitle>{title}</PageTitle>
+        {description !== undefined && (
+          <PageDescription>{description}</PageDescription>
+        )}
         {actions !== undefined && <PageActions>{actions}</PageActions>}
       </PageHeader>
       <PageBody>{children}</PageBody>
@@ -461,6 +467,7 @@ export function PageHeader({
         slots={{
           leading: [PageBack, PageNavigation],
           title: PageTitle,
+          description: PageDescription,
           actions: PageActions,
         }}
         leadingPlacement="above"
@@ -496,6 +503,21 @@ export function PageTitle({
   );
 }
 
+/** Orientação breve e dispensável para a decisão; não recebe regras de negócio. */
+export function PageDescription({
+  className,
+  ...props
+}: HTMLAttributes<HTMLParagraphElement>): ReactElement {
+  requireParent(useContext(PageHeaderContext), "PageDescription", "PageHeader");
+  return (
+    <p
+      data-slot="page-description"
+      className={cn(structuralHeaderClasses.page.description, className)}
+      {...props}
+    />
+  );
+}
+
 export function PageActions({
   className,
   ...props

package/src/ui/components/patterns/surface-anatomy.ts

@@ -60,7 +60,7 @@ interface FamilyAnatomy {
   regions: Record<SurfaceLayout, RegionAnatomy>;
   /** Escala visual do título. O nível semântico do heading é escolhido à parte. */
   title: Record<SurfaceLayout, string>;
-  /** Descrição no header, quando a família a oferece (ADRs 0014 e 0018 excluem modais). */
+  /** Descrição no header, quando a família a oferece (ADR 0059 inclui subheadings opcionais em modais). */
   description: string;
   /** Espaço entre mídia, título e ações na linha do header. */
   headerGap: string;

package/src/ui/components/primitives/dialog.tsx

@@ -5,6 +5,7 @@ import { cn } from "../../lib/cn.ts";
 import {
   SurfaceLayoutProvider,
   surfaceActionsClasses,
+  surfaceDescriptionClasses,
   surfaceHeaderRowClasses,
   surfaceRegionClasses,
   surfaceTitleClasses,
@@ -26,6 +27,7 @@ import {
   exemptLayerFirst,
   focusIsInLayer,
   handleModalTabKey,
+  skipHelpOnAutoFocus,
   isLayerInteraction,
   routeEscapeToLayer,
   useLayerPortal,
@@ -415,6 +417,7 @@ export function DialogContent({
   onEscapeKeyDown,
   onPointerDownOutside,
   onInteractOutside,
+  onOpenAutoFocus,
   onCloseAutoFocus,
   onKeyDown,
   ref,
@@ -481,6 +484,7 @@ export function DialogContent({
           aria-describedby={ariaDescribedBy}
           // O `AlertDialog` do Radix cancela sozinho o clique fora; só o Esc é composto.
           onEscapeKeyDown={dismiss.onEscapeKeyDown}
+          onOpenAutoFocus={onOpenAutoFocus}
           onCloseAutoFocus={dismiss.onCloseAutoFocus}
           onKeyDown={onKeyDown}
           {...props}
@@ -532,6 +536,10 @@ export function DialogContent({
         onPointerDownOutside={dismiss.onPointerDownOutside}
         onInteractOutside={dismiss.onInteractOutside}
         onCloseAutoFocus={dismiss.onCloseAutoFocus}
+        onOpenAutoFocus={(event) => {
+          onOpenAutoFocus?.(event);
+          skipHelpOnAutoFocus(event);
+        }}
         onKeyDown={handleKeyDown}
         {...props}
       >
@@ -584,6 +592,7 @@ export function DialogHeader({
         leading: DialogNavigation,
         media: DialogMedia,
         title: DialogTitle,
+        description: DialogDescription,
         actions: DialogActions,
       }}
       leadingPlacement="inline"
@@ -645,7 +654,11 @@ export function DialogIntro({
       <StructuralHeader
         name="DialogIntro"
         slot="dialog-intro"
-        slots={{ title: DialogTitle, actions: DialogIntroActions }}
+        slots={{
+          title: DialogTitle,
+          description: DialogDescription,
+          actions: DialogIntroActions,
+        }}
         leadingPlacement="inline"
         titleRequired
         className={cn("text-left", className)}
@@ -770,3 +783,17 @@ export function DialogTitle({
     </Title>
   );
 }
+
+/** Orientação opcional sob o título; condições e consequências ficam no corpo. */
+export function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<"p">) {
+  return (
+    <p
+      data-slot="dialog-description"
+      className={cn("mt-1", surfaceDescriptionClasses("dialog"), className)}
+      {...props}
+    />
+  );
+}

package/src/ui/components/primitives/drawer.tsx

@@ -5,6 +5,7 @@ import { cn } from "../../lib/cn.ts";
 import {
   SurfaceLayoutProvider,
   surfaceActionsClasses,
+  surfaceDescriptionClasses,
   surfaceHeaderRowClasses,
   surfaceRegionClasses,
   surfaceTitleClasses,
@@ -28,6 +29,7 @@ import {
   LAYER_MODAL_ATTRIBUTE,
   LayerPortalProvider,
   handleModalTabKey,
+  skipHelpOnAutoFocus,
   useLayerPortal,
   useModalLayerEntry,
 } from "../../lib/modal-layers.ts";
@@ -113,7 +115,9 @@ function DrawerOverlay({
   return (
     <DrawerPrimitive.Overlay
       data-slot="drawer-overlay"
-      {...{ [LAYER_MODAL_ATTRIBUTE]: layer.container !== undefined || undefined }}
+      {...{
+        [LAYER_MODAL_ATTRIBUTE]: layer.container !== undefined || undefined,
+      }}
       className={cn(overlayClasses, layer.zIndexClass, className)}
       {...props}
     />
@@ -146,6 +150,7 @@ function DrawerContent({
   onEscapeKeyDown,
   onPointerDownOutside,
   onInteractOutside,
+  onOpenAutoFocus,
   onCloseAutoFocus,
   onKeyDown,
   ref,
@@ -218,6 +223,10 @@ function DrawerContent({
         onPointerDownOutside={dismiss.onPointerDownOutside}
         onInteractOutside={dismiss.onInteractOutside}
         onCloseAutoFocus={dismiss.onCloseAutoFocus}
+        onOpenAutoFocus={(event) => {
+          onOpenAutoFocus?.(event);
+          skipHelpOnAutoFocus(event);
+        }}
         onKeyDown={handleKeyDown}
         {...props}
       >
@@ -251,6 +260,7 @@ function DrawerHeader({
         leading: DrawerNavigation,
         media: DrawerMedia,
         title: DrawerTitle,
+        description: DrawerDescription,
         actions: DrawerActions,
       }}
       leadingPlacement="inline"
@@ -314,7 +324,11 @@ function DrawerIntro({
       <StructuralHeader
         name="DrawerIntro"
         slot="drawer-intro"
-        slots={{ title: DrawerTitle, actions: DrawerIntroActions }}
+        slots={{
+          title: DrawerTitle,
+          description: DrawerDescription,
+          actions: DrawerIntroActions,
+        }}
         leadingPlacement="inline"
         titleRequired
         className={cn("text-left", className)}
@@ -435,3 +449,17 @@ export {
   DrawerFooter,
   DrawerTitle,
 };
+
+/** Orientação opcional sob o título; condições e consequências ficam no corpo. */
+export function DrawerDescription({
+  className,
+  ...props
+}: React.ComponentProps<"p">) {
+  return (
+    <p
+      data-slot="drawer-description"
+      className={cn("mt-1", surfaceDescriptionClasses("drawer"), className)}
+      {...props}
+    />
+  );
+}

package/src/ui/docs/content/action-form-card.md

@@ -28,7 +28,7 @@ a mesma.
 | ------------------- | ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `title`             | `string`                     |        | Título do cabeçalho. Sem ele e sem `description`, o card começa diretamente pelo corpo.                                                                                                                                                                                     |
 | `titleLevel`        | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3`    | Nível do heading do título. Muda a hierarquia do documento, não a escala visual.                                                                                                                                                                                            |
-| `description`       | `string`                     |        | Texto de apoio abaixo do título.                                                                                                                                                                                                                                            |
+| `description`       | `string`                     |        | Orientação opcional sobre a finalidade. Regras e consequências ficam junto dos campos ou no corpo.                                                                                                                                                                                                                                            |
 | `cardClassName`     | `string`                     |        | Classes aplicadas à superfície do card.                                                                                                                                                                                                                                     |
 | `className`         | `string`                     |        | Classes aplicadas ao `<form>` interno.                                                                                                                                                                                                                                      |
 | Demais propriedades | Propriedades de `ActionForm` |        | `action`, `defaultValues`, `fieldOptions`, `submitLabel`, `cancelLabel`, `cancelVariant`, `onCancel`, `onSuccess`, `disabled`, `onLoadingChange` e `children` mantêm o comportamento de `ActionForm`. `body` e `footer` não são aceitas: o card fornece o corpo e o rodapé. |

package/src/ui/docs/content/action-form-dialog.md

@@ -35,12 +35,20 @@ salvo escolha explícita em `cancelVariant`.
 
 Para consultar uma coleção no mesmo formato de modal, use [`ActionListDialog`](/ui/action-list-dialog).
 
+## Orientação e contexto
+
+`description` apresenta a finalidade no cabeçalho, como “Escolha onde a pasta e suas subpastas
+aparecem.”. É opcional; não repita o título. `intro` apresenta no corpo informações necessárias
+à decisão que não pertencem a um campo específico. Regras, condições e consequências não ficam
+somente no subheading. Quando ambos são fornecidos, ambos participam de `aria-describedby`.
+
 ## Propriedades de ActionFormDialog
 
 | Propriedade           | Tipo                                              | Padrão     | Descrição                                                                                                                                                                   |
 | --------------------- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e, quando não há `onCancel` próprio, ao cancelar.                                                                                       |
 | `title`               | `string`                                          |            | Operação e recurso exibidos no cabeçalho, como `Criar workspace` ou `Editar workspace`. |
+| `description` | `ReactNode` | | Orientação opcional sob o título; não recebe regras de negócio. |
 | `intro`               | `ReactNode`                                       |            | Contexto relevante no início do corpo, como texto ou `Alert`.                                                                                                               |
 | `submitLabel`         | `string`                                          | `'Salvar'` | Resultado da ação principal. Preserve o padrão em criação e edição comuns; sobrescreva apenas quando a operação tiver outro efeito, como `Renomear` ou `Criar nova versão`. |
 | `footerDistribution`  | `'content' \| 'equal'`                            | `'content'` | Mantém a largura das ações pelo conteúdo ou divide a faixa igualmente. |

package/src/ui/docs/content/action-form.md

@@ -84,12 +84,21 @@ do mesmo peso visual. Nesse caso, o cancelamento muda para `outline`, salvo esco
 `cancelVariant`. Para apresentar o formulário como uma seção delimitada da página, use
 [`ActionFormCard`](/ui/action-form-card). As propriedades de cada wrapper estão na página dele.
 
-## Ajuda no rótulo
+## Hint visível ou ícone de help
 
-`FieldSpec.help` aparece como um ícone junto ao rótulo, com o texto em um tooltip. Escreva ali o
-critério, o efeito ou a limitação que o rótulo não diz; ajuda que só repete o rótulo deve ser omitida.
-Não existe texto auxiliar sob o campo: quem precisa de uma frase permanente abaixo do controle usa
-`FieldDescription` na composição própria.
+Use `FieldSpec.hint` abaixo do controle quando a pessoa precisar da informação para preencher
+corretamente ou prever o efeito da escolha. Exemplo: “Sem áreas selecionadas, a pasta aparece em
+todas as áreas.” O texto permanece visível e participa do `aria-describedby` do controle, junto
+do erro quando houver. Em uma composição própria, use `FieldDescription` com a mesma associação.
+
+Use `FieldSpec.help` no ícone junto à label para detalhes complementares, definições e exemplos
+opcionais. A pergunta é: sem abrir essa ajuda, a pessoa ainda consegue escolher corretamente?
+Se não, o trecho necessário deve ser hint. Não use o comprimento da frase como critério nem
+esconda uma condição obrigatória no tooltip. Omita texto que apenas repete a label.
+
+Hint e help podem coexistir se tiverem funções diferentes, sem duplicar a mesma frase. Um erro
+explica uma entrada inválida e sua correção; não substitui uma orientação necessária antes de
+preencher. Uma regra que afeta vários campos pertence ao corpo ou ao grupo correspondente.
 
 `LabelHelp` é esse mesmo ícone, exportado para um formulário sem contrato mostrar a ajuda no mesmo
 lugar:
@@ -185,3 +194,7 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | Propriedade | Tipo     | Descrição                                                    |
 | ----------- | -------- | ------------------------------------------------------------ |
 | `help`      | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
+
+O `hint` aceita texto ou `I18nRef` e permanece visível; o contexto do formulário entrega o texto
+resolvido aos campos personalizados. O botão de `help` participa do Tab e abre por foco ou hover.
+Dialog e Drawer evitam que a ajuda seja o primeiro foco automático quando há outro controle.

package/src/ui/docs/content/action-list-dialog.md

@@ -96,6 +96,13 @@ const roleOptions = roles.items.map((role) => ({ value: role.id, label: role.nam
 </ActionListDialog>;
 ```
 
+## Orientação e contexto
+
+`description` apresenta a finalidade no cabeçalho, como “Escolha onde a pasta e suas subpastas
+aparecem.”. É opcional; não repita o título. `intro` apresenta no corpo informações necessárias
+à decisão que não pertencem a um campo específico. Regras, condições e consequências não ficam
+somente no subheading. Quando ambos são fornecidos, ambos participam de `aria-describedby`.
+
 ## Propriedades de ActionListDialog
 
 | Propriedade                                | Tipo                                | Padrão               | Descrição                                                                                         |
@@ -103,6 +110,7 @@ const roleOptions = roles.items.map((role) => ({ value: role.id, label: role.nam
 | `action / input`                           | `ListAction / TInput`               | `input`: `{}`        | O contrato e o escopo base da consulta. Uma mudança em `input` refaz a consulta; as invalidações declaradas por forms e triggers também. |
 | `open / onOpenChange`                      | `boolean / (open) => void`          |                      | Estado controlado do modal.                                                                       |
 | `title`                                    | `string`                            |                      | Nome da lista exibido no cabeçalho fixo.                                                          |
+| `description` | `ReactNode` | | Orientação opcional sob o título; não recebe regras de negócio. |
 | `intro`                                    | `ReactNode`                         |                      | Contexto relevante no início do corpo, como texto ou `Alert`.                                     |
 | `children`                                 | `(items, refetch) => ReactNode`     |                      | A composição dos itens. Carregamento, erro e vazio já são tratados pelo `ActionList`.            |
 | `note`                                     | `ReactNode`                         |                      | Contexto curto à esquerda da linha de ações. O total de itens já aparece no rodapé do `ActionList`. |

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

@@ -150,8 +150,21 @@ Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem)
 [`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
 quadrado `icon-sm` (1.75rem) por padrão.
 
-O cabeçalho não recebe descrição: um modal já é a superfície de uma tarefa, e o contexto que ajuda a
-decidir aparece no começo do corpo, como texto ou `Alert`.
+O cabeçalho aceita `DialogDescription` como subheading opcional para orientar sobre a finalidade.
+Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
+ficam junto dos controles ou em `DialogBody`. Uma frase curta também pode ser regra: o critério é se
+pular o texto compromete a decisão, não sua extensão.
+
+```tsx
+<DialogHeader>
+  <DialogTitle>Organizar pasta</DialogTitle>
+  <DialogDescription>Escolha onde a pasta e suas subpastas aparecem.</DialogDescription>
+</DialogHeader>
+```
+
+Na composição direta, associe o `id` do texto por `aria-describedby` em `DialogContent` quando ele
+descrever a superfície para tecnologias assistivas. A regra sobre seleção vazia pertence ao
+campo de áreas e permanece fora do subheading.
 
 ## Identificar a tarefa com um ícone
 
@@ -634,3 +647,12 @@ conteúdo no primeiro bloco de `DialogBody`. `DialogIntro` exige um `DialogTitle
 
 No formato compacto, mantenha `DialogTitle` e `DialogActions` no próprio `DialogHeader`. Para
 comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).
+
+## Propriedades de DialogDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação opcional sob o título em `DialogHeader` ou `DialogIntro`. |
+| `id` | `string` | | Identificador para associação acessível explícita. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `ComponentProps<"p">` | | Atributos nativos. |

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

@@ -148,8 +148,21 @@ Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem)
 [`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
 quadrado `icon-sm` (1.75rem) por padrão.
 
-O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
-aparece no começo do corpo, como texto ou `Alert`.
+O cabeçalho aceita `DrawerDescription` como subheading opcional para orientar sobre a finalidade.
+Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
+ficam junto dos controles ou em `DrawerBody`. Uma frase curta também pode ser regra: o critério é se
+pular o texto compromete a decisão, não sua extensão.
+
+```tsx
+<DrawerHeader>
+  <DrawerTitle>Organizar pasta</DrawerTitle>
+  <DrawerDescription>Escolha onde a pasta e suas subpastas aparecem.</DrawerDescription>
+</DrawerHeader>
+```
+
+Na composição direta, associe o `id` do texto por `aria-describedby` em `DrawerContent` quando ele
+descrever a superfície para tecnologias assistivas. A regra sobre seleção vazia pertence ao
+campo de áreas e permanece fora do subheading.
 
 ## Impedir o fechamento durante uma operação
 
@@ -301,3 +314,12 @@ Assim o título acompanha o conteúdo rolável enquanto o chrome permanece está
 
 No formato compacto, mantenha `DrawerTitle` e `DrawerActions` no próprio `DrawerHeader`. Para
 comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).
+
+## Propriedades de DrawerDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação opcional sob o título em `DrawerHeader` ou `DrawerIntro`. |
+| `id` | `string` | | Identificador para associação acessível explícita. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `ComponentProps<"p">` | | Atributos nativos. |

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

@@ -1,7 +1,7 @@
 ## Esqueleto de página
 
 Use `Page` para manter cabeçalho, estado e conteúdo na mesma anatomia. `PageHeader` é a única
-introdução estrutural: reúne navegação contextual opcional, título e ações. O container é
+introdução estrutural: reúne navegação contextual opcional, título, orientação opcional e ações. O container é
 centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). Use `className` somente quando
 a composição pedir outro teto ou largura total.
 
@@ -41,6 +41,19 @@ render(
 );
 ```
 
+## Orientar sobre a finalidade
+
+Use `description` na forma curta ou `PageDescription` em `PageHeader` quando uma frase breve
+ajudar a reconhecer a finalidade da página. Omita texto que só repita o título. Regras de negócio,
+limites e consequências ficam nos campos, ações ou corpo em que são necessários. Pular o
+subheading não deve comprometer a decisão nem a conclusão correta da tarefa.
+
+```tsx
+<Page title="Conhecimento" description="Consulte os materiais de apoio da sua área.">
+  <KnowledgeList />
+</Page>
+```
+
 ## Retorno para a página pai
 
 Use `PageBack` em uma subpágina simples. O destino é explícito para continuar correto após refresh ou
@@ -311,6 +324,7 @@ estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui
 
 | Propriedade | Tipo                       | Padrão      | Descrição                                                                                                                                                          |
 | ----------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `description` | `ReactNode` | | Orientação opcional sob o título na forma curta. |
 | `title`     | `ReactNode`                |             | O h1 da página.                                                                                                                                                    |
 | `actions`   | `ReactNode`                |             | Ações contextuais no extremo oposto do cabeçalho.                                                                                                                  |
 | `layout`    | `'flow' \| 'fill'`         | `'flow'`    | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role e leva essa altura até uma `ActionList` composta em `PageBody`. |
@@ -414,3 +428,11 @@ ocupa a altura.
 | `retryLabel`   | `string`                                     | `'Tentar de novo'`                        | Texto do botão de recuperação.                                                                              |
 | `children`     | `ReactNode`                                  |                                           | Conteúdo renderizado somente em `ready`.                                                                    |
 | `className`    | `string`                                     |                                           | Classes da superfície de estado.                                                                            |
+
+## Propriedades de PageDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação breve e opcional; filho direto de `PageHeader`. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `HTMLAttributes<HTMLParagraphElement>` | | Atributos nativos. |

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

@@ -131,12 +131,11 @@ render(
     as="section"
     framed
     title="Plano atual"
-    description="Renova em 12 de maio."
     level={3}
   >
     <SurfaceBody>
       <p className="text-sm text-muted-foreground">
-        Até 10 workspaces e 50 agentes.
+        Renova em 12 de maio. Até 10 workspaces e 50 agentes.
       </p>
     </SurfaceBody>
     <SurfaceFooter>
@@ -511,3 +510,10 @@ um wrapper filho declara relações locais mais compactas.
 | ----------- | ----------- | ------ | ---------------------------------------------------- |
 | `children`  | `ReactNode` |        | Ações persistentes, alinhadas no fim da linha.       |
 | `className` | `string`    |        | Ajusta o rodapé, inclusive a distribuição das ações. |
+
+## Subheading e regras de negócio
+
+`description` e `SurfaceDescription` apresentam brevemente a finalidade da região. A orientação
+é opcional e não repete o título. A mesma regra vale para uma página (`level={1}`), uma seção ou
+um card: condições, limites e consequências necessários à decisão ficam no corpo ou junto do
+controle correspondente. Pular o subheading não deve comprometer a tarefa.

package/src/ui/lib/modal-layers.ts

@@ -143,6 +143,21 @@ function syncHosts(): void {
   }
 }
 
+/** A ajuda permanece no Tab, mas não toma o foco inicial do campo ao abrir um modal. */
+export function skipHelpOnAutoFocus(event: Event): void {
+  if (event.defaultPrevented || !(event.target instanceof HTMLElement)) return;
+  const candidates = tabbables(event.target).filter(
+    (element) => element.tagName !== "A",
+  );
+  if (candidates[0]?.dataset.slot !== "label-help") return;
+  const control = candidates.find(
+    (element) => element.dataset.slot !== "label-help",
+  );
+  if (control === undefined) return;
+  control.focus();
+  if (document.activeElement === control) event.preventDefault();
+}
+
 /** Elementos alcançáveis pelo Tab dentro de `root`, na ordem do documento. */
 function tabbables(root: HTMLElement): HTMLElement[] {
   const nodes: HTMLElement[] = [];
@@ -178,7 +193,10 @@ function tabbables(root: HTMLElement): HTMLElement[] {
 function focusFromKeyboard(element: HTMLElement): void {
   element.focus();
   // O Tab do navegador seleciona o texto do campo que recebe o foco; a passagem manual imita.
-  if (element instanceof HTMLInputElement && typeof element.select === "function") {
+  if (
+    element instanceof HTMLInputElement &&
+    typeof element.select === "function"
+  ) {
     element.select();
   }
 }
@@ -342,7 +360,10 @@ export function registerFloatingLayer(
   // podem tratar o Tab e marcá-lo com `preventDefault`.
   const onKeyDown = (event: KeyboardEvent): void => {
     if (!isTabKey(event) || event.defaultPrevented) return;
-    if (!layerExemptionsActive() || layerOf(document.activeElement) !== record) {
+    if (
+      !layerExemptionsActive() ||
+      layerOf(document.activeElement) !== record
+    ) {
       return;
     }
     const candidates = tabbables(host);
@@ -361,7 +382,10 @@ export function registerFloatingLayer(
     if (layerWherePersonIs() === record) escape()?.(event);
   };
   const observer = new MutationObserver(() => {
-    if (pointerAnchor !== null && pointerAnchor.parentNode !== pointerLayer?.host) {
+    if (
+      pointerAnchor !== null &&
+      pointerAnchor.parentNode !== pointerLayer?.host
+    ) {
       // O painel apertado saiu da camada, como quando é fechado por código e vira o FAB.
       pointerAnchor = null;
       pointerLayer = null;

package/src/ui/react.tsx

@@ -173,6 +173,7 @@ export {
   DialogBody,
   DialogFooter,
   DialogTitle,
+  DialogDescription,
 } from "./components/primitives/dialog.tsx";
 export type {
   DialogProps,
@@ -326,6 +327,7 @@ export {
   DrawerNavigation,
   DrawerBody,
   DrawerTitle,
+  DrawerDescription,
   DrawerTrigger,
 } from "./components/primitives/drawer.tsx";
 export {
@@ -509,6 +511,7 @@ export {
   PageNavigation,
   PageBack,
   PageTitle,
+  PageDescription,
   PageActions,
   PageActionsTarget,
   PageBody,