srcdev-nuxt-components 9.5.7 → 9.6.1

package/app/components/03.organisms/responsive-header/CONSUMER-STYLING.md

@@ -20,25 +20,51 @@ are documented alongside it since that's where they're consumed.
 | `--responsive-header-padding-block` / `--responsive-header-padding-inline` | `0` | Root element padding. |
 | `--responsive-header-max-height` | `none` | Root element max-height. |
 | `--responsive-header-inline-size` | `100%` | Root element inline-size. |
-| `--responsive-header-sub-nav-bg` / `-border` / `-border-radius` / `-padding` | `Canvas` / `1px solid #efefef75` / `8px` / `12px` | Top-bar dropdown panel (`.main-navigation-sub-nav`). |
+| `--responsive-header-link-color-hover` | `--responsive-header-link-color` | Top-bar link/summary colour on the hovered item. Unset, an active item keeps its active colour. |
+| `--responsive-header-link-color-active` | `--responsive-header-link-color` | Top-bar link/summary colour on the active item (current route or hash). |
+| `--responsive-header-sub-nav-bg` / `-border` / `-border-radius` / `-padding` | `var(--page-bg, var(--theme-surface-subtle))` / `1px solid color-mix(in oklch, var(--theme-text) 20%, transparent)` / `8px` / `12px` | Top-bar dropdown panel (`.main-navigation-sub-nav`). |
 | `--responsive-header-sub-nav-max-inline-size` | `min(48rem, calc(100vw - 3.2rem))` | Widest the top-bar dropdown panel gets; long child names wrap inside it. |
 | `--responsive-header-sub-nav-max-block-size` | `70vh` | Tallest the top-bar dropdown panel gets before it scrolls, so a long child list stays reachable under a sticky header. |
-| `--responsive-header-overflow-btn-bg` / `-size` / `-border` / `-outline` / `-icon-color` / `-hover-outline` | `Canvas` / `20px` / `1px solid #ffffff90` / `1px solid #ffffff10` / `inherit` / `1px solid #ffffff` | Overflow burger button. |
-| `--responsive-header-overflow-nav-bg` / `-border` / `-border-radius` / `-padding-block` | `Canvas` / `1px solid #ffffff90` / `8px` / `12px` | Overflow panel container. |
+| `--responsive-header-overflow-btn-bg` / `-size` / `-border` / `-outline` / `-icon-color` / `-hover-outline` | `transparent` / `20px` / `1px solid color-mix(in oklch, var(--theme-text) 20%, transparent)` / `1px solid transparent` / `inherit` / `1px solid var(--theme-border-focus)` | Overflow burger button. |
+| `--responsive-header-overflow-nav-bg` / `-border` / `-border-radius` / `-padding-block` | `var(--page-bg, var(--theme-surface-subtle))` / `1px solid color-mix(in oklch, var(--theme-text) 20%, transparent)` / `8px` / `12px` | Overflow panel container. |
 | `--responsive-header-overflow-nav-max-block-size` | `70vh` | Tallest the overflow panel gets before it scrolls. |
-| `--overflow-nav-max-inline-size` | `calc(100vw - 3.2rem)` | Widest the overflow panel's content gets (set on `NavigationItems`); long names wrap inside it. |
+| `--responsive-nav-decorator-indicator-color` | `currentColor` | Active-item indicator bar/underline. |
+| `--responsive-nav-decorator-hovered-indicator-color` | inherits the above | Indicator colour while hovering. |
+| `--responsive-nav-decorator-hovered-bg` | `color-mix(in oklch, var(--theme-text) 8%, transparent)` | Hover highlight background behind the hovered item. |
+
+### Overflow panel content (`NavigationItems`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--overflow-nav-link-color` | `inherit` | Link/summary colour in the overflow panel. |
+| `--overflow-nav-link-color-hover` | `--overflow-nav-link-color` | Colour on the hovered item. Unset, an active item keeps its active colour. |
+| `--overflow-nav-link-color-active` | `--overflow-nav-link-color` | Colour on the active item. |
+| `--overflow-nav-link-border-color` | `color-mix(in oklch, var(--theme-text) 12%, transparent)` | Divider under each row. |
+| `--overflow-nav-sub-item-color` / `--overflow-nav-sub-item-font-size` | `inherit` / `inherit` | Child links inside a group. |
+| `--overflow-nav-decorator-indicator-color` | `currentColor` | Active-row indicator bar. |
+| `--overflow-nav-decorator-hovered-indicator-color` | inherits the above | Indicator colour while hovering. |
+| `--overflow-nav-decorator-hovered-bg` | `color-mix(in oklch, var(--theme-text) 6%, transparent)` | Hover highlight behind a row. |
+| `--overflow-nav-padding-inline` / `--overflow-nav-items-padding-block` / `--overflow-nav-items-gap` | `0.8rem` / `0.8rem` / `0px` | Row spacing. |
+| `--overflow-nav-max-inline-size` | `calc(100vw - 3.2rem)` | Widest the overflow panel's content gets; long names wrap inside it. |
+
+Private: `--_link-color` / `--_overflow-link-color` carry the per-state (hover/active) link colour
+from the item to its link and summary. Not public API.
 
 Link and dropdown text is never line-clamped: it names where the link goes. Long unbroken names
 wrap inside the dropdown and overflow panels; in the top bar, an item too wide to fit moves to the
 overflow menu.
 
