DEV Community: Thomas Sweet

Twelve planted accessibility barriers. axe found two.

Thomas Sweet — Sat, 08 Aug 2026 21:16:46 +0000

You have probably heard the figure: automated accessibility tools catch only around a third of the problems on a page. It turns up in talks, vendor decks, and arguments on both sides, almost always without its receipts.

I cannot settle that figure and this article does not try. What I can do is show you where the line falls and why, on a page where I know every answer in advance. On my site there is a page I keep deliberately broken: a mock release page for my band's EP, where the band is real and the page is not its website. It carries twelve WCAG barriers that I planted on purpose. It is noindexed, and the answer key is published beside it. CI runs axe against it on every push, and the result is stable: two violations, image-alt and color-contrast. The other ten pass.

That gap is what the page is for. It is not a complaint about axe, and it is not a coverage statistic either: twelve barriers picked because they need different tools to catch is a rigged sample, and I would not read a percentage off it. What the page is good for is the question underneath. When a scanner stays quiet about a real barrier, what exactly stopped it from speaking?

There are two different answers, and telling them apart is most of what I learned building the thing.

Everything below is checked against axe-core 4.12.1, the version this pipeline resolves. Rule sets move between versions, so if yours pins something else, treat the specifics as things to verify rather than things to take from me.

The setup

The broken page is a self-contained HTML document with deliberately ordinary CSS: no framework, no design system, no safety nets. The isolation is load-bearing. An earlier version lived inside the main site, where a global reduced-motion rule and the preferences layer's focus ring kept quietly repairing planted barriers. A separate document is the only boundary CSS actually respects.

The scan is the ordinary one you would wire into any pipeline: axe-core through @axe-core/playwright, scoped by tag.

const tags = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa']

Some numbers are worth having in hand before the results. axe-core 4.12.1 ships 105 rules, and that tag list selects 70 of them. Fewer than that actually run. axe's default configuration carries tagExclude: ['experimental', 'deprecated'], which benches five of the selected rules tagged experimental (css-orientation-lock, label-content-name-mismatch, p-as-heading, table-fake-caption and td-has-header) and two tagged deprecated (aria-roledescription and audio-caption). One more, target-size, simply ships with enabled: false: a WCAG 2.2 Level AA rule that stays off until you ask for it, and the only rule my wcag22aa tag selects at all. That leaves 62 rules running. At least two of the benched rules are pointed straight at barriers on this page, which is where this article ends up.

The two it reports

The EP cover has no alt attribute at all, which fails 1.1.1 Non-text Content (Level A) and comes back as image-alt. The band's tagline is #a7a7a7 on white, which computes to 2.4:1 against a 4.5:1 minimum and fails 1.4.3 Contrast (Minimum) (Level AA) as color-contrast.

Neither result needs an opinion. One is a missing attribute, the other is arithmetic on two colour values. A rule settles both from the DOM and the computed styles without reference to what the page is for or what its author meant. Which is worth saying plainly, because it is the whole of what a rule is: a predicate a machine can evaluate against a node with certainty.

Hold on to "with certainty". It is the load-bearing part.

Reason one: there is no predicate

Most of the silent barriers are silent because the question they raise is not a question about the document.

The alt text that lies

The second image is a band photo with alt="IMG_2047.jpg". image-alt passes it, correctly: an alt attribute is present and non-empty, which is all that rule claims to check.

To flag it you would have to know what the photograph shows and whether those words describe it. That is not a property of the DOM. It is a fact about the world, and no amount of rule authoring gets you there.

The outcome is worth sitting with for a second. When an image has no alt attribute at all, screen readers commonly fall back to announcing the file name. When it has alt="IMG_2047.jpg", they announce the file name because you asked them to. Two barriers that land on the user in nearly the same way, reported as a violation and a pass.

The div that dresses as a button

The page's primary call to action is a div:

<div class="broken-page-listen">Listen now</div>

styled to look exactly like a button. It is not focusable, not operable by keyboard, and announces as nothing in particular, so it fails 2.1.1 Keyboard (Level A) and 4.1.2 Name, Role, Value (Level A) on the most important control on the page.

Nothing matches it. Not one of the 105 rules, experimental ones included. The rules that police buttons apply to elements that admit to being buttons, through their tag or an explicit role, and a generic element containing text is indistinguishable from a badge, a caption, or a stray line of copy.

