Skip to content
Posts en inglés. Usá el traductor del navegador para leerlos en tu idioma.

How to Build a Basic AI-Powered Website Accessibility Checker

Yammbo
· 9 min read
Copyright: CC BY-NC-SA 4.0
web accessibility wcag guidelines prompt engineering html accessibility ai development
How to Build a Basic AI-Powered Website Accessibility Checker

Ensuring website accessibility is crucial for an inclusive web, yet it often presents a challenge, especially for small businesses or individual creators with limited resources. Manual audits can be time-consuming and expensive, while automated tools sometimes require a deep technical understanding to interpret their reports. This tutorial will guide you through building a basic AI-powered tool that can provide a quick, 'first-look' accessibility assessment of any given HTML content. This type of checker won't replace a full audit, but it can quickly flag common issues, helping you prioritize improvements and make your web content more accessible from the start.

Step 1: Understand Core Web Accessibility Principles

Before building an accessibility checker, it's essential to grasp the fundamental principles it will be evaluating. Web accessibility aims to ensure that websites, tools, and technologies are designed and developed so that people with disabilities can use them. The Web Content Accessibility Guidelines (WCAG), developed by the World Wide Web Consortium (W3C), are the globally recognized standard. Your AI tool will be designed to identify common deviations from these guidelines.

Key areas your checker should consider include:

  • Alternative Text for Images: All meaningful images should have descriptive alt attributes for screen readers.
  • Semantic HTML: Using appropriate HTML tags (e.g., <h1> for main headings, <nav> for navigation, <button> for buttons) instead of generic <div> or <span> elements helps assistive technologies understand content structure.
  • Color Contrast: Text and interactive elements should have sufficient contrast ratios against their background to be legible for users with low vision or color blindness.
  • Link Text: Links should have descriptive text that indicates their purpose, rather than generic phrases like "click here."
  • Form Labels: All form input fields should have associated <label> elements to provide context.
  • Keyboard Navigation: While harder for an AI to fully check from HTML alone, structural hints can be identified.

Familiarizing yourself with these principles will help you craft more effective prompts for your AI and better interpret its output. For a comprehensive overview, refer to the official WCAG Quick Reference.

Step 2: Set Up Your AI Development Environment

To build this checker, you'll need access to a large language model (LLM) through an API. Platforms like Google AI Studio (which powers models like Gemini) provide an accessible way to interact with powerful AI models. These platforms typically offer a free tier for development, requiring you to create an account and generate an API key.

  1. Choose an AI Platform: For this tutorial, we'll assume a platform similar to Google AI Studio, which allows direct interaction with models like Gemini.
  2. Create an Account: Sign up for the chosen AI platform. This usually involves a standard registration process.
  3. Generate an API Key: Once logged in, navigate to the API key management section. Generate a new API key. This key is your credential for making requests to the AI model and should be kept secure. Treat it like a password.
  4. Install Necessary Libraries: You'll likely use a programming language like Python to interact with the API. Install the required libraries for making HTTP requests and handling JSON data. For Python, this usually means requests.
pip install requests

With your API key in hand and your environment set up, you're ready to start crafting the instructions for your AI assistant.

Step 3: Design the AI Prompt for Accessibility Checks

The effectiveness of your AI checker largely depends on how well you instruct the language model. This is known as prompt engineering. Your prompt needs to clearly define the AI's role, the input it will receive, and the desired output format.

Here's a breakdown of what a good prompt for an accessibility checker should include:

  • Role Definition: Tell the AI to act as an expert in web accessibility, specifically knowledgeable in WCAG guidelines.
  • Task Description: Instruct it to analyze the provided HTML content for common accessibility issues.
  • Output Format: Specify that the output should be structured, ideally as a list of identified issues. For each issue, request:
    • A clear description of the problem.
    • The specific WCAG principle or guideline it relates to.
    • A brief explanation of why it's an accessibility issue.
    • A suggestion for how to fix it.
    • The problematic HTML snippet, if applicable.
  • Context and Limitations: Remind the AI that it's performing a 'first-look' analysis based solely on the provided HTML and cannot simulate user interaction or dynamic content.

Here’s an example of a prompt you could use:

You are an expert web accessibility auditor, highly knowledgeable in WCAG 2.2 guidelines. Your task is to perform a 'first-look' accessibility analysis on the provided HTML content.Identify common accessibility issues based on the HTML structure and content. For each issue found, provide the following details in a clear, concise manner:1.  **Issue Description:** A brief explanation of the problem.2.  **WCAG Reference:** The relevant WCAG guideline (e.g., "WCAG 2.2 Success Criterion 1.1.1 Non-text Content"). Provide a direct link to the W3C explanation if possible.3.  **Impact:** Explain why this issue negatively affects users with disabilities.4.  **Suggested Fix:** A practical recommendation to resolve the issue.5.  **Problematic HTML (Optional):** The exact HTML snippet causing the issue, if easily identifiable.Present your findings as a numbered list of issues. If no significant issues are found, state that the HTML appears to be generally accessible from a structural perspective. Focus on issues detectable purely from static HTML.Do not attempt to evaluate dynamic interactions, focus order, or complex JavaScript behaviors, as these require a full browser context.Here is the HTML to analyze:

Following this prompt, you would append the HTML content you want the AI to analyze.

Step 4: Implement the Checker Logic with Code

