gbu-accessibility-package 1.5.0 → 3.0.0

package/README.md

@@ -9,6 +9,7 @@
 ## ✨ Features
 
 - 🖼️ **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
 - 🧹 **Duplicate Cleanup** - Remove duplicate role attributes
@@ -32,7 +33,7 @@ npm install gbu-accessibility-package
 ### Basic Usage
 
 ```bash
-# Fix current directory
+# Comprehensive fixes (default mode)
 gbu-a11y
 
 # Preview changes (dry run)
@@ -41,9 +42,6 @@ gbu-a11y --dry-run
 # Fix specific directory
 gbu-a11y ./src
 
-# Comprehensive fixes (recommended)
-gbu-a11y --comprehensive
-
 # Fix specific file
 gbu-a11y index.html
 ```
@@ -58,13 +56,14 @@ gbu-a11y [options] [directory/file]
 Options:
   -d, --directory <path>    Target directory (default: current directory)
   -l, --language <lang>     Language for lang attribute (default: ja)
+  --backup                 Create backup files (default: enabled)
   --no-backup              Don't create backup files
   --dry-run                Preview changes without applying
-  --comprehensive, --all   Run all fixes including cleanup (recommended)
+  --comprehensive, --all   Run comprehensive fixes (same as default)
   --cleanup-only           Only cleanup duplicate role attributes
-  --alt-only               Only fix alt attributes for images
-  --lang-only              Only fix HTML lang attributes
-  --role-only              Only fix role attributes
+  --alt-only               Fix alt attributes + cleanup
+  --lang-only              Fix HTML lang attributes + cleanup
+  --role-only              Fix role attributes + cleanup
   -h, --help               Show help message
 ```
 
@@ -74,44 +73,45 @@ Options:
 # Basic fixes for current directory (all standard fixes)
 gbu-a11y
 
-# Preview all changes
-gbu-a11y --dry-run --comprehensive
+# Preview all changes (comprehensive by default)
+gbu-a11y --dry-run
 
 # Fix with English language
 gbu-a11y -l en ./public
 
-# Individual fix types
-gbu-a11y --alt-only          # Only fix alt attributes
-gbu-a11y --lang-only         # Only fix lang attributes  
-gbu-a11y --role-only         # Only fix role attributes
+# Individual fix types (all include cleanup)
+gbu-a11y --alt-only          # Fix alt attributes + cleanup
+gbu-a11y --lang-only         # Fix lang attributes + cleanup
+gbu-a11y --role-only         # Fix role attributes + cleanup
 gbu-a11y --cleanup-only      # Only cleanup duplicates
 
 # Combine with other options
-gbu-a11y --alt-only --dry-run ./src    # Preview alt fixes only
-gbu-a11y --role-only -l en ./public    # Fix roles with English lang
+gbu-a11y --alt-only --dry-run ./src    # Preview alt fixes + cleanup
+gbu-a11y --role-only -l en ./public    # Role fixes + cleanup with English lang
 
-# Fix without creating backups
-gbu-a11y --no-backup ./dist
+# Backup options
+gbu-a11y --backup ./dist             # Explicitly enable backups (default)
+gbu-a11y --no-backup ./dist          # Disable backups for faster processing
 ```
 
 ## 🔧 Programmatic Usage
 
 ```javascript
-const AccessibilityFixer = require('gbu-accessibility-package');
+const AccessibilityFixer = require("gbu-accessibility-package");
 
 const fixer = new AccessibilityFixer({
-  language: 'en',
+  language: "en",
   backupFiles: true,
-  dryRun: false
+  dryRun: false,
 });
 
 // Fix all accessibility issues
 async function fixAccessibility() {
   try {
-    const results = await fixer.fixAllAccessibilityIssues('./src');
-    console.log('Fixed files:', results);
+    const results = await fixer.fixAllAccessibilityIssues("./src");
+    console.log("Fixed files:", results);
   } catch (error) {
-    console.error('Error:', error);
+    console.error("Error:", error);
   }
 }
 
@@ -121,14 +121,16 @@ fixAccessibility();
 ## 🎯 Fix Modes
 
 ### Individual Fix Options
+
 You can now fix specific accessibility issues individually:
 
 - `--alt-only` - Only fix alt attributes for images
-- `--lang-only` - Only fix HTML lang attributes  
+- `--lang-only` - Only fix HTML lang attributes
 - `--role-only` - Only fix role attributes
 - `--cleanup-only` - Only cleanup duplicate role attributes
 
 ### Combined Modes
+
 - **Standard mode** (default) - Fixes alt, lang, and role attributes
 - `--comprehensive` - All fixes including duplicate cleanup
 
@@ -152,36 +154,41 @@ gbu-a11y --comprehensive
 ## 🔧 What Gets Fixed
 
 ### 1. Alt Attributes
+
 - **Missing alt attributes** → Adds contextual alt text
 - **Empty alt attributes** → Generates meaningful descriptions
 - **Context-aware generation** → Uses surrounding text, headings, captions
 
 ```html
 <!-- Before -->
