Skip to main content
Introducing packages.sweber.dev
Surjection overview

SurjectionLive demo, free and Pro.

The first section runs axe-core, the engine of the free package, in your browser against a small demo site. Every section after it shows output of the Pro packages, produced with their command-line tools from the same site and shown here as finished HTML.

The demo site, the report and the checklist run in sandboxed frames. Nothing you do here is sent anywhere.

Check

Check (free, MIT)Fix the site, watch the result.

The bakery site below has six common barriers. Tick a fix and the page is checked again against WCAG 2.2 AA, with the same rules @sweberdev/surjection runs in Playwright, Vitest and the CLI.

Demo site, checked in your browser

Loading the check
Fixes

Result

Checking

A clean result here means the automated rules pass. Automated tests find only part of all barriers, so a manual check is still needed.

Same check on the command line

npx surjection check https://baeckerei-muster.example/ \
  --project "Bäckerei Muster" --viewport mobile --keyboard --layout \
  --screenshots a11y-shots --out-md a11y.md --out-json a11y.json --out-junit a11y.xml

✗ https://baeckerei-muster.example/ (6 issues)

6 accessibility issue(s) on 1 page(s).

Markdown report of the first run

# Accessibility report

**Bäckerei Muster**

## Summary

| Page | Critical | Serious | Moderate | Minor |
|---|---:|---:|---:|---:|
| https://baeckerei-muster.example/ | 3 | 3 | 0 | 0 |

## Bäckerei Muster · https://baeckerei-muster.example/

Tested on: 2026-08-03T07:30:00.000Z · Rules passed: 10

### Issues found

#### Buttons must have discernible text (`button-name`)

- **Critical** · WCAG criteria: 4.1.2 (A)
- Affected elements (1):
  - `.icon`
- Learn more: https://dequeuniversity.com/rules/axe/4.13/button-name?application=axeAPI

#### Images must have alternative text (`image-alt`)

- **Critical** · WCAG criteria: 1.1.1 (A)
- Affected elements (1):
  - `img`
- Learn more: https://dequeuniversity.com/rules/axe/4.13/image-alt?application=axeAPI

#### Form elements must have labels (`label`)

- **Critical** · WCAG criteria: 4.1.2 (A)
- Affected elements (1):
  - `input`
- Learn more: https://dequeuniversity.com/rules/axe/4.13/label?application=axeAPI

#### Elements must meet minimum color contrast ratio thresholds (`color-contrast`)

- **Serious** · WCAG criteria: 1.4.3 (AA)
- Affected elements (1):
  - `p`
- Learn more: https://dequeuniversity.com/rules/axe/4.13/color-contrast?application=axeAPI

#### <html> element must have a lang attribute (`html-has-lang`)

- **Serious** · WCAG criteria: 3.1.1 (A)
- Affected elements (1):
  - `html`
- Learn more: https://dequeuniversity.com/rules/axe/4.13/html-has-lang?application=axeAPI

#### Links must have discernible text (`link-name`)

- **Serious** · WCAG criteria: 2.4.4 (A), 4.1.2 (A)
- Affected elements (1):
  - `a`
- Learn more: https://dequeuniversity.com/rules/axe/4.13/link-name?application=axeAPI

---

_Automated tests detect only part of all possible barriers. This report does not replace a manual audit and does not confirm conformance with WCAG, EN 301 549 or the European Accessibility Act._

Coverage

Coverage (free)What a test run can and cannot tell you.

surjection coverage lists the 55 WCAG 2.2 success criteria at level A and AA and says for each how much of it automated rules can decide. The list is derived from the installed axe-core version and Surjection's own checks. Use it to plan the manual testing, not to read a passing run as proof of conformance.

npx surjection coverage --out coverage.md
# 55 success criteria at level A and AA: 11 mostly automatic, 16 partly automatic, 28 manual only.
# WCAG 2.2 coverage of Surjection

55 success criteria at level A and AA: 11 mostly automatic, 16 partly automatic, 28 manual only.
A passing run is no proof of conformance, not even for "mostly automatic" criteria.

