Progressive Enhancement

---
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/>