---
name: ui-nova-a2ui
description: Gerar interfaces A2UI (Agent-to-UI, protocolo v1.0) usando o catálogo de componentes ui-nova (vueui-nova-kit). Use quando um agente precisar responder com UI em vez de texto (formulários, dashboards, listas, confirmações), ao montar mensagens createSurface/updateComponents/updateDataModel, ao tratar actions vindas do renderer, ou ao depurar payloads A2UI que o renderer ui-nova rejeitou.
---

# Telas A2UI com o catálogo ui-nova

> Alvo: **A2UI v1.0**, renderer `@vueui-nova/a2ui` 1.0.0. `references/catalogo.md`,
> `references/mapeamento-111.md`, `references/instrucoes-catalogo.md`, `assets/` e `examples/` são
> **gerados/copiados** por `scripts/gen-skill-refs.mjs`.

## Antes de tudo

- `catalogId`: `https://uinova.walderpinheiro.com.br/a2ui/catalog/v1.json` (decisão D3; o domínio é configurável e o URN antigo `urn:vueui-nova-kit:a2ui:catalog:v1` ainda é aceito). Ids de componente são identificadores UAX #31: use `_`, nunca hífen.
- Use **somente** componentes de `references/catalogo.md`, com **somente** as props listadas.
  O renderer valida cada componente e devolve `error` `VALIDATION_FAILED` para nome ou prop desconhecidos.
- Leia `references/instrucoes-catalogo.md`: são as regras que o catálogo publica para agentes.

## Mensagens (agente → renderer)

Toda mensagem é um objeto `{"version": "1.0", "<tipo>": {...}}`.

| Tipo | Quando | Campos |
|---|---|---|
| `createSurface` | Primeira tela | `surfaceId`, `catalogId`, `components` (lista plana, um deles com `id: "root"`), `dataModel` inicial, `sendDataModel?` |
| `updateComponents` | Trocar ou adicionar componentes | `surfaceId`, `components`. Substitui por `id`; os demais ficam. |
| `updateDataModel` | Mudar dados sem mexer em layout | `surfaceId`, `path` (JSON Pointer), `value` (`null` remove) |
| `deleteSurface` | Encerrar | `surfaceId` |

## Modelo de componente

```json
{ "id": "email", "component": "TextInput", "label": "E-mail", "type": "email",
  "value": { "@path": "/form/email" },
  "@checks": [{ "condition": { "@call": "email", "args": { "value": { "@path": "/form/email" } } },
                "message": "Use um e-mail válido." }] }
```

- **Lista plana**: filhos são referenciados por id (`child: "id"`, `children: ["a","b"]`). Nunca aninhe objetos de componente.
- **Valores dinâmicos**: literal, `{"@path": "/abs"}` ou `{"@call": "fn", "args": {...}}`.
- **Template**: `children: {"componentId": "item", "path": "/lista"}`. Dentro do template os paths são **relativos** (`{"@path": "nome"}`); fora dele, sempre absolutos.
- **Binding de entrada**: inputs escrevem no data model **localmente**. O agente só recebe os
  valores quando uma action dispara, então ponha no `context` da action tudo que precisar.
- **Funções** (catálogo básico v1.0): `required`, `regex`, `length`, `numeric`, `email`,
  `formatString`, `formatNumber`, `formatCurrency`, `formatDate`, `pluralize`, `openUrl`, `and`, `or`, `not`.
- **Ações**: `"action": {"event": {"name": "dominio.verbo", "userMessage"?: ..., "context": {...}}}`.
  Componentes ui-nova com mais de uma ação usam nomes próprios (`confirmAction`, `cancelAction`,
  `rowAction`, `dismissAction`, `retryAction`).
- **A11y**: `@accessibility: {label, description, live, hidden}`. Botão só com ícone **exige** `label`.

## Receita

1. Escolha o componente mais específico (`StatCard` > Card+Text; `DescriptionList` > Row+Text).
   O mapeamento completo dos 111 componentes está em `references/mapeamento-111.md`: os marcados
   **v1** estão no catálogo; os marcados **fora** não existem para o agente (o motivo está na linha).
   `PasswordInput` e `OtpInput` só renderizam se o host ligar `allowSensitive`; não peça senha sem motivo.
2. Desenhe o data model primeiro (`/form/*`, `/ui/*` para estado de tela, dados de domínio na raiz).
3. Escreva os componentes planos com `root` no topo da hierarquia.
4. Adicione `@checks` nos inputs e um `@check` agregado (`and`) no botão de envio.
5. Para mudanças, prefira `updateDataModel` (barato) a `updateComponents`.
6. Valide antes de enviar (ver abaixo).

## Recebendo eventos (renderer → agente)

```json
{ "version": "1.0", "action": { "name": "chamado.enviar", "surfaceId": "chamado-7f3a",
  "sourceComponentId": "enviar", "timestamp": "…", "context": { "email": "ana@example.com" } } }
```

`error` traz `code` (`VALIDATION_FAILED`, `INTEGRITY_ERROR`, `INVALID_FUNCTION_CALL`,
`UNALLOWED_PARENT`, `UNALLOWED_CHILD`, `EXPRESSION_ERROR`), `message` e `path`. Corrija o payload
apontado em `path` e reenvie só o necessário.

## Proibido

- HTML, SVG, CSS, cores, fontes, URLs de script. O visual vem dos tokens do host.
- Ícone fora de `IconName` (`assets/ui-nova.catalog.schema.json#/$defs/IconName`).
- Pedir senha/OTP/arquivo: esses componentes estão fora do catálogo v1 de propósito.
- `AccordionItem` fora de `Accordion` (`allowedParents`).
- IDs de DOM, `testId`, `teleport`, `motion`: não existem no catálogo.

## Validar

Com o repositório do plano: `JSONSCHEMA_PATH=<libs> python3 scripts/validate-payloads.py` (schemas
oficiais v1.0 + regras semânticas). Sem ele, valide cada componente contra
`assets/ui-nova.catalog.schema.json`.

## Arquivos

- `references/catalogo.md`: **gerado**. Componentes do catálogo, props, tipos e defaults.
- `references/instrucoes-catalogo.md`: **copiado**. As `instructions` do catálogo.
- `references/mapeamento-111.md`: **gerado**. Os 111 itens da ui-nova e sua onda A2UI.
- `assets/ui-nova.catalog.schema.json`: **copiado**. O catálogo em JSON Schema.
- `examples/`: **copiados**. Formulário (01), dashboard (02), template + modal (03), cada um com os eventos de volta.
