---

Table of contents

• What Isoso does
• Install
• Quick start
• Commands
  • isoso scan
  • isoso fix
  • isoso rules
  • isoso explain
• Built-in rules
• Static vs AI scanning
• CI integration
• Security & compliance
• Monorepo layout
• Developing Isoso
• Isoso Cloud
• License

---

What Isoso does

Isoso reads your .tsx / .jsx source (not the live DOM) and flags patterns that commonly break WCAG expectations—missing alt text, clickable <div>s without roles, unlabeled inputs, and more.

flowchart LR
  subgraph input [Your repo]
    JSX[.tsx / .jsx files]
  end
  subgraph isoso [Isoso CLI]
    Parse[Babel JSX extract]
    Static[57 static rules]
    AI[Optional AI pass]
    Report[Text or JSON report]
  end
  subgraph output [Outcomes]
    Term[Terminal]
    CI[Exit code for CI]
    Artifact[JSON artifact]
  end
  JSX --> Parse
  Parse --> Static
  Parse --> AI
  Static --> Report
  AI --> Report
  Report --> Term
  Report --> CI
  Report --> Artifact

Note: Isoso is source-level analysis. It complements—not replaces—browser tools (axe, Lighthouse), screen reader testing, and manual QA.

Isoso Cloud (dashboard, org analytics, GitHub-connected scans, policies) is a separate product. This repository is the open-source CLI and rule engine (Phase 1).

---

Install

npm package: @isoso.dev/isoso (scoped). There is no unscoped isoso package on npm—the name is reserved/blocked. The CLI command is still isoso.

Requirements: Node.js 18+

Run once (no package.json change)

Use the scoped name with npx:

npx @isoso.dev/isoso scan
npx @isoso.dev/isoso rules
npx @isoso.dev/isoso explain --rule img-missing-alt --file src/App.tsx --line 12

Pin a version when you care about reproducibility:

npx @isoso.dev/isoso@0.3.3 scan

Add to the repo you scan (typical)

Install as a dev dependency in the app you want to scan, not in unrelated projects:

npm install -D @isoso.dev/isoso

Then run the isoso binary from that project (local install or npm scripts):

npx isoso scan
isoso rules

npx isoso … uses node_modules/.bin/isoso after install. npm @isoso.dev/isoso is not valid—npm expects subcommands like install, not a package name.

Global install (optional)

npm install -g @isoso.dev/isoso@latest
isoso scan
isoso --version

Global isoso does not auto-update when a new version is published. After upgrades on npm, run npm install -g @isoso.dev/isoso@latest again (or keep using npx @isoso.dev/isoso@latest …).

---

Quick start

# Scan the current directory (AI if ISOSO_AI_KEY is in .env, else static rules)
npx @isoso.dev/isoso scan

# Or, after npm install -D @isoso.dev/isoso in this repo:
npx isoso scan

# Scan a sample app in this monorepo (after clone + build)
npx isoso scan examples/sample-app

# Static only—no API calls
npx @isoso.dev/isoso scan --static

# JSON for pipelines + fail the job on serious+ findings
npx @isoso.dev/isoso scan --format json -o isoso-report.json --fail-on serious

# See every rule id and WCAG mapping (57 rules; fixable rules tagged in output)
npx @isoso.dev/isoso rules

# Auto-fix static findings (preview first, then apply)
npx @isoso.dev/isoso fix --dry-run
npx @isoso.dev/isoso fix

# Explain one rule (AI when a key is set)
npx @isoso.dev/isoso explain --rule img-missing-alt --file src/App.tsx --line 12

Suggested package.json script:

{
  "scripts": {
    "a11y": "isoso scan --static --fail-on serious",
    "a11y:report": "isoso scan --format json -o isoso-report.json",
    "a11y:fix": "isoso fix --dry-run"
  }
}

---

Commands

isoso scan

Scan a project tree for accessibility issues in JSX/TSX.

isoso scan [path] [options]

What gets scanned

