VertaaUX Assistant for VS Code

Local a11y source scanning + hosted URL audits, all from the editor. Save a file → see accessibility findings inline (ESLint-style squigglies + Problems panel). Audit public URLs with the hosted runtime engine, or run static localhost analysis from captured HTML when working on a local dev server.

Status: Marketplace pre-release candidate (0.5.x). Two working feature streams: local source scan (primary) and hosted public-URL audits plus static localhost analysis (secondary). Mapping of URL-audit findings back to source files, CSS contrast linting, and a full local browser runner are on the roadmap for later milestones.

Install

• Marketplace pre-release: after the listing is live, install the pre-release build from the VS Code Marketplace extension page.
• From a .vsix: download the latest release artifact and run code --install-extension vertaaux-assistant-*.vsix.
• From source: cd extensions/vscode && npm install && npm run package, then install the produced .vsix.
• Open VSX: planned after Marketplace pre-release validation.

Quick Start

1. Install the extension and reload VS Code.
2. Open any project with .tsx, .jsx, .html, or .htm files. Save one of them — a11y findings appear in the Problems panel and as squigglies in the editor (ESLint-style). No auth, no server, no quota.
3. Use the lightbulb on supported findings for safe placeholder fixes such as adding decorative alt="", lang="en", or empty frame-title placeholders.
4. Run VertaaUX: Audit Codebase (Cmd+K A / Ctrl+K A) to scan your whole workspace at once with a progress notification.
5. Right-click a finding or file group in the VertaaUX Issues tree to copy a fix prompt for AI, export reports, or prepare GitHub, Linear, and Slack handoff text.
6. Use the gear in the VertaaUX side panel, or click the VertaaUX status bar item, for account, export, settings, logs, docs, and about/version info.
7. For runtime testing of an actually-rendered public page, run VertaaUX: Audit URL… (Cmd+K U / Ctrl+K U). For local dev servers, run VertaaUX: Audit Localhost (Cmd+K L / Ctrl+K L) to capture local HTML and run authenticated static analysis. Results open in a side panel with scores and findings.

Features

Local source scan (primary)

Inline a11y diagnostics powered by eslint-plugin-jsx-a11y (39 rules) + a static subset of axe-core (10 HTML rules). No auth required; everything runs locally inside the VSIX.

Supported file types: .tsx, .jsx, .ts, .js, .mts, .mjs, .cts, .cjs, .html, .htm.

Rule categories covered:

• Images & media — missing alt, redundant alt text, missing captions on video/audio.
• ARIA — invalid aria-* attributes / values, missing required attrs for roles, conflicting role/element combinations, aria-hidden on focusable elements.
• Forms — missing labels, invalid autocomplete, positive tabindex.
• Keyboard — clickable elements without keyboard handlers, mouse-only handlers, non-interactive elements with interactive roles.
• Document structure — missing <title>, missing lang, heading-order violations, duplicate IDs, missing <main> landmark.
• Semantic — anchor without content, heading without content, frame without title.

Auto-trigger: on file save (ESLint-style). Toggle via vertaaux.sourceScan.onSave (default true).

Quick fixes: supported findings expose VS Code lightbulb actions for narrow, deterministic edits. Content decisions such as meaningful image alt text remain a human review step.

Workspace ESLint dedup: if your project already has eslint-plugin-jsx-a11y configured, VertaaUX defers to it and only runs the HTML scanner on top. Override with vertaaux.sourceScan.forceRunEvenIfWorkspaceEslint.

Hosted URL / Localhost audits (secondary)

Public URL audits run against a real rendered page. VertaaUX spins up Puppeteer on our servers, runs axe-core + our analyzers against the actual DOM, returns scores per category (accessibility, usability, clarity, conversion, IA, semantic, keyboard) plus findings with recommended fixes. Results open in a webview panel.

Localhost audits are different by design: the hosted runtime engine cannot fetch localhost, 127.0.0.1, private IPs, or internal hosts because the API has SSRF protection. VertaaUX: Audit Localhost captures HTML locally from the detected dev server and sends that HTML to /api/v1/analyze for authenticated static analysis. This avoids the SSRF failure, but it is partial: rendered layout, keyboard navigation, focus order, contrast, and interaction checks require a public URL or a future local browser runner.

Detects things source scan can't: color contrast on rendered elements, keyboard focus order, responsive layout issues, conversion-funnel problems.

When hosted audit findings include source file and line metadata, VertaaUX also mirrors them into VS Code diagnostics so they appear alongside local findings.

Finding handoff and export

The VertaaUX Issues tree merges local source diagnostics and hosted audit diagnostics by file. Findings are labeled as Local or Hosted, and the same visible diagnostics drive every copy/export action.

Supported handoff formats:

• AI fix prompt, prioritized by severity and confidence.
• Markdown report.
• JSON envelope for automation.
• SARIF 2.1.0 for security and quality tooling.
• GitHub issue Markdown.
• Linear task Markdown.
• Slack summary.

