@softize/opus 18.5.0 → 20.0.0

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

@@ -40,6 +40,8 @@ export const surfaceHeaderClasses: Record<
 
 interface SurfaceHeaderSlots {
   leading?: ElementType | readonly ElementType[];
+  /** Ícone ou imagem que abre a linha, antes do heading (ADR 0023). */
+  media?: ElementType;
   title: ElementType;
   count?: ElementType;
   description?: ElementType;
@@ -59,6 +61,16 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
   contentClassName?: string;
   /** Permite uma superfície composta apenas pelas regiões leading/actions. */
   titleRequired?: boolean;
+  /** Classes da linha `inline` — as famílias com anatomia própria trazem a sua (ADR 0023). */
+  rowClassName?: string;
+  /** Nó interno acrescentado ao fim da linha, depois das ações (o botão de fechar). */
+  trailing?: ReactNode;
+  /**
+   * Aceita conteúdo livre além dos slots. Vale para a superfície genérica — um pane
+   * hospeda marca, busca ou chrome que não são título nem ação. As famílias que sempre
+   * NOMEIAM algo (Card, Dialog, Drawer, Page, Content) continuam estritas.
+   */
+  allowFreeContent?: boolean;
 }
 
 /** Expande fragments de primeiro nível: o shorthand monta os slots dentro de um `<>`. */