Now, let's put it all together with a simple Python script. This script will take HTML as input, combine it with your prompt, send it to the AI model via its API, and then print the AI's response.

import requestsimport json# Replace with your actual API key and the API endpoint for your chosen AI modelAPI_KEY = "YOUR_API_KEY"# This URL is illustrative; actual endpoint will vary by provider# For Google AI Studio/Gemini, it might look like: "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=" + API_KEYAPI_ENDPOINT = "https://api.example.com/ai/v1/analyze" # Placeholder# Your carefully crafted prompt from Step 3PROMPT_TEMPLATE = """You are an expert web accessibility auditor, highly knowledgeable in WCAG 2.2 guidelines. Your task is to perform a 'first-look' accessibility analysis on the provided HTML content.Identify common accessibility issues based on the HTML structure and content. For each issue found, provide the following details in a clear, concise manner:1.  **Issue Description:** A brief explanation of the problem.2.  **WCAG Reference:** The relevant WCAG guideline (e.g., "WCAG 2.2 Success Criterion 1.1.1 Non-text Content"). Provide a direct link to the W3C explanation if possible.3.  **Impact:** Explain why this issue negatively affects users with disabilities.4.  **Suggested Fix:** A practical recommendation to resolve the issue.5.  **Problematic HTML (Optional):** The exact HTML snippet causing the issue, if easily identifiable.Present your findings as a numbered list of issues. If no significant issues are found, state that the HTML appears to be generally accessible from a structural perspective. Focus on issues detectable purely from static HTML.Do not attempt to evaluate dynamic interactions, focus order, or complex JavaScript behaviors, as these require a full browser context.Here is the HTML to analyze:"""def check_accessibility(html_content):    full_prompt = PROMPT_TEMPLATE + html_content    headers = {        "Content-Type": "application/json"    }    payload = {        "contents": [            {                "parts": [                    {"text": full_prompt}                ]            }        ]    }    try:        response = requests.post(API_ENDPOINT, headers=headers, json=payload)        response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)        result = response.json()        # Extract the text from the AI's response. This structure varies by AI provider.        # For Gemini, it might be result['candidates'][0]['content']['parts'][0]['text']        # Adjust based on your AI platform's actual response structure.        ai_text_response = result.get('candidates', [{}])[0].get('content', {}).get('parts', [{}])[0].get('text', 'No accessibility issues found or AI response was unclear.')        return ai_text_response    except requests.exceptions.RequestException as e:        return f"Error communicating with AI API: {e}"    except KeyError:        return "Could not parse AI response. Check API documentation for expected format."# Example HTML to test (you can replace this with any HTML)example_html = """<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>Test Page</title></head><body><img src="logo.png"><h1>Welcome</h1><a href="#">Click here</a><input type="text"></body></html>"""if __name__ == "__main__":    print("Running accessibility check...")    report = check_accessibility(example_html)    print("\n--- Accessibility Report ---")    print(report)    print("\n--------------------------")

Remember to replace YOUR_API_KEY and API_ENDPOINT with your actual credentials and the correct endpoint for your chosen AI service. The exact structure for extracting the AI's text response (e.g., result.get('candidates', [{}])[0].get('content', {}).get('parts', [{}])[0].get('text', ...)) will depend on the specific API you are using. Consult your AI provider's documentation.

Step 5: Interpret and Refine AI-Generated Accessibility Reports

Once you run your script, the AI will return an analysis based on your prompt and the provided HTML. It's crucial to understand how to interpret this report and its inherent limitations.

Interpreting the Report:

  1. Review Each Issue: Go through each identified issue. Does the description accurately reflect a problem? Is the WCAG reference correct?
  2. Verify Suggestions: Evaluate the suggested fixes. Are they practical and effective? Sometimes, an AI might offer a generic solution that needs tailoring to your specific context.
  3. Prioritize: Use the report to prioritize your accessibility efforts. Some issues (like missing alt text or poor contrast) are often quick wins, while others might require more significant structural changes.

Understanding Limitations:

An AI-powered 'first-look' checker is a valuable starting point, but it is not a substitute for a comprehensive accessibility audit performed by a human expert or specialized tools that can simulate user interaction.

Here's what your AI checker, relying solely on static HTML, cannot fully assess:

  • Keyboard Navigation: Whether all interactive elements are reachable and operable via keyboard.
  • Focus Order: If the tab order makes logical sense for keyboard users.
  • Dynamic Content Changes: How JavaScript-driven content updates affect screen readers or other assistive technologies.
  • ARIA Attributes: While it can identify the presence of ARIA, it can't fully validate its correct implementation or impact without a live browser context.
  • Video/Audio Captions and Transcripts: Unless the captions are embedded directly in the HTML (which is rare), the AI cannot verify their existence or accuracy.
  • User Experience: The overall usability and intuitiveness for users with various disabilities.

Use the AI's report as a guide to identify obvious structural and content-based issues. For a truly accessible website, this initial scan should be followed by manual testing, user testing, and potentially more advanced automated tools that operate in a browser environment.

Building an AI-powered accessibility checker offers a practical way to quickly identify potential barriers on your website. While it provides a valuable initial scan, remember that true accessibility is an ongoing process that benefits from human review and continuous improvement. If you're looking to build an accessible online presence, Yammbo Web offers an AI-powered website builder at https://web.yammbo.com that can help you create inclusive web experiences.