Purple A11y Use Cases

Improving website accessibility for screen reader users

Screen reader users are not able to understand and navigate across the different website pages because all the navigational buttons read out as “Buttons”. By using Purple A11y, agencies will be able to:

• Scan through the entire website and identify and generate the report on the accessibility-related code issues.
• With the report, developers will be able to quickly pick out similar code issues and refer to the WCAG clause which provide more information and possible solutions
• If the affected code is part of a component, fixing it at the component level may improve the accessibility across all other pages that uses the component
• The other accessibility issues in the report can also be used to plan the team’s accessibility roadmap.

Prioritising accessibility improvements

To help agencies improve their websites’ accessibility, Purple A11y report will group accessibility issues into 2 buckets: “Must-Fix” and “Good-to-Fix”.

• Must-Fix issues: These issues require immediate attention as they create significant barriers for Persons with Disabilities (PWDs), preventing them from accessing essential content or features. For example, the absence of form labels hinders accessibility, as they are crucial for screen reader users to understand input expectations and navigate the form effectively.
• Good-to-Fix issues: These issues may pose challenges for PWDs, but do not completely hinder their access to essential content or features. An example is ensuring that all page content is contained within appropriate landmarks, making navigation easier for screen reader users. Content outside of these landmarks can be difficult to find and the content’s purpose may be unclear, making it inconvenient for screen reader users.

Users should prioritise the “Must-Fix” issues first to prevent the exclusion of PWDs. To assist users in prioritisation, the report also provides additional information on each issue, such as:

• Why it matters: An explanation of the impact and implications of the issue on accessibility.
• WCAG Success Criteria conformance: Identification of the specific violation of the Web Content Accessibility Guidelines (WCAG) associated with the issue.
• Location of each occurrence: The specific areas or pages where the issue is present on the website or platform.
• Recommended fixes: Suggestions and guidance on how to address and resolve the issue effectively.

Continuously scanning for website accessibility

Scenario: An agency website is currently undergoing a sprint where accessibility fixes have been made. A DevOps engineer in the agency wants to ensure that these fixes have not disrupted any other part of the code base.

To do so, the engineer can run Purple A11y on any CI/CD tool which supports Docker-based runners.

The specific instructions provided below are for SHIP GitLab, and the steps show how to implement Purple A11y in the CI/CD pipeline:

1. Create a SHIP GitLab Testing Pipeline under your Project.

2. Build and push the Docker container.
   a. Purple A11y can be installed in a container environment using the included Docker template at Dockerfile.
   b. Build and push the image to your GitLab’s project’s container registry.

   # Checkout the Purple A11y repository
   git clone https://github.com/GovTechSG/purple-a11y.git
   
   # Navigate to purple-a11y
   cd purple-a11y
   
   # Build the image locally
   # Refer to Colima on how to run Docker https://github.com/abiosoft/colima
   docker build --platform linux/amd64 -t purple-a11y .
   
   # Login to your container registry with you username and personal access token
   # You may generate personal access tokens with read registry and write registry permissions at
   # https://sgts.gitlab-dedicated.com/-/user_settings/personal_access_tokens
   # Your GitLab username is usually your e-mail address without the domain
   # You may have to turn off WARP if you encounter `Error response from daemon: Get "https://registry.sgts.gitlab-dedicated.com/v2/": tls: failed to verify certificate: x509: certificate signed by unknown authority`
   docker login registry.sgts.gitlab-dedicated.com
   
   # Tag your image ready for SHIP GitLab
   docker tag purple-a11y:latest registry.sgts.gitlab-dedicated.com/<GitLab username>/<project name>
   
   # Ensure you have created a GitLab project containing Purple A11y's sample .gitlab-ci.yml
   # Push to the GitLab container registry
   docker push registry.sgts.gitlab-dedicated.com/<GitLab username>/<project name>
   

3. Configure the pipeline on GitLab.
   a. Create .gitlab-ci.yml in a test pipeline in the GitLab Editor if you have not done so.
   b. Copy the contents of gitlab-pipeline-template.yml and configure the following:
       i.   Set any tags required to identify the GitLab runner you wish to run your pipeline, e.g. ship_docker.
       ii.  Replace with the URL to docker image.
       iii. Edit the accessibility scan parameters with the type of scan you want to run:
   

   # Location of where you uploaded the docker image to registry
   DOCKER_IMAGE: registry.sgts.gitlab-dedicated.com/<GitLab username>/<project name>:latest
   
   # URL of the website or sitemap
   A11Y_SCAN_URL: "https://example.com"
   
   # Set the scan type [choices: "sitemap:", "website"]
   A11Y_SCAN_TYPE: "website"
   
   # Set the maximum number of pages to scan [default: 100]
   A11Y_SCAN_MAX_NUM_PAGES: 100
   
   # Zip filename of the artifact
   A11Y_SCAN_ARTIFACT_NAME: "ally-scan-results.zip"
   
   # Name:E-mail for telemetry data
   A11Y_SCAN_NAME_EMAIL: "John Doe:john@domain.com"
   

       iv. Commit the changes to GitLab.
   c. Check to see if the pipeline starts by navigating to your project > CI/CD > Jobs. You will then see the job complete, and the following:
       i.   A summary of total issue count and issue breakdown will be in the job log.
       ii.  A generated Purple A11y report can be downloaded at “Job artefacts” panel on the right panel as shown in the screenshot below.

1. After the user has configured and run an accessibility scan in GitLab CI/CD pipeline, the results will be uploaded as a Job Artifact.

The user can access the scan results by browsing the CI/CD Job page, and clicking the Download button under Job artifacts to view the report.html file which contains the Purple A11y report.

Last updated 26 April 2024