docs: establish approved Phase 1 design + Phase 2 spec as project foundation

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-03 21:07:25 +02:00
commit 1f695d3932
39 changed files with 2686 additions and 0 deletions
@@ -0,0 +1,45 @@
+# SCROLL_EXPERIENCE.md
+
+## 1. Governing rule
+
+**The scrollbar is a contract.** Native scroll physics everywhere: no hijacking, no pinned scenes, no snap-scrolling on prose, no horizontal sections. Recruiters skim with momentum-flicks; anything that interferes reads as hostile.
+
+## 2. Homepage scroll narrative (desktop)
+
+| Scroll position | What happens | Why |
+|---|---|---|
+| 0 (load) | Hero static except trace draw (A1) | Decision facts readable instantly |
+| 0–120px | Header compresses 72→56px, gains blur backdrop + hairline bottom border (linear-mapped to scroll, not toggled — no pop) | Reclaims space, signals "we're moving" |
+| Each section at 20% entry | A2 section arrive, once | Reading rhythm |
+| Proof strip enter | Chip dots light in stagger (accent pulse A4) | Draws eye across the four facts |
+| Projects enter | Cards rise in 2-stagger; screenshots have 4px max parallax offset relative to card scroll | Depth without gimmick |
+| Experience enter | Timeline draw (A8) | Guides top-down reading |
+| Contact band enter | No animation — band is high-contrast already | Calm before conversion action |
+| Any position | Header CV button + nav always available | ≤1 interaction to CV rule |
+
+Scroll-spy updates nav underline per section. No "back to top" button on homepage (header is sticky; document is ~5 viewports); case studies (longer) get one after 3 viewports, ghost-style, bottom-right.
+
+## 3. Case-study scroll
+
+- Mini-TOC (≥1200px) tracks reading position with an accent tick; no progress bars (this is a document, not an article funnel — but see next point).
+- Long-form sections use generous `space-9` rhythm; architecture diagram gets full-width breakout (max 1200px) beyond the 72ch prose measure.
+- Images lazy-load 1 viewport ahead with aspect-locked skeletons — **zero cumulative layout shift** is a hard requirement.
+- Section anchors offset by header height + 24px; anchor links in TL;DR jump correctly.
+
+## 4. Mobile scroll
+
+- No parallax, no scroll-linked header compression (fixed 56px slim header from the start); section reveals still fire (opacity-dominant).
+- Sticky elements budget: header only. No sticky CTAs covering content (thumb-reach conversion handled by the contact band + header CV icon-button).
+- Overscroll behaviour default; PWA-style rubber-banding untouched.
+- Gallery swipe is the only horizontal gesture, clearly contained inside the lightbox.
+
+## 5. Deep-link & restoration behaviour
+
+- Anchor navigation (nav click, TOC, TL;DR links): smooth scroll 400ms max — distance-capped so cross-page-length jumps don't take seconds; reduced motion → instant.
+- Back/forward restores scroll position (browser default — do not fight it).
+- Language switch preserves scroll ratio where section structure matches (A7); if the target page differs structurally, land at top of the equivalent section rather than a mismatched pixel offset.
+
+## 6. Performance constraints on scroll effects
+
+- All scroll-linked effects (header compression, spy, reveals) via passive observers/transforms — no scroll-handler layout reads (jank = instant credibility loss with P2).
+- Reveal thresholds via IntersectionObserver semantics (conceptually); everything degrades to "visible" when JS is absent — **content is never gated behind scroll animation.**