Documentation Site SEO & Accessibility Hardening

SEO Foundations

The documentation site at docs.speybooks.com now ships with proper search engine metadata across all 273 pages.

• Canonical tags — every page declares its canonical URL, preventing duplicate content indexing.
• Open Graph tags — title, description, URL, type, and site name are set for every page, improving link previews on social platforms.
• JSON-LD schema — the homepage includes structured WebSite data with publisher and author markup for richer search results.
• Title truncation — page titles are capped at 66 characters to display cleanly in search results, accounting for multi-byte characters.

Duplicate Content Cleanup

• Resource landing pages — API reference titles now include “API Reference” to differentiate from guide pages with similar names.
• Ghost route removed — a legacy /api/introduction/ path that duplicated the API overview now redirects to /api/.
• Redundant guide removed — a duplicate “How It Works” page was consolidated into the existing “Your First Invoice” guide.

Accessibility (WCAG AA Compliance)

Lighthouse accessibility score is now 100 on both mobile and desktop.

• Colour contrast — twelve colour tokens across light and dark themes were adjusted to meet WCAG AA 4.5:1 minimum contrast ratios, keeping the Spey blue aesthetic intact. Every token was verified computationally against its background.
• Link distinguishability — prose and description links now carry a persistent underline with a subtle colour tint, strengthening on hover.
• Form field attributes — the search modal input now includes id and name attributes, resolving browser autofill warnings.

Heading Hierarchy

• API reference pages — section headings corrected from h3 to h2 across 198 pages, resolving heading level skip warnings with zero visual change.

Performance

• Layout reflow eliminated — the enhance.js initialisation now batches all DOM reads before writes and defers viewport height correction via requestAnimationFrame, removing a 40ms forced reflow from the critical path.
• Resize debouncing — window resize events are coalesced into a single animation frame using cancelAnimationFrame, preventing layout thrashing during drag-resize.
• bfcache scroll restore — sidebar scroll position now restores correctly on back/forward navigation via the pageshow event, using a double-rAF technique to avoid reflow when setting scrollTop after layout invalidation.
• Font loading strategy — switched from font-display: block to font-display: swap with a metrics-matched Inter Fallback font face (size-adjust: 107%, ascent-override: 96.9%). Text now paints immediately using the fallback, with zero layout shift on swap. Eliminates the 220ms LCP render delay on the introduction page.
• Non-composited animation — added will-change: transform, opacity to the landing page status ping animation, promoting it to the compositor layer.
• Module preload — search.js is now preloaded via <link rel="modulepreload">, collapsing the critical request chain from sequential to parallel loading.

Mobile Ergonomics

• Fluid typography — font size tokens scale up inside the mobile breakpoint (--sd-text-base from 14px to 16px, --sd-text-xs from 11px to 12px), improving readability on phone screens without adding any new CSS classes.
• Touch targets — sidebar links widened to 12px 14px padding, search trigger expanded from 36px to 44px height, collapsible category titles given min-height: 44px, and search results spacing increased to prevent misclicks.
• Mobile panel depth — the slide-out sidebar now uses a box-shadow instead of a flat border, giving the drawer a premium floating appearance.

Sidebar Modernisation

• Active state — replaced the heavy blue background fill with a subtle gray background and a 3px left accent line in Spey blue (box-shadow: inset 3px 0 0 0). Matches the Stripe/Vercel pattern.
• Search pill — the search trigger now uses a transparent border with a soft background, revealing the border on hover rather than starting with a hard outline.
• Category labels — letter-spacing tightened from 0.08em to 0.04em and the bullet glyphs removed from top-level section titles, creating a cleaner visual hierarchy.
• Link spacing — added margin: 2px 0 between sidebar links for breathing room.

Stylesheet Maintenance

• Duplicate section removed — a duplicate Section 27 (Landing Page) block was stripped, reducing the stylesheet by 290 lines with no functional change.

Lighthouse Scores (Mobile, Slow 4G)