David Gardiner - Accessibility

Fixing my blog (part 6) - Accessibility scanning

2022-04-24T09:00:00.000+09:30

Now we've got broken links sorted, we're in a better state to start accessibility testing using the Accessibility Insights Action. This is available as both a GitHub Action and an Azure DevOps extension. I'll be using the GitHub Action version.

name: Accessibility

on:
  workflow_dispatch:
    
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - uses: ./.github/actions/jekyll-build-pages
        with:
          verbose: false

      - run: |
          sudo find -type f ! -regex ".*\.\(html\|svg\|gif\|css\|jpg\|png\)" -delete
        name: Remove non-HTML
        
        # https://github.com/microsoft/accessibility-insights-action
      - name: Scan for accessibility issues
        uses: microsoft/accessibility-insights-action@v2
        with:
            repo-token: ${{ secrets.GITHUB_TOKEN }}
            site-dir: ${{ github.workspace }}/_site
            scan-timeout: 6000000
            #max-urls: 1500
            localhost-port: 12345
            scan-url-relative-path: /

      - name: Upload report artifact
        uses: actions/upload-artifact@v2
        with:
            name: accessibility-reports
            path: ${{ github.workspace }}/_accessibility-reports/index.html

The action can either scan a local directory or a URL. In my case, I want it to scan all the files that make up my blog. My blog content is written in Markdown (.md) files and uses the Jekyll engine to render those pages into .html. It's the latter that should be scanned for accessibility compliance.

To generate the .html files, I make use of the Jekyll-Build-Pages action. This will generate a bunch of files under the _site directory.

My initial testing with the scanning tool revealed it was triggering on some pages I was including but had no control over (eg. Google Ads and the Disqus comments). I wanted to exclude those from the scanning, and one way to do that is to make the content conditional. eg.

{%- if jekyll.environment == "production" -%}
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-999999999" crossorigin="anonymous"></script>
{%- endif -%}

To exclude this block, I then needed to ensure that jekyll.environment was not set to production. I achieved this by using a local copy of the action in which I set the value of the JEKYLL_ENV environment variable to development. To facilitate that I need to make a few other changes which you can see on this branch.

To help focus the scanning just on the files I care about, I added an extra step to the workflow to remove any files that weren't one of .html, .svg, .gif, .jpg or .png.

Depending on how many files you have in your website, scanning can take quite.

It's probably a good idea to not set max-urls the first time. This uses the default of 100, which will be enough to give you an idea of the kinds of problems you need to fix.

The reason for starting small is if you have a template or CSS that are used across every page, then every page will trigger errors, and your scan will take ages to finish and contains heaps of the same error(s).

Once you've resolved those common errors, then you can ramp up your max-urls to cover all the pages on your site (if it didn't already).

Running the workflow above also produces an 'Accessibility Checks' report. You can use this to get a quick overview of the results. To drill in to the details, you should download the build artifact view the index.html file in your browser.

Fixing the errors

The scan flagged 5 rule violations. Expanding each rule lists the URLs that exhibited the problem, plus a suggestion on how to resolve the issue. Sometime there are multiple suggestions.

color-contrast: Ensure the contrast between foreground and background colors meet WCAG 2 AA contrast ration thresholds

Example

<a href="/tag/Family.html">Family</a>

Fix the following:

