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.