Skip to content
Skills Library
Programming · Review & audit

accessibility

/accessibility

Web accessibility patterns and WCAG 2.1/2.2 compliance. Use to build accessible components, audit a UI for a11y issues, fix screen reader or keyboard problems, check contrast, or add ARIA.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Web accessibility patterns and WCAG 2.1/2.2 compliance. Use to build accessible components, audit a UI for a11y issues, fix screen reader or keyboard problems, check contrast, or add ARIA.

Original author description

Web accessibility patterns and WCAG 2.1/2.2 compliance. Use to build accessible components, audit a UI for a11y issues, fix screen reader or keyboard problems, check contrast, or add ARIA.

How it works

  1. Why accessibility matters
  2. WCAG principles: POUR
  3. Conformance levels
  4. Semantic HTML fundamentals
  5. Common accessibility issues
  6. Accessible forms
  7. Color and contrast
  8. Reference Files
  9. Integration with Other Skills
Original SKILL.md headings · 157 lines, 1,314 words
SKILL.md preview
---
name: accessibility
description: Web accessibility patterns and WCAG 2.1/2.2 compliance. Use to build accessible components, audit a UI for a11y issues, fix screen reader or keyboard problems, check contrast, or add ARIA.
allowed-tools: Read Grep Glob Bash
user-invocable: false
---

# Web Accessibility

Accessibility is a quality attribute, not a feature to bolt on at the end. Consider it from the first line of markup. Accessible interfaces let people with visual, motor, auditory, or cognitive disabilities perceive, navigate, and use your application. They also help keyboard power users, people on slow connections, users with temporary injuries, and anyone in a constrained environment.

## Why accessibility matters

| Dimension | Impact |
|---|---|
| **Legal** | Legislation in most jurisdictions (ADA, EAA, Section 508, EN 301 549) requires digital products to be accessible. Non-compliance carries litigation risk and financial penalties. |
| **Ethical** | Roughly 16% of the global population lives with some form of disability. Excluding them from digital services is a choice, not an inevitability. |
| **Business** | Accessible products reach a wider audience, improve SEO (structured content helps crawlers), reduce support costs, and correlate with higher overall usability scores. |
| **Technical quality** | Accessibility constraints force clean markup, proper semantics, and separation of concerns, which improves maintainability. |

---

## WCAG principles: POUR

The Web Content Accessibility Guidelines organize all success criteria under four principles. Every accessibility requirement maps to at least one.

| Principle | Question it answers | Examples |
|---|---|---|
| **Perceivable** | Can users sense the content? | Text alternatives for images, captions for video, sufficient color contrast, resizable text |
| **Operable** | Can users interact with every control? | Keyboard operability, enough time to complete tasks, no seizure-triggering animations, clear navigation |
| **Understandable** | Can users comprehend the content and UI behavior? | Readable language, predictable navigation, input assistance and error messages |
| **Robust** | Does it work across assistive technologies? | Valid markup, proper use of ARIA, compatibility with screen readers and other tools |

---

## Conformance levels

WCAG defines three levels. Each higher level includes all criteria from the levels below it.

| Level | Target audience | Typical requirement |
|---|---|---|
| **A** | Bare minimum, removes the most severe barriers | Most legal and procurement requirements start here |
| **AA** | Industry standard, addresses the majority of barriers for most users | Required by ADA, EAA, Section 508, and most organizational policies |
| **AAA** | Highest standard, not achievable for all content types | Aspirational; apply selectively where feasible |

For most projects, **target Level AA**. It meets most real-world needs and avoids requirements that conflict with some content types.

---

## Semantic HTML fundamentals

Native HTML elements carry built-in semantics, keyboard behavior, and screen reader announcements. Using the right element is the single most effective accessibility technique.

| Instead of | Use | Why |
|---|---|---|
| `<div onclick="...">` | `<button>` | Buttons are focusable, announce their role, and respond to Enter and Space |
| `<span class="link">` | `<a href="...">` | Links announce as "link," support middle-click, and appear in link lists |
| `<div class="header">` | `<header>`, `<nav>`, `<main>`, `<footer>` | Landmark elements let screen reader users jump between page regions |
| `<div class="list">` | `<ul>` / `<ol>` with `<li>` | Lists announce item count and position ("item 3 of 7") |
| `<div class="table">` | `<table>` with `<th>` | Table headers associate data cells with their labels for screen readers |
| Styled `<div>` for input | `<input>`, `<select>`, `<textarea>` | Native form controls have label association, validation, and assistive tech support built in |

### Heading hierarchy

Headings create an outline that screen reader users navigate like a table of contents.

- One `<h1>` per page that describes the page purpose
- Never skip levels (do not jump from `<h2>` to `<h4>`)
- Use headings for structure, not visual styling. CSS handles appearance

---

## Common accessibility issues

