github / github/annotation-toolkit

[Feature request] Add `aria-disabled` guidance to form element annotations

Open
#32 0 comments 0 reactions 0 assignees View on GitHub
backlog improvement set:form-element
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.