@octaviaflow/accessibility-checker

v1.1.2

Published

a month ago

Accessibility checker for OctaviaFlow Design System - A custom implementation

Downloads

0High
0Medium
0Low

vishal035

octaviaflow octaviaflow-design-system accessibility checker web a11y

@octaviaflow/accessibility-checker

Enterprise-grade accessibility checker for OctaviaFlow Design System

A comprehensive TypeScript-based accessibility testing tool that combines heuristic analysis with axe-core integration to provide detailed accessibility reports in multiple formats.

🚀 Features

🔍 Dual Analysis Engine: Combines custom heuristics with axe-core for comprehensive accessibility testing
📊 Multiple Output Formats: JSON, HTML, CSV, and Excel reports
🎨 Beautiful HTML Reports: Responsive, styled reports with issue categorization
⚡ High Performance: Built with TypeScript and optimized for speed
🛠️ CLI & Programmatic API: Use as command-line tool or integrate into your workflow
📈 WCAG Compliance: Maps issues to WCAG guidelines with help URLs
🔧 Extensible Architecture: Easy to add custom rules and checks

📦 Installation

NPM/Yarn

npm install @octaviaflow/accessibility-checker
# or
yarn add @octaviaflow/accessibility-checker

Bun

bun add @octaviaflow/accessibility-checker

Global Installation

npm install -g @octaviaflow/accessibility-checker

🎯 Quick Start

CLI Usage

# Analyze an HTML file
octaviaflow-achecker --input index.html

# Generate HTML report
octaviaflow-achecker --input page.html --format html --verbose

# Test with sample HTML
octaviaflow-achecker --sample --format excel

# Custom output location
octaviaflow-achecker --input app.html --output reports/accessibility.json

Programmatic Usage

import { analyze } from '@octaviaflow/accessibility-checker';
import { saveReport } from '@octaviaflow/accessibility-checker/storage';

// Analyze HTML content
const html = '<html><body><img src="logo.png"><h1>Welcome</h1></body></html>';
const result = await analyze(html);

// Save results in different formats
await saveReport(result, './report.json', 'json');
await saveReport(result, './report.html', 'html');
await saveReport(result, './report.xlsx', 'excel');

console.log(`Found ${result.summary.totalIssues} accessibility issues`);

📋 CLI Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --input <file> | -i | HTML file to analyze | - | | --output <file> | -o | Output file path | ./data/results.json | | --format <type> | - | Output format: json, html, csv, excel | json | | --sample | - | Run with sample HTML for testing | false | | --verbose | -v | Verbose output with detailed logging | false | | --help | -h | Show help message | - |

📊 Output Formats

JSON Format

{
  "summary": {
    "totalIssues": 3,
    "byType": {
      "image-missing-alt": 1,
      "link-empty": 1,
      "axe:color-contrast": 1
    },
    "axeViolations": 1
  },
  "issues": [
    {
      "type": "image-missing-alt",
      "message": "Image tag missing alt attribute",
      "snippet": "<img src=\"logo.png\">",
      "source": "heuristic"
    }
  ],
  "axe": { /* Full axe-core results */ },
  "meta": {
    "timestamp": "2025-11-13T10:52:00.000Z",
    "source": "index.html",
    "version": "1.1.1"
  }
}

HTML Report

Responsive design with modern styling
Color-coded issues by severity and type
Interactive elements with expandable details
Summary dashboard with metrics
WCAG compliance mapping

Excel Report

Summary sheet with overview metrics
Issues sheet with detailed findings
Formatted tables with proper styling
Multiple worksheets for organization

🔧 Development

Prerequisites

Node.js ≥ 22.0.0
Bun ≥ 1.3.2 (recommended)
TypeScript ≥ 5.8.3

Setup

# Clone the repository
git clone https://github.com/OctaviaFlow/OctaviaFlow-Design-System.git
cd OctaviaFlow-Design-System/packages/accessibility-checker

# Install dependencies
bun install

# Build the project
bun run build

# Run tests
bun run test

# Run linting
bun run lint

# Development mode
bun run dev

Scripts

| Script | Description | |--------|-------------| | bun run build | Build CommonJS, ESM, and TypeScript declarations | | bun run test | Run tests once and exit | | bun run test:watch | Run tests in watch mode | | bun run lint | Run ESLint | | bun run lint:fix | Fix ESLint issues | | bun run format | Format code with Prettier | | bun run ci-check | Full CI pipeline (build + test + lint) | | bun run dev | Build and run sample |

🏗️ Architecture

Core Components

src/
├── checker/
│   └── index.ts          # Main analysis engine
├── storage/
│   └── reportWriter.ts   # Multi-format report generation
├── utils/
│   └── wcag-rules.ts     # WCAG compliance mapping
└── index.ts              # CLI interface

Analysis Engine

The accessibility checker uses a dual-engine approach:

Heuristic Analysis: Fast, lightweight checks for common issues
- Missing alt attributes on images
- Empty links and headings
- Basic structural problems
Axe-Core Integration: Comprehensive WCAG compliance testing
- Color contrast analysis
- Keyboard navigation
- ARIA compliance
- Semantic structure validation

Type Definitions

