masuP9 avatar

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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add masuP9/a11y-specialist-skills.

Contents

Discovered from source

Skills 6

日本語版 (Japanese)

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

  1. When you know the success criterion number: read references/criteria/<number>.md (for example references/criteria/1.1.1.md). The list is in references/index-by-criterion.md.
  2. 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.
  3. 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.
  4. 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

SectionWho reads itContents
RationaleAll situationsSources and key points supporting judgments. The pilot format includes evidence IDs, source types, conditions, and limits
Judgment linesAll situationsHow 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 buildingImplementation and reviewHow to build so the judgment lines are met, and what to avoid
When checkingAuditing and reviewing automated checksWhat 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.

日本語版 (Japanese)

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

Perspectivereviewing-a11yauditing-wcag
GoalFind issues and propose fixesSystematic conformance verification
OutputSeverity-based issues listPass/Fail/NT/NA per success criterion
ScopePractical issues focusFull 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 --checks value 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

  1. If a shell is available, run the a11y-audit CLI first (see "Automated Checks CLI" below). Use --checks all only 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 (including page-snapshot).
  2. Sort the results into "settled / needs review" with the knowledge base rules below.
  3. Use browser interaction to verify candidates that need review and for "4. Interactive Checks".
  4. 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.
  5. 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.md to 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-check scrolls; reflow-check, zoom-200-check and orientation-check resize the window; text-spacing-check injects CSS. zoom-200-check also applies CSS zoom: 200% to the page in addition to resizing the window. time-limit-detector replaces setTimeout / setInterval before 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-snapshot from @a11y-skills/audit 0.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>.md before 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, link a11y-knowledge as 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.md and references/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.md
  • references/interactive-checks.md
  • references/manual-checks.md
  • references/content-checks.md
  • references/output-format.md
  • references/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 nameCriterionDescription
axe-auditMultipleaxe-core comprehensive check
reflow-check1.4.10Horizontal scroll at 320px
text-spacing-check1.4.12Text spacing override clipping
zoom-200-check1.4.4Clipping and other candidates at CSS zoom 200%; verify in the actual browser
orientation-check1.3.4Orientation lock detection
autocomplete-audit1.3.5Missing/invalid autocomplete
time-limit-detector2.2.1Timer/meta refresh detection
auto-play-detection1.4.2, 2.2.2Auto-play content detection (visual changes and the playback state of <audio> / <video>; whether sound is actually heard needs manual review)
focus-indicator-check2.4.7Focus indicator visibility
target-size-check2.5.5, 2.5.8Target size measurement
keyboard-trap-check2.1.2Keyboard trap detection
keyboard-reachability-check2.1.1Keyboard reachability (Tab, arrow keys, activedescendant)
redundant-entry-check3.3.7Overlapping fields asking for the same information (candidates; needs review)
motion-actuation-check2.5.4Listeners reacting to device motion / orientation (candidates; needs review)
change-on-input-check3.2.2Navigation, new windows, focus moves or dialogs caused by just changing a form control (candidates; needs review)
accessible-authentication-check3.3.8Paste blocking and autocomplete="off" on password / code fields, CAPTCHA-like elements (candidates; needs review)
pointer-gesture-check2.5.1, 2.5.7Components likely operated by dragging, swiping or multiple fingers (candidates; needs review)
focus-order-check2.4.3Tab order vs. visual order (moving back up, backwards on a row, detours) and focus on opening / closing modal dialogs (candidates; needs review)
pointer-cancellation-check2.5.2Components 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-check1.4.11Contrast 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-check2.1.4Keys 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-check1.4.13Content 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-snapshotMaterial for 2.4.1 / 2.4.2 / 3.1.1 / 3.2.3 / 3.2.4 / 3.2.6No 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.

日本語版 (Japanese)

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, link a11y-knowledge as 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)

日本語版 (Japanese)

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:

CategoryQuestion ItemWhat to Confirm
BusinessTarget usersB2B/B2C, who are decision makers
BusinessTarget marketUS, Europe, Asia, Global, specific regions only
TechnicalDesign systemExistence, coverage
TechnicalLegacy codeApproximate amount (high/medium/low)
TechnicalUI qualityCurrent quality level (good/average/needs improvement)
OrganizationTeam structureTeam composition, dedicated personnel
OrganizationPrior initiativesTrack 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:

ScenarioAdditional Items
New IntroductionBudget expectations, executive understanding, reference cases
AccelerationCurrent bottlenecks, tooling environment, CI/CD status
External Audit ResponseDeadline, 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.

LevelNameCharacteristics
L0InactiveNo initiatives. Baseline for assessment
L1Ad hocSporadic efforts driven by individual goodwill or interest. No organizational support or structure
L2LaunchOrganization recognizes the need for accessibility and has started. Efforts are underway but inconsistent. New development only
L3IntegrateOrganizational approach defined and deployed. Processes embedded across the development lifecycle. Remediation of existing products begins
L4OptimizeStandardized 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):

  1. User Research: Including people with disabilities in research, participant accommodations, accessible research materials
  2. Planning and Design: Integrating a11y standards into design phase, checklists, design reviews, design system
  3. Development: Developer resources, coding standards, issue management, acceptance criteria
  4. User Experience: UX testing with people with disabilities, accessible test materials
  5. Quality Review Through Release: Manual/automated testing, bug tracking, release gates, ACR creation
  6. ICT Development Training: Role-specific a11y training
  7. Goals and Metrics: Goal setting, metric definition, progress tracking
  8. 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:

PhaseDurationFocus
Immediate0-1 monthsQuick wins, urgent fixes
Near-term2-3 monthsFoundation building, process setup
Mid-term4-6 monthsAutomation, scaling
Long-term7-12 monthsCulture 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:

  1. Executive Summary
  2. Current Assessment (Maturity Assessment, Key Challenges)
  3. Strategic Roadmap (4 Phases)
  4. KPIs/Metrics (Leading, Lagging)
  5. Stakeholder Talking Points
  6. 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

FeedbackResponse
"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

日本語版 (Japanese)

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

  1. Site information gathering
  2. Test method selection
  3. Page selection
  4. Test environment confirmation
  5. 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:

  1. Collect URLs via sitemap.xml or browser-based link collection
  2. Apply exclusion patterns (user-specified)
  3. Identify representative pages
  4. Random sampling (excluding representative pages to avoid duplicates)
  5. Deduplication and merge
  6. 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 pagesAll pages
40+ pages~40 pages (20-25 representative + 15-20 random)
200+ pages40-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

日本語版 (Japanese)

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

TargetIndicatorsGuide
Web pageA http:// / https:// URL, a deployed pagereferences/page-review.md
CodeFile paths or directories (.tsx, .vue, .html, etc.), component namesreferences/code-review.md
DesignA Figma URL (figma.com/design/, /file/, /proto/, /board/), design images or PDFs, specificationsreferences/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.

  1. List the components that appear in the target by ARIA role (button, dialog, combobox, and so on).
  2. 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.
  3. For each criterion found, read "Judgment lines" and "When building" in ../a11y-knowledge/references/criteria/<number>.md before 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.
  4. 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).

SeverityDefinitionExample patterns
CriticalUsers cannot operate or get the information at allInformative 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
MajorPossible but with significant difficultyMissing 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
MinorPossible with room for improvementARIA-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

  1. 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.
  2. 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