@axaraaudit/core

Core logic for A11yEngine: DTCG token parsing and static Design-Drift detection for .css / .tsx source. Zero runtime config — point it at a DTCG token file and your source files.

What it does

1. Parses DTCG tokens (parseDtcg / parseDtcgString)

   • Flattens the group/token tree to dot-paths + CSS variable names.
   • Inherits $type from ancestor groups.
   • Resolves {group.token} aliases, with cycle & unknown-target detection.
   • Builds value→token indexes for colors (canonical sRGB) and dimensions (normalized to px).

2. Analyzes source statically

   • CSS via PostCSS (analyzeCss): colors on every declaration, spacing on spacing-related properties only.
   • TSX/JSX via the TypeScript Compiler API (analyzeTsx): inline style={{…}} objects (colors + spacing, React-numeric → px) and color literals in any string/template (styled-components, theme constants).

3. Emits a structured drift report — for each hard-coded value: exact-token (safe auto-fix → var(--token)), nearest-token (suggested), or no-token, with confidence, location, and a ready-to-apply replacement.

Usage

import { auditPaths, auditSources } from '@axaraaudit/core';

// From disk:
const report = auditPaths('design-tokens.dtcg.json', ['src/Button.tsx', 'src/app.css']);

// Or in-memory:
const report2 = auditSources(tokensJson, [{ path: 'Button.tsx', content }]);

console.log(report.summary); // { filesScanned, totalIssues, errors, warnings, autoFixable }

Scripts

pnpm --filter @axaraaudit/core test       # vitest
pnpm --filter @axaraaudit/core typecheck  # tsc --noEmit (strict)
pnpm --filter @axaraaudit/core build      # emit dist/

RGAA wrapper (axe-core)

Runs axe-core headlessly and re-keys its findings onto RGAA 4.1 criteria, then exports a DINUM/Ara-compatible declaration.

import { auditHtmlRgaa, toAraDeclaration } from '@axaraaudit/core';

const report = await auditHtmlRgaa('<img src="logo.png">');
// report.findings → [{ criterion: '1.1', themeLabel: 'Images', axeRuleId: 'image-alt', ... }]

const declaration = toAraDeclaration(report); // { referential: 'RGAA', criteria: [{ status: 'NC', ... }] }

• mapAxeResults(axeResults) — pure mapper from raw AxeResults (e.g. produced by the Playwright runtime at step 4) to a RgaaReport. The axe→RGAA table lives in src/rgaa/mapping.ts; unmapped rules are surfaced, never dropped.
• runAxeOnHtml / auditHtmlRgaa — execute axe-core inside JSDOM by injecting axe.source. Contrast (color-contrast) needs real rendering and is therefore disabled under JSDOM (accurate pass = Playwright, step 4); it is surfaced as cantTell otherwise.
• toAraDeclaration — only emits the criteria detected as non-conforme (NC); the global conformance rate and C/NA criteria require a manual RGAA grid (stated in the declaration note).

See ../../examples/ for runnable demos: node examples/smoke.mjs (design drift) and node examples/rgaa-smoke.mjs (RGAA → Ara).