To be precise about what "invisible" means here, because it is easy to overstate: the div is in the accessibility tree. It arrives as a generic node carrying its text, so a screen reader user browsing linearly does hear "Listen now". What is missing is a role and a place in the focus order, so it never turns up in the buttons list, never gets tabbed to, and gets filtered straight out by anything selecting for interactive elements.

There is a detail here I did not expect. axe does have a rule for roughly this mistake, focus-order-semantics, and its selector includes div. It could never see mine, though, because its matcher only picks up elements that have been inserted into the focus order, which in practice means something carrying a tabindex. And the rule is itself tagged both best-practice and experimental, so a WCAG-tag-scoped run like this one leaves it on the bench twice over. Give the div tabindex="0" and you make it half usable, and in the same movement you make it visible to the rule, in any run configured to include it. Leave it entirely broken and it stays beneath notice.

Opting out of semantics opts you out of scrutiny. Doing half the job is what puts you back in view.

The label that is not a label

The mailing-list form:

<input type="email" placeholder="Your email address" />

The field's only label is its placeholder, which fails 3.3.2 Labels or Instructions (Level A): its one instruction disappears the moment you act on it.

I assumed for a while that axe was simply not looking. It is looking, and it has decided. The label rule enumerates the ways a control can acquire a name, and placeholder is on the list by name:

any: [
  'implicit-label', 'explicit-label', 'aria-label', 'aria-labelledby',
  { id: 'non-empty-title', options: { attribute: 'title' } },
  { id: 'non-empty-placeholder', options: { attribute: 'placeholder' } },
  'presentational-role'
]

That is not carelessness. placeholder really does participate in the accessible name computation for text inputs, at the very bottom of the fallback chain, so the field genuinely has an accessible name. The rule checks whether a name exists. One does.

What a rule cannot weigh is what kind of name it is: drawn faint by the browser, gone the moment you type, never a label element at all. The field is named on paper and unlabelled in practice, and only the paper is computable.

There is a best-practice rule in the neighbourhood, label-title-only, and it does not help either. Its check fires only when a control's name comes from title or aria-describedby, and a placeholder-only input has neither. No ruleset axe ships reports this field, at any tag scope, experimental included.

The colour that carries the meaning

In the tour list, sold-out dates carry the word "ausverkauft" in red, and that red is the only thing separating a dead entry from the "Tickets" action sitting in the same position one row down.

Whether a colour is reinforcement or the sole carrier of meaning is exactly what 1.4.1 Use of Color (Level A) asks, and answering it means reading the page the way a person does: knowing what the rows are for, then asking what survives when the colour is taken away. Turn on a vision-deficiency emulation in DevTools and watch the distinction thin out.

No rule fires because there is no rule to fire. "Meaning carried by colour alone" is not a property of a node.

While I am on that row: the German word sits in an English document with no lang="de" around it, which is 3.1.2 Language of Parts at Level AA. valid-lang checks the lang attributes that are there, not the ones that should be.

Reason two: there is a rule, and axe ships it switched off

The second reason is a different animal, and it is the one that changed how I read scan results.

The button whose visible label is not its name

The subscribe button reads "Join the mailing list" and carries aria-label="subscribe":

<button type="button" aria-label="subscribe">Join the mailing list</button>

so the words a user can see appear nowhere in the control's accessible name. Someone using voice control who says "click join the mailing list" gets nothing. That fails 2.5.3 Label in Name (Level A, added in WCAG 2.1).

Unlike everything above, axe has a rule for it: label-content-name-mismatch, tagged wcag21a and wcag253, both of which are inside my tag scope. It still never fired, because the rule is also tagged experimental, and the default tagExclude keeps every experimental rule out of the run. withTags chooses among the rules a run will consider. It does not overrule the exclusion.

That is a defensible default. Matching visible text against an accessible name is heuristic work, and heuristics generate false positives, and false positives in a build gate get the gate removed. But it does mean "we run axe" describes a configuration rather than a result, and two pipelines that both say it can disagree about this page.

The tracklist with no headers

Same story, different shape. The tracklist is six rows built entirely of td cells with no th anywhere, so assistive technology cannot answer "which column am I in?". That fails 1.3.1 Info and Relationships (Level A).

