@softize/opus 12.11.0 → 13.1.0

package/src/ui/components/patterns/shell-nav.tsx

@@ -14,9 +14,11 @@
 
 import type { ReactNode } from 'react'
 import { cn } from '../../lib/cn.ts'
+import { focusRing } from '../primitives/control.ts'
 import { useSidebarCollapsed } from './sidebar.tsx'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
 
+/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
 export interface ShellNavItem {
   /** Coordenada estável — volta em `onSelect` e casa com `activeId`. Único em toda a nav. */
   id: string
@@ -29,12 +31,14 @@ export interface ShellNavItem {
   disabled?: boolean
 }
 
+/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
 export interface ShellNavGroup {
   /** Cabeçalho do grupo. Ausente/vazio = itens soltos, sem rótulo. Some no recolhido. */
   label?: string
   items: ShellNavItem[]
 }
 
+/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
 export interface ShellNavProps {
   groups: ShellNavGroup[]
   /** `id` do item ativo. Ausente = nenhum destacado. */
@@ -74,7 +78,8 @@ function renderItem(item: ShellNavItem, activeId: string | undefined, onSelect:
       className={cn(
         'flex w-full items-center gap-2.5 rounded-md py-1.5 text-left text-sm transition-colors',
         'disabled:pointer-events-none disabled:opacity-40',
-        'outline-none focus-visible:ring-2 focus-visible:ring-ring/50',
+        'outline-none',
+        focusRing,
         railed ? 'justify-center px-0' : 'px-2.5',
         active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60',
       )}
@@ -106,6 +111,7 @@ function renderGroup(group: ShellNavGroup, gi: number, activeId: string | undefi
   )
 }
 
+/** @deprecated Use `SidebarNav`: mesma navegação, integrada à `Sidebar`. Mantido por compatibilidade. */
 export function ShellNav({ groups, activeId, onSelect, heading, footer, navLabel = 'Navegação', className }: ShellNavProps): React.ReactElement {
   const railed = useSidebarCollapsed()
 
@@ -127,6 +133,7 @@ export function ShellNav({ groups, activeId, onSelect, heading, footer, navLabel
   return railed ? <TooltipProvider delayDuration={200}>{body}</TooltipProvider> : body
 }
 
+/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
 export interface ShellNavHeadingProps {
   /** Título da seção. */
   title: ReactNode
@@ -135,8 +142,8 @@ export interface ShellNavHeadingProps {
   className?: string
 }
 
-/** Cabeçalho padrão do ShellNav: título + espaço pra um botão. É o gesto que hoje cada
- *  nav monta à mão (o "+" do Relatórios, o título de Configurações). */
+/** @deprecated Use `SidebarHeader` com `SidebarNav`. Cabeçalho do ShellNav: título + espaço
+ *  pra um botão. Mantido por compatibilidade. */
 export function ShellNavHeading({ title, action, className }: ShellNavHeadingProps): React.ReactElement {
   return (
     <div className={cn('flex h-12 shrink-0 items-center gap-1.5 border-b border-border px-4', className)}>

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

@@ -7,6 +7,7 @@ import {
 import { ChevronRight } from "lucide-react";
 import { useOverflowing } from "../../lib/overflow.ts";
 import { cn } from "../../lib/cn.ts";
+import { focusRing } from "../primitives/control.ts";
 import {
   Tooltip,
   TooltipContent,
@@ -177,17 +178,24 @@ export function SidebarItem({
       <button
         type="button"
         disabled={disabled}
+        aria-label={label}
         aria-current={active ? "page" : undefined}
         onClick={onClick}
         className={cn(
           "mx-auto grid size-9 place-items-center rounded-md transition-colors disabled:pointer-events-none disabled:opacity-40",
-          "outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
+          "outline-none",
+          focusRing,
           active
             ? "bg-muted font-medium text-foreground"
             : "text-foreground/80 hover:bg-muted/60",
         )}
       >
-        {icon}
+        <span
+          data-slot="sidebar-item-icon"
+          className="grid size-4 shrink-0 place-items-center [&_svg]:size-4"
+        >
+          {icon}
+        </span>
       </button>
     );
     // `className` vai no MESMO elemento nos dois modos — a linha —, senão a prop mudaria de alvo
@@ -235,8 +243,9 @@ export function SidebarItem({
           {/* Sem ícone, o chevron não se esconde: ele é o único ocupante do lugar. */}
           {icon !== undefined && (
             <span
+              data-slot="sidebar-item-icon"
               className={cn(
-                "absolute inset-0 flex items-center justify-center transition-opacity",
+                "absolute inset-0 flex items-center justify-center transition-opacity [&_svg]:size-4",
                 onToggle !== undefined &&
                   "group-hover/sidebar-item:opacity-0 group-has-[[data-slot=sidebar-item-toggle]:focus-visible]/sidebar-item:opacity-0",
               )}
@@ -252,7 +261,8 @@ export function SidebarItem({
               aria-label={expanded ? `Fechar ${label}` : `Abrir ${label}`}
               aria-expanded={expanded}
               className={cn(
-                "absolute inset-0 grid place-items-center rounded-sm text-muted-foreground transition-[color,opacity] outline-none hover:text-foreground focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-ring/50",
+                "absolute inset-0 grid place-items-center rounded-sm text-muted-foreground transition-[color,opacity] outline-none hover:text-foreground focus-visible:pointer-events-auto focus-visible:opacity-100",
+                focusRing,
                 icon === undefined
                   ? "pointer-events-auto opacity-100"
                   : "pointer-events-none opacity-0 group-hover/sidebar-item:pointer-events-auto group-hover/sidebar-item:opacity-100",
@@ -275,7 +285,8 @@ export function SidebarItem({
         onClick={onClick}
         className={cn(
           "flex min-w-0 flex-1 items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm disabled:pointer-events-none",
-          "outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
+          "outline-none",
+          focusRing,
           disabled
             ? "text-muted-foreground/50"
             : active
@@ -327,24 +338,15 @@ export function SidebarItem({
 
 export interface SidebarNavGroup {
   label?: string;
-  items?: SidebarNavItem[];
-  subgroups?: SidebarNavSubgroup[];
+  items: SidebarNavItem[];
 }
 
 export type SidebarNavItem = Omit<SidebarItemProps, "active" | "onClick"> & {
   id: string;
 };
 
-export interface SidebarNavSubgroup {
-  label?: string;
-  items: SidebarNavItem[];
-}
-
 const titled = (label?: string): boolean => (label ?? "").trim() !== "";
-const subFilled = (subgroup: SidebarNavSubgroup): boolean =>
-  subgroup.items.length > 0;
-const groupFilled = (group: SidebarNavGroup): boolean =>
-  (group.items?.length ?? 0) > 0 || (group.subgroups?.some(subFilled) ?? false);
+const groupFilled = (group: SidebarNavGroup): boolean => group.items.length > 0;
 
 /** Rótulo discreto de um grupo de navegação, compartilhado por listas e árvores. */
 export function SidebarGroupLabel({
@@ -358,7 +360,30 @@ export function SidebarGroupLabel({
     <div
       data-slot="sidebar-group-label"
       className={cn(
-        "px-2.5 pb-1 text-sm font-medium text-muted-foreground/70",
+        "px-2.5 py-1 text-sm font-medium text-muted-foreground/70",
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface SidebarTreeGroupProps {
+  className?: string;
+  children: ReactNode;
+}
+
+/** Agrupa descendentes de um nó e desenha a guia visual da hierarquia. */
+export function SidebarTreeGroup({
+  className,
+  children,
+}: SidebarTreeGroupProps): React.ReactElement {
+  return (
+    <div
+      data-slot="sidebar-tree-group"
+      className={cn(
+        "ml-[1.0625rem] space-y-0.5 border-l border-border pl-1.5",
         className,
       )}
     >
@@ -406,21 +431,7 @@ export function SidebarNav({
             {!collapsed && titled(group.label) && (
               <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
             )}
-            {group.items?.map((item) => renderItem(item))}
-            {group.subgroups?.map((subgroup, si) =>
-              !subFilled(subgroup) ? null : (
-                <div key={si} className="space-y-0.5">
-                  {!collapsed && titled(subgroup.label) && (
-                    <div className="pb-0.5 pl-4 pr-2.5 pt-1.5 text-[0.6875rem] font-medium text-muted-foreground/50">
-                      {subgroup.label}
-                    </div>
-                  )}
-                  {subgroup.items.map((item) =>
-                    renderItem(item, titled(subgroup.label)),
-                  )}
-                </div>
-              ),
-            )}
+            {group.items.map((item) => renderItem(item))}
           </div>
         ),
       )}

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

@@ -4,7 +4,7 @@
  * Use pra mutações sem form: assign, escalate, close, archive, excluir.
  * - Loading state automático (disabled + "..." enquanto roda).
  * - Toast em sucesso/erro; cache invalidation via action.invalidates.
- * - Confirmação opcional via <AlertDialog> (compacto, não fecha no clique fora) antes de disparar.
+ * - Confirmação opcional via <Dialog> (compacto, não fecha no clique fora) antes de disparar.
  * - `icon` faz o botão virar icon-only com tooltip: é a ação que mora NO item (linha,
  *   card). Absorveu o antigo DeleteButton, que era este componente com uma lixeira.
  * Emite `data-action="<action.name>"` na raiz (selector E2E).
@@ -16,16 +16,18 @@ import type { SimpleContract } from '../../../core/index.ts'
 import { useTriggerAction } from '../../drivers/react.tsx'
 import { toast } from '../primitives/sonner.tsx'
 import { cn } from '../../lib/cn.ts'
+import { humanizeActionError } from '../../lib/action-errors.ts'
 import { Button, type ButtonProps } from '../primitives/button.tsx'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../primitives/tooltip.tsx'
 import {
-  AlertDialog,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-} from '../primitives/alert-dialog.tsx'
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '../primitives/dialog.tsx'
 
 /** action.messages.* pode ser string ou I18nRef ({ key, default }). Resolve pra texto. */
 function msgText(m: unknown, fallback: string): string {
@@ -70,16 +72,6 @@ export interface ActionTriggerProps<TInput, TData> {
   className?: string
 }
 
-/**
- * Categorias de erro cuja frase do SERVIDOR vence o rótulo do contrato: "Este agente tem 3
- * conversas — desabilite em vez de excluir" é acionável; "Falha ao excluir" não. É
- * ALLOWLIST de propósito — erro inesperado carrega texto técnico cru (uma violação de FK
- * viraria `violates foreign key constraint "user_unit_id_fkey"` no toast de quem só clicou
- * no botão), então categoria desconhecida cai no rótulo genérico, o lado seguro de errar.
- * `authorization` fica de fora: o runtime lança `Forbidden`, pior que a frase em pt-BR.
- */
-const BUSINESS_ERRORS = ['conflict', 'validation', 'not_found']
-
 export function ActionTrigger<TInput, TData>({
   action,
   input,
@@ -102,9 +94,9 @@ export function ActionTrigger<TInput, TData>({
       setOpen(false)
     },
     onError: (err) => {
-      const detail = err.message.trim()
-      const speakable = BUSINESS_ERRORS.includes(err.category as string) && detail !== ''
-      toast.error(speakable ? detail : msgText(action.messages?.error, err.message))
+      // A frase de negócio do servidor vence o rótulo do contrato (ver lib/action-errors.ts);
+      // fora da allowlist, vale o rótulo — nunca o texto técnico cru.
+      toast.error(humanizeActionError(err, msgText(action.messages?.error, 'Não foi possível concluir.')))
     },
   })
 
@@ -123,12 +115,19 @@ export function ActionTrigger<TInput, TData>({
         }
       : undefined)
   const destructive = spec?.destructive === true
-  // Com ícone o botão é chrome do item: fica ghost, e o vermelho aparece no hover — uma
-  // lixeira sólida vermelha em cada linha seria um campo minado visual.
+  /**
+   * Precedência de aparência:
+   * - Gatilho: `context` explícito vence `destructive`; sem ele, destrutivo é `danger`. Com
+   *   ícone o botão é chrome do item: fica ghost e o vermelho aparece no hover — uma lixeira
+   *   sólida vermelha em cada linha seria um campo minado visual.
+   * - Confirmar: `destructive` vence `context` (a pergunta é o momento de avisar o risco) e o
+   *   botão é sempre `solid` — não herda o `variant` do gatilho, que descreve o item, não a
+   *   decisão.
+   */
   const triggerContext = context ?? (destructive ? 'danger' : icon !== undefined ? 'neutral' : 'primary')
   const triggerVariant = variant ?? (icon !== undefined ? 'ghost' : 'solid')
   const confirmContext = destructive ? 'danger' : (context ?? 'primary')
-  const confirmVariant = variant ?? 'solid'
+  const confirmVariant = 'solid'
 
   const fire = () => {
     void trigger(input)
@@ -174,28 +173,30 @@ export function ActionTrigger<TInput, TData>({
     <>
       {renderButton(() => setOpen(true))}
 
-      <AlertDialog open={open} onOpenChange={setOpen}>
-        <AlertDialogContent data-action={action.name}>
-          <AlertDialogHeader>
-            <AlertDialogTitle>{confirm.title}</AlertDialogTitle>
+      <Dialog mode="alert" open={open} onOpenChange={setOpen}>
+        <DialogContent data-action={action.name}>
+          <DialogHeader>
+            <DialogTitle>{confirm.title}</DialogTitle>
             {(itemLabel !== undefined || confirm.description !== undefined) && (
-              <AlertDialogDescription>
+              <DialogDescription>
                 {itemLabel !== undefined && <span className="font-medium text-foreground">“{itemLabel}”</span>}
                 {itemLabel !== undefined && confirm.description !== undefined ? ' — ' : ''}
                 {confirm.description}
-              </AlertDialogDescription>
+              </DialogDescription>
             )}
-          </AlertDialogHeader>
-          <AlertDialogFooter>
-            <Button context="neutral" variant="ghost" onClick={() => setOpen(false)} disabled={isLoading}>
-              {confirm.cancelLabel ?? 'Cancelar'}
-            </Button>
+          </DialogHeader>
+          <DialogFooter>
+            <DialogClose initialFocus asChild>
+              <Button context="neutral" variant="ghost" disabled={isLoading}>
+                {confirm.cancelLabel ?? 'Cancelar'}
+              </Button>
+            </DialogClose>
             <Button context={confirmContext} variant={confirmVariant} busy={isLoading} onClick={fire}>
               {confirm.actionLabel ?? buttonLabel}
             </Button>
-          </AlertDialogFooter>
-        </AlertDialogContent>
-      </AlertDialog>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </>
   )
 }

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

@@ -9,6 +9,7 @@
 import type { ReactNode } from 'react'
 import type { ViewAction } from '../../../core/index.ts'
 import { useViewAction } from '../../drivers/react.tsx'
+import { isBusinessError, isRetryable } from '../../lib/action-errors.ts'
 import { Alert } from '../primitives/alert.tsx'
 import { Skeleton } from '../primitives/skeleton.tsx'
 import { Button } from '../primitives/button.tsx'
@@ -22,10 +23,13 @@ export interface ActionViewProps<TInput, TData> {
   render?: (data: TData, refetch: () => Promise<void>) => ReactNode
   /** Renderiza estado vazio (200 mas sem dado). Default: nada. */
   empty?: ReactNode
-  /** Renderiza loading. Default: 3 skeletons stackados. */
-  loading?: ReactNode
-  /** Renderiza erro. Default: mensagem + botão "Tentar de novo". */
-  error?: (err: { code: string; message: string }, retry: () => Promise<void>) => ReactNode
+  /** Renderiza loading. Default (ou `true`): 3 skeletons empilhados; `false` não renderiza
+   *  nada enquanto carrega — o contêiner `data-action` permanece. */
+  loading?: ReactNode | boolean
+  /** Renderiza erro. Default: "Não foi possível carregar" + botão "Tentar de novo" (omitido em
+   *  falta de permissão ou sessão); a frase do servidor entra como descrição só quando está na
+   *  allowlist de lib/action-errors.ts. */
+  error?: (err: { code: string; message: string; category?: string }, retry: () => Promise<void>) => ReactNode
 }
 
 export function ActionView<TInput, TData>({
@@ -44,17 +48,16 @@ export function ActionView<TInput, TData>({
   }
 
   if (isLoading) {
-    return (
-      <div data-action={action.name}>
-        {loading ?? (
-          <div className="space-y-3">
-            <Skeleton className="h-6 w-1/3" />
-            <Skeleton className="h-4 w-2/3" />
-            <Skeleton className="h-4 w-1/2" />
-          </div>
-        )}
+    const defaultLoading = (
+      <div className="space-y-3">
+        <Skeleton className="h-6 w-1/3" />
+        <Skeleton className="h-4 w-2/3" />
+        <Skeleton className="h-4 w-1/2" />
       </div>
     )
+    const loadingNode =
+      typeof loading === 'boolean' ? (loading ? defaultLoading : null) : (loading ?? defaultLoading)
+    return <div data-action={action.name}>{loadingNode}</div>
   }
 
   if (isError && err !== undefined) {
@@ -63,10 +66,16 @@ export function ActionView<TInput, TData>({
     }
     return (
       <div data-action={action.name}>
-        <Alert context="danger" title={err.code} description={err.message}>
-          <Button variant="outline" size="sm" onClick={() => void refetch()}>
-            Tentar de novo
-          </Button>
+        <Alert
+          context="danger"
+          title="Não foi possível carregar"
+          description={isBusinessError(err) ? err.message.trim() : undefined}
+        >
+          {isRetryable(err) && (
+            <Button variant="outline" size="sm" onClick={() => void refetch()}>
+              Tentar de novo
+            </Button>
+          )}
         </Alert>
       </div>
     )

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

@@ -8,8 +8,13 @@ import {
 
 export type AlertContext = Exclude<UiContext, "primary">;
 export type AlertVariant = "subtle" | "outline";
+/**
+ * @deprecated Aliases de migração: `default` → `context="neutral"`, `destructive` →
+ * `context="danger"`; `success`, `warning` e `info` → o `context` homônimo (todos em
+ * `subtle`). Declare `context` + `variant`.
+ */
 export type LegacyAlertVariant =
-  "default" | "destructive" | "success" | "warning" | "info" | "danger";
+  "default" | "destructive" | "success" | "warning" | "info";
 
 interface AlertStyleOptions {
   context?: AlertContext | null;
@@ -47,13 +52,15 @@ function resolveAlertStyle({ context, variant }: AlertStyleOptions = {}): {
   context: AlertContext;
   variant: AlertVariant;
 } {
+  // `danger` não é alias: é um contexto que chegou pela prop errada. Segue como contexto.
+  if ((variant as string) === "danger")
+    return { context: "danger", variant: "subtle" };
   const legacy =
     variant === "default" ||
     variant === "destructive" ||
     variant === "success" ||
     variant === "warning" ||
-    variant === "info" ||
-    variant === "danger";
+    variant === "info";
   if (context != null && legacy) {
     throw new Error(
       "Alert não permite combinar context com uma variante semântica legada.",
@@ -65,8 +72,7 @@ function resolveAlertStyle({ context, variant }: AlertStyleOptions = {}): {
   if (
     variant === "success" ||
     variant === "warning" ||
-    variant === "info" ||
-    variant === "danger"
+    variant === "info"
   ) {
     return { context: variant, variant: "subtle" };
   }
@@ -76,7 +82,7 @@ function resolveAlertStyle({ context, variant }: AlertStyleOptions = {}): {
 export function alertVariants(options: AlertStyleOptions = {}): string {
   const resolved = resolveAlertStyle(options);
   return cn(
-    "relative grid w-full grid-cols-[0_minmax(0,1fr)] items-stretch gap-x-0 gap-y-1 rounded-lg border px-4 py-3 text-sm has-[>[data-slot=alert-media]]:grid-cols-[2.25rem_minmax(0,1fr)] has-[>[data-slot=alert-media]]:gap-x-3",
+    "relative grid w-full grid-cols-[0_minmax(0,1fr)_auto] items-stretch gap-x-0 gap-y-1 rounded-lg border p-4 text-sm has-[>[data-slot=alert-media]]:grid-cols-[3rem_minmax(0,1fr)_auto]",
     resolved.variant === "outline"
       ? semanticOutlineClasses[resolved.context]
       : semanticSubtleClasses[resolved.context],
@@ -92,7 +98,7 @@ function alertMediaClasses(context: AlertContext): string {
     danger: "text-context-danger-emphasis",
   };
   return cn(
-    "col-start-1 row-start-1 flex min-h-9 w-9 self-stretch items-center justify-center rounded-md bg-current/10 [&_svg]:size-5",
+    "col-start-1 row-start-1 flex size-9 self-start items-center justify-center rounded-md bg-current/10 [&_svg]:size-5",
     textClasses[context],
   );
 }
@@ -325,7 +331,7 @@ export function AlertActions({
     <div
       data-slot="alert-actions"
       className={cn(
-        "col-start-2 row-start-2 mt-1 flex items-center gap-2",
+        "col-start-3 row-start-1 ms-3 flex self-center items-center gap-2",
         className,
       )}
       {...props}

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

@@ -115,7 +115,7 @@ export function Ask({
                           type="button"
                           size="sm"
                           shape="pill"
-                          context={selected ? 'neutral' : 'primary'}
+                          context={selected ? 'primary' : 'neutral'}
                           variant={selected ? 'solid' : 'outline'}
                           role={question.multiSelect ? undefined : 'radio'}
                           aria-checked={question.multiSelect ? undefined : selected}
@@ -159,7 +159,7 @@ export function Ask({
                     disabled={locked}
                   />
                   {invalid && (
-                    <p id={errorId} className="text-sm text-destructive">
+                    <p id={errorId} className="text-sm text-context-danger-emphasis">
                       Escolha uma opção ou escreva uma resposta.
                     </p>
                   )}
@@ -169,7 +169,7 @@ export function Ask({
           </div>
         </TooltipProvider>
         {!validCount && (
-          <p role="alert" className="mt-3 text-sm text-destructive">
+          <p role="alert" className="mt-3 text-sm text-context-danger-emphasis">
             Ask aceita de 1 a 4 perguntas.
           </p>
         )}

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

@@ -3,6 +3,7 @@ import { Slot } from '@radix-ui/react-slot'
 
 import type { UiContext } from '../../../core/ui-context.ts'
 import { cn } from '../../lib/cn.ts'
+import { focusRing } from './control.ts'
 import {
   semanticOutlineClasses,
   semanticSolidClasses,
@@ -11,6 +12,11 @@ import {
 
 export type BadgeContext = UiContext
 export type BadgeVariant = 'solid' | 'subtle' | 'outline'
+/**
+ * @deprecated Aliases de migração: `default` → `context="primary"` solid, `secondary` →
+ * `context="neutral"` solid, `destructive` → `context="danger"` solid; `success`, `warning` e
+ * `info` → o `context` homônimo em `subtle`. Declare `context` + `variant`.
+ */
 export type LegacyBadgeVariant =
   | 'default'
   | 'secondary'
@@ -18,7 +24,6 @@ export type LegacyBadgeVariant =
   | 'success'
   | 'warning'
   | 'info'
-  | 'danger'
 
 export interface BadgeStyleOptions {
   context?: BadgeContext | null
@@ -26,20 +31,21 @@ export interface BadgeStyleOptions {
 }
 
 const baseClasses =
-  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 [&>svg]:pointer-events-none [&>svg]:size-3'
+  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 [&>svg]:pointer-events-none [&>svg]:size-3'
 
 export function resolveBadgeStyle({
   context,
   variant,
 }: BadgeStyleOptions = {}): { context: BadgeContext; variant: BadgeVariant } {
+  // `danger` não é alias: é um contexto que chegou pela prop errada. Segue como contexto.
+  if ((variant as string) === 'danger') return { context: 'danger', variant: 'subtle' }
   const legacy =
     variant === 'default' ||
     variant === 'secondary' ||
     variant === 'destructive' ||
     variant === 'success' ||
     variant === 'warning' ||
-    variant === 'info' ||
-    variant === 'danger'
+    variant === 'info'
   if (context != null && legacy) {
     throw new Error('Badge não permite combinar context com uma variante semântica legada.')
   }
@@ -53,7 +59,6 @@ export function resolveBadgeStyle({
     case 'success':
     case 'warning':
     case 'info':
-    case 'danger':
       return { context: variant, variant: 'subtle' }
     default:
       return {
@@ -72,7 +77,7 @@ export function badgeVariants(options: BadgeStyleOptions = {}): string {
       : resolved.variant === 'outline'
         ? semanticOutlineClasses[resolved.context]
         : semanticSubtleClasses[resolved.context]
-  return cn(baseClasses, classes)
+  return cn(baseClasses, focusRing, classes)
 }
 
 export interface BadgeProps extends React.ComponentProps<'span'>, BadgeStyleOptions {

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

@@ -5,7 +5,7 @@ import { Slot } from "radix-ui"
 import { cn } from '../../lib/cn.ts'
 
 function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
-  return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />
+  return <nav aria-label="Navegação estrutural" data-slot="breadcrumb" {...props} />
 }
 
 function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
@@ -93,7 +93,7 @@ function BreadcrumbEllipsis({
       {...props}
     >
       <MoreHorizontal className="size-4" />
-      <span className="sr-only">More</span>
+      <span className="sr-only">Mais</span>
     </span>
   )
 }

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

@@ -3,23 +3,30 @@ import { Slot } from '@radix-ui/react-slot'
 
 import type { UiContext } from '../../../core/ui-context.ts'
 import { cn } from '../../lib/cn.ts'
-import type { ControlShape } from './control.ts'
+import { focusRing, type ControlShape } from './control.ts'
 import { Spinner } from './spinner.tsx'
 
 export type ButtonContext = Extract<UiContext, 'neutral' | 'primary' | 'danger'>
 export type ButtonVariant = 'solid' | 'subtle' | 'outline' | 'ghost' | 'link'
+/**
+ * @deprecated Aliases de migração: `default` → `context="primary"`, `secondary` →
+ * `context="neutral"`, `destructive` → `context="danger"` (todos com `variant="solid"`).
+ * Declare `context` + `variant`.
+ */
 export type LegacyButtonVariant = 'default' | 'secondary' | 'destructive'
 export type ButtonSize = 'default' | 'sm' | 'lg' | 'icon' | 'icon-sm' | 'icon-xs'
 
 export interface ButtonStyleOptions {
+  /** Sem `context`, `solid`/`subtle` assumem `primary`; `outline`/`ghost`/`link` assumem `neutral`. */
   context?: ButtonContext | null
+  /** Tratamento visual. Os valores de `LegacyButtonVariant` são aliases em retirada. */
   variant?: ButtonVariant | LegacyButtonVariant | null
   size?: ButtonSize | null
   shape?: ControlShape | null
 }
 
 const baseClasses =
-  'inline-flex shrink-0 items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium outline-none transition-all focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 active:brightness-90 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4'
+  'inline-flex shrink-0 items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium outline-none transition-all disabled:pointer-events-none disabled:opacity-50 active:brightness-90 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4'
 
 const sizeClasses: Record<ButtonSize, string> = {
   default: 'h-9 px-4 py-2 has-[>svg]:px-3',
@@ -71,7 +78,12 @@ export function resolveButtonStyle({ context, variant }: ButtonStyleOptions = {}
   if (variant === 'default') return { context: 'primary', variant: 'solid' }
   if (variant === 'secondary') return { context: 'neutral', variant: 'solid' }
   if (variant === 'destructive') return { context: 'danger', variant: 'solid' }
-  return { context: context ?? 'primary', variant: variant ?? 'solid' }
+  const resolvedVariant: ButtonVariant = variant ?? 'solid'
+  // Tratamentos de superfície (solid/subtle) pedem destaque; os leves (outline/ghost/link)
+  // são o chrome discreto da casa e só ganham cor quando o contexto é declarado.
+  const defaultContext: ButtonContext =
+    resolvedVariant === 'solid' || resolvedVariant === 'subtle' ? 'primary' : 'neutral'
+  return { context: context ?? defaultContext, variant: resolvedVariant }
 }
 
 /**
@@ -92,6 +104,7 @@ export function buttonVariants(options: ButtonStyleOptions = {}): string {
             : linkClasses[resolved.context]
   return cn(
     baseClasses,
+    focusRing,
     variantClasses,
     sizeClasses[options.size ?? 'default'],
     options.shape === 'pill' && 'rounded-full',