@softize/opus 12.9.0 → 12.10.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ 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.10.0 — 2026-09-03
+
+`Alert` ganha a variante aditiva `warning` e passa a oferecer realce tonal nativo ao redor do
+ícone. O layout com ícone reserva uma coluna estável; sem ícone, o aviso continua em bloco e não
+cria espaço vazio. `style` permite ajustar as medidas internas quando uma composição exigir.
+
+`FieldLabel` adota a mesma hierarquia tipográfica de `DetailField`, com ritmo vertical menor, e o
+estado marcado de uma escolha em cartão deixa de vazar para rótulos comuns com checkbox. Tooltips
+passam a ter largura máxima compartilhada e quebra de linha natural; `ActionForm` apenas consome
+esse padrão, sem decidir a largura do primitivo.
+
+`opus copy` passa a inventariar estaticamente `label`, `description` e `doc` declarados em
+`t.dict`, inclusive a documentação do dicionário. Metadados livres não viram copy por inferência;
+declarações dinâmicas continuam falhando no gate em vez de executar código consumidor. Em runtime,
+o dicionário mantém um snapshot imutável das entradas, então alterações posteriores no objeto
+original, em `metaFor` ou na metadata lógica não mudam a copy já declarada.
+
 ## 12.9.0 — 2026-09-03
 
 `Chat` aceita `empty`, um nó React para o estado sem mensagens: o app compõe o vazio com os

package/bin/lib/copy.mjs

@@ -1,7 +1,7 @@
 /**
- * Inventário semântico de copy dos contratos Opus.
+ * Inventário semântico de copy dos contratos e dicionários Opus.
  *
- * O Opus conhece o papel dos textos declarados em defineAction/defineContract;
+ * O Opus conhece o papel dos textos declarados em defineAction/defineContract e t.dict;
  * a @softize/base continua dona da política e da validação editorial. Este módulo
  * apenas projeta o protocolo JSON v2 sem executar código do consumidor.
  */