A headerless table is legal HTML, and the genuine difficulty is that a layout table which never needed headers and a data table that lost them look the same in the markup. The difference is intent.

axe takes a run at it anyway, and how it does that is the interesting bit. td-has-header is aimed at exactly this barrier, and it gets there by guessing: a matcher decides whether the element looks like a data table at all, and the rule only applies to tables of at least three rows and three columns. The tracklist, six rows of three cells each, qualifies; enable the rule and it fires. So the rule exists, it encodes a heuristic for intent, and it sits on the experimental bench for the same reason as the one above.

Line the two reasons up and the shape is hard to miss. The rules axe runs by default are the ones that can be decided from the document with certainty. The rules it withholds are the ones that have to guess at intent. The barriers with no rule at all are the ones where there is nothing to guess with. axe's own packaging draws the same line this page is about, which is a better argument for that line than any percentage I could quote at you.

Same level, different bug

One calibration before the tooling, because conformance levels invite a misreading. Level A does not mean "hurts more than AA". The level grades how foundational a requirement is, not how much a given instance harms.

The unpressable div and the filename alt both fail at Level A. One is the page's primary call to action being absent for every keyboard and screen reader user. The other is a photo at the foot of the page announcing itself as a camera file. Same level, not remotely the same bug. Prioritisation needs human judgement for the same reason detection did.

The test that fails when the bug gets fixed

A fixture like this earns its keep only while it stays exactly as broken as documented, so the suite pins it from both sides. The scan of the broken page does not assert "no unexpected violations". It asserts that the violation set equals the documented pair:

const results = await new AxeBuilder({ page }).withTags(tags).analyze()

expect(results.violations.map((v) => v.id).sort()).toEqual([
  'color-contrast',
  'image-alt',
])

A companion test scans the surrounding page with the fixture excluded, via .exclude('#broken-page'), and asserts zero violations. Between them: nothing outside the frame may be broken, and nothing inside it may heal. If a refactor accidentally repairs a planted barrier, CI goes red, because a teaching fixture that quietly heals teaches a lie.

It is the most cheerful red build I own. A failure means either the page got better, which has to be undone, or axe got better, which is worth knowing the day it happens. That second one is not hypothetical. Every benched rule above is a candidate for graduating into the default set, and this page will tell me the morning it does.

Go and look

The audit room holds the broken page as an inert half-scale preview, with one disclosure per barrier: a hint first, the full answer a level deeper. Open the broken page at full scale in its own tab and hunt with the Tab key, the heading list and the accessibility pane before you touch the answers. Several of the twelve never came up in this article at all.

Then run your own scan against it. If your axe reports something other than those two, I would like to hear about it, because that is the interesting failure.

Edited after publishing: the original said a scanner cannot distinguish a layout table from a data table. axe does try, via an experimental rule it ships switched off. The corrected section is above.

prefers-color-scheme doesn't ask your OS. It asks your browser.

Thomas Sweet — Sat, 08 Aug 2026 18:45:19 +0000

My OS was in light mode. GitHub was set to sync with the system. The README's images were dark.

I checked the srcsets. I suspected GitHub's HTML sanitizer. I cleared caches I had no reason to believe were involved. Then I opened the page in a private window and the images were correct, which ruled out my markup entirely and left me with no suspects at all.

The override was in my own browser. Chrome's appearance setting was pinned to Dark, and had been for months. Not the OS, not GitHub, not the markup.

The chain

I had been thinking about dark mode as one setting. It is a chain of at least three, and each link can silently override the one above it while reporting nothing to the one below.

1. The operating system has a colour scheme setting. This is the one everybody means by "follows your system".

2. The browser defaults to following the OS, and can pin its own value instead. Chrome's appearance setting has Light and Dark options that override the system for every page you visit. This layer's output is what prefers-color-scheme reports — MDN is precise about it, if you read closely: the preference comes from "an operating system setting or a user agent setting". CSS never talks to your OS. It talks to this.

3. The site can follow the browser, via light-dark() or media queries, or run its own theme control on top. GitHub does the latter: its theme preference drives the page chrome, and only agrees with your images' media queries when it is set to sync.

