Autumn is designed to produce WCAG 2.1 AA-compliant HTML by default. This guide explains the built-in helpers, the patterns recommended for htmx-driven pages, and how to integrate autumn check --a11y into your CI pipeline.


Quick-start checklist

Every page served by an Autumn app should satisfy these five requirements:

  1. <html lang="en"> (or the appropriate BCP-47 tag)
  2. A skip-to-content link as the first focusable element
  3. Landmark regions: <header role="banner">, <main>, <footer role="contentinfo">
  4. An ARIA live region for htmx swap announcements
  5. All form controls have an associated <label>

The scaffold generated by autumn new already includes items 1–4. Items 5 and beyond are enforced by the form helpers described below.


Form helpers (autumn_web::form)

Import the helpers you need:

Rust
use autumn_web::form::{
    text_input, password_input, textarea_input, required_text_input,
    checkbox_input, number_input, date_input, datetime_input, select_input,
    aria_live_region, skip_link,
};

text_input

Rust
pub fn text_input<T: Serialize>(
    changeset: &Changeset<T>,
    field: &str,
    label: &str,
) -> maud::Markup

Renders a labelled <input type="text"> with:

  • <label for="{field}"> linked via matching id="{field}" on the input
  • Inline error message (wrapped in role="alert") when the changeset has a validation error for that field
  • aria-invalid="true" and aria-describedby pointing at the error element
Rust
html! {
    (text_input(&changeset, "username", "Username"))
}

password_input

Identical to text_input but renders <input type="password"> and never sets value=, preventing password leakage into the DOM.

Rust
html! {
    (password_input(&changeset, "password", "Password"))
}

password_input_with has these options for a password. See Forms.

  • reveal() adds a toggle button with aria-pressed. Its label does not change, so a screen reader announces one control with a state. The button is hidden until the script runs, so a user never finds a button that does nothing.
  • strength_hint() adds a polite live region, linked by aria-describedby. It speaks only when the level changes. The region is in the accessibility tree before the first level, and each label names its subject ("Strength: weak").
  • current_password() and new_password() set autocomplete, so a password manager fills the field (WCAG 3.3.8).

otp_input

One <input autocomplete="one-time-code" inputmode="numeric"> over a row of aria-hidden boxes. A screen reader finds one field with one label, not one field for each digit. SMS autofill and paste fill the whole code.

required_text_input and the other required_* helpers

Like text_input but adds both the HTML required attribute and aria-required="true" so assistive technology announces the field as mandatory. The label also shows a * marker with aria-hidden="true", so a screen reader does not say "required" two times. Each control has a required_* helper, for example required_password_input, required_textarea_input and required_checkbox_input.

Rust
html! {
    (required_text_input(&changeset, "email", "Email address"))
}

Hints and attributes: the *_with helpers

Each helper has a *_with variant that takes &FieldOptions. A hint renders between the label and the control with id="{field}-hint", and aria-describedby names it before the error. FieldOptions has no setter for id, name or aria-*, so the links between the label, hint, error and control stay correct. See the forms guide.

textarea_input

Renders a labelled <textarea> with the same error-linking pattern.

Rust
html! {
    (textarea_input(&changeset, "body", "Post body"))
}

checkbox_input

Renders a labelled <input type="checkbox"> for a bool field. Unchecked checkboxes are omitted from submitted form data by the browser, so the target field must be marked with #[serde(default)] to decode as false when absent (rather than pairing it with a hidden input sibling, which would cause duplicate-key errors on checked submissions).

Rust
html! {
    (checkbox_input(&changeset, "published", "Published"))
}

number_input

Renders a labelled <input type="number"> for i32/i64/f32/f64 fields. Pass step to control the HTML step attribute — Some("1") for integers, Some("0.01") or Some("any") for floats, None for the browser default.

Rust
html! {
    (number_input(&changeset, "quantity", "Quantity", Some("1")))
    (number_input(&changeset, "price", "Price", Some("0.01")))
}

date_input / datetime_input

