Project Documentation · Engineering Phase · May 2026

Technical Specification

The Louis Clergerie Letter Website · michaeldbush.org/clergerie

Version 1.0 · May 2026 · Status: Approved · Prerequisite: Functional Specification v1.0

0. Site Title

Context	Text
Full title (H1, home page)	The Louis Clergerie Letter: A Soldier's Account of the China Campaign, 1860
Browser tab / `<title>` tag	The Louis Clergerie Letter
Navigation bar	The Clergerie Letter

1. Technology Stack

Layer	Technology	Notes
Markup	HTML5	Hand-authored; no templating engine
Styling	CSS3 with custom properties	One main stylesheet + one print stylesheet
Behavior	Vanilla JavaScript ES6+	Two files only: lightbox + tab switcher
Fonts	Google Fonts CDN	Playfair Display, Source Serif 4, DM Mono
Server	Apache on Alabama (Raspberry Pi)	Static file serving only
Development	ELMORE (Ubuntu 24.04)	See §8 for rationale
PHP / Node.js / MySQL	Available, not used	No backend logic required
Build tools	None	No npm, no bundler, no preprocessor

Rationale for no build tools

The site is small, long-lived, and will be maintained by non-specialist family members in the future. Vanilla HTML/CSS/JS requires no toolchain to modify or understand. It will still work correctly in ten years without dependency rot.

2. File Structure

/[alabama-webroot]/clergerie/
|
|== index.html                    ← Home page
|== letter.html                   ← Letter viewer
|== context.html                  ← Historical context + SVG map
|== campaign.html                 ← China campaign document
|== research.html                 ← Genealogical research guide
|== downloads.html                ← Downloads page
|== about.html                    ← About / family connection
|
|== css/
|   |== style.css                 ← Main stylesheet (all pages)
|   \== print.css                 ← Print stylesheet
|
|== js/
|   |== lightbox.js               ← ~80 lines, no dependencies
|   \== tabs.js                   ← ~30 lines, no dependencies
|
|== images/
|   |== letter/
|   |   |== page1-thumb.jpg       ← 800px wide thumbnail
|   |   |== page2-thumb.jpg
|   |   |== page3-thumb.jpg
|   |   |== page4-thumb.jpg
|   |   |== page1-full.jpg        ← Original resolution (lightbox only)
|   |   |== page2-full.jpg
|   |   |== page3-full.jpg
|   |   \== page4-full.jpg
|   \== map/
|       \== jura-voyage.svg       ← Self-contained SVG
|
\== downloads/
    |== clergerie-transcription.docx
    |== artillerie-chine-1860.pdf
    |== clergerie-letter-pages.pdf
    \== shd-request-letter.txt

3. CSS Architecture

3.1 Custom Properties

:root {
  /* Colors */
  --color-parchment:   #F5F0E8;
  --color-text:        #2C2C2C;
  --color-text-light:  #555555;
  --color-gold:        #C9A84C;
  --color-navy:        #1F3864;
  --color-rust:        #8B3A2A;
  --color-border:      #D4C9B0;

  /* Typography */
  --font-heading:  'Playfair Display', Georgia, serif;
  --font-body:     'Source Serif 4', Georgia, serif;
  --font-mono:     'DM Mono', 'Courier New', monospace;

  /* Layout */
  --max-width:     900px;
  --gutter:        2rem;
  --section-gap:   3.5rem;
}

3.2 Stylesheet Sections

Reset and base
Custom properties (:root)
Typography
Layout — page shell, nav, main, footer
Navigation (sticky header, hamburger)
Home page — hero, navigation cards
Letter viewer — two-column grid, thumbnails
Lightbox
Language tabs
Historical context — pull-quotes, timeline aside
Campaign page
Research guide — info boxes, pre block
Downloads page
About page
Utility classes
Responsive breakpoints

3.3 Responsive Strategy

Mobile-first. Base styles target narrow viewports. Two breakpoints: @media (min-width: 700px) activates the two-column letter viewer and expands navigation; @media (min-width: 900px) applies full max-width layout.

