Getting Started with @weable/a11y-color-utils: Installation & Basic Usage

So you want to leverage the power of the @weable/a11y-color-utils library to build more accessible applications? Great! This guide will walk you through the installation and basic usage.

Installation

This package is hosted on GitHub Packages. You'll need to configure npm (or your preferred package manager like yarn or pnpm) to authenticate with GitHub Packages.

1. Create a Personal Access Token (PAT):

   • Go to your GitHub Developer settings > Personal access tokens.
   • Generate a new token (classic or fine-grained).
   • Ensure the token has the read:packages scope.
   • Copy the token immediately! You won't be able to see it again.

2. Configure npm:

   • Create or edit the .npmrc file in your project's root directory (or your global user directory ~/.npmrc).

   • Add the following lines, replacing YOUR_GITHUB_USERNAME and YOUR_PAT:

     @oliksueddaht:registry=https://npm.pkg.github.com/
     //npm.pkg.github.com/:_authToken=YOUR_PAT
     

3. Install the Package: Now you can install the package using your package manager:

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

Initialization (License Key Required)

This library requires a valid license key for initialization. You must call initLicense before using most functions.

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

const licenseKey = 'YOUR_WEABLE_LICENSE_KEY'; // Obtain this from WeAble

async function initializeLibrary() {
  const success = await initLicense(licenseKey);
  if (success) {
    console.log('WeAble Color Utils initialized successfully!');
    // Now you can use other library functions
  } else {
    console.error('Failed to initialize WeAble Color Utils. Check your license key.');
  }
}

initializeLibrary();

Important: The initLicense function is asynchronous because it verifies the key against a server. Ensure you handle the Promise correctly (e.g., using async/await or .then()).

Basic Usage Examples

Once initialized, you can import and use the various utility functions.

Checking WCAG Contrast:

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

const bgColor = '#FFFFFF';
const fgColor = '#757575';

// Check against WCAG AA (4.5:1) - the default
const { ratio, pass } = checkContrast(bgColor, fgColor);
console.log(`Contrast Ratio: ${ratio}, Passes AA: ${pass}`); // Example: Contrast Ratio: 2.81, Passes AA: false

// Check against WCAG AAA (7:1)
const { ratio: ratioAAA, pass: passAAA } = checkContrast(bgColor, fgColor, 7);
console.log(`Contrast Ratio: ${ratioAAA}, Passes AAA: ${passAAA}`); // Example: Contrast Ratio: 2.81, Passes AAA: false

Calculating APCA Contrast:

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

const bgColor = '#333333';
const fgColor = '#FFFFFF';
const fontSize = 18;

const apcaScore = calculateAPCA(fgColor, bgColor, fontSize);
console.log(`APCA Score (Lc): ${apcaScore}`); // Example: APCA Score (Lc): 78.9

Fixing Contrast Automatically:

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

const palette = ['#FFFFFF', '#AAAAAA', '#000000']; // #FFFFFF / #AAAAAA fails 4.5:1
const targetContrast = 4.5;

const result = fixWorstContrastPair(palette, targetContrast);

if (result.fixed) {
  console.log('Original failing color:', result.originalColor);
  console.log('Adjusted color:', result.newColor);
  console.log('Fixed Palette:', result.fixedPalette);
} else {
  console.log('No fix needed or possible.');
}

Next Steps

Explore the other functions available in the library:

• calculateContrastRatio, calculateLuminance
• hexToRgb, rgbToHex
• lightenColor, darkenColor, shiftHue, adjustSaturation
• deltaE
• generatePalette

Refer to the full API documentation (coming soon!) for details on all functions and their parameters.