accessibility-compliance

Visão geral da skill accessibility-compliance

O que a skill accessibility-compliance faz

A skill accessibility-compliance ajuda um agente a gerar orientação de acessibilidade pronta para implementação em interfaces web e mobile, com foco forte em WCAG 2.2, uso de ARIA, acesso por teclado, suporte a leitores de tela e acessibilidade em dispositivos móveis. Ela faz mais sentido para equipes trabalhando em interfaces reais, e não apenas montando um checklist genérico de acessibilidade.

Quem deve instalar accessibility-compliance

Esta skill é uma boa escolha para:

• auditores de UX que precisam de accessibility-compliance for UX Audit
• engenheiros frontend corrigindo problemas de acessibilidade em componentes
• equipes de design systems definindo padrões de interação acessíveis
• times de produto que entregam formulários, dialogs, menus e outras interfaces interativas
• equipes mobile ou multiplataforma que precisam de orientação considerando VoiceOver e TalkBack

Se a sua necessidade é “transformar esta tela ou componente em algo mais próximo da conformidade com WCAG, com correções concretas”, esta skill tende a ser mais útil do que um prompt amplo de design.

Por que esta skill é diferente de um prompt genérico

O principal valor da accessibility-compliance skill é direcionar o modelo para padrões práticos de implementação de acessibilidade, em vez de princípios vagos. O repositório inclui referências específicas em:

• references/wcag-guidelines.md
• references/aria-patterns.md
• references/mobile-accessibility.md

Isso a torna mais adequada para tarefas como escolher HTML semântico em vez de ARIA, estruturar formulários acessíveis, melhorar o comportamento via teclado ou verificar orientações de touch target para mobile.

O que os usuários querem saber antes de instalar

A maioria das pessoas avaliando accessibility-compliance install quer entender:

• se ela entrega correções concretas orientadas a código, em vez de linguagem de política ou conformidade abstrata
• se cobre preocupações tanto de web quanto de mobile
• se ajuda em auditorias e também na implementação
• se tem uma posição clara sobre semântica nativa versus ARIA
• se pode reduzir idas e vindas na revisão de componentes de UI

Nesses pontos, a skill parece consistente. Seu diferencial mais forte é a amplitude prática: reúne conceitos de WCAG, padrões ARIA e acessibilidade mobile em um único pacote.

Casos de melhor encaixe e casos de má adequação

Melhor encaixe:

• auditar componentes interativos
• corrigir problemas de acessibilidade em código existente
• planejar comportamento acessível para dialogs, accordions, formulários e navegação
• revisar ordem de foco, labels, anúncios e suporte a reduced motion

Má adequação:

• interpretação jurídica de conformidade para uma jurisdição específica
• configuração de testes automatizados por si só
• crítica visual em nível de pixel sem relação com acessibilidade
• APIs nativas profundamente específicas de plataforma além da orientação referenciada

Como usar a skill accessibility-compliance

Contexto de instalação e invocação

O SKILL.md de origem não traz um comando de instalação, então quem usa o diretório normalmente adiciona a skill a partir do repositório:

npx skills add https://github.com/wshobson/agents --skill accessibility-compliance

Depois, invoque a skill passando uma tarefa concreta de acessibilidade, e não apenas “verifique acessibilidade”. A skill accessibility-compliance funciona melhor quando o pedido inclui um componente, fluxo ou tela com estrutura suficiente para análise.

Leia estes arquivos primeiro

Para adotar rápido, comece por aqui:

1. plugins/ui-design/skills/accessibility-compliance/SKILL.md
2. plugins/ui-design/skills/accessibility-compliance/references/wcag-guidelines.md
3. plugins/ui-design/skills/accessibility-compliance/references/aria-patterns.md
4. plugins/ui-design/skills/accessibility-compliance/references/mobile-accessibility.md

Essa ordem de leitura acompanha a forma como a maioria das equipes trabalha: primeiro a meta de conformidade, depois os padrões de implementação e, por fim, os casos de borda de plataforma.

Quais entradas a skill precisa para funcionar bem

A qualidade de accessibility-compliance usage depende muito da especificidade do seu input. Informe:

• tipo de componente ou página
• código ou markup atual
• framework (React, Next.js, Vue, plain HTML, React Native)
• comportamento da interação
• padrão-alvo, geralmente WCAG 2.2 AA
• escopo de dispositivo: desktop web, mobile web, iOS, Android
• problemas já identificados por ferramentas de auditoria ou testes com usuários