Element has insufficient color contrast of 4.14 (foreground color: #2a7ae2, background color: #fdfdfd, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1Element has insufficient color contrast of 4.14 (foreground color: #2a7ae2, background color: #fdfdfd, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
- Use foreground color: #2773d6 and the original background color: #fdfdfd to meet a contrast ratio of 4.58:1.
Element has insufficient color contrast of 3.77 (foreground color: #828282, background color: #fdfdfd, font size: 10.5pt (14px), font weight: normal). Expected contrast ratio of 4.5:1Element has insufficient color contrast of 3.77 (foreground color: #828282, background color: #fdfdfd, font size: 10.5pt (14px), font weight: normal). Expected contrast ratio of 4.5:1
- Use foreground color: #747474 and the original background color: #fdfdfd to meet a contrast ratio of 4.59:1.

These were common across all pages, so fixing these early is a quick win. I searched for the hex color (usually it was defined in one of the .scss files that generate the CSS) and replaced it with the suggested colour

link-name: Ensures links have discernible text

Fix the following:

Element is in tab order and does not have accessible text

Fix ONE of the following:

Element does not have text that is visible to screen readers
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute

image-alt: Ensures `<img>` elements have alternate text or a role of none or presentation

Fix ONE of the following:

Element does not have an alt attribute
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute
Element's default semantics were not overridden with role="none" or role="presentation"

html-has-lang: Ensure every HTML document has a lang attribute

Fix the following:

The <html> element does not have a lang attribute

This was a false positive as for some reason it was being flagged on images.

frame-title: Ensures `<iframe>` and `<frame>` elements have an accessible name

Fix ONE of the following:

Element has no title attribute
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element's default semantics were not overridden with role="none" or role="presentation"

This was being flagged by some older YouTube embedded player HTML.

I've raise a bug to report the problem with links to images being flagged. It feels to me like the scanner is trying to scan image URLs (which it shouldn't). Whether that's a bug in the action, or in how I'm using it, I hope to find out soon.

Fixing my blog (part 1) - Introduction

2022-04-19T13:00:00.000+09:30

I've been revisiting web accessibility. It's something I remember first learning about accessibility many years ago at a training workshop run by Vision Australia back when I worked at the University of South Australia. The web has progressed a little bit in the last 15 odd years, but the challenge of accessibility remains. More recently I had the opportunity to update my accessibility knowledge by attending a couple of presentations given by Larene Le Gassick (who also happens to be a fellow Microsoft MVP).

I wondered how accessible my blog was. Theoretically it should be pretty good, considering it is largely text with just a few images. There shouldn't be any complicated navigation system or confusing layout. Using tools to check accessibility, and in particular compliance with a particular level of the Web Content Accessibility Guidelines (WCAG) standard will not give you the complete picture. But it can identify some deficiencies and give you confidence that particular problems have been eliminated.

Ross Mullen wrote a great article showing how to use the pa11y GitHub Action as part of your continuous integration workflow to automatically scan files at build time. Pa11y is built on the axe-core library.

Further research brought me to Accessibility Insights - Android, browser and Windows desktop accessibility tools produced by Microsoft. From here I then found that Microsoft had also made a GitHub Action (currently in development) Accessibility Insights Action, which as I understand it, also leverages axe-core.

The next few blog posts will cover my adventures working towards being able to run that action against my blog. I thought it would be simple, but it turns out I had some other issues with my blog that needed to be addressed along the way. Stay tuned!

Don't let me be misunderstood

2022-02-07T09:00:00.000+10:30

A common goal of many people, including myself, is to be understood. To not only be heard but listened to. For the person receiving to 'get' what the first person is saying.

This is trickier with the written word compared to a verbal conversation. You can't usually rely on quick feedback techniques like 'reflective listening' or similar to correct misunderstandings or gain clarification. Writing clearly can also improve the accessibility of your content.

So if good written communication is your goal, then there are a few things you can employ:

Correct spelling
Appropriate grammar
Proofreading (ideally by another person)

I was reminded of this recently when an old work colleague (hi Simon!) reached out to let me know that I had a typo in my GitHub 'About Me' page. He knew me well enough to know that I love this kind of feedback! It caused me to review the text again myself, and I discovered a second error, so it was good to get them both fixed.

Another example that comes to mind is an ebook I purchased a couple of years ago from a well-known book publisher. I won't name the title, but it relates to .NET, and almost from the first page I was encountering grammatical errors. I don't blame the author for this, but rather the book publisher. My understanding is that these should have been caught in the editing phase of publishing. It doesn't reflect well on the publisher (or the editor) that they somehow missed addressing this, and makes me more cautious about buying other books from them. The result was a book that I found hard to read. Sentences didn't flow, and comprehension was more of a challenge than it should have been. I gave up reading the book in the end as it was too distracting.

I've recently been going back and running cspell over my older blog posts. It's embarrassing to find numerous spelling errors in old posts that have been sitting there for years. At least I can fix them. A little while ago, I migrated my blog from Blogger to self-hosting on GitHub using Jekyll, with all the posts now being written in Markdown. I have the Code Spell Checker extension installed in Visual Studio Code. For newer posts, spelling errors should be flagged in the editor.

Microsoft Word has had grammar checking built-in for quite a while, and I thought I'd have a search to see if there was something similar for Visual Studio Code (the editor I use to write my blog posts in). It looks like Rahul Kadyan has written an unofficial Grammarly extension. I just installed it, and check out all the extra squiggles as I was writing this page in the screenshot below!

Do take the time to review Grammarly's privacy policy. They run "as a service", so all your text for grammar checking will be sent to them, so make sure you're comfortable with that.

Look, it's spotted another repeated word ("an an old work") already!

The extension has some limitations. Some of the corrections are only available to paid Grammarly users (it took me a bit to figure that out - signing in with a free account doesn't seem to have any benefit).

It is interesting to compare that to copying and pasting the text into Microsoft Word. Fewer squiggles, but it has flagged the repeated word.

Tools are great, but the skill is knowing when to use them and when it is ok to ignore them.

Getting at least one extra pair of eyes to proofread your text is probably the best idea. Only this week, I asked a colleague to review something I'd written to confirm that my intentions were being conveyed correctly before sharing it more widely. It's less useful for my blog, being my thoughts, but I have used it in the past. While my blog content is hosted on GitHub, the repository is private, as sometimes I might have future posts or drafts that aren't ready to be publicly viewable.

In conclusion, my goal is to create clear and understandable content. Do reach out in the comments if you find cases where I've fallen short of that - I'm sure there are many (probably some I've still overlooked in this post!). With your help, I hope you find it easier to understand what I'm trying to say.

User group audio and video

2015-09-11T16:57:00.001+09:30

I’ve been pondering how to improve the ability of ADNUG (Adelaide .NET User Group) to do a decent job at:

Skype/Google Hangout video conferences – so that the remote presenter can see and hear attendees
Record audio of our group for a member with a vision impairment which means that they can’t physically attend meetings.

I’m not sure if there’s necessarily a huge overlap between those two requirements, but they both involve audio so they’re kind of related.

For the recent Google Hangout we had with Scott Hanselman, I purchased a Microsoft LifeCam Studio webcam. I mounted this on a tripod and used a couple of USB extension cables. Scott reported that the video quality was a bit poor with some flickering. I suspect the use of the extension cables might have reduced the quality of the signal too much – combined with the fact that I was only on Wifi instead of using the network cable (that I only noticed when the meeting was almost over!). The tripod mount is definitely a plus though.

Scott recommended the Logitech Webcam 930e, which has the advantage of being wider-angle (90° vs the LifeCam’s 75°). I’ll see how I go with the Microsoft camera, otherwise trading up might be an option.

Sound-wise was also not ideal. I didn’t have any complaints with previous hangouts earlier in the year with Jon Galloway and Sayed Hashimi, but maybe Scott was possibly more interactive and wanted to hear questions raised from and converse with the crowd. As it was, I had to repeat the questions for him (as I was standing near my laptop). So a microphone that can pick up the whole room would be great.

It seems the kind of microphone I’d need to pick up is a a conference or ‘boundary’ type. Most of these are ‘omni-directional’, meaning they pick up sound in all directions and from a wide area – contract that with a normal vocal mic, which works best right in front of your mouth.

For a USB solution, these models from MXL seem to be well regarded:

For an XLR connector (XLR is the 3-pin connector commonly used with professional audio equipment), then maybe something like this:

The meeting we had this week at Marcellina had over 40 people in attendance. It turns out Marcellina function room has their own PA system, so I was glad to make use of that so that everyone could hear better. Having said that, they just have a hand-held microphone with no mic-stand – so that can get tricky if you’re speaking and trying to type at the same time.

Having a mic and loud speaker was a big help to the people in the room, but I didn’t have time beforehand to see if I could hook into their amplifier to record the audio. Instead to make the audio recording of the meeting, I just used the Windows 10 Voice Recorder app on my laptop (using my laptop’s inbuilt microphone), and just left that running for the duration of the talks.

A lapel microphone would be ideal, and wireless even better (so you’re free to walk around).

Audio2000 AWM-6032UL UHF Dual Channel Wireless Microphone System with One Handheld & One Lapel (Lavalier) Mic. This kit with a wireless hand-held and lapel would be pretty nice – wire up the main presenter with the lapel, which leaves the hand-held for the MC.

I get the impression that if you got the XLR-type microphones, you really need some kind of mixer/pre-amp that you’d then feed into the laptop (or other recording device).

Something like one of these:

So who knows if we ever get any of this. Given the costs, most of it’s probably just a pipe-dream. Having said that I’d appreciate any thoughts/suggestions/feedback on the options above or other ways that we might take some ‘baby-steps’ to improve things just a little bit.

Writing Accessible Web Applications

2006-11-08T09:40:00.000+10:30

Microsoft have published a useful whitepaper on how to create an accessible web site/application.

Acronym support - A Windows Live Writer Plugin I'd like to see

2006-10-11T15:37:00.001+09:30

I try to make the effort to use the <acronym> element to explain any acronyms used in my posts.

What I'd like is a plugin for Windows Live Writer that lets me select text and add surround it with <acronym> element.

If there was a acronym web service out there somewhere, then it could hook into that to source the definitions of the acronym.

Simple, accessible external links

2006-01-13T14:22:00.000+10:30

Russ Weakley shows an example of some clever CSS hacking so that you can always indicate that a hyperlink is "external" (eg. it is leaving the current site).

Converting HTML to CSS

2005-10-05T11:02:00.000+09:30

I came across this really useful site today that has some nice examples of how to convert old-style HTML into nice, accessible new HTML+CSS.

I made use of the "Line up form inputs" example, which gives a really clean, elegant result.

Web Accessibility Network for Australian Universities

2005-04-11T09:17:00.000+09:30

Web Accessibility Network for Australian Universities Based at Monash University. There will be a forum in Adelaide on September 5th, hosted by the University of South Australia.

Accessible ASP.NET DataGrid Control

2005-04-10T20:47:00.000+09:30

Accessible ASP.NET DataGrid Control: "The DataGrid was initially developed by David at the University of South Australia, where he works as a senior developer in the Flexible Learning Centre. UniSA has kindly agreed that this control would be of benefit to many others so it has been released and will continue to be developed as an open-source project." My first project hosted on sourceforge!

David Gardiner - Accessibility

Fixing my blog (part 6) - Accessibility scanning

Fixing the errors

color-contrast: Ensure the contrast between foreground and background colors meet WCAG 2 AA contrast ration thresholds

link-name: Ensures links have discernible text

image-alt: Ensures <img> elements have alternate text or a role of none or presentation

html-has-lang: Ensure every HTML document has a lang attribute

frame-title: Ensures <iframe> and <frame> elements have an accessible name

Fixing my blog (part 1) - Introduction

Don't let me be misunderstood

User group audio and video

Writing Accessible Web Applications

Acronym support - A Windows Live Writer Plugin I'd like to see

Simple, accessible external links

Converting HTML to CSS

Web Accessibility Network for Australian Universities

Accessible ASP.NET DataGrid Control

image-alt: Ensures `<img>` elements have alternate text or a role of none or presentation

frame-title: Ensures `<iframe>` and `<frame>` elements have an accessible name