diff --git a/app/components/ReadmeTocDropdown.vue b/app/components/ReadmeTocDropdown.vue
new file mode 100644
index 000000000..36226ee24
--- /dev/null
+++ b/app/components/ReadmeTocDropdown.vue
@@ -0,0 +1,246 @@
+<script setup lang="ts">
+import type { TocItem } from '#shared/types/readme'
+import { onClickOutside, useEventListener } from '@vueuse/core'
+import { scrollToAnchor } from '~/utils/scrollToAnchor'
+
+const props = defineProps<{
+  toc: TocItem[]
+  activeId?: string | null
+  scrollToHeading?: (id: string) => void
+}>()
+
+interface TocNode extends TocItem {
+  children: TocNode[]
+}
+
+function buildTocTree(items: TocItem[]): TocNode[] {
+  const result: TocNode[] = []
+  const stack: TocNode[] = []
+
+  for (const item of items) {
+    const node: TocNode = { ...item, children: [] }
+
+    // Find parent: look for the last item with smaller depth
+    while (stack.length > 0 && stack[stack.length - 1]!.depth >= item.depth) {
+      stack.pop()
+    }
+
+    if (stack.length === 0) {
+      result.push(node)
+    } else {
+      stack[stack.length - 1]!.children.push(node)
+    }
+
+    stack.push(node)
+  }
+
+  return result
+}
+
+const tocTree = computed(() => buildTocTree(props.toc))
+
+// Create a map from id to index for efficient lookup
+const idToIndex = computed(() => {
+  const map = new Map<string, number>()
+  props.toc.forEach((item, index) => map.set(item.id, index))
+  return map
+})
+
+const listRef = useTemplateRef('listRef')
+const triggerRef = useTemplateRef('triggerRef')
+const isOpen = shallowRef(false)
+const highlightedIndex = shallowRef(-1)
+
+const dropdownPosition = shallowRef<{ top: number; right: number } | null>(null)
+
+function getDropdownStyle(): Record<string, string> {
+  if (!dropdownPosition.value) return {}
+  return {
+    top: `${dropdownPosition.value.top}px`,
+    right: `${document.documentElement.clientWidth - dropdownPosition.value.right}px`,
+  }
+}
+
+// Close on scroll (but not when scrolling inside the dropdown)
+function handleScroll(event: Event) {
+  if (!isOpen.value) return
+  if (listRef.value && event.target instanceof Node && listRef.value.contains(event.target)) {
+    return
+  }
+  close()
+}
+useEventListener('scroll', handleScroll, true)
+
+// Generate unique ID for accessibility
+const inputId = useId()
+const listboxId = `${inputId}-toc-listbox`
+
+function toggle() {
+  if (isOpen.value) {
+    close()
+  } else {
+    if (triggerRef.value) {
+      const rect = triggerRef.value.getBoundingClientRect()
+      dropdownPosition.value = {
+        top: rect.bottom + 4,
+        right: rect.right,
+      }
+    }
+    isOpen.value = true
+    // Highlight active item if any
+    const activeIndex = idToIndex.value.get(props.activeId ?? '')
+    highlightedIndex.value = activeIndex ?? 0
+  }
+}
+
+function close() {
+  isOpen.value = false
+  highlightedIndex.value = -1
+}
+
+function select(id: string) {
+  scrollToAnchor(id, { scrollFn: props.scrollToHeading })
+  close()
+  triggerRef.value?.focus()
+}
+
+function getIndex(id: string): number {
+  return idToIndex.value.get(id) ?? -1
+}
+
+// Check for reduced motion preference
+const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')
+
+onClickOutside(listRef, close, { ignore: [triggerRef] })
+
+function handleKeydown(event: KeyboardEvent) {
+  if (!isOpen.value) return
+
+  const itemCount = props.toc.length
+
+  switch (event.key) {
+    case 'ArrowDown':
+      event.preventDefault()
+      highlightedIndex.value = (highlightedIndex.value + 1) % itemCount
+      break
+    case 'ArrowUp':
+      event.preventDefault()
+      highlightedIndex.value =
+        highlightedIndex.value <= 0 ? itemCount - 1 : highlightedIndex.value - 1
+      break
+    case 'Enter': {
+      event.preventDefault()
+      const item = props.toc[highlightedIndex.value]
+      if (item) {
+        select(item.id)
+      }
+      break
+    }
+    case 'Escape':
+      close()
+      triggerRef.value?.focus()
+      break
+  }
+}
+</script>
+
+<template>
+  <button
+    ref="triggerRef"
+    type="button"
+    class="flex items-center gap-1.5 px-2 py-2 font-mono text-xs text-fg-muted bg-bg-subtle border border-border-subtle border-solid rounded-md transition-colors duration-150 hover:(text-fg border-border-hover) active:scale-95 focus:border-border-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fg/50 hover:text-fg"
+    :aria-expanded="isOpen"
+    aria-haspopup="listbox"
+    :aria-label="$t('package.readme.toc_title')"
+    :aria-controls="listboxId"
+    @click="toggle"
+    @keydown="handleKeydown"
+  >
+    <span class="i-carbon:list w-3.5 h-3.5" aria-hidden="true" />
+    <span
+      class="i-carbon:chevron-down w-3 h-3"
+      :class="[
+        { 'rotate-180': isOpen },
+        prefersReducedMotion ? '' : 'transition-transform duration-200',
+      ]"
+      aria-hidden="true"
+    />
+  </button>
+
+  <Teleport to="body">
+    <Transition
+      :enter-active-class="prefersReducedMotion ? '' : 'transition-opacity duration-150'"
+      :enter-from-class="prefersReducedMotion ? '' : 'opacity-0'"
+      enter-to-class="opacity-100"
+      :leave-active-class="prefersReducedMotion ? '' : 'transition-opacity duration-100'"
+      leave-from-class="opacity-100"
+      :leave-to-class="prefersReducedMotion ? '' : 'opacity-0'"
+    >
+      <div
+        v-if="isOpen"
+        :id="listboxId"
+        ref="listRef"
+        role="listbox"
+        :aria-activedescendant="
+          highlightedIndex >= 0 ? `${listboxId}-${toc[highlightedIndex]?.id}` : undefined
+        "
+        :aria-label="$t('package.readme.toc_title')"
+        :style="getDropdownStyle()"
+        class="fixed bg-bg-subtle border border-border rounded-md shadow-lg z-50 max-h-80 overflow-y-auto w-56 overscroll-contain"
+      >
+        <template v-for="node in tocTree" :key="node.id">
+          <div
+            :id="`${listboxId}-${node.id}`"
+            role="option"
+            :aria-selected="activeId === node.id"
+            class="flex items-center gap-2 px-3 py-1.5 text-sm cursor-pointer transition-colors duration-150"
+            :class="[
+              activeId === node.id ? 'text-fg font-medium' : 'text-fg-muted',
+              highlightedIndex === getIndex(node.id) ? 'bg-bg-elevated' : 'hover:bg-bg-elevated',
+            ]"
+            @click="select(node.id)"
+            @mouseenter="highlightedIndex = getIndex(node.id)"
+          >
+            <span class="truncate">{{ node.text }}</span>
+          </div>
+
+          <template v-for="child in node.children" :key="child.id">
+            <div
+              :id="`${listboxId}-${child.id}`"
+              role="option"
+              :aria-selected="activeId === child.id"
+              class="flex items-center gap-2 px-3 py-1.5 ps-6 text-sm cursor-pointer transition-colors duration-150"
+              :class="[
+                activeId === child.id ? 'text-fg font-medium' : 'text-fg-subtle',
+                highlightedIndex === getIndex(child.id) ? 'bg-bg-elevated' : 'hover:bg-bg-elevated',
+              ]"
+              @click="select(child.id)"
+              @mouseenter="highlightedIndex = getIndex(child.id)"
+            >
+              <span class="truncate">{{ child.text }}</span>
+            </div>
+
+            <div
+              v-for="grandchild in child.children"
+              :id="`${listboxId}-${grandchild.id}`"
+              :key="grandchild.id"
+              role="option"
+              :aria-selected="activeId === grandchild.id"
+              class="flex items-center gap-2 px-3 py-1.5 ps-9 text-sm cursor-pointer transition-colors duration-150"
+              :class="[
+                activeId === grandchild.id ? 'text-fg font-medium' : 'text-fg-subtle',
+                highlightedIndex === getIndex(grandchild.id)
+                  ? 'bg-bg-elevated'
+                  : 'hover:bg-bg-elevated',
+              ]"
+              @click="select(grandchild.id)"
+              @mouseenter="highlightedIndex = getIndex(grandchild.id)"
+            >
+              <span class="truncate">{{ grandchild.text }}</span>
+            </div>
+          </template>
+        </template>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
diff --git a/app/composables/useActiveTocItem.ts b/app/composables/useActiveTocItem.ts
new file mode 100644
index 000000000..3898e6a23
--- /dev/null
+++ b/app/composables/useActiveTocItem.ts
@@ -0,0 +1,196 @@
+import type { TocItem } from '#shared/types/readme'
+import type { Ref } from 'vue'
+import { scrollToAnchor } from '~/utils/scrollToAnchor'
+
+/**
+ * Composable for tracking the currently visible heading in a TOC.
+ * Uses IntersectionObserver to detect which heading is at the top of the viewport.
+ *
+ * @param toc - Reactive array of TOC items
+ * @returns Object containing activeId and scrollToHeading function
+ * @public
+ */
+export function useActiveTocItem(toc: Ref<TocItem[]>) {
+  const activeId = ref<string | null>(null)
+
+  // Only run observer logic on client
+  if (import.meta.server) {
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    return { activeId, scrollToHeading: (_id: string) => {} }
+  }
+
+  let observer: IntersectionObserver | null = null
+  const headingElements = new Map<string, Element>()
+  let scrollCleanup: (() => void) | null = null
+
+  const setupObserver = () => {
+    // Clean up previous observer
+    if (observer) {
+      observer.disconnect()
+    }
+    headingElements.clear()
+
+    // Find all heading elements that match TOC IDs
+    const ids = toc.value.map(item => item.id)
+    if (ids.length === 0) return
+
+    for (const id of ids) {
+      const el = document.getElementById(id)
+      if (el) {
+        headingElements.set(id, el)
+      }
+    }
+
+    if (headingElements.size === 0) return
+
+    // Create observer that triggers when headings cross the top 20% of viewport
+    observer = new IntersectionObserver(
+      entries => {
+        // Get all visible headings sorted by their position
+        const visibleHeadings: { id: string; top: number }[] = []
+
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            visibleHeadings.push({
+              id: entry.target.id,
+              top: entry.boundingClientRect.top,
+            })
+          }
+        }
+
+        // If there are visible headings, pick the one closest to the top
+        if (visibleHeadings.length > 0) {
+          visibleHeadings.sort((a, b) => a.top - b.top)
+          activeId.value = visibleHeadings[0]?.id ?? null
+        } else {
+          // No headings visible in intersection zone - find the one just above viewport
+          const headingsWithPosition: { id: string; top: number }[] = []
+          for (const [id, el] of headingElements) {
+            const rect = el.getBoundingClientRect()
+            headingsWithPosition.push({ id, top: rect.top })
+          }
+
+          // Find the heading that's closest to (but above) the viewport top
+          const aboveViewport = headingsWithPosition
+            .filter(h => h.top < 100) // Allow some buffer
+            .sort((a, b) => b.top - a.top) // Sort descending (closest to top first)
+
+          if (aboveViewport.length > 0) {
+            activeId.value = aboveViewport[0]?.id ?? null
+          }
+        }
+      },
+      {
+        rootMargin: '-80px 0px -70% 0px', // Trigger in top ~30% of viewport (accounting for header)
+        threshold: 0,
+      },
+    )
+
+    // Observe all heading elements
+    for (const el of headingElements.values()) {
+      observer.observe(el)
+    }
+  }
+
+  // Scroll to a heading with observer disconnection during scroll
+  const scrollToHeading = (id: string) => {
+    if (!document.getElementById(id)) return
+
+    // Clean up any previous scroll monitoring
+    if (scrollCleanup) {
+      scrollCleanup()
+      scrollCleanup = null
+    }
+
+    // Immediately set activeId
+    activeId.value = id
+
+    // Disconnect observer to prevent interference during scroll
+    if (observer) {
+      observer.disconnect()
+    }
+
+    // Scroll, but do not update url until scroll ends
+    scrollToAnchor(id, { updateUrl: false })
+
+    const handleScrollEnd = () => {
+      history.replaceState(null, '', `#${id}`)
+      setupObserver()
+      scrollCleanup = null
+    }
+
+    // Check for scrollend support (Chrome 114+, Firefox 109+, Safari 18+)
+    const supportsScrollEnd = 'onscrollend' in window
+
+    if (supportsScrollEnd) {
+      window.addEventListener('scrollend', handleScrollEnd, { once: true })
+      scrollCleanup = () => window.removeEventListener('scrollend', handleScrollEnd)
+    } else {
+      // Fallback: use RAF polling for older browsers
+      let lastScrollY = window.scrollY
+      let stableFrames = 0
+      let rafId: number | null = null
+      const STABLE_THRESHOLD = 5 // Number of frames with no movement to consider settled
+
+      const checkScrollSettled = () => {
+        const currentScrollY = window.scrollY
+
+        if (Math.abs(currentScrollY - lastScrollY) < 1) {
+          stableFrames++
+          if (stableFrames >= STABLE_THRESHOLD) {
+            handleScrollEnd()
+            return
+          }
+        } else {
+          stableFrames = 0
+        }
+
+        lastScrollY = currentScrollY
+        rafId = requestAnimationFrame(checkScrollSettled)
+      }
+
+      rafId = requestAnimationFrame(checkScrollSettled)
+
+      scrollCleanup = () => {
+        if (rafId !== null) {
+          cancelAnimationFrame(rafId)
+          rafId = null
+        }
+      }
+    }
+
+    // Safety timeout - reconnect observer after max scroll time
+    setTimeout(() => {
+      if (scrollCleanup) {
+        scrollCleanup()
+        scrollCleanup = null
+        history.replaceState(null, '', `#${id}`)
+        setupObserver()
+      }
+    }, 1000)
+  }
+
+  // Set up observer when TOC changes
+  watch(
+    toc,
+    () => {
+      // Use nextTick to ensure DOM is updated
+      nextTick(setupObserver)
+    },
+    { immediate: true },
+  )
+
+  // Clean up on unmount
+  onUnmounted(() => {
+    if (scrollCleanup) {
+      scrollCleanup()
+      scrollCleanup = null
+    }
+    if (observer) {
+      observer.disconnect()
+      observer = null
+    }
+  })
+
+  return { activeId, scrollToHeading }
+}
diff --git a/app/pages/[...package].vue b/app/pages/[...package].vue
index 40c6b7bd1..f912a5aed 100644
--- a/app/pages/[...package].vue
+++ b/app/pages/[...package].vue
@@ -57,9 +57,13 @@ const { data: readmeData } = useLazyFetch<ReadmeResponse>(
     const version = requestedVersion.value
     return version ? `${base}/v/${version}` : base
   },
