Accessibility Best Practices: Inclusive Feedback

Accessibility isn’t optional—it’s essential. The Qaid feedback embed is built with accessibility as a core principle, ensuring that all users can provide feedback regardless of their abilities or assistive technology needs.

Built-in Accessibility Features

The Qaid embed includes comprehensive accessibility support out of the box:

• Semantic HTML - Proper button elements, labels, and form controls
• ARIA attributes - Descriptive labels for screen readers
• Keyboard navigation - Full functionality without a mouse
• Focus management - Logical focus order and visible focus indicators
• Color contrast - WCAG AA compliant color ratios
• Reduced motion - Respects user preferences for reduced animations

Try navigating the widget above using only your keyboard to experience the accessibility features firsthand.

Keyboard Navigation

All embed functionality is accessible via keyboard:

Key	Action
Tab	Move focus to next interactive element
Shift + Tab	Move focus to previous element
Enter or Space	Activate buttons and controls
Escape	Close modal or cancel targeting mode
Arrow keys	Navigate within modal content

Focus Order

The embed follows a logical focus order:

1. Thumbs up button
2. Thumbs down button
3. Target element button (if enabled)
4. Modal content (when open)
5. Submit button

// Focus is automatically managed when the modal opens
Qaid.init({
  apiKey: "your-api-key",
  // Focus trapping is enabled by default in modals
});

Screen Reader Support

The embed provides comprehensive screen reader support through ARIA attributes:

Button Labels

Each button includes descriptive ARIA labels:

<!-- Generated markup includes proper labeling -->
<button aria-label="Submit positive feedback">
  <!-- Thumbs up icon -->
</button>

<button aria-label="Submit negative feedback">
  <!-- Thumbs down icon -->
</button>

<button aria-label="Select an element on the page to provide feedback">
  <!-- Target icon -->
</button>

Live Regions

Status updates are announced to screen readers:

<div role="status" aria-live="polite">
  Feedback submitted successfully
</div>

Modal Accessibility

When the feedback modal opens:

• Focus moves to the modal
• Background content is marked with aria-hidden="true"
• Modal has role="dialog" and aria-modal="true"
• Close button is clearly labeled

Focus Management in Modals

Proper focus management prevents users from getting lost:

Focus Trapping

When the modal is open, focus is contained within:

// The embed automatically traps focus in the modal
// Users can Tab through modal elements without
// accidentally focusing background content

Focus Restoration

When the modal closes, focus returns to the triggering element:

// After closing the modal, focus returns to
// the button that opened it

Visible Focus Indicators

All interactive elements have visible focus states:

/* The embed includes focus styles like these */
button:focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: 2px;
}

Color Contrast Requirements

The embed meets WCAG 2.1 AA color contrast requirements:

Element	Contrast Ratio	Requirement
Body text	4.5:1 minimum	AA (normal text)
Large text	3:1 minimum	AA (18px+ or 14px bold)
UI components	3:1 minimum	AA (buttons, inputs)
Focus indicators	3:1 minimum	AA

Default Theme Contrast

The default theme exceeds minimum requirements:

• Text on background: 7.2:1
• Button text: 5.8:1
• Icon buttons: 4.8:1

Testing Your Customizations

If you customize colors, verify contrast with tools like:

• WebAIM Contrast Checker
• Colour Contrast Analyser
• Browser DevTools accessibility panel

Customizing ARIA Labels

You can customize ARIA labels to match your application’s terminology:

Qaid.init({
  apiKey: "your-api-key",
  ariaLabels: {
    thumbsUp: "Mark as helpful",
    thumbsDown: "Mark as not helpful",
    targetMode: "Select a specific element to comment on",
    closeModal: "Close feedback form",
    submitButton: "Send your feedback",
    feedbackInput: "Describe your feedback",
  },
});

Localization

For multilingual applications, provide translated labels:

const ariaLabels = {
  en: {
    thumbsUp: "Submit positive feedback",
    thumbsDown: "Submit negative feedback",
  },
  es: {
    thumbsUp: "Enviar comentario positivo",
    thumbsDown: "Enviar comentario negativo",
  },
  // Add more languages as needed
};

Qaid.init({
  apiKey: "your-api-key",
  ariaLabels: ariaLabels[userLanguage],
});

Testing with Screen Readers

Regular testing with screen readers ensures your implementation works correctly:

Recommended Screen Readers

Platform	Screen Reader	Cost
macOS	VoiceOver	Built-in
Windows	NVDA	Free
Windows	JAWS	Paid
iOS	VoiceOver	Built-in
Android	TalkBack	Built-in

Testing Checklist

1. Navigation - Can you reach all controls with Tab?
2. Activation - Do Enter and Space activate controls?
3. Announcements - Are button purposes announced?
4. State changes - Are modal open/close announced?
5. Feedback - Is success/error status announced?
6. Escape - Does Escape close the modal?

VoiceOver Quick Start (macOS)

1. Press Cmd + F5 to enable VoiceOver
2. Use Tab to navigate to the embed
3. Press Enter to activate buttons
4. Listen for announcements
5. Press Cmd + F5 again to disable

WCAG 2.1 AA Compliance Checklist

Use this checklist to verify accessibility compliance:

Perceivable

• 1.1.1 Non-text Content - All buttons have text alternatives
• 1.3.1 Info and Relationships - Proper heading structure and labels
• 1.4.1 Use of Color - Color is not the only indicator of state
• 1.4.3 Contrast (Minimum) - 4.5:1 for text, 3:1 for UI
• 1.4.11 Non-text Contrast - 3:1 for icons and focus indicators

Operable

• 2.1.1 Keyboard - All functionality available via keyboard
• 2.1.2 No Keyboard Trap - Focus can move freely (except in modals)
• 2.4.3 Focus Order - Logical and intuitive focus sequence
• 2.4.7 Focus Visible - Visible focus indicators on all elements

Understandable

• 3.2.1 On Focus - No unexpected changes on focus
• 3.2.2 On Input - No unexpected changes without warning
• 3.3.1 Error Identification - Errors are clearly described
• 3.3.2 Labels or Instructions - Clear labels for inputs

Robust

• 4.1.1 Parsing - Valid HTML markup
• 4.1.2 Name, Role, Value - Proper ARIA attributes

Common Accessibility Issues to Avoid

Icon-Only Buttons Without Labels

// Bad - no accessible name
<button><svg>...</svg></button>

// Good - includes aria-label
<button aria-label="Submit positive feedback">
  <svg aria-hidden="true">...</svg>
</button>

Missing Focus Management

// The embed handles this automatically, but if customizing:
// Always return focus when closing modals
modalCloseButton.addEventListener('click', () => {
  modal.close();
  triggerButton.focus(); // Return focus
});

Insufficient Color Contrast

When customizing the theme, always verify contrast:

// Verify these colors meet contrast requirements
Qaid.init({
  apiKey: "your-api-key",
  theme: {
    primaryColor: "#2563eb", // Check against background
    textColor: "#1f2937",    // Must be 4.5:1 minimum
  },
});

Resources

• WCAG 2.1 Guidelines
• WebAIM
• A11y Project
• Inclusive Components

Next Steps

• Review our Configuration Guide for all ARIA options
• Learn about Keyboard Shortcuts for power users
• Explore Customization Options while maintaining accessibility