@alea-design/audit
v0.1.2
Published
One config-driven quality audit for Alea and the apps built on it: axe, overflow, touch targets, focus, reduced motion, a screen-reader simulation and CSS guardrails, across viewports, themes and text sizes.
Maintainers
Readme
@alea-design/audit
One config-driven quality audit for apps built on Alea (and any other web app). It opens your app in a real browser once for every combination of width, theme, text size, language, pointer and motion setting, and checks every route.
npm i -D @alea-design/audit playwright-core axe-core
npx alea-audit init # alea-audit.config.mjs and a GitHub Actions workflow (one job, weekly)
npx alea-audit # run it (or: npx alea audit, with @alea-design/cli)It bundles no browser. playwright-core is used for its API and the audit drives the Google Chrome on the machine
(CHROME_PATH or browser.executablePath to point elsewhere). playwright-core and axe-core are optional peers; the
audit says what to install when one is missing.
Config
// alea-audit.config.mjs
import { defineConfig } from '@alea-design/audit';
export default defineConfig({
server: { command: 'npm run build && npx vite preview --port {port} --strictPort', url: 'http://127.0.0.1:{port}' },
routes: ['/', '/pricing'],
themes: ['light', 'dark'],
theme: { attribute: 'data-theme', storageKey: 'my-app-theme' },
checks: { overflow: { scrollRegions: ['.alea-table-wrap'] }, 'layout-parity': true, guardrails: true },
guardrails: { files: ['src/**'], rules: { 'raw-px': true, 'raw-hex': true, 'long-dash': true } },
ignore: [{ check: 'axe', rule: 'color-contrast', route: '/legal', reason: 'Third-party widget, reported upstream.' }],
});Defaults: widths 320, 375, 768, 1024, 1280, 1920; light and dark; text 100, 150, 200 percent (the real browser font-size
preference); fine and coarse pointers; full and reduced motion. The cover strategy uses every value of every axis at
least once; matrix: { strategy: 'cross' } runs the full product.
Checks
structure, console, axe (it never audits the engine's hidden live region, [data-live-announcer]; options.exclude adds more selectors), overflow, clipped-text, touch-targets, unique-names, focus, reduced-motion,
screen-reader run by default; layout-parity and guardrails are on request. npx alea-audit list describes each.
Custom checks go in customChecks; scripts of actions with assertions go in flows.
Every ignore needs a reason of at least a sentence, or the config is refused.
CLI
alea-audit [run] [--config f] [--route text] [--combo text] [--check a,b] [--shard 2/3]
[--jobs n] [--json file] [--fail-on error|warning|info|none] [--no-cache] [--quiet] [--plan]
alea-audit init [--force] [--no-workflow] [--shards n] [--schedule '0 5 * * 1']
alea-audit listExit code: 0 clean, 1 findings at or above failOn, 2 the audit could not run. AUDIT_JOBS or --jobs sets the
combinations run at once; by default it follows the CPU load. Results are cached in .alea-audit/cache by route,
combination, build hash and check settings. Screenshots of failing screens go to .alea-audit/artifacts/<run>.
--plan counts the matrix (routes x widths x themes x text sizes x locales x pointers x motion) and estimates the time
without opening a browser, so you know what a CI run will cost before you add a trigger.
CI cost
Private repositories pay for every minute of every job, and each job installs the project again. The workflow that
init writes is one job that runs on demand (workflow_dispatch) and weekly (--schedule changes the cron), cancels
an older run of the same ref, stops after 30 minutes and caches the npm install and the audit results. A header in the
file estimates the billed minutes. pull_request is there as a commented opt-in limited to the paths that change the UI.
--shards n splits the matrix over n parallel jobs: it finishes sooner but bills about two more minutes per shard. The
audit drives the Google Chrome that GitHub's Ubuntu runners already have, so no browser is downloaded or cached. Running
npx alea-audit run on your machine costs nothing.
Screen-reader simulation
@alea-design/audit/reader exposes the simulation for end-to-end tests: it reads Chrome's accessibility tree, computes
what would be announced and records live regions while you act. It does not replace VoiceOver or NVDA.
Docs: https://alea.alevasquez.dev/quality-audit?utm_source=npm&utm_medium=readme&utm_campaign=alea-audit · MIT license
