@softize/opus 18.5.0 → 20.0.0

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

@@ -35,33 +35,73 @@ acompanham o tamanho.
 ```tsx preview
 <Avatar size="xs">
   <AvatarFallback>AL</AvatarFallback>
+  <AvatarBadge className="bg-context-success" />
 </Avatar>
 <Avatar size="sm">
   <AvatarFallback>AL</AvatarFallback>
+  <AvatarBadge className="bg-context-success" />
 </Avatar>
 <Avatar size="default">
   <AvatarFallback>AL</AvatarFallback>
+  <AvatarBadge className="bg-context-success" />
 </Avatar>
 <Avatar size="lg">
   <AvatarFallback>AL</AvatarFallback>
+  <AvatarBadge className="bg-context-success" />
 </Avatar>
 ```
 
 ## Com selo de status
 
-AvatarBadge é o ponto no canto inferior — verde para o agente developer rodando uma sessão, cinza
-para o ocioso. Tinja com className.
+AvatarBadge mostra o estado de quem o avatar representa: verde para a pessoa online ou para o
+agente developer rodando uma sessão, cinza para quem está ocioso. Sem classe, o selo usa a cor
+primária; tinja-o com className. Ele fica no canto inferior direito, sobre a borda do círculo.
+
+O selo comunica o estado só pela cor. Quando o estado importa e não aparece em texto ao lado, dê um
+nome ao selo com `role="img"` e `aria-label`, como o `label` do [`Dot`](/ui/dot) faz.
 
 ```tsx preview
+<Avatar>
+  <AvatarImage src="https://github.com/joaocampos.png" alt="João Campos" />
+  <AvatarFallback>JC</AvatarFallback>
+  <AvatarBadge className="bg-context-success" role="img" aria-label="Online" />
+</Avatar>
 <Avatar>
   <AvatarFallback>
     <Bot className="size-4" />
   </AvatarFallback>
-  <AvatarBadge className="bg-context-success" />
+  <AvatarBadge className="bg-context-success" role="img" aria-label="Em sessão" />
 </Avatar>
 <Avatar>
   <AvatarFallback>RV</AvatarFallback>
-  <AvatarBadge className="bg-muted-foreground" />
+  <AvatarBadge className="bg-context-neutral-emphasis" role="img" aria-label="Ocioso" />
+</Avatar>
+```
+
+Um ícone filho aparece dentro do selo, em `0.5rem`. No tamanho `xs`, o selo é pequeno demais para o
+ícone e mostra só a cor.
+
+```tsx preview
+<Avatar size="lg">
+  <AvatarFallback>AL</AvatarFallback>
+  <AvatarBadge role="img" aria-label="Verificado">
+    <Check />
+  </AvatarBadge>
+</Avatar>
+```
+
+## Forma do avatar
+
+O avatar é circular por padrão. Para logo de organização ou workspace, declare outra forma no
+próprio Avatar, como `rounded-lg`: a imagem e o fallback a acompanham. O Avatar não recorta o que
+você coloca direto nele; para imagem ou iniciais, use AvatarImage e AvatarFallback.
+
+```tsx preview
+<Avatar className="rounded-lg">
+  <AvatarFallback>EX</AvatarFallback>
+</Avatar>
+<Avatar size="lg" className="rounded-lg">
+  <AvatarFallback>EX</AvatarFallback>
 </Avatar>
 ```
 
@@ -91,6 +131,7 @@ excedente — os membros do workspace Empresa X.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato na escala única dos controles (1.5 · 2 · 2.25 · 2.5rem); o fallback e o selo acompanham. |
+| `className` | `string` | | Classes do root. Uma forma declarada aqui, como `rounded-lg`, vale também para AvatarImage e AvatarFallback. |
 
 ## Propriedades de AvatarImage
 