| Criterion | Level | Name | Coverage | Rules |
| --- | --- | --- | --- | --- |
| 1.1.1 | A | Non-text Content | partly automatic | `aria-meter-name`, `aria-progressbar-name`, `image-alt`, `input-image-alt`, `object-alt`, `role-img-alt`, `svg-img-alt` |
| 1.2.1 | A | Audio-only and Video-only (Prerecorded) | partly automatic | `audio-caption` |
| 1.2.2 | A | Captions (Prerecorded) | partly automatic | `video-caption` |
| 1.2.3 | A | Audio Description or Media Alternative (Prerecorded) | manual only | - |
| 1.2.4 | AA | Captions (Live) | manual only | - |
| 1.2.5 | AA | Audio Description (Prerecorded) | manual only | - |
| 1.3.1 | A | Info and Relationships | partly automatic | `aria-hidden-body`, `aria-required-children`, `aria-required-parent`, `definition-list`, `dlitem`, `list`, `listitem`, `p-as-heading`, `table-fake-caption`, `td-has-header`, `td-headers-attr`, `th-has-data-cells` |
| 1.3.2 | A | Meaningful Sequence | manual only | - |
| 1.3.3 | A | Sensory Characteristics | manual only | - |
| 1.3.4 | AA | Orientation | partly automatic | `css-orientation-lock` |
| 1.3.5 | AA | Identify Input Purpose | mostly automatic | `autocomplete-valid` |
| 1.4.1 | A | Use of Color | partly automatic | `link-in-text-block` |
| 1.4.2 | A | Audio Control | partly automatic | `no-autoplay-audio` |
| 1.4.3 | AA | Contrast (Minimum) | mostly automatic | `color-contrast` |
| 1.4.4 | AA | Resize Text | mostly automatic | `meta-viewport` |
| 1.4.5 | AA | Images of Text | manual only | - |
| 1.4.10 | AA | Reflow | mostly automatic | `surjection-reflow` |
| 1.4.11 | AA | Non-text Contrast | manual only | - |
| 1.4.12 | AA | Text Spacing | mostly automatic | `avoid-inline-spacing`, `surjection-text-spacing` |
| 1.4.13 | AA | Content on Hover or Focus | manual only | - |
| 2.1.1 | A | Keyboard | partly automatic | `frame-focusable-content`, `scrollable-region-focusable`, `server-side-image-map` |
| 2.1.2 | A | No Keyboard Trap | mostly automatic | `surjection-focus-trap` |
| 2.1.4 | A | Character Key Shortcuts | manual only | - |
| 2.2.1 | A | Timing Adjustable | partly automatic | `meta-refresh` |
| 2.2.2 | A | Pause, Stop, Hide | partly automatic | `blink`, `marquee` |
| 2.3.1 | A | Three Flashes or Below Threshold | manual only | - |
| 2.4.1 | A | Bypass Blocks | mostly automatic | `bypass` |
| 2.4.2 | A | Page Titled | mostly automatic | `document-title` |
| 2.4.3 | A | Focus Order | partly automatic | `surjection-focus-order` |
| 2.4.4 | A | Link Purpose (In Context) | partly automatic | `area-alt`, `link-name` |
| 2.4.5 | AA | Multiple Ways | manual only | - |
| 2.4.6 | AA | Headings and Labels | manual only | - |
| 2.4.7 | AA | Focus Visible | partly automatic | `surjection-focus-visible` |
| 2.4.11 | AA | Focus Not Obscured (Minimum) | manual only | - |
| 2.5.1 | A | Pointer Gestures | manual only | - |
| 2.5.2 | A | Pointer Cancellation | manual only | - |
| 2.5.3 | A | Label in Name | partly automatic | `label-content-name-mismatch` |
| 2.5.4 | A | Motion Actuation | manual only | - |
| 2.5.7 | AA | Dragging Movements | manual only | - |
| 2.5.8 | AA | Target Size (Minimum) | mostly automatic | `target-size` |
| 3.1.1 | A | Language of Page | mostly automatic | `html-has-lang`, `html-lang-valid`, `html-xml-lang-mismatch` |
| 3.1.2 | AA | Language of Parts | partly automatic | `valid-lang` |
| 3.2.1 | A | On Focus | manual only | - |
| 3.2.2 | A | On Input | manual only | - |
| 3.2.3 | AA | Consistent Navigation | manual only | - |
| 3.2.4 | AA | Consistent Identification | manual only | - |
| 3.2.6 | A | Consistent Help | manual only | - |
| 3.3.1 | A | Error Identification | manual only | - |
| 3.3.2 | A | Labels or Instructions | partly automatic | `form-field-multiple-labels` |
| 3.3.3 | AA | Error Suggestion | manual only | - |
| 3.3.4 | AA | Error Prevention (Legal, Financial, Data) | manual only | - |
| 3.3.7 | A | Redundant Entry | manual only | - |
| 3.3.8 | AA | Accessible Authentication (Minimum) | manual only | - |
| 4.1.2 | A | Name, Role, Value | mostly automatic | `area-alt`, `aria-allowed-attr`, `aria-braille-equivalent`, `aria-command-name`, `aria-conditional-attr`, `aria-deprecated-role`, `aria-hidden-body`, `aria-hidden-focus`, `aria-input-field-name`, `aria-prohibited-attr`, `aria-required-attr`, `aria-roledescription`, `aria-roles`, `aria-tab-name`, `aria-toggle-field-name`, `aria-tooltip-name`, `aria-valid-attr`, `aria-valid-attr-value`, `button-name`, `duplicate-id-aria`, `frame-title`, `frame-title-unique`, `input-button-name`, `input-image-alt`, `label`, `link-name`, `nested-interactive`, `select-name`, `summary-name` |
| 4.1.3 | AA | Status Messages | manual only | - |

