Eleventy build: Support generating WCAG 2.1 docs from main branch

[kfranqueiro]

Background

There has long been interest in re-generating updated versions of the informative docs for WCAG 2.1. Previously, this relied upon a separate WCAG-2.1 branch, but the ideal outcome is to be able to build directly from main, altering/pruning content as appropriate.

Changes

This adds more functionality to the Eleventy-based build system to support building content targeting WCAG 2.1 in addition to 2.2, specifically when WCAG_VERSION=21 is set in environment variables:

• Guidelines are pulled from the web so as to not pick up information and alterations from newer WCAG versions (e.g. addition of new SC and removal of 4.1.1)
  • Parsing/processing is augmented as necessary to support both source and pre-processed guidelines
• Acknowledgements are also pulled from the web, pinned to 2.1
• target-size-enhanced is output to target-size for 2.1
• Detects what techniques only apply to later WCAG versions, and prunes them from associations
• Avoids emitting pages for techniques and understanding documents that exclusively pertain to later WCAG versions
• Further updates hard-coded version numbers in titles and level-1 headings, as well as throughout pages (especially refer-to-wcag) via Liquid expressions
• Adds support for setting both note and wcagXY class on the same element
• Conditionalizes a couple of 2.2-specific notes that were not within elements with wcag22 class
• Unchanged but worth noting: Obsolete technique data includes version information, so anything marked obsolete as of 2.2 will not contain an obsolete banner when publishing for 2.1

Preview

Do not use the Netlify preview for this, as it always builds 2.2 docs. (I've done a pass to verify that this PR doesn't visibly affect 2.2 output.)

I have set up a preview of this branch on my fork for the lifetime of this PR:

• https://kfranqueiro.github.io/wcag/techniques/
• https://kfranqueiro.github.io/wcag/understanding/

I have done quick-ish passes over both folders to try to spot and resolve any surprises. The Techniques pages largely only changed with respect to Test Rules (due to updated act-mapping.json) or the de-listing of obsolete techniques. I particularly looked over the Understanding pages since those align parallel with the guidelines and seem to have more meaningful updates. It is still possible that I have missed additional cases, e.g. of 2.2-specific wording that isn't properly enclosed in a class="wcag22" element. This ideally warrants a thorough review.

The following Understanding pages inherit notable changes: (checkboxes included for review tracking purposes)

• Use of Color (2.2, 2.1)
• Contrast (Minimum) (2.2, 2.1)
• Resize Text (2.2, 2.1)
• Reflow (2.2, 2.1)
• Non-text Contrast (2.2, 2.1)
• Text Spacing (2.2, 2.1)
• Keyboard (No Exception) (2.2, 2.1)
• Character Key Shortcuts (2.2, 2.1)
• Timing Adjustable (2.2, 2.1)
• Three Flashes or Below Threshold (2.2, 2.1)
  • Removes a 2.2-specific note
• Page Titled (2.2, 2.1)
• Focus Visible (2.2, 2.1)
• Pointer Gestures (2.2, 2.1)
• Label in Name (2.2, 2.1)
• Target Size (2.2, 2.1)
• Reading Level (2.2, 2.1)
  • Restores content that the XSLT build had suppressed
• Error Identification (2.2, 2.1)
• Labels or Instructions (2.2, 2.1)
• Parsing (2.2, 2.1)
  • No longer discusses removal, since it was only removed in 2.2 and there was seemingly some dedicated change on the WCAG-2.1 branch; do we still want a more prominent note here that is 2.1-specific? (The WCAG-2.1 branch also ends up repeating the SC a second time in this section even though it is still presented as usual in the box above Intent)
• Name, Role, Value (2.2, 2.1)
  • Removes a link that 404s
• Understanding Techniques (2.2, 2.1)
  • Updates “Techniques Submission Form” link to GitHub repo link
• Understanding Conformance (2.2, 2.1)
  • Examples no longer suppressed from build (content already existed)
  • Key Terms section is now properly generated
• How to Refer to WCAG from Other Documents (2.2, 2.1)
  • Version numbers consistently updated (examples were previously referencing 2.0)

[netlify]

✅ Deploy Preview for wcag2 ready!

Name	Link
🔨 Latest commit	895e0b1
🔍 Latest deploy log	https://app.netlify.com/sites/wcag2/deploys/672e8a0faf55220008e8ef23
😎 Deploy Preview	https://deploy-preview-4007--wcag2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[w3cbot]

kfranqueiro marked as non substantive for IPR from ash-nazg.

[alastc]

I'm fairly sure we didn't include anything 2.2 specific in 2.1 docs without that markup, it was very rare.

[stevefaulkner]

@mbgower - use of color, contrast (minimum), resize text
@patrickhlauke - reflow, non-text contrast, text spacing
@alastc - keyboard (no exception), character key shortcuts, timing adjustable
@scottaohara - three flashes or below threshold, page titled, focus visible
@dbjorge - pointer gestures, label in name, target size
@stevefaulkner - reading level, error identification, labels or instructions
@bruce-usab - parsing, name role value, understanding techniques

[bruce-usab]

Discussed on backlog call 11-1 and review divided up (as above).

[mbgower]

@kfranqueiro, the files for changed understanding docs (for instance use-of-color) are not generally showing up in the Files changed tab's list; however, I have confirmed that modifications to notes and the addition of paragraphs from 2.2 have been incorporated into the 2.1 preview (e.g., where the note or paragraph is missing from the current 2.1 Understanding doc).

[mbgower]

@kfranqueiro while the contrast minimum material has been updated, I assume the double-square bracket references in all 3 versions of this understanding document (2.0, 2.1, 2.2) were intended to be linked references, but did not generate properly. It looks like this is covered by #2535 so just flagging again here.

[kfranqueiro]

@kfranqueiro, the files for changed understanding docs (for instance use-of-color) are not generally showing up in the Files changed tab's list; however, I have confirmed that modifications to notes and the addition of paragraphs from 2.2 have been incorporated into the 2.1 preview (e.g., where the note or paragraph is missing from the current 2.1 Understanding doc).

Right, the actual source files for informative docs won't change. The difference is this builds 2.1 docs from main rather than from the variably-out-of-date WCAG-2.1 branch, which is what's responsible for all of the backports, the idea being that updates to informative docs on main will impact both versions. The only thing the WCAG-2.1 branch will still be used for is things directly impacting the TR doc itself.

@kfranqueiro while the contrast minimum material has been updated, I assume the double-square bracket references in all 3 versions of this understanding document (2.0, 2.1, 2.2) were intended to be linked references, but did not generate properly. It looks like this is covered by #2535 so just flagging again here.

Right, this doesn't affect that, and those have been an issue for as long as these docs have existed in their current form; there's a separate PR I opened this Tuesday that addresses as much of that as can currently be addressed with the information available in specref and our local biblio.js.

[mbgower]

@kfranqueiro I am now reviewing understanding/conformance.

IMO, for both 2.2 and 2.1, "which includes techniques for providing Conforming Alternate Version" should be lower case, to read:

See also Understanding Conforming Alternate Versions which includes techniques for providing conforming alternate versions.

The rationale is that the definition itself (2 paragraphs earlier) is lower case, so while it is fine to leave the heading link in camel case, the final term should be lc.

---

I'm also trying to understand whether "conforming alternative version" and "conforming alternate version" are accidental differences, or if there are actually two different terms. There are 31 occurrences of the former and 5 of the latter. I'm 90% sure this is supposed to all be the same thing; you'll note that under the title "Understanding Conforming Alternate Versions" both terms are used in the next paragraph, seemingly as synonyms.

IMO, these should all be alternative. That means "another option", while alternate implies a vacillation between two options.

I just had a look at WCAG 2.2, and its use of the two terms is almost opposite that in the Understanding section: 52 occurrences of "alternative" and 14 of "alternate"; however, there continues to be, within the normative text, use of the term "conforming alternate version" including in a definition.

@alastc do we just leave all these conflicts in place in the normative text, or do we try to incorporate this into the CFC?

PS When I just checked various files, I seemed to come up with different counts (48, 25). I'm not sure if I was doing a search with match case last time or what

[mbgower]

@kfranqueiro
In the understanding/conformance document, an opening quotation mark has ended up before the word "Note" rather than in front of the word "If"

[mbgower]

@kfranqueiro potentially the same issue in the Technical Definition of "Accessibility Supported" section; however, it is also like this on the 2.2 version, so maybe this is intentional?!

