UI touch ups

openspec/changes/archive/2026-02-11-final-touches/design.md

@@ -0,0 +1,82 @@
+## Context
+
+The primary header navigation is currently laid out as a simple left brand + right nav flex row. This makes the header feel left-heavy and de-emphasizes the brand. The site already uses a cohesive visual system (tokenized colors, glow accents, motion preferences) and has existing accessibility constraints (focus-visible, reduced motion).
+
+Relevant implementation notes:
+
+- Header markup is in `site/src/layouts/BaseLayout.astro`.
+- Styling is in `site/src/styles/global.css`.
+- Public feature flags are expressed via `PUBLIC_*` env vars and commonly use an opt-out string comparison (`!== "false"`) similar to `PUBLIC_ENABLE_SW`.
+
+This change is purely UI-level: layout and hover presentation. No routing, data, or backend behavior changes are required.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add a left-side logo in the header using the same asset as the favicon, sized appropriately and aligned with the header rhythm.
+- Center the site brand label ("SanthoshJ") in the primary header layout without breaking the mobile hamburger behavior.
+- Introduce a novel animated hover-line treatment that appears only on hover:
+  - primary header title links (brand + Videos, Podcast, Blog)
+  - section/module titles for Videos, Podcast, Blog (titles only)
+- Gate the hover-line treatment behind a public env flag so it can be turned off to preserve the current behavior.
+- Preserve accessibility:
+  - no layout shift due to hover effects
+  - keyboard focus remains visible and not confused with hover-only affordances
+  - reduced motion mode substantially reduces/disables the animation
+
+**Non-Goals:**
+
+- Redesigning the overall header/nav visual language beyond layout + hover line.
+- Changing navigation destinations, labels, or analytics tracking attributes.
+- Introducing new font families or major typography changes.
+- Adding new build dependencies.
+
+## Decisions
+
+### 1) Header layout strategy: CSS Grid for centering
+
+Decision: implement the header container as a 3-column grid (`left / center / right`) and place:
+
+- left: logo link
+- center: brand text link
+- right: nav links (desktop) and hamburger toggle (mobile)
+
+Rationale: grid makes true center alignment robust even when left/right columns have different widths, and avoids brittle absolute positioning.
+
+Alternative: flex with spacer elements. Rejected due to center drift as content changes.
+
+### 2) Logo asset and sizing
+
+Decision: reuse `site/public/favicon.png` as the logo source initially, styled to a fixed square size with pixel-snapped rendering.
+
+Rationale: avoids introducing new assets. If needed later, replace with a dedicated logo asset (same path/size contract).
+
+### 3) Hover-line implementation: pseudo-element with no layout impact
+
+Decision: implement the hover line using `::after` (or `background-size`) so it does not affect layout metrics.
+
+- visible only on `:hover`
+- reduced motion: animation disabled/reduced
+- focus-visible: keep existing focus ring; optionally show a static line for focus (not animated)
+
+Rationale: avoids CLS and keeps the effect decorative.
+
+### 4) Feature flag: public opt-out env var
+
+Decision: add `PUBLIC_ENABLE_NAV_HOVER_LINE` (string) and treat `"false"` as disabled; all other values (including undefined) keep current behavior.
+
+Rationale: matches existing public env patterns and ensures default behavior remains unchanged.
+
+### 5) Scope of "titles"
+
+Decision: apply the hover-line to primary header title links (center brand + Videos/Podcast/Blog nav) and to explicit title elements for the three primary content surfaces (Videos, Podcast, Blog) where they are presented as headings; avoid applying to card titles and other headings.
+
+Rationale: keeps the effect intentional and avoids visual noise.
+
+## Risks / Trade-offs
+
+- [Mobile header regressions] Grid changes could break the hamburger layout → Mitigation: keep mobile nav toggle and panel behavior unchanged; add targeted CSS at the existing breakpoint.
+- [Accessibility confusion] Hover-only affordance might be mistaken for focus indicator → Mitigation: do not remove focus-visible styles; keep hover line hover-only and optionally static on focus.
+- [Theme contrast] Line color may be low-contrast in some themes → Mitigation: use existing accent tokens and test across dark/light/high-contrast.
+- [Over-application] Accidentally applying effect to card titles → Mitigation: apply only to selectors scoped to nav links + specific page/module title classes.