4. The SVG Voyage Map

4.1 Confirmed Waypoints

Constructed from the letter (pages 1–3) and the Scherer military study (artillerie.asso.fr, 2026):

#	Location	Coordinates	Source
1	Toulon (departure)	43.1°N, 5.9°E	Letter p.1
2	Strait of Gibraltar	36.1°N, 5.3°W	Letter p.3
3	Santa Cruz de Tenerife	28.5°N, 16.3°W	Letter p.3 (water stop, Christmas Day)
4	Cape of Good Hope	34.4°S, 18.5°E	Letter p.2 (letter dated here, 25 Feb 1860)
5	Réunion / Mauritius	20.9°S, 55.5°E	Standard French colonial route
6	Singapore / Strait of Malacca	1.3°N, 103.8°E	Standard route to Far East
7	Shanghai	31.2°N, 121.5°E	Scherer PDF — troops assembled here
8	Nagasaki, Japan	32.7°N, 129.9°E	Scherer: Jura carried 114 horses from Japan
9	Shanghai (return)	31.2°N, 121.5°E	Scherer PDF
10	Tché-fou / Beitang	37.5°N, 121.4°E	Scherer PDF — disembarkation point

Pékin (Beijing, 39.9°N, 116.4°E) marked as a non-visited reference point. The campaign's decisive battles — Palikao, the Summer Palace — are noted with smaller markers.

4.2 SVG Design Specifications

Property	Value
Viewport	1000 × 600px; `viewBox="0 0 1000 600"`; scales via CSS `width:100%; height:auto`
Projection	Simple equirectangular — covers 40°W to 150°E, 45°S to 50°N
Background	`#EDE8DC` — aged paper
Coastlines	Simplified paths, `#C9B99A` — no country borders
Sea areas	`#D6E4F0`
Route line	Dashed, `#C9A84C` (gold), stroke-width 2.5, directional arrowheads
Waypoint markers	Filled circles, `#1F3864` (navy), radius 5
Labels	Playfair Display, 11px, `#2C2C2C`
Style	Cartographic, period-appropriate; compass rose bottom-right
Embedding	Inline in `context.html` — no external file reference needed

5. Letter Viewer

5.1 Wide Screen Layout (≥ 900px)

CSS Grid: grid-template-columns: 1fr 1fr. Left column: active image + four thumbnail buttons. Right column: language tab switcher + active text panel (French or English). Each column scrolls independently. Active thumbnail indicated by gold border.

5.2 Narrow Screen Layout (< 900px)

Single column, top to bottom: horizontal scrolling thumbnail row → active page image (full width) → language tab switcher → active text panel.

5.3 Lightbox (`js/lightbox.js`)

Fixed-position overlay: background: rgba(0,0,0,0.88)
Full-resolution image centered: max-width: 95vw; max-height: 90vh
Image lazy-loaded on click — not preloaded at page load
Navigation: left/right buttons + keyboard arrow keys
Close: Escape key or click outside image
Page counter via <span aria-live="polite">Page 2 of 4</span>
Focus trapped within lightbox while open; returns to trigger on close
Graceful fallback (no JS): each image wrapped in <a href="page1-full.jpg">

5.4 Language Tab Switcher (`js/tabs.js`)

// On tab click:
// 1. Remove 'active' class from all tabs
// 2. Add 'active' to clicked tab
// 3. Set hidden attribute on all tabpanels
// 4. Remove hidden from corresponding tabpanel
// 5. Store selection: sessionStorage.setItem('lang', 'fr' | 'en')

// On page load:
// Read sessionStorage('lang') — default 'fr'
// Restore previously selected tab

6. Page Content Summary

