wcag-accessibility
Skill194 starsChanged 4 months agoMITView on GitHub
WCAG 2.2 AA compliance as required by the European Accessibility Act. Use when designing, building or reviewing any user-facing interface for accessibility.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- mrKanoh/wcag-accessibility-audit-skilltheir own version, first seen Nov 1, 2026
- mrKanoh/claude-wcag-accessibility-skilltheir own version, first seen Apr 21, 2026
- LeahyCC/claude-skillstheir own version, first seen Mar 29, 2026
- salawi45/skill-wcag-accessibilitytheir own version, first seen Mar 23, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- mrKanoh/claude-wcag-accessibility-skill★ 10same name
- mrKanoh/wcag-accessibility-audit-skill★ 10same name
- LeahyCC/claude-skills★ 3same name
- salawi45/skill-wcag-accessibility★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository44 other files it gives its agents.
- algorithmic-color-paletteSkill
- app-shellSkill
- authentic-product-representationSkill
- brand-visual-languageSkill
- button-statesSkill
- clone-websiteSkill
- color-mode-and-themeSkill
- component-family-consistencySkill
- coordinated-data-viewsSkill
- data-display-and-selectionSkill
- dembrandtSkill
- domain-expert-configurationSkill
- elevation-and-depthSkill
- extract-designSkill
- form-designSkill
- generate-ui-from-brandSkill
- gestalt-ui-organisationSkill
- global-toolbar-controlsSkill
- information-architectureSkill
- layout-paradigms-and-consistencySkill
- loading-states-and-perceived-performanceSkill
- marketing-vs-product-systemSkill
- micro-interactionsSkill
- modal-and-overlay-patternsSkill
- modular-scale-typographySkill
- motion-and-storytellingSkill
- nielsen-usability-heuristicsSkill
- notifications-and-recoverySkill
- operational-expert-tool-uiSkill
- performance-and-web-vitalsSkill
- real-world-metaphorsSkill
- repeated-component-alignmentSkill
- responsive-paradigmsSkill
- scroll-areasSkill
- semantic-html-and-seoSkill
- sizing-unitsSkill
- status-colors-and-errorsSkill
- sticky-and-fixed-elementsSkill
- surface-separationSkill
- tab-navigationSkill
- ui-context-and-scopeSkill
- ui-densitySkill
- user-flows-and-guided-pathsSkill
- visual-emphasis-and-hierarchySkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 7 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 84
Do not use colour as the only means of conveying information (e.g.
- Very specific: line 89
Every meaningful image needs alt text describing its content or function
- Distinctive: line 105
All interactive elements must be reachable and operable by keyboard alone.
- Distinctive: line 107
Every button, link, input, and control must receive focus via Tab
- Distinctive: line 109
No keyboard traps — users must be able to navigate away from any component
- Very specific: line 123
Never use outline: none without providing a custom focus style.
- Distinctive: line 147
Every form input must have a visible label — not just a placeholder (placeholders disappear on input)
- Distinctive: line 167
Use the correct HTML element for the job.
- Distinctive: line 205
Do not add artificial contrast to disabled elements — the reduced contrast communicates "this is unavailable"
“Common” is measured: kept by at least 6 in 10 of the 4 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.
Files
WCAG Accessibility (EN 301 549 / European Standard)
The Standard
The European Accessibility Act (EAA) requires digital products and services in the EU to meet EN 301 549, which references WCAG 2.2 Level AA as the technical baseline. This is not optional — it is a legal requirement for products operating in the EU market.
Default: always build to WCAG 2.2 AA. Deviating requires explicit, documented justification. Do not skip accessibility requirements because of timeline pressure or design preference.
WCAG 2.2 AA organises requirements under four principles: Perceivable, Operable, Understandable, Robust.
Perceivable
Users must be able to perceive all content and UI components.
Colour Contrast
| Context | Minimum ratio | Enhanced (AAA) |
| Normal text (< 18pt / < 14pt bold) | 4.5 : 1 | 7 : 1 |
| Large text (≥ 18pt / ≥ 14pt bold) | 3 : 1 | 4.5 : 1 |
| UI components and graphical objects | 3 : 1 | — |
Check contrast on the real rendered page, not the spec (dembrandt engine, optional). Design-time swatches lie once real text lands on real backgrounds, gradients, and overlays.
get_findings/render_reportrun against the live DOM and surface the actual failing text/background pairs with their measured ratios — a fast way to catch the combinations a static palette review misses. Seeextract-design.
Disabled elements are exempt. WCAG explicitly excludes inactive UI components from contrast requirements (WCAG 1.4.3 exception). A disabled button may use low-contrast text — this is intentional and correct, as it communicates the unavailable state.
Do not use colour as the only means of conveying information (e.g. a red border alone to indicate an error — add an icon or text label).
Weight is part of legibility, and the ratio cannot see it. The contrast formula measures ink colour against background colour and nothing else. It scores a hairline and a heavy weight identically at the same hue, while perceived legibility is the product of both. So the palette's faintest legible colour and the type scale's lightest weight must not land on the same text: a muted or secondary token, the one carrying captions, labels and helper text, takes a weight of at least 500 wherever the body default reads as regular or light. That floor is a house rule, not a WCAG requirement. The standard has nothing to say about weight, which is exactly why the failure gets through the audit. The same physics on dark surfaces is in [[color-mode-and-theme]]. A muted colour is already the palette's least assertive choice, and pairing it with the lightest weight compounds two decisions that both mean recede. The result at caption sizes is text a reader has to work at consciously, while the audit reports a pass.
Text Alternatives
- Every meaningful image needs
alttext describing its content or function - Decorative images use
alt=""so screen readers skip them - Icons used as buttons need an accessible label:
aria-labelor visually hidden text - Charts and data visualisations need a text summary or data table alternative
Captions and Transcripts
- Video content needs captions
- Audio-only content needs a transcript
Operable
Users must be able to operate all UI components.
Keyboard Navigation
All interactive elements must be reachable and operable by keyboard alone.
- Every button, link, input, and control must receive focus via Tab
- Focus order must follow the visual reading order of the page
- No keyboard traps — users must be able to navigate away from any component
- Modal dialogs must trap focus inside while open, and return focus to the trigger element on close
Focus Visibility
A visible focus indicator is required on every interactive element (WCAG 2.2 strengthens focus visibility requirements).
/* Minimum: do not remove focus outline without a replacement */
:focus-visible {
outline: 2px solid var(--color-focus);
outline-offset: 2px;
}Never use outline: none without providing a custom focus style. The focus ring is not a design problem to eliminate — it is a navigation tool.
Replace the outline by hiding it, not removing it. When a custom ring (often a box-shadow) takes over, set outline: 2px solid transparent instead of outline: none. Forced-colours and high-contrast modes repaint a transparent outline in a visible system colour, but they do not paint box-shadows, so a removed outline leaves those users with no focus at all. Normal mode looks identical either way, which is why the bug survives review. Check what a framework's "no outline" utility actually emits.
Touch Target Size
Interactive elements on touch devices must be at least 24×24px (WCAG 2.2) — 44×44px is the recommended comfortable minimum (Apple HIG, Material Design). Small icon buttons need padding to reach this size even if the visual icon is smaller.
No Seizure Triggers
Nothing on screen should flash more than 3 times per second.
Skip Links
Pages with repeated navigation must provide a "Skip to main content" link as the first focusable element, so keyboard users can bypass navigation on every page.
Understandable
Users must be able to understand the content and how the UI works.
Language
- Set
langattribute on the<html>element:<html lang="fi">or<html lang="en"> - Mark inline content in a different language with
langon that element
Labels and Instructions
- Every form input must have a visible label — not just a placeholder (placeholders disappear on input)
- Required fields must be indicated — do not rely on colour alone; add an asterisk and a legend
- Error messages must be associated with their input via
aria-describedby
Predictability
- Components that look the same must behave the same (see Consistency and Standards)
- Navigation must appear in the same location across pages
- Opening a new tab or window must be communicated in advance
Error Identification
- Form validation errors must identify which field failed
- Errors must be described in text — not only by colour or icon
Robust
Content must be interpreted reliably by assistive technologies.
Semantic HTML
Use the correct HTML element for the job. Semantics convey role, state, and structure to screen readers for free.
<!-- Correct -->
<button>Save</button>
<nav aria-label="Main navigation">...</nav>
<h1>Page title</h1>
<!-- Wrong — requires manual ARIA to replicate what the element provides natively -->
<div onclick="save()">Save</div>
<div class="nav">...</div>
<div class="heading">Page title</div>ARIA — Use Sparingly
ARIA supplements HTML semantics where native elements fall short. It does not fix broken HTML.
Rule: no ARIA is better than incorrect ARIA. Incorrect ARIA actively breaks screen reader output.
Required patterns:
aria-labeloraria-labelledbyfor components with no visible text labelaria-expandedon toggles, accordions, and dropdownsaria-liveregions for dynamic content updates (toast notifications, search results)role="dialog"witharia-modal="true"on modal overlaysaria-current="page"on the active navigation item
Status Messages
Dynamic updates (success toasts, loading states, error counts) must be announced to screen readers via aria-live or role="status" — they will not be announced automatically unless the focused element changes.
The Disabled Element Exception
WCAG 1.4.3 explicitly states: "Text or images of text that are part of an inactive user interface component… have no contrast requirement."
This means:
- Disabled buttons, inputs, and links may use low-contrast text and colours
- The visual dimming of disabled states is both correct and compliant
- Do not add artificial contrast to disabled elements — the reduced contrast communicates "this is unavailable"
Review Checklist
| Area | Check |
| Contrast | All active text ≥ 4.5:1 (normal) or 3:1 (large/UI) |
| Contrast | Disabled elements exempt — intentionally low contrast is fine |
| Colour | Colour is never the only information carrier |
| Keyboard | All interactive elements reachable and operable by keyboard |
| Focus | Visible focus indicator on every interactive element |
| Focus | Custom rings keep a transparent outline for forced-colours mode, never outline: none |
| Touch | Interactive targets ≥ 44×44px on touch surfaces |
| Labels | Every input has a visible label (not just placeholder) |
| Errors | Validation errors identify the field and describe the problem in text |
| HTML | Semantic elements used correctly; ARIA only where needed |
| Language | lang attribute set on <html> |
| Skip link | "Skip to main content" as first focusable element |
| Live regions | Dynamic updates announced via aria-live or role="status" |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
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.

