Make the companion accessible for all

[matt-dray]

As per the Service Manual.

I ran the Companion through tenon.io, an online resource for detecting accessibility issues. Apparently there are 629 issues at time of writing. I've saved a CSV of the report as a gist. You can click here to re-run the tenon.io report online.

[matt-dray]

Probable actions:

• [ ] Fix issues identified by tenon.io or other sources
• [ ] Adjust CONTRIBUTING.md with advice and link to Service Manual
• [ ] Do user research with the companion to find stumbling blocks (could be done with #80 in mind as well)
• [ ] Take to accessibility clinic every Thursday at 4pm

[nacnudus]

Firstly: :flushed:

• Bookdown book that talks about accessibility but doesn't seem to have customised bookdown itself?
• Conference talk.
• Bookdown template for US Web Design standards, including WCAG.
• @matt-dray's post on the RStudio Community, with some helpful replies.
• Suggestions from a blind R user.

[nacnudus]

Perhaps styling it with the GOV.UK Design System would help.

It turns out this is harder than a mere yaml setting:

output:
  html_document:
    css: govuk.css

The design system uses classes, so to style <h1>foo</h1> you have to do <h1 class="govuk-heading-xl">foo</h1>, which means you need to write a pandoc filter -- and Lua seems easier than Haskell -- that modifies the Abstract Syntax Tree representation of the document.

function Header(elem)
  level = elem.level
  content = elem.content
  identifier = elem.attr.identifier
  if level == 1 then
    attr = pandoc.Attr(identifier, {"govuk-heading-xl"})
  elseif level == 2 then
    attr = pandoc.Attr(identifier, {"govuk-heading-l"})
  elseif level == 3 then
    attr = pandoc.Attr(identifier, {"govuk-heading-m"})
  elseif level == 4 then
    attr = pandoc.Attr(identifier, {"govuk-heading-s"})
  elseif level == 5 then
    attr = pandoc.Attr(identifier, {"govuk-body-l"})
    return pandoc.Para(pandoc.Span(content, attr))
  end
  return pandoc.Header(level, content, attr)
end

And then in the yaml you put something like

output:
  html_document:
    css: ./node_modules/govuk-frontend/govuk.css
    pandoc_args: [
           --lua-filter, ./govuk.lua
        ]
    section_divs: no
    theme: null

Why section_divs: no? Otherwise the header and its body text (and nested headers) are wrapped in a <div>, the class is added to the <div>, so the body is styled like a header too.

Where does govuk.css come from? You have to compile the sass in the Design System after you 'install' it (basically downloads the node_modules directory. There's an R package for that.

This doesn't make it possible to invent new markdown syntax, so we can't port govspeak (and R doesn't work well with Ruby). Instead the pattern seems to be to use fenced divs and spans like here. This level of hack is known as a 'custom writer', with an official example.

Code blocks in the Design System are still 'todo' but the site of the design system itself has an implentation.

[nacnudus]

I've clone the content of the companion to the RAP website, built on govdown, which uses accessible components from the GOV.UK Design System. The original RAP Companion bookdown website will remain as-is because it's too hard to fix and we should break compatibility with the MOOC.

I'll add subsequent steps as govdown or rap-website issues, e.g. testing in the empathy lab.