Part 1. Before you start

Who this guide is for

This guide is written for three readers at once, and it assumes none of them has worked with a design system, with design tokens, or with WCAG before.

A designer decides what an interface looks like and how it behaves. A developer builds it. A tester or QA engineer decides whether what was built is acceptable.

The specification names its own audiences slightly differently, and it is worth seeing both lists side by side, because the mapping tells you which parts of the specification you will actually need. Clause 1.3 names three audiences and what each needs from the document.

So the three readers this guide addresses are not a fourth and fifth audience added to clause 1.3's list. They are the same three people, described by the job they do rather than by the part of the document they consult.

Beyond that mapping, here is where each reader will find most of what they need.

A designer needs the design-system layers and the placing exercise below, the token and branding material, the layout method, and the annotation rules that record what a mock-up cannot show.

A developer needs the layout primitives, the component contract and its required fields, the keyboard and focus material, and the whole of the package format, because that is what a build consumes and verifies.

A tester or QA engineer needs the assertions, the testing levels, the assistive-technology evidence records, and the requirement to test inside a realistic page rather than in isolation.

You do not need to read this guide in order.

Its ordering is not the specification's ordering. The specification is organised as an argument that ends in a serialisation format: purpose, model, conformance, the component contract, the method profiles, then the package (front matter, Organisation). This guide is organised around tasks, so a section that draws on clause 7 may sit next to one that draws on clause 29. Each section states the problem it addresses before it explains the mechanism, and each section that carries an obligation names the clause behind it, so you can enter anywhere and follow the citation outward.

How to read this guide alongside the specification

Keep docs/AFDS-SPECIFICATION.md open while you read. This guide is documentation and carries no requirement of its own. Where the guide and the specification disagree, the specification wins and the disagreement is a defect in the guide.

Clause numbers are the citation mechanism

Every instruction in this guide that rests on a requirement cites the clause it rests on, inline, in the form (clause 7.2). That is possible because clause numbers are global and permanent within a version of the specification: clause 23 is clause 23 wherever it is rendered, so a citation never has to name a part or a page, and when the specification is published as web pages each clause carries a stable anchor derived from its number (front matter, Organisation). If a sentence here tells you to do something and does not cite a clause, treat it as advice rather than as an obligation.

The specification is one document in four parts. Part I, clauses 1 to 6, states what an AFDS is, why it exists, the model it assumes, how conformance works, and the terms and references the rest depends on. Part II defines the component contract. Part III defines the method profiles, which carry this project's own choices about layout, reflow, colour, typography, and the component catalogue. Part IV defines serialisation: the container, the two root artefacts, the verification algorithm, security requirements, adapters, profiles, and versioning.

Not all of it binds equally. Clause 4, clause 5, and Parts II and IV are normative. Part III is normative only for a package that claims the relevant method profile, and has no force over a package that does not. Clause 1, clause 2, clause 3, clause 6.2, and the annexes are informative: they explain why the normative clauses say what they say, they create no requirement, and a package cannot fail to conform by disagreeing with them (front matter, Normative and informative material). Most of this section of the guide draws on those informative clauses, which is why it argues rather than instructs.

What the capitalised keywords mean, and what the lower-case ones do not

The specification uses MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL as defined in RFC 2119 (clause 4.1). Capitalised, they carry force: an absolute requirement, an absolute prohibition, a strong expectation whose departure needs a stated reason, or a genuine option that a consumer may not assume is present.

Two things follow for a reader of this guide.

The first is that clause 4.1 says a reader who encounters one of those words in lower case must read it as ordinary prose carrying no requirement. This matters, because the informative clauses — clause 2 and clause 3 among them — use "must" and "should" in their ordinary English sense. A lower-case "must" in clause 2 is a sentence about how design work tends to go, not a rule you can fail.

The second is that this guide never issues a requirement in its own voice. It writes "the specification requires that", or "a package that omits this does not conform", and it names the clause. Where it quotes a capitalised keyword it marks the quotation as a quotation. The capitalisation is the signal that carries the force; clause 4.1 also marks keywords as emphasis, and says the emphasis is deliberately redundant, so that a reader or an assistive technology conveying no emphasis loses nothing.

The reference for a term is clause 5

This guide explains a term before relying on it, but the authoritative wording for every defined term, including Accessibility Focused Design System itself, is clause 5, and where a term defined there is used in a normative clause it carries that meaning and no other.

The project's other documents are history, not authority

The project's research notes, its colophon of decisions, and its register of open questions are not part of the specification (clause 1.4). They record how the decisions were reached, which were rejected, and what remains unsettled. When you want to know why a requirement exists, the argument is in clause 2 and the decision record is in the colophon; when the two are read against each other, the specification governs. Where the specification is silent on something the project has not decided, clause 1.4 says the silence is deliberate and the open-questions register names it, and that a silence in a specification is not permission.

One further piece of status, because it changes how much weight the identifiers here can carry. AFDS 1.0.0 is a project draft. It is not a W3C standard, not a published industry specification, and not on any standards track, and every identifier and field name it defines is stable within this project and unstable outside it (front matter, Status of this document).

What the specification defines, and what it leaves to others (clauses 1.1, 1.2)

The specification opens with a single sentence of purpose worth keeping in view through everything that follows: an AFDS exists so that an accessibility decision, its reasoning, and the evidence for it can be made once and then travel, instead of being rediscovered on every screen that needs it (front matter).

Clause 1.1 lists nine things the specification defines.

1. The layers a design system is composed of, and what belongs in each.
2. What a component declares about itself, including what it refuses to promise.
3. The record types that carry evidence, uncertainty, and machine-checkable assertions.
4. The keyboard contract model, and the sense in which keyboard operation is not only about keyboards.
5. The levels at which conformance is tested, and the difference between a component conforming and a composition conforming.
6. A set of named method profiles carrying a layout method, a reflow policy, a colour and typography policy, and an approved component catalogue.
7. A container and package hierarchy for carrying all of the above between organisations, with a verification algorithm and security requirements.
8. Adapter obligations in both directions, and the report an adapter must produce.
9. Versioning behaviour for the format and for the payload.

Clause 1.2 is as explicit about the other side. It makes five statements of exclusion, naming twelve things between them.

The third and fourth rows are the ones that surprise people, and the fourth is worth restating on its own, because it decides what you are allowed to ship. A conforming package may contain an implementation, and may contain none. A package of tokens, contracts, evidence, and no code at all can conform. So can one that carries a working component library. The format is indifferent to the choice, and the exclusion of the third row's items — signature format, registry, update protocol, editing tool — means an organisation adopting AFDS is expected to bring its own distribution and tooling arrangements.