My machine had layer 2 pinned. Every media query on every site I visited was being told "dark" while the OS said light, and nothing anywhere indicates that an override is active. If a user has ever told you your dark mode toggle does nothing, there is a fair chance nothing was broken except this chain.

The debugging order that would have saved me two hours: check a private window first, which isolates site-level state, then walk the chain upward from the page rather than downward from the OS. The layer you are least likely to suspect is the one in the middle, because you configured it once and forgot.

The part where I had shipped the wrong claim

My README stated that the images "follow your OS colour scheme".

That is not what they do. They follow prefers-color-scheme, which usually reflects the OS and, on my own machine at that moment, did not. The claim was false on the very machine I wrote it on.

For a repository whose subject is accessibility education, naming the wrong mechanism is a defect like any other, so it got a commit. The README now says the images follow your colour-scheme preference as reported by your browser, which is usually your OS setting unless the browser overrides it. It also gained the troubleshooting line I wish I had read at the start: if a scheme toggle seems to do nothing, check your browser's own appearance setting.

Precision about mechanisms is not pedantry here. Documentation that names the wrong layer sends the next person to debug the wrong thing.

What actually works in a README

Worth stating plainly, because the constraints surprised me and the capability is better than I expected.

GitHub's sanitizer allows <picture>, which is the whole scheme-swap:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/hub-dark.png">
  <img alt="The overview hub" src="docs/screenshots/hub-light.png">
</picture>

And an SVG referenced as a plain image still evaluates its own internal CSS, including media queries. One file can adapt to colour scheme and gate its animation behind prefers-reduced-motion. It cannot load external resources, so fonts have to be system stacks and everything has to be self-contained, but within that boundary it is a real stylesheet.

One consequence worth thinking through: an animation inside an <img> has nowhere to put a pause button. WCAG expects moving content to be pausable, and an image cannot offer controls. So the banner's animation is finite by design. It draws, holds, replays twice, then settles permanently into its end state. Reduced-motion users get the settled state with no motion at all, through the same media query that handles the colours. When you cannot give motion an off switch, the alternative is giving it an ending.

Two sharp edges in the same file

Neither of these is about colour schemes. Both cost me hours in the same banner, and both are the kind of thing you only meet by walking into them.

Never put an angle bracket inside an SVG <style> element. I wrote a CSS comment that mentioned an <img> tag — literally, inside the stylesheet. In XML that < starts markup, so the parser silently truncated the stylesheet at that point and discarded everything after it.

The consequences were disproportionate to the typo. The banner's animation was dead in every version I had shipped. Every fix I tried was invisible, because the code I was fixing sat after the comment and never ran. And there was no error, in any console, at any point — a truncated stylesheet is not malformed, it is just short. I was debugging keyframes that the parser had never seen. The comment now says "an image", and the file carries a warning for future me.

textLength needs lengthAdjust="spacing". The banner's headline has to fit its plate on macOS, Windows and Linux system fonts, so textLength pins the width. But lengthAdjust decides what absorbs the difference: spacingAndGlyphs stretches the letterforms themselves, which came out around 25 percent in my case and reads as a strange skew rather than a font substitution. spacing flexes only the gaps and leaves the glyphs alone. Measure the natural width on your reference platform, set textLength to that, and declare lengthAdjust explicitly rather than trusting whatever you inherit — it is the difference between a banner that adapts and one that looks subtly wrong on every platform except the one you designed it on.

Go and flip a setting

The adaptive banner, the scheme-swapping screenshots and the corrected wording are all on the repo now. Change your browser's appearance setting while looking at it — not your OS. That is the demo, and if the images change while your system stays put, you have just watched layer 2 do its thing.

ThomasSweet / a11y-foundation

An accessibility-first styling playground — how much of accessibility the modern web platform handles natively, with little to no JavaScript. WCAG rules you can break, cutting-edge CSS showcases, tokens and cascade layers.

Accessible by default

How much of accessibility does the modern web platform handle natively — with little to no JavaScript? This site is that question, answered as one argument in four parts: what the standard (WCAG) asks for, the craft of meeting it with modern CSS and HTML, what cutting-edge CSS makes possible next, and the proof that it holds up.

