QUAIL: Accessibility Information LibraryΒΆ
QUAIL is a jQuery and Sizzle-comptable library for checking content against accessibility guidelines. It provides a flexible way to test for certain problems (say, images missing an alt text) and a collection of over 250 tests to get you started.
TestsΒΆ
At the core of QUAIL are tests. Tests search for a single type of accessibility problem, and they are all defined in the file src/resources/tests.yaml (a JSON version is available in dist/tests.json - read more about building these files). For example, one of the most common accessibility problems out there is an image missing an alt attribute (which allows users with screen readers to hear a description of the image). The test definition in the tests.yaml file looks like this:
imgHasAlt:
selector: "img:not(img[alt])"
tags:
- "image"
- "content"
testability: 1
type: "selector"
guidelines:
508:
- "a"
wcag:
1.1.1:
techniques:
- "F65"
- "H37"
title:
en: "Image elements must have an \"alt\" attribute"
description:
en: "All <code>img</code> elements must have an alt attribute"
....
- The test name in this example is “imgHasAlt,” which is the unique label for the test. These are used in creating guidelines. There are at least two definitions for each test:
- type - QUAIL has some default test types to simplify the process of writing test definitions. The simplest is a selector, which just takes a jQuery/Sizzle-compatable selector and finds all items that match that selector. For selector tests, we also must define the selector to use (in this case, img:not(img[alt])).
- severity - The default severity level. Severity is a measure of how certain we are a test will not create false positives: - severe - We are 100% certain that this test is always correct. If an image is missing its alt attribute, it’s missing its alt attribute. - moderate - We are mostly certain this test is correct. This is usually found for content-related tests, like testing to see if a block of text is written at or below a certain grade level. - suggestion - We cannot test for this, but can suggest things to manually review. For exmaple, we cannot test that content in a Flash object is accessible, but we can point out that a flash object is there and link to appropriate guidelines on making accessible flash.
- guidelines - A list of pre-defined guidelines (right now, either 508 or WCAG 2.0) including: - techinques - The WCAG techniques aligned with this test - configuration - Optional configuration options for this test only specific to this test.
- title - The human-readable title of the test, prefixed by language code.
- description - The human-readable description of the test, prefixed by language code.
GuidelinesΒΆ
Guidelines are simply a collection of tests. QUAIL comes with US Section 508 and WCAG guideline files in src/resources/guidelines. Every guideline is simply an array of test names, which means you can easily create your own guidelines. In the examples/php directory you can see a custom guideline being defined in a PHP script.
UsageΒΆ
To use QUAIL, you will need to make a simple jQuery/Sizzle object (in this example, we are checking an element with the ID of content), then run the quail function against it:
$('#content').quail({ jsonPath : 'src/resources',
guideline : 'wcag2a',
accessibilityTests : accessibilityTests,
testFailed : function(event) { ... },
customTests : {
myCustomTest : {
type : 'custom',
callback : function(quail) {
quail.html.find('.error').each(function() {
quail.testFails('myCustomTest', $(this));
})
}
}
},
complete : function(event) { ... },
});
The quail function accepts a single object with the following items:
- jsonPath - Required - The path to the resources folder where QUAIL is located. Certain tests load additional strings like emoticons or filler words from JSON files to save space. If a test ends up needing to load additional resources, this will be required.
- guideline - Required - Either the name of a guideline file that can be found in the jsonPath directive, or an array of test names.
- accessibilityTests - Optional - If you wish to load your own custom test definitions, this will prevent QUAIL from using it’s own tests.json file to load the tests. This is also useful if you are loading tests.json through your own method and don’t want QUAIL to do it for you.
- testFailed - Optional - A callback that will be called everytime an item fails a test. This callback recieves an object with the following items:
- element - The native jQuery/Sizzle object that represents the DOM element.
- testName - The name of the test that failed
- severity - The severity of the test.
- options - Additional options as passed by the test definition.
- customTests - Optional - An object of tests that can be added to QUAIL on the fly. Tests should have a name, and either use some of the pre-defined callbacks in QUAIL (like “selector”), or a “custom” type, where you define a callback that accepts a QUAIL object.
- preFilter - Optional - A callback that can be used to pre-filter out failed items. If this callback returns false, then the item is skipped and not considered failed. This callback receives the following argumetns: - testName - The name of the test that failed - element - A full jQuery/Sizzle object of the element - options - Any additional options set by the test
- complete - Optional - Called when all the tests are completed. This is useful for reporting, as it gets a summary of all resutls. This callback gets a single object with the following items:
- totals - An object with the total number of severe, moderate, and suggestion tests which failed.
- results - An object with all the elements and tests that failed.
Available testsΒΆ
- Adjacent links that point to the same location should be merged
- When an image is in a link, its “alt” attribute should not repeat other text in the link
- Link text should not begin with redundant text
- Lists of links should be seperated by printable characters
- Links should not open a new window without warning
- The text in links should make sense out of context
- Any links to a multimedia file should also include a link to a transcript
- Any links to a sound file should also include a link to a transcript
- Links should contain text
- All links must have a “title” attribute
- Links should not use “javascript” in their location
- Link text should be useful
- The title attribute of all source a (anchor) elements describes the link destination.
- The document should contain an address for the author
- The document should contain a valid email address for the author
- All applets should contain the same content within the body of the applet
- All applets should contain a text equivalent in the “alt” attribute
- All applets should provide a way for keyboard users to escape
- Any user interface in an applet must be accessible
- All applets do not flicker
- Applets should not use color alone to communicate content
- All “area” elements must have an “alt” attribute which describes the link destination
- Alt text for “area” elements should replicate the text found in the image
- No “area” elements should open a new window without warning
- All “area” elements must have an “alt” attribute
- All “area” elements which link to a sound file should also provide a link to a transcript
- Pages using ARIA roles should not have orphaned content
- Basefont” should not be used
- The “blink” tag should not be used
- The “blockquote” tag should not be used just for indentation
- If long quotes are in the document, use the “blockquote” element to mark them
- Contrast between active link text and background should be 5:1
- Contrast between text and background should be 5:1
- Contrast between link text and background should be 5:1
- Body elements do not use a background image
- Contrast between visited link text and background should be 5:1
- The “b” (bold) element is not used
- All checkboxes must have a corresponding label
- All “checkbox” input elements have a label that is close
- The document must be readable with styles turned off
- All elements should have appropriate color contrast
- The document should contain a valid “doctype” declaration
- Abbreviations must be marked with an “abbr” element
- Acronyms must be marked with an “acronym” element
- All the document colors must be set
- Auto-redirect with “meta” elements must not be used
- Contrast between active link text and the background must be greater than the WAI ERT color algorithm threshold
- Contrast between text and the background must be greater than the WAI ERT color algorithm threshold
- Contrast between link text and the background must be greater than the WAI ERT color algorithm threshold
- Contrast between visited link text and the background must be greater than the WAI ERT color algorithm threshold
- Content should be readable without style sheets
- The document should have a title element
- All element “id” attributes must be unique
- The document should be written to the target audience and read clearly
- The document’s language attribute should be a standard code
- The document must have a “lang” attribute
- Meta” elements must not be used to refresh the content of a page
- Reading direction of text is correctly marked
- The page uses a strict doctype
- The title describes the document
- The document title should not be placeholder text
- The document title should be short
- The document should not have an empty title
- Document must validate to the doctype
- Visual lists of items are marked using ordered or unordered lists
- Any words or phrases which are not the document’s primary language should be marked
- All “embed” elements have an associated “noembed” element
- Embed” elements must have an “alt” attribute
- Embed” elements cannot have an empty “alt” attribute
- All embed elements should provide a way for keyboard users to escape
- Emoticons should not be used excessively
- All “file” input elements have a corresponding label
- All “file” input elements have a label that is close
- Font” elements should not be used
- Deleting items using a form should be reversable
- Forms offer the user a way to check the results of their form before performing an irrevokable action
- Form error messages should assist in solving errors
- Input items which are required are marked as so in the label element
- Frames are not used
- Complex framesets should contain a “longdesc” attribute
- The source for each frame is accessible content.
- All “frame” elemetns should have a “title” attribute that describes the purpose of the frame
- Frames cannot have empty “title” attributes
- Frames cannot have “title” attributes that are just placeholder text
- All “frame” elements should have a “title” attribute
- The “frameset” element should not be used
- All framesets should contain a noframes section
- The header following an h1 is h1 or h2
- All h1 elements are not used for formatting
- The header following an h2 is h1, h2 or h3
- All h2 elements are not used for formatting
- The header following an h3 is h1, h2, h3 or h4
- All h3 elements are not used for formatting
- The header following an h4 is h1, h2, h3, h4 or h5
- All h4 elements are not used for formatting
- The header following an h5 is h6 or any header less than h6
- All h5 elements are not used for formatting
- All h6 elements are not used for formatting
- All headers should contain readable text
- Use headers to mark the beginning of each section
- The “i” (italic) element is not used
- Inline frames (“iframes”) should not have a “longdesc” attribute
- All links in a server-side map should have duplicate links available in the document
- If an image is purely decorative, the “alt” text must be empty
- Any image within a link must have “alt” text the describes the link destination
- Image “alt” attributes should not be the same as the filename
- Check that any text within an image is also in the “alt” attribute
- Image Alt text is short
- An image within a link cannot have an empty “alt” attribute if there is no other text within the link
- Images should not have a simple placeholder text as an “alt” attribute
- Unless the image files are the same, no image should contain redundant alt text
- Any animated GIF should not flicker
- Image elements must have an “alt” attribute
- A “longdesc” attribute is required for any image where additional information not in the “alt” attribute is required
- Images that are important should not have a purely white-space “alt” attribute
- All links within a client-side image are duplicated elsewhere in the document
- An image with a “longdesc” attribute should have a corresponding description link
- Any non-decorative images should have a non-empty “alt” attribute
- For any image, the “alt” text cannot refer to color alone
- Server-side image maps should not be used
- Images should not have a “title” attribute
- Any image with an “ismap” attribute have a valid “usemap” attribute
- Images which contain math equations should provide equivalent MathML
- All “checkbox” input elements require a valid “tabindex” attribute
- Logical groups of check boxes should be grouped with a “fieldset
- An “input” element should not use color alone
- Input elements which are not images should not have an “alt” attribute
- All “file” input elements require a valid “tabindex” attribute
- All “input” elements with a type of “image” must have an “alt” attribute that describes the function of the input
- All “input” elements with a type of “image” must have an “alt” attribute which is not the same as the filename
- All “input” elements with a type of “image” must have an “alt” attribute which is not placeholder text
- All “input” elements with a type of “image” must have an “alt” attribute which is as short as possible
- The “alt” text for input “image” submit buttons must not be filler text
- All “input” elements with a type of “image” must have an “alt” attribute
- The “alt” text for input “image” buttons must be the same as text inside the image
- All “password” input elements require a valid “tabindex” attribute
- All “radio” input elements require a valid “tabindex” attribute
- All input elements, type of “submit
- All “input” elements should have a corresponding “label
- All “text” input elements require a valid “tabindex” attribute
- All “input” elements of type “text” must have a default text
- Text” input elements require a non-whitespace default text
- Label” elements should not contain an input element
- Every form input must have only one label
- Labels must contain text
- All labels should be associated with an input
- All “legend” elements must describe the group of choices
- Legend” text must not contain just whitespace
- Legend” text must not contain placeholder text like “form” or “field
- Use a “link” element for alternate content
- Document uses link element to describe navigation if it is within a collection.
- Lists should not be used for formatting
- The “marquee” tag should not be used
- Menu” elements should not be used for formattin
- Noembed” elements must be the same content as their “embed” element
- All “noframes” elements should contain the text content from all frames
- When objects are disabled, content should still be available
- Objects do not flicker
- Objects must not use color to communicate alone
- Interfaces within objects must be accessible
- Objects which reference multimedia files should also provide a link to a transcript
- Objects must contain their text equivalents
- Every object should contain an “embed” element
- Objects should have a title attribute
- Objects must not have an empty title attribute
- All objects should provide a way for keyboard users to escape
- An object might require a long description
- The text equivalents of an object should update if the object changes
- Content within an “object” element should be usable with objects disabled
- Objects with “classid” attributes should change their text if the content of the object changes
- Paragraphs must not be used for headers
- All password input elements should have a corresponding label
- All “password” input elements have a label that is close
- Pre” elements should not be used for tabular data
- All “radio” input elements have a corresponding label
- All “radio” input elements have a label that is close
- All radio button groups are marked using fieldset and legend elements.
- Content on the page should still be available if scripts are disabled
- Scripts should have a corresponding “noscript” element
- If an element has an “onclick” attribute
- Any element with an “ondblclick” attribute shoul have a keyboard-related action as well
- If an element has a “mousedown” attribute
- Any element with an “onmousemove” attribute shoul have a keyboard-related action as well
- If an element has a “onmouseout” attribute
- If an element has an “onmouseover” attribute
- If an element has an “onmouseup” attribute
- The user interface for scripts should be accessible
- Scripts should not cause the screen to flicker
- The interface in scripts should not use color alone
- Select” elemetns must not contain an “onchange” attribute
- All select elements have an explicitly associated label.
- Select jump menus should jump on button press, not on state change
- Form select elements should use optgroups for long selections
- Websites must have a site map
- A “skip to content” link should exist as one of the first links on the page
- Inline SVG should use Title elements
- The tab order of a document is logical
- Captions should identify their table
- Complex tables should have a summary
- Data tables should contain “th” elements
- Table header lables must be terse
- Mark up the areas of tables using “thead
- Layout tables should not contain “th” elements
- All tables used for layout have no “caption” element
- All tables used for layout have no summary or an empty summary
- All tables used for layout should make sense when removed
- Table summaries should describe the navigation and structure of the table
- Table “summary” elements should not duplicate the “caption” element
- All data tables should have a summary
- All data tables should have an adequate summary
- Group columns using “colgroup” or “col” elements
- Table headers over 20 characters should provide an “abbr” attribute
- Data tables should contain a “caption” element if not described elsewhere
- Data tables should use scoped headers for rows with headers
- Data tables with multiple headers should use the “scope” attribute
- Complex data tables should provide “id” attributes to headers
- All tabular information should use a table
- The text size is not less than 9 pixels high
- All textareas should have a corresponding label
- All textareas should have a label that is close to it
- All video tags must provide captions
- All linked or embedded videos need captions