docs(adr): ADR-0007: Progressive Enhancement as Baseline Requirement

# ADR-0007: Progressive Enhancement as Baseline Requirement

## Status

Accepted

## Context

HTMX is often misunderstood as "adding JavaScript to make things dynamic." The opposite is true: HTMX enables server-rendered HTML to be enhanced with dynamic behavior while maintaining full functionality without JavaScript.

For documentation sites, this is critical:
- Search engine crawlers may not execute JavaScript
- Users on slow connections benefit from immediate content
- Accessibility tools work better with semantic HTML
- Corporate firewalls sometimes strip JavaScript

## Decision Drivers

1. **Accessibility** - Screen readers and assistive tech need working HTML
2. **SEO** - Search engines must index content without JS execution
3. **Resilience** - Sites must work when JS fails/blocks/loads slowly
4. **HTMX Philosophy** - Enhancement, not replacement

## Principle

> **All mdbook-htmx output MUST function completely without JavaScript.**
> JavaScript (via HTMX) enhances the experience but never underpins it.

## Implementation Requirements

### 1. All Links Must Be Real Links

```html

Chapter 2

Chapter 2
```

### 2. Forms Must Submit Normally

```html

Search

```

### 3. Full Pages Must Be Complete

The `pages/` directory contains fully-rendered HTML documents:

```html

Chapter 2 - My Book

```

No `` fallbacks needed - the page IS the fallback.

### 4. Content-First Loading

```html

```

### 5. Lazy Loading Is Progressive

Lazy-loaded sections must show meaningful placeholder content:

```html

Examples are loading... View examples page

```

## Verification Checklist

For every generated page, verify:

- [ ] Page renders complete content with JS disabled
- [ ] All navigation links work without JS
- [ ] Search form submits and returns results without JS
- [ ] Sidebar displays full chapter list without JS
- [ ] No empty containers that require JS to populate
- [ ] No `` tags (they indicate broken baseline)

## Testing

```bash
# Chrome DevTools: Disable JavaScript
# Settings > Preferences > Debugger > Disable JavaScript

# Or via CLI
curl -s https://docs.example.com/chapter-1 | grep -c ""
# Should return 1 (content present)
```

## Consequences

### Positive
- Works everywhere: slow networks, corporate proxies, screen readers
- SEO-friendly: crawlers see full content
- Fast First Contentful Paint: no JS blocking
- Resilient: partial JS failures don't break navigation

### Negative
- Slightly larger initial HTML (full content vs skeleton)
- Server must render complete pages, not just fragments
- Some dynamic features need careful design (e.g., live search needs form fallback)

## References

- [HTMX Essays: Progressive Enhancement](https://htmx.org/essays/progressive-enhancement/)
- [Hypermedia Systems: Chapter 2 - Progressive Enhancement](https://hypermedia.systems/hypermedia-components/)
- [MDN: Progressive Enhancement](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement)