@softize/opus 21.0.1 → 22.1.0

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

@@ -17,10 +17,7 @@ import {
   SurfaceMedia,
   type SurfaceMediaProps,
 } from "../patterns/surface-media.tsx";
-import {
-  CloseButton,
-  type CloseButtonSize,
-} from "./close-button.tsx";
+import { CloseButton, type CloseButtonSize } from "./close-button.tsx";
 import { overlayClasses, preventDismissWhen } from "./dialog.tsx";
 
 interface DrawerContentContextValue {
@@ -117,15 +114,15 @@ 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 [--surface-background:var(--background)] 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 overflow-hidden rounded-xl border 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",
+            "inset-y-1 right-1 h-[calc(100%-0.5rem)] w-3/4 max-w-sm data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right",
           side === "left" &&
-            "inset-y-0 left-0 h-full w-3/4 max-w-sm border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left",
+            "inset-y-1 left-1 h-[calc(100%-0.5rem)] w-3/4 max-w-sm data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left",
           side === "top" &&
-            "inset-x-0 top-0 h-auto border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
+            "inset-x-1 top-1 h-auto data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
           side === "bottom" &&
-            "inset-x-0 bottom-0 h-auto border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+            "inset-x-1 bottom-1 h-auto data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
           className,
         )}
         aria-describedby={ariaDescribedBy}
@@ -189,7 +186,10 @@ function DrawerMedia(props: SurfaceMediaProps) {
 }
 
 /** Região introdutória do header — o voltar de um fluxo modal encadeado. */
