Part 3. Conformance, claims, and the three axes

Conformance: what conforms, what a claim means, and the words behind it

This section serves all three readers, and it serves the tool author most of all. A designer needs it to know which of the project's design methods are optional. A developer needs it to know which obligations attach to writing a package and which to reading one. A tester needs it to know what a conformance claim does and does not entitle anyone to say.

Everything here comes from clause 4 (Conformance), clause 5 (Terms and definitions), clause 34 (Completeness profiles) and clause 35 (Versioning). Clause 4 and clause 5 are normative, and they are part of the core, so nothing in this section is declinable.

How to read a requirement, and why this guide never issues one

The specification marks its obligations with capitalised keywords from RFC 2119, and clause 4.1 fixes the force of each one. The right-hand column below quotes clause 4.1 directly.

Two consequences of clause 4.1 matter to a reader more than the table does.

The first is that the capitalisation carries the meaning on its own. The specification also marks keywords as emphasis, and says so plainly: the emphasis is "deliberately redundant", so a reader, a renderer or an assistive technology that conveys no emphasis loses nothing (clause 4.1). No requirement in the specification depends on colour, typographic weight, or emphasis being perceived. That is worth noticing early, because it is the specification applying its own subject matter to itself.

The second is that lower-case "must" and "should" in the specification carry no requirement at all. Clause 4.1 is explicit that a reader who meets one of the keywords in lower case reads it as ordinary prose, and it gives the reason: the informative clauses use those words in their ordinary English sense.

This guide is informative documentation, not specification. It therefore never issues a requirement in its own voice. Where an obligation exists, this guide reports it and cites the clause — "the specification requires that", or "a package that omits this does not conform (clause 34)" — so that you can always get from an instruction here to the normative text behind it. Capitalised keywords appear in this guide only inside quotations, and quotations are marked as quotations.

Who carries the obligations: producers and consumers

Clause 4.2 says two roles carry obligations, and defines both.

A producer is any tool or person that creates a package. A consumer is any tool or person that reads a package and relies on its contents.

The rule that matters if you are building tooling is the next sentence of clause 4.2: a single tool may be both, and when it is, the specification requires it to satisfy both sets of obligations independently. "Independently" is the operative word. Satisfying the producer obligations does not discharge any consumer obligation, and satisfying the consumer obligations does not discharge any producer obligation. A build tool that reads an upstream package of tokens and emits a package of its own is held to the reading rules for what it consumed and to the writing rules for what it produced, with no netting off between the two.

Clause 4.2 also settles the case that catches people out: an adapter is always both. An import adapter reads a non-AFDS representation and produces a package; an export adapter reads a package and produces something else. Either way it sits on both sides of the boundary, which is why Part IV gives adapters their own clause (clause 33).

Practically, if you are writing tooling, treat the two obligation sets as two separate checklists and satisfy each on its own terms. The most common way to get this wrong is to write a tool that verifies its own output carefully and reads its input trustingly.

What every package must satisfy, and what it may decline

This is the most important part of this section, and it is the part the previous edition of this guide got structurally wrong.

The specification has a core and a set of named method profiles (clause 4.3).

The core is clause 4, clause 5, Part II and Part IV. Every AFDS package has to satisfy the core; clause 4.3 states it without qualification. So the definitions, the conformance rules, the whole component contract, and the whole serialisation format apply to every package that calls itself an AFDS package.

A method profile is something different in kind. Clause 4.3 defines it as a named group of requirements carrying a specific way of building interfaces, and Part III defines the profiles themselves. Two rules govern them, and both are prohibitions:

• a package is not to be judged against a method profile it does not claim; and
• a consumer is not to treat the absence of a method-profile claim as a defect (clause 4.3).

Read those twice if you have used a design system that shipped its layout opinions as a condition of entry. They mean that declining a method profile is a legitimate position, not a partial adoption, and that a tool which flags an unclaimed profile as a shortfall is itself misbehaving.

Clause 4.3 gives the reason for the separation: the core describes how to carry an accessibility contract and its evidence, while a method profile describes one way of designing. Those are different problems, and the specification declines to make the second a price of the first.

The worked case. Consider an organisation whose brand palette is fixed, whose layout conventions are settled, and which has no appetite to change either. Perhaps the palette came out of a brand programme that will not be reopened for three years; perhaps the layout conventions are baked into a framework the organisation does not control.

That organisation can satisfy the core completely. Clause 4.3 spells out what it gets and what it does not:

"That organisation gets the contract, the evidence, the uncertainty records, and the portability, and it does not get the layout method. That is the intended outcome, not a loophole."

