Interpreting Results

Accessibility analysis tools return comprehensive data about issues found on your site. This guide helps you understand the results and turn them into actionable tasks.

Key Fields in Issues

Every issue returned by the tools includes structured fields:

{
  "ruleId": "image-alt",
  "severity": "serious",
  "wcag": {
    "criterion": "1.1.1",
    "level": "A",
    "principle": "perceivable"
  },
  "priority": "critical",
  "remediationEffort": "low",
  "affectedUsers": ["screen-reader", "low-vision"],
  "humanContext": "**Non-text content (WCAG 1.1.1 - Level A)**\n\nAll non-text content must have a text alternative...",
  "suggestedActions": [
    "Add descriptive alt attribute to images",
    "Use aria-label for decorative icons with function"
  ]
}

Field Descriptions

ruleId

Unique identifier for the accessibility rule

axe-core: image-alt, color-contrast, aria-valid-attr
Pa11y: WCAG2AA.Principle1.Guideline1_1.1_1_1.H37
Lighthouse: image-alt, color-contrast, button-name

Use this to:

Group similar issues across the site
Exclude specific rules if needed
Look up detailed rule documentation

severity

Issue severity from the tool’s perspective

critical: Blocks users entirely from functionality
serious: Significantly hinders users, major barriers
moderate: Some difficulty, workarounds exist
minor: Annoyance but doesn’t prevent access

Note: Severity is tool-specific. Use priority for business decisions.

wcag

WCAG success criterion mapping

criterion: Specific WCAG guideline (1.1.1, 2.4.4, etc.)
level: Conformance level (A, AA, AAA)
principle: One of 4 WCAG principles

Use this to:

Understand which WCAG requirement is violated
Group issues by principle or level
Link to official WCAG documentation

priority

Business-oriented priority (enriched by AccessibilityHub)Based on user impact and WCAG level:

critical: Blocks essential tasks, Level A violations
high: Significant barriers, Level AA violations
medium: Moderate impact, some workarounds
low: Minor issues, Level AAA or edge cases

Use this for sprint planning and deployment decisions.

remediationEffort

Estimated time to fix (enriched by AccessibilityHub)

low: < 30 minutes per issue
medium: 1-4 hours per issue
high: Days or sprints

Based on typical fixes for this issue type. Actual time may vary by codebase.

affectedUsers

User groups impacted (enriched by AccessibilityHub)

screen-reader: JAWS, NVDA, VoiceOver users
keyboard-only: Users who can’t use a mouse
low-vision: Screen magnifier users
color-blind: Color vision deficiencies
cognitive: Learning/memory disabilities
motor-impaired: Limited dexterity

Use this to prioritize based on your user base.

humanContext

Human-readable explanation (enriched by AccessibilityHub)Includes:

WCAG criterion name and explanation
Real-world impact example
Why it matters for accessibility

Use this for understanding and team education.

suggestedActions

Actionable fix steps (enriched by AccessibilityHub)Concrete steps with code examples:

What to change
How to change it
Code snippets when applicable

Use this for implementation guidance.

How to Prioritize

Prioritization Matrix

The most effective way to prioritize is by combining priority and effort:

Priority	Low Effort	Medium Effort	High Effort
Critical	🔥 Fix TODAY Drop everything	📅 This Sprint High priority	📅 Plan Sprint Needs estimation
High	✅ Quick Wins Do soon	📅 This Sprint Medium priority	📅 Next Sprint Needs planning
Medium	📝 Easy Fix When available	📝 Backlog Plan eventually	📝 Backlog Evaluate vs impact
Low	📝 Nice to Have Low priority	📝 Backlog Consider deferring	❌ Defer Not worth effort

Triage Example

Prompt:

From the previous analysis, show me:
Critical issues with low effort (fix today)
High issues with low effort (fix this week)
The rest grouped by WCAG principle

Result:

## 🔥 Fix TODAY (Critical + Low Effort)

1. Missing form labels (WCAG 1.3.1)
   - 8 instances
   - Effort: 15 min total
   - Users: screen-reader, keyboard-only
   
2. Images without alt text (WCAG 1.1.1)
   - 5 instances
   - Effort: 10 min total
   - Users: screen-reader

## ✅ Quick Wins (High + Low Effort)

3. Color contrast on buttons (WCAG 1.4.3)
   - 3 instances
   - Effort: 20 min
   - Fix: Change button color from #999 to #666

Tips for Prioritization

Use the matrix

Always prioritize by combining priority and effort:

Critical + Low effort = Fix TODAY
Critical + Medium/High effort = Plan for sprint
High + Low effort = Quick wins
Medium/Low + High effort = Evaluate carefully

Validate duplicates

If deduplicatedCount > issueCount in analyze-mixed results:

Check individualResults to see which tool found it
Higher confidence if multiple tools report the same issue
Lower confidence if only one tool reports it (possible false positive)

Review affected users

Prioritize issues that affect:

screen-reader and keyboard-only users (most common AT users)
User groups that represent your actual user base
Critical user journeys (checkout, signup, login)

Leverage humanContext

Read the real-world examples to understand:

Actual impact on users
Whether it’s a blocker or annoyance
Whether workarounds exist

Consider WCAG level

Legal and compliance perspective:

Level A: Must fix (legal requirement in most jurisdictions)
Level AA: Should fix (standard for compliance)
Level AAA: Nice to have (enhanced accessibility)

Advanced Tips

1. SPA Analysis with Lazy Loading

For single-page applications with dynamic content:

{
  "url": "https://spa-app.com",
  "options": {
    "browser": {
      "waitForSelector": "[data-loaded='true']",
      "waitForTimeout": 5000
    }
  }
}

Use waitForSelector when you know the app sets a specific attribute/element when loaded.

2. Mobile Viewport Analysis

Test responsive layouts:

{
  "url": "https://responsive-site.com",
  "options": {
    "browser": {
      "viewport": {
        "width": 375,
        "height": 667,
        "isMobile": true,
        "hasTouch": true
      }
    }
  }
}

Common mobile viewports:

iPhone SE: 375x667
iPhone 12/13: 390x844
iPad: 768x1024
Android: 360x640

3. Exclude Specific Rules

Useful for known false positives:

{
  "url": "https://example.com",
  "options": {
    "excludeRules": ["color-contrast", "duplicate-id"]
  }
}

Only exclude rules after confirming they’re false positives. Document why you’re excluding them.

4. Contrast Analysis with AAA Level

For maximum accessibility:

{
  "url": "https://example.com",
  "options": {
    "wcagLevel": "AAA",
    "suggestFixes": true
  }
}

Required contrast ratios: | Text Type | AA | AAA | |-----------|----|----|----| | Normal text (< 18pt) | 4.5:1 | 7:1 | | Large text (≥ 18pt or 14pt bold) | 3:1 | 4.5:1 | | UI components | 3:1 | - |

5. Specific Section Contrast

Analyze only part of the page:

{
  "url": "https://example.com",
  "options": {
    "selector": ".hero-section",
    "includePassingElements": false
  }
}

Common selectors:

.header, header, [role="banner"]
.main-content, main, [role="main"]
.footer, footer, [role="contentinfo"]
.modal, [role="dialog"]

6. APCA Analysis (WCAG 3.0 Draft)

For projects preparing for WCAG 3.0:

{
  "url": "https://example.com",
  "options": {
    "contrastAlgorithm": "APCA",
    "suggestFixes": true
  }
}

APCA vs WCAG 2.1:

WCAG 2.1 (Current)
APCA (WCAG 3.0 Draft)

Algorithm: Relative luminance ratioFormat: 4.5:1, 7:1 (ratios)Pros:

Current legal standard
Well understood
Widely supported

Cons:

Not perceptually uniform
Doesn’t account for polarity
Can miss readability issues

APCA thresholds:

75Lc: Body text (16px)
60Lc: Large text (24px)
45Lc: Non-text UI components

APCA is experimental (WCAG 3.0 draft). Use WCAG 2.1 for legal compliance.

Tool Comparison

Same Issue, Different Tools

How different tools report the same problem:

axe-core
Pa11y
Lighthouse

{
  "tool": "axe-core",
  "ruleId": "image-alt",
  "severity": "critical",
  "impact": "critical",
  "location": {
    "selector": "img:nth-child(2)"
  },
  "message": "Images must have alternate text",
  "html": "<img src='logo.png'>"
}

Characteristics:

Compact selectors
Clear impact levels
HTML snippet included
Low false positive rate

{
  "tool": "pa11y",
  "ruleId": "WCAG2AA.Principle1.Guideline1_1.1_1_1.H37",
  "severity": "serious",
  "type": "error",
  "location": {
    "selector": "html > body > div > img:nth-child(2)"
  },
  "message": "Img element missing an alt attribute. Use the alt attribute to specify a short text alternative.",
  "context": "<img src='logo.png'>"
}

Characteristics:

Full CSS path selectors
Verbose rule IDs
Detailed messages
Good HTML structure validation

{
  "tool": "lighthouse",
  "ruleId": "image-alt",
  "score": 0,
  "displayValue": "2 elements",
  "details": {
    "items": [
      {
        "node": {
          "selector": "img:nth-child(2)",
          "snippet": "<img src='logo.png'>"
        }
      }
    ]
  },
  "scoreDisplayMode": "binary"
}

Characteristics:

Contributes to overall score
Groups multiple instances
Shows count of affected elements
Part of larger accessibility score