-function DrawerNavigation({ className, ...props }: React.ComponentProps<"div">) {
+function DrawerNavigation({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="drawer-navigation-content"
@@ -210,7 +210,11 @@ function DrawerActions({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
-function DrawerBody({ className, style, ...props }: React.ComponentProps<"div">) {
+function DrawerBody({
+  className,
+  style,
+  ...props
+}: React.ComponentProps<"div">) {
   const layout = useSurfaceLayout("drawer");
   return (
     <div
@@ -220,7 +224,7 @@ function DrawerBody({ className, style, ...props }: React.ComponentProps<"div">)
         surfaceRegionClasses("drawer", layout, "body"),
         className,
       )}
-      style={{ "--opus-inline-gutter": "1rem", ...style } as React.CSSProperties}
+      style={style}
       {...props}
     />
   );

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

@@ -1,43 +1,65 @@
-import * as React from "react"
-import { cva, type VariantProps } from "class-variance-authority"
-import { Tabs as TabsPrimitive } from "radix-ui"
+import * as React from "react";
+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'
+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) e a medida é a
 // da escala de control.ts.
-type TabsSize = Extract<ControlSize, "default" | "sm">
-const TabsSizeContext = React.createContext<TabsSize>("default")
-type TabsOrientation = "horizontal" | "vertical"
-const TabsOrientationContext = React.createContext<TabsOrientation>("horizontal")
-const TabsListVariantContext = React.createContext<"default" | "line">("default")
+type TabsSize = Extract<ControlSize, "default" | "sm">;
+type TabsDistribution = "content" | "equal";
+const TabsSizeContext = React.createContext<TabsSize>("default");
+const TabsDistributionContext =
+  React.createContext<TabsDistribution>("content");
+const TabsFramedContext = React.createContext(false);
+type TabsOrientation = "horizontal" | "vertical";
+const TabsOrientationContext =
+  React.createContext<TabsOrientation>("horizontal");
+const TabsListVariantContext = React.createContext<"default" | "line">(
+  "default",
+);
 
 function Tabs({
   className,
   orientation = "horizontal",
   size = "default",
+  distribution = "content",
+  framed = false,
   ...props
-}: React.ComponentProps<typeof TabsPrimitive.Root> & { size?: TabsSize }) {
+}: React.ComponentProps<typeof TabsPrimitive.Root> & {
+  size?: TabsSize;
+  /** Distribui os gatilhos pela largura do conjunto ou preserva a largura do conteúdo. */
+  distribution?: TabsDistribution;
+  /** Delimita a composição sem criar uma nova superfície. */
+  framed?: boolean;
+}) {
   return (
     <TabsOrientationContext.Provider value={orientation}>
-      <TabsSizeContext.Provider value={size}>
-        <TabsPrimitive.Root
-          data-slot="tabs"
-          data-orientation={orientation}
-          data-size={size}
-          orientation={orientation}
-          className={cn(
-            "group/tabs flex gap-2 data-[orientation=horizontal]:flex-col",
-            className
-          )}
-          {...props}
-        />
-      </TabsSizeContext.Provider>
+      <TabsDistributionContext.Provider value={distribution}>
+        <TabsFramedContext.Provider value={framed}>
+          <TabsSizeContext.Provider value={size}>
+            <TabsPrimitive.Root
+              data-slot="tabs"
+              data-orientation={orientation}
+              data-size={size}
+              data-distribution={distribution}
+              data-framed={framed}
+              orientation={orientation}
+              className={cn(
+                "group/tabs flex gap-2 data-[orientation=horizontal]:flex-col",
+                framed && "overflow-hidden rounded-xl border",
+                className,
+              )}
+              {...props}
+            />
+          </TabsSizeContext.Provider>
+        </TabsFramedContext.Provider>
+      </TabsDistributionContext.Provider>
     </TabsOrientationContext.Provider>
-  )
+  );
 }
 
 const tabsListVariants = cva(
@@ -49,14 +71,14 @@ const tabsListVariants = cva(
     variants: {
       variant: {
         default: "bg-muted",
-        line: "gap-5 bg-transparent",
+        line: "gap-1 bg-transparent",
       },
     },
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
 function TabsList({
   className,
@@ -67,20 +89,33 @@ function TabsList({
 }: React.ComponentProps<typeof TabsPrimitive.List> &
   VariantProps<typeof tabsListVariants>) {
   // O size vem do <Tabs> (contexto) — a altura mora aqui, na list.
-  const size = React.useContext(TabsSizeContext)
-  const orientation = React.useContext(TabsOrientationContext)
-  const normalizedVariant = variant ?? "default"
-  const hasHorizontalLine = normalizedVariant === "line" && orientation === "horizontal"
+  const size = React.useContext(TabsSizeContext);
+  const orientation = React.useContext(TabsOrientationContext);
+  const distribution = React.useContext(TabsDistributionContext);
+  const normalizedVariant = variant ?? "default";
+  const hasHorizontalLine =
+    normalizedVariant === "line" && orientation === "horizontal";
   return (
     <TabsListVariantContext.Provider value={normalizedVariant}>
       <TabsPrimitive.List
         data-slot="tabs-list"
         data-variant={normalizedVariant}
         data-size={size}
-        className={cn(tabsListVariants({ variant: normalizedVariant }), controlHeight[size], className)}
+        data-distribution={distribution}
+        className={cn(
+          tabsListVariants({ variant: normalizedVariant }),
+          controlHeight[size],
+          distribution === "equal" && orientation === "horizontal" && "w-full",
+          className,
+        )}
         style={{
           ...(hasHorizontalLine
-            ? { position: "relative", width: "100%", height: "auto", justifyContent: "flex-start" }
+            ? {
+                position: "relative",
+                width: "100%",
+                height: "auto",
+                justifyContent: "flex-start",
+              }
             : {}),
           ...style,
         }}
@@ -92,7 +127,7 @@ function TabsList({
             data-slot="tabs-line"
             style={{
               position: "absolute",
-              insetInline: "calc(var(--opus-inline-gutter, 0rem) * -1)",
+              insetInline: "0rem",
               bottom: 0,
               borderBottomWidth: "0.0625rem",
               borderBottomStyle: "solid",
@@ -104,7 +139,7 @@ function TabsList({
         {children}
       </TabsPrimitive.List>
     </TabsListVariantContext.Provider>
-  )
+  );
 }
 
 function TabsTrigger({
@@ -115,38 +150,72 @@ function TabsTrigger({
   ...props
 }: React.ComponentProps<typeof TabsPrimitive.Trigger> & {
   /** Ícone decorativo antes do rótulo. Em uma aba sem texto, declare também `aria-label`. */
-  icon?: React.ReactNode
+  icon?: React.ReactNode;
 }) {
-  const variant = React.useContext(TabsListVariantContext)
-  const orientation = React.useContext(TabsOrientationContext)
-  const hasHorizontalLine = variant === "line" && orientation === "horizontal"
+  const variant = React.useContext(TabsListVariantContext);
+  const orientation = React.useContext(TabsOrientationContext);
+  const size = React.useContext(TabsSizeContext);
+  const distribution = React.useContext(TabsDistributionContext);
+  const framed = React.useContext(TabsFramedContext);
+  const hasHorizontalLine = variant === "line" && orientation === "horizontal";
+  const content = (
+    <>
+      {icon !== undefined && (
+        <span
+          data-slot="tabs-trigger-icon"
+          aria-hidden="true"
+          className="flex size-4 shrink-0 items-center justify-center [&_svg]:size-4"
+        >
+          {icon}
+        </span>
+      )}
+      {children}
+    </>
+  );
   return (
     <TabsPrimitive.Trigger
       data-slot="tabs-trigger"
       // px: altura e indicador compensam a hairline do contêiner (um pixel físico, não escala).
       className={cn(
         "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap text-foreground/60 transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start hover:text-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none dark:text-muted-foreground dark:hover:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
-        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent",
+        "dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-transparent",
         "data-[state=active]:bg-background data-[state=active]:text-foreground dark:data-[state=active]:border-input dark:data-[state=active]:text-foreground",
-        "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-1px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100",
-        hasHorizontalLine && "px-0 py-3",
-        className
+        "after:absolute after:bg-primary after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-1px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100",
+        hasHorizontalLine &&
+          cn(
+            "group/tab-trigger rounded-none px-0 py-0 hover:bg-transparent active:brightness-100 data-[state=active]:bg-transparent data-[state=active]:hover:bg-transparent",
+            framed ? "pb-2" : "pb-1.5",
+          ),
+        className,
       )}
-      style={{ ...(hasHorizontalLine ? { flex: "none", height: "auto" } : {}), ...style }}
+      style={{
+        ...(hasHorizontalLine
+          ? {
+              flex: distribution === "equal" ? "1 1 0%" : "none",
+              height: "auto",
+              minWidth: distribution === "equal" ? 0 : undefined,
+            }
+          : {}),
+        ...style,
+      }}
       {...props}
     >
-      {icon !== undefined && (
+      {hasHorizontalLine ? (
         <span
-          data-slot="tabs-trigger-icon"
-          aria-hidden="true"
-          className="flex size-4 shrink-0 items-center justify-center [&_svg]:size-4"
+          data-slot="tabs-trigger-content"
+          className={cn(
+            "inline-flex items-center justify-center gap-1.5 rounded-md px-3 transition-colors hover:bg-accent hover:text-accent-foreground active:brightness-90 group-data-[state=active]/tab-trigger:text-foreground",
+            distribution === "equal" && "w-full",
+            controlHeight[size],
+          )}
         >
-          {icon}
+          {content}
         </span>
+      ) : (
+        content
       )}
-      {children}
     </TabsPrimitive.Trigger>
-  )
+  );
 }
 
 function TabsContent({
@@ -159,7 +228,7 @@ function TabsContent({
       className={cn("flex-1 outline-none", className)}
       {...props}
     />
-  )
+  );
 }
 
-export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };

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

@@ -152,54 +152,62 @@ A autorização é fechada por padrão: sem `public: true`, a action exige usuá
 
 ## Prototipar com dados simulados
 
-Para desenhar a interface antes de o backend existir, declare um `mockHandler` no contrato. Com
-`OPUS_MODE=design`, o runtime executa o `mockHandler` no lugar do `handler`; sem ele, usa o
-`handler` real. Como o mock fica no contrato, a mesma declaração serve ao design e, depois, ao
-handler real, e o mock não precisa acessar `ctx.db`.
+Para desenhar a interface antes de o backend existir, rode o app em modo design. Nesse modo, toda
+action responde sem que o contrato declare nada: a resposta é gerada pelo `fake` a partir do
+`output` do contrato (ADR 0037).
 
-`fake` e `fakeMany` geram dados determinísticos a partir do próprio schema (ver
-[Testes de action](/docs/testing)). Em `list`, o `mockHandler` devolve a página inteira, com
-`items`, `cursor` e `total`:
+- A mesma requisição recebe sempre a mesma resposta.
+- Uma `list` devolve três páginas do tamanho pedido em `limit` (20 quando a entrada não pede, até
+  100) e respeita a paginação declarada. Busca e filtros não filtram o dado gerado.
+- Quando a entrada e a saída têm `id`, a saída repete o `id` da entrada, desde que o schema da saída
+  aceite esse valor. Assim, abrir um item da lista mostra o mesmo identificador.
+
+O dado gerado tem o formato certo, mas não segue a regra de negócio: os valores de um enum são
+sorteados, e uma listagem e um detalhe só coincidem no `id`. Quando o design precisa de coerência,
+como um item em cada situação ou algo criado que aparece na lista, escreva um cenário. Ele fica fora
+do contrato e é ligado à action pelo nome:
 
 ```ts
-import { bindAction, defineContract } from '@softize/opus/core'
-import { entityRowSchema } from '@softize/opus/schema'
-import { fake, fakeMany } from '@softize/opus/testing'
-import { z } from 'zod'
-import { EventEntity } from '../entity.ts'
+import { defineDesignScenario } from '@softize/opus/design'
+import { eventGet, eventList } from '../domains/event/contract.ts'
+
+// Valor fixo: o caso mais comum.
+export const eventsInEachState = defineDesignScenario(eventList, {
+  items: [
+    { id: 'e1', title: 'Revisão agendada', status: 'scheduled' },
+    { id: 'e2', title: 'Revisão perdida', status: 'lost' },
+  ],
+  cursor: { next: null },
+  total: 2,
+})
 
-// `entityRowSchema` deriva da entidade o schema de uma linha.
-const eventRowSchema = entityRowSchema(EventEntity)
+// Função: quando a resposta depende da entrada.
+export const eventDetail = defineDesignScenario(eventGet, (input) => ({
+  id: input.id,
+  title: 'Revisão agendada',
+  status: 'scheduled',
+}))
+```
 
-export const eventGet = defineContract({
-  name: 'event.get',
-  kind: 'view',
-  input: z.object({ id: z.string().uuid() }),
-  output: eventRowSchema,
-  mockHandler: () => fake(eventRowSchema),
-})
+A resposta é tipada pela entrada e pela saída do contrato; em `list`, é a página inteira. Informe ao
+plugin onde os cenários estão, com caminhos ou globs:
+`opusDesign({ scenarios: 'design/scenarios/*.ts' })`. O cenário vence a resposta gerada. Um cenário
+de uma action que não existe, ou dois cenários para a mesma action, impedem o runtime de design de
+subir, e o erro lista os nomes.
 
-export const eventList = defineContract({
-  name: 'event.list',
-  kind: 'list',
-  input: z.object({}),
-  output: eventRowSchema,
-  paginate: 'cursor',
-  mockHandler: async () => ({ items: fakeMany(eventRowSchema, 20), cursor: { next: null }, total: 20 }),
-})
+O Opus não decide onde os cenários ficam nem se entram no repositório. Eles não fazem parte da
+aplicação: podem ficar numa pasta ignorada pelo git e ser escritos durante a sessão de design,
+quando forem necessários.
 
-// Depois, o servidor liga o handler real ao mesmo contrato.
-export const eventGetImpl = bindAction(eventGet, {
-  handler: async (ctx, input) =>
-    ctx.db.selectFrom('events').selectAll().where('id', '=', input.id).executeTakeFirstOrThrow(),
-})
-```
+`mockHandler` está obsoleto desde a 22.1.0 e sai na próxima major. Enquanto existir, ele ainda
+responde no modo design, abaixo do cenário e acima da resposta gerada, e o `opus check` conta
+quantas actions ainda o declaram. Para migrar, apague o `mockHandler`; se a resposta dele importar
+para o design, transforme-a em cenário.
 
-O `mockHandler` roda no servidor, não no navegador. O plugin `opusDesign()`, de
-`@softize/opus/vite`, monta o runtime do Opus dentro do dev server e responde `/api` no próprio
-processo. No modo design, qualquer `server.proxy` para um backend externo fica desligado: um prefixo
-que ia para o proxy e não tem action correspondente responde 503 em envelope, sem alcançar o
-backend. A aplicação chama `/api` como sempre e recebe os dados simulados.
+O plugin `opusDesign()`, de `@softize/opus/vite`, monta o runtime do Opus dentro do dev server e
+responde `/api` no próprio processo. No modo design, qualquer `server.proxy` para um backend externo
+fica desligado: um prefixo que ia para o proxy e não tem action correspondente responde 503 em
+envelope, sem alcançar o backend. A aplicação chama `/api` como sempre e recebe os dados simulados.
 
 ```ts
 // vite.config.ts — o plugin só carrega no modo design, por import dinâmico.
@@ -233,9 +241,7 @@ nem reiniciar o dev server. Quando uma action não é encontrada, o plugin recon
 vez por ciclo de mudança e tenta de novo; se a action continuar ausente, a resposta indica o
 `entry` a conferir.
 
-Como o contrato vai para os dois lados, o `mockHandler` também entra no bundle da web, onde nunca é
-chamado. Não o condicione com `import.meta.env` no contrato: essa variável não existe no Node e
-quebraria o servidor.
+Os cenários não entram no bundle da web: eles ficam fora do contrato, e só o plugin os carrega.
 
 ## Consumir o contrato na interface
 

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

@@ -1,8 +1,9 @@
 ## Contexto e variante
 
-Use `Button` para iniciar uma ação. `context` declara a hierarquia ou o risco da ação; `variant`
-escolhe o tratamento visual. Use `primary` para a ação principal, `neutral` para ações de apoio e
-`danger` quando a ação tiver uma consequência perigosa. A variante `outline` mantém o fundo
+Use `Button` para iniciar uma ação. `context` declara a hierarquia, a cautela ou o risco da ação;
+`variant` escolhe o tratamento visual. Use `primary` para a ação principal, `neutral` para ações de
+apoio, `warning` quando a pessoa puder prosseguir mas o efeito merecer atenção e `danger` quando a
+ação tiver uma consequência perigosa. A variante `outline` mantém o fundo
 transparente em repouso e usa uma superfície apenas no hover, preservando o fundo da região onde o
 botão está inserido. `subtle` preenche o botão com um tom suave do contexto, para ações que precisam
 de presença sem competir com a principal.
@@ -13,6 +14,7 @@ de presença sem competir com a principal.
 <Button variant="subtle">Convidar pessoa</Button>
 <Button context="neutral" variant="outline">Ver prévia</Button>
 <Button context="neutral" variant="ghost">Cancelar</Button>
+<Button context="warning" variant="ghost">Registrar tentativa sem sucesso</Button>
 <Button context="danger" variant="solid">Excluir</Button>
 <Button context="primary" variant="link">Ver documentação</Button>
 ```
@@ -27,16 +29,16 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 `icon-xs`, `icon-sm` e `icon`; 1rem em `default`; 1.25rem em `lg` e `icon-lg`), a menos que o
 ícone traga um `size-*` próprio. O quadrado `icon` mantém a área de 2.25rem com o glifo discreto.
 
-| Nome      | Medida  | Uso                                                                                                                              |
-| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `xs`      | 1.5rem  | Ação dentro de um campo (`InputGroupButton`).                                                                                    |
-| `sm`      | 2rem    | Operação densa em toolbar ou dentro de uma seção, ao lado de `Select` e `Tabs` `sm`.                                             |
+| Nome      | Medida  | Uso                                                                                                                                   |
+| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `xs`      | 1.5rem  | Ação dentro de um campo (`InputGroupButton`).                                                                                         |
+| `sm`      | 2rem    | Operação densa em toolbar ou dentro de uma seção, ao lado de `Select` e `Tabs` `sm`.                                                  |
 | `default` | 2.25rem | Decisão da superfície: header de Page, criação no cabeçalho de uma coleção e footer de Dialog ou Drawer; é também a linha de `Input`. |
-| `lg`      | 2.5rem  | Chamada principal com mais área de toque.                                                                                        |
-| `icon-xs` | 1.5rem  | Ação só de ícone dentro de um campo ou de uma linha densa; é o quadrado de `ActionTrigger` com `icon`.                           |
-| `icon-sm` | 1.75rem | Ação só de ícone em composições compactas que precisam de mais presença; também é o quadrado das setas do pager de `ActionList`. |
-| `icon`    | 2.25rem | Ação só de ícone na linha padrão.                                                                                                |
-| `icon-lg` | 2.5rem  | Ação só de ícone ao lado de um `lg`.                                                                                             |
+| `lg`      | 2.5rem  | Chamada principal com mais área de toque.                                                                                             |
+| `icon-xs` | 1.5rem  | Ação só de ícone dentro de um campo ou de uma linha densa; é o quadrado de `ActionTrigger` com `icon`.                                |
+| `icon-sm` | 1.75rem | Ação só de ícone em composições compactas que precisam de mais presença; também é o quadrado das setas do pager de `ActionList`.      |
+| `icon`    | 2.25rem | Ação só de ícone na linha padrão.                                                                                                     |
+| `icon-lg` | 2.5rem  | Ação só de ícone ao lado de um `lg`.                                                                                                  |
 
 Escolha o tamanho pela região, não pela importância visual: `variant` e `context` resolvem a
 hierarquia da ação. Headers de Page, a criação no cabeçalho de uma coleção e footers de
@@ -102,15 +104,15 @@ estilos, use `buttonVariants` para obter as classes.
 
 ## Propriedades de Button
 
-| Propriedade | Tipo                                                                                 | Padrão      | Descrição                                                                                                                                         |
-| ----------- | ------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `context`   | `'neutral' \| 'primary' \| 'danger'`                                                 | `'primary'` em `solid` e `subtle`; `'neutral'` nas demais variantes | A hierarquia ou o risco comunicado pela ação. |
-| `variant`   | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'`                              | `'solid'`   | O tratamento visual aplicado ao contexto.                                                                                                         |
-| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'default'` | A medida na escala única dos controles (tabela acima). Os `icon-*` são quadrados para botões só de ícone, com `aria-label`.                       |
-| `shape`     | `'default' \| 'pill'`                                                                 | `'default'` | Geometria do botão; `pill` arredonda as extremidades por completo. |
-| `asChild`   | `boolean`                                                                            | `false`     | Renderiza como o filho (Radix Slot) em vez de `<button>` — para âncoras e afins.                                                                  |
-| `busy`      | `boolean`                                                                            | `false`     | Ação em andamento, depois do clique: mostra o `Spinner` e desabilita o botão. Não indica carregamento de conteúdo; para isso, use `DataState` ou `Skeleton`. |
-| `icon`      | `React.ReactNode`                                                                    |             | Ícone à esquerda, como nó (ex.: `icon={<Plus />}`); o glifo segue o `size`. Com `busy`, dá lugar ao `Spinner`; os dois não aparecem juntos.     |
+| Propriedade | Tipo                                                                                 | Padrão                                                              | Descrição                                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `context`   | `'neutral' \| 'primary' \| 'warning' \| 'danger'`                                    | `'primary'` em `solid` e `subtle`; `'neutral'` nas demais variantes | A hierarquia, a cautela ou o risco comunicado pela ação.                                                                                                     |
+| `variant`   | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'`                              | `'solid'`                                                           | O tratamento visual aplicado ao contexto.                                                                                                                    |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'default'`                                                         | A medida na escala única dos controles (tabela acima). Os `icon-*` são quadrados para botões só de ícone, com `aria-label`.                                  |
+| `shape`     | `'default' \| 'pill'`                                                                | `'default'`                                                         | Geometria do botão; `pill` arredonda as extremidades por completo.                                                                                           |
+| `asChild`   | `boolean`                                                                            | `false`                                                             | Renderiza como o filho (Radix Slot) em vez de `<button>` — para âncoras e afins.                                                                             |
+| `busy`      | `boolean`                                                                            | `false`                                                             | Ação em andamento, depois do clique: mostra o `Spinner` e desabilita o botão. Não indica carregamento de conteúdo; para isso, use `DataState` ou `Skeleton`. |
+| `icon`      | `React.ReactNode`                                                                    |                                                                     | Ícone à esquerda, como nó (ex.: `icon={<Plus />}`); o glifo segue o `size`. Com `busy`, dá lugar ao `Spinner`; os dois não aparecem juntos.                  |
 
 ## ButtonGroup
 
@@ -146,6 +148,27 @@ conectar bordas. Esse modo atende ações só com ícone em barras e linhas de l
 </ButtonGroup>
 ```
 
+### Ações divididas
+
+Use `mode="divided"` quando cada controle precisar preservar sua própria interação, mas divisores
+visuais ajudarem a ler o conjunto. O grupo insere os divisores entre os filhos e acompanha a
+orientação automaticamente. Combine `framed` para delimitar o conjunto sem criar um fundo e
+`distribution="equal"` quando as ações precisarem ocupar larguras iguais.
+
+```tsx preview col
+<ButtonGroup framed mode="divided" distribution="equal">
+  <Button variant="ghost" icon={<Phone />}>
+    Ligar
+  </Button>
+  <Button variant="ghost" icon={<MessageSquare />}>
+    Anotar
+  </Button>
+  <Button context="danger" variant="ghost" icon={<CircleX />}>
+    Encerrar
+  </Button>
+</ButtonGroup>
+```
+
 ### No rodapé de Dialog e Drawer
 
 `DialogFooter` e `DrawerFooter` cuidam somente da faixa; envolva as decisões em um
@@ -169,13 +192,15 @@ confirmação. As ações dividem a largura disponível; use `outline` no `Cance
 ```tsx preview col
 <div className="w-80">
   <ButtonGroup mode="spaced" distribution="equal">
-    <Button context="neutral" variant="outline">Cancelar</Button>
+    <Button context="neutral" variant="outline">
+      Cancelar
+    </Button>
     <Button context="danger">Excluir</Button>
   </ButtonGroup>
 </div>
 ```
 
-### Ação dividida
+### Ação com variações
 
 Combine a ação principal, um separador e um botão de ícone quando o mesmo comando oferecer
 variações.
@@ -227,12 +252,13 @@ semântica de outro elemento, como `label`.
 
 ### Propriedades de ButtonGroup
 
-| Propriedade    | Tipo                         | Padrão         | Descrição                                                                                 |
-| -------------- | ---------------------------- | -------------- | ----------------------------------------------------------------------------------------- |
-| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do bloco e do colapso das bordas.                                                 |
-| `mode`         | `'connected' \| 'spaced'`    | `'connected'`  | Conecta as bordas dos controles ou preserva cada controle com intervalo compacto.         |
-| `shape`        | `'default' \| 'pill'`        | `'default'`    | Geometria das extremidades externas do grupo.                                             |
-| `distribution` | `'content' \| 'equal'`       | `'content'`    | Mantém a largura do conteúdo ou divide igualmente o espaço disponível entre os controles. |
+| Propriedade    | Tipo                                   | Padrão         | Descrição                                                                                 |
+| -------------- | -------------------------------------- | -------------- | ----------------------------------------------------------------------------------------- |
+| `orientation`  | `'horizontal' \| 'vertical'`           | `'horizontal'` | Direção do bloco e do colapso das bordas.                                                 |
+| `mode`         | `'connected' \| 'spaced' \| 'divided'` | `'connected'`  | Conecta as bordas, separa por espaço ou insere divisores entre os controles.              |
+| `shape`        | `'default' \| 'pill'`                  | `'default'`    | Geometria das extremidades externas do grupo.                                             |
+| `distribution` | `'content' \| 'equal'`                 | `'content'`    | Mantém a largura do conteúdo ou divide igualmente o espaço disponível entre os controles. |
+| `framed`       | `boolean`                              | `false`        | Aplica borda, raio e padding ao grupo sem definir uma nova superfície.                    |
 
 ### Propriedades de ButtonGroupSeparator