@@ -61,6 +61,7 @@ const COPY_ROLES = new Set([
 const AUDIT_REFERENCE = /^(?:https?:\/\/\S+|[a-z][a-z0-9-]*:\S+|(?:[A-Za-z0-9._-]+\/)+[A-Za-z0-9._#/-]+|[A-Za-z0-9._-]+\.(?:md|json|ya?ml)(?:#[^\s]+)?)$/u
 const CONTRACT_MODULES = new Set(['@softize/opus', '@softize/opus/core'])
 const CONTRACT_FACTORIES = new Set(['defineAction', 'defineContract'])
+const SCHEMA_ZOD_MODULES = new Set(['@softize/opus/schema/zod'])
 const ACTION_BINDING_KEYS = new Set(['authorize', 'background', 'emits', 'handler', 'idempotency', 'loads'])
 
 // Somente exports Opus cujo papel textual é estável por contrato do componente.
@@ -397,6 +398,18 @@ function knownContractFactory(call, checker) {
   return name !== null && CONTRACT_FACTORIES.has(name)
 }
 
+function knownDictionaryFactory(call, checker) {
+  const expression = resolveBinding(call.expression, checker)
+  if (!ts.isPropertyAccessExpression(expression) && !ts.isElementAccessExpression(expression)) return false
+  const member = ts.isPropertyAccessExpression(expression)
+    ? expression.name.text
+    : expression.argumentExpression === undefined
+      ? null
+      : staticText(expression.argumentExpression, checker)?.text ?? null
+  return member === 'dict' &&
+    importedMemberName(expression.expression, checker, (module) => SCHEMA_ZOD_MODULES.has(module)) === 't'
+}
+
 function knownBindAction(call, checker) {
   return importedMemberName(call.expression, checker, (module) => CONTRACT_MODULES.has(module)) === 'bindAction'
 }
@@ -512,7 +525,10 @@ function stableExpressionUse(node, checker, mode, stack) {
     ts.isSpreadAssignment(parent) || ts.isSpreadElement(parent) || ts.isArrayLiteralExpression(parent)
   ) return consumerMode === 'aggregate' && stableComposition(carrier, checker, stack)
   if (ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === carrier)) {
-    if (consumerMode === 'aggregate') return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
+    if (consumerMode === 'aggregate') {
+      if (knownDictionaryFactory(parent, checker)) return true
+      return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
+    }
     if (
       consumerMode === 'factory-result' && parent.arguments[0] === carrier &&
       knownBindAction(parent, checker) && safeBindActionBinding(parent, checker)
@@ -865,14 +881,15 @@ function diagnostic(file, sourceFile, node, field, category = 'content') {
 /**
  * Extrai as superfícies humanas de um source isolado.
  *
- * O retorno distingue arquivo sem contrato de contrato sem copy. Essa diferença é
- * necessária para hashear todo contrato e detectar a adição posterior de um texto.
+ * O retorno distingue arquivo sem superfície Opus de contrato sem copy. Essa diferença é
+ * necessária para hashear todo contrato ou dicionário e detectar a adição posterior de texto.
  */
 export function extractCopyFromSource(file, sourceText) {
   const { sourceFile, checker } = parseSource(file, sourceText)
   const entries = []
   const diagnostics = []
   let hasContract = false
+  let hasDictionary = false
   const hasUiImport = sourceFile.statements.some(
     (statement) =>
       ts.isImportDeclaration(statement) &&
@@ -999,6 +1016,42 @@ export function extractCopyFromSource(file, sourceText) {
     nestedObject(object, 'errors', (error, prefix) => addProperty(error, 'description', 'error', prefix))
   }
 
+  function extractDictionary(call) {
+    const entriesNode = call.arguments[0]
+    const entries = resolveBinding(entriesNode, checker)
+    if (!ts.isObjectLiteralExpression(entries)) {
+      diagnostics.push(diagnostic(file, sourceFile, entriesNode, 't.dict entries', 'structure'))
+      return
+    }
+
+    const listed = properties(entries, sourceFile, checker)
+    for (const opaque of listed.opaque) {
+      diagnostics.push(diagnostic(file, sourceFile, opaque, 't.dict entries', 'structure'))
+    }
+    for (const [key, entry] of listed.items) {
+      const valueNode = propertyValue(entry)
+      const value = resolveBinding(valueNode, checker)
+      if (!ts.isObjectLiteralExpression(value)) {
+        diagnostics.push(diagnostic(file, sourceFile, valueNode, `t.dict.${key}`, 'structure'))
+        continue
+      }
+      addProperty(value, 'label', 'label', `t.dict.${key}.`)
+      addProperty(value, 'description', 'description', `t.dict.${key}.`)
+      addProperty(value, 'doc', 'description', `t.dict.${key}.`)
+    }
+
+    if (call.arguments.length < 2) return
+    const optionsNode = call.arguments[1]
+    const options = resolveBinding(optionsNode, checker)
+    if (ts.isIdentifier(options) && options.text === 'undefined') {
+      const symbol = checker.getSymbolAtLocation(options)
+      const shadowed = symbol?.declarations?.some((declaration) => declaration.getSourceFile() === sourceFile) ?? false
+      if (!shadowed) return
+    }
+    if (ts.isObjectLiteralExpression(options)) addProperty(options, 'doc', 'description', 't.dict.options.')
+    else diagnostics.push(diagnostic(file, sourceFile, optionsNode, 't.dict options', 'structure'))
+  }
+
   function importedMember(node, modulePredicate) {
     return importedMemberName(node, checker, modulePredicate)
   }
@@ -1790,12 +1843,16 @@ export function extractCopyFromSource(file, sourceText) {
         else diagnostics.push(diagnostic(file, sourceFile, node.arguments[0], `${factory}(...)`, 'structure'))
       }
     }
+    if (ts.isCallExpression(node) && knownDictionaryFactory(node, checker) && node.arguments.length > 0) {
+      hasDictionary = true
+      extractDictionary(node)
+    }
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) extractJsx(node)
     ts.forEachChild(node, visit)
   }
   visit(sourceFile)
 
-  return { hasContract, hasCopySurface: hasContract || hasUiImport, entries, diagnostics }
+  return { hasContract, hasCopySurface: hasContract || hasDictionary || hasUiImport, entries, diagnostics }
 }
 
 function globRegex(pattern) {

package/docs/code-style.md

@@ -92,16 +92,20 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 | `Select.emptyText`, `Select.searchPlaceholder` | `empty-state`, `placeholder` |
 | `Select.options[].hint/triggerLabel/group` | `label`, `label`, `heading` |
 | `ActionTrigger.confirm.*` | papel correspondente do diálogo |
+| `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário | `label`, `description` |
 
 ## Cobertura e significado do gate verde
 
-O extrator cobre duas superfícies, sem heurística de nome:
+O extrator cobre três superfícies, sem heurística de nome:
 
 1. propriedades estáticas de `defineAction` e `defineContract` descritas acima, somente
    quando a factory resolve por símbolo a um import de `@softize/opus` ou
    `@softize/opus/core`; alias, namespace e destructuring `const` de namespace funcionam,
    homônimo local não é contrato;
-2. texto estático em filhos e props de uma allowlist de componentes importados diretamente
+2. `label`, `description` e `doc` estáticos de `t.dict` importado de
+   `@softize/opus/schema/zod`; metadata livre não é classificada por nome, declarações dinâmicas
+   reprovam em vez de serem executadas e o dicionário mantém um snapshot imutável das entradas;
+3. texto estático em filhos e props de uma allowlist de componentes importados diretamente
    de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogDescription`,
    `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
    continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.9.0",
+  "version": "12.10.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/schema/drivers/zod.ts

@@ -680,7 +680,7 @@ export interface DictType<K extends string, M extends DictEntryMeta> {
    */
   labelFor(key: K, locale?: string): string
   /** Meta completa da chave (label + extras). */
-  metaFor(key: K): M
+  metaFor(key: K): Readonly<M>
   /** Lista pronta pra `<Select options={...} />`: `{ value, ...meta }`. */
   options(): DictOption<K, M>[]
   /** True se `key` está no dict. */
@@ -707,7 +707,7 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
   opts?: DictOpts,
 ): DictType<Extract<keyof M, string>, M[keyof M]> => {
   type K = Extract<keyof M, string>
-  const keys = Object.keys(entries) as K[]
+  const keys = Object.freeze(Object.keys(entries)) as readonly K[]
   if (keys.length === 0) {
     throw new Error('t.dict precisa de pelo menos uma entrada')
   }
@@ -729,16 +729,22 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
       )
     }
   }
+  // O dicionário é declarativo: mantém um snapshot próprio e imutável para que `metaFor`,
+  // a metadata do schema e mutações posteriores no objeto de entrada não alterem a copy
+  // ou a apresentação que foram inventariadas no código-fonte.
+  const stableEntries = Object.freeze(
+    Object.fromEntries(keys.map((key) => [key, Object.freeze({ ...entries[key] })])),
+  ) as unknown as Readonly<M>
   const zodSchema = z.enum(keys as [K, ...K[]])
-  const meta: LogicalTypeMeta = {
+  const meta: LogicalTypeMeta = Object.freeze({
     logicalType: 'dict',
-    params: {
+    params: Object.freeze({
       keys,
-      entries,
+      entries: stableEntries,
       ...(opts?.doc !== undefined ? { doc: opts.doc } : {}),
       ...(opts?.presentation !== undefined ? { presentation: opts.presentation } : {}),
-    },
-  }
+    }),
+  })
   attachLogicalType(zodSchema as unknown as object, meta)
 
   return {
@@ -749,16 +755,16 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
     keys: () => [...keys],
     labelFor: (key, _locale) => {
       // _locale reservado pra i18n futuro; no v1 sempre retorna o label cru.
-      return (entries[key] as M[keyof M]).label
+      return (stableEntries[key] as M[keyof M]).label
     },
-    metaFor: (key) => entries[key] as M[keyof M],
+    metaFor: (key) => stableEntries[key] as M[keyof M],
     options: () =>
       keys.map((k) => ({
-        ...(entries[k] as M[keyof M]),
+        ...(stableEntries[k] as M[keyof M]),
         value: k,
       })) as DictOption<K, M[keyof M]>[],
     has: (key: string): key is K =>
-      Object.prototype.hasOwnProperty.call(entries, key),
+      Object.prototype.hasOwnProperty.call(stableEntries, key),
   }
 }
 

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

@@ -197,7 +197,7 @@ function LabelHelp({ help }: { help: string | undefined }): React.ReactElement |
         </TooltipTrigger>
         {/* max-w-sm: frase de help típica (~50 caracteres) cabe numa linha; o
             text-balance do primitivo só divide o que realmente transborda. */}
-        <TooltipContent className="max-w-sm">{help}</TooltipContent>
+        <TooltipContent>{help}</TooltipContent>
       </Tooltip>
     </TooltipProvider>
   )

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

@@ -3,25 +3,38 @@ import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '../../lib/cn.ts'
 
 /**
- * Variantes do alert (cva). COM ícone o layout é grid (1ª coluna pro `>svg`, 2ª pro
- * conteúdo, que se ancora em `col-start-2`); sem ícone é bloco comum.
- * `destructive` e `success` mantêm superfície tonalizada + borda (divergência da
- * casa — o shadcn rebaixou destructive pra bg-card, nós preservamos o realce).
+ * Variantes do alert (cva). COM ícone o componente abre uma coluna de realce tonal;
+ * sem ícone é bloco comum. `destructive`, `success` e `warning` mantêm superfície
+ * tonalizada + borda (divergência da casa — o shadcn rebaixou destructive pra bg-card,
+ * nós preservamos o realce).
  */
 export const alertVariants = cva(
-  // O grid (coluna do ícone + coluna do conteúdo) só existe QUANDO HÁ ícone. Era fixo, com
-  // a 1ª coluna em `0` — e aí qualquer nó de texto solto virava item anônimo NESSA coluna
-  // de largura zero, saindo uma palavra por linha. Sem ícone, bloco comum: o `col-start-2`
-  // dos slots é inócuo fora de grid.
-  "relative w-full rounded-lg border px-4 py-3 text-sm has-[>svg]:grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-[>svg]:items-start has-[>svg]:gap-x-3 has-[>svg]:gap-y-0.5 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
+  'relative w-full rounded-lg border px-4 py-3 text-sm has-[>svg]:grid has-[>svg]:grid-cols-[1rem_minmax(0,1fr)] has-[>svg]:items-start has-[>svg]:gap-x-3 has-[>svg]:gap-y-1 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
   {
     variants: {
       variant: {
         default: 'bg-card text-card-foreground',
         destructive:
-          'border-destructive/50 bg-destructive/5 text-destructive *:data-[slot=alert-description]:text-destructive/90 [&>svg]:text-current',
+          'border-destructive/50 bg-destructive/5 text-destructive *:data-[slot=alert-description]:text-destructive/90',
         success:
-          'border-emerald-500/40 bg-emerald-500/10 text-emerald-700 dark:text-emerald-400 *:data-[slot=alert-description]:text-emerald-700/90 dark:*:data-[slot=alert-description]:text-emerald-400/90 [&>svg]:text-current',
+          'border-emerald-500/40 bg-emerald-500/10 text-emerald-700 dark:text-emerald-400 *:data-[slot=alert-description]:text-emerald-700/90 dark:*:data-[slot=alert-description]:text-emerald-400/90',
+        warning:
+          'border-amber-500/40 bg-amber-500/10 text-foreground *:data-[slot=alert-description]:text-muted-foreground',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+)
+
+const alertIconVariants = cva(
+  'flex size-9 shrink-0 items-center justify-center rounded-md [&_svg]:size-5',
+  {
+    variants: {
+      variant: {
+        default: 'bg-muted text-muted-foreground',
+        destructive: 'bg-destructive/10 text-destructive',
+        success: 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-300',
+        warning: 'bg-amber-500/15 text-amber-700 dark:text-amber-300',
       },
     },
     defaultVariants: { variant: 'default' },
@@ -49,9 +62,11 @@ export function Alert({
   description,
   icon,
   children,
+  style,
   ...props
 }: AlertProps): React.ReactElement {
   const short = title !== undefined || description !== undefined
+  const hasIcon = icon !== undefined && icon !== null
   // Texto CRU como filho (`<Alert>Sincronizado.</Alert>`) vira descrição: no layout com
   // ícone ele cairia na coluna do ícone, espremido. Assim o atalho de sempre continua
   // valendo e cai no slot certo.
@@ -61,16 +76,31 @@ export function Alert({
     <div
       data-slot="alert"
       role="alert"
-      className={cn(alertVariants({ variant }), className)}
+      className={cn(alertVariants({ variant }), hasIcon && 'grid items-start', className)}
+      style={hasIcon ? {
+        gridTemplateColumns: '2.25rem minmax(0, 1fr)',
+        columnGap: '0.75rem',
+        rowGap: '0.25rem',
+        ...style,
+      } : style}
       {...props}
     >
-      {icon}
+      {hasIcon && (
+        <span
+          data-slot="alert-icon"
+          aria-hidden="true"
+          className={alertIconVariants({ variant })}
+          style={{ gridRow: '1 / span 2' }}
+        >
+          {icon}
+        </span>
+      )}
       {short ? (
         <>
           {title !== undefined && <AlertTitle>{title}</AlertTitle>}
           {description !== undefined && <AlertDescription>{description}</AlertDescription>}
           {/* A ação (children DEPOIS da frase) precisa da coluna 2: sem `col-start-2`
-              ela cai na coluna do ícone (~1rem) e é espremida pra esquerda. O
+              ela cai na coluna do ícone e é espremida pra esquerda. O
               `col-start-2` é inócuo sem o grid (forma curta sem ícone). */}
           {children !== undefined && children !== null && (
             <div data-slot="alert-actions" className="col-start-2 mt-1">

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

@@ -57,14 +57,14 @@ const fieldVariants = cva(
   {
     variants: {
       orientation: {
-        vertical: ["flex-col gap-2 [&>*]:w-full [&>.sr-only]:w-auto"],
+        vertical: ["flex-col gap-1.5 [&>*]:w-full [&>.sr-only]:w-auto"],
         horizontal: [
           "flex-row items-center gap-3",
           "[&>[data-slot=field-label]]:flex-auto",
           "has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
         ],
         responsive: [
-          "flex-col gap-2 @md/field-group:flex-row @md/field-group:items-center @md/field-group:gap-3 [&>*]:w-full @md/field-group:[&>*]:w-auto [&>.sr-only]:w-auto",
+          "flex-col gap-1.5 @md/field-group:flex-row @md/field-group:items-center @md/field-group:gap-3 [&>*]:w-full @md/field-group:[&>*]:w-auto [&>.sr-only]:w-auto",
           "@md/field-group:[&>[data-slot=field-label]]:flex-auto",
           "@md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
         ],
@@ -113,9 +113,9 @@ function FieldLabel({
     <Label
       data-slot="field-label"
       className={cn(
-        "group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50",
+        "group/field-label peer/field-label flex w-fit gap-2 text-xs leading-snug font-medium text-muted-foreground group-data-[invalid=true]/field:text-destructive group-data-[disabled=true]/field:opacity-50",
         "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border [&>*]:data-[slot=field]:p-4",
-        "has-data-[state=checked]:border-primary has-data-[state=checked]:bg-primary/5 dark:has-data-[state=checked]:bg-primary/10",
+        "has-[>[data-slot=field]]:has-data-[state=checked]:border-primary has-[>[data-slot=field]]:has-data-[state=checked]:bg-primary/5 dark:has-[>[data-slot=field]]:has-data-[state=checked]:bg-primary/10",
         className
       )}
       {...props}

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

@@ -40,7 +40,7 @@ function TooltipContent({
         data-slot="tooltip-content"
         sideOffset={sideOffset}
         className={cn(
-          "z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+          "z-50 w-fit max-w-sm origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-pretty text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
           className
         )}
         {...props}

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

@@ -16,6 +16,12 @@ Quase todo alert é ícone + título + uma frase — então isso é UMA linha: `
   title="Skill publicada"
   description="Os agentes do workspace já enxergam a nova versão."
 />
+<Alert
+  variant="warning"
+  icon={<CircleAlert />}
+  title="Revisão necessária"
+  description="Confira os dados antes de continuar."
+/>
 ```
 
 ## Só a frase
@@ -29,7 +35,7 @@ Título é opcional — o aviso de uma linha dispensa. `destructive` e `success`
 
 ## Ícone é opcional
 
-Sem `icon` o alert é bloco comum; com ele, vira grid de duas colunas e o conteúdo se alinha ao lado. Texto solto como filho também vale (`<Alert>Sincronizado.</Alert>`) — cai no slot de descrição sozinho.
+Sem `icon` o alert é bloco comum; com ele, vira grid de duas colunas e o conteúdo se alinha ao lado. O ícone da prop recebe o slot `alert-icon` e um realce tonal coerente com a variante. A composição legada com um SVG direto continua abrindo a coluna do ícone. Texto solto como filho também vale (`<Alert>Sincronizado.</Alert>`) — cai no slot de descrição sozinho.
 
 ```tsx preview col
 <Alert title="Sem provider próprio" description="As conversas usam o padrão do sistema." />
@@ -64,6 +70,7 @@ Os dois modos convivem: com `title`/`description` preenchidos, `children` entra
 |---|---|---|---|
 | `title` | `React.ReactNode` | | Título do alert (a forma curta). Não é o atributo `title` do HTML — esse é tooltip nativo, banido na casa, e o componente não o aceita. |
 | `description` | `React.ReactNode` | | A frase. Sozinha, dispensa título. |
-| `icon` | `React.ReactNode` | | Ícone à esquerda; é ele que liga o layout de duas colunas. Decorativo — quem nomeia é o título. |
-| `variant` | `'default' \| 'destructive' \| 'success'` | `'default'` | O tom da mensagem. |
+| `icon` | `React.ReactNode` | | Ícone à esquerda; liga o layout de duas colunas e recebe realce tonal no slot `alert-icon`. Decorativo — quem nomeia é o título. |
+| `variant` | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | O tom da mensagem e do realce do ícone. |
 | `children` | `React.ReactNode` | | Composição (`AlertTitle`/`AlertDescription`), texto cru, ou — junto da forma curta — o que vem depois da frase. |
+| `style` | `React.CSSProperties` | | Ajuste excepcional das medidas internas; com `icon`, pode sobrescrever as colunas e os espaçamentos padrão. |

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

@@ -1,6 +1,6 @@
 ## Campo vertical
 
-A composição base: FieldLabel (htmlFor↔id), o controle e FieldDescription como ajuda — empilhados, com o respiro do Field.
+A composição base: FieldLabel (htmlFor↔id), o controle e FieldDescription como ajuda — empilhados, com o respiro do Field. O rótulo usa a mesma hierarquia compacta de `DetailField`; quando o campo é inválido, muda explicitamente para o tom destrutivo.
 
 ```tsx preview col md
 <Field>

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

@@ -41,10 +41,24 @@ O TooltipProvider embrulha o app uma vez (delay compartilhado); cada Tooltip dis
 </TooltipProvider>
 ```
 
+## Texto longo
+
+O conteúdo tem largura máxima compartilhada e distribui as palavras naturalmente. O consumidor
+pode reduzir ou ampliar esse limite com `className` quando a composição exigir, sem repetir o
+default nos formulários.
+
+```tsx preview
+<Tooltip>
+  <TooltipTrigger asChild><Button variant="ghost">Como funciona</Button></TooltipTrigger>
+  <TooltipContent>Registre a evidência usada para que esta decisão possa ser consultada depois.</TooltipContent>
+</Tooltip>
+```
+
 ## Props
 
 | Prop | Tipo | Default | Descrição |
 |---|---|---|---|
 | `TooltipProvider.delayDuration` | `number` | `0` | Atraso (ms) até aparecer — compartilhado por todos os tooltips do app. |
 | `TooltipContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Lado preferido; inverte sozinho sem espaço (Radix). |
-| `TooltipContent.sideOffset` | `number` | `4` | Distância (px) entre gatilho e dica. |
+| `TooltipContent.sideOffset` | `number` | `0` | Distância (px) entre gatilho e dica. |
+| `TooltipContent.className` | `string` | `max-w-sm text-pretty` | Permite substituir o limite e a distribuição de linha quando necessário. |

package/src/ui/meta.ts

@@ -21,7 +21,7 @@ export const componentMeta = {
     name: 'alert',
     ancestry: 'opus',
     whenToUse:
-      'Aviso INLINE no fluxo da página (o erro do login, o "sincronizado" da lista) — `role="alert"`, então o leitor de tela anuncia sozinho. Forma CURTA (o caso comum): `<Alert title description icon variant />` numa linha; composição (`AlertTitle`/`AlertDescription`) só quando o conteúdo é rico (parágrafos, link, ação). `variant` default/destructive/success. Pra INTERROMPER cobrando decisão, use `confirm()`; pra recado passageiro, `toast`.',
+      'Aviso INLINE no fluxo da página (o erro do login, o "sincronizado" da lista) — `role="alert"`, então o leitor de tela anuncia sozinho. Forma CURTA (o caso comum): `<Alert title description icon variant />` numa linha; composição (`AlertTitle`/`AlertDescription`) só quando o conteúdo é rico (parágrafos, link, ação). `variant` default/destructive/success/warning; quando informado, o ícone recebe realce tonal nativo. Pra INTERROMPER cobrando decisão, use `confirm()`; pra recado passageiro, `toast`.',
   },
   'badge': {
     name: 'badge',