Reading success criteria like an auditor

The same grey, #888888 on white, passes WCAG’s contrast criterion as 24 px text and fails it as 18 px bold text. The colour never changes: the verdict turns on how WCAG’s glossary defines large-scale text, and many disputes between auditors come down to a definition, a condition or an exception that one of them skipped.

You will be able to apply WCAG’s defined terms, read a criterion’s conditions and exceptions as logic, use not applicable correctly, find the techniques and documented failures for a criterion, and write a verdict that quotes the criterion and survives a second opinion.

The glossary decides what a criterion means

1.4.3 Contrast (Minimum) asks for “a contrast ratio of at least 4.5:1”, except that large-scale text needs 3:1, and text that is incidental or part of a logo has no requirement (Understanding 1.4.3). Three of those words are defined in WCAG’s glossary, and the definitions are part of the requirement. A contrast ratioWCAG's measure of the difference in brightness between two colours, from 1:1 for the same colour to 21:1 for black on white, worked out from their relative luminance with the formula in WCAG's glossary. comes from a formula, and large-scale textlarge-scale text: In WCAG, text of at least 18 point, or at least 14 point if bold: 24 CSS px and about 18.67 CSS px bold, since CSS sets 1pt at 4/3 px. It needs a contrast ratio of 3:1 under 1.4.3 instead of 4.5:1. means at least 18 point, or 14 point bold. The program works out eight verdicts from those definitions alone:

// Verdicts for 1.4.3 Contrast (Minimum), worked from WCAG 2.2's own definitions: relative
// luminance and contrast ratio from the glossary, "large scale" text as at least 18 point, or
// 14 point bold, and the criterion's exceptions for incidental text and logotypes. CSS defines
// 1pt as 4/3 px, so 18pt is 24 px and 14pt is 18.67 px. Ratios are compared without rounding.