-<img src="logo.png">
-<img src="chart.jpg" alt="">
+<img src="logo.png" />
+<img src="chart.jpg" alt="" />
 
 <!-- After -->
-<img src="logo.png" alt="ロゴ">
-<img src="chart.jpg" alt="グラフ">
+<img src="logo.png" alt="ロゴ" />
+<img src="chart.jpg" alt="グラフ" />
 ```
 
 ### 2. HTML Lang Attributes
+
 - **Missing lang attributes** → Adds specified language
 - **Empty lang attributes** → Sets proper language code
 
 ```html
 <!-- Before -->
 <html>
-<html lang="">
-
-<!-- After -->
-<html lang="ja">
-<html lang="ja">
+  <html lang="">
+    <!-- After -->
+    <html lang="ja">
+      <html lang="ja"></html>
+    </html>
+  </html>
+</html>
 ```
 
-### 3. Role Attributes
-- **Images** → `role="img"`
+### 3. Role Attributes & Aria Labels
+
+- **Images** → `role="img"` + `aria-label` (matching alt text)
 - **Picture elements** → Moves `role="img"` from `<picture>` to `<img>` inside
 - **Links** → `role="link"`
 - **Clickable elements** → `role="button"`
@@ -190,33 +197,48 @@ gbu-a11y --comprehensive
 
 ```html
 <!-- Before -->
-<img src="icon.png" alt="Icon">
+<img src="icon.png" alt="Icon" />
 <picture role="img">
-  <img src="photo.jpg" alt="Photo">
+  <img src="photo.jpg" alt="Photo" />
 </picture>
 <a href="/home">Home</a>
 <div class="btn-click">Click me</div>
 
 <!-- After -->
-<img src="icon.png" alt="Icon" role="img">
+<img src="icon.png" alt="Icon" role="img" aria-label="Icon" />
 <picture>
-  <img src="photo.jpg" alt="Photo" role="img">
+  <img src="photo.jpg" alt="Photo" role="img" aria-label="Photo" />
 </picture>
 <a href="/home" role="link">Home</a>
 <div class="btn-click" role="button">Click me</div>
 ```
 
-### 4. Duplicate Cleanup
+### 4. Aria Label Enhancement
+
+- **Automatic aria-label** → Adds `aria-label` matching `alt` text for images
+- **Preserves existing** → Won't override existing `aria-label` attributes
+- **Smart detection** → Only adds when `alt` text exists and is not empty
+
+```html
+<!-- Before -->
+<img src="chart.jpg" alt="Sales Chart" />
+
+<!-- After -->
+<img src="chart.jpg" alt="Sales Chart" role="img" aria-label="Sales Chart" />
+```
+
+### 5. Duplicate Cleanup
+
 - **Removes duplicate role attributes**
 - **Preserves first occurrence**
 - **Handles mixed quote styles**
 
 ```html
 <!-- Before -->
-<img src="test.jpg" role="img" role="img" alt="Test">
+<img src="test.jpg" role="img" role="img" alt="Test" />
 
 <!-- After -->
