CogJS - Cognitive-Oriented Web Accessibility Toolkit

cog-read

cog-read is a declarative attribute that adds a speech synthesis button to read aloud the contents of a section or block of text. It supports users with dyslexia, ADHD, cognitive fatigue, and those who benefit from audio reinforcement.

What It Does

When applied to any element, CogJS injects an accessible "Read Aloud" button that uses the browser’s built-in speech synthesis (Text-to-Speech API) to vocalize the element’s text content. It enhances comprehension and reduces reading fatigue.

Customising cog-read

You can customize the button label, style, icon, and size via window.cogReadConfig. This allows you to align it with your design system.

window.cogReadConfig = {
  read: {
    label: "Speak text",
    iconSize: "1.25rem",
    styles: `
      .cog-read-button {
        background-color: #007acc;
        color: white;
        border-radius: 4px;
        padding: 0.25rem;
      }
      .cog-read-button:hover {
        background-color: #005fa3;
      }
      .cog-read-button svg {
        fill: white;
      }
    `
  }
};

Enabling in HTML

Simply add cog-read to the element you want to be read aloud. The button is injected automatically when CogJS initializes.

<article cog-read>
  <h2>Key Policy Update</h2>
  <p>We’ve revised our privacy terms effective May 1st.</p>
</article>

Technical Details

• Uses SpeechSynthesisUtterance for voice playback
• Button is labelled with aria-hidden="true" for assistive technology
• Only reads visible text within the element

Accessibility Considerations

• Enhances Multimodal Access: Ideal for users who prefer audio to visual reading.
• Fully Keyboard Accessible: Injected buttons are focusable and operable via keyboard.
• Screen Reader Compatible: Button includes an ARIA hidden attribute to avoid screen reader conflict or confusion.

Testing cog-read

// Test Checklist
// - Apply cog-read to a section with content
// - Verify read button appears and reads aloud correctly
// - Confirm keyboard accessibility and visible focus styles
// - Check fallback if browser does not support speech synthesis

Best Practices for cog-read

• Use for Important Content: Apply to summaries, policy updates, help instructions, or long articles.
• Keep It Short: Break long sections into smaller cog-read blocks to improve control.
• Style Accessibly: Ensure button contrast and focus styles are visible to all users.
• Test in Multiple Browsers: Speech support varies slightly across platforms-test for consistency.
• Pair with cog-background: Enhance both visual and auditory comprehension for diverse users.