Render <input type="date"> and <input type="datetime-local"> respectively. The current value is normalized to the shape each control requires (YYYY-MM-DD / YYYY-MM-DDTHH:MM[:SS[.f]], preserving seconds/fractional seconds when present), regardless of whether the underlying field serializes as a bare date or a full RFC 3339 timestamp.

Rust
html! {
    (date_input(&changeset, "birthday", "Birthday"))
    (datetime_input(&changeset, "starts_at", "Starts at"))
}

<input type="datetime-local"> has no timezone concept, so a Timestamp field's rendered value never carries an offset — the default Deserialize for autumn_web::time::Timestamp (a jiff::Timestamp) requires one and rejects the submission. Attach deserialize_datetime_local_utc (or deserialize_datetime_local_utc_option for Option<Timestamp>). It reads the offsetless value as UTC and still accepts RFC 3339 with an offset, so a struct that doubles as a JSON body keeps decoding:

Rust
#[derive(serde::Deserialize)]
struct EventForm {
    #[serde(deserialize_with = "autumn_web::form::deserialize_datetime_local_utc")]
    starts_at: autumn_web::time::Timestamp,
}

civil::DateTime fields don't hit that offset problem, and the default Deserialize reads a value without seconds, which the browser's native picker may post. It is looser than the control, though: it also takes a bare date (as midnight) and a value with an offset, which it drops. Attach deserialize_naive_datetime_local (or deserialize_naive_datetime_local_option for Option<civil::DateTime>) to accept exactly the YYYY-MM-DDTHH:MM[:SS[.f]] shape the control posts:

Rust
#[derive(serde::Deserialize)]
struct EventForm {
    #[serde(deserialize_with = "autumn_web::form::deserialize_naive_datetime_local")]
    starts_at: autumn_web::time::civil::DateTime,
}

select_input

Renders a labelled <select> from (value, label) option pairs. It marks the first option that matches the changeset's current value as selected. This is the control closed-set fields (enums, references) target.

Rust
let statuses = [("draft", "Draft"), ("published", "Published")];
html! {
    (select_input(&changeset, "status", "Status", &statuses))
}

grouped_select_input adds <optgroup> elements, and FieldOptions::multiple() adds multiple. See Forms.

  • The control stays a native <select>. The browser gives each group label to assistive technology. The browser supplies the keyboard support.
  • FieldOptions::styled_select() changes only CSS (appearance: base-select). The element and its role do not change. The browser keeps the keyboard support: the arrow keys open the picker, Enter chooses an option and Escape closes the picker. With no browser support, the native control shows.

Native inputs and choice groups

switch_input, range_input, radio_group, checkbox_group, segmented_control, email_input, tel_input, url_input, time_input, month_input, color_input and hidden_input use native controls. See Forms.

  • A switch is <input type="checkbox" role="switch">. A screen reader says "on" or "off".
  • A radio group, a checkbox group and a segmented control are a <fieldset> with a <legend>. The hint and error links (aria-describedby, aria-invalid) go on the <fieldset>.
  • A radio gets required, not aria-required: ARIA does not allow aria-required on a radio.
  • A segmented radio is visually hidden, but it stays in the Tab order. The arrow keys move the selection, and the label shows the focus ring.
  • A hidden input has no label. It is not visible and not announced.

Renders a visually hidden "Skip to …" anchor that becomes visible on keyboard focus. Place it as the first element inside <body>.

Rust
html! {
    (skip_link("#main-content", "Skip to main content"))
    header role="banner" { ... }
    main id="main-content" { ... }
}

The helper emits class="skip-link". The Autumn CSS template already ships the matching Tailwind utilities (-top-full at rest, top-0 on :focus) in input.css.

aria_live_region

Renders a <div role="status" aria-live="polite" aria-atomic="true"> that screen readers monitor for updates. Keep the element present in the DOM at all times and update its text content via an htmx out-of-band swap — this avoids focus loss.

Rust
html! {
    (aria_live_region("htmx-status", ""))   // empty at page load
}

