From 1c10c4bf0e03e0d8069dca59f6104079be8f0b8d Mon Sep 17 00:00:00 2001
From: StarLand1 <canolhfv@gmail.com>
Date: Thu, 8 Oct 2026 17:29:32 +0800
Subject: [PATCH] feat(theme): adopt LobeHub-inspired documentation styles

---
 .github/workflows/build.yml                   |   6 +-
 .vitepress/theme/assets/docs-logo-dark.png    | Bin 0 -> 496 bytes
 .vitepress/theme/assets/docs-logo-light.png   | Bin 0 -> 547 bytes
 .vitepress/theme/components/DocBreadcrumb.vue |  80 ++++
 .vitepress/theme/components/DocHeader.vue     |  45 +-
 .../components/EmbeddedSidebarButton.vue      |   4 +-
 .vitepress/theme/document-ui.css              | 386 +++++++++++++++++
 .vitepress/theme/index.ts                     |  70 ++--
 .vitepress/theme/markdown.css                 | 388 ++++++++++++------
 .vitepress/theme/search.css                   |  78 +++-
 10 files changed, 878 insertions(+), 179 deletions(-)
 create mode 100644 .vitepress/theme/assets/docs-logo-dark.png
 create mode 100644 .vitepress/theme/assets/docs-logo-light.png
 create mode 100644 .vitepress/theme/components/DocBreadcrumb.vue
 create mode 100644 .vitepress/theme/document-ui.css

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index f20fcc61..3ea519c5 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -87,17 +87,17 @@ jobs:
     - name: set env
       if: ${{ github.event_name == 'pull_request' && github.repository	== 'deepflowio/docs' && github.event.pull_request.base.ref == 'main' }}
       run: |
-        echo "IMAGE_TAG_PREFIX=${{ github.event.pull_request.head.ref }}"|sed 's|main|latest|' >> $GITHUB_ENV
+        echo "IMAGE_TAG_PREFIX=${{ github.event.pull_request.head.ref }}"|sed 's|main|latest|; s|/|-|g' >> $GITHUB_ENV
 
     - name: set env
       if: ${{ github.event_name == 'push' && github.repository	== 'deepflowio/docs'}}
       run: |
-        echo "IMAGE_TAG_PREFIX=${{ github.ref_name }}"|sed 's|main|latest|' >> $GITHUB_ENV
+        echo "IMAGE_TAG_PREFIX=${{ github.ref_name }}"|sed 's|main|latest|; s|/|-|g' >> $GITHUB_ENV
 
     - name: set env
       if: ${{ github.event_name == 'workflow_dispatch' && github.repository	== 'deepflowio/docs'}}
       run: |
-        echo "IMAGE_TAG_PREFIX=${{ github.ref_name }}"|sed 's|main|latest|' >> $GITHUB_ENV
+        echo "IMAGE_TAG_PREFIX=${{ github.ref_name }}"|sed 's|main|latest|; s|/|-|g' >> $GITHUB_ENV
 
     - name: Build and push docs image
       if: ${{ github.repository == 'deepflowio/docs'}}
