@softize/opus 19.0.0 → 20.1.0

package/src/ui/meta.ts

@@ -27,13 +27,13 @@ export const componentMeta = {
     name: "alert",
     ancestry: "opus",
     whenToUse:
-      "Aviso inline no fluxo da página — `context` declara neutral/info/success/warning/danger e `variant` escolhe subtle/outline (ADR 0006). Forma curta: `<Alert title description icon context />`; para conteúdo rico, componha AlertMedia + AlertHeader (AlertTitle e AlertDescription) + AlertActions. Ações usam Button ghost como ponto de partida; tentativas repetidas podem usar somente o ícone, com nome acessível e tooltip. A mídia mantém uma moldura tonal quadrada, mesmo com descrição multilinha. O texto comunica o significado sem depender só da cor. Para interromper cobrando decisão, use `dialog.confirm()`; para recado passageiro, `toast`.",
+      "Mantenha uma informação visível no contexto da página até que ela deixe de valer. `context` declara neutral, info, success, warning ou danger, e `variant` escolhe subtle ou outline. No caso comum, use a forma curta `<Alert title description icon context />`; para conteúdo rico, componha AlertMedia, AlertHeader (com AlertTitle e AlertDescription) e AlertActions. As ações partem de Button ghost; uma nova tentativa pode usar somente o ícone, com nome acessível e tooltip. A mídia mantém uma moldura tonal quadrada, mesmo com descrição de várias linhas, e o texto comunica o significado sem depender só da cor. Para cobrar uma decisão, use `dialog.confirm()`; para confirmar o resultado de uma ação sem ocupar espaço na página, use `toast`; para o erro de uma consulta, use DataState.",
   },
   badge: {
     name: "badge",
     ancestry: "shadcn",
     whenToUse:
-      "Rótulo curto de status/categoria. `context` declara neutral/primary/info/success/warning/danger; `variant` escolhe solid/subtle/outline (ADR 0006). Não-interativo — para clique, use Button ou `asChild` em um <a>. Valor de dicionário com papel declarado usa DictionaryValue em vez de escolher contexto ou variante na tela.",
+      "Rotule um estado ou uma categoria com um texto curto que continua legível. `context` declara neutral, primary, info, success, warning ou danger, e `variant` escolhe solid, subtle ou outline. O Badge não é interativo: para uma ação, use Button; para navegar, use `asChild` com um `<a>`. Quando só a cor basta, ao lado de um texto que já nomeia o item, use Dot. Um valor de dicionário com papel declarado usa DictionaryValue em vez de escolher contexto ou variante na tela.",
   },
   "empty-value": {
     name: "empty-value",
@@ -51,7 +51,7 @@ export const componentMeta = {
     name: "dot",
     ancestry: "opus",
     whenToUse:
-      "Sinal compacto de estado. `context` declara neutral/primary/info/success/warning/danger e `variant` escolhe solid/outline. Passe `label` quando a cor reforçar informação; sem label, o ponto é decorativo. Para texto visível, use Badge.",
+      "Sinalize um estado com um ponto compacto quando o texto ao redor já dá o contexto. `context` declara neutral, primary, info, success, warning ou danger, e `variant` escolhe solid ou outline. Passe `label` quando a cor reforçar informação; sem `label`, o ponto é decorativo e fica oculto dos leitores de tela. Quando o estado precisar continuar legível sozinho, use Badge.",
   },
   "icon-tile": {
     name: "icon-tile",
@@ -63,7 +63,7 @@ export const componentMeta = {
     name: "detail",
     ancestry: "opus",
     whenToUse:
-      'Dados somente leitura em pares chave/valor. Compõe DetailGroup > DetailField com semântica de lista de definições; `columns` controla a grade, `orientation` posiciona chave e valor e alinha uma coluna compartilhada de rótulos no modo horizontal, `variant="framed"` aplica moldura e `dividers` acrescenta somente as divisórias internas. Para entrada, validação e erro, use Field; para uma coleção pesquisável, use ActionList.',
+      'Apresente dados somente leitura como pares de rótulo e valor. DetailGroup organiza os DetailField com a semântica de uma lista de definições; `columns` controla a grade, `orientation` posiciona rótulo e valor e, no modo horizontal, alinha os rótulos em uma coluna compartilhada. `variant="framed"` aplica a moldura e `dividers` acrescenta somente as divisórias internas. Para entrada, validação e erro, use Field; para uma coleção pesquisável, use ActionList.',
   },
   dock: {
     name: "dock",
@@ -87,7 +87,7 @@ export const componentMeta = {
     name: "metric-card",
     ancestry: "opus",
     whenToUse:
-      "Medida resumida com rótulo, valor em destaque e descrição opcional. Use `secondaryMetric` para uma segunda leitura diretamente relacionada, exibida como lâmina posterior com explicação própria. `context` realça semanticamente somente o ícone; aceita ação relacionada e estado de carregamento. O consumidor calcula e formata os valores; para conteúdo geral ou estrutura livre, use Card.",
+      "Apresente uma medida resumida, como um total ou uma contagem, com rótulo, valor em destaque e descrição opcional. O consumidor calcula e formata os valores. Use `secondaryMetric` para uma segunda leitura da mesma dimensão, exibida como lâmina posterior com rótulo próprio; `context` realça somente o ícone, `action` acrescenta uma ação diretamente relacionada e `loading` substitui rótulo e valor durante a carga. Com `onActivate`, `active` e `activationLabel`, informados juntos, o card vira um controle que aplica o recorte que a medida resume e expõe o estado por `aria-pressed`. Para conteúdo geral ou estrutura livre, use Card.",
   },
   chat: {
     name: "chat",
@@ -99,7 +99,7 @@ export const componentMeta = {
     name: "checkbox",
     ancestry: "shadcn",
     whenToUse:
-      "Caixa de marcação booleana (Radix). Controlado por `checked`/`onCheckedChange`. Parear com Label. Para escolha única de várias opções, use Select/RadioGroup.",
+      "Permita marcar uma opção que só vale ao salvar um formulário, como aceitar uma condição ou incluir uma etapa. Associe cada caixa a um Label e controle o estado com `checked` e `onCheckedChange`, ou defina o inicial com `defaultChecked`. Para uma preferência que entra em vigor no clique, use Switch; para uma escolha única entre várias opções, use RadioGroup ou Select.",
   },
   "icon-picker": {
     name: "icon-picker",
@@ -111,7 +111,7 @@ export const componentMeta = {
     name: "command",
     ancestry: "shadcn",
     whenToUse:
-      "Lista filtrável com teclado (cmdk) — base de command-palettes. Use CommandDialog para palette modal (⌘K). Para escolha simples, use o Select direto.",
+      "Permita encontrar um item ou uma ação digitando parte do nome e escolhê-lo pelo teclado. A lista filtra enquanto a busca muda, organiza os itens em grupos e mostra um estado vazio quando nada corresponde. Para uma paleta de comandos em modal, use CommandDialog; o aplicativo registra o atalho que a abre, como ⌘K. Para escolher um valor em um formulário, use Select.",
   },
   composer: {
     name: "composer",
@@ -123,7 +123,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      'Estruture uma região com título e corpo. No caso comum, declare título, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `as="fieldset"` para agrupar campos sob uma legenda nativa e `frameVariant="legend"` somente quando essa legenda precisar integrar visualmente a borda. Componha ContentHeader apenas quando precisar controlar a anatomia.',
+      'Estruture uma região com título e corpo. No caso comum, declare título, mídia, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `frameVariant="legend"` para integrar visualmente o header à borda e `as="fieldset"` somente para agrupar campos sob uma legenda nativa. Componha ContentHeader apenas quando precisar controlar a anatomia.',
   },
   copyable: {
     name: "copyable",
@@ -147,25 +147,25 @@ export const componentMeta = {
     name: "label",
     ancestry: "shadcn",
     whenToUse:
-      "Rótulo acessível de um campo. `htmlFor` aponta para o id do controle. Parear com Input/Textarea/Select.",
+      "Nomeie um controle de formulário. Associe `htmlFor` ao `id` do controle: o rótulo passa a ser o nome acessível do campo, e clicar nele move o foco para o controle. Quando o campo também tiver ajuda e mensagem de erro, use Field.",
   },
   markdown: {
     name: "markdown",
     ancestry: "opus",
     whenToUse:
-      "Renderize Markdown como HTML semântico com a tipografia do tema. HTML recebido no texto é escapado, por isso o componente pode apresentar conteúdo de pessoas ou modelos com segurança. Para código com destaque e cópia, use CodeBlock.",
+      "Exiba texto formatado que chega como Markdown, como a resposta de um agente no Chat ou uma descrição escrita por uma pessoa. Passe o texto em `content`; o resultado é HTML semântico com a tipografia do tema. HTML presente no texto é escapado, não interpretado, por isso o componente serve para conteúdo de pessoas ou de modelos, e endereços soltos viram links.",
   },
   menu: {
     name: "menu",
     ancestry: "opus",
     whenToUse:
-      'O menu de ações da casa: lista flutuante ancorada em um gatilho (Radix DropdownMenu). Compõe Menu > MenuTrigger + MenuContent e seus itens. `context="danger"` sinaliza item com consequência perigosa. Para escolher um valor, use Select; para busca por teclado, Command; para conteúdo livre ancorado, Popover.',
+      'Reúna ações relacionadas em uma lista flutuante aberta por um gatilho. Componha Menu > MenuTrigger + MenuContent com seus itens; `onSelect` executa a ação do item e fecha o menu, e `context="danger"` sinaliza um item com consequência perigosa. Para escolher um valor de formulário, use Select; para buscar pelo teclado, Command; para conteúdo livre ancorado, Popover.',
   },
   popover: {
     name: "popover",
     ancestry: "shadcn",
     whenToUse:
-      "Painel flutuante ancorado em um gatilho, sem modal (Radix). Para conteúdo livre (form curto, detalhes). Use PopoverHeader/PopoverTitle/PopoverDescription para estruturar. Para lista de ações, use Menu; para modal, Dialog.",
+      "Apresente conteúdo livre junto a um gatilho sem abrir um modal, como um formulário curto ou detalhes. PopoverHeader agrupa PopoverTitle e PopoverDescription. Para uma lista de ações, use Menu; para uma dica curta ao passar o ponteiro, Tooltip; para uma tarefa que exige atenção exclusiva, Dialog.",
   },
   select: {
     name: "select",
@@ -177,7 +177,7 @@ export const componentMeta = {
     name: "separator",
     ancestry: "shadcn",
     whenToUse:
-      "Linha divisória entre seções/itens (Radix). `orientation` horizontal|vertical. Decorativa por padrão (a11y).",
+      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Card, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões com `layout="sectioned"`.',
   },
   skeleton: {
     name: "skeleton",
@@ -195,7 +195,7 @@ export const componentMeta = {
     name: "table",
     ancestry: "shadcn",
     whenToUse:
-      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). `variant="plain"` vem sem borda externa; `variant="framed"` aplica a moldura canônica, recorta o scroll e destaca o cabeçalho. Para uma coleção com busca, filtros e paginação, use ActionList.',
+      'Organize em linhas e colunas os dados que a tela já tem em mãos. Componha Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). `variant="plain"` vem sem borda externa; `variant="framed"` aplica a moldura, recorta a rolagem e destaca o cabeçalho. Para uma coleção com busca, filtros e paginação, use ActionList.',
   },
   tabs: {
     name: "tabs",
@@ -207,7 +207,7 @@ export const componentMeta = {
     name: "textarea",
     ancestry: "shadcn",
     whenToUse:
-      "Campo de texto multilinha. Aceita os atributos nativos de <textarea> (rows, placeholder, disabled). Cresce com o conteúdo via `field-sizing-content`.",
+      "Receba texto livre com várias linhas, como uma descrição ou um contexto. O campo aceita os atributos nativos de `<textarea>` e cresce com o conteúdo a partir da altura mínima. Associe um Label; para uma caixa de envio com botão integrado, use Composer; para uma única linha, use Input.",
   },
   toast: {
     name: "toast",
@@ -231,7 +231,7 @@ export const componentMeta = {
     name: "accordion",
     ancestry: "shadcn",
     whenToUse:
-      "Lista de seções empilhadas que abrem/fecham (Radix). `type` single (um painel por vez — combine com `collapsible` para permitir fechar todos) ou multiple (vários abertos). Cada AccordionItem precisa de `value`; o chevron já vem no AccordionTrigger. Para alternar conteúdo lado a lado, use Tabs; para um único bloco recolhível solto, use Collapsible.",
+      'Divida um conteúdo longo em painéis que a pessoa expande sob demanda, cada um com seu título. `type="single"` mantém um painel aberto por vez — combine com `collapsible` para permitir fechar todos — e `type="multiple"` permite vários abertos. Cada AccordionItem precisa de `value`, e o AccordionTrigger já traz o ícone de estado. Para um único bloco recolhível, use Collapsible; para alternar entre painéis do mesmo nível, Tabs.',
   },
   "aspect-ratio": {
     name: "aspect-ratio",
@@ -249,25 +249,25 @@ export const componentMeta = {
     name: "breadcrumb",
     ancestry: "shadcn",
     whenToUse:
-      "Trilha de navegação hierárquica (workspace → repositório → sessão): mostra onde o usuário está e o caminho de volta. `BreadcrumbLink` para os níveis navegáveis, `BreadcrumbPage` para o atual (não clicável), `BreadcrumbSeparator` entre eles e `BreadcrumbEllipsis` para colapsar trilhas longas. Para alternar painéis no mesmo nível, use Tabs.",
+      "Mostre onde a pessoa está quando a página fica vários níveis abaixo da entrada da seção e permita voltar a um nível intermediário. Use BreadcrumbLink nos níveis navegáveis, BreadcrumbPage no nível atual, que não é clicável, BreadcrumbSeparator entre eles e BreadcrumbEllipsis para colapsar trilhas longas. Quando basta voltar ao nível imediatamente acima, use PageBack; para alternar painéis no mesmo nível, Tabs.",
   },
   calendar: {
     name: "calendar",
     ancestry: "shadcn",
     whenToUse:
-      'Grade de datas (react-day-picker) para escolher um dia ou um intervalo. `mode` define a seleção (single/multiple/range) e o formato de `selected`/`onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês/ano (pular para um período distante); `numberOfMonths` mostra meses lado a lado; `disabled` (Matcher) corta datas. Para exibir em um popover de campo, ancore no Popover.',
+      'Permita escolher datas vendo o mês inteiro, como a data de uma entrega ou o período de um relatório. `mode` define a seleção — `single`, `multiple` ou `range` — e o formato de `selected` e `onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês e ano, útil para chegar a um período distante; `numberOfMonths` mostra meses lado a lado e `disabled` impede a escolha de datas específicas. Os textos usam pt-BR por padrão. Para abrir o calendário a partir de um campo, ancore-o em um Popover.',
   },
   carousel: {
     name: "carousel",
     ancestry: "shadcn",
     whenToUse:
-      "Trilho de slides deslizáveis (embla). Compõe Carousel > CarouselContent > CarouselItem + CarouselPrevious/CarouselNext; o `basis` do item controla quantos cabem na vista. `orientation` (horizontal/vertical), `opts` repassa o embla (loop, align), `setApi` expõe a instância. Para lista paginada de dados, use Table; para navegação entre painéis, Tabs.",
+      "Percorra uma sequência de itens do mesmo tipo em um espaço limitado, um ou alguns por vez. Componha Carousel > CarouselContent > CarouselItem com CarouselPrevious e CarouselNext; a largura de cada item define quantos cabem na área visível. `orientation` escolhe o eixo, `opts` configura o deslocamento, como `loop` e `align`, e `setApi` permite controlar o carrossel por código. Nomeie o carrossel com `aria-label`. Para consultar e comparar muitos registros, use ActionList; para navegar entre painéis, Tabs.",
   },
   collapsible: {
     name: "collapsible",
     ancestry: "shadcn",
     whenToUse:
-      "Seção que abre e fecha (Radix): um CollapsibleTrigger revela ou esconde o CollapsibleContent. Compõe Collapsible > (CollapsibleTrigger + CollapsibleContent) — o Trigger já é o `<button>`. `defaultOpen` para o modo não controlado; `open`/`onOpenChange` para o controlado (ex.: girar o chevron); `disabled` trava o gatilho. Para alternar entre vários painéis, use Tabs; para menu de ações ancorado, Menu.",
+      "Esconda um bloco secundário atrás de um gatilho, mantendo o restante da tela visível. Componha Collapsible > (CollapsibleTrigger + CollapsibleContent); o gatilho já renderiza o `<button>`. Use `defaultOpen` no modo não controlado e `open` com `onOpenChange` quando outra parte da tela precisar conhecer o estado; `disabled` trava o gatilho. Para vários painéis recolhíveis, use Accordion; para alternar entre painéis, Tabs; para ações ancoradas, Menu.",
   },
   drawer: {
     name: "drawer",
@@ -291,7 +291,7 @@ export const componentMeta = {
     name: "input-otp",
     ancestry: "shadcn",
     whenToUse:
-      "Receba um código numérico dividido em posições, como uma confirmação de acesso ou segundo fator. InputOTP define o comprimento, os slots representam as posições e o separador organiza blocos. Para texto livre, use Input.",
+      "Receba um código curto enviado por outro canal, como uma confirmação de acesso ou um segundo fator. `maxLength` define o comprimento, cada InputOTPSlot representa uma posição e InputOTPSeparator divide os blocos. Sem `pattern`, qualquer caractere é aceito; passe `pattern` para restringir a entrada, por exemplo a dígitos. Para texto livre, use Input.",
   },
   item: {
     name: "item",
@@ -309,7 +309,7 @@ export const componentMeta = {
     name: "pagination",
     ancestry: "shadcn",
     whenToUse:
-      "Navegação entre páginas montada por composição: Pagination › PaginationContent › PaginationItem com PaginationLink, mais PaginationPrevious/PaginationNext e PaginationEllipsis. `page` dá o número e o nome acessível (“Página N”); `isActive` marca a atual. Com `href` o link é `<a>`; sem `href` vira `<button>` (modo controlado, com foco e `disabled`). Os números têm largura mínima quadrada e crescem com os dígitos; as setas seguem quadradas (`iconOnly`). `label` localiza as setas. É o único paginador: ActionList compõe esta primitiva na escala densa do rodapé. Para rolagem infinita ou listas curtas, dispense a barra.",
+      "Permita saltar entre as páginas de uma coleção dividida em partes. Em uma listagem derivada de uma action, ActionList já monta esta paginação no rodapé; componha-a diretamente apenas em coleções próprias, com Pagination › PaginationContent › PaginationItem e PaginationLink, PaginationPrevious, PaginationNext e PaginationEllipsis. `page` fornece o número e o nome acessível (“Página N”), e `isActive` marca a página atual. Com `href`, o link é um `<a>`; sem `href`, vira `<button>` para o modo controlado, com foco e `disabled`. `label` localiza o texto das setas. Para rolagem infinita ou listas curtas, dispense a paginação.",
   },
   progress: {
     name: "progress",
@@ -321,7 +321,7 @@ export const componentMeta = {
     name: "radio-group",
     ancestry: "shadcn",
     whenToUse:
-      "Escolha única entre opções mutuamente exclusivas, todas visíveis ao mesmo tempo (Radix). Cada RadioGroupItem tem um `value`; o item escolhido vira o `value` do RadioGroup, controlado por `value`/`onValueChange` (ou `defaultValue` no modo não controlado). Pareie cada item com um Label. Para poucas opções que cabem na tela; com muitas, prefira Select; para ligar/desligar um único item, Checkbox ou Switch.",
+      "Permita uma escolha única entre opções mutuamente exclusivas que precisam permanecer visíveis. Cada RadioGroupItem declara um `value` e se associa a um Label; o RadioGroup guarda a escolha em `value` com `onValueChange`, ou em `defaultValue` no modo não controlado. Com muitas opções, prefira Select; para ligar ou desligar um único item, use Checkbox ou Switch.",
   },
   split: {
     name: "split",
@@ -339,25 +339,25 @@ export const componentMeta = {
     name: "pane",
     ancestry: "opus",
     whenToUse:
-      "Estruture a coluna ou faixa encaixada num Split: PaneHeader nomeia a região e leva mídia e ações, PaneBody rola e PaneFooter fixa o que precisa ficar à vista. `layout` escolhe entre regiões seccionadas, com divisores derivados da vizinhança, e o fluxo contínuo. O `inset` vale para o pane sem slots; com eles, o recuo é de cada região.",
+      "Estruture a coluna ou faixa encaixada em um Split. PaneHeader nomeia a região e acomoda mídia e ações; ao lado desses slots, também aceita conteúdo livre, como uma busca ou a marca de uma barra lateral. PaneBody rola e PaneFooter mantém à vista o que não pode sair da tela. `layout` escolhe entre regiões seccionadas, com divisores derivados da vizinhança, e o fluxo contínuo. `inset` vale para o pane sem slots; com eles, o recuo pertence a cada região.",
   },
   "scroll-area": {
     name: "scroll-area",
     ancestry: "shadcn",
     whenToUse:
-      'Região rolável com barra estilizada da casa (Radix), no lugar da scrollbar do sistema. Dê altura (ou largura) ao ScrollArea via className e ponha o conteúdo dentro; a barra vertical já vem por padrão. Para rolagem horizontal, acrescente `<ScrollBar orientation="horizontal" />` como filho. Para a página inteira rolar, deixe o navegador cuidar — isto é para um painel com altura fixa (lista de sessões, log, trilho de skills).',
+      'Mantenha a altura de um bloco, como uma lista, um log ou um histórico, e role o conteúdo que passar dela com a barra do tema no lugar da barra do sistema. Dê a altura ao ScrollArea por `className` e coloque o conteúdo dentro; a barra vertical já vem incluída. Para rolar na horizontal, acrescente `<ScrollBar orientation="horizontal" />` como filho. Quando a página inteira precisar rolar, deixe a rolagem com o navegador.',
   },
   slider: {
     name: "slider",
     ancestry: "shadcn",
     whenToUse:
-      "Controle de valor em uma faixa contínua, arrastado pelo thumb (Radix). `min`/`max`/`step` delimitam a faixa; `value`/`onValueChange` controlam (array de números — `[n]` para um thumb, `[a, b]` para um intervalo) ou `defaultValue` no modo não controlado. `orientation` horizontal/vertical, `disabled` esmaece. Para um número exato digitado, use Input type=number; para ligar/desligar, Switch.",
+      'Permita escolher um valor ou um intervalo dentro de uma faixa contínua, arrastando o controle (thumb). `min`, `max` e `step` delimitam a faixa; `value` com `onValueChange` controla o estado — `[n]` para um valor, `[a, b]` para um intervalo — e `defaultValue` atende o modo não controlado. Nomeie o controle com `aria-label` ou `aria-labelledby` no Slider, que os repassa ao thumb; o `htmlFor` de um Label não o alcança. Em um intervalo, passe `thumbLabels` com um nome por thumb, na ordem dos valores. Para digitar um número exato, use Input com `type="number"`; para ligar ou desligar, Switch.',
   },
   switch: {
     name: "switch",
     ancestry: "shadcn",
     whenToUse:
-      "Liga/desliga imediato de uma preferência booleana (Radix). Controlado por `checked`/`onCheckedChange` (boolean) e em par com Label. Use para estado que vale na hora (ativar agente, sincronizar); para confirmar dentro de um formulário, prefira Checkbox.",
+      "Permita ligar ou desligar uma preferência que entra em vigor imediatamente, como ativar um agente ou a sincronização. Associe o controle a um Label e controle o estado com `checked` e `onCheckedChange`, ou defina o inicial com `defaultChecked`. Quando a escolha só vale ao salvar um formulário, use Checkbox.",
   },
   toggle: {
     name: "toggle",
@@ -376,13 +376,13 @@ export const componentMeta = {
     name: "action-form",
     ancestry: "opus",
     whenToUse:
-      "Renderize e envie uma FormAction com validação, estado de envio e notificação consistentes. Sem filhos, os campos seguem o schema do contrato; com ActionFormField, o consumidor controla o layout sem duplicar rótulos ou erros. Para uma ação sem campos, use ActionTrigger.",
+      "Renderize e envie uma FormAction com validação, estado de envio e notificação consistentes. Sem filhos, o formulário monta um campo para cada entrada de `fields` do contrato, na ordem declarada; um campo do schema sem entrada em `fields` não aparece. Com ActionFormField, o consumidor controla o layout sem duplicar rótulos ou erros. Para uma ação sem campos, use ActionTrigger.",
   },
   "action-form-dialog": {
     name: "action-form-dialog",
     ancestry: "opus",
     whenToUse:
-      "ActionForm dentro de um Dialog (form em modal) — controla open/onOpenChange + title; fecha no sucesso. Aceita children (modo composição) como o ActionForm. Para form inline em uma página, use ActionForm direto.",
+      "Apresente um formulário de action em um modal, sem levar a pessoa para outra página. O consumidor controla `open` e `onOpenChange`, e o modal fecha depois de uma execução bem-sucedida. O título nomeia a operação e o recurso, como `Criar {recurso}` ou `Editar {recurso}`, e a ação principal mantém `Salvar`; use `submitLabel` somente para outro efeito, como `Renomear`. Assim como ActionForm, aceita ActionFormField como filhos. Para um formulário na própria página, use ActionForm; para uma seção delimitada, ActionFormCard.",
   },
   "action-form-card": {
     name: "action-form-card",
@@ -406,13 +406,13 @@ export const componentMeta = {
     name: "action-view",
     ancestry: "opus",
     whenToUse:
-      "Carregue e apresente um recurso de uma ViewAction com estados de carregamento, erro e ausência consistentes. Os filhos definem o layout a partir dos dados e de `refetch`; para uma coleção, use ActionList.",
+      "Carregue e apresente um recurso de uma ViewAction com estados de carregamento e erro consistentes. Os filhos definem o layout a partir dos dados e de `refetch`. O handler deve devolver um valor: represente um recurso ausente com o erro `not_found`, cuja frase aparece para a pessoa. Quando o recurso alimentar mais de uma região, use `useViewAction`; para uma coleção, use ActionList.",
   },
   page: {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). PageHeader declara navegação e ações globais; PageIntro é a introdução opcional; PageBody recebe o conteúdo. PageShell mantém a barra de 3.75rem e projeta os slots do PageHeader. Uma região interna pode fornecer o heading principal com Content. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState oculta PageIntro; informações importantes entram no corpo como Alert ou texto. Para uma região disponível à criação ou vínculo, use Empty.",
+      "Estruture uma página com cabeçalho, introdução, estado e conteúdo na mesma anatomia. Page renderiza o `<main>` com um container centralizado de até 80rem (`max-w-7xl`); PageHeader declara navegação e ações globais, PageIntro é a introdução opcional e PageBody recebe o conteúdo. PageShell mantém a barra persistente de 3.75rem e projeta nela os slots do PageHeader. Uma região interna pode fornecer o heading principal com Content. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState substitui o conteúdo inteiro durante carregamento, falha ou ausência e oculta PageIntro, por isso informações indispensáveis entram no corpo, como Alert ou texto. Para uma falha parcial, mantenha o estado na seção com DataState; para uma região disponível à criação ou vínculo, use Empty.",
   },
   presentation: {
     name: "presentation",
@@ -430,7 +430,7 @@ export const componentMeta = {
     name: "data-state",
     ancestry: "opus",
     whenToUse:
-      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona com as mesmas superfícies de PageState: `emptyMessage` compõe Empty com moldura sólida, o erro é um Alert com `onRetry` e `retryLabel`. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
+      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona na escala de uma seção. O carregamento mostra um Spinner; o vazio compõe Empty com moldura sólida e `emptyMessage`; o erro é um Alert danger com `errorMessage`, sem expor o texto técnico, e `onRetry` com `retryLabel` acrescenta a nova tentativa. Em uma tabela, `colSpan` ocupa uma linha inteira. Para o estado da página inteira, use PageState; uma coleção carregada por ActionList já trata esses estados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
   },
   "action-list-dialog": {
     name: "action-list-dialog",

package/src/ui/react.tsx

@@ -487,6 +487,7 @@ export type {
 export {
   Content,
   ContentHeader,
+  ContentMedia,
   ContentTitle,
   ContentDescription,
   ContentMeta,

package/src/vite/design.ts

@@ -15,10 +15,22 @@
  * dos entries são IGNORADOS (não registrados), senão o `start()` exige
  * eventbus/scheduler adapters que o design não tem por que montar.
  *
- * Uso (vite.config.ts do app):
- *   import { opusDesign } from '@softize/opus/vite'
- *   export default defineConfig({ plugins: [react(), opusDesign()] })
- *   // vite --mode design
+ * Uso (vite.config.ts do app, como no template de `opus create`):
+ *   const DESIGN_RUN = process.argv.includes('--mode=design') ||
+ *     process.argv.some((arg, i) => (arg === '--mode' || arg === '-m') && process.argv[i + 1] === 'design')
+ *   const designPlugins: PluginOption[] = DESIGN_RUN
+ *     ? [(await import('@softize/opus/vite')).opusDesign()]
+ *     : []
+ *   export default defineConfig({ plugins: [react(), ...designPlugins] })
+ *   // vite --mode design --configLoader runner
+ *
+ * Não importe o plugin de forma estática: o pacote publica TypeScript, e o
+ * carregador padrão de config do Vite o externaliza, o que o Node 22+ recusa
+ * dentro de `node_modules` (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). O
+ * import dinâmico no top-level, condicionado ao modo design e carregado com
+ * `--configLoader runner`, deixa o Vite transformar o TypeScript; build e
+ * preview nem chegam a carregá-lo. Detalhes em "Prototipar com dados
+ * simulados", no guia de actions (src/ui/docs/content/actions.md).
  */
 
 import { readdirSync } from 'node:fs'