htmx patterns for accessible interactivity

Announcing dynamic updates without moving focus

When htmx swaps content into the page, keyboard and screen-reader users lose context if focus jumps unexpectedly. The recommended pattern:

  1. Add a persistent live region near the top of <body>:

    Html
    <div id="htmx-status" role="status" aria-live="polite"
         aria-atomic="true" class="sr-only"></div>
    
  2. In every htmx response that changes meaningful content, include an out-of-band update to announce the change:

    Html
    <!-- primary swap target -->
    <div id="post-list"> ... </div>
    
    <!-- screen-reader announcement (oob) -->
    <div id="htmx-status" hx-swap-oob="true">Post submitted.</div>
    
  3. Clear the region after a short delay by including an empty update in the next response, or use a small JavaScript snippet:

    Js
    document.body.addEventListener('htmx:afterSwap', () => {
      setTimeout(() => {
        const r = document.getElementById('htmx-status');
        if (r) r.textContent = '';
      }, 2000);
    });
    

The Autumn CSRF script (autumn-htmx-csrf.js) is already loaded from a separate file so pages can use script-src 'self' in their CSP headers — no inline event listener code is needed in the HTML.

Managing focus after htmx navigation

For operations that replace the entire <main> region (e.g. pagination, form submission), explicitly move focus to a heading or the main landmark so keyboard users know what changed:

Html
<!-- response HTML -->
<main id="main-content" tabindex="-1">
  <h1 autofocus>Search results</h1>
  ...
</main>

Or trigger focus programmatically with the htmx:afterSwap event:

Js
document.body.addEventListener('htmx:afterSwap', e => {
  const heading = e.detail.target.querySelector('h1, h2, [data-focus]');
  if (heading) heading.focus({ preventScroll: true });
});

Color contrast with Tailwind

Autumn's generated Tailwind config uses the default Tailwind color palette. The following combinations used in the scaffold templates meet the WCAG 2.1 AA 4.5:1 contrast ratio for normal text and 3:1 for large text and UI components:

ForegroundBackgroundRatioUsage
gray-900gray-10016:1Body text on page
gray-700white9.5:1Secondary nav links
whiteorange-5003.1:1CTA buttons (large text)
orange-600white4.7:1Inline links
gray-400white2.6:1Avoid — placeholder/hint text only, never body text

Warning: text-gray-400 on white falls below 4.5:1. Use it only for supplemental placeholder text. For any text that carries meaning, use text-gray-600 (5.9:1) or darker.

To verify contrast ratios during development:

Shell
# Using the axe browser extension (Chrome/Firefox) on the dev server
autumn dev
# Then open DevTools → axe → Analyse

Or run the Autumn a11y checker (see below) against the rendered HTML.


Keyboard-only navigation testing checklist

Perform this manual checklist before shipping any new page or component:

  • [ ] Tab through the page from the skip link — every interactive element is reachable in a logical order
  • [ ] Skip link appears visibly on first Tab keypress and navigates to #main-content
  • [ ] All buttons and links have a visible focus indicator (:focus-visible ring)
  • [ ] Dropdown menus and modals trap focus correctly (tabindex="-1" on container + manual focus management)
  • [ ] Form submission errors are announced by the screen reader without page reload (use role="alert" on error summaries)
  • [ ] htmx-powered interactions do not silently replace content — the live region announces the change
  • [ ] No keyboard trap: pressing Escape or Tab always allows leaving a widget
  • [ ] Tabs, menus and listboxes use the APG arrow keys. See the keyboard core.
  • [ ] Images have meaningful alt text; purely decorative images use alt=""
  • [ ] All form fields have a visible <label> (not just placeholder)

autumn check --a11y

The CLI ships a static accessibility linter that scans HTML for common WCAG violations. It runs entirely in Rust — no Node.js or browser dependency.

Usage

Shell
# Check a running development server
autumn check --a11y --url http://localhost:8080