-  { default: () => ({ html: '', playgroundLinks: [] }) },
+  { default: () => ({ html: '', playgroundLinks: [], toc: [] }) },
 )
 
+// Track active TOC item based on scroll position
+const tocItems = computed(() => readmeData.value?.toc ?? [])
+const { activeId: activeTocId, scrollToHeading } = useActiveTocItem(tocItems)
+
 // Check if package exists on JSR (only for scoped packages)
 const { data: jsrInfo } = useLazyFetch<JsrPackageInfo>(() => `/api/jsr/${packageName.value}`, {
   default: () => ({ exists: false }),
@@ -961,18 +965,29 @@ function handleClick(event: MouseEvent) {
 
       <!-- README -->
       <section id="readme" class="area-readme min-w-0 scroll-mt-20">
-        <h2 id="readme-heading" class="group text-xs text-fg-subtle uppercase tracking-wider mb-4">
-          <a
-            href="#readme"
-            class="inline-flex py-4 px-2 items-center gap-1.5 text-fg-subtle hover:text-fg-muted transition-colors duration-200 no-underline"
-          >
-            {{ $t('package.readme.title') }}
-            <span
-              class="i-carbon:link w-3 h-3 opacity-0 group-hover:opacity-100 transition-opacity duration-200"
-              aria-hidden="true"
+        <div class="flex flex-wrap items-center justify-between mb-3">
+          <h2 id="readme-heading" class="group text-xs text-fg-subtle uppercase tracking-wider">
+            <a
+              href="#readme"
+              class="inline-flex py-4 px-2 items-center gap-1.5 text-fg-subtle hover:text-fg-muted transition-colors duration-200 no-underline"
+            >
+              {{ $t('package.readme.title') }}
+              <span
+                class="i-carbon:link w-3 h-3 opacity-0 group-hover:opacity-100 transition-opacity duration-200"
+                aria-hidden="true"
+              />
+            </a>
+          </h2>
+          <ClientOnly>
+            <ReadmeTocDropdown
+              v-if="readmeData?.toc && readmeData.toc.length > 1"
+              :toc="readmeData.toc"
+              :active-id="activeTocId"
+              :scroll-to-heading="scrollToHeading"
             />
-          </a>
-        </h2>
+          </ClientOnly>
+        </div>
+
         <!-- eslint-disable vue/no-v-html -- HTML is sanitized server-side -->
         <Readme v-if="readmeData?.html" :html="readmeData.html" @click="handleClick" />
         <p v-else class="text-fg-subtle italic">
diff --git a/app/utils/scrollToAnchor.ts b/app/utils/scrollToAnchor.ts
new file mode 100644
index 000000000..f0ec64be4
--- /dev/null
+++ b/app/utils/scrollToAnchor.ts
@@ -0,0 +1,45 @@
+export interface ScrollToAnchorOptions {
+  /** Custom scroll function (e.g., from useActiveTocItem) */
+  scrollFn?: (id: string) => void
+  /** Whether to update the URL hash (default: true) */
+  updateUrl?: boolean
+}
+
+/**
+ * Scroll to an element by ID, using a custom scroll function if provided,
+ * otherwise falling back to default scroll behavior with header offset.
+ *
+ * @param id - The element ID to scroll to
+ * @param options - Optional configuration for scroll behavior
+ */
+export function scrollToAnchor(id: string, options?: ScrollToAnchorOptions): void {
+  const { scrollFn, updateUrl = true } = options ?? {}
+
+  // Use custom scroll function if provided
+  if (scrollFn) {
+    scrollFn(id)
+    return
+  }
+
+  // Fallback: scroll with header offset
+  const element = document.getElementById(id)
+  if (!element) return
+
+  // Calculate scroll position with header offset (matches scroll-padding-top in main.css)
+  const HEADER_OFFSET = 80
+  const PKG_STICKY_HEADER_OFFSET = 52
+  const elementTop = element.getBoundingClientRect().top + window.scrollY
+  const targetScrollY = elementTop - (HEADER_OFFSET + PKG_STICKY_HEADER_OFFSET)
+
+  // Use scrollTo for precise control
+  window.scrollTo({
+    top: targetScrollY,
+    behavior: 'smooth',
+  })
+
+  // Update URL hash after initiating scroll
+  // Use replaceState to avoid triggering native scroll-to-anchor behavior
+  if (updateUrl) {
+    history.replaceState(null, '', `#${id}`)
+  }
+}
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index 57361f72b..9c366162e 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -200,7 +200,8 @@
     "readme": {
       "title": "Readme",
       "no_readme": "No README available.",
-      "view_on_github": "View on GitHub"
+      "view_on_github": "View on GitHub",
+      "toc_title": "Outline"
     },
     "keywords_title": "Keywords",
     "compatibility": "Compatibility",
diff --git a/lunaria/files/en-US.json b/lunaria/files/en-US.json
index 57361f72b..9c366162e 100644
--- a/lunaria/files/en-US.json
+++ b/lunaria/files/en-US.json
@@ -200,7 +200,8 @@
     "readme": {
       "title": "Readme",
       "no_readme": "No README available.",
-      "view_on_github": "View on GitHub"
+      "view_on_github": "View on GitHub",
+      "toc_title": "Outline"
     },
     "keywords_title": "Keywords",
     "compatibility": "Compatibility",
diff --git a/server/api/registry/readme/[...pkg].get.ts b/server/api/registry/readme/[...pkg].get.ts
index c523bbd01..d72b76442 100644
--- a/server/api/registry/readme/[...pkg].get.ts
+++ b/server/api/registry/readme/[...pkg].get.ts
@@ -107,7 +107,7 @@ export default defineCachedEventHandler(
       }
 
       if (!readmeContent || readmeContent === NPM_MISSING_README_SENTINEL) {
-        return { html: '', playgroundLinks: [] }
+        return { html: '', playgroundLinks: [], toc: [] }
       }
 
       // Parse repository info for resolving relative URLs to GitHub
diff --git a/server/utils/readme.ts b/server/utils/readme.ts
index 66373985b..505989ed0 100644
--- a/server/utils/readme.ts
+++ b/server/utils/readme.ts
@@ -1,7 +1,7 @@
 import { marked, type Tokens } from 'marked'
 import sanitizeHtml from 'sanitize-html'
 import { hasProtocol } from 'ufo'
-import type { ReadmeResponse } from '#shared/types/readme'
+import type { ReadmeResponse, TocItem } from '#shared/types/readme'
 import { convertBlobToRawUrl, type RepositoryInfo } from '#shared/utils/git-providers'
 import { highlightCodeSync } from './shiki'
 import { convertToEmoji } from '#shared/utils/emoji'
@@ -255,7 +255,7 @@ export async function renderReadmeHtml(
   packageName: string,
   repoInfo?: RepositoryInfo,
 ): Promise<ReadmeResponse> {
-  if (!content) return { html: '', playgroundLinks: [] }
+  if (!content) return { html: '', playgroundLinks: [], toc: [] }
 
   const shiki = await getShikiHighlighter()
   const renderer = new marked.Renderer()
@@ -264,6 +264,9 @@ export async function renderReadmeHtml(
   const collectedLinks: PlaygroundLink[] = []
   const seenUrls = new Set<string>()
 
+  // Collect table of contents items during parsing
+  const toc: TocItem[] = []
+
   // Track used heading slugs to handle duplicates (GitHub-style: foo, foo-1, foo-2)
   const usedSlugs = new Map<string, number>()
 
@@ -303,6 +306,12 @@ export async function renderReadmeHtml(
     // (e.g., #install, #dependencies, #versions are used by the package page)
     const id = `user-content-${uniqueSlug}`
 
+    // Collect TOC item with plain text (HTML stripped)
+    const plainText = text.replace(/<[^>]*>/g, '').trim()
+    if (plainText) {
+      toc.push({ text: plainText, id, depth })
+    }
+
     return `<h${semanticLevel} id="${id}" data-level="${depth}">${text}</h${semanticLevel}>\n`
   }
 
@@ -420,5 +429,6 @@ ${html}
   return {
     html: convertToEmoji(sanitized),
     playgroundLinks: collectedLinks,
+    toc,
   }
 }
diff --git a/shared/types/readme.ts b/shared/types/readme.ts
index 58246fd2a..350450c4d 100644
--- a/shared/types/readme.ts
+++ b/shared/types/readme.ts
@@ -12,6 +12,18 @@ export interface PlaygroundLink {
   label: string
 }
 
+/**
+ * Table of contents item extracted from README headings
+ */
+export interface TocItem {
+  /** Plain text heading (HTML stripped) */
+  text: string
+  /** Anchor ID (e.g., "user-content-installation") */
+  id: string
+  /** Original heading depth (1-6) */
+  depth: number
+}
+
 /**
  * Response from README API endpoint
  */
@@ -20,4 +32,6 @@ export interface ReadmeResponse {
   html: string
   /** Extracted playground/demo links */
   playgroundLinks: PlaygroundLink[]
+  /** Table of contents extracted from headings */
+  toc: TocItem[]
 }
diff --git a/test/nuxt/a11y.spec.ts b/test/nuxt/a11y.spec.ts
index e2490b110..472b76eb4 100644
--- a/test/nuxt/a11y.spec.ts
+++ b/test/nuxt/a11y.spec.ts
@@ -106,6 +106,7 @@ import {
   PaginationControls,
   ProvenanceBadge,
   Readme,
+  ReadmeTocDropdown,
   SettingsAccentColorPicker,
   SettingsToggle,
   TerminalExecute,
@@ -1683,6 +1684,54 @@ describe('component accessibility audits', () => {
     })
   })
 
+  describe('ReadmeTocDropdown', () => {
+    const mockToc = [
+      { text: 'Installation', id: 'installation', depth: 2 },
+      { text: 'Usage', id: 'usage', depth: 2 },
+      { text: 'Basic Usage', id: 'basic-usage', depth: 3 },
+      { text: 'Advanced Usage', id: 'advanced-usage', depth: 3 },
+      { text: 'API', id: 'api', depth: 2 },
+    ]
+
+    it('should have no accessibility violations', async () => {
+      const component = await mountSuspended(ReadmeTocDropdown, {
+        props: { toc: mockToc },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+
+    it('should have no accessibility violations with active item', async () => {
+      const component = await mountSuspended(ReadmeTocDropdown, {
+        props: {
+          toc: mockToc,
+          activeId: 'usage',
+        },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+
+    it('should have no accessibility violations with nested active item', async () => {
+      const component = await mountSuspended(ReadmeTocDropdown, {
+        props: {
+          toc: mockToc,
+          activeId: 'basic-usage',
+        },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+
+    it('should have no accessibility violations with empty toc', async () => {
+      const component = await mountSuspended(ReadmeTocDropdown, {
+        props: { toc: [] },
+      })
+      const results = await runAxe(component)
+      expect(results.violations).toEqual([])
+    })
+  })
+
   describe('HeaderSearchBox', () => {
     it('should have no accessibility violations', async () => {
       const component = await mountSuspended(HeaderSearchBox)