
a11y-specialist-skills
Accessibility skills: reviewing-a11y (WCAG reviews), auditing-wcag (conformance audits with automated scripts), planning-wcag-audit (audit planning), planning-a11y-improvement (maturity + roadmap), implementing-a11y (build with the knowledge base), a11y-knowledge (per-criterion judgment lines and check reading).
- version
- 2.27.0
- GitHub stars
- 61
Install
/plugin install a11y-specialist-skills@a11y-specialist-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add masuP9/a11y-specialist-skills.
Contents
Discovered from sourceSkills 6
Accessibility Knowledge Base
A reference knowledge base that collects, per success criterion, "what the judgment is based on". It does not restate the definitions of WCAG success criteria or the ARIA specification (the agent is assumed to know them). What it does write down is: which parts of the Understanding documents to hold onto, the judgment lines for interpretation, how to build so the judgment lines are met, and what automated checks can and cannot decide.
This skill does not do work on its own. The implementation, review, and audit skills use it to read only the files for the success criteria they need.
How to look things up
- When you know the success criterion number: read
references/criteria/<number>.md(for examplereferences/criteria/1.1.1.md). The list is in references/index-by-criterion.md. - When searching by component type (when writing or reviewing code): use references/index-by-component.md to find, from the component (button, link, image, dialog, and so on), the success criteria that apply to it, then read each file.
- When reading the results of automated checks (axe,
@a11y-skills/audit): use references/checks-axe.md and references/checks-audit.md to confirm which results are settled and which need review, then read "When checking" in each success criterion's file. - Success criteria that compare multiple pages (3.2.3 / 3.2.4 / 3.2.6, and the comparison for 2.4.2): first read the shared judgment rules in references/cross-page.md.
Do not read everything at once. Read only the success criteria being asked about.
When editing references, read Editing and checking judgment evidence. 2.5.8 / 1.1.1 / 4.1.2 / 2.4.3 / 2.4.7 / 2.4.11 / 1.4.11 / 2.4.12 / 2.4.13 / 1.4.4 / 1.4.10 / 1.4.12 / 2.5.1 / 2.5.7 / 2.5.5 / 2.1.4 / 2.5.2 / 2.5.4 / 1.3.3 / 1.3.4 / 1.4.1 / 2.2.1 / 2.2.2 / 1.4.2 / 3.3.1 / 3.3.2 / 3.3.3 / 3.2.3 / 3.2.4 / 3.2.6 / 2.4.1 / 2.4.2 / 2.4.4 / 1.3.1 / 1.3.5 / 3.1.1 / 2.1.1 / 3.2.1 / 3.3.4 / 1.2.2 / 1.4.5 / 1.2.1 / 1.2.3 / 1.2.5 / 2.1.2 / 1.4.13 / 3.2.2 / 2.5.3 / 2.4.6 / 4.1.3 / 3.3.7 / 3.3.8 / 1.3.2 / 3.1.2 / 2.4.5 / 1.2.4 / 1.4.3 / 2.3.1 use the pilot format with evidence IDs. Read each item’s source type, conditions, and limits and follow IDs from judgment lines. Verification covers the documented scope, not all cases or criteria without files.
The four sections of each file
| Section | Who reads it | Contents |
|---|---|---|
| Rationale | All situations | Sources and key points supporting judgments. The pilot format includes evidence IDs, source types, conditions, and limits |
| Judgment lines | All situations | How to read this criterion. What it does not apply to, exceptions, common misjudgments. The existing format uses [Understanding] / [Our interpretation]; the pilot uses evidence IDs and marks operational interpretations |
| When building | Implementation and review | How to build so the judgment lines are met, and what to avoid |
| When checking | Auditing and reviewing automated checks | What automated checks decide, what remains, and what must not be asserted (conditions for leaving it as needs review) |
Rules for use
- Use this as an opinionated knowledge base. [Our interpretation] denotes a deliberately adopted policy, distinct from [Unverified] evidence gaps. Separate source summaries from author judgments and state scope, reasons, and reporting treatment.
- [Our interpretation] judgment lines are not the only way to read WCAG. A project may override them by its own decision. If you override one, record the reason on the project side.
- Preserve the scope of automated findings. Match applicability and exceptions in the criterion file. Do not extend partial passes to criterion-wide conformance; leave unverified conditions as needs review.
- When you cannot decide, leave it as "needs review". Do not mark it non-conformant or conformant by guesswork. Write down what would need to be confirmed to decide.
- Write the reason first, then attach the verdict that fits the reason. Do not write only the verdict and add the reason afterwards.
Rules for what to include
- Include only "what the judgment is based on". Do not copy the text of the success criteria or the full Understanding documents.
- Limit the key points from the Understanding documents to the parts the judgment rests on (definitions of terms, intent, where exceptions come from).
- Distinguish source-backed judgment lines ([Understanding] in the existing format, evidence IDs in the pilot format) from operational interpretations ([Our interpretation]).
- Write down the patterns of misjudgment learned from measurement. Do not write the measurement numbers.
WCAG Conformance Audit
You perform WCAG 2.2 AA conformance audits. Report Pass/Fail/NT/NA per success criterion with evidence.
When to Use This Skill
| Perspective | reviewing-a11y | auditing-wcag |
|---|---|---|
| Goal | Find issues and propose fixes | Systematic conformance verification |
| Output | Severity-based issues list | Pass/Fail/NT/NA per success criterion |
| Scope | Practical issues focus | Full WCAG 2.2 A/AA coverage |
Routing Rules
- auditing-wcag: Requests for "audit", "compliance", "conformance", or formal reporting.
- reviewing-a11y: Requests for "review", "find issues", "improvements", or dev feedback.
- If unclear, ask which goal they want: compliance report or issue review.
Workflow (6 Steps)
1. Input Acceptance
- Accept a URL or local file path.
- For multiple pages, confirm the list and entry points.
- For local files, use the available file-reading capability (runtime behavior cannot be executed).
2. Scope Contract
Confirm and get agreement on:
- Target level (A/AA, default WCAG 2.2 AA)
- Page scope (all pages / representative pages / provided URLs)
- Target environment (production / staging) and whether key presses, value changes and submissions may happen (confirm with the user; this decides the
--checksvalue in "Automated Checks" below) - Limitations (AT checks out of scope, dynamic behavior depends on browser interaction)
- Output format (Pass/Fail/NT/NA per success criterion)
3. Automated Checks
- If a shell is available, run the
a11y-auditCLI first (see "Automated Checks CLI" below). Use--checks allonly when the scope contract confirmed that side effects are acceptable. If that was not confirmed or side effects are not acceptable, list only the "allowlist of checks that do not operate the page" below (includingpage-snapshot). - Sort the results into "settled / needs review" with the knowledge base rules below.
- Use browser interaction to verify candidates that need review and for "4. Interactive Checks".
- If no shell is available, use browser interaction in place of step 1 (navigate and capture the accessibility tree). Record the checks it could not cover under limitations.
- If neither is available, retrieve HTML with the available web capability and limit judgments accordingly.
- Collect the material for each criterion with
references/automated-checks.md. - Use
references/coverage-matrix.mdto ensure A/AA coverage.
Allowlist of checks that do not operate the page: "Side effects" means input operations that can cause submission, saving, authentication requests and the like (key presses, clicks, pointer operations, typing values, pasting, dispatching synthetic events). The checks below perform none of these, so they may run even when side effects are not confirmed acceptable.
--checks axe-audit,page-snapshot,reflow-check,text-spacing-check,zoom-200-check,orientation-check,autocomplete-audit,time-limit-detector,target-size-check,redundant-entry-check,pointer-gesture-check,non-text-contrast-check
- They do change the display (scrolling, resizing the window, injecting CSS):
target-size-checkscrolls;reflow-check,zoom-200-checkandorientation-checkresize the window;text-spacing-checkinjects CSS.zoom-200-checkalso applies CSSzoom: 200%to the page in addition to resizing the window.time-limit-detectorreplacessetTimeout/setIntervalbefore load to record the calls (the page's timers still run normally). On pages that run handlers on scroll or resize, the user may drop these. - Checks not on the allowlist (
focus-indicator-check,keyboard-trap-check,keyboard-reachability-check,content-on-hover-check,auto-play-detection,motion-actuation-check,change-on-input-check,accessible-authentication-check,focus-order-check,pointer-cancellation-check,character-key-shortcut-check) run only when side effects are confirmed acceptable. For criteria whose checks were not run, have a person verify with browser interaction or mark NT (not tested), and state the reason under limitations.
Sort the results with the knowledge base (a11y-knowledge):
- Also run
page-snapshotfrom@a11y-skills/audit0.14.0 or later (include it even when narrowing--checks). It gives no verdict, but it is the material for 2.4.1 / 2.4.2 / 3.1.1 and for comparing multiple pages. - Sort the results into "settled / needs review" by the rules in checks-axe.md and checks-audit.md. Use axe passes as evidence within each rule’s scope, not as criterion-wide conformance (Pass). Check the remaining conditions in each criterion file.
- For criteria that need review, read "Judgment lines" and "When checking" in
../a11y-knowledge/references/criteria/<number>.mdbefore deciding. Anything under "do not assert" stays NT, with a note on what would settle it. - When auditing multiple pages, first read the shared judgment rules in cross-page.md.
- Judgment rules live in the knowledge base; the reference guides hold only the material and the judgments for criteria without a knowledge base file. The knowledge base is referenced by the relative path
../a11y-knowledge/(it resolves when installed as a plugin; when installed by symlinking individual skill directories, linka11y-knowledgeas well).
4. Interactive Checks
- Perform keyboard operation and focus checks.
- Follow
references/interactive-checks.md. - If execution is blocked, mark affected criteria as NT.
5. Manual Check Items
- Present items from
references/manual-checks.mdandreferences/content-checks.md. - If evidence is not available, keep them as NT and list them explicitly.
- Incorporate any evidence the user provides.
6. Report Generation
- Follow
references/output-format.md. - Assign a status to every A/AA success criterion (Pass/Fail/NT/NA).
- Summarize scope, limitations, tools, and unresolved items.
Automation Scope and Limits
- Browser interaction only provides computed accessibility tree signals (role/name/state).
- Automated test results alone do not guarantee audit outcomes.
- Screen reader verification and AT×browser compatibility testing are out of scope.
- Do not guess; use NT when evidence is missing.
Reference Guides
references/automated-checks.mdreferences/interactive-checks.mdreferences/manual-checks.mdreferences/content-checks.mdreferences/output-format.mdreferences/coverage-matrix.md- Knowledge base (
../a11y-knowledge/):references/checks-axe.md,references/checks-audit.md,references/cross-page.md,references/criteria/<number>.md
Automated Checks CLI
Automated checks are run via the a11y-audit CLI included in the npm package @a11y-skills/audit (requires Node 18+; peer dependencies are fetched automatically by npm 7+).
Setup (first time only):
npx playwright install chromium
Run all checks (only when side effects are confirmed acceptable):
npx -y @a11y-skills/audit --url "https://example.com" --checks all --output-dir ./results
Run specific checks (the example uses allowlist checks only):
npx -y @a11y-skills/audit --url "https://example.com" --checks axe-audit,page-snapshot --output-dir ./results
Omitting --checks means all, which also runs the checks with side effects. Always pass --checks <the value decided in the scope contract>. Add checks not on the allowlist, such as focus-indicator-check, only when side effects are confirmed acceptable.
Include page-snapshot (0.14.0 or later) even when narrowing --checks. It is the material for 2.4.1 / 2.4.2 / 3.1.1 and for comparing multiple pages.
With annotated screenshots (focus-indicator; not on the allowlist, so only when side effects are acceptable):
npx -y @a11y-skills/audit --url "https://example.com" --checks focus-indicator-check --screenshot --output-dir ./results
Custom output directory (default: ./a11y-audit-results):
npx -y @a11y-skills/audit --url "https://example.com" --checks axe-audit,page-snapshot --output-dir ./results
Exit codes: 0 = no violations / 1 = violations found / 2 = runtime error
| Check name | Criterion | Description |
|---|---|---|
axe-audit | Multiple | axe-core comprehensive check |
reflow-check | 1.4.10 | Horizontal scroll at 320px |
text-spacing-check | 1.4.12 | Text spacing override clipping |
zoom-200-check | 1.4.4 | Clipping and other candidates at CSS zoom 200%; verify in the actual browser |
orientation-check | 1.3.4 | Orientation lock detection |
autocomplete-audit | 1.3.5 | Missing/invalid autocomplete |
time-limit-detector | 2.2.1 | Timer/meta refresh detection |
auto-play-detection | 1.4.2, 2.2.2 | Auto-play content detection (visual changes and the playback state of <audio> / <video>; whether sound is actually heard needs manual review) |
focus-indicator-check | 2.4.7 | Focus indicator visibility |
target-size-check | 2.5.5, 2.5.8 | Target size measurement |
keyboard-trap-check | 2.1.2 | Keyboard trap detection |
keyboard-reachability-check | 2.1.1 | Keyboard reachability (Tab, arrow keys, activedescendant) |
redundant-entry-check | 3.3.7 | Overlapping fields asking for the same information (candidates; needs review) |
motion-actuation-check | 2.5.4 | Listeners reacting to device motion / orientation (candidates; needs review) |
change-on-input-check | 3.2.2 | Navigation, new windows, focus moves or dialogs caused by just changing a form control (candidates; needs review) |
accessible-authentication-check | 3.3.8 | Paste blocking and autocomplete="off" on password / code fields, CAPTCHA-like elements (candidates; needs review) |
pointer-gesture-check | 2.5.1, 2.5.7 | Components likely operated by dragging, swiping or multiple fingers (candidates; needs review) |
focus-order-check | 2.4.3 | Tab order vs. visual order (moving back up, backwards on a row, detours) and focus on opening / closing modal dialogs (candidates; needs review) |
pointer-cancellation-check | 2.5.2 | Components that act on the down-event alone (navigation, new window, dialog, DOM change) and elements with only press listeners (candidates; needs review) |
non-text-contrast-check | 1.4.11 | Contrast of input, checkbox, radio and switch borders or fills against the surrounding color, and of icons in icon-only buttons (below 3:1 or not measurable; needs review) |
character-key-shortcut-check | 2.1.4 | Keys that cause a navigation, new window, dialog, focus move, DOM change, scroll or preventDefault() when pressed one at a time with focus on the page body (candidates; needs review) |
content-on-hover-check | 1.4.13 | Content shown on hover or focus (found from CSS :hover / :focus rules and listeners) that Escape does not dismiss, that disappears when the pointer moves onto it, or that disappears on its own (candidates; needs review). Delegated listeners are reported only |
page-snapshot | Material for 2.4.1 / 2.4.2 / 3.1.1 / 3.2.3 / 3.2.4 / 3.2.6 | No verdict. Writes the body's aria snapshot, the title, the lang of <html>, the URLs and an aria snapshot per iframe (read it to judge; for several pages, use a separate --output-dir per page and compare) |
See the @a11y-skills/audit README for detailed documentation.
Accessible Implementation
Look up the success criteria that apply to the UI component you are about to write in a11y-knowledge, read "Judgment lines" and "When building", then implement. This skill holds only the procedure, not the knowledge.
- You want issues reported on what you wrote →
reviewing-a11y - You want a formal audit with Pass/Fail per success criterion →
auditing-wcag
The knowledge base is referenced by the relative path
../a11y-knowledge/. It resolves when installed as a plugin. When installed by symlinking individual skill directories, linka11y-knowledgeas well.
Procedure
1. List the components to write by role
Break the UI you are about to implement into ARIA roles (for example dialog, with button and textbox inside). List by role, not by visual name (modal, toggle).
2. Look up the success criteria for each component
Use index-by-component.md to find the success criteria that apply to each role you listed.
Whole-page and multi-page success criteria (2.4.1, 2.4.2, 3.1.1, 1.4.1, 1.3.3, 3.2.3, 3.2.4, 3.2.6) are not attached to components. When writing layouts, templates, or page scaffolding, use index-by-criterion.md and pick the criteria whose nature is "whole page" or "multiple pages".
3. Read "Judgment lines" and "When building" for each criterion
For each criterion found, open ../a11y-knowledge/references/criteria/<number>.md and read only the two sections "Judgment lines" and "When building" ("Rationale" and "When checking" are not needed for implementation). Do not read everything at once.
- [Understanding] judgment lines are based on the Understanding documents. Follow them.
- [Our interpretation] judgment lines are operational interpretations. The project's own decisions (design guidelines, how existing components are built) may override them. If you override one, record the reason in a code comment or the PR description.
4. Build
- If a standard HTML element does the job, use it (
<button>,<a href>,<input>,<dialog>,<details>). Add roles with ARIA only when a standard element cannot express it. - For custom components, follow the WAI-ARIA APG patterns (keyboard interaction, roles, states).
- While writing, check that you are not falling into the "what to avoid" items under "When building".
5. Self-check and leave the visual checks on record
Re-read what you wrote against the "When building" sections you read. Then open "When checking" for each criterion and, for anything listed under "what not to assert" (things that can only be decided by looking or operating), leave a note in a code comment or the PR description as "needs visual verification". Do not write "handled" for anything you have not verified yourself.
Output
Alongside the implementation, add the following.
### Success criteria considered for accessibility
- dialog: 2.1.2 (focus containment), 2.4.3 (focus on open/close). Provide a name as best practice under the [knowledge base’s author policy](../a11y-knowledge/references/criteria/4.1.2.md). Controls inside must also meet 4.1.2.
- button: 2.5.8, 4.1.2
### Needs visual verification
- [ ] Focus returns to the opening button after closing (2.4.3)
- [ ] The focus ring is visible against the background (2.4.7)
### [Our interpretation] judgment lines overridden
- (if any: what and why)
Planning Accessibility Improvement
You are an accessibility improvement planning consultant. Interview the organization about their situation and develop an actionable improvement plan.
Workflow Overview
┌─────────────────────┐
│ 1. Identify Scenario│
│ Determine purpose │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ 2. Gather Info │
│ Required→Context→ │
│ Optional │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ 3. Maturity Assess │
│ Determine level │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ 4. Generate Draft │
│ Roadmap, KPIs, etc. │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ 5. Review & Adjust │
│ Refine strategy │
│ with user feedback │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ 6. Export File │
│ Save final MD file │
└─────────────────────┘
Step 1: Identify Scenario
First, identify the user's purpose. Classify into one of the three scenarios:
New Introduction Phase
Indicators:
- "We're just starting with accessibility"
- "Where should we begin?"
- Little to no prior initiatives
Characteristics: Prioritize baseline establishment, foundational training, seeding design system
Acceleration Phase
Indicators:
- "We want to systematize existing efforts"
- "We want to be more efficient"
- Have some track record
Characteristics: Prioritize governance strengthening, QA gates, toolchain automation
External Audit Response Phase
Indicators:
- "We have an audit coming" "There's litigation risk"
- "We need to comply by [date]"
- Urgent response to regulations or external requirements
Characteristics: Prioritize rapid triage, legal alignment, communication plan
Ambiguous Cases
Ask the user:
I'll help develop an accessibility improvement strategy. Which situation is closest to yours?
1. **New Introduction** - Just starting to work on accessibility
2. **Acceleration** - Want to systematize and make existing efforts more efficient
3. **External Audit Response** - Need urgent response to regulations or audits
Step 2: Gather Information
Once the scenario is identified, collect information in the following order. Ask short, efficient questions using the available interaction mechanism.
Stage 0: Reference Documents (Check first)
If documentation about prior initiatives exists, reading it first enables more accurate planning.
Example documents to read:
- Accessibility test results / conformance reports
- History of prior initiatives / retrospective documents
- Existing a11y guidelines / policies
- Tech stack or organizational structure descriptions
Example question:
Do you have any reference documents for planning?
(e.g., test results, initiative history, guidelines, etc.)
Please provide the file path and I'll review the contents.
For multiple files, separate paths with commas.
If none, reply "none".
If file paths are provided, use the available file-reading capability and apply the content to the maturity assessment and roadmap.
Stage 1: Required Items (Always confirm first)
These items are essential for strategy development. Combine multiple questions efficiently:
| Category | Question Item | What to Confirm |
|---|---|---|
| Business | Target users | B2B/B2C, who are decision makers |
| Business | Target market | US, Europe, Asia, Global, specific regions only |
| Technical | Design system | Existence, coverage |
| Technical | Legacy code | Approximate amount (high/medium/low) |
| Technical | UI quality | Current quality level (good/average/needs improvement) |
| Organization | Team structure | Team composition, dedicated personnel |
| Organization | Prior initiatives | Track record, content |
Example questions:
Let me ask a few questions for strategy development:
1. **Target users and market**
- Is this B2B or B2C? For B2B, who are the decision makers?
- What is your target market? (US, Europe, Asia, Global, etc.)
2. **Technical situation**
- Do you have a design system? If so, what's its coverage?
- How much legacy code do you have? (high/medium/low)
- How would you rate your current UI quality?
3. **Organizational situation**
- Please describe your team structure (design, frontend, QA, etc.)
- Please share any prior accessibility improvement initiatives
Stage 2: Context-Dependent Items (Confirm based on scenario)
Additional items to confirm based on scenario:
| Scenario | Additional Items |
|---|---|
| New Introduction | Budget expectations, executive understanding, reference cases |
| Acceleration | Current bottlenecks, tooling environment, CI/CD status |
| External Audit Response | Deadline, target scope, legal/compliance structure |
Stage 3: Optional Items (If user has additional information)
Not required but improves strategy accuracy:
- Competitor situation
- Procurement requirements (public sector, etc.)
- Vendor involvement status
- Past audit results or user feedback
Step 3: Maturity Assessment
Based on collected information, assess the organization's accessibility maturity.
Maturity Levels
Based on the W3C Accessibility Maturity Model ICT Development Lifecycle dimension, supplemented with Microsoft AEM and Level Access DAMM.
| Level | Name | Characteristics |
|---|---|---|
| L0 | Inactive | No initiatives. Baseline for assessment |
| L1 | Ad hoc | Sporadic efforts driven by individual goodwill or interest. No organizational support or structure |
| L2 | Launch | Organization recognizes the need for accessibility and has started. Efforts are underway but inconsistent. New development only |
| L3 | Integrate | Organizational approach defined and deployed. Processes embedded across the development lifecycle. Remediation of existing products begins |
| L4 | Optimize | Standardized approach permeates the entire organization. A11y tests integrated into CI/CD. Continuous evaluation and improvement cycle operational |
Assessment Axes
Evaluate on these 8 axes (W3C ICT Development Lifecycle 7 sub-dimensions + Governance):
- User Research: Including people with disabilities in research, participant accommodations, accessible research materials
- Planning and Design: Integrating a11y standards into design phase, checklists, design reviews, design system
- Development: Developer resources, coding standards, issue management, acceptance criteria
- User Experience: UX testing with people with disabilities, accessible test materials
- Quality Review Through Release: Manual/automated testing, bug tracking, release gates, ACR creation
- ICT Development Training: Role-specific a11y training
- Goals and Metrics: Goal setting, metric definition, progress tracking
- Governance: Executive sponsor, policy, budget, accountability
Proof Points: See references/maturity-proof-points.md for detailed proof points per axis and level.
Output Format
## Maturity Assessment
**Current Level**: L2 Launch
### Assessment Rationale
| Axis | Rating | Rationale |
|------|--------|-----------|
| User Research | L1 | No process for including people with disabilities |
| Planning and Design | L2 | Some components have a11y guidance, design checklists started |
| Development | L2 | Code review includes a11y but ad-hoc |
| User Experience | L1 | No AT testing in UX process |
| Quality Review Through Release | L1 | Manual checks only, no automated tests |
| ICT Development Training | L1 | No systematic education program |
| Goals and Metrics | L1 | No formal a11y goals or metrics |
| Governance | L1 | Point of contact exists but no policy defined |
### Strengths
- Design system foundation exists
- Some engineers have a11y knowledge
### Gap Summary
- No lifecycle-wide quality gates established
- Cross-organizational ownership unclear
- Measurement mechanisms not established
- No formal user research with people with disabilities
### Target Level
**12-month target**: L3 Integrate
Step 4: Strategy Draft Generation
Based on maturity assessment, generate draft deliverables.
Important: See references/output-templates.md for detailed output templates.
4.1 Roadmap
Create a phased improvement plan:
| Phase | Duration | Focus |
|---|---|---|
| Immediate | 0-1 months | Quick wins, urgent fixes |
| Near-term | 2-3 months | Foundation building, process setup |
| Mid-term | 4-6 months | Automation, scaling |
| Long-term | 7-12 months | Culture building, continuous improvement |
Scope Recommendation: For organizations in New Introduction phase with limited resources or large/legacy codebases, strongly recommend limiting the initial scope:
- Pilot scope selection criteria:
- High-traffic features used by many users
- Critical features like login, checkout
- Prioritize new development over legacy code (easier to improve, easier to create success stories)
- Rationale: Showing results each quarter is critical for sustaining initiatives. Smaller scope enables hitting milestones on schedule rather than extending timelines.
- Pattern: "Succeed with one first" → "Scale horizontally" is more sustainable than attempting organization-wide change from day one.
When recommending scope limitation, explain to the user:
Given your situation (new to accessibility + [limited resources / large codebase / legacy code]),
I recommend starting with a limited scope:
Recommended pilot scope: [specific recommendation based on their context]
- Start with high-traffic features used by many users, or critical features like login
- Prioritizing new development over legacy makes it easier to show results
Benefits of this approach:
- Show concrete results each quarter (important for continued investment)
- Build internal expertise before scaling
- Create a success story that makes horizontal expansion easier
Once the pilot succeeds, you can expand scope in subsequent cycles.
4.2 KPI/Metrics Design
Leading Indicators:
- Percentage of components with a11y specs defined
- Review coverage
- Training completion rate
Lagging Indicators:
- Audit finding counts (by severity)
- Rework rate
- A11y-related support tickets
4.3 Stakeholder Persuasion Materials
Organize around business impact:
- Risk: Regulatory violations, litigation risk, market access restrictions
- Opportunity: Market expansion, brand value, user satisfaction improvement
- Cost: Future cost of not addressing vs. cost of addressing now
Scenario-Specific Guidance
See references/scenario-playbooks.md for detailed guidance for each scenario.
Output Format
Final output follows "5. Complete Strategy Report Structure" in references/output-templates.md.
Key sections:
- Executive Summary
- Current Assessment (Maturity Assessment, Key Challenges)
- Strategic Roadmap (4 Phases)
- KPIs/Metrics (Leading, Lagging)
- Stakeholder Talking Points
- Next Steps
Step 5: Review and Adjustment
After presenting the strategy draft, engage with the user to refine the strategy.
5.1 Collect Feedback
After presenting the draft, ask for feedback on these points:
Please review the strategy draft. I'd like your feedback on:
1. **Are any initiatives already done or in progress?**
- We'll remove or adjust them in the roadmap
2. **Are any initiatives difficult to implement?**
- Resource, budget, or organizational constraints?
- We'll consider alternatives
3. **Would you like to change priorities?**
- Reorder phases or adjust timelines
4. **Would you like to add any initiatives?**
- Organization-specific efforts or requirements
5. **Any other concerns?**
5.2 Adjustment Patterns
| Feedback | Response |
|---|---|
| "We already do this" | Remove from roadmap or mark as "ongoing" |
| "This is difficult" | Understand why, propose alternatives or defer to later phase |
| "We want this first" | Move to earlier phase, verify dependencies |
| "Add X" | Add to appropriate phase, consider KPIs |
| "Timeline too short/long" | Adjust based on organizational capacity |
5.3 Iteration
Continue feedback cycles as needed. Keep adjusting until user confirms the strategy is acceptable.
Step 6: File Export
Once strategy is finalized, export as a Markdown file.
6.1 Confirm Output Path
Ask user for output location:
I'll save the strategy as a Markdown file.
Please specify the path (e.g., ./docs/a11y-strategy.md)
Default suggestion: ./a11y-strategy-YYYY-MM-DD.md
6.2 Write File
When workspace writing is available, save the final strategy as a Markdown file.
Include at the end of the file:
---
*This strategy was created on [date].*
*Review periodically (quarterly recommended) and update based on progress.*
6.3 Suggest Next Actions
After export, suggest:
- How to share the strategy with stakeholders
- When to start the first action items
- Setting up regular review schedule
Notes
- Be specific: Not abstract recommendations but concrete actions
- Be realistic: Create executable plans considering organizational resources and constraints
- Be flexible: Adjust timelines and priorities based on user's situation
- Business perspective: Always tie explanations to business impact
- Be interactive: After draft generation, dialogue with user to refine the strategy
Planning a WCAG Audit
You are a WCAG audit planner. Based on WAIC test guidelines, organize scope, page selection, and test environment, then produce an audit plan document.
Workflow Overview
- Site information gathering
- Test method selection
- Page selection
- Test environment confirmation
- Audit plan document generation
Step 1: Site Information Gathering
Capture the audit target at a high level. Ask short, direct questions.
Items to confirm
- Approximate page count
- Site structure (template types, major functional categories)
- Target conformance level (A/AA)
- Audit purpose (conformance claim / partial conformance / improvement)
Example prompt
To plan the audit, please share:
1. Approximate number of pages
2. Site structure and main page types
3. Target conformance level (A/AA)
4. Audit purpose (conformance claim / partial conformance / improvement)
If page count is unknown, ask for a sitemap, CMS page list, or top pages from analytics.
Step 2: Test Method Selection
Select from the WAIC-based methods below.
- All pages
- Random selection
- Representative pages
- Combination method
See references/page-selection-guide.md for details.
Step 3: Page Selection
Follow references/page-selection-guide.md to select target pages.
When target pages are not yet determined
If the user does not have a URL list, follow Steps 1-6 in the guide for URL collection and sampling:
- Collect URLs via sitemap.xml or browser-based link collection
- Apply exclusion patterns (user-specified)
- Identify representative pages
- Random sampling (excluding representative pages to avoid duplicates)
- Deduplication and merge
- Final confirmation
Note: Collect URLs with available browser interaction, sitemap.xml, or CMS exports. If browsing is unavailable, ask the user for a URL list.
Sample Size Guidelines (Baseline: ~40 pages, majority representative)
| Site size (after exclusions) | Target pages |
|---|---|
| ~40 pages | All pages |
| 40+ pages | ~40 pages (20-25 representative + 15-20 random) |
| 200+ pages | 40-55 pages (25-30 representative + 15-25 random) |
Step 4: Test Environment Confirmation
Clarify the environment for reproducibility.
Items to confirm
- Browsers (target coverage)
- Assistive technologies (intended usage environment / accessibility-supported context)
- Devices (desktop / mobile)
- Tools used (automated checks, contrast tools, etc.)
Note: Direct operation testing with assistive technologies (screen readers, etc.) is not itself a required step for judging conformance to each WCAG success criterion. Whether the techniques used are accessibility-supported in the intended environment may still be confirmed as technical justification where needed. Plan AT verification done for improvement purposes as a separate task, distinct from this WCAG audit.
Example prompt
Please confirm the test environment:
- Browsers (e.g., Chrome/Firefox/Safari/Edge)
- Device scope (desktop / iOS / Android)
- Tools (optional)
Step 5: Audit Plan Document Generation
Create the plan using references/audit-plan-template.md and save it as Markdown when workspace writing is available.
Output requirements
- Include overview, test method, target page list
- Capture test environment, tools, schedule, and roles
- Present the page list in a table
Confirm output path
I will save the audit plan as Markdown.
Please provide the output path (e.g., ./docs/wcag-audit-plan.md)
Notes
- Mark unknowns as "TBD" and request follow-up input
- Prioritize key user flows when selecting representative pages
- Record a reproducible random sampling method (seed, steps)
- Once the plan is ready, pass the target page list (one URL per line) to auditing-wcag to run the audit
Accessibility Review
Identify the review target, find accessibility issues by following the matching reference guide, and report them by severity.
Step 1: Identify Review Target
| Target | Indicators | Guide |
|---|---|---|
| Web page | A http:// / https:// URL, a deployed page | references/page-review.md |
| Code | File paths or directories (.tsx, .vue, .html, etc.), component names | references/code-review.md |
| Design | A Figma URL (figma.com/design/, /file/, /proto/, /board/), design images or PDFs, specifications | references/design-review.md |
If you cannot decide, ask in one line whether to review a URL, file paths, or a design.
Step 2: Look Up the Judgment Lines in the Knowledge Base
Once you identify the target, and before looking at the code or page, align your findings with a11y-knowledge.
- List the components that appear in the target by ARIA role (button, dialog, combobox, and so on).
- Use index-by-component.md to find the success criteria that apply to each role. When reviewing a layout or a whole page, also pick the "Whole page" and "Multiple pages" criteria from index-by-criterion.md.
- For each criterion found, read "Judgment lines" and "When building" in
../a11y-knowledge/references/criteria/<number>.mdbefore writing a finding. Do not report items excluded from WCAG applicability as WCAG failures. Report items the knowledge base treats as best practice as improvement candidates without assigning a success criterion, such as a missing name on the dialog itself. - When a finding is based on an [Our interpretation] judgment line (an operational interpretation), say so in the finding (for example, "[Our interpretation] judgment line; the project may override it"). [Understanding] judgment lines need no such note.
The knowledge base is referenced by the relative path ../a11y-knowledge/. It resolves when installed as a plugin. When installed by symlinking individual skill directories, link a11y-knowledge as well. If it does not resolve, skip this step and write "knowledge base not consulted" in the report.
Step 3: Load the Guide and Review
Read the guide from the Step 1 table in the user's language (.ja.md for Japanese, .md for English) and execute its process in this agent. Use one guide per target type; do not mix them.
Use sub-agents only when the user explicitly requests parallel review, delegation, or division across multiple targets. Give each agent one target type with its guide and target, wait for every result, remove duplicates, and return one report. If sub-agents are unavailable, review the targets sequentially.
Severity
All guides assign severity with this table. Severity reflects the impact on users and is independent of the WCAG level (A/AA).
| Severity | Definition | Example patterns |
|---|---|---|
| Critical | Users cannot operate or get the information at all | Informative image without an alternative, icon-only button without a name, input without an associated label, click-only or unfocusable controls, keyboard trap, aria-labelledby pointing to a non-existent ID, important information hidden with display:none or aria-hidden="true", errors shown by color alone |
| Major | Possible but with significant difficulty | Missing or broken heading structure, missing or duplicate landmarks, wrong role or invalid aria-* values, focus order far from visual order, links or buttons that only say "click here" or "details", tables missing th / scope, missing page language (3.1.1), insufficient contrast |
| Minor | Possible with room for improvement | ARIA-built part that could be a native element (name, role, and keyboard operation already met), redundant ARIA duplicating native semantics, no skip link (when headings or landmarks let users bypass blocks), minor heading level inconsistencies, best practices that are not WCAG requirements |
Mark findings that are not WCAG requirements as "best practice" and do not attach a success criterion.
Step 4: Return Results
- Present the findings in the guide's output format. Separate what was verified from what could not be verified (sent to manual verification). Do not turn missing evidence into a conclusive finding.
- If useful, offer to review another target type (e.g., "Would you like me to review the code implementation next?").
Sponsors
Details
- Marketplace
- masuP9/a11y-specialist-skills
- Author
- masuP9
- Category
- Productivity
- License
- MIT
- Keywords
- accessibility, a11y, wcag, aria, review, planning, maturity, audit, compliance, roadmap, conformance