@softize/opus 19.0.0 → 20.1.0

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

@@ -11,6 +11,7 @@ import {
   useSurfaceLayout,
   type SurfaceLayout,
 } from "../patterns/surface-anatomy.ts";
+import { FillBoundary } from "../patterns/fill-region.ts";
 import { headingTags, type HeadingLevel } from "../patterns/heading-level.ts";
 import { SurfaceHeader } from "../patterns/surface-header.tsx";
 import {
@@ -45,6 +46,24 @@ const DialogContentContext = React.createContext<DialogContentContextValue>({
   closeSize: "sm",
 });
 
+/**
+ * Compõe o handler de dispensa do consumidor com o bloqueio de `closeDisabled`: o handler dele
+ * roda primeiro e, com a superfície bloqueada, o evento é cancelado para que Esc, clique fora ou
+ * foco fora não a fechem. Sem bloqueio, devolve o handler original.
+ */
+export function preventDismissWhen<
+  E extends { defaultPrevented: boolean; preventDefault(): void },
+>(
+  blocked: boolean,
+  handler: ((event: E) => void) | undefined,
+): ((event: E) => void) | undefined {
+  if (!blocked) return handler;
+  return (event) => {
+    handler?.(event);
+    if (!event.defaultPrevented) event.preventDefault();
+  };
+}
+
 function useDialogContext(): DialogContextValue {
   return React.useContext(DialogContext);
 }
@@ -192,11 +211,16 @@ export function DialogContent({
   closeSize = "sm",
   layout = "sectioned",
   "aria-describedby": ariaDescribedBy,
+  onEscapeKeyDown,
+  onInteractOutside,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Content> & {
   /** Mostra a ação “Fechar” no modo padrão. O modo `alert` exige uma resposta identificável. */
   showCloseButton?: boolean;
-  /** Mantém a ação visível, mas impede fechar enquanto a superfície está bloqueada. */
+  /**
+   * Bloqueia o fechamento enquanto a superfície está ocupada: desabilita a ação “Fechar”, que
+   * continua visível, e cancela Esc e clique ou foco fora depois dos handlers do consumidor.
+   */
   closeDisabled?: boolean;
   /** Tamanho da ação circular de fechar no cabeçalho. */
   closeSize?: CloseButtonSize;
@@ -206,7 +230,7 @@ export function DialogContent({
   const { mode } = useDialogContext();
   const showClose = showCloseButton ?? mode !== "alert";
   const contentClasses =
-    "fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] overflow-clip rounded-xl border border-transparent bg-background text-foreground shadow-xl duration-200 outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:border-border/70";
+    "fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] overflow-clip rounded-xl border border-transparent bg-background text-foreground shadow-xl duration-200 outline-none [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:border-border/70";
 
   if (mode === "alert") {
     return (
@@ -217,17 +241,22 @@ export function DialogContent({
           data-mode="alert"
           className={cn(contentClasses, "grid max-w-xs gap-4 p-6", className)}
           aria-describedby={ariaDescribedBy}
+          onEscapeKeyDown={preventDismissWhen(closeDisabled, onEscapeKeyDown)}
           {...props}
         >
-          <DialogContentContext.Provider
-            value={{
-              showCloseButton: false,
-              closeDisabled: true,
-              closeSize,
-            }}
-          >
-            {children}
-          </DialogContentContext.Provider>
+          {/* Sem anatomia seccionada (exceção da ADR 0023), mas a altura continua sendo
+              decisão do diálogo: a cadeia `fill` da página não atravessa o portal. */}
+          <FillBoundary>
+            <DialogContentContext.Provider
+              value={{
+                showCloseButton: false,
+                closeDisabled: true,
+                closeSize,
+              }}
+            >
+              {children}
+            </DialogContentContext.Provider>
+          </FillBoundary>
         </AlertDialogPrimitive.Content>
       </DialogPortal>
     );
@@ -246,6 +275,8 @@ export function DialogContent({
           className,
         )}
         aria-describedby={ariaDescribedBy}
+        onEscapeKeyDown={preventDismissWhen(closeDisabled, onEscapeKeyDown)}
+        onInteractOutside={preventDismissWhen(closeDisabled, onInteractOutside)}
         {...props}
       >
         <SurfaceLayoutProvider value={layout}>

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

@@ -21,7 +21,7 @@ import {
   CloseButton,
   type CloseButtonSize,
 } from "./close-button.tsx";
-import { overlayClasses } from "./dialog.tsx";
+import { overlayClasses, preventDismissWhen } from "./dialog.tsx";
 
 interface DrawerContentContextValue {
   showCloseButton: boolean;
@@ -95,10 +95,16 @@ function DrawerContent({
   closeSize = "sm",
   layout = "sectioned",
   "aria-describedby": ariaDescribedBy,
+  onEscapeKeyDown,
+  onInteractOutside,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Content> & {
   side?: "top" | "right" | "bottom" | "left";
   showCloseButton?: boolean;
+  /**
+   * Bloqueia o fechamento enquanto a superfície está ocupada: desabilita a ação “Fechar”, que
+   * continua visível, e cancela Esc e clique ou foco fora depois dos handlers do consumidor.
+   */
   closeDisabled?: boolean;
   closeSize?: CloseButtonSize;
   /** Anatomia da superfície: `sectioned` (default) ou `continuous` — ADR 0023. */
@@ -111,7 +117,7 @@ function DrawerContent({
         data-slot="drawer-content"
         data-layout={layout}
         className={cn(
-          "fixed z-50 flex flex-col bg-background shadow-lg transition ease-in-out data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
+          "fixed z-50 flex flex-col bg-background shadow-lg transition ease-in-out [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
           side === "right" &&
             "inset-y-0 right-0 h-full w-3/4 max-w-sm border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right",
           side === "left" &&
@@ -123,6 +129,8 @@ function DrawerContent({
           className,
         )}
         aria-describedby={ariaDescribedBy}
+        onEscapeKeyDown={preventDismissWhen(closeDisabled, onEscapeKeyDown)}
+        onInteractOutside={preventDismissWhen(closeDisabled, onInteractOutside)}
         {...props}
       >
         <SurfaceLayoutProvider value={layout}>

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

@@ -69,7 +69,7 @@ function EmptyTitle({ className, ...props }: React.ComponentProps<"div">) {
   )
 }
 
-function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
+function EmptyDescription({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="empty-description"

package/src/ui/components/primitives/icon-picker.tsx

@@ -46,7 +46,7 @@ import {
   type LucideIcon,
 } from 'lucide-react'
 import { cn } from '../../lib/cn.ts'
-import { focusRing } from './control.ts'
+import { controlHeight, focusRing } from './control.ts'
 import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from './command.tsx'
 import { Popover, PopoverContent, PopoverTrigger } from './popover.tsx'
 
@@ -142,8 +142,12 @@ export function IconPicker({
           aria-describedby={ariaDescribedBy}
           data-slot="icon-picker"
           className={cn(
-            'flex h-10 w-full items-center gap-2 rounded-md border border-input bg-muted/30 px-3 text-sm outline-none transition-[color,box-shadow] disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30',
+            // Mesma altura do Input e do Select no tamanho default: lado a lado num form, alinham.
+            'flex w-full items-center gap-2 rounded-md border border-input bg-muted/30 px-3 text-sm outline-none transition-[color,box-shadow] disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30',
+            controlHeight.default,
             focusRing,
+            // As mesmas classes de inválido do Input e do Select: o erro aparece na moldura.
+            'aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:aria-invalid:ring-context-danger/40',
             className,
           )}
         >

package/src/ui/components/primitives/icon-tile.tsx

@@ -41,6 +41,13 @@ export interface IconTileProps
   extends React.ComponentProps<'span'>,
     IconTileStyleOptions {}
 
+/**
+ * Preenche os padrões de `context`, `variant` e `size` (`neutral`, `subtle`, `default`).
+ *
+ * @deprecated Não há decisão a tomar com os valores resolvidos fora do próprio IconTile. Para a
+ * moldura, renderize `IconTile`; para aplicá-la a outro elemento, use `iconTileVariants`, que já
+ * aplica os mesmos padrões. Sai do pacote numa próxima versão major.
+ */
 export function resolveIconTileStyle({
   context,
   variant,

package/src/ui/components/primitives/input-group.tsx

@@ -37,7 +37,12 @@ function InputGroup({ className, shape = 'default', ...props }: React.ComponentP
 }
 
 const inputGroupAddonVariants = cva(
-  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-0.3125rem)] [&>svg:not([class*='size-'])]:size-4",
+  [
+    "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-0.3125rem)] [&>svg:not([class*='size-'])]:size-4",
+    // O addon acompanha o controle desabilitado sem depender do `data-disabled` manual. Só o
+    // controle conta: um InputGroupButton desabilitado não apaga o grupo inteiro.
+    "group-has-[[data-slot=input-group-control]:disabled]/input-group:opacity-50",
+  ],
   {
     variants: {
       align: {
@@ -72,7 +77,9 @@ function InputGroupAddon({
         if ((e.target as HTMLElement).closest("button")) {
           return
         }
-        e.currentTarget.parentElement?.querySelector("input")?.focus()
+        e.currentTarget.parentElement
+          ?.querySelector<HTMLElement>("input, textarea")
+          ?.focus()
       }}
       {...props}
     />

package/src/ui/components/primitives/input-otp.tsx

@@ -49,7 +49,7 @@ function InputOTPSlot({
       data-slot="input-otp-slot"
       data-active={isActive}
       className={cn(
-        "relative flex h-9 w-9 items-center justify-center border-y border-r border-input text-sm transition-all outline-none first:rounded-l-md first:border-l last:rounded-r-md aria-invalid:border-context-danger data-[active=true]:z-10 data-[active=true]:border-ring data-[active=true]:ring-[0.1875rem] data-[active=true]:ring-ring/50 data-[active=true]:aria-invalid:border-context-danger data-[active=true]:aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:data-[active=true]:aria-invalid:ring-context-danger/40",
+        "relative flex h-9 w-9 items-center justify-center border-y border-r border-input bg-muted/30 text-sm transition-all outline-none first:rounded-l-md first:border-l last:rounded-r-md aria-invalid:border-context-danger data-[active=true]:z-10 data-[active=true]:border-ring data-[active=true]:ring-[0.1875rem] data-[active=true]:ring-ring/50 data-[active=true]:aria-invalid:border-context-danger data-[active=true]:aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:data-[active=true]:aria-invalid:ring-context-danger/40",
         className
       )}
       {...props}

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

@@ -15,7 +15,7 @@ function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
   )
 }
 
-function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
+function KbdGroup({ className, ...props }: React.ComponentProps<"kbd">) {
   return (
     <kbd
       data-slot="kbd-group"

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

@@ -12,6 +12,9 @@ function Label({
       data-slot="label"
       className={cn(
         "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        // O Field declara o grupo nomeado `group/field`: sem o sufixo, o Label não enxerga o
+        // `data-disabled` dele e continua aceso ao lado de um controle desabilitado.
+        "group-data-[disabled=true]/field:pointer-events-none group-data-[disabled=true]/field:opacity-50",
         className
       )}
       {...props}

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

@@ -12,6 +12,11 @@ function Menu({
   return <MenuPrimitive.Root data-slot="menu" {...props} />
 }
 
+/**
+ * @deprecated `MenuContent` já renderiza o painel num portal próprio, então envolvê-lo com
+ * `MenuPortal` não muda onde o painel aparece. Use `MenuContent` diretamente. Sai do pacote numa
+ * próxima versão major.
+ */
 function MenuPortal({
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Portal>) {

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

@@ -59,7 +59,7 @@ function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
   )
 }
 
-function PopoverTitle({ className, ...props }: React.ComponentProps<"h2">) {
+function PopoverTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="popover-title"

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

@@ -32,13 +32,21 @@ export interface ProgressProps extends React.ComponentProps<typeof ProgressPrimi
 function Progress({
   className,
   value,
+  max = 100,
   context = 'primary',
   ...props
 }: ProgressProps) {
+  // A largura é a fração de `max`, não de 100: `value={3} max={4}` enche três quartos. Um `max`
+  // não positivo cai em 100, como o Radix faz no Root.
+  const scale = max > 0 ? max : 100
+  const percent = ((value ?? 0) / scale) * 100
   return (
     <ProgressPrimitive.Root
       data-slot="progress"
       data-context={context}
+      // O Root precisa do `value` para anunciar o andamento (aria-valuenow, data-state).
+      value={value}
+      max={max}
       className={cn(
         "relative h-2 w-full overflow-hidden rounded-full",
         trackClasses[context],
@@ -49,7 +57,7 @@ function Progress({
       <ProgressPrimitive.Indicator
         data-slot="progress-indicator"
         className={cn("h-full w-full flex-1 transition-all", indicatorClasses[context])}
-        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+        style={{ transform: `translateX(-${100 - percent}%)` }}
       />
     </ProgressPrimitive.Root>
   )

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

@@ -4,14 +4,40 @@ import { Slider as SliderPrimitive } from "radix-ui"
 import { cn } from '../../lib/cn.ts'
 import { focusRing } from './control.ts'
 
+export interface SliderProps extends React.ComponentProps<typeof SliderPrimitive.Root> {
+  /**
+   * Nome de cada thumb, na ordem de `value`. Use em intervalos, em que cada controle precisa de
+   * um nome próprio (`['Custo mínimo', 'Custo máximo']`). Prevalece sobre `aria-label` e
+   * `aria-labelledby` no thumb correspondente.
+   */
+  thumbLabels?: readonly string[]
+}
+
+// Quem recebe foco e anuncia o valor é o thumb (`role="slider"`), não a raiz. Por isso
+// `aria-label` e `aria-labelledby` vão para os thumbs, como o Select faz com o campo interno;
+// na raiz, sem papel, não nomeariam nada. Em intervalo, `thumbLabels` dá um nome a cada controle.
+// Sem nome declarado, o Radix usaria "Minimum"/"Maximum": o fallback fica em português. Em
+// intervalo sem `thumbLabels`, o nome comum se compõe com o fallback ("Preço, mínimo"), senão os
+// dois thumbs teriam o mesmo nome; com `aria-labelledby`, o fallback entra por um span oculto
+// referenciado junto (`hidden` sai da tela, mas continua valendo como rótulo referenciado).
+function thumbFallback(index: number, total: number): string | undefined {
+  if (total > 2) return `Valor ${index + 1} de ${total}`
+  if (total === 2) return index === 0 ? 'Mínimo' : 'Máximo'
+  return undefined
+}
+
 function Slider({
   className,
   defaultValue,
   value,
   min = 0,
   max = 100,
+  thumbLabels,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledby,
   ...props
-}: React.ComponentProps<typeof SliderPrimitive.Root>) {
+}: SliderProps) {
+  const fallbackIdBase = React.useId()
   const _values = React.useMemo(
     () =>
       Array.isArray(value)
@@ -48,16 +74,41 @@ function Slider({
           )}
         />
       </SliderPrimitive.Track>
-      {Array.from({ length: _values.length }, (_, index) => (
-        <SliderPrimitive.Thumb
-          data-slot="slider-thumb"
-          key={index}
-          className={cn(
-            "block size-4 shrink-0 rounded-full border border-primary bg-background shadow-sm transition-[color,box-shadow] hover:ring-[0.1875rem] hover:ring-ring/50 focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50",
-            focusRing,
-          )}
-        />
-      ))}
+      {Array.from({ length: _values.length }, (_, index) => {
+        const thumbLabel = thumbLabels?.[index]
+        const fallback = thumbFallback(index, _values.length)
+        const fallbackId = `${fallbackIdBase}-thumb-${index}`
+        const composeLabelledby = thumbLabel === undefined && ariaLabelledby !== undefined && fallback !== undefined
+        const label =
+          thumbLabel ??
+          (ariaLabel !== undefined && fallback !== undefined
+            ? `${ariaLabel}, ${fallback.toLowerCase()}`
+            : ariaLabel ?? fallback)
+        return (
+          <React.Fragment key={index}>
+            {composeLabelledby && (
+              <span id={fallbackId} hidden>
+                {fallback}
+              </span>
+            )}
+            <SliderPrimitive.Thumb
+              data-slot="slider-thumb"
+              aria-label={composeLabelledby ? undefined : label}
+              aria-labelledby={
+                thumbLabel !== undefined
+                  ? undefined
+                  : composeLabelledby
+                    ? `${ariaLabelledby} ${fallbackId}`
+                    : ariaLabelledby
+              }
+              className={cn(
+                "block size-4 shrink-0 rounded-full border border-primary bg-background shadow-sm transition-[color,box-shadow] hover:ring-[0.1875rem] hover:ring-ring/50 focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50",
+                focusRing,
+              )}
+            />
+          </React.Fragment>
+        )
+      })}
     </SliderPrimitive.Root>
   )
 }

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

@@ -2,6 +2,7 @@ import * as React from 'react'
 import { Tooltip, TooltipContent, TooltipTrigger } from './tooltip.tsx'
 import { useOverflowing } from '../../lib/overflow.ts'
 import { cn } from '../../lib/cn.ts'
+import { focusRing } from './control.ts'
 
 export interface TruncateProps extends React.ComponentProps<'span'> {
   /** Conteúdo do tooltip quando transborda. Default: os próprios children. */
@@ -17,13 +18,21 @@ export interface TruncateProps extends React.ComponentProps<'span'> {
  * Requer `<TooltipProvider>` na raiz do app (o esqueleto do `opus create` já monta).
  * Com `fade`, a mesma medição decide quando esmaecer o fim da linha em vez de cortar
  * em reticências — sem transbordo, nada é aplicado.
+ * Com o texto cortado, o span entra na ordem de tabulação para que o teclado alcance a dica;
+ * sem corte, fica fora dela, porque não há nada escondido para revelar.
  */
 export function Truncate({ tooltip, fade = false, children, className, ...props }: TruncateProps): React.ReactElement {
   const { ref, overflowing } = useOverflowing<HTMLSpanElement>(children)
   const cut = fade ? (overflowing ? 'truncate-fade' : 'overflow-hidden whitespace-nowrap') : 'truncate'
 
   const span = (
-    <span ref={ref} data-slot="truncate" className={cn('block', cut, className)} {...props}>
+    <span
+      ref={ref}
+      data-slot="truncate"
+      tabIndex={overflowing ? 0 : undefined}
+      className={cn('block', cut, overflowing && ['rounded-sm outline-none', focusRing], className)}
+      {...props}
+    >
       {children}
     </span>
   )

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

@@ -1,7 +1,11 @@
 ## Um painel por vez
 
+Use `Accordion` para dividir um conteúdo longo em painéis que a pessoa expande sob demanda, cada um
+com seu título. Para um único bloco recolhível, use [`Collapsible`](/ui/collapsible).
+
 Use `type="single"` quando somente um painel deve permanecer aberto. Com `collapsible`, a pessoa
-também pode fechar o painel atual; sem essa propriedade, um item permanece expandido.
+também pode fechar o painel atual; sem essa propriedade, depois que um item é aberto, sempre haverá
+um item expandido.
 `defaultValue` define o item inicialmente aberto no modo não controlado.
 
 ```tsx preview
@@ -9,41 +13,43 @@ também pode fechar o painel atual; sem essa propriedade, um item permanece expa
   <AccordionItem value="overview">
     <AccordionTrigger>Visão geral</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">Resumo do workspace Empresa X.</p>
+      <p className="text-muted-foreground">Corolla XEi 2022, placa ABC-1D23.</p>
     </AccordionContent>
   </AccordionItem>
-  <AccordionItem value="agents">
-    <AccordionTrigger>Agentes</AccordionTrigger>
+  <AccordionItem value="services">
+    <AccordionTrigger>Serviços</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">developer, reviewer e designer ativos.</p>
+      <p className="text-muted-foreground">Troca de óleo, filtro de ar e alinhamento.</p>
     </AccordionContent>
   </AccordionItem>
-  <AccordionItem value="repos">
-    <AccordionTrigger>Repositórios</AccordionTrigger>
+  <AccordionItem value="parts">
+    <AccordionTrigger>Peças</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">empresa-x-api e empresa-x-web vinculados.</p>
+      <p className="text-muted-foreground">Filtro de óleo e pastilhas de freio.</p>
     </AccordionContent>
   </AccordionItem>
 </Accordion>
 ```
 
+O `AccordionTrigger` já traz o ícone que gira conforme o estado; não acrescente outro.
+
 ## Múltiplos abertos
 
 Use `type="multiple"` quando os painéis puderem permanecer abertos ao mesmo tempo. Nesse modo,
 `defaultValue` recebe um array com os itens inicialmente expandidos.
 
 ```tsx preview
-<Accordion type="multiple" defaultValue={['skills', 'prompt']} className="w-full">
-  <AccordionItem value="prompt">
-    <AccordionTrigger>Prompt</AccordionTrigger>
+<Accordion type="multiple" defaultValue={['notes', 'parts']} className="w-full">
+  <AccordionItem value="notes">
+    <AccordionTrigger>Observações</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">O prompt do agente developer.</p>
+      <p className="text-muted-foreground">O cliente relatou ruído ao frear.</p>
     </AccordionContent>
   </AccordionItem>
-  <AccordionItem value="skills">
-    <AccordionTrigger>Skills</AccordionTrigger>
+  <AccordionItem value="parts">
+    <AccordionTrigger>Peças</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">clean-code, code-style, ddd e test vinculadas.</p>
+      <p className="text-muted-foreground">Pastilhas de freio substituídas.</p>
     </AccordionContent>
   </AccordionItem>
 </Accordion>
@@ -55,38 +61,79 @@ Use `value` e `onValueChange` quando outro elemento ou estado do aplicativo tamb
 controlar o painel aberto.
 
 ```tsx preview
-const [open, setOpen] = React.useState('developer')
+const [open, setOpen] = React.useState('diagnosis')
 
 render(
   <Accordion type="single" collapsible value={open} onValueChange={setOpen} className="w-full">
-    <AccordionItem value="developer">
-      <AccordionTrigger>Agente developer</AccordionTrigger>
+    <AccordionItem value="diagnosis">
+      <AccordionTrigger>Diagnóstico</AccordionTrigger>
       <AccordionContent>
-        <p className="text-muted-foreground">Implementa a task no worktree da sessão.</p>
+        <p className="text-muted-foreground">Identifica a causa do ruído relatado pelo cliente.</p>
       </AccordionContent>
     </AccordionItem>
-    <AccordionItem value="reviewer">
-      <AccordionTrigger>Agente reviewer</AccordionTrigger>
+    <AccordionItem value="execution">
+      <AccordionTrigger>Execução</AccordionTrigger>
       <AccordionContent>
-        <p className="text-muted-foreground">Revisa o handoff e carimba o diff.</p>
+        <p className="text-muted-foreground">Substitui as peças aprovadas no orçamento.</p>
       </AccordionContent>
     </AccordionItem>
   </Accordion>,
 )
 ```
 
+## Item indisponível
+
+Use `disabled` no `AccordionItem` quando um painel existe, mas ainda não pode ser aberto. O gatilho
+fica esmaecido e não responde ao clique nem ao teclado.
+
+```tsx preview
+<Accordion type="single" collapsible className="w-full">
+  <AccordionItem value="quote">
+    <AccordionTrigger>Orçamento</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">Aprovado pelo cliente em 12 de maio.</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="invoice" disabled>
+    <AccordionTrigger>Nota fiscal</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">Emitida depois da entrega do veículo.</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
 ## Propriedades de Accordion
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `type` | `'single' \| 'multiple'` | | `single` abre um painel por vez; `multiple` permite manter vários abertos. |
+| `type` | `'single' \| 'multiple'` | | Obrigatório. `single` abre um painel por vez; `multiple` permite manter vários abertos. |
 | `collapsible` | `boolean` | `false` | No modo `single`, permite fechar o item aberto. |
-| `defaultValue` | `string \| string[]` | | Item ou itens inicialmente abertos no modo não controlado. |
-| `value` | `string \| string[]` | | Item ou itens abertos no modo controlado. Use com `onValueChange`. |
-| `onValueChange` | `(value) => void` | | Chamado quando a pessoa abre ou fecha um item. |
+| `defaultValue` | `string` em `single`; `string[]` em `multiple` | | Item ou itens inicialmente abertos no modo não controlado. |
+| `value` | `string` em `single`; `string[]` em `multiple` | | Item ou itens abertos no modo controlado. Use com `onValueChange`. |
+| `onValueChange` | `(value: string) => void` em `single`; `(value: string[]) => void` em `multiple` | | Chamado quando a pessoa abre ou fecha um item. Em `single`, recebe `''` quando o item aberto é fechado. |
+| `disabled` | `boolean` | `false` | Desabilita todos os itens. |
+| `className` | `string` | | Ajusta o contêiner. |
 
 ## Propriedades de AccordionItem
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `string` | | Identificador usado por `defaultValue` e `value` no `Accordion`. |
+| `value` | `string` | | Obrigatório. Identificador usado por `defaultValue` e `value` no `Accordion`. |
+| `disabled` | `boolean` | `false` | Impede abrir ou fechar este item. |
+| `className` | `string` | | Ajusta o item, que traz um divisor inferior exceto no último. |
+
+## Propriedades de AccordionTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Rótulo do painel. O ícone de estado é acrescentado depois dele. |
+| `className` | `string` | | Ajusta o botão do gatilho. |
+
+## Propriedades de AccordionContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Conteúdo do painel. |
+| `className` | `string` | | Ajusta o recuo interno do conteúdo, aplicado a um contêiner dentro da região animada. |
+| `forceMount` | `boolean` | `false` | Mantém o conteúdo montado mesmo fechado. |