accessibility-compliance

Overview of accessibility-compliance skill

What the accessibility-compliance skill does

The accessibility-compliance skill helps an agent produce implementation-ready accessibility guidance for web and mobile UI work, with a strong focus on WCAG 2.2, ARIA usage, keyboard access, screen reader support, and mobile accessibility. It is best for teams doing real interface work, not just writing a generic accessibility checklist.

Who should install accessibility-compliance

This skill is a good fit for:

• UX auditors who need accessibility-compliance for UX Audit
• frontend engineers fixing accessibility issues in components
• design systems teams defining accessible interaction patterns
• product teams shipping forms, dialogs, menus, and other interactive UI
• mobile or cross-platform teams that need VoiceOver and TalkBack-aware guidance

If your job-to-be-done is “turn this screen or component into something closer to WCAG-compliant with concrete fixes,” this skill is more useful than a broad design prompt.

Why this skill is different from a generic prompt

The main value of the accessibility-compliance skill is that it narrows the model toward practical accessibility implementation patterns instead of vague principles. The repository includes focused references on:

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

That makes it better suited to tasks like choosing semantic HTML over ARIA, structuring accessible forms, improving keyboard behavior, or checking touch target guidance for mobile.

What users care about before installing

Most users evaluating accessibility-compliance install want to know:

• whether it gives concrete code-oriented fixes rather than policy language
• whether it covers both web and mobile concerns
• whether it helps with audits as well as implementation
• whether it is opinionated about native semantics vs ARIA
• whether it can reduce back-and-forth when reviewing UI components

On those points, this skill looks solid. Its strongest differentiation is practical breadth across WCAG concepts, ARIA patterns, and mobile accessibility in one package.

Best-fit and misfit cases

Best-fit:

• auditing interactive components
• fixing accessibility issues in existing code
• planning accessible behavior for dialogs, accordions, forms, and navigation
• reviewing focus order, labels, announcements, and reduced-motion support

Misfit:

• legal compliance interpretation for a specific jurisdiction
• automated testing setup by itself
• pixel-level visual design critique unrelated to accessibility
• deep platform-specific native APIs beyond the referenced guidance

How to Use accessibility-compliance skill

Install context and invocation

The upstream SKILL.md does not provide an install command, so directory users will typically add it from the repo:

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

Then invoke it by giving the agent a concrete accessibility task, not just “check accessibility.” The skill works best when the request includes a component, flow, or screen with enough structure to review.

Read these files first

For fast adoption, start here:

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

That reading order mirrors how most teams work: compliance target first, implementation patterns second, platform edge cases third.

What input the skill needs to work well

The accessibility-compliance usage quality depends heavily on the specificity of your input. Provide:

• component or page type
• current code or markup
• framework (React, Next.js, Vue, plain HTML, React Native)
• interaction behavior
• target standard, usually WCAG 2.2 AA
• device scope: desktop web, mobile web, iOS, Android
• known issues from audit tools or user testing

Weak input:

• “Make this accessible.”

Strong input:

• “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.”

Turn a rough goal into a good prompt

A good accessibility-compliance guide prompt usually has five parts:

1. target UI
2. user interactions
3. conformance target
4. expected deliverable
5. constraints

Example:

• “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.”

This is better than asking for “best practices” because it forces the model to produce fixable output.

Best workflow for a UX audit

For accessibility-compliance for UX Audit, use this sequence:

1. ask for issue discovery
2. ask for severity and user impact
3. ask for mapped fixes
4. ask for revised markup or component code
5. ask for a retest checklist

This avoids the common failure mode where the first answer stays too conceptual. The skill is most useful when you push it from audit findings into implementation details.

Use it for components, not just pages

The skill is especially strong on reusable interaction patterns. Good targets include:

• dialogs and focus traps
• accordions
• menus and disclosures
• forms and validation
• tabs
• carousels
• icon buttons
• mobile touch targets

These are exactly the places where generic prompts often overuse ARIA or miss keyboard and screen reader behavior.

What the references imply in practice

The included references suggest three important operating rules:

• prefer semantic HTML before adding ARIA
• treat WCAG 2.2 AA as the default baseline
• account for mobile accessibility, not only desktop keyboard use

That matters in real use. A decent prompt should explicitly ask the agent to minimize unnecessary ARIA and justify any ARIA attributes it adds.

