Communitygithub.com

Padrões de Auditoria WCAG

Realize auditorias de acessibilidade WCAG 2.2 com testes automatizados, verificação manual e orientações de remediação. Use ao auditar sites para acessibilidade, corrigir violações WCAG ou implementar padrões de design acessível.

O que é Padrões de Auditoria WCAG?

Esta skill fornece um guia abrangente para auditar conteúdo web de acordo com as diretrizes WCAG 2.2, incluindo estratégias de remediação acionáveis. Ela é útil para desenvolvedores, designers e profissionais de qualidade que precisam garantir que seus sites estejam em conformidade com leis de acessibilidade como ADA, Seção 508 e VPAT. A skill suporta plataformas como axe-core, Playwright e ferramentas de linha de comando (CLI) para testes automatizados, além de orientar verificações manuais para violações que exigem julgamento humano. O conteúdo é organizado pelos quatro princípios POUR (Perceptível, Operável, Compreensível e Robusto) e inclui checklists detalhados, exemplos de código, correções de remediação e listas de verificação para cada nível de conformidade (A, AA, AAA).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ulasalyesil/personal-website-v2/tree/HEAD/.agent/skills/wcag-audit-patterns

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

Padrões de Auditoria WCAG preview
Padrões de Auditoria WCAG preview

Documentação

O que Padrões de Auditoria WCAG faz?

Guia abrangente para auditar conteúdo web de acordo com as diretrizes WCAG 2.2 com estratégias de remediação acionáveis.

Quando Usar Esta Skill

  • Conduzindo auditorias de acessibilidade
  • Corrigindo violações WCAG
  • Implementando componentes acessíveis
  • Preparando-se para processos judiciais de acessibilidade
  • Atendendo aos requisitos ADA/Seção 508
  • Alcançando conformidade VPAT

Conceitos Principais

1. Níveis de Conformidade WCAG

NívelDescriçãoObrigatório Para
AAcessibilidade mínimaBase legal
AAConformidade padrãoMaioria das regulamentações
AAAAcessibilidade aprimoradaNecessidades especializadas

2. Princípios POUR

Perceptível:  Os usuários conseguem perceber o conteúdo?
Operável:     Os usuários conseguem operar a interface?
Compreensível: Os usuários conseguem entender o conteúdo?
Robusto:      Funciona com tecnologia assistiva?

3. Violações Comuns por Impacto

Crítico (Bloqueadores):
├── Texto alternativo ausente em imagens funcionais
├── Sem acesso por teclado a elementos interativos
├── Rótulos de formulário ausentes
├── Mídia com reprodução automática sem controles

Grave:
├── Contraste de cor insuficiente
├── Links de pular ausentes
├── Widgets personalizados inacessíveis
├── Títulos de página ausentes

Moderado:
├── Atributo de idioma ausente
├── Texto de link pouco claro
├── Marcos ausentes
├── Hierarquia de cabeçalhos inadequada

Lista de Verificação de Auditoria

Perceptível (Princípio 1)

## 1.1 Alternativas em Texto

### 1.1.1 Conteúdo Não Textual (Nível A)

- [ ] Todas as imagens possuem texto alternativo
- [ ] Imagens decorativas possuem alt=""
- [ ] Imagens complexas possuem descrições longas
- [ ] Ícones com significado possuem nomes acessíveis
- [ ] CAPTCHAs possuem alternativas

Verificar:

```html
<!-- Bom -->
<img src="chart.png" alt="As vendas aumentaram 25% do Q1 para o Q2" />
<img src="decorative-line.png" alt="" />

<!-- Ruim -->
<img src="chart.png" />
<img src="decorative-line.png" alt="linha decorativa" />
```

1.2 Mídia Baseada em Tempo

1.2.1 Somente Áudio e Somente Vídeo (Nível A)

  • Áudio possui transcrição em texto
  • Vídeo possui descrição em áudio ou transcrição

1.2.2 Legendas (Nível A)

  • Todo vídeo possui legendas sincronizadas
  • Legendas são precisas e completas
  • Identificação do falante incluída

1.2.3 Descrição em Áudio (Nível A)

  • Vídeo possui descrição em áudio para conteúdo visual

1.3 Adaptável

1.3.1 Informações e Relações (Nível A)

  • Cabeçalhos usam tags apropriadas (h1-h6)
  • Listas usam ul/ol/dl
  • Tabelas possuem cabeçalhos
  • Entradas de formulário possuem rótulos
  • Marcos ARIA presentes

Verificar:

<!-- Hierarquia de cabeçalhos -->
<h1>Título da Página</h1>
<h2>Seção</h2>
<h3>Subseção</h3>
<h2>Outra Seção</h2>

<!-- Cabeçalhos de tabela -->
<table>
  <thead>
    <tr>
      <th scope="col">Nome</th>
      <th scope="col">Preço</th>
    </tr>
  </thead>
</table>

1.3.2 Sequência Significativa (Nível A)

  • Ordem de leitura é lógica
  • Posicionamento CSS não quebra a ordem
  • Ordem de foco corresponde à ordem visual

1.3.3 Características Sensoriais (Nível A)

  • Instruções não dependem apenas de forma/cor
  • "Clique no botão vermelho" → "Clique em Enviar (botão vermelho)"

1.4 Distinguível

1.4.1 Uso de Cor (Nível A)

  • Cor não é o único meio de transmitir informação
  • Links distinguíveis sem cor
  • Estados de erro não são apenas por cor

1.4.3 Contraste (Mínimo) (Nível AA)

  • Texto: taxa de contraste 4,5:1
  • Texto grande (18pt+): taxa 3:1
  • Componentes de UI: taxa 3:1

Ferramentas: WebAIM Contrast Checker, axe DevTools

1.4.4 Redimensionar Texto (Nível AA)

  • Texto redimensiona até 200% sem perda
  • Sem rolagem horizontal a 320px
  • Conteúdo se reorganiza adequadamente

1.4.10 Refluir (Nível AA)

  • Conteúdo reflui com zoom de 400%
  • Sem rolagem bidimensional
  • Todo conteúdo acessível com largura de 320px

1.4.11 Contraste de Não Texto (Nível AA)

  • Componentes de UI têm contraste 3:1
  • Indicadores de foco visíveis
  • Objetos gráficos distinguíveis

1.4.12 Espaçamento de Texto (Nível AA)

  • Sem perda de conteúdo com espaçamento aumentado
  • Altura de linha 1,5x tamanho da fonte
  • Espaçamento entre parágrafos 2x tamanho da fonte
  • Espaçamento entre letras 0,12x tamanho da fonte
  • Espaçamento entre palavras 0,16x tamanho da fonte

### Operável (Princípio 2)

```markdown
## 2.1 Acessível por Teclado

### 2.1.1 Teclado (Nível A)
- [ ] Toda funcionalidade acessível por teclado
- [ ] Sem armadilhas de teclado
- [ ] Ordem de tabulação lógica
- [ ] Widgets personalizados operáveis por teclado

Verificar:
```javascript
// Botão personalizado deve ser acessível por teclado
<div role="button" tabindex="0"
     onkeydown="if(event.key === 'Enter' || event.key === ' ') ativar()">
```

### 2.1.2 Sem Armadilha de Teclado (Nível A)

- [ ] Foco pode sair de todos os componentes
- [ ] Diálogos modais prendem foco corretamente
- [ ] Foco retorna após modal fechar

## 2.2 Tempo Suficiente

### 2.2.1 Tempo Ajustável (Nível A)

- [ ] Timeouts de sessão podem ser estendidos
- [ ] Usuário avisado antes do timeout
- [ ] Opção de desabilitar atualização automática

### 2.2.2 Pausar, Parar, Ocultar (Nível A)

- [ ] Conteúdo em movimento pode ser pausado
- [ ] Conteúdo com atualização automática pode ser pausado
- [ ] Animações respeitam prefers-reduced-motion

```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}
```

## 2.3 Convulsões e Reações Físicas

### 2.3.1 Três Flashes (Nível A)

- [ ] Nenhum conteúdo pisca mais de 3 vezes/segundo
- [ ] Área de flash é pequena (<25% viewport)

## 2.4 Navegável

### 2.4.1 Pular Blocos (Nível A)

- [ ] Link para pular para conteúdo principal presente
- [ ] Regiões de marco definidas
- [ ] Estrutura de cabeçalho adequada

```html
<a href="#main" class="skip-link">Pular para conteúdo principal</a>
<main id="main">...</main>
```

### 2.4.2 Página Titulada (Nível A)

- [ ] Títulos de página únicos e descritivos
- [ ] Título reflete o conteúdo da página

### 2.4.3 Ordem de Foco (Nível A)

- [ ] Ordem de foco corresponde à ordem visual
- [ ] tabindex usado corretamente

### 2.4.4 Propósito do Link (Em Contexto) (Nível A)

- [ ] Links fazem sentido fora de contexto
- [ ] Sem "clique aqui" ou "leia mais" sozinhos

```html
<!-- Ruim -->
<a href="report.pdf">Clique aqui</a>