Copy commands write to the VS Code clipboard. Export commands open a save dialog and write .md, .json, or .sarif files locally.

Quota:

Localhost static analysis uses /api/v1/analyze and requires an API key in this pre-release.

Credentials stored in VS Code's SecretStorage (OS keychain), never plain-text.

Browser-based OAuth sign-in is hidden by default in this pre-release because the production API has not enabled the VS Code OAuth client yet. Use VertaaUX: Paste API Key for authenticated hosted audits.

Commands

The VertaaUX side panel also has a gear action that opens the account/settings menu. The same menu is available from the status bar item.

All commands are also in the Command Palette (Cmd+Shift+P / Ctrl+Shift+P, search for "VertaaUX"). Rebind any keybinding via VS Code's Keyboard Shortcuts UI (Cmd+K Cmd+S / Ctrl+K Ctrl+S).

Configuration

Troubleshooting

• No findings on a file I expected issues in. Make sure the file extension is in vertaaux.sourceScan.include. .vue and .svelte are not yet supported. Also: if the workspace has its own eslint-plugin-jsx-a11y, VertaaUX defers to it — check the eslint output channel for the workspace ESLint's output, or set vertaaux.sourceScan.forceRunEvenIfWorkspaceEslint to true to get our findings alongside.
• Duplicate diagnostics. Your workspace likely has eslint-plugin-jsx-a11y AND vertaaux.sourceScan.forceRunEvenIfWorkspaceEslint set to true. Pick one.
• Hosted audit 400 Bad Request. The source: "ide-extension" value isn't accepted by the server you're pointing at. Point vertaaux.apiBaseUrl at the production https://vertaaux.ai or a recent enough self-hosted build.
• Localhost audit says private or disallowed host. Update to 0.5.6 or later. Earlier builds sent http://localhost:<port> to the hosted runtime endpoint, which the API rejects by design. Current builds use local HTML capture plus authenticated static analysis.
• No dev server detected. Run your app (npm run dev, pnpm dev, etc.) before running Audit Localhost. Add ports to vertaaux.localhost.ports if your setup uses something non-standard.
• Browser sign-in is missing. Browser sign-in is hidden until the configured API enables the VS Code OAuth client. Use VertaaUX: Paste API Key or the side-panel gear -> Paste API Key; setup docs live at https://vertaaux.ai/docs/vscode-extension.
• Sign-in says invalid_client / Unknown client_id. Disable vertaaux.auth.deviceFlowEnabled and use VertaaUX: Paste API Key. The configured API does not recognize the VS Code OAuth client.
• Hosted audit quota exhausted. Anonymous limit is per-IP (3/day). Sign in, or wait until UTC midnight for the counter to reset.

Rule catalog

JSX/TSX (via eslint-plugin-jsx-a11y, recommended ruleset)

39 rules covering ARIA validity, role/element constraints, keyboard parity, form labeling, media captions, semantic structure, and more. Full catalog.

HTML (axe-core static subset)

10 rules that don't require a rendered DOM:

• axe/image-alt — images without alt text
• axe/document-title — missing or empty <title>
• axe/html-has-lang — missing lang on <html>
• axe/label — form controls without associated labels
• axe/aria-valid-attr — invalid aria-* attribute names
• axe/aria-valid-attr-value — invalid enum values on aria-hidden/aria-expanded/aria-checked
• axe/duplicate-id — duplicate id attributes
• axe/frame-title — iframes without title
• axe/heading-order — heading levels skipped (h1 → h3)
• axe/landmark-one-main — zero or more than one <main> element

Each finding is linked to the rule's public documentation via a clickable code link in the Problems panel. Findings below vertaaux.confidenceThreshold are filtered out, and each file is capped by vertaaux.maxDiagnosticsPerFile.

Development

cd extensions/vscode
npm install
npm run build      # tsc → out/
npm run watch      # tsc -w
npm run lint       # eslint src
npm test           # @vscode/test-electron smoke + unit suite
npm run package    # vsce package → stable VSIX
npm run package:pre # vsce package --pre-release → Marketplace pre-release VSIX

Press F5 in this folder to launch an Extension Development Host with the extension loaded.

Roadmap

• 0.5.x (current): local source scan primary + hosted URL/localhost audits secondary.
• Next: findings-to-source mapping on hosted audits — link a DOM finding back to the exact JSX file/line that produced it (via React __source pragma + a data-vx-source bundler plugin for other frameworks).
• After that: CSS contrast + focus-indicator rules (still local where possible).
• 1.0: stable Marketplace + Open VSX publish, anonymous-tier quota via install-ID, opt-in telemetry, bundled extension via esbuild (VSIX < 2 MB).

Resources

• VS Code Extension Documentation
• VertaaUX Platform
• VertaaUX CLI
• eslint-plugin-jsx-a11y rule catalog
• axe-core documentation
• VS Code Extension API

License

MIT — see LICENSE.