Accessibility Best Practices: Inclusive Feedback

Accessibility matters for every interactive component you put on a page, and a feedback widget is no exception. This guide is a frank account of what the qaid embed currently does and does not provide for accessibility, and what you as the host page can do to make sure every visitor has a way to send you feedback.

What the embed provides today

The embed renders inside a Shadow DOM root that is appended to document.body. That gives it style isolation from your page, but it also means the embed’s internals are not directly reachable or modifiable from your host page’s CSS or scripts.

Within that shadow root, the embed gives you:

Native HTML buttons. Thumbs up, thumbs down, and the optional record and dismiss buttons are real <button type="button"> elements. They are keyboard-focusable in the page’s natural tab order, and they activate on Enter or Space because that is the platform default for <button>.
A native <textarea> in the comment modal. It accepts standard text editing keystrokes and works with screen reader text-input modes.
Auto-focus on the textarea when the modal opens. About 100ms after the modal appears, focus moves into the textarea so the user can start typing immediately without an extra Tab.
Escape key closes the modal. While the modal is open, pressing Escape dismisses it. The same key cancels element targeting mode and stops a screen recording in progress.
An aria-label on the dismiss (X) button. That button announces as “Hide Feedback” so screen reader users understand what the small icon does.
CSS focus styles on the textarea and submit button. When focused via keyboard or click, those controls show a visible outline.

That is the complete list. Everything else below is something the embed does not do today, or something you need to handle at the page level.

Honest limitations

If you tell your accessibility reviewer that the embed includes ARIA dialog roles, focus trapping, live regions, or arrow-key shortcuts, you will be wrong. The embed does not implement any of those. Specifically:

No `role="dialog"` or `aria-modal`

The modal is a styled <div>. It is not announced as a dialog by screen readers, and the surrounding page is not marked aria-hidden. Users navigating with a screen reader will not get a “dialog opened” announcement, and they can navigate out into the page content behind the modal by Tab or by virtual cursor.

No focus trap

Tab and Shift+Tab from inside the modal will eventually move focus into the host page rather than cycling within the modal. There is no programmatic trap that prevents this.

No focus restoration

When the modal closes, focus is not explicitly returned to the thumb button that opened it. Browsers may land focus on <body> depending on what was last focused. Keyboard users may need to reorient.

No live regions

There is no role="status", aria-live, or aria-atomic element in the embed. Submission success, submission failure, and feedback type toggling happen silently as far as assistive technology is concerned.

No `aria-label` on the thumb buttons

The thumbs up and thumbs down buttons contain SVG icons but no accessible name. A screen reader will read them as “button” with no further description. The record button is in the same state.

There is no special handling for arrow keys, no roving tabindex, no documented shortcut other than Escape. The buttons participate in the page’s normal Tab order and respond to Enter and Space because they are native buttons. Nothing more.

Shadow DOM blocks host-page ARIA injection

Because the embed lives in a closed-over shadow tree, you cannot patch ARIA attributes onto the embed’s internals from your page’s JavaScript or stylesheet. Trying to inject role="dialog" from outside will not reach the modal element.

What you can do at the page level

You own the page. Even though you cannot reach inside the embed’s shadow root, there is a lot you can do around it to make the overall experience inclusive.

Always offer an alternative feedback channel

This is the most important step. The embed is one way to collect feedback, not the only way. Provide a clearly labeled, fully accessible alternative:

A “Contact us” or “Send feedback” link in your footer or main navigation, going to a standard form or mailto: address.
A documented support email in your help center.
A standard <form> on a dedicated feedback page, built with the accessibility patterns you already use elsewhere on your site.

If a user’s assistive technology cannot operate the embed effectively, the alternative channel ensures they are not blocked from giving you feedback.

Place the embed thoughtfully

By default the embed is fixed-positioned (typically bottom-right) and sits above your page content. Consider:

Landmark structure. Make sure your page has clear <header>, <main>, <nav>, and <footer> landmarks so keyboard and screen reader users can skip around the embed if they need to.
Skip links. A “Skip to main content” link at the top of the page lets keyboard users bypass the embed and any other floating UI quickly.
z-index conflicts. If the embed overlaps a focus indicator on a real page control, users may not see where their focus is. Test by tabbing through the page and watching focus visibility.

Use the `container` config to put the embed in flow

If you pass a container selector to Qaid.init, the embed renders inside that element instead of being fixed to the viewport. This places it in the document’s normal reading and tab order, which is often better for screen reader users than a floating launcher. A common pattern is to put a feedback embed at the end of an article, inside <footer>, or alongside a “Was this helpful?” prompt.

Guarantee surrounding contrast and motion

Although the embed has its own theme, the experience around it depends on you:

Background contrast. If the buttons sit on top of an image or gradient, make sure the contrast against whatever is actually behind them meets WCAG 2.1 AA (3:1 for non-text UI components, 4.5:1 for text).
Theme colors. If you customize the embed’s colors.positive, colors.negative, or backdrop opacity, verify each color against the surface it sits on. Tools like the WebAIM Contrast Checker or your browser’s DevTools accessibility panel make this quick.
Reduced motion. The embed does not currently honor prefers-reduced-motion. If your users have indicated a preference for reduced motion and you are concerned about animations or transitions in the embed, you can add a CSS rule on your page that uses prefers-reduced-motion to advise users to use your alternative feedback channel, or hide the embed entirely.

Announce relevant state changes from your page

Because the embed has no live regions, anything you want screen reader users to hear about feedback flow has to come from your page. For example, after a user submits feedback you might choose to render a host-page role="status" element thanking them. Coordinate this with whatever success signal you receive from your backend.

Testing checklist

Before shipping the embed, walk through each of these on the page where it is installed:

Tab from the top of the page. Does focus reach the thumb buttons in a sensible order? Is the focus indicator visible against the page background?
Activate a thumb with Enter and again with Space. Both should work because they are native buttons.
In the modal, type a comment. Does the textarea accept input from a screen reader’s text-entry mode?
Press Escape. The modal should close.
After the modal closes, look at where focus lands. It will most likely be on <body>. Decide whether that is acceptable for your site or whether you want to provide a host-page alternative.
Turn on a screen reader (VoiceOver, NVDA, TalkBack) and try the full flow. Take notes on what is and is not announced. The thumb buttons announce only as “button”. The dismiss button announces as “Hide Feedback”. Modal opening is silent.
Confirm your alternative feedback channel is reachable without using the embed at all.

Resources

Summary

The embed renders inside a Shadow DOM and uses native <button> and <textarea> elements, which gives you keyboard activation, basic focus styles, and Escape-to-close on the modal for free.
The textarea auto-focuses when the modal opens; the dismiss button has aria-label="Hide Feedback". That is the extent of explicit ARIA in the embed today.
The embed does not implement role="dialog", aria-modal, focus trapping, focus restoration, live regions, or arrow-key shortcuts. Do not advertise those behaviors to your users or your accessibility reviewers.
Because the embed is in a shadow root, you cannot patch ARIA into its internals from the host page.
Always provide an accessible alternative feedback channel (link, email, or standard form) so users whose assistive technology cannot operate the embed are not blocked.
Use landmarks, skip links, and the container config to keep the embed from disrupting your page’s overall accessibility.
Verify contrast yourself if you customize colors, and check focus visibility against your real page background.