Appendix A. Glossary
AFDS user guide
The thirty-eight terms clause 5 defines, which carry these meanings and no other wherever a normative clause uses them.
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". Clause 5 defines thirty-eight terms. All thirty-eight are below, in the specification's own words or a close paraphrase.
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."
That sentence is the whole project in one line. 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.
The rest, in the order clause 5 gives them.
| Term | Definition (clause 5) |
|---|---|
| Container | The archive format that carries a package. |
| Artefact | Any addressable file inside a package. |
| Manifest | The root artefact declaring the package's identity, versions, profiles, and the location of the inventory. |
| Inventory | The root artefact listing the package's artefacts with their roles and digests. |
| Producer | Any tool or person that creates a package. |
| Consumer | Any tool or person that reads a package and relies on its contents. |
| Core | The clauses every package must satisfy, being clause 4, clause 5, Part II, and Part IV. |
| Method profile | A named group of requirements in Part III carrying one way of designing interfaces, binding only on a package that claims it. |
| Completeness profile | A named group of requirements in Part IV stating how much of a package hierarchy is present. |
| Conformance claim | A statement naming a format version, a completeness profile, and a set of method profiles. |
| Principle | A commitment that applies across the system and is not negotiable for an individual screen. |
| Token | A named, platform-neutral value. |
| Canonical token source | The token file a package declares as authoritative for a given token set, against which any other representation of the same values is derivative. |
| Layout primitive | A composable arrangement rule that positions content without knowing what the content means. |
| Component | An interactive element with declared semantics and behaviour. |
| Pattern | Several components co-operating through a task, together with the guidance governing that co-operation. |
| Component contract | The whole set of commitments a component makes about itself: what it guarantees, what it does not guarantee, and the assertions that make those statements checkable. Part II defines it, and it is carried by a component specification rather than being a separate artefact. |
| Component specification | The machine-readable record carrying a component contract, whose form and required fields clause 7 defines. A JSON document, and the authoritative source of every fact it carries. |
| Component documentation | The human-readable counterpart to a component specification, carrying the reasoning the specification's fields cannot express. Explanatory, introducing no fact of its own. |
| Guarantee | A statement of behaviour or property that a component commits to, expressed so that it can be tested. |
| Non-guarantee | An explicit statement of something a component does not commit to, recorded so that a consumer cannot arrive at it by assumption. |
| Assertion | A machine-checkable statement attached to a specification, whose truth can be evaluated against an implementation without human judgement. |
| Evidence record | A record of an observed result for one component in one assistive-technology combination, qualified by engine, browser, versions, observed behaviour, and date. |
| Assistive-technology combination | A named tuple of assistive technology, browser, operating system, and versions, treated as the unit that evidence attaches to. |
| Uncertainty record | A record stating that something is not known, of the same standing as a record stating a result. |
| Keyboard contract | The declared operation of a component across entry, internal movement, activation, exit, state change, restoration, pointer and touch parity, and speech-recognition operation. |
| Native baseline | The behaviour and semantics a component would have if built from platform-native elements without added roles or scripted behaviour. |
| Support-dependent pattern | A pattern whose declared behaviour is known to depend on assistive-technology or engine support that is incomplete, and which therefore carries a reassessment obligation. |
| Adapter | A tool that converts between an AFDS package and some other representation. |
| Export adapter | An adapter producing a non-AFDS representation from a package. |
| Import adapter | An adapter producing a package, or part of one, from a non-AFDS representation. |
| Transform report | The record an adapter produces stating what it carried, what it could not carry, and what a consumer must therefore not assume. |
| Measure | The length of a line of text, treated as a constraint on layout rather than as a stylistic preference. |
| User technology support | The branch of accessibility concerned with assistive-technology compatibility: roles, accessible names, states, focus, and keyboard operation. |
| User layout support | The branch of accessibility concerned with reflow, measure, spacing, contrast, and reading order. |
| Composition conformance | Conformance measured with a component placed inside a realistic page, as distinct from conformance measured with the component in isolation. |
Four of these terms are worth pausing on now, because later sections rely on them and a reader who skims the table will not have absorbed them.
Uncertainty record is defined as being "of the same standing as a record stating a result". That standing is deliberate, and clause 17 depends on it.
Non-guarantee exists because of an asymmetry in how people read documentation: a component that lists only what it promises invites a reader to assume the rest. Clause 14 makes the refusals explicit for that reason.
Native baseline is a disclosure, not a design preference: it names what the component would have done if built from platform-native elements without added roles or scripted behaviour, so that the cost of not doing so can be seen (clauses 5, 8.3).
Composition conformance is a different measurement from component conformance, not a stronger one. It is conformance measured with the component inside a realistic page.
A note on "component specification"
This phrase used to mean two different things in the specification, and if you have read an earlier edition of either document you will have met the collision.
Clause 5 defined a component specification as the human-readable counterpart to a component contract, while clause 7.1 defined it as the machine-readable JSON record — and clause 7.5 compounded it by requiring that "every component specification SHOULD have a human-readable counterpart", which under clause 5's definition asked every prose document to have a prose document.
That is settled, and the three terms now name three different things (clause 5).
| Term | What it names |
|---|---|
| Component contract | The whole set of commitments a component makes about itself. Part II defines it. It is not a separate artefact. |
| Component specification | The machine-readable JSON record that carries the contract. Clause 7 fixes its form and its seventeen required fields. |
| Component documentation | The prose counterpart to a specification, carrying the reasoning the JSON cannot express. Clause 7.5 recommends it. |
The resolution followed usage rather than the glossary: the manifest already pairs a specification path with a documentation path, the filename convention is .spec.json, and clause 28.1 already had a documentation artefact role.
The project's reasoning, and what it cost, are recorded in docs/COLOPHON.md.
One consequence is worth carrying with you. Because the contract is the commitments rather than the file, a clause that speaks of placing or reading a component contract is speaking of the specification that carries it, and both readings are true.