Underneath it is an accessibility-first styling foundation — SCSS mixins design tokens, and a cascade-layer architecture — where components adapt to user preferences (reduced motion, high contrast, forced colors, dark mode reduced transparency) and input capabilities (hover, touch) by default, with the cascade doing the work instead of !important.

Note

The design vote is settled. The blueprint restructure — an overview hub plus four chapter pages, wearing a technical-drawing look — won the review round and is now the live design. The previous single-page design is kept under…

View on GitHub

The site the banner belongs to has since been rebuilt as an overview hub plus four chapter pages, making the same argument with rather more room for it. If you find a barrier anywhere in it, the issues tab is open.

My zero-JS page transitions flashed white. Two bugs, two causes, one blend mode I'd never heard of.

Thomas Sweet — Fri, 31 Jul 2026 19:48:46 +0000

The short version, if you arrived here from a search:

Your automation browser may not run cross-document view transitions at all. Check that before you debug anything else.
If you replace the default transition animation, you inherit mix-blend-mode: plus-lighter, which was chosen for the animation you just deleted. That is your brightness pulse.
A hard white blink before the transition is not the transition. It is an unstyled frame of the incoming document painting the UA default.

The long version follows, because the reasoning is more useful than the fixes.

My site accessible-by-default.dev is a multi-page app on purpose. Real page loads mean screen readers announce the new page, focus resets, the URL bar tells the truth, and there is no routing JavaScript to break. It is an overview hub plus four chapter pages, and I wanted moving between them to feel calm: the frame stays put, the content quietly fades.

The platform hands you exactly this. One at-rule in both documents:

@view-transition {
  navigation: auto;
}

The browser snapshots the old page, loads the new one, and animates between them, across a real navigation, with no JavaScript.

Then I customised the animation and got flashes. Bright pulses mid-fade in light mode, odd glare in dark mode, and separately a hard white blink on some navigations. I spent a while chasing them as one bug. They were not one bug.

The trap that cost me an evening first

I could not reproduce any of it in my e2e setup, for an unhelpful reason: the Chromium build my test runner drives does not execute cross-document view transitions at all. Pages swapped instantly. No snapshots, nothing to observe, nothing to debug.

I ended up driving my real installed Chrome over the DevTools protocol to see what users see.

So: if your transition works locally but not in tests, or passes tests but misbehaves locally, verify that your automation browser actually performs cross-document view transitions before you form a single hypothesis about your CSS. Mine did not, and every conclusion I drew from those runs was noise.

Bug one: the brightness pulse

My custom animation is deliberately simple. The new page renders immediately underneath, and the old page's snapshot fades out on top of it:

::view-transition-new(root) {
  animation: none;
}

::view-transition-old(root) {
  z-index: 1;
  animation: 0.28s ease both vt-content-fade;
}

@keyframes vt-content-fade {
  to { opacity: 0; }
}

Fade one opaque layer over another opaque layer. There is no frame in that description which should produce something brighter than either page. And yet, a visible brightness pulse, on every navigation.

The answer is in the browser's own stylesheet. The spec places the old and new snapshots inside an isolated group and blends them with mix-blend-mode: plus-lighter, which adds the colours of the layers together, weighted by alpha.

That default is a good decision. In the browser's default cross-fade, the old snapshot's opacity runs 1 to 0 while the new one runs 0 to 1, so the weights always sum to one, and plus-lighter makes the crossfade mathematically seamless: two half-transparent copies of similar content add back up to full brightness instead of dipping grey in the middle.

But I had replaced the default animation. My new snapshot sits at full opacity for the entire transition, and early in the fade the old snapshot is still nearly opaque on top of it. Plus-lighter adds them. Almost double the light, which on a light theme clips straight to white.

So the pulse was a blend mode doing precisely what it was told, under an assumption my keyframes had quietly invalidated.

The fix is to restore normal painting:

::view-transition-image-pair(root) {
  isolation: auto;
}

::view-transition-old(root),
::view-transition-new(root) {
  mix-blend-mode: normal;
}

The generalisable version: if you replace the default view-transition animation with anything whose opacities do not sum to one, you have also inherited a blend mode designed for the animation you just deleted.

Bug two: the hard white blink

After the blend fix, something was still there. A pure white flash on some navigations, and this one was fast enough that I could not tell where in the sequence it sat.

