# a11y.css shows a page its own accessibility mistakes

> a11y.css is a MIT licensed stylesheet, written in SCSS and shipped in ten languages, that overlays visual warnings on HTML rather than reporting them, so a developer sees a missing label by looking at the page instead of reading a report.

**ffoodd/a11y.css** — This CSS file intends to warn developers about possible risks and mistakes that exist in HTML code. It can also be used to roughly evaluate a site's quality by simply including it as an external stylesheet.

- Repository: https://github.com/ffoodd/a11y.css
- Website: https://ffoodd.github.io/a11y.css
- Stars: 1,613 · Forks: 96
- Language: SCSS
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ffoodd-a11y-css

## The diagnostic is the stylesheet, not a report

The stated purpose is narrow and worth quoting in spirit: the file warns developers about possible risks and mistakes that exist in HTML code. The second half of the description adds the other use, that it can roughly evaluate a site's quality by simply including it as an external stylesheet.

Both uses come from the same mechanism. a11y.css uses CSS selectors to match the elements that represent a problem, then styles them so the problem is visible. A missing alt attribute, an absent lang attribute, a heading order that skips a level: each is a selector that can find the markup. There is no scanning step and no output file.

That design has a real consequence for how the tool fits into a workflow. Because the output is visual, it works on the page you are building, at the moment you are building it, without a separate tool window. The word roughly in the second claim is doing the honest work, since the tool is describing what it can detect through selectors alone.

The name is pronounced Alix, and the project says it is because it is simpler. The primary language of the source is SCSS, and the published artefacts are plain CSS files.

## Ten languages and two levels, which is where the files multiply

The distribution matrix is the practical detail for anyone including the file. CSS files are available in French, English, Spanish, Greek, Arabic, Portuguese, Russian, Chinese, Polish and Dutch, and each comes in a leveled or a full variant.

That means the choice of stylesheet is not one file but a combination of language and level. The package metadata names the default entry points explicitly, `css/a11y-en.css` for style and `sass/a11y-en.scss` for the Sass source, which is English and one of the two levels. Including the file means choosing a language at minimum, and the level if you want the stricter set of warnings.

The two-level design is a usability decision about output density. Warnings visible at once on a complex page can be unreadable, so a leveled variant that reveals progressively more is the sane default for day-to-day use, with the full variant for a deliberate review pass.

The Sass sources live in `sass/` and the compiled CSS in `css/`, and only those two directories are published in the package files list, so nothing else from the repository ships to npm.

## npm run build compiles Sass, then autoprefixer and cssnano rewrite it

The build is a two-step chain, and the second step is easy to miss from the script list.

The Sass compile runs first, in expanded and watch variants, with `--no-error-css` so a broken rule does not abort the whole build:

```bash
npm run build
```

That produces `css/` from `sass/` in compressed mode. A postbuild hook then runs `postcss css/*.css -r -u autoprefixer cssnano -m`, rewriting every compiled file in place to add vendor prefixes and minify it.

The in-place rewrite with `-r` is worth understanding before you rely on it. The committed CSS is a build artefact that gets regenerated and then modified again, so hand-editing anything under `css/` is pointless and a diff there will confuse you.

Watch mode is the same compile with `-w` added, and `npm start` runs all the watch tasks together through concurrently with `--kill-others`, so stopping one stops the set.

The interesting negative fact is the test script. The package's `test` script is a stylelint run over the Sass sources:

That validates the project's own style conventions and nothing about any page's accessibility. There is no test in this package that checks markup, which is the honest shape of a tool that has no analyzer.

## The WebExtension adds what a stylesheet cannot do

The browser extension lives in its own repository, a11y.css-webextension, and it adds features not included in the main CSS file.

Four capabilities are listed as beyond the CSS file itself: forcing focus visibility, showing lang attributes, checking image alternatives by displaying them, and increasing text spacings. The last one matters because it is a runtime manipulation of the page's own text rendering rather than a property an external stylesheet can set on a per-element basis without side effects.

Three more come from being an extension: toggling the CSS and changing the level on the fly, remembering the settings for each tab, and automatic background updates. That last point is the one with an adoption consequence, since the extension can pull in new warnings without you changing a version pin, which is convenient and also means the behaviour you audit against can shift under you.

Installations are listed for Firefox, Edge and Chrome, each from its own add-on store.

## A single maintainer, MIT, and no release since 5.3.0

