Automatic ARIA via accessible_rails gem versus manual content_tag markup for Rails form fields

Short answer

In a codebase that already leans on Stimulus controllers, the gem-plus-convention approach is the more maintainable default, but only if you scope the gem to static attributes and let Stimulus own dynamic ARIA state. Manual content_tag markup is the right choice for the handful of fields with custom widget behavior, not as the application-wide strategy.

Why the gem scales better

The core maintainability problem is drift. When a validation changes in the model — say you add validates :email, format: ... — manually written ARIA attributes in views do not update themselves. Someone has to remember every form that renders that field. With automatic injection driven by model validations, the model stays the single source of truth and the rendered aria-required, aria-invalid, and aria-describedby attributes follow it. Across dozens or hundreds of forms, that convention beats individual discipline every time.

Manual markup does buy full control: custom patterns like aria-controls on composite widgets, or non-standard error-summary wiring, are awkward to express through a gem's configuration. The failure mode is inconsistency — three developers write three slightly different aria-describedby ID schemes, and screen-reader behavior becomes unpredictable.

Compatibility with Stimulus-driven widgets

The real risk is two owners for the same attribute. If the gem injects aria-expanded or aria-selected at render time while a Stimulus controller toggles the same attribute on connect() or user interaction, you get fights: the gem's server-rendered value is stale the moment the controller runs, or a re-render clobbers the controller's state.

The workable split is:

• Gem owns static, validation-derived attributes: aria-required, aria-invalid, aria-describedby pointing at error containers.
• Stimulus owns dynamic state: aria-expanded, aria-pressed, aria-selected, live-region updates driven by interaction.
• Opt out per field (e.g., a skip option on the helper) for fields wrapped by custom widgets that manage everything themselves.

Watch for double announcements: if the gem injects an aria-live error region and a Stimulus controller also writes error text into a live region, screen readers may announce twice. Pick one live-region owner per form.

Test coverage that actually guarantees sync

Automatic generation only helps if you can prove it tracks validation changes. A reasonable floor:

1. Mapping specs: for each validator type you use (presence, format, length), assert the expected attribute set is produced.
2. Rendering/integration specs: render a representative form and assert aria-required, aria-invalid, and aria-describedby presence and correct ID linkage.
3. Stimulus interaction specs: a system test where a controller toggles aria-expanded and you assert the value persists after any re-render — this catches the gem overwriting runtime state.
4. Regression-on-change: a test that mutates a model validation and fails if the rendered ARIA does not change accordingly, so view code never silently goes stale.

Caveats before adopting

The gem is not Rails core. Before committing, verify its maintenance status and compatibility with your Rails version, and confirm it hooks the form builders you actually use — custom builders or non-standard input helpers may be skipped, leaving inconsistent coverage. Treat this as a spike on a branch: render your real forms, diff the HTML against an ARIA checklist, and run the system tests above before rolling it out.