Prompt pattern for stronger outputs

Use a request format like this:

• 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.”

This structure consistently produces better accessibility-compliance usage than open-ended review requests.

What to expect from the output

A good response from the accessibility-compliance skill should include:

• issue list tied to user impact
• references to accessibility principles or criteria
• specific markup or code changes
• keyboard and focus behavior notes
• screen reader naming and announcement guidance
• mobile-specific notes where relevant

If the output stops at principles without code-level correction, your prompt is too broad.

accessibility-compliance skill FAQ

Is accessibility-compliance good for beginners?

Yes, if you already know basic UI structure. The skill gives more value when you can provide markup, components, or audit findings. Beginners can still use it, but should expect to ask follow-up questions about why certain semantics or ARIA choices matter.

Is this better than a normal accessibility prompt?

Usually yes for implementation work. A normal prompt may return generic guidance like “add alt text” or “ensure keyboard navigation.” The accessibility-compliance skill is more likely to stay anchored to WCAG 2.2, ARIA patterns, and mobile accessibility concerns found in the repository references.

Does it replace automated accessibility testing?

No. It complements automated tools and manual review. Use it to interpret issues, propose fixes, and review component behavior that static tools often miss, such as focus management, announcement timing, or mobile interaction details.

When should I not use accessibility-compliance?

Skip it when you need:

• legal advice or certification decisions
• fully automated codebase-wide scanning
• deep native mobile platform specifics beyond the referenced patterns
• non-accessibility UX critique

It is a guidance skill, not a compliance guarantee.

Does it support mobile accessibility well?

Reasonably well for an AI skill. The dedicated mobile-accessibility.md reference covers touch target sizing, spacing, and screen reader concerns for iOS and Android. That makes this skill more credible for mobile review than accessibility prompts focused only on desktop web.

Can I use it for design system work?

Yes. It is well suited to defining accessible defaults for reusable components, especially where semantics, keyboard handling, ARIA state, and focus management need to be consistent across many products.

How to Improve accessibility-compliance skill

Give the skill real artifacts, not summaries

The fastest way to improve accessibility-compliance results is to provide actual JSX, HTML, React Native code, screenshots with annotations, or a step-by-step interaction description. The skill cannot infer focus order, labels, or announcements reliably from vague product summaries.

Ask for issue mapping, not only recommendations

A stronger request is:

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

That pushes the model to produce auditable output. Without that structure, answers tend to drift into generic advice.

Tell it your acceptable level of change

Accessibility fixes often trade off with design system constraints. State whether the agent can:

• change markup only
• add ARIA only where needed
• restructure component hierarchy
• modify copy for clarity
• change interaction patterns if the current design is inaccessible

This changes the quality of the result more than most users expect.

Common failure mode: overusing ARIA

One predictable issue in accessibility work is adding ARIA where native HTML would work better. Improve output by explicitly saying:

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

That instruction aligns with the repository’s ARIA reference and reduces low-quality fixes.

Common failure mode: forgetting state changes

Many first-pass answers catch labels and focus but miss dynamic behavior. Ask specifically for:

• focus entry and return
• expanded/collapsed state announcements
• validation error association
• async status messaging with live regions
• reduced motion and high contrast considerations where relevant

These details materially improve the usefulness of the accessibility-compliance guide.

Iterate after the first answer

After the initial audit, follow with one of these:

• “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.”

This turns the skill from a reviewer into a delivery aid.

Use repository references surgically

Do not read the whole repository first. If your problem is:

• semantic structure or conformance target: start with references/wcag-guidelines.md
• widget behavior or roles: open references/aria-patterns.md
• touch targets or mobile AT: open references/mobile-accessibility.md

That targeted reading path makes accessibility-compliance install and adoption faster.

Improve trust by requesting rationale

Ask the skill to explain why each fix matters for keyboard users, screen reader users, low-vision users, or users with motion sensitivity. This catches shallow fixes and helps teams justify implementation work during reviews.

Best way to get production-ready output

For the highest-value accessibility-compliance usage, request all of the following in one pass:

• prioritized findings
• corrected code
• rationale
• manual verification checklist
• remaining risks or assumptions

That package is what most teams actually need to move from “we should improve accessibility” to “we can implement and verify this now.”