Qaid
ARTICLE

Accessibility: Built In, Not Bolted On

The Qaid thumbs and quests embeds are built to WCAG 2.2 AA — keyboard operable, screen-reader friendly, with dialog semantics, focus management, and live-region announcements. Here's what that gives you and how to integrate accessibly.

Qaid Team

Accessibility is something we own in the component, so you inherit it for free. Both the thumbs feedback embed and the quests questionnaire embed are built to WCAG 2.2 Level AA — real native controls, accessible names, keyboard operation, managed focus, and assistive-technology announcements. This guide covers what that gives your users and the few page-level habits that keep the whole experience inclusive.

How the embeds are structured

Both embeds render inside a Shadow DOM root attached to the page, which isolates their styles from yours so nothing collides in either direction. The root is created in mode: 'open', so it is not a black box — advanced integrators can reach element.shadowRoot to inspect or extend it when needed. Everything below is built on native, keyboard-operable HTML.

The thumbs embed

  • Native buttons with accessible names. Thumbs up, thumbs down, record, and dismiss are real <button> elements, focusable in the tab order and activated by Enter or Space. Each icon-only button has an aria-label ("Send positive feedback", "Send negative feedback", "Record a screen recording", "Hide feedback buttons"), overridable via the text config.
  • Keyboard-operable element targeting. Choosing the element your feedback refers to works from the keyboard — not just the mouse — and the targeting state is announced.
  • A real dialog. The comment modal, mobile bottom sheet, and recording preview expose role="dialog" with aria-modal and an accessible name, trap focus while open, make the rest of the page inert, and return focus to the button that opened them on close. Escape closes them.
  • Announcements. A live region announces submission success and failure, screenshot capture, recording start/stop and the final countdown, and feedback-type changes — so nothing important happens silently. The type toggle exposes aria-pressed.
  • Native textarea with auto-focus when the modal opens, visible focus styles, prefers-reduced-motion and forced-colors support.

The quests embed

  • Every input is labeled and grouped. Controls carry accessible names; single/multi choice questions are exposed as role="radiogroup"/group with radio/checkbox options and aria-checked; the range control is a native accessible slider.
  • Keyboard-first. Arrow-key roving between options plus 1–9 quick-select, and focus moves to the active field as you advance.
  • Validation that assistive tech understands. Required fields are marked aria-required; on a failed submit the field is set aria-invalid and programmatically linked to its error text via aria-describedby, and the error is announced through a live region — never color alone.
  • Progress is conveyed non-visually via role="progressbar" with live value updates and a "Step X of Y" announcement on each step.
  • Dialog + completion. In modal mode the questionnaire is a proper focus-trapped dialog with an accessible name; inline mode stays a plain in-flow region. On completion, focus moves to the thank-you heading and the confirmation is announced. Reduced-motion and forced-colors are honored.

Integrating the embeds accessibly

You own the page around the embed, and a few habits keep everything inclusive:

  • Landmarks & skip links. Clear <header>, <main>, <nav>, <footer> and a "Skip to main content" link let keyboard and screen-reader users move around any floating UI.
  • Focus visibility. Tab through your page and confirm the embed never obscures a focus indicator on your own controls (watch z-index).
  • Inline mode where it fits. Passing a container selector renders the embed in the document's normal reading and tab order — often the nicest placement for a "Was this helpful?" prompt at the end of an article.
  • Verify contrast when you theme. The embeds honor whatever colors you set, so when you customize colors.positive, colors.negative, or colors.marker, check each against the surface behind it: 4.5:1 for text and 3:1 for non-text UI (WCAG 1.4.3 / 1.4.11). The WebAIM Contrast Checker makes this quick.

Testing checklist

On the page where an embed is installed:

  1. Tab from the top. Focus reaches the controls in a sensible order and stays visible.
  2. Activate with Enter and Space. Both work — they are native buttons.
  3. Open a dialog / a quest and Tab. Focus stays trapped inside; Escape closes; focus returns to where you were.
  4. Listen with a screen reader (VoiceOver, NVDA, TalkBack). Controls announce by name and role; validation errors, progress, and submissions are announced.
  5. Complete the flow from the keyboard only — thumb → target → comment → submit, or a full questionnaire → thank-you.
  6. Themed your colors? Re-check contrast against your real background.

Resources

Summary

  • Both embeds are built to WCAG 2.2 AA: native controls, accessible names, keyboard operation, dialog semantics, managed focus, and live-region announcements — in the component, so you inherit it.
  • Thumbs: named icon buttons, keyboard targeting, a focus-trapped dialog with focus restore, and spoken status for every state change.
  • Quests: labeled and grouped inputs, an accessible slider, aria-required/aria-invalid with linked error text, progressbar semantics, per-step focus, and an announced thank-you.
  • The shadow root is mode: 'open', so integrators can reach in when needed.
  • Around the embed: use landmarks and skip links, consider inline container mode, and verify contrast whenever you theme your colors.
Back to all articles