# Check pre-rendered HTML. `--html` takes the markup itself, so the shell
# reads the file — there is no file or stdin flag.
autumn check --a11y --html "$(cat rendered.html)"

# Only fail CI on Critical violations (Serious and Moderate are reported but
# exit 0)
autumn check --a11y --url http://localhost:8080 --critical-only

Rules

Rule IDSeverityWhat it checks
html-has-langSerious<html> element has a non-empty lang attribute
bypassSeriousFirst focusable element is a skip link to #main
landmark-one-mainModeratePage contains exactly one <main> element
image-altCriticalEvery <img> has an alt attribute (may be empty)
labelCriticalEvery <input> (non-hidden) has an associated <label>
button-nameCriticalEvery <button> has discernible text or aria-label

The severity decides whether a finding stops the build, so it is worth reading off this table rather than assuming: Critical always fails, Serious fails unless you pass --critical-only, and Moderate is reported with a ⚠️ and never changes the exit code. landmark-one-main is the one to note — a missing or duplicated <main> is a warning, not a failure.

bypass is skipped entirely when the main landmark is the first thing inside <body>: there is nothing before it to skip past, so no skip link is required.

CI integration

Add a job step that runs the checker against a preview deployment or a pre-rendered snapshot:

Yaml
# GitHub Actions example
- name: Accessibility check
  run: |
    cargo install autumn-cli --locked
    autumn check --a11y --url ${{ env.PREVIEW_URL }}

Exit code 0 means no Critical or Serious violations — a run whose only findings are Moderate reports them and still exits 0. Exit code 1 means at least one Critical or Serious violation was found, or, with --critical-only, at least one Critical.

From a test

--html takes markup on the command line, so a test can check a component without serving anything. Pass it a whole document, not a bare fragment. The checker audits a page: html-has-lang, bypass and landmark-one-main run on every input, so a naked <form> fails all three on the document it is missing rather than on anything wrong with the form.

Wrapping the fragment in a three-tag shell is enough to put those rules at rest and leave the assertion about your markup. A <main> as the first thing in <body> satisfies bypass with no skip link — there is nothing before the landmark to skip:

Rust
use std::process::Command;

#[test]
fn comment_form_is_accessible() {
    // Render your `Markup` to a String however your app does it.
    let page = format!(
        r#"<html lang="en"><body><main>{}</main></body></html>"#,
        comment_form().into_string(),
    );

    let out = Command::new("autumn")
        .args(["check", "--a11y", "--html", &page])
        .output()
        .expect("could not run `autumn` (on PATH? markup under the argv limit?)");

    assert!(
        out.status.success(),
        "a11y violations:\n{}",
        String::from_utf8_lossy(&out.stdout),
    );
}

The exit code is the assertion: 0 when no Critical or Serious violation was found, 1 otherwise, exactly as in CI above. Add --critical-only to let Serious violations pass as warnings.

If your layout helper already emits the <html>/<main> shell, render through it instead of hand-rolling one — then the test covers the real page.

--html has a size ceiling, so use --url for whole pages. The markup travels as one command-line argument, and the OS caps that: Linux rejects a single argument over ~128 KiB with E2BIG, and Windows caps the entire command line near 32 KiB. A full rendered page can cross either. Past the limit the checker never starts — Command::output() returns an Err before any audit runs, which is why the expect above does not claim a missing binary as the cause. For a whole page, serve it and point --url at it, as in the CI example above; keep --html for fragments, where the limit is not in reach.

There is no library import for the checker. autumn-cli ships a binary and no lib target, so use autumn_cli::… does not resolve from another crate no matter how the path is spelled — run the command, as above.


Actuator endpoint: /actuator/a11y

When you implement ProvideActuatorState for your application state, you can expose an accessibility posture endpoint:

Rust
impl ProvideActuatorState for AppState {
    fn a11y_posture(&self) -> autumn_web::actuator::A11yPosture {
        autumn_web::actuator::A11yPosture {
            lang_set: true,
            skip_link_present: true,
            landmark_regions_present: true,
        }
    }
}