<!-- Bom -->
<a href="report.pdf">Baixar Relatório de Vendas Q4 (PDF)</a>
```

### 2.4.6 Cabeçalhos e Rótulos (Nível AA)

- [ ] Cabeçalhos descrevem conteúdo
- [ ] Rótulos descrevem propósito

### 2.4.7 Foco Visível (Nível AA)

- [ ] Indicador de foco visível em todos os elementos
- [ ] Estilos de foco personalizados atendem contraste

```css
:focus {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}
```

### 2.4.11 Foco Não Obscurecido (Nível AA) - WCAG 2.2

- [ ] Elemento focado não totalmente oculto
- [ ] Cabeçalhos fixos não obscurecem foco

```

### Compreensível (Princípio 3)

```markdown
## 3.1 Legível

### 3.1.1 Idioma da Página (Nível A)
- [ ] Atributo lang do HTML definido
- [ ] Idioma correto para o conteúdo

```html
<html lang="pt">
```

### 3.1.2 Idioma das Partes (Nível AA)

- [ ] Mudanças de idioma marcadas

```html
<p>A palavra francesa <span lang="fr">bonjour</span> significa olá.</p>
```

## 3.2 Previsível

### 3.2.1 Ao Foco (Nível A)

- [ ] Nenhuma mudança de contexto apenas com foco
- [ ] Sem popups inesperados ao focar

### 3.2.2 Na Entrada (Nível A)

- [ ] Sem envio automático de formulário
- [ ] Usuário avisado antes de mudança de contexto

### 3.2.3 Navegação Consistente (Nível AA)

- [ ] Navegação consistente entre páginas
- [ ] Componentes repetidos na mesma ordem

### 3.2.4 Identificação Consistente (Nível AA)

- [ ] Mesma funcionalidade = mesmo rótulo
- [ ] Ícones usados consistentemente

## 3.3 Assistência de Entrada

### 3.3.1 Identificação de Erro (Nível A)

- [ ] Erros claramente identificados
- [ ] Mensagem de erro descreve o problema
- [ ] Erro vinculado ao campo

```html
<input aria-describedby="email-erro" aria-invalid="true" />
<span id="email-erro" role="alert">Por favor, insira um e-mail válido</span>
```

### 3.3.2 Rótulos ou Instruções (Nível A)

- [ ] Todas as entradas possuem rótulos visíveis
- [ ] Campos obrigatórios indicados
- [ ] Dicas de formato fornecidas

### 3.3.3 Sugestão de Erro (Nível AA)

- [ ] Erros incluem sugestão de correção
- [ ] Sugestões são específicas

### 3.3.4 Prevenção de Erro (Nível AA)

- [ ] Formulários legais/financeiros reversíveis
- [ ] Dados verificados antes do envio
- [ ] Usuário pode revisar antes de enviar

Robusto (Princípio 4)

## 4.1 Compatível

### 4.1.1 Parsing (Nível A) - Obsoleto no WCAG 2.2
- [ ] HTML válido (boa prática)
- [ ] Sem IDs duplicados
- [ ] Tags de abertura/fechamento completas

### 4.1.2 Nome, Função, Valor (Nível A)
- [ ] Widgets personalizados têm nomes acessíveis
- [ ] Funções ARIA corretas
- [ ] Mudanças de estado anunciadas

```html
<!-- Checkbox personalizado acessível -->
<div role="checkbox"
     aria-checked="false"
     tabindex="0"
     aria-labelledby="label">
</div>
<span id="label">Aceitar termos</span>

4.1.3 Mensagens de Status (Nível AA)

  • Atualizações de status anunciadas
  • Regiões ativas usadas corretamente
<div role="status" aria-live="polite">3 itens adicionados ao carrinho</div>

<div role="alert" aria-live="assertive">Erro: Falha no envio do formulário</div>

## Teste Automatizado

```javascript
// Integração com axe-core
const axe = require('axe-core');

async function executarAuditoriaAcessibilidade(pagina) {
  await pagina.addScriptTag({ path: require.resolve('axe-core') });

  const resultados = await pagina.evaluate(async () => {
    return await axe.run(document, {
      runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa']
      }
    });
  });

  return {
    violacoes: resultados.violations,
    aprovados: resultados.passes,
    incompletos: resultados.incomplete
  };
}

// Exemplo de teste Playwright
test('não deve ter violações de acessibilidade', async ({ page }) => {
  await page.goto('/');
  const resultados = await executarAuditoriaAcessibilidade(page);

  expect(resultados.violacoes).toHaveLength(0);
});
```