• Glob: **/*.{tsx,jsx}
• Ignored: node_modules, dist, build, .next, coverage

Example text output (abbreviated)

Isoso accessibility scan
Engine: static rules
Root: /app
Files scanned: 42
Findings: 3

  critical: 1
  serious: 2

[critical] img-missing-alt — src/Hero.tsx:18:7
  <img> is missing an alt attribute.
  Fix: Add alt="..." describing the image, or alt="" if decorative.

Completed in 124ms

---

isoso fix

Apply automatic codemods for findings from the static rule engine. Each fixable rule id is marked [fixable] in isoso rules. Fixes run on the same .tsx / .jsx files as scan (AI findings are not auto-fixed).

isoso fix [path] [options]

Typical workflow

isoso scan --static
isoso fix --dry-run    # review proposed edits
isoso fix              # apply to disk

Review diffs in git before merging—codemods handle common patterns but cannot replace judgment on every component.

---

isoso rules

Print all static rules with id, human name, severity, and WCAG success criteria references.

isoso rules

Use the ids with --rules or isoso explain --rule <id>.

---

isoso explain

Expand a finding into Summary, Impact, and Remediation.

isoso explain --rule <id> [options]

Environment: ISOSO_AI_KEY in .env (see below). Optional ISOSO_AI_MODEL, ISOSO_AI_BASE_URL, or ISOSO_AI_CHAT_URL for your provider.

---

Built-in rules

57 static checks ship with @isoso/core (images, forms, keyboard, landmarks, media, tables, focus, document structure, autocomplete, captions, and viewport). Severity drives --fail-on and CI gates.

List every rule id, WCAG reference, and severity:

npx @isoso.dev/isoso rules

Categories include: text alternatives (img-missing-alt, svg-missing-accessible-name, role-img-missing-label, …), keyboard & focus (click-without-keyboard-handler, tabindex-zero-without-role, outline-none-utility, …), forms (input-missing-label, label-without-htmlfor, fieldset-needs-legend, …), links & buttons, landmarks (nav-missing-label, multiple-main-landmarks, …), media, and document (html-missing-lang, multiple-h1).

Run a subset:

npx @isoso.dev/isoso scan --static --rules img-missing-alt,button-missing-name

---

Static vs AI scanning

Auto behavior

1. If ISOSO_AI_KEY is set → AI scan (unless --static).
2. If no key → static rules (CLI prints a yellow hint).
3. --ai → fail fast if no key.

Setup

1. Copy .env.example → .env in this repo or in the app where you run isoso.
2. Set ISOSO_AI_KEY=... (your provider’s API key)
3. Run npx @isoso.dev/isoso scan (omit --static), or isoso scan after a local install.

The CLI walks upward from the current working directory to find .env.

cp .env.example .env
# edit .env, then:
npx @isoso.dev/isoso explain --rule img-missing-alt --file src/App.tsx --line 24

Use --builtin on explain when you want zero network calls.

Custom AI provider (chat completions JSON API):

---

CI integration

Run isoso scan in any CI pipeline (GitHub Actions, GitLab CI, etc.). Exit code 1 when findings meet or exceed --fail-on.

# Example GitHub Actions step
- run: npx @isoso.dev/isoso scan --static --format json --fail-on serious -o isoso-report.json

Severity gate: --fail-on serious fails on critical and serious findings. Use --fail-on critical for a looser gate, or --fail-on moderate for stricter.

Tips

• Prefer --static in CI for speed and predictable cost.
• Store ISOSO_AI_KEY in CI secrets only if you intentionally run AI in the pipeline.
• GitHub org integration (connect repos, PR scans, dashboard history) is Isoso Cloud only—not part of this CLI.

---

Security & compliance

Read this before you gate releases, publish compliance claims, or treat scan output as proof of accessibility.

No WCAG or legal compliance guarantee

Isoso does not certify, audit, or guarantee that your application meets WCAG 2.x (any level), ADA, Section 508, EN 301 549, EAA, or any other accessibility standard or law.

Rule ids and WCAG references in isoso rules describe why a pattern is risky, not a determination that your product complies or violates the law. You remain responsible for your product’s accessibility and legal obligations.

Source-level analysis only

The CLI analyzes .tsx / .jsx source files—not the live DOM, runtime CSS, content from CMS/APIs, PDFs, native apps, or third-party embeds. Findings can be false positives (safe patterns flagged) or false negatives (issues only visible at runtime or in production builds).

Use Isoso together with browser tools (e.g. axe DevTools, Lighthouse), manual testing, assistive technology checks, and professional audits when compliance matters.

Auto-fix (isoso fix) risks

Codemods apply mechanical edits. They can change behavior, break tests, or miss context (decorative vs informative images, custom components, design-system wrappers). Always review git diffs before merge; do not run fix unattended on production branches without review.

AI scanning and explain

When ISOSO_AI_KEY is set, file snippets and rule context may be sent to your configured AI provider. You are responsible for provider terms, data handling, and never committing API keys to git.

• Prefer --static in CI when you want zero external data transfer.
• Use --builtin on explain for offline, curated copy only.
• AI output can vary by model and is not deterministic legal or compliance advice.

Secrets and environment

The CLI loads .env by walking up from the current working directory—it does not encrypt or store keys beyond what your shell and provider do.

Severity gates are policy, not law

--fail-on controls exit codes for your pipeline (e.g. fail on serious and above). That is your quality bar, not a mapping to WCAG conformance levels or legal safe harbor.

Isoso Cloud

Dashboard scans, policies, and GitHub-connected runs on isoso.dev are subject to separate Terms and Privacy Policy. Cloud storage of findings does not mean your application is compliant.

Reporting security issues

If you believe you have found a security vulnerability in the Isoso CLI (not an accessibility finding in your app), report it responsibly via info@isoso.dev (subject: security). Do not open public issues with exploit details before coordination.

---

Monorepo layout

Published @isoso.dev/isoso bundles vendored @isoso/core and @isoso/scanner for a single install.

---

Developing Isoso

From the monorepo root:

npm install
npm run build
npm test                    # @isoso/core unit tests
npx isoso scan examples/sample-app

Sample violations: examples/sample-app/BadExample.tsx intentionally breaks several rules—use it to verify scans locally.

---

Isoso Cloud

Need org-wide dashboards, GitHub-connected repo scans, teams, policies, and billing? That lives in Isoso Web / Cloud, not in this CLI repo. The CLI remains the open-source local and CI story; cloud scans align on the same rule IDs where static heuristics apply.

---

License

MIT — see LICENSE.

---