The endpoint is available at GET /actuator/a11y and returns:

Json
{
  "lang_set": true,
  "skip_link_present": true,
  "landmark_regions_present": true
}

is_compliant() returns true only when all three fields are true. You can poll this endpoint in health checks or monitoring dashboards to confirm your accessibility posture hasn't regressed.


Typed accessible primitives (autumn_web::a11y)

The form helpers above make the right thing easy. The primitives in autumn_web::a11y go one step further and make the wrong thing impossible: they encode the accessible name as a type-level obligation, so an image without alt text, a button without a name, or an input without a label does not compile. This is accessibility conformance by construction, proven at build time by the framework's compile-fail test harness.

Each primitive implements maud::Render, so it splices straight into an html! block, and maps to a specific WCAG 2.1 success criterion:

PrimitiveWCAG SCObligation
Img1.1.1 Non-text Contentalt is a required constructor argument
Button4.1.2 Name, Role, Valueaccessible name is a required constructor argument
Link2.4.4 Link Purpose (In Context) / 4.1.2 Name, Role, Valuelink text is a required constructor argument
MenuItem4.1.2 Name, Role, Valueaccessible name is a required constructor argument (renders role="menuitem")
TextField1.3.1 Info and Relationships / 3.3.2 Labels / 4.1.2only a labeled field can be rendered (typestate)
RadioGroup1.3.1 Info and Relationships / 3.3.2 Labels / 4.1.2only a labeled group can be rendered; each choice carries its own label
Rust
use autumn_web::a11y::{Button, Img, Link, MenuItem, TextField};
use autumn_web::html;

let page = html! {
    (Img::new("/logo.svg", "Autumn logo"))                 // alt required
    (Img::decorative("/divider.svg"))                       // explicit alt=""
    (TextField::new("email").input_type("email").label("Email address"))
    (Button::icon(html! { span aria-hidden="true" { "🗑" } }, "Delete"))
    (Button::new("Save").submit())
    (Link::new("/about", "About us"))                       // link text required
    (Link::new("https://example.com", "Docs").new_tab())    // rel="noopener noreferrer"
    (MenuItem::new("Settings"))                             // role="menuitem", name required
    (MenuItem::new("Home").href("/"))                       // link-style menu item
};

TextArea, Select (with SelectOption), Checkbox, FileField and RadioGroup (with RadioOption) carry the same typestate obligation as TextField. A radio group needs two names — one per choice and one for the group — so both are required:

Rust
use autumn_web::a11y::{RadioGroup, RadioOption};

let speed = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
    .option(RadioOption::new("express", "Express"))   // each choice names itself
    .checked_value("express")
    .label("Shipping speed");                         // the group names itself

The first choice is a constructor argument, so a group of choices always has at least one. A visible group name renders <fieldset><legend>; .aria_label(..) / .labelled_by(..) render a <div> instead. Both carry role="radiogroup" — <fieldset> alone maps to role group, which does not support aria-required. Each choice gets an id that pairs it with its own <label for=…>, derived from the group name and the choice value. Each byte other than a letter, digit or _ is written --HH (upper-case hex), so two groups never give the same id: plan-type gives plan--2Dtype-…. The second choice with the same value ends in --n1. The third ends in --n2. The same group rendered repeatedly — one per table row — shares its form name by design, so .id_prefix(..) supplies the discriminator. An id is also a valid CSS selector, so hx-target="#…" and querySelector work on it. If the first part of the id, after any leading _, does not start with a letter, the id gets one more _ at the start (1plan gives _1plan-…, _1plan gives __1plan-…). aria-invalid and any hx-* attributes land on each <input>, where assistive technology reads validity and htmx reads a value; aria-describedby and aria-required stay on the group.

Select::option(value, label) takes the pair, but RadioGroup::option(..) takes a built RadioOption. The difference is on purpose: RadioGroup::new takes its first choice as a RadioOption, and .option(..) takes the same type, so a choice is built the same way in both places.