IMO, since there is styling showing the WHOLE thing is a quote, the quotation marks in front of note are not correct.

[mbgower]

if the position of these quotation marks is intentional, than there should be one in front of "See", I believe, in Understanding Conformance Alternate Versions:

[kfranqueiro]

The open quote issue appears to be a pre-existing issue in CSS.

Both the open quote and alternative/alternate issues should be entered as separate issues so we don't lose track of them, as they aren't specifically consequences of this PR.

Update: blockquote CSS issue entered at #4134

[bruce-usab]

I'm also trying to understand whether "conforming alternative version" and "conforming alternate version" are accidental differences, or if there are actually two different terms. There are 31 occurrences of the former and 5 of the latter. I'm 90% sure this is supposed to all be the same thing; you'll note that under the title "Understanding Conforming Alternate Versions" both terms are used in the next paragraph, seemingly as synonyms.

The canonical term, since 2008 is conforming alternate version. There is nothing wrong with "alternative" elsewhere -- but we should avoid it between "conforming" and "version". I find one (and only one) use of "conforming alternative version" in the spec, in Note 5. We should correct that for the CFC. It is editorial.

[mbgower]

@kfranqueiro an additional case of odd quotations marks on the Conformance page, this time appearing alone on the last lines

[mbgower]

In addition to completing my review of the three assigned files, I have also now completed the penultimate Conformance topic, and marked it as complete.

[mbgower]

I'm also trying to understand whether "conforming alternative version" and "conforming alternate version" are accidental differences, or if there are actually two different terms. There are 31 occurrences of the former and 5 of the latter. I'm 90% sure this is supposed to all be the same thing; you'll note that under the title "Understanding Conforming Alternate Versions" both terms are used in the next paragraph, seemingly as synonyms.

The canonical term, since 2008 is conforming alternate version. There is nothing wrong with "alternative" elsewhere -- but we should avoid it between "conforming" and "version". I find one (and only one) use of "conforming alternative version" in the spec, in Note 5. We should correct that for the CFC. It is editorial.

Despite me beginning to note a number of inconsistencies in the pre-existing content, that is not the purpose of this PR. It is to unearth issues with the migration of 2.2 changes to 2.1 content.

I have opened up a new issue to track this #4135

[dbjorge]

Reviewed my 3 assigned files. Didn't notice any issues (good catch on the pointer-gestures reference to dragging motion) except for one note/question on the slug override functionality for target-size-enhanced vs target-size

[dbjorge]