Statement

Accessibility statement (free)Five languages.

The statement generator is part of the free package. This one is in Swiss German, with the status and the known issue taken from the Pro checklist below.

erklaerung.md

# Erklärung zur Barrierefreiheit

Bäckerei Muster ist bemüht, baeckerei-muster.example im Einklang mit den geltenden Anforderungen an die Barrierefreiheit zugänglich zu machen. Diese Erklärung gilt für baeckerei-muster.example.

## Beschreibung der Dienstleistung

Website mit Sortiment, Öffnungszeiten und Newsletter.

## Stand der Vereinbarkeit mit den Anforderungen

Dieses Angebot ist mit WCAG 2.2 AA / EN 301 549 V3.2.1 teilweise vereinbar. Die unten aufgeführten Inhalte sind nicht barrierefrei.

## Nicht barrierefreie Inhalte

- Die Öffnungszeiten auf der Startseite haben zu wenig Kontrast. Geplante Behebung: 31. Oktober 2026

## Erstellung dieser Erklärung

Diese Erklärung wurde am 5. Oktober 2026 erstellt. Die Bewertung beruht auf einer Prüfung durch Pixel & Co.

## Feedback und Kontakt

Sind Ihnen Mängel beim barrierefreien Zugang aufgefallen oder benötigen Sie Inhalte in einer zugänglichen Form? Dann wenden Sie sich bitte an uns:

- E-Mail: hallo@baeckerei-muster.example

Report

Client report (Pro)In your branding.

surjection-report turns the check, the screenshots of the affected elements, the history and the manual checklist into a report for the client, with the logo and colour of the agency, here the made-up Pixel & Co. A section "Fixed since the last report" shows what you fixed, with the element before and after. It is available as HTML, PDF and an editable Word document in German, Swiss German, French, Italian and English.

npx surjection-history record --results a11y.json
npx surjection-checklist apply --checklist checklist.json --results a11y.json
npx surjection-report --results a11y.json --brand brand.json \
  --checklist checklist.json --history-dir .surjection-history \
  --locale de --out bericht.pdf   # or bericht.docx for Word
npx surjection-report --results a11y.json --locale de --out massnahmen.csv

Conformance

Conformance report and ACR (Pro)From the checklist to a document.

Since Pro 2.0 surjection-report turns the decided checklist and the results into a WCAG-EM style conformance report, with the outcome per success criterion, and into an Accessibility Conformance Report with the usual conformance levels. The example is made up, for the Bäckerei Muster site: one criterion fails, thirteen do not apply. Neither document promises legal conformity, and the ACR is not an official VPAT.

npx surjection-report --results a11y.json --brand brand.json \
  --checklist checklist.json --type conformance --out konformitaet.pdf
