sinanisler
444 lines
14 KiB
Markdown
444 lines
14 KiB
Markdown
# Accessibility Widgets
|
|
|
|
[](https://www.npmjs.com/package/accessibility-widgets)
|
|
[](https://opensource.org/licenses/GPL-3.0)
|
|
[](https://unpkg.com/accessibility-widgets)
|
|
|
|
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.
|
|
|
|
<img width="1280" height="963" alt="image" src="https://github.com/user-attachments/assets/3effb334-03f7-4e63-b831-421d69d991b2" />
|
|
|
|
|
|
## ⚡ 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 | ✅ | ✅ |
|
|
|
|
> **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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 🎯 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 = {
|
|
// ===== Feature Toggles =====
|
|
enableHighContrast: true,
|
|
enableBiggerText: true,
|
|
enableTextSpacing: true,
|
|
enablePauseAnimations: true,
|
|
enableHideImages: true,
|
|
enableDyslexiaFont: true,
|
|
enableBiggerCursor: true,
|
|
enableLineHeight: true,
|
|
enableTextAlign: true,
|
|
enableScreenReader: true,
|
|
enableVoiceControl: true,
|
|
enableFontSelection: true,
|
|
enableColorFilter: true,
|
|
|
|
// ===== Widget Layout =====
|
|
widgetWidth: '440px',
|
|
widgetColumns: 2, // Grid columns (1-4)
|
|
|
|
// ===== Position =====
|
|
widgetPosition: {
|
|
side: 'right', // 'left' or 'right'
|
|
right: '20px',
|
|
left: '20px',
|
|
bottom: '20px'
|
|
},
|
|
|
|
// ===== Colors =====
|
|
colors: {
|
|
primary: '#1663d7',
|
|
secondary: '#ffffff',
|
|
optionBg: '#ffffff',
|
|
optionText: '#333333',
|
|
optionIcon: '#000000'
|
|
},
|
|
|
|
// ===== Button Styling =====
|
|
button: {
|
|
size: '55px',
|
|
borderRadius: '100px',
|
|
iconSize: '40px',
|
|
shadow: '0 4px 8px rgba(0, 0, 0, 0.2)'
|
|
},
|
|
|
|
// ===== Typography =====
|
|
typography: {
|
|
fontFamily: 'Arial, sans-serif',
|
|
fontSize: '17px',
|
|
titleFontSize: '22px',
|
|
titleFontWeight: '700'
|
|
},
|
|
|
|
// ===== Internationalization (i18n) =====
|
|
lang: {
|
|
accessibilityMenu: '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'
|
|
},
|
|
|
|
// ===== Voice Commands =====
|
|
voiceCommands: {
|
|
showMenu: ['show menu', 'open menu'],
|
|
highContrast: ['high contrast'],
|
|
biggerText: ['bigger text', 'large text'],
|
|
textSpacing: ['text spacing'],
|
|
pauseAnimations: ['pause animations'],
|
|
hideImages: ['hide images'],
|
|
dyslexiaFont: ['dyslexia font'],
|
|
biggerCursor: ['bigger cursor'],
|
|
screenReader: ['screen reader'],
|
|
resetAll: ['reset all', 'reset everything']
|
|
}
|
|
};
|
|
```
|
|
|
|
## 🌍 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**
|