@justin_evo/evo-ui 1.2.0 → 1.2.1

package/src/css/topnav.module.scss

@@ -1,568 +1,568 @@
-@use 'base/variables' as *;
-@use 'base/color' as *;
-
-// ---------------------------------------------------------------------------
-// Animations (token-aligned with modal.module.scss — see CLAUDE.md §0.2)
-// ---------------------------------------------------------------------------
-
-@keyframes topNavOverlayFadeIn {
-  from { opacity: 0; }
-  to   { opacity: 1; }
-}
-
-@keyframes topNavDrawerSlideIn {
-  from { transform: translateX(100%); }
-  to   { transform: translateX(0); }
-}
-
-@keyframes topNavDropdownFadeIn {
-  from { opacity: 0; transform: translateY(-4px); }
-  to   { opacity: 1; transform: translateY(0); }
-}
-
-@keyframes topNavRise {
-  from { opacity: 0; transform: translateY(0.5rem); }
-  to   { opacity: 1; transform: translateY(0); }
-}
-
-@keyframes topNavFade {
-  from { opacity: 0; }
-  to   { opacity: 1; }
-}
-
-// ---------------------------------------------------------------------------
-// Root
-// ---------------------------------------------------------------------------
-
-.topNav {
-  position: relative;
-  width: 100%;
-  font-family: $font-sans;
-  background-color: $color-surface;
-  border-bottom: 1px solid $color-border;
-}
-
-.topNavInner {
-  display: flex;
-  align-items: center;
-  gap: 1.5rem;
-  padding: 0 1rem;
-  min-height: 3.25rem;
-}
-
-// ---------------------------------------------------------------------------
-// Brand
-// ---------------------------------------------------------------------------
-
-.topNavBrand {
-  display: flex;
-  align-items: center;
-  flex-shrink: 0;
-  font-size: $text-base;
-  font-weight: 600;
-  color: $color-text-primary;
-}
-
-// ---------------------------------------------------------------------------
-// Menu — horizontal on desktop
-// ---------------------------------------------------------------------------
-
-.topNavMenu {
-  display: flex;
-  align-items: center;
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  gap: 0.125rem;
-  flex: 1;
-  min-width: 0;
-}
-
-.topNavItemRow {
-  display: flex;
-  align-items: stretch;
-}
-
-// ---------------------------------------------------------------------------
-// Menu — horizontal-scroll fallback (only when collapsed AND no Toggle present)
-// ---------------------------------------------------------------------------
-
-.topNavMenuScroll {
-  overflow-x: auto;
-  flex-wrap: nowrap;
-  -webkit-overflow-scrolling: touch;
-  scrollbar-width: none;
-
-  &::-webkit-scrollbar { display: none; }
-
-  > li { flex-shrink: 0; }
-}
-
-// ---------------------------------------------------------------------------
-// Item / Dropdown trigger (shared visual class)
-// ---------------------------------------------------------------------------
-
-.topNavItem {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.4375rem 0.75rem;
-  min-height: 2rem;
-  font-size: $text-sm;
-  font-weight: 500;
-  color: $color-text-secondary;
-  background: transparent;
-  border: none;
-  border-radius: $radius-sm;
-  cursor: pointer;
-  white-space: nowrap;
-  text-decoration: none;
-  transition:
-    background-color $transition-fast,
-    color $transition-fast;
-  font-family: inherit;
-
-  &:hover {
-    background-color: $color-surface-hover;
-    color: $color-text-primary;
-  }
-
-  &:focus-visible {
-    outline: 2px solid $evo-primary-focus;
-    outline-offset: 2px;
-  }
-}
-
-.topNavItemActive {
-  background-color: color-mix(in srgb, $evo-primary-color 12%, transparent);
-  color: $evo-primary-color;
-
-  &:hover {
-    background-color: color-mix(in srgb, $evo-primary-color 18%, transparent);
-    color: $evo-primary-color;
-  }
-}
-
-.topNavItemLabel {
-  display: inline-block;
-}
-
-.topNavIcon {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
-  width: 1.125rem;
-  height: 1.125rem;
-  font-size: 1rem;
-}
-
-// ---------------------------------------------------------------------------
-// Actions slot
-// ---------------------------------------------------------------------------
-
-.topNavActions {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  margin-left: auto;
-  flex-shrink: 0;
-}
-
-// ---------------------------------------------------------------------------
-// Search trigger (EvoTopNav.Search) — presentational ⌘K affordance
-// ---------------------------------------------------------------------------
-
-.topNavSearch {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.5rem;
-  height: 2rem;
-  min-width: 12rem;
-  padding: 0 0.625rem;
-  font-family: inherit;
-  font-size: $text-sm;
-  color: $color-text-muted;
-  background-color: $color-surface-sunken;
-  border: 1px solid $color-border;
-  border-radius: $radius-sm;
-  cursor: pointer;
-  transition:
-    background-color $transition-fast,
-    border-color $transition-fast,
-    color $transition-fast;
-
-  &:hover {
-    background-color: $color-surface-hover;
-    color: $color-text-secondary;
-  }
-
-  &:focus-visible {
-    outline: 2px solid $evo-primary-focus;
-    outline-offset: 2px;
-  }
-}
-
-.topNavSearchIcon {
-  display: inline-flex;
-  flex-shrink: 0;
-}
-
-.topNavSearchText {
-  flex: 1;
-  text-align: left;
-}
-
-.topNavSearchKbd {
-  flex-shrink: 0;
-  font-family: inherit;
-  font-size: $text-xs;
-  color: $color-text-muted;
-  background-color: $color-surface;
-  border: 1px solid $color-border;
-  border-radius: 4px;
-  padding: 0.0625rem 0.3125rem;
-}
-
-// ---------------------------------------------------------------------------
-// Toggle (hamburger) — hidden above the collapse breakpoint
-// ---------------------------------------------------------------------------
-
-.topNavToggle {
-  display: none;
-  align-items: center;
-  justify-content: center;
-  width: 2.75rem;
-  height: 2.75rem;
-  min-width: 2.75rem;
-  min-height: 2.75rem;
-  margin-left: 0.25rem;
-  background: transparent;
-  border: none;
-  border-radius: $radius-sm;
-  color: $color-text-primary;
-  cursor: pointer;
-  transition: background-color $transition-fast;
-
-  &:hover {
-    background-color: $color-surface-hover;
-  }
-
-  &:focus-visible {
-    outline: 2px solid $evo-primary-focus;
-    outline-offset: 2px;
-  }
-}
-
-.toggleIcon {
-  display: block;
-}
-
-// ---------------------------------------------------------------------------
-// Dropdown
-// ---------------------------------------------------------------------------
-
-.topNavDropdown {
-  position: relative;
-  display: flex;
-  align-items: stretch;
-}
-
-.topNavDropdownTrigger {
-  // inherits .topNavItem styles
-}
-
-.topNavDropdownChevron {
-  transition: transform $transition-fast;
-  margin-left: 0.125rem;
-  opacity: 0.7;
-}
-
-.topNavDropdownChevronOpen {
-  transform: rotate(180deg);
-}
-
-.topNavDropdownContent {
-  position: absolute;
-  top: calc(100% + 0.375rem);
-  left: 0;
-  min-width: 12rem;
-  list-style: none;
-  margin: 0;
-  padding: 0.375rem;
-  background-color: $color-surface-elevated;
-  border: 1px solid $color-border;
-  border-radius: $radius-md;
-  box-shadow: $shadow-lg;
-  z-index: 50;
-  // Hidden by default — the .topNavDropdownContentOpen modifier flips display
-  // to flex. Using display:none here keeps focus + tab order behaviour correct
-  // and avoids the [hidden] / display:flex specificity conflict that left the
-  // empty panel visible.
-  display: none;
-  flex-direction: column;
-  gap: 0.125rem;
-
-  > li {
-    margin: 0;
-    padding: 0;
-    list-style: none;
-  }
-}
-
-.topNavDropdownContentOpen {
-  display: flex;
-  animation: topNavDropdownFadeIn 140ms ease;
-}
-
-.topNavDropdownItem {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  width: 100%;
-  padding: 0.5rem 0.625rem;
-  min-height: 2rem;
-  font-size: $text-sm;
-  font-weight: 500;
-  color: $color-text-secondary;
-  background: transparent;
-  border: none;
-  border-radius: $radius-sm;
-  cursor: pointer;
-  white-space: nowrap;
-  text-align: left;
-  text-decoration: none;
-  transition: background-color $transition-fast, color $transition-fast;
-  font-family: inherit;
-
-  &:hover,
-  &:focus-visible {
-    background-color: $color-surface-hover;
-    color: $color-text-primary;
-  }
-
-  &:focus-visible {
-    outline: 2px solid $evo-primary-focus;
-    outline-offset: 2px;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Mobile drawer (≤ collapseBelow breakpoint)
-// ---------------------------------------------------------------------------
-
-@media (max-width: 767px) {
-  .topNavInner {
-    gap: 0.75rem;
-  }
-
-  .topNavToggle {
-    display: inline-flex;
-  }
-
-  // Menu becomes the drawer panel (only when a Toggle is registered —
-  // see .topNavMenuScroll for the no-Toggle fallback handled above).
-  .topNavMenuDrawer {
-    position: fixed;
-    top: 0;
-    right: 0;
-    bottom: 0;
-    width: min(20rem, 88vw);
-    flex-direction: column;
-    align-items: stretch;
-    gap: 0.25rem;
-    padding: 4rem 1rem 1.5rem;
-    background-color: $color-surface-elevated;
-    border-left: 1px solid $color-border;
-    box-shadow: $shadow-2xl;
-    overflow-y: auto;
-    z-index: 60;
-    animation: topNavDrawerSlideIn 220ms ease;
-
-    // Items in the drawer take the full row and become taller for touch.
-    .topNavItem,
-    .topNavDropdownTrigger {
-      width: 100%;
-      justify-content: flex-start;
-      min-height: 2.75rem;
-      padding: 0.625rem 0.75rem;
-      font-size: $text-base;
-    }
-  }
-
-  // Drawer closed → keep it mounted (state preserved) but visually hidden
-  // and removed from the a11y tree.
-  .topNavMenuDrawerClosed {
-    transform: translateX(100%);
-    pointer-events: none;
-    animation: none;
-    visibility: hidden;
-  }
-
-  // Dropdowns inside the drawer flatten to an inline expandable section
-  // (no floating panel — would clip on mobile).
-  .topNavDropdownInDrawer {
-    flex-direction: column;
-    align-items: stretch;
-
-    .topNavDropdownContent {
-      position: static;
-      box-shadow: none;
-      border: none;
-      background: transparent;
-      padding: 0.125rem 0 0.125rem 1rem;
-      min-width: 0;
-      animation: none;
-    }
-  }
-
-  .topNavBackdrop {
-    position: fixed;
-    inset: 0;
-    background-color: $color-backdrop;
-    -webkit-backdrop-filter: blur(2px);
-    backdrop-filter: blur(2px);
-    z-index: 55;
-    animation: topNavOverlayFadeIn 180ms ease;
-  }
-
-  .topNavSearch {
-    min-width: 0;
-    width: 2.75rem;
-    height: 2.75rem;
-    justify-content: center;
-    padding: 0;
-
-    .topNavSearchText,
-    .topNavSearchKbd { display: none; }
-  }
-}
-
-// Above the breakpoint, drawer-specific bits never render visually.
-@media (min-width: 768px) {
-  .topNavMenuDrawer,
-  .topNavMenuDrawerClosed,
-  .topNavBackdrop {
-    // no-op: structural classes shouldn't leak desktop styles
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Entrance animation (opt-in via `entrance` prop → data-entrance attribute)
-// ---------------------------------------------------------------------------
-
-.topNav[data-entrance='rise'] .topNavBrand,
-.topNav[data-entrance='rise'] .topNavMenu > li,
-.topNav[data-entrance='rise'] .topNavSearch,
-.topNav[data-entrance='rise'] .topNavActions {
-  animation: topNavRise 440ms cubic-bezier(0.22, 1, 0.36, 1) both;
-}
-
-.topNav[data-entrance='fade'] .topNavBrand,
-.topNav[data-entrance='fade'] .topNavMenu > li,
-.topNav[data-entrance='fade'] .topNavSearch,
-.topNav[data-entrance='fade'] .topNavActions {
-  animation: topNavFade 440ms ease both;
-}
-
-// Shared left-to-right stagger (applies to both variants).
-.topNav[data-entrance] .topNavBrand { animation-delay: 40ms; }
-.topNav[data-entrance] .topNavMenu > li:nth-child(1) { animation-delay: 110ms; }
-.topNav[data-entrance] .topNavMenu > li:nth-child(2) { animation-delay: 160ms; }
-.topNav[data-entrance] .topNavMenu > li:nth-child(3) { animation-delay: 210ms; }
-.topNav[data-entrance] .topNavMenu > li:nth-child(4) { animation-delay: 260ms; }
-.topNav[data-entrance] .topNavMenu > li:nth-child(n + 5) { animation-delay: 300ms; }
-.topNav[data-entrance] .topNavSearch { animation-delay: 320ms; }
-.topNav[data-entrance] .topNavActions { animation-delay: 360ms; }
-
-// ---------------------------------------------------------------------------
-// Sticky + scroll-aware behavior (opt-in via `sticky` / `scrollBehavior`)
-// ---------------------------------------------------------------------------
-
-.topNavSticky {
-  position: sticky;
-  top: 0;
-  z-index: 30;
-}
-
-.topNav[data-scroll] {
-  transition:
-    background-color $transition-fast,
-    box-shadow $transition-fast,
-    transform 220ms ease;
-
-  .topNavInner { transition: min-height $transition-fast; }
-}
-
-.topNav[data-scrolled] {
-  background-color: $color-surface; // fallback for browsers without color-mix()
-  background-color: color-mix(in srgb, $color-surface 85%, transparent);
-  -webkit-backdrop-filter: blur(10px);
-  backdrop-filter: blur(10px);
-  box-shadow: $shadow-md;
-}
-
-.topNav[data-scroll='shrink'][data-scrolled] .topNavInner {
-  min-height: 2.75rem;
-}
-
-.topNav[data-scroll='hide'] { will-change: transform; }
-.topNav[data-scroll='hide'][data-hidden] { transform: translateY(-100%); }
-
-// ---------------------------------------------------------------------------
-// Scroll-progress line (opt-in via `showProgress`)
-// ---------------------------------------------------------------------------
-
-.topNavProgress {
-  position: absolute;
-  left: 0;
-  bottom: 0;
-  width: 100%;
-  height: 2px;
-  background: $evo-primary-color;
-  transform: scaleX(var(--evo-topnav-progress, 0));
-  transform-origin: left center;
-  pointer-events: none;
-  z-index: 31;
-}
-
-// ---------------------------------------------------------------------------
-// Reduced motion — kill animations
-// ---------------------------------------------------------------------------
-
-.topNavReducedMotion {
-  .topNavMenuDrawer,
-  .topNavDropdownContentOpen,
-  .topNavBackdrop {
-    animation: none;
-  }
-
-  .topNavDropdownChevron {
-    transition: none;
-  }
-
-  .topNavBrand,
-  .topNavMenu > li,
-  .topNavSearch,
-  .topNavActions {
-    animation: none !important;
-  }
-
-  &[data-scroll='hide'][data-hidden] { transition: none; }
-  .topNavProgress { transition: none; }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .topNavMenuDrawer,
-  .topNavDropdownContentOpen,
-  .topNavBackdrop {
-    animation: none;
-  }
-
-  .topNav[data-entrance] .topNavBrand,
-  .topNav[data-entrance] .topNavMenu > li,
-  .topNav[data-entrance] .topNavSearch,
-  .topNav[data-entrance] .topNavActions {
-    animation: none !important;
-  }
-}
+@use 'base/variables' as *;
+@use 'base/color' as *;
+
+// ---------------------------------------------------------------------------
+// Animations (token-aligned with modal.module.scss — see CLAUDE.md §0.2)
+// ---------------------------------------------------------------------------
+
+@keyframes topNavOverlayFadeIn {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+@keyframes topNavDrawerSlideIn {
+  from { transform: translateX(100%); }
+  to   { transform: translateX(0); }
+}
+
+@keyframes topNavDropdownFadeIn {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes topNavRise {
+  from { opacity: 0; transform: translateY(0.5rem); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes topNavFade {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+// ---------------------------------------------------------------------------
+// Root
+// ---------------------------------------------------------------------------
+
+.topNav {
+  position: relative;
+  width: 100%;
+  font-family: $font-sans;
+  background-color: $color-surface;
+  border-bottom: 1px solid $color-border;
+}
+
+.topNavInner {
+  display: flex;
+  align-items: center;
+  gap: 1.5rem;
+  padding: 0 1rem;
+  min-height: 3.25rem;
+}
+
+// ---------------------------------------------------------------------------
+// Brand
+// ---------------------------------------------------------------------------
+
+.topNavBrand {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  font-size: $text-base;
+  font-weight: 600;
+  color: $color-text-primary;
+}
+
+// ---------------------------------------------------------------------------
+// Menu — horizontal on desktop
+// ---------------------------------------------------------------------------
+
+.topNavMenu {
+  display: flex;
+  align-items: center;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  gap: 0.125rem;
+  flex: 1;
+  min-width: 0;
+}
+
+.topNavItemRow {
+  display: flex;
+  align-items: stretch;
+}
+
+// ---------------------------------------------------------------------------
+// Menu — horizontal-scroll fallback (only when collapsed AND no Toggle present)
+// ---------------------------------------------------------------------------
+
+.topNavMenuScroll {
+  overflow-x: auto;
+  flex-wrap: nowrap;
+  -webkit-overflow-scrolling: touch;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar { display: none; }
+
+  > li { flex-shrink: 0; }
+}
+
+// ---------------------------------------------------------------------------
+// Item / Dropdown trigger (shared visual class)
+// ---------------------------------------------------------------------------
+
+.topNavItem {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.4375rem 0.75rem;
+  min-height: 2rem;
+  font-size: $text-sm;
+  font-weight: 500;
+  color: $color-text-secondary;
+  background: transparent;
+  border: none;
+  border-radius: $radius-sm;
+  cursor: pointer;
+  white-space: nowrap;
+  text-decoration: none;
+  transition:
+    background-color $transition-fast,
+    color $transition-fast;
+  font-family: inherit;
+
+  &:hover {
+    background-color: $color-surface-hover;
+    color: $color-text-primary;
+  }
+
+  &:focus-visible {
+    outline: 2px solid $evo-primary-focus;
+    outline-offset: 2px;
+  }
+}
+
+.topNavItemActive {
+  background-color: color-mix(in srgb, $evo-primary-color 12%, transparent);
+  color: $evo-primary-color;
+
+  &:hover {
+    background-color: color-mix(in srgb, $evo-primary-color 18%, transparent);
+    color: $evo-primary-color;
+  }
+}
+
+.topNavItemLabel {
+  display: inline-block;
+}
+
+.topNavIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.125rem;
+  height: 1.125rem;
+  font-size: 1rem;
+}
+
+// ---------------------------------------------------------------------------
+// Actions slot
+// ---------------------------------------------------------------------------
+
+.topNavActions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-left: auto;
+  flex-shrink: 0;
+}
+
+// ---------------------------------------------------------------------------
+// Search trigger (EvoTopNav.Search) — presentational ⌘K affordance
+// ---------------------------------------------------------------------------
+
+.topNavSearch {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  height: 2rem;
+  min-width: 12rem;
+  padding: 0 0.625rem;
+  font-family: inherit;
+  font-size: $text-sm;
+  color: $color-text-muted;
+  background-color: $color-surface-sunken;
+  border: 1px solid $color-border;
+  border-radius: $radius-sm;
+  cursor: pointer;
+  transition:
+    background-color $transition-fast,
+    border-color $transition-fast,
+    color $transition-fast;
+
+  &:hover {
+    background-color: $color-surface-hover;
+    color: $color-text-secondary;
+  }
+
+  &:focus-visible {
+    outline: 2px solid $evo-primary-focus;
+    outline-offset: 2px;
+  }
+}
+
+.topNavSearchIcon {
+  display: inline-flex;
+  flex-shrink: 0;
+}
+
+.topNavSearchText {
+  flex: 1;
+  text-align: left;
+}
+
+.topNavSearchKbd {
+  flex-shrink: 0;
+  font-family: inherit;
+  font-size: $text-xs;
+  color: $color-text-muted;
+  background-color: $color-surface;
+  border: 1px solid $color-border;
+  border-radius: 4px;
+  padding: 0.0625rem 0.3125rem;
+}
+
+// ---------------------------------------------------------------------------
+// Toggle (hamburger) — hidden above the collapse breakpoint
+// ---------------------------------------------------------------------------
+
+.topNavToggle {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: 2.75rem;
+  height: 2.75rem;
+  min-width: 2.75rem;
+  min-height: 2.75rem;
+  margin-left: 0.25rem;
+  background: transparent;
+  border: none;
+  border-radius: $radius-sm;
+  color: $color-text-primary;
+  cursor: pointer;
+  transition: background-color $transition-fast;
+
+  &:hover {
+    background-color: $color-surface-hover;
+  }
+
+  &:focus-visible {
+    outline: 2px solid $evo-primary-focus;
+    outline-offset: 2px;
+  }
+}
+
+.toggleIcon {
+  display: block;
+}
+
+// ---------------------------------------------------------------------------
+// Dropdown
+// ---------------------------------------------------------------------------
+
+.topNavDropdown {
+  position: relative;
+  display: flex;
+  align-items: stretch;
+}
+
+.topNavDropdownTrigger {
+  // inherits .topNavItem styles
+}
+
+.topNavDropdownChevron {
+  transition: transform $transition-fast;
+  margin-left: 0.125rem;
+  opacity: 0.7;
+}
+
+.topNavDropdownChevronOpen {
+  transform: rotate(180deg);
+}
+
+.topNavDropdownContent {
+  position: absolute;
+  top: calc(100% + 0.375rem);
+  left: 0;
+  min-width: 12rem;
+  list-style: none;
+  margin: 0;
+  padding: 0.375rem;
+  background-color: $color-surface-elevated;
+  border: 1px solid $color-border;
+  border-radius: $radius-md;
+  box-shadow: $shadow-lg;
+  z-index: 50;
+  // Hidden by default — the .topNavDropdownContentOpen modifier flips display
+  // to flex. Using display:none here keeps focus + tab order behaviour correct
+  // and avoids the [hidden] / display:flex specificity conflict that left the
+  // empty panel visible.
+  display: none;
+  flex-direction: column;
+  gap: 0.125rem;
+
+  > li {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+}
+
+.topNavDropdownContentOpen {
+  display: flex;
+  animation: topNavDropdownFadeIn 140ms ease;
+}
+
+.topNavDropdownItem {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  padding: 0.5rem 0.625rem;
+  min-height: 2rem;
+  font-size: $text-sm;
+  font-weight: 500;
+  color: $color-text-secondary;
+  background: transparent;
+  border: none;
+  border-radius: $radius-sm;
+  cursor: pointer;
+  white-space: nowrap;
+  text-align: left;
+  text-decoration: none;
+  transition: background-color $transition-fast, color $transition-fast;
+  font-family: inherit;
+
+  &:hover,
+  &:focus-visible {
+    background-color: $color-surface-hover;
+    color: $color-text-primary;
+  }
+
+  &:focus-visible {
+    outline: 2px solid $evo-primary-focus;
+    outline-offset: 2px;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mobile drawer (≤ collapseBelow breakpoint)
+// ---------------------------------------------------------------------------
+
+@media (max-width: 767px) {
+  .topNavInner {
+    gap: 0.75rem;
+  }
+
+  .topNavToggle {
+    display: inline-flex;
+  }
+
+  // Menu becomes the drawer panel (only when a Toggle is registered —
+  // see .topNavMenuScroll for the no-Toggle fallback handled above).
+  .topNavMenuDrawer {
+    position: fixed;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    width: min(20rem, 88vw);
+    flex-direction: column;
+    align-items: stretch;
+    gap: 0.25rem;
+    padding: 4rem 1rem 1.5rem;
+    background-color: $color-surface-elevated;
+    border-left: 1px solid $color-border;
+    box-shadow: $shadow-2xl;
+    overflow-y: auto;
+    z-index: 60;
+    animation: topNavDrawerSlideIn 220ms ease;
+
+    // Items in the drawer take the full row and become taller for touch.
+    .topNavItem,
+    .topNavDropdownTrigger {
+      width: 100%;
+      justify-content: flex-start;
+      min-height: 2.75rem;
+      padding: 0.625rem 0.75rem;
+      font-size: $text-base;
+    }
+  }
+
+  // Drawer closed → keep it mounted (state preserved) but visually hidden
+  // and removed from the a11y tree.
+  .topNavMenuDrawerClosed {
+    transform: translateX(100%);
+    pointer-events: none;
+    animation: none;
+    visibility: hidden;
+  }
+
+  // Dropdowns inside the drawer flatten to an inline expandable section
+  // (no floating panel — would clip on mobile).
+  .topNavDropdownInDrawer {
+    flex-direction: column;
+    align-items: stretch;
+
+    .topNavDropdownContent {
+      position: static;
+      box-shadow: none;
+      border: none;
+      background: transparent;
+      padding: 0.125rem 0 0.125rem 1rem;
+      min-width: 0;
+      animation: none;
+    }
+  }
+
+  .topNavBackdrop {
+    position: fixed;
+    inset: 0;
+    background-color: $color-backdrop;
+    -webkit-backdrop-filter: blur(2px);
+    backdrop-filter: blur(2px);
+    z-index: 55;
+    animation: topNavOverlayFadeIn 180ms ease;
+  }
+
+  .topNavSearch {
+    min-width: 0;
+    width: 2.75rem;
+    height: 2.75rem;
+    justify-content: center;
+    padding: 0;
+
+    .topNavSearchText,
+    .topNavSearchKbd { display: none; }
+  }
+}
+
+// Above the breakpoint, drawer-specific bits never render visually.
+@media (min-width: 768px) {
+  .topNavMenuDrawer,
+  .topNavMenuDrawerClosed,
+  .topNavBackdrop {
+    // no-op: structural classes shouldn't leak desktop styles
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entrance animation (opt-in via `entrance` prop → data-entrance attribute)
+// ---------------------------------------------------------------------------
+
+.topNav[data-entrance='rise'] .topNavBrand,
+.topNav[data-entrance='rise'] .topNavMenu > li,
+.topNav[data-entrance='rise'] .topNavSearch,
+.topNav[data-entrance='rise'] .topNavActions {
+  animation: topNavRise 440ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+.topNav[data-entrance='fade'] .topNavBrand,
+.topNav[data-entrance='fade'] .topNavMenu > li,
+.topNav[data-entrance='fade'] .topNavSearch,
+.topNav[data-entrance='fade'] .topNavActions {
+  animation: topNavFade 440ms ease both;
+}
+
+// Shared left-to-right stagger (applies to both variants).
+.topNav[data-entrance] .topNavBrand { animation-delay: 40ms; }
+.topNav[data-entrance] .topNavMenu > li:nth-child(1) { animation-delay: 110ms; }
+.topNav[data-entrance] .topNavMenu > li:nth-child(2) { animation-delay: 160ms; }
+.topNav[data-entrance] .topNavMenu > li:nth-child(3) { animation-delay: 210ms; }
+.topNav[data-entrance] .topNavMenu > li:nth-child(4) { animation-delay: 260ms; }
+.topNav[data-entrance] .topNavMenu > li:nth-child(n + 5) { animation-delay: 300ms; }
+.topNav[data-entrance] .topNavSearch { animation-delay: 320ms; }
+.topNav[data-entrance] .topNavActions { animation-delay: 360ms; }
+
+// ---------------------------------------------------------------------------
+// Sticky + scroll-aware behavior (opt-in via `sticky` / `scrollBehavior`)
+// ---------------------------------------------------------------------------
+
+.topNavSticky {
+  position: sticky;
+  top: 0;
+  z-index: 30;
+}
+
+.topNav[data-scroll] {
+  transition:
+    background-color $transition-fast,
+    box-shadow $transition-fast,
+    transform 220ms ease;
+
+  .topNavInner { transition: min-height $transition-fast; }
+}
+
+.topNav[data-scrolled] {
+  background-color: $color-surface; // fallback for browsers without color-mix()
+  background-color: color-mix(in srgb, $color-surface 85%, transparent);
+  -webkit-backdrop-filter: blur(10px);
+  backdrop-filter: blur(10px);
+  box-shadow: $shadow-md;
+}
+
+.topNav[data-scroll='shrink'][data-scrolled] .topNavInner {
+  min-height: 2.75rem;
+}
+
+.topNav[data-scroll='hide'] { will-change: transform; }
+.topNav[data-scroll='hide'][data-hidden] { transform: translateY(-100%); }
+
+// ---------------------------------------------------------------------------
+// Scroll-progress line (opt-in via `showProgress`)
+// ---------------------------------------------------------------------------
+
+.topNavProgress {
+  position: absolute;
+  left: 0;
+  bottom: 0;
+  width: 100%;
+  height: 2px;
+  background: $evo-primary-color;
+  transform: scaleX(var(--evo-topnav-progress, 0));
+  transform-origin: left center;
+  pointer-events: none;
+  z-index: 31;
+}
+
+// ---------------------------------------------------------------------------
+// Reduced motion — kill animations
+// ---------------------------------------------------------------------------
+
+.topNavReducedMotion {
+  .topNavMenuDrawer,
+  .topNavDropdownContentOpen,
+  .topNavBackdrop {
+    animation: none;
+  }
+
+  .topNavDropdownChevron {
+    transition: none;
+  }
+
+  .topNavBrand,
+  .topNavMenu > li,
+  .topNavSearch,
+  .topNavActions {
+    animation: none !important;
+  }
+
+  &[data-scroll='hide'][data-hidden] { transition: none; }
+  .topNavProgress { transition: none; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .topNavMenuDrawer,
+  .topNavDropdownContentOpen,
+  .topNavBackdrop {
+    animation: none;
+  }
+
+  .topNav[data-entrance] .topNavBrand,
+  .topNav[data-entrance] .topNavMenu > li,
+  .topNav[data-entrance] .topNavSearch,
+  .topNav[data-entrance] .topNavActions {
+    animation: none !important;
+  }
+}