function channel(hex) {
  const c = parseInt(hex, 16) / 255;
  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
}
function luminance(colour) {
  const [r, g, b] = [1, 3, 5].map((i) => channel(colour.slice(i, i + 2)));
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
function contrast(a, b) {
  const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
  return (light + 0.05) / (dark + 0.05);
}

const cases = [
  { text: 'Price, 16 px', fg: '#888888', bg: '#ffffff', px: 16, bold: false },
  { text: 'Heading, 24 px', fg: '#888888', bg: '#ffffff', px: 24, bold: false },
  { text: 'Label, 18 px bold', fg: '#888888', bg: '#ffffff', px: 18, bold: true },
  { text: 'Label, 19 px bold', fg: '#888888', bg: '#ffffff', px: 19, bold: true },
  { text: 'Body, 16 px', fg: '#767676', bg: '#ffffff', px: 16, bold: false },
  { text: 'Body, 16 px', fg: '#777777', bg: '#ffffff', px: 16, bold: false },
  { text: 'Disabled button', fg: '#aaaaaa', bg: '#ffffff', px: 16, bold: false, inactive: true },
  { text: 'Logo wordmark', fg: '#cccccc', bg: '#ffffff', px: 32, bold: true, logo: true },
];

console.log('Text               Colour    Ratio   Large  Needs  Verdict');
for (const c of cases) {
  const ratio = contrast(c.fg, c.bg);
  const pt = c.px * 0.75;
  const large = pt >= 18 || (c.bold && pt >= 14);
  const needs = large ? 3 : 4.5;
  let verdict;
  if (c.inactive) verdict = 'pass: inactive control, no requirement';
  else if (c.logo) verdict = 'pass: logotype, no requirement';
  else verdict = ratio >= needs ? 'pass' : 'fail';
  const shown = `${ratio.toFixed(3)}:1`;
  console.log(`${c.text.padEnd(19)}${c.fg.padEnd(10)}${shown.padEnd(8)}${(large ? 'yes' : 'no').padEnd(7)}${`${needs}:1`.padEnd(7)}${verdict}`);
}

Text               Colour    Ratio   Large  Needs  Verdict
Price, 16 px       #888888   3.545:1 no     4.5:1  fail
Heading, 24 px     #888888   3.545:1 yes    3:1    pass
Label, 18 px bold  #888888   3.545:1 no     4.5:1  fail
Label, 19 px bold  #888888   3.545:1 yes    3:1    pass
Body, 16 px        #767676   4.542:1 no     4.5:1  pass
Body, 16 px        #777777   4.478:1 no     4.5:1  fail
Disabled button    #aaaaaa   2.323:1 no     4.5:1  pass: inactive control, no requirement
Logo wordmark      #cccccc   1.606:1 yes    3:1    pass: logotype, no requirement

The first four rows are the same grey at 3.545:1. At 16 px it fails, at 24 px it passes, because 24 px is 18 point. At 18 px bold it fails, because 18 px is only 13.5 point, and at 19 px bold it passes. The next two rows show why auditors never round: #767676 gives 4.542:1 and passes, #777777 gives 4.478:1 and fails, and the Understanding page is explicit that “4.499:1 would not meet the 4.5:1 threshold”. The last two pass by exception, not by contrast.

Contrast is the easy case, because its definitions are numbers. Other defined terms decide verdicts in the same way:

Conditions and exceptions read as logic

Success criteria are written in a small number of patterns, and each pattern is a piece of logic. “For each” scopes the test: every instance is judged on its own. “At least one of the following is true” is an OR across a list. A list item with several parts joined by “and” is an AND: every part must hold. “Except” names cases where the criterion asks nothing. Numbers are thresholds, compared exactly.

2.2.1 Timing Adjustable uses almost all of them. For each time limit that the content sets, at least one of six options must be true: the user can turn the limit off; adjust it beforehand to at least ten times the default; or extend it after a warning, with at least 20 seconds to act, by a simple action, at least ten times. Three exceptions follow: a limit that is a required part of a real-time event, a limit that is essential, and a limit longer than 20 hours (Understanding 2.2.1). Read it option by option on two time limits:

The bank failed on one word of the extend option, “ten”, although it had a warning, a simple action and more than 20 seconds. A quick reading that stops at “there is a warning and a button” passes the session, and the auditor who reads the whole option fails it. The seat hold passed through an exception that the Understanding page itself uses as its example, “two minutes to confirm a purchase”, after which the seats go back on sale.

Not applicable means satisfied, and the report says why

A page with no video still has a verdict for 1.2.2 Captions (Prerecorded). WCAG’s definition says a page satisfies a criterion when the criterion “does not evaluate to ‘false’” on it, and the Understanding page on conformance spells out the consequence: when no content on the page is of the kind a criterion covers, that criterion “is satisfied” (Understanding Conformance). For the conformance decision, then, not applicable counts as a pass.

Reports still keep the two apart, because a reader needs to know what was there to test. W3C’s evaluation methodology, WCAG-EM, lets a report mark such criteria as not present (WCAG-EM 2.0), and conformance reports commonly say not applicable. Either way, the line names the reason:

Not applicable is a finding about the page, so it needs the same care as a fail. Mark a criterion not applicable only after looking for its content: a page whose video loads only after a click on Play still has a video.

Techniques show ways to pass; failures show ways to fail

Every Understanding page lists its techniques near its end, and W3C’s quick reference, How to Meet WCAG, lists the same techniques for every criterion with filters by level and technology. Each technique has an identifier whose prefix says what it is about: G for general, H for HTML, C for CSS, ARIA, SCR for client-side script, SVR for server-side script, SM for SMIL, T for plain text, PDF, and F for the common failures (Techniques for WCAG 2.2). For the two criteria of this lesson:

The kinds carry different weight. A sufficient technique done correctly is good evidence of a pass, and content may still pass in ways no technique describes. Advisory techniques improve accessibility without counting as sufficient. A documented failure is the strongest evidence of all, because content that matches one does not meet the criterion, so an auditor checks the failures first (Understanding Techniques).

A verdict quotes the criterion and the evidence

A verdict that only says “fail” invites an argument. A defensible verdict is two sentences: the first gives the result, the criterion and the instance; the second gives the evidence and the words of the criterion that decide. A developer can then fix it, and another auditor can check it without asking you anything.

Each defensible verdict names one instance, gives measurements or behaviour anyone can repeat, and quotes only the words that decide, briefly. That last habit matters most in disputes: when two auditors disagree, the quoted words show which condition or exception one of them missed.

Practise: reach a verdict on 2.2.1 in code

The exercise asks you to write 2.2.1 as code: the six options in the criterion’s order, the extend option with all four of its parts, and not applicable for limits the content does not set. Its sample tests include the bank’s session and the seat hold:

/** The verdict on 2.2.1 Timing Adjustable for one time limit. */
export function timingVerdict(limit) {
  if (!limit.setByContent) return 'not-applicable';
  if (limit.canTurnOff) return 'pass:turn-off';
  // Check the other five options here, in the criterion's order.
  return 'fail';
}

import { test, assert } from 'mysmartcopilot:test';
import { timingVerdict } from './timing.mjs';

// A time limit with every option false; each test switches on what it needs.
const limit = (extra = {}) => ({
  setByContent: true, canTurnOff: false, adjustUpTo: 1, warnSeconds: null, simpleAction: false,
  extensions: 0, realTime: false, essential: false, hours: 0.25, ...extra,
});

test("the lesson's bank session, one extension after a 30 second warning, fails", () => {
  assert.equal(timingVerdict(limit({ hours: 10 / 60, warnSeconds: 30, simpleAction: true, extensions: 1 })), 'fail');
});

test('the same session with ten extensions passes by the extend option', () => {
  assert.equal(timingVerdict(limit({ warnSeconds: 30, simpleAction: true, extensions: 10 })), 'pass:extend');
});

test('extend needs all four parts: 20 seconds, a simple action and ten extensions after a warning', () => {
  assert.equal(timingVerdict(limit({ warnSeconds: 19, simpleAction: true, extensions: 10 })), 'fail');
  assert.equal(timingVerdict(limit({ warnSeconds: 20, simpleAction: false, extensions: 10 })), 'fail');
  assert.equal(timingVerdict(limit({ warnSeconds: null, simpleAction: true, extensions: 10 })), 'fail');
  assert.equal(timingVerdict(limit({ warnSeconds: 20, simpleAction: true, extensions: 10 })), 'pass:extend');
});

test('adjusting to ten times the default passes, nine times does not', () => {
  assert.equal(timingVerdict(limit({ adjustUpTo: 10 })), 'pass:adjust');
  assert.equal(timingVerdict(limit({ adjustUpTo: 9 })), 'fail');
});

test('the seat hold passes by the essential exception, an auction by the real-time one', () => {
  assert.equal(timingVerdict(limit({ hours: 2 / 60, essential: true })), 'pass:essential');
  assert.equal(timingVerdict(limit({ realTime: true })), 'pass:real-time');
});

test('the 20 hour exception needs more than 20 hours', () => {
  assert.equal(timingVerdict(limit({ hours: 24 })), 'pass:20-hour');
  assert.equal(timingVerdict(limit({ hours: 20 })), 'fail');
});

test('the first true option in the criterion order is the one reported', () => {
  assert.equal(timingVerdict(limit({ canTurnOff: true, essential: true })), 'pass:turn-off');
  assert.equal(timingVerdict(limit({ adjustUpTo: 20, realTime: true })), 'pass:adjust');
});

test('a limit the content does not set is not applicable', () => {
  assert.equal(timingVerdict(limit({ setByContent: false })), 'not-applicable');
});

Then test your reading of all five ideas, from the glossary to the verdict; the questions follow your answers:

Interview questions

Fresher · What does “programmatically determined” mean in WCAG, and why does it matter?

It means software can work the information out from what the author provided, so that browsers and assistive technology can present it in other ways, such as speech or braille. WCAG uses it in criteria such as 1.3.1 Info and Relationships: a heading must be marked up as a heading, not just made big and bold, because a screen reader cannot tell that bold text is a heading, and so it cannot list it or let a user jump to it. In short, what is shown visually must also be in the markup, where software can read it.

Two harder questions of this module start from this lesson:

Key takeaways

• WCAG’s glossary is part of the requirement: large-scale text, contrast ratio, CSS pixel and the other defined terms decide verdicts, and thresholds are compared without rounding.
• Read each criterion as logic, “for each”, OR, AND and “except”, and look for the exceptions before failing anything.
• A criterion with nothing to judge on a page is satisfied; reports still say not applicable, with the reason.
• Sufficient techniques show ways to pass and documented failures ways to fail; failures are the first thing to check.
• A defensible verdict is two sentences: the result, the criterion and the instance, then the evidence with the criterion’s deciding words.