Accessibility Use Case Definition Language (UCDL) and Runner

Document version:

1.0.0

Document date:

2026-10-04

Editors:

AFixt Engineering

This version:

https://ucdl.org/spec/ (this document)

Companion document:

spec.md (architectural design notes — informative)

Reference implementation:

@afixt/usecase-runner

This is the formal specification for the Accessibility Use Case Definition Language (UCDL) and the conformance requirements for processors that consume it. The document is intended to be read in the style of a W3C Recommendation: sections marked normative define requirements, sections marked informative provide context, examples, and rationale.

This document is published by AFixt as the authoritative description of the file format, the step language, the processing model, the execution modes, and the reporting format implemented by the @afixt/usecase-runner reference implementation. It supersedes any conflicting prose in spec.md, Use-case-description.md, README.md, or TUTORIAL.md. Where those documents and this specification disagree, this specification wins.

The language is versioned independently of the reference implementation. This document defines UCDL 1.0. A processor states which language version it implements, and a document MAY declare the version it is written to with a top-level ucdl field (§2.4). Package versions of @afixt/usecase-runner move on their own schedule and do not imply a language release.

Copyright © 2026 AFixt. This document is available under the W3C Document License. The code examples in it — use case documents, step lists, and other snippets — are additionally available under the MIT License, so they can be copied into a project without carrying the document licence's terms with them.

This specification defines:

1. A YAML-based document format ("use case document") for describing accessibility test cases in terms of user-visible roles, accessible names, and intent-bearing actions.
2. A small, keyword-driven domain-specific language ("Step Language") for expressing the steps of a use case in a way that is readable by non-developers and that maps unambiguously to accessibility-aware browser automation.
3. A processing model that takes one or more use case documents and produces either (a) standalone Playwright .spec.ts files or (b) live execution results, together with a structured report.
4. A reporting model and scoring rubric that align with AFixt's manual use case testing methodology so that automated and manual results can be compared and aggregated.

The design centers a single principle: all element targeting goes through the accessibility tree. CSS selectors and XPath are not part of the authoring surface. If an element cannot be identified by its role and accessible name, that is reported as a finding, not worked around. Two narrow escape hatches, id and data-* (§5.4.2), exist for the cases where a test must reach the element a finding is about; they are discouraged, their use SHOULD be flagged in reports (§5.4.2), and a step that uses one establishes nothing about the element's exposure to assistive technology.

1. Introduction
2. Conformance
3. Terminology
4. Use Case Document Format
5. Step Language
6. Target Resolution Model
7. Processing Model
8. Execution Modes
9. Audit Steps
   • 9A. Contrast and Language Verbs
10. Reporting
11. Scoring
12. Configuration
13. Programmatic API
14. Command-Line Interface
15. Accessibility-First Design
16. Security and Privacy Considerations
17. Appendix A. ABNF Grammar for Steps
18. Appendix B. Use Case Document Schema
19. Appendix C. Examples
20. Appendix D. Glossary
21. Appendix E. References
22. Appendix F. Acknowledgments