+> **Changed 2026-10-07**: the defaults assumed a dark bar: `Canvas` panel and button backgrounds,
+> translucent white borders (`#ffffff90`, `#efefef75`), a white button outline/hover outline and
+> white-tint hover highlights, all near-invisible on a light header. They now come from the
+> `--theme-*` slots and `--page-bg` (see the tables). A dark header sets these tokens. Also added
+> the `-link-color-hover` / `-link-color-active` tokens (top bar and overflow panel), which
+> TabNavigation had and ResponsiveHeader lacked.
+
 > **Changed 2026-10-05**: the dropdown and overflow panels had no maximum size, so a long child
-> name or a long child list ran off-screen. They are now capped by the four tokens above.
+> name or a long child list ran off-screen. They are now capped by the max-size tokens above.
 > `--_overflow-drop-down-width`, a private token nothing ever set, is gone (`min-width: fit-content`
 > directly).
-| `--responsive-nav-decorator-indicator-color` | `currentColor` | Active-item indicator bar/underline. |
-| `--responsive-nav-decorator-hovered-indicator-color` | inherits the above | Indicator colour while hovering. |
-| `--responsive-nav-decorator-hovered-bg` | `oklch(100% 0 0 / 8%)` | Hover highlight background behind the hovered item. |
 
 ---
 
@@ -50,8 +76,9 @@ tokens on a scope class matching the one passed via `styleClassPassthrough`:
 ```css
 /* assets/styles/setup/07.components/responsive-header.css */
 .site-header-nav {
-  --responsive-header-link-color: var(--slate-00);
-  --responsive-header-bg: #efefef05;
+  --responsive-header-link-color: var(--theme-text);
+  --responsive-header-link-color-hover: var(--theme-accent);
+  --responsive-header-link-color-active: var(--theme-accent);
   --responsive-header-padding-inline: 1.2rem;
 
   /* Fixed, NOT a fluid var(--step-*) token — see the token table above. */
@@ -80,12 +107,16 @@ Set the tokens above on an element you own (a page or section class, or a class
 
 ## Notes
 
+- Same-page `#anchor` items (since 2026-10-06) render as plain `<a>` with the same classes as route
+  links (`.main-navigation-link`, `.overflow-navigation-link`, the sub-nav link classes), so every token
+  and selector here applies to them. Their `li.is-active` follows the current hash rather than the route.
+
 - Anything with async-loaded content (an `iconName` icon on a nav item, a new decorator inside
   a nav link) must reserve its own `width`/`height` in CSS — an unsized element measures at
   `0` during the initial geometry pass and then pops in afterward with nothing to detect it.
   See `.decorator-icon`/the chevron `.icon` in the component's own `<style>` block for the
   pattern (`1.35em` square, `flex-shrink: 0`).
