---
name: ui-nova-a11y
description: Garantir acessibilidade (WCAG 2.2 AA) ao usar componentes da ui-nova (vueui-nova-kit) ou ao gerar surfaces A2UI com o catálogo ui-nova. Use ao montar formulários, diálogos, botões só com ícone, tabelas, abas, feedback dinâmico (alertas, carregamento), ou ao revisar/auditar telas com ui-nova.
---

# Acessibilidade com ui-nova

> `references/a11y-por-componente.md` é **gerado** (seção de acessibilidade de cada
> componente + props de a11y) por `scripts/gen-skill-refs.mjs`.

## O que a lib já faz (não reimplemente)

Foco visível, navegação por teclado, roles/ARIA dos padrões (abas, accordion, diálogo com trap e
retorno de foco, listbox) e respeito a `prefers-reduced-motion`. Veja o que cada componente
garante na referência antes de adicionar ARIA manual: ARIA duplicada piora.

## O que você precisa preencher

| Situação | Faça |
|---|---|
| Campo de formulário | Sempre `label` visível. `helperText`/`error` são ligados por `aria-describedby` pela lib. |
| Botão só com ícone | `ariaLabel` (Vue) ou `@accessibility.label` (A2UI). |
| Controle sem rótulo visível (SegmentedControl, Slider) | `ariaLabel` / `@accessibility.label`. |
| Conteúdo que muda sozinho (resultado, erro, contagem) | Região viva: `@accessibility.live: "polite"` (ou `assertive` só para erro bloqueante). |
| Imagem informativa | `alt` com o conteúdo. Decorativa: `decorative: true`. |
| Títulos | Hierarquia sem saltos. Em `Section`, use `headingLevel` coerente com a página do host. |
| Diálogo destrutivo | `variant="confirmation"`, `intent="destructive"`, título que diga o objeto (“Remover Jira?”). |
| Cor | Nunca o único sinal: combine com ícone/texto (Badge + texto, `trend` + `delta`). |

## Mapeamento A2UI `@accessibility` → ui-nova (renderer)

| `@accessibility` (v1.0) | Vira |
|---|---|
| `label` | `ariaLabel` do componente (ou `aria-label` no elemento raiz) |
| `description` | `aria-describedby` → texto visualmente oculto |
| `live` | `aria-live` no wrapper do componente |
| `hidden` | `aria-hidden="true"` (proibido em elemento focável: o renderer ignora e avisa) |

## Checklist de revisão

- [ ] Tab percorre tudo em ordem lógica e não prende fora de diálogo.
- [ ] Todo controle tem nome acessível (axe: `button-name`, `label`).
- [ ] Contraste AA nos dois temas (os tokens semânticos já atendem: não sobrescreva com cor crua).
- [ ] Mensagens de validação (`@checks`) aparecem no campo e são anunciadas.
- [ ] Animações param com `prefers-reduced-motion: reduce`.

## Arquivos

- `references/a11y-por-componente.md`: **gerado**. Garantias e props de a11y de cada componente.