The maintenance picture is modest and should be weighed as such. The most recent tags are v5.3.0 on 2024-12-10, v5.2.2 on 2024-11-04 and v5.2.1 on 2023-08-22, and the package version is 5.3.0, matching the newest tag. The last push to the repository was on 2026-04-24 and the project is not archived.

So there is recent commit activity without recent releases. For a stylesheet that is not fatal, since a rules change does not usually break an include, but it does mean a version pin tells you less than usual.

The project is a single author, Gaël Poupard, both in package.json and as the person who says issues and pull requests will be read. The README routes contribution through a wiki rather than describing a process in the repository itself.

The licence is MIT, which is the least complicated part of adopting this: include it, ship it, modify it, keep the notice. Customization is the intended path rather than an exception, and the wiki is where the documentation lives, which is worth checking before you fork.

The repository also holds the documentation site itself, built with Eleventy: `.eleventy.js`, `.eleventyignore` and a `site/` directory, with link checking as part of the docs scripts and uglifyjs plus Sass and PostCSS assembling `docs.js` and the site stylesheets.

## Where a11y.css is the wrong tool

Three limits are structural rather than fixable.

It cannot report. Everything it knows arrives as pixels on the page, so there is no file to attach to a ticket, no severity ranking, and no way to say that a specific defect on a specific page must be fixed by a specific date. If your process needs a regression gate, you need a tool that produces an artifact, and this is not it.

It cannot judge. A selector can match markup that looks suspicious, not a page that is actually inaccessible to a screen reader user. The project describes itself as warning about possible risks, and the word possible covers the whole gap between what CSS can see and what an assistive technology experiences. The WebExtension narrows the gap slightly by displaying image alternatives, but a visual check is still not a test with NVDA or VoiceOver.

It is scoped to HTML. Nothing here validates ARIA patterns, focus order, or keyboard behaviour, which are the failures most likely to block a real user.

The honest comparison is with an automated audit tool run in a headless browser. That approach produces a machine-readable report, integrates into continuous integration, and detects a similar class of selector-level problems. a11y.css wins on the opposite axis: no tooling, no setup, and the finding is attached to the exact element on the screen you are already looking at. For a quick review with a colleague, that is worth more than a report nobody reads.

## Conclusion

a11y.css fits a team doing a first pass on markup, or a reviewer who wants to point at a specific element instead of filing a ticket, because the diagnostic and the visual output are the same stylesheet. It is not a substitute for testing with assistive technology, for an automated audit tool that produces a pass or fail report, or for a build-time gate, and the README does not claim it is. Before adopting it, read the wiki for the customization path, decide whether you want the leveled or full variant and which language you need, and note that the package's `npm test` runs stylelint over the Sass sources, so it checks the stylesheet's own style rather than a page's accessibility.

## FAQ

### How do I use a11y.css on a page?

Include the compiled CSS file as an external stylesheet. The package publishes `css/` and `sass/` directories, with the default entry points `css/a11y-en.css` and `sass/a11y-en.scss`, and files are available in ten languages in leveled or full variants.

### Does a11y.css have a browser extension?

Yes, in its own repository as a11y.css-webextension, with installs for Firefox, Edge and Chrome. It adds force focus visibility, showing lang attributes, displaying image alternatives, increased text spacings, per-tab settings and background updates.

### Does a11y.css report accessibility errors or show them?

It shows them. It warns developers about possible risks and mistakes in HTML code by styling the offending elements, and the README describes it as a rough evaluation of a site's quality rather than a report.

### How do I build a11y.css from source?

Run `npm run build`, which compiles `sass/` into `css/` with Sass in compressed mode and `--no-error-css`. A postbuild hook then rewrites the compiled CSS in place with PostCSS, autoprefixer and cssnano.

### What does the a11y.css test script check?

The `test` script runs stylelint over the Sass sources, so it validates the project's own style rules rather than checking any page's accessibility.

## Sources

- [ffoodd/a11y.css on GitHub](https://github.com/ffoodd/a11y.css)
- [License: MIT](https://github.com/ffoodd/a11y.css/blob/main/LICENSE)
- [Project website](https://ffoodd.github.io/a11y.css)
- [README](https://github.com/ffoodd/a11y.css/blob/main/README.md)
- [Releases](https://github.com/ffoodd/a11y.css/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ffoodd-a11y-css