If someone somehow tries to visit the non-overriden slug, this is still going to resolve it; if I try that for target-size-enhanced in your test branch (ie, https://kfranqueiro.github.io/wcag/understanding/target-size-enhanced ), it resolves, but the resulting page is mistitled using the 2.2 title instead of the 2.1 title. Perhaps better to prevent it from resolving?

[kfranqueiro]

Thanks for taking a detailed look at this. The -enhanced page you are seeing is a remnant from what was already on the gh-pages branch that this published over; when running a clean build with WCAG_VERSION=21, only target-size.html is produced.

$ ls _site/understanding/target-size*
_site/understanding/target-size.html

The way that scSlugOverrides works is that each input file's basename (i.e. target-size-enhanced) gets looked up, and if a function for that name is found, the output of the function is used as the output basename instead. This results in target-size-enhanced being mapped (or "moved") to target-size specifically for WCAG < 2.2; there is no "fallback".

[bruce-usab]

WRT Parsing 4.1.1, @kfranqueiro asks:

...do we still want a more prominent note here that is 2.1-specific?

No, I think what you have is fine. I even considered the case of the 2018 2.1 edition, and if a different note (or Understanding doc) is needed. Again, what you have is fine. Thank you!

[bruce-usab]

Understanding Techniques 2.1 has ~Beginning of suite~ in the navigation bar at the top of the page. I have not spotted that artifact anywhere else.

[kfranqueiro]

Understanding Techniques 2.1 has ~Beginning of suite~ in the navigation bar at the top of the page. I have not spotted that artifact anywhere else.

@bruce-usab that is a known issue (#2953) found widely across existing WCAG 2.1 pages like the one you linked. Building with this PR fixes that. (See the example of the same page built with this PR: https://kfranqueiro.github.io/wcag/understanding/understanding-techniques)

[mbgower]

@kfranqueiro, the decision you have made in the final section on referring to WCAG from other documetns is a bit novel, and I think needs a bit more consideration/confirmation.

How to Refer to WCAG from Other Documents (2.2, 2.1)
Version numbers consistently updated (examples were previously referencing 2.0)

Looking exclusively at what has been done in 2.2, we have moved to generic usage of "WCAG 2" unless a specific version is required. That is, in the lastest document, there are 27 occurrences of the term "WCAG 2" and only 7 occurrences of the term "WCAG 2.2". I am inserting a very scaled-down version to provide some visual context of where these specific uses of 2.2 occur (one can also discover them by doing a Find for "WCAG 2.2" on the published page

On first consideration, then, tactically it appears that a similar approach should be taken with 2.1 (keep all but 7 generic). Instead, what you have done in this update is left all 34 occurrences as WCAG 2.1 and modified the generic title to be 2.1 specific.. In other words, it has altered from something titled "How to refer to WCAG from Other Documents" to being specifically about "How to refer to WCAG 2.1 from Other Documents".

This is a slight departure from the 2.1 specification itself, where the headings in some cases have been genericized to just "2" (but the specifics point to 2.1).

So, the immediate question for me is: should the heading include "2", with or without the ".1"?

This is a harder question to answer than one would expect, because although the existing 2.1 material includes 7 references to back to "2.0", each appears to be an error that should have been updated when the original 2.0 page was modified. In other words, it appears the authors intended this page to be exclusively about referencing 2.1, not either version of the spec.

CONCLUSION: I think what you have done preserves the intent of 2.1 as published (and fixes some errors). That said, the 2.2 version is more generic. IMO, the same treatment employed in 2.2 could be used in 2.1 (i.e., modify to 2.1 references only the 7 occurrences highlighted in yellow in the first image I posted); however, I can also accept it as you have implemented it, so I am checking this off as resolved BUT I am cc'ing @bruce-usab on this for his review.

[bruce-usab]

Every little thing is an improvement, so I think we should go forward with this. I would also characterize this PR as editor or bug fixes.

WCAG2-Issues TF will continue to iterate on substantive improvements to informative documents.

[patrickhlauke]

Not related to this PR specifically, but: the heading levels in https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast seem a bit haphazard later on - will file a separate issue. Also, while the technique in the 2.1 output https://kfranqueiro.github.io/wcag/techniques/failures/F78 doesn't list 2.4.13 which is WCAG 2.2 specific, the actual title of the technique includes it...

For both of these, probably worth filing separate follow-up tweaks

[patrickhlauke]

Again, not related to this PR, but noticed that https://www.w3.org/WAI/WCAG22/Understanding/text-spacing makes liberal use of SC throughout, rather than fully writing it out as "Success Criterion" or just "criterion". Again, something I'll file separately, as I don't think we do that (not as pervasively anyway?) in other understandings.

[mbgower]

Again, not related to this PR, but noticed that https://www.w3.org/WAI/WCAG22/Understanding/text-spacing makes liberal use of SC throughout, rather than fully writing it out as "Success Criterion" or just "criterion". Again, something I'll file separately, as I don't think we do that (not as pervasively anyway?) in other understandings.

I have held off on pushing updates to the styling for "SC", "Success Criterion/Criteria", etc., in the non-normative documents until we had a mechanism to correct across versions, which we will have after this. (The styling updates for normative content are included in the CFC.)

[kfranqueiro]

... while the technique in the 2.1 output https://kfranqueiro.github.io/wcag/techniques/failures/F78 doesn't list 2.4.13 which is WCAG 2.2 specific, the actual title of the technique includes it...

... probably worth filing separate follow-up tweaks

Great catch @patrickhlauke! I'd argue that'd be a regression, so I've committed a fix. Here's what it impacts:

• F55
• F78 (as you observed)
• Everywhere that references these:
  • Techniques index
  • Focus visible
  • Keyboard
  • Non-text contrast
  • On focus

Both F55 and F78 referenced 2.4.13 in their title/h1 and that now gets removed. There was one other technique that referenced 3.3.8 and 3.3.9, but both of those are 2.2-only and so the entire technique is already suppressed in 2.1 output.

[bruce-usab]

Discussed on TF call 11/8.