From 1f8b6abf159c5efa379d5c0a841911893aa3fe73 Mon Sep 17 00:00:00 2001 From: sinanisler Date: Mon, 22 Dec 2025 02:04:53 +0300 Subject: [PATCH] Add GitHub Actions workflow for NPM publishing on release creation --- .github/workflows/publish.yml | 30 ++ README.md | 790 ++++++++++++++++++---------------- 2 files changed, 450 insertions(+), 370 deletions(-) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..453e65f --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,30 @@ +name: Publish to NPM + +on: + release: + types: [created] + workflow_dispatch: + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20.x' + registry-url: 'https://registry.npmjs.org' + + - name: Install dependencies + run: npm ci || npm install + + - name: Publish to NPM + run: npm publish --provenance --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/README.md b/README.md index 66483d9..b27b113 100644 --- a/README.md +++ b/README.md @@ -1,202 +1,157 @@ # Accessibility Widgets +[![npm version](https://badge.fury.io/js/accessibility-widgets.svg)](https://www.npmjs.com/package/accessibility-widgets) +[![License: GPL](https://img.shields.io/badge/License-GPL-blue.svg)](https://opensource.org/licenses/GPL-3.0) +[![CDN](https://img.shields.io/badge/CDN-unpkg-orange.svg)](https://unpkg.com/accessibility-widgets) -A comprehensive, lightweight accessibility tool that enhances web accessibility for all users. This single-file JavaScript widget provides multiple accessibility features to make websites more usable for people with disabilities. +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. -![image](https://github.com/user-attachments/assets/2d0e761e-dac5-4319-8a64-970d1b5fe28f) +![Accessibility Widget Demo](https://github.com/user-attachments/assets/2d0e761e-dac5-4319-8a64-970d1b5fe28f) - - -### Feature coverage against WCAG 2.1 AA criteria -> These checks show how each feature aligns with WCAG 2.1 AA success criteria. -> They do **not** by themselves make a site fully compliant with WCAG, EN 301 549 or Section 508. -> To become fully compliant you still need to run a manual checks, fix any underlying HTML/CSS/ARIA issues, test with real users, and re-test every time the site changes. - - - - -| Feature | WCAG AA criterion(s) | EU (EN 301 549 / EAA / WAD) | US (ADA / Section 508) | -|---------|---------------------|-----------------------------|------------------------| -| High Contrast Mode | ✔️ | ✔️ | ✔️ | -| Text Size Adjustment | ✔️ | ✔️ | ✔️ | -| Text Spacing | ✔️ | ✔️ | ✔️ | -| Line Height Adjustment | ✔️ | ✔️ | ✔️ | -| Text Alignment (Left Align) | ✔️ (1.4.8) | ✔️ | ✔️ | -| Cursor Enhancement | ✔️ | ✔️ | ✔️ | -| Pause Animations | ✔️ | ✔️ | ✔️ | -| Reduced Motion | ✔️ | ✔️ | ✔️ | -| Hide Images | ✔️ (1.1.1) | ✔️ | ✔️ | -| Dyslexia-Friendly / Font Select | ✔️ | ✔️ | ✔️ | -| Screen Reader Assist | ✔️ | ✔️ | ✔️ | -| Voice Control | ✔️ (Chrome-only API) | ◑ | ◑ | -| Color-Blindness Filters | ✔️ | ✔️ | ✔️ | - - - - - - -## Features - -### Core Accessibility Features - -#### **High Contrast Mode** -Provides three levels of contrast enhancement: -- **Medium**: 1.3x contrast boost for subtle improvement -- **High**: Black background with white text and 1.5x contrast -- **Ultra**: Black background with yellow text and 2.0x contrast for maximum visibility - -How it works: Applies CSS filters and background/text color overrides while preserving the widget's own styling. - -#### **Text Size Adjustment** -Offers four text size options: -- **Default**: Original website text size -- **Medium**: 20px font size for all text elements -- **Large**: 24px font size for improved readability -- **X-Large**: 28px font size for maximum accessibility - -How it works: Uses CSS to override font-size properties across all page elements while excluding the widget interface. - -#### **Text Spacing** -Enhances text readability by adding: -- **Letter spacing**: 0.2em between characters -- **Word spacing**: 0.3em between words - -How it works: Applies CSS letter-spacing and word-spacing properties to all text elements except the widget interface. - -#### **Animation Control** -Completely stops all animations and transitions on the page. - -How it works: Uses CSS to disable all `animation` and `transition` properties, helping users with vestibular disorders or attention difficulties. - -#### **Image Hiding** -Removes all images from the page for users who prefer text-only content or have slow connections. - -How it works: Sets `display: none` on all `` elements. The system caches image queries for performance and updates every 5 seconds to catch dynamically loaded images. - -#### **Dyslexia-Friendly Font** -Replaces all fonts with dyslexia-friendly alternatives: -- Primary: Comic Sans MS (widely available dyslexia-friendly font) -- Fallbacks: Chalkboard SE, Bradley Hand, Brush Script MT, fantasy - -How it works: Overrides the font-family CSS property for all elements on the page. - -#### **Cursor Enhancement** -Provides a larger, high-contrast cursor for better visibility. - -How it works: Uses a custom SVG cursor (48x72px) with black fill and white stroke, applied via CSS cursor property. - -#### **Line Height Adjustment** -Increases line spacing to 2.5x normal for improved readability. - -How it works: Applies CSS `line-height: 2.5` to all text elements except the widget interface. - -#### **Text Alignment** -Provides three alignment options: -- **Left**: Forces left alignment for consistent reading flow -- **Center**: Centers all text for specific user preferences -- **Right**: Right-aligns all text - -How it works: Uses CSS `text-align` property override for all text elements. - -### Advanced Features - -#### **Screen Reader Support** -Built-in text-to-speech functionality that reads focused elements aloud. - -How it works: Uses the Web Speech API's SpeechSynthesis interface. When enabled, it listens for `focusin` events and speaks the text content, alt text, or title of focused elements. Includes error handling for unsupported browsers. - -#### **Voice Control** -Voice commands to control accessibility features hands-free. - -How it works: Uses the Web Speech API's SpeechRecognition interface. Continuously listens for voice commands and maps them to widget functions. Includes retry logic for reliability and graceful degradation for unsupported browsers. - -Supported commands: -- "show menu" / "open menu" - Opens accessibility menu -- "high contrast" - Cycles through contrast levels -- "bigger text" - Cycles through text sizes -- "text spacing" - Toggles text spacing -- "pause animations" - Toggles animation control -- "hide images" - Toggles image visibility -- "dyslexia font" - Toggles dyslexia-friendly font -- "bigger cursor" - Toggles cursor enhancement -- "screen reader" - Toggles screen reader -- "reset all" - Resets all settings - -#### **Reduced Motion** -Disables all animations and transitions for users with motion sensitivity. - -How it works: Similar to Animation Control but specifically targets motion-related CSS properties including pseudo-elements (::before, ::after). - -#### **Font Selection** -Cycle through three professional font options: -- **Arial**: Sans-serif, high readability -- **Times New Roman**: Serif, traditional -- **Verdana**: Sans-serif, designed for screen reading - -How it works: Applies font-family overrides via CSS classes, cycling through options when activated. - -#### **Color Blindness Filters** -Provides specialized filters for different types of color blindness: -- **Protanopia**: Red-blind color correction -- **Deuteranopia**: Green-blind color correction -- **Tritanopia**: Blue-blind color correction -- **Grayscale**: Complete color removal - -How it works: Uses SVG filters with color matrix transformations applied via CSS filter property to the entire document. - -## Installation - -### Method 1: Direct Download -1. Download the `widget.js` file -2. Include it in your HTML page: +## ⚡ Quick Start ```html - + + ``` -### Method 2: NPM +Or install via NPM: + ```bash npm install accessibility-widgets ``` -### Method 3: CDN +```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 + + + + + +``` + +### 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 + +``` + +## ⚙️ Configuration + +### Basic Setup (No Configuration Needed) +The widget works out of the box with zero configuration: + ```html ``` -That's it! The widget will automatically initialize when the page loads. +### Custom Configuration +Customize the widget by defining `window.ACCESSIBILITY_WIDGET_CONFIG` before loading the script: -## Configuration - -The widget is highly customizable. You can override the default settings by defining `window.ACCESSIBILITY_WIDGET_CONFIG` before loading the widget script. - -### Basic Configuration ```html ``` -### Complete Configuration Options -```html - - ``` -### Partial Configuration -You only need to specify the settings you want to change. The widget will merge your settings with the defaults: +## 🌍 Internationalization (i18n) +Full multilingual support - customize all text and voice commands: + +### Spanish Example ```html - -``` - -### Widget Positioning -The widget can be positioned on either side of the screen: - -```html - -``` - -### Internationalization (i18n) -The widget supports full internationalization. You can customize all text strings and voice commands: - -```html - -``` - -## Voice Commands - -When voice control is enabled, users can activate features using these commands (default English commands shown - fully customizable via `voiceCommands` configuration): - -- "show menu" / "open menu" / "accessibility menu" - Opens the accessibility menu -- "high contrast" - Toggles high contrast mode -- "bigger text" / "large text" - Toggles larger text size -- "text spacing" - Toggles text spacing -- "pause animations" / "stop animations" - Toggles animation pausing -- "hide images" - Toggles image hiding -- "dyslexia friendly" / "dyslexia font" - Toggles dyslexia-friendly font -- "bigger cursor" / "large cursor" - Toggles larger cursor -- "line height" - Toggles line height adjustment -- "align text" / "text align" - Cycles through text alignment options -- "screen reader" - Toggles screen reader -- "voice command" / "voice control" - Toggles voice control -- "reset all" / "reset everything" - Resets all accessibility settings - -**Note:** All voice commands can be customized for different languages using the `voiceCommands` configuration option. - -## Browser Compatibility - -- **Modern Browsers**: Full functionality in Chrome, Firefox, Safari, Edge -- **Screen Reader**: Requires Speech Synthesis API support -- **Voice Control**: Requires Speech Recognition API support -- **Graceful Degradation**: Features that aren't supported are automatically disabled - -## Technical Features - -- **Single File Deployment** - No dependencies, just include one JavaScript file -- **Persistent Settings** - User preferences saved in localStorage -- **Keyboard Navigation** - Full keyboard accessibility with Tab, Arrow keys, and Escape -- **ARIA Compliance** - Proper ARIA labels and roles for screen readers -- **Performance Optimized** - DOM caching and efficient event handling -- **Error Handling** - Robust error handling for browser compatibility -- **Responsive Design** - Works on desktop and mobile devices -- **Flexible Positioning** - Support for left/right side positioning -- **Full Internationalization** - Complete text customization for any language -- **Configurable Colors** - Dynamic color theming including SVG icon colors -- **Screen Reader Optimized** - Proper text labels for all interactive elements - -## Usage Examples - -### Basic Implementation -```html - - - - My Accessible Website - - -