@@ -109,7 +150,15 @@ excedente — os membros do workspace Empresa X.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `className` | `string` | | Classes usadas para comunicar visualmente o status no selo. |
+| `className` | `string` | | Classes usadas para comunicar visualmente o status no selo. Sem cor própria, o fundo é `bg-primary`. |
+| `children` | `React.ReactNode` | | Ícone opcional dentro do selo; fica oculto no tamanho `xs`. |
+
+Os demais atributos, como `role` e `aria-label`, vão para o elemento `span`.
+
+## Propriedades de AvatarGroup
+
+`AvatarGroup` sobrepõe os `Avatar` filhos e desenha o anel de fundo que os separa. Não tem props
+próprias; aceita as de um elemento `div`, como `className`.
 
 ## Propriedades de AvatarGroupCount
 

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

@@ -1,7 +1,11 @@
 ## Contexto e variante
 
-Badge é não-interativo — para clique, use Button. `context` comunica o significado; `variant`
-escolhe entre preenchimento sólido, superfície sutil ou contorno.
+Use `Badge` para um rótulo curto de estado ou categoria que precisa continuar legível. O Badge não é
+interativo; para clique, use [`Button`](/ui/button). Quando só a cor basta, ao lado de um texto que
+já nomeia o item, use [`Dot`](/ui/dot).
+
+`context` comunica o significado; `variant` escolhe entre preenchimento sólido, superfície sutil ou
+contorno.
 
 ```tsx preview
 <Badge context="neutral">Agente</Badge>
@@ -11,9 +15,9 @@ escolhe entre preenchimento sólido, superfície sutil ou contorno.
 
 ## Contextos de status
 
-`success`, `warning`, `info` e `danger` usam `subtle` por padrão. Valor de dicionário com papel
-declarado usa `DictionaryValue`, que escolhe o contexto pela metadata em vez de repetir esta
-decisão em cada tela.
+Todos os contextos usam `subtle` por padrão, incluindo `success`, `warning`, `info` e `danger`.
+Valor de dicionário com papel declarado usa [`DictionaryValue`](/ui/dictionary-value), que escolhe o
+contexto pelo próprio dicionário em vez de repetir esta decisão em cada tela.
 
 ```tsx preview
 <Badge context="success">Ativa</Badge>
@@ -24,7 +28,7 @@ decisão em cada tela.
 
 ## Com ícone
 
-Um svg filho ganha size-3 automaticamente — bom para reforçar o estado sem crescer o rótulo.
+Um ícone filho recebe `size-3` automaticamente e reforça o estado sem aumentar a altura do rótulo.
 
 ```tsx preview
 <Badge context="success"><CircleCheck /> Regressão verde</Badge>
@@ -32,8 +36,9 @@ Um svg filho ganha size-3 automaticamente — bom para reforçar o estado sem cr
 
 ## Como link (asChild)
 
-asChild renderiza o filho (Radix Slot) — um `<a>` com cara de badge. O Badge não aplica estado de
-hover; acrescente-o por `className` quando o link precisar de retorno visual.
+Com `asChild`, o Badge entrega a aparência ao filho em vez de renderizar o próprio `<span>`: um
+`<a>` passa a ter a forma de badge e mantém a navegação. O Badge não aplica estado de hover;
+acrescente-o por `className` quando o link precisar de retorno visual.
 
 ```tsx preview
 <Badge asChild context="neutral" variant="solid">