diff --git a/.vitepress/theme/assets/docs-logo-dark.png b/.vitepress/theme/assets/docs-logo-dark.png
new file mode 100644
index 0000000000000000000000000000000000000000..49b3967f7cd3144ae55dca582b143303a0c060bd
GIT binary patch
literal 496
zcmV<M0T2F(P)<h;3K|Lk000e1NJLTq001xm001xu1^@s6R|5Hm00009a7bBm000XU
z000XU0RWnu7ytkO0drDELIAGL9O(c600d`2O+f$vv5yP<VFdsH01k9TSaefwW^{L9
za%BKUX=iO=p0So=0004NNkl<ZcmeI1fo;Pe5Ji7Ffk$8jZ&WsDH)u9VH}MD_ff3vd
zTC7ls;KP7@fZE)Xz7!?oa|eWre1ISbA%oS2)nxUZsl|<dw^Etjroex;(#Sv+8pm|Q
zV<HM=3lfvT{sOTC@9)aGBX90Cm+u<mKn1TEC#kI~mB1Vf`ix~tFuDaW8Iw;)|5kjI
zizW2f5Kg3Uj5Rpw$ow9uBMgM!hU9<(M#68zImq}f!2q8N&QDm~?*)GxNuW1RmB1_L
z>(RK+O5yfPUZZ<OYU$-yvIBcn`3vQ6`z2RQgI=`-^k3a3ep1MKBMJ0I>Hwq;u=z<H
zpeC&DC)a3iB!S-i>jZM2%C$h{44UwG&)#ys7$H>$av5AKzSm3*ydqxOQ=<9<R02o)
z1EDk`nVvBXcQ1TzV)8cFL4mhNz%7H!W391$+}=|Y?nk`Z#Zt3B(3~3mf#$3`;wQ1-
me1D)h8uud=`+qM80s}uTmk^FnD-37=0000<MNUMnLSTY;u*=l|

literal 0
HcmV?d00001

diff --git a/.vitepress/theme/assets/docs-logo-light.png b/.vitepress/theme/assets/docs-logo-light.png
new file mode 100644
index 0000000000000000000000000000000000000000..9ce51d51596aae549c92be51e85bff8c3c1a1a62
GIT binary patch
literal 547
zcmV+;0^I$HP)<h;3K|Lk000e1NJLTq001xm001xu1^@s6R|5Hm00009a7bBm000XU
z000XU0RWnu7ytkO0drDELIAGL9O(c600d`2O+f$vv5yP<VFdsH01k9TSaefwW^{L9
za%BKUX=iO=p0So=0004=Nkl<ZcmeI1fpNni3`IpJ$Ov=;XM|2tcY}0-I1_Y)bQ5QT
zb_2YDy@4vu^bQm3fQ?Pl=-ug(!{j3oKt2S(Fw6i%+>ss0Y7D0}{SRa^P+MU*Uu0#7
z^D<I+jI$kx(XDYg3Y`fOP5_ENB&4AuJ84<6ifjjIXvp?Lh;GnI&X;&UR99hPzs_tv
z$%1B$`W4tufC?DA#v6OZ(U!)SfrhW6i-Z{%=UR`RZacsXu;2Uxe4VB{#0^+@0w`bs
zWBv)dgZ%^ABmx$&mEIHFIUGQ49wz|WL$4#pqteeHlGJ)Pk5QaXQf)51m?bool{<(h
ziC#<q@6f+U`35^dJW2F8k>!R1$PMR#*mFCz9_InzJg`iUkI~$40J-_U0bt;*+!o-(
zC7T_<#d-FDGjHcoVkYwFG=KX#Ryd!l`hYL><NW%7OX-ai)6@nuXHQ#=X;8M`Zhb({
zp1%2&@Hc75UMLASzYT*;tRIj))7Llft+RYwpnpHw+s-EgSF8_g4z5ri*c|hZw2t$O
l>I0i&Eh+7M2@J!m!VhMu6&iwl(g^?n002ovPDHLkV1nsj;t~J=

literal 0
HcmV?d00001

diff --git a/.vitepress/theme/components/DocBreadcrumb.vue b/.vitepress/theme/components/DocBreadcrumb.vue
new file mode 100644
index 00000000..c19e32ef
--- /dev/null
+++ b/.vitepress/theme/components/DocBreadcrumb.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useData, useRoute, withBase } from 'vitepress'
+import type { DefaultTheme } from 'vitepress'
+
+const { theme, page, lang } = useData()
+const route = useRoute()
+const isZh = computed(() => lang.value.startsWith('zh'))
+
+function normalize(path: string) {
+  return decodeURI(path.split(/[?#]/)[0]).replace(/\.(html|md)$/, '').replace(/\/$/, '')
+}
+
+function findPath(items: DefaultTheme.SidebarItem[], parents: DefaultTheme.SidebarItem[] = []): DefaultTheme.SidebarItem[] {
+  for (const item of items) {
+    const path = [...parents, item]
+    if (item.link && normalize(withBase(item.link)) === normalize(route.path)) return path
+    if (item.items) {
+      const found = findPath(item.items, path)
+      if (found.length) return found
+    }
+  }
+  return []
+}
+
+const crumbs = computed(() => {
+  const sidebar = theme.value.sidebar
+  if (!sidebar || typeof sidebar === 'string') return []
+  if (Array.isArray(sidebar)) return findPath(sidebar)
+  // A language or section may have its own sidebar; use the longest matching prefix.
+  const key = Object.keys(sidebar)
+    .filter(prefix => route.path.startsWith(withBase(prefix)))
+    .sort((a, b) => b.length - a.length)[0]
+  const value = key ? sidebar[key] : []
+  return findPath(Array.isArray(value) ? value : value?.items || [])
+})
+
+const title = computed(() => crumbs.value.at(-1)?.text || page.value.title)
+const parents = computed(() => crumbs.value.slice(0, -1))
+</script>
+
+<template>
+  <nav class="doc-breadcrumb" :aria-label="isZh ? '文档路径' : 'Breadcrumb'">
+    <a :href="withBase(isZh ? '/zh/' : '/')">{{ isZh ? '文档' : 'Docs' }}</a>
+    <template v-for="(item, index) in parents" :key="index">
+      <span class="separator" aria-hidden="true">/</span>
+      <a v-if="item.link" :href="withBase(item.link)">{{ item.text }}</a>
+      <span v-else>{{ item.text }}</span>
+    </template>
+    <span class="separator" aria-hidden="true">/</span>
+    <span class="current" aria-current="page">{{ title }}</span>
+  </nav>
+</template>
+
+<style scoped>
+.doc-breadcrumb {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  max-width: var(--df-md-reading-width);
+  margin: 0 auto 28px;
+  color: var(--df-md-text-3);
+  font-family: var(--df-md-font-sans);
+  font-size: 13px;
+  line-height: 1.6;
+  overflow-wrap: anywhere;
+}
+.doc-breadcrumb a { color: inherit; text-decoration: none; }
+.doc-breadcrumb a:hover { color: var(--df-md-primary-6); }
+.separator { color: var(--df-md-border-3); }
+.current { color: var(--df-md-text-1); }
+.doc-breadcrumb a:focus-visible {
+  outline: 2px solid var(--df-md-primary-6);
+  outline-offset: 3px;
+}
+@media (max-width: 959px) {
+  .doc-breadcrumb { margin-top: 8px; margin-bottom: 24px; }
+}
+</style>
diff --git a/.vitepress/theme/components/DocHeader.vue b/.vitepress/theme/components/DocHeader.vue
index b3d598b4..e076ac13 100644
--- a/.vitepress/theme/components/DocHeader.vue
+++ b/.vitepress/theme/components/DocHeader.vue
@@ -2,15 +2,30 @@
   <!-- doc-only 变体(build:doc-only)专属顶栏:常规构建也渲染本组件,但由
        custom.css 隐藏(html.doc-only 未标记时 .doc-header 不显示),与
        SiteNavbar 的显隐同由构建期写入 head 的 html 类驱动,无需构建开关。
-       布局:左 logo / 中搜索 / 右语言切换 + 明暗主题切换。
+       布局:左文档 Logo 和 Docs / 中搜索 / 右语言切换 + 明暗主题切换。
        搜索/语言/主题的实现与 SidebarActions 一致:点击唤起 VitePress 本地
        搜索、router 切换中英路径、翻转 isDark。配色走 VitePress 主题变量,
        随明暗主题自适应(区别于刻意的深色品牌导航 SiteNavbar) -->
   <header class="doc-header">
     <div class="doc-header-inner">
-      <a class="doc-brand" :href="docsHref" aria-label="DeepFlow Docs">
-        <img class="doc-brand-logo" :src="withBase('/img/logo.png')" alt="DeepFlow" />
-        <span class="doc-brand-name">DeepFlow</span>
+      <a class="doc-brand" :href="docsHref" aria-label="Docs">
+        <img
+          class="doc-brand-logo doc-brand-logo-on-light"
+          :src="darkLogo"
+          width="24"
+          height="24"
+          alt=""
+          aria-hidden="true"
+        />
+        <img
+          class="doc-brand-logo doc-brand-logo-on-dark"
+          :src="lightLogo"
+          width="24"
+          height="24"
+          alt=""
+          aria-hidden="true"
+        />
+        <span class="doc-brand-name">Docs</span>
       </a>
 
       <div class="doc-search-trigger">
@@ -78,7 +93,9 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue'
-import { useData, useRouter, withBase } from 'vitepress'
+import { useData, useRouter } from 'vitepress'
+import darkLogo from '../assets/docs-logo-dark.png'
+import lightLogo from '../assets/docs-logo-light.png'
 
 const { lang, site, isDark } = useData()
 const router = useRouter()
@@ -146,7 +163,7 @@ function openSearch() {
   padding: 0 20px;
 }
 
-/* 左:logo(彩色图标明暗主题均可用)+ 站名 */
+/* 左:文档 Logo + 站名。深色图案用于浅色主题,浅色图案用于深色主题。 */
 .doc-brand {
   display: inline-flex;
   align-items: center;
@@ -157,8 +174,20 @@ function openSearch() {
 }
 .doc-brand-logo {
   display: block;
-  width: 28px;
-  height: 28px;
+  flex-shrink: 0;
+  width: 24px;
+  height: 24px;
+  object-fit: contain;
+}
+/* Follow the html class set before the first frame to avoid hydration flicker. */
+.doc-brand-logo-on-dark {
+  display: none;
+}
+:global(html.dark .doc-brand-logo-on-light) {
+  display: none;
+}
+:global(html.dark .doc-brand-logo-on-dark) {
+  display: block;
 }
 .doc-brand-name {
   font-size: 17px;
diff --git a/.vitepress/theme/components/EmbeddedSidebarButton.vue b/.vitepress/theme/components/EmbeddedSidebarButton.vue
index 0fdb84a2..ec54ac91 100644
--- a/.vitepress/theme/components/EmbeddedSidebarButton.vue
+++ b/.vitepress/theme/components/EmbeddedSidebarButton.vue
@@ -1,7 +1,7 @@
 <template>
-  <!-- 嵌入式(iframe)模式下导航栏被隐藏,移动端用内容区左上角的悬浮按钮
+  <!-- 嵌入式(iframe)模式下导航栏被隐藏,移动端用面包屑同行的目录按钮
        展开侧边栏。默认隐藏,显隐规则在 custom.css 的 html.embedded 部分,
-       经 doc-top 插槽渲染(仅文档页存在,首页等无侧边栏页面天然没有) -->
+       经 doc-before 插槽渲染(仅文档页存在,首页等无侧边栏页面天然没有) -->
   <button
     type="button"
     class="embedded-sidebar-button"
diff --git a/.vitepress/theme/document-ui.css b/.vitepress/theme/document-ui.css
new file mode 100644
index 00000000..7afa46b9
--- /dev/null
+++ b/.vitepress/theme/document-ui.css
@@ -0,0 +1,386 @@
+/* Reading layout and navigation shared by normal and doc-only builds. */
+.Layout:has(.VPDoc) {
+  --vp-sidebar-width: 272px;
+  --df-doc-layout-width: 1360px;
+  --df-doc-side-space: max(24px, calc((100vw - var(--df-doc-layout-width)) / 2));
+  --df-doc-top-space: 40px;
+  --vp-font-family-base: var(--df-md-font-sans);
+  --vp-font-family-mono: var(--df-md-font-mono);
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPDoc > .container > .content {
+  min-width: 0;
+}
+
+.Layout:has(.VPDoc) .VPDoc .content-container {
+  max-width: var(--df-md-reading-width);
+}
+
+.Layout:has(.VPDoc) .VPDoc > .container {
+  max-width: 1056px;
+}
+
+.Layout:has(.VPDoc) .VPDoc .aside {
+  max-width: 240px;
+  padding-left: 40px;
+}
+
+.Layout:has(.VPDoc) .VPDoc .aside-container,
+.Layout:has(.VPDoc) .VPDoc .aside-curtain {
+  width: 200px;
+}
+
+.Layout:has(.VPDoc) .VPDoc .aside-container {
+  padding-top: calc(var(--vp-nav-height) + 48px);
+}
+
+.Layout:has(.VPDoc) .VPDocAsideOutline > .content {
+  padding: 0 0 0 16px;
+  border-color: var(--df-md-border-1);
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPDocAsideOutline .outline-title {
+  margin-bottom: 8px;
+  color: var(--df-md-text-1);
+  font-weight: var(--df-md-font-strong);
+}
+
+.Layout:has(.VPDoc) .VPDocAsideOutline .outline-link {
+  color: var(--df-md-text-2);
+  line-height: 28px;
+  font-size: 13px;
+}
+
+.Layout:has(.VPDoc) .VPDocAsideOutline .outline-link:hover {
+  color: var(--df-md-text-1);
+}
+
+.Layout:has(.VPDoc) .VPDocAsideOutline .outline-link.active {
+  color: var(--df-md-text-1);
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPDocAsideOutline .outline-marker {
+  background-color: var(--df-md-primary-6);
+}
+
+.Layout:has(.VPDoc) .VPSidebar {
+  font-family: var(--df-md-font-sans);
+  border-right: 1px solid var(--df-md-layout-divider);
+}
+
+.Layout:has(.VPDoc) .VPSidebar .group {
+  width: 100%;
+  padding: 12px 0 0;
+  border-top: 0;
+}
+
+.Layout:has(.VPDoc) .VPSidebar .group ~ .group {
+  padding-top: 0;
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem.level-0 {
+  padding-bottom: 0;
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem.level-0 > .item .text {
+  padding: 8px 0;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: var(--df-md-font-normal);
+  color: var(--df-md-text-2);
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem > .item {
+  width: calc(100% + 8px);
+  margin-left: -8px;
+  padding-left: 8px;
+  padding-right: 8px;
+  border-radius: 8px;
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem:not(.level-0) > .item .text {
+  padding: 8px 8px 8px 0;
+  line-height: 20px;
+  font-size: 14px;
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem > .item:hover,
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem.is-active > .item {
+  background-color: var(--df-md-fill-2);
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem.is-active > .item .text {
+  color: var(--df-md-text-1);
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem .items {
+  border-color: var(--df-md-sidebar-guide);
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem.level-0 > .items {
+  border-left: 1px solid var(--df-md-sidebar-guide);
+  padding-left: 16px;
+}
+
+.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem .caret {
+  align-self: center;
+  margin-right: -7px;
+  color: var(--df-md-text-3);
+}
+
+.Layout:has(.VPDoc) .VPSidebar .sidebar-actions {
+  width: 100%;
+  padding-bottom: 12px;
+  border-bottom: 0;
+}
+
+.Layout:has(.VPDoc) .sidebar-actions .search-box {
+  border-radius: 8px;
+  border-color: var(--df-md-search-border);
+  background: var(--df-md-search-bg);
+}
+
+.Layout:has(.VPDoc) .sidebar-actions .search-box:hover {
+  border-color: var(--df-md-search-hover-border);
+  background: var(--df-md-search-hover-bg);
+}
+
+.Layout:has(.VPDoc) :is(.sidebar-actions, .doc-header) .search-icon,
+.Layout:has(.VPDoc) .sidebar-actions .search-box::placeholder,
+.Layout:has(.VPDoc) .doc-header .doc-search::placeholder {
+  color: var(--df-md-search-text);
+  opacity: 1;
+}
+
+.Layout:has(.VPDoc) .sidebar-actions .search-box:focus {
+  border-color: var(--df-md-primary-6);
+}
+
+.Layout:has(.VPDoc) .sidebar-actions .theme-toggle {
+  border-radius: 8px;
+  border-color: var(--df-md-border-1);
+}
+
+.Layout:has(.VPDoc) .doc-header {
+  border-bottom-color: var(--df-md-layout-divider);
+  --vp-c-text-1: var(--df-md-text-1);
+  --vp-c-text-2: var(--df-md-text-2);
+  --vp-c-text-3: var(--df-md-text-3);
+  --vp-c-border: var(--df-md-border-1);
+  --vp-c-brand-1: var(--df-md-primary-6);
+  --vp-c-bg: var(--df-md-bg-1);
+  --vp-c-bg-soft: var(--df-md-fill-1);
+  font-family: var(--df-md-font-sans);
+}
+
+.Layout:has(.VPDoc) .doc-header .doc-search,
+.Layout:has(.VPDoc) .doc-header .theme-toggle,
+.Layout:has(.VPDoc) .doc-header .lang-switch-trigger {
+  border-radius: 8px;
+  border-color: var(--df-md-border-1);
+}
+
+.Layout:has(.VPDoc) .doc-header .doc-search {
+  border-color: var(--df-md-search-border);
+  background: var(--df-md-search-bg);
+}
+
+.Layout:has(.VPDoc) .doc-header .doc-search:hover,
+.Layout:has(.VPDoc) .doc-header .theme-toggle:hover,
+.Layout:has(.VPDoc) .doc-header .lang-switch-trigger:hover {
+  border-color: var(--df-md-border-2);
+  background-color: var(--df-md-fill-1);
+}
+
+.Layout:has(.VPDoc) .doc-header .doc-search:hover {
+  border-color: var(--df-md-search-hover-border);
+  background-color: var(--df-md-search-hover-bg);
+}
+
+.Layout:has(.VPDoc) .doc-header .doc-search:focus {
+  border-color: var(--df-md-primary-6);
+}
+
+.Layout:has(.VPDoc) .VPDocFooter {
+  margin-top: 56px;
+  font-family: var(--df-md-font-sans);
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .edit-link-button {
+  color: var(--df-md-text-3);
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .edit-link-button:hover {
+  color: var(--df-md-primary-6);
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .VPLastUpdated {
+  color: var(--df-md-text-3);
+  font-size: 13px;
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .prev-next {
+  border-color: var(--df-md-border-1);
+  padding-top: 24px;
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .pager-link {
+  padding: 16px 20px;
+  border-color: var(--df-md-border-1);
+  border-radius: 12px;
+  background-color: var(--df-md-bg-1);
+  transition: background-color 0.2s, border-color 0.2s;
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .pager-link:hover {
+  border-color: var(--df-md-border-2);
+  background-color: var(--df-md-fill-1);
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .pager-link .desc {
+  margin-bottom: 8px;
+  color: var(--df-md-text-3);
+  font-size: 13px;
+  font-weight: var(--df-md-font-normal);
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .pager-link .title {
+  color: var(--df-md-text-1);
+  font-size: 16px;
+  line-height: 1.5;
+  font-weight: 500;
+}
+
+.Layout:has(.VPDoc) .VPDocFooter .pager-link:hover .title {
+  color: var(--df-md-primary-6);
+}
+
+.Layout:has(.VPDoc) .embedded-sidebar-button,
+.Layout:has(.VPDoc) :is(.sidebar-actions, .doc-header) .theme-toggle {
+  color: var(--df-md-text-2);
+  background: var(--df-md-search-bg);
+  border-color: var(--df-md-search-border);
+}
+
+.Layout:has(.VPDoc) .embedded-sidebar-button:hover,
+.Layout:has(.VPDoc) :is(.sidebar-actions, .doc-header) .theme-toggle:hover {
+  color: var(--df-md-text-1);
+  background: var(--df-md-search-hover-bg);
+  border-color: var(--df-md-search-hover-border);
+}
+
+.Layout:has(.VPDoc) .embedded-sidebar-button:focus-visible,
+.Layout:has(.VPDoc) :is(.sidebar-actions, .doc-header) .theme-toggle:focus-visible {
+  outline: 2px solid var(--df-md-primary-6);
+  outline-offset: 2px;
+}
+
+.Layout:has(.VPDoc) .doc-heading-row {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  max-width: var(--df-md-reading-width);
+  margin: 0 auto 28px;
+}
+
+.Layout:has(.VPDoc) .doc-heading-row .doc-breadcrumb {
+  flex: 1;
+  min-width: 0;
+  margin: 0;
+}
+
+.Layout:has(.VPDoc) .doc-heading-row .embedded-sidebar-button {
+  position: absolute;
+  top: 50%;
+  /* Keep the menu at the viewport's left edge beside the centered reading column. */
+  left: calc((100% - 100vw) / 2 + 12px);
+  transform: translateY(-50%);
+  flex: none;
+}
+
+@media (max-width: 959px) {
+  .Layout:has(.VPDoc) .doc-heading-row {
+    min-height: 34px;
+    margin-bottom: 24px;
+  }
+
+  html.embedded .Layout:has(.VPDoc) .doc-heading-row .doc-breadcrumb {
+    /* Reserve space only when the centered column approaches the menu button. */
+    padding-left: max(0px, calc(58px - (100vw - 100%) / 2));
+  }
+}
+
+.Layout:has(.VPDoc) :is(.VPSidebar, .VPDocFooter, .doc-header, .embedded-sidebar-button) :is(a, button):focus-visible {
+  outline: 2px solid var(--df-md-primary-6);
+  outline-offset: 2px;
+}
+
+@media (min-width: 960px) {
+  /* Center the sidebar, reading column and outline using the same outer gutters. */
+  .Layout:has(.VPDoc) .VPContent.has-sidebar {
+    padding-left: calc(var(--df-doc-side-space) + var(--vp-sidebar-width));
+    padding-right: var(--df-doc-side-space);
+  }
+
+  .Layout:has(.VPDoc) .VPDoc {
+    padding: var(--df-doc-top-space) 24px 0;
+  }
+
+  .Layout:has(.VPDoc) .VPDoc > .container > .content {
+    padding: 0 16px 96px;
+  }
+
+  .Layout:has(.VPDoc) .VPSidebar {
+    left: var(--df-doc-side-space);
+    width: var(--vp-sidebar-width);
+    padding-left: 24px;
+    padding-right: 24px;
+  }
+
+  /* Exclude both 24px paddings and the 1px divider; keep this width when
+     a vertical scrollbar reduces the sidebar's available content width. */
+  .Layout:has(.VPDoc) .VPSidebar .nav {
+    width: calc(var(--vp-sidebar-width) - 48px - 1px);
+  }
+
+  /* Align the first label with the breadcrumb after the group's 12px
+     top padding and the label's 8px top padding. */
+  html.doc-only .Layout:has(.VPDoc) .VPSidebar .nav {
+    padding-top: calc(var(--df-doc-top-space) - 12px - 8px);
+  }
+}
+
+@media (min-width: 1280px) {
+  .Layout:has(.VPDoc) .VPDoc > .container > .content {
+    flex: 1 1 680px;
+    max-width: 744px;
+  }
+}
+
+@media (max-width: 639px) {
+  .Layout:has(.VPDoc) .VPDoc {
+    padding-left: 24px;
+    padding-right: 24px;
+  }
+
+  .Layout:has(.VPDoc) .VPDocFooter .pager-link {
+    padding: 14px 16px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .Layout:has(.VPDoc) *,
+  .VPLocalSearchBox * {
+    scroll-behavior: auto;
+    transition-duration: 0.01ms;
+    animation-duration: 0.01ms;
+  }
+}
diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts
index 51b61921..6e41fe51 100644
--- a/.vitepress/theme/index.ts
+++ b/.vitepress/theme/index.ts
@@ -1,4 +1,4 @@
-import { h, nextTick, onMounted, watch } from 'vue'
+import { defineComponent, h, nextTick, onMounted, watch } from 'vue'
 import { useRoute } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import mediumZoom from 'medium-zoom'
@@ -8,41 +8,47 @@ import SiteFooter from './components/SiteFooter.vue'
 import HomeHero from './components/HomeHero.vue'
 import EmbeddedSidebarButton from './components/EmbeddedSidebarButton.vue'
 import SidebarActions from './components/SidebarActions.vue'
+import DocBreadcrumb from './components/DocBreadcrumb.vue'
 import './custom.css'
 import './markdown.css'
+import './document-ui.css'
 import './search.css'
 
 export default {
   extends: DefaultTheme,
-  Layout: () => {
-    const route = useRoute()
-    const initZoom = () =>
-      mediumZoom('.vp-doc img:not(.no-zoom)', { background: 'var(--vp-c-bg)' })
-    onMounted(initZoom)
-    watch(
-      () => route.path,
-      () => nextTick(initZoom)
-    )
-    return h(DefaultTheme.Layout, null, {
-      // 顶部导航:还原旧版 DeepFlow 自定义导航栏(替代 VitePress 默认 navbar,
-      // 默认导航已在 custom.css 中隐藏)
-      'layout-top': () => [
-        h(SiteNavbar),
-        // doc-only 变体的 doc 专属顶栏:常规构建也渲染,但 html 未标记
-        // doc-only 时由 custom.css 隐藏(显隐机制与 SiteNavbar 一致)
-        h(DocHeader)
-      ],
-      // 首页 hero:还原旧版 vdoing Home 布局(单行大标题 + 描述)
-      'home-hero-info': () => h(HomeHero),
-      // 页脚:旧版深色链接矩阵 footer。组件内部按官方 VPFooter 的规则
-      // 只在无侧边栏的页面(首页/404)渲染,内容页不显示
-      'layout-bottom': () => h(SiteFooter),
-      // 嵌入式(iframe)移动端:内容区左上角的侧边栏悬浮按钮(默认隐藏,
-      // 仅 html.embedded 且 <960px 显示,见 custom.css)
-      'doc-top': () => h(EmbeddedSidebarButton),
-      // 侧边栏菜单上方的搜索 + 语言切换(自 SiteNavbar 迁来):iframe 嵌入
-      // 模式下导航栏整体隐藏,这两项能力常驻侧边栏保持可用
-      'sidebar-nav-before': () => h(SidebarActions)
-    })
-  }
+  Layout: defineComponent({
+    setup() {
+      const route = useRoute()
+      const initZoom = () =>
+        mediumZoom('.vp-doc img:not(.no-zoom)', { background: 'var(--vp-c-bg)' })
+      onMounted(initZoom)
+      watch(
+        () => route.path,
+        () => nextTick(initZoom)
+      )
+      return () => h(DefaultTheme.Layout, null, {
+        // 顶部导航:还原旧版 DeepFlow 自定义导航栏(替代 VitePress 默认 navbar,
+        // 默认导航已在 custom.css 中隐藏)
+        'layout-top': () => [
+          h(SiteNavbar),
+          // doc-only 变体的 doc 专属顶栏:常规构建也渲染,但 html 未标记
+          // doc-only 时由 custom.css 隐藏(显隐机制与 SiteNavbar 一致)
+          h(DocHeader)
+        ],
+        // 首页 hero:还原旧版 vdoing Home 布局(单行大标题 + 描述)
+        'home-hero-info': () => h(HomeHero),
+        // 页脚:旧版深色链接矩阵 footer。组件内部按官方 VPFooter 的规则
+        // 只在无侧边栏的页面(首页/404)渲染,内容页不显示
+        'layout-bottom': () => h(SiteFooter),
+        // 将嵌入模式的目录按钮与面包屑放在同一行。
+        'doc-before': () => h('div', { class: 'doc-heading-row' }, [
+          h(EmbeddedSidebarButton),
+          h(DocBreadcrumb)
+        ]),
+        // 侧边栏菜单上方的搜索 + 语言切换(自 SiteNavbar 迁来):iframe 嵌入
+        // 模式下导航栏整体隐藏,这两项能力常驻侧边栏保持可用
+        'sidebar-nav-before': () => h(SidebarActions)
+      })
+    }
+  })
 }
diff --git a/.vitepress/theme/markdown.css b/.vitepress/theme/markdown.css
index 022252b2..20ddca3f 100644
--- a/.vitepress/theme/markdown.css
+++ b/.vitepress/theme/markdown.css
@@ -1,66 +1,93 @@
-/* Shared DeepFlow Markdown styles for all VitePress documentation pages. */
+/* Documentation colors sampled from LobeHub docs (light and dark modes). */
 :root {
-  /* Semantic tokens from DeepFlow design.md — light mode. */
-  --df-md-bg-0: #e9ecf2;
-  --df-md-bg-0-1: #f4f5f7;
+  --df-md-font-sans: Geist, -apple-system, BlinkMacSystemFont, "Segoe UI Variable Display", "Segoe UI", Roboto, "Helvetica Neue", Arial, "HarmonyOS Sans SC", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", "Source Han Sans SC", "Noto Sans CJK SC", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+  --df-md-font-mono: "Geist Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, "Cascadia Code", Consolas, "Liberation Mono", monospace;
+  --df-md-font-normal: 400;
+  --df-md-font-strong: 600;
+  --df-md-font-heading: 700;
+  --df-md-reading-width: 680px;
+  --df-md-bg-0: #f8f8f8;
+  --df-md-bg-0-1: #f5f5f5;
   --df-md-bg-1: #ffffff;
-  --df-md-bg-2: #ffffff;
+  --df-md-bg-2: rgba(0, 0, 0, 0.016);
   --df-md-bg-4: #ffffff;
-  --df-md-fill-1: #f4f5f7;
-  --df-md-fill-2: #e9ecf2;
-  --df-md-fill-3: #d8dce5;
-  --df-md-border-1: #e9ecf2;
-  --df-md-border-2: #d8dce5;
-  --df-md-border-3: #c1c9d6;
-  --df-md-sidebar-divider: #d8dce5;
-  --df-md-text-1: #18212e;
-  --df-md-text-2: #3c485c;
-  --df-md-text-3: #5a677a;
-  --df-md-primary-6: #5a65f6;
-  --df-md-primary-link: #5a65f6;
-  --df-md-primary-hover: #4f46e5;
+  --df-md-fill-1: rgba(0, 0, 0, 0.03);
+  --df-md-fill-2: rgba(0, 0, 0, 0.06);
+  --df-md-fill-3: rgba(0, 0, 0, 0.12);
+  --df-md-border-1: #eeeeee;
+  --df-md-border-2: #e3e3e3;
+  --df-md-border-3: #dddddd;
+  --df-md-inline-code-border: var(--df-md-border-1);
+  --df-md-layout-divider: var(--df-md-border-1);
+  --df-md-sidebar-divider: var(--df-md-border-1);
+  --df-md-sidebar-guide: #d4d4d4;
+  --df-md-search-bg: var(--df-md-bg-1);
+  --df-md-search-border: var(--df-md-border-1);
+  --df-md-search-text: var(--df-md-text-3);
+  --df-md-search-hover-bg: var(--df-md-fill-1);
+  --df-md-search-hover-border: var(--df-md-border-2);
+  --df-md-text-1: #080808;
+  --df-md-text-2: #666666;
+  --df-md-text-3: #999999;
+  --df-md-primary-6: #222222;
+  --df-md-primary-hover: #333333;
+  --df-md-primary-link: #0072f5;
+  --df-md-link-hover: #4c90ff;
   --df-md-text-on-primary: #ffffff;
-  --df-md-mask-bg: rgba(0, 0, 0, 0.7);
-  --df-md-success-border: #aff0b5;
-  --df-md-success-bg: #e8ffea;
-  --df-md-success-text: #008026;
-  --df-md-warning-border: #ffe4ba;
-  --df-md-warning-bg: #fff7e8;
-  --df-md-warning-text: #d96a00;
-  --df-md-danger-border: #fdcdc5;
-  --df-md-danger-bg: #ffece8;
-  --df-md-danger-text: #da3838;
+  --df-md-mask-bg: rgba(0, 0, 0, 0.44);
+  --df-md-info-bg: #e6f4ff;
+  --df-md-info-border: #91caff;
+  --df-md-success-border: #c7eabd;
+  --df-md-success-bg: #f4fdeb;
+  --df-md-success-text: #379d4a;
+  --df-md-warning-border: #ffd591;
+  /* Give warning callouts a visible amber tint on the white canvas. */
+  --df-md-warning-bg: #fff7e6;
+  --df-md-warning-text: #ee9e0b;
+  --df-md-danger-border: #ffcec5;
+  --df-md-danger-bg: #fff7f6;
+  --df-md-danger-text: #ec5e41;
 }
 
 .dark {
-  /* The same roles resolve to the dark values in DeepFlow design.md. */
-  --df-md-bg-0: #11151f;
-  --df-md-bg-0-1: #161b29;
-  --df-md-bg-1: #11151f;
-  --df-md-bg-2: #161b29;
-  --df-md-bg-4: #1f283d;
-  --df-md-fill-1: rgba(255, 255, 255, 0.04);
-  --df-md-fill-2: rgba(255, 255, 255, 0.08);
-  --df-md-fill-3: rgba(255, 255, 255, 0.12);
-  --df-md-border-1: #1e293b;
-  --df-md-border-2: #2a3646;
-  --df-md-border-3: #475569;
-  --df-md-sidebar-divider: #1e293b;
-  --df-md-text-1: #e2e8f0;
-  --df-md-text-2: #cbd5e1;
-  --df-md-text-3: #94a3b8;
-  --df-md-primary-6: #5a65f6;
-  --df-md-primary-link: #5a65f6;
-  --df-md-primary-hover: #b1b3fa;
-  --df-md-success-border: #0a802d;
-  --df-md-success-bg: rgba(0, 180, 42, 0.12);
-  --df-md-success-text: #b2f0b7;
-  --df-md-warning-border: #a64b0a;
-  --df-md-warning-bg: rgba(255, 125, 0, 0.12);
-  --df-md-warning-text: #ff7d00;
-  --df-md-danger-border: #a1161f;
-  --df-md-danger-bg: rgba(245, 63, 63, 0.12);
-  --df-md-danger-text: #f53f3f;
+  --df-md-bg-0: #000000;
+  --df-md-bg-0-1: #141414;
+  --df-md-bg-1: #151518;
+  --df-md-bg-2: rgba(255, 255, 255, 0.02);
+  --df-md-bg-4: #1a1a1a;
+  --df-md-fill-1: rgba(255, 255, 255, 0.06);
+  --df-md-fill-2: rgba(255, 255, 255, 0.10);
+  --df-md-fill-3: rgba(255, 255, 255, 0.16);
+  --df-md-border-1: #1a1a1a;
+  --df-md-border-2: #202020;
+  --df-md-border-3: #333333;
+  --df-md-inline-code-border: var(--df-md-border-2);
+  --df-md-layout-divider: var(--df-md-border-3);
+  --df-md-sidebar-guide: #444448;
+  --df-md-search-bg: #222226;
+  --df-md-search-border: #444448;
+  --df-md-search-text: var(--df-md-text-2);
+  --df-md-search-hover-bg: #2b2b30;
+  --df-md-search-hover-border: #66666c;
+  --df-md-text-1: #ffffff;
+  --df-md-text-2: #aaaaaa;
+  --df-md-text-3: #6f6f6f;
+  --df-md-primary-6: #eeeeee;
+  --df-md-primary-hover: #ffffff;
+  --df-md-primary-link: #0072f5;
+  --df-md-link-hover: #a7d3ff;
+  --df-md-text-on-primary: #080808;
+  --df-md-info-bg: #111f33;
+  --df-md-info-border: #244d75;
+  --df-md-success-border: #4b6800;
+  --df-md-success-bg: #142100;
+  --df-md-success-text: #c4f042;
+  --df-md-warning-border: #916400;
+  --df-md-warning-bg: #2a1b00;
+  --df-md-warning-text: #ffb224;
+  --df-md-danger-border: #9d0042;
+  --df-md-danger-bg: #380015;
+  --df-md-danger-text: #f4416c;
 }
 
 body:has(.VPDoc) {
@@ -68,7 +95,7 @@ body:has(.VPDoc) {
 }
 
 .Layout:has(.VPDoc) .VPSidebar {
-  --vp-sidebar-bg-color: var(--df-md-bg-0-1);
+  --vp-sidebar-bg-color: var(--df-md-bg-1);
   --vp-c-text-1: var(--df-md-text-1);
   --vp-c-text-2: var(--df-md-text-2);
   --vp-c-text-3: var(--df-md-text-3);
@@ -91,28 +118,32 @@ body:has(.VPDoc) {
   --shadow-1: none;
 }
 
-.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem.level-1.is-link > .item {
-  width: calc(100% + 8px);
-  margin-left: -8px;
-  padding-left: 8px;
-}
-
-.Layout:has(.VPDoc) .VPSidebar .VPSidebarItem.level-1.is-link > .item:hover {
-  border-radius: 4px;
-  background-color: var(--df-md-fill-3);
-}
-
 .Layout:has(.VPDoc) .VPDoc {
   --vp-c-brand-1: var(--df-md-primary-link);
-  --vp-c-brand-2: var(--df-md-primary-hover);
+  --vp-c-brand-2: var(--df-md-link-hover);
+  --vp-c-text-1: var(--df-md-text-1);
+  --vp-c-text-2: var(--df-md-text-2);
+  --vp-c-text-3: var(--df-md-text-3);
+  --vp-c-divider: var(--df-md-border-1);
+  --vp-c-border: var(--df-md-border-2);
+  --vp-c-bg-soft: var(--df-md-fill-1);
+  font-family: var(--df-md-font-sans);
 }
 
 .Layout:has(.VPDoc) .vp-doc {
   --vp-code-font-size: 1em;
+  --vp-code-line-height: 1.8;
   --vp-code-color: var(--df-md-text-1);
-  --vp-code-bg: var(--df-md-fill-1);
+  --vp-code-bg: var(--df-md-fill-2);
   --vp-code-block-bg: var(--df-md-bg-2);
   --vp-code-block-divider-color: var(--df-md-border-2);
+  --vp-code-line-highlight-color: var(--df-md-fill-1);
+  --vp-code-line-error-color: var(--df-md-danger-bg);
+  --vp-code-line-warning-color: var(--df-md-warning-bg);
+  --vp-code-line-diff-add-color: var(--df-md-success-bg);
+  --vp-code-line-diff-add-symbol-color: var(--df-md-success-text);
+  --vp-code-line-diff-remove-color: var(--df-md-danger-bg);
+  --vp-code-line-diff-remove-symbol-color: var(--df-md-danger-text);
   --vp-code-tab-bg: var(--df-md-fill-1);
   --vp-code-tab-divider: var(--df-md-border-1);
   --vp-code-tab-text-color: var(--df-md-text-3);
@@ -123,10 +154,11 @@ body:has(.VPDoc) {
   --vp-code-copy-code-bg: var(--df-md-fill-1);
   --vp-code-copy-code-hover-border-color: var(--df-md-primary-6);
   --vp-code-copy-code-hover-bg: var(--df-md-fill-2);
-  color: var(--df-md-text-2);
-  font-family: "PingFang SC", "Microsoft YaHei", system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+  color: var(--df-md-text-1);
+  font-family: var(--df-md-font-sans);
+  font-weight: var(--df-md-font-normal);
   font-size: 16px;
-  line-height: 1.7;
+  line-height: 1.8;
   overflow-wrap: break-word;
 }
 
@@ -142,25 +174,31 @@ body:has(.VPDoc) {
 .Layout:has(.VPDoc) .vp-doc h1,
 .Layout:has(.VPDoc) .vp-doc h2,
 .Layout:has(.VPDoc) .vp-doc h3,
-.Layout:has(.VPDoc) .vp-doc h4 {
+.Layout:has(.VPDoc) .vp-doc h4,
+.Layout:has(.VPDoc) .vp-doc h5,
+.Layout:has(.VPDoc) .vp-doc h6 {
   color: var(--df-md-text-1);
-  font-weight: 500;
-  letter-spacing: -0.02em;
+  font-weight: var(--df-md-font-heading);
+  letter-spacing: normal;
 }
 
 .Layout:has(.VPDoc) .vp-doc h1 {
-  margin: 0 0 20px;
-  font-size: 32px;
-  line-height: 1.3;
+  margin: 0 0 24px;
+  font-size: 40px;
+  line-height: 1.25;
 }
 
-.Layout:has(.VPDoc) .vp-doc h2 {
-  --df-md-heading-padding-top: 16px;
+.Layout:has(.VPDoc) .vp-doc h1 ~ h1 {
   margin-top: 48px;
+}
+
+.Layout:has(.VPDoc) .vp-doc h2 {
+  --df-md-heading-padding-top: 0px;
+  margin: 40px 0 20px;
   padding-top: var(--df-md-heading-padding-top);
-  border-top: 1px solid var(--df-md-border-1);
-  font-size: 24px;
-  line-height: 1.35;
+  border-top: 0;
+  font-size: 32px;
+  line-height: 1.25;
 }
 
 .Layout:has(.VPDoc) .vp-doc h2 .header-anchor {
@@ -168,18 +206,27 @@ body:has(.VPDoc) {
 }
 
 .Layout:has(.VPDoc) .vp-doc h3 {
-  margin-top: 32px;
+  margin: 32px 0 16px;
+  font-size: 24px;
+  line-height: 1.25;
+}
+
+.Layout:has(.VPDoc) .vp-doc h4 {
+  margin: 28px 0 12px;
   font-size: 20px;
   line-height: 1.4;
 }
 
-.Layout:has(.VPDoc) .vp-doc h4 {
+.Layout:has(.VPDoc) .vp-doc h5,
+.Layout:has(.VPDoc) .vp-doc h6 {
+  margin: 24px 0 12px;
   font-size: 16px;
+  line-height: 1.5;
 }
 
 .Layout:has(.VPDoc) .vp-doc p,
 .Layout:has(.VPDoc) .vp-doc li {
-  line-height: 1.7;
+  line-height: 1.8;
 }
 
 .Layout:has(.VPDoc) .vp-doc p {
@@ -188,19 +235,20 @@ body:has(.VPDoc) {
 
 .Layout:has(.VPDoc) .vp-doc strong {
   color: var(--df-md-text-1);
-  font-weight: 500;
+  font-weight: var(--df-md-font-strong);
 }
 
 .Layout:has(.VPDoc) .vp-doc a:not(.header-anchor) {
   color: var(--df-md-primary-link);
+  font-weight: inherit;
   text-decoration-color: var(--df-md-primary-link);
   text-decoration-thickness: 1px;
   text-underline-offset: 3px;
 }
 
 .Layout:has(.VPDoc) .vp-doc a:not(.header-anchor):hover {
-  color: var(--df-md-primary-hover);
-  text-decoration-color: var(--df-md-primary-hover);
+  color: var(--df-md-link-hover);
+  text-decoration-color: var(--df-md-link-hover);
 }
 
 .Layout:has(.VPDoc) .vp-doc a:focus-visible,
@@ -212,20 +260,20 @@ body:has(.VPDoc) {
 
 .Layout:has(.VPDoc) .vp-doc :not(pre) > code {
   padding: 0.14em 0.34em;
-  border: 1px solid var(--df-md-border-1);
+  border: 1px solid var(--df-md-inline-code-border);
   border-radius: 4px;
-  background-color: var(--df-md-fill-1);
+  background-color: var(--vp-code-bg);
   color: var(--df-md-text-1);
   font-size: var(--vp-code-font-size);
-  font-weight: 500;
+  font-weight: var(--df-md-font-normal);
   overflow-wrap: break-word;
 }
 
 .Layout:has(.VPDoc) .vp-doc blockquote {
   margin: 24px 0;
   padding: 8px 0 8px 16px;
-  border-left: 2px solid var(--df-md-primary-6);
-  color: var(--df-md-text-3);
+  border-left: 2px solid var(--df-md-border-3);
+  color: var(--df-md-text-2);
 }
 
 .Layout:has(.VPDoc) .vp-doc blockquote p {
@@ -251,7 +299,7 @@ body:has(.VPDoc) {
 }
 
 .Layout:has(.VPDoc) .vp-doc li::marker {
-  color: var(--df-md-primary-link);
+  color: var(--df-md-text-3);
 }
 
 .Layout:has(.VPDoc) .vp-doc input[type='checkbox'] {
@@ -261,14 +309,14 @@ body:has(.VPDoc) {
 .Layout:has(.VPDoc) .vp-doc div[class*='language-'] {
   margin: 20px 0 24px;
   border: 1px solid var(--df-md-border-1);
-  border-radius: 6px;
+  border-radius: 12px;
   background-color: var(--df-md-bg-2);
   box-shadow: none;
 }
 
 .Layout:has(.VPDoc) .vp-doc div[class*='language-'] pre {
-  font-size: 13px;
-  line-height: 1.7;
+  font-size: 14px;
+  line-height: 1.8;
 }
 
 .Layout:has(.VPDoc) .vp-doc .vp-code-group {
@@ -278,39 +326,39 @@ body:has(.VPDoc) {
 .Layout:has(.VPDoc) .vp-doc .vp-code-group .tabs {
   border: 1px solid var(--df-md-border-1);
   border-bottom: 0;
-  border-radius: 6px 6px 0 0;
+  border-radius: 12px 12px 0 0;
 }
 
 .Layout:has(.VPDoc) .vp-doc .vp-code-group div[class*='language-'] {
   margin: 0;
-  border-radius: 0 0 6px 6px;
+  border-radius: 0 0 12px 12px;
 }
 
 .Layout:has(.VPDoc) .vp-doc table {
-  display: table;
-  width: 100%;
+  display: block;
+  width: fit-content;
   max-width: 100%;
   margin: 20px 0 24px;
   overflow-x: auto;
   border: 1px solid var(--df-md-border-1);
-  border-radius: 6px;
+  border-radius: 12px;
   border-collapse: separate;
   border-spacing: 0;
-  font-size: 14px;
+  font-size: 16px;
 }
 
 .Layout:has(.VPDoc) .vp-doc tr,
 .Layout:has(.VPDoc) .vp-doc tr:nth-child(2n) {
   border: 0;
-  background-color: var(--df-md-bg-2);
+  background-color: var(--df-md-bg-1);
 }
 
 .Layout:has(.VPDoc) .vp-doc th,
 .Layout:has(.VPDoc) .vp-doc td {
-  padding: 10px 12px;
+  padding: 12px 16px;
   border: 0;
   border-bottom: 1px solid var(--df-md-border-1);
-  color: var(--df-md-text-2);
+  color: var(--df-md-text-1);
   text-align: left;
   vertical-align: top;
 }
@@ -318,8 +366,8 @@ body:has(.VPDoc) {
 .Layout:has(.VPDoc) .vp-doc th {
   background-color: var(--df-md-fill-1);
   color: var(--df-md-text-1);
-  font-size: 14px;
-  font-weight: 500;
+  font-size: inherit;
+  font-weight: var(--df-md-font-heading);
 }
 
 .Layout:has(.VPDoc) .vp-doc tr:last-child td {
@@ -328,11 +376,11 @@ body:has(.VPDoc) {
 
 .Layout:has(.VPDoc) .vp-doc .custom-block {
   margin: 20px 0;
-  padding: 14px 16px;
+  padding: 12px 16px;
   border: 1px solid var(--df-md-border-1);
-  border-radius: 6px;
+  border-radius: 12px;
   background-color: var(--df-md-fill-1);
-  color: var(--df-md-text-2);
+  color: var(--df-md-text-1);
   box-shadow: none;
 }
 
@@ -381,7 +429,8 @@ body:has(.VPDoc) {
 
 .Layout:has(.VPDoc) .vp-doc .custom-block-title {
   color: var(--df-md-text-1);
-  font-weight: 500;
+  font-size: 14px;
+  font-weight: var(--df-md-font-strong);
 }
 
 .Layout:has(.VPDoc) .vp-doc .custom-block.tip .custom-block-title,
@@ -390,7 +439,9 @@ body:has(.VPDoc) {
 }
 
 .Layout:has(.VPDoc) .vp-doc .custom-block.tip .custom-block-title,
+.Layout:has(.VPDoc) .vp-doc .custom-block.info .custom-block-title,
 .Layout:has(.VPDoc) .vp-doc .custom-block.warning .custom-block-title,
+.Layout:has(.VPDoc) .vp-doc .custom-block.success .custom-block-title,
 .Layout:has(.VPDoc) .vp-doc .custom-block.danger .custom-block-title {
   display: flex;
   align-items: center;
@@ -398,6 +449,8 @@ body:has(.VPDoc) {
 }
 
 .Layout:has(.VPDoc) .vp-doc .custom-block.tip .custom-block-title::before,
+.Layout:has(.VPDoc) .vp-doc .custom-block.info .custom-block-title::before,
+.Layout:has(.VPDoc) .vp-doc .custom-block.success .custom-block-title::before,
 .Layout:has(.VPDoc) .vp-doc .custom-block.warning .custom-block-title::before,
 .Layout:has(.VPDoc) .vp-doc .custom-block.danger .custom-block-title::before {
   content: '';
@@ -420,7 +473,7 @@ body:has(.VPDoc) {
 
 .Layout:has(.VPDoc) .vp-doc .custom-block p {
   color: var(--df-md-text-2);
-  line-height: 1.7;
+  line-height: 1.8;
 }
 
 .Layout:has(.VPDoc) .vp-doc .footnotes {
@@ -432,22 +485,117 @@ body:has(.VPDoc) {
   border-color: var(--df-md-border-1);
 }
 
+/* Smaller Markdown elements, media and legacy content use the same palette. */
+.Layout:has(.VPDoc) .vp-doc :is(hr, .footnotes-sep) {
+  height: 0;
+  margin: 32px 0;
+  border: 0;
+  border-top: 1px solid var(--df-md-border-1);
+}
+
+.Layout:has(.VPDoc) .vp-doc :is(h1, h2, h3, h4, h5, h6) .header-anchor {
+  color: var(--df-md-primary-link);
+  font-weight: var(--df-md-font-heading);
+}
+
+.Layout:has(.VPDoc) .vp-doc li + li { margin-top: 6px; }
+.Layout:has(.VPDoc) .vp-doc li > :is(ul, ol) { margin: 8px 0; }
+.Layout:has(.VPDoc) .vp-doc .contains-task-list { list-style: none; padding-left: 0; }
+.Layout:has(.VPDoc) .vp-doc .task-list-item { padding-left: 0; }
+.Layout:has(.VPDoc) .vp-doc .task-list-item input { margin-right: 8px; }
+
+.Layout:has(.VPDoc) .vp-doc kbd {
+  padding: 2px 6px;
+  border: 1px solid var(--df-md-border-2);
+  border-radius: 4px;
+  background: var(--df-md-fill-1);
+  color: var(--df-md-text-2);
+  font-size: 13px;
+}
+
+.Layout:has(.VPDoc) .vp-doc mark {
+  padding: 1px 3px;
+  border-radius: 3px;
+  background: var(--df-md-warning-bg);
+  color: var(--df-md-text-1);
+}
+
+.Layout:has(.VPDoc) .vp-doc :is(s, del) { color: var(--df-md-text-3); }
+.Layout:has(.VPDoc) .vp-doc sup,
+.Layout:has(.VPDoc) .vp-doc sub { line-height: 0; }
+
+.Layout:has(.VPDoc) .vp-doc div[class*='language-'] .line-numbers-wrapper {
+  border-color: var(--df-md-border-2);
+  color: var(--df-md-text-3);
+  font-size: 14px;
+  line-height: 1.8;
+}
+
+.Layout:has(.VPDoc) .vp-doc div[class*='language-'] > span.lang {
+  color: var(--df-md-text-3);
+  font-size: 12px;
+}
+
+.Layout:has(.VPDoc) .vp-doc div[class*='language-'] > button.copy {
+  width: 32px;
+  height: 32px;
+  top: 8px;
+  right: 8px;
+  border-radius: 6px;
+}
+
+.Layout:has(.VPDoc) .vp-doc .vp-code-group .tabs label {
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.Layout:has(.VPDoc) .vp-doc :is(img, video, iframe) {
+  max-width: 100%;
+  border-radius: 12px;
+}
+.Layout:has(.VPDoc) .vp-doc img { height: auto; margin: 24px auto; }
+.Layout:has(.VPDoc) .vp-doc .mermaid { margin: 24px 0; overflow-x: auto; }
+.Layout:has(.VPDoc) .vp-doc .csv-box { display: block; width: 100%; }
+.Layout:has(.VPDoc) .vp-doc .csv-url { color: var(--df-md-text-3); font-size: 13px; }
+
+.Layout:has(.VPDoc) .vp-doc .custom-block > :first-child { margin-top: 0; }
+.Layout:has(.VPDoc) .vp-doc .custom-block > :last-child { margin-bottom: 0; }
+.Layout:has(.VPDoc) .vp-doc .custom-block .custom-block-title + p { margin-top: 8px; }
+.Layout:has(.VPDoc) .vp-doc .custom-block.details > summary {
+  color: var(--df-md-text-2);
+  font-size: 14px;
+  font-weight: var(--df-md-font-strong);
+  cursor: pointer;
+}
+.Layout:has(.VPDoc) .vp-doc .custom-block.details > summary:hover { color: var(--df-md-text-1); }
+.Layout:has(.VPDoc) .vp-doc .custom-block.info {
+  --df-md-callout-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='12' cy='12' r='10'/%3E%3Cpath d='M12 16v-4M12 8h.01'/%3E%3C/svg%3E");
+  border-color: var(--df-md-info-border);
+  background: var(--df-md-info-bg);
+}
+.Layout:has(.VPDoc) .vp-doc .custom-block.info .custom-block-title {
+  color: var(--df-md-primary-link);
+}
+
+.Layout:has(.VPDoc) .vp-doc .footnote-ref { font-size: 0.8em; }
+.Layout:has(.VPDoc) .vp-doc .footnotes li::marker { color: var(--df-md-text-3); }
+
 @media (max-width: 640px) {
   .Layout:has(.VPDoc) .vp-doc h1 {
-    font-size: 28px;
+    font-size: 32px;
   }
 
   .Layout:has(.VPDoc) .vp-doc h2 {
-    margin-top: 40px;
-    font-size: 22px;
+    margin-top: 32px;
+    font-size: 26px;
   }
 
   .Layout:has(.VPDoc) .vp-doc h3 {
-    font-size: 18px;
+    font-size: 22px;
   }
 
   .Layout:has(.VPDoc) .vp-doc table {
     display: block;
-    white-space: nowrap;
+    font-size: 14px;
   }
 }
diff --git a/.vitepress/theme/search.css b/.vitepress/theme/search.css
index ee30b884..756468f9 100644
--- a/.vitepress/theme/search.css
+++ b/.vitepress/theme/search.css
@@ -1,5 +1,5 @@
-/* The local-search dialog is teleported to body; it shares the DeepFlow tokens. */
-.VPLocalSearchBox {
+/* The local-search dialog is teleported to body; it shares the documentation theme tokens. */
+.VPLocalSearchBox.VPLocalSearchBox {
   --vp-c-brand-1: var(--df-md-primary-6);
   --vp-c-brand-2: var(--df-md-primary-hover);
   --vp-c-text-1: var(--df-md-text-1);
@@ -7,6 +7,7 @@
   --vp-c-text-3: var(--df-md-text-3);
   --vp-c-divider: var(--df-md-border-2);
   --vp-code-color: var(--df-md-text-1);
+  --vp-font-family-mono: var(--df-md-font-mono);
   --vp-code-bg: var(--df-md-fill-1);
   --vp-backdrop-bg-color: var(--df-md-mask-bg);
   --vp-local-search-bg: var(--df-md-bg-4);
@@ -14,43 +15,92 @@
   --vp-local-search-result-border: var(--df-md-border-1);
   --vp-local-search-result-selected-bg: var(--df-md-fill-1);
   --vp-local-search-result-selected-border: var(--df-md-primary-6);
-  --vp-local-search-highlight-bg: var(--df-md-primary-6);
-  --vp-local-search-highlight-text: var(--df-md-text-on-primary);
+  --vp-local-search-highlight-bg: var(--df-md-primary-link);
+  --vp-local-search-highlight-text: var(--df-md-bg-1);
   color: var(--df-md-text-1);
+  font-family: var(--df-md-font-sans);
 }
 
-.VPLocalSearchBox .shell {
+.VPLocalSearchBox.VPLocalSearchBox .shell {
   border: 1px solid var(--df-md-border-2);
+  width: min(720px, calc(100vw - 48px));
+  padding: 16px;
+  border-radius: 16px;
 }
 
-.VPLocalSearchBox .search-bar {
+.VPLocalSearchBox.VPLocalSearchBox .search-bar {
   background-color: var(--df-md-fill-1);
+  min-height: 48px;
+  border-color: var(--df-md-border-1);
+  border-radius: 10px;
 }
 
-.VPLocalSearchBox .search-input {
+.VPLocalSearchBox.VPLocalSearchBox .search-bar:focus-within {
+  border-color: var(--df-md-primary-6);
+}
+
+.VPLocalSearchBox.VPLocalSearchBox .search-input {
   color: var(--df-md-text-1);
+  font-size: 16px;
+  line-height: 1.5;
 }
 
-.VPLocalSearchBox .search-input::placeholder,
-.VPLocalSearchBox .search-icon,
-.VPLocalSearchBox .search-actions,
-.VPLocalSearchBox .no-results {
+.VPLocalSearchBox.VPLocalSearchBox .search-input::placeholder,
+.VPLocalSearchBox.VPLocalSearchBox .search-icon,
+.VPLocalSearchBox.VPLocalSearchBox .search-actions,
+.VPLocalSearchBox.VPLocalSearchBox .no-results {
   color: var(--df-md-text-3);
 }
 
-.VPLocalSearchBox .result {
+.VPLocalSearchBox.VPLocalSearchBox .result {
   background-color: var(--vp-local-search-result-bg);
   color: var(--df-md-text-2);
+  border-radius: 10px;
+}
+
+.VPLocalSearchBox.VPLocalSearchBox .results { gap: 8px; }
+.VPLocalSearchBox.VPLocalSearchBox .search-actions button { border-radius: 6px; }
+.VPLocalSearchBox.VPLocalSearchBox .search-actions button:not(:disabled):hover {
+  background-color: var(--df-md-fill-2);
+  color: var(--df-md-primary-6);
 }
+.VPLocalSearchBox.VPLocalSearchBox .no-results { font-size: 14px; }
 
-.VPLocalSearchBox .search-keyboard-shortcuts {
+.VPLocalSearchBox.VPLocalSearchBox .excerpt .vp-doc {
+  color: var(--df-md-text-2);
+  font-family: var(--df-md-font-sans);
+  --vp-code-block-bg: var(--df-md-fill-1);
+  --vp-c-bg: var(--df-md-bg-4);
+  --vp-c-bg-soft: var(--df-md-fill-1);
+}
+
+.VPLocalSearchBox.VPLocalSearchBox .search-keyboard-shortcuts {
   color: var(--df-md-text-3);
   opacity: 1;
+  border-top: 1px solid var(--df-md-border-1);
+  padding-top: 12px;
+  font-size: 12px;
 }
 
-.VPLocalSearchBox .search-keyboard-shortcuts kbd {
+.VPLocalSearchBox.VPLocalSearchBox .search-keyboard-shortcuts kbd {
   background-color: var(--df-md-fill-1);
   border-color: var(--df-md-border-2);
   color: var(--df-md-text-2);
   box-shadow: none;
 }
+
+.VPLocalSearchBox.VPLocalSearchBox :is(a, button):focus-visible {
+  outline: 2px solid var(--df-md-primary-6);
+  outline-offset: 2px;
+}
+
+@media (max-width: 767px) {
+  .VPLocalSearchBox.VPLocalSearchBox .shell {
+    margin: 0;
+    width: 100%;
+    height: 100dvh;
+    max-height: 100dvh;
+    border: 0;
+    border-radius: 0;
+  }
+}