Two documentation pages say opposite things about @a11y. Which one should I believe?

Asked 28 Aug 20257,910 views2 answers

33votes

Not a bug report, a request for a ruling, because I have to tell a client which it is.

The guide describes a hook that runs an accessibility pass after each UI step, violations attached per step, an assertion step with an impact threshold, performance budgets per environment and gates on a process.

The workshop chapter says:

The tag taxonomy reserves @a11y and @perf, and the project schema accepts accessibility and performance gates on a process. Neither is implemented in the runner today — an @a11y scenario runs as an ordinary scenario, and a performance budget is not enforced.

Both pages are in the same documentation set, published together. One of them is wrong and I cannot tell from the outside which.

a11y perf

asked by Rasha Halabi572 · 28 Aug 2025

2 answers

47votes✓
Accepted answer
The workshop chapter is right. As of today, @a11y and @perf are schema-only: reserved in the tag taxonomy, accepted by the project schema, read by nothing at run time.
The accessibility and performance guide describes a design that was written before the code and never retracted when the code went a different way. The step library reference is wrong in the same direction — it lists two steps that are not in the catalogue, which you can confirm yourself with sdods steps list. Known limitations records the visual-baseline gap and not this one, which is a third instance of the same bug.
It is on the roadmap as a choice between implementing the checks and retracting the pages. I am not going to give you a date in a forum post; tell your client that the tags are reserved and the checks are not implemented, because that is the sentence that will still be true whichever way it goes.
answered by Reeta Nandalmaintainer41,280 · 28 Aug 2025
21votes
A habit worth having generally, not just here: when a claim in a guide matters, verify it against the catalogue rather than the prose.
bash
```
sdods steps list -p demo-shop
```
A step that is not in that output cannot run, whatever a table says. The same trick works for config: sdods config show --explain tells you a key resolved, which is a weaker statement than "something reads it", and this thread is exactly the gap between those two.
answered by Helle Borg352 · 29 Aug 2025

Have a different question? Ask it.

Two documentation pages say opposite things about @a11y. Which one should I believe?

2 answers

Know the answer?

Related