@softize/opus 12.2.1 → 12.4.0

package/CHANGELOG.md

@@ -7,6 +7,48 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.4.0 — 2026-08-24
+
+Superfícies de trabalho — canvas, editor, preview — ganham os dois lugares que faltavam. `Dock`
+ancora as ferramentas à própria superfície, com `DockGroup` separando intenções e `DockAction`
+distinguindo modo de execução; a barra é uma `toolbar` de verdade, com setas e Home/End entre as
+ações. `SurfaceStatus` recebe o que a superfície diz sobre si — salvamento, versão, execução
+percorrida — num canto estável, fora da barra: estado não é ação, e uma toolbar que carrega texto
+vivo deixa de ser navegável como toolbar.
+
+O truncamento passa a ter uma segunda forma. `Truncate` aceita `fade`, e a utilitária
+`truncate-fade` esmaece o fim da linha no lugar das reticências. O hook `useOverflowing`, extraído
+do próprio `Truncate`, fica exposto para quem precisa do sinal de corte sem o tooltip — é o que
+mantém a máscara fora do texto que cabe inteiro.
+
+`SidebarItem` vira a linha das árvores de navegação: `actions`, `onToggle`/`expanded` e
+`dropPosition` são irmãos do destino, nunca botões aninhados, e o rótulo cortado esmaece até a
+borda. Ele e o item do `ShellNav` também ganham foco visível com o anel do `Button` — antes a
+navegação por teclado caía no anel do navegador, que destoa do tema.
+
+Entram ainda `Dot`, para estado compacto onde o contexto já explica o significado, e
+`Table variant="framed"`, que traz para o componente a moldura de datagrid antes montada à mão em
+cada consumidor. `Select` passa a aplicar `className` na raiz do controle em todos os modos.
+
+O `opus copy` reconhece `Dock.label`, `DockAction.label` e `DockAction.hint`: componente com texto
+em prop precisa entrar no mapa de papéis, senão a copy sai do inventário em silêncio quando uma
+superfície migra de `aria-label` para prop.
+
+Tudo é aditivo e não exige migração. Consumidores que montavam a moldura da tabela à mão podem
+trocar o wrapper por `variant="framed"` quando quiserem.
+
+## 12.3.0 — 2026-08-23
+
+O Opus deixa de definir `font-size` em `html`. A fonte raiz volta a pertencer ao navegador e à
+aplicação, enquanto texto, espaçamento, arredondamento, foco, elevação e limites dimensionais da
+UI usam uma escala relativa em `rem`. Assim, preferências de acessibilidade e identidades próprias
+conseguem ajustar a densidade do documento sem disputar com o tema da biblioteca.
+
+A mudança é visual e não exige migração de API. Sem uma regra do consumidor, `1rem` segue a
+configuração do navegador. Aplicações que desejarem conservar a proporção anterior podem definir
+`html { font-size: 93.75%; }` no próprio CSS. `px` permanece apenas em hairlines e compensações
+geométricas inventariadas por teste.
+
 ## 12.2.1 — 2026-08-23
 
 O cabeçalho de `Page` passa a alinhar `actions` à base do bloco formado por título e descrição.

package/bin/cli.mjs

@@ -509,8 +509,8 @@ Fundação de UI (só apps web — preset Tailwind + tema + flags do Opus):
   tema/tsconfig/dep — avisa o que falta plugar (não edita seus arquivos: sem clobber)
 
 Este comando materializa somente os artefatos Opus. O template encadeia
-\`opus setup && base setup\`: a Base 2.0 é obrigatória quando o gate universal de copy
-está habilitado; Maestro continua opcional.
+\`opus setup && base setup\`: a versão da Base registrada em base.json é obrigatória quando
+o gate universal de copy está habilitado; Maestro continua opcional.
 `)
       return
     }

package/bin/lib/copy.mjs

