From 70f155eabd8ddaf55a24af4f24b6cf51f79437c8 Mon Sep 17 00:00:00 2001
From: daguanren21 <1363917353@qq.com>
Date: Sun, 13 Sep 2026 17:47:15 +0800
Subject: [PATCH] fix(docs): restore overview catalogs

---
 apps/docs/.vitepress/theme/index.ts           |   4 +
 apps/docs/components/index.md                 |   2 +
 apps/docs/e2e/docs-smoke.spec.ts              |  10 +-
 apps/docs/en/components/index.md              |   2 +
 apps/docs/en/primitives/index.md              |   4 +
 apps/docs/primitives/index.md                 |   4 +
 apps/docs/src/components/ComponentCatalog.vue | 551 ++++++++++++++++++
 apps/docs/src/components/PrimitiveCatalog.vue | 377 ++++++++++++
 apps/docs/src/docs-navigation.test.ts         |   4 +-
 9 files changed, 951 insertions(+), 7 deletions(-)
 create mode 100644 apps/docs/src/components/ComponentCatalog.vue
 create mode 100644 apps/docs/src/components/PrimitiveCatalog.vue

diff --git a/apps/docs/.vitepress/theme/index.ts b/apps/docs/.vitepress/theme/index.ts
index 4958c422..5b1b0494 100644
--- a/apps/docs/.vitepress/theme/index.ts
+++ b/apps/docs/.vitepress/theme/index.ts
@@ -29,6 +29,7 @@ import {
 import DefaultTheme from 'vitepress/theme'
 import AgentComponentDemo from '../../src/components/AgentComponentDemo.vue'
 import AgentComponentsDemo from '../../src/components/AgentComponentsDemo.vue'
+import ComponentCatalog from '../../src/components/ComponentCatalog.vue'
 import DateFieldDemo from '../../src/components/DateFieldDemo.vue'
 import FormComponentDemo from '../../src/components/FormComponentDemo.vue'
 import InteractivePreview from '../../src/components/InteractivePreview.vue'
@@ -36,6 +37,7 @@ import ListDemo from '../../src/components/ListDemo.vue'
 import MapDemo from '../../src/components/MapDemo.vue'
 import MiniProgramBlocksGallery from '../../src/components/MiniProgramBlocksGallery.vue'
 import PlatformTabsDemo from '../../src/components/PlatformTabsDemo.vue'
+import PrimitiveCatalog from '../../src/components/PrimitiveCatalog.vue'
 import PrimitiveExample from '../../src/components/PrimitiveExample.vue'
 import PrimitiveInteractionDemo from '../../src/components/PrimitiveInteractionDemo.vue'
 import PullRefreshDemo from '../../src/components/PullRefreshDemo.vue'
@@ -60,11 +62,13 @@ const theme: Theme = {
     app.component('FormComponentDemo', FormComponentDemo)
     app.component('InteractivePreview', InteractivePreview)
     app.component('ListDemo', ListDemo)
+    app.component('ComponentCatalog', ComponentCatalog)
     app.component('MiniProgramBlocksGallery', MiniProgramBlocksGallery)
     app.component('MapDemo', MapDemo)
     app.component('RobotChatDemo', RobotChatDemo)
     app.component('PlatformTabsDemo', PlatformTabsDemo)
     app.component('PullRefreshDemo', PullRefreshDemo)
+    app.component('PrimitiveCatalog', PrimitiveCatalog)
     app.component('PrimitiveExample', PrimitiveExample)
     app.component('SignatureDemo', SignatureDemo)
     app.component('WatermarkDemo', WatermarkDemo)
diff --git a/apps/docs/components/index.md b/apps/docs/components/index.md
index af1df935..093eb907 100644
--- a/apps/docs/components/index.md
+++ b/apps/docs/components/index.md
@@ -7,3 +7,5 @@ outline: false
 # 组件
 
 选择组件查看双端演示、用法和 API。
+
+<ComponentCatalog />
diff --git a/apps/docs/e2e/docs-smoke.spec.ts b/apps/docs/e2e/docs-smoke.spec.ts
index 3a6fbe61..950938e9 100644
--- a/apps/docs/e2e/docs-smoke.spec.ts
+++ b/apps/docs/e2e/docs-smoke.spec.ts
@@ -23,7 +23,7 @@ describe('docs smoke baseline', () => {
     }
   })
 
-  it('keeps one concise headless install surface and linked detail pages', () => {
+  it('keeps one headless install surface and restores the overview catalogs', () => {
     const config = readFileSync(resolve(docsRoot, '.vitepress/config.ts'), 'utf8')
     const zhOverview = readFileSync(resolve(docsRoot, 'primitives/index.md'), 'utf8')
     const enOverview = readFileSync(resolve(docsRoot, 'en/primitives/index.md'), 'utf8')
@@ -32,10 +32,10 @@ describe('docs smoke baseline', () => {
 
     expect(zhOverview).toContain('pnpm add @varo-ui/headless @varo-ui/h5')
     expect(enOverview).toContain('pnpm add @varo-ui/headless @varo-ui/weapp')
-    expect(zhOverview).not.toContain('<PrimitiveCatalog')
-    expect(enOverview).not.toContain('<PrimitiveCatalog')
-    expect(zhComponents).not.toContain('<ComponentCatalog')
-    expect(enComponents).not.toContain('<ComponentCatalog')
+    expect(zhOverview).toContain('<PrimitiveCatalog locale="zh" />')
+    expect(enOverview).toContain('<PrimitiveCatalog locale="en" />')
+    expect(zhComponents).toContain('<ComponentCatalog />')
+    expect(enComponents).toContain('<ComponentCatalog locale="en" />')
     expect(config).toContain('/blocks/build-your-own')
     expect(config).toContain('/en/blocks/build-your-own')
     expect(existsSync(resolve(docsRoot, 'blocks/build-your-own.md'))).toBe(true)
diff --git a/apps/docs/en/components/index.md b/apps/docs/en/components/index.md
index f34e5d55..a37c5bdc 100644
--- a/apps/docs/en/components/index.md
+++ b/apps/docs/en/components/index.md
@@ -7,3 +7,5 @@ outline: false
 # Components
 
 Choose a component to view its demos, usage, and API.
+
+<ComponentCatalog locale="en" />
diff --git a/apps/docs/en/primitives/index.md b/apps/docs/en/primitives/index.md
index bf4df878..41a504ac 100644
--- a/apps/docs/en/primitives/index.md
+++ b/apps/docs/en/primitives/index.md
@@ -23,3 +23,7 @@ See [Wevu Registry](/en/guide/shadcn-mode) for global styles and Tailwind config
 | `@varo-ui/headless`         | Platform-neutral state and events |
 | `@varo-ui/h5/primitives`    | DOM, keyboard, and ARIA           |
 | `@varo-ui/weapp/primitives` | WXML, touch, and native events    |
+
+## Catalog
+
+<PrimitiveCatalog locale="en" />
diff --git a/apps/docs/primitives/index.md b/apps/docs/primitives/index.md
index b74917c8..508d7a67 100644
--- a/apps/docs/primitives/index.md
+++ b/apps/docs/primitives/index.md
@@ -23,3 +23,7 @@ pnpm add @varo-ui/headless @varo-ui/weapp
 | `@varo-ui/headless`         | 平台中立状态与事件   |
 | `@varo-ui/h5/primitives`    | DOM、键盘与 ARIA     |
 | `@varo-ui/weapp/primitives` | WXML、触摸与原生事件 |
+
+## 目录
+
+<PrimitiveCatalog locale="zh" />
diff --git a/apps/docs/src/components/ComponentCatalog.vue b/apps/docs/src/components/ComponentCatalog.vue
new file mode 100644
index 00000000..e4fc1e01
--- /dev/null
+++ b/apps/docs/src/components/ComponentCatalog.vue
@@ -0,0 +1,551 @@
+<script setup lang="ts">
+import type { ComponentTarget, DocsLocale } from '../component-catalog'
+import { computed, shallowRef } from 'vue'
+import {
+  componentCatalog,
+  componentCatalogItems,
+  componentCount,
+  componentDocsRoute,
+} from '../component-catalog'
+
+type AvailabilityFilter = 'all' | 'dual' | ComponentTarget
+const props = withDefaults(defineProps<{ locale?: DocsLocale }>(), { locale: 'zh' })
+
+const withDocsBase = (path: string) => `${import.meta.env.BASE_URL}${path.replace(/^\/+/, '')}`
+
+const query = shallowRef('')
+const targetFilter = shallowRef<AvailabilityFilter>('all')
+
+const copy = computed(() => props.locale === 'zh'
+  ? {
+      all: '全部',
+      availability: '按支持端筛选',
+      count: '个组件',
+      dual: '双端',
+      empty: '没有匹配的组件',
+      emptyDetail: '尝试其他名称，或清除当前端筛选。',
+      eyebrow: '组件目录',
+      h5: 'H5',
+      of: '共',
+      open: '查看文档',
+      reset: '清除筛选',
+      searchLabel: '搜索组件',
+      searchPlaceholder: '搜索名称，如 Badge、地图或 Picker',
+      summary: '按名称或支持端筛选。',
+      targets: '支持端',
+      weapp: 'Weapp',
+    }
+  : {
+      all: 'All',
+      availability: 'Filter by target availability',
+      count: 'components',
+      dual: 'Dual',
+      empty: 'No components match',
+      emptyDetail: 'Try another name or clear the target filter.',
+      eyebrow: 'Component catalog',
+      h5: 'H5',
+      of: 'of',
+      open: 'Open documentation',
+      reset: 'Clear filters',
+      searchLabel: 'Search components',
+      searchPlaceholder: 'Search by name, such as Badge, Map, or Picker',
+      summary: 'Filter by name or target.',
+      targets: 'Targets',
+      weapp: 'Weapp',
+    })
+
+const targetCounts = {
+  h5: componentCatalogItems.filter(item => item.targets.includes('h5')).length,
+  weapp: componentCatalogItems.filter(item => item.targets.includes('weapp')).length,
+  dual: componentCatalogItems.filter(item => item.targets.length === 2).length,
+}
+
+const filterOptions = computed(() => [
+  { id: 'all' as const, label: copy.value.all, count: componentCount },
+  { id: 'h5' as const, label: copy.value.h5, count: targetCounts.h5 },
+  { id: 'weapp' as const, label: copy.value.weapp, count: targetCounts.weapp },
+  { id: 'dual' as const, label: copy.value.dual, count: targetCounts.dual },
+])
+
+function matchesTarget(targets: readonly ComponentTarget[]): boolean {
+  if (targetFilter.value === 'all') { return true }
+  if (targetFilter.value === 'dual') { return targets.length === 2 }
+  return targets.includes(targetFilter.value)
+}
+
+const groups = computed(() => {
+  const search = query.value.trim().toLowerCase()
+
+  return componentCatalog
+    .map(group => ({
+      id: group.id,
+      summary: group.summary[props.locale],
+      title: group.title[props.locale],
+      items: group.items
+        .filter(item => matchesTarget(item.targets))
+        .filter((item) => {
+          if (!search) { return true }
+          return [
+            item.id,
+            item.name,
+            item.label.en,
+            item.label.zh,
+          ].some(value => value.toLowerCase().includes(search))
+        })
+        .map(item => ({
+          ...item,
+          href: withDocsBase(componentDocsRoute(item.id, props.locale)),
+          label: item.label[props.locale],
+        })),
+    }))
+    .filter(group => group.items.length > 0)
+})
+
+const visibleComponentCount = computed(() =>
+  groups.value.reduce((count, group) => count + group.items.length, 0),
+)
+
+const hasActiveFilters = computed(() => query.value.trim().length > 0 || targetFilter.value !== 'all')
+
+function targetAvailabilityLabel(targets: readonly ComponentTarget[]): string {
+  const names = targets.map(target => target === 'h5' ? copy.value.h5 : copy.value.weapp)
+  return `${copy.value.targets}: ${names.join(' + ')}`
+}
+
+function resetFilters() {
+  query.value = ''
+  targetFilter.value = 'all'
+}
+</script>
+
+<template>
+  <div class="component-catalog">
+    <header class="component-catalog__intro">
+      <div>
+        <span>{{ copy.eyebrow }}</span>
+        <p>{{ copy.summary }}</p>
+      </div>
+      <output aria-live="polite">
+        <strong>{{ visibleComponentCount }}</strong>
+        <template v-if="hasActiveFilters"> {{ copy.of }} {{ componentCount }}</template>
+        {{ copy.count }}
+      </output>
+    </header>
+
+    <div class="component-catalog__toolbar">
+      <label class="component-catalog__search" for="component-catalog-search">
+        <span class="component-catalog__sr-only">{{ copy.searchLabel }}</span>
+        <input
+          id="component-catalog-search"
+          v-model="query"
+          class="component-catalog__search-input"
+          type="search"
+          name="component-search"
+          :placeholder="copy.searchPlaceholder"
+          autocomplete="off"
+          spellcheck="false"
+          @keydown.esc="query = ''"
+        >
+      </label>
+
+      <div
+        class="component-catalog__filters"
+        role="group"
+        :aria-label="copy.availability"
+      >
+        <button
+          v-for="option in filterOptions"
+          :key="option.id"
+          type="button"
+          :aria-pressed="targetFilter === option.id"
+          @click="targetFilter = option.id"
+        >
+          {{ option.label }}
+          <span>{{ option.count }}</span>
+        </button>
+      </div>
+    </div>
+
+    <div v-if="groups.length > 0" class="component-catalog__groups">
+      <section v-for="group in groups" :key="group.id" class="component-catalog__group">
+        <header>
+          <div>
+            <h2>{{ group.title }}</h2>
+            <p>{{ group.summary }}</p>
+          </div>
+          <span>{{ group.items.length }}</span>
+        </header>
+
+        <div class="component-catalog__links">
+          <a
+            v-for="item in group.items"
+            :key="item.id"
+            :href="item.href"
+            :aria-label="`${item.name}. ${targetAvailabilityLabel(item.targets)}. ${copy.open}`"
+          >
+            <span class="component-catalog__identity">
+              <strong>{{ item.name }}</strong>
+              <small>{{ item.label }}</small>
+            </span>
+            <span class="component-catalog__targets" aria-hidden="true">
+              <small v-for="target in item.targets" :key="target">
+                {{ target === 'h5' ? copy.h5 : copy.weapp }}
+              </small>
+            </span>
+            <svg
+              aria-hidden="true"
+              viewBox="0 0 16 16"
+              width="16"
+              height="16"
+              fill="none"
+            >
+              <path d="M5 3h8v8M13 3 3 13" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
+            </svg>
+          </a>
+        </div>
+      </section>
+    </div>
+
+    <div v-else class="component-catalog__empty" role="status">
+      <strong>{{ copy.empty }}</strong>
+      <p>{{ copy.emptyDetail }}</p>
+      <button type="button" @click="resetFilters">
+        {{ copy.reset }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.component-catalog {
+  display: grid;
+  gap: 18px;
+  margin: 24px 0 40px;
+}
+
+.component-catalog__intro {
+  display: flex;
+  gap: 20px;
+  align-items: flex-end;
+  justify-content: space-between;
+  padding: 18px 20px;
+  background: color-mix(in srgb, var(--varo-accent-soft) 56%, var(--varo-card-solid));
+  border: 1px solid var(--varo-border);
+  border-radius: var(--varo-radius-lg);
+}
+
+.component-catalog__intro > div {
+  min-width: 0;
+}
+
+.component-catalog__intro span {
+  font-size: 0.72rem;
+  font-weight: 800;
+  color: var(--varo-accent);
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+}
+
+.component-catalog__intro p {
+  max-width: 68ch;
+  margin: 7px 0 0;
+  line-height: 1.65;
+  color: var(--varo-muted);
+}
+
+.component-catalog__intro output {
+  flex: none;
+  font-size: 0.82rem;
+  color: var(--varo-muted);
+}
+
+.component-catalog__intro output strong {
+  font-size: 1rem;
+  color: var(--varo-foreground);
+}
+
+.component-catalog__toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px 14px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px;
+  background: color-mix(in srgb, var(--varo-card) 82%, transparent);
+  border: 1px solid var(--varo-border);
+  border-radius: var(--varo-radius-lg);
+}
+
+.component-catalog__search {
+  flex: 1 1 280px;
+  min-width: 0;
+}
+
+.component-catalog__search-input {
+  width: 100%;
+  height: 44px;
+  padding: 0 14px;
+  font: inherit;
+  color: var(--varo-foreground);
+  outline: none;
+  background: var(--varo-card-solid);
+  border: 1px solid var(--varo-border-strong);
+  border-radius: var(--varo-radius);
+}
+
+.component-catalog__search-input::placeholder {
+  color: var(--varo-placeholder);
+}
+
+.component-catalog__search-input:focus-visible {
+  border-color: var(--varo-accent);
+  box-shadow: 0 0 0 3px var(--varo-ring);
+}
+
+.component-catalog__filters {
+  display: flex;
+  flex: 0 1 auto;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.component-catalog__filters button,
+.component-catalog__empty button {
+  min-height: 44px;
+  padding: 0 11px;
+  font: inherit;
+  font-size: 0.76rem;
+  font-weight: 750;
+  color: var(--varo-text-regular);
+  cursor: pointer;
+  background: var(--varo-surface-strong);
+  border: 1px solid var(--varo-border);
+  border-radius: var(--varo-radius);
+}
+
+.component-catalog__filters button {
+  display: inline-flex;
+  gap: 6px;
+  align-items: center;
+}
+
+.component-catalog__filters button span {
+  font-size: 0.68rem;
+  color: var(--varo-muted);
+}
+
+.component-catalog__filters button:hover,
+.component-catalog__empty button:hover {
+  border-color: var(--varo-accent);
+}
+
+.component-catalog__filters button:focus-visible,
+.component-catalog__empty button:focus-visible {
+  outline: 2px solid var(--varo-accent);
+  outline-offset: 2px;
+}
+
+.component-catalog__filters button[aria-pressed='true'] {
+  color: var(--varo-primary-text);
+  background: var(--varo-primary-soft);
+  border-color: color-mix(in srgb, var(--varo-primary) 64%, var(--varo-border));
+}
+
+.component-catalog__filters button[aria-pressed='true'] span {
+  color: currentcolor;
+}
+
+.component-catalog__groups {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 14px;
+}
+
+.component-catalog__group {
+  min-width: 0;
+  padding: 18px;
+  background: color-mix(in srgb, var(--varo-card) 82%, transparent);
+  border: 1px solid var(--varo-border);
+  border-radius: var(--varo-radius-lg);
+}
+
+.component-catalog__group > header {
+  display: flex;
+  gap: 16px;
+  align-items: flex-start;
+  justify-content: space-between;
+  margin-bottom: 16px;
+}
+
+.component-catalog__group h2 {
+  padding: 0;
+  margin: 0;
+  font-size: 1.05rem;
+  color: var(--varo-foreground);
+  letter-spacing: -0.02em;
+  border: 0;
+}
+
+.component-catalog__group p {
+  margin: 5px 0 0;
+  font-size: 0.82rem;
+  line-height: 1.55;
+  color: var(--varo-muted);
+}
+
+.component-catalog__group > header > span {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  min-width: 30px;
+  height: 26px;
+  font-size: 0.72rem;
+  font-weight: 800;
+  color: var(--varo-muted);
+  background: var(--varo-surface-strong);
+  border: 1px solid var(--varo-border);
+  border-radius: 7px;
+}
+
+.component-catalog__links {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 7px;
+}
+
+.component-catalog__links a {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto 16px;
+  gap: 9px;
+  align-items: center;
+  min-width: 0;
+  min-height: 68px;
+  padding: 9px 11px;
+  color: var(--varo-foreground);
+  text-decoration: none;
+  background: color-mix(in srgb, var(--varo-surface-strong) 72%, transparent);
+  border: 1px solid transparent;
+  border-radius: var(--varo-radius);
+  transition:
+    border-color 160ms ease,
+    background 160ms ease,
+    color 160ms ease;
+}
+
+.component-catalog__links a:hover {
+  color: var(--varo-accent);
+  background: var(--varo-accent-soft);
+  border-color: color-mix(in srgb, var(--varo-accent) 36%, var(--varo-border));
+}
+
+.component-catalog__links a:focus-visible {
+  outline: 2px solid var(--varo-accent);
+  outline-offset: 2px;
+}
+
+.component-catalog__identity {
+  display: grid;
+  min-width: 0;
+}
+
+.component-catalog__identity strong {
+  font-size: 0.84rem;
+  color: inherit;
+  overflow-wrap: anywhere;
+}
+
+.component-catalog__identity small {
+  font-size: 0.72rem;
+  color: var(--varo-muted);
+}
+
+.component-catalog__targets {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  justify-content: flex-end;
+}
+
+.component-catalog__targets small {
+  padding: 2px 5px;
+  font-family: var(--vp-font-family-mono);
+  font-size: 0.58rem;
+  font-weight: 700;
+  line-height: 1.3;
+  color: var(--varo-primary-text);
+  background: var(--varo-primary-soft);
+  border: 1px solid color-mix(in srgb, var(--varo-primary) 32%, var(--varo-border));
+  border-radius: 5px;
+}
+
+.component-catalog__links svg {
+  flex: none;
+  color: var(--varo-muted);
+}
+
+.component-catalog__empty {
+  display: grid;
+  justify-items: start;
+  padding: 28px;
+  color: var(--varo-foreground);
+  background: color-mix(in srgb, var(--varo-card) 82%, transparent);
+  border: 1px dashed var(--varo-border-strong);
+  border-radius: var(--varo-radius-lg);
+}
+
+.component-catalog__empty p {
+  margin: 6px 0 16px;
+  color: var(--varo-muted);
+}
+
+.component-catalog__sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  white-space: nowrap;
+  border: 0;
+  clip-path: inset(50%);
+}
+
+@media (max-width: 960px) {
+  .component-catalog__links {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 760px) {
+  .component-catalog__groups {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .component-catalog__intro {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .component-catalog__toolbar {
+    align-items: stretch;
+  }
+
+  .component-catalog__search {
+    flex-basis: 100%;
+  }
+}
+
+@media (max-width: 480px) {
+  .component-catalog__group {
+    padding: 14px;
+  }
+
+  .component-catalog__links {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .component-catalog__links a {
+    grid-template-columns: minmax(0, 1fr) auto 16px;
+  }
+}
+</style>
diff --git a/apps/docs/src/components/PrimitiveCatalog.vue b/apps/docs/src/components/PrimitiveCatalog.vue
new file mode 100644
index 00000000..a6c72c61
--- /dev/null
+++ b/apps/docs/src/components/PrimitiveCatalog.vue
@@ -0,0 +1,377 @@
+<script setup lang="ts">
+import { withBase } from 'vitepress'
+
+type Locale = 'zh' | 'en'
+type Category = 'foundation' | 'controls' | 'content' | 'disclosure' | 'layers'
+
+interface CatalogItemDefinition {
+  id: string
+  title: string
+  parts: string
+  summary: Record<Locale, string>
+  category: Category
+}
+
+const props = withDefaults(
+  defineProps<{
+    locale?: Locale
+  }>(),
+  {
+    locale: 'zh',
+  },
+)
+
+const copy = props.locale === 'en'
+  ? {
+      categories: {
+        foundation: 'Foundation',
+        controls: 'Selection & Toggle',
+        content: 'Content & Layout',
+        disclosure: 'Disclosure & Floating',
+        layers: 'Layers',
+      },
+      parts: 'Parts',
+      open: 'Open page',
+    }
+  : {
+      categories: {
+        foundation: '基础控件',
+        controls: '选择与切换',
+        content: '内容与布局',
+        disclosure: '展开与轻浮层',
+        layers: '遮罩与弹层',
+      },
+      parts: 'Parts',
+      open: '打开文档',
+    }
+
+const definitions: CatalogItemDefinition[] = [
+  {
+    id: 'button',
+    title: 'Button',
+    parts: 'ButtonRoot / usePressableRoot',
+    summary: {
+      zh: '统一 pressed、disabled、loading 与原生激活语义。',
+      en: 'Shared pressed, disabled, loading, and native activation semantics.',
+    },
+    category: 'foundation',
+  },
+  {
+    id: 'input',
+    title: 'Input',
+    parts: 'InputRoot / useFieldRoot',
+    summary: {
+      zh: '文本值、格式化、只读、校验与输入事件基座。',
+      en: 'Text value, formatting, readonly, invalid, and input-event foundation.',
+    },
+    category: 'foundation',
+  },
+  {
+    id: 'number-field',
+    title: 'Number Field',
+    parts: 'NumberFieldRoot / Decrement / Input / Increment',
+    summary: {
+      zh: '数值边界、步进、精度与组合式加减控件。',
+      en: 'Numeric bounds, step, precision, and composable increment controls.',
+    },
+    category: 'controls',
+  },
+  {
+    id: 'image',
+    title: 'Image',
+    parts: 'ImageRoot / useImageRoot',
+    summary: {
+      zh: '图片加载、失败、占位与尺寸适配状态。',
+      en: 'Image loading, failure, placeholder, and sizing state.',
+    },
+    category: 'content',
+  },
+  {
+    id: 'cell',
+    title: 'Cell',
+    parts: 'CellGroupRoot / CellRoot',
+    summary: {
+      zh: '列表行、设置项、链接行与键盘激活契约。',
+      en: 'List row, settings item, link row, and keyboard activation contract.',
+    },
+    category: 'content',
+  },
+  {
+    id: 'sticky',
+    title: 'Sticky',
+    parts: 'StickyRoot',
+    summary: {
+      zh: '吸顶状态、偏移量与滚动事件适配。',
+      en: 'Sticky state, offset, and runtime-specific scroll events.',
+    },
+    category: 'content',
+  },
+  {
+    id: 'checkbox',
+    title: 'Checkbox',
+    parts: 'CheckboxRoot / CheckboxIndicator',
+    summary: {
+      zh: '选中态、禁用态与 indicator 渲染契约。',
+      en: 'Checked state, disabled behavior, and indicator rendering.',
+    },
+    category: 'controls',
+  },
+  {
+    id: 'radio-group',
+    title: 'Radio Group',
+    parts: 'RadioGroup / RadioItem / RadioIndicator',
+    summary: {
+      zh: '单选组 value 与选项级 disabled 语义。',
+      en: 'Single-select group value with item-level disabled support.',
+    },
+    category: 'controls',
+  },
+  {
+    id: 'switch',
+    title: 'Switch',
+    parts: 'SwitchRoot / SwitchThumb',
+    summary: {
+      zh: '开关态、loading 与 disabled 契约。',
+      en: 'Binary toggle with loading and disabled contracts.',
+    },
+    category: 'controls',
+  },
+  {
+    id: 'tabs',
+    title: 'Tabs',
+    parts: 'TabsRoot / TabsList / TabsTrigger / TabsContent',
+    summary: {
+      zh: '当前 tab value、orientation 与 panel 关联。',
+      en: 'Tab value ownership, orientation, and panel association.',
+    },
+    category: 'controls',
+  },
+  {
+    id: 'select',
+    title: 'Select',
+    parts: 'SelectRoot / Trigger / Value / Content / Item',
+    summary: {
+      zh: '选择器状态、open 契约与选项组合。',
+      en: 'Composable select state, open contract, and option rendering.',
+    },
+    category: 'controls',
+  },
+  {
+    id: 'collapsible',
+    title: 'Collapsible',
+    parts: 'CollapsibleRoot / Trigger / Content',
+    summary: {
+      zh: '单个展开区域的 open 状态契约。',
+      en: 'Single disclosure open state for expandable content.',
+    },
+    category: 'disclosure',
+  },
+  {
+    id: 'accordion',
+    title: 'Accordion',
+    parts: 'AccordionRoot / Item / Trigger / Content',
+    summary: {
+      zh: 'single/multiple 展开集合与 item disabled。',
+      en: 'Single or multiple expandable sections with item disable.',
+    },
+    category: 'disclosure',
+  },
+  {
+    id: 'popover',
+    title: 'Popover',
+    parts: 'PopoverRoot / Trigger / Content / Close',
+    summary: {
+      zh: '轻量浮层开关与显式 dismiss 契约。',
+      en: 'Lightweight floating layer open/close and explicit dismiss contract.',
+    },
+    category: 'disclosure',
+  },
+  {
+    id: 'dialog',
+    title: 'Dialog',
+    parts: 'DialogRoot / Trigger / Overlay / Content / Close',
+    summary: {
+      zh: '模态打开态、遮罩、内容与退出动作。',
+      en: 'Modal open state, overlay, content, and exit actions.',
+    },
+    category: 'layers',
+  },
+  {
+    id: 'overlay',
+    title: 'Overlay',
+    parts: 'OverlayRoot',
+    summary: {
+      zh: '遮罩可见态、点击关闭与滚动锁定。',
+      en: 'Overlay visibility, click dismiss, and scroll locking.',
+    },
+    category: 'layers',
+  },
+  {
+    id: 'popup',
+    title: 'Popup',
+    parts: 'PopupRoot',
+    summary: {
+      zh: '带定位、遮罩、安全区与关闭行为的弹出层。',
+      en: 'Positioned popup with overlay, safe area, and close behavior.',
+    },
+    category: 'layers',
+  },
+]
+
+const routePrefix = props.locale === 'en' ? '/en' : ''
+const groups = (['foundation', 'controls', 'content', 'disclosure', 'layers'] as const).map(id => ({
+  id,
+  title: copy.categories[id],
+  items: definitions
+    .filter(item => item.category === id)
+    .map(item => ({
+      ...item,
+      href: `${routePrefix}/primitives/${item.id}`,
+      summary: item.summary[props.locale],
+    })),
+}))
+</script>
+
+<template>
+  <div class="primitive-catalog">
+    <section v-for="group in groups" :key="group.id" class="primitive-catalog__group">
+      <header class="primitive-catalog__group-head">
+        <h3>{{ group.title }}</h3>
+        <span>{{ group.items.length }}</span>
+      </header>
+      <div class="primitive-catalog__grid">
+        <a
+          v-for="item in group.items"
+          :key="item.id"
+          class="primitive-catalog__card"
+          :href="withBase(item.href)"
+        >
+          <div class="primitive-catalog__card-top">
+            <strong>{{ item.title }}</strong>
+            <span>{{ copy.open }}</span>
+          </div>
+          <p>{{ item.summary }}</p>
+          <small>
+            <em>{{ copy.parts }}</em>
+            {{ item.parts }}
+          </small>
+        </a>
+      </div>
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.primitive-catalog {
+  display: grid;
+  gap: 18px;
+  margin: 18px 0 28px;
+}
+
+.primitive-catalog__group {
+  display: grid;
+  gap: 12px;
+}
+
+.primitive-catalog__group-head {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.primitive-catalog__group-head h3 {
+  margin: 0;
+  font-size: 1rem;
+  letter-spacing: -0.02em;
+}
+
+.primitive-catalog__group-head span {
+  display: inline-flex;
+  align-items: center;
+  min-height: 24px;
+  padding: 0 10px;
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--varo-muted);
+  background: color-mix(in srgb, var(--varo-demo-surface-strong, var(--varo-card-solid)) 92%, transparent);
+  border: 1px solid var(--varo-demo-border, var(--varo-border));
+  border-radius: 999px;
+}
+
+.primitive-catalog__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 12px;
+}
+
+.primitive-catalog__card {
+  display: grid;
+  gap: 10px;
+  min-height: 132px;
+  padding: 14px;
+  color: inherit;
+  text-decoration: none;
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, var(--varo-demo-surface, var(--varo-card-solid)) 94%, transparent),
+    var(--varo-demo-surface-strong, var(--varo-card-solid))
+  );
+  border: 1px solid var(--varo-demo-border, var(--varo-border));
+  border-radius: 16px;
+  box-shadow: var(--varo-demo-shadow, var(--varo-shadow-sm));
+  transition:
+    border-color 160ms ease,
+    transform 160ms ease,
+    box-shadow 160ms ease;
+}
+
+.primitive-catalog__card:hover {
+  border-color: color-mix(in srgb, var(--varo-primary) 42%, var(--varo-demo-border, var(--varo-border)));
+  box-shadow: 0 12px 28px color-mix(in srgb, var(--varo-primary) 12%, transparent);
+  transform: translateY(-1px);
+}
+
+.primitive-catalog__card:focus-visible {
+  outline: 2px solid color-mix(in srgb, var(--varo-primary) 70%, transparent);
+  outline-offset: 2px;
+}
+
+.primitive-catalog__card-top {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.primitive-catalog__card-top strong {
+  font-size: 0.98rem;
+}
+
+.primitive-catalog__card-top span {
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--varo-demo-brand, var(--varo-primary));
+}
+
+.primitive-catalog__card p {
+  margin: 0;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--varo-muted);
+}
+
+.primitive-catalog__card small {
+  font-size: 12px;
+  line-height: 1.45;
+  color: var(--varo-foreground);
+}
+
+.primitive-catalog__card small em {
+  display: block;
+  margin-bottom: 2px;
+  font-style: normal;
+  font-weight: 700;
+  color: var(--varo-muted);
+}
+</style>
diff --git a/apps/docs/src/docs-navigation.test.ts b/apps/docs/src/docs-navigation.test.ts
index 85435822..788f9519 100644
--- a/apps/docs/src/docs-navigation.test.ts
+++ b/apps/docs/src/docs-navigation.test.ts
@@ -80,8 +80,8 @@ describe('docs navigation', () => {
     expect(primitiveZh).toContain('pnpm add @varo-ui/headless @varo-ui/weapp')
     expect(primitiveEn).toContain('pnpm add @varo-ui/headless @varo-ui/h5')
     expect(primitiveEn).toContain('pnpm add @varo-ui/headless @varo-ui/weapp')
-    expect(primitiveZh).not.toContain('<PrimitiveCatalog')
-    expect(primitiveEn).not.toContain('<PrimitiveCatalog')
+    expect(primitiveZh).toContain('<PrimitiveCatalog locale="zh" />')
+    expect(primitiveEn).toContain('<PrimitiveCatalog locale="en" />')
     expect(primitiveZh).not.toContain('<RegistryInstallStrip')
     expect(primitiveEn).not.toContain('<RegistryInstallStrip')