Skip to content

Make SweetAlert dialogs announce their title, hide the decorative icon, and fix confirm-button contrast - #1363

Merged
jaredgalanis merged 3 commits into
eclipse-pass:mainfrom
uvalib:1269-sweetalert-a11y
Nov 16, 2026
Merged

jaredgalanis merged 3 commits into
eclipse-pass:mainfrom
uvalib:1269-sweetalert-a11y

Conversation

@dougchestnut

@dougchestnut dougchestnut commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

When a SweetAlert2 dialog opened (Files → Remove, change submitter, Review → submit, session timeout and other error dialogs), screen reader users often heard only "!" and the focused button. The title ("Are you sure?") and the description were skipped. Two things caused this. The warning/error icon glyph is in the accessibility tree. SweetAlert2 also puts aria-live="assertive" on modal dialogs, which competes with the normal announcement of the dialog's aria-labelledby / aria-describedby when focus moves into it. Separately, the confirm button (I Agree, Next, Confirm, ...) was white text on #418fde, which is 3.38:1, below the 4.5:1 minimum.

  • New app/util/swal.ts registers a makePopupAccessible handler on SweetAlert2's global didRender event (Swal.on('didRender', …)), so it runs on every render of every popup, including swal.update(), and a call's own didRender can't replace it. The handler sets aria-hidden="true" on .swal2-icon, removes aria-live from role="dialog" popups (toasts keep theirs), and gives .swal2-validation-message its own aria-live="polite" / aria-atomic="true" region, since the dialog's live region was also what announced validation messages. The module exports SweetAlert2 itself, so the API is unchanged.
  • Every sweetalert2 import in app/ now uses pass-ui/util/swal instead (external-repo-review, submission-action-cell, workflow-basics, workflow-files, workflow-review, submissions/detail, submissions/new, new/files, new/repositories, error-handler). The options passed at each call site are unchanged. The // @ts-ignore comments on those imports are gone because the helper is typed.
  • .swal2-confirm in app/styles/app.css now uses var(--primary-600, #1e40af) for background and border, with white text: 8.72:1 with the default branding (was 3.38:1).
  • The stock sample overlay (public/branding-overrides.css, which pass-docker loads) set --primary-600 to #e37108, which would have made the button 3.17:1. It is darkened to #8a3f00, so the button is 7.52:1 there too.
  • Tests: new tests/unit/util/swal-test.ts checks the dialog role, accessible name and description, that aria-live is gone and the icon hidden, that this holds after update(), through a nested mixin, for positional fire(title, text, icon) calls and when a call passes its own didRender, and that a validation message is in a polite live region. After each test it turns off the hide animation before closing, so SweetAlert2 removes the popup and its aria-hidden on the rest of the page right away, and it checks that nothing is left behind. The Files → Remove integration test also checks the live dialog, and the controller unit tests that stub SweetAlert2 now import it from the util.
  • eslint.config.mjs: no-restricted-imports blocks importing any sweetalert2 JS entry point (the main export or a dist bundle) in app/ (except the util), so new dialogs get the fixes. Its stylesheets, like the import in app.ts, are still allowed.
  • public/branding.css notes that overlays must keep white on --primary-600 at 4.5:1 or more.

Fixes eclipse-pass/main#1269
Part of eclipse-pass/main#718

How to test

  1. Start a new submission, go to Files, add a file, and click Remove.
  2. Inspect the dialog. .swal2-popup has role="dialog", aria-modal="true", aria-labelledby and aria-describedby, and no aria-live; .swal2-validation-message has aria-live="polite". .swal2-icon has aria-hidden="true".
  3. Turn on VoiceOver or NVDA and open the dialog again. It should announce "Are you sure?" and the description, and it should not say "!". On Review → Submit, press Next → in the deposit agreement dialog without choosing an option: the validation message is read.
  4. Check the confirm button contrast in pass-docker (sample overlay): white on #8a3f00 is 7.52:1. Without the overlay it is white on #1e40af, 8.72:1. An easy dialog to check: start a submission with no grant and press Next on Repositories ("No repositories selected"), or Files → Remove.
  5. Run the tests: pnpm exec ember test --path dist --filter "swal" and pnpm exec ember test --path dist --filter "workflow files".

Notes

  • Focus still moves to the confirm button on open (SweetAlert2's default). The issue lists changing that as optional, so each call keeps its current behavior; a destructive dialog can pass focusCancel: true.
  • The confirm button follows each deployment's --primary-600. The bundled sample overlay is darkened here, but an institution overlay with a light --primary-600 would fall back under 4.5:1, so public/branding.css now says overlays must keep white-on---primary-600 at 4.5:1 or more.
  • .swal2-confirm keeps its existing !important, so per-call confirmButtonColor values are still overridden, as before.
  • If sweetalert2 is replaced later (replace sweetalert2 with something else for modals main#663), the replacement should keep the same behaviours: decorative icon hidden, dialog named by its title, no assertive live region on the dialog, validation messages announced, and a 4.5:1 confirm button.

🤖 Generated with Claude Code

dougchestnut and others added 2 commits October 20, 2026 22:38
Screen readers often heard only the decorative "!" icon and the focused
confirm button when a SweetAlert2 dialog opened: the icon glyph is in the
accessibility tree, and SweetAlert2 marks modal dialogs aria-live="assertive",
which gets in the way of announcing the dialog name and description.

Add app/util/swal.ts, a Swal.mixin with a didRender hook that hides the icon
from assistive tech and drops aria-live from role="dialog" popups, and switch
every sweetalert2 import in app/ to it. Call options are unchanged.

The .swal2-confirm button used white on #418fde (3.38:1); use
var(--primary-600) (default #1e40af, 8.72:1) instead.

Fixes eclipse-pass/main#1269

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The confirm button now uses --primary-600, and the stock sample overlay set
it to #e37108, so white text on it was 3.17:1, slightly worse than before.
Darken the sample --primary-500 / --primary-600 to #b35400 / #8a3f00 so the
button meets 4.5:1 (7.52:1) with the overlay pass-docker loads by default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@jaredgalanis jaredgalanis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this — the didRender hook approach is clean and the writeup made it easy to verify. I checked the claims against the installed sweetalert2 (11.17.2) source. A few findings, roughly in order of severity:

Validation messages lose their announcement (app/util/swal.ts). The aria-live we're removing was also what announced showValidationMessage() text. In the workflow-review agreement dialog (input: 'radio' + inputValidator), the first failure is still read because focus moves to the radio, but pressing Confirm again with focus already on the input produces no focus event and no live region, so the repeat failure is silent to screen readers. Suggest makePopupAccessible also set aria-live="polite" (or role="alert") on .swal2-validation-message.

Consider Swal.on('didRender', ...) instead of the mixin option. SweetAlert2 merges options shallowly, so any future call site that passes its own didRender silently drops the a11y hook — the "call makePopupAccessible yourself" note in the PR body is the symptom. 11.17.2 has a global event API: Swal.on('didRender', makePopupAccessible) registered once applies to every popup and can't be clobbered per call. Fine as a follow-up if you'd rather not rework it here.

Possible test leak in tests/unit/util/swal-test.ts. With sweetalert2.css loaded, swal.close() removes the container only after the hide animation ends (~150ms), and the positional-args test fires with no target, mounting on document.body. A popup can outlive its test into the next seed-randomized one, and the workflow-files integration test asserts on .swal2-popup scoped to document.body, so this could add to our CI flakiness. Synchronously removing .swal2-container in afterEach (or awaiting its removal) closes the gap.

Smaller notes, none blocking:

  • Confirm-button contrast now follows each deployment's --primary-600. The bundled sample overlay was audited and darkened, but an institution overlay with a light --primary-600 would land back under 4.5:1. Worth a line in the branding docs.
  • Four controller unit tests (files-test.ts, detail-test.ts, new-test.ts, repositories-test.ts) still stub the dist Swal class; that works only through static inheritance into the mixin subclass and breaks if the util ever wraps fire. Stubbing the util's export is sturdier.
  • Nothing enforces "new dialogs import pass-ui/util/swal". An eslint no-restricted-imports rule for sweetalert2 scoped to app/** (allowing the util and the CSS import) would make the convention stick.

Happy to approve once the validation-message announcement and the test cleanup are in.

These findings and message were written with the help of Claude.

Removing aria-live from the dialog also removed what announced
validation messages, so give .swal2-validation-message its own polite
live region.

Register makePopupAccessible once with Swal.on('didRender') instead of
a mixin option, so a call's own didRender can't drop it, and export
SweetAlert2 itself from the util. Controller tests now stub that export,
and an eslint rule keeps app code importing the util rather than
sweetalert2. public/branding.css notes the 4.5:1 requirement for
--primary-600.

Only the sample overlay's --primary-600 drives the confirm button, so
--primary-500 goes back to its original value.

In the swal unit tests, turn off the hide animation before closing, so
SweetAlert2 removes the popup and the aria-hidden it put on the page
right away, and check nothing is left behind after each test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dougchestnut

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review — all good catches. Pushed fbd604e:

  • Validation messages: makePopupAccessible now gives .swal2-validation-message its own aria-live="polite" / aria-atomic="true", since the dialog's live region was what announced them. Unit test included.
  • Global hook: took your suggestion here rather than as a follow-up. The handler is registered once with Swal.on('didRender', …) and the util now exports SweetAlert2 itself, so a call's own didRender can't drop it (tested). The "call makePopupAccessible yourself" note is gone.
  • Test leak: swal-test.ts turns off the hide animation before close() in afterEach, so SweetAlert2 removes the container and undoes its aria-hidden on the page right away (just removing the node would have skipped that cleanup), and then asserts nothing is left. Full suite passes on repeated runs.
  • Controller tests: the four tests now import Swal from pass-ui/util/swal. Since the util exports SweetAlert2 itself, their stubs hit the same object the controllers call.
  • Enforcement: added a no-restricted-imports rule in app/** for every sweetalert2 JS entry point, dist bundles included (the util and the stylesheet imports are allowed).
  • Overlay contrast: there's no branding doc, so I put the 4.5:1 note for --primary-600 in public/branding.css and in the PR description. I also put the sample overlay's --primary-500 back, since only --primary-600 affects the confirm button.

@sonarqubecloud

Copy link
Copy Markdown

dougchestnut added a commit to uvalib/pass-ui that referenced this pull request Nov 11, 2026
…#1363)

# Conflicts:
#	app/components/workflow-review/index.gts
#	app/controllers/submissions/detail.ts
#	app/util/swal.ts
#	public/branding-overrides.css
#	tests/unit/controllers/submissions/detail-test.ts
#	tests/unit/util/swal-test.ts

@jaredgalanis jaredgalanis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! Thank you!

@jaredgalanis
jaredgalanis merged commit 5953c14 into eclipse-pass:main Nov 16, 2026
6 checks passed
@dougchestnut
dougchestnut deleted the 1269-sweetalert-a11y branch November 17, 2026 14:40
dougchestnut added a commit to uvalib/pass-ui that referenced this pull request Nov 17, 2026
# Conflicts:
#	app/components/workflow-review/index.gts
#	app/controllers/submissions/detail.ts
#	public/branding-overrides.css
#	tests/unit/controllers/submissions/detail-test.ts
dougchestnut added a commit to uvalib/pass-ui that referenced this pull request Nov 17, 2026
…ipse-pass#1301 filed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SweetAlert dialogs: “!” icon is announced, dialog title is skipped, and confirm fails 4.5:1

2 participants