@a11ylint/core

A powerful accessibility testing tool designed to validate web projects against French accessibility guidelines (RGAA - Référentiel Général d'Amélioration de l'Accessibilité).

🎯 Motivation

This project was born from an idea by CROQUET Mickael, who envisioned implementing a comprehensive series of tests for French RGAA accessibility rules. After extensive research, we discovered a significant gap in the ecosystem - no suitable library existed to address this specific need for French accessibility standards.

Inspired by this vision and driven by the necessity to fill this gap, PLANCQ Paul joined forces with Mickael to initiate this project. Together, we decided to create our own robust package to validate RGAA rules, making French web accessibility testing more accessible to developers and organizations.

Our goal is to provide the French web development community with a reliable, comprehensive tool that ensures websites meet the stringent accessibility standards required by French regulations, ultimately making the web more inclusive for everyone.

🚧 Under Construction

This repository is currently under active development. While the foundation is being laid, please note that certain features and components may still be incomplete. Stay tuned for updates as we build a robust and cohesive accessibility testing system.

✨ Features

• RGAA Compliance Testing: Automated testing for French accessibility standards
• Multiple Output Formats: Generate reports in HTML, JSON, or CLI formats
• Comprehensive Rule Coverage: Support for RGAA 1.x, 2.x, 3.x, 6.x, 8.x, and 9.x rules
• DOM & Virtual Testing: Works with both real DOM elements and virtual representations
• Color Contrast Analysis: Advanced color contrast calculations following RGAA guidelines
• Detailed Reporting: Get actionable insights with specific element references and fix suggestions

🚀 Quick Start

Installation

npm install @a11ylint/core

Basic Usage

import A11ylint from '@a11ylint/core';

// Initialize the core
const a11ylint = new A11ylint();

// Run accessibility tests
const results = a11ylint.run({
  mode: 'dom', // or 'virtual'
  document: document, // Your DOM document
  images: [], // Array of image elements to test
  frames: [], // Array of frame/iframe elements to test
  links: [], // Array of link elements to test
  colorsElements: [], // Array of elements for color contrast testing
  headings: [], // Array of heading elements to test (h1-h6 or role="heading")
  customIframeBannedWords: ['frame', 'iframe'] // Optional custom banned words
});

console.log(results);

Generate Reports

// Generate different types of reports
a11ylint.generateAudit({
  results: [
    {
      url: 'https://example.com',
      result: results
    }
  ],
  options: {
    html: true,
    json: true,
    cli: true,
    baseUrl: 'https://example.com'
  }
});

📊 Supported RGAA Rules

Category	Rules	Description
RGAA 1	1.1.1, 1.1.2, 1.1.5	Image accessibility (alt text, area elements, SVG)
RGAA 2	2.1.1, 2.2.1	Frame accessibility (titles, relevance)
RGAA 3	3.2.x	Color contrast requirements
RGAA 6	6.2.1	Link accessibility (labels, titles)
RGAA 8	8.1.1, 8.1.3, 8.3, 8.5	Document structure (doctype, language, title)
RGAA 9	9.1.1, 9.1.3	Heading structure and hierarchy

📈 Report Generation

@a11ylint/core generates comprehensive accessibility reports in multiple formats:

HTML Reports

• Visual, interactive reports with detailed issue descriptions
• Color-coded severity levels
• Direct links to RGAA documentation
• Element-specific code examples

JSON Reports

• Machine-readable format for CI/CD integration
• Structured data for custom processing
• API-friendly output

CLI Reports

• Terminal-friendly output for development workflows
• Quick overview of accessibility issues
• Perfect for continuous integration

🧪 Testing Modes

DOM Mode

Test real DOM elements in browser environments:

// Collect heading elements from the DOM
const headings = [
  ...document.querySelectorAll('h1, h2, h3, h4, h5, h6'),
  ...document.querySelectorAll('[role="heading"]')
];

const results = a11ylint.run({
  mode: 'dom',
  document: document,
  headings: headings,
  // ... other options
});

Virtual Mode

Test serialized element data (perfect for server-side testing):

import { HeadingVirtualElement } from '@a11ylint/core';

const virtualHeadings: HeadingVirtualElement[] = [
  {
    type: 'heading',
    tagName: 'H1',
    textContent: 'Main Title',
    outerHTML: '<h1>Main Title</h1>',
    index: 0
  },
  {
    type: 'heading',
    tagName: 'DIV',
    role: 'heading',
    ariaLevel: '2',
    textContent: 'Custom heading',
    outerHTML: '<div role="heading" aria-level="2">Custom heading</div>',
    index: 1
  }
];

const results = core.run({
  mode: 'virtual',
  document: virtualDocument,
  images: virtualImageElements,
  headings: virtualHeadings,
  // ... other options
});

Roadmap

📋 View detailed project roadmap

Our comprehensive roadmap includes:

• Extended RGAA rule coverage (106 rules planned)
• Integration with popular testing frameworks
• Browser extension for real-time testing
• Advanced color contrast algorithms
• Multi-language support beyond French

Track our progress with priority-based implementation, GitHub issues integration, and automated progress tracking.

📚 Documentation

For more information about RGAA guidelines, visit https://accessibilite.numerique.gouv.fr.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT ©

---

Made with ❤️ for French web accessibility