| Issue | Impact | Fix |
|---|---|---|
| Missing alt text on images | Screen readers announce the filename or nothing | Add descriptive `alt`; use `alt=""` for purely decorative images |
| Insufficient color contrast | Users with low vision cannot read text | Meet 4.5:1 ratio for normal text, 3:1 for large text (AA) |
| No keyboard access to interactive elements | Keyboard and switch users are completely blocked | Use native interactive elements or add `tabindex="0"` and key handlers |
| Missing form labels | Screen readers cannot announce what an input is for | Associate every input with a `<label>` using `for`/`id` or wrapping |
| Auto-playing media | Disorienting for screen reader users, harmful for those with cognitive disabilities | Never auto-play; if unavoidable, provide a visible pause/stop control |
| Missing skip link | Keyboard users must tab through the entire nav on every page | Add a skip-to-main-content link as the first focusable element |
| No focus indicator | Keyboard users lose track of their position on the page | Never remove `outline` without providing a visible custom alternative |
| Missing page language | Screen readers may mispronounce content | Set `lang` attribute on `<html>` (e.g., `lang="en"`) |
| Inaccessible dynamic content | Screen readers do not announce changes that happen after page load | Use ARIA live regions to announce dynamic updates |
| Missing document title | Screen reader users cannot identify the page when switching tabs | Set a unique, descriptive `<title>` for every page |
| Touch targets too small | Motor-impaired users cannot reliably tap small controls | Minimum 24x24 CSS pixels (AA), prefer 44x44 for comfortable interaction |
| Motion and animation | Can cause vertigo, nausea, or seizures | Respect `prefers-reduced-motion` media query; never flash more than 3 times per second |

---

## Accessible forms

Forms are where accessibility failures do the most damage: users cannot complete purchases, registrations, or other critical workflows.

### Label association

Every form control needs a programmatically associated label:

```html
<!-- Explicit association -->
<label for="email">Email address</label>
<input type="email" id="email" name="email" required>

<!-- Implicit association (wrapping) -->
<label>
  Email address
  <input type="email" name="email" required>
</label>
```

### Error handling

- Display errors inline next to the relevant field, not only at the top of the form
- Use `aria-describedby` to associate error messages with their input
- Use `aria-invalid="true"` on fields that fail validation
- Write clear, specific error text ("Enter an email in the format name@example.com", not "Invalid input")

### Required fields

- Mark required fields with the `required` attribute (native validation) or `aria-required="true"` (custom validation)
- Do not rely on color or an asterisk alone to indicate required status. Add text like "(required)"

---

## Color and contrast

Color must never be the only way to convey information. Pair it with text, icons, patterns, or other visual cues.

**Contrast ratios (WCAG AA):**

| Element | Minimum ratio |
|---|---|
| Normal text (under 18pt / 14pt bold) | 4.5:1 |
| Large text (18pt+ / 14pt+ bold) | 3:1 |
| UI components and graphical objects | 3:1 |

**Quick wins:**
- Check contrast with browser developer tools (Chrome DevTools shows ratios on hover)
- Respect `prefers-color-scheme` for dark mode support
- Test designs with simulated color blindness (protanopia, deuteranopia, tritanopia)

---

## Reference Files

| Reference | Contents |
|---|---|
| [ARIA Patterns](references/aria-patterns.md) | When to use ARIA, roles and properties, widget patterns (tabs, modals, accordions, dropdowns), live regions, landmark roles |
| [Keyboard and Focus](references/keyboard-and-focus.md) | Tab order, arrow key navigation, focus trapping, skip links, focus restoration, visible focus indicators, touch targets |
| [Testing Strategies](references/testing-strategies.md) | Automated tools, manual testing checklist, screen reader testing, contrast verification, accessibility tree, CI integration |

---

## Integration with Other Skills

| Situation | Recommended Skill |
|---|---|
| Building REST or GraphQL APIs with accessible error responses | `api-design` |
| Security headers that affect accessibility (CSP, iframe restrictions) | `security` |
| Testing accessible components with unit and integration tests | `testing` |
| Performance optimization that does not sacrifice accessibility | `performance` |
Files in this package (4)
  • SKILL.md 9 KB
  • references/aria-patterns.md 8 KB
  • references/keyboard-and-focus.md 7 KB
  • references/testing-strategies.md 7 KB

Versions

RepositoryScoreLicence
This page · krzysztofsurdy/code-virtuoso100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
evanca/flutter-ai-rules100MIT
yonatangross/orchestkit100MIT
yonatangross/orchestkit100MIT
xobotyi/cc-foundry100MIT
andreibesleaga/gabbe100CC-BY-4.0
kennykennethkkang/switchboard100Apache-2.0

Database snapshot: 13.11.2026 · package version 63a4770d13aa (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 84audit-accessibility
    Audit UI components and pages for accessibility (a11y) issues. Use when user says "check accessibility", "audit a11y compliance", "find WCAG violations", "is this component accessible", "run an accessibility audit", or "check screen reader support".
  • 100a11y-review
    Review custom element HTML for accessibility issues. Use when the user asks to "review accessibility", "check a11y", "audit accessibility", "find accessibility issues", or mentions "WCAG", "screen reader", "keyboard navigation", or "ARIA" in the context of custom elements.
  • 95web-accessibility
    Implement web accessibility (a11y) standards following WCAG 2.1 guidelines. Use when building accessible UIs, fixing accessibility issues, or ensuring compliance with disability standards. Handles ARIA attributes, keyboard navigation, screen readers, semantic HTML, and accessibility testing.
  • 100accessibility-a11y
    Semantic HTML, keyboard navigation, focus states, ARIA labels, skip links, and WCAG contrast requirements. Use when ensuring accessibility compliance, implementing keyboard navigation, or adding screen reader support.
  • 90wcag-a11y-audit
    Use when auditing or fixing web accessibility: keyboard and focus, semantics and ARIA, accessible names, contrast, screen-reader checks against WCAG 2.2 AA.
  • 100accessibility-expert
    Expert web accessibility (a11y): WCAG 2.2 AA, semantic HTML, ARIA, keyboard, and screen readers. Trigger keywords: accessibility, a11y, WCAG, ARIA, role, screen reader, keyboard navigation, focus, focus trap, contrast, alt text, semantic HTML, label, axe, tab order. Use to build…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.