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:
<html lang="en">(or the appropriate BCP-47 tag)- A skip-to-content link as the first focusable element
- Landmark regions:
<header role="banner">,<main>,<footer role="contentinfo"> - An ARIA live region for htmx swap announcements
- 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:
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
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 matchingid="{field}"on the input- Inline error message (wrapped in
role="alert") when the changeset has a validation error for that field aria-invalid="true"andaria-describedbypointing at the error element
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.
html! {
(password_input(&changeset, "password", "Password"))
}
password_input_with has these options for a password. See
Forms.
reveal()adds a toggle button witharia-pressed. Its label does not change, so a screen reader announces one control with a state. The button ishiddenuntil the script runs, so a user never finds a button that does nothing.strength_hint()adds a polite live region, linked byaria-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()andnew_password()setautocomplete, 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.
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.
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).
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.
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.
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:
#[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:
#[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.
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, notaria-required: ARIA does not allowaria-requiredon 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.
skip_link
Renders a visually hidden "Skip to …" anchor that becomes visible on keyboard
focus. Place it as the first element inside <body>.
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.
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:
-
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> -
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> -
Clear the region after a short delay by including an empty update in the next response, or use a small JavaScript snippet:
Jsdocument.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:
<!-- response HTML -->
<main id="main-content" tabindex="-1">
<h1 autofocus>Search results</h1>
...
</main>
Or trigger focus programmatically with the htmx:afterSwap event:
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:
| Foreground | Background | Ratio | Usage |
|---|---|---|---|
gray-900 | gray-100 | 16:1 | Body text on page |
gray-700 | white | 9.5:1 | Secondary nav links |
white | orange-500 | 3.1:1 | CTA buttons (large text) |
orange-600 | white | 4.7:1 | Inline links |
gray-400 | white | 2.6:1 | Avoid — placeholder/hint text only, never body text |
Warning:
text-gray-400onwhitefalls below 4.5:1. Use it only for supplemental placeholder text. For any text that carries meaning, usetext-gray-600(5.9:1) or darker.
To verify contrast ratios during development:
# 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-visiblering) - [ ] 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
alttext; purely decorative images usealt="" - [ ] All form fields have a visible
<label>(not justplaceholder)
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
# 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 ID | Severity | What it checks |
|---|---|---|
html-has-lang | Serious | <html> element has a non-empty lang attribute |
bypass | Serious | First focusable element is a skip link to #main |
landmark-one-main | Moderate | Page contains exactly one <main> element |
image-alt | Critical | Every <img> has an alt attribute (may be empty) |
label | Critical | Every <input> (non-hidden) has an associated <label> |
button-name | Critical | Every <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:
# 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:
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:
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:
{
"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:
| Primitive | WCAG SC | Obligation |
|---|---|---|
Img | 1.1.1 Non-text Content | alt is a required constructor argument |
Button | 4.1.2 Name, Role, Value | accessible name is a required constructor argument |
Link | 2.4.4 Link Purpose (In Context) / 4.1.2 Name, Role, Value | link text is a required constructor argument |
MenuItem | 4.1.2 Name, Role, Value | accessible name is a required constructor argument (renders role="menuitem") |
TextField | 1.3.1 Info and Relationships / 3.3.2 Labels / 4.1.2 | only a labeled field can be rendered (typestate) |
RadioGroup | 1.3.1 Info and Relationships / 3.3.2 Labels / 4.1.2 | only a labeled group can be rendered; each choice carries its own label |
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:
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:
// 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:
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 id | Element | Condition | WCAG SC |
|---|---|---|---|
image-alt | <img> | no alt attribute | 1.1.1 |
label | <input> / <select> / <textarea> | no matching <label for=…>, aria-label, or aria-labelledby | 1.3.1 / 3.3.2 / 4.1.2 |
button-name | <button> | no text content and no aria-label/aria-labelledby | 4.1.2 |
link-name | <a href> | no link text and no aria-label/aria-labelledby | 2.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:
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()andviews::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 acfgthat 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,bturns on each name in each crate that declares it.views/anames one crate.--all-featuresturns on every feature. As in Cargo, an optional dependency that adep:entry names is not a feature.--no-default-featuresturns off the default set.
A crate also turns on what it asks for in a path dependency of the same workspace:
- the
featureslist of the dependency, - the default features, unless
default-features = false, - the
views/aandviews?/aentries 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
syncannot 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
modwith 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
# 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.
{
"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:
# 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
examples/reddit-clone— the submit and edit forms are built entirely froma11y::TextField/TextArea/Select/Button/Link, witharia-invalid+aria-describedbyerror wiring driven by the changeset- Forms, validation and normalization — where these primitives
meet
ChangesetForm's per-field errors - WCAG 2.1 Quick Reference
- APG Patterns (ARIA Authoring Practices Guide)
- htmx accessibility notes
- Maud documentation