Stretching the transition to 1.5 seconds settled it: the flash happened first, then the fade played cleanly. It was not part of the transition at all.

It was the incoming document. During the handoff there can be a painted frame of the new page before its CSS has been applied, and an unstyled document paints the user-agent default, which is white. In dev this was worst, because Vite injects CSS through JavaScript, but a cold navigation in production can catch it too.

The fix is unglamorous and reliable. Every entry HTML inlines one declaration, so that even a completely unstyled frame paints in the page's background colour rather than white:

<style>
  @layer base {
    :root { --boot-ground: light-dark(#f5f5f5, #1a1a1a); }
    html { background-color: var(--bp-ground, var(--boot-ground)); }
  }
</style>

Those two hex values are the light and dark background colours of the blueprint theme — the "ground" the rest of the page sits on. The declaration lives in the lowest cascade layer, so the moment the real stylesheet arrives, the theme's own ground token wins through the var() fallback chain. Before that moment, the raw frame is already roughly the right colour.

Two related details if you build this. Give the entry script blocking="render", so the first rendered frame — and therefore the snapshot the transition captures — is the full page rather than an empty mount point. And check that your bundler preserves the attribute: Vite dropped it from the built HTML, which took a four-line plugin to put back.

Why a flash is worth this much attention

Sudden full-screen luminance changes are not a cosmetic issue. For photosensitive users they are the exact thing WCAG's flash criteria exist to prevent, and a page that blinks bright white between navigations is a worse experience than a page with no transition at all.

Which is why the whole feature is an enhancement rather than a baseline:

@media (prefers-reduced-motion: no-preference) {
  /* the entire transition setup lives in here */
}

Reduced-motion users get instant, ordinary navigations. Everyone else gets a 0.28 second content fade on top of real multi-page semantics: proper page announcements, focus reset, a working back button, no router.

Total change for two multi-day bugs: six declarations and one inline style block.

You can feel it on the live site, and the source is here:

ThomasSweet / a11y-foundation

An accessibility-first styling playground — how much of accessibility the modern web platform handles natively, with little to no JavaScript. WCAG rules you can break, cutting-edge CSS showcases, tokens and cascade layers.

Accessible by default

Note

View on GitHub

If you have hit a third cause of flashing in a cross-document transition, I would like to hear about it. Two took me long enough that a catalogue seems worth starting.

Every state of the page passed axe. The page was still broken.

Thomas Sweet — Tue, 28 Jul 2026 17:44:55 +0000

Open the CSS showcase catalog on my site. Filter it to "typography" with the topic chips. Now click a sidebar link that points at a layout showcase.

Nothing happens.

The URL updates. The page does not move. The link is real, its target exists in the document, and it leads nowhere, because the active filter is hiding that target with display: none. For a keyboard user this is a dead end with no feedback of any kind: you activate a link, and the page silently declines.

Here is the part that stuck with me. Axe reports zero violations on that page. Before the click, after the click, filtered, unfiltered. Every individual state is clean, and always was.

Why no scanner can catch this

Automated accessibility tooling evaluates a state. It walks the accessibility tree at a moment in time and checks it against rules: does this control have a name, does this contrast ratio clear the threshold, is this landmark in the right place. Those are excellent questions and axe answers them faster and more consistently than I ever will.

But nothing in this page is malformed at any instant. The filter is a set of radio chips plus :has(), no state management, no JavaScript. The sidebar is anchor links pointing at ids that exist. Both are patterns I would happily recommend. The defect only exists in the composition of the two, and a composition is not a state, so there is no snapshot in which a rule could fire.

This is not a gap in axe's ruleset that a future version will close. It is the shape of the tool.

The fix stayed pure CSS

The project has one hard architectural rule: no unlayered CSS, ever. Everything lives in a cascade layer, which meant the fix was available without touching specificity or reaching for JavaScript.

The filter hides non-matching showcases with display: none from the components layer. A rule in the utilities layer, which sits above it, puts the current :target back — along with the tier group containing it, which the filter may also have collapsed:

@layer utilities {
  .showcase:target,
  .showcase-group:has(.showcase:target) {
    display: grid;
  }
}

Layer order does the whole job. No !important, no specificity arms race, no JavaScript to reset the filter. The linked-to showcase reappears, the filter stays intact for everything else, and neither feature needs to know the other exists.

Two details that matter if you copy this. Keep the selectors scoped to your own classes: a bare :has(:target) matches every ancestor of the target, body and html included. And declare the real value rather than revert-layer, which sounds like the right tool and is not — it rolls back to the value from the layer below, which here is the display: none you are trying to undo.

A keyboard spec now pins the behaviour so it cannot quietly regress: a link to a filtered-out showcase still reveals it. That assertion came from asking what a keyboard user would actually do on this page. It could not have come from a rule.

Which means the steps at the top of this post no longer reproduce. Follow them today and the link lands, because of that rule. I would rather say so than leave the bug up as a museum piece.

What each layer actually caught

The site's last chapter argues that accessibility testing has to be layered. Building the site was the first real test of that argument, so here is the honest inventory, split by when each finding surfaced, because that distinction matters more than a combined list would suggest.

Caught in CI, before anything shipped.

Stylelint enforces the no-unlayered-CSS rule and mixin ordering; vue-tsc handles types. Vitest guards the theming engine's contrast maths and watches Baseline data for fallback drift. The axe sweep runs every page in Chromium, Firefox and WebKit, and it found two things I would have missed: an icon-only GitHub link with nothing for a screen reader to announce, and a missing color-scheme meta, which let native form controls render light inside a dark theme.

Small, mechanical, entirely real. Running three engines matters more than I expected, too. WebKit and Firefox disagree with Chromium often enough that a single-engine sweep is quietly telling you less than you think.

The Playwright keyboard specs sit here as well, and they pin the things no rule expresses: skip link is the first tab stop, dialog traps focus and closes on Escape, popovers light-dismiss, the theme panel survives a full keyboard round trip, and the filter bug above.

Caught by others, on their phones

A phantom focus ring on iOS: someone opened a dialog demo, closed it, and the content column behind it kept drawing a focus ring. A tabindex="-1" container was receiving programmatic focus. No tool flags a focus ring that should not be there.

Non-colour state cues vanishing in Safari: the theming system renders them through style queries, and WebKit does not apply pseudo-element rules inside a style query. Someone browsing on an iPhone mentioned, almost in passing, that they could not see the non-colour cues at all. Visually broken, semantically fine, invisible to every automated layer I run. The fix — have the query set a custom property on the element and let the pseudo-element render that — is now taught in the site's own snippet for the feature.

Caught by visitors, after shipping.

A loading spinner and the timeline's watermark years derived their colour from the border token rather than a text token, so on some seed combinations they nearly disappeared. The contrast maths was never wrong; I had wired two elements around it. Somebody said "I can barely see this," which is a bug report no scanner produces.

And this, from a keyboard user: after tabbing deep into a long chapter, getting back to navigation meant tabbing through everything again. That is not a WCAG failure. It is friction that a checklist will never surface and a human feels within ten seconds. Every chapter now ends with a back-to-navigation link, pinned by e2e.

The uncomfortable arithmetic

Line the inventory up and it makes an argument I did not set out to make.

If my pipeline had been "run axe in CI" — which is what a great many pipelines are — every finding in the last two sections ships. The site would have been scanner-clean and still had a dead-end filter for keyboard users, invisible state cues for every Safari visitor, a phantom focus ring on iOS, and washed-out decorative elements on several themes.

None of those layers is redundant with another. What each one misses, another one catches, and the only way to find that out is to run all of them and see which findings overlap. On this site, almost none did.

Where this actually stands

The suite is green today across three engines. Worth being precise about what that means: the failures I have already met cannot come back. It is a regression net, not a certificate, and the site is very much still a work in progress. I would rather publish that sentence than a badge.

The site is also the demo. Every claim above is running code you can poke at, including "break this rule" toggles on the WCAG criteria so you can feel what each one prevents.

ThomasSweet / a11y-foundation

An accessibility-first styling playground — how much of accessibility the modern web platform handles natively, with little to no JavaScript. WCAG rules you can break, cutting-edge CSS showcases, tokens and cascade layers.

Accessible by default

Note

View on GitHub

If you find a barrier I missed, the issues tab is open and that is a genuinely welcome outcome. Composition bugs like the one at the top of this post are the hardest class to find alone, because they need someone who did not write both features to try using them at the same time.