progressive-enhancement · diff
git:20260331.0b2aead to git:20260331.f09d889
11 added, 0 removed. Audit C to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
+ ---
+ name: progressive-enhancement
+ description: >
+ Load this skill when building any web feature, reviewing architecture
+ decisions, or evaluating JavaScript dependencies. Under no circumstances
+ build features that break completely when JavaScript is unavailable or fails.
+ Absolutely always start with semantic HTML, layer CSS enhancements, and add
+ JavaScript as the final, optional layer. Prioritize resilience and universal
+ access over cutting-edge features.
+ ---
+
# Progressive Enhancement Accessibility Skill
> **Canonical source**: `examples/PROGRESSIVE_ENHANCEMENT_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
> This skill is derived from that file. When in doubt, the example is authoritative.
Apply these rules when building any web feature or reviewing architecture decisions.
---
## Core Mandate
Start with a solid foundation that works for every user, then layer enhancements.
Every user — regardless of browser capability, network speed, assistive technology,
or JavaScript availability — must be able to access core content and complete core
tasks.
Progressive enhancement is also a sustainability practice. Pages that work without
JavaScript are dramatically lighter: fewer bytes transferred, less CPU spent on
parsing and executing scripts, and less energy consumed per page view. See
[SUSTAINABILITY.md](https://github.com/mgifford/SUSTAINABILITY.md) and the
[Web Sustainability Guidelines](https://www.w3.org/TR/web-sustainability-guidelines/).
---
## Severity Scale (this skill)
| Level | Meaning |
| --- | --- |
| **Critical** | Core content or task inaccessible without JS/CSS |
| **Serious** | Core content accessible but significantly degraded without JS/CSS |
| **Moderate** | Enhancement degrades gracefully but with friction |
| **Minor** | Best-practice gap; marginal impact |
---
## The Three Layers
### Layer 1 — Semantic HTML (always required)
**Failure here is Critical.**
* All core content readable in plain HTML — no CSS or JS required
* Forms submittable with native browser behaviour
* Navigation functions as standard links
* Headings, lists, tables, and landmarks accurately reflect document structure
### Layer 2 — CSS (enhance presentation)
**Failure here is Moderate to Serious.**
* External stylesheets that can be disabled without losing content
* Respect user preferences: `prefers-reduced-motion`, `prefers-color-scheme`,
`prefers-contrast`, `forced-colors`
* Page remains usable if stylesheets fail to load
### Layer 3 — JavaScript (enhance interactivity)
**JS that gates core content or tasks is Critical.**
* JS enhances; it does not gate access to core content or tasks
* Apply JS-dependent classes/behaviours from scripts, not static markup
* Handle script failure gracefully — the HTML layer must still work
* Use feature detection, not browser detection:
```js
if ('fetch' in window && 'querySelector' in document) {
// apply enhanced experience
}
```
### Layer 3 extension — Service Workers (offline capability)
Service Workers are a Layer 3 enhancement: they require JavaScript, are
registered by a script, and must degrade gracefully when unavailable (private
browsing, unsupported browsers, HTTPS not available).
When implemented, they extend both accessibility and sustainability:
* **Accessibility**: users on unreliable connections (common in rural areas,
low-income households, and developing regions) can continue to access
previously loaded content offline
* **Sustainability**: cached responses eliminate repeat network requests,
reducing data transfer and server energy per page view
```js
// Register Service Worker only if supported — classic PE feature detection
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('/sw.js').catch((err) => {
// Registration failure: page continues to work normally without it
console.warn('Service Worker registration failed:', err);
});
}
```
**Offline fallback pattern:**
```js
// sw.js — cache-first with network fallback
const CACHE_NAME = 'v1';
const OFFLINE_URL = '/offline.html';
self.addEventListener('install', (event) => {
event.waitUntil(
caches.open(CACHE_NAME).then((cache) =>
cache.addAll([OFFLINE_URL, '/', '/styles.css'])
)
);
});
self.addEventListener('fetch', (event) => {
if (event.request.mode === 'navigate') {
event.respondWith(
fetch(event.request).catch(() => caches.match(OFFLINE_URL))
);
}
});
```
The offline fallback page (`/offline.html`) must itself be a valid Layer 1
HTML document — semantic, readable without CSS or JS.
Service Worker caching strategies (cache-first, network-first, stale-while-
revalidate) should be chosen based on content update frequency. Avoid caching
strategies that serve stale content for content that changes frequently without
a cache-invalidation plan.
---
## Critical: Core Content Must Not Require JavaScript
Rendering page content exclusively in JavaScript is **Critical** — users with
JS disabled, AT users encountering compatibility issues, and low-bandwidth users
are completely excluded.
* Deliver complete HTML from the server; hydrate interactivity in the browser
* Core content must be in the initial HTML response
* When using React/Vue/Angular/Svelte: configure SSR or static generation
* Avoid SPA patterns that require JS to render any visible content
Every byte of JavaScript that is not needed to access core content is unnecessary
energy consumption. Prefer server rendering — it transfers HTML once; a JS bundle
transfers code that must then be parsed, compiled, and executed on every visit.
---
## Critical: Forms Must Work Without JavaScript
```html
<!-- Layer 1: works without JS -->
<form action="/search" method="get">
<label for="query">Search</label>
<input id="query" name="q" type="search">
<button type="submit">Search</button>
</form>
```
Enhance with JS for instant results, autocomplete, or inline validation —
while keeping the server-processed form as fallback.
**A form that cannot be submitted without JS is Critical.**
---
## Critical: Navigation Must Work Without JavaScript
```html
<!-- Layer 1: plain links always work -->
<nav aria-label="Main">
<ul>
<li><a href="/about">About</a></li>
<li><a href="/contact">Contact</a></li>
</ul>
</nav>
```
Enhance with JS for dropdowns or animated transitions.
---
## Serious: Dynamic Content Must Have a Fallback Route
```js
if ('fetch' in window) {
loadContentAsync(url);
} else {
// Standard link navigation works automatically
}
```
Use `aria-live` regions only after confirming the base content is accessible
without them.
---
## Moderate: CSS User Preferences Must Be Respected
`prefers-reduced-motion`, `prefers-color-scheme`, `prefers-contrast`, and
`forced-colors` are Layer 2 responsibilities. Ignoring them is **Moderate** at
minimum; ignoring `prefers-reduced-motion` for fast or flashing animations can
reach **Serious**.
---
## What to Avoid
* Rendering page content exclusively in JavaScript — **Critical**
* `display:none` / `visibility:hidden` on content required at the HTML layer — **Critical**
* Requiring JS to navigate between pages without a server-rendered fallback — **Critical**
* `user-scalable=no` — **Serious** (prevents zoom for low-vision users)
* Assuming scripts will execute — always handle failure states
* Polyfills as a substitute for progressive enhancement (they patch features;
PE builds around their absence)
* Shipping large JS bundles for functionality that could be server-rendered —
this is both an accessibility risk and a sustainability cost
---
## Definition of Done Checklist
* [ ] Core content readable with JavaScript disabled
* [ ] Core tasks completable with JavaScript disabled
* [ ] Forms submit via native browser behaviour
* [ ] Navigation works as standard HTML links
* [ ] CSS respects `prefers-reduced-motion`, `prefers-color-scheme`, `prefers-contrast`
* [ ] Script failure handled gracefully
* [ ] Feature detection used (not browser detection)
* [ ] SSR or static generation configured for JS frameworks
* [ ] Service Worker registered with feature detection and silent failure handling
* [ ] Offline fallback page is valid Layer 1 HTML
* [ ] Caching strategy documented and matched to content update frequency
* [ ] Tested: disable JS → verify core content; disable CSS → verify logical reading order
---
## Key WCAG Criteria
* 2.1.1 Keyboard (A) — native elements have built-in keyboard support
* 4.1.2 Name, Role, Value (A)
> **Note:** WCAG 4.1.1 Parsing was **removed in WCAG 2.2** (August 2023).
> Modern browsers handle parsing errors uniformly. Valid semantic HTML remains
> important as a progressive enhancement foundation, but it is no longer a
> testable WCAG criterion. Do not cite it in audits or compliance statements.
---
## References
* [Full best practices guide](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/examples/PROGRESSIVE_ENHANCEMENT_BEST_PRACTICES.md)
* [SUSTAINABILITY.md](https://github.com/mgifford/SUSTAINABILITY.md) — PE reduces page weight and energy use; see WSG alignment
* [Web Sustainability Guidelines (WSG) 1.0](https://www.w3.org/TR/web-sustainability-guidelines/)
* [MDN: Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
* [MDN: Offline and background operation](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Offline_and_background_operation)
> **Standards horizon:** WCAG 3.0 is in development. No breaking changes to
> progressive enhancement principles are anticipated.
> Monitor: <https://www.w3.org/TR/wcag-3.0/>