a11y-shiftleft-cli

KO | EN

gitlite — search

#python #golang #android #machine-learning #rust #linux #docker #macos #windows #awesome-list #vue #security #pytorch #mcp

a11y-shiftleft-cli

(★ 10)

Accessibility checks for web apps, pull requests, visual reports, and CI workflows.

a11y-shiftleft-cli 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# a11y-shiftleft-cli

[![Quality](https://github.com/olboyarshinova/a11y-shiftleft-cli/actions/workflows/quality.yml/badge.svg)](https://github.com/olboyarshinova/a11y-shiftleft-cli/actions/workflows/quality.yml)
[![Accessibility Shift-Left](https://github.com/olboyarshinova/a11y-shiftleft-cli/actions/workflows/a11y.yml/badge.svg)](https://github.com/olboyarshinova/a11y-shiftleft-cli/actions/workflows/a11y.yml)
[![npm version](https://img.shields.io/npm/v/a11y-shiftleft-cli.svg)](https://www.npmjs.com/package/a11y-shiftleft-cli)
[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](https://nodejs.org/)

Catch accessibility issues while you code, not after release.

`a11y-shiftleft-cli` is a local-first, shift-left accessibility audit tool for
frontend developers who are not accessibility specialists. Run one command
against a local, staging, or preview URL. It opens your app in a browser,
safely explores UI states, deduplicates overlapping WCAG-oriented findings, and
generates a visual HTML report with screenshots, keyboard evidence, grouped
issues, and practical fix guidance.

Use it locally during development or add it to CI/CD so pull requests get
repeatable accessibility feedback before issues reach production.

It works with any rendered web app or website, including React, Vue, Angular,
Next.js, Svelte, Astro, Rails, Django, and static HTML. Optional source-code
adapters add framework-aware checks for React, Vue, and Angular. For SPAs and
dynamic pages, the browser audit checks the rendered UI after client-side data
loads, not just the initial HTML source.

## Why It Helps

- Replaces several separate review steps with one developer-friendly workflow.
- Turns raw rule output into grouped, prioritized findings.
- Helps developers understand what to fix without becoming accessibility
  specialists first.
- Lets teams start report-only, then tighten CI gates after they understand the
  findings.

## Built On Known Tools

The CLI orchestrates established engines instead of replacing their rule
systems:

| Engine | Used for |
|---|---|
| [`@axe-core/playwright`](https://www.npmjs.com/package/@axe-core/playwright) | Automated accessibility rules against the rendered page |
| [Playwright](https://playwright.dev/) | Browser automation, safe UI-state exploration, screenshots, and keyboard evidence |
| [ESLint](https://eslint.org/) adapters | Optional source checks for React, Vue, and Angular projects |
| [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) | Optional accessibility score comparison when installed |

The report combines these signals with deduplication, WCAG labels, visual
evidence, compact WCAG review coverage, and manual-review guidance. It is an
evidence workflow, not a replacement for the underlying tools or a conformance
certification.

## 2-Minute Quick Start

Use this when your app already runs locally. You need Node.js 18 or newer, but
you do not need to configure a framework first.

Privacy first: the CLI runs in your project environment and does not upload
source code, screenshots, URLs, cookies, auth state, or report data to an
external analysis server. Reports stay local by default.

Screenshots mask common sensitive fields such as passwords, emails, phone
numbers, payment inputs, and elements marked with `data-a11y-sensitive`. Use
`--no-screenshots` for private, authenticated, or production customer pages.

1. Install the CLI and the Chromium browser used by Playwright:

```bash
npm install --save-dev a11y-shiftleft-cli
npx playwright install chromium
```

2. Start your app in another terminal:

```bash
npm run dev
```

3. Run your first visual audit. Replace `YOUR_PORT` with the port printed by
   your dev server:

```bash
export APP_URL=http://localhost:YOUR_PORT
npx a11y-shiftleft-cli audit --url $APP_URL --out reports --open
```

4. If the report does not open automatically:

```bash
open reports/a11y-report.html
```

On Linux use `xdg-open reports/a11y-report.html`. On Windows PowerShell use
`start reports/a11y-report.html`.

Expected result: `reports/a11y-report.html` opens with summary metrics,
screenshots, grouped findings, WCAG labels, and fix guidance.

## Authenticated Pages

If your app requires login, create a local Playwright auth state first. The CLI
opens a real browser; you log in manually, including 2FA if needed, and then the
session is saved locally.

Enter your username, password, and 2FA code in the browser window opened by the
command, not in the terminal. The CLI does not ask for or store your password.

Authenticated scans are still local-first: login cookies, storage state,
screenshots, URLs, and reports are not sent to an external server by the CLI.

```bash
npx a11y-shiftleft-cli auth login --url https://example.com/login
npx a11y-shiftleft-cli audit --url https://example.com/account --auth-state .a11y-auth/state.json --out reports --open
```

The generated `.a11y-auth/` folder is added to `.gitignore` by default. Do not
commit auth-state files because they may contain session cookies.

See the [authenticated pages recipe](docs/recipes/authenticated-pages.md) for
post-login redirects, existing Playwright `storageState` files, keyboard checks,
CI-safe scripted test-account login, and privacy settings.

If a public site shows a CAPTCHA or "verify you are human" page, run a visual
audit in manual verification mode. The CLI opens a visible browser, waits while
you complete the challenge yourself, and then continues the scan:

```bash
npx a11y-shiftleft-cli audit --url $APP_URL --out reports --pause-on-human-verification --open
```

## Add CI/CD

After the first local audit works, create npm scripts, the starter config,
report `.gitignore` entries, and a report-only CI workflow:

```bash
npx a11y-shiftleft-cli setup --url $APP_URL --start-command "npm run dev"
```

Recommended pull-request setup: scan two or three important smoke-test pages,
keep the crawl bounded, and start in `report-only` mode:

```bash
npx a11y-shiftleft-cli setup \
  --url http://localhost:YOUR_PORT http://localhost:YOUR_PORT/account http://localhost:YOUR_PORT/checkout \
  --crawl-depth 1 \
  --crawl-limit 10 \
  --gate report-only \
  --start-command "npm run dev"
```

After the team reviews the first reports, tighten the PR workflow to
`--gate new-critical-only`. Keep slower full-site audits separate with
`--profile split` or a scheduled/manual workflow.

GitHub Actions is the default. For GitLab CI, add `--ci gitlab`:

```bash
npx a11y-shiftleft-cli setup --ci gitlab --url $APP_URL --start-command "npm run dev"
```

For CircleCI, add `--ci circleci`:

```bash
npx a11y-shiftleft-cli setup --ci circleci --url $APP_URL --start-command "npm run dev"
```

For Jenkins or another shell-based runner, generate a portable script:

```bash
npx a11y-shiftleft-cli setup --ci shell --url $APP_URL --start-command "npm run dev"
```

Optional pre-commit checks can be generated with `--git-hooks husky` or
`--git-hooks lefthook`; they run static accessibility checks in the selected
gate mode against staged frontend files. If the project does not already use
that hook runner, `setup` prints the install command to enable it.

This creates `.a11y-shiftleft.json`, adds `a11y:audit` and `a11y:check` npm
scripts when `package.json` exists, updates `.gitignore`, and adds a CI workflow
that installs the project, runs `npm run build --if-present`, starts your app,
runs accessibility checks, and keeps reports as CI artifacts. Use
`--build-command "<your command>"` for custom generated-code or build steps, or
`--no-build` when CI should start the app without a separate build. Shell setup
creates `scripts/a11y-ci.sh`. GitHub workflows also post a pull request comment.
The default quality gate is `report-only`, so teams can adopt it before failing
builds on legacy issues.

After setup, local checks become:

```bash
npm run a11y:audit
npm run a11y:check
```

Copy-paste CI examples are available for
[GitHub Actions](docs/recipes/github-actions.md),
[GitLab CI](docs/recipes/gitlab-ci.md), and
[CI/CD without SaaS](docs/recipes/ci-without-saas.md).
The GitHub Actions recipe also shows how to generate a CI-safe authenticated
workflow for preview URLs behind login using test-account secrets.

For an existing pipeline, the smallest integration is one npm script:

```json
{
  "scripts": {
    "test:a11y": "a11y-shiftleft-cli check --dynamic --url $APP_URL --out reports"
  }
}
```

## Optional Framework Adapters

You do not need an adapter for the visual browser audit. `audit` and dynamic
`check` run against any rendered URL.

Adapters add source-code checks on top of the browser audit. Install only the
adapter for the framework your project uses:

| Project | Optional adapter | What it adds |
|---|---|---|
| React / Next.js | `@a11y-shiftleft/react` | JSX/TSX accessibility lint rules |
| Vue | `@a11y-shiftleft/vue` | Vue template accessibility lint support |
| Angular | `@a11y-shiftleft/angular` | Angular template accessibility lint support |

```bash
npm install --save-dev @a11y-shiftleft/react
npm install --save-dev @a11y-shiftleft/vue
npm install --save-dev @a11y-shiftleft/angular
```

If you are not sure, skip adapters first and run the browser audit. Add an
adapter later when you want static source findings in the same report.

## What You Get

- A local visual HTML report you can open in your browser.
- Annotated screenshots that show where issues were found.
- WCAG A/AA labels, severity, confidence, and user-impact hints.
- Fix guidance, including contrast ratios and color suggestions.
- Cross-page hints for repeated page titles and potentially inconsistent
  navigation, help mechanisms, and same-purpose control names.
- Separate `needs review` findings when axe cannot prove a result automatically,
  such as text over images, gradients, video, or complex overlays.
- Keyboard evidence and manual-review tasks for things automation cannot prove.

## See The Visual Report

This is the main output of `audit`:

## Audit Or Check?

Start with `audit` when a person needs to review the result. Use `check` when a
pipeline needs a fast pass/fail signal.

| Command | Use it when | Main output | Best for | Typical runtime |
|---|---|---|---|---|
| `audit` | You want a deeper local review with visual evidence | Visual HTML report with screenshots, explored states, keyboard evidence, manual-review checklist, JSON, and Markdown | Local debugging, design/dev review, sharing evidence with a team | Slower |
| `check` | You want a quick automated check against known URL(s) | JSON and Markdown reports, optional CI summary and baseline comparison | Pull requests, CI gates, npm scripts, regression checks | Faster |
| `explore` | You want to debug UI-state discovery itself | Visual exploration report for safe clicks, links, dialogs, and screenshots | Tuning depth, safe-mode blocks, screenshots, and state discovery | Medium |

Rule of thumb: run `audit --url $APP_URL --out reports --open` first. After the
main issues are understood, add `check --dynamic --url $APP_URL --out reports`
to CI.

## Common Commands

The commands below assume `APP_URL` is set to your local, staging, or preview URL.

| Command type | Need | Command |
|---|---|---|
| `audit` | First local review | `npx a11y-shiftleft-cli audit --url $APP_URL --out reports --open` |
| `agent` | Run audit and get local next-step guidance | `npx a11y-shiftleft-cli agent run --url $APP_URL --out reports --open` |
| `agent` | Summarize an existing report | `npx a11y-shiftleft-cli agent review --report reports` |
| `audit` | Quick risk triage | `npx a11y-shiftleft-cli audit --url $APP_URL --profile risk --out reports` |
| `audit` | Broader local scan | `npx a11y-shiftleft-cli audit --url $APP_URL --max-depth 3 --limit 50 --out reports` |
| `audit` | Compare desktop, phone, and tablet layouts | `npx a11y-shiftleft-cli audit --url $APP_URL --devices desktop mobile tablet --out reports/devices` |
| `audit` | Compare Chromium, Firefox, and WebKit evidence | `npx a11y-shiftleft-cli audit --url $APP_URL --browsers chromium firefox webkit --out reports/browsers` |
| `audit` | Check one component or page area | `npx a11y-shiftleft-cli audit --url $APP_URL --scope '#main' --out reports` |
| `check` | Fast CI or PR check | `npx a11y-shiftleft-cli check --dynamic --url $APP_URL --out reports` |
| `check` | Save current known findings as a baseline | `npx a11y-shiftleft-cli check --dynamic --url $APP_URL --out reports --update-baseline` |
| `check` | Block only new critical regressions | `npx a11y-shiftleft-cli check --dynamic --url $APP_URL --out reports --gate new-critical-only --verbose` |
| `check` | Pre-commit static check for changed frontend files | `npx a11y-shiftleft-cli check --static --staged --out reports` |
| `check` | PR static check against a base branch | `npx a11y-shiftleft-cli check --static --changed-since origin/main --out reports` |
| `explore` | Debug visual state discovery | `npx a11y-shiftleft-cli explore --url $APP_URL --out reports` |
| `setup` | Create npm scripts, config, `.gitignore`, and CI workflow | `npx a11y-shiftleft-cli setup --url $APP_URL --start-command "npm run dev"` |
| `generate-ci` | Regenerate only CI workflow files | `npx a11y-shiftleft-cli generate-ci --provider github --url $APP_URL --start-command "npm run dev"` |
| `pr-comment` | Post an existing local report to a GitHub PR | `npx a11y-shiftleft-cli pr-comment --repo owner/repo --pr 123 --report reports --include-labels` |
| `ticket export` | Create reviewable Jira/Linear/GitHub issue drafts from a report | `npx a11y-shiftleft-cli ticket export --report reports/a11y-report.json --out reports/a11y-tickets.md` |
| `evidence export` | Export JSON, JSONL, or JSON-LD finding evidence for scripts or validation studies | `npx a11y-shiftleft-cli evidence export --report reports/a11y-report.json --out reports/a11y-evidence.jsonl --format jsonl` |
| `evidence pack` | Copy report artifacts into a local checksummed handoff package | `npx a11y-shiftleft-cli evidence pack --reports reports --out a11y-evidence` |
| `evidence verify` | Recheck package checksums, privacy notes, review hints, and journey summary before sharing | `npx a11y-shiftleft-cli evidence verify --package a11y-evidence` |
| `ignore audit` | Review expired or invalid temporary exceptions | `npx a11y-shiftleft-cli ignore audit` |
| `ignore cleanup-plan` | Generate a read-only cleanup plan for stale exceptions | `npx a11y-shiftleft-cli ignore cleanup-plan` |
| `doctor` | Diagnose setup problems | `npx a11y-shiftleft-cli doctor --url $APP_URL` |

Use `--update-baseline` only after reviewing the first report. The baseline is
for known existing findings, not a pass certificate. Use `--gate
new-critical-only` while the team fixes legacy issues without allowing new
critical regressions.

By default, `audit` explores up to 2 interaction levels from the start page.
`--max-depth` lets you change that safety limit; it does not mean "scan forever"
or "visit every possible page."

The audit automatically explores safe links, buttons, dialogs, forms, theme
states, and same-origin UI transitions within bounded depth and state limits.
It is designed to find issues earlier, not to certify that every page and every
WCAG criterion has been fully tested.

Use `1` for a quick smoke test, the default `2` for most local reviews, and `3`
or more only when you intentionally want a broader scan.

Use `--scope <selector>` when you want browser checks and safe UI-state
exploration to stay inside one component, dialog, checkout step, or page
section.

Use `--wait-ms <ms>`, `--wait-for-selector <selector>`,
`--wait-until-url <pattern>`, or `--wait-until-path <path>` when a SPA loads
data, redirects after login, or renders authenticated content after the first
paint:

```bash
npx a11y-shiftleft-cli audit --url $APP_URL --wait-for-selector "[data-page-ready]" --out reports
npx a11y-shiftleft-cli audit --url $APP_URL --wait-until-path /dashboard --out reports
```

Use `--navigation-timeout-ms <ms>` when an external or slow staging site times
out before the first screenshot is captured. This changes the initial
`page.goto` timeout; `--wait-ms` only adds settle time after the page opens:

```bash
npx a11y-shiftleft-cli audit --url $APP_URL --navigation-timeout-ms 60000 --out reports
```

Use `--hide-elements <selectors>` when cookie banners, sticky ads, chat widgets,
or other non-product overlays make screenshots noisy. Hidden selectors are
recorded in the visual and Markdown reports.

Use `--browser chromium|firefox|webkit` when you need evidence from another
browser engine. Use `--mobile` for one default phone audit, `--tablet` for one
default tablet audit, or `--device "<Playwright device>"` when you need an exact
Playwright preset. Use `--devices desktop mobile tablet` when you want separate
reports for several responsive profiles in one command. Each profile is written
to its own subfolder under `--out`, with a local comparison summary that points
to the highest-priority differences to review first.

Install the browser engine before using it, for example:

```bash
npx playwright install webkit
```

Use `--browsers chromium firefox webkit` when you want separate reports for
several browser engines in one command. This writes one report per browser plus
local comparison summaries under `--out`, including browser-specific rule
signals and links to matching visual evidence.

Audit profiles are shortcuts:

- `risk`: faster triage with lower depth and fewer explored states.
- `validation`: the standard local evidence profile.
- `full`: broader scan with keyboard activation checks and Lighthouse comparison.
  Install `lighthouse` first when you want this comparison:

```bash
npm install --save-dev lighthouse
```

Explicit flags override profile defaults, for example:

```bash
npx a11y-shiftleft-cli audit --url $APP_URL --profile risk --max-depth 2 --out reports
```

After the report opens:

1. Start with the "Fix First" and screenshot sections.
2. Check the manual-review tasks for keyboard, screen reader, content, and forms.
3. Re-run the same command after fixing issues.

Reports and screenshots usually should not be committed. Run `init --gitignore`
once to add common report paths. For private pages, add `--no-screenshots`.

More recipes for [privacy and local artifacts](docs/recipes/privacy-and-local-artifacts.md),
[user impact review](docs/recipes/user-impact-review.md),
[external validation](docs/recipes/external-validation.md),
[quality gates in existing projects](docs/recipes/quality-gates.md), browser
profiles, hidden overlays, and advanced configuration are in
[Configuration](docs/configuration.md) and [Recipes](docs/recipes/index.md).

## Standards

Use `--standard` when the report needs a specific evidence context:

```bash
npx a11y-shiftleft-cli audit --url $APP_URL --standard wcag22-aa --out reports
npx a11y-shiftleft-cli audit --url $APP_URL --standard section508 --out reports
npx a11y-shiftleft-cli audit --url $APP_URL --standard ada-title-ii --out reports
npx a11y-shiftleft-cli audit --url $APP_URL --standard en301549 --out reports
```

Available presets: `wcag22-aa`, `section508`, `ada-title-ii`, and `en301549`.
They adjust labels, evidence guidance, and report context; they do not certify
legal compliance. See the [Section 508](docs/recipes/section-508.md),
[ADA Title II](docs/recipes/ada-title-ii.md), and
[EN 301 549](docs/recipes/en-301-549.md) recipes for more context.

## Coverage And Limits

- The report supports accessibility review; it is not a WCAG, ADA, Section 508,
  EN 301 549, or EAA certification.
- Use automated evidence together with manual keyboard, screen-reader, content,
  and task-flow review.
- Some public websites block automated scans with bot detection or CAPTCHA.
- Third-party embeds such as YouTube, Vimeo, Spotify, Google Maps, and CodePen
  are marked separately when ownership can be detected.

<details>
<summary>Run the local demo</summary>

This repository includes a React/Vite demo with intentional accessibility
defects.

```bash
nvm use
npm install
npm run demo -- --port 5173
```

In another terminal:

```bash
nvm use
npm run build
export APP_URL=http://localhost:YOUR_PORT
node bin/cli.js audit --url $APP_URL --out reports
```

For the demo command above, replace `YOUR_PORT` with `5173`.

</details>

## Learn More

- [FAQ](docs/faq.md)
- [Recipes](docs/recipes/index.md)
- [Configuration](docs/configuration.md)
- [Visual reports](docs/visual-reports.md)
- [Report sharing and privacy](docs/report-sharing.md)
- [Keyboard focus audit](docs/keyboard-audit.md)
- [WCAG 2.2 coverage](docs/wcag-coverage.md)
- [Evidence methodology](docs/evidence-methodology.md)
- [Roadmap](docs/roadmap.md)
- [Contributing](CONTRIBUTING.md)

a11y-shiftleft-cli

a11y-shiftleft-cli 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

a11y-shiftleft-cli

a11y-shiftleft-cli 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README