interface Issue {
  type: string;
  message: string;
  snippet?: string;
  helpUrl?: string;
  source?: string;
}

interface Result {
  summary: {
    totalIssues: number;
    byType: Record<string, number>;
    axeViolations?: number;
  };
  issues: Issue[];
  axe?: AxeResults | { error: string };
  meta?: ResultMeta;
}

🎨 Examples

Basic HTML Analysis

import { analyze } from '@octaviaflow/accessibility-checker';

const html = `
<!DOCTYPE html>
<html lang="en">
<head>
  <title>Test Page</title>
</head>
<body>
  <h1>Welcome</h1>
  <img src="hero.jpg">
  <a href="/about"></a>
  <button style="color: #ccc; background: #ddd;">Click me</button>
</body>
</html>
`;

const result = await analyze(html);
console.log(`Found ${result.summary.totalIssues} issues:`);
result.issues.forEach(issue => {
  console.log(`- ${issue.type}: ${issue.message}`);
});

CI/CD Integration

# GitHub Actions example
- name: Accessibility Check
  run: |
    octaviaflow-achecker --input dist/index.html --format json --output accessibility-report.json
    
- name: Upload Report
  uses: actions/upload-artifact@v3
  with:
    name: accessibility-report
    path: accessibility-report.json

Custom Report Generation

import { analyze, saveReport } from '@octaviaflow/accessibility-checker';

async function generateAccessibilityReport(htmlFiles: string[]) {
  const results = [];
  
  for (const file of htmlFiles) {
    const html = await fs.readFile(file, 'utf8');
    const result = await analyze(html);
    result.meta = { ...result.meta, source: file };
    results.push(result);
  }
  
  // Generate combined report
  const combinedResult = {
    summary: {
      totalIssues: results.reduce((sum, r) => sum + r.summary.totalIssues, 0),
      byType: results.reduce((acc, r) => {
        Object.entries(r.summary.byType).forEach(([type, count]) => {
          acc[type] = (acc[type] || 0) + count;
        });
        return acc;
      }, {})
    },
    issues: results.flatMap(r => r.issues),
    meta: {
      timestamp: new Date().toISOString(),
      source: 'batch-analysis',
      fileCount: htmlFiles.length
    }
  };
  
  await saveReport(combinedResult, './batch-report.html', 'html');
}

Integration with Testing Frameworks

// Jest/Vitest example
import { analyze } from '@octaviaflow/accessibility-checker';

describe('Accessibility Tests', () => {
  test('homepage should be accessible', async () => {
    const html = await getRenderedHTML('/');
    const result = await analyze(html);
    
    expect(result.summary.totalIssues).toBe(0);
  });
  
  test('should have no critical axe violations', async () => {
    const html = await getRenderedHTML('/dashboard');
    const result = await analyze(html);
    
    if (result.axe && 'violations' in result.axe) {
      const criticalViolations = result.axe.violations.filter(
        v => v.impact === 'critical'
      );
      expect(criticalViolations).toHaveLength(0);
    }
  });
});

🔧 Configuration

ESLint Integration

The package uses ESLint v9 with flat config:

// eslint.config.js
import typescriptEslint from '@typescript-eslint/eslint-plugin';
import tsParser from '@typescript-eslint/parser';
import js from '@eslint/js';

export default [
  js.configs.recommended,
  {
    files: ['**/*.ts'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        ecmaVersion: 2022,
        sourceType: 'module'
      }
    },
    plugins: {
      '@typescript-eslint': typescriptEslint
    },
    rules: {
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': 'off'
    }
  }
];

TypeScript Configuration

Uses unified OctaviaFlow TypeScript configs:

{
  "extends": "typescript-config-octaviaflow/base",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  }
}

🚀 Performance

Fast Analysis: Optimized for large HTML files
Memory Efficient: Streaming analysis for large documents
Concurrent Processing: Parallel heuristic and axe-core analysis
Minimal Dependencies: Lightweight package with essential dependencies only

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

TypeScript: All code must be properly typed
Testing: Maintain 100% test coverage for new features
Linting: Follow ESLint configuration
Documentation: Update README for new features

📄 License

Licensed under the Apache-2.0 License. See LICENSE file for details.

🔗 Related Packages

@octaviaflow/react - React components with built-in accessibility
@octaviaflow/styles - Accessible CSS framework
@octaviaflow/themes - Accessible color themes

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: OctaviaFlow Docs

Made with ❤️ by the OctaviaFlow Team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@octaviaflow/accessibility-checker

🚀 Features

📦 Installation

NPM/Yarn

Bun

Global Installation

🎯 Quick Start

CLI Usage

Programmatic Usage

📋 CLI Options

📊 Output Formats

JSON Format

HTML Report

Excel Report

🔧 Development

Prerequisites

Setup

Scripts

🏗️ Architecture

Core Components

Analysis Engine

Type Definitions

🎨 Examples

Basic HTML Analysis

CI/CD Integration

Custom Report Generation

Integration with Testing Frameworks

🔧 Configuration

ESLint Integration

TypeScript Configuration

🚀 Performance

🤝 Contributing

Development Guidelines

📄 License

🔗 Related Packages

📞 Support