Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: CI
on:
push:
branches: [ main ]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npm test
commitlint:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
13 changes: 0 additions & 13 deletions .github/workflows/lint.yml

This file was deleted.

13 changes: 10 additions & 3 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,28 @@ name: Release
on:
push:
branches: [ main ]
permissions:
contents: write
issues: write
pull-requests: write
jobs:
release:
name: Release
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v1
uses: actions/setup-node@v4
with:
node-version: '14'
node-version: 22
cache: npm
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
node_modules
dist
test-results
playwright-report
1 change: 1 addition & 0 deletions .husky/commit-msg
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
npx --no -- commitlint --edit "$1"
96 changes: 82 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,100 @@
# inaccessible.css

![NPM Version 1.2.0](https://img.shields.io/npm/v/inaccessible.css?style=for-the-badge)
[![npm](https://img.shields.io/npm/v/inaccessible.css?style=for-the-badge)](https://www.npmjs.com/package/inaccessible.css)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=for-the-badge)](https://github.com/semantic-release/semantic-release)

A stylesheet to highlight inaccessible markup. It'll add an obnoxious red outline around elements which are lacking important attributes.
A drop-in stylesheet that highlights inaccessible markup while you develop. Problems get an obnoxious outline:

## Violations
The stylesheet will highlight the following accessibility mistakes:
- **Red** for errors: markup that fails WCAG.
- **Orange** for warnings: markup that is usually a problem but might be fine in context.

- Document missing the `lang`
- Images missing an `alt`
- Labels without a `for`
- Links without an `href`
- iframes without a `title`
Where the browser allows it, a short label also explains the problem, for example "Label not linked to a control". Images, form fields, frames and video can't show these labels, so they only get an outline.

It's a quick visual check, not a replacement for an automated audit (such as axe) or testing with real assistive technology. Some checks can't be done in CSS, such as checking that a `<label for>` points at an element that exists.

## Usage

### CSS
Add `inaccessible.css` to the document head:
Add the stylesheet after your own styles, during development only:

```html
<link href="inacessible.css" rel="stylesheet">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/inaccessible.css/dist/inaccessible.min.css">
```

Or install it with `npm install --save-dev inaccessible.css` and link to `node_modules/inaccessible.css/dist/inaccessible.css`.

### SCSS
Import `inaccessible.scss` into your stylesheet:

```scss
@import 'inaccessible';
@use 'inaccessible.css/src/scss/inaccessible';
```

The `inaccessible($level, $message)` mixin is forwarded too, so you can add your own checks:

```scss
@use 'inaccessible.css/src/scss/inaccessible' as a11y;

.legacy-widget:not([role]) {
@include a11y.inaccessible(warning, 'Widget has no role');
}
```

### Customising
Every setting is a CSS custom property, so you can change it without Sass:

body { … }
```css
:root {
--inaccessible-error: magenta;
--inaccessible-warning: gold;
--inaccessible-width: 4px;
--inaccessible-offset: 1px;
--inaccessible-message-display: none; /* hide the text labels */
}
```

## Browser support
Several checks use `:has()`, which is supported by all major browsers released since December 2023.

## What it checks

### Errors
| Check | WCAG |
|---|---|
| `<html>` without a `lang`, or with an empty one | 3.1.1 |
| Document without a `<title>`, or with an empty one | 2.4.2 |
| Viewport `<meta>` that stops people zooming in (`user-scalable=no`/`0`, `maximum-scale=1`) | 1.4.4 |
| `<meta http-equiv="refresh">` with a delay | 2.2.1 |
| `<img>` without `alt`. `<input type="image">` or `[role="img"]` without an accessible name | 1.1.1 |
| `<iframe>` without a `title` | 4.1.2 |
| `<video>` without a captions or subtitles `<track>` | 1.2.2 |
| `<audio autoplay>`, or `<video autoplay>` that isn't `muted`. `autoplay="false"` still autoplays | 1.4.2 |
| `<marquee>` and `<blink>` | 2.2.2 |
| `<label>` that neither has `for` nor wraps a control | 1.3.1 |
| Input, select or textarea with no `id`, `aria-label`, `aria-labelledby` or `title`, and not inside a `<label>` | 4.1.2 |
| Empty links, buttons and headings | 2.4.4, 2.4.6, 4.1.2 |
| Positive `tabindex` | 2.4.3 |
| Focusable content inside `aria-hidden="true"` | 4.1.2 |

### Warnings
| Check | Why |
|---|---|
| `<a>` without an `href`, or with `href="#"` or `javascript:` | Probably should be a `<button>` |
| `<video autoplay muted>` without `controls` | Moving content can't be paused (2.2.2) |
| `<table>` without any `<th>` | Data tables need headers (1.3.1). Mark layout tables with `role="presentation"` |
| `<fieldset>` without a `<legend>` | The group has no name (1.3.1) |
| Anything other than `<li>` inside `<ul>` or `<ol>` | Invalid list structure (1.3.1) |
| `accesskey` | Clashes with assistive technology shortcuts |
| `autofocus` | Can disorient screen reader and magnifier users |
| Inline `onclick` on an element that isn't interactive | Probably can't be used with a keyboard (2.1.1) |

## Development

```sh
npm install
npm start # rebuild dist/inaccessible.css on change
npm test # build, then check every example in demo/ in Chromium
```

The pages in `demo/` are both the demo and the test fixtures. Each example has a `data-expect="error|warning|none"` attribute, and the tests fail if any element is highlighted differently. If you add a check, add passing and failing examples there.

Commits follow [Conventional Commits](https://www.conventionalcommits.org/), which semantic-release uses to version and publish from `main`.
178 changes: 178 additions & 0 deletions demo/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
<!DOCTYPE html>
<html lang="en-GB" data-expect="none">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1" data-expect="none">
<title>inaccessible.css demo</title>
<link rel="stylesheet" href="../dist/inaccessible.css">
<style>
/* A typical reset. inaccessible.css must still show through it. */
*, *:focus { outline: none; }

body { font-family: system-ui, sans-serif; max-width: 60rem; margin: 0 auto; padding: 1rem; line-height: 1.5; }
.case { display: flex; flex-wrap: wrap; gap: 1rem; align-items: center; margin-block: 0.5rem; }
code { background: #eee; padding: 0 0.2em; }
.key { display: flex; gap: 1rem; }
.key span { padding: 0 0.4em; }
.key .error { outline: 3px solid #d00000; }
.key .warning { outline: 3px solid #e67e00; }
</style>
</head>
<body>
<main>
<h1>inaccessible.css</h1>
<p>Each example below is tagged with the result it should produce. The test suite checks every tag.</p>
<p class="key"><span class="error" data-expect="error">Error</span> <span class="warning" data-expect="warning">Warning</span></p>

<p>Document-level checks have their own pages: <a href="no-lang.html">no <code>lang</code></a>, <a href="no-title.html">no <code>&lt;title&gt;</code></a>, <a href="no-zoom.html">zoom disabled</a> and <a href="meta-refresh.html">timed refresh</a>.</p>

<section>
<h2>Images</h2>
<div class="case">
<img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='40'/%3E" width="80" height="40" data-expect="error">
<img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='40'/%3E" width="80" height="40" alt="" data-expect="none">
<img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='40'/%3E" width="80" height="40" alt="A grey box" data-expect="none">
<input type="image" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='40' height='40'/%3E" width="40" height="40" data-expect="error">
<svg role="img" width="40" height="40" data-expect="error"><rect width="40" height="40" fill="#ccc"/></svg>
<svg role="img" width="40" height="40" data-expect="none"><title>Grey square</title><rect width="40" height="40" fill="#ccc"/></svg>
</div>
</section>

<section>
<h2>Frames</h2>
<div class="case">
<iframe srcdoc="No title" width="150" height="60" data-expect="error"></iframe>
<iframe srcdoc="Empty title" title="" width="150" height="60" data-expect="error"></iframe>
<iframe srcdoc="Titled" title="Example frame" width="150" height="60" data-expect="none"></iframe>
</div>
</section>

<section>
<h2>Video and audio</h2>
<div class="case">
<video width="160" height="90" controls data-expect="error"></video>
<video width="160" height="90" controls data-expect="none"><track kind="captions" src="captions.vtt" srclang="en"></video>
<video width="160" height="90" controls data-expect="none"><track src="captions.vtt" srclang="en"></video>
<video width="160" height="90" controls data-expect="error"><track kind="chapters" src="chapters.vtt" srclang="en"></video>
<video width="160" height="90" controls autoplay="false" data-expect="error"><track kind="captions" src="captions.vtt" srclang="en"></video>
<video width="160" height="90" controls autoplay muted data-expect="none"><track kind="captions" src="captions.vtt" srclang="en"></video>
<video width="160" height="90" autoplay muted data-expect="warning"><track kind="captions" src="captions.vtt" srclang="en"></video>
<audio controls autoplay data-expect="error"></audio>
</div>
</section>

<section>
<h2>Moving content</h2>
<marquee data-expect="error">Scrolling text that can't be paused</marquee>
</section>

<section>
<h2>Forms</h2>
<form action="#">
<div class="case">
<label data-expect="error" data-message="Label not linked to a control">Unlinked label</label>
<input id="unlinked" type="text" data-expect="none">
</div>
<div class="case">
<label for="" data-expect="error">Empty for</label>
</div>
<div class="case">
<label for="linked" data-expect="none">Linked label</label>
<input id="linked" type="text" data-expect="none">
</div>
<div class="case">
<label data-expect="none">Wrapping label <input type="text" data-expect="none"></label>
<label data-expect="none"><input type="checkbox" data-expect="none"> Wrapped checkbox</label>
</div>
<div class="case">
<input type="text" data-expect="error">
<input type="text" placeholder="Placeholder isn't a label" data-expect="error">
<input type="search" aria-label="Search" data-expect="none">
<select data-expect="error"><option>No label</option></select>
<textarea aria-labelledby="unlinked" data-expect="none"></textarea>
<input type="hidden" data-expect="none">
<input type="submit" value="Submit" data-expect="none">
</div>
<fieldset data-expect="warning" data-message="Fieldset has no legend">
<label><input type="radio" name="a"> A</label>
</fieldset>
<fieldset data-expect="none">
<legend>Choose</legend>
<label><input type="radio" name="b"> B</label>
</fieldset>
</form>
</section>

<section>
<h2>Links and buttons</h2>
<div class="case">
<a data-expect="warning" data-message="Link has no href">No href</a>
<a href="#" data-expect="warning" data-message="Link goes nowhere">Hash</a>
<a href="javascript:void(0)" data-expect="warning">JavaScript</a>
<a href="#top" data-expect="none">Real link</a>
<a href="#top" data-expect="error" data-message="Link has no text"></a>
<a href="#top" aria-label="Home" data-expect="none"></a>
<button type="button" data-expect="error" data-message="Button has no text"></button>
<button type="button" data-expect="none">Real button</button>
</div>
</section>

<section>
<h2>Headings</h2>
<h3 data-expect="error" data-message="Empty heading"></h3>
</section>

<section>
<h2>Tables</h2>
<div class="case">
<table data-expect="warning">
<tr><td>No</td><td>headers</td></tr>
</table>
<table data-expect="none">
<thead><tr><th scope="col">Column one</th><th scope="col">Column two</th></tr></thead>
<tbody><tr><td>A</td><td>B</td></tr></tbody>
</table>
<table role="presentation" data-expect="none">
<tr><td>Layout</td><td>table</td></tr>
</table>
</div>
</section>

<section>
<h2>Lists</h2>
<ul data-expect="none">
<li data-expect="none">List item</li>
<div data-expect="warning">Not a list item</div>
</ul>
</section>

<section>
<h2>Focus and ARIA</h2>
<div class="case">
<div tabindex="1" data-expect="error">tabindex="1"</div>
<div tabindex="0" data-expect="none">tabindex="0"</div>
<div tabindex="-1" data-expect="none">tabindex="-1"</div>
</div>
<div class="case">
<div aria-hidden="true" data-expect="error"><a href="#top">Focusable but hidden</a></div>
<button type="button" aria-hidden="true" data-expect="error">Hidden button</button>
<div aria-hidden="true" data-expect="none"><a href="#top" tabindex="-1">Removed from tab order</a></div>
<div aria-hidden="true" data-expect="none"><button type="button" disabled>Disabled</button></div>
<div aria-hidden="true" inert data-expect="none"><a href="#top">Inert</a></div>
<div aria-hidden="true" data-expect="none">Decoration</div>
</div>
</section>

<section>
<h2>Worth a second look</h2>
<div class="case">
<button type="button" accesskey="s" data-expect="warning">Access key</button>
<input id="autofocus" aria-label="Autofocus" autofocus data-expect="warning">
<div onclick="void 0" data-expect="warning">Clickable div</div>
<div onclick="void 0" role="button" tabindex="0" data-expect="none">Div with role</div>
<button type="button" onclick="void 0" data-expect="none">Clickable button</button>
</div>
</section>
</main>
</body>
</html>
13 changes: 13 additions & 0 deletions demo/meta-refresh.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<!DOCTYPE html>
<html lang="en" data-expect="none">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="300" data-expect="error">
<title>Timed refresh</title>
<link rel="stylesheet" href="../dist/inaccessible.css">
</head>
<body>
<h1>This page reloads itself after 5 minutes</h1>
<p><a href="index.html">Back to the demo</a></p>
</body>
</html>
Loading
Loading