WCAG 2.1 and support materials
The issues on the wcag 2.1 repo are currently reserved for success criteria proposals for wcag 2.1. Discussion of changes for understanding documents and techniques should take place on the list or in the wcag 2.0 repo issues.
The WCAG 2.1 repository contains source and auxiliary files for WCAG 2.1, Understanding WCAG 2.1, and eventually techniques, along with some content from WCAG 2.0 for context. It also contains auxiliary files that support automated formatting of the document. To facilitate multi-party editing, each success criterion is in a separate file, consisting of a HTML fragment that can be included into the main guidelines. Key files include:
- guidelines/index.html - the main guidelines file
- guidelines/sc/21/*.html - files for each success criterion
- guidelines/terms/21/*.html - files for each definition
- understanding/21/*.html - understanding files for each success criterion
Review links have been put at the top of each issue tracking the success criterion proposal. The pattern for review links is:
- SC for viewing: https://rawgit.com/w3c/wcag21/{branchname}/guidelines/sc/21/{scfile}.html
- SC for editing: https://github.com/w3c/wcag21/blob/{branchname{/guidelines/sc/21/{scfile}.html
- Term for viewing: https://rawgit.com/w3c/wcag21/{branchname}/guidelines/terms/21/{termfile}.html
- Term for editing: https://github.com/w3c/wcag21/blob/{branchname{/guidelines/terms/21/{termfile}.html
- SC in context of full guidelines: https://rawgit.com/w3c/wcag21/branchname/guidelines/#{scfile}
Success Criteria Managers will prepare candidate success criteria, ready for inclusion in the guidelines document. To prepare success criteria, follow these steps:
- Clone the repository, using the URI https://github.com/w3c/wcag21.git to clone.
- Switch to the working branch for the proposal, which is named for the shortname of the draft success criterion and the issue number, concatenated together.
- Find the appropriate file for the success criterion in the guidelines/sc/21 folder, named the same as the start of the branch name, and open in an HTML-capable editor. Do the same with any definitions referenced by the success criterion, in the guidelines/terms/21 folder.
- Open the guidelines/index.html file and remove comment marks around the lines that reference the success criterion and terms you have edited..
- Follow the success criteria format below to create the SC content.
- Save the file and commit the change. NOTE: It is important to also add a suitable 'commit message'. In the comments, reference the issue number from which the proposal was developed starting with a hash, e.g.,
#1. - When the success criterion is ready for Working Group review, inform the chairs. Once the proposal has been accepted by the Working Group, the editors will merge the working branch into the master branch, which puts it in the editors' draft and eventual Technical Report publication.
Success criteria use a simple structure of HTML elements, with a few class attribute values, to ensure consistency. Enhancement scripts and style key off this structure. Content you provide is indicated in braces. Items after comments are optional.
<section class="sc">
<h4>{SC Handle}</h4>
<p class="conformance-level">{Level}</p>
<p class="change">{Change}</p>
<p>{Main SC Text}</p>
<!-- if SC has sub-points -->
<dl>
<dt>{Point Handle}</dt>
<dd>{Point Text}</dd>
</dl>
<!-- if SC has notes -->
<p class="note">{Note}</p>
</section>Note you do not provide the SC number. Numbers will be assigned, and most likely automatically generated, later.
Values you provide are described below. Refer to Success Criterion 2.2.1 for an example of each of these pieces of content.
- {SC Handle}
- The short name of the SC. In SC 2.2.1 this is "Timing Adjustable".
- {Level}
- The conformance level of the SC. Values can be "A", "AA", or "AAA". Do not include the word "Level".
- {Change}
- Indicate whether the SC is unchanged from WCAG 2.0, changed, or new. Values can be "Unchanged", "Changed", or "New".
- {Main SC Text}
- The main text of the SC, or the starting paragraph. In SC 2.2.1 this is the content that begins "For each time limit...".
- {Point Handle}
- If the SC has bullets, each bullet has a handle. In SC 2.2.1 the first bullet point handle is "Turn off".
- {Point Text}
- The content of the bullet. In SC 2.2.1 the first bullet point text begins "The user is allowed...".
- {Note}
- If there is a note to the SC, provide it after the other content (without the starter "Note"). In SC 2.2.1, this is the content that begins "This success criterion...". If there is more than one note, multiple `
`elements may be provided.
If you providing term definitions along with your SC, include them in the glossary. Position them in the appropriate alphabetical order with the rest of the terms and use the following format:
<dt><dfn>{Term}</dfn></dt>
<dd>{Definition}</dd>The dfn element tells the script that this is a term and causes special styling and linking features. To link to a term, use an <a> element without an href attribute; if the link text is the same as the term, the link will be correctly generated. For example, if there is a term <dfn>web page</dfn> on the page, a link in the form of <a>web page</a> will result in a proper link. If the link text has a different form from the canonical term, e.g., "web pages" (note the plural), you can provide a hint on the term definition with the data-lt attribute. In this example, modify the term to be <dfn data-lt="web pages">web page</dfn>. Multiple alternate names for the term can be separated with pipe characters, with no leading or trailing space, e.g., <dfn data-lt="web pages|page|pages">web page</dfn>.
There is one Understanding file per success criterion, plus an index:
- understanding/index.html - index page, need to uncomment or add a reference to individual Understanding pages as they are made available
- understanding/21/*.html - files for each understanding page, named the same as the success criterion file in the guidelines
Files are populated with a template that provides the expected structure. Leave the template structure in place, and add content as appropriate within the sections. Elements with class="instructions" provide guidance about what content to include in that section; you can remove those elements if you want but don't have to. The template for examples proposes either a bullet list or a series of sub-sections, choose one of those approaches and remove the other from the template. The template for techniques includes sub-sections for "situations", remove that wrapper section if not needed.
Understanding files are referenced from the relevant Success Criterion on the WCAG 2.1 page; these links are put in by the script.
The formal publication location for Understanding pages is https://www.w3.org/WAI/WCAG21/Understanding/. This content is updated as needed; and may be automated.
The approach to techniques in WCAG 2.1 is not yet worked out. For the moment, list techniques in the Understanding document. References to existing WCAG 2.0 techniques should link to the technique on https://www.w3.org/TR/WCAG20-TECHS/. Proposed new techniques should be included as a draft technique title in the Understanding document, which will seed later work.