github / github/annotation-toolkit
[Feature request] Add `aria-disabled` guidance to form element annotations
- Dominant language
- No language data
- Stars
- 320
- Forks
- 33
- Avg merge
- 36m
- Merged PRs (30d)
- 2
Description
### Description
When annotating form elements that should be non-interactive, the toolkit currently offers a `disabled` toggle. In practice, using the native `disabled` attribute removes the element from the accessibility tree, making it undiscoverable to assistive technology users. The preferred approach in most cases is to use `aria-disabled="true"` instead, which keeps the element discoverable while preventing interaction.
### Requested change
When the disabled state is toggled on for a form element annotation, the annotation should communicate that `aria-disabled` is the recommended approach. This could look like:
- Replacing the simple "disabled: true" label with guidance text, such as: "This field should use `aria-disabled` to maintain accessibility and discoverability"
- Adding a flyout tip (similar to how Primer A11y Presets work) that appears when the toggle is enabled, explaining the rationale
### Why
Using `aria-disabled` instead of `disabled` is a widely recommended practice. By surfacing this guidance directly in the annotation, we can help designers communicate the right implementation to developers without requiring specialized accessibility knowledge.
### References
- [Make disabled buttons accessible](https://advancedbytez.com/make-disabled-buttons-accessible/)
Contributor guide
Research direction
Start with the form element annotation entry point and inspect how the disabled toggle is represented, then compare it with the existing Primer A11y Presets flyout behavior. Done means that enabling the toggle communicates the aria-disabled recommendation and rationale in the annotation, with the final presentation approach agreed and verified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- figma
- Domain
- accessibility, design
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100