Merge pull request #1 from BRO3886/claude/polish-ui-animations-kqmeR

Author: BRO3886

journals/002-2026-02-18-journal.md

@@ -0,0 +1,142 @@
+# Journal Entry 002 - 2026-02-18 - iOS Health-inspired UI polish
+
+## Goal
+
+Polish the Hugo website with microanimations and a professional, iOS Health-inspired design system. Criteria: no flashy effects, professional/detail-oriented feel, looks good on mobile, preserves existing UX.
+
+## What Changed
+
+### `website/assets/css/main.css` (complete rewrite)
+
+**Color system — Apple semantic palette:**
+- `--text: #1d1d1f` (Apple near-black, up from `#1a1a1a`)
+- `--text-secondary: #6e6e73` (Apple secondary, up from `#666`)
+- `--bg-secondary: #f5f5f7` (Apple light surface, was `#f6f6f6`)
+- `--accent: #007AFF` (Apple blue, was GitHub blue `#0969da`)
+- `--accent-hover: #0055D4` (was `#0550ae`)
+- Added `--accent-subtle: rgba(0, 122, 255, 0.08)` for hover backgrounds
+- Added `--border-subtle: rgba(0, 0, 0, 0.06)` for hairline separators
+- Added `--radius-sm: 6px`, `--radius-md: 10px`, `--radius-lg: 14px`
+- Added `--shadow-sm`, `--shadow-md`, `--ease: 0.15s ease`
+- Dark mode: `--bg: #1c1c1e`, `--accent: #0A84FF` (Apple exact dark-mode variants)
+
+**Nav — iOS frosted glass:**
+```css
+.nav {
+  background: rgba(255, 255, 255, 0.82);
+  backdrop-filter: saturate(180%) blur(16px);
+  -webkit-backdrop-filter: saturate(180%) blur(16px);
+  border-bottom: 1px solid var(--border-subtle);
+}
+[data-theme="dark"] .nav { background: rgba(28, 28, 30, 0.88); }
+```
+
+**Hero — staggered entrance animation:**
+```css
+@keyframes fadeSlideUp {
+  from { opacity: 0; transform: translateY(10px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.home-hero h1    { animation: fadeSlideUp 0.45s ease both; }
+.home-desc       { animation: fadeSlideUp 0.45s 0.07s ease both; }
+.home-links      { animation: fadeSlideUp 0.45s 0.14s ease both; }
+.home-metrics    { animation: fadeSlideUp 0.45s 0.21s ease both; }
+```
+
+**CTA buttons — Apple HIG-style:**
+- Primary: `background: var(--accent)` filled with `box-shadow: 0 1px 4px rgba(0,122,255,0.28)`; hover lifts with `translateY(-1px)` and stronger shadow
+- Secondary: outlined with `border: 1px solid var(--border)`, hover fills `--bg-secondary`
+
+**Sidebar active state — iOS selected cell:**
+```css
+.sidebar-link.active::before {
+  content: '';
+  position: absolute;
+  left: 0; top: 20%; height: 60%;
+  width: 2.5px;
+  background: var(--accent);
+  border-radius: 0 2px 2px 0;
+}
+```
+
+**Other interactions (all `0.15s ease`):**
+- All `a` tags: `transition: color`
+- Nav brand: `opacity` fade on hover
+- Dark toggle: `color + border-color + background`
+- Table rows: `background` on `tbody tr:hover`
+- Docs list items: `translateY(-1px) + shadow-md + border-color` on hover
+- Mobile sidebar: `slideDown` keyframe entrance + close-on-outside-click
+- TOC links: `color` transition + `.toc-active` class set by JS
+
+**Mobile sidebar** adds `animation: slideDown 0.2s ease` on `.sidebar.open`.
+
+**Quick Start steps** — card-style via:
+```css
+.home-section ol {
+  list-style: none; padding-left: 0;
+  display: flex; flex-direction: column; gap: 0.6rem;
+}
+.home-section ol > li {
+  padding: 0.85rem 1rem;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+}
+```
+
+**`prefers-reduced-motion`** — disables all animations/transitions for accessibility.
+
+### `website/layouts/index.html`
+
+Added `.home-metrics` section between CTA links and terminal code block:
+```html
+<div class="home-metrics">
+  <span class="metric-badge"><span class="badge-dot badge-dot-heart"></span>Heart Rate</span>
+  <span class="metric-badge"><span class="badge-dot badge-dot-steps"></span>Steps</span>
+  <span class="metric-badge"><span class="badge-dot badge-dot-sleep"></span>Sleep</span>
+  <span class="metric-badge"><span class="badge-dot badge-dot-spo2"></span>Blood Oxygen</span>
+  <span class="metric-badge"><span class="badge-dot badge-dot-vo2"></span>VO2 Max</span>
+  <span class="metric-badge"><span class="badge-dot badge-dot-workout"></span>Workouts</span>
+</div>
+```
+
+Badges use iOS Health metric colors: `#FF375F` heart, `#30D158` steps, `#636EFF` sleep, `#5AC8FA` SpO2, `#FF9F0A` VO2, `#FF6B35` workouts.
+
+### `website/static/js/main.js`
+
+- **Mobile sidebar**: Added `document.addEventListener("click", ...)` to close sidebar when tapping outside it or the hamburger button.
+- **TOC IntersectionObserver**: Highlights the active TOC link as user scrolls:
+```js
+var observer = new IntersectionObserver(fn, {
+  rootMargin: "-8% 0px -75% 0px", threshold: 0
+});
+```
+Uses `rootMargin` trick: heading must be in the top ~17% of the viewport to be "active". Sets `.toc-active` class on the corresponding `<a>` tag.
+
+## Key Insights
+
+### `backdrop-filter` needs explicit dark-mode override
+The nav `background: rgba(255,255,255,0.82)` is hardcoded (not `var(--bg)`) because CSS variables can't decompose to `rgba` components. Dark mode requires a separate `[data-theme="dark"] .nav { background: rgba(28,28,30,0.88) }` rule. This is the same pattern iOS itself uses — bg color + blur, not transparency alone.
+
+### Quick Start `ol` card styling doesn't affect docs `ol`
+The `.home-section ol` selector is scoped to the homepage only (docs pages don't have `.home-section` ancestors), so stripping `list-style` and adding `display: flex` doesn't leak into docs content.
+
+### Hugo not available in the deployment environment
+`hugo` binary was not installed in the session environment (not on PATH, not findable). Validated:
+- CSS brace balance via Python (`128 opens == 128 closes`)
+- HTML div balance via Python
+- JS syntax via `node --check`
+Build validation depends on CI (GitHub Actions → Cloudflare Pages).
+
+### IntersectionObserver `rootMargin` for TOC is tricky
+`rootMargin: "-8% 0px -75% 0px"` means the "active zone" is from 8% from top to 25% from top of viewport. When a heading scrolls into that narrow band, it becomes active. This gives a natural feel where the TOC highlights slightly ahead of the heading reaching the very top.
+
+## Decisions Made
+
+- **Apple blue (`#007AFF`) over GitHub blue (`#0969da`)** — the project is health-data tooling inspired by iOS Health; Apple blue is more on-brand and warmer. The exact dark-mode variant `#0A84FF` is from Apple's HIG.
+- **`fadeSlideUp` not `fadeIn`** — the 10px vertical movement makes the entrance feel physical and intentional, not a flat opacity pop. 0.45s is the sweet spot: fast enough to not feel slow, long enough to read as intentional.
+- **Metric badge color dots, not icons** — icons would require SVG assets or an icon font. Tiny colored dots (7px circles) convey the same category identity as iOS Health's chart colors with zero added complexity.
+- **No scroll-triggered animations beyond hero** — section headings and content boxes do NOT animate in on scroll. Only the hero (above the fold) gets the entrance animation. Scroll animations on content risk looking like a SaaS landing page.
+- **`prefers-reduced-motion`** — zero-cost accessibility improvement, collapses all `animation-duration` and `transition-duration` to `0.01ms`. Important for users with vestibular disorders.
+
+---