Tool Feature Comparison

Feature	axe-core	Pa11y	Lighthouse	Contrast
Speed	~2-3s	~2s	~5-10s	~1-2s
Selector format	Compact	Full path	Compact	Compact
Severity levels	4 levels	3 types	Binary	4 levels
HTML snippet	✅	✅	✅	✅
Confidence score	✅	✅	-	Always 1.0
False positives	Very low	Moderate	Low	Very low
Scoring	-	-	0-100	-
Fix suggestions	-	-	Limited	✅ Colors
WCAG 3.0 (APCA)	-	-	-	✅

Frequently Asked Questions

Which tool should I use in CI/CD?

For deployed web: Use analyze-mixed for maximum coverage

Runs axe-core, Pa11y, and Lighthouse in parallel
Deduplicates common issues
Provides Lighthouse score for tracking

For color verification: Use analyze-contrast with fix suggestions

Fast and focused
Provides actionable color fixes
Can run on specific components

How do I handle false positives?

Verify with a second tool: Run analyze-mixed and check if multiple tools report it
Check confidence score: Scores < 0.8 may be false positives
Manual verification: Test with actual assistive technology
Exclude if confirmed: Use excludeRules option with documentation

{
  "options": {
    "excludeRules": ["duplicate-id"],
    "excludeReason": "False positive: IDs are unique per component instance"
  }
}

Can I analyze authenticated pages?

Not directly. Tools analyze public pages without authentication.Workarounds:

Capture HTML: Save authenticated page HTML and analyze with html parameter
Test environment: Configure test environment with auth bypass
Component testing: Analyze components in isolation

Future enhancement planned for cookie-based auth.

What are MCP Resources used for?

Resources provide reference data to complement analysis tools:

WCAG criteria lookup: wcag://criteria/{criterion}
Contrast thresholds: contrast://thresholds/wcag21 or apca
Lighthouse audits: lighthouse://audits

Resources are read-only and don’t require input—they expose accessibility knowledge.Example:

Tell me about WCAG 1.4.3 (contrast minimum)

What do severity levels mean?

Severity	User Impact
critical	Completely blocks users from tasks
serious	Major barriers, significantly hinders access
moderate	Some difficulty, but workarounds exist
minor	Annoyance that doesn’t prevent access

Use priority field for business decisions, not severity. Priority considers WCAG level and user impact.

How often should I run accessibility checks?

Scenario	Frequency	Tool
During development	Every feature branch	analyze-with-axe (fast)
Pre-deployment	Every release	analyze-mixed (comprehensive)
Production monitoring	Weekly or per sprint	analyze-mixed + Lighthouse
After major redesigns	Once	full-accessibility-audit prompt
Continuous tracking	Every commit	analyze-with-axe in CI

Workflows

Recommended workflows for common tasks

Effective Prompts

Tips for better prompts

Enriched Context

Understanding enriched human context

WCAG Criteria Resource

Browse WCAG reference data

Get Started

Core Concepts

Guides

Contributing

Key Fields in Issues

Field Descriptions

How to Prioritize

Prioritization Matrix

Triage Example

Tips for Prioritization

Advanced Tips

1. SPA Analysis with Lazy Loading

2. Mobile Viewport Analysis

3. Exclude Specific Rules

4. Contrast Analysis with AAA Level

5. Specific Section Contrast

6. APCA Analysis (WCAG 3.0 Draft)

Tool Comparison

Same Issue, Different Tools

Tool Feature Comparison

Frequently Asked Questions

Workflows

Effective Prompts

Enriched Context

WCAG Criteria Resource

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Contributing

​Key Fields in Issues

​Field Descriptions

​How to Prioritize

​Prioritization Matrix

​Triage Example

​Tips for Prioritization

​Advanced Tips

​1. SPA Analysis with Lazy Loading

​2. Mobile Viewport Analysis

​3. Exclude Specific Rules

​4. Contrast Analysis with AAA Level

​5. Specific Section Contrast

​6. APCA Analysis (WCAG 3.0 Draft)

​Tool Comparison

​Same Issue, Different Tools

​Tool Feature Comparison

​Frequently Asked Questions

​Related

Workflows

Effective Prompts

Enriched Context

WCAG Criteria Resource

Build docs developers (and LLMs) love

Key Fields in Issues

Field Descriptions

How to Prioritize

Prioritization Matrix

Triage Example

Tips for Prioritization

Advanced Tips

1. SPA Analysis with Lazy Loading

2. Mobile Viewport Analysis

3. Exclude Specific Rules

4. Contrast Analysis with AAA Level

5. Specific Section Contrast

6. APCA Analysis (WCAG 3.0 Draft)

Tool Comparison

Same Issue, Different Tools

Tool Feature Comparison

Frequently Asked Questions

Related