@@ -47,4 +52,19 @@ hover; acrescente-o por `className` quando o link precisar de retorno visual.
 |---|---|---|---|
 | `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado ou destaque contextual. |
 | `variant` | `'solid' \| 'subtle' \| 'outline'` | `'subtle'` | O tratamento visual aplicado ao contexto. |
-| `asChild` | `boolean` | `false` | Renderiza como o filho (Radix Slot) em vez de `<span>` — ex.: um `<a>` com cara de badge. |
+| `asChild` | `boolean` | `false` | Renderiza o filho, como um `<a>`, com a aparência de badge, em vez de um `<span>`. |
+
+Os demais atributos vão para o `<span>` ou, com `asChild`, para o filho.
+
+## Função badgeVariants
+
+`badgeVariants({ context, variant })` retorna as classes do Badge para um componente que só aceita
+`className` e não pode ser envolvido com `asChild`. Os padrões são os mesmos do Badge: `neutral` e
+`subtle`.
+
+```ts
+function badgeVariants(options?: {
+  context?: BadgeContext | null
+  variant?: BadgeVariant | null
+}): string
+```

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

@@ -1,7 +1,13 @@
 ## Caminho atual
 
-A composição é manual: BreadcrumbLink nos níveis navegáveis, BreadcrumbPage no atual (não
-clicável, aria-current=page) e um BreadcrumbSeparator entre cada item.
+Use `Breadcrumb` quando a página estiver vários níveis abaixo da entrada da seção e a pessoa
+precisar ver onde está e voltar a um nível intermediário. Em uma página, a trilha ocupa a região de
+navegação do cabeçalho, como descreve [`Page`](/ui/page); quando basta voltar ao nível imediatamente
+acima, use o retorno de `PageBack`.
+
+Monte a trilha item a item: `BreadcrumbLink` nos níveis navegáveis, `BreadcrumbPage` no nível atual
+e um `BreadcrumbSeparator` entre cada item. `BreadcrumbPage` não é clicável e marca a página atual
+com `aria-current="page"`.
 
 ```tsx preview col-start
 <Breadcrumb>
@@ -21,10 +27,10 @@ clicável, aria-current=page) e um BreadcrumbSeparator entre cada item.
 </Breadcrumb>
 ```
 
-## Com ícone e separador custom
+## Com ícone e separador próprio
 
-O primeiro nível pode levar um ícone do lucide. BreadcrumbSeparator aceita children para trocar o
-chevron padrão por outro glifo (aqui, uma barra).
+O primeiro nível pode levar um ícone para reforçar a origem da trilha. `BreadcrumbSeparator` aceita
+`children` para trocar o chevron padrão por outro ícone, como a barra do exemplo.
 
 ```tsx preview col-start
 <Breadcrumb>
@@ -53,9 +59,10 @@ chevron padrão por outro glifo (aqui, uma barra).
 
 ## Colapsado
 
