agentleFS
Sign inStart free
krzysztofsurdykrzysztofsurdy/code-virtuoso/skills/knowledge/accessibility/SKILL.md

accessibility

Skill36 starsChanged 6 days agoMITView on GitHub

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.

We split this skill into the rules it gives an agent

9 rules. 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 96 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never skip levels (do not jump from <h2> to <h4>)

    line 57
  2. Distinctive:

    Use headings for structure, not visual styling.

    line 58
  3. Distinctive:

    Every form control needs a programmatically associated label:

    line 87
  4. Very specific:

    Use aria-describedby to associate error messages with their input

    line 104
  5. Very specific:

    Use aria-invalid="true" on fields that fail validation

    line 105
  6. Distinctive:

    Write clear, specific error text ("Enter an email in the format name@example.com", not "Invalid input")

    line 106
  7. Distinctive:

    Do not rely on color or an asterisk alone to indicate required status.

    line 111
  8. Distinctive:

    Check contrast with browser developer tools (Chrome DevTools shows ratios on hover)

    line 128
  9. Distinctive:

    Test designs with simulated color blindness (protanopia, deuteranopia, tritanopia)

    line 130

“Common” is measured: kept by at least 6 in 10 of the 96 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Web Accessibility

Accessibility is a quality attribute, not a feature to bolt on at the end. Consider it from the first line of markup. Legislation in most jurisdictions (ADA, EAA, Section 508, EN 301 549) requires digital products to be accessible.

WCAG principles: POUR

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

PrincipleQuestion it answersExamples
PerceivableCan users sense the content?Text alternatives for images, captions for video, sufficient color contrast, resizable text
OperableCan users interact with every control?Keyboard operability, enough time to complete tasks, no seizure-triggering animations, clear navigation
UnderstandableCan users comprehend the content and UI behavior?Readable language, predictable navigation, input assistance and error messages
RobustDoes 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.

LevelTarget audienceTypical requirement
ABare minimum, removes the most severe barriersMost legal and procurement requirements start here
AAIndustry standard, addresses the majority of barriers for most usersRequired by ADA, EAA, Section 508, and most organizational policies
AAAHighest standard, not achievable for all content typesAspirational; 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 ofUseWhy
<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

IssueImpactFix
Missing alt text on imagesScreen readers announce the filename or nothingAdd descriptive alt; use alt="" for purely decorative images
Insufficient color contrastUsers with low vision cannot read textMeet 4.5:1 ratio for normal text, 3:1 for large text (AA)
No keyboard access to interactive elementsKeyboard and switch users are completely blockedUse native interactive elements or add tabindex="0" and key handlers
Missing form labelsScreen readers cannot announce what an input is forAssociate every input with a <label> using for/id or wrapping
Auto-playing mediaDisorienting for screen reader users, harmful for those with cognitive disabilitiesNever auto-play; if unavoidable, provide a visible pause/stop control
Missing skip linkKeyboard users must tab through the entire nav on every pageAdd a skip-to-main-content link as the first focusable element
No focus indicatorKeyboard users lose track of their position on the pageNever remove outline without providing a visible custom alternative
Missing page languageScreen readers may mispronounce contentSet lang attribute on <html> (e.g., lang="en")
Inaccessible dynamic contentScreen readers do not announce changes that happen after page loadUse ARIA live regions to announce dynamic updates
Missing document titleScreen reader users cannot identify the page when switching tabsSet a unique, descriptive <title> for every page
Touch targets too smallMotor-impaired users cannot reliably tap small controlsMinimum 24x24 CSS pixels (AA), prefer 44x44 for comfortable interaction
Motion and animationCan cause vertigo, nausea, or seizuresRespect 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:

<!-- 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):

ElementMinimum ratio
Normal text (under 18pt / 14pt bold)4.5:1
Large text (18pt+ / 14pt+ bold)3:1
UI components and graphical objects3: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

ReferenceContents
ARIA PatternsWhen to use ARIA, roles and properties, widget patterns (tabs, modals, accordions, dropdowns), live regions, landmark roles
Keyboard and FocusTab order, arrow key navigation, focus trapping, skip links, focus restoration, visible focus indicators, touch targets
Testing StrategiesAutomated tools, manual testing checklist, screen reader testing, contrast verification, accessibility tree, CI integration

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free