@softize/opus 13.1.0 → 15.0.0

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

@@ -3,38 +3,44 @@ import { Slot } from '@radix-ui/react-slot'
 
 import type { UiContext } from '../../../core/ui-context.ts'
 import { cn } from '../../lib/cn.ts'
-import { focusRing, type ControlShape } from './control.ts'
+import {
+  controlBase,
+  controlGlyphClass,
+  controlHeight,
+  controlSquare,
+  focusRing,
+  type ControlScale,
+  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'
+/** A escala completa de control.ts: alturas de linha e quadrados só-ícone. */
+export type ButtonSize = ControlScale
 
 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
+  /** Tratamento visual. */
+  variant?: ButtonVariant | 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 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'
 
+/** Padding e ritmo por tamanho; altura e quadrado vêm da escala compartilhada. */
 const sizeClasses: Record<ButtonSize, string> = {
-  default: 'h-9 px-4 py-2 has-[>svg]:px-3',
-  sm: 'h-8 gap-1.5 px-3 has-[>svg]:px-2.5',
-  lg: 'h-10 px-6 has-[>svg]:px-4',
-  icon: 'size-9',
-  'icon-sm': 'size-8',
-  'icon-xs': 'size-6',
+  xs: `${controlHeight.xs} gap-1 px-2 text-xs has-[>svg]:px-1.5`,
+  sm: `${controlHeight.sm} gap-1.5 px-3 has-[>svg]:px-2.5`,
+  default: `${controlHeight.default} px-4 py-2 has-[>svg]:px-3`,
+  lg: `${controlHeight.lg} px-6 has-[>svg]:px-4`,
+  'icon-xs': controlSquare['icon-xs'],
+  'icon-sm': controlSquare['icon-sm'],
+  icon: controlSquare.icon,
+  'icon-lg': controlSquare['icon-lg'],
 }
 
 const solidClasses: Record<ButtonContext, string> = {
@@ -71,13 +77,6 @@ export function resolveButtonStyle({ context, variant }: ButtonStyleOptions = {}
   context: ButtonContext
   variant: ButtonVariant
 } {
-  const legacy = variant === 'default' || variant === 'secondary' || variant === 'destructive'
-  if (context != null && legacy) {
-    throw new Error('Button não permite combinar context com uma variante semântica legada.')
-  }
-  if (variant === 'default') return { context: 'primary', variant: 'solid' }
-  if (variant === 'secondary') return { context: 'neutral', variant: 'solid' }
-  if (variant === 'destructive') return { context: 'danger', 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.
@@ -87,8 +86,8 @@ export function resolveButtonStyle({ context, variant }: ButtonStyleOptions = {}
 }
 
 /**
- * Classes do Button. `context` seleciona a família semântica e `variant` seleciona
- * o tratamento visual. `default`, `secondary` e `destructive` são aliases temporários.
+ * Classes do Button. `context` seleciona a família semântica, `variant` o tratamento visual e
+ * `size` a medida na escala compartilhada de control.ts.
  */
 export function buttonVariants(options: ButtonStyleOptions = {}): string {
   const resolved = resolveButtonStyle(options)
@@ -107,6 +106,7 @@ export function buttonVariants(options: ButtonStyleOptions = {}): string {
     focusRing,
     variantClasses,
     sizeClasses[options.size ?? 'default'],
+    controlGlyphClass(options.size),
     options.shape === 'pill' && 'rounded-full',
   )
 }
@@ -116,8 +116,9 @@ export interface ButtonProps extends React.ComponentProps<'button'>, ButtonStyle
   asChild?: boolean
   /** Estado de ação em andamento; mostra Spinner e desabilita o controle. */
   busy?: boolean
-  /** Ícone à esquerda. No `busy`, o Spinner ocupa o mesmo espaço. */
-  icon?: React.ElementType
+  /** Ícone à esquerda, como nó (`icon={<Plus />}`); o tamanho do glifo vem do `size`. No
+   *  `busy`, o Spinner ocupa o mesmo espaço. */
+  icon?: React.ReactNode
 }
 
 export function Button({
@@ -128,14 +129,13 @@ export function Button({
   shape,
   asChild = false,
   busy = false,
-  icon: Icon,
+  icon,
   disabled,
   children,
   ...props
 }: ButtonProps): React.ReactElement {
   const Comp = asChild ? Slot : 'button'
   const resolved = resolveButtonStyle({ context, variant })
-  const iconSize = size === 'sm' ? 'size-3' : 'size-4'
   return (
     <Comp
       data-slot="button"
@@ -149,11 +149,7 @@ export function Button({
         children
       ) : (
         <>
-          {busy ? (
-            <Spinner size={size === 'sm' ? 'sm' : 'default'} />
-          ) : Icon ? (
-            <Icon className={iconSize} />
-          ) : null}
+          {busy ? <Spinner size={controlBase(size)} /> : icon}
           {children}
         </>
       )}

package/src/ui/components/primitives/control.ts

@@ -1,6 +1,75 @@
 /** Geometria compartilhada pelos controles inline da casa. */
 export type ControlShape = 'default' | 'pill'
 
+/**
+ * A escala única de `size` dos controles (14.0.0). Um nome, uma medida — em qualquer
+ * componente que aceite `size`, `sm` é a mesma altura de linha e `icon-sm` é o mesmo quadrado.
+ * Cada componente aceita o subconjunto coerente com seu papel, nunca um nome com outra medida.
+ *
+ * - Altura de linha (`xs` · `sm` · `default` · `lg`): 1.5 · 2 · 2.25 · 2.5rem.
+ * - Quadrado só-ícone (`icon-xs` · `icon-sm` · `icon` · `icon-lg`): 1.5 · 1.75 · 2.25 · 2.5rem.
+ *   `icon-xs` é o degrau da ação que mora dentro de uma linha densa. `icon-sm` atende
+ *   composições compactas que ainda precisam de mais presença.
+ * - Glifo (o svg dentro do controle daquele tamanho): 0.875 · 0.875 · 1 · 1.25rem. O Spinner
+ *   usa esta medida, por isso `busy` substitui o ícone sem mexer na largura do botão.
+ */
+export type ControlSize = 'xs' | 'sm' | 'default' | 'lg'
+export type ControlIconSize = 'icon-xs' | 'icon-sm' | 'icon' | 'icon-lg'
+export type ControlScale = ControlSize | ControlIconSize
+
+export const controlHeight: Record<ControlSize, string> = {
+  xs: 'h-6',
+  sm: 'h-8',
+  default: 'h-9',
+  lg: 'h-10',
+}
+
+export const controlSquare: Record<ControlIconSize, string> = {
+  'icon-xs': 'size-6',
+  'icon-sm': 'size-7',
+  icon: 'size-9',
+  'icon-lg': 'size-10',
+}
+
+export const controlGlyph: Record<ControlSize, string> = {
+  xs: 'size-3.5',
+  sm: 'size-3.5',
+  default: 'size-4',
+  lg: 'size-5',
+}
+
+// As classes completas precisam permanecer literais para o scanner do Tailwind gerar os seletores.
+// Montar `]:${controlGlyph[...]}` em runtime devolve o nome certo no DOM, mas deixa o CSS ausente.
+const controlGlyphSelector: Record<ControlSize, string> = {
+  xs: '[&_svg:not([class*=size-])]:size-3.5',
+  sm: '[&_svg:not([class*=size-])]:size-3.5',
+  default: '[&_svg:not([class*=size-])]:size-4',
+  lg: '[&_svg:not([class*=size-])]:size-5',
+}
+
+/** A altura de linha por trás de um tamanho da escala (`icon-sm` → `sm`). */
+export function controlBase(size: ControlScale | null | undefined): ControlSize {
+  switch (size) {
+    case 'icon-xs':
+      return 'xs'
+    case 'icon-sm':
+      return 'sm'
+    case 'icon-lg':
+      return 'lg'
+    case 'icon':
+    case null:
+    case undefined:
+      return 'default'
+    default:
+      return size
+  }
+}
+
+/** Fallback de tamanho do svg descendente, respeitando um `size-*` explícito no próprio ícone. */
+export function controlGlyphClass(size: ControlScale | null | undefined): string {
+  return controlGlyphSelector[controlBase(size)]
+}
+
 /**
  * Anel de foco da casa: fino (0.1875rem), translúcido e encostado na borda — sem offset.
  * Todo controle focável usa esta constante; espessuras próprias (`ring-2`, `ring-4`) ou

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

@@ -5,22 +5,9 @@ import { cn } from '../../lib/cn.ts'
 
 export type DotContext = UiContext
 export type DotVariant = 'solid' | 'outline'
-/**
- * @deprecated Aliases de migração: `default` → `context="primary"`, `secondary` →
- * `context="neutral"`, `destructive` → `context="danger"`; `success`, `warning` e `info` → o
- * `context` homônimo. Declare `context` + `variant`.
- */
-export type LegacyDotVariant =
-  | 'default'
-  | 'secondary'
-  | 'destructive'
-  | 'success'
-  | 'warning'
-  | 'info'
-
 interface DotStyleOptions {
   context?: DotContext | null
-  variant?: DotVariant | LegacyDotVariant | null
+  variant?: DotVariant | null
 }
 
 const solidClasses: Record<DotContext, string> = {
@@ -45,22 +32,6 @@ export function resolveDotStyle({ context, variant }: DotStyleOptions = {}): {
   context: DotContext
   variant: DotVariant
 } {
-  const legacy =
-    variant === 'default' ||
-    variant === 'secondary' ||
-    variant === 'destructive' ||
-    variant === 'success' ||
-    variant === 'warning' ||
-    variant === 'info'
-  if (context != null && legacy) {
-    throw new Error('Dot não permite combinar context com uma variante semântica legada.')
-  }
-  if (variant === 'default') return { context: 'primary', variant: 'solid' }
-  if (variant === 'secondary') return { context: 'neutral', variant: 'solid' }
-  if (variant === 'destructive') return { context: 'danger', variant: 'solid' }
-  if (variant === 'success' || variant === 'warning' || variant === 'info') {
-    return { context: variant, variant: 'solid' }
-  }
   return { context: context ?? 'neutral', variant: variant ?? 'solid' }
 }
 

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

@@ -3,7 +3,7 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from '../../lib/cn.ts'
 import type { ControlShape } from './control.ts'
-import { Button } from './button.tsx'
+import { Button, type ButtonProps } from './button.tsx'
 import { Input } from './input.tsx'
 import { Textarea } from './textarea.tsx'
 
@@ -79,16 +79,16 @@ function InputGroupAddon({
   )
 }
 
+/** Só o acabamento por tamanho: altura, quadrado e glifo vêm da escala de control.ts via Button. */
 const inputGroupButtonVariants = cva(
   "flex items-center gap-2 text-sm shadow-none",
   {
     variants: {
       size: {
-        xs: "h-6 gap-1 rounded-[calc(var(--radius)-0.3125rem)] px-2 has-[>svg]:px-2 [&>svg:not([class*='size-'])]:size-3.5",
-        sm: "h-8 gap-1.5 rounded-md px-2.5 has-[>svg]:px-2.5",
-        "icon-xs":
-          "size-6 rounded-[calc(var(--radius)-0.3125rem)] p-0 has-[>svg]:p-0",
-        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+        xs: "rounded-[calc(var(--radius)-0.3125rem)] has-[>svg]:px-2",
+        sm: "rounded-md",
+        "icon-xs": "rounded-[calc(var(--radius)-0.3125rem)] p-0 has-[>svg]:p-0",
+        "icon-sm": "p-0 has-[>svg]:p-0",
       },
     },
     defaultVariants: {
@@ -97,19 +97,22 @@ const inputGroupButtonVariants = cva(
   }
 )
 
+/** Subconjunto da escala que cabe dentro de um campo: `xs`, `sm`, `icon-xs` e `icon-sm`. */
+type InputGroupButtonSize = Extract<NonNullable<ButtonProps['size']>, 'xs' | 'sm' | 'icon-xs' | 'icon-sm'>
+
 function InputGroupButton({
   className,
   type = "button",
   variant = "ghost",
   size = "xs",
   ...props
-}: Omit<React.ComponentProps<typeof Button>, "size"> &
-  VariantProps<typeof inputGroupButtonVariants>) {
+}: Omit<ButtonProps, 'size'> & { size?: InputGroupButtonSize }) {
   return (
     <Button
       type={type}
       data-size={size}
       variant={variant}
+      size={size}
       className={cn(inputGroupButtonVariants({ size }), className)}
       {...props}
     />

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

@@ -3,6 +3,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 
 import { cn } from "../../lib/cn.ts";
+import type { ControlSize } from "./control.ts";
 import { Separator } from "./separator.tsx";
 
 const itemGroupVariants = cva(
@@ -72,10 +73,11 @@ const itemVariants = cva(
         outline: "border-border",
         muted: "bg-muted/50",
       },
+      // Nomes da escala de control.ts; a linha não tem altura fixa, `sm` aperta o respiro.
       size: {
         default: "gap-4 p-4",
         sm: "gap-2.5 px-4 py-3",
-      },
+      } satisfies Partial<Record<ControlSize, string>>,
     },
     defaultVariants: { variant: "default", size: "default" },
   },

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

@@ -67,18 +67,12 @@ function MenuItem({
   className,
   inset,
   context,
-  variant,
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Item> & {
   inset?: boolean
   context?: Extract<UiContext, 'neutral' | 'danger'>
-  /** @deprecated Use `context="danger"`. */
-  variant?: "default" | "destructive"
 }) {
-  if (context !== undefined && variant !== undefined) {
-    throw new Error('MenuItem não permite combinar context com uma variante semântica legada.')
-  }
-  const resolvedContext = context ?? (variant === 'destructive' ? 'danger' : 'neutral')
+  const resolvedContext = context ?? 'neutral'
   return (
     <MenuPrimitive.Item
       data-slot="menu-item"

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

@@ -3,6 +3,7 @@ import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from 'lucide-re
 
 import { cn } from '../../lib/cn.ts'
 import { buttonVariants, type ButtonProps } from './button.tsx'
+import { controlSquare, type ControlIconSize } from './control.ts'
 
 function Pagination({ className, ...props }: React.ComponentProps<'nav'>) {
   return (
@@ -33,8 +34,8 @@ function PaginationItem({ ...props }: React.ComponentProps<'li'>) {
 export interface PaginationLinkProps extends Omit<React.ComponentProps<'a'>, 'children'> {
   /** Página atual: vira `outline` e ganha `aria-current="page"`. */
   isActive?: boolean
-  /** Escala do Button. `default` (números: altura fixa, largura mínima quadrada que cresce
-   *  com os dígitos) ou uma escala `icon*` (setas quadradas, sem padding horizontal). */
+  /** A escala de control.ts, via Button. `default` (números: altura fixa, largura mínima
+   *  quadrada que cresce com os dígitos) ou um `icon*` (setas quadradas, sem padding). */
   size?: ButtonProps['size']
   /** Número da página: dá o nome acessível (“Página N”) e o conteúdo, quando `children` falta. */
   page?: number
@@ -83,10 +84,11 @@ function PaginationLink({ className, isActive, page, disabled, href, size = 'def
 export interface PaginationControlProps extends Omit<PaginationLinkProps, 'page' | 'isActive'> {
   /** Nome acessível e texto visível. Default: “Página anterior” / “Próxima página”. */
   label?: string
-  /** Só a seta, quadrada (escala `icon`, `size-9`); o `label` continua como nome acessível. */
+  /** Só a seta, quadrada (`icon`, 2.25rem; `size="icon-sm"` para o rodapé denso); o `label`
+   *  continua como nome acessível. */
   iconOnly?: boolean
-  /** Classe do ícone (ex.: `size-3.5` na escala densa). Vai no próprio svg, porque o
-   *  fallback `[&_svg:not([class*='size-'])]:size-4` do Button vence qualquer seletor de fora. */
+  /** Classe do ícone, quando o glifo da escala não servir. Vai no próprio svg, porque o
+   *  fallback `[&_svg:not([class*=size-])]` do Button vence qualquer seletor de fora. */
   iconClassName?: string
 }
 
@@ -132,16 +134,22 @@ function PaginationNext({
   )
 }
 
+export interface PaginationEllipsisProps extends React.ComponentProps<'span'> {
+  /** O quadrado da escala de control.ts — o mesmo das setas ao lado. */
+  size?: ControlIconSize
+}
+
 /** Decorativa: `aria-hidden`; os números ao redor já dizem que há páginas no vão. */
-function PaginationEllipsis({ className, ...props }: React.ComponentProps<'span'>) {
+function PaginationEllipsis({ className, size = 'icon', ...props }: PaginationEllipsisProps) {
   return (
     <span
       aria-hidden
       data-slot="pagination-ellipsis"
-      className={cn('flex size-9 items-center justify-center', className)}
+      data-size={size}
+      className={cn('flex items-center justify-center', controlSquare[size], className)}
       {...props}
     >
-      <MoreHorizontalIcon className="size-4" />
+      <MoreHorizontalIcon className={size === 'icon-xs' || size === 'icon-sm' ? 'size-3.5' : 'size-4'} />
     </span>
   )
 }

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

@@ -25,7 +25,7 @@ import { Check, ChevronDownIcon, SearchIcon, X } from 'lucide-react'
 import { Command as CommandPrimitive } from 'cmdk'
 
 import { cn } from '../../lib/cn.ts'
-import { focusRing, focusRingWithin, type ControlShape } from './control.ts'
+import { focusRing, focusRingWithin, type ControlShape, type ControlSize } from './control.ts'
 import { CommandEmpty, CommandGroup, CommandItem, CommandList } from './command.tsx'
 import { Popover, PopoverAnchor, PopoverContent } from './popover.tsx'
 
@@ -60,7 +60,7 @@ interface SelectBaseProps {
   'aria-invalid'?: boolean
   'aria-describedby'?: string
   /** Altura: `default` (h-9, a do Input/Button) ou `sm` (h-8) pra toolbar densa. */
-  size?: 'sm' | 'default'
+  size?: Extract<ControlSize, 'sm' | 'default'>
   /** Geometria do controle; `pill` preserva a variante visual escolhida. */
   shape?: ControlShape
   'aria-label'?: string

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

@@ -1,28 +1,25 @@
 import * as React from 'react'
 import { Loader2Icon } from 'lucide-react'
-import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '../../lib/cn.ts'
+import { controlGlyph, type ControlSize } from './control.ts'
 
-/** Tamanhos do spinner — divergência da casa (o shadcn atual só tem `size-4` fixo).
- *  Mantido aditivo pra cobrir botão (sm) e estados maiores (lg). */
-const spinnerVariants = cva('animate-spin', {
-  variants: {
-    size: { sm: 'size-3', default: 'size-4', lg: 'size-6' },
-  },
-  defaultVariants: { size: 'default' },
-})
-
-export interface SpinnerProps extends React.ComponentProps<'svg'>, VariantProps<typeof spinnerVariants> {}
+export interface SpinnerProps extends React.ComponentProps<'svg'> {
+  /** O glifo do controle daquele tamanho na escala de control.ts (`sm` cabe num Button sm). */
+  size?: ControlSize | null
+}
 
-/** Indicador de carregamento (Loader2Icon girando) — substitui o `<Loader2Icon className="animate-spin"/>`
- *  inline repetido. Tamanhos sm/default/lg. Pra placeholder de conteúdo, use Skeleton. */
+/**
+ * Indicador de carregamento (Loader2Icon girando) — substitui o `<Loader2Icon
+ * className="animate-spin"/>` inline repetido. É decorativo: quem nomeia a espera é o contêiner
+ * (`role="status"` em DataState, PageState ou no seu) ou o texto ao lado; assim a superfície
+ * carrega um status só, sem role duplicado. Pra placeholder de conteúdo, use Skeleton.
+ */
 export function Spinner({ className, size, ...props }: SpinnerProps): React.ReactElement {
   return (
     <Loader2Icon
       data-slot="spinner"
-      role="status"
-      aria-label="Carregando"
-      className={cn(spinnerVariants({ size }), className)}
+      aria-hidden="true"
+      className={cn('animate-spin', controlGlyph[size ?? 'default'], className)}
       {...props}
     />
   )

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

@@ -2,13 +2,16 @@ import * as React from "react"
 import { Switch as SwitchPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import type { ControlSize } from './control.ts'
 
+/** `size` usa os nomes da escala de control.ts; a chave é um trilho (não uma linha), então a
+ *  medida é a do glifo daquele tamanho: `sm` acompanha o svg de um controle sm (0.875rem). */
 function Switch({
   className,
   size = "default",
   ...props
 }: React.ComponentProps<typeof SwitchPrimitive.Root> & {
-  size?: "sm" | "default"
+  size?: Extract<ControlSize, "sm" | "default">
 }) {
   return (
     <SwitchPrimitive.Root

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

@@ -3,11 +3,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { Tabs as TabsPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { controlHeight, type ControlSize } from './control.ts'
 
 // Divergência da casa (ejetado): o Tabs ganhou `size` — Button e Select têm `sm`, o Tabs
 // não tinha, e uma fileira densa ficava com o segmento 0.25rem mais alto
-// que os irmãos. O tamanho flui pra TabsList via contexto (a altura é dela).
-type TabsSize = "default" | "sm"
+// que os irmãos. O tamanho flui pra TabsList via contexto (a altura é dela) e a medida é a
+// da escala de control.ts.
+type TabsSize = Extract<ControlSize, "default" | "sm">
 const TabsSizeContext = React.createContext<TabsSize>("default")
 
 function Tabs({
@@ -64,7 +66,7 @@ function TabsList({
       data-slot="tabs-list"
       data-variant={variant}
       data-size={size}
-      className={cn(tabsListVariants({ variant }), size === "sm" ? "h-8" : "h-9", className)}
+      className={cn(tabsListVariants({ variant }), controlHeight[size], className)}
       {...props}
     />
   )

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

@@ -3,9 +3,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { Toggle as TogglePrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { controlHeight, focusRing } from './control.ts'
 
 const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground dark:aria-invalid:ring-context-danger/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  [
+    "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground dark:aria-invalid:ring-context-danger/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+    focusRing,
+  ],
   {
     variants: {
       variant: {
@@ -13,10 +17,11 @@ const toggleVariants = cva(
         outline:
           "border border-input bg-transparent hover:bg-accent hover:text-accent-foreground",
       },
+      // Alturas da escala de control.ts (`sm` = o mesmo h-8 de Button e Select).
       size: {
-        default: "h-9 min-w-9 px-2",
-        sm: "h-8 min-w-8 px-1.5",
-        lg: "h-10 min-w-10 px-2.5",
+        default: `${controlHeight.default} min-w-9 px-2`,
+        sm: `${controlHeight.sm} min-w-8 px-1.5`,
+        lg: `${controlHeight.lg} min-w-10 px-2.5`,
       },
       shape: {
         default: '',

package/src/ui/docs/content/action-form.md

@@ -88,6 +88,32 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | `options` | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum. |
 | `className` | `string` | Classes do invólucro (ex.: `col-span-2` em uma grid). |
 
+## Ajuda na label
+
+`FieldSpec.help` aparece como um ícone junto à label, com o texto num tooltip. Escreva ali o
+critério, o efeito ou a limitação que a label não diz; ajuda que só repete a label deve ser omitida.
+Não existe texto auxiliar sob o campo: quem precisa de uma frase permanente abaixo do controle usa
+`FieldDescription` na composição própria.
+
+`LabelHelp` é esse mesmo ícone, exportado para um formulário sem contrato mostrar a ajuda no mesmo
+lugar:
+
+```tsx preview col md
+<Field>
+  <FieldLabel htmlFor="staff" className="items-center gap-1.5">
+    <span>Staff</span>
+    <LabelHelp help="Tem acesso ao back-office e a todos os workspaces." />
+  </FieldLabel>
+  <Input id="staff" placeholder="Empresa X" />
+</Field>
+```
+
+### Propriedades de LabelHelp
+
+| Propriedade | Tipo | Descrição |
+|---|---|---|
+| `help` | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
+
 ## Origem das opções de seleção
 
 As opções seguem esta precedência: `options` no campo, `fieldOptions` no formulário, `options` no

package/src/ui/docs/content/action-list-dialog.md

@@ -23,7 +23,7 @@ render(
           <Plus /> Workspace
         </Button>
       }
-      emptyText="Nenhum workspace."
+      emptyMessage="Nenhum workspace."
     >
       {(workspaces) => (
         <div className="space-y-2">
@@ -69,5 +69,5 @@ corpo do modal.
 | `actions` | `ReactNode` | | Ação à direita da toolbar — em geral o botão de criar. |
 | `empty` | `(items) => boolean` | `items.length === 0` | Sobrepõe o vazio derivado. |
 | `loading` | `boolean` | | Carga extra agregada à do fetch (query irmã). |
-| `emptyText / errorText` | `string` | | Textos dos estados (DataState). |
+| `emptyMessage / errorMessage / retryLabel` | `string` | | Textos dos estados; `retryLabel` nomeia a ação somente com ícone e seu tooltip. |
 | `className` | `string` | `sm:max-w-3xl` | Largura do DialogContent. |