@softize/opus 13.0.0 → 13.1.0

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

@@ -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'
@@ -111,8 +112,9 @@ function inferFieldKind(schema: ZodTypeAny): FieldKind {
 interface FieldSpec {
   label?: string
   placeholder?: string
+  /** @deprecated Use `help` (ajuda junto à label) ou `description` do campo composto. */
   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 +128,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
 }
 
@@ -208,7 +210,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>
@@ -530,7 +532,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}
@@ -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
 

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

@@ -754,7 +754,7 @@ function PeriodControl({
               <Button
                 key={p.value}
                 size="sm"
-                context={period === p.value ? "neutral" : "primary"}
+                context={period === p.value ? "primary" : "neutral"}
                 variant={period === p.value ? "solid" : "ghost"}
                 className="justify-start"
                 onClick={() => {
@@ -1428,6 +1428,7 @@ export function ActionList<TInput, TItem>({
                   <PopoverTrigger asChild>
                     <Button
                       variant="outline"
+                      size="icon"
                       className="shrink-0"
                       aria-label="Exibição"
                     >
@@ -1790,9 +1791,8 @@ export function ActionList<TInput, TItem>({
                 <DialogClose asChild>
                   <Button
                     size="sm"
-                    variant={
-                      confirming.destructive === true ? "destructive" : "default"
-                    }
+                    context={confirming.destructive === true ? "danger" : "primary"}
+                    variant="solid"
                     onClick={() => {
                       const a = confirming;
                       setConfirming(null);

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

@@ -14,10 +14,26 @@ import {
   type ReactElement,
   type ReactNode,
 } from "react";
+import { createPortal } from "react-dom";
 import { cn } from "../../lib/cn.ts";
 
 const PageContext = createContext(false);
 const PageHeaderContext = createContext(false);
+const PageActionsTargetContext = createContext<HTMLElement | null>(null);
+
+export function PageActionsTarget({
+  target,
+  children,
+}: {
+  target: HTMLElement | null;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <PageActionsTargetContext.Provider value={target}>
+      {children}
+    </PageActionsTargetContext.Provider>
+  );
+}
 
 function requireParent(
   inside: boolean,
@@ -221,7 +237,8 @@ export function PageActions({
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
   requireParent(useContext(PageHeaderContext), "PageActions", "PageHeader");
-  return (
+  const target = useContext(PageActionsTargetContext);
+  const actions = (
     <div
       data-slot="page-actions"
       className={cn(
@@ -231,6 +248,7 @@ export function PageActions({
       {...props}
     />
   );
+  return target === null ? actions : createPortal(actions, target);
 }
 
 export function PageBody({

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
@@ -349,7 +360,7 @@ 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,
       )}
     >

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

@@ -16,6 +16,7 @@ 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 {
@@ -71,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,
@@ -103,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.')))
     },
   })
 
@@ -124,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)

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" };
   }

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',