Welcome to My Website

-

This site includes accessibility features.

- - - - - -``` - -### Custom Configuration -```html - ``` + +## 🎤 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 + + + + + My Accessible Website + + +

Welcome

+

This site is fully accessible.

+ + + + + +``` + +### With Custom Configuration +```html + + + + + Custom Accessible Site + + +

Custom Configuration

+ + + + + +``` + +### NPM/Module Usage +```javascript +// main.js +import 'accessibility-widgets/widget.js'; + +// Optional: Configure before import +window.ACCESSIBILITY_WIDGET_CONFIG = { + enableVoiceControl: false, + widgetWidth: '400px' +}; + +// Widget auto-initializes +``` + +### React/Vue/Angular Integration +```javascript +// App.jsx (React) +import { useEffect } from 'react'; + +function App() { + useEffect(() => { + // Configure widget + window.ACCESSIBILITY_WIDGET_CONFIG = { + colors: { primary: '#4caf50' } + }; + + // Load widget script + const script = document.createElement('script'); + script.src = 'https://unpkg.com/accessibility-widgets@latest/widget.js'; + script.async = true; + document.body.appendChild(script); + + return () => { + // Cleanup if needed + document.body.removeChild(script); + }; + }, []); + + return
Your App Content
; +} +``` + +## 🛠️ Development + +```bash +# Clone repository +git clone https://github.com/sinanisler/accessibility-widgets.git +cd accessibility-widgets + +# Install dependencies (optional) +npm install + +# Start local server +npm run dev +# Opens http://localhost:8000 +``` + +## 📦 NPM Publishing Setup + +After setting up your NPM account: + +1. **Create NPM Token**: + ```bash + npm login + npm token create + ``` + +2. **Add to GitHub Secrets**: + - Go to your repository Settings → Secrets and variables → Actions + - Create new secret: `NPM_TOKEN` + - Paste your NPM token + +3. **Publish**: + ```bash + # Manual publish + npm publish + + # Or create GitHub release to trigger workflow + git tag v2.0.0 + git push origin v2.0.0 + ``` + +The GitHub Actions workflow will automatically publish to NPM on new releases. + +## 🤝 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) +- 💡 [Request features](https://github.com/sinanisler/accessibility-widgets/issues) +- ❤️ [Sponsor on GitHub](https://github.com/sponsors/sinanisler) + +## 📊 Stats + +![GitHub stars](https://img.shields.io/github/stars/sinanisler/accessibility-widgets?style=social) +![npm downloads](https://img.shields.io/npm/dm/accessibility-widgets) +![GitHub issues](https://img.shields.io/github/issues/sinanisler/accessibility-widgets) +![GitHub license](https://img.shields.io/github/license/sinanisler/accessibility-widgets) + +--- + +**Made with ❤️ for a more accessible web**