gbu-accessibility-package
Version:
Comprehensive accessibility fixes for HTML files. Smart context-aware alt text generation, form labels, button names, link names, landmarks, heading analysis, and WCAG-compliant role attributes. Covers major axe DevTools issues with individual fix modes.
192 lines (136 loc) • 4.46 kB
Markdown
# 📦 Accessibility Fixer Package - Summary
## 🎯 Mục đích
Tool tự động sửa các vấn đề accessibility phổ biến trong HTML files, giúp website tuân thủ WCAG guidelines.
## 📁 Cấu trúc Package
```
accessibility-package/
├── lib/
│ └── fixer.js # Core logic
├── demo/
│ └── sample.html # File demo để test
├── cli.js # Command line interface
├── example.js # Ví dụ sử dụng
├── package.json # Package configuration
├── README.md # Hướng dẫn đầy đủ
├── QUICK_START.md # Hướng dẫn nhanh
└── PACKAGE_SUMMARY.md # File này
```
## ✨ Tính năng chính
### 1. Alt Attributes
- ✅ Tự động thêm alt text cho images thiếu
- ✅ Sửa empty alt attributes
- ✅ Context-aware: phân tích nội dung xung quanh để tạo alt text phù hợp
- ✅ Hỗ trợ nhiều ngôn ngữ (ja, en, vi, zh, etc.)
### 2. Lang Attributes
- ✅ Thêm lang attribute cho thẻ `<html>`
- ✅ Configurable language
### 3. Role Attributes
- ✅ `role="img"` cho tất cả thẻ `<img>`
- ✅ `role="link"` cho thẻ `<a>`
- ✅ `role="button"` cho elements có onclick
- ✅ `role="menubar"` và `role="menuitem"` cho navigation
- ✅ Tự động detect clickable elements
## 🚀 Cách sử dụng
### Option 1: CLI (Đơn giản)
```bash
node accessibility-package/cli.js
```
### Option 2: Node.js
```javascript
const AccessibilityFixer = require("./accessibility-package/lib/fixer.js");
const fixer = new AccessibilityFixer({ language: "ja" });
await fixer.fixRoleAttributes(".");
```
### Option 3: NPM Scripts
```json
{
"scripts": {
"fix-a11y": "node accessibility-package/cli.js",
"preview-a11y": "node accessibility-package/cli.js --dry-run"
}
}
```
## 📊 Kết quả Demo
Với file demo, tool đã tìm và sửa:
- **16 issues** tổng cộng
- **1 lang attribute** missing
- **3 alt attributes** missing/empty
- **12 role attributes** missing
## ⚙️ Configuration
```javascript
{
language: 'ja', // 'ja', 'en', 'vi', 'zh', etc.
backupFiles: true, // Tạo .backup files
dryRun: false // Preview mode
}
```
## 🎨 Before/After Example
### Before:
```html
<html>
<img src="logo.png" />
<a href="/about">About</a>
<button onclick="submit()">Submit</button>
</html>
```
### After:
```html
<html lang="ja">
<img src="logo.png" alt="ロゴ" role="img" />
<a href="/about" role="link">About</a>
<button onclick="submit()" role="button">Submit</button>
</html>
```
## 🔧 Customization
### Thay đổi alt text generation
Sửa method `generateAltText()` trong `lib/fixer.js`
### Thêm role rules mới
Sửa method `fixRoleAttributesInContent()` trong `lib/fixer.js`
### Thay đổi ngôn ngữ
Set `language` parameter trong config
## 📈 Performance
- ✅ Xử lý hàng trăm files trong vài giây
- ✅ Memory efficient
- ✅ Backup tự động
- ✅ Error handling tốt
## 🛡️ Safety Features
- ✅ Dry run mode để preview
- ✅ Automatic backups (.backup files)
- ✅ Duplicate attribute prevention
- ✅ Error handling và logging
## 📋 Checklist sử dụng
1. [ ] Copy package vào dự án
2. [ ] `npm install` dependencies
3. [ ] Backup code (git commit)
4. [ ] Test với `--dry-run`
5. [ ] Chạy tool
6. [ ] Review kết quả
7. [ ] Commit changes
## 🎯 Use Cases
### Dự án mới
```bash
node accessibility-package/cli.js ./src
```
### Dự án có sẵn
```bash
node accessibility-package/cli.js --dry-run ./public
# Review results, then:
node accessibility-package/cli.js ./public
```
### CI/CD Integration
```bash
# In build script
node accessibility-package/cli.js --no-backup ./dist
```
## 📞 Support
- 📖 Đọc [README.md](./README.md) để biết chi tiết
- 🚀 Xem [QUICK_START.md](./QUICK_START.md) để bắt đầu nhanh
- 💡 Chạy [example.js](./example.js) để xem demos
- ❓ Chạy `node cli.js --help` để xem options
## 🎉 Kết luận
Package này giúp bạn:
- ⚡ **Tiết kiệm thời gian**: Tự động fix thay vì manual
- 🎯 **Cải thiện accessibility**: Tuân thủ WCAG guidelines
- 🛡️ **An toàn**: Backup và preview trước khi apply
- 🔧 **Linh hoạt**: Dễ customize và integrate
**Ready to make your website more accessible! 🌟**