Link::new takes the visible link text as a required argument (an icon-only link routes its name to aria-label via Link::icon), and MenuItem::new requires the accessible name, emitting role="menuitem" on a <button> by default or an <a> when an .href(..) is attached.

Red build → fix → green build

Red — an alt-less image or an unlabeled input used to compile clean. With the typed primitives it does not:

Rust
// error[E0061]: this function takes 2 arguments but 1 argument was supplied
let _ = Img::new("/logo.png");

// error[E0061]: this function takes 2 arguments but 1 argument was supplied
//        — a link with no text has no accessible name
let _ = Link::new("/about");

// error[E0061]: this function takes 1 argument but 0 arguments were supplied
//        — a menu item must carry an accessible name
let _ = MenuItem::new();

// error[E0599]: no method named `render` found for struct `TextField<State>` in the current scope
//        method not found in `TextField<NoLabel>`
//        — an unlabeled field cannot be turned into markup
let _ = TextField::new("email").render();

// error[E0599]: no method named `render` found for struct `RadioGroup<State>` in the current scope
//        method not found in `RadioGroup<NoLabel>`
//        — a radio group with no group name cannot be turned into markup
let _ = RadioGroup::new("speed", RadioOption::new("standard", "Standard")).render();

These are the errors of the compile-fail fixtures autumn/tests/compile-fail/a11y_img_missing_alt.rs, autumn/tests/compile-fail/a11y_link_missing_text.rs, autumn/tests/compile-fail/a11y_menuitem_missing_name.rs, autumn/tests/compile-fail/a11y_textfield_unlabeled.rs and autumn/tests/compile-fail/a11y_radiogroup_unlabeled.rs. The test a11y_guide_matches_the_real_diagnostics fails when this page and the goldens do not agree.

Fix — supply the accessible name / attach a label:

Rust
let _ = Img::new("/logo.png", "Company logo");            // ✅ compiles
let _ = Link::new("/about", "About us");                  // ✅ compiles
let _ = MenuItem::new("Settings");                        // ✅ compiles
let _ = TextField::new("email").label("Email").render();  // ✅ compiles
let _ = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
    .label("Shipping speed")                              // ✅ compiles
    .render();

Green — the build passes only once every primitive carries its accessible name. TextField::new(..) returns a TextField<NoLabel>; attaching a label with .label(..), .aria_label(..), or .labelled_by(..) transitions it to TextField<Labeled>, the only state that implements Render. There is no .render()/.build() on the unlabeled state, so an unlabeled field is literally unrepresentable as markup.

What this proves at compile time: the presence of an accessible name on every image, button, and text field. The types do not prove that the name holds text: Img::new(src, "") or .aria_label("") compiles, and gives an element with no name. Every entry point that takes a name has a debug_assert!, so an empty or blank name panics at the call site in a debug build. A release build renders the name as it is. For an image that carries no information, use Img::decorative(src). A name from data can be blank, so give it a fallback. autumn_web::a11y::is_blank(text) uses the same rule as the check (white space and zero-width characters). The generated select-options loader uses it, and puts the row id in place of a blank label.

What still belongs to runtime/authoring review: whether that name is meaningful (a helpful alt, not "image"), plus page structure, contrast, and focus order — the checklist and audit tooling above cover those.


autumn a11y verify (build-time raw-html! audit)

The typed primitives above are the compile-time proof: code that uses them cannot ship without an accessible name, so it never needs re-checking. But a project can always drop down to raw maud::html! { … } markup, which bypasses the primitives entirely and the type system cannot see. autumn a11y verify is the net for that escape hatch.

Because there is no walkable widget tree at runtime, verify is a static pass: it token-scans the html! blocks in your project's .rs files (the same descent autumn i18n check uses to find t! calls inside html!) and reports raw elements that are missing an accessible name. It reuses the WCAG success criteria, rule ids, and severity levels of autumn check --a11y, applied to source rather than rendered HTML.

What it checks