npx surjection-report --results a11y.json --brand brand.json \
  --checklist checklist.json --type acr --product "Webshop" --out acr.docx

# After a fix: check only what was affected, then update results and checklist
npx surjection-history retest --config surjection.config.json --results a11y.json --out retest.config.json
npx surjection check --config retest.config.json --out-json retest.json
npx surjection-history merge --base a11y.json --update retest.json --out a11y.json
npx surjection-checklist retest --checklist checklist.json --results a11y.json

History

History (Pro)Every client, every run.

surjection-history records each run per project and renders one dashboard for all clients: the latest status, the change since the last run and a trend line. These three projects were checked three times each, from August to October.

Status badges for READMEs and client portals

  • Bäckerei Musteraccessibility: 1 issue
  • Praxis Dr. Kelleraccessibility: 2 issues
  • Velo Huberaccessibility: no issues found
npx surjection-history badge --out-dir badges
# badges/backerei-muster.svg, badges/praxis-dr-keller.svg, badges/velo-huber.svg

Monitoring: what got worse since the last run

Run it on a schedule. The command exits with 1 when new issues reach the chosen impact, so the failed job mails you. In the example one client got two new critical issues:

npx surjection check --config surjection.config.json --out-json a11y.json
npx surjection-history record --results a11y.json
npx surjection-history regressions --fail-on serious --out-md monitoring.md \
  --webhook "$MONITORING_WEBHOOK" --mail-to team@agency.ch --mail-from monitoring@agency.ch
## Accessibility monitoring: Bäckerei Muster

No new issues since the previous run.

## Accessibility monitoring: Praxis Dr. Keller

2 new issues, 0 fixed since the previous run.

| Impact | Page | Rule | Element |
|---|---|---|---|
| Critical | / | `image-alt` | `img` |
| Critical | / | `label` | `input` |

## Accessibility monitoring: Velo Huber

No new issues since the previous run.

Checklist

Manual checklist (Pro)Try it below.

surjection-checklist guides the part no tool can check. The full checklist has all 55 WCAG 2.2 A and AA criteria; this editor shows ten of them, here in English, French and Italian (German and Swiss German are included too). The contrast criterion is already marked as failed by the automated check. Set the others and download the result as JSON.

Free 2.0

What 2.0 adds for everyoneSurjection, free.

Surjection 2.0 can check whole journeys, show honestly what automatic tests cover, give every finding a stable id and test single components. All of it is in the MIT package.

Flows: check every step of a journey

Describe a checkout or sign-up once and the page is checked after each step. Every check shows up as its own page in the report and the baseline.

surjection.config.json (local demo shop)

{
  "baseUrl": "http://127.0.0.1:8099",
  "flows": [
    {
      "name": "checkout",
      "url": "/",
      "steps": [
        {
          "check": "cart"
        },
        {
          "click": "#to-address"
        },
        {
          "waitFor": "#address-form"
        },
        {
          "check": "address"
        }
      ]
    }
  ]
}

npx surjection check --config surjection.config.json

✗ http://127.0.0.1:8099/ (1 issue)
✗ http://127.0.0.1:8099/#flow:checkout:cart (1 issue)
✗ http://127.0.0.1:8099/#flow:checkout:address (3 issues)

5 accessibility issue(s) on 3 page(s).

Coverage: what automatic tests can and cannot decide

See which of the 55 WCAG 2.2 A and AA criteria are tested automatically, partly, or only by a person, so a green run is not mistaken for conformance.

Terminal

npx surjection coverage

Output (first lines and three rows)

# WCAG 2.2 coverage of Surjection

55 success criteria at level A and AA: 11 mostly automatic, 16 partly automatic, 28 manual only.
A passing run is no proof of conformance, not even for "mostly automatic" criteria.

| Criterion | Level | Name | Coverage | Rules |
| --- | --- | --- | --- | --- |
...
| 1.1.1 | A | Non-text Content | partly automatic | `aria-meter-name`, `aria-progressbar-name`, `image-alt`, `input-image-alt`, `object-alt`, `role-img-alt`, `svg-img-alt` |
| 1.3.2 | A | Meaningful Sequence | manual only | - |
| 1.4.3 | AA | Contrast (Minimum) | mostly automatic | `color-contrast` |

