@softize/opus 26.0.0 → 26.2.0

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/sidebar.tsx

@@ -79,6 +79,8 @@ export interface SidebarItemProps {
   className?: string;
   /** Destino nativo. Com onClick, intercepta somente a navegação simples; preserva novas abas. */
   href?: string;
+  /** Abre o destino em nova aba, sem interceptar a navegação nativa. */
+  newTab?: boolean;
   onClick?: () => void;
 }
 
@@ -98,11 +100,19 @@ export function SidebarItem({
   className,
   onClick,
   href,
+  newTab = false,
 }: SidebarItemProps): React.ReactElement {
   const collapsed = useSidebarCollapsed();
   const Target = href !== undefined && !disabled ? "a" : "button";
   const targetProps =
-    Target === "a" ? { href } : { type: "button" as const, disabled };
+    Target === "a"
+      ? {
+          href,
+          ...(newTab ? { target: "_blank", rel: "noopener noreferrer" } : {}),
+        }
+      : { type: "button" as const, disabled };
+  const accessibleLabel =
+    Target === "a" && newTab ? `${label} (abre em nova aba)` : label;
   const activate = (
     event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
   ) => {
@@ -113,6 +123,7 @@ export function SidebarItem({
         event.ctrlKey ||
         event.shiftKey ||
         event.altKey ||
+        newTab ||
         !onClick
       )
         return;
@@ -129,7 +140,7 @@ export function SidebarItem({
     const button = (
       <Target
         {...targetProps}
-        aria-label={label}
+        aria-label={accessibleLabel}
         aria-current={active ? "page" : undefined}
         onClick={activate}
         className={cn(
@@ -156,7 +167,7 @@ export function SidebarItem({
         <Tooltip>
           <TooltipTrigger asChild>{button}</TooltipTrigger>
           <TooltipContent side="right">
-            {label}
+            {accessibleLabel}
             {tooltipHint}
           </TooltipContent>
         </Tooltip>
@@ -275,6 +286,9 @@ export function SidebarItem({
             {badge}
           </span>
         )}
+        {Target === "a" && newTab && (
+          <span className="sr-only"> (abre em nova aba)</span>
+        )}
       </Target>
       {hasActions && (
         <div

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/DocBrowser.tsx

@@ -12,8 +12,15 @@
  * Nos dois, navegar emite `popstate`: host que guarda o path por conta própria acompanha.
  * `basePath` adapta o prefixo das URLs (`/docs` no Maestro, `/__docs` nos apps).
  */
-import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
-import { ArrowLeft, ArrowRight, Search } from "lucide-react";
+import {
+  Fragment,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { ArrowLeft, ArrowRight, ExternalLink, Search } from "lucide-react";
 import type { DocEntry, DocGroup, DocSection } from "./types.ts";
 import { Pane, Split, type PaneSize } from "../components/patterns/split.tsx";
 import { Input } from "../components/primitives/input.tsx";
@@ -33,14 +40,28 @@ import {
 } from "../components/patterns/sidebar.tsx";
 import { navigate, usePathname } from "../router.ts";
 
+function documentEntries(
+  sections: DocSection[],
+): Array<{ entry: DocEntry; context: string }> {
+  const entriesFrom = (
+    groups: DocGroup[],
+    parent: string,
+  ): Array<{ entry: DocEntry; context: string }> =>
+    groups.flatMap((group) => {
+      const context = group.label?.trim() || parent;
+      return [
+        ...group.pages.map((entry) => ({ entry, context })),
+        ...entriesFrom(group.groups ?? [], context),
+      ];
+    });
+  return sections.flatMap((section) =>
+    entriesFrom(section.groups, section.label),
+  );
+}
+
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
-  for (const s of sections) {
-    for (const g of s.groups) {
-      const p = g.pages.find((p) => p.slug === slug);
-      if (p) return p;
-    }
-  }
-  return undefined;
+  return documentEntries(sections).find(({ entry }) => entry.slug === slug)
+    ?.entry;
 }
 
 interface DocBrowserSearchCopy {
@@ -58,7 +79,7 @@ export interface DocBrowserProps {
   basePath?: string;
   /** Path controlado pelo host (modo Maestro). Ausente = standalone (gerencia o próprio). */
   path?: string;
-  /** Seções a exibir (seção → grupo → página). */
+  /** Seções a exibir; grupos podem conter páginas e subgrupos. */
   sections: DocSection[];
   /** Slugs antigos que devem abrir e substituir a URL pela página canônica. */
   redirects?: Readonly<Record<string, string>>;
@@ -79,8 +100,13 @@ export interface DocBrowserProps {
   additionalPages?: DocEntry[];
   /** Substitui a leitura, mantendo a árvore; o host resolve conteúdo, título e rota. */
   content?: ReactNode;
-  /** Destinos fora dos capítulos; não participam da sequência de leitura. */
-  sidebarLinks?: Array<{ label: string; href: string; active?: boolean }>;
+  /** Destinos fora dos capítulos; `newTab` abre em nova aba com ícone e descrição acessível. */
+  sidebarLinks?: Array<{
+    label: string;
+    href: string;
+    active?: boolean;
+    newTab?: boolean;
+  }>;
   /** Seções e grupos começam recolhidos; a busca revela resultados sem mudar a escolha manual. */
   sidebarInitiallyCollapsed?: boolean;
 }
@@ -116,14 +142,7 @@ function EditorialDocument({
   const [headings, setHeadings] = useState<
     Array<{ id: string; title: string }>
   >([]);
-  const entries = sections.flatMap((section) =>
-    section.groups.flatMap((group) =>
-      group.pages.map((entry) => ({
-        entry,
-        context: group.label || section.label,
-      })),
-    ),
-  );
+  const entries = documentEntries(sections);
   const index = entries.findIndex(({ entry }) => entry.slug === page.slug);
   const previous = index > 0 ? entries[index - 1]?.entry : undefined;
   const next = index >= 0 ? entries[index + 1]?.entry : undefined;
@@ -271,9 +290,14 @@ function searchable(value: string): string {
     .toLocaleLowerCase("pt-BR");
 }
 
+type SidebarGroup = Omit<DocGroup, "groups"> & {
+  navigationKey: string;
+  groups: SidebarGroup[];
+};
+
 type SidebarSection = Omit<DocSection, "groups"> & {
   navigationKey: string;
-  groups: Array<DocGroup & { navigationKey: string }>;
+  groups: SidebarGroup[];
 };
 
 function filterSections(
@@ -282,25 +306,35 @@ function filterSections(
 ): SidebarSection[] {
   const terms = searchable(query).split(/\s+/).filter(Boolean);
   // Identidade vem do manifesto completo, antes de remover ramos pela busca.
+  const indexGroups = (groups: DocGroup[], parent: string): SidebarGroup[] =>
+    groups.map((group, index) => {
+      const navigationKey = `${parent}:${index}`;
+      return {
+        ...group,
+        navigationKey,
+        groups: indexGroups(group.groups ?? [], navigationKey),
+      };
+    });
   const indexedSections = sections.map((section, sectionIndex) => ({
     ...section,
     navigationKey: `section:${sectionIndex}`,
-    groups: section.groups.map((group, groupIndex) => ({
-      ...group,
-      navigationKey: `group:${sectionIndex}:${groupIndex}`,
-    })),
+    groups: indexGroups(section.groups, `group:${sectionIndex}`),
   }));
-  if (terms.length === 0) return indexedSections;
-  return indexedSections.flatMap((section) => {
-    const groups = section.groups.flatMap((group) => {
+  const matchingGroups = (groups: SidebarGroup[]): SidebarGroup[] =>
+    groups.flatMap((group) => {
       const pages = group.pages.filter((page) => {
         const text = searchable(
           `${page.title}\n${page.navigationTitle ?? ""}\n${page.badge ?? ""}\n${page.searchText ?? ""}`,
         );
         return terms.every((term) => text.includes(term));
       });
-      return pages.length === 0 ? [] : [{ ...group, pages }];
+      const children = matchingGroups(group.groups);
+      return pages.length === 0 && children.length === 0
+        ? []
+        : [{ ...group, pages, groups: children }];
     });
+  return indexedSections.flatMap((section) => {
+    const groups = matchingGroups(section.groups);
     return groups.length === 0 ? [] : [{ ...section, groups }];
   });
 }
@@ -327,22 +361,21 @@ function DocSidebarTree({
 
   useEffect(() => {
     if (forceExpanded || initiallyCollapsed) return;
-    const activeGroup = sections
-      .flatMap((section) =>
-        section.groups.map((group) => ({
-          key: group.navigationKey,
-          group,
-        })),
-      )
-      .find(({ group }) =>
-        group.pages.some((page) => page.slug === activeSlug),
-      );
-
-    if (activeGroup === undefined) return;
+    const activePath = (groups: SidebarGroup[]): string[] => {
+      for (const group of groups) {
+        if (group.pages.some((page) => page.slug === activeSlug))
+          return [group.navigationKey];
+        const children = activePath(group.groups);
+        if (children.length > 0) return [group.navigationKey, ...children];
+      }
+      return [];
+    };
+    const keys = sections.flatMap((section) => activePath(section.groups));
+    if (keys.length === 0) return;
     setToggledBranches((current) => {
-      if (!current.has(activeGroup.key)) return current;
+      if (!keys.some((key) => current.has(key))) return current;
       const next = new Set(current);
-      next.delete(activeGroup.key);
+      keys.forEach((key) => next.delete(key));
       return next;
     });
   }, [activeSlug, forceExpanded, sections, initiallyCollapsed]);
@@ -372,6 +405,36 @@ function DocSidebarTree({
     />
   );
 
+  const renderGroup = (group: SidebarGroup): ReactNode => {
+    const key = group.navigationKey;
+    const children = [
+      ...group.pages.map(renderPage),
+      ...group.groups.map(renderGroup),
+    ];
+    if ((group.label ?? "").trim() === "") {
+      return <Fragment key={key}>{children}</Fragment>;
+    }
+    const expanded =
+      forceExpanded ||
+      (initiallyCollapsed
+        ? toggledBranches.has(key)
+        : !toggledBranches.has(key));
+    return (
+      <div key={key} className="space-y-0.5">
+        <SidebarItem
+          label={group.label!}
+          icon={group.icon}
+          expanded={expanded}
+          onToggle={forceExpanded ? undefined : () => toggleGroup(key)}
+          onClick={() => {
+            if (!forceExpanded) toggleGroup(key);
+          }}
+        />
+        {expanded && <SidebarTreeGroup>{children}</SidebarTreeGroup>}
+      </div>
+    );
+  };
+
   return (
     <nav
       aria-label="Navegação da documentação"
@@ -384,38 +447,7 @@ function DocSidebarTree({
           initiallyCollapsed && section.label.trim() !== "";
         const sectionExpanded =
           forceExpanded || toggledBranches.has(sectionBranch);
-        const groups = section.groups.map((group) => {
-          const key = group.navigationKey;
-          if (group.pages.length === 0) return null;
-          if ((group.label ?? "").trim() === "") {
-            return group.pages.map((page) => renderPage(page));
-          }
-
-          const expanded =
-            forceExpanded ||
-            (initiallyCollapsed
-              ? toggledBranches.has(key)
-              : !toggledBranches.has(key));
-          return (
-            <div key={key} className="space-y-0.5">
-              <SidebarItem
-                label={group.label!}
-                icon={group.icon}
-                expanded={expanded}
-                onToggle={forceExpanded ? undefined : () => toggleGroup(key)}
-                // Durante a busca, o grupo é contexto dos resultados e permanece aberto.
-                onClick={() => {
-                  if (!forceExpanded) toggleGroup(key);
-                }}
-              />
-              {expanded && (
-                <SidebarTreeGroup>
-                  {group.pages.map((page) => renderPage(page))}
-                </SidebarTreeGroup>
-              )}
-            </div>
-          );
-        });
+        const groups = section.groups.map(renderGroup);
         return (
           <div key={sectionBranch} className="space-y-0.5">
             {collapsibleSection ? (
@@ -452,9 +484,24 @@ function DocSidebarTree({
               key={link.href}
               href={link.href}
               active={link.active}
-              onClick={() => navigate(link.href)}
+              newTab={link.newTab}
+              badge={
+                link.newTab ? (
+                  <ExternalLink
+                    aria-hidden="true"
+                    className="size-3.5 text-muted-foreground"
+                  />
+                ) : undefined
+              }
+              onClick={
+                link.newTab || /^https?:\/\//i.test(link.href)
+                  ? undefined
+                  : () => navigate(link.href)
+              }
               label={link.label}
-              icon={initiallyCollapsed ? <span aria-hidden="true" /> : undefined}
+              icon={
+                initiallyCollapsed ? <span aria-hidden="true" /> : undefined
+              }
             />
           ))}
         </div>
@@ -485,8 +532,8 @@ export function DocBrowser({
   // hooks); o que muda é quem vence no `??`.
   const livePath = usePathname();
   const path = controlledPath ?? livePath;
-  // Default = 1ª página do 1º grupo da 1ª seção (a doc abre na 1ª página).
-  const defaultSlug = sections[0]?.groups[0]?.pages[0]?.slug ?? "";
+  // Abre na primeira página do percurso, inclusive dentro de subgrupos.
+  const defaultSlug = documentEntries(sections)[0]?.entry.slug ?? "";
   // Slug = TODOS os segmentos após o basePath, unidos (rota aninhada: `/docs/guias/deploy`
   // → `guias/deploy`). Slug flat de 1 segmento continua igual (`join` de 1 elemento = ele).
   const rel = path.startsWith(basePath) ? path.slice(basePath.length) : "";
@@ -567,14 +614,14 @@ export function DocBrowser({
             <div className="min-h-0 flex-1 overflow-y-auto px-3 py-6">
               <p
                 className={
-                  visibleSections.length === 0
+                  query.trim() !== "" && visibleSections.length === 0
                     ? "px-2 text-sm text-muted-foreground"
                     : "sr-only"
                 }
                 role={search === false ? undefined : "status"}
                 aria-atomic={search === false ? undefined : "true"}
               >
-                {visibleSections.length === 0
+                {query.trim() !== "" && visibleSections.length === 0
                   ? (searchOptions.emptyMessage ??
                     "Nenhum documento encontrado. Tente outro termo.")
                   : ""}

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. |