Rule idElementConditionWCAG SC
image-alt<img>no alt attribute1.1.1
label<input> / <select> / <textarea>no matching <label for=…>, aria-label, or aria-labelledby1.3.1 / 3.3.2 / 4.1.2
button-name<button>no text content and no aria-label/aria-labelledby4.1.2
link-name<a href>no link text and no aria-label/aria-labelledby2.4.4 / 4.1.2

Each finding carries the fix hint — the typed primitive that discharges the obligation at compile time (Img::new(src, alt), TextField::new(..).label(..), Button::new(name), Link::new(href, text)).

Which route is broken

A file and a line say where a defect is; a route says which page it breaks. verify reads the route attribute macros — #[get], #[post], #[put], #[patch], #[delete] and #[static_get], path-qualified or not — out of the same token stream, indexes every function and the free functions it calls, then walks out from each handler to the markup it reaches. A finding in a shared partial names the routes that reach it:

Code
    src/views/settings.rs:42: <img> [WCAG 1.1.1] Serious — raw <img> has no alt attribute
        routes: GET /settings, POST /settings
        hint: use autumn_web::a11y::Img::new(src, alt) / Img::decorative(src)

The walk is as conservative as the scanner. A call is followed only when the called name is defined exactly once in the scope that the call can see — two functions sharing a name cannot be told apart from tokens, and guessing would blame a route that never renders the markup. A bare name() resolves first to a helper fn that the caller declares at the top of its body, then to one in each enclosing body, then to a free item. A nested fn in an inner block, and an associated fn (reached through a receiver or a type-qualified path), are never a target. The scan does not track blocks, so a helper in an inner block makes its name resolve to nothing in the whole function.

These call shapes are followed:

  • sidebar() and views::sidebar(). A path always names a free item, so a local helper or a local binding of the same name does not shadow it.
  • A turbofish: sidebar::<Html>().
  • A function passed by name: rows.map(render_row), .map(views::render_row).

These are skipped: a method call (page.sidebar()), a type-qualified call (Widget::new(), .map(Widget::render) — Rust names types in UpperCamelCase), a path into a primitive type or the standard library (str::trim, std::mem::drop), and a name bound inside the function — a parameter, a local, a closure argument, a for or match-arm pattern — which shadows any free function that shares it. #[cfg(test)] items are skipped, and the path is the path as declared: mount-time prefixes (a scope, a nested router) are applied at runtime and are not resolved here.

An item, statement, match arm or field under #[cfg(…)] counts only when the predicate is true for the enabled features. A #[cfg_attr(…, cfg(…))] counts when its condition is true. A gated handler is not a route. A gated helper is not a target. The scan does not follow a gated call.

The scan parses each file with syn, so a gated node ends where the Rust grammar ends it. It also applies these rules:

  • It reads a macro body as Rust when the body parses as Rust.
  • A #![cfg(…)] that is off takes out its file, module, function or block.
  • A mod name; under a cfg that is off takes out the module files.
  • In cfg_if!, it keeps only the branch that builds.

The scan solves the features as cargo build --workspace solves them. It reads [features] default from the nearest Cargo.toml.

  • --features a,b turns on each name in each crate that declares it. views/a names one crate.
  • --all-features turns on every feature. As in Cargo, an optional dependency that a dep: entry names is not a feature.
  • --no-default-features turns off the default set.

A crate also turns on what it asks for in a path dependency of the same workspace:

  • the features list of the dependency,
  • the default features, unless default-features = false,
  • the views/a and views?/a entries of its enabled features.

A [workspace.dependencies] entry and a [patch] entry with a path count too. A target table counts when its cfg or its triple matches the host. A target cfg that the scan cannot decide does not count. Each workspace is solved alone. Resolver 1 also counts dev and build dependencies.

A predicate that the scan cannot decide (target_env = "gnu") keeps the item. A file with no package manifest also keeps it. A finding inside a gated item or statement that is off has no route. The features change only the route attribution. They do not change the findings or the exit code. A --features name that no crate declares gets a warning on stderr.

