@softize/opus 25.7.0 → 26.1.0

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

@@ -1,10 +1,58 @@
 import * as React from "react";
-import { SendHorizontalIcon } from "lucide-react";
+import { ImageIcon, ImagePlusIcon, SendHorizontalIcon, XIcon } from "lucide-react";
+import type { AiImageMediaType } from "../../../core/index.ts";
 import { cn } from "../../lib/cn.ts";
+import { IMAGE_MEDIA_TYPES, imageTypeList } from "../../lib/prepare-image.ts";
 import { Button } from "./button.tsx";
 import { Spinner } from "./spinner.tsx";
 import { Textarea } from "./textarea.tsx";
 
+/** Estado de um anexo pendente: enviando, pronto para ir com a mensagem ou com falha. */
+export type ComposerAttachmentStatus = "uploading" | "ready" | "failed";
+
+/** Um anexo pendente da mensagem, no estado que o app mantém (ADR 0058). */
+export interface ComposerAttachment {
+  /** Identidade estável do anexo, dada pelo app. */
+  id: string;
+  /** Nome mostrado na faixa; identifica o anexo também para leitores de tela. */
+  name: string;
+  status: ComposerAttachmentStatus;
+  /** Endereço da miniatura (por exemplo, `URL.createObjectURL` da imagem preparada). */
+  previewUrl?: string;
+  /** Motivo da falha, mostrado no lugar do estado quando `status` é `failed`. */
+  error?: string;
+}
+
+/** Um arquivo recusado pela triagem: fora dos tipos aceitos ou além do limite da mensagem. */
+export interface ComposerFileRejection {
+  file: File;
+  reason: "type" | "limit";
+}
+
+/**
+ * Anexos da mensagem, controlados pelo app (ADR 0058). O composer faz a triagem e mostra a faixa;
+ * preparar, enviar, guardar e limpar depois do envio são do app, que é o dono do transporte.
+ */
+export interface ComposerAttachments {
+  /** Anexos pendentes, na ordem em que aparecem na faixa. */
+  items: ComposerAttachment[];
+  /** Recebe os arquivos aceitos pela triagem — do botão, do colar ou do soltar. */
+  onAddFiles: (files: File[]) => void;
+  /** A pessoa removeu um anexo da faixa. */
+  onRemove: (id: string) => void;
+  /** Limite de anexos por mensagem. Padrão: 4. */
+  max?: number;
+  /** Formatos aceitos, um subconjunto dos que a mensagem da IA leva. Padrão: PNG, JPEG e WebP.
+   *  Não há curinga (`image/*`): a triagem compara o tipo exato do arquivo. */
+  accept?: readonly AiImageMediaType[];
+  /** Recebe os arquivos recusados. Presente, a explicação da recusa é do app; ausente, o
+   *  composer a mostra acima do campo. */
+  onReject?: (rejections: ComposerFileRejection[]) => void;
+}
+
+/** Limite padrão de anexos por mensagem. */
+export const COMPOSER_MAX_ATTACHMENTS = 4;
+
 export interface ComposerProps {
   /** Texto (controlado): o dono do estado é o consumidor — o `<Chat>` por dentro, ou o app
    *  (ex.: o composer de criação de sessão do Maestro, que nem tem histórico). */
@@ -29,15 +77,165 @@ export interface ComposerProps {
    *  embaixo); ausente → linha única (textarea + enviar inline), o composer clássico do Chat.
    *  Estilize os controles como discretos (ghost/sem borda) — a barra não é um formulário. */
   actions?: React.ReactNode;
+  /** Anexos da mensagem (ADR 0058). Presente → duas linhas, faixa de anexos acima do texto,
+   *  botão **Anexar imagem** na barra, colar e soltar imagens; ausente → só texto. */
+  attachments?: ComposerAttachments;
   className?: string;
 }
 
