Skip to main content
Back to User Guide

Technical Documentation

Comprehensive Guide with Detailed Examples

This technical documentation provides in-depth information about using the WCAG Scanner, including detailed workflows, feature explanations, and best practices for achieving WCAG 2.2 Level AA compliance.

How-To Guide: Using Kosansh WCAG Scanner

This comprehensive guide walks you through using all features of Kosansh WCAG Scanner with step-by-step instructions and screenshots.

Table of Contents

  1. 100% WCAG 2.2 AA Coverage
  2. AI-Powered Alt Text Validation
  3. Real-Time Streaming Results
  4. Detailed Solutions with Code Examples
  5. Video, PDF, and Document Scanning
  6. Scanning
  7. Authenticated Page Scanning

1. 100% WCAG 2.2 AA Coverage

Overview: WCAG 2.2 AA Coverage

Kosansh WCAG Scanner provides complete coverage of all WCAG 2.2 Level AA success criteria across all 4 principles (Perceivable, Operable, Understandable, Robust).

How It Works

Step 1: Start a Scan

  1. Navigate to the home page
  2. Enter your website URL (e.g., example.com or `)
  3. Click "Start Scan"
    Home page with URL input form

    Home page with URL input form

    The home page shows the URL input form where you can enter any website URL Step 2: View Comprehensive Coverage
  4. Once the scan starts, you'll be redirected to the scan dashboard
  5. The dashboard shows real-time progress and violations
  6. Each violation is tagged with its specific WCAG 2.2 criterion ID (e.g., 1.1.1, 1.4.3, 2.4.2)
    Scan dashboard showing violations with WCAG criterion IDs

    Scan dashboard showing violations with WCAG criterion IDs

    The dashboard displays all violations organized by WCAG 2.2 criteria Step 3: Review Coverage Report
  7. Scroll through the violations list
  8. Each violation shows:
    • WCAG criterion ID (e.g., "1.1.1 - Non-text Content")
    • Severity level (Error, Warning, Info)
    • Element location
    • Detailed description
      Violations list with WCAG criterion details

      Violations list with WCAG criterion details

      Each violation is clearly labeled with its WCAG 2.2 criterion ID and level Step 4: Check Compliance Score
  9. View the compliance score breakdown
  10. See scores by principle (Perceivable, Operable, Understandable, Robust)
  11. See scores by level (A, AA, AAA)
    Compliance score breakdown by principle and level

    Compliance score breakdown by principle and level

    The compliance score shows detailed breakdowns by WCAG principles and levels
  • ✅ All 78+ WCAG 2.2 AA success criteria are checked
  • ✅ Violations are mapped to specific criterion IDs
  • ✅ Coverage includes all 4 principles and 13 guidelines

2. AI-Powered Alt Text Validation

Overview: AI-Powered Alt Text Validation

Unlike basic alt text checking, our AI-powered validation analyzes image content and compares it with alt text to determine accuracy and relevance.

How It Works

Step 1: Enable AI Features

  1. When starting a scan, AI features are enabled by default
  2. The scanner automatically detects all images on the page
  3. Each image is analyzed using AI vision models
    Scan options showing AI features enabled

    Scan options showing AI features enabled

    AI features are automatically enabled for all scans Step 2: View AI Validation Results
  4. Navigate to the scan dashboard
  5. Look for violations with "AI validation" in the message
  6. These violations show accuracy scores (0-100)
    AI alt text validation results showing accuracy scores

    AI alt text validation results showing accuracy scores

    AI validation results show accuracy scores and specific issues Step 3: Review AI Suggestions
  7. Click on an AI validation violation
  8. View the detailed solution page
  9. See:
    • Current alt text
    • AI-detected image content
    • Accuracy score
    • Suggested improvements
    • AI-generated alternative alt text
      Solution page showing AI analysis and suggestions

      Solution page showing AI analysis and suggestions

      The solution page shows AI analysis comparing alt text with actual image content Step 4: Understand Accuracy Scores
  • 90-100: Excellent - Alt text accurately describes image
  • 70-89: Good - Minor improvements possible
  • 50-69: Fair - Some inaccuracies or missing details
  • 0-49: Poor - Alt text is generic, inaccurate, or missing
    Accuracy score explanation

    Accuracy score explanation

    Accuracy scores help you understand the quality of alt text
  • ✅ AI analyzes actual image content
  • ✅ Compares with existing alt text
  • ✅ Provides accuracy scores and suggestions
  • ✅ Generates improved alt text alternatives

3. Real-Time Streaming Results

Overview: Real-Time Streaming Results

Get instant feedback as violations are discovered. No need to wait for the entire scan to complete.

How It Works

Step 1: Start a Scan

  1. Enter your URL and click "Start Scan"
  2. You'll be immediately redirected to the scan dashboard
  3. The dashboard starts showing results in real-time
    Scan dashboard immediately after starting scan

    Scan dashboard immediately after starting scan

    The dashboard appears instantly with live updates Step 2: Watch Live Progress
  4. Observe the progress bar updating in real-time
  5. See pages being scanned as they complete
  6. Watch violation count increase as issues are found
    Live progress bar and real-time updates

    Live progress bar and real-time updates

    Progress updates appear instantly as pages are scanned Step 3: View Streaming Violations
  7. Violations appear in the feed as they're discovered
  8. Each violation shows:
    • Timestamp
    • Page URL
    • Violation details
    • Link to solution
      Real-time violations feed

      Real-time violations feed

      Violations stream in real-time as they're discovered Step 4: Monitor Multiple Pages
  9. For site scans, see results for each page as it completes
  10. Each page result shows:
    • Page title and URL
    • Compliance score
    • Number of violations
    • Timestamp
      Page-by-page results streaming in

      Page-by-page results streaming in

      Multiple pages show results as they're scanned Step 5: Export Results Anytime
  11. You can export results even while the scan is in progress
  12. Click "Export PDF" or "Export JSON"
  13. Get a snapshot of current results
    Export options available during scan

    Export options available during scan

    Export options are available throughout the scan process
  • ✅ Results appear instantly as discovered
  • ✅ No waiting for scan completion
  • ✅ Progress updates in real-time
  • ✅ Can export partial results

4. Detailed Solutions with Code Examples

Overview: Detailed Solutions with Code Examples

Every violation includes a dedicated solution page with before/after code examples, framework-specific solutions, and step-by-step testing instructions.

How It Works

Step 1: Find a Violation

  1. Navigate to the scan dashboard
  2. Click on any violation in the list
  3. You'll be taken to the detailed solution page
    Violations list with clickable items

    Violations list with clickable items

    Click any violation to see its detailed solution Step 2: View Solution Overview
  4. The solution page shows:
    • WCAG criterion reference
    • Severity badge
    • Clear description of the issue
    • General solution explanation
      Solution page header with overview

      Solution page header with overview

      The solution page header provides context and overview Step 3: Review Before/After Code
  5. Scroll to the "Code Examples" section
  6. See side-by-side comparison:
    • Before (Incorrect): Shows the problematic code
    • After (Correct): Shows the fixed code
  7. Code is syntax-highlighted for readability
    Before/after code comparison

    Before/after code comparison

    Side-by-side code comparison makes fixes clear Step 4: Get Framework-Specific Solutions
  8. Scroll to "Framework-Specific Solutions"
  9. Find solutions for:
    • React
    • Vue.js
    • Angular
  10. Copy-paste ready code examples
    Framework-specific solutions

    Framework-specific solutions

    Framework-specific solutions for popular technologies Step 5: Follow Testing Steps
  11. Review the "Testing Steps" section
  12. Follow step-by-step instructions to verify your fix
  13. Use the provided checklist
    Testing steps checklist

    Testing steps checklist

    Step-by-step testing instructions Step 6: Explore Additional Resources
  14. Check the "Resources" section
  15. Find links to:
    • Official WCAG documentation
    • Tools and examples
    • External learning resources
      Resources section with links

      Resources section with links

      Additional resources for deeper understanding Step 7: Learn from Common Mistakes
  16. Review "Common Mistakes" section
  17. Understand frequent errors to avoid
  18. Prevent similar issues in the future
    Common mistakes section

    Common mistakes section

    Learn from common mistakes to prevent future issues

Example Solution Page Structure

┌─────────────────────────────────────┐ │ WCAG 2.2 1.1.1 - Non-text Content │ │ Severity: Error │ ├─────────────────────────────────────┤ │ Issue Description │ │ General Solution │ ├─────────────────────────────────────┤ │ Code Examples │ │ ┌───────────┬───────────┐ │ │ │ Before ❌ │ After ✅ │ │ │ └───────────┴───────────┘ │ ├─────────────────────────────────────┤ │ Framework-Specific Solutions │ │ • HTML │ │ • React │ │ • Vue.js │ │ • Angular │ ├─────────────────────────────────────┤ │ Testing Steps │ │ 1. Check all <img> elements... │ │ 2. Verify alt text describes... │ │ 3. Test with screen reader │ ├─────────────────────────────────────┤ │ Resources │ │ • WCAG Documentation │ │ • WebAIM Guide │ ├─────────────────────────────────────┤ │ Common Mistakes │ │ • Using generic alt text │ │ • Missing alt attribute │ └─────────────────────────────────────┘

  • ✅ Every violation has a solution page
  • ✅ Before/after code examples provided
  • ✅ Framework-specific solutions available
  • ✅ Testing steps included
  • ✅ Resources and common mistakes documented

5. Video, PDF, and Document Scanning

Overview: Video, PDF, and Document Scanning

Kosansh WCAG Scanner automatically detects and scans videos, PDFs, and other documents embedded on web pages for accessibility compliance.

How It Works

Step 1: Automatic Detection

  1. Start a scan of any website
  2. The scanner automatically detects:
    • <video> elements
    • PDF links and embeds
    • Document links (DOCX, XLSX, PPTX)
  3. No additional configuration needed
    Scan starting with automatic detection

    Scan starting with automatic detection

    The scanner automatically detects media and documents Step 2: View Video Accessibility Results
  4. Navigate to the scan dashboard
  5. Look for violations related to videos
  6. Each video violation shows:
    • Missing captions/subtitles
    • Missing audio descriptions
    • Caption quality issues
    • WebVTT validation errors
      Video accessibility violations

      Video accessibility violations

      Video violations show specific accessibility issues Step 3: Review Video Scores
  7. Click on a video violation
  8. See the video accessibility score (0-100)
  9. Breakdown shows:
    • Captions (40 points)
    • Audio description (30 points)
    • Voice content (20 points)
    • Basic video element (10 points)
      Video accessibility score breakdown

      Video accessibility score breakdown

      Video scores show detailed breakdown of accessibility features Step 4: View PDF Accessibility Results
  10. Find PDF-related violations in the dashboard
  11. Each PDF violation shows:
    • Missing document title
    • Missing language declaration
    • Untagged structure
    • Missing bookmarks/outline
    • Missing alt text for images
    • Form field accessibility issues
      PDF accessibility violations

      PDF accessibility violations

      PDF violations show document accessibility issues Step 5: Review PDF Scores
  12. Click on a PDF violation
  13. See the PDF accessibility score (0-100)
  14. View recommendations for improvement
    PDF accessibility score and recommendations

    PDF accessibility score and recommendations

    PDF scores include specific recommendations Step 6: Check Document Results
  15. For other documents (DOCX, XLSX, PPTX), see similar results
  16. Each document type has specific checks
  17. View format-specific recommendations
    Document accessibility results

    Document accessibility results

    Document results show format-specific issues
  • ✅ Videos automatically detected and checked
  • ✅ PDFs scanned for full accessibility
  • ✅ Documents analyzed for compliance
  • ✅ Scores and recommendations provided

Overview

Scan native lications for and to ensure WCAG 2.2 AA compliance in mobile contexts.

Prerequisites

Required Software:

  1. ** Server**: Install and run
  2. ** Requirements** (for scanning):
    • installed
    • or physical device
    • driver
  3. ** Requirements** (for scanning):
    • installed
    • or physical device
    • 2 driver
    • : `` file or
    • : `` file or
  4. Start your /
    Appium server running

    Appium server running

  • server must be running before scanning* **Step 2: Start Mobile Scan **
  1. Use the mobile scan :
    API request for mobile scan

    API request for mobile scan

    *Mobile scans are initiated * Step 3: View Scan Results
  2. For apps, results show:
    • compatibility issues
    • Missing accessibility labels
    • Touch target size violations (minimum 44x44 points)
    • UIKit accessibility trait issues
    • Screen reader announcement problems
      iOS scan results

      iOS scan results

  • scan results show and accessibility issues* Step 4: View Scan Results
  1. For apps, results show:
    • compatibility issues
    • Missing content descriptions
    • Touch target size violations (minimum 48x48 dp)
    • AccessibilityNodeInfo issues
    • Accessibility role problems
      Android scan results

      Android scan results

  • scan results show and accessibility issues* Step 5: Review Mobile Violations
  1. Each violation shows:
    • Screen name
    • Element location
    • Issue type
    • WCAG criterion reference
    • Solution recommendations
      Mobile violations with solutions

      Mobile violations with solutions

      Mobile violations include screen context and solutions Step 6: Check Screen-by-Screen Results
  2. View results organized by screen
  3. Each screen shows:
    • Screen name
    • Elements found
    • Violations on that screen
    • Accessibility score
      Screen-by-screen mobile results

      Screen-by-screen mobile results

      Results organized by app screens
  • ✅ apps can be scanned
  • ✅ apps can be scanned
  • ✅ Native and hybrid apps supported
  • ✅ Screen-by-screen results provided
  • ✅ Mobile-specific WCAG checks included

Overview

Scan pages behind login/authentication, including corporate applications, SPAs, and protected content.

How It Works

  1. Identify your
  2. Gather required credentials:
    • For : username, password, form selectors
    • For : and header name
    • For : JWT/ token
    • For : configuration
      Authentication method selection

      Authentication method selection

      *Choose your * **Step 2: Start Authenticated Scan **
  3. Use the authenticated scan :
    Authenticated scan API request

    Authenticated scan API request

    Authenticated scans are initiated with auth details Step 3: View Authentication Status
  4. The scan dashboard shows authentication status
  5. See if authentication was successful
  6. View session maintenance status
    Authentication status in dashboard

    Authentication status in dashboard

    Dashboard shows authentication and session status Step 4: Review Protected Page Results
  7. See results for each protected route
  8. Each page shows:
    • Page URL
    • Authentication status
    • Violations found
    • Compliance score
      Protected page scan results

      Protected page scan results

      Results show which protected pages were scanned **Step 5: Handle **
  9. The scanner automatically:
    • Maintains session across pages
    • Re-authenticates if session expires
    • Retries on authentication failures
  10. View session status in the dashboard
    Session management status

    Session management status

  • is handled automatically* Step 6: Review SPA-Specific Results
  1. For Single-Page Applications (SPAs):
    • Scanner waits for content to load
    • Checks dynamic content
    • Validates client-side routing
  2. See SPA-specific violations
    SPA scan results

    SPA scan results

  • include *
  • ✅ authentication works
  • ✅ authentication works
  • ✅ authentication works
  • ✅ authentication works
  • ✅ works
  • ✅ works
  • ✅ Multiple can be scanned

Overview

Prerequisites

Required Software:

  1. ** 18+** - Install from nodejs.org
  2. QL - Install from ql.org
  3. Chrome/Chromium - Required for Puppeteer

Setup Steps

Step 1: Install Dependencies **Step 2: Configure **

  1. Create a `` file in the project root (Next.js convention)
  2. Add your :
  3. Add any optional s for AI features: =your-key-here **Step 3: Create QL ** Or using : Step 4: Run s
  4. Ensure your `` file has _URL set
  5. Run the script:
  6. This will:
    • Create the s
    • Run all pending s
    • Add the metadata to scan_results
    • Create necessary indexes Step 5: Verify Setup Check status: You should see all s as executed. **Step 6: ** Visit ` to use the application.
  • ✅ connection works
  • ✅ All s executed successfully
  • ✅ Application starts without errors
  • ✅ Scans can be created and results saved
Back to User GuideReturn to Scanner