Part 7. Reading paths, mistakes, and what is open

Reading paths by role

Part 1 said which reader each part serves. This is the same advice as a working order, for someone who has to start today.

If you are a designer

Start with the five layers, because most scope disputes are really arguments about which layer a question belongs to. Then read the typography and colour profile (clause 23) if your organisation claims it, and the annotation rules (clause 19) whether it does or not.

The annotation rules matter more than they look. A mock-up cannot show what a component promises, which keys operate it, where focus goes when a dialog closes, or what happens at high zoom. Annotation is how you hand those decisions to a developer without relying on a conversation neither of you will remember.

Read clause 19's economy rule before you start annotating. Do not annotate what the visual design, the component API, or the coded component already guarantees.

If you are a developer

You will consume packages and you will produce them, and clause 4.2 says that a tool doing both must satisfy both sets of obligations independently.

Read Part II in full. It is where the obligations that affect daily work live: the seventeen fields a component specification carries (clause 7.2), the keyboard contract's eight stages (clause 10), the seven reflowBehaviour fields (clause 11.1), and the rule that a guarantee naming no assertion makes the package non-conforming (clause 14.2).

Then read Part IV, and read clause 31 twice. The verification algorithm is ordered, and a consumer that runs the steps out of order can accept a package it should have refused.

Clause 35.2 is the other one to get right. A consumer that meets a package whose major version is higher than it understands has one correct behaviour, and guessing is not it.

If you are a tester or QA engineer

The five testing levels (clause 18) tell you what a given piece of evidence is actually evidence for. Evidence gathered at one level does not support a claim at another, which is the point of recording the level at all.

Read clause 16 for what an evidence record must carry — all fourteen fields, including engine, browser, version, observed behaviour and test date. A claim that omits the engine is not a weaker claim; it is an unverifiable one.

Read clause 17 for uncertainty records. Recording that something has not been tested, with not-yet-tested, is a conforming and useful act. Leaving it out is not.

Then read the composition material in clause 18.1 to 18.3, and the companion document for the failure modes. A component can pass every test it has and still break when assembled, and finding that is your job rather than the component author's.

Common mistakes

These are drawn from the project's own decision record and from defects found in earlier drafts of this guide.

Treating the layout method as mandatory. It is one method profile among those Part III defines, and a package may claim none. Clause 4.3 calls an organisation satisfying the core while declining the layout method "the intended outcome, not a loophole".

Inferring one profile axis from the other. Completeness profiles say how much of the hierarchy is present; method profiles say which design method is followed; the WCAG level is a third thing again. Clause 4.5 requires them to be declared separately and prohibits inferring either from the other.

Claiming APG conformance. Clause 4.4 prohibits it outright, because the ARIA Authoring Practices Guide is informative and has no conformance model to conform to. What you can publish about a component is the accessibility criteria met, the semantics used, and the recorded assistive-technology results.

Listing guarantees without non-guarantees. Clause 2.5 gives the reason: a component that lists only what it promises invites the reader to assume the rest, and the assumption is where accessibility is lost.

Writing a guarantee that no assertion substantiates. Clause 14.2 makes a package containing one non-conforming. The guarantee is not the claim; the assertion is what makes the claim checkable.

Recording an assistive-technology result without the engine. Clause 16.2 requires engine, browser and version because behaviour differs between them, and a result that does not say what it was observed on cannot be reproduced or retired.

Reading a silence in the specification as permission. Clause 1.2 states what the specification does not define, and clause 1.4 says the omissions the project has not decided are named in the open-questions register. Clause 1.4 puts it directly: "A silence in a specification is not permission."

Presenting a conformance claim as evidence that a service is accessible. Clause 4.4 prohibits it, and clause 2.5 explains why: a design system supplies parts, and cannot know whether the parts were assembled into a task a user can complete.

Using the retired status names. pattern-derived and pattern-adjacent replaced the earlier APG-specific names, deliberately, so that the core does not name one external pattern library (clause 24.8).

Calling a navigation menu widget a misuse. Clause 24.5 sanctions it in the cases the APG allows, says it must not be called a misuse, and permits recording it as a product-deviation. An earlier draft of this guide listed it as a mistake, wrongly.

What this guide does not settle

The project keeps a register of open questions, and this guide does not resolve any of them. Where the specification is silent on something the project has not decided, clause 1.4 records that the silence is deliberate.

The register is docs/OPEN-QUESTIONS.md, organised in nine groups. The items most likely to affect a reader adopting the system now:

Three of these deserve a note for anyone reading the guide as an adoption plan.

A2 is the one that will cost you time. Clause 2.2 records the honest version: an organisation without a design system cannot adopt this method directly, because it must first identify its de facto components. The register has not settled how to do that.

C3 affects every contrast decision you record. Clause 23 sets Level AA as the default and the mechanism for declaring otherwise is settled, but the project has not decided whether to raise its own default. Record the level you are claiming rather than assuming the project's.

E6 affects how anyone reads your evidence. A matrix row records a combination someone thought worth considering, not a combination observed to work, and the specification does not yet say so. Until it does, a reader who skims the rows without reading the result field can take your matrix for a support table. The practical protection is the one the sample package uses: state in your own limitations prose what the results are and are not, and keep every result field populated from the clause 16.3 vocabulary rather than left blank.

Where the rest of the material lives

This guide is one document in a set, and the set has an order of authority.

docs/AFDS-SPECIFICATION.md is normative for all four Parts. Where this guide and the specification disagree, the specification wins and the disagreement is a defect in this guide.

docs/COLOPHON.md records the decisions and the arguments that produced them, including decisions that were rejected. docs/OPEN-QUESTIONS.md records what is unsettled. Clause 1.4 is explicit that neither is part of the specification: they record how the decisions were reached, not what conforms. Read them for why a requirement exists, not for whether it applies.

research/COMPONENT-FRAMEWORKS.md, Component Design Frameworks and the Assembly Problem, carries the assembly analysis this guide cross-references rather than restates: the assembly hierarchy, the eight compositional failure modes, worked composite breakdowns, state propagation, and testing across the hierarchy.

research/DESIGN-SYSTEMS.md and research/PORTABLE-REPRESENTATIONS.md carry the survey work behind clauses 2.3 and 2.4.

afds-sample/ is a working package that the worked example in this guide is taken from, and afds-sample/tools/build-inventory.py rebuilds its inventory.