So the position is this. The organisation writes component specifications with their guarantees, non-guarantees and assertions; it records evidence against real assistive-technology combinations; it records what it does not know as uncertainty rather than leaving it to be assumed; it ships all of that in a package another tool can read. It declares an empty set of method profiles. It has not cut a corner, and no consumer is entitled to treat it as though it had.

The declinable things are the project's own design methods — the intrinsic layout method, the scoped reflow rule, the typography and colour scale, and the native-first pattern catalogue (clause 20.4). The non-declinable thing is the honesty machinery: the contract, the evidence, the uncertainty, the serialisation. If you take one sentence from this section, take that one.

Two supporting rules from Part III are worth knowing here, though the method profiles themselves belong to another section of this guide. A profile is not a level: the profiles are unordered, do not build on one another, and a package claiming none "is not deficient" (clause 20.1). And a package may adopt a profile's requirements without claiming the profile, which the specification expects to be common — but it may not then describe itself as claiming that profile (clause 20.3).

The three axes, and why they are separate

There are three separate statements a package makes about itself, and none of them may be derived from either of the others.

Clause 4.5 states the rule for two of them: completeness profiles (Part IV) state how much of a package hierarchy is present, method profiles (Part III) state which design method a package follows, these are independent axes, the specification requires them to be declared separately, and a consumer is not to infer either kind of profile from the other. Clause 4.5 makes the independence concrete in both directions: a package containing only tokens may claim a method profile, and a package containing components, evidence and fixtures may claim none.

Clause 34 adds the third axis and states the rule across all three: the completeness field "states completeness only", it is a different axis from the method-profile array and from the WCAG target level, and "None of the three may be inferred from either of the others: a package may be afds-full, claim no method, and target Level A."

The manifest field for completeness is named conformanceProfile, which is a historical name rather than a description. Clause 29.1 says so directly: the field name is retained from the first release of the format, and "the value it carries is a completeness profile and nothing else". This guide uses "completeness profile" for the concept throughout, and names the field only where the field is what you are writing.

Avoid the bare word "conformance" for any one of the three axes. The specification reserves conformance for a property of a package and its claim (clause 4.4), and using it loosely is how the previous edition of this guide came to imply that a package with no method claim was somehow less conformant than one with three.

The completeness profiles themselves

Clause 34 defines three, and the identifiers are exactly these.

Three rules govern them (clause 34).

A package has to satisfy every requirement of the profile it declares. A package may exceed its declared profile, so the specification requires a consumer to treat the declared profile as a floor rather than a description. And a consumer that needs a higher profile than the package declares has to refuse to treat the package as sufficient — even if inspection suggests the extra artefacts are there — because an undeclared artefact carries no commitment to remain present in the next version.

That third rule is the one that surprises people, and it is the right rule. Finding evidence records in a package that declares afds-tokens tells you what happened to be in this build, not what the producer has undertaken to keep shipping.

One provision of afds-full shows the project's attitude more clearly than anything else in Part IV. The profile requires evidence records but does not require that they contain results, and a record whose result is not-yet-tested conforms (clause 34). Clause 34 gives the reason: recording an untested combination is the mechanism by which uncertainty becomes visible, and a profile that demanded results would create pressure to invent them.

What a conformance claim consists of

A conformance claim has three required parts, and clause 4.4 names all three: the format version, the completeness profile, and the set of method profiles claimed, which may be empty.

An empty method-profile array is a complete claim, not an incomplete one. Clause 20.2 treats an omitted array and an empty array as having identical meaning.

Clause 4.4 then sets two prohibitions, and both exist because claims of the forbidden kinds were being made in the wild.

A claim cannot be a claim of conformance to something that has no conformance model. The specification forbids expressing a claim as conformance to an informative document, and forbids expressing it as conformance to a guide that has no conformance model. It names the case: a package is not to claim that a component conforms to the ARIA Authoring Practices Guide, "because that guide is informative and has no conformance model to conform to" (clause 4.4). This is not a slight on that guide. It is a statement about what kind of thing it is. An informative document explains how something is usually done; it does not define a testable set of obligations, so there is nothing there to conform to, and a claim of conformance to it would be unfalsifiable.

What you can publish about a component instead is stated in the same clause, and it is a short list of three:

• the accessibility criteria met;
• the semantics used; and
• the recorded assistive-technology results.

Each of those is checkable by someone who does not trust you, which is the point. The relationship between the project and that guide, and the vocabulary for recording that a component was derived from a published pattern, is treated elsewhere in this guide under clauses 9.2 and 24.