Page	Key elements
index.html	Full-bleed hero (letter page 1 image + overlay text); epigraph blockquote (ocean sunset passage); two-sentence introduction; six navigation cards
letter.html	Two-column / stacked viewer; transcription conventions note; four-page navigation; lightbox; language tabs (French + English)
context.html	Three sections; embedded SVG voyage map (section 2); pull-quotes; key-dates aside in section 3
campaign.html	Scherer findings summary; highlighted passage naming the Jura's cargo; Japan horse excursion note; PDF download card
research.html	Six-step guide; SHD Vincennes and Toulon info boxes; draft request letter in `<pre>` block; external links
downloads.html	Four download cards: Word doc, Scherer PDF, combined letter PDF, SHD request letter
about.html	Family connection statement; research origin; attribution

7. Image Preparation

Source files: Clergerie-1s.jpg through Clergerie-4s.jpg. Run on ELMORE using ImageMagick:

# Install ImageMagick if needed
sudo apt install imagemagick

# Copy and rename originals
cp Clergerie-1s.jpg images/letter/page1-full.jpg
cp Clergerie-2s.jpg images/letter/page2-full.jpg
cp Clergerie-3s.jpg images/letter/page3-full.jpg
cp Clergerie-4s.jpg images/letter/page4-full.jpg

# Create 800px thumbnails
convert images/letter/page1-full.jpg -resize 800x images/letter/page1-thumb.jpg
convert images/letter/page2-full.jpg -resize 800x images/letter/page2-thumb.jpg
convert images/letter/page3-full.jpg -resize 800x images/letter/page3-thumb.jpg
convert images/letter/page4-full.jpg -resize 800x images/letter/page4-thumb.jpg

# Create combined PDF of all four pages
convert images/letter/page{1,2,3,4}-full.jpg downloads/clergerie-letter-pages.pdf

8. Development and Deployment

8.1 Why ELMORE, Not Alabama

	ELMORE	Alabama
CPU	AMD Ryzen 7 7700X	Raspberry Pi ARM
Architecture	x86-64 — native for Claude Code	ARM — occasional npm friction
Role	Development machine	Web server
ImageMagick	Full speed	Slow
Claude Code	Recommended	Not recommended

8.2 Local Preview on ELMORE

cd /home/mike/clergerie
python3 -m http.server 8080
# Open browser to http://10.12.1.20:8080

8.3 Deploy to Alabama

# Adjust path to match actual CIFS mount point
cp -r /home/mike/clergerie/* /mnt/data/[alabama-webroot]/clergerie/

# Verify after deployment
curl -I https://michaeldbush.org/clergerie/
# Expected: HTTP/1.1 200 OK

No .htaccess changes needed. No virtual host modifications. Apache's DirectoryIndex handles index.html automatically.

9. Performance Budget

Asset	Target
Each thumbnail × 4	≤ 300 KB each
Each full-resolution page × 4 (lightbox only)	≤ 2 MB each
SVG voyage map	≤ 80 KB
All HTML pages combined	≤ 200 KB
CSS + JS combined	≤ 40 KB
First load weight (index.html, no lightbox)	~500–700 KB total

10. Accessibility Checklist

All <img> elements have descriptive alt attributes
Navigation landmark: <nav aria-label="Main navigation">
Lightbox: aria-modal="true", focus trapped, aria-live page counter
Language tabs: role="tablist", role="tab", role="tabpanel", aria-selected
All text/background color combinations ≥ 4.5:1 contrast ratio
No content conveyed by color alone
All interactive elements reachable and operable by keyboard
lang="en" on <html>; French text blocks marked lang="fr"

11. Build Order for Claude Code Sessions

css/style.css — custom properties, base styles, typography, navigation
css/print.css — print stylesheet
index.html — home page; validates overall design and layout
letter.html — letter viewer shell, without JavaScript
js/lightbox.js + js/tabs.js — interactive behavior
context.html — historical context, text content only
images/map/jura-voyage.svg — voyage map SVG
Embed SVG inline in context.html
campaign.html, research.html, downloads.html, about.html
Image preparation via ImageMagick commands (§7)
Deploy to Alabama; verify with curl

Session discipline

Each Claude Code session begins by confirming the current state of the relevant file before making changes. Deviations from this specification require a conscious decision and a note — not silent improvisation.

✓

Approved — Proceed to Coding Technical Specification v1.0 · May 2026

✦