Skip to content

sprezzature-accessibility

Accessibility

Two halves of one job: audit what a page gets wrong about accessibility — twenty rules decidable from the HyperText Markup Language (HTML) source alone, no browser, no runtime Document Object Model (DOM) — and make the content it is missing, drafting alt text with a local vision model.

SKILL.md (the agent spec) ⭐ on GitHub

Makes

  • Alt text for an image, drafted by a local Ollama vision model along the World Wide Web Consortium (W3C) image-purpose decision tree — informative, decorative, functional, text, complex, group — in any language, cached on disk
  • JavaScript Object Notation (JSON) / stdout / exit codes for pre-commit and continuous integration (CI)
  • An opt-in "comfortable reading" CSS toggle at the WCAG 1.4.12 Text Spacing minimums, for pages that ship it as a reader-facing setting

Audits

  • Missing alt, unlabelled inputs, button-without-text, clickable div
  • Missing dialog close, lang attribute, heading order
  • Color-only state, motion-reduce guards, tight letter-spacing on running text
  • Captions, track language and media controls on <video> and <audio>
  • A fast, deterministic gate (twenty rules, six with a mechanical fixer), not a replacement for axe-core / Pa11y / Lighthouse

Say one of these

The skill triggers itself on phrasing like this, no command to memorize.

a11y lint check this HTML for accessibility static a11y check WCAG-friendly lint missing alt unlabelled input ARIA / keyboard check fix accessibility

Reference library

The knowledge the skill draws on: read them straight from the repo.

The twenty rules

Frequently asked questions

How do I install sprezzature-accessibility?

Run pip install sprezzature-accessibility (Python 3.10 to 3.13): one line installs the linter, the alt-text drafter, the HTTP API and the MCP server, with no extras to choose. To use it as an agent skill, pip install sprezzature then sprezzature-skills --install (or sprezzature-skills --install --agent opencode).

What does sprezzature-accessibility check?

sprezzature-accessibility applies twenty rules decidable from the HTML source alone: missing alt text, unlabelled inputs, empty links and buttons, clickable div elements with no keyboard access, dialogs with no close, a missing lang, skipped heading levels, status shown by colour alone, animation with no reduced-motion guard, tight letter-spacing, and missing captions, transcripts or controls on video and audio. Six of the rules also have a mechanical repair, applied with --fix.

How is sprezzature-accessibility different from axe-core, Pa11y or Lighthouse?

sprezzature-accessibility reads the HTML source without opening a browser, so it runs in milliseconds and gives the same answer every time, but it cannot see what only exists once a page renders: focus order, screen-reader timing, contrast against a real background. axe-core, Pa11y and Lighthouse drive a real browser and catch that layer; use this one as the fast first gate and one of them as the second pass, not as a replacement.

Can sprezzature-accessibility write the missing alt text?

Yes: sprezzature-accessibility drafts the missing alt text with sprezzature-accessibility-lint --fix-alt public/, from each image and the text around it on the same page, in the page's language or the one set by --alt-lang; sprezzature-accessibility-alt photo.jpg does a single image. This half needs Ollama and the qwen3-vl:8b vision model, set up by sprezzature-accessibility-install-alt, while the linter needs no browser and no model. Each draft should be read by a person before it is committed.

Does sprezzature-accessibility send my pages or images to a cloud service?

No: sprezzature-accessibility's linter keeps everything on your machine and calls no model at all; only the alt-text drafter (--fix-alt, sprezzature-accessibility-alt) calls a vision model, served by Ollama on your own machine unless you point OLLAMA_URL elsewhere. The HTTP API lints a string of HTML and never fetches a URL.

Can I run sprezzature-accessibility in CI or a pre-commit hook?

Yes: sprezzature-accessibility-lint public/ lints every .html file under the folder and exits 1 on any finding, warnings included, and 0 on a clean run, with --format json for a CI parser and --ignore to skip named rules. For a hook, pip install --no-deps sprezzature-accessibility plus pip install click is enough to run the lint.

Can I use sprezzature-accessibility without Claude Code?

Yes: sprezzature-accessibility is a Python library (import sprezzature_accessibility), a command line (sprezzature-accessibility, one command per tool), an HTTP API with a Docker image, and an MCP server, sprezzature-accessibility-mcp, for any MCP client. The Docker image runs that server, so one port answers both the HTTP routes and /mcp.

Is sprezzature-accessibility free?

Yes: sprezzature-accessibility is open source under the BSD 3-Clause licence, with no account, API key or paid tier, and the source is on GitHub.