a11yGuard

a11yGuard home page
Tabular summary of accessibility violations
List of new violations
Detailed description of violations
Action running within pull request

Inspiration

According to WebAIM, around 94% - 98% of websites are not fully compliant with Web Content Accessibility Guidelines (WCAG). Examples of these guidelines include alternative text for images, distinguishable text, readability, and much more. These guidelines are put into place to promote accessibility within software, yet they are often ignored and not enforced. Our project, a11yGuard, was created with the hopes of changing this. We do not see these guidelines as recommendations, and built this program to ensure that software developers make their code accessible.

What it does

Whenever new code is pushed onto GitHub through a pull request, a11yGuard automatically checks for Web accessibility violations using the industry-standard axe-core engine. This is done as a GitHub action. After displaying the violations to the user, a11yGuard automatically creates a version of the code that complies with the Web accessibility guidelines, without affecting the functionality of the code.

How we built it

We started by writing simple Python code to detect the WCAG violations of webpages and printing the results. After hours of research and planning, we decided to switch the core architecture to JavaScript because axe-core is native to JS. We then started to build the GitHub action workflow which consisted in a lot of trial and error. We use a YML file to call all of our JavaScript code on the pull request and then use the Gemini LLM API to fix the code. To run the check, the file below needs to be added to the root of the repository in the folder .github/workflows

name: Accessibility Regression Check

on:
  pull_request:

jobs:
  a11y:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Run accessibility check
        uses: zachkklein/WCAG_PR_Checker@v2
        with:
          APP_DIR: '.'
          BUILD_DIR: 'public'
          URLS: '/'
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

Challenges we ran into

Writing most of the code base in JavaScript was definitely a challenge as most of us have not done significant native JS. The biggest road block we hit was a bug within the a11y.yml file. We were getting the same results across different repositories, noticing the errors were things found in almost every project. We found the issue was due to the build folder specified within the yml file that our code was looking for html files in. After solving this bug we were able to get the action to run successfully across many different repositories.

Accomplishments that we're proud of

First and foremost, we are proud to be making software more accessible by creating a tool that all developers can seamlessly integrate into their GitHub workflows. We are especially proud of our LLM integration into the workflow, allowing developers to receive automatic feedback and corrections to their code.

What we learned

GitHub actions. We approached this Hackathon hoping to build both a meaningful project, and something we can learn a new technology from. Learning more in depth JavaScript was also super useful throughout building this project. Overall, it was such a great experience working as a team to build a meaningful project

Team

Andrew Bacigalupi
Will Goldman
Zachary Klein
Ethan Li
Theethat Thakong
Alex Vu

Acknowledgments

Jordan Pittignano for the amazing snacks!
The Jumbohack coordinators for the Redbull and amazing experience
Claude, Cursor, and Gemini for the help in structuring, coding, and debugging our project

What's next for a11yGuard

Future improvements include an improved algorithm for finding accessibility violations and an improved format of the user output. Additional features could include a proprietary "accessibility score” to numerically assign a grade to the overall accessibility of the website.