From 36a71db330dc74a75bd6f5ef7e66319752cc8dcb Mon Sep 17 00:00:00 2001
From: LunaStev <luna@lunastev.org>
Date: Mon, 12 Oct 2026 17:22:53 +0900
Subject: [PATCH] feat: refresh documentation navigation and reading layout

---
 .../src/components/docs/DocumentationTree.vue |  34 +++
 frontend/src/i18n/index.ts                    |  16 +-
 frontend/src/pages/DocsPage.vue               | 118 +++++++----
 frontend/src/ui/service-pages.css             | 193 ++++++++++--------
 4 files changed, 233 insertions(+), 128 deletions(-)
 create mode 100644 frontend/src/components/docs/DocumentationTree.vue

diff --git a/frontend/src/components/docs/DocumentationTree.vue b/frontend/src/components/docs/DocumentationTree.vue
new file mode 100644
index 0000000..b922d55
--- /dev/null
+++ b/frontend/src/components/docs/DocumentationTree.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { ChevronRight, Search } from '@lucide/vue'
+import { useI18n } from '../../i18n'
+import type { DocumentSummary } from '../../services/http'
+
+const props = defineProps<{
+  groups: Array<{ id: string; title: string; items: DocumentSummary[] }>
+  base: string
+  catalog: string
+  projectName: string
+  currentPath: string
+  activeGroup?: string
+}>()
+const query = defineModel<string>({ required: true })
+const { t } = useI18n()
+</script>
+
+<template>
+  <div class="docs-tree-heading">{{ projectName }} {{ t('docs.title') }}</div>
+  <label class="docs-search">
+    <Search :size="16" aria-hidden="true" />
+    <input v-model="query" type="search" :aria-label="t('docs.search')" :placeholder="t('docs.filter')" />
+  </label>
+  <nav class="docs-tree-links" :aria-label="t('docs.navigation')">
+    <RouterLink class="docs-tree-overview" :to="catalog" :aria-current="!currentPath ? 'page' : undefined">{{ t('docs.overview') }}</RouterLink>
+    <details v-for="group in groups" :key="`${group.id}:${query.trim()}`" :open="!!query.trim() || !activeGroup || group.id === activeGroup">
+      <summary><ChevronRight :size="14" aria-hidden="true" /><span>{{ group.title }}</span></summary>
+      <div class="docs-tree-group">
+        <RouterLink v-for="item in group.items" :key="item.path" :to="`${base}/${item.path}`" :aria-current="item.path === currentPath ? 'page' : undefined">{{ item.title }}</RouterLink>
+      </div>
+    </details>
+    <p v-if="query.trim() && !props.groups.length" class="docs-tree-empty" role="status">{{ t('docs.noResults') }}</p>
+  </nav>
+</template>
diff --git a/frontend/src/i18n/index.ts b/frontend/src/i18n/index.ts
index b19dfa4..e62548a 100644
--- a/frontend/src/i18n/index.ts
+++ b/frontend/src/i18n/index.ts
@@ -273,7 +273,7 @@ const messages: Record<Locale, Record<string, string>> = {
 	'blog.comments.policyDisabled': 'Disabled',
 	'blog.comments.moderation': 'Comment moderation',
     'docs.search': 'Search documentation',
-    'docs.contents': 'Contents',
+    'docs.contents': 'In this article',
     'docs.popular': 'Popular guides',
     'docs.browse': 'Browse all documentation',
     'docs.installation': 'Installation',
@@ -295,6 +295,12 @@ const messages: Record<Locale, Record<string, string>> = {
     'docs.tools': 'Tools',
     'docs.reference': 'Reference',
     'docs.navigation': 'Documentation navigation',
+    'docs.filter': 'Filter documentation',
+    'docs.overview': 'Overview',
+    'docs.article': 'Article',
+    'docs.breadcrumb': 'Breadcrumb',
+    'docs.focus': 'Focus mode',
+    'docs.exitFocus': 'Exit focus mode',
     'docs.sourceRevision': 'Source',
     'docs.previous': 'Previous',
     'docs.next': 'Next',
@@ -1045,7 +1051,7 @@ const messages: Record<Locale, Record<string, string>> = {
     'docs.ecosystem': '생태계',
     'docs.ecosystem.detail': 'Vex, Whale, WSON과 관련 프로젝트',
     'docs.search': '문서 검색',
-    'docs.contents': '문서 목차',
+    'docs.contents': '이 문서의 내용',
     'docs.popular': '많이 찾는 문서',
     'docs.browse': '전체 문서 둘러보기',
     'docs.installation': '설치',
@@ -1067,6 +1073,12 @@ const messages: Record<Locale, Record<string, string>> = {
     'docs.tools': '도구',
     'docs.reference': '참조',
     'docs.navigation': '문서 탐색',
+    'docs.filter': '문서 목록 필터',
+    'docs.overview': '전체 문서',
+    'docs.article': '문서',
+    'docs.breadcrumb': '현재 위치',
+    'docs.focus': '집중 모드',
+    'docs.exitFocus': '집중 모드 종료',
     'docs.sourceRevision': '소스',
     'docs.previous': '이전 문서',
     'docs.next': '다음 문서',
diff --git a/frontend/src/pages/DocsPage.vue b/frontend/src/pages/DocsPage.vue
index 1a8c5a8..768ad00 100644
--- a/frontend/src/pages/DocsPage.vue
+++ b/frontend/src/pages/DocsPage.vue
@@ -1,9 +1,10 @@
 <script setup lang="ts">
-import { Search } from '@lucide/vue'
-import { computed, ref, watch, watchEffect } from 'vue'
+import { ArrowLeft, ArrowRight, BookOpen, ChevronRight, List, Maximize2, Minimize2 } from '@lucide/vue'
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch, watchEffect } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 
 import MarkdownContent from '../components/MarkdownContent.vue'
+import DocumentationTree from '../components/docs/DocumentationTree.vue'
 import { useI18n } from '../i18n'
 import { documentLocales, isDocumentLocale, saveDocumentLocale } from '../services/documentLocale'
 import { documentationCatalog, documentationPath, documentationProject, projectDocuments } from '../services/documentNavigation'
@@ -14,10 +15,14 @@ import UiSkeletonRows from '../ui/UiSkeletonRows.vue'
 
 const route = useRoute()
 const router = useRouter()
-const { locale, t } = useI18n()
+const { t } = useI18n()
 const documents = ref<DocumentSummary[]>([])
 const document = ref<DocumentView | null>(null)
 const query = ref('')
+const readingMode = ref(false)
+const article = ref<HTMLElement | null>(null)
+const mobileNavigation = ref<HTMLDetailsElement | null>(null)
+const activeHeading = ref('')
 const loading = ref(true)
 const failed = ref(false)
 const showingEnglishFallback = ref(false)
@@ -101,7 +106,31 @@ async function load() {
   }
 }
 
-watch([requestedPath, docLocale], () => { query.value = ''; void load() }, { immediate: true })
+watch([requestedPath, docLocale], () => {
+  query.value = ''
+  activeHeading.value = ''
+  if (mobileNavigation.value) mobileNavigation.value.open = false
+  void load()
+}, { immediate: true })
+
+let scrollFrame = 0
+function updateActiveHeading() {
+  const elements = article.value?.querySelectorAll<HTMLElement>('.document-content h2[id], .document-content h3[id], .document-content h4[id]')
+  if (!elements?.length) return
+  let selected = elements[0].id
+  for (const element of elements) {
+    if (element.getBoundingClientRect().top > 100) break
+    selected = element.id
+  }
+  activeHeading.value = selected
+}
+function onScroll() {
+  if (scrollFrame) return
+  scrollFrame = requestAnimationFrame(() => { scrollFrame = 0; updateActiveHeading() })
+}
+onMounted(() => window.addEventListener('scroll', onScroll, { passive: true }))
+onBeforeUnmount(() => { window.removeEventListener('scroll', onScroll); cancelAnimationFrame(scrollFrame) })
+watch([document, readingMode], async () => { await nextTick(); updateActiveHeading() })
 
 function changeDocumentLocale(event: Event) {
   const value = (event.target as HTMLSelectElement).value
@@ -150,68 +179,71 @@ watchEffect(() => {
 </script>
 
 <template>
-  <main class="docs-service">
+  <main class="docs-service" :class="{ 'docs-reading-mode': readingMode && document }">
     <header class="docs-service-header">
       <div class="docs-width docs-service-header-inner">
-        <div><RouterLink class="docs-service-title" :to="catalogBase">{{ t('docs.title') }}</RouterLink></div>
+        <RouterLink class="docs-service-title" :to="catalogBase"><BookOpen :size="19" aria-hidden="true" />{{ t('docs.title') }}</RouterLink>
+        <nav class="docs-project-tabs" :aria-label="t('docs.projectSelector')">
+          <RouterLink v-for="item in (['wave', 'stdlib', 'whale'] as const)" :key="item" :to="documentationCatalog(docLocale, item)" :class="{ active: project === item }" :aria-current="project === item ? 'page' : undefined">{{ projectLabel(item) }}</RouterLink>
+        </nav>
         <label class="docs-locale-select">
           <span>{{ t('docs.languageSelector') }}</span>
           <select :value="docLocale" @change="changeDocumentLocale">
             <option v-for="option in documentLocales" :key="option.id" :value="option.id">{{ option.label }}</option>
           </select>
         </label>
-        <label class="docs-search"><Search :size="16" aria-hidden="true" /><input v-model="query" :aria-label="t('docs.search')" :placeholder="t('docs.search')" /></label>
       </div>
-      <nav class="docs-width docs-project-tabs" :aria-label="t('docs.projectSelector')">
-        <RouterLink v-for="item in (['wave', 'stdlib', 'whale'] as const)" :key="item" :to="documentationCatalog(docLocale, item)" :class="{ active: project === item }" :aria-current="project === item ? 'page' : undefined">{{ projectLabel(item) }}</RouterLink>
-      </nav>
     </header>
 
     <div v-if="loading" class="docs-width docs-loading"><UiSkeletonRows :rows="8" /></div>
     <div v-else-if="failed" class="docs-width docs-loading"><UiInlineState :message="t('common.loadError')" :action="t('common.retry')" @action="load" /></div>
 
-    <div v-else-if="document" class="docs-width docs-reader-layout">
-      <aside class="docs-tree docs-tree-desktop" :aria-label="t('docs.navigation')">
-        <section v-for="group in groups" :key="group.id">
-          <strong>{{ group.title }}</strong>
-          <RouterLink v-for="item in group.items" :key="item.path" :to="`${docBase}/${item.path}`" :class="{ active: item.path === document.path }">{{ item.title }}</RouterLink>
-        </section>
+    <div v-else class="docs-width docs-reader-layout" :class="{ 'docs-catalog-layout': !document }">
+      <aside class="docs-tree docs-tree-desktop">
+        <DocumentationTree v-model="query" :groups="groups" :base="docBase" :catalog="catalogBase" :project-name="projectName" :current-path="currentPath" :active-group="document?.group" />
       </aside>
-
-      <details class="docs-tree-mobile">
-        <summary>{{ t('docs.navigation') }}</summary>
-        <div>
-          <section v-for="group in groups" :key="group.id">
-            <strong>{{ group.title }}</strong>
-            <RouterLink v-for="item in group.items" :key="item.path" :to="`${docBase}/${item.path}`" :class="{ active: item.path === document.path }">{{ item.title }}</RouterLink>
-          </section>
-        </div>
+      <details ref="mobileNavigation" class="docs-tree-mobile">
+        <summary><List :size="18" aria-hidden="true" />{{ t('docs.navigation') }}<ChevronRight :size="16" aria-hidden="true" /></summary>
+        <div><DocumentationTree v-model="query" :groups="groups" :base="docBase" :catalog="catalogBase" :project-name="projectName" :current-path="currentPath" :active-group="document?.group" /></div>
       </details>
 
-      <article class="document-page">
-        <nav class="document-breadcrumb"><RouterLink :to="catalogBase">{{ projectName }} {{ t('docs.title') }}</RouterLink><span>/</span><span>{{ groupName(document.group) }}</span></nav>
+      <article v-if="document" ref="article" class="document-page">
+        <div class="document-toolbar">
+          <nav class="document-breadcrumb" :aria-label="t('docs.breadcrumb')">
+            <RouterLink :to="catalogBase">{{ projectName }}</RouterLink><ChevronRight :size="12" aria-hidden="true" /><span>{{ groupName(document.group) }}</span>
+          </nav>
+          <button class="document-focus" type="button" :aria-pressed="readingMode" @click="readingMode = !readingMode">
+            <Minimize2 v-if="readingMode" :size="15" aria-hidden="true" /><Maximize2 v-else :size="15" aria-hidden="true" />{{ t(readingMode ? 'docs.exitFocus' : 'docs.focus') }}
+          </button>
+        </div>
         <p v-if="showingEnglishFallback" class="docs-translation-notice" role="status">{{ t('docs.englishFallback') }}</p>
-        <header><h1>{{ document.title }}</h1><p>{{ document.summary }}</p></header>
+        <header class="document-heading"><p class="document-eyebrow">{{ t('docs.article') }}</p><h1>{{ document.title }}</h1><p>{{ document.summary }}</p></header>
+        <details v-if="headings.length" class="docs-toc-inline">
+          <summary>{{ t('docs.contents') }}<ChevronRight :size="14" aria-hidden="true" /></summary>
+          <nav :aria-label="t('docs.contents')"><a v-for="heading in headings" :key="heading.anchor" :href="`#${heading.anchor}`" :class="`level-${heading.level}`">{{ heading.text }}</a></nav>
+        </details>
         <div class="document-content"><MarkdownContent :source="document.markdown" runnable /></div>
-        <nav class="document-pagination">
-          <RouterLink v-if="previous" :to="`${docBase}/${previous.path}`"><small>{{ t('docs.previous') }}</small><span>← {{ previous.title }}</span></RouterLink><span v-else />
-          <RouterLink v-if="next" :to="`${docBase}/${next.path}`"><small>{{ t('docs.next') }}</small><span>{{ next.title }} →</span></RouterLink>
+        <nav class="document-pagination" :aria-label="t('docs.navigation')">
+          <RouterLink v-if="previous" :to="`${docBase}/${previous.path}`"><small><ArrowLeft :size="14" aria-hidden="true" />{{ t('docs.previous') }}</small><span>{{ previous.title }}</span></RouterLink><span v-else />
+          <RouterLink v-if="next" :to="`${docBase}/${next.path}`"><small>{{ t('docs.next') }}<ArrowRight :size="14" aria-hidden="true" /></small><span>{{ next.title }}</span></RouterLink>
         </nav>
       </article>
 
-      <aside class="docs-toc" :aria-label="t('docs.contents')"><strong>{{ t('docs.contents') }}</strong><a v-for="heading in headings" :key="heading.anchor" :href="`#${heading.anchor}`" :class="`level-${heading.level}`">{{ heading.text }}</a></aside>
-    </div>
+      <aside v-if="document && headings.length" class="docs-toc">
+        <nav :aria-label="t('docs.contents')"><strong>{{ t('docs.contents') }}</strong><a v-for="heading in headings" :key="heading.anchor" :href="`#${heading.anchor}`" :class="[`level-${heading.level}`, { active: activeHeading === heading.anchor }]" :aria-current="activeHeading === heading.anchor ? 'location' : undefined">{{ heading.text }}</a></nav>
+      </aside>
 
-    <div v-else class="docs-width docs-catalog-page">
-      <header class="docs-titlebar"><h1>{{ projectName }} {{ t('docs.title') }}</h1><p>{{ project === 'stdlib' ? t('docs.stdlibLead') : project === 'whale' ? t('docs.whaleLead') : t('docs.lead') }}</p></header>
-      <p v-if="hasEnglishFallbackItems" class="docs-translation-notice" role="status">{{ t('docs.englishFallbackCatalog') }}</p>
-      <div class="docs-catalog">
-        <section v-for="group in groups" :key="group.id" class="docs-catalog-group">
-          <h2>{{ group.title }}</h2>
-          <ul><li v-for="item in group.items" :key="item.path"><RouterLink :to="`${docBase}/${item.path}`"><strong>{{ item.title }}</strong><span>{{ item.summary }}</span></RouterLink></li></ul>
-        </section>
-      </div>
-      <p v-if="groups.length === 0" class="docs-empty" role="status">{{ t(documents.length === 0 ? 'docs.emptyProject' : 'docs.noResults') }}</p>
+      <article v-if="!document" class="docs-catalog-page">
+        <header class="docs-titlebar"><p class="document-eyebrow">{{ t('docs.title') }}</p><h1>{{ projectName }} {{ t('docs.title') }}</h1><p>{{ project === 'stdlib' ? t('docs.stdlibLead') : project === 'whale' ? t('docs.whaleLead') : t('docs.lead') }}</p></header>
+        <p v-if="hasEnglishFallbackItems" class="docs-translation-notice" role="status">{{ t('docs.englishFallbackCatalog') }}</p>
+        <div class="docs-catalog">
+          <section v-for="group in groups" :key="group.id" class="docs-catalog-group">
+            <h2>{{ group.title }}</h2>
+            <ul><li v-for="item in group.items" :key="item.path"><RouterLink :to="`${docBase}/${item.path}`"><strong>{{ item.title }}</strong><span>{{ item.summary }}</span></RouterLink></li></ul>
+          </section>
+        </div>
+        <p v-if="groups.length === 0" class="docs-empty" role="status">{{ t(documents.length === 0 ? 'docs.emptyProject' : 'docs.noResults') }}</p>
+      </article>
     </div>
   </main>
 </template>
diff --git a/frontend/src/ui/service-pages.css b/frontend/src/ui/service-pages.css
index 0496215..78cac5e 100644
--- a/frontend/src/ui/service-pages.css
+++ b/frontend/src/ui/service-pages.css
@@ -616,71 +616,103 @@
 
 /* Documentation */
 .docs-service { min-height: 720px; background: var(--wave-surface); }
-.docs-service-header { border-bottom: 1px solid var(--wave-border); background: var(--wave-bg-subtle); }
-.docs-project-tabs { display: flex; flex-wrap: wrap; gap: 8px; }
-.docs-project-tabs a { display: inline-flex; align-items: center; min-height: 44px; padding: 8px 20px; border-bottom: 3px solid transparent; color: var(--wave-text-secondary); text-decoration: none; }
-.docs-project-tabs a.active { border-bottom-color: var(--wave-accent); color: var(--wave-text); font-weight: 700; }
-.docs-project-tabs a:hover { background: var(--wave-surface); }
-.docs-project-tabs a:focus-visible { outline: 2px solid var(--wave-focus); outline-offset: -3px; }
-.docs-service-header-inner { display: flex; min-height: 62px; align-items: center; justify-content: space-between; gap: 28px; }
-.docs-service-header-inner > div { display: flex; align-items: baseline; gap: 10px; }
-.docs-locale-select { display: grid; gap: 3px; margin-left: auto; color: var(--wave-text-muted); font-size: 11px; }
-.docs-locale-select select { min-width: 170px; border: 1px solid var(--wave-border-strong); border-radius: 5px; background: var(--wave-surface); color: var(--wave-text); padding: 7px 30px 7px 9px; font: inherit; font-size: 13px; }
-.docs-locale-select select:focus-visible { outline: 2px solid var(--wave-focus); outline-offset: 2px; }
-.docs-translation-notice { margin: 0 0 20px; border-left: 3px solid var(--wave-accent); background: var(--wave-bg-subtle); color: var(--wave-text-secondary); padding: 10px 12px; font-size: 13px; }
+.docs-service .docs-width { width: min(calc(100% - 48px), 1440px); }
+.docs-service-header { border-bottom: 1px solid var(--wave-border); background: var(--wave-surface); }
+.docs-service-header-inner { display: flex; align-items: center; gap: 32px; min-height: 64px; }
+.docs-service-title { display: inline-flex; align-items: center; gap: 9px; color: var(--wave-text); text-decoration: none; font-size: 18px; font-weight: 650; white-space: nowrap; }
+.docs-project-tabs { display: flex; align-self: stretch; gap: 24px; }
+.docs-project-tabs a { display: inline-flex; align-items: center; min-height: 44px; padding: 12px 2px; border-bottom: 2px solid transparent; color: var(--wave-text-secondary); font-size: 14px; text-decoration: none; }
+.docs-project-tabs a.active { border-bottom-color: var(--wave-accent); color: var(--wave-text); font-weight: 650; }
+.docs-project-tabs a:hover { color: var(--wave-accent); }
+.docs-locale-select { display: flex; align-items: center; gap: 10px; margin-left: auto; color: var(--wave-text-muted); font-size: 12px; }
+.docs-locale-select select { max-width: 215px; border: 1px solid var(--wave-border-strong); border-radius: 2px; background: var(--wave-surface); color: var(--wave-text); padding: 7px 24px 7px 9px; font: inherit; }
+.docs-service a:focus-visible, .docs-service button:focus-visible, .docs-service summary:focus-visible, .docs-locale-select select:focus-visible { outline: 2px solid var(--wave-focus); outline-offset: 2px; }
+.docs-translation-notice { margin: 16px 0 24px; border-left: 3px solid var(--wave-accent); background: var(--wave-bg-subtle); color: var(--wave-text-secondary); padding: 10px 14px; font-size: 13px; }
 .community-language-policy { margin: 0; border-left: 3px solid var(--wave-border-strong); background: var(--wave-bg-subtle); color: var(--wave-text-secondary); padding: 9px 11px; font-size: 12px; line-height: 1.5; }
-.docs-service-title { color: var(--wave-text); text-decoration: none; font-size: 19px; font-weight: 700; letter-spacing: -0.02em; }
-.docs-service-header span { color: var(--wave-text-muted); font-size: 12px; }
-.docs-search { display: flex; width: min(100%, 420px); height: 36px; align-items: center; gap: 8px; padding: 0 10px; border: 1px solid var(--wave-border-strong); border-radius: 4px; background: var(--wave-surface-raised); }
-.docs-search:focus-within { border-color: var(--service-accent); box-shadow: 0 0 0 2px var(--wave-accent-soft); }
-.docs-search svg { color: var(--wave-text-muted); }
-.docs-search input { width: 100%; border: 0; outline: 0; background: transparent; }
+.docs-search { display: flex; align-items: center; gap: 8px; min-height: 36px; width: 100%; margin: 14px 0 18px; padding: 0 9px; border: 1px solid var(--wave-border-strong); border-radius: 2px; background: var(--wave-surface); color: var(--wave-text-muted); }
+.docs-search:focus-within { outline: 2px solid var(--wave-focus); outline-offset: 1px; }
+.docs-search input { min-width: 0; width: 100%; padding: 6px 0; border: 0; outline: 0; background: transparent; color: var(--wave-text); font-size: 13px; }
+.docs-search input::placeholder { color: var(--wave-text-muted); }
 .docs-loading { padding: 32px 0; }
-.docs-catalog-page { padding: 34px 0 56px; }
-.docs-titlebar { padding-bottom: 22px; border-bottom: 1px solid var(--wave-border-strong); }
-.docs-titlebar h1 { margin: 0 0 6px; font-size: 27px; letter-spacing: -0.03em; }
-.docs-titlebar p { margin: 0; color: var(--wave-text-secondary); }
-.docs-catalog { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 48px; }
-.docs-catalog-group { padding: 26px 0 22px; border-bottom: 1px solid var(--wave-border); }
-.docs-catalog-group h2 { margin: 0 0 11px; font-size: 17px; }
-.docs-catalog-group ul { margin: 0; padding: 0; list-style: none; }
-.docs-catalog-group li { border-top: 1px solid var(--wave-border); }
-.docs-catalog-group li:first-child { border-top: 0; }
-.docs-catalog-group a { display: grid; gap: 2px; padding: 9px 8px; border-left: 2px solid transparent; color: var(--wave-text); text-decoration: none; }
-.docs-catalog-group a:hover { border-left-color: var(--service-accent); background: var(--wave-surface-hover); }
-.docs-catalog-group a strong { font-size: 14px; }
-.docs-catalog-group a span { color: var(--wave-text-secondary); font-size: 12px; line-height: 1.45; }
-.docs-empty { color: var(--wave-text-secondary); }
-.docs-reader-layout { display: grid; grid-template-columns: 246px minmax(0, 1fr) 210px; align-items: start; }
-.docs-tree, .docs-toc { position: sticky; top: 0; max-height: calc(100vh - 98px); overflow-y: auto; padding: 25px 18px 40px 0; }
+.docs-reader-layout { display: grid; grid-template-columns: 258px minmax(0, 1fr) 216px; align-items: start; column-gap: 36px; }
+.docs-catalog-layout { grid-template-columns: 258px minmax(0, 1fr); }
+.docs-tree, .docs-toc { position: sticky; top: 24px; max-height: calc(100dvh - 48px); overflow-y: auto; scrollbar-width: thin; }
+.docs-tree { padding: 30px 12px 40px 0; }
+.docs-tree-heading { color: var(--wave-text); font-size: 15px; font-weight: 650; }
 .docs-tree-mobile { display: none; }
-.docs-tree section { display: grid; margin-bottom: 20px; }
-.docs-tree strong, .docs-toc > strong { margin-bottom: 7px; color: var(--wave-text-muted); font-size: 11px; letter-spacing: .03em; text-transform: uppercase; }
-.docs-tree a { padding: 5px 9px; border-left: 2px solid transparent; color: var(--wave-text-secondary); font-size: 12px; line-height: 1.35; text-decoration: none; }
-.docs-tree a:hover { background: var(--wave-bg-subtle); color: var(--wave-text); }
-.docs-tree a.active { border-left-color: var(--service-accent); background: var(--wave-accent-soft); color: var(--wave-accent-text); font-weight: 680; }
-.document-page { min-width: 0; max-width: 860px; padding: 32px clamp(24px, 3vw, 44px) 64px; border-right: 1px solid var(--wave-border); border-left: 1px solid var(--wave-border); }
-.document-breadcrumb { display: flex; gap: 7px; margin-bottom: 22px; color: var(--wave-text-muted); font-size: 12px; }
-.document-breadcrumb a { color: var(--service-accent); text-decoration: none; }
-.document-page > header { padding-bottom: 10px; }
-.document-page > header h1 { margin: 0 0 10px; font-size: 30px; line-height: 1.25; letter-spacing: -.035em; }
-.document-page > header p { margin: 0; color: var(--wave-text-secondary); font-size: 15px; line-height: 1.6; }
-.document-page > header div { display: flex; flex-wrap: wrap; gap: 12px; margin-top: 12px; color: var(--wave-text-muted); font: 11px var(--wave-font-code); }
-.document-content { color: var(--wave-text); font-size: 16px; line-height: 1.8; overflow-wrap: anywhere; }
+.docs-tree-links { display: grid; gap: 4px; }
+.docs-tree-links details { min-width: 0; }
+.docs-tree-links summary { display: flex; align-items: flex-start; gap: 7px; padding: 8px 4px; color: var(--wave-text); font-size: 14px; font-weight: 600; line-height: 1.45; list-style: none; cursor: pointer; }
+.docs-tree-links summary::-webkit-details-marker { display: none; }
+.docs-tree-links summary svg { flex-shrink: 0; margin-top: 3px; }
+.docs-tree-links details[open] > summary svg { transform: rotate(90deg); }
+.docs-tree-group { display: grid; margin-left: 10px; padding-left: 7px; border-left: 1px solid var(--wave-border); }
+.docs-tree-links a { display: block; padding: 7px 10px; border-left: 2px solid transparent; color: var(--wave-text-secondary); font-size: 13px; line-height: 1.5; text-decoration: none; overflow-wrap: anywhere; }
+.docs-tree-links a:hover { color: var(--wave-accent); background: var(--wave-bg-subtle); }
+.docs-tree-links a[aria-current="page"] { border-left-color: var(--wave-accent); background: var(--wave-accent-soft); color: var(--wave-accent-text); font-weight: 600; }
+.docs-tree-links .docs-tree-overview { margin-bottom: 8px; }
+.docs-tree-empty { padding: 8px 4px; color: var(--wave-text-muted); font-size: 13px; }
+.document-page { min-width: 0; width: 100%; max-width: 860px; padding: 28px 0 72px; }
+.document-toolbar { display: flex; align-items: start; justify-content: space-between; flex-wrap: wrap; gap: 12px; margin-bottom: 30px; }
+.document-breadcrumb { display: flex; align-items: center; flex-wrap: wrap; gap: 7px; color: var(--wave-text-muted); font-size: 12px; }
+.document-breadcrumb a { color: var(--wave-accent); text-decoration: none; }
+.document-focus { display: inline-flex; align-items: center; gap: 6px; padding: 0; border: 0; background: transparent; color: var(--wave-text-secondary); cursor: pointer; font: inherit; font-size: 12px; }
+.document-focus:hover { color: var(--wave-accent); }
+.document-heading { padding-bottom: 18px; }
+.document-eyebrow { margin: 0 0 10px; color: var(--wave-text-muted); font-size: 12px; }
+.document-heading h1, .docs-titlebar h1 { margin: 0 0 18px; color: var(--wave-text); font-size: clamp(28px, 2.6vw, 38px); font-weight: 650; line-height: 1.25; letter-spacing: -.025em; overflow-wrap: anywhere; }
+.document-heading > p:last-child, .docs-titlebar > p:last-child { margin: 0; color: var(--wave-text-secondary); font-size: 16px; line-height: 1.65; }
+.document-content { color: var(--wave-text); font-size: 16px; line-height: 1.75; overflow-wrap: anywhere; }
 .document-content .markdown-content { width: 100%; min-width: 0; padding: 0; color: inherit; font: inherit; }
-.document-content h2 { margin: 32px 0 12px; padding-bottom: 0; border-bottom: 0; font-size: 22px; line-height: 1.35; }
-.document-content h3 { margin: 27px 0 9px; font-size: 18px; }
-.document-content p { margin: 10px 0 17px; }
-.document-content ul { margin: 10px 0 20px; padding-left: 24px; }
-.document-content li { margin: 5px 0; }
-.document-content blockquote { margin: 18px 0; padding: 11px 14px; border-left: 3px solid var(--service-accent); background: var(--wave-accent-soft); color: var(--wave-text-secondary); }
+.document-content .markdown-content h2 { margin: 36px 0 16px; padding: 0; border-bottom: 0; font-size: 27px; font-weight: 600; line-height: 1.35; letter-spacing: -.02em; scroll-margin-top: 28px; }
+.document-content .markdown-content h3 { margin: 28px 0 12px; font-size: 21px; font-weight: 600; line-height: 1.4; scroll-margin-top: 28px; }
+.document-content .markdown-content h4 { scroll-margin-top: 28px; }
+.document-content p { margin: 12px 0 20px; }
+.document-content ul { margin: 12px 0 20px; padding-left: 24px; }
+.document-content li { margin: 6px 0; }
+.document-content blockquote { margin: 20px 0; padding: 12px 16px; border-left: 3px solid var(--wave-accent); background: var(--wave-accent-soft); color: var(--wave-text-secondary); }
 .document-content blockquote p { margin: 3px 0; }
-.document-content pre { overflow-x: auto; margin: 17px 0 22px; padding: 18px 20px; border: 1px solid var(--wave-border); border-radius: 5px; background: var(--wave-bg-subtle); color: var(--wave-text); }
+.document-content pre { overflow-x: auto; margin: 20px 0; padding: 16px; border: 1px solid var(--wave-border); border-radius: 2px; background: var(--wave-bg-subtle); color: var(--wave-text); }
 .document-content pre code { color: inherit; font: 13px/1.65 var(--wave-font-code); font-variant-ligatures: none; white-space: pre; }
 .document-content pre .token.comment { color: var(--wave-syntax-comment); }.document-content pre .token.keyword { color: var(--wave-syntax-keyword); }.document-content pre .token.builtin { color: var(--wave-syntax-type); }.document-content pre .token.string { color: var(--wave-syntax-string); }.document-content pre .token.number { color: var(--wave-syntax-number); }.document-content pre .token.operator { color: var(--wave-syntax-keyword); }
-.document-content table { display: block; max-width: 100%; overflow-x: auto; margin: 18px 0 24px; border-collapse: collapse; font-size: 14px; }
-.document-content table th, .document-content table td { padding: 8px 10px; border: 1px solid var(--wave-border); text-align: left; vertical-align: top; }
-.document-content table th { background: var(--wave-bg-subtle); font-weight: 680; }
+.document-content table { display: block; max-width: 100%; overflow-x: auto; margin: 20px 0; border-collapse: collapse; font-size: 14px; }
+.document-content table th, .document-content table td { padding: 10px 12px; border: 1px solid var(--wave-border); text-align: left; vertical-align: top; }
+.document-content table th { background: var(--wave-bg-subtle); font-weight: 600; }
+.document-pagination { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px; margin-top: 48px; padding-top: 24px; border-top: 1px solid var(--wave-border); }
+.document-pagination a { display: grid; align-content: start; gap: 10px; color: var(--wave-text); text-decoration: none; }
+.document-pagination a:last-child { text-align: right; }
+.document-pagination small { display: flex; align-items: center; gap: 6px; color: var(--wave-text-muted); font-size: 12px; }
+.document-pagination a:last-child small { justify-content: flex-end; }
+.document-pagination span { color: var(--wave-accent); font-size: 14px; line-height: 1.5; }
+.docs-toc { padding: 34px 0 40px; }
+.docs-toc nav { display: grid; align-content: start; }
+.docs-toc strong { display: block; margin: 0 0 14px 12px; color: var(--wave-text); font-size: 14px; font-weight: 600; }
+.docs-toc a { padding: 6px 12px; border-left: 2px solid var(--wave-border); color: var(--wave-text-secondary); font-size: 12px; line-height: 1.5; text-decoration: none; }
+.docs-toc a.level-3, .docs-toc a.level-4 { padding-left: 22px; }
+.docs-toc a.active { border-left-color: var(--wave-accent); color: var(--wave-accent); font-weight: 600; }
+.docs-toc a:hover { color: var(--wave-accent); }
+.docs-toc-inline { display: none; margin: 8px 0 24px; border-block: 1px solid var(--wave-border); }
+.docs-toc-inline > summary { display: flex; align-items: center; justify-content: space-between; padding: 12px 0; color: var(--wave-text-secondary); font-size: 13px; list-style: none; cursor: pointer; }
+.docs-toc-inline > summary::-webkit-details-marker { display: none; }
+.docs-toc-inline[open] > summary svg { transform: rotate(90deg); }
+.docs-toc-inline nav { display: grid; gap: 8px; padding-bottom: 16px; }
+.docs-toc-inline a { color: var(--wave-accent); font-size: 13px; text-decoration: none; }
+.docs-toc-inline a.level-3, .docs-toc-inline a.level-4 { padding-left: 12px; }
+.docs-reading-mode .docs-reader-layout { display: block; max-width: 860px; }
+.docs-reading-mode .docs-tree-desktop, .docs-reading-mode .docs-toc { display: none; }
+.docs-catalog-page { min-width: 0; padding: 38px 0 72px; }
+.docs-titlebar { max-width: 780px; padding-bottom: 30px; border-bottom: 1px solid var(--wave-border); }
+.docs-catalog { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 32px; padding-top: 30px; }
+.docs-catalog-group { min-width: 0; }
+.docs-catalog-group h2 { margin: 0 0 16px; font-size: 21px; font-weight: 600; }
+.docs-catalog-group ul { margin: 0; padding: 0; list-style: none; }
+.docs-catalog-group li { border-top: 1px solid var(--wave-border); }
+.docs-catalog-group a { display: grid; gap: 6px; padding: 14px 0; color: var(--wave-accent); text-decoration: none; }
+.docs-catalog-group a:hover strong { text-decoration: underline; text-underline-offset: 3px; }
+.docs-catalog-group a strong { font-size: 15px; font-weight: 600; }
+.docs-catalog-group a span { color: var(--wave-text-secondary); font-size: 13px; line-height: 1.6; }
+.docs-empty { margin-top: 24px; color: var(--wave-text-secondary); }
+
 .document-notice { margin: 18px 0; padding: 12px 14px; border-left: 3px solid var(--service-accent); background: var(--wave-accent-soft); }
 .document-notice.warning { border-left-color: var(--wave-warning); background: var(--wave-warning-soft); }
 .document-notice strong { display: block; margin-bottom: 3px; font-size: 13px; }
@@ -694,14 +726,6 @@
 .document-table-wrap table { width: 100%; border-collapse: collapse; font-size: 13px; }
 .document-table-wrap th, .document-table-wrap td { padding: 8px 10px; border: 1px solid var(--wave-border); text-align: left; vertical-align: top; }
 .document-table-wrap th { background: var(--wave-bg-subtle); font-weight: 680; }
-.document-pagination { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px; margin-top: 44px; padding-top: 18px; border-top: 1px solid var(--wave-border-strong); }
-.document-pagination a { display: grid; gap: 3px; color: var(--wave-text); text-decoration: none; }
-.document-pagination a:last-child { text-align: right; }
-.document-pagination small { color: var(--wave-text-muted); }.document-pagination span { color: var(--service-accent); font-size: 13px; font-weight: 650; }
-.docs-toc { display: grid; align-content: start; padding-right: 0; padding-left: 20px; }
-.docs-toc a { padding: 4px 0; color: var(--wave-text-secondary); font-size: 12px; line-height: 1.4; text-decoration: none; }
-.docs-toc a.level-3 { padding-left: 10px; }
-.docs-toc a:hover { color: var(--service-accent); }
 
 /* Read-only Source mirror */
 .source-forge { min-height: calc(100vh - 97px); background: var(--wave-bg-canvas); }
@@ -928,9 +952,10 @@
   .source-about { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px; }
 	.mail-workspace { grid-template-columns: 200px 340px minmax(0, 1fr); }
 	.mailing-list-workspace { grid-template-columns: 220px 340px minmax(0, 1fr); }
-  .docs-reader-layout { grid-template-columns: 220px minmax(0, 1fr); }
+  .docs-reader-layout { grid-template-columns: 238px minmax(0, 1fr); column-gap: 32px; }
   .docs-toc { display: none; }
-  .document-page { max-width: none; border-right: 0; }
+  .docs-toc-inline { display: block; }
+  .document-page { max-width: none; }
 }
 
 @media (max-width: 800px) {
@@ -950,19 +975,21 @@
   .portal-intro { grid-template-columns: 1fr; gap: 24px; }
   .portal-modules { grid-template-columns: 1fr; gap: 30px; }
   .portal-module-pair { grid-template-columns: 1fr; gap: 30px; }
+  .docs-service .docs-width { width: calc(100% - 40px); }
   .docs-catalog { grid-template-columns: 1fr; }
-  .docs-reader-layout { width: 100%; grid-template-columns: 1fr; }
+  .docs-reader-layout { display: block; }
   .docs-tree-desktop { display: none; }
-  .docs-tree-mobile { display: block; border-bottom: 1px solid var(--wave-border); background: var(--wave-bg-subtle); }
-  .docs-tree-mobile summary { cursor: pointer; padding: 12px 20px; color: var(--wave-text-secondary); font-size: 13px; font-weight: 680; }
-  .docs-tree-mobile > div { max-height: 52vh; overflow-y: auto; padding: 4px 20px 18px; }
-  .docs-tree-mobile section { display: grid; margin-top: 14px; }
-  .docs-tree-mobile section > strong { margin-bottom: 6px; color: var(--wave-text-muted); font-size: 11px; text-transform: uppercase; }
-  .docs-tree-mobile a { padding: 6px 8px; border-left: 2px solid transparent; color: var(--wave-text-secondary); font-size: 13px; text-decoration: none; }
-  .docs-tree-mobile a.active { border-left-color: var(--service-accent); background: var(--wave-accent-soft); color: var(--wave-accent-text); font-weight: 680; }
-  .document-page { width: 100%; max-width: 100%; overflow: hidden; padding: 24px 20px 48px; border-left: 0; }
-  .document-page > header h1, .document-page > header p, .document-content, .document-content p { width: 100%; min-width: 0; max-width: 100%; overflow-wrap: anywhere; white-space: normal; }
+  .docs-tree-mobile { display: block; margin-top: 16px; border: 1px solid var(--wave-border); }
+  .docs-tree-mobile > summary { display: flex; align-items: center; gap: 8px; padding: 12px; color: var(--wave-text-secondary); font-size: 13px; list-style: none; cursor: pointer; }
+  .docs-tree-mobile > summary::-webkit-details-marker { display: none; }
+  .docs-tree-mobile > summary svg:last-child { margin-left: auto; }
+  .docs-tree-mobile[open] > summary svg:last-child { transform: rotate(90deg); }
+  .docs-tree-mobile > div { max-height: 60dvh; overflow-y: auto; padding: 12px; border-top: 1px solid var(--wave-border); }
+  .document-page { width: 100%; max-width: 100%; padding: 24px 0 48px; }
+  .document-toolbar { margin-bottom: 24px; }
+  .document-focus { display: none; }
   .document-content pre { max-width: 100%; }
+  .docs-catalog-page { padding: 28px 0 48px; }
   .community-workspace,
   .community-workspace.has-topics { grid-template-columns: 164px minmax(0, 1fr); }
 	.community-bar-inner { grid-template-columns: auto minmax(160px, 1fr) auto; gap: 12px; }
@@ -987,11 +1014,11 @@
 }
 
 @media (max-width: 600px) {
-	.docs-service-header-inner { display: grid; grid-template-columns: minmax(0, 1fr); gap: 8px; padding: 10px 12px; }
-	.docs-locale-select { margin-left: 0; }
-	.docs-locale-select span { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); }
-	.docs-locale-select select { min-width: 0; width: 100%; }
-	.docs-search { grid-column: 1 / -1; width: 100%; }
+  .docs-service-header-inner { flex-wrap: wrap; gap: 12px; padding-top: 12px; }
+  .docs-locale-select { order: 1; min-width: 0; }
+  .docs-locale-select span { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+  .docs-locale-select select { min-width: 0; max-width: 160px; }
+  .docs-project-tabs { order: 2; flex-basis: 100%; gap: 24px; }
 	.rfc-page { padding-top: 24px; }
 	.rfc-page-heading { align-items: stretch; flex-direction: column; }
 	.rfc-page-heading .ui-button { align-self: flex-start; }