-Trilha funda demais para o espaço: BreadcrumbEllipsis marca os níveis do meio omitidos e mantém só a
-raiz e o destino. A elipse é decorativa (`aria-hidden`), não um menu: os níveis ocultos deixam de ser
-alcançáveis pela trilha. Ofereça esse caminho por outro meio, como a navegação da seção.
+Quando a trilha tiver mais níveis do que o espaço comporta, `BreadcrumbEllipsis` substitui os níveis
+intermediários e mantém visíveis a raiz e os níveis mais próximos da página atual. A elipse é
+decorativa (`aria-hidden`), e não um menu: os níveis omitidos deixam de ser alcançáveis pela trilha.
+Ofereça esse caminho por outro meio, como a navegação da seção.
 
 ```tsx preview col-start
 <Breadcrumb>
@@ -91,3 +98,9 @@ alcançáveis pela trilha. Ofereça esse caminho por outro meio, como a navegaç
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `children` | `React.ReactNode` | `<ChevronRight />` | Elemento entre os itens. Omita para usar o chevron padrão ou passe outro ícone. |
+
+`Breadcrumb` renderiza um `<nav>` com o nome acessível “Navegação estrutural”; `BreadcrumbList`, um
+`<ol>`; `BreadcrumbItem`, um `<li>`; `BreadcrumbPage`, um `<span>`; e `BreadcrumbEllipsis`, um
+`<span>`. Nenhum deles tem propriedades próprias: todos aceitam as props nativas do respectivo
+elemento, incluindo `className`. Passe `aria-label` ao `Breadcrumb` quando a página tiver mais de
+uma trilha.

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

@@ -1,13 +1,16 @@
 ## Contexto e variante
 
-`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 transparente em repouso e usa uma
-superfície apenas no hover, preservando o fundo da região onde o botão está inserido.
+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
+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.
 
 ```tsx preview
 <Button>Criar workspace</Button>
 <Button context="neutral" variant="solid">Duplicar</Button>
+<Button variant="subtle">Convidar pessoa</Button>
 <Button context="neutral" variant="outline">Ver prévia</Button>
 <Button context="neutral" variant="ghost">Cancelar</Button>
 <Button context="danger" variant="solid">Excluir</Button>
@@ -16,8 +19,9 @@ superfície apenas no hover, preservando o fundo da região onde o botão está
 
 ## Tamanhos
 
-`size` usa a escala única dos controles: o mesmo nome tem a mesma medida em `Button`, `Select`,
-`Tabs`, `Toggle`, `Switch`, `Avatar`, `Spinner` e nos botões embutidos. Os tamanhos de texto dão a
+`size` usa a escala única dos controles: o mesmo nome tem a mesma altura em `Button`, `Select`,
+`Tabs`, `Toggle`, `Avatar` e nos botões embutidos. `Switch` e `Spinner` usam os mesmos nomes, mas
+acompanham o tamanho do ícone de cada degrau, e não a altura da linha. Os tamanhos de texto dão a
 altura da linha; os `icon-*` são quadrados para botões só de ícone, que exigem `aria-label` porque não
 há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em `xs`, `sm`,
 `icon-xs`, `icon-sm` e `icon`; 1rem em `default`; 1.25rem em `lg` e `icon-lg`), a menos que o
@@ -26,8 +30,8 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 | Nome      | Medida  | Uso                                                                                                                              |
 | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | `xs`      | 1.5rem  | Ação dentro de um campo (`InputGroupButton`).                                                                                    |
-| `sm`      | 2rem    | Ação operacional em toolbar, seção ou coleção densa, ao lado de `Select` e `Tabs` `sm`.                                         |
-| `default` | 2.25rem | Decisão da superfície em header de Page ou footer de Dialog/Drawer; é também a linha padrão de `Input`.                         |
+| `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`. |
@@ -35,10 +39,11 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 | `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 e footers de Dialog/Drawer usam `default`; ações operacionais
-de seção, toolbar e coleção usam `sm`; ações dentro de linha ou célula usam `xs` ou `icon-xs`.
-Assim a mesma decisão mantém a mesma altura mesmo quando uma superfície troca uma ação secundária
-por uma primária.
+hierarquia da ação. Headers de Page, a criação no cabeçalho de uma coleção e footers de
+[`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) usam `default`; a criação de uma coleção é um botão textual, sem
+ícone, como mostra [`Content`](/ui/content). Operações densas de toolbar ou de seção usam `sm`;
+ações dentro de linha ou célula usam `xs` ou `icon-xs`. Assim a mesma decisão mantém a mesma altura
+mesmo quando uma superfície troca uma ação secundária por uma primária.
 
 O retorno de `PageBack` usa `icon`. O fechamento de Dialog e Drawer é um `CloseButton` circular
 (`shape="pill"`), `neutral` e `subtle`, no quadrado `icon-sm` por padrão, ou `icon-xs` com
@@ -49,29 +54,43 @@ O retorno de `PageBack` usa `icon`. O fechamento de Dialog e Drawer é um `Close
 <Button size="sm">Pequeno</Button>
 <Button>Padrão</Button>
 <Button size="lg">Grande</Button>
-<Button size="icon-xs" variant="ghost" aria-label="Novo"><Plus /></Button>
-<Button size="icon-sm" variant="ghost" aria-label="Novo"><Plus /></Button>
-<Button size="icon" aria-label="Novo"><Plus /></Button>
-<Button size="icon-lg" aria-label="Novo"><Plus /></Button>
+<Button size="icon-xs" variant="ghost" aria-label="Configurações"><Settings /></Button>
+<Button size="icon-sm" variant="ghost" aria-label="Configurações"><Settings /></Button>
+<Button size="icon" aria-label="Configurações"><Settings /></Button>
+<Button size="icon-lg" aria-label="Configurações"><Settings /></Button>
+```
+
+## Forma
+
+`shape="pill"` arredonda as extremidades por completo. Use-a quando o botão acompanhar outros
+controles arredondados, como a busca da toolbar de listas ou um grupo de filtros em pílula.
+
+```tsx preview
+<Button shape="pill" variant="outline" context="neutral">Todos os status</Button>
+<Button shape="pill" size="icon" variant="ghost" aria-label="Filtros"><Filter /></Button>
 ```
 
 ## Estados
 
-busy = ação em andamento (DEPOIS do clique): o Spinner e o disabled vêm do botão. `icon` recebe o
-elemento do ícone e o dimensiona pelo `size`; com icon, o Spinner TROCA o ícone (não soma). Não
-confunda com carregar conteúdo (ANTES) — isso é `DataState` ou `Skeleton` em um nível de página.
+`busy` indica que a ação já foi acionada e ainda está em andamento: o botão mostra um
+[`Spinner`](/ui/spinner) e fica desabilitado até a conclusão. `icon` recebe o elemento do ícone e o
+dimensiona pelo `size`; com `busy`, o spinner ocupa o lugar do ícone, sem alterar a largura. Para o
+carregamento de conteúdo antes de qualquer ação, use [`DataState`](/ui/data-state) ou
+[`Skeleton`](/ui/skeleton).
 
 ```tsx preview
 <Button disabled>Desabilitado</Button>
 <Button busy>Salvando…</Button>
-<Button icon={<Plus />}>Novo</Button>
-<Button icon={<Plus />} busy>Novo</Button>
+<Button icon={<Download />}>Exportar</Button>
+<Button icon={<Download />} busy>Exportar</Button>
 ```
 
 ## Como outro elemento (asChild)
 
-Âncora com cara de botão: asChild renderiza o filho (Radix Slot) — sem forkar estilo.
-buttonVariants serve para o caso sem filho único.
+Quando a ação navega para outro endereço, o elemento correto é um link, mesmo que ele precise da
+aparência de botão. Com `asChild`, o `Button` aplica seus estilos ao filho, como um `<a>` ou o link
+do roteador, sem criar uma cópia das classes. Quando não houver um único filho para receber os
+estilos, use `buttonVariants` para obter as classes.
 
 ```tsx preview
 <Button asChild variant="outline">
@@ -90,20 +109,20 @@ buttonVariants serve para o caso sem filho único.
 | `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 Spinner + desabilita. Não é "carregando" de conteúdo (que é Spinner/Skeleton em um nível de página). |
-| `icon`      | `React.ReactNode`                                                                    |             | Ícone à esquerda, como nó (ex.: `icon={<Plus />}`); o glifo segue o `size`. No busy é trocado pelo Spinner — não soma.                            |
+| `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
 
-Use `ButtonGroup` para manter ações relacionadas juntas. No modo `connected`, que permanece como
-padrão, as bordas internas colapsam e somente as pontas externas ficam arredondadas. Mantenha a
+Use `ButtonGroup` para manter ações relacionadas juntas. No modo `connected`, o padrão, as
+bordas internas colapsam e somente as pontas externas ficam arredondadas. Mantenha a
 mesma variante nos filhos para preservar a unidade visual.
 
 ```tsx preview
 <ButtonGroup>
   <Button variant="outline">Visão geral</Button>
-  <Button variant="outline">Sessões</Button>
-  <Button variant="outline">Habilidades</Button>
+  <Button variant="outline">Histórico</Button>
+  <Button variant="outline">Anexos</Button>
 </ButtonGroup>
 ```
 
@@ -111,7 +130,7 @@ mesma variante nos filhos para preservar a unidade visual.
 
 Use `mode="spaced"` quando os controles pertencem ao mesmo conjunto, mas cada um precisa preservar
 sua própria forma e superfície de hover. O grupo aplica o intervalo compacto de `0.25rem` sem
-conectar bordas. Esse modo atende ações icon-only em barras e linhas de listagem.
+conectar bordas. Esse modo atende ações só com ícone em barras e linhas de listagem.
 
 ```tsx preview
 <ButtonGroup mode="spaced">
@@ -131,8 +150,7 @@ conectar bordas. Esse modo atende ações icon-only em barras e linhas de listag
 
 `DialogFooter` e `DrawerFooter` cuidam somente da faixa; envolva as decisões em um
 `ButtonGroup mode="spaced"`, que responde pelo agrupamento e pela distribuição. Por padrão, as
-ações preservam a largura do conteúdo e `Cancelar` usa `ghost`. Use `distribution="equal"` somente
-quando as duas decisões tiverem peso equivalente; nesse caso, `Cancelar` usa `outline`.
+ações preservam a largura do conteúdo e `Cancelar` usa `ghost`.
 
 ```tsx
 <DialogFooter>
@@ -145,6 +163,18 @@ quando as duas decisões tiverem peso equivalente; nesse caso, `Cancelar` usa `o
 </DialogFooter>
 ```
 
+Use `distribution="equal"` somente quando as duas decisões tiverem peso equivalente, como em uma
+confirmação. As ações dividem a largura disponível; use `outline` no `Cancelar`.
+
+```tsx preview col
+<div className="w-80">
+  <ButtonGroup mode="spaced" distribution="equal">
+    <Button context="neutral" variant="outline">Cancelar</Button>
+    <Button context="danger">Excluir</Button>
+  </ButtonGroup>
+</div>
+```
+
 ### Ação dividida
 
 Combine a ação principal, um separador e um botão de ícone quando o mesmo comando oferecer
@@ -152,9 +182,9 @@ variações.
 
 ```tsx preview
 <ButtonGroup>
-  <Button icon={<Play />}>Rodar agente developer</Button>
+  <Button icon={<Download />}>Exportar relatório</Button>
   <ButtonGroupSeparator />
-  <Button size="icon" aria-label="Mais opções">
+  <Button size="icon" aria-label="Mais formatos de exportação">
     <ChevronDown />
   </Button>
 </ButtonGroup>
@@ -168,11 +198,11 @@ semântica de outro elemento, como `label`.
 ```tsx preview
 <ButtonGroup>
   <ButtonGroupText>
-    <GitBranch />
-    empresa-x-api
+    <CalendarDays />
+    Junho de 2026
   </ButtonGroupText>
   <Button variant="outline" icon={<RotateCw />}>
-    Sincronizar
+    Atualizar
   </Button>
 </ButtonGroup>
 ```
@@ -183,14 +213,14 @@ semântica de outro elemento, como `label`.
 
 ```tsx preview col-start
 <ButtonGroup orientation="vertical">
-  <Button variant="outline" size="icon" aria-label="Rodar sessão">
-    <Play />
+  <Button variant="outline" size="icon" aria-label="Ampliar">
+    <ZoomIn />
   </Button>
-  <Button variant="outline" size="icon" aria-label="Pausar sessão">
-    <Pause />
+  <Button variant="outline" size="icon" aria-label="Reduzir">
+    <ZoomOut />
   </Button>
-  <Button variant="outline" size="icon" aria-label="Reiniciar sessão">
-    <RotateCw />
+  <Button variant="outline" size="icon" aria-label="Restaurar zoom">
+    <RotateCcw />
   </Button>
 </ButtonGroup>
 ```