rsx-a11y

Playground

A static analysis tool that checks for ARIA and accessibility issues in Rust web framework code. Works with Rust web frameworks such as Yew, Leptos and Dioxus by parsing JSX-like macros html!, view!, and rsx! directly.

Inspired by eslint-plugin-jsx-a11y — the same idea, but for Rust.

Quick Start

# Install the CLI
cargo install rsx-a11y

# Lint a file
rsx-a11y src/components/navbar.rs

# Lint an entire project
rsx-a11y src/

# JSON output (for CI)
rsx-a11y --format json src/

Example Output

error: <img> element is missing an `alt` attribute. [alt-text]
  --> src/app.rs:13:13
  help: Add an `alt` attribute with descriptive text, or `alt=""` for decorative images.

warning: Redundant role "button" on <button>. This is the element's implicit role. [no-redundant-roles]
  --> src/app.rs:28:20
  help: Remove the `role` attribute.

warning: <div> with click handler must also have a keyboard event handler. [click-events-have-key-events]
  --> src/app.rs:37:13
  help: Add an `onkeydown` or `onkeyup` handler, or use an interactive element like <button> instead.

Checked 3 files in 12ms. Found 1 error, 2 warnings, 0 infos.

Supported Frameworks

The tool parses all macro invocations using rstml — no compilation or framework dependencies required. Leptos-specific attribute prefixes like on:click and class:active are handled automatically.

Lint Rules (36)

Errors (10)

Warnings (25)

Info (1)

CLI Options

rsx-a11y [OPTIONS] [PATH]

Arguments:
  [PATH]  Path to a Rust file or directory to lint [default: .]

Options:
      --format <FORMAT>    Output format [default: pretty] [possible values: pretty, json]
  -q, --quiet              Only show errors (hide warnings and info)
      --list-rules         List all available lint rules and exit
      --only <RULES>       Only enable specific rules (comma-separated)
      --skip <RULES>       Disable specific rules (comma-separated)
      --out-file <PATH>    Write output to a file instead of stdout
  -h, --help               Print help
  -V, --version            Print version

Examples

# Only check for alt text and ARIA role issues
rsx-a11y --only alt-text,aria-role src/

# Skip the autofocus warning
rsx-a11y --skip no-autofocus src/

# Errors only, for CI
rsx-a11y --quiet src/

# JSON for tooling integration
rsx-a11y --format json src/ > report.json

# Write output to a file
rsx-a11y --out-file report.txt src/

How It Works

1. Walk — Finds all .rs files in the target path, processing them in parallel with rayon. Skips target/, node_modules/, and hidden directories.
2. Parse — Uses syn to parse each file's AST and visit all macro invocations. Uses rstml to parse the token stream inside each macro as HTML elements and attributes.
3. Lint — Runs all enabled lint rules against each extracted element. Each rule provides a severity, description, and help text with WCAG references.
4. Report — Outputs diagnostics sorted by file, line, and column. Supports colored terminal output and JSON.

Dynamic attribute values (e.g. aria-hidden={is_hidden}) are detected but skipped for value validation, since they can't be checked statically.

Library / Testing API

You can use rsx-a11y as a library (without the CLI) to lint a project programmatically — useful for unit tests that enforce accessibility as part of CI.

Add it to your Cargo.toml with default features disabled:

[dev-dependencies]
rsx-a11y = { version = "*", default-features = false }

Then call check_project and assert on the returned LintSummary:

#[cfg(test)]
mod accessibility_tests {
    use std::path::Path;
    use rsx_a11y::prelude::*;

    #[test]
    fn no_accessibility_errors() {
        let summary = check_project(&Path::new(env!("CARGO_MANIFEST_DIR")));

        let errors: Vec<_> = summary.diagnostics
            .iter()
            .filter(|d| d.severity == Severity::Error)
            .collect();

        assert!(errors.is_empty(), "accessibility errors found: {errors:#?}");
    }
}

check_project discovers .rs files, parses RSX macros, runs all 36 lint rules, and returns a LintSummary with sorted diagnostics — no filtering is applied, so you can filter by rule, severity, or file path after the fact:

mod accessibility_tests {
    use std::path::Path;
    use rsx_a11y::prelude::*;

    #[test]
    fn no_missing_alt_text() {
        let summary = check_project(&Path::new(env!("CARGO_MANIFEST_DIR")));

        let alt_issues: Vec<_> = summary.diagnostics
            .iter()
            .filter(|d| d.rule == Rule::AltText)
            .collect();

        assert!(alt_issues.is_empty(), "missing alt text: {alt_issues:#?}");
    }
}

Playground

A browser-based playground is available in the playground/ directory. Built with Leptos and compiled to WebAssembly using Trunk, it lets you paste RSX snippets, select a framework (Yew, Leptos, or Dioxus), and see lint results in real time.

cd playground
trunk serve

Development

# Run all tests
cargo test

# Run the linter on the test fixtures
cargo run -- tests/fixtures/

# List available rules
cargo run -- --list-rules

References

• WAI-ARIA 1.2 Specification
• WAI-ARIA Authoring Practices
• eslint-plugin-jsx-a11y

License

MIT