Generating an accessibility statement without inventing the judgements
An accessibility statement has to say which criteria are not met, what a person actually runs into, what alternative is offered, which content is exempt from the requirements, and when a human last reviewed the text. A record of tests answers the first of those and nothing else. A generator that fills the remaining fields with plausible sentences hands you a document that reads as answered, which is a worse outcome than one that reads as unfinished.
We build the evidence layer under that document in a11ytrail, and statement() is where the limit of machine-readable evidence stops being an abstract concern. It fills in what the evidence settles and returns the rest as Pending entries, each one a question plus the reason the record cannot answer it.
The constraint: the record stops before the sentence does#
assess() turns recorded checks into a claim. For every criterion in claim.failed,describe() can build most of a statement entry out of the checks themselves:
export type NonAccessibleItem = {
readonly criterion: string;
readonly name: string;
readonly level: Level;
/** Scopes where a check recorded a failure. */
readonly failingScopes: readonly string[];
/** Scopes with no check for this criterion at all. */
readonly uncheckedScopes: readonly string[];
/** What a person runs into, taken from the notes on the failing checks. */
readonly reason?: string;
/** How to reach the same content or service another way. */
readonly alternative?: string;
};The first five fields are derivable. failingScopes comes from the checks whose outcome is failed, and uncheckedScopes comes from the criterion's unevaluatedScopes, so you can tell a page nobody opened from a page that failed. The last two fields are not derivable. reason exists only because somebody wrote a note while running the check:
const failing = result.checks.filter((check) => check.outcome === "failed");
const notes = [
...new Set(failing.flatMap((check) => (check.note?.trim() ? [check.note.trim()] : []))),
];Trimmed, de-duplicated, joined with a semicolon, and empty when nobody typed anything. alternative is read from organisation.alternatives by criterion id, so it comes from a decision about how the service operates, not from the audit at all.
"2.1.1 Keyboard is not satisfied on checkout" is a true statement about the evidence. "Users cannot operate the date picker with a keyboard" is a guess about the barrier. "A telephone line is available instead" is a guess about the organisation's operations, and it is the kind of guess a complainant reads back to your team. A criterion number does not describe what a person runs into, and expanding one into the other is the characteristic failure of statement generators.
Open judgements come back as data#
So we return each one, addressable:
/** Where in the statement a decision belongs. */
export type Section =
| "non-accessible-content"
| "disproportionate-burden"
| "out-of-scope"
| "preparation";
/** A part of the statement the evidence cannot settle. */
export type Pending = {
readonly id: string;
readonly section: Section;
/** What a person has to decide. */
readonly question: string;
/** Why the record cannot answer it. */
readonly because: string;
};statement() assembles pending from three sources: the per-item gaps, the exemption questions, and the preparation fields. Run the demo against a claim with one failing criterion and an organisation that has supplied only its contact details, and the output is a work list:
5 parts still need a human decision:
- Describe what a person runs into for 1.4.3 Contrast (Minimum).
- Name the accessible alternative for 1.4.3 Contrast (Minimum), or say there is none.
- State which content, if any, is exempt as a disproportionate burden.
- State which content, if any, falls outside the scope of the legislation.
- Give the date this statement was last reviewed.The id is what makes this a work list rather than decoration, so we pin the ids with tests instead of leaving them to the renderer:
test("a failure with no recorded reason is marked, not written for the organisation", () => {
const s = statement(assess(evidenceWith({}, ["2.1.1"]), { asOf }), decided, asOf);
assert.equal(s.nonAccessibleContent[0].reason, undefined);
assert.deepEqual(
s.pending.map((item) => item.id),
["reason:2.1.1", "alternative:2.1.1"],
);
const markdown = toMarkdown(s);
assert.ok(markdown.includes("Describe what a person runs into for 2.1.1 Keyboard."));
assert.ok(markdown.includes("Draft: 2 part(s) of this statement need a human decision"));
});reason:2.1.1 can go into a tracker, be assigned to whoever owns the checkout flow, and be closed when the sentence is written. A bold marker buried in a rendered document cannot be assigned to anyone.
The same rule has to hold for a field that was filled in with nothing. pendingForItem adds its reason entry when no failing check carried a note, and the trim in describe() decides whether a note counts:
test("a note that is only whitespace is not a description of a barrier", () => {
const evidence = fullPass();
evidence.add(
check({ criterion: "2.1.1", outcome: "failed", checkedAt: "2026-08-10", note: " " }),
);
const published = statement(assess(evidence, { asOf }), decided, asOf);
assert.equal(published.nonAccessibleContent[0].reason, undefined);
assert.deepEqual(
published.pending.map((decision) => decision.id),
["reason:2.1.1", "alternative:2.1.1"],
);
});One press of the space bar should not be able to close a judgement, and the symmetric case matters too: an alternative supplied for a criterion that holds is simply not published, because there is nothing for it to be an alternative to.
Empty is an answer; absent is a question#
Two fields on Organisation carry a distinction a boolean cannot hold:
/**
* Content exempted as a disproportionate burden, one entry per exemption. An
* empty array says the question was considered and nothing is claimed;
* leaving the field out says nobody has answered it yet.
*/
readonly disproportionateBurden?: readonly string[];
/** Content outside the scope of the legislation. Same empty-versus-absent rule. */
readonly outOfScope?: readonly string[];pendingForExemptions tests both against undefined, not against length. That is the whole mechanism, and it buys something specific: a team that has considered exemptions and claims none gets a clean statement, while a team that has not looked gets a question. Collapse the two states and you are choosing between leaving a permanent marker in the statement of every organisation that honestly claims nothing, and treating "not answered" as "nothing exempt", which is the comfortable option and the indefensible one.
The renderer carries the same three states. The exemptions helper prints the heading with the marker when the field is undefined, prints nothing at all for an empty array, and lists the entries otherwise:
test("a declared-empty exemption prints no heading; an unanswered one opens the section", () => {
const published = statement(
assess(fullPass(), { asOf }),
{ ...decided, disproportionateBurden: [], outOfScope: undefined },
asOf,
);
assert.deepEqual(
published.pending.map((decision) => decision.id),
["out-of-scope"],
);
const markdown = toMarkdown(published);
assert.ok(!markdown.includes("### Disproportionate burden"));
assert.ok(markdown.includes("### Content outside the scope of the legislation"));
});Look at what the second assertion means: every criterion passed, and the section still opens. An exemption nobody has answered is content the statement has to account for regardless of how the checks came out.
The marker goes where the answer belongs — unless something was handed over#
In the rendered draft,mark writes **[needs a human decision]** followed by the question and the reason the record cannot answer it, in the exact position the answer would occupy. toMarkdown opens with a draft banner counting the pending parts whenever the list is not empty. You cannot skim past the gap, and a reviewer cannot mistake the document for finished.
There is one deliberate exception, and it is the part of the module we would defend hardest. When a caller hands over a blank, we print the blank as given rather than replace it with a marker:
test("a blank review date stays pending, and the blank is printed as it was given", () => {
const published = statement(
assess(fullPass(), { asOf }),
{ ...decided, lastReviewedOn: " " },
asOf,
);
assert.deepEqual(
published.pending.map((decision) => decision.id),
["last-review"],
);
const markdown = toMarkdown(published);
assert.ok(markdown.includes("Last reviewed on: ."));
assert.ok(!markdown.includes("**[needs a human decision]** Give the date"));
assert.ok(markdown.includes("Draft: 1 part(s) of this statement need a human decision"));
});The judgement is open (last-review is in pending, and the banner counts it), but the document shows the caller what they actually passed in. Overwriting a submitted value with a marker would hide the fact that something upstream produced a space instead of a date, and that is a bug worth seeing rather than papering over. pendingForPreparation asks for assessmentMethod and lastReviewedOn when either is blank, and preparedOn comes from the Date the caller passes and does not stand in for the review date: a statement generated today is not a statement reviewed today.
The outer guard works in the same spirit. statement() throws UnsupportedClaim when the claim is incomplete, because there is no honest way to render "we have not finished looking" as one of "fully compliant","partially compliant" or "non-compliant", and a library that quietly picked the middle one would be helping someone publish a claim they cannot defend.
What it costs to run#
The optional fields are not free. Every one is a branch in the renderer and at least one test, and the three-state exemption fields need a test per state. The pending ids have to stay stable, because a tracker holds them. The draft banner only works if somebody reads it, which makes the handover to whoever owns the statement text a real step in delivery rather than a file drop.
What it buys you is that the handover is itself a list. Instead of "review the generated statement", the ask is five named decisions, each attached to the criterion and the scope that raised it, with the reason the evidence could not settle it. That is a review a non-engineer can complete.
The statement a team publishes then contains no sentence nobody chose to write. Where the evidence runs out, the document says so, in the place the answer belongs, and once the decisions are made the markers disappear because the questions were answered, not because they were overwritten.