GBU Accessibility Package

Accessibility checking and reporting toolkit for HTML projects.

The package runs in check-only mode. It does not edit or delete source files, and is intended for accessibility review, project validation, and report export.

What It Does

• Checks HTML lang, alt, role, aria-label, forms, buttons, links, landmarks, nested controls, headings, and description lists
• Checks broken external links and missing local resources
• Checks meta tags, Google Tag Manager installation, dead code, unused files, and large files
• Exports unused file lists and comprehensive Excel reports
• Supports enhanced alt-text analysis with stricter review rules and richer suggestions

Installation

npm install -g gbu-accessibility-package

Or install locally:

npm install gbu-accessibility-package

Quick Start

# Default comprehensive check
gbu-a11y

# Check a specific directory
gbu-a11y ./src

# Check only alt text issues
gbu-a11y --alt-only ./src

# Check broken links and missing resources
gbu-a11y --links-check ./public

# Export a full Excel report
gbu-a11y --full-report -o reports/accessibility-report.xlsx

CLI

gbu-a11y [options] [directory]

Core options:

• -d, --directory <path>: target directory, defaults to current directory
• -l, --language <lang>: language context, defaults to ja
• --dry-run: legacy alias; check-only mode is always on
• -h, --help: show help
• -v, --version: show version

Check modes:

• --comprehensive, --all: run the default multi-area review for accessibility structure, labels, links/resources, and project-level quality signals in one pass
• --alt-only: review image alt text quality, including missing alt, empty alt on meaningful images, overly generic descriptions, and enhanced alt analysis when enabled
• --lang-only: review missing or incorrect root HTML lang usage so you can catch pages that do not declare the expected document language
• --role-only: review suspicious or missing ARIA role usage, including cases where elements may need better semantic roles or have role patterns that do not match their behavior
• --aria-label-only: review elements that depend on aria-label for accessible naming, such as images, links, or controls that do not expose enough text on their own
• --forms-only: review form accessibility issues such as inputs without clear labels, weak accessible names, or fields that rely too heavily on placeholder text
• --nested-only: review nested interactive controls, for example a button inside a link, a link inside a button, or clickable controls placed inside other focusable widgets; these patterns often confuse keyboard users and screen readers because multiple interactive targets overlap
• --buttons-only: review buttons and button-like controls for missing accessible names, empty text, or controls that appear clickable but do not expose enough meaning
• --links-only: review accessible link naming issues such as empty links, image-only links without usable text alternatives, or vague labels like “click here” without context
• --landmarks-only: review page landmark structure such as missing main, weak navigation structure, or layouts that make region-based navigation harder for assistive technology users
• --headings-only: review heading hierarchy and document outline problems, such as skipped heading levels, duplicate headings in the same context, multiple top-level headings, or empty heading text
• --dl-only: review description list markup problems, such as invalid dl structure, missing dt/dd pairing, or malformed content inside description lists
• --links-check: run both external link validation and local resource existence checks so you can catch broken URLs and missing files together
• --broken-links: check external HTTP/HTTPS links only and report unreachable URLs, 404/5xx responses, redirects that fail, and similar outbound link problems
• --404-resources: check local resources only, such as missing images, scripts, stylesheets, and other referenced files that do not exist at the expected path
• --gtm-check: review Google Tag Manager installation patterns, including whether the expected script and noscript pieces are present and placed correctly
• --check-meta: review meta tags and Open Graph metadata for typos, malformed attributes, suspicious property names, and other metadata quality issues
• --unused-files: scan the project for files that do not appear to be referenced anywhere, helping you spot dead assets or stale source files for manual review
• --unused-files-list: export the unused-file findings to a text file so your team can review and clean them up manually outside the tool
• --dead-code: review CSS and JavaScript for selectors, rules, or functions that appear unused based on static project references
• --file-size: review large files and oversized assets to highlight optimization opportunities and possible frontend performance risks
• --full-report: generate the Excel report with aggregated findings across the supported check areas for sharing, triage, or audit tracking
• -o, --output <file>: custom output path for --full-report
• --list-file <file>: custom output path/name for --unused-files-list

Enhanced alt analysis:

• --enhanced-alt
• --alt-creativity <mode>: conservative, balanced, creative
• --include-emotions
• --strict-alt

Examples

# Comprehensive review
gbu-a11y

# Forms only
gbu-a11y --forms-only ./pages

# Broken links only
gbu-a11y --broken-links ./dist

# Meta tags only
gbu-a11y --check-meta ./site

# Unused file list export
gbu-a11y --unused-files-list --list-file reports/unused-files.txt ./project

# Enhanced alt review
gbu-a11y --alt-only --enhanced-alt --strict-alt ./src

Programmatic Usage

const { AccessibilityChecker } = require('gbu-accessibility-package');

const checker = new AccessibilityChecker({
  language: 'en',
  enhancedAltMode: true,
  strictAltChecking: true
});

async function main() {
  await checker.checkAltText('./src');
  await checker.checkBrokenLinks('./src');
  await checker.generateFullReport('./src', './reports/accessibility-report.xlsx');
}

main().catch(console.error);

AccessibilityFixer is still exported for compatibility, but it is now locked to the same check-only behavior and will not modify source files.

Output Behavior

• Source files stay unchanged
• --unused-files-list writes a report file only
• --full-report writes an Excel report only
• Findings are printed to the console during analysis

Publish Checklist

Before publishing:

npm test
npm pack

Then verify:

• gbu-a11y --help
• gbu-a11y
• gbu-a11y --full-report

License

MIT