Stable ids for every finding

The results file is now version 2. Each affected element gets an id that stays the same between runs, so you can tell a new problem from a known one.

Terminal

npx surjection check --config surjection.config.json --out-json results.json

node -e "const r=require('./results.json');console.log('version',r.version,'tool',r.tool.name+'@'+r.tool.version);for(const p of r.pages)for(const f of p.findings)for(const n of f.nodes)console.log(n.id,f.rule,n.target)"

Version, tool and ids read from results.json (identical in a second run)

version 2 tool surjection@2.0.0
f3c3baacfbbb image-alt #hero
9797a81be492 image-alt #hero
de0fbf6fa9c8 image-alt #hero
877d4ef132f5 target-size #to-address
5cd6660f38ba target-size #email

Convert old files with one command

Results files and baselines from 1.x are still read, and you can rewrite them as version 2 once.

Terminal

npx surjection convert surjection-baseline.json --out surjection-baseline.json

Output (a version 1 baseline with one entry)

Converted baseline surjection-baseline.json to version 2: surjection-baseline.json
{
  "version": 2,
  "createdAt": "2026-09-01T10:00:00.000Z",
  "entries": [
    {
      "id": "f3c3baacfbbb",
      "page": "/",
      "rule": "image-alt",
      "target": "#hero"
    }
  ]
}

Component checks for Storybook and tests

Check a single component in a Storybook play function or a Testing Library test, with no Playwright needed. Page-level rules are switched off.

Test

import { expectAccessibleComponent } from "@sweberdev/surjection/component";

await expectAccessibleComponent(container, { name: "toolbar" });

Failure message (run in jsdom, shortened)

2 accessibility issue(s) on component:toolbar
...
### Issues found

#### Buttons must have discernible text (`button-name`)

- **Critical** · WCAG criteria: 4.1.2 (A)
- Affected elements (1):
  - `button`
- Learn more: https://dequeuniversity.com/rules/axe/4.14/button-name?application=axeAPI

#### Images must have alternative text (`image-alt`)

- **Critical** · WCAG criteria: 1.1.1 (A)
- Affected elements (1):
  - `img`
- Learn more: https://dequeuniversity.com/rules/axe/4.14/image-alt?application=axeAPI

---

Outputs were produced with @sweberdev/surjection 2.0.0 from npm on Node 22.

Read the docs

Pro 2.1.0

Run it in your pipelineSurjection Pro.

Pro 2.1.0 turns the history from a tool you run by hand into something that runs by itself. New issues show up on the pull request, and a daily check tells you when a client site got worse.

One comment per pull requestBeta

Compares the production results with the preview results and posts what is new on the pull request. The comment is updated on every push, so there is no spam, and the job can fail from a chosen severity.

Compare base and head

npx surjection-history pr-comment --base base.json --head head.json --fail-on serious

Ready-made workflowsBeta

init-ci writes the GitHub Actions workflow files for you, so you do not build the pipeline yourself. It never overwrites files that already exist.

Generate the workflows

npx surjection-history init-ci --pull-request --monitor

Scheduled monitoringBeta

The monitoring workflow runs daily and keeps the history in its own branch called surjection-history, so it survives between runs. It fails the job when results got worse.

What the workflow runs

surjection check --out-json a11y.json
surjection-history record --results a11y.json --dir .history
surjection-history regressions --dir .history --fail-on serious --out-md monitoring.md

Alerts only when it got worseBeta

Send a message to Slack, Teams or Discord, or an email, but only when results reach your chosen severity. Nothing is sent when nothing got worse.

Notify by webhook

npx surjection-history regressions --fail-on serious --webhook https://hooks.example/...

The demo cannot show these. They run in your own GitHub repository and need your own production and preview URLs. Both are beta and not yet verified on a real repository.

Read the docs

Next step

Use it in your own projectsPricing is per person.

The check and the statement are free on npm. After checkout, Polar gives your GitHub account access to the Pro packages, which install from GitHub Packages with a read-only token.

See pricing

Surjection does not make a site legally compliant. Automated tests find only part of all barriers.