dangpv94GBU Accessibility Package
🚀 Automated accessibility fixes for HTML files - Smart, context-aware accessibility improvements with zero configuration.
✨ Features
🎯 Core Accessibility Fixes
- 🖼️ Smart Alt Text Generation - Context-aware alt attributes for images
- 🏷️ Aria Label Support - Automatic aria-label matching alt text
- 🌐 HTML Lang Attributes - Automatic language attribute fixes
- 🎭 Role Attributes - WCAG-compliant role attribute management
- 📋 Form Labels - Fix missing labels with intelligent aria-label generation
- 🔘 Button Names - Fix empty buttons and input buttons without names
- 🔗 Link Names - Fix empty links and detect generic link text
- 🏛️ Landmarks - Add missing main and navigation landmarks
- 📑 Heading Analysis & Auto-Fix - Analyze heading structure with optional auto-fix using
--auto-fix-headings - 🎯 Nested Controls Detection - Detect and fix nested interactive controls
- 🔍 Broken Links Detection - Detect broken links and 404 resources
- 🧹 Duplicate Cleanup - Remove duplicate role attributes
🚀 Enhanced Alt Attribute Features (Integrated!)
- 🔍 Comprehensive Analysis - Image type classification and quality checking built-in
- 🎨 Diverse Alt Generation - Multiple strategies for creative alt text integrated in core
- 🌐 Multi-language Support - Japanese, English, Vietnamese vocabulary built-in
- 🎭 Creativity Levels - Conservative, Balanced, Creative modes
- 🧠 Context Awareness - Brand, emotional, and technical context integration
- 📊 Data Visualization - Specialized descriptions for charts and graphs
- 🧹 Clean Architecture - All enhanced features integrated in a single file
🛠️ Utility Features
- 📁 Batch Processing - Process entire directories recursively
- 💾 Optional Backups - Create backup files when needed with --backup flag
- 🔍 Dry Run Mode - Preview changes before applying
- 📊 Detailed Reports - Comprehensive fix summaries
- ⚡ Individual Fix Modes - Target specific accessibility issues
🚀 Quick Start
Installation
# Global installation (recommended)
npm install -g gbu-accessibility-package
# Local installation
npm install gbu-accessibility-packageUninstall and Reinstall
# Uninstall global package
npm uninstall -g gbu-accessibility-package
# Uninstall local package
npm uninstall gbu-accessibility-package
# Clear npm cache (recommended when having issues)
npm cache clean --force
# Reinstall latest version
npm install -g gbu-accessibility-package@latest
# Check installed version
npm list -g gbu-accessibility-package
gbu-a11y --version
# Install specific version
npm install -g gbu-accessibility-package@3.2.1Installation Troubleshooting
# If permission errors (macOS/Linux)
sudo npm install -g gbu-accessibility-package
# If cache issues
npm cache clean --force
npm install -g gbu-accessibility-package --force
# Verify installation
which gbu-a11y
gbu-a11y --help
# Update to latest version
npm update -g gbu-accessibility-packageBasic Usage
# Comprehensive fixes (default mode)
gbu-a11y
# Preview changes (dry run)
gbu-a11y --dry-run
# Fix specific directory
gbu-a11y ./src
# Fix specific file
gbu-a11y index.htmlEnhanced Alt Attribute Mode
# Enable enhanced alt attribute analysis
gbu-a11y --enhanced-alt
# Creative alt text generation with emotions
gbu-a11y --enhanced-alt --alt-creativity creative --include-emotions
# Strict quality checking
gbu-a11y --enhanced-alt --strict-alt
# English with creative mode
gbu-a11y -l en --enhanced-alt --alt-creativity creative📖 Detailed Usage
Command Line Options
gbu-a11y [options] [directory/file]
Basic Options:
-d, --directory <path> Target directory (default: current directory)
-l, --language <lang> Language for lang attribute (default: ja)
--backup Create backup files
--no-backup Don't create backup files (default)
--dry-run Preview changes without applying
Fix Modes:
--comprehensive, --all Run comprehensive fixes (default)
--alt-only Fix alt attributes + cleanup
--lang-only Fix HTML lang attributes + cleanup
--role-only Fix role attributes + cleanup
--forms-only Fix form labels + cleanup
--buttons-only Fix button names + cleanup
--links-only Fix link names + cleanup
--landmarks-only Fix landmarks + cleanup
--headings-only Analyze heading structure with optional auto-fix
--auto-fix-headings Enable automatic heading structure fixes
--links-check Check for broken links and 404 resources
--cleanup-only Only cleanup duplicate role attributes
Enhanced Alt Options:
--enhanced-alt Use enhanced alt attribute analysis and generation
--alt-creativity <mode> Alt text creativity: conservative, balanced, creative
--include-emotions Include emotional descriptors in alt text
--strict-alt Enable strict alt attribute quality checking
Help:
-h, --help Show help messageExamples
# Basic comprehensive fixes
gbu-a11y
# Preview all changes
gbu-a11y --dry-run
# Fix with English language
gbu-a11y -l en ./public
# Individual fix types
gbu-a11y --alt-only # Fix alt attributes + cleanup
gbu-a11y --forms-only # Fix form labels + cleanup
gbu-a11y --buttons-only # Fix button names + cleanup
gbu-a11y --headings-only # Analyze heading structure
gbu-a11y --headings-only --auto-fix-headings # Auto-fix heading structure
gbu-a11y --links-check # Check broken links + cleanup
# Enhanced alt attribute features
gbu-a11y --enhanced-alt # Basic enhanced mode
gbu-a11y --enhanced-alt --alt-creativity creative # Creative descriptions
gbu-a11y --enhanced-alt --include-emotions # Include emotional context
gbu-a11y --enhanced-alt --strict-alt # Strict quality checking
gbu-a11y -l en --enhanced-alt --alt-creativity creative # English creative mode
# Combine with other options
gbu-a11y --enhanced-alt --backup ./src # Enhanced mode with backups
gbu-a11y --enhanced-alt --dry-run # Preview enhanced fixes🎨 Enhanced Alt Attribute Features
Creativity Levels
Conservative
- Simple, factual descriptions
- Focus on basic functionality
- Minimal vocabulary variation
Example: alt="Chart", alt="Logo"
Balanced (Default)
- Context-aware descriptions
- Moderate creativity
- Balance between simple and detailed
Example: alt="Sales performance chart", alt="Company logo"
Creative
- Rich, detailed descriptions
- Emotional context integration
- High brand and context awareness
Example: alt="Dynamic sales performance chart showing impressive 25% quarterly growth", alt="Innovative technology company logo representing digital transformation"
Image Type Classification
- Decorative Images: Automatically detected and marked with
alt="" - Functional Icons: Described by their action (e.g., "Open chat", "Search")
- Data Visualizations: Include chart type, trends, and key data points
- Complex Images: Short alt + recommendation for detailed description
- Logos: Include brand name and "logo" keyword
- Content Images: Context-aware descriptions based on surrounding content
Quality Checks
- ❌ Error Level: Missing alt, empty alt for content, generic text
- ⚠️ Warning Level: Too long/short, redundant words, filename in alt
- ℹ️ Info Level: Optimization suggestions, consistency checks
📋 Programmatic Usage
Basic Usage
const { AccessibilityFixer } = require('gbu-accessibility-package');
const fixer = new AccessibilityFixer({
language: 'ja',
backupFiles: true,
dryRun: false
});
// Fix all accessibility issues
fixer.fixAllAccessibilityIssues('./src').then(results => {
console.log('Accessibility fixes completed:', results);
});
// Fix specific issues
await fixer.fixEmptyAltAttributes('./src');
await fixer.fixFormLabels('./src');
await fixer.fixButtonNames('./src');Enhanced Alt Attribute Mode (Integrated)
const { AccessibilityFixer } = require('gbu-accessibility-package');
// Use AccessibilityFixer with enhanced mode (integrated)
const fixer = new AccessibilityFixer({
language: 'en',
enhancedAltMode: true,
altCreativity: 'creative',
includeEmotions: true,
strictAltChecking: true
});
await fixer.fixEmptyAltAttributes('./src');
// All enhanced features are now integrated in AccessibilityFixer
// No need to import separate classes
const results = await fixer.fixAllAccessibilityIssues('./src');
console.log('Accessibility fixes completed with enhanced features:', results);🎯 What Gets Fixed
Alt Attributes (Enhanced Mode)
- Missing alt attributes → Context-aware alt text generation
- Empty alt attributes → Smart content-based descriptions
- Generic alt text → Specific, meaningful descriptions
- Too long alt text → Optimized length with key information
- Redundant words → Clean, concise descriptions
- Data visualizations → Chart type + trends + key data
Form Accessibility
- Missing form labels → Intelligent aria-label generation
- Unlabeled inputs → Context-based label suggestions
- Form structure → Proper label associations
Interactive Elements
- Empty buttons → Action-based button names
- Generic link text → Descriptive link purposes
- Missing button names → Function-based descriptions
Document Structure
- Missing lang attributes → Automatic language detection
- Missing landmarks → Main and navigation landmarks
- Heading structure → Analysis and auto-fix with
--auto-fix-headings- Fix multiple h1 elements
- Fix heading level skipping (h2 → h4)
- Add text to empty headings
- Fix duplicate headings
- Nested interactive controls → Detect and fix nested controls
- Role attributes → WCAG-compliant role assignments
Link Validation
- Broken links → Detect HTTP 404, 500, timeout errors
- Missing resources → Check for missing local files
- Invalid URLs → Detect malformed URL formats
- Slow links → Warn about timeouts and slow responses
🔧 Package Management
Check package information
# Check current version
gbu-a11y --version
npm list -g gbu-accessibility-package
# View package info
npm info gbu-accessibility-package
# Verify installation
which gbu-a11y
npm list -g | grep gbu-accessibility-packageUpdate package
# Check for new versions
npm outdated -g gbu-accessibility-package
# Update to latest version
npm update -g gbu-accessibility-package
# Or reinstall latest version
npm uninstall -g gbu-accessibility-package
npm install -g gbu-accessibility-package@latestCache management
# Verify cache
npm cache verify
# Clean cache (when having issues)
npm cache clean --force
# View cache location
npm config get cache🧪 Testing and Demo
# Test the package
npm test
# Demo basic features
npm run demo
# Demo enhanced alt features
npm run demo-enhanced
# Demo creative alt generation
npm run demo-creative
# Test enhanced alt features
npm run test-enhanced-alt📊 Performance
- Basic Mode: Fast processing, suitable for large projects
- Enhanced Mode: ~20-30% slower but 85-90% improvement in alt text quality
- Memory Usage: +15-20% for enhanced vocabulary and analysis
- Accuracy: 95%+ detection of accessibility issues
🌐 Language Support
- Japanese (ja): Default language with rich vocabulary
- English (en): Comprehensive English support
- Vietnamese (vi): Vietnamese language support
Enhanced alt features include language-specific vocabulary and grammar rules for natural, contextually appropriate descriptions.
📚 Documentation
- Enhanced Alt Features Guide - Detailed documentation for enhanced alt attribute features
- Quick Start Guide - Get started quickly
- Package Summary - Overview of all features
- Changelog - Version history and updates
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Development Setup
git clone https://github.com/dangpv94/gbu-accessibility-tool.git
cd gbu-accessibility-tool/accessibility-package
npm install
npm test📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Built with accessibility best practices in mind
- Follows WCAG guidelines
- Inspired by the need for automated accessibility improvements
- Community feedback and contributions
Made with ❤️ by the GBU Team
For more information, visit our GitHub repository.