-- `NavigationItems`' own tokens (`--overflow-nav-*`) are documented in its own skill doc since
+- `NavigationItems`' own tokens (`--overflow-nav-*`) have their own table above since
   they style the overflow-panel's *content*, distinct from `ResponsiveHeader`'s own tokens
   above which style the top bar and the overflow *button*/*container*.
 

package/app/components/03.organisms/responsive-header/NavigationItems.vue

@@ -34,7 +34,16 @@
           role="none"
           @mouseenter="hoveredItemKey = `${String(groupKey)}-${localIndex}`"
         >
-          <NuxtLink class="overflow-navigation-link" :to="link.path" role="menuitem">
+          <a
+            v-if="isAnchorPath(link.path)"
+            class="overflow-navigation-link"
+            :href="link.path"
+            role="menuitem"
+            @click="emit('anchorClick', $event, link.path)"
+          >
+            <span class="overflow-navigation-text">{{ link.name }}</span>
+          </a>
+          <NuxtLink v-else class="overflow-navigation-link" :to="link.path" role="menuitem">
             <span class="overflow-navigation-text">{{ link.name }}</span>
           </NuxtLink>
         </li>
@@ -87,7 +96,16 @@
                     }"
                     @mouseenter="hoveredChildKey = `${String(groupKey)}-${localIndex}-${childIndex}`"
                   >
-                    <NuxtLink :to="childLink.path" class="overflow-navigation-sub-nav-link" role="menuitem">
+                    <a
+                      v-if="childLink.path && isAnchorPath(childLink.path)"
+                      :href="childLink.path"
+                      class="overflow-navigation-sub-nav-link"
+                      role="menuitem"
+                      @click="emit('anchorClick', $event, childLink.path)"
+                    >
+                      <span class="overflow-navigation-sub-nav-text">{{ childLink.name }}</span>
+                    </a>
+                    <NuxtLink v-else :to="childLink.path" class="overflow-navigation-sub-nav-link" role="menuitem">
                       <span class="overflow-navigation-sub-nav-text">{{ childLink.name }}</span>
                     </NuxtLink>
                   </li>
@@ -117,6 +135,8 @@ interface Props {
   ariaLabel?: string;
   /** aria-label on each submenu summary; {title} is replaced with the item's title. */
   submenuAriaLabel?: string;
+  /** The active "#anchor" path, owned by ResponsiveHeader so both menus agree. */
+  activeHash?: string;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -128,8 +148,13 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
   ariaLabel: "Overflow navigation menu",
   submenuAriaLabel: "{title} submenu",
+  activeHash: "",
 });
 
+const emit = defineEmits<{
+  anchorClick: [event: MouseEvent, href: string];
+}>();
+
 const submenuLabel = (link: ResponsiveHeaderNavItem) =>
   props.submenuAriaLabel.replace("{title}", link.childLinksTitle ?? link.name);
 