@@ -130,6 +130,10 @@ const JSX_PROP_ROLES = new Map([
   ['Alert', new Map([['title', 'title'], ['description', 'message']])],
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
   ['DataState', new Map([['emptyText', 'empty-state'], ['errorText', 'error']])],
+  // A Dock nomeia a barra e cada ação por prop. Sem estas linhas, a copy sairia do inventário
+  // exatamente quando uma superfície migra de <Button aria-label> para <DockAction label>.
+  ['Dock', new Map([['label', 'label']])],
+  ['DockAction', new Map([['label', 'label'], ['hint', 'description']])],
   ['Input', new Map([['placeholder', 'placeholder']])],
   ['InputGroupInput', new Map([['placeholder', 'placeholder']])],
   ['InputGroupTextarea', new Map([['placeholder', 'placeholder']])],

package/docs/elevation-scale.md

@@ -20,6 +20,8 @@ uma superfície que precisava apenas de mais presença acabava recebendo um nome
 - O Opus declara a composição diretamente em `--shadow-*`, mantendo a progressão do
   Tailwind com camadas mais claras, difusas e spread negativo. Sem variável intermediária,
   modifiers nativos como `shadow-xl/30` continuam funcionando.
+- Deslocamento, desfoque e spread usam `rem`, portanto a elevação acompanha a escala raiz
+  escolhida pelo documento.
 - Componentes escolhem a intensidade pelo contexto: `sm` para repouso, `md` para
   flutuantes e `lg` para modais ou destaques fortes. Essa associação é default, não uma
   restrição semântica.

package/docs/radius-scale.md

@@ -18,6 +18,7 @@ voltaria a acoplar forma e tipo de componente, problema removido na versão 10.0
 
 - `--radius` passa a `0.75rem`. Aplicações podem sobrescrever essa base para ajustar a identidade
   inteira sem forkar componentes.
+- Os offsets da escala também usam `rem`, acompanhando a fonte raiz escolhida pelo documento.
 - `rounded-xs` até `rounded-2xl` formam uma progressão derivada da mesma base. `rounded-full`
   continua reservado a círculos e variantes explicitamente pill.
 - Componentes escolhem o degrau pela escala visual. Em geral, detalhes e itens internos usam

package/docs/relative-unit-scale.md

@@ -0,0 +1,55 @@
+# Escala relativa e fonte raiz
+
+> **Status: decidido (ago/2026).** O documento define a fonte raiz; o Opus organiza sua
+> escala visual em `rem` e não altera essa escolha.
+
+## Contexto
+
+O tema do Opus fixava `font-size: 15px` em `html`. Isso tornava a densidade uniforme, mas
+também fazia uma biblioteca decidir a tipografia raiz de toda a aplicação. A regra alcançava
+conteúdo que não pertencia ao Opus, reduzia a preferência do navegador e obrigava o consumidor
+a desfazer o tema antes de escolher sua própria escala.
+
+Parte das medidas visuais ainda usava `px`. Radius, elevação, foco, limites de conteúdo e texto
+compacto deixavam de acompanhar a raiz mesmo quando a aplicação assumia essa responsabilidade.
+
+## Decisão
+
+- O tema do Opus não declara `font-size` em `html` nem em `:root`. O navegador e a aplicação
+  definem a fonte raiz.
+- Medidas que pertencem à identidade e à escala da interface usam `rem`, diretamente ou pela
+  escala do Tailwind, que também é relativa à raiz.
+- Aplicações ajustam a densidade no próprio CSS. Para conservar a proporção que antes resultava
+  de uma raiz de 15 sobre a base usual de 16, podem usar `html { font-size: 93.75%; }`.
+- `px` fica restrito a encaixes técnicos que não devem crescer com a tipografia: espessura de
+  hairline, compensação exata de uma borda, ajuste óptico preso a esse traço e o raio efetivamente
+  infinito do scrollbar nativo. Cada ocorrência integra a allowlist do teste de contrato.
+- Valores históricos no changelog podem continuar em `px`, pois descrevem versões anteriores;
+  eles não definem o contrato vigente.
+
+## Consequências
+
+- Sem uma regra da aplicação, `1rem` segue a configuração do navegador. A UI pode ficar maior
+  para consumidores que recebiam os antigos 15px; essa mudança é visual e intencional.
+- Preferências de acessibilidade e identidades próprias deixam de disputar com um override da
+  biblioteca.
+- Alterar a raiz na aplicação escala texto, espaçamento, radius, foco, elevação e limites
+  dimensionais do Opus como um conjunto.
+- Hairlines e compensações de borda permanecem nítidas e geometricamente estáveis.
+
+## Alternativas descartadas
+
+- **Manter 15px como default:** conserva a densidade anterior, mas mantém a biblioteca como dona
+  do documento inteiro.
+- **Declarar `font-size: 100%`:** costuma reproduzir o default, mas ainda é uma opinião redundante
+  e pode sobrescrever uma decisão anterior da aplicação.
+- **Converter também hairlines para `rem`:** torna a regra absoluta, mas permite que bordas e
+  compensações deixem de coincidir quando a raiz muda.
+
+## Verificação
+
+- Um teste de contrato confirma que o tema não define a fonte raiz.
+- O mesmo teste inventaria `px` no código vivo da UI e reprova qualquer ocorrência fora da
+  allowlist técnica.
+- Testes de radius e elevação validam as fórmulas em `rem`.
+- A documentação de tokens e a skill `build-opus-ui` orientam a responsabilidade do consumidor.

package/docs/releasing.md

@@ -53,7 +53,7 @@ pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
 `pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.0.0` em `dependencies`, pois usa
+se qualquer um falhar**. O Opus declara `@softize/base ^2.1.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
@@ -63,7 +63,7 @@ um `tsc` vermelho, inventário desatualizado ou violação da política vaza pro
 **Smoke do esqueleto**: depois do bump e antes do publish, o `release.sh` gera um app com
 `opus create`, instala o **tarball exato** que vai ser publicado e roda os gates dele
 (typecheck · test · `opus check` · `opus copy --check` · `base copy check` · manifest ·
-build). O template exige `@softize/base ^2.0.0`; publique a Base compatível antes do Opus.
+build). O template exige `@softize/base ^2.1.0`; publique a Base compatível antes do Opus.
 O `minimumReleaseAgeExclude` do template inclui os dois pacotes, e o smoke executa os
 fragmentos de pre-push para provar que o layout pnpm instalado resolve ambos os CLIs.
 É o que pega o que typecheck+test não

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.2.1",
+  "version": "12.4.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -201,7 +201,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@softize/base": "^2.0.0",
     "@radix-ui/react-checkbox": "^1.1.3",
     "@radix-ui/react-dialog": "^1.1.4",
     "@radix-ui/react-dropdown-menu": "^2.1.4",
@@ -211,6 +210,7 @@
     "@radix-ui/react-slot": "^1.1.1",
     "@radix-ui/react-tabs": "^1.1.2",
     "@radix-ui/react-tooltip": "^1.1.6",
+    "@softize/base": "^2.1.0",
     "@tailwindcss/typography": "^0.5.20",
     "@types/markdown-it": "^14.1.2",
     "class-variance-authority": "^0.7.1",
@@ -234,11 +234,11 @@
     "zod-to-json-schema": "^3.23.0"
   },
   "peerDependencies": {
-    "@opentelemetry/api": "^1.9.0",
     "@anthropic-ai/sdk": ">=0.35.0",
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/s3-request-presigner": "^3.0.0",
     "@hookform/resolvers": "^3.0.0",
+    "@opentelemetry/api": "^1.9.0",
     "@tanstack/react-query": "^5.0.0",
     "bullmq": "^5.0.0",
     "fastify": "^5.0.0",

package/registry/skills/build-opus-ui/SKILL.md

@@ -19,18 +19,22 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    o produto precisa de deep link, back/forward ou refresh.
 4. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
-5. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
-6. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
+5. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
+   responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
+   relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
+   com justificativa e cobertura explícitas.
+6. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
+7. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
    `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da
    igualdade atual com `--foreground`, porque o app pode sobrescrever cada par.
-7. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
+8. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
    `rounded-xs` a `rounded-2xl` já expressam a forma. Escolher o degrau pela escala visual:
    detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
    molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação
    orienta o default, não cria uma restrição semântica. Em aninhamento, evitar moldura dupla e
    reduzir o raio interno; em grupos conectados, remover os raios das arestas internas. Tamanho
    e forma permanecem eixos separados; usar `shape="pill"` quando a pílula for intencional.
-8. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+9. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
 
 ## Verificação
 

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -5,6 +5,8 @@
   operação, não a uma tela isolada.
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
+- A fonte raiz pertence ao navegador e à aplicação. Medidas escaláveis usam `rem` ou a escala
+  relativa do Tailwind; `px` fica restrito a hairlines e compensações ligadas a essas bordas.
 - Superfície semântica e foreground são um par local (`bg-card text-card-foreground`,
   `bg-popover text-popover-foreground`); herança do foreground global não substitui o par.
 - Forma usa a escala `rounded-*`; nome de componente não cria uma segunda escala de radius.

package/registry/templates/app/package.json

@@ -30,7 +30,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@softize/base": "^2.0.0",
+    "@softize/base": "^2.1.0",
     "@tailwindcss/vite": "^4.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",

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

@@ -0,0 +1,182 @@
+/**
+ * <Dock /> — a barra de ferramentas que flutua sobre uma superfície de trabalho.
+ *
+ * Canvas, editor e preview têm o mesmo problema: as ferramentas não cabem num cabeçalho
+ * sem empilhar mais uma faixa de chrome sobre a trilha que a aplicação já desenha. A Dock
+ * resolve isso ancorando as ações à própria superfície, agrupadas e sempre visíveis.
+ *
+ * O componente é dono da moldura, dos separadores entre grupos, da forma dos botões e da
+ * semântica de toolbar (`role="toolbar"` com navegação por setas). QUAIS ferramentas
+ * existem e o que cada uma faz continua sendo da aplicação.
+ *
+ * Requer `<TooltipProvider>` na raiz do app — cada ação nomeia-se por tooltip.
+ */
+
+import * as React from 'react'
+import { cn } from '../../lib/cn.ts'
+import { Button } from '../primitives/button.tsx'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../primitives/tooltip.tsx'
+
+const POSITION = {
+  bottom: 'bottom-3 left-1/2 -translate-x-1/2',
+  'bottom-left': 'bottom-3 left-3',
+  'bottom-right': 'bottom-3 right-3',
+} as const
+
+export interface DockProps {
+  /** Aresta da superfície onde a barra se ancora. */
+  position?: keyof typeof POSITION
+  /** Nome acessível da barra; é o que a tecnologia assistiva anuncia ao entrar nela. */
+  label: string
+  className?: string
+  children: React.ReactNode
+}
+
+/** Barra flutuante ancorada à superfície. O contêiner precisa ser `relative`. */
+export function Dock({ position = 'bottom', label, className, children }: DockProps): React.ReactElement {
+  const ref = React.useRef<HTMLDivElement>(null)
+
+  // Navegação de toolbar: as setas andam entre as ações, e Home/End vão às pontas. Sem isso
+  // uma barra com dez ícones cobra dez Tabs de quem navega por teclado.
+  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>): void => {
+    const keys = ['ArrowRight', 'ArrowLeft', 'Home', 'End']
+    if (!keys.includes(event.key) || ref.current === null) return
+    const items = Array.from(ref.current.querySelectorAll<HTMLButtonElement>('button:not([disabled])'))
+    if (items.length === 0) return
+    const current = items.indexOf(document.activeElement as HTMLButtonElement)
+    if (current === -1) return
+    event.preventDefault()
+    const next =
+      event.key === 'Home'
+        ? 0
+        : event.key === 'End'
+          ? items.length - 1
+          : event.key === 'ArrowRight'
+            ? (current + 1) % items.length
+            : (current - 1 + items.length) % items.length
+    items[next]?.focus()
+  }
+
+  return (
+    <div
+      ref={ref}
+      data-slot="dock"
+      role="toolbar"
+      aria-label={label}
+      aria-orientation="horizontal"
+      onKeyDown={onKeyDown}
+      className={cn(
+        'absolute z-10 flex max-w-[calc(100%-1.5rem)] flex-row items-center gap-1.5 overflow-x-auto',
+        'rounded-2xl border border-border bg-background/95 p-1.5 shadow-lg backdrop-blur',
+        POSITION[position],
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/** Grupo de ações afins. A divisória entre grupos é do componente, não do consumidor. */
+export function DockGroup({ className, children }: { className?: string; children: React.ReactNode }): React.ReactElement {
+  return (
+    <div
+      data-slot="dock-group"
+      className={cn(
+        'flex shrink-0 flex-row items-center gap-1 border-l border-border pl-1.5',
+        'first:border-l-0 first:pl-0',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+export interface DockActionProps {
+  icon: React.ReactNode
+  /** Nome da ação: vai para o tooltip e para o nome acessível. */
+  label: string
+  /** Presente quando a ação liga um modo; ausente quando ela apenas executa. */
+  pressed?: boolean
+  disabled?: boolean
+  /** Conteúdo do tooltip quando ele precisa dizer mais que o rótulo. */
+  hint?: React.ReactNode
+  className?: string
+  onClick: () => void
+}
+
+/** Ação de ícone da Dock. Com `pressed`, comunica modo ligado em vez de execução. */
+export function DockAction({ icon, label, pressed, disabled = false, hint, className, onClick }: DockActionProps): React.ReactElement {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          data-slot="dock-action"
+          size="icon"
+          variant={pressed === true ? 'default' : 'ghost'}
+          aria-label={label}
+          aria-pressed={pressed}
+          disabled={disabled}
+          onClick={onClick}
+          className={cn('size-9 shrink-0 rounded-xl', className)}
+        >
+          {icon}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent>{hint ?? label}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+const STATUS_POSITION = {
+  'top-right': 'top-3 right-3',
+  'top-left': 'top-3 left-3',
+} as const
+
+export interface SurfaceStatusProps {
+  /** Canto da superfície onde o estado se ancora. */
+  position?: keyof typeof STATUS_POSITION
+  /** Ações do recurso aberto — em geral o mesmo menu que a linha dele tem na navegação. */
+  actions?: React.ReactNode
+  className?: string
+  children?: React.ReactNode
+}
+
+/**
+ * O que a superfície diz sobre SI — salvamento, versão, execução percorrida — flutuando no canto,
+ * separado das ferramentas. Fica fora da Dock de propósito: estado não é ação, e uma toolbar que
+ * carrega texto vivo deixa de ser navegável como toolbar.
+ *
+ * A região é `role="status"` com `aria-live="polite"`: a mudança é anunciada sem roubar o foco.
+ * Mensagem de sucesso é transitória por natureza; falha permanece até o estado mudar. Quem decide
+ * isso é a aplicação, que conhece o ciclo — o componente só reserva o lugar.
+ */
+export function SurfaceStatus({ position = 'top-right', actions, className, children }: SurfaceStatusProps): React.ReactElement {
+  const hasActions = actions !== undefined && actions !== null
+  return (
+    <div
+      data-slot="surface-status"
+      className={cn(
+        'pointer-events-none absolute z-10 flex max-w-[calc(100%-1.5rem)] flex-row items-center gap-2',
+        'rounded-full border border-border bg-background/95 py-1.5 pl-3 text-xs text-muted-foreground shadow-sm backdrop-blur',
+        hasActions ? 'pr-1' : 'pr-3',
+        STATUS_POSITION[position],
+        className,
+      )}
+    >
+      {/* Só o texto é região viva: anunciar o menu a cada mudança de estado seria ruído. */}
+      <span role="status" aria-live="polite" className="flex min-w-0 flex-row items-center gap-2">
+        {children}
+      </span>
+      {hasActions && (
+        <span
+          data-slot="surface-status-actions"
+          className="pointer-events-auto flex shrink-0 items-center [&_button]:size-6 [&_button]:rounded-full [&_svg]:size-3.5"
+        >
+          {actions}
+        </span>
+      )}
+    </div>
+  )
+}

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

@@ -74,6 +74,7 @@ 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',
         railed ? 'justify-center px-0' : 'px-2.5',
         active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60',
       )}

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

@@ -1,4 +1,6 @@
-import { createContext, useContext, type ReactNode } from 'react'
+import { createContext, useContext, type HTMLAttributes, type ReactNode } from 'react'
+import { ChevronRight } from 'lucide-react'
+import { useOverflowing } from '../../lib/overflow.ts'
 import { cn } from '../../lib/cn.ts'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
 
@@ -50,22 +52,58 @@ export interface SidebarItemProps {
   badge?: ReactNode
   active?: boolean
   disabled?: boolean
+  /** Controles irmãos do alvo de navegação (ex.: menu de ações). */
+  actions?: ReactNode
+  /** Presente quando a linha desdobra filhos; o controle fica fora do botão principal. */
+  onToggle?: () => void
+  expanded?: boolean
+  /** Posição indicada durante drag-and-drop; bordas inserem, centro recebe dentro. */
+  dropPosition?: 'before' | 'inside' | 'after'
+  /** Props de drag-and-drop aplicadas à linha, sem acoplar a um driver. */
+  dragProps?: HTMLAttributes<HTMLDivElement>
+  /** Complemento do tooltip no rail recolhido. */
+  tooltipHint?: ReactNode
   className?: string
   onClick: () => void
 }
 
-/** Item de navegação que se adapta ao colapso da Sidebar em que está. */
-export function SidebarItem({ label, icon, badge, active = false, disabled = false, className, onClick }: SidebarItemProps): React.ReactElement {
+/** Linha única de navegação: o alvo principal e seus controles são irmãos, nunca botões aninhados. */
+export function SidebarItem({ label, icon, badge, active = false, disabled = false, actions, onToggle, expanded = false, dropPosition, dragProps, tooltipHint, className, onClick }: SidebarItemProps): React.ReactElement {
   const collapsed = useSidebarCollapsed()
-  const button = (
-    <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} onClick={onClick} className={cn('flex items-center gap-2.5 rounded-md transition-colors', 'disabled:pointer-events-none disabled:opacity-40', collapsed ? 'mx-auto size-9 justify-center p-0' : 'w-full px-2.5 py-1.5 text-left text-sm', active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60', className)}>
-      {icon !== undefined && <span className="flex shrink-0">{icon}</span>}
-      {!collapsed && <span className="min-w-0 flex-1 truncate">{label}</span>}
-      {!collapsed && badge !== undefined && <span className="shrink-0">{badge}</span>}
-    </button>
+  const hasActions = actions !== undefined && actions !== null
+  // O rótulo cortado esmaece em vez de terminar em reticências; a medição do transbordo
+  // mantém a máscara fora do rótulo que cabe inteiro na linha.
+  const { ref: labelRef, overflowing: labelCut } = useOverflowing<HTMLSpanElement>(label)
+  if (collapsed) {
+    const button = (
+      <button type="button" disabled={disabled} 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', active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60', className)}>
+        {icon}
+      </button>
+    )
+    return <div {...dragProps}><Tooltip><TooltipTrigger asChild>{button}</TooltipTrigger><TooltipContent side="right">{label}{tooltipHint}</TooltipContent></Tooltip></div>
+  }
+
+  return (
+    <div data-slot="sidebar-item" className={cn('group/sidebar-item relative flex items-center rounded-md transition-colors', disabled ? 'text-muted-foreground/50 opacity-40' : 'hover:bg-muted/60', active && 'bg-muted', dropPosition === 'inside' && 'bg-primary/5 ring-2 ring-inset ring-primary/60', className)} {...dragProps}>
+      {(dropPosition === 'before' || dropPosition === 'after') && <span data-slot="sidebar-item-drop-indicator" className={cn('pointer-events-none absolute inset-x-1 z-20 h-0.5 rounded-full bg-primary before:absolute before:-left-1 before:top-1/2 before:size-2 before:-translate-y-1/2 before:rounded-full before:border-2 before:border-primary before:bg-background', dropPosition === 'before' ? '-top-px' : '-bottom-px')} />}
+      {icon !== undefined && (
+        <span data-slot="sidebar-item-leading" className="pointer-events-none absolute left-2.5 top-1/2 z-10 grid size-4 -translate-y-1/2 place-items-center">
+          <span className={cn('absolute inset-0 flex items-center justify-center transition-opacity', onToggle !== undefined && 'group-hover/sidebar-item:opacity-0 group-has-[[data-slot=sidebar-item-toggle]:focus-visible]/sidebar-item:opacity-0')}>{icon}</span>
+          {onToggle !== undefined && (
+            <button type="button" data-slot="sidebar-item-toggle" onClick={onToggle} aria-label={expanded ? `Fechar ${label}` : `Abrir ${label}`} aria-expanded={expanded} className="pointer-events-none absolute inset-0 grid place-items-center rounded-sm text-muted-foreground opacity-0 transition-[color,opacity] outline-none hover:text-foreground group-hover/sidebar-item:pointer-events-auto group-hover/sidebar-item:opacity-100 focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-ring/50">
+              <ChevronRight className={cn('size-3 transition-transform', expanded && 'rotate-90')} />
+            </button>
+          )}
+        </span>
+      )}
+      <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} 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', disabled ? 'text-muted-foreground/50' : active ? 'font-medium text-foreground' : 'text-foreground/80')}>
+        {icon !== undefined && <span data-slot="sidebar-item-leading-space" aria-hidden className="size-4 shrink-0" />}
+        <span ref={labelRef} data-slot="sidebar-item-label" className={cn('min-w-0 flex-1 overflow-hidden whitespace-nowrap group-has-[[data-slot=dot]]/sidebar-item:mr-[1.1875rem]', labelCut && 'truncate-fade')}>{label}</span>
+        {badge !== undefined && <span data-slot="sidebar-item-badge" className={cn('shrink-0 transition-opacity has-[[data-slot=dot]]:absolute has-[[data-slot=dot]]:right-1 has-[[data-slot=dot]]:top-1/2 has-[[data-slot=dot]]:z-10 has-[[data-slot=dot]]:grid has-[[data-slot=dot]]:size-6 has-[[data-slot=dot]]:-translate-y-1/2 has-[[data-slot=dot]]:place-items-center', hasActions && 'group-hover/sidebar-item:has-[[data-slot=dot]]:opacity-0')}>{badge}</span>}
+      </button>
+      {hasActions && <div data-slot="sidebar-item-actions" className="pointer-events-none absolute right-1 top-1/2 z-10 flex -translate-y-1/2 items-center opacity-0 transition-opacity group-hover/sidebar-item:pointer-events-auto group-hover/sidebar-item:opacity-100 has-[:focus-visible]:pointer-events-auto has-[:focus-visible]:opacity-100 has-[[data-state=open]]:pointer-events-auto has-[[data-state=open]]:opacity-100 [&_button]:grid [&_button]:size-6 [&_button]:place-items-center [&_button]:p-0 [&_svg]:size-3.5">{actions}</div>}
+    </div>
   )
-  if (!collapsed) return button
-  return <Tooltip><TooltipTrigger asChild>{button}</TooltipTrigger><TooltipContent side="right">{label}</TooltipContent></Tooltip>
 }
 
 export interface SidebarNavGroup {
@@ -86,6 +124,11 @@ const subFilled = (subgroup: SidebarNavSubgroup): boolean => subgroup.items.leng
 const groupFilled = (group: SidebarNavGroup): boolean =>
   (group.items?.length ?? 0) > 0 || (group.subgroups?.some(subFilled) ?? false)
 
+/** Rótulo discreto de um grupo de navegação, compartilhado por listas e árvores. */
+export function SidebarGroupLabel({ className, children }: { className?: string; children: ReactNode }): React.ReactElement {
+  return <div data-slot="sidebar-group-label" className={cn('px-2.5 pb-1 text-sm font-medium text-muted-foreground/70', className)}>{children}</div>
+}
+
 /** Navegação controlada para Sidebar. Header/footer continuam slots explícitos do pai. */
 export function SidebarNav({ groups, activeId, onSelect, navLabel = 'Navegação', className }: { groups: SidebarNavGroup[]; activeId?: string; onSelect: (id: string) => void; navLabel?: string; className?: string }): React.ReactElement {
   const collapsed = useSidebarCollapsed()
@@ -101,10 +144,10 @@ export function SidebarNav({ groups, activeId, onSelect, navLabel = 'Navegação
   const body = (
     <nav aria-label={navLabel} data-slot="sidebar-nav" className={cn('space-y-4 p-2', className)}>
       {groups.map((group, gi) => !groupFilled(group) ? null : <div key={gi} className="space-y-0.5">
-        {!collapsed && titled(group.label) && <div className="px-2.5 pb-1 text-xs font-medium text-muted-foreground/70">{group.label}</div>}
+        {!collapsed && titled(group.label) && <SidebarGroupLabel>{group.label}</SidebarGroupLabel>}
         {group.items?.map((item) => renderItem(item))}
         {group.subgroups?.map((subgroup, si) => !subFilled(subgroup) ? null : <div key={si} className="space-y-0.5">
-          {!collapsed && titled(subgroup.label) && <div className="pb-0.5 pl-4 pr-2.5 pt-1.5 text-[11px] font-medium text-muted-foreground/50">{subgroup.label}</div>}
+          {!collapsed && titled(subgroup.label) && <div className="pb-0.5 pl-4 pr-2.5 pt-1.5 text-[0.6875rem] font-medium text-muted-foreground/50">{subgroup.label}</div>}
           {subgroup.items.map((item) => renderItem(item, titled(subgroup.label)))}
         </div>)}
       </div>)}

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

@@ -33,7 +33,7 @@ function AccordionTrigger({
       <AccordionPrimitive.Trigger
         data-slot="accordion-trigger"
         className={cn(
-          "flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180",
+          "flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180",
           className
         )}
         {...props}

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

@@ -31,11 +31,11 @@ export const buttonVariants = cva(
         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',
-        // Ícone na escala `sm` (32px) — o par do `sm` pra fileiras densas (toolbar, header)
-        // onde os irmãos são sm. Sem ele, um botão de ícone ao lado de controles sm ficava
-        // 4px mais alto ou virava override na mão.
+        // Ícone na escala `sm` (2rem) — o par do `sm` para fileiras densas, onde os irmãos
+        // também usam `sm`. Sem ele, um botão de ícone ao lado desses controles ficava
+        // 0.25rem mais alto ou virava override local.
         'icon-sm': 'size-8',
-        // Ícone MENOR (24px) — a ação DENTRO de um campo (o clear/mostrar-senha no
+        // Ícone menor (1.5rem) — a ação dentro de um campo (clear/mostrar senha no
         // `trailing` do Input/Select), que precisa caber folgado num h-9. É o mesmo tamanho
         // do `icon-xs` do InputGroupButton; sem ele, o exemplo virava `className="size-6"`.
         'icon-xs': 'size-6',

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

@@ -72,7 +72,7 @@ function Calendar({
           defaultClassNames.dropdowns
         ),
         dropdown_root: cn(
-          "relative rounded-md border border-input has-focus:border-ring has-focus:ring-[3px] has-focus:ring-ring/50",
+          "relative rounded-md border border-input has-focus:border-ring has-focus:ring-[0.1875rem] has-focus:ring-ring/50",
           defaultClassNames.dropdown_root
         ),
         dropdown: cn(
@@ -206,7 +206,7 @@ function CalendarDayButton({
       data-range-end={modifiers.range_end}
       data-range-middle={modifiers.range_middle}
       className={cn(
-        "flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-accent-foreground [&>span]:text-xs [&>span]:opacity-70",
+        "flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[0.1875rem] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-accent-foreground [&>span]:text-xs [&>span]:opacity-70",
         defaultClassNames.day,
         className
       )}

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

@@ -136,7 +136,7 @@ const ChatTranscript = React.memo(function ChatTranscript({
       className="flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto p-4"
     >
       {items.length === 0 && !indicatorVisible && greeting !== undefined && (
-        <div data-slot="chat-empty" className="m-auto max-w-[280px] text-center text-muted-foreground">
+        <div data-slot="chat-empty" className="m-auto max-w-[17.5rem] text-center text-muted-foreground">
           <div className="mb-2 text-4xl">✦</div>
           <p className="text-sm leading-relaxed">{greeting}</p>
         </div>

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

@@ -12,7 +12,7 @@ function Checkbox({
     <CheckboxPrimitive.Root
       data-slot="checkbox"
       className={cn(
-        "peer size-4 shrink-0 rounded-[4px] border border-input transition-shadow outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground dark:bg-input/30 dark:aria-invalid:ring-destructive/40 dark:data-[state=checked]:bg-primary",
+        "peer size-4 shrink-0 rounded-[0.25rem] border border-input transition-shadow outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground dark:bg-input/30 dark:aria-invalid:ring-destructive/40 dark:data-[state=checked]:bg-primary",
         className
       )}
       {...props}

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

@@ -88,7 +88,7 @@ function CommandList({
     <CommandPrimitive.List
       data-slot="command-list"
       className={cn(
-        "max-h-[300px] scroll-py-1 overflow-x-hidden overflow-y-auto",
+        "max-h-[18.75rem] scroll-py-1 overflow-x-hidden overflow-y-auto",
         className
       )}
       {...props}