Input fraco:

• “Make this accessible.”

Input forte:

• “Review this React modal for WCAG 2.2 AA. Check keyboard trap behavior, focus return, accessible name/description, escape handling, and screen reader announcements. Suggest code changes before release.”

Como transformar um objetivo vago em um bom prompt

Um bom prompt de accessibility-compliance guide normalmente tem cinco partes:

1. UI alvo
2. interações do usuário
3. meta de conformidade
4. entregável esperado
5. restrições

Exemplo:

• “Use the accessibility-compliance skill to audit this checkout form for WCAG 2.2 AA. Identify failures by issue, explain user impact, and provide corrected JSX for labels, error messaging, field grouping, and keyboard flow. Keep the current visual design if possible.”

Isso é melhor do que pedir apenas “best practices”, porque força o modelo a produzir uma saída acionável e corrigível.

Melhor fluxo de trabalho para uma auditoria de UX

Para accessibility-compliance for UX Audit, use esta sequência:

1. peça a identificação dos problemas
2. peça severidade e impacto para o usuário
3. peça o mapeamento das correções
4. peça markup revisado ou código atualizado do componente
5. peça um checklist de reteste

Isso evita um problema comum: a primeira resposta ficar conceitual demais. A skill accessibility-compliance é mais útil quando você leva os achados da auditoria até os detalhes de implementação.

Use para componentes, não só para páginas

A skill é especialmente forte em padrões de interação reutilizáveis. Bons alvos incluem:

• dialogs e focus traps
• accordions
• menus e disclosures
• formulários e validação
• tabs
• carousels
• icon buttons
• touch targets em mobile

Esses são exatamente os pontos em que prompts genéricos costumam exagerar no uso de ARIA ou deixar passar comportamento de teclado e leitor de tela.

O que as referências indicam na prática

As referências incluídas sugerem três regras operacionais importantes:

• prefira HTML semântico antes de adicionar ARIA
• trate WCAG 2.2 AA como a linha de base padrão
• considere acessibilidade mobile, e não só uso de teclado no desktop

Isso faz diferença no uso real. Um bom prompt deve pedir explicitamente ao agente para minimizar ARIA desnecessário e justificar qualquer atributo ARIA que ele adicionar.

Padrão de prompt para resultados melhores

Use um formato de solicitação como este:

• Context: “This is a React checkout drawer.”
• Target: “Meet WCAG 2.2 AA.”
• Review scope: “Keyboard access, focus order, visible labels, error association, live region announcements.”
• Constraints: “Do not rewrite the design system API.”
• Deliverable: “Return prioritized issues, corrected JSX, and a manual test checklist.”

Essa estrutura gera resultados de accessibility-compliance usage de forma mais consistente do que pedidos de revisão em aberto.

O que esperar da saída

Uma boa resposta da accessibility-compliance skill deve incluir:

• lista de problemas vinculada ao impacto no usuário
• referências a princípios ou critérios de acessibilidade
• mudanças específicas de markup ou código
• observações sobre comportamento de teclado e foco
• orientações sobre nomeação e anúncios para leitores de tela
• observações específicas para mobile quando fizer sentido

Se a resposta parar nos princípios sem chegar a correções em nível de código, o seu prompt está amplo demais.

FAQ da skill accessibility-compliance

A accessibility-compliance é boa para iniciantes?

Sim, desde que você já entenda o básico de estrutura de UI. A skill entrega mais valor quando você consegue fornecer markup, componentes ou achados de auditoria. Iniciantes também podem usar, mas devem esperar a necessidade de fazer perguntas complementares sobre por que certas escolhas de semântica ou ARIA importam.

Isso é melhor do que um prompt normal de acessibilidade?

Na maioria dos casos, sim, para trabalho de implementação. Um prompt comum pode devolver orientações genéricas como “add alt text” ou “ensure keyboard navigation.” A accessibility-compliance skill tem mais chance de permanecer ancorada em WCAG 2.2, padrões ARIA e preocupações de acessibilidade mobile presentes nas referências do repositório.

Ela substitui testes automatizados de acessibilidade?

Não. Ela complementa ferramentas automatizadas e revisão manual. Use a skill accessibility-compliance para interpretar problemas, propor correções e revisar comportamentos de componentes que ferramentas estáticas frequentemente não capturam, como gestão de foco, timing de anúncios ou detalhes de interação em mobile.

Quando eu não devo usar accessibility-compliance?

Evite usar quando você precisa de:

• aconselhamento jurídico ou decisões de certificação
• varredura totalmente automatizada em todo o codebase
• detalhes profundos de plataformas mobile nativas além dos padrões referenciados
• crítica de UX sem relação com acessibilidade

Ela é uma skill de orientação, não uma garantia de conformidade.

Ela oferece bom suporte a acessibilidade mobile?

De forma razoável, sim, para uma skill de IA. A referência dedicada mobile-accessibility.md cobre dimensionamento de touch targets, espaçamento e questões de leitor de tela para iOS e Android. Isso torna a skill accessibility-compliance mais confiável para revisão mobile do que prompts de acessibilidade focados apenas em desktop web.

Posso usar para trabalho em design system?

Sim. Ela é bem adequada para definir padrões acessíveis em componentes reutilizáveis, especialmente quando semântica, tratamento de teclado, estado ARIA e gestão de foco precisam ser consistentes em vários produtos.

Como melhorar a skill accessibility-compliance

Dê artefatos reais para a skill accessibility-compliance, não resumos

A forma mais rápida de melhorar os resultados de accessibility-compliance é fornecer JSX, HTML, código React Native, screenshots com anotações ou uma descrição passo a passo da interação. A skill não consegue inferir com confiabilidade ordem de foco, labels ou anúncios a partir de resumos vagos do produto.

Peça mapeamento de problemas, não só recomendações

Uma solicitação mais forte é:

• “List each issue, affected users, violated principle or criterion, and exact fix.”

Isso leva o modelo a produzir uma saída auditável. Sem essa estrutura, as respostas tendem a escorregar para conselhos genéricos.

Diga qual nível de mudança é aceitável

Correções de acessibilidade muitas vezes envolvem trade-offs com restrições do design system. Deixe claro se o agente pode:

• alterar apenas o markup
• adicionar ARIA apenas onde for necessário
• reestruturar a hierarquia do componente
• ajustar o texto para melhorar clareza
• mudar padrões de interação se o design atual for inacessível

Isso afeta a qualidade do resultado mais do que a maioria dos usuários imagina.

Falha comum: uso excessivo de ARIA

Um problema previsível em acessibilidade é adicionar ARIA onde HTML nativo funcionaria melhor. Para melhorar a saída, diga explicitamente:

• “Prefer native semantic elements and only use ARIA when native semantics are insufficient.”

Essa instrução está alinhada com a referência de ARIA do repositório e reduz correções de baixa qualidade.

Falha comum: esquecer mudanças de estado

Muitas respostas de primeira passada identificam labels e foco, mas deixam passar comportamento dinâmico. Peça especificamente:

• entrada e retorno de foco
• anúncios de estado expanded/collapsed
• associação de erros de validação
• mensagens assíncronas de status com live regions
• considerações sobre reduced motion e alto contraste quando relevantes

Esses detalhes melhoram de forma concreta a utilidade do accessibility-compliance guide.

Itere depois da primeira resposta

Depois da auditoria inicial, continue com uma destas opções:

• “Rewrite the component with the fixes applied.”
• “Prioritize only release-blocking issues.”
• “Convert this into QA test steps.”
• “Explain what should be tested with screen readers.”
• “Separate WCAG AA requirements from nice-to-have AAA improvements.”

Isso transforma a skill de revisora em apoio real para entrega.

Use as referências do repositório de forma cirúrgica

Não leia o repositório inteiro primeiro. Se o seu problema for:

• estrutura semântica ou meta de conformidade: comece por references/wcag-guidelines.md
• comportamento de widgets ou roles: abra references/aria-patterns.md
• touch targets ou tecnologias assistivas mobile: abra references/mobile-accessibility.md

Esse caminho de leitura direcionado torna accessibility-compliance install e a adoção mais rápidos.

Aumente a confiança pedindo justificativa

Peça à skill para explicar por que cada correção importa para usuários de teclado, usuários de leitores de tela, pessoas com baixa visão ou usuários com sensibilidade a movimento. Isso ajuda a detectar correções superficiais e dá ao time argumentos para sustentar o trabalho de implementação durante as revisões.

Melhor forma de obter uma saída pronta para produção

Para extrair o máximo valor de accessibility-compliance usage, peça tudo isso de uma vez:

• achados priorizados
• código corrigido
• justificativa
• checklist de verificação manual
• riscos ou premissas remanescentes

Esse pacote é o que a maioria das equipes realmente precisa para sair de “precisamos melhorar a acessibilidade” para “conseguimos implementar e validar isso agora”.