Accessibility Gen User Guide

Accessibility Gen is a Node 20 ESM package at tool/accessibility-gen. It provides pure JavaScript modules for contrast checking, APCA, color-vision simulation, Auric SD scoring, deterministic dataset generation, pair recommendation, reports, exports and SVG visualizations.

The package backs Accessibility Library, which browses a compact manifest at /data/accessibility-db/accessibility.json. The viewer regenerates visible pairs from the same deterministic seed instead of downloading an expanded multi-gigabyte dataset.

Use the package when you need repeatable programmatic checks. Use the Accessibility Library when you want to see which foregrounds pass on a given ground, look up a record, or browse the generated pairs visually.

Import the high-level API from the package entrypoint or from src/api/api.js in local examples.

import { checkPairAll } from "@auric-artisan/accessibility-gen";

const fg = [16, 18, 22];
const bg = [255, 255, 255];
const result = checkPairAll(fg, bg);

console.log(result.wcag21.pass_level);
console.log(result.wcag30.tier, result.wcag30.Lc);
console.log(result.auric_strict.grade);

RGB arrays use 0 to 255 channel values. checkPairAll() returns WCAG 2.1 and WCAG 2.2 verdicts, APCA results (under the wcag30 key), Auric SD Flexible, Auric SD Strict and foreground CVD simulations.

Local examples live in tool/accessibility-gen/examples. The most useful starting commands are node examples/basic-check.js, node examples/wcag-suite.js, node examples/color-blindness.js and node examples/audit-report.js.

checkPair(standard, fg, bg) runs one selected standard. Valid names are WCAG 2.1, WCAG 2.2, WCAG 3.0, Auric SD Flexible and Auric SD Strict.

APCA is a candidate contrast method that was proposed for WCAG 3. WCAG 3 is still a Working Draft with no final contrast method, so APCA results are guidance; WCAG 2.x (4.5:1 for body text, 3:1 for large text and non-text) is the current standard.

APCA produces signed Lc values. Positive Lc means dark text on a light background, and negative Lc means light text on a dark background. The package maps absolute Lc to use-case brackets: body text, large text, UI, spot text, non-text and decorative.

Auric SD is a composite design-system score. It weights five axes:

• WCAG: 30 percent.
• APCA: 30 percent.
• CVD distinguishability: 20 percent.
• OKLCH lightness gap: 10 percent.
• Hue and chroma distance: 10 percent.

Flexible mode is suitable for editorial, brand and decorative surfaces. Strict mode is intended for healthcare, public-sector, learning, finance and other mission-critical interfaces where color pairs must remain readable across stronger constraints.

The color-blindness module uses Machado, Oliveira and Fernandes style matrices in linear sRGB. It supports these simulation names:

• protanopia and protanomaly.
• deuteranopia and deuteranomaly.
• tritanopia and tritanomaly.
• achromatopsia and achromatomaly.
• cataracts and low_vision.

Use simulateColorBlindness(type, rgb) for a single transformed color, or import simulateAll() and distinguishabilityScore() from the color_blindness module when you need all previews and pair survival scores.

The default dataset is defined by ACCESSIBILITY_DATASET_DEFAULTS: seed 9001, count 5000000, batch size 50000 and batch seed stride 2654435761. pairForIndex(index) derives one foreground and background pair from the global index.

Use generatePair(index) for one record, or instantiate AccessibilityDatasetGenerator for slices, audits and offline datasets.

import { AccessibilityDatasetGenerator } from "@auric-artisan/accessibility-gen";

const generator = new AccessibilityDatasetGenerator({
  count: 5000,
  includeMetrics: true,
  includeCvd: false
});

const records = generator.generateAll();

For large exports, run node scripts/generate-dataset.js from tool/accessibility-gen. The script supports ndjson, json, csv and binary writer modes.

Use recommendation helpers when a pair fails but you want to preserve hue and saturation where possible.

• recommendAccessibleInk(fg, bg) moves the foreground lightness until the target ratio passes.
• recommendAccessibleBackground(fg, bg) moves the background instead.
• auditPalette(rgbColors) checks every pair in a palette against Auric SD Flexible and Strict.

The lower-level pairs module also includes accessible foreground ramps, generated accessible palettes, best WCAG ink and best APCA ink helpers.

The current exporter module supports these format keys: hex, css, scss, tailwind, json, csv and svg.

Reports are available as Markdown, JSON and HTML through reportToMarkdown(), reportToJson() and reportToHtml().

The browser UI at /library/accessibility/ reads the compact manifest and regenerates cards from the deterministic stream. It draws a contrast map of every foreground that passes on a chosen ground at a 3:1, 4.5:1 or 7:1 target, suggests passing colors you can copy as CSS, pins a pasted palette on the map, looks up any record by id or index, and scrolls through the corpus showing only passing pairs or everything.

The readout beside the map shows the foreground and ground, OKLCH lightness and hue, the contrast ratio and verdict, APCA Lc, a color-vision margin and the distance to the target line. A looked-up record shows its pair, contrast, APCA, Auric SD score and grade, and recommended use; opening a browsed record loads its two colors into the map.

• Use WCAG 2.x for compatibility with current policy and audit expectations.
• Use APCA Lc to understand perceptual contrast and polarity, alongside a WCAG 2.x result rather than instead of one.
• Use Auric SD Strict for mission-critical interface tokens.
• Use CVD distinguishability before relying on hue alone.
• Use deterministic indices when you need reproducible examples in documentation or tests.
• Avoid generating all 5,000,000 full-metric records in memory; stream large outputs instead.
• Treat automated contrast results as engineering evidence, not a complete substitute for human accessibility review.

For module and implementation details, see the Accessibility Gen Developer Reference.