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

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.