@softize/opus 13.0.0 → 14.0.0

package/src/ui/components/patterns/content-header.tsx

@@ -1,6 +1,5 @@
 import {
   Children,
-  Fragment,
   createContext,
   isValidElement,
   useContext,
@@ -10,9 +9,14 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import {
+  SurfaceHeader,
+  surfaceHeaderClasses,
+  type SurfaceHeaderVariant,
+} from "./surface-header.tsx";
 
 export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
-export type ContentHeaderVariant = "page" | "section";
+export type ContentHeaderVariant = SurfaceHeaderVariant;
 
 interface ContentContextValue {
   level: ContentHeaderLevel;
@@ -39,14 +43,14 @@ interface ContentBaseProps extends Omit<
 > {
   /** Nível semântico do heading, independente de seu destaque visual. */
   level?: ContentHeaderLevel;
-  /** Hierarquia visual. `page` permanece somente para compatibilidade durante a versão 12. */
+  /** Hierarquia visual: `section` (default) ou `page`, a mesma de PageHeader. */
   variant?: ContentHeaderVariant;
 }
 
 interface ContentShorthandProps extends ContentBaseProps {
   title: ReactNode;
-  /** Conteúdo complementar exibido ao lado do título, como uma contagem. */
-  meta?: ReactNode;
+  /** Total de itens ao lado do título — o mesmo `count` de Page. */
+  count?: number;
   description?: ReactNode;
   actions?: ReactNode;
   children: ReactNode;
@@ -54,7 +58,7 @@ interface ContentShorthandProps extends ContentBaseProps {
 
 interface ContentComposedProps extends ContentBaseProps {
   title?: never;
-  meta?: never;
+  count?: never;
   description?: never;
   actions?: never;
   children: ReactNode;
@@ -65,7 +69,7 @@ export type ContentProps = ContentShorthandProps | ContentComposedProps;
 /** Região de conteúdo nomeada. A forma curta e a explícita produzem a mesma anatomia. */
 export function Content({
   title,
-  meta,
+  count,
   description,
   actions,
   level = 2,
@@ -119,7 +123,7 @@ export function Content({
           <>
             <ContentHeader>
               <ContentTitle>{title}</ContentTitle>
-              {meta !== undefined && <ContentMeta>{meta}</ContentMeta>}
+              {count !== undefined && <ContentMeta>{count}</ContentMeta>}
               {description !== undefined && (
                 <ContentDescription>{description}</ContentDescription>
               )}
@@ -137,128 +141,36 @@ export function Content({
   );
 }
 
-interface ContentHeaderShorthandProps extends Omit<
-  HTMLAttributes<HTMLDivElement>,
-  "children" | "title"
-> {
-  /** @deprecated Prefira os slots explícitos ou o shorthand de Content. */
-  title: ReactNode;
-  meta?: ReactNode;
-  description?: ReactNode;
-  actions?: ReactNode;
-  /** @deprecated Declare o nível em Content. Compatibilidade da série 12. */
-  level?: ContentHeaderLevel;
-  /** @deprecated Declare a hierarquia visual em Content. Compatibilidade da série 12. */
-  variant?: ContentHeaderVariant;
-  children?: never;
-}
-
-interface ContentHeaderComposedProps extends Omit<
-  HTMLAttributes<HTMLDivElement>,
-  "title"
-> {
-  /** @deprecated Declare o nível em Content. Compatibilidade da série 12. */
-  level?: ContentHeaderLevel;
-  /** @deprecated Declare a hierarquia visual em Content. Compatibilidade da série 12. */
-  variant?: ContentHeaderVariant;
-  title?: never;
-  meta?: never;
-  description?: never;
-  actions?: never;
-  children: ReactNode;
-}
-
-export type ContentHeaderProps =
-  ContentHeaderShorthandProps | ContentHeaderComposedProps;
+export type ContentHeaderProps = Omit<HTMLAttributes<HTMLDivElement>, "title">;
 
-/** Header estrutural de Content; não é uma região autônoma. */
+/**
+ * Header estrutural de Content; não é uma região autônoma. A anatomia é a de
+ * `SurfaceHeader`, a mesma de `PageHeader`: só os nomes dos slots e a hierarquia mudam.
+ */
 export function ContentHeader({
-  title,
-  meta,
-  description,
-  actions,
-  level,
-  variant,
   children,
-  className,
   ...props
 }: ContentHeaderProps): ReactElement {
-  const parent = useContext(ContentContext);
-  const standaloneTitleId = useId();
-  const shorthand = title !== undefined;
-  if (parent === null && !shorthand) {
-    throw new Error("ContentHeader deve estar dentro de Content.");
-  }
-  const content: ContentContextValue = {
-    level: level ?? parent?.level ?? 2,
-    titleId: parent?.titleId ?? standaloneTitleId,
-    variant: variant ?? parent?.variant ?? "section",
-  };
-  const nodes = Children.toArray(
-    shorthand ? (
-      <>
-        <ContentTitle>{title}</ContentTitle>
-        {meta !== undefined && <ContentMeta>{meta}</ContentMeta>}
-        {description !== undefined && (
-          <ContentDescription>{description}</ContentDescription>
-        )}
-        {actions !== undefined && <ContentActions>{actions}</ContentActions>}
-      </>
-    ) : (
-      children
-    ),
-  ).flatMap((node) =>
-    isValidElement(node) && node.type === Fragment
-      ? Children.toArray((node.props as { children?: ReactNode }).children)
-      : [node],
-  );
-  const titles = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentTitle,
-  );
-  const metas = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentMeta,
-  );
-  const descriptions = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentDescription,
-  );
-  const actionSlots = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentActions,
+  const content = requiredContext(
+    useContext(ContentContext),
+    "ContentHeader",
+    "Content",
   );
-  const recognized =
-    titles.length + metas.length + descriptions.length + actionSlots.length;
-
-  if (
-    titles.length !== 1 ||
-    metas.length > 1 ||
-    descriptions.length > 1 ||
-    actionSlots.length > 1 ||
-    recognized !== nodes.length
-  ) {
-    throw new Error(
-      "ContentHeader exige um ContentTitle e aceita no máximo um ContentDescription, ContentMeta e ContentActions como filhos diretos.",
-    );
-  }
-
   return (
     <ContentHeaderContext.Provider value={content}>
-      <div
-        data-slot="content-header"
-        className={cn(
-          actionSlots.length > 0 &&
-            "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
-          className,
-        )}
+      <SurfaceHeader
+        name="ContentHeader"
+        slot="content"
+        slots={{
+          title: ContentTitle,
+          count: ContentMeta,
+          description: ContentDescription,
+          actions: ContentActions,
+        }}
         {...props}
       >
-        <div data-slot="content-header-heading" className="min-w-0">
-          <div className="flex items-baseline gap-2">
-            {titles}
-            {metas}
-          </div>
-          {descriptions}
-        </div>
-        {actionSlots}
-      </div>
+        {children}
+      </SurfaceHeader>
     </ContentHeaderContext.Provider>
   );
 }
@@ -287,11 +199,7 @@ export function ContentTitle({
     <Heading
       id={id ?? context.titleId}
       data-slot="content-title"
-      className={cn(
-        "font-semibold",
-        context.variant === "page" ? "text-2xl tracking-tight" : "text-sm",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses[context.variant].title, className)}
       {...props}
     />
   );
@@ -309,26 +217,29 @@ export function ContentDescription({
   return (
     <p
       data-slot="content-description"
-      className={cn(
-        "truncate text-muted-foreground",
-        context.variant === "page" ? "mt-1 text-sm" : "mt-0.5 text-xs",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses[context.variant].description, className)}
       {...props}
     />
   );
 }
 
+/** O contador ao lado do título — o slot `count` do shorthand. */
 export function ContentMeta({
   className,
   ...props
 }: HTMLAttributes<HTMLSpanElement>): ReactElement {
-  requiredContext(
+  const context = requiredContext(
     useContext(ContentHeaderContext),
     "ContentMeta",
     "ContentHeader",
   );
-  return <span data-slot="content-meta" className={className} {...props} />;
+  return (
+    <span
+      data-slot="content-meta"
+      className={cn(surfaceHeaderClasses[context.variant].count, className)}
+      {...props}
+    />
+  );
 }
 
 export function ContentActions({
@@ -343,11 +254,7 @@ export function ContentActions({
   return (
     <div
       data-slot="content-actions"
-      className={cn(
-        "flex w-full shrink-0 items-center sm:w-auto",
-        context.variant === "page" ? "gap-4" : "gap-2",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses[context.variant].actions, className)}
       {...props}
     />
   );

package/src/ui/components/patterns/data-state.tsx

@@ -2,31 +2,39 @@
  * <DataState /> — o estado "carregando" da casa: o que mostrar ANTES do conteúdo chegar.
  *
  * Orquestra os estados de uma carga assíncrona (lista/fetch) num lugar só: erro (calmo, sem
- * jargão na tela), carregando (Spinner centralizado), vazio (texto) e, por fim, o conteúdo.
+ * jargão na tela), carregando (Spinner centralizado), vazio (Empty) e, por fim, o conteúdo.
  * Dissolve o `error ? … : isLoading ? <Spinner/> : empty ? … : children` repetido em toda
  * tela. NÃO confundir com "processando" (AÇÃO em andamento depois do clique) — isso é o
  * `busy` do Button. Pra placeholder com forma de conteúdo, use Skeleton.
+ *
+ * As superfícies são as mesmas de PageState (state-surface.tsx); aqui elas ficam na escala de
+ * uma seção: o vazio é a frase discreta com moldura sólida e o erro é o Alert com recuperação.
  */
 import * as React from 'react'
-import { cn } from '../../lib/cn.ts'
-import { Alert } from '../primitives/alert.tsx'
-import { Button } from '../primitives/button.tsx'
-import { Spinner } from '../primitives/spinner.tsx'
+import {
+  DEFAULT_EMPTY_MESSAGE,
+  DEFAULT_ERROR_MESSAGE,
+  DEFAULT_RETRY_LABEL,
+  EmptySurface,
+  ErrorSurface,
+  LoadingSurface,
+} from './state-surface.tsx'
 
 export interface DataStateProps {
   /** Carregando (antes do conteúdo) — mostra o Spinner centralizado. */
   loading?: boolean
-  /** Erro da carga. A mensagem técnica NÃO vai pra tela (passe `errorText` pra um aviso). */
+  /** Erro da carga. A mensagem técnica NÃO vai pra tela (passe `errorMessage` pra um aviso). */
   error?: { message?: string } | null
-  /** Sem itens — mostra o `emptyText`. */
+  /** Sem itens — mostra o `emptyMessage`. */
   empty?: boolean
-  /** Texto do vazio (pt-BR, ex.: "Nenhum papel."). */
-  emptyText?: string
-  /** Aviso de erro (calmo, orientado ao usuário). Default: "Não foi possível carregar.". */
-  errorText?: string
+  /** Frase do vazio (pt-BR, ex.: "Nenhum papel."). Default: "Nada por aqui.". */
+  emptyMessage?: string
+  /** Aviso de erro (calmo, orientado à pessoa). Default: "Não foi possível carregar.". */
+  errorMessage?: string
   /** Recuperação opcional exibida somente no estado de erro. */
   onRetry?: () => Promise<void> | void
-  retryText?: string
+  /** Rótulo do botão de recuperação. Default: "Tentar de novo". */
+  retryLabel?: string
   /** Em TABELA: renderiza o estado como UMA linha (<tr><td colSpan>), não um bloco — pra
    *  caber direto no <tbody>. Passe o nº de colunas da tabela. */
   colSpan?: number
@@ -39,78 +47,44 @@ export function DataState({
   loading = false,
   error = null,
   empty = false,
-  emptyText = 'Nada por aqui.',
-  errorText,
+  emptyMessage = DEFAULT_EMPTY_MESSAGE,
+  errorMessage = DEFAULT_ERROR_MESSAGE,
   onRetry,
-  retryText = 'Tentar de novo',
+  retryLabel = DEFAULT_RETRY_LABEL,
   colSpan,
   children,
 }: DataStateProps): React.ReactElement {
   // Há conteúdo: passa direto (no modo tabela, são as <tr> dos itens).
   if (!error && !loading && !empty) return <>{children}</>
 
+  const status = error ? 'error' : loading ? 'loading' : 'empty'
+  const surface = error ? (
+    <ErrorSurface
+      title={errorMessage}
+      {...(onRetry !== undefined ? { onRetry } : {})}
+      retryLabel={retryLabel}
+    />
+  ) : loading ? (
+    <LoadingSurface className="py-10" />
+  ) : (
+    // A tabela já traz a moldura: dentro dela o vazio é só a frase (`bare`).
+    <EmptySurface title={emptyMessage} compact frame={colSpan === undefined ? 'structural' : 'bare'} />
+  )
+
   // Modo TABELA: o estado vira UMA linha de largura cheia (<td colSpan>), pra caber no <tbody>.
   if (colSpan !== undefined) {
-    const status = error ? 'error' : loading ? 'loading' : 'empty'
     return (
       <tr data-slot="data-state" data-status={status}>
-        <td
-          colSpan={colSpan}
-          className={cn('px-4 py-10 text-center text-sm', error ? 'text-destructive' : 'text-muted-foreground/60')}
-        >
-          {error ? (
-            <div className="flex flex-col items-center gap-3">
-              <span>{errorText ?? 'Não foi possível carregar.'}</span>
-              {onRetry !== undefined && (
-                <Button variant="outline" size="sm" onClick={() => void onRetry()}>
-                  {retryText}
-                </Button>
-              )}
-            </div>
-          ) : loading ? (
-            <Spinner className="mx-auto" />
-          ) : (
-            emptyText
-          )}
+        <td colSpan={colSpan} className="px-4 py-4 text-center text-sm">
+          {surface}
         </td>
       </tr>
     )
   }
 
-  // Modo BLOCO (default).
-  if (error) {
-    return (
-      <div data-slot="data-state" data-status="error">
-        <Alert context="danger" description={errorText ?? 'Não foi possível carregar.'}>
-          {onRetry !== undefined && (
-            <Button variant="outline" size="sm" onClick={() => void onRetry()}>
-              {retryText}
-            </Button>
-          )}
-        </Alert>
-      </div>
-    )
-  }
-  if (loading) {
-    return (
-      <div
-        data-slot="data-state"
-        data-status="loading"
-        role="status"
-        aria-live="polite"
-        className="py-10 text-center text-muted-foreground"
-      >
-        <Spinner className="mx-auto" />
-      </div>
-    )
-  }
   return (
-    <p
-      data-slot="data-state"
-      data-status="empty"
-      className="rounded-lg border border-border py-10 text-center text-sm text-muted-foreground/60"
-    >
-      {emptyText}
-    </p>
+    <div data-slot="data-state" data-status={status}>
+      {surface}
+    </div>
   )
 }

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

@@ -13,6 +13,7 @@
  */
 
 import * as React from 'react'
+import type { UiContext } from '../../../core/ui-context.ts'
 import { cn } from '../../lib/cn.ts'
 import { Button } from '../primitives/button.tsx'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../primitives/tooltip.tsx'
@@ -142,7 +143,8 @@ export function DockAction({ icon, label, pressed, disabled = false, hint, class
         <Button
           data-slot="dock-action"
           size="icon"
-          variant={pressed === true ? 'default' : 'ghost'}
+          context={pressed === true ? 'primary' : 'neutral'}
+          variant={pressed === true ? 'solid' : 'ghost'}
           aria-label={label}
           aria-pressed={pressed}
           disabled={disabled}
@@ -162,9 +164,22 @@ const STATUS_POSITION = {
   'top-left': 'top-3 left-3',
 } as const
 
+export type SurfaceStatusContext = Exclude<UiContext, 'primary'>
+
+/** `neutral` mantém o cinza do chrome; os demais tingem borda e texto pela família semântica. */
+const STATUS_CONTEXT: Record<SurfaceStatusContext, string> = {
+  neutral: 'border-border text-muted-foreground',
+  info: 'border-context-info-border text-context-info-emphasis',
+  success: 'border-context-success-border text-context-success-emphasis',
+  warning: 'border-context-warning-border text-context-warning-emphasis',
+  danger: 'border-context-danger-border text-context-danger-emphasis',
+}
+
 export interface SurfaceStatusProps {
   /** Canto da superfície onde o estado se ancora. */
   position?: keyof typeof STATUS_POSITION
+  /** O que o estado comunica (salvo, falhou, publicando…). Sem contexto, fica neutro. */
+  context?: SurfaceStatusContext
   /** Ações do recurso aberto — em geral o mesmo menu que a linha dele tem na navegação. */
   actions?: React.ReactNode
   className?: string
@@ -180,14 +195,16 @@ export interface SurfaceStatusProps {
  * Mensagem de sucesso é transitória por natureza; falha permanece até o estado mudar. Quem decide
  * isso é a aplicação, que conhece o ciclo — o componente só reserva o lugar.
  */
-export function SurfaceStatus({ position = 'top-right', actions, className, children }: SurfaceStatusProps): React.ReactElement {
+export function SurfaceStatus({ position = 'top-right', context = 'neutral', actions, className, children }: SurfaceStatusProps): React.ReactElement {
   const hasActions = actions !== undefined && actions !== null
   return (
     <div
       data-slot="surface-status"
+      data-context={context}
       className={cn(
         'pointer-events-none absolute z-10 flex max-w-[calc(100%-1.5rem)] flex-row items-center gap-2',
-        'rounded-full border border-border bg-background/95 py-1.5 pl-3 text-xs text-muted-foreground shadow-sm backdrop-blur',
+        'rounded-full border bg-background/95 py-1.5 pl-3 text-xs shadow-sm backdrop-blur',
+        STATUS_CONTEXT[context],
         hasActions ? 'pr-1' : 'pr-3',
         STATUS_POSITION[position],
         className,

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/hint/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
+ *   (label/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.
  *
@@ -28,6 +28,7 @@ import {
 import { useDicts, useFormAction, type DictLike } from '../../drivers/react.tsx'
 import { z, type ZodTypeAny } from 'zod'
 import { cn } from '../../lib/cn.ts'
+import { humanizeActionError } from '../../lib/action-errors.ts'
 import { objectSchemaShape } from '../../lib/object-schema.ts'
 import { toast } from '../primitives/sonner.tsx'
 import { Button } from '../primitives/button.tsx'
@@ -39,7 +40,7 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../pri
 import { Info } from 'lucide-react'
 import { Select, type SelectOption } from '../primitives/select.tsx'
 import { ToggleGroup, ToggleGroupItem } from '../primitives/toggle-group.tsx'
-import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from '../primitives/field.tsx'
+import { Field, FieldError, FieldGroup, FieldLabel } from '../primitives/field.tsx'
 
 // =============================================================================
 // Inferência de tipo de field a partir do Zod schema
@@ -111,8 +112,7 @@ function inferFieldKind(schema: ZodTypeAny): FieldKind {
 interface FieldSpec {
   label?: string
   placeholder?: string
-  hint?: string
-  /** Ajuda na label: ícone ⓘ + tooltip no hover (explicação mais longa que o hint). */
+  /** Ajuda na label: ícone ⓘ + tooltip no hover. */
   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),
@@ -126,7 +126,7 @@ interface FieldSpec {
    *  No modo COMPOSIÇÃO o condicional pode (e deve) ser JSX de quem diagrama. */
   showWhen?: (input: Record<string, unknown>) => boolean
   /** Origem declarada das opções (static/dictionary/lookup) — ver a precedência
-   *  em `ActionFormField`. `dictionary` resolve pelos dicts do TbdlibProvider. */
+   *  em `ActionFormField`. `dictionary` resolve pelos dicts do OpusProvider. */
   options?: OptionsSpec
 }
 
@@ -171,11 +171,18 @@ function dictMetaOptions(schema: ZodTypeAny): SelectOption[] | undefined {
   })
 }
 
-/** Ícone de ajuda na label (ⓘ + tooltip Radix). Self-contained (inclui o Provider) — só
- *  renderiza quando o FieldSpec define `help`. `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). */
-function LabelHelp({ help }: { help: string | undefined }): React.ReactElement | null {
+/**
+ * Ícone de ajuda junto à label (ⓘ + tooltip Radix). Self-contained (inclui o Provider):
+ * renderiza somente quando `help` tem texto. É o mesmo slot que o `ActionFormField` usa para
+ * `FieldSpec.help`; exportado para que um formulário sem contrato mostre a ajuda no mesmo
+ * 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).
+ */
+export function LabelHelp({ help }: { help: string | undefined }): React.ReactElement | null {
   if (help === undefined || help.trim().length === 0) return null
   return (
     <TooltipProvider delayDuration={300}>
@@ -208,7 +215,7 @@ function RequiredMark({ required }: { required: boolean }): React.ReactElement |
   if (!required) return null
   return (
     <>
-      <span aria-hidden className="ml-0.5 text-destructive">
+      <span aria-hidden className="ml-0.5 text-context-danger-emphasis">
         *
       </span>
       <span className="sr-only"> (obrigatório)</span>
@@ -287,9 +294,8 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
   const spec: FieldSpec = fields[name] ?? {}
   const fieldError = form.formState.errors[name]
   const errorMessage = typeof fieldError?.message === 'string' ? fieldError.message : undefined
-  const descriptionId = spec.hint !== undefined ? `${name}-description` : undefined
   const errorId = errorMessage !== undefined ? `${name}-error` : undefined
-  const describedBy = [descriptionId, errorId].filter(Boolean).join(' ') || undefined
+  const describedBy = errorId
   useEffect(() => {
     if (errorMessage === undefined) return
     const control = document.getElementById(name)
@@ -371,7 +377,6 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           </span>
           <LabelHelp help={spec.help} />
         </FieldLabel>
-        {spec.hint !== undefined && <FieldDescription id={descriptionId}>{spec.hint}</FieldDescription>}
         {errorMessage !== undefined && <FieldError id={errorId}>{errorMessage}</FieldError>}
       </Field>
     )
@@ -530,7 +535,7 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
                   <Input
                     id={`${name}-${i}-text`}
                     value={item.text}
-                    placeholder={spec.placeholder ?? 'O quê (com critério)…'}
+                    placeholder={spec.placeholder ?? 'Descreva o critério…'}
                     onChange={(e) => setItems(items.map((it, j) => (j === i ? { ...it, text: e.target.value } : it)))}
                     aria-invalid={errorMessage !== undefined}
                     aria-describedby={describedBy}
@@ -593,9 +598,6 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
         />
       )}
 
-      {spec.hint !== undefined && (
-        <FieldDescription id={descriptionId}>{spec.hint}</FieldDescription>
-      )}
       {errorMessage !== undefined && (
         <FieldError id={errorId}>{errorMessage}</FieldError>
       )}
@@ -651,7 +653,7 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
       onSuccess?.(data)
     },
     onError: (err) => {
-      toast.error(msgText(action.messages?.error, err.message))
+      toast.error(humanizeActionError(err, msgText(action.messages?.error, 'Não foi possível salvar.')))
     },
   })
 
@@ -669,13 +671,15 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
     ))
 
   // Banner de erro do servidor (chrome do próprio form, nos dois modos). O FieldGroup
-  // mantém o mesmo ritmo entre campos, blocos compostos e este estado.
+  // mantém o mesmo ritmo entre campos, blocos compostos e este estado. Só a frase de
+  // negócio chega aqui; código e mensagem técnica ficam no log do servidor.
   const errorBanner =
     error !== undefined && !isSuccess ? (
       <div
-        className="rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive"
+        role="alert"
+        className="rounded-md border border-context-danger-border bg-context-danger-subtle p-3 text-sm text-context-danger-emphasis"
       >
-        <strong>{error.code}</strong>: {error.message}
+        {humanizeActionError(error, msgText(action.messages?.error, 'Não foi possível salvar.'))}
       </div>
     ) : null