From a983c6db97be60993b5648eb2de0f928624e6dcd Mon Sep 17 00:00:00 2001 From: Dan Matthew <111794+danielmatthew@users.noreply.github.com> Date: Wed, 23 Sep 2026 18:09:10 +0100 Subject: [PATCH 1/9] fix: highlight video el with no caption --- src/scss/_no-video-captions.scss | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 src/scss/_no-video-captions.scss diff --git a/src/scss/_no-video-captions.scss b/src/scss/_no-video-captions.scss new file mode 100644 index 0000000..c3c67e0 --- /dev/null +++ b/src/scss/_no-video-captions.scss @@ -0,0 +1,3 @@ +video:not(video > track) { + @include inaccessible; +} From 8d269f0410aadba94727339679090f16ae8b11d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 19:16:10 +0000 Subject: [PATCH 2/9] fix: only highlight videos without a captions or subtitles track The previous selector, video:not(video > track), matched every video, and the partial was never imported so it did not ship at all. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018z2Z3qN9ZawWK4VnZhhd1H --- src/scss/_no-video-captions.scss | 3 ++- src/scss/inaccessible.scss | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/scss/_no-video-captions.scss b/src/scss/_no-video-captions.scss index c3c67e0..f845ed6 100644 --- a/src/scss/_no-video-captions.scss +++ b/src/scss/_no-video-captions.scss @@ -1,3 +1,4 @@ -video:not(video > track) { +// A with no kind defaults to subtitles. +video:not(:has(> track:is([kind="captions" i], [kind="subtitles" i], :not([kind])))) { @include inaccessible; } diff --git a/src/scss/inaccessible.scss b/src/scss/inaccessible.scss index b3759e0..ad34c28 100644 --- a/src/scss/inaccessible.scss +++ b/src/scss/inaccessible.scss @@ -7,5 +7,6 @@ 'no-frame-title', 'no-table-col-id', 'no-video-autoplay', + 'no-video-captions', 'no-scale' ; From 4cf7311d585e7c2bd48eab578aacab2f3a698a20 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 19:20:05 +0000 Subject: [PATCH 3/9] feat: configurable error and warning highlights - Outline is 3px, uses !important so outline resets can't hide it, and reads its colour, width and offset from CSS custom properties. - Checks now have a level: error (red) or warning (orange), and can show a short message via ::after where the element supports it. - Migrate from the deprecated Sass @import to @use/@forward. Existing checks: - Labels that wrap their control are no longer flagged. - Replace the th[id]/td[headers] rule, which flagged almost every table, with a warning for tables that have no at all. - Links without an href are now a warning, and links to "#" or "javascript:" are also flagged. - Also catch empty lang/title values, input[type=image] and role=img without a name, audio autoplay, muted autoplay without controls, and more ways of disabling zoom. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018z2Z3qN9ZawWK4VnZhhd1H --- src/scss/_head.scss | 3 ++ src/scss/_highlight.scss | 52 ++++++++++++++++++++++++++++++-- src/scss/_no-alt.scss | 9 ++++-- src/scss/_no-for.scss | 9 ++++-- src/scss/_no-frame-title.scss | 9 ++++-- src/scss/_no-href.scss | 10 +++++- src/scss/_no-lang.scss | 10 +++--- src/scss/_no-scale.scss | 20 +++++++----- src/scss/_no-table-col-id.scss | 6 ---- src/scss/_no-video-autoplay.scss | 14 +++++++-- src/scss/_no-video-captions.scss | 5 ++- src/scss/_table-headers.scss | 6 ++++ src/scss/inaccessible.scss | 34 +++++++++++++-------- 13 files changed, 144 insertions(+), 43 deletions(-) create mode 100644 src/scss/_head.scss delete mode 100644 src/scss/_no-table-col-id.scss create mode 100644 src/scss/_table-headers.scss diff --git a/src/scss/_head.scss b/src/scss/_head.scss new file mode 100644 index 0000000..c8c75a1 --- /dev/null +++ b/src/scss/_head.scss @@ -0,0 +1,3 @@ +head { + display: block; +} diff --git a/src/scss/_highlight.scss b/src/scss/_highlight.scss index b5ed721..028e080 100644 --- a/src/scss/_highlight.scss +++ b/src/scss/_highlight.scss @@ -1,3 +1,51 @@ -@mixin inaccessible { - outline: 1px solid red +@use "sass:list"; +@use "sass:map"; + +// Every value can be overridden from plain CSS, e.g. +// :root { --inaccessible-error: magenta; --inaccessible-message-display: none; } +$colours: ( + error: (#d00000, #fff), + warning: (#e67e00, #000), +); + +@mixin inaccessible($level: error, $message: null, $offset: var(--inaccessible-offset, 2px)) { + $colour: list.nth(map.get($colours, $level), 1); + $text: list.nth(map.get($colours, $level), 2); + + // !important so that `outline: none` resets can't hide an issue. + outline: var(--inaccessible-width, 3px) solid var(--inaccessible-#{$level}, #{$colour}) !important; + outline-offset: $offset !important; + + // Pseudo-elements don't render on replaced or void elements (img, input, + // iframe, video…), so only pass a message for elements that can show one. + @if $message { + &::after { + content: "#{$message}"; + display: var(--inaccessible-message-display, inline-block); + margin-inline-start: 0.25em; + padding: 0.1em 0.35em; + border-radius: 2px; + background: var(--inaccessible-#{$level}, #{$colour}); + color: var(--inaccessible-#{$level}-text, #{$text}); + font: 700 12px/1.3 system-ui, sans-serif; + letter-spacing: normal; + text-transform: none; + text-decoration: none; + white-space: nowrap; + vertical-align: middle; + } + } +} + +// Outlines on are drawn outside the viewport, so pull them inside. +@mixin inaccessible-document { + @include inaccessible($offset: calc(var(--inaccessible-width, 3px) * -1)); +} + +// Make elements in visible so they can be outlined. The +// rest of stays hidden by the browser's own styles. +@mixin inaccessible-meta($level: error) { + display: block; + height: 1em; + @include inaccessible($level); } diff --git a/src/scss/_no-alt.scss b/src/scss/_no-alt.scss index d8fc434..8c4a1f4 100644 --- a/src/scss/_no-alt.scss +++ b/src/scss/_no-alt.scss @@ -1,3 +1,8 @@ -img:not([alt]) { - @include inaccessible +@use "highlight" as *; + +// WCAG 1.1.1 Non-text Content. alt="" is valid for decorative images. +img:not([alt]), +input[type="image" i]:not([alt], [aria-label], [aria-labelledby]), +[role="img" i]:not(img, [aria-label], [aria-labelledby], :has(> title)) { + @include inaccessible; } diff --git a/src/scss/_no-for.scss b/src/scss/_no-for.scss index 587f665..9ee0821 100644 --- a/src/scss/_no-for.scss +++ b/src/scss/_no-for.scss @@ -1,3 +1,8 @@ -label:not([for]) { - @include inaccessible +@use "highlight" as *; + +// WCAG 1.3.1 Info and Relationships. A label must either point at a control +// with `for` or wrap it. +label:not([for]):not(:has(input, select, textarea, meter, output, progress, button)), +label[for=""] { + @include inaccessible($message: "Label not linked to a control"); } diff --git a/src/scss/_no-frame-title.scss b/src/scss/_no-frame-title.scss index d7c7d6b..aeca1e1 100644 --- a/src/scss/_no-frame-title.scss +++ b/src/scss/_no-frame-title.scss @@ -1,4 +1,7 @@ -iframe:not([title]), -frame:not([title]) { - @include inaccessible +@use "highlight" as *; + +// WCAG 4.1.2 Name, Role, Value +:is(iframe, frame):not([title], [aria-label], [aria-labelledby]), +:is(iframe, frame)[title=""] { + @include inaccessible; } diff --git a/src/scss/_no-href.scss b/src/scss/_no-href.scss index ae809a0..74e8915 100644 --- a/src/scss/_no-href.scss +++ b/src/scss/_no-href.scss @@ -1,3 +1,11 @@ +@use "highlight" as *; + +// Links without an href can't be focused. Often a sign a + + + + +
+

Headings

+

+
+ +
+

Tables

+
+ + +
Noheaders
+ + + +
Column oneColumn two
AB
+ + +
Layouttable
+
+
+ +
+

Lists

+
    +
  • List item
  • +
    Not a list item
    +
+
+ +
+

Focus and ARIA

+
+
tabindex="1"
+
tabindex="0"
+
tabindex="-1"
+
+
+ + + + + + +
+
+ +
+

Worth a second look

+
+ + +
Clickable div
+
Div with role
+ +
+
+ + + diff --git a/demo/meta-refresh.html b/demo/meta-refresh.html new file mode 100644 index 0000000..91da5ae --- /dev/null +++ b/demo/meta-refresh.html @@ -0,0 +1,13 @@ + + + + + + Timed refresh + + + +

This page reloads itself after 5 minutes

+

Back to the demo

+ + diff --git a/dist/no-lang.html b/demo/no-lang.html similarity index 61% rename from dist/no-lang.html rename to demo/no-lang.html index c32c657..c59d7ef 100644 --- a/dist/no-lang.html +++ b/demo/no-lang.html @@ -1,12 +1,13 @@ - + - + Document with no language defined - +

What language am I?

+

Back to the demo

diff --git a/demo/no-title.html b/demo/no-title.html new file mode 100644 index 0000000..77034fd --- /dev/null +++ b/demo/no-title.html @@ -0,0 +1,12 @@ + + + + + + + + +

This page has no title

+

Back to the demo

+ + diff --git a/demo/no-zoom.html b/demo/no-zoom.html new file mode 100644 index 0000000..2e28991 --- /dev/null +++ b/demo/no-zoom.html @@ -0,0 +1,13 @@ + + + + + + Zoom disabled + + + +

This page stops people zooming in

+

Back to the demo

+ + diff --git a/dist/index.html b/dist/index.html deleted file mode 100644 index 4d44b5a..0000000 --- a/dist/index.html +++ /dev/null @@ -1,63 +0,0 @@ - - - - - - inaccessible.css demo - - - -

inaccessible.css

-

Violations

-

No title

-

No lang attribute

- - - -

Missing alt text

- - - - - -

No for attribute

- -
- - - - - - -
- - - - - - - - - - - - - - - - -
Column OneColumn TwoColumn Three
ABC
- - - - - - - diff --git a/playwright.config.js b/playwright.config.js new file mode 100644 index 0000000..43d24c4 --- /dev/null +++ b/playwright.config.js @@ -0,0 +1,7 @@ +const { defineConfig } = require('@playwright/test'); + +module.exports = defineConfig({ + testDir: 'test', + reporter: process.env.CI ? 'github' : 'list', + use: { browserName: 'chromium' }, +}); diff --git a/test/inaccessible.spec.js b/test/inaccessible.spec.js new file mode 100644 index 0000000..955403e --- /dev/null +++ b/test/inaccessible.spec.js @@ -0,0 +1,64 @@ +const { test, expect } = require('@playwright/test'); +const fs = require('node:fs'); +const path = require('node:path'); + +const demo = path.join(__dirname, '..', 'demo'); +const pages = fs.readdirSync(demo).filter((file) => file.endsWith('.html')); +const url = (file) => `file://${path.join(demo, file)}`; + +// Runs in the page: what each element should show and what it does show. +function inspect() { + const levels = { 'rgb(208, 0, 0)': 'error', 'rgb(230, 126, 0)': 'warning' }; + + return [...document.querySelectorAll('*')].map((el) => { + const style = getComputedStyle(el); + const outlined = style.outlineStyle !== 'none' && parseFloat(style.outlineWidth) > 0; + return { + html: el.outerHTML.split('>')[0].slice(0, 120) + '>', + expected: el.dataset.expect ?? 'none', + actual: outlined ? levels[style.outlineColor] ?? `other (${style.outlineColor})` : 'none', + message: el.dataset.message, + after: getComputedStyle(el, '::after').content, + }; + }); +} + +for (const file of pages) { + test(`${file}: every element is highlighted as expected`, async ({ page }) => { + await page.goto(url(file)); + const elements = await page.evaluate(inspect); + + const wrong = elements + .filter(({ expected, actual }) => expected !== actual) + .map(({ html, expected, actual }) => `${html} expected ${expected}, got ${actual}`); + expect(wrong).toEqual([]); + + const messages = elements + .filter(({ message, after }) => message && after !== `"${message}"`) + .map(({ html, message, after }) => `${html} expected "${message}", got ${after}`); + expect(messages).toEqual([]); + }); +} + +test('outline resets on the page do not hide highlights', async ({ page }) => { + await page.goto(url('index.html')); + await page.addStyleTag({ content: '*, *:focus { outline: 0; outline-offset: 0; }' }); + const outline = await page.$eval('img:not([alt])', (el) => getComputedStyle(el).outlineStyle); + expect(outline).toBe('solid'); +}); + +test('colours, width and messages can be customised with CSS variables', async ({ page }) => { + await page.goto(url('index.html')); + await page.addStyleTag({ + content: ':root { --inaccessible-error: rgb(0, 0, 255); --inaccessible-width: 5px; --inaccessible-message-display: none; }', + }); + + const img = await page.$eval('img:not([alt])', (el) => { + const { outlineColor, outlineWidth } = getComputedStyle(el); + return { outlineColor, outlineWidth }; + }); + expect(img).toEqual({ outlineColor: 'rgb(0, 0, 255)', outlineWidth: '5px' }); + + const display = await page.$eval('button:empty', (el) => getComputedStyle(el, '::after').display); + expect(display).toBe('none'); +}); From 382a1dfb4a9f9799e0fee82cbd654a8495eea0a2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 19:20:26 +0000 Subject: [PATCH 7/9] ci: run the tests on pull requests and fix the commit-msg hook Husky 8+ ignores husky.config.js, so commitlint wasn't running. Replace the outdated super-linter workflow with a build and test job, and lint commit messages on pull requests. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018z2Z3qN9ZawWK4VnZhhd1H --- .github/workflows/ci.yml | 30 ++++++++++++++++++++++++++++++ .github/workflows/lint.yml | 13 ------------- .husky/commit-msg | 1 + husky.config.js | 6 ------ 4 files changed, 31 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 .github/workflows/lint.yml create mode 100644 .husky/commit-msg delete mode 100644 husky.config.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..97b70fd --- /dev/null +++ b/.github/workflows/ci.yml @@ -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 diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml deleted file mode 100644 index 5865fa9..0000000 --- a/.github/workflows/lint.yml +++ /dev/null @@ -1,13 +0,0 @@ -name: Lint -on: - push: - branches: [ main ] - pull_request: - branches: [ main ] -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: Super-Linter - uses: github/super-linter@V3.8.0 diff --git a/.husky/commit-msg b/.husky/commit-msg new file mode 100644 index 0000000..da99483 --- /dev/null +++ b/.husky/commit-msg @@ -0,0 +1 @@ +npx --no -- commitlint --edit "$1" diff --git a/husky.config.js b/husky.config.js deleted file mode 100644 index 9026268..0000000 --- a/husky.config.js +++ /dev/null @@ -1,6 +0,0 @@ -module.exports = { - hooks: { - // 'pre-commit': 'lint-staged', - 'commit-msg': 'commitlint -E HUSKY_GIT_PARAMS', - }, -}; From ead2e2f76c6619e0c0a6c72a10f58d625f7c29b2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 19:20:26 +0000 Subject: [PATCH 8/9] docs: document every check, severity and customisation option Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018z2Z3qN9ZawWK4VnZhhd1H --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 82 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 8bc790f..0e30d95 100644 --- a/README.md +++ b/README.md @@ -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 `