Please use this branch as the target for pull requests until July 10, 2016.

This repository is used to develop content for WCAG 2, as well as associated understanding documents and techniques.

@@To complete

• Avoid use of RFC2119 terms such as "must", "shall", or "may" in non-normative content, to avoid confusion with normative role.

See also: WCAG 2 Style Guide

WCAG 2.0 was maintained in a different file structure than subsequent versions of WCAG. Source files for WCAG 2.0 are in the wcag20 folder and exists primarily for archival purposes. Do not edit content in that folder.

Content for WCAG 2.1 and later is organized according to the file structure below. The WCAG repository contains source and auxiliary files for WCAG 2, Understanding WCAG 2, and eventually techniques. 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/{version}/*.html - files for each success criterion
• guidelines/terms/{version}/*.html - files for each definition
• understanding/{version}/*.html - understanding files for each success criterion
• wcag20/ was used by a previous version of WCAG, so anything ending .xml is no longer used, do not update.

Where {version} is "20", content came from WCAG 2.0. "21" is used for content introduced in WCAG 2.1, "22" for WCAG 2.2, etc.

The Techniques and Understanding documents are processed through a build system based on Eleventy and Liquid for templating and Cheerio for transformations. More details, including instructions for previewing the output locally, can be found in the build process README.

Success Criteria Managers will prepare candidate success criteria, ready for inclusion in the guidelines document. To prepare success criteria, follow these steps:

1. Clone the repository, using the URI https://github.com/w3c/wcag.git to clone.
2. 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.
3. 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.
4. Open the guidelines/index.html file and remove comment marks around the lines that reference the success criterion and terms you have edited..
5. Follow the success criteria format below to create the SC content.
6. 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.
7. 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 main 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>
	
	<dl>
		<dt>{Point Handle}dt>
		<dd>{Point Text}dd>
	dl>
	
	<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 are providing term definitions along with your SC, include them in the respective guidelines/terms/{version} directory, one-per-file, using the following format:

<dt><dfn id="dfn-{shortname}">{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 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 web page on the page, a link in the form of web page 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 web page. Multiple alternate names for the term can be separated with pipe characters, with no leading or trailing space, e.g., web page.

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/{version}/*.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 specification; these links are put in by the script.

The formal publication location for Understanding pages is currently https://www.w3.org/WAI/WCAG21/Understanding/. This content is updated as needed; and may be automated.

Techniques are in the techniques folder, and grouped by technology into sub-folders. Each technique is a standalone file, which is in HTML format with a regular structure of elements, classes, and ids.

The technique template shows the structure of techniques. Main sections are in top-level