@weable-tools/a11y-color-utils

Version: 0.1.1

Overview

A standalone JavaScript/TypeScript library providing core functions for web accessibility color analysis and manipulation. Designed for developers and teams needing robust, reliable color accessibility logic in their own applications or design systems.

Built on the SACA principles of resilience, reusability, and self-contained value.

Requires initialization with a license key.

Key Features (Mini-Rangers)

• WCAG Contrast Calculation: calculateContrastRatio()
• Contrast Compliance Check: checkContrast() (AA/AAA)
• Relative Luminance Calculation: calculateLuminance()
• APCA Calculation: calculateAPCA() (Supports newer contrast model).
• Intelligent Color Fixing:
  • findMinLightnessAdjustment(): Finds minimum visual change (DeltaE) to meet contrast.
  • fixWorstContrastPair(): Analyzes and fixes the most problematic color pair in a palette.
• Basic Palette Generation: generatePalette() (Generates scheme from base color using chroma-js scale).
• Color Manipulation: lightenColor(), darkenColor(), shiftHue(), adjustSaturation()
• Color Conversion: hexToRgb(), rgbToHex()
• Color Difference: deltaE() (Calculates DeltaE 2000).

Use Cases

• Integrating accessibility checks into design tools or CI/CD pipelines.
• Building custom theme generators.
• Validating user-generated content for color compliance.
• Powering automated accessibility auditing tools.
• Enhancing UI development workflows.

Installation

This package is published publicly to the npm registry.

1. Install the Package:

   npm install @weable-tools/a11y-color-utils
   # or
   yarn add @weable-tools/a11y-color-utils

Usage

First, initialize the library with your license key:

import { initLicense } from '@weable-tools/a11y-color-utils';

// Replace 'YOUR_LICENSE_KEY' with the actual key
initLicense('YOUR_LICENSE_KEY'); 

Then, use the exported functions:

import {
    checkContrast,
    fixWorstContrastPair,
    calculateLuminance,
    calculateAPCA,
    generatePalette,
    hexToRgb,
    deltaE
} from '@weable-tools/a11y-color-utils';

// Check WCAG Contrast
const { ratio, pass } = checkContrast('#FFFFFF', '#757575', 4.5); // Check white on grey for AA
console.log(`WCAG Contrast: ${ratio}, Passes AA: ${pass}`); // Output: WCAG Contrast: 4.54, Passes AA: true

// Check APCA Contrast
const apcaScore = calculateAPCA('#000000', '#FFFFFF'); // Black text on white bg
console.log(`APCA Score (Lc): ${apcaScore?.toFixed(1)}`); // Output: APCA Score (Lc): 106.X

// Calculate Luminance
const lum = calculateLuminance('#808080');
console.log(`Luminance of grey: ${lum.toFixed(3)}`); // Output: Luminance of grey: 0.216

// Fix a palette
const myPalette = ['#FFFFFF', '#000000', '#888888', '#777777']; // Contains a low-contrast pair (#777 vs #888)
const { fixedPalette, changedIndex, newColor, fixed } = fixWorstContrastPair(myPalette, 4.5);
if (fixed) {
  console.log(`Palette fixed! Index ${changedIndex} changed to ${newColor}`);
  console.log('New Palette:', fixedPalette);
}

// Generate a palette
const base = '#3366CC';
const palette = generatePalette(base, 5);
console.log(`Generated 5 colors from ${base}:`, palette);

// Convert Hex to RGB
const rgb = hexToRgb('#FF8C00'); // DarkOrange
console.log('#FF8C00 in RGB:', rgb); // Output: #FF8C00 in RGB: [ 255, 140, 0 ]

// Calculate Color Difference
const diff = deltaE('#FF0000', '#FE0000'); // Very similar reds
console.log(`DeltaE between #FF0000 and #FE0000: ${diff.toFixed(2)}`); // Output: DeltaE between #FF0000 and #FE0000: 0.XX (very small)

Contributing

Contributions are welcome! Please follow standard GitHub flow (fork, feature branch, pull request).

License

MIT License (See LICENSE file for details).