Critical a11y fix requiring a breaking API change

What's really being asked

This evaluates judgment under tension: a real user-harming bug pulls toward speed, while a breaking API change pulls toward careful process. You must serve both.

The full answer

First confirm severity and reproduce the issue, since accessibility blockers can legally and ethically demand urgency. Look for a non-breaking interim mitigation you can ship now, for example correcting focus trapping or ARIA internally without changing the public API. If the real fix genuinely requires an API change, design it so the accessible behavior becomes the default. Release it as a major version, but where feasible keep the old behavior available behind a clearly deprecated, discouraged flag during a short overlap so teams are not stranded. Provide a codemod and a migration guide, and communicate the accessibility rationale prominently so teams prioritize upgrading. Track adoption and remove the deprecated path in the next major. Add a regression test so it cannot recur.

The mistakes people make

Forcing an immediate breaking release with no migration path. Conversely, blocking the fix for months purely on process while users are harmed. Hiding the change in a minor version. Skipping the regression test.

What usually comes next

What if no safe interim fix exists? How do you decide overlap length when the bug is critical? How do you handle teams that refuse to upgrade?

A concrete example

The Modal does not trap focus, failing keyboard users. You first ship an internal fix that adds focus trapping without API change. Then you find that proper return-focus behavior needs a new required prop. You release version 6.0.0 with the accessible default, keep a deprecated legacy mode briefly, publish a codemod, and flag the accessibility urgency so teams upgrade quickly.