accessibility-widgets
Version:
A comprehensive, lightweight accessibility widget that enhances web accessibility for all users. Provides multiple accessibility features including screen reader support, voice control, high contrast mode, and more.
500 lines (404 loc) • 17.8 kB
Markdown
# Accessibility Widgets
[](https://www.npmjs.com/package/accessibility-widgets)
[](https://opensource.org/licenses/GPL-3.0)
[](https://unpkg.com/accessibility-widgets)
<a href="https://github.com/sponsors/sinanisler">
<img src="https://img.shields.io/badge/Consider_Supporting_My_Projects_❤-GitHub-d46" width="300" height="auto" />
</a>
<br><br>
A comprehensive, zero-dependency accessibility widget that enhances web accessibility for all users. This lightweight, single-file JavaScript solution provides 14+ accessibility features to make your website instantly more inclusive and compliant with WCAG 2.1 AA, Section 508, and EN 301 549 standards.
<br><br>
> **Note**: This widget helps meet accessibility criteria but does not guarantee full compliance. Complete WCAG/Section 508 compliance requires proper HTML semantics, ARIA attributes, manual testing, and user validation.
<br><br>
<img width="1793" height="1028" alt="image" src="https://github.com/user-attachments/assets/610138f5-e60d-4297-b5e3-ea040f361209" />
## Supported Language List
English, Deutsch, Español, Italiano, Français, Русский, Türkçe, العربية, हिन्दी, 简体中文, 日本語, Português, বাংলা, 한국어, Tiếng Việt, Bahasa Indonesia, ไทย, Polski, Nederlands, Ελληνικά, Svenska, Norsk, Dansk, Suomi, Čeština, Magyar, Română, עברית, فارسی, اردو, ਪੰਜਾਬੀ, मराठी, తెలుగు, தமிழ், Bahasa Melayu, Filipino
## ⚡ Quick Start
```html
<!-- Include the widget - That's it! -->
<script src="https://unpkg.com/accessibility-widgets@latest/widget.js"></script>
```
Or install via NPM:
```bash
npm install accessibility-widgets
```
```javascript
// Import in your project
import 'accessibility-widgets';
// or
require('accessibility-widgets');
```
## ✨ Key Features
### 🎨 Visual Enhancements
- **High Contrast Mode** - 3 levels (Medium 1.3x, High 1.5x, Ultra 2.0x) for improved visibility
- **Text Size Control** - 4 size options (Default, Medium 20px, Large 24px, X-Large 28px)
- **Line Height Adjustment** - 3 spacing levels (2em, 3em, 4em) for better readability
- **Text Spacing** - Enhanced letter (0.2em) and word spacing (0.3em)
- **Text Alignment** - Left, Center, or Right alignment options
- **Bigger Cursor** - High-contrast 48x72px cursor with SVG rendering
- **Hide Images** - Text-only mode for focused reading or bandwidth saving
### 🧠 Cognitive Support
- **Dyslexia-Friendly Font** - Comic Sans MS and other dyslexia-optimized fonts
- **Font Selection** - Choose between Arial, Times New Roman, or Verdana
- **Animation Control** - Pause all animations and transitions
- **Reduced Motion** - Motion sensitivity support for vestibular disorders
### ♿ Assistive Technology
- **Screen Reader** - Built-in text-to-speech using Web Speech API
- **Voice Control** - Hands-free navigation with 15+ voice commands
- **Color Blindness Filters** - Protanopia, Deuteranopia, Tritanopia, and Grayscale modes
- **Keyboard Navigation** - Full Tab/Arrow key support with proper focus indicators
## 📊 Compliance & Standards
### WCAG 2.1 AA Coverage
| Feature | WCAG Criteria | EU EN 301 549 | US Section 508 |
|---------|---------------|---------------|----------------|
| High Contrast Mode | ✅ 1.4.3, 1.4.6 | ✅ | ✅ |
| Text Size Adjustment | ✅ 1.4.4 | ✅ | ✅ |
| Text Spacing | ✅ 1.4.12 | ✅ | ✅ |
| Line Height Adjustment | ✅ 1.4.12 | ✅ | ✅ |
| Text Alignment | ✅ 1.4.8 | ✅ | ✅ |
| Cursor Enhancement | ✅ 2.5.5 | ✅ | ✅ |
| Pause Animations | ✅ 2.2.2, 2.3.3 | ✅ | ✅ |
| Reduced Motion | ✅ 2.3.3 | ✅ | ✅ |
| Hide Images | ✅ 1.1.1 | ✅ | ✅ |
| Dyslexia-Friendly Font | ✅ 1.4.8 | ✅ | ✅ |
| Screen Reader | ✅ 4.1.3 | ✅ | ✅ |
| Voice Control | ⚠️ Browser API | ⚠️ | ⚠️ |
| Color Filters | ✅ 1.4.1 | ✅ | ✅ |
## 🎯 Installation Methods
### CDN (Fastest)
```html
<!-- unpkg CDN -->
<script src="https://unpkg.com/accessibility-widgets@latest/widget.js"></script>
<!-- jsdelivr CDN -->
<script src="https://cdn.jsdelivr.net/npm/accessibility-widgets@latest/widget.js"></script>
```
### NPM
```bash
npm install accessibility-widgets
```
```javascript
// ES6 Import
import 'accessibility-widgets/widget.js';
// CommonJS
require('accessibility-widgets/widget.js');
```
### Direct Download
1. Download [widget.js](https://github.com/sinanisler/accessibility-widgets/raw/main/widget.js)
2. Include in your HTML:
```html
<script src="path/to/widget.js"></script>
```
## ⚙️ Configuration
### Basic Setup (No Configuration Needed)
The widget works out of the box with zero configuration:
```html
<script src="https://unpkg.com/accessibility-widgets@latest/widget.js"></script>
```
### Custom Configuration
Customize the widget by defining `window.ACCESSIBILITY_WIDGET_CONFIG` before loading the script:
```html
<script>
window.ACCESSIBILITY_WIDGET_CONFIG = {
// Disable specific features
enableVoiceControl: false,
enableScreenReader: true,
// Custom styling
widgetWidth: '400px',
colors: {
primary: '#0066cc',
secondary: '#ffffff'
},
// Position on left side
widgetPosition: {
side: 'left',
left: '20px',
bottom: '20px'
}
};
</script>
<script src="https://unpkg.com/accessibility-widgets@latest/widget.js"></script>
```
### Full Configuration Options
```javascript
window.ACCESSIBILITY_WIDGET_CONFIG = {
// ===== Core Feature Toggles =====
enableHighContrast: true, // 3-level high contrast mode
enableBiggerText: true, // 4-level text size control
enableTextSpacing: true, // 3-level text spacing
enablePauseAnimations: true, // Pause animations & reduced motion
enableHideImages: true, // Hide images toggle
enableDyslexiaFont: true, // Dyslexia-friendly fonts
enableBiggerCursor: true, // Large cursor
enableLineHeight: true, // 3-level line height (2em, 3em, 4em)
enableTextAlign: true, // Text alignment (left, center, right)
// ===== Advanced Features =====
enableScreenReader: true, // Built-in text-to-speech
enableVoiceControl: true, // Voice command control
enableFontSelection: true, // Font family selection
enableColorFilter: true, // Color blindness filters
// ===== Widget Layout =====
widgetWidth: '440px',
// ===== Grid Configuration =====
gridLayout: {
columns: '1fr 1fr', // Default 2-column grid
gap: '10px' // Gap between grid items
},
// ===== Position =====
widgetPosition: {
side: 'right', // 'left' or 'right'
right: '20px',
left: '20px',
bottom: '20px'
},
// ===== Colors =====
colors: {
primary: '#1663d7', // Header bg, main button, active borders
secondary: '#ffffff', // Main button icon, header text
optionBg: '#ffffff', // Option button background
optionText: '#333333', // Option button text
optionIcon: '#000000' // Option button icons
},
// ===== Button Styling =====
button: {
size: '55px',
borderRadius: '100px',
iconSize: '40px',
shadow: '0 4px 8px rgba(0, 0, 0, 0.2)'
},
// ===== Menu Styling =====
menu: {
headerHeight: '70px',
padding: '0 10px 10px 10px',
optionPadding: '20px 10px',
optionMargin: '10px',
borderRadius: '8px',
fontSize: '16px',
titleFontSize: '16px',
closeButtonSize: '44px'
},
// ===== Typography =====
typography: {
fontFamily: 'Arial, sans-serif',
fontSize: '17px',
titleFontSize: '22px',
titleFontWeight: '700',
lineHeight: '1'
},
// ===== Animation =====
animation: {
transition: '0.2s',
hoverScale: '1.05'
},
// ===== Internationalization (i18n) =====
lang: {
accessibilityMenu: 'Accessibility Menu',
closeAccessibilityMenu: 'Close Accessibility Menu',
accessibilityTools: 'Accessibility Tools',
resetAllSettings: 'Reset All Settings',
screenReader: 'Screen Reader',
voiceCommand: 'Voice Command',
textSpacing: 'Text Spacing',
pauseAnimations: 'Pause Animations',
hideImages: 'Hide Images',
dyslexiaFriendly: 'Dyslexia Friendly',
biggerCursor: 'Bigger Cursor',
lineHeight: 'Line Height',
fontSelection: 'Font Selection',
colorFilter: 'Color Filter',
textAlign: 'Text Align',
textSize: 'Text Size',
highContrast: 'High Contrast',
defaultFont: 'Default Font',
noFilter: 'No Filter',
default: 'Default',
screenReaderOn: 'Screen reader on',
screenReaderOff: 'Screen reader off',
voiceControlActivated: 'Voice control activated',
notSupportedBrowser: 'is not supported in this browser',
close: 'Close',
reset: 'Reset',
saturation: 'Saturation',
selectLanguage: 'Select Language'
},
// ===== Voice Commands (Multi-language Support) =====
voiceCommands: {
en: {
showMenu: ['show menu', 'open menu', 'accessibility menu', 'access menu'],
highContrast: ['high contrast', 'contrast', 'dark mode', 'increase contrast'],
biggerText: ['bigger text', 'large text', 'text size', 'increase text', 'bigger', 'larger text', 'text bigger', 'make text bigger', 'enlarge text'],
textSpacing: ['text spacing', 'spacing', 'letter spacing', 'text space'],
pauseAnimations: ['pause animations', 'stop animations', 'disable animations', 'no animations'],
hideImages: ['hide images', 'remove images', 'no images'],
dyslexiaFont: ['dyslexia friendly', 'dyslexia font', 'readable font', 'easy font'],
biggerCursor: ['bigger cursor', 'large cursor', 'cursor size', 'big cursor'],
lineHeight: ['line height', 'line spacing', 'space between lines', 'line space'],
textAlign: ['align text', 'text align', 'center text', 'alignment'],
screenReader: ['screen reader', 'read aloud', 'voice reader'],
voiceControl: ['voice command', 'voice control', 'voice commands'],
resetAll: ['reset all', 'reset everything', 'clear all', 'reset settings', 'reset']
},
// Additional languages: de, es, it, fr, ru, tr, ar, hi, zh-cn, jp available in widget
}
};
```
## 🌍 Internationalization (i18n)
Full multilingual support - customize all text and voice commands:
### Spanish Example
```html
<script>
window.ACCESSIBILITY_WIDGET_CONFIG = {
lang: {
accessibilityMenu: 'Menú de Accesibilidad',
accessibilityTools: 'Herramientas de Accesibilidad',
screenReader: 'Lector de Pantalla',
highContrast: 'Alto Contraste',
biggerText: 'Texto Más Grande',
resetAllSettings: 'Restablecer Todo'
},
voiceCommands: {
showMenu: ['mostrar menú', 'abrir menú'],
highContrast: ['alto contraste'],
biggerText: ['texto grande', 'texto más grande'],
resetAll: ['reiniciar todo']
}
};
</script>
<script src="https://unpkg.com/accessibility-widgets@latest/widget.js"></script>
```
## 🎤 Voice Commands
When voice control is enabled (Chrome/Edge only), use these commands:
| Command | Action |
|---------|--------|
| "show menu" / "open menu" | Opens accessibility menu |
| "high contrast" | Toggles contrast mode |
| "bigger text" / "large text" | Increases text size |
| "text spacing" | Toggles text spacing |
| "pause animations" | Stops all animations |
| "hide images" | Removes images |
| "dyslexia font" | Activates dyslexia-friendly font |
| "bigger cursor" | Enlarges cursor |
| "line height" | Adjusts line spacing |
| "screen reader" | Activates text-to-speech |
| "reset all" | Resets all settings |
*All commands are fully customizable via `voiceCommands` configuration*## 📚 Feature Details
### High Contrast Mode
Three contrast enhancement levels:
- **Medium**: 1.3x boost for subtle improvement
- **High**: Black background + white text + 1.5x contrast
- **Ultra**: Black background + yellow text + 2.0x contrast
### Text Size Control
Four size options (Default, Medium 20px, Large 24px, X-Large 28px) with smart widget exclusion to maintain UI consistency.
### Text Spacing
Enhanced letter spacing (0.2em) and word spacing (0.3em) for improved readability, especially helpful for dyslexia.
### Line Height Adjustment
Three spacing levels (2em, 3em, 4em) to reduce visual crowding and improve reading flow.
### Animation Control
Completely disables CSS animations and transitions - critical for users with vestibular disorders or ADHD.
### Image Hiding
Text-only mode with smart caching (5-second intervals) to catch dynamically loaded images.
### Dyslexia-Friendly Font
Uses Comic Sans MS and fallback fonts optimized for dyslexia (Chalkboard SE, Bradley Hand, Brush Script MT).
### Cursor Enhancement
Custom 48x72px SVG cursor with high-contrast black fill and white stroke for better visibility.
### Screen Reader (Text-to-Speech)
Built-in TTS using Web Speech API - reads focused element text, alt attributes, and titles.
### Voice Control
Hands-free operation with Web Speech Recognition API. Supports 15+ customizable commands.
### Color Blindness Filters
SVG-based filters for Protanopia (red-blind), Deuteranopia (green-blind), Tritanopia (blue-blind), and Grayscale modes.
### Font Selection
Cycle through Arial (modern sans-serif), Times New Roman (traditional serif), and Verdana (screen-optimized).
## 🚀 Technical Features
- ✅ **Zero Dependencies** - Pure vanilla JavaScript, no frameworks required
- ✅ **Lightweight** - Single file, ~1900 lines minified
- ✅ **Persistent Settings** - localStorage saves user preferences across sessions
- ✅ **Keyboard Accessible** - Full Tab/Arrow key navigation with proper focus management
- ✅ **ARIA Compliant** - Complete ARIA labels and roles for assistive technologies
- ✅ **Performance Optimized** - DOM caching, efficient event delegation, debounced updates
- ✅ **Error Handling** - Graceful degradation for unsupported browser APIs
- ✅ **Responsive Design** - Works seamlessly on desktop, tablet, and mobile
- ✅ **Flexible Positioning** - Left or right side placement with custom offsets
- ✅ **Full i18n Support** - Complete text customization for any language
- ✅ **Dynamic Theming** - Customizable colors with SVG icon color synchronization
- ✅ **Auto-initialization** - Automatically loads when DOM is ready
## 🌐 Browser Compatibility
| Browser | Core Features | Screen Reader | Voice Control |
|---------|---------------|---------------|---------------|
| Chrome 90+ | ✅ | ✅ | ✅ |
| Edge 90+ | ✅ | ✅ | ✅ |
| Firefox 88+ | ✅ | ✅ | ❌ |
| Safari 14+ | ✅ | ✅ | ❌ |
| Opera 76+ | ✅ | ✅ | ✅ |
**Note**: Voice Control requires Web Speech Recognition API (Chromium-based browsers only). Screen Reader requires Web Speech Synthesis API.
## 💡 Usage Examples
### Minimal Implementation
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Accessible Website</title>
</head>
<body>
<h1>Welcome</h1>
<p>This site is fully accessible.</p>
<!-- Add widget - automatically initializes -->
<script src="https://unpkg.com/accessibility-widgets@latest/widget.js"></script>
</body>
</html>
```
### With Custom Configuration
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Custom Accessible Site</title>
</head>
<body>
<h1>Custom Configuration</h1>
<script>
// Configure before loading widget
window.ACCESSIBILITY_WIDGET_CONFIG = {
widgetWidth: '380px',
colors: {
primary: '#9c27b0', // Purple theme
secondary: '#ffffff'
},
enableVoiceControl: false, // Disable voice control
widgetPosition: {
side: 'left',
left: '15px',
bottom: '15px'
}
};
</script>
<script src="https://unpkg.com/accessibility-widgets@latest/widget.js"></script>
</body>
</html>
```
## 🤝 Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
GPL-3.0 License - See [LICENSE](LICENSE) file for details.
## 👨💻 Author
**Sinan Isler**
- Website: [sinan.im](https://sinan.im)
- Email: sinan@sinan.im
- GitHub: [@sinanisler](https://github.com/sinanisler)
## 🌟 Support
- ⭐ Star this repository
- 🐛 [Report bugs](https://github.com/sinanisler/accessibility-widgets/issues)
- ❤️ [Sponsor on GitHub](https://github.com/sponsors/sinanisler)
## 📊 Stats
---
**Made with ❤️ for a more accessible web**