Known limits:

  • When syn cannot parse a file, the scan reads its tokens. It also reads the tokens of a macro body that is not Rust. The token reader finds the end of a gated node by heuristics.
  • A crate outside the scan root does not turn on features in the scan.
  • The scan does not follow a mod with a #[path] attribute.

Attribution is therefore a lower bound. status: "pass" means no finding was attributed to that route, not that the page is proven clean — read it alongside the summary's unrouted count, which is how many findings no route reached. An unattributed finding is still a finding, and still fails the build: the exit code is computed from severities alone, so attribution reports and never gates.

Usage

Shell
# Audit the current project (defaults to the working directory)
autumn a11y verify

# Point at a specific crate/directory
autumn a11y verify ./crates/web

# Machine-readable conformance manifest
autumn a11y verify --format json

# Fail on any finding (Moderate and above), mirroring `i18n check --strict`
autumn a11y verify --strict

# Read the `admin` feature as on for `#[cfg(feature = "admin")]` calls
autumn a11y verify --features admin

--format json (conformance manifest)

The JSON output is a conformance manifest: per-route status, the findings with the routes each one breaks, a per-criterion rollup, and a summary.

Json
{
  "files_scanned": 12,
  "html_blocks": 34,
  "routes": [
    {
      "method": "GET",
      "path": "/profile",
      "handler": "profile",
      "file": "src/views/profile.rs",
      "line": 18,
      "findings": 1,
      "status": "fail"
    }
  ],
  "findings": [
    {
      "file": "src/views/profile.rs",
      "line": 42,
      "element": "img",
      "rule_id": "image-alt",
      "wcag": "1.1.1",
      "severity": "Serious",
      "message": "raw <img> has no alt attribute",
      "hint": "use autumn_web::a11y::Img::new(src, alt) / Img::decorative(src)",
      "routes": ["GET /profile"]
    }
  ],
  "wcag": [
    { "criterion": "1.1.1", "rules": ["image-alt"], "findings": 1 }
  ],
  "summary": {
    "critical": 0, "serious": 1, "moderate": 0, "total": 1,
    "routes": 1, "routes_failing": 1, "unrouted": 0
  }
}

Three views of the same run: routes is the per-route conformance status (pass when no finding was attributed to the route), findings is the defect list with the routes each one breaks, and wcag rolls the findings up by success criterion — the multi-criterion rules are split, so label reports separately under 1.3.1, 3.3.2 and 4.1.2. A finding no route reaches carries an empty routes array and is counted in summary.unrouted. A clean run emits an empty wcag array and every route as pass.

CI integration

autumn a11y verify exits non-zero when any finding meets the failure threshold (Serious by default; --strict lowers it to Moderate), so it fails the build just like autumn i18n check:

Yaml
# GitHub Actions example
- name: Accessibility (raw html!) verification
  run: autumn a11y verify --format json

Scope and limitations

The primitives are the proof; verify is the safety net. Code that splices a typed primitive — (Img::new(src, alt)) — is a (expr) splice, not an img element, so it is never re-scanned or falsely flagged. Like autumn i18n check, the scanner reads tokens rather than a resolved AST and always errs toward not flagging what it cannot resolve, so it never breaks CI on a false positive: a spliced attribute value or content (alt=(caption), button { (label) }) is treated as present, and a <label for=…>/id association a splice makes unresolvable suppresses the label finding.

In short, verify is best-effort and advisory. Because it prefers to skip anything ambiguous, dynamic, or non-maud — unresolved splices, complex Rust expressions, and non-maud html! macros are passed over rather than guessed at — a clean run is not itself a proof of accessibility: the scanner can miss a defect buried in exotic markup (an acceptable trade by design), so its raw-html! findings are advisory-grade signal and may not be exhaustive. For the real, by-construction guarantee, route accessible content through the typed primitives in autumn_web::a11y, where an accessible name is a compile-time type obligation (proven by trybuild) rather than something a source scan has to infer.


Further reading