```bash
# Ferramentas CLI
npx @axe-core/cli https://exemplo.com
npx pa11y https://exemplo.com
lighthouse https://exemplo.com --only-categories=accessibility
```

## Padrões de Remediação

### Correção: Rótulos de Formulário Ausentes

```html
<!-- Antes -->
<input type="email" placeholder="Email" />

<!-- Depois: Opção 1 - Rótulo visível -->
<label for="email">Endereço de Email</label>
<input id="email" type="email" />

<!-- Depois: Opção 2 - aria-label -->
<input type="email" aria-label="Endereço de Email" />

<!-- Depois: Opção 3 - aria-labelledby -->
<span id="email-label">Email</span>
<input type="email" aria-labelledby="email-label" />
```

### Correção: Contraste de Cor Insuficiente

```css
/* Antes: 2,5:1 de contraste */
.text {
  color: #767676;
}

/* Depois: 4,5:1 de contraste */
.text {
  color: #595959;
}

/* Ou adicionar fundo */
.text {
  color: #767676;
  background: #000;
}
```

### Correção: Navegação por Teclado

```javascript
// Tornar elemento personalizado acessível por teclado
class DropdownAcessivel extends HTMLElement {
  connectedCallback() {
    this.setAttribute("tabindex", "0");
    this.setAttribute("role", "combobox");
    this.setAttribute("aria-expanded", "false");

    this.addEventListener("keydown", (e) => {
      switch (e.key) {
        case "Enter":
        case " ":
          this.alternar();
          e.preventDefault();
          break;
        case "Escape":
          this.fechar();
          break;
        case "ArrowDown":
          this.focarProximo();
          e.preventDefault();
          break;
        case "ArrowUp":
          this.focarAnterior();
          e.preventDefault();
          break;
      }
    });
  }
}
```

## Melhores Práticas

### Faça

- **Comece cedo** - Acessibilidade desde a fase de design
- **Teste com usuários reais** - Usuários com deficiência fornecem o melhor feedback
- **Automatize o que puder** - 30-50% dos problemas detectáveis
- **Use HTML semântico** - Reduz a necessidade de ARIA
- **Documente padrões** - Construa uma biblioteca de componentes acessíveis

### Não Faça

- **Não confie apenas em testes automatizados** - Teste manual é necessário
- **Não use ARIA como primeira solução** - HTML nativo primeiro
- **Não oculte contornos de foco** - Usuários de teclado precisam deles
- **Não desabilite o zoom** - Usuários precisam redimensionar
- **Não use apenas cor** - Vários indicadores são necessários

## Recursos

- [Diretrizes WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [WebAIM](https://webaim.org/)
- [Lista de Verificação do Projeto A11y](https://www.a11yproject.com/checklist/)
- [axe DevTools](https://www.deque.com/axe/)

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ulasalyesil/personal-website-v2

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

ulasalyesil/personal-website-v2

Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.

ulasalyesil/personal-website-v2

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

ulasalyesil/personal-website-v2

Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.

ulasalyesil/personal-website-v2

This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).

ulasalyesil/personal-website-v2

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

ulasalyesil/personal-website-v2

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples.

ulasalyesil/personal-website-v2

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

ulasalyesil/personal-website-v2

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

ulasalyesil/personal-website-v2

Build modern, composable, and accessible React UI components following the components.build specification. Use when creating, reviewing, or refactoring component libraries, design systems, or any reusable UI components. Triggers on tasks involving component APIs, composition patterns, accessibility, styling systems, or TypeScript props.

ulasalyesil/personal-website-v2

Ship correct, complete metadata.

ulasalyesil/personal-website-v2

Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.

ulasalyesil/personal-website-v2

Defines the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer

ulasalyesil/personal-website-v2

Maps domain concepts, terminology conflicts, and bounded contexts — produces a noun harvest for the conceptual model layer

ulasalyesil/personal-website-v2

Maps interaction structure and flow — produces breadboard notation with edge cases, failure paths, and open decisions

ulasalyesil/personal-website-v2

Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on

ulasalyesil/personal-website-v2

User research planning and synthesis at the observed behaviour layer — produces candidate job stories with confidence ratings

ulasalyesil/personal-website-v2

Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus

ulasalyesil/personal-website-v2

Connects user opportunities to business outcomes and solution bets — produces a strategy tree and prioritised experiments

ulasalyesil/personal-website-v2

Audits existing surface against lower-layer decisions and produces a surface decision inventory — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility

Habilidades Relacionadas