A claim about a package is not a claim about a service. Clause 4.4 states that a conformance claim is a claim about a package, not about a service built from it, and it puts the obligation on the producer: a producer is not to present a conformance claim as evidence that a service assembled from the package is accessible.

Note where that obligation sits. It is not merely advice to a cautious consumer to avoid over-reading a claim. It is a prohibition on the producer's marketing, procurement responses, and audit submissions. A package can be afds-full, claim every method profile, carry evidence for every component, and be assembled into a service that fails a real user at the first form, because the assembly is where most accessibility failures live. Clause 12.4 makes the parallel point about target levels: a declared level is a statement of intent and is not to be read as evidence that the level is met.

Version behaviour, and when a consumer must refuse

Two versions travel in every package and they move independently (clause 35).

afdsVersion is the version of the package format. packageVersion is the version of the design-system payload. Both use semantic versioning: major for incompatible change, minor for backwards-compatible addition, patch for a correction that changes no meaning (clause 35).

Separating them lets a consumer tell "the format changed" from "the design system changed", which are different problems for whoever has to react to them.

Format-version rules, if you produce packages

Clause 35.1 sorts changes to the format into three kinds. The left column reproduces the specification's wording, so the capitalised keywords in it are quoted from clause 35.1.

The line to remember is that adding a required field is a major change. A consumer written against the earlier version would fail on a package it ought to have been able to read, so the format cannot pretend the addition was compatible.

Consumer behaviour on an unexpected format version

Clause 35.2 gives a table of six situations and the required behaviour in each. This is the part a consumer most often gets wrong, and getting it wrong is dangerous precisely because it fails silently: a partial read of a package whose semantics you do not know produces plausible output and a misread accessibility contract. The table is reproduced faithfully below; the capitalised keywords are the specification's own.

Four things in that table are easy to implement wrongly.

An unknown minor version is not an error. The consumer processes the package and drops the fields it does not recognise, rather than refusing.

An older minor version is not an error either, and the consumer may not demand a field that did not exist when the package was written. A tool that requires a field introduced in a later minor version is rejecting conforming packages.

A higher major version is a refusal, and specifically a refusal without a partial read. Reading "as much as you can" of a package written to a format you do not know is the failure mode this row exists to prevent.

A lower major version is a choice, but a declared one. Refusing is permitted and a documented compatibility mode is permitted; what is not permitted is doing either quietly.

Clause 35.2 explains why the two major-version cases are treated differently. A higher major may rely on semantics the consumer cannot know about, so guessing risks a silent misreading of an accessibility contract. A lower major is fully knowable, so a compatibility mode is safe as long as it is declared.

These rules are not optional extras at the edge of a verifier. Clause 31 places them inside the verification algorithm: reading afdsVersion and applying the clause 35 rules is a step of verifying a package, not a courtesy afterwards.

Payload-version rules, if you publish a design system

packageVersion changes when the design system changes (clause 35.3).

Clause 35.3 then settles the two cases that decide whether this scheme is honest.

Withdrawing an assistive-technology guarantee is a major payload change even when nothing else moves, because a consumer may have relied on it. Someone downstream shipped a service on the strength of that guarantee, and the version number is the only signal they get.

Adding an evidence record that turns a recorded uncertainty into a guarantee is a minor change, because nothing that was relied upon has been taken away.

Those two rules together are the versioning scheme's whole ethic: taking a promise away is a breaking change, and learning something new is not.

Terms you need before going further

Clause 5 is normative, and it says how to read itself: where a term defined there is used in a normative clause, "it carries this meaning and no other". It defines thirty-eight terms. All thirty-eight are set out in the glossary at the end of this guide, in the specification's own words or a close paraphrase.

Two of them carry more weight than the rest and are worth having before you read any further.

Accessibility Focused Design System (AFDS). "A design system whose accessibility contract, supporting evidence, and recorded uncertainty are first-class parts of the system rather than documentation about it."

The distinguishing move is not that the components are accessible. It is that the contract, the evidence and the uncertainty are parts of the system — versioned, addressable, shipped — rather than prose written about the system afterwards and left behind when the system travels.

AFDS package. A single file conforming to Part IV, containing a declared hierarchy of artefacts and the two required root artefacts (clause 5).

Where to go next

• The method profiles themselves, and what claiming one commits you to: clauses 20 to 24.
• What goes into a component contract, its guarantees, non-guarantees, assertions, evidence and uncertainty: Part II, clauses 7 to 19.
• The package hierarchy, the manifest and inventory fields, artefact roles, and the verification algorithm: Part IV, clauses 25 to 33.