@@ -77,6 +89,9 @@ export function SurfaceHeader({
   leadingPlacement = "above",
   contentClassName,
   titleRequired = true,
+  rowClassName,
+  trailing,
+  allowFreeContent = false,
   className,
   children,
   ...props
@@ -91,13 +106,30 @@ export function SurfaceHeader({
         ? slots.leading
         : [slots.leading as ElementType];
   const leading = leadingTypes.flatMap(of);
+  const medias = slots.media === undefined ? [] : of(slots.media);
   const titles = of(slots.title);
   const counts = slots.count === undefined ? [] : of(slots.count);
   const descriptions =
     slots.description === undefined ? [] : of(slots.description);
   const actionSlots = of(slots.actions);
+  const slotTypes = [
+    ...leadingTypes,
+    slots.media,
+    slots.title,
+    slots.count,
+    slots.description,
+    slots.actions,
+  ].filter((type): type is ElementType => type !== undefined);
+  const free = allowFreeContent
+    ? nodes.filter(
+        (node) =>
+          !(isValidElement(node) && slotTypes.includes(node.type as ElementType)),
+      )
+    : [];
   const recognized =
+    free.length +
     leading.length +
+    medias.length +
     titles.length +
     counts.length +
     descriptions.length +
@@ -106,6 +138,7 @@ export function SurfaceHeader({
   if (
     (titleRequired ? titles.length !== 1 : titles.length > 1) ||
     leading.length > 1 ||
+    medias.length > 1 ||
     counts.length > 1 ||
     descriptions.length > 1 ||
     actionSlots.length > 1 ||
@@ -117,6 +150,7 @@ export function SurfaceHeader({
         : ((type as { name?: string }).name ?? "");
     const optionalSlots = [
       ...leadingTypes,
+      slots.media,
       slots.description,
       slots.count,
       slots.actions,
@@ -140,16 +174,23 @@ export function SurfaceHeader({
     );
   }
 
-  const heading = titles.length + counts.length + descriptions.length > 0 && (
+  const heading = titles.length +
+    counts.length +
+    descriptions.length +
+    free.length >
+    0 && (
     <div
       data-slot={`${slot}-heading`}
       className={cn("min-w-0", leadingPlacement === "inline" && "flex-1")}
     >
-      <div className="flex items-baseline gap-2">
-        {titles}
-        {counts}
-      </div>
+      {titles.length + counts.length > 0 && (
+        <div className="flex items-baseline gap-2">
+          {titles}
+          {counts}
+        </div>
+      )}
       {descriptions}
+      {free}
     </div>
   );
   // A região introdutória carrega o mesmo `data-slot` nas duas apresentações: seletor de teste
@@ -166,13 +207,17 @@ export function SurfaceHeader({
           {leading}
         </div>
       )}
+      {medias}
       {heading}
       {actionSlots}
+      {trailing}
     </>
   );
   const layout =
     leadingPlacement === "inline" ? (
-      <div className="flex min-w-0 items-center gap-3">{row}</div>
+      <div className={cn("flex min-w-0 items-center gap-3", rowClassName)}>
+        {row}
+      </div>
     ) : leading.length > 0 ? (
       <>
         <div data-slot={`${slot}-navigation`} className="mb-4">

package/src/ui/components/patterns/surface-media.tsx

@@ -0,0 +1,69 @@
+/**
+ * Mídia de superfície (interno): a moldura que abre a linha do header — ADR 0023.
+ *
+ * Reusa `IconTile`; nenhuma família cria outra escala de molduras. O slot público de
+ * cada família (`CardMedia`, `DialogMedia`, …) delega para cá, escolhendo apenas o
+ * `data-slot` e a escala default.
+ */
+import type { ReactElement } from "react";
+
+import { Slot } from "@radix-ui/react-slot";
+
+import {
+  IconTile,
+  iconTileVariants,
+  type IconTileContext,
+  type IconTileSize,
+  type IconTileVariant,
+} from "../primitives/icon-tile.tsx";
+import { cn } from "../../lib/cn.ts";
+
+export interface SurfaceMediaProps
+  extends Omit<React.ComponentProps<"span">, "children"> {
+  /** Escala da moldura; a família define o default. */
+  size?: IconTileSize;
+  context?: IconTileContext;
+  variant?: IconTileVariant;
+  /**
+   * Renderiza como o filho: para a marca que já tem visual próprio — um orbe, um
+   * logotipo — ocupar o slot sem ganhar a moldura por cima.
+   */
+  asChild?: boolean;
+  children?: React.ReactNode;
+}
+
+export function SurfaceMedia({
+  slot,
+  size = "sm",
+  context,
+  variant,
+  asChild = false,
+  className,
+  ...props
+}: SurfaceMediaProps & { slot: string }): ReactElement {
+  if (asChild) {
+    return (
+      <Slot
+        data-slot={slot}
+        className={cn(
+          iconTileVariants({ size, context: null, variant: null }),
+          // Sem fundo nem borda: quem compõe traz o próprio visual.
+          "bg-transparent",
+          "shrink-0",
+          className,
+        )}
+        {...props}
+      />
+    );
+  }
+  return (
+    <IconTile
+      data-slot={slot}
+      size={size}
+      {...(context !== undefined ? { context } : {})}
+      {...(variant !== undefined ? { variant } : {})}
+      className={cn("shrink-0", className)}
+      {...props}
+    />
+  );
+}

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

@@ -66,6 +66,7 @@ export interface ActionTriggerProps<TInput, TData> {
     title: string;
     /** Conteúdo relevante apresentado antes das ações. */
     body?: ReactNode;
+    /** Texto do botão de confirmar. Default: `action.label`; o `label` do gatilho só sem ele. */
     actionLabel?: string;
     cancelLabel?: string;
   };
@@ -123,6 +124,15 @@ export function ActionTrigger<TInput, TData>({
 
   const buttonLabel =
     label ?? (typeof action.label === "string" ? action.label : action.name);
+  /**
+   * Botão de confirmar: `confirmLabel` do contrato, depois o `label` da action. O `label` do
+   * gatilho costuma ser um nome acessível que identifica o alvo ("Excluir Unidade Centro"); na
+   * pergunta o alvo já está no corpo, então ele só entra quando o contrato não tem rótulo.
+   */
+  const confirmActionLabel =
+    action.label !== undefined
+      ? msgText(action.label, buttonLabel)
+      : buttonLabel;
 
   // Prop sobrepõe; sem prop, o ConfirmSpec DECLARADO no contrato (action.confirm) vale.
   const spec = action.confirm;
@@ -135,7 +145,7 @@ export function ActionTrigger<TInput, TData>({
             ? { body: msgText(spec.message, "") }
             : {}),
           ...(spec.confirmLabel !== undefined
-            ? { actionLabel: msgText(spec.confirmLabel, buttonLabel) }
+            ? { actionLabel: msgText(spec.confirmLabel, confirmActionLabel) }
             : {}),
           ...(spec.cancelLabel !== undefined
             ? { cancelLabel: msgText(spec.cancelLabel, "Cancelar") }
@@ -248,7 +258,7 @@ export function ActionTrigger<TInput, TData>({
                 busy={isLoading}
                 onClick={fire}
               >
-                {confirm.actionLabel ?? buttonLabel}
+                {confirm.actionLabel ?? confirmActionLabel}
               </Button>
             </ButtonGroup>
           </DialogFooter>

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

@@ -71,6 +71,14 @@ function alertMediaClasses(context: AlertContext): string {
   );
 }
 
+/**
+ * `role="alert"` interrompe o leitor de tela; só perigo e atenção justificam a interrupção.
+ * Os demais contextos são anunciados sem cortar a leitura, como `role="status"`.
+ */
+function alertRole(context: AlertContext): "alert" | "status" {
+  return context === "danger" || context === "warning" ? "alert" : "status";
+}
+
 const alertHeaderClasses =
   "col-start-2 row-start-1 flex min-w-0 flex-col justify-center gap-1";
 
@@ -147,7 +155,7 @@ export function Alert({
         data-slot="alert"
         data-context={resolved.context}
         data-variant={resolved.variant}
-        role="alert"
+        role={alertRole(resolved.context)}
         className={cn(alertVariants(resolved), className)}
         {...props}
       >

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

@@ -8,6 +8,10 @@ import type { ControlSize } from './control.ts'
  * Ejetado (14.0.0): `size` segue a escala de control.ts — o avatar de uma linha `sm` mede o
  * mesmo que o controle `sm` ao lado (2rem); `xs` (1.5rem) é a lista densa; `default` (2.25rem)
  * e `lg` (2.5rem) pareiam com Button/Input. O fallback e o selo acompanham o tamanho.
+ *
+ * O root não recorta (20.0.0): imagem e fallback herdam o raio do root e se recortam sozinhos, e
+ * o AvatarBadge, que transborda o círculo no canto, aparece inteiro. A forma continua declarada
+ * no root (`rounded-full` por padrão, `rounded-lg` para logo) e o anel do AvatarGroup a segue.
  */
 function Avatar({
   className,
@@ -21,7 +25,7 @@ function Avatar({
       data-slot="avatar"
       data-size={size}
       className={cn(
-        "group/avatar relative flex shrink-0 overflow-hidden rounded-full select-none data-[size=xs]:size-6 data-[size=sm]:size-8 data-[size=default]:size-9 data-[size=lg]:size-10",
+        "group/avatar relative flex shrink-0 rounded-full select-none data-[size=xs]:size-6 data-[size=sm]:size-8 data-[size=default]:size-9 data-[size=lg]:size-10",
         className
       )}
       {...props}
@@ -36,7 +40,7 @@ function AvatarImage({
   return (
     <AvatarPrimitive.Image
       data-slot="avatar-image"
-      className={cn("aspect-square size-full", className)}
+      className={cn("aspect-square size-full rounded-[inherit] object-cover", className)}
       {...props}
     />
   )
@@ -50,7 +54,7 @@ function AvatarFallback({
     <AvatarPrimitive.Fallback
       data-slot="avatar-fallback"
       className={cn(
-        "flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=xs]/avatar:text-xs group-data-[size=sm]/avatar:text-xs",
+        "flex size-full items-center justify-center overflow-hidden rounded-[inherit] bg-muted text-sm text-muted-foreground group-data-[size=xs]/avatar:text-xs group-data-[size=sm]/avatar:text-xs",
         className
       )}
       {...props}

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

@@ -1,61 +1,116 @@
 import * as React from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { cn } from "../../lib/cn.ts";
+import {
+  SurfaceLayoutProvider,
+  surfaceActionsClasses,
+  surfaceDescriptionClasses,
+  surfaceHeaderRowClasses,
+  surfaceRegionClasses,
+  surfaceTitleClasses,
+  useSurfaceLayout,
+  type SurfaceLayout,
+} from "../patterns/surface-anatomy.ts";
+import { SurfaceHeader } from "../patterns/surface-header.tsx";
+import {
+  SurfaceMedia,
+  type SurfaceMediaProps,
+} from "../patterns/surface-media.tsx";
+import { headingTags, type HeadingLevel } from "../patterns/heading-level.ts";
 
 /**
  * Card — a superfície da casa: SÓ a casca (borda + raio + bg). Divergência DECLARADA vs
- * shadcn: FLAT (sem `shadow-sm`) e SEM `flex/gap/py` forçados. O upstream embute
- * `py-6 gap-6` + slots `px-6`, o que briga com card-box
- * simples (o `gap-6` do Card + o `space-y` do consumidor = espaçamento dobrado) — por isso
- * a casa hand-rollava. Aqui o padding mora no SLOT (Header/Body/Footer) ou no `className`
- * do consumidor (box simples) — mesmo modelo do Dialog.
+ * shadcn: FLAT (sem `shadow-sm`) e SEM `flex/gap/py` forçados. O padding mora no SLOT
+ * (Header/Body/Footer) ou no `className` do consumidor (box simples).
  *
  *   Box simples:   <Card className="p-4">…</Card>
- *   Estruturado:   <Card><CardHeader>…</CardHeader><CardBody>…</CardBody><CardFooter>…</CardFooter></Card>
+ *   Estruturado:   <Card><CardHeader>…</CardHeader><CardBody>…</CardBody></Card>
+ *
+ * `layout` é o pacote de anatomia da ADR 0023 e vale para a superfície inteira:
+ *
+ *   contínuo (default): sem divisores; o ritmo separa as regiões.
+ *   seccionado:         regiões simétricas, com divisor entre as adjacentes.
+ *
+ * O divisor é derivado da presença das regiões — o consumidor não escreve `border-b`.
  */
 export function Card({
   className,
   asChild = false,
+  layout = "continuous",
   ...props
 }: React.ComponentProps<"div"> & {
   /** Renderiza como o filho (Radix Slot) — pra card CLICÁVEL manter a semântica do filho
    *  (ex.: <button>) com a superfície do Card: `<Card asChild><button onClick>…</button></Card>`. */
   asChild?: boolean;
+  /** Anatomia da superfície: `continuous` (default) ou `sectioned`. */
+  layout?: SurfaceLayout;
 }): React.ReactElement {
   const Comp = asChild ? Slot : "div";
   return (
-    <Comp
-      data-slot="card"
-      className={cn(
-        "rounded-xl border border-border bg-card text-card-foreground",
-        className,
-      )}
-      {...props}
-    />
+    <SurfaceLayoutProvider value={layout}>
+      <Comp
+        data-slot="card"
+        data-layout={layout}
+        className={cn(
+          "rounded-xl border border-border bg-card text-card-foreground",
+          // Seccionado: o divisor encosta na borda, então o raio precisa recortar.
+          layout === "sectioned" && "overflow-hidden",
+          className,
+        )}
+        {...props}
+      />
+    </SurfaceLayoutProvider>
   );
 }
 
 export function CardHeader({
   className,
+  children,
   ...props
 }: React.ComponentProps<"div">): React.ReactElement {
+  const layout = useSurfaceLayout("card");
   return (
-    <div
-      data-slot="card-header"
-      className={cn("flex flex-col gap-1.5 px-5 pt-5 pb-3", className)}
+    <SurfaceHeader
+      name="CardHeader"
+      slot="card"
+      slots={{
+        media: CardMedia,
+        title: CardTitle,
+        description: CardDescription,
+        actions: CardAction,
+      }}
+      leadingPlacement="inline"
+      titleRequired={false}
+      rowClassName={surfaceHeaderRowClasses("card")}
+      className={cn(surfaceRegionClasses("card", layout, "header"), className)}
       {...props}
-    />
+    >
+      {children}
+    </SurfaceHeader>
   );
 }
 
+/** Moldura de ícone ou imagem que abre a linha do header. */
+export function CardMedia(props: SurfaceMediaProps): React.ReactElement {
+  return <SurfaceMedia slot="card-media" {...props} />;
+}
+
 export function CardTitle({
   className,
+  level = 3,
+  asChild = false,
   ...props
-}: React.ComponentProps<"div">): React.ReactElement {
+}: React.ComponentProps<"h3"> & {
+  /** Hierarquia do documento (`h1`–`h6`). O tamanho vem do layout, nunca do nível. */
+  level?: HeadingLevel;
+  asChild?: boolean;
+}): React.ReactElement {
+  const layout = useSurfaceLayout("card");
+  const Comp = asChild ? Slot : headingTags[level];
   return (
-    <div
+    <Comp
       data-slot="card-title"
-      className={cn("font-semibold leading-none", className)}
+      className={cn(surfaceTitleClasses("card", layout), className)}
       {...props}
     />
   );
@@ -64,17 +119,17 @@ export function CardTitle({
 export function CardDescription({
   className,
   ...props
-}: React.ComponentProps<"div">): React.ReactElement {
+}: React.ComponentProps<"p">): React.ReactElement {
   return (
-    <div
+    <p
       data-slot="card-description"
-      className={cn("text-sm text-muted-foreground", className)}
+      className={cn(surfaceDescriptionClasses("card"), className)}
       {...props}
     />
   );
 }
 
-/** Slot de ação no header (botão/menu) — o consumidor posiciona (ex.: header em flex-row). */
+/** Ações do header — a família posiciona no extremo oposto ao título. */
 export function CardAction({
   className,
   ...props
@@ -82,7 +137,7 @@ export function CardAction({
   return (
     <div
       data-slot="card-action"
-      className={cn("shrink-0", className)}
+      className={cn(surfaceActionsClasses, className)}
       {...props}
     />
   );
@@ -92,10 +147,11 @@ export function CardBody({
   className,
   ...props
 }: React.ComponentProps<"div">): React.ReactElement {
+  const layout = useSurfaceLayout("card");
   return (
     <div
       data-slot="card-body"
-      className={cn("px-5 py-3", className)}
+      className={cn(surfaceRegionClasses("card", layout, "body"), className)}
       {...props}
     />
   );
@@ -106,10 +162,11 @@ export function CardContent({
   className,
   ...props
 }: React.ComponentProps<"div">): React.ReactElement {
+  const layout = useSurfaceLayout("card");
   return (
     <div
       data-slot="card-content"
-      className={cn("px-5 py-3", className)}
+      className={cn(surfaceRegionClasses("card", layout, "body"), className)}
       {...props}
     />
   );
@@ -119,10 +176,15 @@ export function CardFooter({
   className,
   ...props
 }: React.ComponentProps<"div">): React.ReactElement {
+  const layout = useSurfaceLayout("card");
   return (
     <div
       data-slot="card-footer"
-      className={cn("flex items-center px-5 pt-3 pb-5", className)}
+      className={cn(
+        "flex items-center justify-end gap-2",
+        surfaceRegionClasses("card", layout, "footer"),
+        className,
+      )}
       {...props}
     />
   );

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

@@ -34,12 +34,33 @@ function useCarousel() {
   const context = React.useContext(CarouselContext)
 
   if (!context) {
-    throw new Error("useCarousel must be used within a <Carousel />")
+    throw new Error(
+      "useCarousel só funciona dentro de <Carousel />. Coloque CarouselContent, CarouselItem, CarouselPrevious e CarouselNext dentro de um <Carousel>."
+    )
   }
 
   return context
 }
 
+// Quem usa as setas por conta própria: campos editáveis e widgets compostos que navegam por dentro
+// (Slider, RadioGroup, Tabs, listas, menus; ToggleGroup e Accordion pelos itens de coleção do
+// Radix). A captura do carrossel roda antes deles e, com `preventDefault`, os handlers do Radix
+// desistem do evento — por isso as setas vindas daqui ficam com o widget.
+const ARROW_OWNERS =
+  "input, textarea, select, [contenteditable]:not([contenteditable=false]), " +
+  "[role=slider], [role=radiogroup], [role=tablist], [role=listbox], [role=menu], [role=menubar], " +
+  "[role=combobox], [role=grid], [role=tree], [role=spinbutton], [role=toolbar], " +
+  "[data-radix-collection-item]"
+
+// Só conta o dono que está DENTRO do carrossel (ou num portal aberto a partir dele): um carrossel
+// posto dentro de uma toolbar ou de uma célula de grid continua respondendo às setas.
+function ownsArrowKeys(target: EventTarget, carousel: EventTarget): boolean {
+  if (!(target instanceof HTMLElement)) return false
+  if (target.isContentEditable) return true
+  const owner = target.closest(ARROW_OWNERS)
+  return owner !== null && !(carousel instanceof Node && owner.contains(carousel))
+}
+
 function Carousel({
   orientation = "horizontal",
   opts,
@@ -75,15 +96,22 @@ function Carousel({
 
   const handleKeyDown = React.useCallback(
     (event: React.KeyboardEvent<HTMLDivElement>) => {
-      if (event.key === "ArrowLeft") {
+      // As setas de um campo editável dentro do slide movem o cursor ou mudam a opção; o
+      // carrossel não as rouba.
+      if (ownsArrowKeys(event.target, event.currentTarget)) return
+      const [prevKey, nextKey] =
+        orientation === "vertical"
+          ? ["ArrowUp", "ArrowDown"]
+          : ["ArrowLeft", "ArrowRight"]
+      if (event.key === prevKey) {
         event.preventDefault()
         scrollPrev()
-      } else if (event.key === "ArrowRight") {
+      } else if (event.key === nextKey) {
         event.preventDefault()
         scrollNext()
       }
     },
-    [scrollPrev, scrollNext]
+    [orientation, scrollPrev, scrollNext]
   )
 
   React.useEffect(() => {
@@ -98,7 +126,8 @@ function Carousel({
     api.on("select", onSelect)
 
     return () => {
-      api?.off("select", onSelect)
+      api.off("reInit", onSelect)
+      api.off("select", onSelect)
     }
   }, [api, onSelect])
 

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

@@ -1,5 +1,5 @@
 import * as React from "react"
-import { CheckIcon } from "lucide-react"
+import { CheckIcon, MinusIcon } from "lucide-react"
 import { Checkbox as CheckboxPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
@@ -12,7 +12,7 @@ function Checkbox({
     <CheckboxPrimitive.Root
       data-slot="checkbox"
       className={cn(
-        "peer size-4 shrink-0 rounded-[0.25rem] border border-input transition-shadow outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground dark:bg-input/30 dark:aria-invalid:ring-context-danger/40 dark:data-[state=checked]:bg-primary",
+        "peer group/checkbox size-4 shrink-0 rounded-[0.25rem] border border-input transition-shadow outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=indeterminate]:border-primary data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-primary-foreground dark:bg-input/30 dark:aria-invalid:ring-context-danger/40 dark:data-[state=checked]:bg-primary dark:data-[state=indeterminate]:bg-primary",
         className
       )}
       {...props}
@@ -21,7 +21,15 @@ function Checkbox({
         data-slot="checkbox-indicator"
         className="grid place-content-center text-current transition-none"
       >
-        <CheckIcon className="size-3.5" />
+        {/* Indeterminado ("alguns marcados") tem glifo próprio: o traço não se confunde com o check. */}
+        <CheckIcon
+          data-slot="checkbox-check"
+          className="size-3.5 group-data-[state=indeterminate]/checkbox:hidden"
+        />
+        <MinusIcon
+          data-slot="checkbox-indeterminate"
+          className="hidden size-3.5 group-data-[state=indeterminate]/checkbox:block"
+        />
       </CheckboxPrimitive.Indicator>
     </CheckboxPrimitive.Root>
   )

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

@@ -38,15 +38,23 @@ function CommandDialog({
   return (
     <Dialog {...props}>
       <DialogContent
+        // A paleta é uma superfície contínua: a lista já separa os grupos, e uma faixa
+        // sob o cabeçalho competiria com ela.
+        layout="continuous"
         className={cn("overflow-hidden p-0", className)}
         showCloseButton={showCloseButton}
         aria-describedby={descriptionId}
       >
-        <DialogHeader className="border-b-0 px-3 py-2">
+        {/* A descrição só existe para o `aria-describedby`; fora do header, que só
+            nomeia a superfície (ADRs 0018 e 0023). */}
+        <p id={descriptionId} className="sr-only">
+          {description}
+        </p>
+        {/* O recuo e a escala são os da paleta, não os da família: a caixa de busca
+            manda na densidade, e o título aqui é um rótulo acima dela. É a única
+            superfície do SDK que diverge nos dois, e por isso está escrito aqui. */}
+        <DialogHeader className="px-3 py-2">
           <DialogTitle className="text-sm">{title}</DialogTitle>
-          <p id={descriptionId} className="sr-only">
-            {description}
-          </p>
         </DialogHeader>
         <Command className="**:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
           {children}
@@ -95,12 +103,13 @@ function CommandList({
 }
 
 function CommandEmpty({
+  className,
   ...props
 }: React.ComponentProps<typeof CommandPrimitive.Empty>) {
   return (
     <CommandPrimitive.Empty
       data-slot="command-empty"
-      className="py-6 text-center text-sm"
+      className={cn("py-6 text-center text-sm", className)}
       {...props}
     />
   );