Requirements for Design Guide in WAI Supporting Documents

From Cognitive Accessibility Task Force


Note: current activity can be tracked in the wa1-coga-design-guide github repo.


Introduce tooling and process to support the Cognitive and Learning Disabilities Accessibility Task Force in publishing the Design Guide section of Content Usable TR note as part of the new Supporting Documents for WCAG 2 section of the WAI site. The new pages and the TR note need to share content but will have different presentation styles (document vs. web page).


  • Primary: People who want the web products they work on to provide excellent cognitive accessibility (including designers, developers, content creators, quality assurance testers). Could be accessibility champions, could be team members looking for "what to do" guidance.
  • Secondary: Researchers and Educators

Use cases

  • A designer or developer who is building a new feature, wants to learn ways to provide best cognitive accessibility practice
  • A Quality Assurance engineer who needs to approve the implementation of a new feature and wants to find a definitive source and intent
  • A content strategist wants to assess whether the content in a new feature has accessibility implications
  • An accessibility auditor wants to verify if something was built conform the standard

See also the more comprehensive current user flows.


The Cognitive and Learning Disabilities Accessibility Task Force publication Content Usable contains practical guidance developed from the research and gap analysis activities. It has three main sections: User Stories, Personas and a Design Guide. The Design Guide contains some 50 Patterns for Content Creators, Designers and Developers to implement in order to improve cognitive accessibility. However, the document format of a W3C TR note is not ideal for reviewing a large number of such Patterns and stakeholders have requested an interactive web resource for improved access. A proof of concept was previously created.

At the same time, there is a current WAI project to redesign the Supporting Documents for WCAG 2. This aims to make these documents easier to discover, navigate, and apply to web projects. The Supporting Documents are the "non-normative" technical guidance from the AG Working Group, such as Techniques and Understanding.

This page presents the requirements so the Design Guide can appear as part of these new resources.


The following aspects need to be addressed:

  • Integration with the WAI Supporting Documents project
  • Format of content required for the new supporting documents
  • Structure within a page
  • Organisation across web pages
  • Navigation within the Design Guide
  • Navigation and linkage within the supporting docs and WAI site
  • Integration with search
  • Pipeline to create both new and existing note
  • Enhanced TF editorial workflow
  • Updates to current content

Integration with the WAI Supporting Documents project

This project is being led by Hidde. The exact formats are being determined by the Supporting Documents project, perhaps with minor adjustments if required for this work.

Current discussion has agreed the following:

Build pipeline

  • Supporting Docs will have own GitHub Repo
    • new wai-coga-design-guide repo for content
  • Integrated into exist WIA website
    • ? URIs ?
  • Existing WAI website Jeckyll-based SSG
    • liquid templates
    • short codes for components
    • theme
  • GitHub action to push from Coga
    • may need content process depending on exact TF editing process
  • trigger
    • manual like WAI site publish GitHub action
    • ?or on push to main on coga repo

Content Format and Layout technologies

  • Markdown with yaml front matter
    • Pattern text in content, side bar links in yaml
  • minimal HTML, if any, ideally using custom tags
  • liquid templates if required
  • Page layouts (with header footer etc) provide by Supporting Documents project

Structure and Navigation of new repo and WAI resource

As scoped by the Supporting Documents project.

In wai-coga-design-guide repo

/ _objectives -> *.md
/ _patterns -> *.md
/ content ->,
  • linked to from Supporting Docs 'index' page in Wai site:
  • pages
    • "About Design Guide" page - summary / introduction
    • "Design Guide" page like all techniques page - index / navigation for browsing
      • collapsible Objectives
    • page per Objective - as per current TF format
    • page per Pattern - mockup but using the new DG template
  • outgoing links from pages in side bar
    • Design Guide internal links
    • external links eg to related techniques
  • The "Help Improve This page" section MUST link to coga repo not wai-coga-design-guide


  • Integration with WAI Search as defined by the Supporting Documents project.

Changes to coga repo and workflow

There should be a single review and approval cycle for each Objective / Pattern. The "approved" Patterns will be immediately published as part of the "Supporting Documents". They also get merged into the main branch of the "Note" ready for it's next publication.

  • Design guide document to be broken up:
    • page per Objective and per Pattern
    • minimal pure HTML content so can be used by
      • respec including document for the TR note
      • action that copies to WAI repo

New Coga editing tooling for New Pages and Existing Note

See detailed investigation in Tooling

  • input format, either:
    • Preferred, new shared format, per pattern - preferred, also supports new workflow (below), or
    • Existing note HTML + respc (or multi-page version) - complex to edit and automate
  • outputs
    • Design Guide as Supporting docs - as defined above
    • TR note - HTML + respec
      • Design Guide + other sections
      • integrates with W3C note publishing process
  • Repositories - coga, Wai new?
  • Tooling - GitHub actions
  • Triggers / flow
    • manual or on merge to master when updates approvded by TF, or
    • pull from the Supporting Docs or Note to be updated

Enhanced TF Editorial Workflow

The TF do not like working directly with HTML source. Ideally could work in a google docs like environment with track changes and commenting. A work able solution may be as per htmldiffs with or without in screen comments. This topic is explored in detail in the Tooling page.

  • Enable Taskforce to edit plain content without markup:
    • Live edit
    • Track changes + other formatting
    • Commments
  • Semi-automated editorial step to ensure correct structure and markup
    • Currently manual: HTML + respec in GitHub -> extract text to Google Doc -> edit -> reformat in HTML + respec
  • Frontend to the pipeline (above)

Possible implementation technologies

  • Netlify CMS - simple editor with YAML + markdown in GitHub content storage
  • Sanity - Google doc like editing tools with own data format + data server
  • Craft CMS being used in W3C site redesign

Updates to current content

  • Review all patterns not part of current review batch
  • Add links to other patterns and other Supporting docs in the side bar