+/**
+ * Ponte interna entre o `<Chat>` e o seu composer: o Chat recebe o soltar sobre a conversa
+ * inteira e entrega os arquivos à mesma triagem do composer. Não faz parte da API pública.
+ */
+export const ComposerDropBridge = React.createContext<React.RefObject<
+  ((files: File[]) => void) | null
+> | null>(null);
+
+/** O arraste traz arquivos (e não texto ou um link). */
+export function dragHasFiles(transfer: DataTransfer | null): boolean {
+  return transfer !== null && Array.from(transfer.types ?? []).includes("Files");
+}
+
+const PASTED_EXTENSIONS: Record<string, string> = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+};
+
+/** A imagem colada chega como "image.png"; ganha um nome que a pessoa reconhece na conversa. O
+ *  número vem de um contador da instância, que não volta atrás: remover "Imagem colada 1" e colar
+ *  de novo dá "Imagem colada 3", e não uma segunda "Imagem colada 1" na mesma conversa. */
+function namePasted(file: File, position: number): File {
+  const extension = PASTED_EXTENSIONS[file.type];
+  if (extension === undefined) return file;
+  return new File([file], `Imagem colada ${position}${extension}`, {
+    type: file.type,
+    lastModified: file.lastModified,
+  });
+}
+
+function rejectionMessage(
+  rejections: ComposerFileRejection[],
+  accept: readonly AiImageMediaType[],
+  max: number,
+): string {
+  const parts: string[] = [];
+  if (rejections.some((r) => r.reason === "type")) {
+    parts.push(`Só é possível anexar imagens ${imageTypeList(accept)}.`);
+  }
+  if (rejections.some((r) => r.reason === "limit")) {
+    parts.push(
+      max === 1 ? "Cada mensagem aceita 1 imagem." : `Cada mensagem aceita até ${max} imagens.`,
+    );
+  }
+  return parts.join(" ");
+}
+
+/** O que mudou nos anexos desde o render anterior, para a região viva anunciar. */
+function statusAnnouncement(
+  previous: ReadonlyMap<string, ComposerAttachmentStatus>,
+  items: ComposerAttachment[],
+): string | null {
+  const changes: string[] = [];
+  for (const item of items) {
+    const before = previous.get(item.id);
+    if (before === item.status) continue;
+    if (item.status === "ready") changes.push(`${item.name} pronta para enviar.`);
+    else if (item.status === "failed") changes.push(`${item.name}: ${statusLabel(item)}`);
+  }
+  return changes.length > 0 ? changes.join(" ") : null;
+}
+
+function statusLabel(item: ComposerAttachment): string {
+  if (item.status === "uploading") return "Enviando…";
+  if (item.status === "failed") return item.error ?? "Não foi possível enviar.";
+  return "Pronta";
+}
+
+/** A faixa de anexos pendentes: miniatura, nome, estado e remover. */
+function AttachmentStrip({
+  items,
+  max,
+  onRemove,
+}: {
+  items: ComposerAttachment[];
+  max: number;
+  onRemove: (item: ComposerAttachment) => void;
+}): React.ReactElement {
+  return (
+    <div data-slot="composer-attachments" className="flex items-end gap-2 px-1 pb-1.5">
+      <ul aria-label="Imagens anexadas" className="flex min-w-0 flex-1 flex-wrap gap-1.5">
+        {items.map((item) => (
+          <li
+            key={item.id}
+            data-slot="composer-attachment"
+            data-status={item.status}
+            aria-busy={item.status === "uploading" || undefined}
+            className={cn(
+              "flex min-w-0 max-w-52 items-center gap-2 rounded-lg border bg-muted/40 p-1 text-xs",
+              item.status === "failed" ? "border-context-danger-border" : "border-border",
+            )}
+          >
+            <span className="relative grid size-10 shrink-0 place-items-center overflow-hidden rounded-md bg-muted">
+              {item.previewUrl !== undefined ? (
+                // O nome está ao lado: a miniatura é decorativa para leitores de tela.
+                <img src={item.previewUrl} alt="" className="size-full object-cover" />
+              ) : (
+                <ImageIcon aria-hidden className="size-4 text-muted-foreground" />
+              )}
+              {item.status === "uploading" && (
+                <span className="absolute inset-0 grid place-items-center bg-background/60">
+                  <Spinner size="xs" />
+                </span>
+              )}
+            </span>
+            <span className="min-w-0 flex-1 leading-tight">
+              <span className="block truncate font-medium text-foreground" title={item.name}>
+                {item.name}
+              </span>
+              <span
+                className={cn(
+                  "block truncate",
+                  item.status === "failed"
+                    ? "text-context-danger-emphasis"
+                    : "text-muted-foreground",
+                )}
+                title={item.status === "failed" ? statusLabel(item) : undefined}
+              >
+                {statusLabel(item)}
+              </span>
+            </span>
+            <Button
+              type="button"
+              size="icon-xs"
+              variant="ghost"
+              shape="pill"
+              aria-label={`Remover ${item.name}`}
+              onClick={() => onRemove(item)}
+              className="shrink-0 self-start text-muted-foreground hover:text-foreground"
+            >
+              <XIcon />
+            </Button>
+          </li>
+        ))}
+      </ul>
+      <span
+        data-slot="composer-attachment-count"
+        className="shrink-0 pb-1 text-xs text-muted-foreground"
+      >
+        {max === 1 ? `${items.length} de 1 imagem` : `${items.length} de ${max} imagens`}
+      </span>
+    </div>
+  );
+}
+
 /**
  * <Composer /> — a caixa de escrever da casa: textarea (Enter envia / Shift+Enter quebra
  * linha) numa pílula elevada (rounded-xl + border + shadow-sm), com o enviar dentro.
  * É o composer do `<Chat>` extraído pra ser reusável SOZINHO — o Maestro cria sessão com
  * ele (sem chat nenhum), e a GB prende seletores nele. Com `actions`, ganha uma barra
- * embaixo pros seletores; sem, é a linha única de sempre.
+ * embaixo pros seletores; sem, é a linha única de sempre. Com `attachments`, ganha a faixa
+ * de anexos e o botão **Anexar imagem** (ADR 0058).
  */
 export function Composer({
   value,
@@ -51,19 +249,118 @@ export function Composer({
   rows = 1,
   autoFocus,
   actions,
+  attachments,
   className,
 }: ComposerProps): React.ReactElement {
-  const canSubmit = value.trim() !== "" && !busy && !submitDisabled;
+  const items = attachments?.items ?? [];
+  const max = attachments?.max ?? COMPOSER_MAX_ATTACHMENTS;
+  const accept = attachments?.accept ?? IMAGE_MEDIA_TYPES;
+  const [notice, setNotice] = React.useState<string | null>(null);
+  const [dragging, setDragging] = React.useState(false);
+  const [announcement, setAnnouncement] = React.useState("");
+  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
+  const fileInputRef = React.useRef<HTMLInputElement>(null);
+  const pastedCount = React.useRef(0);
+  const pickerUsed = React.useRef(false);
+  const previousStatus = React.useRef(new Map<string, ComposerAttachmentStatus>());
+  const bridge = React.useContext(ComposerDropBridge);
+  const full = items.length >= max;
+
+  // Anexo que fica pronto ou falha é anunciado: a mudança na faixa é só visual. O estado com que
+  // o composer nasce não é novidade e não é anunciado.
+  const statusKnown = React.useRef(false);
+  React.useEffect(() => {
+    const next = statusKnown.current ? statusAnnouncement(previousStatus.current, items) : null;
+    statusKnown.current = true;
+    previousStatus.current = new Map(items.map((item) => [item.id, item.status]));
+    if (next !== null) setAnnouncement(next);
+  }, [items]);
+
+  // Quem atinge o limite pelo botão fica com o foco num botão desabilitado; o foco vai ao campo.
+  React.useEffect(() => {
+    if (!full || !pickerUsed.current) return;
+    pickerUsed.current = false;
+    textareaRef.current?.focus();
+  }, [full]);
+
+  // Envio: texto ou pelo menos um anexo pronto; nunca com anexo em envio ou em falha, para que
+  // nada do que está na faixa fique de fora sem aviso.
+  const hasReady = items.some((item) => item.status === "ready");
+  const pending = items.some((item) => item.status !== "ready");
+  const canSubmit = (value.trim() !== "" || hasReady) && !pending && !busy && !submitDisabled;
   const fire = (): void => {
-    if (canSubmit) onSubmit();
+    if (!canSubmit) return;
+    setNotice(null);
+    onSubmit();
+  };
+  const twoRow = actions !== undefined || attachments !== undefined;
+
+  /** Triagem: tipo aceito e espaço na mensagem. Os aceitos vão ao app; os recusados, ao
+   *  `onReject` do app ou ao aviso do composer. */
+  const intake = (files: File[]): void => {
+    if (attachments === undefined || files.length === 0) return;
+    const remaining = Math.max(0, max - items.length);
+    const accepted: File[] = [];
+    const rejected: ComposerFileRejection[] = [];
+    for (const file of files) {
+      if (!(accept as readonly string[]).includes(file.type)) rejected.push({ file, reason: "type" });
+      else if (accepted.length >= remaining) rejected.push({ file, reason: "limit" });
+      else accepted.push(file);
+    }
+    if (accepted.length > 0) attachments.onAddFiles(accepted);
+    if (rejected.length > 0 && attachments.onReject !== undefined) {
+      attachments.onReject(rejected);
+      setNotice(null);
+    } else {
+      setNotice(rejected.length > 0 ? rejectionMessage(rejected, accept, max) : null);
+    }
+  };
+
+  // Dentro do <Chat>, o soltar é recebido pela conversa inteira e chega aqui pela ponte. A
+  // ponte acompanha cada render, para a triagem contar os anexos atuais.
+  React.useEffect(() => {
+    if (bridge === null) return;
+    bridge.current = attachments !== undefined ? intake : null;
+  });
+  React.useEffect(
+    () => () => {
+      if (bridge !== null) bridge.current = null;
+    },
+    [bridge],
+  );
+
+  const remove = (item: ComposerAttachment): void => {
+    attachments?.onRemove(item.id);
+    setNotice(null);
+    // O botão some com o anexo; o foco volta ao campo em vez de cair no documento.
+    textareaRef.current?.focus();
   };
-  const twoRow = actions !== undefined;
 
   const textarea = (
     <Textarea
+      ref={textareaRef}
       autoFocus={autoFocus}
       value={value}
       onChange={(e) => onChange(e.target.value)}
+      onPaste={
+        attachments === undefined
+          ? undefined
+          : (e) => {
+              // Texto vence: copiar células de uma planilha traz texto e uma imagem juntos, e
+              // quem cola ali quer o texto. Só a imagem sem texto, como um print, vira anexo.
+              if (e.clipboardData.getData("text/plain") !== "") return;
+              const files = Array.from(e.clipboardData.files ?? []);
+              if (files.length === 0) return;
+              e.preventDefault();
+              intake(
+                files.map((file) =>
+                  PASTED_EXTENSIONS[file.type] === undefined
+                    ? file
+                    : namePasted(file, (pastedCount.current += 1)),
+                ),
+              );
+            }
+      }
       onKeyDown={(e) => {
         if (e.key === "ArrowUp" && onHistoryPrevious?.()) {
           e.preventDefault();
@@ -101,29 +398,122 @@ export function Composer({
       {busy ? <Spinner size="sm" /> : <SendHorizontalIcon className="size-4" />}
     </Button>
   );
+  const attach = attachments !== undefined && (
+    <>
+      <Button
+        type="button"
+        size="icon-sm"
+        variant="ghost"
+        shape="pill"
+        aria-label="Anexar imagem"
+        title="Anexar imagem"
+        disabled={full}
+        onClick={() => {
+          pickerUsed.current = true;
+          fileInputRef.current?.click();
+        }}
+        onBlur={(e) => {
+          // Abrir o seletor tira o foco da janela (sem destino); ir a outro controle desfaz a marca.
+          if (e.relatedTarget !== null) pickerUsed.current = false;
+        }}
+        className="text-muted-foreground hover:text-foreground"
+      >
+        <ImagePlusIcon />
+      </Button>
+      <input
+        ref={fileInputRef}
+        data-slot="composer-file-input"
+        type="file"
+        accept={accept.join(",")}
+        multiple={max - items.length > 1}
+        hidden
+        tabIndex={-1}
+        onChange={(e) => {
+          intake(Array.from(e.target.files ?? []));
+          // Escolher o mesmo arquivo de novo precisa disparar `change` outra vez.
+          e.target.value = "";
+        }}
+      />
+    </>
+  );
+  // Fora do <Chat>, o próprio composer recebe o soltar.
+  const ownDrop = attachments !== undefined && bridge === null;
 
   return (
     <form
       data-slot="composer"
+      data-dragging={dragging || undefined}
       onSubmit={(e) => {
         e.preventDefault();
         fire();
       }}
+      onDragOver={
+        ownDrop
+          ? (e) => {
+              if (!dragHasFiles(e.dataTransfer)) return;
+              e.preventDefault();
+              e.stopPropagation();
+              setDragging(true);
+            }
+          : undefined
+      }
+      onDragLeave={
+        ownDrop
+          ? (e) => {
+              if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setDragging(false);
+            }
+          : undefined
+      }
+      onDrop={
+        ownDrop
+          ? (e) => {
+              if (!dragHasFiles(e.dataTransfer)) return;
+              e.preventDefault();
+              // O soltar foi consumido aqui; um contêiner do app não deve recebê-lo de novo.
+              e.stopPropagation();
+              setDragging(false);
+              intake(Array.from(e.dataTransfer.files));
+            }
+          : undefined
+      }
       className={cn(
         "rounded-xl border border-border bg-card text-card-foreground shadow-sm transition",
         twoRow ? "p-2" : "relative flex items-end gap-2 p-2 pl-3.5",
+        dragging && "border-primary ring-2 ring-primary/30",
         className,
       )}
     >
       {twoRow ? (
         <>
+          {attachments !== undefined && (
+            // Região viva montada desde o início: um aviso que nasce junto com ela não é
+            // anunciado por todos os leitores de tela.
+            <p
+              role="status"
+              data-slot="composer-attachment-notice"
+              className={cn(
+                notice === null ? "sr-only" : "px-1.5 pb-1.5 text-xs text-context-warning-emphasis",
+              )}
+            >
+              {notice}
+            </p>
+          )}
+          {attachments !== undefined && (
+            <p role="status" data-slot="composer-attachment-announcement" className="sr-only">
+              {announcement}
+            </p>
+          )}
+          {items.length > 0 && <AttachmentStrip items={items} max={max} onRemove={remove} />}
           {textarea}
           <div
             data-slot="composer-actions"
             className="mt-1 flex items-center justify-between gap-2"
           >
-            {/* Seletores à esquerda (discretos), enviar à direita. */}
-            <div className="flex min-w-0 items-center gap-1">{actions}</div>
+            {/* Anexar e seletores à esquerda (discretos), enviar à direita. */}
+            <div className="flex min-w-0 items-center gap-1">
+              {attach}
+              {actions}
+            </div>
             {send}
           </div>
         </>

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