-<img src="test.jpg" role="img" alt="Test">
+<img src="test.jpg" role="img" alt="Test" />
 ```
 
 ## 🌟 Smart Alt Text Generation
@@ -224,8 +246,9 @@ gbu-a11y --comprehensive
 The package uses intelligent context analysis to generate meaningful alt text:
 
 ### Context Sources
+
 1. **Title attributes**
-2. **Aria-label attributes**  
+2. **Aria-label attributes**
 3. **Definition terms (dt elements)**
 4. **Parent link text**
 5. **Nearby headings**
@@ -233,6 +256,7 @@ The package uses intelligent context analysis to generate meaningful alt text:
 7. **Surrounding text content**
 
 ### Fallback Patterns
+
 - `logo.png` → "ロゴ" (Logo)
 - `icon.svg` → "アイコン" (Icon)
 - `banner.jpg` → "バナー" (Banner)
@@ -242,6 +266,7 @@ The package uses intelligent context analysis to generate meaningful alt text:
 ## 📊 Output Examples
 
 ### Standard Mode
+
 ```
 🚀 Starting Accessibility Fixer...
 📝 Step 1: Fixing HTML lang attributes...
@@ -250,7 +275,7 @@ The package uses intelligent context analysis to generate meaningful alt text:
 🖼️ Step 2: Fixing alt attributes...
 ✅ Fixed alt attributes in 12 files (34 issues)
 
-🎭 Step 3: Fixing role attributes...  
+🎭 Step 3: Fixing role attributes...
 ✅ Fixed role attributes in 8 files (67 issues)
 
 📊 Summary:
@@ -262,6 +287,7 @@ The package uses intelligent context analysis to generate meaningful alt text:
 ```
 
 ### Comprehensive Mode
+
 ```
 🎯 Running comprehensive accessibility fixes...
 📝 Step 1: HTML lang attributes...
@@ -272,14 +298,32 @@ The package uses intelligent context analysis to generate meaningful alt text:
 🎉 All accessibility fixes completed!
 📊 Final Summary:
    Total files scanned: 25
-   Files fixed: 15  
+   Files fixed: 15
    Total issues resolved: 106
 ```
 
 ## 🔒 Safety Features
 
-- **Automatic backups** with `.backup` extension
-- **Dry run mode** for safe previewing
+### Backup Options
+
+- **Default behavior**: Creates `.backup` files automatically for safety
+- **Disable backups**: Use `--no-backup` for faster processing
+- **Explicit enable**: Use `--backup` to be explicit about backup creation
+
+```bash
+# Safe mode (default) - creates backups
+gbu-a11y --comprehensive
+
+# Fast mode - no backups
+gbu-a11y --no-backup --comprehensive
+
+# Explicit backup mode
+gbu-a11y --backup --comprehensive
+```
+
+### Other Safety Features
+
+- **Dry run mode** for safe previewing with `--dry-run`
 - **Non-destructive** - only adds missing attributes
 - **Duplicate prevention** - won't add existing attributes
 - **Error handling** - continues processing on individual file errors
@@ -287,6 +331,7 @@ The package uses intelligent context analysis to generate meaningful alt text:
 ## 🛠️ Configuration
 
 ### Package.json Scripts
+
 ```json
 {
   "scripts": {
@@ -295,19 +340,20 @@ The package uses intelligent context analysis to generate meaningful alt text:
     "a11y:comprehensive": "gbu-a11y --comprehensive",
     "a11y:cleanup": "gbu-a11y --cleanup-only",
     "a11y:alt": "gbu-a11y --alt-only",
-    "a11y:lang": "gbu-a11y --lang-only", 
+    "a11y:lang": "gbu-a11y --lang-only",
     "a11y:role": "gbu-a11y --role-only"
   }
 }
 ```
 
 ### CI/CD Integration
+
 ```yaml
 # GitHub Actions example
 - name: Check Accessibility
   run: npx gbu-accessibility-package --dry-run
 
-- name: Fix Accessibility Issues  
+- name: Fix Accessibility Issues
   run: npx gbu-accessibility-package --comprehensive
 ```
 
@@ -340,4 +386,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-Made with ❤️ by the GBU Team
+Made with ❤️ by the GBU Team