@@ -162,9 +187,13 @@ onUnmounted(() => {
 
 const route = useRoute();
 
+const isAnchorPath = (path?: string) => Boolean(path?.startsWith("#"));
+const isCurrentPath = (path?: string) =>
+  Boolean(path) && (isAnchorPath(path) ? path === props.activeHash : path === route.path);
+
 const isActiveNavItem = (link: ResponsiveHeaderNavItem): boolean => {
-  if (link.path) return route.path === link.path;
-  if (link.childLinks) return link.childLinks.some((child) => child.path && route.path === child.path);
+  if (link.path) return isCurrentPath(link.path);
+  if (link.childLinks) return link.childLinks.some((child) => isCurrentPath(child.path));
   return false;
 };
 // const DETAILS_ANIMATION_DURATION_STRING = `${DETAILS_ANIMATION_DURATION}ms` as const;
@@ -211,13 +240,15 @@ watch(
        --overflow-nav-items-padding-block    (default: 0.8rem)
 
        --overflow-nav-link-color             (default: inherit)
-       --overflow-nav-link-border-color      (default: #efefef75)
+       --overflow-nav-link-color-hover       (default: --overflow-nav-link-color)
+       --overflow-nav-link-color-active      (default: --overflow-nav-link-color)
+       --overflow-nav-link-border-color      (default: color-mix(in oklch, var(--theme-text) 12%, transparent))
        --overflow-nav-sub-item-color         (default: inherit)
        --overflow-nav-sub-item-font-size     (default: inherit)
 
        --overflow-nav-decorator-indicator-color         (default: currentColor)
        --overflow-nav-decorator-hovered-indicator-color (default: inherits --overflow-nav-decorator-indicator-color)
-       --overflow-nav-decorator-hovered-bg              (default: oklch(100% 0 0 / 6%))
+       --overflow-nav-decorator-hovered-bg              (default: color-mix(in oklch, var(--theme-text) 6%, transparent))
     ──────────────────────────────────────────────────────────────────────── */
 
     --_max-inline-size: var(--overflow-nav-max-inline-size, calc(100vw - 3.2rem));
@@ -247,13 +278,26 @@ watch(
           display: block;
         }
 
+        /* Per-state link colour; hover falls back to the item's current state. Unset means the resting colour. */
+        &.is-active {
+          --_overflow-link-color: var(--overflow-nav-link-color-active);
+        }
+
+        &.is-hovered {
+          --_overflow-link-color: var(--overflow-nav-link-color-hover, var(--overflow-nav-link-color-active));
+        }
+
+        &.is-hovered:not(.is-active) {
+          --_overflow-link-color: var(--overflow-nav-link-color-hover);
+        }
+
         .overflow-navigation-link {
           text-decoration: none;
-          color: var(--overflow-nav-link-color, inherit);
+          color: var(--_overflow-link-color, var(--overflow-nav-link-color, inherit));
           padding-block: var(--overflow-nav-items-padding-block, 0.8rem);
           padding-inline: var(--overflow-nav-padding-inline, 0.8rem);
           display: flex;
-          border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
+          border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, color-mix(in oklch, var(--theme-text) 12%, transparent));
         }
 
         .overflow-navigation-details {
@@ -271,8 +315,8 @@ watch(
                 padding-block: var(--overflow-nav-items-padding-block, 0.8rem);
                 padding-inline: var(--overflow-nav-padding-inline, 0.8rem);
                 gap: 1rem;
-                color: var(--overflow-nav-link-color, inherit);
-                border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
+                color: var(--_overflow-link-color, var(--overflow-nav-link-color, inherit));
+                border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, color-mix(in oklch, var(--theme-text) 12%, transparent));
 
                 .label-wrapper {
                   min-inline-size: 0;
@@ -287,7 +331,7 @@ watch(
                   border-bottom: 0.1rem solid transparent;
                 }
                 + .expanding-panel-content {
-                  border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
+                  border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, color-mix(in oklch, var(--theme-text) 12%, transparent));
                   .overflow-navigation-sub-nav-inner {
                     margin-top: var(--overflow-nav-items-gap, 0px);
                   }
@@ -332,8 +376,8 @@ watch(
                 padding-block: var(--overflow-nav-items-padding-block, 0.8rem);
                 padding-inline: var(--overflow-nav-padding-inline, 0.8rem);
                 gap: 1rem;
-                color: var(--overflow-nav-link-color, inherit);
-                border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
+                color: var(--_overflow-link-color, var(--overflow-nav-link-color, inherit));
+                border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, color-mix(in oklch, var(--theme-text) 12%, transparent));
 
                 .label-wrapper {
                   min-inline-size: 0;
@@ -348,7 +392,7 @@ watch(
                   border-bottom: 0.1rem solid transparent;
                 }
                 + .expanding-panel-classic-content {
-                  border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, #efefef75);
+                  border-bottom: 0.1rem solid var(--overflow-nav-link-border-color, color-mix(in oklch, var(--theme-text) 12%, transparent));
                   .overflow-navigation-sub-nav-inner {
                     margin-top: var(--overflow-nav-items-gap, 0px);
                   }
@@ -457,7 +501,7 @@ watch(
     right: 0;
     top: anchor(top);
     bottom: anchor(bottom);
-    background: var(--overflow-nav-decorator-hovered-bg, oklch(100% 0 0 / 6%));
+    background: var(--overflow-nav-decorator-hovered-bg, color-mix(in oklch, var(--theme-text) 6%, transparent));
     z-index: 1;
     opacity: 0;
     transition:
@@ -523,7 +567,7 @@ watch(
     right: 0;
     top: anchor(top);
     bottom: anchor(bottom);
-    background: var(--overflow-nav-decorator-hovered-bg, oklch(100% 0 0 / 6%));
+    background: var(--overflow-nav-decorator-hovered-bg, color-mix(in oklch, var(--theme-text) 6%, transparent));
     border-inline-start: 2px solid var(
       --overflow-nav-decorator-hovered-indicator-color,
       var(--overflow-nav-decorator-indicator-color, currentColor)

package/app/components/03.organisms/responsive-header/ResponsiveHeader.vue

@@ -39,8 +39,18 @@
           @mouseenter="handleNavigationItemHover(`${String(groupKey)}-${localIndex}`)"
           @focusin="handleNavigationItemHover(`${String(groupKey)}-${localIndex}`)"
         >
+          <a
+            v-if="link.path && isAnchorPath(link.path)"
+            class="main-navigation-link"
+            :class="{ 'has-icon': link.iconName }"
+            :href="link.path"
+            @click="handleAnchorClick($event, link.path)"
+          >
+            <Icon v-if="link.iconName" :name="link.iconName" class="decorator-icon" aria-hidden="true" />
+            {{ link.name }}
+          </a>
           <NuxtLink
-            v-if="link.path"
+            v-else-if="link.path"
             class="main-navigation-link"
             :class="{ 'has-icon': link.iconName }"
             :to="link.path"
@@ -69,7 +79,16 @@
                   :key="childIndex"
                   class="main-navigation-sub-nav-item"
                 >
-                  <NuxtLink :to="childLink.path" class="main-navigation-sub-nav-link" role="menuitem">
+                  <a
+                    v-if="childLink.path && isAnchorPath(childLink.path)"
+                    :href="childLink.path"
+                    class="main-navigation-sub-nav-link"
+                    role="menuitem"
+                    @click="handleAnchorClick($event, childLink.path)"
+                  >
+                    {{ childLink.name }}
+                  </a>
+                  <NuxtLink v-else :to="childLink.path" class="main-navigation-sub-nav-link" role="menuitem">
                     {{ childLink.name }}
                   </NuxtLink>
                 </li>
@@ -108,6 +127,8 @@
             :panel-variant="panelVariant"
             :aria-label="overflowMenuAriaLabel"
             :submenu-aria-label="submenuAriaLabel"
+            :active-hash="activeHash"
+            @anchor-click="handleAnchorClick"
           />
         </div>
       </details>
@@ -144,6 +165,11 @@ interface Props {
   overflowButtonLabel?: string;
   /** aria-label on each dropdown summary; {title} is replaced with the item's title. Forwarded to NavigationItems. */
   submenuAriaLabel?: string;
+  /**
+   * Pixels to leave above a section when a same-page "#anchor" link scrolls to it (e.g. a sticky
+   * header's height). Pass a getter to read it at click time.
+   */
+  anchorScrollOffset?: number | (() => number);
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -165,6 +191,7 @@ const props = withDefaults(defineProps<Props>(), {
   overflowMenuAriaLabel: "Overflow navigation menu",
   overflowButtonLabel: "More navigation",
   submenuAriaLabel: "{title} submenu",
+  anchorScrollOffset: undefined,
 });
 
 const submenuLabel = (link: ResponsiveHeaderNavItem) =>
@@ -315,12 +342,32 @@ const hoveredItemKey = ref<string | null>(null);
 
 const route = useRoute();
 
+// "#anchor" paths are same-page section links: plain <a>, smooth-scrolled, active by hash.
+const { handleNavClick, activeHash } = useAnchorScroll({ offset: props.anchorScrollOffset });
+const isAnchorPath = (path?: string) => Boolean(path?.startsWith("#"));
+const isCurrentPath = (path?: string) =>
+  Boolean(path) && (isAnchorPath(path) ? path === activeHash.value : path === route.path);
+
 const isActiveNavItem = (link: ResponsiveHeaderNavItem): boolean => {
-  if (link.path) return route.path === link.path;
-  if (link.childLinks) return link.childLinks.some((child) => child.path && route.path === child.path);
+  if (link.path) return isCurrentPath(link.path);
+  if (link.childLinks) return link.childLinks.some((child) => isCurrentPath(child.path));
   return false;
 };
 
+const handleAnchorClick = (event: MouseEvent, href: string) => {
+  handleNavClick(event, href);
+  closeAllNavigationDetails();
+};
+
+onMounted(() => {
+  if (activeHash.value) return;
+  const firstAnchor = Object.values(props.responsiveNavLinks)
+    .flat()
+    .flatMap((link) => [link, ...(link.childLinks ?? [])])
+    .find((link) => isAnchorPath(link.path));
+  if (firstAnchor?.path) activeHash.value = firstAnchor.path;
+});
+
 const isAnimated = ref(true);
 
 // Local (non-useState) flag — resets to false on every mount.
@@ -704,30 +751,32 @@ watch(
 
        --responsive-header-color                (default: inherit)
        --responsive-header-link-color           (default: inherit)
+       --responsive-header-link-color-hover     (default: --responsive-header-link-color)
+       --responsive-header-link-color-active    (default: --responsive-header-link-color)
 
-       --responsive-header-sub-nav-bg           (default: Canvas)
-       --responsive-header-sub-nav-border       (default: 1px solid #efefef75)
+       --responsive-header-sub-nav-bg           (default: var(--page-bg, var(--theme-surface-subtle)))
+       --responsive-header-sub-nav-border       (default: 1px solid color-mix(in oklch, var(--theme-text) 20%, transparent))
        --responsive-header-sub-nav-border-radius (default: 8px)
        --responsive-header-sub-nav-padding      (default: 12px)
        --responsive-header-sub-nav-max-inline-size (default: min(48rem, calc(100vw - 3.2rem)))
        --responsive-header-sub-nav-max-block-size  (default: 70vh)
 
-       --responsive-header-overflow-btn-bg              (default: Canvas)
+       --responsive-header-overflow-btn-bg              (default: transparent)
        --responsive-header-overflow-btn-size            (default: 20px)
-       --responsive-header-overflow-btn-border          (default: 1px solid #ffffff90)
-       --responsive-header-overflow-btn-outline         (default: 1px solid #ffffff10)
+       --responsive-header-overflow-btn-border          (default: 1px solid color-mix(in oklch, var(--theme-text) 20%, transparent))
+       --responsive-header-overflow-btn-outline         (default: 1px solid transparent)
        --responsive-header-overflow-btn-icon-color      (default: inherit)
-       --responsive-header-overflow-btn-hover-outline   (default: 1px solid #ffffff)
+       --responsive-header-overflow-btn-hover-outline   (default: 1px solid var(--theme-border-focus))
 
-       --responsive-header-overflow-nav-bg              (default: Canvas)
-       --responsive-header-overflow-nav-border          (default: 1px solid #ffffff90)
+       --responsive-header-overflow-nav-bg              (default: var(--page-bg, var(--theme-surface-subtle)))
+       --responsive-header-overflow-nav-border          (default: 1px solid color-mix(in oklch, var(--theme-text) 20%, transparent))
        --responsive-header-overflow-nav-border-radius   (default: 8px)
        --responsive-header-overflow-nav-padding-block   (default: 12px)
        --responsive-header-overflow-nav-max-block-size  (default: 70vh)
 
        --responsive-nav-decorator-indicator-color         (default: currentColor)
        --responsive-nav-decorator-hovered-indicator-color (default: inherits --responsive-nav-decorator-indicator-color)
-       --responsive-nav-decorator-hovered-bg              (default: oklch(100% 0 0 / 8%))
+       --responsive-nav-decorator-hovered-bg              (default: color-mix(in oklch, var(--theme-text) 8%, transparent))
 
        --responsive-header-link-font-size       (default: inherit)
        --responsive-header-main-nav-justify-content (default: space-between)
@@ -807,7 +856,7 @@ watch(
             gap: 6px;
             white-space: nowrap;
             font-size: var(--responsive-header-link-font-size, inherit);
-            color: var(--responsive-header-link-color, inherit);
+            color: var(--_link-color, var(--responsive-header-link-color, inherit));
             text-decoration: none;
             cursor: pointer;
             margin-inline-start: 0;
@@ -869,7 +918,7 @@ watch(
               position: relative;
               z-index: 4;
               font-size: var(--responsive-header-link-font-size, inherit);
-              color: var(--responsive-header-link-color, inherit);
+              color: var(--_link-color, var(--responsive-header-link-color, inherit));
 
               &::-webkit-details-marker,
               &::marker {
@@ -885,9 +934,9 @@ watch(
               position: absolute;
 
               padding: var(--responsive-header-sub-nav-padding, 12px);
-              border: var(--responsive-header-sub-nav-border, 1px solid #efefef75);
+              border: var(--responsive-header-sub-nav-border, 1px solid color-mix(in oklch, var(--theme-text) 20%, transparent));
               border-radius: var(--responsive-header-sub-nav-border-radius, 8px);
-              background-color: var(--responsive-header-sub-nav-bg, Canvas);
+              background-color: var(--responsive-header-sub-nav-bg, var(--page-bg, var(--theme-surface-subtle)));
               translate: 0 12px;
 
               min-width: var(--_main-navigation-item-width);
@@ -933,6 +982,19 @@ watch(
               margin-inline-start: var(--_main-navigation-item-width);
             }
           }
+
+          /* Per-state link colour; hover falls back to the item's current state. Unset means the resting colour. */
+          &.is-active {
+            --_link-color: var(--responsive-header-link-color-active);
+          }
+
+          &.is-hovered {
+            --_link-color: var(--responsive-header-link-color-hover, var(--responsive-header-link-color-active));
+          }
+
+          &.is-hovered:not(.is-active) {
+            --_link-color: var(--responsive-header-link-color-hover);
+          }
         }
 
         &:last-child {
@@ -1024,9 +1086,9 @@ watch(
 
           aspect-ratio: 1;
           border-radius: 4px;
-          border: var(--responsive-header-overflow-btn-border, 1px solid #ffffff90);
-          outline: var(--responsive-header-overflow-btn-outline, 1px solid #ffffff10);
-          background-color: var(--responsive-header-overflow-btn-bg, Canvas);
+          border: var(--responsive-header-overflow-btn-border, 1px solid color-mix(in oklch, var(--theme-text) 20%, transparent));
+          outline: var(--responsive-header-overflow-btn-outline, 1px solid transparent);
+          background-color: var(--responsive-header-overflow-btn-bg, transparent);
 
           width: var(--_icon-size);
           overflow: hidden;
@@ -1042,7 +1104,7 @@ watch(
           &:hover,
           &:focus-visible {
             --_icon-zoom: 1.2;
-            outline: var(--responsive-header-overflow-btn-hover-outline, 1px solid #ffffff);
+            outline: var(--responsive-header-overflow-btn-hover-outline, 1px solid var(--theme-border-focus));
           }
 
           .icon {
@@ -1068,8 +1130,8 @@ watch(
           position: absolute;
           top: 135%;
           right: 0;
-          background-color: var(--responsive-header-overflow-nav-bg, Canvas);
-          border: var(--responsive-header-overflow-nav-border, 1px solid #ffffff90);
+          background-color: var(--responsive-header-overflow-nav-bg, var(--page-bg, var(--theme-surface-subtle)));
+          border: var(--responsive-header-overflow-nav-border, 1px solid color-mix(in oklch, var(--theme-text) 20%, transparent));
           border-radius: var(--responsive-header-overflow-nav-border-radius, 8px);
           padding-block: var(--responsive-header-overflow-nav-padding-block, 12px);
           margin: 0;
@@ -1125,7 +1187,7 @@ watch(
       right: anchor(right);
       top: anchor(top);
       bottom: anchor(bottom);
-      background: var(--responsive-nav-decorator-hovered-bg, oklch(100% 0 0 / 8%));
+      background: var(--responsive-nav-decorator-hovered-bg, color-mix(in oklch, var(--theme-text) 8%, transparent));
       border-radius: 4px;
       z-index: 1;
       opacity: 0;

package/app/components/03.organisms/responsive-header/stories/ResponsiveHeader.stories.ts

@@ -82,6 +82,11 @@ const meta: Meta<StoryArgs> = {
       description: "aria-label on each dropdown summary; {title} is replaced with the item's title",
       table: { category: "Labels", defaultValue: { summary: "{title} submenu" } },
     },
+    anchorScrollOffset: {
+      control: { type: "number", min: 0, step: 10 },
+      description: "Pixels left above a section when a #anchor link scrolls to it (e.g. a sticky header's height)",
+      table: { category: "Behaviour", defaultValue: { summary: "0" } },
+    },
     styleClassPassthrough: {
       control: "object",
       description: "Extra CSS classes applied to the root element",
@@ -200,6 +205,53 @@ export const MainNavAlignment: Story = {
   },
 };
 
+export const SamePageAnchorLinks: Story = {
+  name: "Same-Page Anchor Links",
+  args: {
+    responsiveNavLinks: {
+      main: [
+        { name: "Home", path: "#rh-home" },
+        { name: "About", path: "#rh-about" },
+        { name: "Testimonials", path: "#rh-testimonials" },
+        {
+          name: "More",
+          childLinks: [
+            { name: "Prices", path: "#rh-prices" },
+            { name: "Blog (a route)", path: "/blog" },
+          ],
+        },
+        { name: "Contact", path: "#rh-contact" },
+      ],
+    },
+    anchorScrollOffset: 80,
+  },
+  render: renderWith(`
+    <div style="position: sticky; top: 0; z-index: 2; background: var(--page-bg, white); border-block-end: 1px solid currentColor;">
+      <ResponsiveHeader v-bind="componentArgs" />
+    </div>
+    <section
+      v-for="id in ['rh-home', 'rh-about', 'rh-testimonials', 'rh-prices', 'rh-contact']"
+      :id="id"
+      :key="id"
+      style="min-block-size: 70vh; padding: 2.4rem; border-block-end: 1px dashed currentColor;"
+    >
+      <h2 style="margin: 0;">#{{ id }}</h2>
+    </section>
+  `),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Items whose `path` starts with `#` are same-page section links: they render as plain `<a>` (not NuxtLink), " +
+          "smooth-scroll to the section (an instant jump under reduced motion), and are active by hash rather than by " +
+          "route; the first anchor is active on load. `anchorScrollOffset` (80 here) leaves room for the sticky header. " +
+          "Route links like Blog mix in as normal. Narrow the canvas so items move into the overflow menu: anchor links " +
+          "there scroll the same way and close the menu.",
+      },
+    },
+  },
+};
+
 // ─── Stress test ──────────────────────────────────────────────────────────────
 
 const stressNavLinks: ResponsiveHeaderProp = {

package/app/components/03.organisms/responsive-header/tests/NavigationItems.spec.ts

@@ -168,4 +168,24 @@ describe("NavigationItems", () => {
     });
     expect(wrapper.html()).toMatchSnapshot();
   });
+
+  // ─── Same-page anchor links ─────────────────────────────────────────────
+
+  it("renders #anchor items as plain links, emits anchorClick and follows activeHash", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: {
+        activeHash: "#about",
+        mainNavigationState: {
+          clonedNavLinks: { firstNav: [{ name: "Home", path: "#home" }, { name: "About", path: "#about" }] },
+          navListVisibility: { firstNav: false },
+          hasSecondNav: false,
+        },
+      },
+    });
+    const links = wrapper.findAll(".overflow-navigation-link");
+    expect(links[0]!.attributes("href")).toBe("#home");
+    expect(wrapper.findAll(".overflow-navigation-item")[1]!.classes()).toContain("is-active");
+    await links[0]!.trigger("click");
+    expect(wrapper.emitted("anchorClick")?.[0]?.[1]).toBe("#home");
+  });
 });

package/app/components/03.organisms/responsive-header/tests/ResponsiveHeader.spec.ts

@@ -401,4 +401,44 @@ describe("ResponsiveHeader", () => {
     });
     expect(wrapper.html()).toMatchSnapshot();
   });
+
+  // ─── Same-page anchor links ─────────────────────────────────────────────
+
+  describe("anchor links", () => {
+    const anchorLinks: ResponsiveHeaderProp = {
+      firstNav: [
+        { name: "Home", path: "#home" },
+        { name: "About", path: "#about" },
+        { name: "Blog", path: "/blog" },
+      ],
+    };
+
+    it("renders #anchor paths as plain links and route paths as NuxtLinks", async () => {
+      const wrapper = await mountSuspended(ResponsiveHeader, { props: { responsiveNavLinks: anchorLinks } });
+      const links = wrapper.findAll(".main-navigation-link");
+      expect(links[0]!.attributes("href")).toBe("#home");
+      expect(links[2]!.attributes("href")).toBe("/blog");
+    });
+
+    it("marks the first anchor item active on load", async () => {
+      const wrapper = await mountSuspended(ResponsiveHeader, { props: { responsiveNavLinks: anchorLinks } });
+      await nextTick();
+      const items = wrapper.findAll(".main-navigation-item");
+      expect(items[0]!.classes()).toContain("is-active");
+      expect(items[1]!.classes()).not.toContain("is-active");
+    });
+
+    it("moves the active item to a clicked anchor and scrolls instead of jumping", async () => {
+      vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({ matches: false }));
+      const section = document.createElement("section");
+      section.id = "about";
+      section.scrollIntoView = vi.fn();
+      document.body.appendChild(section);
+      const wrapper = await mountSuspended(ResponsiveHeader, { props: { responsiveNavLinks: anchorLinks } });
+      await wrapper.findAll(".main-navigation-link")[1]!.trigger("click");
+      expect(section.scrollIntoView).toHaveBeenCalled();
+      expect(wrapper.findAll(".main-navigation-item")[1]!.classes()).toContain("is-active");
+      section.remove();
+    });
+  });
 });