From 4299b514eb12be224cd1821c2d52acfdaaed3614 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:07:40 +0800
Subject: [PATCH 01/26] fix: resolve dialog trigger, table empty safety, and
 release workflow issues

---
 .changeset/moody-cases-itch.md                    |  5 +++++
 .github/workflows/ci.yml                          |  2 +-
 .github/workflows/release.yml                     |  8 +++++++-
 .gitignore                                        |  1 +
 package.json                                      |  2 +-
 packages/ui/package.json                          |  3 +++
 packages/ui/src/components/dialog/Dialog.vue      | 11 +++++++----
 packages/ui/src/components/table/DataTable.vue    |  8 +++++---
 packages/ui/src/components/tag-input/TagInput.vue |  1 +
 packages/ui/src/nuxt/types.ts                     |  6 +++---
 packages/ui/vite.config.ts                        |  2 +-
 11 files changed, 35 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/moody-cases-itch.md

diff --git a/.changeset/moody-cases-itch.md b/.changeset/moody-cases-itch.md
new file mode 100644
index 0000000..ab4a2e7
--- /dev/null
+++ b/.changeset/moody-cases-itch.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Fix Dialog trigger slot handling, DataTable fallback for empty or undefined rows, TagInput IME composition behavior, Nuxt module type prefix, and package externalization.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1789d39..a75b2d3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,7 +3,7 @@ name: CI
 on:
   pull_request:
   push:
-    branches: [main]
+    branches: [main, dev]
 
 permissions:
   contents: read
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 617810a..ce03a47 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -17,6 +17,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: "1.4.2"
@@ -40,6 +42,8 @@ jobs:
             url: https://npm.pkg.github.com
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
           node-version: 24
@@ -48,7 +52,7 @@ jobs:
         with:
           bun-version: "1.4.2"
       - run: bun install --frozen-lockfile
-      - run: bun run --cwd packages/ui typecheck && bun run --cwd packages/ui build
+      - run: bun run --cwd packages/ui typecheck && bun run --cwd packages/ui test && bun run --cwd packages/ui build
       - run: test "v$(node -p "require('./packages/ui/package.json').version")" = "$GITHUB_REF_NAME"
       # 重新推送同一 tag 时，跳过已发布过该版本的注册表，只补发失败的那一个
       - id: published
@@ -64,6 +68,8 @@ jobs:
       - if: matrix.registry.name == 'npm' && steps.published.outputs.exists != 'true'
         run: npm publish --provenance --access public --registry=${{ matrix.registry.url }}
         working-directory: packages/ui
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       - if: matrix.registry.name == 'github' && steps.published.outputs.exists != 'true'
         run: npm publish --registry=${{ matrix.registry.url }}
         working-directory: packages/ui
diff --git a/.gitignore b/.gitignore
index 02b0eb3..34d5f83 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@ dist/
 .turbo/
 .nuxt/
 .output/
+.vitest/
 *.log
 .DS_Store
 .direnv/
diff --git a/package.json b/package.json
index a408e89..6f90487 100644
--- a/package.json
+++ b/package.json
@@ -17,7 +17,7 @@
     "format": "biome format --write apps packages .github .changeset package.json turbo.json biome.json tsconfig.json README.md",
     "ci": "bun run lint && bun run typecheck && bun run test && bun run build",
     "changeset": "changeset",
-    "version-packages": "changeset version"
+    "version-packages": "changeset version && bun install"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
diff --git a/packages/ui/package.json b/packages/ui/package.json
index df6e5aa..b30049f 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -56,6 +56,9 @@
   "peerDependenciesMeta": {
     "@nuxt/kit": {
       "optional": true
+    },
+    "@nuxt/schema": {
+      "optional": true
     }
   },
   "devDependencies": {
diff --git a/packages/ui/src/components/dialog/Dialog.vue b/packages/ui/src/components/dialog/Dialog.vue
index 855ac80..733f0d9 100644
--- a/packages/ui/src/components/dialog/Dialog.vue
+++ b/packages/ui/src/components/dialog/Dialog.vue
@@ -1,6 +1,8 @@
 <template>
-  <DialogRoot :open="open" @update:open="$emit('update:open', $event)">
-    <slot name="trigger" />
+  <DialogRoot :open="props.open" @update:open="$emit('update:open', $event)">
+    <DialogTrigger as-child v-if="$slots.trigger">
+      <slot name="trigger" />
+    </DialogTrigger>
     <DialogPortal>
       <DialogOverlay class="fixed inset-0 z-50 bg-slate-950/40 backdrop-blur-xs data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0" />
       <DialogContent :class="contentClasses">
@@ -42,7 +44,8 @@ import {
   DialogContent,
   DialogTitle,
   DialogDescription,
-  DialogClose
+  DialogClose,
+  DialogTrigger
 } from 'reka-ui'
 import { cn } from '../../utils/cn'
 
@@ -54,7 +57,7 @@ export interface DialogProps {
 }
 
 const props = withDefaults(defineProps<DialogProps>(), {
-  open: false,
+  open: undefined,
   title: '',
   description: '',
   class: ''
diff --git a/packages/ui/src/components/table/DataTable.vue b/packages/ui/src/components/table/DataTable.vue
index c9ee324..233e5d5 100644
--- a/packages/ui/src/components/table/DataTable.vue
+++ b/packages/ui/src/components/table/DataTable.vue
@@ -30,7 +30,7 @@
         </tr>
       </tbody>
     </table>
-    <div v-if="props.rows.length === 0" class="px-4 py-10 text-center text-sm text-slate-500 dark:text-slate-400">
+    <div v-if="!props.rows || props.rows.length === 0" class="px-4 py-10 text-center text-sm text-slate-500 dark:text-slate-400">
       {{ props.emptyText }}
     </div>
   </div>
@@ -48,8 +48,8 @@ export interface DataTableColumn {
 }
 
 export interface DataTableProps {
-  columns: DataTableColumn[]
-  rows: Record<string, any>[]
+  columns?: DataTableColumn[]
+  rows?: Record<string, any>[]
   hoverable?: boolean
   divide?: boolean
   emptyText?: string
@@ -57,6 +57,8 @@ export interface DataTableProps {
 }
 
 const props = withDefaults(defineProps<DataTableProps>(), {
+  columns: () => [],
+  rows: () => [],
   hoverable: true,
   divide: true,
   emptyText: '暂无数据',
diff --git a/packages/ui/src/components/tag-input/TagInput.vue b/packages/ui/src/components/tag-input/TagInput.vue
index 8c56ef8..a145e23 100644
--- a/packages/ui/src/components/tag-input/TagInput.vue
+++ b/packages/ui/src/components/tag-input/TagInput.vue
@@ -165,6 +165,7 @@ function onInput(event: Event) {
 }
 
 function onKeydown(event: KeyboardEvent) {
+  if (event.isComposing || event.keyCode === 229) return
   if (event.key === 'Enter') {
     event.preventDefault()
     commitMany([draft.value])
diff --git a/packages/ui/src/nuxt/types.ts b/packages/ui/src/nuxt/types.ts
index caf4fa8..0542799 100644
--- a/packages/ui/src/nuxt/types.ts
+++ b/packages/ui/src/nuxt/types.ts
@@ -1,7 +1,7 @@
 export interface ModuleOptions {
   /**
-   * Prefix for components (e.g. 'Rc' -> <RcButton />)
-   * @default 'Rc'
+   * Prefix for components (e.g. 'Re' -> <ReButton />)
+   * @default 'Re'
    */
   prefix?: string
 
@@ -13,6 +13,6 @@ export interface ModuleOptions {
 }
 
 export const defaultOptions: ModuleOptions = {
-  prefix: 'Rc',
+  prefix: 'Re',
   injectTheme: true
 }
diff --git a/packages/ui/vite.config.ts b/packages/ui/vite.config.ts
index 6f1a31b..32cb8cd 100644
--- a/packages/ui/vite.config.ts
+++ b/packages/ui/vite.config.ts
@@ -26,7 +26,7 @@ export default defineConfig({
         "@nuxt/kit",
         "reka-ui",
         "lucide-vue-next",
-        "shiki",
+        /^shiki(\/.*)?$/,
         "tailwind-merge",
         "clsx",
       ],

From 93d285eab30e580a44839303b1e2a0d601a39a11 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:50:20 +0800
Subject: [PATCH 02/26] feat: add experimental command palette

---
 .changeset/quick-cloud-commands.md            |   5 +
 .../pages/components/command-palette.vue      |  78 +++++++
 apps/playground/utils/catalog.ts              |  11 +-
 .../command-palette/CommandPalette.vue        | 200 ++++++++++++++++++
 .../command-palette/commandMatcher.test.ts    |  24 +++
 .../command-palette/commandMatcher.ts         |  52 +++++
 .../src/components/command-palette/index.ts   |   2 +
 .../src/components/command-palette/types.ts   |  22 ++
 packages/ui/src/index.ts                      |   5 +
 9 files changed, 396 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/quick-cloud-commands.md
 create mode 100644 apps/playground/pages/components/command-palette.vue
 create mode 100644 packages/ui/src/components/command-palette/CommandPalette.vue
 create mode 100644 packages/ui/src/components/command-palette/commandMatcher.test.ts
 create mode 100644 packages/ui/src/components/command-palette/commandMatcher.ts
 create mode 100644 packages/ui/src/components/command-palette/index.ts
 create mode 100644 packages/ui/src/components/command-palette/types.ts

diff --git a/.changeset/quick-cloud-commands.md b/.changeset/quick-cloud-commands.md
new file mode 100644
index 0000000..c101607
--- /dev/null
+++ b/.changeset/quick-cloud-commands.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add the experimental CommandPalette for accessible command navigation in developer tools.
diff --git a/apps/playground/pages/components/command-palette.vue b/apps/playground/pages/components/command-palette.vue
new file mode 100644
index 0000000..3e4592c
--- /dev/null
+++ b/apps/playground/pages/components/command-palette.vue
@@ -0,0 +1,78 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="CommandPalette 命令面板" description="面向开发者工具的全局导航与操作入口；支持分组、模糊检索、键盘导航与可选快捷键。" />
+
+    <DocExample title="命令与导航" description="按下 Ctrl/⌘ K 或点击按钮，使用方向键和 Enter 选择命令。" :code="rcCode0">
+      <Button @click="open = true">打开命令面板 <Kbd class="ml-2">⌘ K</Kbd></Button>
+      <CommandPalette v-model:open="open" :groups="groups" shortcut="mod+k" @select="selectCommand" />
+      <p v-if="selected" class="mt-3 text-xs text-slate-500 dark:text-slate-400">最近选择：{{ selected }}</p>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="command-palette" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { CommandGroup, CommandItem } from '@recloudstudio/ui'
+
+const open = ref(false)
+const selected = ref('')
+
+const groups: CommandGroup[] = [
+  {
+    heading: '导航',
+    items: [
+      { id: 'dashboard', label: '前往仪表盘', description: '查看服务总览', keywords: ['home', 'dashboard'], shortcut: ['G', 'D'] },
+      { id: 'webhooks', label: '管理 Webhooks', description: '查看投递和规则', keywords: ['events', 'hooks'], shortcut: ['G', 'W'] }
+    ]
+  },
+  {
+    heading: '操作',
+    items: [
+      { id: 'new-webhook', label: '新建 Webhook', description: '创建新的事件投递规则', shortcut: ['C'] },
+      { id: 'refresh', label: '刷新数据', description: '重新获取当前页面数据', shortcut: ['R'], keepOpen: true },
+      { id: 'disabled', label: '维护中操作', disabled: true }
+    ]
+  }
+]
+
+function selectCommand(item: CommandItem) {
+  selected.value = item.label
+}
+
+const rcCode0 = `<script setup lang="ts">
+import { ref } from 'vue'
+import type { CommandGroup, CommandItem } from '@recloudstudio/ui'
+
+const open = ref(false)
+const groups: CommandGroup[] = [{
+  heading: '操作',
+  items: [{ id: 'refresh', label: '刷新数据', shortcut: ['R'] }]
+}]
+
+function selectCommand(item: CommandItem) {
+  refreshData()
+}
+<\/script>
+
+<template>
+  <Button @click="open = true">打开命令面板</Button>
+  <CommandPalette
+    v-model:open="open"
+    :groups="groups"
+    shortcut="mod+k"
+    @select="selectCommand"
+  />
+<\/template>`
+
+const apiRows = [
+  { name: 'groups', type: 'CommandGroup[]', default: '—', description: '分组命令数据；条目支持 id、label、description、keywords、shortcut、icon、disabled、keepOpen。' },
+  { name: 'v-model:open', type: 'boolean', default: 'false', description: '控制命令面板开关。' },
+  { name: 'v-model:query', type: 'string', default: '—', description: '可选的受控查询文本。' },
+  { name: 'shortcut', type: 'string', default: '—', description: '可选全局快捷键，如 mod+k、shift+mod+p。' },
+  { name: 'filter', type: '(items, query) => CommandItem[]', default: '内置模糊匹配', description: '替换检索与排序策略。' },
+  { name: 'select', type: '(item: CommandItem) => void', default: '—', description: '选择非禁用命令时触发。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 886a2a1..47f06c4 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -53,7 +53,8 @@ export const docGroups: DocGroup[] = [
       { name: 'pin-input', title: 'PinInput 验证码', description: 'OTP 分段输入。' },
       { name: 'editable', title: 'Editable 行内编辑', description: '点击即改的文本。' },
       { name: 'toggle', title: 'Toggle / ToggleGroup', description: '按压态工具按钮与分组。' },
-      { name: 'label', title: 'Label 标签', description: '表单控件关联标签。' }
+      { name: 'label', title: 'Label 标签', description: '表单控件关联标签。' },
+      { name: 'date-picker', title: 'DatePicker 日期选择', description: '单日期与日期范围筛选。' }
     ]
   },
   {
@@ -74,7 +75,10 @@ export const docGroups: DocGroup[] = [
       { name: 'breadcrumb', title: 'Breadcrumb 面包屑', description: '层级路径导航。' },
       { name: 'stepper', title: 'Stepper 步骤条', description: '多步流程进度。' },
       { name: 'navigation-menu', title: 'NavigationMenu 导航菜单', description: '悬停展开的顶部导航。' },
-      { name: 'toolbar', title: 'Toolbar 工具条', description: '编辑器式按钮组。' }
+      { name: 'toolbar', title: 'Toolbar 工具条', description: '编辑器式按钮组。' },
+      { name: 'command-palette', title: 'CommandPalette 命令面板', description: '面向开发者工具的全局命令与导航入口。' },
+      { name: 'app-shell', title: 'AppShell 应用布局', description: '控制台的侧栏、顶栏与主内容骨架。' },
+      { name: 'resizable-panel', title: 'ResizablePanel 可调面板', description: '可拖拽、可键盘调整的工作区分栏。' }
     ]
   },
   {
@@ -94,7 +98,8 @@ export const docGroups: DocGroup[] = [
       { name: 'tooltip', title: 'Tooltip 文字提示', description: '悬停即时提示。' },
       { name: 'popover', title: 'Popover 浮层', description: '轻量内容弹层。' },
       { name: 'hover-card', title: 'HoverCard 悬停卡片', description: '预览用户信息卡。' },
-      { name: 'toast', title: 'Toast 吐司提示', description: '全局操作反馈队列。' }
+      { name: 'toast', title: 'Toast 吐司提示', description: '全局操作反馈队列。' },
+      { name: 'sheet', title: 'Sheet 抽屉面板', description: '资源详情、配置与辅助操作面板。' }
     ]
   },
   {
diff --git a/packages/ui/src/components/command-palette/CommandPalette.vue b/packages/ui/src/components/command-palette/CommandPalette.vue
new file mode 100644
index 0000000..91a09bb
--- /dev/null
+++ b/packages/ui/src/components/command-palette/CommandPalette.vue
@@ -0,0 +1,200 @@
+<template>
+  <DialogRoot :open="open" @update:open="setOpen">
+    <DialogPortal>
+      <DialogOverlay class="fixed inset-0 z-50 bg-slate-950/45 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0" />
+      <DialogContent
+        class="fixed top-[16vh] left-1/2 z-50 w-[calc(100%-2rem)] max-w-2xl -translate-x-1/2 overflow-hidden rounded-xl bg-white shadow-2xl ring-1 ring-slate-200 outline-none dark:bg-[#0F172A] dark:ring-slate-800 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95"
+        :class="props.class"
+        @open-auto-focus="focusInput"
+      >
+        <DialogTitle class="sr-only">{{ props.label }}</DialogTitle>
+        <div class="flex items-center gap-3 border-b border-slate-200 px-4 dark:border-slate-800">
+          <svg class="h-4 w-4 shrink-0 text-slate-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7" /><path stroke-linecap="round" d="m20 20-3.5-3.5" /></svg>
+          <input
+            ref="input"
+            :value="query"
+            type="text"
+            role="combobox"
+            aria-autocomplete="list"
+            aria-controls="command-palette-list"
+            :aria-activedescendant="activeItem ? itemDomId(activeItem) : undefined"
+            :placeholder="props.placeholder"
+            class="h-14 min-w-0 grow bg-transparent text-sm text-slate-900 outline-none placeholder:text-slate-400 dark:text-slate-100"
+            @input="setQuery(($event.target as HTMLInputElement).value)"
+            @keydown.down.prevent="moveActive(1)"
+            @keydown.up.prevent="moveActive(-1)"
+            @keydown.enter.prevent="selectActive"
+            @keydown.esc.prevent="setOpen(false)"
+          >
+          <kbd v-if="props.shortcut" class="rounded border border-slate-200 bg-slate-50 px-1.5 py-0.5 font-mono text-[10px] text-slate-500 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-400">{{ displayShortcut }}</kbd>
+        </div>
+
+        <div id="command-palette-list" role="listbox" :aria-label="props.label" class="max-h-[min(60vh,30rem)] overflow-y-auto p-2">
+          <template v-for="group in filteredGroups" :key="group.key">
+            <div v-if="group.heading" class="px-2 pt-3 pb-1 text-[11px] font-semibold tracking-wider text-slate-400 uppercase dark:text-slate-500">{{ group.heading }}</div>
+            <button
+              v-for="item in group.items"
+              :id="itemDomId(item)"
+              :key="item.id"
+              type="button"
+              role="option"
+              :aria-selected="activeItem?.id === item.id"
+              :disabled="item.disabled"
+              class="flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left outline-none transition-colors disabled:pointer-events-none disabled:opacity-45"
+              :class="activeItem?.id === item.id ? 'bg-slate-100 dark:bg-slate-800' : 'hover:bg-slate-50 dark:hover:bg-slate-800/60'"
+              @mouseenter="setActive(item.id)"
+              @click="selectItem(item)"
+            >
+              <component :is="item.icon" v-if="item.icon" class="h-4 w-4 shrink-0 text-slate-500 dark:text-slate-400" aria-hidden="true" />
+              <slot name="item" :item="item" :active="activeItem?.id === item.id">
+                <span class="min-w-0 grow">
+                  <span class="block truncate text-sm font-medium text-slate-800 dark:text-slate-100">{{ item.label }}</span>
+                  <span v-if="item.description" class="mt-0.5 block truncate text-xs text-slate-500 dark:text-slate-400">{{ item.description }}</span>
+                </span>
+                <span v-if="item.shortcut?.length" class="ml-auto flex shrink-0 gap-1">
+                  <kbd v-for="key in item.shortcut" :key="key" class="rounded border border-slate-200 bg-slate-50 px-1.5 py-0.5 font-mono text-[10px] text-slate-500 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-400">{{ key }}</kbd>
+                </span>
+              </slot>
+            </button>
+          </template>
+          <div v-if="!filteredItems.length" class="px-3 py-10 text-center text-sm text-slate-500 dark:text-slate-400">
+            <slot name="empty" :query="query">{{ props.emptyText }}</slot>
+          </div>
+        </div>
+      </DialogContent>
+    </DialogPortal>
+  </DialogRoot>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTitle } from 'reka-ui'
+import { filterCommands } from './commandMatcher'
+import type { CommandFilter, CommandGroup, CommandItem } from './types'
+
+export interface CommandPaletteProps {
+  open?: boolean
+  query?: string
+  groups: CommandGroup[]
+  placeholder?: string
+  emptyText?: string
+  label?: string
+  shortcut?: string
+  /** Allow the global shortcut while typing in an editable element. */
+  shortcutInEditable?: boolean
+  filter?: CommandFilter
+  class?: string
+}
+
+const props = withDefaults(defineProps<CommandPaletteProps>(), {
+  open: false,
+  query: undefined,
+  placeholder: '搜索命令…',
+  emptyText: '没有找到匹配的命令。',
+  label: '命令面板',
+  shortcut: undefined,
+  shortcutInEditable: false,
+  filter: undefined,
+  class: ''
+})
+
+const emit = defineEmits<{
+  (event: 'update:open', value: boolean): void
+  (event: 'update:query', value: string): void
+  (event: 'select', item: CommandItem): void
+}>()
+
+const input = ref<HTMLInputElement>()
+const internalQuery = ref('')
+const activeId = ref<string>()
+const isQueryControlled = computed(() => props.query !== undefined)
+const query = computed(() => isQueryControlled.value ? props.query ?? '' : internalQuery.value)
+const allItems = computed(() => props.groups.flatMap((group) => group.items))
+const filteredItems = computed(() => props.filter ? props.filter(allItems.value, query.value) : filterCommands(allItems.value, query.value))
+const filteredGroups = computed(() => props.groups.map((group, index) => ({
+  key: group.id ?? `${group.heading ?? 'group'}-${index}`,
+  heading: group.heading,
+  items: group.items.filter((item) => filteredItems.value.some((filtered) => filtered.id === item.id))
+})).filter((group) => group.items.length > 0))
+const enabledItems = computed(() => filteredItems.value.filter((item) => !item.disabled))
+const activeItem = computed(() => enabledItems.value.find((item) => item.id === activeId.value))
+const displayShortcut = computed(() => props.shortcut?.replace(/mod/gi, navigatorPlatformIsMac() ? '⌘' : 'Ctrl').replace(/\+/g, ' + '))
+
+function navigatorPlatformIsMac() {
+  return typeof navigator !== 'undefined' && /mac/i.test(navigator.platform)
+}
+
+function itemDomId(item: CommandItem) {
+  return `command-palette-item-${item.id}`
+}
+
+function setOpen(value: boolean) {
+  emit('update:open', value)
+  if (value) {
+    if (!isQueryControlled.value) internalQuery.value = ''
+    nextTick(focusInput)
+  }
+}
+
+function setQuery(value: string) {
+  if (!isQueryControlled.value) internalQuery.value = value
+  emit('update:query', value)
+}
+
+function setActive(id: string) {
+  activeId.value = id
+}
+
+function moveActive(direction: 1 | -1) {
+  const items = enabledItems.value
+  if (!items.length) return
+  const currentIndex = items.findIndex((item) => item.id === activeId.value)
+  const nextIndex = (currentIndex + direction + items.length) % items.length
+  activeId.value = items[nextIndex].id
+  document.getElementById(itemDomId(items[nextIndex]))?.scrollIntoView({ block: 'nearest' })
+}
+
+function selectActive() {
+  if (activeItem.value) selectItem(activeItem.value)
+}
+
+function selectItem(item: CommandItem) {
+  if (item.disabled) return
+  emit('select', item)
+  if (!item.keepOpen) setOpen(false)
+}
+
+function focusInput(event?: Event) {
+  event?.preventDefault()
+  nextTick(() => input.value?.focus())
+}
+
+function isEditable(target: EventTarget | null) {
+  const element = target instanceof HTMLElement ? target : null
+  return Boolean(element?.closest('input, textarea, [contenteditable="true"]'))
+}
+
+function matchesShortcut(event: KeyboardEvent) {
+  if (!props.shortcut) return false
+  const parts = props.shortcut.toLocaleLowerCase().split('+').map((part) => part.trim())
+  const key = parts.find((part) => !['mod', 'shift', 'alt'].includes(part))
+  return Boolean(key)
+    && event.key.toLocaleLowerCase() === key
+    && event.shiftKey === parts.includes('shift')
+    && event.altKey === parts.includes('alt')
+    && (navigatorPlatformIsMac() ? event.metaKey : event.ctrlKey) === parts.includes('mod')
+}
+
+function handleGlobalKeydown(event: KeyboardEvent) {
+  if (props.open || (!props.shortcutInEditable && isEditable(event.target)) || !matchesShortcut(event)) return
+  event.preventDefault()
+  setOpen(true)
+}
+
+watch(enabledItems, (items) => {
+  if (!items.some((item) => item.id === activeId.value)) activeId.value = items[0]?.id
+}, { immediate: true })
+
+onMounted(() => window.addEventListener('keydown', handleGlobalKeydown))
+onBeforeUnmount(() => window.removeEventListener('keydown', handleGlobalKeydown))
+</script>
diff --git a/packages/ui/src/components/command-palette/commandMatcher.test.ts b/packages/ui/src/components/command-palette/commandMatcher.test.ts
new file mode 100644
index 0000000..f0abb23
--- /dev/null
+++ b/packages/ui/src/components/command-palette/commandMatcher.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { filterCommands, scoreCommand } from './commandMatcher'
+import type { CommandItem } from './types'
+
+const items: CommandItem[] = [
+  { id: 'webhooks', label: '管理 Webhooks', keywords: ['webhook', 'events'] },
+  { id: 'dashboard', label: '前往仪表盘', keywords: ['home', 'dashboard'] },
+  { id: 'disabled', label: '已禁用命令', disabled: true }
+]
+
+describe('commandMatcher', () => {
+  it('matches abbreviations as a subsequence', () => {
+    expect(scoreCommand(items[0], 'wh')).not.toBeNull()
+    expect(scoreCommand(items[0], 'wz')).toBeNull()
+  })
+
+  it('returns matches in descending relevance order', () => {
+    expect(filterCommands(items, 'dash').map((item) => item.id)).toEqual(['dashboard'])
+  })
+
+  it('preserves the input order for an empty query', () => {
+    expect(filterCommands(items, '').map((item) => item.id)).toEqual(items.map((item) => item.id))
+  })
+})
diff --git a/packages/ui/src/components/command-palette/commandMatcher.ts b/packages/ui/src/components/command-palette/commandMatcher.ts
new file mode 100644
index 0000000..f9d0141
--- /dev/null
+++ b/packages/ui/src/components/command-palette/commandMatcher.ts
@@ -0,0 +1,52 @@
+import type { CommandItem } from './types'
+
+export interface CommandMatch {
+  item: CommandItem
+  score: number
+  index: number
+}
+
+/**
+ * Scores a case-insensitive subsequence match. Consecutive characters and
+ * word boundaries rank above scattered matches, while preserving input order
+ * for equally relevant commands.
+ */
+export function scoreCommand(item: CommandItem, query: string): number | null {
+  const normalizedQuery = query.trim().toLocaleLowerCase()
+  if (!normalizedQuery) return 0
+
+  const haystack = [item.label, item.description, ...(item.keywords ?? [])]
+    .filter(Boolean)
+    .join(' ')
+    .toLocaleLowerCase()
+
+  let score = 0
+  let previousIndex = -2
+  let cursor = 0
+
+  for (const character of normalizedQuery) {
+    const index = haystack.indexOf(character, cursor)
+    if (index === -1) return null
+
+    score += 10
+    if (index === previousIndex + 1) score += 8
+    if (index === 0 || /[\s/._:-]/.test(haystack[index - 1])) score += 5
+
+    previousIndex = index
+    cursor = index + 1
+  }
+
+  // Prefer concise labels when all other match characteristics are equal.
+  return score - haystack.length / 1000
+}
+
+export function filterCommands(items: CommandItem[], query: string): CommandItem[] {
+  return items
+    .map((item, index): CommandMatch | null => {
+      const score = scoreCommand(item, query)
+      return score === null ? null : { item, score, index }
+    })
+    .filter((match): match is CommandMatch => match !== null)
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .map(({ item }) => item)
+}
diff --git a/packages/ui/src/components/command-palette/index.ts b/packages/ui/src/components/command-palette/index.ts
new file mode 100644
index 0000000..094fd16
--- /dev/null
+++ b/packages/ui/src/components/command-palette/index.ts
@@ -0,0 +1,2 @@
+export { default as CommandPalette } from './CommandPalette.vue'
+export type { CommandFilter, CommandGroup, CommandItem } from './types'
diff --git a/packages/ui/src/components/command-palette/types.ts b/packages/ui/src/components/command-palette/types.ts
new file mode 100644
index 0000000..674e461
--- /dev/null
+++ b/packages/ui/src/components/command-palette/types.ts
@@ -0,0 +1,22 @@
+import type { Component } from 'vue'
+
+export interface CommandItem {
+  /** Stable identifier returned with the select event. */
+  id: string
+  label: string
+  description?: string
+  keywords?: string[]
+  shortcut?: string[]
+  icon?: Component
+  disabled?: boolean
+  /** Keep the palette open after this item is selected. */
+  keepOpen?: boolean
+}
+
+export interface CommandGroup {
+  id?: string
+  heading?: string
+  items: CommandItem[]
+}
+
+export type CommandFilter = (items: CommandItem[], query: string) => CommandItem[]
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 740a568..f686d9f 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -49,6 +49,11 @@ export * from './components/aspect-ratio'
 export * from './components/toolbar'
 export * from './components/visually-hidden'
 export * from './components/navigation-menu'
+export * from './components/command-palette'
+export * from './components/sheet'
+export * from './components/date-picker'
+export * from './components/app-shell'
+export * from './components/resizable-panel'
 
 // Composables & Utilities
 export * from './composables/useTheme'

From e0be15719272dd3106a6021ccf7886fe34fb9e82 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:50:42 +0800
Subject: [PATCH 03/26] feat: add sheet drawer

---
 .changeset/calm-sheets-deploy.md           |  5 ++
 apps/playground/pages/components/sheet.vue | 54 +++++++++++++++++
 packages/ui/src/components/sheet/Sheet.vue | 68 ++++++++++++++++++++++
 packages/ui/src/components/sheet/index.ts  |  1 +
 4 files changed, 128 insertions(+)
 create mode 100644 .changeset/calm-sheets-deploy.md
 create mode 100644 apps/playground/pages/components/sheet.vue
 create mode 100644 packages/ui/src/components/sheet/Sheet.vue
 create mode 100644 packages/ui/src/components/sheet/index.ts

diff --git a/.changeset/calm-sheets-deploy.md b/.changeset/calm-sheets-deploy.md
new file mode 100644
index 0000000..ae3180a
--- /dev/null
+++ b/.changeset/calm-sheets-deploy.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add Sheet, a directional drawer for console details and secondary actions.
diff --git a/apps/playground/pages/components/sheet.vue b/apps/playground/pages/components/sheet.vue
new file mode 100644
index 0000000..dcb6bc6
--- /dev/null
+++ b/apps/playground/pages/components/sheet.vue
@@ -0,0 +1,54 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Sheet 抽屉面板" description="用于资源详情、配置编辑和辅助操作的可访问模态侧栏，支持四个展开方向。" />
+
+    <DocExample title="实例详情" description="默认从右侧展开；使用 header、默认和 footer 插槽构建详情工作流。" :code="rcCode0">
+      <Button @click="open = true">查看实例详情</Button>
+      <Sheet v-model:open="open" title="hkg-edge-07" description="运行中的边缘节点 · 香港" size="30rem">
+        <div class="space-y-5">
+          <div class="grid grid-cols-2 gap-3 text-sm">
+            <div class="rounded-lg bg-slate-50 p-3 dark:bg-slate-800/60"><p class="text-xs text-slate-500">公网地址</p><p class="mt-1 font-mono text-slate-800 dark:text-slate-100">203.0.113.42</p></div>
+            <div class="rounded-lg bg-slate-50 p-3 dark:bg-slate-800/60"><p class="text-xs text-slate-500">运行时间</p><p class="mt-1 text-slate-800 dark:text-slate-100">14 天 8 小时</p></div>
+          </div>
+          <Banner color="success" title="健康检查正常">最近一次心跳：刚刚</Banner>
+        </div>
+        <template #footer>
+          <div class="flex justify-end gap-2">
+            <Button variant="outline" color="neutral" @click="open = false">关闭</Button>
+            <Button @click="open = false">保存配置</Button>
+          </div>
+        </template>
+      </Sheet>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="sheet" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+const open = ref(false)
+
+const rcCode0 = `<Button @click="open = true">查看实例详情</Button>
+<Sheet
+  v-model:open="open"
+  title="hkg-edge-07"
+  description="运行中的边缘节点 · 香港"
+  side="right"
+  size="30rem"
+>
+  <InstanceDetails />
+  <template #footer>
+    <Button @click="open = false">保存配置</Button>
+  </template>
+</Sheet>`
+
+const apiRows = [
+  { name: 'v-model:open', type: 'boolean', default: 'false', description: '受控展开状态。' },
+  { name: 'side', type: "'left' | 'right' | 'top' | 'bottom'", default: "'right'", description: '抽屉展开方向。' },
+  { name: 'size', type: 'string', default: "'28rem'", description: '左右抽屉的宽度，或上下抽屉的高度。' },
+  { name: 'title / description', type: 'string', default: '—', description: '默认头部文案。' },
+  { name: 'trigger / header / footer', type: 'slot', default: '—', description: '触发器和结构区域插槽。' }
+]
+</script>
diff --git a/packages/ui/src/components/sheet/Sheet.vue b/packages/ui/src/components/sheet/Sheet.vue
new file mode 100644
index 0000000..aa51f08
--- /dev/null
+++ b/packages/ui/src/components/sheet/Sheet.vue
@@ -0,0 +1,68 @@
+<template>
+  <DialogRoot :open="props.open" @update:open="$emit('update:open', $event)">
+    <DialogTrigger v-if="$slots.trigger" as-child><slot name="trigger" /></DialogTrigger>
+    <DialogPortal>
+      <DialogOverlay class="fixed inset-0 z-50 bg-slate-950/45 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0" />
+      <DialogContent :class="contentClasses" :style="{ '--sheet-size': props.size }">
+        <div v-if="title || description || $slots.header" class="shrink-0 border-b border-slate-200 px-5 py-4 dark:border-slate-800">
+          <slot name="header">
+            <DialogTitle v-if="title" class="pr-8 text-base font-semibold tracking-tight text-slate-900 dark:text-slate-100">{{ title }}</DialogTitle>
+            <DialogDescription v-if="description" class="mt-1 text-sm leading-6 text-slate-500 dark:text-slate-400">{{ description }}</DialogDescription>
+          </slot>
+        </div>
+
+        <div class="min-h-0 grow overflow-y-auto px-5 py-5"><slot /></div>
+
+        <div v-if="$slots.footer" class="shrink-0 border-t border-slate-200 px-5 py-4 dark:border-slate-800"><slot name="footer" /></div>
+
+        <DialogClose aria-label="关闭" class="absolute top-3.5 right-3.5 rounded-md p-1 text-slate-400 transition-colors hover:bg-slate-100 hover:text-slate-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-500 dark:hover:bg-slate-800 dark:hover:text-slate-300">
+          <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" /></svg>
+        </DialogClose>
+      </DialogContent>
+    </DialogPortal>
+  </DialogRoot>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from 'reka-ui'
+import { cn } from '../../utils/cn'
+
+export interface SheetProps {
+  open?: boolean
+  side?: 'left' | 'right' | 'top' | 'bottom'
+  /** CSS size value; width for left/right and height for top/bottom. */
+  size?: string
+  title?: string
+  description?: string
+  class?: string
+}
+
+const props = withDefaults(defineProps<SheetProps>(), {
+  open: undefined,
+  side: 'right',
+  size: '28rem',
+  title: '',
+  description: '',
+  class: ''
+})
+
+defineEmits<{
+  (event: 'update:open', value: boolean): void
+}>()
+
+const contentClasses = computed(() => {
+  const position = {
+    right: 'top-0 right-0 h-dvh w-[var(--sheet-size)] data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right',
+    left: 'top-0 left-0 h-dvh w-[var(--sheet-size)] data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left',
+    top: 'top-0 left-0 h-[var(--sheet-size)] w-full data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top',
+    bottom: 'bottom-0 left-0 h-[var(--sheet-size)] w-full data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom'
+  }[props.side]
+
+  return cn(
+    'fixed z-50 flex max-w-full flex-col bg-white shadow-2xl outline-none ring-1 ring-slate-200 dark:bg-[#0F172A] dark:ring-slate-800 data-[state=open]:animate-in data-[state=closed]:animate-out',
+    position,
+    props.class
+  )
+})
+</script>
diff --git a/packages/ui/src/components/sheet/index.ts b/packages/ui/src/components/sheet/index.ts
new file mode 100644
index 0000000..a8c9060
--- /dev/null
+++ b/packages/ui/src/components/sheet/index.ts
@@ -0,0 +1 @@
+export { default as Sheet } from './Sheet.vue'

From 39f3ac906a95b8f9732a1ee33f0a7229dab8713b Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:50:47 +0800
Subject: [PATCH 04/26] feat: add date picker components

---
 .changeset/green-dates-arrive.md              |  5 ++
 .../pages/components/date-picker.vue          | 48 +++++++++++
 .../src/components/date-picker/DatePicker.vue | 79 ++++++++++++++++++
 .../date-picker/DateRangePicker.vue           | 82 +++++++++++++++++++
 .../components/date-picker/dateUtils.test.ts  | 19 +++++
 .../src/components/date-picker/dateUtils.ts   | 44 ++++++++++
 .../ui/src/components/date-picker/index.ts    |  3 +
 7 files changed, 280 insertions(+)
 create mode 100644 .changeset/green-dates-arrive.md
 create mode 100644 apps/playground/pages/components/date-picker.vue
 create mode 100644 packages/ui/src/components/date-picker/DatePicker.vue
 create mode 100644 packages/ui/src/components/date-picker/DateRangePicker.vue
 create mode 100644 packages/ui/src/components/date-picker/dateUtils.test.ts
 create mode 100644 packages/ui/src/components/date-picker/dateUtils.ts
 create mode 100644 packages/ui/src/components/date-picker/index.ts

diff --git a/.changeset/green-dates-arrive.md b/.changeset/green-dates-arrive.md
new file mode 100644
index 0000000..9bd1f00
--- /dev/null
+++ b/.changeset/green-dates-arrive.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add DatePicker and DateRangePicker with stable local date values and range presets.
diff --git a/apps/playground/pages/components/date-picker.vue b/apps/playground/pages/components/date-picker.vue
new file mode 100644
index 0000000..e374c09
--- /dev/null
+++ b/apps/playground/pages/components/date-picker.vue
@@ -0,0 +1,48 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="DatePicker 日期选择" description="适用于备份、事件和任务记录的单日期与日期范围筛选，采用稳定的 YYYY-MM-DD 值。" />
+
+    <DocExample title="日期范围筛选" description="范围选择器内置快捷范围；日期禁用和边界由调用方以本地日期键控制。" :code="rcCode0">
+      <div class="grid gap-4 sm:grid-cols-2">
+        <DatePicker v-model="date" label="执行日期" min="2026-01-01" />
+        <DateRangePicker v-model="range" label="事件时间范围" :presets="presets" />
+      </div>
+      <p class="mt-3 font-mono text-xs text-slate-500 dark:text-slate-400">日期：{{ date }} · 范围：{{ range?.start }} → {{ range?.end }}</p>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="date-picker" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { DateRangeValue } from '@recloudstudio/ui'
+
+const date = ref('2026-10-04')
+const range = ref<DateRangeValue>({ start: '2026-09-28', end: '2026-10-04' })
+const presets = [
+  { label: '今天', value: { start: '2026-10-04', end: '2026-10-04' } },
+  { label: '近 7 天', value: { start: '2026-09-28', end: '2026-10-04' } },
+  { label: '本月', value: { start: '2026-10-01', end: '2026-10-04' } }
+]
+
+const rcCode0 = `<script setup lang="ts">
+import { ref } from 'vue'
+const date = ref('2026-10-04')
+const range = ref({ start: '2026-09-28', end: '2026-10-04' })
+<\/script>
+
+<template>
+  <DatePicker v-model="date" label="执行日期" min="2026-01-01" />
+  <DateRangePicker v-model="range" label="事件时间范围" :presets="presets" />
+<\/template>`
+
+const apiRows = [
+  { name: 'v-model', type: 'string', default: '—', description: 'DatePicker 绑定 YYYY-MM-DD 本地日期键。' },
+  { name: 'v-model', type: '{ start: string; end: string }', default: '—', description: 'DateRangePicker 绑定起止日期键。' },
+  { name: 'min / max', type: 'string', default: '—', description: '可选的 YYYY-MM-DD 可选日期边界。' },
+  { name: 'disabled-dates', type: 'string[] | (date) => boolean', default: '—', description: '禁用指定日期或自定义禁用规则。' },
+  { name: 'presets', type: '{ label, value }[]', default: '[]', description: 'DateRangePicker 中的快捷日期范围。' }
+]
+</script>
diff --git a/packages/ui/src/components/date-picker/DatePicker.vue b/packages/ui/src/components/date-picker/DatePicker.vue
new file mode 100644
index 0000000..2a07281
--- /dev/null
+++ b/packages/ui/src/components/date-picker/DatePicker.vue
@@ -0,0 +1,79 @@
+<template>
+  <div class="w-full" :class="props.class">
+    <label v-if="label" class="mb-1.5 block text-sm font-medium text-slate-700 dark:text-slate-200">{{ label }}</label>
+    <PopoverRoot v-model:open="open">
+      <PopoverTrigger as-child>
+        <button type="button" :disabled="disabled" class="flex h-10 w-full items-center gap-2 rounded-lg bg-white px-3.5 text-left text-sm text-slate-900 shadow-xs ring-1 ring-inset ring-slate-300 transition-all hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] disabled:cursor-not-allowed disabled:opacity-50 dark:bg-[#0F172A] dark:text-slate-100 dark:ring-slate-700 dark:hover:bg-slate-900 dark:focus-visible:ring-[#70ACFE]">
+          <svg class="h-4 w-4 shrink-0 text-slate-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="5" width="18" height="16" rx="2"/><path d="M16 3v4M8 3v4M3 11h18" /></svg>
+          <span :class="displayValue ? '' : 'text-slate-400 dark:text-slate-500'">{{ displayValue || placeholder }}</span>
+        </button>
+      </PopoverTrigger>
+      <PopoverPortal>
+        <PopoverContent side="bottom" align="start" :side-offset="6" class="z-50 w-[19rem] rounded-xl bg-white p-3 shadow-xl ring-1 ring-slate-200 outline-none dark:bg-[#0F172A] dark:ring-slate-800">
+          <div class="mb-3 flex items-center justify-between">
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 hover:text-slate-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100" aria-label="上个月" @click="visibleMonth = addMonths(visibleMonth, -1)">‹</button>
+            <span class="text-sm font-semibold text-slate-800 dark:text-slate-100">{{ monthLabel }}</span>
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 hover:text-slate-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100" aria-label="下个月" @click="visibleMonth = addMonths(visibleMonth, 1)">›</button>
+          </div>
+          <div class="mb-1 grid grid-cols-7 text-center text-[11px] font-medium text-slate-400 dark:text-slate-500"><span v-for="day in weekdays" :key="day">{{ day }}</span></div>
+          <div role="grid" :aria-label="monthLabel" class="grid grid-cols-7 gap-0.5">
+            <button v-for="day in days" :key="day.key" type="button" role="gridcell" :disabled="isDisabled(day.key)" :aria-selected="modelValue === day.key" :class="dayClasses(day)" @click="selectDay(day.key)">{{ day.date.getDate() }}</button>
+          </div>
+        </PopoverContent>
+      </PopoverPortal>
+    </PopoverRoot>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger } from 'reka-ui'
+import { addMonths, formatDate, monthDays, parseDateKey, toDateKey } from './dateUtils'
+import { cn } from '../../utils/cn'
+
+export interface DatePickerProps {
+  modelValue?: string
+  placeholder?: string
+  label?: string
+  min?: string
+  max?: string
+  disabledDates?: string[] | ((date: string) => boolean)
+  disabled?: boolean
+  class?: string
+}
+
+const props = withDefaults(defineProps<DatePickerProps>(), { modelValue: '', placeholder: '选择日期', label: '', min: '', max: '', disabledDates: undefined, disabled: false, class: '' })
+const emit = defineEmits<{ (event: 'update:modelValue', value: string): void }>()
+const open = ref(false)
+const visibleMonth = ref(parseDateKey(props.modelValue) ?? new Date())
+const weekdays = ['一', '二', '三', '四', '五', '六', '日']
+const days = computed(() => monthDays(visibleMonth.value))
+const monthLabel = computed(() => new Intl.DateTimeFormat(undefined, { year: 'numeric', month: 'long' }).format(visibleMonth.value))
+const displayValue = computed(() => formatDate(props.modelValue))
+
+watch(() => props.modelValue, (value) => {
+  const parsed = parseDateKey(value)
+  if (parsed) visibleMonth.value = parsed
+})
+
+function isDisabled(date: string) {
+  if (props.min && date < props.min) return true
+  if (props.max && date > props.max) return true
+  return Array.isArray(props.disabledDates) ? props.disabledDates.includes(date) : props.disabledDates?.(date) ?? false
+}
+
+function selectDay(date: string) {
+  if (isDisabled(date)) return
+  emit('update:modelValue', date)
+  open.value = false
+}
+
+function dayClasses(day: { key: string; outside: boolean }) {
+  return cn(
+    'grid h-9 place-items-center rounded-md text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] disabled:pointer-events-none disabled:opacity-35 dark:focus-visible:ring-[#70ACFE]',
+    day.outside ? 'text-slate-400 dark:text-slate-600' : 'text-slate-700 hover:bg-slate-100 dark:text-slate-200 dark:hover:bg-slate-800',
+    day.key === toDateKey(new Date()) && 'font-semibold text-[#2563EB] dark:text-[#70ACFE]',
+    props.modelValue === day.key && 'bg-[#2563EB] text-white hover:bg-[#1D4ED8] dark:bg-[#70ACFE] dark:text-slate-950 dark:hover:bg-[#70ACFE]'
+  )
+}
+</script>
diff --git a/packages/ui/src/components/date-picker/DateRangePicker.vue b/packages/ui/src/components/date-picker/DateRangePicker.vue
new file mode 100644
index 0000000..05240bf
--- /dev/null
+++ b/packages/ui/src/components/date-picker/DateRangePicker.vue
@@ -0,0 +1,82 @@
+<template>
+  <div class="w-full" :class="props.class">
+    <label v-if="label" class="mb-1.5 block text-sm font-medium text-slate-700 dark:text-slate-200">{{ label }}</label>
+    <PopoverRoot v-model:open="open">
+      <PopoverTrigger as-child>
+        <button type="button" :disabled="disabled" class="flex h-10 w-full items-center gap-2 rounded-lg bg-white px-3.5 text-left text-sm text-slate-900 shadow-xs ring-1 ring-inset ring-slate-300 transition-all hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] disabled:cursor-not-allowed disabled:opacity-50 dark:bg-[#0F172A] dark:text-slate-100 dark:ring-slate-700 dark:hover:bg-slate-900 dark:focus-visible:ring-[#70ACFE]">
+          <svg class="h-4 w-4 shrink-0 text-slate-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="5" width="18" height="16" rx="2"/><path d="M16 3v4M8 3v4M3 11h18" /></svg>
+          <span :class="displayValue ? '' : 'text-slate-400 dark:text-slate-500'">{{ displayValue || placeholder }}</span>
+        </button>
+      </PopoverTrigger>
+      <PopoverPortal>
+        <PopoverContent side="bottom" align="start" :side-offset="6" class="z-50 w-[19rem] rounded-xl bg-white p-3 shadow-xl ring-1 ring-slate-200 outline-none dark:bg-[#0F172A] dark:ring-slate-800">
+          <div v-if="presets.length" class="mb-3 flex flex-wrap gap-1 border-b border-slate-100 pb-3 dark:border-slate-800">
+            <button v-for="preset in presets" :key="preset.label" type="button" class="rounded-md px-2 py-1 text-xs font-medium text-slate-600 hover:bg-slate-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-300 dark:hover:bg-slate-800" @click="applyPreset(preset.value)">{{ preset.label }}</button>
+          </div>
+          <div class="mb-3 flex items-center justify-between">
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 dark:text-slate-400 dark:hover:bg-slate-800" aria-label="上个月" @click="visibleMonth = addMonths(visibleMonth, -1)">‹</button>
+            <span class="text-sm font-semibold text-slate-800 dark:text-slate-100">{{ monthLabel }}</span>
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 dark:text-slate-400 dark:hover:bg-slate-800" aria-label="下个月" @click="visibleMonth = addMonths(visibleMonth, 1)">›</button>
+          </div>
+          <div class="mb-1 grid grid-cols-7 text-center text-[11px] font-medium text-slate-400 dark:text-slate-500"><span v-for="day in weekdays" :key="day">{{ day }}</span></div>
+          <div role="grid" :aria-label="monthLabel" class="grid grid-cols-7 gap-0.5">
+            <button v-for="day in days" :key="day.key" type="button" role="gridcell" :disabled="isDisabled(day.key)" :aria-selected="isSelected(day.key)" :class="dayClasses(day)" @click="selectDay(day.key)">{{ day.date.getDate() }}</button>
+          </div>
+          <p v-if="pendingStart" class="mt-3 text-center text-xs text-slate-500 dark:text-slate-400">已选择开始日期，请选择结束日期。</p>
+        </PopoverContent>
+      </PopoverPortal>
+    </PopoverRoot>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger } from 'reka-ui'
+import { addMonths, compareDateKeys, formatDate, monthDays, parseDateKey, toDateKey, type DateRangeValue } from './dateUtils'
+import { cn } from '../../utils/cn'
+
+export interface DateRangePreset { label: string; value: DateRangeValue }
+export interface DateRangePickerProps {
+  modelValue?: DateRangeValue | undefined
+  placeholder?: string
+  label?: string
+  min?: string
+  max?: string
+  disabledDates?: string[] | ((date: string) => boolean)
+  presets?: DateRangePreset[]
+  disabled?: boolean
+  class?: string
+}
+
+const props = withDefaults(defineProps<DateRangePickerProps>(), { modelValue: undefined, placeholder: '选择日期范围', label: '', min: '', max: '', disabledDates: undefined, presets: () => [], disabled: false, class: '' })
+const emit = defineEmits<{ (event: 'update:modelValue', value: DateRangeValue | undefined): void }>()
+const open = ref(false)
+const pendingStart = ref<string>()
+const visibleMonth = ref(parseDateKey(props.modelValue?.start) ?? new Date())
+const weekdays = ['一', '二', '三', '四', '五', '六', '日']
+const days = computed(() => monthDays(visibleMonth.value))
+const monthLabel = computed(() => new Intl.DateTimeFormat(undefined, { year: 'numeric', month: 'long' }).format(visibleMonth.value))
+const displayValue = computed(() => props.modelValue ? `${formatDate(props.modelValue.start)} — ${formatDate(props.modelValue.end)}` : '')
+
+watch(() => props.modelValue?.start, (value) => { const parsed = parseDateKey(value); if (parsed) visibleMonth.value = parsed })
+
+function isDisabled(date: string) {
+  if (props.min && date < props.min) return true
+  if (props.max && date > props.max) return true
+  return Array.isArray(props.disabledDates) ? props.disabledDates.includes(date) : props.disabledDates?.(date) ?? false
+}
+function isSelected(date: string) { return Boolean(props.modelValue && date >= props.modelValue.start && date <= props.modelValue.end) }
+function selectDay(date: string) {
+  if (isDisabled(date)) return
+  if (!pendingStart.value) { pendingStart.value = date; return }
+  const [start, end] = compareDateKeys(pendingStart.value, date) <= 0 ? [pendingStart.value, date] : [date, pendingStart.value]
+  emit('update:modelValue', { start, end })
+  pendingStart.value = undefined
+  open.value = false
+}
+function applyPreset(value: DateRangeValue) { emit('update:modelValue', value); pendingStart.value = undefined; open.value = false }
+function dayClasses(day: { key: string; outside: boolean }) {
+  const selected = isSelected(day.key)
+  return cn('grid h-9 place-items-center rounded-md text-sm transition-colors disabled:pointer-events-none disabled:opacity-35', day.outside ? 'text-slate-400 dark:text-slate-600' : 'text-slate-700 hover:bg-slate-100 dark:text-slate-200 dark:hover:bg-slate-800', selected && 'rounded-none bg-blue-50 text-[#1D4ED8] dark:bg-blue-950/60 dark:text-[#93C5FD]', (props.modelValue?.start === day.key || props.modelValue?.end === day.key) && 'rounded-md bg-[#2563EB] font-medium text-white dark:bg-[#70ACFE] dark:text-slate-950', day.key === toDateKey(new Date()) && !selected && 'font-semibold text-[#2563EB] dark:text-[#70ACFE]')
+}
+</script>
diff --git a/packages/ui/src/components/date-picker/dateUtils.test.ts b/packages/ui/src/components/date-picker/dateUtils.test.ts
new file mode 100644
index 0000000..be435bc
--- /dev/null
+++ b/packages/ui/src/components/date-picker/dateUtils.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { addMonths, monthDays, parseDateKey, toDateKey } from './dateUtils'
+
+describe('dateUtils', () => {
+  it('parses only valid ISO date keys', () => {
+    expect(toDateKey(parseDateKey('2026-02-28')!)).toBe('2026-02-28')
+    expect(parseDateKey('2026-02-30')).toBeUndefined()
+  })
+
+  it('always generates a six-week calendar grid', () => {
+    const days = monthDays(new Date(2026, 1, 1))
+    expect(days).toHaveLength(42)
+    expect(days.some((day) => day.key === '2026-02-01')).toBe(true)
+  })
+
+  it('moves months over year boundaries', () => {
+    expect(toDateKey(addMonths(new Date(2026, 0, 1), -1))).toBe('2025-12-01')
+  })
+})
diff --git a/packages/ui/src/components/date-picker/dateUtils.ts b/packages/ui/src/components/date-picker/dateUtils.ts
new file mode 100644
index 0000000..50108b8
--- /dev/null
+++ b/packages/ui/src/components/date-picker/dateUtils.ts
@@ -0,0 +1,44 @@
+export interface DateRangeValue {
+  start: string
+  end: string
+}
+
+export function toDateKey(date: Date): string {
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${year}-${month}-${day}`
+}
+
+export function parseDateKey(value?: string): Date | undefined {
+  if (!value || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return undefined
+  const [year, month, day] = value.split('-').map(Number)
+  const date = new Date(year, month - 1, day)
+  return toDateKey(date) === value ? date : undefined
+}
+
+export function compareDateKeys(a: string, b: string): number {
+  return a.localeCompare(b)
+}
+
+export function formatDate(value?: string): string {
+  const date = parseDateKey(value)
+  return date ? new Intl.DateTimeFormat(undefined, { year: 'numeric', month: 'short', day: 'numeric' }).format(date) : ''
+}
+
+export function monthDays(month: Date): Array<{ date: Date; key: string; outside: boolean }> {
+  const first = new Date(month.getFullYear(), month.getMonth(), 1)
+  const offset = (first.getDay() + 6) % 7
+  const start = new Date(first)
+  start.setDate(first.getDate() - offset)
+
+  return Array.from({ length: 42 }, (_, index) => {
+    const date = new Date(start)
+    date.setDate(start.getDate() + index)
+    return { date, key: toDateKey(date), outside: date.getMonth() !== month.getMonth() }
+  })
+}
+
+export function addMonths(month: Date, offset: number): Date {
+  return new Date(month.getFullYear(), month.getMonth() + offset, 1)
+}
diff --git a/packages/ui/src/components/date-picker/index.ts b/packages/ui/src/components/date-picker/index.ts
new file mode 100644
index 0000000..7118089
--- /dev/null
+++ b/packages/ui/src/components/date-picker/index.ts
@@ -0,0 +1,3 @@
+export { default as DatePicker } from './DatePicker.vue'
+export { default as DateRangePicker } from './DateRangePicker.vue'
+export type { DateRangeValue } from './dateUtils'

From ef36708bab99153024d585c26e4b95291d8d0ecc Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:50:59 +0800
Subject: [PATCH 05/26] feat: enhance data table controls

---
 .changeset/bright-tables-expand.md            |   5 +
 .../pages/components/data-table.vue           |  40 ++++--
 .../ui/src/components/table/DataTable.vue     | 117 +++++++++---------
 packages/ui/src/components/table/index.ts     |   2 +-
 packages/ui/src/components/table/types.ts     |  14 +++
 5 files changed, 112 insertions(+), 66 deletions(-)
 create mode 100644 .changeset/bright-tables-expand.md
 create mode 100644 packages/ui/src/components/table/types.ts

diff --git a/.changeset/bright-tables-expand.md b/.changeset/bright-tables-expand.md
new file mode 100644
index 0000000..dc26a77
--- /dev/null
+++ b/.changeset/bright-tables-expand.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Enhance DataTable with controlled sorting, pagination, selection, column visibility, and loading, empty, and error states.
diff --git a/apps/playground/pages/components/data-table.vue b/apps/playground/pages/components/data-table.vue
index 6f7b42d..12129e1 100644
--- a/apps/playground/pages/components/data-table.vue
+++ b/apps/playground/pages/components/data-table.vue
@@ -1,9 +1,12 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="DataTable 数据表" description="轻量数据表：列对齐、悬浮行与按列插槽富渲染。" />
+    <DocPageHeader title="DataTable 数据表" description="面向控制台的受控增强表格：排序、分页、行选择与一致状态。" />
 
-    <DocExample title="插槽单元格" description="slot: true 的列查找 #cell-<key> 作用域插槽。" :code="rcCode0">
-      <DataTable :columns="columns" :rows="rows">
+    <DocExample title="可控表格状态" description="排序、分页、选择状态由调用方保存；slot: true 的列查找 #cell-<key> 作用域插槽。" :code="rcCode0">
+      <DataTable v-model:selected="selected" v-model:sortable="sort" v-model:page="page" :columns="columns" :rows="rows" row-key="name" selectable :page-size="2">
+        <template #toolbar="{ selected, clearSelection }">
+          <div class="flex items-center justify-between gap-3 text-sm text-slate-600 dark:text-slate-300"><span>已选择 {{ selected.length }} 个节点</span><Button v-if="selected.length" size="xs" variant="ghost" color="neutral" @click="clearSelection">取消选择</Button></div>
+        </template>
         <template #cell-status="{ value }">
           <Badge :color="value === '在线' ? 'success' : value === '维护' ? 'warning' : 'neutral'" variant="soft" dot size="xs">{{ value }}</Badge>
         </template>
@@ -21,6 +24,7 @@
 
 <script setup lang="ts">
 import { ref } from 'vue'
+import type { DataTableSort } from '@recloudstudio/ui'
 const columns = [
   { key: 'name', label: '节点' },
   { key: 'region', label: '地域' },
@@ -28,6 +32,9 @@ const columns = [
   { key: 'latency', label: '延迟', align: 'right' as const },
   { key: 'actions', label: '操作', align: 'right' as const, slot: true }
 ]
+const page = ref(1)
+const selected = ref<string[]>([])
+const sort = ref<DataTableSort>()
 const rows = ref([
   { name: 'hkg-edge-01', region: '中国香港', status: '在线', latency: '8ms' },
   { name: 'nrt-edge-02', region: '日本东京', status: '在线', latency: '14ms' },
@@ -35,7 +42,19 @@ const rows = ref([
   { name: 'sjc-edge-03', region: '美国硅谷', status: '离线', latency: '—' }
 ])
 
-const rcCode0 = `<DataTable :columns="columns" :rows="rows">
+const rcCode0 = `<DataTable
+  v-model:selected="selected"
+  v-model:sortable="sort"
+  v-model:page="page"
+  :columns="columns"
+  :rows="rows"
+  row-key="name"
+  selectable
+  :page-size="20"
+>
+  <template #toolbar="{ selected, clearSelection }">
+    已选择 {{ selected.length }} 项
+  </template>
   <template #cell-status="{ value }">
     <Badge :color="value === '在线' ? 'success' : value === '维护' ? 'warning' : 'neutral'" variant="soft" dot size="xs">{{ value }}</Badge>
   </template>
@@ -45,9 +64,12 @@ const rcCode0 = `<DataTable :columns="columns" :rows="rows">
 </DataTable>`
 
 
-const apiRows = [ { name: 'columns', type: '{ key, label, width?, align?, slot? }[]', default: '—', description: '列定义。' },
-  { name: 'rows', type: 'Record<string, any>[]', default: '—', description: '行数据。' },
-  { name: 'hoverable / divide', type: 'boolean', default: 'true', description: '悬浮高亮与行分割线。' },
-  { name: 'emptyText', type: 'string', default: '暂无数据', description: '空态文案。' },
-  { name: 'cell-<key>', type: 'slot', default: '—', description: '作用域插槽 { row, value }。' } ]
+const apiRows = [ { name: 'columns', type: '{ key, label, width?, align?, slot?, sortable? }[]', default: '—', description: '列定义；sortable 开启受控列排序。' },
+  { name: 'rows / rowKey', type: 'Record<string, unknown>[] / string | function', default: '—', description: '行数据和稳定行标识。' },
+  { name: 'v-model:selected', type: '(string | number)[]', default: '[]', description: '启用 selectable 后的受控行选择。' },
+  { name: 'v-model:sortable', type: '{ key, direction } | undefined', default: '—', description: '受控排序状态，数据排序由调用方处理。' },
+  { name: 'v-model:page / pageSize / total', type: 'number', default: '1 / 0 / rows.length', description: '受控分页；传 total 时适配服务端分页。' },
+  { name: 'loading / error', type: 'boolean / string', default: 'false / —', description: '统一骨架加载与错误状态。' },
+  { name: 'visibleColumnKeys', type: 'string[]', default: '全部列', description: '受控列显隐。' },
+  { name: 'toolbar / empty / error / cell-<key>', type: 'slot', default: '—', description: '工具栏、状态与单元格插槽。' } ]
 </script>
diff --git a/packages/ui/src/components/table/DataTable.vue b/packages/ui/src/components/table/DataTable.vue
index 233e5d5..d663d47 100644
--- a/packages/ui/src/components/table/DataTable.vue
+++ b/packages/ui/src/components/table/DataTable.vue
@@ -1,72 +1,77 @@
 <template>
-  <div :class="cn('w-full overflow-x-auto rounded-xl ring-1 ring-inset ring-slate-200 dark:ring-slate-800 bg-white dark:bg-[#0F172A]', props.class)">
-    <table class="w-full border-collapse text-left text-sm">
-      <thead>
-        <tr class="border-b border-slate-200 bg-slate-50/80 dark:border-slate-800 dark:bg-slate-900/60">
-          <th
-            v-for="col in props.columns"
-            :key="col.key"
-            :class="cn('px-4 py-2.5 text-xs font-semibold uppercase tracking-wider text-slate-500 dark:text-slate-400 whitespace-nowrap', col.align === 'right' ? 'text-right' : col.align === 'center' ? 'text-center' : 'text-left')"
-            :style="col.width ? { width: col.width } : undefined"
-          >
-            {{ col.label }}
+  <div :class="cn('w-full overflow-hidden rounded-xl bg-white ring-1 ring-inset ring-slate-200 dark:bg-[#0F172A] dark:ring-slate-800', props.class)">
+    <div v-if="$slots.toolbar" class="border-b border-slate-200 px-4 py-3 dark:border-slate-800"><slot name="toolbar" :selected="selectedRows" :clear-selection="clearSelection" /></div>
+    <div class="overflow-x-auto">
+      <table class="w-full border-collapse text-left text-sm">
+        <thead><tr class="border-b border-slate-200 bg-slate-50/80 dark:border-slate-800 dark:bg-slate-900/60">
+          <th v-if="selectable" class="w-11 px-4 py-2.5"><input type="checkbox" :checked="allPageSelected" :indeterminate="somePageSelected" aria-label="选择当前页所有行" class="h-4 w-4 accent-[#2563EB]" @change="togglePageSelection" /></th>
+          <th v-for="col in visibleColumns" :key="col.key" :style="col.width ? { width: col.width } : undefined" :class="cn('px-4 py-2.5 text-xs font-semibold uppercase tracking-wider text-slate-500 dark:text-slate-400 whitespace-nowrap', alignClass(col.align))">
+            <button v-if="col.sortable" type="button" class="inline-flex items-center gap-1 hover:text-slate-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:hover:text-slate-100" @click="toggleSort(col.key)">{{ col.label }}<span aria-hidden="true" class="text-slate-400">{{ sortIcon(col.key) }}</span></button>
+            <span v-else>{{ col.label }}</span>
           </th>
-        </tr>
-      </thead>
-      <tbody :class="props.divide ? 'divide-y divide-slate-100 dark:divide-slate-800' : ''">
-        <tr
-          v-for="(row, idx) in props.rows"
-          :key="idx"
-          :class="cn('transition-colors', props.hoverable ? 'hover:bg-slate-50/70 dark:hover:bg-slate-900/40' : '')"
-        >
-          <td
-            v-for="col in props.columns"
-            :key="col.key"
-            :class="cn('px-4 py-3 text-slate-700 dark:text-slate-300 align-middle', col.align === 'right' ? 'text-right' : col.align === 'center' ? 'text-center' : 'text-left')"
-          >
-            <slot v-if="col.slot" :name="`cell-${col.key}`" :row="row" :value="row[col.key]" />
-            <span v-else class="whitespace-nowrap">{{ formatCell(row[col.key]) }}</span>
-          </td>
-        </tr>
-      </tbody>
-    </table>
-    <div v-if="!props.rows || props.rows.length === 0" class="px-4 py-10 text-center text-sm text-slate-500 dark:text-slate-400">
-      {{ props.emptyText }}
+        </tr></thead>
+        <tbody v-if="!loading && !error && pagedRows.length" :class="props.divide ? 'divide-y divide-slate-100 dark:divide-slate-800' : ''">
+          <tr v-for="(row, index) in pagedRows" :key="rowKey(row, index)" :class="cn('transition-colors', hoverable ? 'hover:bg-slate-50/70 dark:hover:bg-slate-900/40' : '', isSelected(row, index) && 'bg-blue-50/70 dark:bg-blue-950/20')">
+            <td v-if="selectable" class="px-4 py-3"><input type="checkbox" :checked="isSelected(row, index)" :aria-label="`选择第 ${index + 1} 行`" class="h-4 w-4 accent-[#2563EB]" @change="toggleRow(row, index)" /></td>
+            <td v-for="col in visibleColumns" :key="col.key" :class="cn('px-4 py-3 align-middle text-slate-700 dark:text-slate-300', alignClass(col.align))"><slot v-if="col.slot" :name="`cell-${col.key}`" :row="row" :value="row[col.key]" :index="index" /><span v-else class="whitespace-nowrap">{{ formatCell(row[col.key]) }}</span></td>
+          </tr>
+        </tbody>
+      </table>
     </div>
+    <div v-if="loading" class="space-y-3 p-4" aria-label="加载中" role="status"><div v-for="row in 4" :key="row" class="flex gap-4"><Skeleton v-for="column in visibleColumns.length + Number(selectable)" :key="column" height="1.5rem" /></div></div>
+    <div v-else-if="error" class="p-4"><slot name="error"><EmptyState title="数据加载失败" :description="error"><template #icon><svg class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"/><path d="M12 8v4M12 16h.01"/></svg></template></EmptyState></slot></div>
+    <div v-else-if="!pagedRows.length" class="p-4"><slot name="empty"><EmptyState :title="emptyText" /></slot></div>
+    <div v-if="showPagination" class="flex flex-wrap items-center justify-between gap-3 border-t border-slate-200 px-4 py-3 dark:border-slate-800"><span class="text-xs text-slate-500 dark:text-slate-400">第 {{ currentPage }} / {{ pageCount }} 页，共 {{ total }} 条</span><div class="flex gap-1"><button :disabled="currentPage <= 1" class="inline-flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium text-slate-600 transition-colors hover:bg-slate-100 disabled:pointer-events-none disabled:opacity-40 dark:text-slate-300 dark:hover:bg-slate-800" @click="setPage(currentPage - 1)">上一页</button><button :disabled="currentPage >= pageCount" class="inline-flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium text-slate-600 transition-colors hover:bg-slate-100 disabled:pointer-events-none disabled:opacity-40 dark:text-slate-300 dark:hover:bg-slate-800" @click="setPage(currentPage + 1)">下一页</button></div></div>
   </div>
 </template>
 
-<script setup lang="ts">
+<script setup lang="ts" generic="T extends Record<string, unknown>">
+import { computed } from 'vue'
+import EmptyState from '../empty/EmptyState.vue'
+import Skeleton from '../skeleton/Skeleton.vue'
 import { cn } from '../../utils/cn'
+import type { DataTableColumn, DataTableSort } from './types'
 
-export interface DataTableColumn {
-  key: string
-  label: string
-  width?: string
-  align?: 'left' | 'center' | 'right'
-  slot?: boolean
-}
-
-export interface DataTableProps {
+export interface DataTableProps<T extends Record<string, unknown> = Record<string, unknown>> {
   columns?: DataTableColumn[]
-  rows?: Record<string, any>[]
+  rows?: T[]
+  rowKey?: keyof T | ((row: T, index: number) => string | number)
+  selected?: Array<string | number>
+  /** Controlled list of rendered column keys. Omit to show every column. */
+  visibleColumnKeys?: string[]
+  sortable?: DataTableSort | undefined
+  page?: number
+  pageSize?: number
+  total?: number
+  loading?: boolean
+  error?: string
+  selectable?: boolean
   hoverable?: boolean
   divide?: boolean
   emptyText?: string
   class?: string
 }
 
-const props = withDefaults(defineProps<DataTableProps>(), {
-  columns: () => [],
-  rows: () => [],
-  hoverable: true,
-  divide: true,
-  emptyText: '暂无数据',
-  class: ''
-})
-
-function formatCell(value: unknown) {
-  if (value === null || value === undefined) return '-'
-  return String(value)
-}
+const props = withDefaults(defineProps<DataTableProps<T>>(), { columns: () => [], rows: () => [], rowKey: undefined, selected: () => [], visibleColumnKeys: undefined, sortable: undefined, page: 1, pageSize: 0, total: undefined, loading: false, error: '', selectable: false, hoverable: true, divide: true, emptyText: '暂无数据', class: '' })
+const emit = defineEmits<{ (event: 'update:selected', value: Array<string | number>): void; (event: 'update:visibleColumnKeys', value: string[]): void; (event: 'update:sortable', value: DataTableSort | undefined): void; (event: 'update:page', value: number): void }>()
+const visibleColumns = computed(() => props.visibleColumnKeys ? props.columns.filter((column) => props.visibleColumnKeys!.includes(column.key)) : props.columns)
+const showPagination = computed(() => props.pageSize > 0)
+const total = computed(() => props.total ?? props.rows.length)
+const pageCount = computed(() => Math.max(1, Math.ceil(total.value / Math.max(props.pageSize, 1))))
+const currentPage = computed(() => Math.min(Math.max(props.page, 1), pageCount.value))
+const pagedRows = computed(() => { if (!showPagination.value || props.total !== undefined) return props.rows; const start = (currentPage.value - 1) * props.pageSize; return props.rows.slice(start, start + props.pageSize) })
+const selectedRows = computed(() => props.rows.filter((row, index) => props.selected.includes(rowKey(row, index))))
+const pageKeys = computed(() => pagedRows.value.map((row, index) => rowKey(row, index)))
+const allPageSelected = computed(() => pageKeys.value.length > 0 && pageKeys.value.every((key) => props.selected.includes(key)))
+const somePageSelected = computed(() => !allPageSelected.value && pageKeys.value.some((key) => props.selected.includes(key)))
+function rowKey(row: T, index: number): string | number { const key = props.rowKey; return typeof key === 'function' ? key(row, index) : key ? String(row[key] ?? index) : index }
+function alignClass(align?: DataTableColumn['align']) { return align === 'right' ? 'text-right' : align === 'center' ? 'text-center' : 'text-left' }
+function formatCell(value: unknown) { return value === null || value === undefined ? '-' : String(value) }
+function isSelected(row: T, index: number) { return props.selected.includes(rowKey(row, index)) }
+function toggleRow(row: T, index: number) { const key = rowKey(row, index); emit('update:selected', props.selected.includes(key) ? props.selected.filter((value) => value !== key) : [...props.selected, key]) }
+function togglePageSelection() { const keys = pageKeys.value; emit('update:selected', allPageSelected.value ? props.selected.filter((key) => !keys.includes(key)) : [...new Set([...props.selected, ...keys])]) }
+function clearSelection() { emit('update:selected', []) }
+function toggleSort(key: string) { const next: DataTableSort = props.sortable?.key === key && props.sortable.direction === 'asc' ? { key, direction: 'desc' } : { key, direction: 'asc' }; emit('update:sortable', props.sortable?.key === key && props.sortable.direction === 'desc' ? undefined : next) }
+function sortIcon(key: string) { return props.sortable?.key === key ? props.sortable.direction === 'asc' ? '↑' : '↓' : '↕' }
+function setPage(value: number) { emit('update:page', Math.min(Math.max(value, 1), pageCount.value)) }
 </script>
diff --git a/packages/ui/src/components/table/index.ts b/packages/ui/src/components/table/index.ts
index e734766..052485b 100644
--- a/packages/ui/src/components/table/index.ts
+++ b/packages/ui/src/components/table/index.ts
@@ -1,2 +1,2 @@
 export { default as DataTable } from './DataTable.vue'
-export type { DataTableProps, DataTableColumn } from './DataTable.vue'
+export type { DataTableColumn, DataTableSort } from './types'
diff --git a/packages/ui/src/components/table/types.ts b/packages/ui/src/components/table/types.ts
new file mode 100644
index 0000000..ebe4ae6
--- /dev/null
+++ b/packages/ui/src/components/table/types.ts
@@ -0,0 +1,14 @@
+export interface DataTableColumn {
+  key: string
+  label: string
+  width?: string
+  align?: 'left' | 'center' | 'right'
+  slot?: boolean
+  sortable?: boolean
+  hideable?: boolean
+}
+
+export interface DataTableSort {
+  key: string
+  direction: 'asc' | 'desc'
+}

From da38d21fb47da76c0c7dbf7c5b3e65e6a9421b43 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:51:04 +0800
Subject: [PATCH 06/26] feat: add application shell layout

---
 .changeset/quiet-shells-build.md              |  5 ++
 .../playground/pages/components/app-shell.vue | 47 +++++++++++++++++++
 .../ui/src/components/app-shell/AppShell.vue  | 20 ++++++++
 .../ui/src/components/app-shell/Sidebar.vue   | 18 +++++++
 packages/ui/src/components/app-shell/index.ts |  2 +
 5 files changed, 92 insertions(+)
 create mode 100644 .changeset/quiet-shells-build.md
 create mode 100644 apps/playground/pages/components/app-shell.vue
 create mode 100644 packages/ui/src/components/app-shell/AppShell.vue
 create mode 100644 packages/ui/src/components/app-shell/Sidebar.vue
 create mode 100644 packages/ui/src/components/app-shell/index.ts

diff --git a/.changeset/quiet-shells-build.md b/.changeset/quiet-shells-build.md
new file mode 100644
index 0000000..2dd2727
--- /dev/null
+++ b/.changeset/quiet-shells-build.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add AppShell and Sidebar primitives for developer console layouts.
diff --git a/apps/playground/pages/components/app-shell.vue b/apps/playground/pages/components/app-shell.vue
new file mode 100644
index 0000000..87e7a1b
--- /dev/null
+++ b/apps/playground/pages/components/app-shell.vue
@@ -0,0 +1,47 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="AppShell 应用布局" description="为开发者控制台提供稳定的侧栏、顶栏与内容区骨架；小屏下自动收起桌面侧栏。" />
+
+    <DocExample title="控制台骨架" description="AppShell 负责页面结构，Sidebar 专注可滚动的导航内容与固定底部操作。" :code="rcCode0">
+      <div class="h-[28rem] overflow-hidden rounded-xl ring-1 ring-slate-200 dark:ring-slate-800">
+        <AppShell sidebar-width="13rem">
+          <template #sidebar>
+            <Sidebar>
+              <template #header><span class="text-sm font-semibold text-slate-900 dark:text-slate-100">ReCloud Console</span></template>
+              <div class="space-y-1">
+                <a v-for="item in navItems" :key="item" href="#" class="block rounded-lg px-3 py-2 text-sm font-medium text-slate-600 hover:bg-slate-100 hover:text-slate-950 dark:text-slate-300 dark:hover:bg-slate-800 dark:hover:text-white" @click.prevent>{{ item }}</a>
+              </div>
+              <template #footer><Button class="w-full" size="sm" variant="outline" color="neutral">工作区设置</Button></template>
+            </Sidebar>
+          </template>
+          <template #header><div class="flex h-12 items-center px-5 text-sm font-medium text-slate-700 dark:text-slate-200">Webhook 投递记录</div></template>
+          <div class="p-5"><Card title="近 24 小时投递"><p class="text-sm text-slate-500 dark:text-slate-400">这里是控制台主内容区。</p></Card></div>
+        </AppShell>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="app-shell" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const navItems = ['概览', 'Webhooks', '投递记录', '通知规则']
+const rcCode0 = `<AppShell sidebar-width="16rem">
+  <template #sidebar>
+    <Sidebar>
+      <template #header>ReCloud Console</template>
+      <nav><!-- navigation items --></nav>
+      <template #footer><Button>工作区设置</Button></template>
+    </Sidebar>
+  </template>
+  <template #header><ConsoleHeader /></template>
+  <main><!-- page content --></main>
+</AppShell>`
+const apiRows = [
+  { name: 'AppShell sidebarWidth', type: 'string', default: "'16rem'", description: '桌面端侧栏宽度，可传任意 CSS 尺寸。' },
+  { name: 'AppShell sidebar / header / default', type: 'slot', default: '—', description: '分别为桌面侧栏、粘性顶栏与主内容区。' },
+  { name: 'Sidebar label', type: 'string', default: "'侧边导航'", description: '导航语义的无障碍标签。' },
+  { name: 'Sidebar header / default / footer', type: 'slot', default: '—', description: '固定头部、可滚动导航区与固定底部区域。' }
+]
+</script>
diff --git a/packages/ui/src/components/app-shell/AppShell.vue b/packages/ui/src/components/app-shell/AppShell.vue
new file mode 100644
index 0000000..580f7b2
--- /dev/null
+++ b/packages/ui/src/components/app-shell/AppShell.vue
@@ -0,0 +1,20 @@
+<template>
+  <div :class="cn('flex min-h-dvh bg-slate-50 text-slate-800 dark:bg-[#090E17] dark:text-slate-100', props.class)" :style="{ '--app-sidebar-width': props.sidebarWidth }">
+    <aside v-if="$slots.sidebar" class="hidden w-[var(--app-sidebar-width)] shrink-0 border-r border-slate-200 bg-white dark:border-slate-800 dark:bg-[#0F172A] lg:block"><slot name="sidebar" /></aside>
+    <div class="flex min-w-0 grow flex-col">
+      <header v-if="$slots.header" class="sticky top-0 z-30 shrink-0 border-b border-slate-200 bg-white/90 backdrop-blur-md dark:border-slate-800 dark:bg-[#090E17]/90"><slot name="header" /></header>
+      <main class="min-w-0 grow"><slot /></main>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { cn } from '../../utils/cn'
+
+export interface AppShellProps {
+  sidebarWidth?: string
+  class?: string
+}
+
+const props = withDefaults(defineProps<AppShellProps>(), { sidebarWidth: '16rem', class: '' })
+</script>
diff --git a/packages/ui/src/components/app-shell/Sidebar.vue b/packages/ui/src/components/app-shell/Sidebar.vue
new file mode 100644
index 0000000..2438d92
--- /dev/null
+++ b/packages/ui/src/components/app-shell/Sidebar.vue
@@ -0,0 +1,18 @@
+<template>
+  <nav :aria-label="props.label" :class="cn('flex h-full flex-col', props.class)">
+    <div v-if="$slots.header" class="shrink-0 border-b border-slate-200 px-4 py-4 dark:border-slate-800"><slot name="header" /></div>
+    <div class="min-h-0 grow overflow-y-auto px-3 py-4"><slot /></div>
+    <div v-if="$slots.footer" class="shrink-0 border-t border-slate-200 px-3 py-3 dark:border-slate-800"><slot name="footer" /></div>
+  </nav>
+</template>
+
+<script setup lang="ts">
+import { cn } from '../../utils/cn'
+
+export interface SidebarProps {
+  label?: string
+  class?: string
+}
+
+const props = withDefaults(defineProps<SidebarProps>(), { label: '侧边导航', class: '' })
+</script>
diff --git a/packages/ui/src/components/app-shell/index.ts b/packages/ui/src/components/app-shell/index.ts
new file mode 100644
index 0000000..d9692fc
--- /dev/null
+++ b/packages/ui/src/components/app-shell/index.ts
@@ -0,0 +1,2 @@
+export { default as AppShell } from './AppShell.vue'
+export { default as Sidebar } from './Sidebar.vue'

From 6269ae1df9906b4ec30849d21052e9d489bc7794 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:51:20 +0800
Subject: [PATCH 07/26] feat: add resizable panel

---
 .changeset/tiny-panels-scale.md               |  5 ++
 .../pages/components/resizable-panel.vue      | 36 ++++++++
 .../resizable-panel/ResizablePanel.vue        | 82 +++++++++++++++++++
 .../src/components/resizable-panel/index.ts   |  1 +
 4 files changed, 124 insertions(+)
 create mode 100644 .changeset/tiny-panels-scale.md
 create mode 100644 apps/playground/pages/components/resizable-panel.vue
 create mode 100644 packages/ui/src/components/resizable-panel/ResizablePanel.vue
 create mode 100644 packages/ui/src/components/resizable-panel/index.ts

diff --git a/.changeset/tiny-panels-scale.md b/.changeset/tiny-panels-scale.md
new file mode 100644
index 0000000..7a74475
--- /dev/null
+++ b/.changeset/tiny-panels-scale.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add ResizablePanel for accessible, keyboard-adjustable console workspaces.
diff --git a/apps/playground/pages/components/resizable-panel.vue b/apps/playground/pages/components/resizable-panel.vue
new file mode 100644
index 0000000..b26c473
--- /dev/null
+++ b/apps/playground/pages/components/resizable-panel.vue
@@ -0,0 +1,36 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="ResizablePanel 可调面板" description="为日志、资源详情和编辑器工作区提供可拖拽且可键盘操作的分栏布局。" />
+
+    <DocExample title="双栏工作区" description="拖动中间分隔线，或聚焦后通过方向键调整左侧面板；Home / End 跳到最小或最大尺寸。" :code="rcCode0">
+      <ResizablePanel v-model="panelSize" class="h-72 rounded-xl ring-1 ring-slate-200 dark:ring-slate-800" :min="160" :max="420">
+        <template #first><div class="h-full bg-slate-50 p-4 dark:bg-slate-900/70"><p class="text-xs font-semibold uppercase tracking-wider text-slate-500">资源</p><div class="mt-3 space-y-1"><button v-for="item in resources" :key="item" class="block w-full rounded-lg px-2.5 py-2 text-left text-sm text-slate-600 hover:bg-white hover:text-slate-950 dark:text-slate-300 dark:hover:bg-slate-800 dark:hover:text-white">{{ item }}</button></div></div></template>
+        <template #second><div class="h-full bg-white p-5 dark:bg-[#0F172A]"><p class="text-xs font-semibold uppercase tracking-wider text-slate-500">部署日志</p><pre class="mt-4 overflow-auto rounded-lg bg-slate-950 p-4 text-xs leading-6 text-slate-300">$ deploy production
+✓ Building image
+✓ Migrating database
+✓ Service healthy</pre><p class="mt-3 text-xs text-slate-500">左侧宽度：{{ panelSize }}px</p></div></template>
+      </ResizablePanel>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="resizable-panel" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+const panelSize = ref(240)
+const resources = ['production', 'staging', 'preview-482']
+const rcCode0 = `<ResizablePanel v-model="sidebarWidth" :min="160" :max="480">
+  <template #first><ResourceSidebar /></template>
+  <template #second><LogViewer /></template>
+</ResizablePanel>`
+const apiRows = [
+  { name: 'v-model', type: 'number', default: '280', description: '第一个面板的受控像素尺寸。省略时组件维护内部尺寸。' },
+  { name: 'defaultSize', type: 'number', default: '280', description: '非受控模式的初始尺寸。' },
+  { name: 'orientation', type: "'horizontal' | 'vertical'", default: "'horizontal'", description: '分栏方向；horizontal 为左右面板。' },
+  { name: 'min / max / step', type: 'number', default: '160 / 自动 / 16', description: '尺寸边界与键盘调整步长。' },
+  { name: 'resizeStart / resizeEnd', type: 'event', default: '—', description: '拖拽开始和结束事件，结束时提供最终尺寸。' },
+  { name: 'first / second', type: 'slot', default: '—', description: '两个面板的内容插槽。' }
+]
+</script>
diff --git a/packages/ui/src/components/resizable-panel/ResizablePanel.vue b/packages/ui/src/components/resizable-panel/ResizablePanel.vue
new file mode 100644
index 0000000..4415477
--- /dev/null
+++ b/packages/ui/src/components/resizable-panel/ResizablePanel.vue
@@ -0,0 +1,82 @@
+<template>
+  <div ref="container" :class="cn('flex min-h-0 min-w-0 overflow-hidden', props.orientation === 'horizontal' ? 'flex-row' : 'flex-col', props.class)">
+    <section :style="firstPanelStyle" class="min-h-0 min-w-0 shrink-0 overflow-auto"><slot name="first" /></section>
+    <div
+      role="separator"
+      :aria-label="props.label"
+      :aria-orientation="props.orientation === 'horizontal' ? 'vertical' : 'horizontal'"
+      :aria-valuemin="props.min"
+      :aria-valuemax="effectiveMax"
+      :aria-valuenow="panelSize"
+      tabindex="0"
+      :class="cn('group relative z-10 shrink-0 touch-none bg-slate-200 transition-colors hover:bg-[#2563EB] focus-visible:bg-[#2563EB] focus-visible:outline-none dark:bg-slate-800 dark:hover:bg-[#70ACFE] dark:focus-visible:bg-[#70ACFE]', props.orientation === 'horizontal' ? 'w-px cursor-col-resize' : 'h-px cursor-row-resize')"
+      @pointerdown="startResize"
+      @keydown="onKeydown"
+    >
+      <span :class="cn('absolute rounded-full bg-slate-400 opacity-0 transition-opacity group-hover:opacity-100 group-focus-visible:opacity-100 dark:bg-slate-500', props.orientation === 'horizontal' ? 'inset-y-0 -left-0.5 w-1' : 'inset-x-0 -top-0.5 h-1')" />
+    </div>
+    <section class="min-h-0 min-w-0 grow overflow-auto"><slot name="second" /></section>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { cn } from '../../utils/cn'
+
+export interface ResizablePanelProps {
+  /** Direction of the panes. Horizontal means a vertical drag handle. */
+  orientation?: 'horizontal' | 'vertical'
+  /** Controlled size of the first pane in pixels. */
+  modelValue?: number
+  /** Initial size used when modelValue is omitted. */
+  defaultSize?: number
+  min?: number
+  max?: number
+  step?: number
+  label?: string
+  class?: string
+}
+
+const props = withDefaults(defineProps<ResizablePanelProps>(), {
+  orientation: 'horizontal', modelValue: undefined, defaultSize: 280, min: 160, max: undefined,
+  step: 16, label: '调整面板大小', class: ''
+})
+const emit = defineEmits<{
+  (event: 'update:modelValue', value: number): void
+  (event: 'resizeStart'): void
+  (event: 'resizeEnd', value: number): void
+}>()
+
+const container = ref<HTMLElement>()
+const internalSize = ref(props.defaultSize)
+const isControlled = computed(() => props.modelValue !== undefined)
+const panelSize = computed(() => isControlled.value ? props.modelValue! : internalSize.value)
+const containerSize = computed(() => {
+  const element = container.value
+  return element ? props.orientation === 'horizontal' ? element.clientWidth : element.clientHeight : 0
+})
+const effectiveMax = computed(() => props.max ?? Math.max(props.min, containerSize.value - props.min))
+const firstPanelStyle = computed(() => props.orientation === 'horizontal' ? { width: `${panelSize.value}px` } : { height: `${panelSize.value}px` })
+
+function clamp(value: number) { return Math.min(Math.max(Math.round(value), props.min), effectiveMax.value) }
+function updateSize(value: number) { const next = clamp(value); if (!isControlled.value) internalSize.value = next; emit('update:modelValue', next) }
+function pointToSize(event: PointerEvent) { const bounds = container.value?.getBoundingClientRect(); if (!bounds) return panelSize.value; return props.orientation === 'horizontal' ? event.clientX - bounds.left : event.clientY - bounds.top }
+function startResize(event: PointerEvent) {
+  event.preventDefault()
+  const target = event.currentTarget as HTMLElement
+  target.setPointerCapture(event.pointerId)
+  emit('resizeStart')
+  const onMove = (moveEvent: PointerEvent) => updateSize(pointToSize(moveEvent))
+  const onEnd = () => { target.removeEventListener('pointermove', onMove); target.removeEventListener('pointerup', onEnd); target.removeEventListener('pointercancel', onEnd); emit('resizeEnd', panelSize.value) }
+  target.addEventListener('pointermove', onMove)
+  target.addEventListener('pointerup', onEnd)
+  target.addEventListener('pointercancel', onEnd)
+}
+function onKeydown(event: KeyboardEvent) {
+  const decrement = props.orientation === 'horizontal' ? event.key === 'ArrowLeft' : event.key === 'ArrowUp'
+  const increment = props.orientation === 'horizontal' ? event.key === 'ArrowRight' : event.key === 'ArrowDown'
+  if (decrement || increment) { event.preventDefault(); updateSize(panelSize.value + (increment ? props.step : -props.step)) }
+  else if (event.key === 'Home') { event.preventDefault(); updateSize(props.min) }
+  else if (event.key === 'End') { event.preventDefault(); updateSize(effectiveMax.value) }
+}
+</script>
diff --git a/packages/ui/src/components/resizable-panel/index.ts b/packages/ui/src/components/resizable-panel/index.ts
new file mode 100644
index 0000000..cbe36bc
--- /dev/null
+++ b/packages/ui/src/components/resizable-panel/index.ts
@@ -0,0 +1 @@
+export { default as ResizablePanel } from './ResizablePanel.vue'

From ac0087beac2ac3c611cdbed1523f5fda88528107 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 03:53:13 +0800
Subject: [PATCH 08/26] chore: sort sidebar components alphabetically

---
 apps/playground/utils/catalog.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 47f06c4..1b5345d 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -9,7 +9,7 @@ export interface DocGroup {
   items: DocItem[]
 }
 
-export const docGroups: DocGroup[] = [
+const groups: DocGroup[] = [
   {
     label: '指南',
     items: [
@@ -112,6 +112,12 @@ export const docGroups: DocGroup[] = [
   }
 ]
 
+/** Component entries are presented alphabetically within each sidebar group. */
+export const docGroups: DocGroup[] = groups.map((group) => ({
+  ...group,
+  items: [...group.items].sort((a, b) => a.title.localeCompare(b.title, 'en'))
+}))
+
 export const flatDocs = docGroups.flatMap((g) => g.items.map((i) => ({ ...i, group: g.label })))
 
 export function docPath(name: string): string {

From ad9579bd8084fb69fccf8fc778c321bb94a6454a Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 04:04:30 +0800
Subject: [PATCH 09/26] feat: add file upload

---
 .changeset/smooth-files-arrive.md             |  5 ++
 .../pages/components/file-upload.vue          | 60 ++++++++++++++++
 apps/playground/utils/catalog.ts              |  1 +
 .../src/components/file-upload/FileUpload.vue | 71 +++++++++++++++++++
 .../ui/src/components/file-upload/index.ts    |  2 +
 .../ui/src/components/file-upload/types.ts    | 18 +++++
 packages/ui/src/index.ts                      |  1 +
 7 files changed, 158 insertions(+)
 create mode 100644 .changeset/smooth-files-arrive.md
 create mode 100644 apps/playground/pages/components/file-upload.vue
 create mode 100644 packages/ui/src/components/file-upload/FileUpload.vue
 create mode 100644 packages/ui/src/components/file-upload/index.ts
 create mode 100644 packages/ui/src/components/file-upload/types.ts

diff --git a/.changeset/smooth-files-arrive.md b/.changeset/smooth-files-arrive.md
new file mode 100644
index 0000000..f9ef06c
--- /dev/null
+++ b/.changeset/smooth-files-arrive.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add FileUpload with drag-and-drop, validation, upload progress, cancellation, previews, and retry states.
diff --git a/apps/playground/pages/components/file-upload.vue b/apps/playground/pages/components/file-upload.vue
new file mode 100644
index 0000000..b31745a
--- /dev/null
+++ b/apps/playground/pages/components/file-upload.vue
@@ -0,0 +1,60 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="FileUpload 文件上传" description="为资源、头像、镜像与配置导入提供可拖放的多文件上传工作流，状态始终由文件列表清晰呈现。" />
+
+    <DocExample title="带进度的资源上传" description="可拖放多张图片；演示请求会显示进度，并随机模拟一次可重试的失败。" :code="rcCode0">
+      <FileUpload accept="image/png,image/jpeg,image/webp" :max-size="5 * 1024 * 1024" :max-files="4" :upload="mockUpload" @reject="lastRejection = $event.reason" />
+      <p v-if="lastRejection" class="text-xs text-red-600 dark:text-red-400">{{ lastRejection }}</p>
+    </DocExample>
+
+    <DocExample title="配置文件校验" description="不传 upload 时，组件作为文件选择与校验控件使用；通过 change 获取当前文件项。" :code="rcCode1">
+      <FileUpload accept=".json,.yaml,.yml" :multiple="false" :max-size="256 * 1024" @change="configFiles = $event" />
+      <p v-if="configFiles.length" class="text-xs text-slate-500 dark:text-slate-400">已选择 {{ configFiles[0].file.name }}</p>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="file-upload" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { FileUploadHandler, FileUploadItem } from '@recloudstudio/ui'
+
+const lastRejection = ref('')
+const configFiles = ref<FileUploadItem[]>([])
+
+const mockUpload: FileUploadHandler = ({ signal, setProgress }) => new Promise((resolve, reject) => {
+  let progress = 0
+  const timer = window.setInterval(() => {
+    if (signal.aborted) { window.clearInterval(timer); reject(new DOMException('上传已取消', 'AbortError')); return }
+    progress += 20
+    setProgress(progress)
+    if (progress >= 100) { window.clearInterval(timer); resolve() }
+  }, 240)
+})
+
+const rcCode0 = `<FileUpload
+  accept="image/png,image/jpeg,image/webp"
+  :max-size="5 * 1024 * 1024"
+  :max-files="4"
+  :upload="uploadAsset"
+  @reject="showError($event.reason)"
+/>`
+
+const rcCode1 = `<FileUpload
+  accept=".json,.yaml,.yml"
+  :multiple="false"
+  :max-size="256 * 1024"
+  @change="configFiles = $event"
+/>`
+
+const apiRows = [
+  { name: 'accept / multiple', type: 'string / boolean', default: "'' / true", description: '原生 accept 规则和多文件选择开关。' },
+  { name: 'maxSize / maxFiles', type: 'number', default: '—', description: '单文件字节上限与最多文件数。' },
+  { name: 'upload', type: 'FileUploadHandler', default: '—', description: '异步上传处理器，接收 file、signal 和 setProgress。传入后自动上传。' },
+  { name: 'change / reject', type: 'event', default: '—', description: '当前文件列表变化，或某个文件未通过校验。' },
+  { name: 'upload / success / error / cancel', type: 'event', default: '—', description: '文件上传生命周期事件。' },
+  { name: 'label', type: 'string', default: "'上传文件'", description: '拖放区域的无障碍标签。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 1b5345d..8849b6f 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -64,6 +64,7 @@ const groups: DocGroup[] = [
       { name: 'progress', title: 'Progress 进度条', description: '任务进度与百分比。' },
       { name: 'skeleton', title: 'Skeleton 骨架屏', description: '加载占位。' },
       { name: 'empty-state', title: 'EmptyState 空状态', description: '空数据页面引导。' },
+      { name: 'file-upload', title: 'FileUpload 文件上传', description: '拖放、校验、进度与失败重试。' },
       { name: 'separator', title: 'Separator 分隔线', description: '水平与垂直分隔。' }
     ]
   },
diff --git a/packages/ui/src/components/file-upload/FileUpload.vue b/packages/ui/src/components/file-upload/FileUpload.vue
new file mode 100644
index 0000000..5a9bb8f
--- /dev/null
+++ b/packages/ui/src/components/file-upload/FileUpload.vue
@@ -0,0 +1,71 @@
+<template>
+  <div :class="cn('space-y-3', props.class)">
+    <input ref="input" class="sr-only" type="file" :accept="props.accept" :multiple="props.multiple" @change="onInputChange" />
+    <div
+      role="button"
+      tabindex="0"
+      :aria-label="props.label"
+      :class="cn('group relative flex min-h-44 cursor-pointer flex-col items-center justify-center overflow-hidden rounded-xl border border-dashed px-6 py-8 text-center transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] focus-visible:ring-offset-2 dark:focus-visible:ring-[#70ACFE] dark:focus-visible:ring-offset-[#090E17]', isDragging ? 'border-[#2563EB] bg-blue-50/70 dark:border-[#70ACFE] dark:bg-blue-950/30' : 'border-slate-300 bg-slate-50/50 hover:border-blue-400 hover:bg-blue-50/40 dark:border-slate-700 dark:bg-slate-900/30 dark:hover:border-blue-700 dark:hover:bg-blue-950/20')"
+      @click="openPicker"
+      @keydown.enter.prevent="openPicker"
+      @keydown.space.prevent="openPicker"
+      @dragenter.prevent="isDragging = true"
+      @dragover.prevent="isDragging = true"
+      @dragleave.prevent="isDragging = false"
+      @drop.prevent="onDrop"
+    >
+      <div class="mb-3 flex h-11 w-11 items-center justify-center rounded-xl bg-white text-[#2563EB] shadow-xs ring-1 ring-slate-200 transition-transform group-hover:-translate-y-0.5 dark:bg-slate-800 dark:text-[#70ACFE] dark:ring-slate-700"><svg class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><path d="M12 16V4m0 0L7.5 8.5M12 4l4.5 4.5M5 14v4.5A1.5 1.5 0 0 0 6.5 20h11a1.5 1.5 0 0 0 1.5-1.5V14" stroke-linecap="round" stroke-linejoin="round" /></svg></div>
+      <p class="text-sm font-semibold text-slate-800 dark:text-slate-100"><span class="text-[#2563EB] dark:text-[#70ACFE]">选择文件</span> 或拖放到这里</p>
+      <p class="mt-1 text-xs leading-5 text-slate-500 dark:text-slate-400">{{ helpText }}</p>
+    </div>
+
+    <ul v-if="items.length" class="space-y-2" aria-label="上传文件列表">
+      <li v-for="item in items" :key="item.id" class="flex items-center gap-3 rounded-xl border border-slate-200 bg-white p-3 dark:border-slate-800 dark:bg-[#0F172A]">
+        <img v-if="item.previewUrl" :src="item.previewUrl" :alt="item.file.name" class="h-10 w-10 rounded-lg object-cover ring-1 ring-slate-200 dark:ring-slate-700" />
+        <div v-else class="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-slate-100 text-xs font-bold uppercase text-slate-500 dark:bg-slate-800 dark:text-slate-400">{{ fileExtension(item.file.name) }}</div>
+        <div class="min-w-0 grow"><div class="flex items-center gap-2"><p class="truncate text-sm font-medium text-slate-800 dark:text-slate-100">{{ item.file.name }}</p><span :class="statusClass(item.status)">{{ statusLabel(item.status) }}</span></div><p v-if="item.error" class="mt-0.5 text-xs text-red-600 dark:text-red-400">{{ item.error }}</p><p v-else class="mt-0.5 text-xs text-slate-500 dark:text-slate-400">{{ formatSize(item.file.size) }}</p><div v-if="item.status === 'uploading'" class="mt-2 h-1.5 overflow-hidden rounded-full bg-slate-100 dark:bg-slate-800"><div class="h-full rounded-full bg-[#2563EB] transition-[width] duration-200 dark:bg-[#70ACFE]" :style="{ width: `${item.progress ?? 0}%` }" /></div></div>
+        <div class="flex shrink-0 items-center gap-1"><button v-if="item.status === 'uploading'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-slate-500 transition-colors hover:bg-slate-100 hover:text-red-600 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-red-400" :aria-label="`取消上传 ${item.file.name}`" @click="cancel(item.id)"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 6 12 12M18 6 6 18"/></svg></button><button v-else-if="item.status === 'error' || item.status === 'cancelled'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-[#2563EB] transition-colors hover:bg-slate-100 dark:text-[#70ACFE] dark:hover:bg-slate-800" :aria-label="`重试上传 ${item.file.name}`" @click="retry(item.id)"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="h-4 w-4"><path d="M20 11a8 8 0 1 0 2 5.5"/><path d="M20 4v7h-7"/></svg></button><button v-if="item.status !== 'uploading'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-slate-400 transition-colors hover:bg-slate-100 hover:text-red-600 dark:hover:bg-slate-800 dark:hover:text-red-400" :aria-label="`移除 ${item.file.name}`" @click="remove(item.id)"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 6 12 12M18 6 6 18"/></svg></button></div>
+      </li>
+    </ul>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref } from 'vue'
+import { cn } from '../../utils/cn'
+import type { FileUploadHandler, FileUploadItem } from './types'
+
+export interface FileUploadProps {
+  accept?: string
+  multiple?: boolean
+  maxSize?: number
+  maxFiles?: number
+  label?: string
+  upload?: FileUploadHandler
+  class?: string
+}
+
+const props = withDefaults(defineProps<FileUploadProps>(), { accept: '', multiple: true, maxSize: undefined, maxFiles: undefined, label: '上传文件', upload: undefined, class: '' })
+const emit = defineEmits<{ (event: 'change', items: FileUploadItem[]): void; (event: 'reject', payload: { file: File; reason: string }): void; (event: 'upload', item: FileUploadItem): void; (event: 'success', item: FileUploadItem): void; (event: 'error', item: FileUploadItem): void; (event: 'cancel', item: FileUploadItem): void }>()
+const input = ref<HTMLInputElement>()
+const items = ref<FileUploadItem[]>([])
+const isDragging = ref(false)
+const controllers = new Map<string, AbortController>()
+const helpText = computed(() => [props.accept ? `支持 ${props.accept}` : '支持任意文件类型', props.maxSize ? `单个文件最大 ${formatSize(props.maxSize)}` : ''].filter(Boolean).join(' · '))
+
+function openPicker() { input.value?.click() }
+function onInputChange(event: Event) { addFiles(Array.from((event.target as HTMLInputElement).files ?? [])); if (input.value) input.value.value = '' }
+function onDrop(event: DragEvent) { isDragging.value = false; addFiles(Array.from(event.dataTransfer?.files ?? [])) }
+function matchesAccept(file: File) { if (!props.accept) return true; return props.accept.split(',').some((rule) => { const value = rule.trim().toLowerCase(); return value.startsWith('.') ? file.name.toLowerCase().endsWith(value) : value.endsWith('/*') ? file.type.startsWith(value.slice(0, -1)) : file.type === value }) }
+function addFiles(files: File[]) { const accepted = props.multiple ? files : files.slice(0, 1); for (const file of accepted) { if (props.maxFiles && items.value.length >= props.maxFiles) { emit('reject', { file, reason: `最多上传 ${props.maxFiles} 个文件` }); continue } if (!matchesAccept(file)) { emit('reject', { file, reason: '文件类型不受支持' }); continue } if (props.maxSize && file.size > props.maxSize) { emit('reject', { file, reason: `文件不能超过 ${formatSize(props.maxSize)}` }); continue } const item: FileUploadItem = { id: crypto.randomUUID(), file, status: props.upload ? 'uploading' : 'pending', progress: props.upload ? 0 : undefined, previewUrl: file.type.startsWith('image/') ? URL.createObjectURL(file) : undefined }; items.value.push(item); notify(); if (props.upload) runUpload(item) } }
+async function runUpload(item: FileUploadItem) { const controller = new AbortController(); controllers.set(item.id, controller); emit('upload', item); try { await props.upload!({ file: item.file, signal: controller.signal, setProgress: (progress) => { item.progress = Math.min(Math.max(progress, 0), 100); notify() } }); if (controller.signal.aborted) return; item.status = 'success'; item.progress = 100; emit('success', item) } catch (error) { if (controller.signal.aborted) return; item.status = 'error'; item.error = error instanceof Error ? error.message : '上传失败，请重试'; emit('error', item) } finally { controllers.delete(item.id); notify() } }
+function cancel(id: string) { const item = items.value.find((entry) => entry.id === id); if (!item) return; controllers.get(id)?.abort(); controllers.delete(id); item.status = 'cancelled'; item.error = '上传已取消'; emit('cancel', item); notify() }
+function retry(id: string) { const item = items.value.find((entry) => entry.id === id); if (!item || !props.upload) return; item.status = 'uploading'; item.progress = 0; item.error = undefined; runUpload(item); notify() }
+function remove(id: string) { const item = items.value.find((entry) => entry.id === id); controllers.get(id)?.abort(); if (item?.previewUrl) URL.revokeObjectURL(item.previewUrl); items.value = items.value.filter((entry) => entry.id !== id); notify() }
+function notify() { emit('change', [...items.value]) }
+function fileExtension(name: string) { return name.split('.').pop()?.slice(0, 4) || 'file' }
+function formatSize(bytes: number) { if (bytes < 1024) return `${bytes} B`; if (bytes < 1024 ** 2) return `${(bytes / 1024).toFixed(1)} KB`; return `${(bytes / 1024 ** 2).toFixed(1)} MB` }
+function statusLabel(status: FileUploadItem['status']) { return ({ pending: '等待上传', uploading: '上传中', success: '已完成', error: '失败', cancelled: '已取消' })[status] }
+function statusClass(status: FileUploadItem['status']) { return cn('rounded-md px-1.5 py-0.5 text-[10px] font-semibold', status === 'success' && 'bg-emerald-50 text-emerald-700 dark:bg-emerald-950/50 dark:text-emerald-400', status === 'error' && 'bg-red-50 text-red-700 dark:bg-red-950/50 dark:text-red-400', status === 'cancelled' && 'bg-slate-100 text-slate-600 dark:bg-slate-800 dark:text-slate-400', status === 'uploading' && 'bg-blue-50 text-blue-700 dark:bg-blue-950/50 dark:text-blue-300', status === 'pending' && 'bg-amber-50 text-amber-700 dark:bg-amber-950/50 dark:text-amber-400') }
+onBeforeUnmount(() => { controllers.forEach((controller) => controller.abort()); items.value.forEach((item) => { if (item.previewUrl) URL.revokeObjectURL(item.previewUrl) }) })
+</script>
diff --git a/packages/ui/src/components/file-upload/index.ts b/packages/ui/src/components/file-upload/index.ts
new file mode 100644
index 0000000..223b211
--- /dev/null
+++ b/packages/ui/src/components/file-upload/index.ts
@@ -0,0 +1,2 @@
+export { default as FileUpload } from './FileUpload.vue'
+export type { FileUploadHandler, FileUploadItem, FileUploadRequest, FileUploadStatus } from './types'
diff --git a/packages/ui/src/components/file-upload/types.ts b/packages/ui/src/components/file-upload/types.ts
new file mode 100644
index 0000000..3b8af8e
--- /dev/null
+++ b/packages/ui/src/components/file-upload/types.ts
@@ -0,0 +1,18 @@
+export type FileUploadStatus = 'pending' | 'uploading' | 'success' | 'error' | 'cancelled'
+
+export interface FileUploadItem {
+  id: string
+  file: File
+  status: FileUploadStatus
+  progress?: number
+  error?: string
+  previewUrl?: string
+}
+
+export interface FileUploadRequest {
+  file: File
+  signal: AbortSignal
+  setProgress: (value: number) => void
+}
+
+export type FileUploadHandler = (request: FileUploadRequest) => Promise<void>
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index f686d9f..c7ae41d 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -54,6 +54,7 @@ export * from './components/sheet'
 export * from './components/date-picker'
 export * from './components/app-shell'
 export * from './components/resizable-panel'
+export * from './components/file-upload'
 
 // Composables & Utilities
 export * from './composables/useTheme'

From d3e231c4a970a50d8032835e2ae795588e4c3187 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 04:09:55 +0800
Subject: [PATCH 10/26] feat: add multi select

---
 .changeset/tender-selects-grow.md             |  5 ++
 .../pages/components/multi-select.vue         | 51 +++++++++++++++++++
 apps/playground/utils/catalog.ts              |  1 +
 .../ui/src/components/combobox/Combobox.vue   | 24 +--------
 packages/ui/src/components/combobox/index.ts  |  3 +-
 packages/ui/src/components/combobox/types.ts  | 22 ++++++++
 .../components/multi-select/MultiSelect.vue   | 31 +++++++++++
 .../ui/src/components/multi-select/index.ts   |  2 +
 .../ui/src/components/multi-select/types.ts   | 21 ++++++++
 packages/ui/src/index.ts                      |  1 +
 10 files changed, 136 insertions(+), 25 deletions(-)
 create mode 100644 .changeset/tender-selects-grow.md
 create mode 100644 apps/playground/pages/components/multi-select.vue
 create mode 100644 packages/ui/src/components/combobox/types.ts
 create mode 100644 packages/ui/src/components/multi-select/MultiSelect.vue
 create mode 100644 packages/ui/src/components/multi-select/index.ts
 create mode 100644 packages/ui/src/components/multi-select/types.ts

diff --git a/.changeset/tender-selects-grow.md b/.changeset/tender-selects-grow.md
new file mode 100644
index 0000000..ee964eb
--- /dev/null
+++ b/.changeset/tender-selects-grow.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add MultiSelect with searchable grouped options, removable selection tags, clearing, and form validation support.
diff --git a/apps/playground/pages/components/multi-select.vue b/apps/playground/pages/components/multi-select.vue
new file mode 100644
index 0000000..e72a6cd
--- /dev/null
+++ b/apps/playground/pages/components/multi-select.vue
@@ -0,0 +1,51 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="MultiSelect 多选" description="为告警渠道、区域、标签与成员分配提供可搜索、多标签的选择体验。" />
+
+    <DocExample title="按区域筛选节点" description="已选项显示为可移除标签；可输入过滤、从分组选项中多选，或一键清除。" :code="rcCode0">
+      <MultiSelect v-model="regions" :options="options" label="部署区域" hint="至少选择一个可用区域" placeholder="搜索区域…" />
+      <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">已选择：{{ regions.length ? regions.join('、') : '无' }}</p>
+    </DocExample>
+
+    <DocExample title="禁用与校验状态" description="继承 Field 的标签、提示、必填和错误信息能力。" :code="rcCode1">
+      <MultiSelect v-model="reviewers" :options="reviewerOptions" label="变更审批人" error="至少指定一位审批人" required />
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="multi-select" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+const regions = ref(['hkg', 'nrt'])
+const reviewers = ref<string[]>([])
+const options = [
+  { label: '中国香港 · HKG', value: 'hkg', group: '亚太' },
+  { label: '日本东京 · NRT', value: 'nrt', group: '亚太' },
+  { label: '德国法兰克福 · FRA', value: 'fra', group: '欧洲' },
+  { label: '美国硅谷 · SJC', value: 'sjc', group: '美洲', disabled: true }
+]
+const reviewerOptions = [{ label: 'Lin Chen', value: 'lin' }, { label: 'Mira Wang', value: 'mira' }]
+const rcCode0 = `<MultiSelect
+  v-model="regions"
+  :options="options"
+  label="部署区域"
+  placeholder="搜索区域…"
+/>`
+const rcCode1 = `<MultiSelect
+  v-model="reviewers"
+  :options="reviewerOptions"
+  label="变更审批人"
+  error="至少指定一位审批人"
+  required
+/>`
+const apiRows = [
+  { name: 'v-model', type: 'string[]', default: '[]', description: '已选选项值的受控数组。' },
+  { name: 'options', type: '{ label, value, group?, disabled? }[]', default: '—', description: '支持分组和禁用状态的选项数据。' },
+  { name: 'placeholder / emptyText', type: 'string', default: "'搜索并选择...' / '无匹配项'", description: '搜索输入与空结果文案。' },
+  { name: 'clearable', type: 'boolean', default: 'true', description: '显示清除全部已选项的按钮。' },
+  { name: 'label / hint / error / required', type: 'string / boolean', default: '—', description: '继承 Field 的表单语义与校验呈现。' },
+  { name: 'clear', type: 'event', default: '—', description: '用户清除所有已选项时触发。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 8849b6f..7793c67 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -50,6 +50,7 @@ const groups: DocGroup[] = [
       { name: 'rating', title: 'Rating 评分', description: '星级评分组件。' },
       { name: 'combobox', title: 'Combobox 组合框', description: '可搜索的下拉选择。' },
       { name: 'number-field', title: 'NumberField 数字输入', description: '步进增减数字。' },
+      { name: 'multi-select', title: 'MultiSelect 多选', description: '带搜索和标签的多值选择。' },
       { name: 'pin-input', title: 'PinInput 验证码', description: 'OTP 分段输入。' },
       { name: 'editable', title: 'Editable 行内编辑', description: '点击即改的文本。' },
       { name: 'toggle', title: 'Toggle / ToggleGroup', description: '按压态工具按钮与分组。' },
diff --git a/packages/ui/src/components/combobox/Combobox.vue b/packages/ui/src/components/combobox/Combobox.vue
index d314778..3f666f2 100644
--- a/packages/ui/src/components/combobox/Combobox.vue
+++ b/packages/ui/src/components/combobox/Combobox.vue
@@ -92,29 +92,7 @@ import {
   ComboboxEmpty
 } from 'reka-ui'
 import Field from '../field/Field.vue'
-
-export interface ComboboxOption {
-  label: string
-  value: string
-  disabled?: boolean
-  group?: string
-}
-
-export interface ComboboxProps {
-  modelValue?: string | string[]
-  options: ComboboxOption[]
-  multiple?: boolean
-  placeholder?: string
-  id?: string
-  label?: string
-  hint?: string
-  error?: string
-  required?: boolean
-  emptyText?: string
-  noClear?: boolean
-  disabled?: boolean
-  class?: string
-}
+import type { ComboboxOption, ComboboxProps } from './types'
 
 const props = withDefaults(defineProps<ComboboxProps>(), {
   modelValue: '',
diff --git a/packages/ui/src/components/combobox/index.ts b/packages/ui/src/components/combobox/index.ts
index 79c36d0..6850713 100644
--- a/packages/ui/src/components/combobox/index.ts
+++ b/packages/ui/src/components/combobox/index.ts
@@ -1,3 +1,2 @@
 export { default as Combobox } from './Combobox.vue'
-export type { ComboboxProps } from './Combobox.vue'
-export type { ComboboxOption } from './Combobox.vue'
+export type { ComboboxOption, ComboboxProps } from './types'
diff --git a/packages/ui/src/components/combobox/types.ts b/packages/ui/src/components/combobox/types.ts
new file mode 100644
index 0000000..08517fa
--- /dev/null
+++ b/packages/ui/src/components/combobox/types.ts
@@ -0,0 +1,22 @@
+export interface ComboboxOption {
+  label: string
+  value: string
+  disabled?: boolean
+  group?: string
+}
+
+export interface ComboboxProps {
+  modelValue?: string | string[]
+  options: ComboboxOption[]
+  multiple?: boolean
+  placeholder?: string
+  id?: string
+  label?: string
+  hint?: string
+  error?: string
+  required?: boolean
+  emptyText?: string
+  noClear?: boolean
+  disabled?: boolean
+  class?: string
+}
diff --git a/packages/ui/src/components/multi-select/MultiSelect.vue b/packages/ui/src/components/multi-select/MultiSelect.vue
new file mode 100644
index 0000000..387d3b9
--- /dev/null
+++ b/packages/ui/src/components/multi-select/MultiSelect.vue
@@ -0,0 +1,31 @@
+<template>
+  <Field :id="props.id" :label="props.label" :hint="props.hint" :error="props.error" :required="props.required">
+    <template #default="field">
+      <ComboboxRoot v-model:open="open" :model-value="props.modelValue" :multiple="true" :disabled="props.disabled" class="w-full" @update:model-value="updateValue">
+        <ComboboxAnchor :class="cn('flex min-h-10 w-full flex-wrap items-center gap-1.5 rounded-lg bg-white px-2 py-1.5 text-sm shadow-xs ring-1 ring-inset transition-all focus-within:ring-2 dark:bg-[#0F172A]', props.error ? 'ring-red-500 focus-within:ring-red-500' : 'ring-slate-300 focus-within:ring-[#2563EB] dark:ring-slate-700 dark:focus-within:ring-[#70ACFE]', props.disabled && 'cursor-not-allowed bg-slate-50 opacity-50 dark:bg-slate-900/60', props.class)" :aria-describedby="field.describedby" :aria-invalid="field.invalid || undefined">
+          <span v-for="option in selectedOptions" :key="option.value" class="inline-flex max-w-full items-center gap-1 rounded-md bg-blue-50 px-2 py-0.5 text-xs font-medium text-[#1E63CE] dark:bg-blue-950/60 dark:text-[#70ACFE]">{{ option.label }}<button type="button" :disabled="props.disabled" :aria-label="`移除 ${option.label}`" class="inline-flex h-3.5 w-3.5 items-center justify-center rounded-full text-blue-400 hover:bg-blue-100 hover:text-blue-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-blue-500 dark:hover:bg-blue-900" @click.stop="remove(option.value)"><svg class="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg></button></span>
+          <ComboboxInput :id="field.id" :required="props.required && !props.modelValue.length" :placeholder="props.modelValue.length ? '' : props.placeholder" :disabled="props.disabled" class="min-w-24 grow bg-transparent px-1 py-0.5 text-sm text-slate-900 outline-none placeholder:text-slate-400 disabled:cursor-not-allowed dark:text-slate-100" :display-value="() => ''" />
+          <button v-if="props.clearable && props.modelValue.length" type="button" :disabled="props.disabled" class="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-slate-400 hover:bg-slate-100 hover:text-slate-600 dark:hover:bg-slate-800 dark:hover:text-slate-200" aria-label="清除所有选择" @click.stop="clear"><svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg></button>
+          <ComboboxTrigger class="shrink-0 text-slate-400 dark:text-slate-500"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="m7 15 5 5 5-5M7 9l5-5 5 5" /></svg></ComboboxTrigger>
+        </ComboboxAnchor>
+        <ComboboxPortal><ComboboxContent position="popper" :side-offset="4" class="z-50 max-h-72 w-[var(--reka-combobox-trigger-width,280px)] overflow-hidden rounded-lg bg-white text-slate-900 shadow-md ring-1 ring-inset ring-slate-200 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:bg-[#0F172A] dark:text-slate-100 dark:ring-slate-800"><ComboboxViewport class="p-1"><ComboboxGroup v-for="group in groupedOptions" :key="group.name ?? '__default__'"><ComboboxLabel v-if="group.name" class="px-2 pt-2 pb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400 dark:text-slate-500">{{ group.name }}</ComboboxLabel><ComboboxItem v-for="option in group.options" :key="option.value" :value="option.value" :disabled="option.disabled" class="relative flex w-full cursor-pointer select-none items-center rounded-md py-1.5 pr-8 pl-3 text-sm outline-none transition-colors hover:bg-slate-100 focus:bg-slate-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-50 dark:hover:bg-slate-800 dark:focus:bg-slate-800">{{ option.label }}<ComboboxItemIndicator class="absolute right-2 text-[#2563EB] dark:text-[#70ACFE]"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7" /></svg></ComboboxItemIndicator></ComboboxItem></ComboboxGroup><ComboboxEmpty class="px-3 py-6 text-center text-sm text-slate-400 dark:text-slate-500">{{ props.emptyText }}</ComboboxEmpty></ComboboxViewport></ComboboxContent></ComboboxPortal>
+      </ComboboxRoot>
+    </template>
+  </Field>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { ComboboxAnchor, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxLabel, ComboboxPortal, ComboboxRoot, ComboboxTrigger, ComboboxViewport } from 'reka-ui'
+import { cn } from '../../utils/cn'
+import Field from '../field/Field.vue'
+import type { MultiSelectOption, MultiSelectProps } from './types'
+const props = withDefaults(defineProps<MultiSelectProps>(), { modelValue: () => [], placeholder: '搜索并选择...', id: undefined, label: '', hint: '', error: '', required: false, emptyText: '无匹配项', clearable: true, disabled: false, class: '' })
+const emit = defineEmits<{ (event: 'update:modelValue', value: string[]): void; (event: 'clear'): void }>()
+const open = ref(false)
+const selectedOptions = computed(() => props.modelValue.map((value) => props.options.find((option) => option.value === value)).filter((option): option is MultiSelectOption => Boolean(option)))
+const groupedOptions = computed(() => { const groups: { name?: string; options: MultiSelectOption[] }[] = []; for (const option of props.options) { const previous = groups.at(-1); if (previous && previous.name === option.group) previous.options.push(option); else groups.push({ name: option.group, options: [option] }) } return groups })
+function updateValue(value: unknown) { emit('update:modelValue', Array.isArray(value) ? value.map(String) : []) }
+function remove(value: string) { emit('update:modelValue', props.modelValue.filter((item) => item !== value)) }
+function clear() { emit('update:modelValue', []); emit('clear') }
+</script>
diff --git a/packages/ui/src/components/multi-select/index.ts b/packages/ui/src/components/multi-select/index.ts
new file mode 100644
index 0000000..92e9465
--- /dev/null
+++ b/packages/ui/src/components/multi-select/index.ts
@@ -0,0 +1,2 @@
+export { default as MultiSelect } from './MultiSelect.vue'
+export type { MultiSelectOption, MultiSelectProps } from './types'
diff --git a/packages/ui/src/components/multi-select/types.ts b/packages/ui/src/components/multi-select/types.ts
new file mode 100644
index 0000000..ad54e47
--- /dev/null
+++ b/packages/ui/src/components/multi-select/types.ts
@@ -0,0 +1,21 @@
+export interface MultiSelectOption {
+  label: string
+  value: string
+  disabled?: boolean
+  group?: string
+}
+
+export interface MultiSelectProps {
+  modelValue?: string[]
+  options: MultiSelectOption[]
+  placeholder?: string
+  id?: string
+  label?: string
+  hint?: string
+  error?: string
+  required?: boolean
+  emptyText?: string
+  clearable?: boolean
+  disabled?: boolean
+  class?: string
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index c7ae41d..7df5dc2 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -55,6 +55,7 @@ export * from './components/date-picker'
 export * from './components/app-shell'
 export * from './components/resizable-panel'
 export * from './components/file-upload'
+export * from './components/multi-select'
 
 // Composables & Utilities
 export * from './composables/useTheme'

From 044917a6b500634cc283dd11b124c52251d2ab3e Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 04:16:04 +0800
Subject: [PATCH 11/26] feat: add tree view

---
 .changeset/bright-trees-navigate.md           |  5 ++
 .../playground/pages/components/tree-view.vue | 52 +++++++++++++++++++
 apps/playground/utils/catalog.ts              |  1 +
 .../ui/src/components/tree-view/TreeView.vue  | 37 +++++++++++++
 .../src/components/tree-view/TreeViewNode.vue | 40 ++++++++++++++
 packages/ui/src/components/tree-view/index.ts |  2 +
 packages/ui/src/components/tree-view/types.ts |  6 +++
 packages/ui/src/index.ts                      |  1 +
 8 files changed, 144 insertions(+)
 create mode 100644 .changeset/bright-trees-navigate.md
 create mode 100644 apps/playground/pages/components/tree-view.vue
 create mode 100644 packages/ui/src/components/tree-view/TreeView.vue
 create mode 100644 packages/ui/src/components/tree-view/TreeViewNode.vue
 create mode 100644 packages/ui/src/components/tree-view/index.ts
 create mode 100644 packages/ui/src/components/tree-view/types.ts

diff --git a/.changeset/bright-trees-navigate.md b/.changeset/bright-trees-navigate.md
new file mode 100644
index 0000000..dacc522
--- /dev/null
+++ b/.changeset/bright-trees-navigate.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add TreeView for accessible resource, directory, and permission hierarchies with selection, expansion, and cascaded checkbox states.
diff --git a/apps/playground/pages/components/tree-view.vue b/apps/playground/pages/components/tree-view.vue
new file mode 100644
index 0000000..04ba7d6
--- /dev/null
+++ b/apps/playground/pages/components/tree-view.vue
@@ -0,0 +1,52 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="TreeView 树形视图" description="用于权限继承、云资源拓扑与目录管理的层级浏览控件。" />
+    <DocExample title="资源目录" description="可通过鼠标或键盘展开节点；方向键浏览可见节点，Enter 选中当前项。" :code="rcCode0">
+      <TreeView v-model="selectedResource" v-model:expanded-ids="expandedResources" :nodes="resources" label="云资源目录" class="max-w-md" />
+      <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">当前资源：{{ selectedResource || '未选择' }}</p>
+    </DocExample>
+    <DocExample title="权限范围" description="勾选父节点会级联选择子节点；半选状态反映部分已授权的目录。" :code="rcCode1">
+      <TreeView v-model:checked-ids="grants" :nodes="permissions" checkable :default-expanded-ids="['project', 'production']" label="项目权限" class="max-w-md" />
+      <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">授权项：{{ grants.length }}</p>
+    </DocExample>
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="tree-view" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+const selectedResource = ref('api')
+const expandedResources = ref(['production', 'services'])
+const grants = ref(['logs-read'])
+const resources = [
+  { id: 'production', label: '生产环境', children: [
+    { id: 'services', label: '服务', children: [{ id: 'api', label: 'gateway-api' }, { id: 'worker', label: 'event-worker' }] },
+    { id: 'storage', label: '对象存储' }
+  ] },
+  { id: 'staging', label: '预发布环境', children: [{ id: 'preview', label: 'preview-api' }] }
+]
+const permissions = [{ id: 'project', label: 'recloud-console', children: [{ id: 'production', label: '生产环境', children: [{ id: 'logs-read', label: '查看日志' }, { id: 'deploy', label: '部署服务' }] }, { id: 'billing', label: '账单管理', disabled: true }] }]
+const rcCode0 = `<TreeView
+  v-model="selectedResource"
+  v-model:expanded-ids="expandedResources"
+  :nodes="resources"
+  label="云资源目录"
+/>`
+const rcCode1 = `<TreeView
+  v-model:checked-ids="grants"
+  :nodes="permissions"
+  :default-expanded-ids="['project', 'production']"
+  checkable
+  label="项目权限"
+/>`
+const apiRows = [
+  { name: 'nodes', type: 'TreeNode[]', default: '—', description: '节点数据，节点包含 id、label、children? 和 disabled?。' },
+  { name: 'v-model', type: 'string', default: '—', description: '当前选中节点的 id。' },
+  { name: 'v-model:expanded-ids', type: 'string[]', default: '—', description: '受控的展开节点集合。' },
+  { name: 'default-expanded-ids', type: 'string[]', default: '[]', description: '非受控模式下的初始展开节点。' },
+  { name: 'checkable / v-model:checked-ids', type: 'boolean / string[]', default: 'false / []', description: '启用勾选并受控管理已授权节点。' },
+  { name: 'cascade', type: 'boolean', default: 'true', description: '勾选父节点时是否级联子节点。' },
+  { name: 'select / toggle / check', type: 'event', default: '—', description: '节点选中、展开与勾选变化事件。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 7793c67..817ae0e 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -78,6 +78,7 @@ const groups: DocGroup[] = [
       { name: 'stepper', title: 'Stepper 步骤条', description: '多步流程进度。' },
       { name: 'navigation-menu', title: 'NavigationMenu 导航菜单', description: '悬停展开的顶部导航。' },
       { name: 'toolbar', title: 'Toolbar 工具条', description: '编辑器式按钮组。' },
+      { name: 'tree-view', title: 'TreeView 树形视图', description: '权限、资源与目录的层级浏览。' },
       { name: 'command-palette', title: 'CommandPalette 命令面板', description: '面向开发者工具的全局命令与导航入口。' },
       { name: 'app-shell', title: 'AppShell 应用布局', description: '控制台的侧栏、顶栏与主内容骨架。' },
       { name: 'resizable-panel', title: 'ResizablePanel 可调面板', description: '可拖拽、可键盘调整的工作区分栏。' }
diff --git a/packages/ui/src/components/tree-view/TreeView.vue b/packages/ui/src/components/tree-view/TreeView.vue
new file mode 100644
index 0000000..ce43c37
--- /dev/null
+++ b/packages/ui/src/components/tree-view/TreeView.vue
@@ -0,0 +1,37 @@
+<template>
+  <ul role="tree" :aria-label="props.label" :class="cn('space-y-0.5 rounded-xl bg-white p-2 ring-1 ring-inset ring-slate-200 dark:bg-[#0F172A] dark:ring-slate-800', props.class)">
+    <TreeViewNode v-for="node in props.nodes" :key="node.id" :node="node" :level="1" :expanded-ids="expandedIds" :selected-id="props.modelValue" :checked-ids="props.checkedIds" :checkable="props.checkable" @toggle="toggle" @select="select" @check="toggleChecked" @navigate="navigate" />
+  </ul>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { cn } from '../../utils/cn'
+import TreeViewNode from './TreeViewNode.vue'
+import type { TreeNode } from './types'
+
+export interface TreeViewProps {
+  nodes: TreeNode[]
+  modelValue?: string
+  expandedIds?: string[]
+  defaultExpandedIds?: string[]
+  checkedIds?: string[]
+  checkable?: boolean
+  cascade?: boolean
+  label?: string
+  class?: string
+}
+const props = withDefaults(defineProps<TreeViewProps>(), { modelValue: undefined, expandedIds: undefined, defaultExpandedIds: () => [], checkedIds: () => [], checkable: false, cascade: true, label: '树形目录', class: '' })
+const emit = defineEmits<{ (event: 'update:modelValue', value: string): void; (event: 'update:expandedIds', value: string[]): void; (event: 'update:checkedIds', value: string[]): void; (event: 'select', node: TreeNode): void; (event: 'toggle', node: TreeNode): void; (event: 'check', payload: { node: TreeNode; checked: boolean }): void }>()
+const internalExpanded = ref([...props.defaultExpandedIds])
+const isControlledExpanded = computed(() => props.expandedIds !== undefined)
+const expandedIds = computed(() => isControlledExpanded.value ? props.expandedIds! : internalExpanded.value)
+const visibleNodes = computed(() => { const list: TreeNode[] = []; const visit = (nodes: TreeNode[]) => nodes.forEach((node) => { list.push(node); if (node.children?.length && expandedIds.value.includes(node.id)) visit(node.children) }); visit(props.nodes); return list })
+watch(() => props.defaultExpandedIds, (value) => { if (!isControlledExpanded.value) internalExpanded.value = [...value] })
+function toggle(id: string) { const node = findNode(id); if (!node || node.disabled) return; const next = expandedIds.value.includes(id) ? expandedIds.value.filter((value) => value !== id) : [...expandedIds.value, id]; if (!isControlledExpanded.value) internalExpanded.value = next; emit('update:expandedIds', next); emit('toggle', node) }
+function select(id: string) { const node = findNode(id); if (!node || node.disabled) return; emit('update:modelValue', id); emit('select', node) }
+function toggleChecked(node: TreeNode) { if (node.disabled) return; const affected = props.cascade ? [node.id, ...descendants(node)] : [node.id]; const allChecked = affected.every((id) => props.checkedIds.includes(id)); const next = allChecked ? props.checkedIds.filter((id) => !affected.includes(id)) : [...new Set([...props.checkedIds, ...affected])]; emit('update:checkedIds', next); emit('check', { node, checked: !allChecked }) }
+function descendants(node: TreeNode): string[] { const ids: string[] = []; node.children?.forEach((child) => { ids.push(child.id, ...descendants(child)) }); return ids }
+function findNode(id: string): TreeNode | undefined { const visit = (nodes: TreeNode[]): TreeNode | undefined => { for (const node of nodes) { if (node.id === id) return node; const match = node.children && visit(node.children); if (match) return match } }; return visit(props.nodes) }
+function navigate({ event, node }: { event: KeyboardEvent; node: TreeNode }) { const index = visibleNodes.value.findIndex((entry) => entry.id === node.id); if (event.key === 'ArrowRight' && node.children?.length && !expandedIds.value.includes(node.id)) { event.preventDefault(); toggle(node.id); return } if (event.key === 'ArrowLeft' && expandedIds.value.includes(node.id)) { event.preventDefault(); toggle(node.id); return } const target = event.key === 'ArrowDown' ? visibleNodes.value[index + 1] : event.key === 'ArrowUp' ? visibleNodes.value[index - 1] : event.key === 'Home' ? visibleNodes.value[0] : event.key === 'End' ? visibleNodes.value.at(-1) : undefined; if (target) { event.preventDefault(); document.getElementById(`tree-item-${target.id}`)?.focus() } else if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); select(node.id) } }
+</script>
diff --git a/packages/ui/src/components/tree-view/TreeViewNode.vue b/packages/ui/src/components/tree-view/TreeViewNode.vue
new file mode 100644
index 0000000..b64db34
--- /dev/null
+++ b/packages/ui/src/components/tree-view/TreeViewNode.vue
@@ -0,0 +1,40 @@
+<template>
+  <li role="none">
+    <div
+      :id="`tree-item-${node.id}`"
+      role="treeitem"
+      :aria-level="level"
+      :aria-expanded="hasChildren ? expanded : undefined"
+      :aria-selected="selected"
+      :aria-disabled="node.disabled || undefined"
+      :aria-checked="checkable ? (checkState === 'partial' ? 'mixed' : checkState === 'checked') : undefined"
+      :class="cn('group flex min-h-8 items-center gap-1 rounded-md pr-2 text-sm outline-none transition-colors', selected ? 'bg-blue-50 text-[#1E63CE] dark:bg-blue-950/50 dark:text-[#70ACFE]' : 'text-slate-700 hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-800', node.disabled && 'pointer-events-none opacity-45')"
+      :style="{ paddingLeft: `${(level - 1) * 1.25 + 0.375}rem` }"
+      tabindex="0"
+      @click="selectNode"
+      @keydown="onKeydown"
+    >
+      <button v-if="hasChildren" type="button" class="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded text-slate-400 hover:bg-slate-200 hover:text-slate-700 dark:hover:bg-slate-700 dark:hover:text-slate-200" :aria-label="expanded ? `收起 ${node.label}` : `展开 ${node.label}`" @click.stop="emit('toggle', node.id)"><svg :class="cn('h-3.5 w-3.5 transition-transform', expanded && 'rotate-90')" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="m9 18 6-6-6-6" /></svg></button><span v-else class="w-6 shrink-0" />
+      <input v-if="checkable" type="checkbox" :checked="checkState === 'checked'" :indeterminate="checkState === 'partial'" :aria-label="`选择 ${node.label}`" class="h-4 w-4 shrink-0 accent-[#2563EB]" @click.stop @change="emit('check', node)" />
+      <span class="truncate">{{ node.label }}</span>
+    </div>
+    <ul v-if="hasChildren && expanded" role="group"><TreeViewNode v-for="child in node.children" :key="child.id" :node="child" :level="level + 1" :expanded-ids="expandedIds" :selected-id="selectedId" :checked-ids="checkedIds" :checkable="checkable" @toggle="emit('toggle', $event)" @select="emit('select', $event)" @check="emit('check', $event)" @navigate="emit('navigate', $event)" /></ul>
+  </li>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { cn } from '../../utils/cn'
+import type { TreeNode } from './types'
+
+defineOptions({ name: 'TreeViewNode' })
+const props = defineProps<{ node: TreeNode; level: number; expandedIds: string[]; selectedId?: string; checkedIds: string[]; checkable: boolean }>()
+const emit = defineEmits<{ (event: 'toggle', id: string): void; (event: 'select', id: string): void; (event: 'check', node: TreeNode): void; (event: 'navigate', payload: { event: KeyboardEvent; node: TreeNode }): void }>()
+const hasChildren = computed(() => Boolean(props.node.children?.length))
+const expanded = computed(() => props.expandedIds.includes(props.node.id))
+const selected = computed(() => props.selectedId === props.node.id)
+const descendantIds = computed(() => { const ids: string[] = []; const visit = (entry: TreeNode) => entry.children?.forEach((child) => { ids.push(child.id); visit(child) }); visit(props.node); return ids })
+const checkState = computed(() => { const ids = [props.node.id, ...descendantIds.value]; const count = ids.filter((id) => props.checkedIds.includes(id)).length; return count === 0 ? 'unchecked' : count === ids.length ? 'checked' : 'partial' })
+function selectNode() { if (!props.node.disabled) emit('select', props.node.id) }
+function onKeydown(event: KeyboardEvent) { if (!props.node.disabled) emit('navigate', { event, node: props.node }) }
+</script>
diff --git a/packages/ui/src/components/tree-view/index.ts b/packages/ui/src/components/tree-view/index.ts
new file mode 100644
index 0000000..aae7efb
--- /dev/null
+++ b/packages/ui/src/components/tree-view/index.ts
@@ -0,0 +1,2 @@
+export { default as TreeView } from './TreeView.vue'
+export type { TreeNode } from './types'
diff --git a/packages/ui/src/components/tree-view/types.ts b/packages/ui/src/components/tree-view/types.ts
new file mode 100644
index 0000000..e342830
--- /dev/null
+++ b/packages/ui/src/components/tree-view/types.ts
@@ -0,0 +1,6 @@
+export interface TreeNode {
+  id: string
+  label: string
+  disabled?: boolean
+  children?: TreeNode[]
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 7df5dc2..cf02de7 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -56,6 +56,7 @@ export * from './components/app-shell'
 export * from './components/resizable-panel'
 export * from './components/file-upload'
 export * from './components/multi-select'
+export * from './components/tree-view'
 
 // Composables & Utilities
 export * from './composables/useTheme'

From 30b131f093978e58e51209ce6da8b16dc3e635ae Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 04:20:27 +0800
Subject: [PATCH 12/26] feat: add timeline

---
 .changeset/fresh-timelines-flow.md            |  5 +++
 apps/playground/pages/components/timeline.vue | 38 +++++++++++++++++++
 apps/playground/utils/catalog.ts              |  3 +-
 .../ui/src/components/timeline/Timeline.vue   | 25 ++++++++++++
 packages/ui/src/components/timeline/index.ts  |  2 +
 packages/ui/src/components/timeline/types.ts  | 12 ++++++
 packages/ui/src/index.ts                      |  1 +
 7 files changed, 85 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/fresh-timelines-flow.md
 create mode 100644 apps/playground/pages/components/timeline.vue
 create mode 100644 packages/ui/src/components/timeline/Timeline.vue
 create mode 100644 packages/ui/src/components/timeline/index.ts
 create mode 100644 packages/ui/src/components/timeline/types.ts

diff --git a/.changeset/fresh-timelines-flow.md b/.changeset/fresh-timelines-flow.md
new file mode 100644
index 0000000..4bae723
--- /dev/null
+++ b/.changeset/fresh-timelines-flow.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Add Timeline for operational logs and change history with status markers, actor metadata, and customization slots.
diff --git a/apps/playground/pages/components/timeline.vue b/apps/playground/pages/components/timeline.vue
new file mode 100644
index 0000000..62a156a
--- /dev/null
+++ b/apps/playground/pages/components/timeline.vue
@@ -0,0 +1,38 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Timeline 时间线" description="以清晰的状态脉络呈现部署、审计操作和资源变更历史。" />
+    <DocExample title="部署操作日志" description="内置成功、警告、失败和信息状态；支持操作者、时间、说明及元数据。" :code="rcCode0">
+      <Timeline :items="deploymentEvents" class="max-w-2xl" />
+    </DocExample>
+    <DocExample title="自定义标记" description="通过 marker 插槽将时间线节点替换为版本号、头像或业务图标。" :code="rcCode1">
+      <Timeline :items="releaseEvents" class="max-w-2xl">
+        <template #marker="{ index }"><span class="text-[10px] font-bold">{{ index + 1 }}</span></template>
+      </Timeline>
+    </DocExample>
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="timeline" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const deploymentEvents = [
+  { id: 'build', title: '构建已完成', description: '镜像 recloud/gateway:2026.04.18 已推送至生产仓库。', timestamp: '10:32', status: 'success', actor: 'CI Pipeline', metadata: 'sha: 7af19c2' },
+  { id: 'review', title: '变更已批准', description: '生产环境策略检查通过，开始滚动部署。', timestamp: '10:35', status: 'info', actor: 'Lin Chen' },
+  { id: 'rollback', title: '健康检查延迟升高', description: '一个实例未能在预期时间内就绪，系统继续观察。', timestamp: '10:38', status: 'warning', actor: 'Deploy Controller' }
+]
+const releaseEvents = [
+  { id: 'v3', title: 'v3.8.0 发布', description: '加入速率限制策略和审计字段。', timestamp: '今天', status: 'success' },
+  { id: 'v2', title: 'v3.7.0 发布', description: '优化集群节点同步。', timestamp: '上周', status: 'info' }
+]
+const rcCode0 = `<Timeline :items="deploymentEvents" />`
+const rcCode1 = `<Timeline :items="releaseEvents">
+  <template #marker="{ index }">{{ index + 1 }}</template>
+</Timeline>`
+const apiRows = [
+  { name: 'items', type: 'TimelineItem[]', default: '—', description: '时间线项目：id、title、description?、timestamp?、status?、actor?、avatar?、metadata?。' },
+  { name: 'status', type: "'default' | 'info' | 'success' | 'warning' | 'error'", default: "'default'", description: '决定节点标记的颜色和默认图标。' },
+  { name: 'label', type: 'string', default: "'时间线'", description: '列表的无障碍标签。' },
+  { name: 'marker', type: 'slot', default: '—', description: '自定义节点标记，接收 item 和 index。' },
+  { name: 'details', type: 'slot', default: '—', description: '在操作者与元数据之后追加详情。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 817ae0e..b4d331e 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -66,7 +66,8 @@ const groups: DocGroup[] = [
       { name: 'skeleton', title: 'Skeleton 骨架屏', description: '加载占位。' },
       { name: 'empty-state', title: 'EmptyState 空状态', description: '空数据页面引导。' },
       { name: 'file-upload', title: 'FileUpload 文件上传', description: '拖放、校验、进度与失败重试。' },
-      { name: 'separator', title: 'Separator 分隔线', description: '水平与垂直分隔。' }
+      { name: 'separator', title: 'Separator 分隔线', description: '水平与垂直分隔。' },
+      { name: 'timeline', title: 'Timeline 时间线', description: '操作日志与变更历史。' }
     ]
   },
   {
diff --git a/packages/ui/src/components/timeline/Timeline.vue b/packages/ui/src/components/timeline/Timeline.vue
new file mode 100644
index 0000000..b9c2463
--- /dev/null
+++ b/packages/ui/src/components/timeline/Timeline.vue
@@ -0,0 +1,25 @@
+<template>
+  <ol :class="cn('relative space-y-0', props.class)" :aria-label="props.label">
+    <li v-for="(item, index) in props.items" :key="item.id" class="relative grid grid-cols-[auto_minmax(0,1fr)] gap-x-3 pb-7 last:pb-0">
+      <div class="relative z-10 flex w-6 justify-center">
+        <span :class="cn('mt-0.5 flex h-6 w-6 items-center justify-center rounded-full ring-4 ring-white dark:ring-[#0F172A]', statusClasses[item.status ?? 'default'])"><slot name="marker" :item="item" :index="index"><svg v-if="item.status === 'success'" class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="m5 13 4 4L19 7" /></svg><svg v-else-if="item.status === 'error'" class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" d="M12 8v4m0 4h.01" /></svg><svg v-else-if="item.status === 'warning'" class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" d="M12 8v4m0 4h.01" /></svg><span v-else class="h-2 w-2 rounded-full bg-current" /></slot></span>
+      </div>
+      <div v-if="index < props.items.length - 1" class="absolute top-7 bottom-0 left-3 w-px -translate-x-1/2 bg-slate-200 dark:bg-slate-800" aria-hidden="true" />
+      <div class="min-w-0 pt-0.5">
+        <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1"><h3 class="text-sm font-medium text-slate-900 dark:text-slate-100">{{ item.title }}</h3><time v-if="item.timestamp" class="text-xs text-slate-400 dark:text-slate-500">{{ item.timestamp }}</time></div>
+        <p v-if="item.description" class="mt-1 text-sm leading-6 text-slate-600 dark:text-slate-400">{{ item.description }}</p>
+        <div v-if="item.actor || item.metadata || $slots.details" class="mt-2 flex flex-wrap items-center gap-2 text-xs text-slate-500 dark:text-slate-400"><span v-if="item.actor" class="inline-flex items-center gap-1.5"><Avatar v-if="item.avatar" :src="item.avatar" :alt="item.actor" size="xs" />{{ item.actor }}</span><span v-if="item.metadata" class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[11px] text-slate-600 dark:bg-slate-800 dark:text-slate-300">{{ item.metadata }}</span><slot name="details" :item="item" :index="index" /></div>
+      </div>
+    </li>
+  </ol>
+</template>
+
+<script setup lang="ts">
+import { cn } from '../../utils/cn'
+import Avatar from '../avatar/Avatar.vue'
+import type { TimelineItem, TimelineStatus } from './types'
+
+export interface TimelineProps { items: TimelineItem[]; label?: string; class?: string }
+const props = withDefaults(defineProps<TimelineProps>(), { label: '时间线', class: '' })
+const statusClasses: Record<TimelineStatus, string> = { default: 'bg-slate-100 text-slate-500 dark:bg-slate-800 dark:text-slate-400', info: 'bg-blue-100 text-[#2563EB] dark:bg-blue-950 dark:text-[#70ACFE]', success: 'bg-emerald-100 text-emerald-600 dark:bg-emerald-950 dark:text-emerald-400', warning: 'bg-amber-100 text-amber-600 dark:bg-amber-950 dark:text-amber-400', error: 'bg-red-100 text-red-600 dark:bg-red-950 dark:text-red-400' }
+</script>
diff --git a/packages/ui/src/components/timeline/index.ts b/packages/ui/src/components/timeline/index.ts
new file mode 100644
index 0000000..a426a17
--- /dev/null
+++ b/packages/ui/src/components/timeline/index.ts
@@ -0,0 +1,2 @@
+export { default as Timeline } from './Timeline.vue'
+export type { TimelineItem, TimelineStatus } from './types'
diff --git a/packages/ui/src/components/timeline/types.ts b/packages/ui/src/components/timeline/types.ts
new file mode 100644
index 0000000..ac7941f
--- /dev/null
+++ b/packages/ui/src/components/timeline/types.ts
@@ -0,0 +1,12 @@
+export type TimelineStatus = 'default' | 'info' | 'success' | 'warning' | 'error'
+
+export interface TimelineItem {
+  id: string
+  title: string
+  description?: string
+  timestamp?: string
+  status?: TimelineStatus
+  actor?: string
+  avatar?: string
+  metadata?: string
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index cf02de7..a428731 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -57,6 +57,7 @@ export * from './components/resizable-panel'
 export * from './components/file-upload'
 export * from './components/multi-select'
 export * from './components/tree-view'
+export * from './components/timeline'
 
 // Composables & Utilities
 export * from './composables/useTheme'

From 407951c426aae267400eeb1da1ce2fb2ef3b5734 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 04:40:39 +0800
Subject: [PATCH 13/26] feat(theme): add configurable design tokens

---
 .changeset/soft-themes-adapt.md         |   5 +
 AGENTS.md                               |  58 ++++
 apps/playground/nuxt.config.ts          |   5 +-
 packages/ui/src/composables/useTheme.ts | 172 +++++++-----
 packages/ui/src/index.ts                |   1 +
 packages/ui/src/nuxt/index.ts           |  14 +-
 packages/ui/src/nuxt/types.ts           |  10 +-
 packages/ui/src/theme.css               | 346 ++++++++++++------------
 packages/ui/src/utils/themeScript.ts    |  10 +
 9 files changed, 382 insertions(+), 239 deletions(-)
 create mode 100644 .changeset/soft-themes-adapt.md
 create mode 100644 packages/ui/src/utils/themeScript.ts

diff --git a/.changeset/soft-themes-adapt.md b/.changeset/soft-themes-adapt.md
new file mode 100644
index 0000000..32ce9a3
--- /dev/null
+++ b/.changeset/soft-themes-adapt.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add a configurable theme system with system color mode, palettes, density, radius, shadows, persistent preferences, and hydration-safe Nuxt initialization. Publish layered primitive and semantic CSS design tokens for consistent component styling.
diff --git a/AGENTS.md b/AGENTS.md
index 6d68298..cc76829 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,6 +9,29 @@ Read `docs/README.md` inside that installed package first, then read the relevan
 This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
 <!-- END:turborepo-agent-rules -->
 
+## ReCloud UI Agent Guide
+
+## External Engineering Standards
+
+The following standards are mandatory when their subject applies to the task:
+
+- [Git workflow](https://docs.worldexecute.me/development/git/)
+- [TypeScript style](https://docs.worldexecute.me/development/ts-style/)
+- [Markdown style](https://docs.worldexecute.me/development/markdown/)
+
+Read only the standard required for the current work; do not preload all three to conserve context.
+
+| Work being performed | Required reading |
+| --- | --- |
+| Creating branches, committing, preparing a PR, merging, tagging, or changing Git history | Git workflow |
+| Adding or modifying `.ts`, `.tsx`, `.js`, `.jsx`, or Vue script code | TypeScript style |
+| Adding or modifying `.md` / `.mdx` content, including Changesets | Markdown style |
+
+- Read the relevant linked standard before performing the matching work, and apply its rules throughout that task.
+- Repository-local instructions, package scripts, and release workflow take precedence where they explicitly conflict with an external standard. In particular, this repository develops on `dev` as described in [Releases](#releases).
+- Do not fetch, quote, or duplicate the full external standards in issues, PRs, commits, or repository files. Link to them and retain only task-specific project rules here.
+- Do not commit secrets, credentials, tokens, local IDE settings, build output, or temporary files. Keep commits focused and independently verifiable.
+
 ## Workspace
 
 - Use Bun 1.4.2. This is a Bun workspace: the publishable Vue 3 library is `packages/ui`; `apps/playground` is the Nuxt 4 documentation and integration app.
@@ -24,6 +47,41 @@ This block is written and re-added by `turbo` before repository-scoped commands
 - The Playground build refuses to run while a Nuxt dev server holds `apps/playground/.nuxt`; stop the dev server first.
 - `bun run ci` is the full workspace gate. Biome intentionally excludes `.vue` files, so do not treat a passing root lint as Vue validation.
 
+## Component Delivery
+
+- A published component lives in `packages/ui/src/components/<name>/`. Keep its implementation, public types, and `index.ts` barrel together.
+- Export every public component and type from `packages/ui/src/index.ts`. Do not expose implementation-only helpers by accident.
+- Every new public component needs a Playground page at `apps/playground/pages/components/<name>.vue` and an entry in `apps/playground/utils/catalog.ts`.
+- `catalog.ts` sorts entries inside each category by title; preserve category order and do not manually work around that sort.
+- Follow existing Vue 3 patterns: typed props and emits, `cn()` for class composition, keyboard interactions and ARIA semantics for every interactive control, and light/dark mode support.
+- Build console-oriented primitives first: dense but readable states, durable empty/loading/error states, controlled data APIs, and explicit async ownership. Do not make network requests or invent backend protocols inside UI components.
+- Keep public state controlled where consumers need to own it. If a component also offers an uncontrolled default, document the interaction and preserve predictable update events.
+
+## Theme and Design Tokens
+
+- Treat `packages/ui/src/theme.css` as the token source of truth. Use semantic tokens (`--background`, `--foreground`, `--card`, `--primary`, `--border`, `--ring`, and status tokens) rather than hard-coded palette values in new or modified components.
+- Keep the three visual layers distinct: brand gradients are for emphasis and primary moments; surfaces are neutral; semantic colors communicate status. Never use the brand gradient as generic decoration.
+- `useTheme()` owns persisted user preferences for color mode, palette, density, radius, and shadow. Keep `light`, `dark`, and `system` behavior hydration-safe; `auto` remains a compatibility alias only.
+- Any persisted theme preference must be represented both by `useTheme()` and `createThemeInitScript()` so the pre-hydration document state matches the hydrated app.
+- Preserve legacy CSS variable aliases while migrating components; removing or renaming a public token is a breaking change.
+- Use the Sans font stack for UI and the Mono stack for code. Apply tabular numbers to data-heavy tables and metrics with `.rc-tabular-nums` or `data-numeric`.
+
+## Changesets
+
+- Every consumer-visible `@recloudstudio/ui` change requires a Changeset in `.changeset/`; docs-only, tests-only, tooling-only, and behavior-neutral refactors do not.
+- Read package names from `package.json`; never list private apps or invent package names.
+- Choose the smallest valid bump: `patch` for compatible fixes, `minor` for compatible public features/options/exports, and `major` only for consumer-breaking API or behavior changes.
+- Write one or two concise English release-note sentences focused on consumer impact. Do not edit package versions, generated changelogs, or `.changeset/config.json` unless explicitly asked.
+- Create and validate the Changeset in the same change as the feature. A typical file is:
+
+  ```md
+  ---
+  "@recloudstudio/ui": minor
+  ---
+
+  Add configurable theme preferences and hydration-safe initialization.
+  ```
+
 ## Releases
 
 - Develop on `dev`; merge `dev` into `main` only for a planned release. Do not commit feature work directly to `main`, except an urgent production fix.
diff --git a/apps/playground/nuxt.config.ts b/apps/playground/nuxt.config.ts
index 93067e5..ead15c4 100644
--- a/apps/playground/nuxt.config.ts
+++ b/apps/playground/nuxt.config.ts
@@ -1,5 +1,6 @@
 import { defineNuxtConfig } from 'nuxt/config'
 import tailwindcss from '@tailwindcss/vite'
+import { createThemeInitScript } from '../../packages/ui/src/utils/themeScript'
 
 export default defineNuxtConfig({
   // 固定 buildDir：Nuxt 4 生产构建会在 .nuxt 已存在时自动切到 node_modules/.cache，
@@ -12,8 +13,8 @@ export default defineNuxtConfig({
       title: 'ReCloud UI · ReCloud Studio 设计系统',
       script: [
         {
-          // 首屏主题引导：在渲染前应用已保存主题，避免深浅色闪烁
-          innerHTML: `(function(){try{var m=localStorage.getItem('recloud-theme')||'auto';var d=m==='dark'||(m==='auto'&&matchMedia('(prefers-color-scheme: dark)').matches);var e=document.documentElement;e.classList.toggle('dark',d);e.dataset.theme=d?'dark':'light';}catch(e){}})();`
+          // 首屏应用完整的主题偏好，避免 Vue hydration 前的颜色、密度与圆角闪烁。
+          innerHTML: createThemeInitScript()
         }
       ],
       link: [
diff --git a/packages/ui/src/composables/useTheme.ts b/packages/ui/src/composables/useTheme.ts
index e0eca5c..6ee32f3 100644
--- a/packages/ui/src/composables/useTheme.ts
+++ b/packages/ui/src/composables/useTheme.ts
@@ -1,86 +1,130 @@
-import { ref, computed, onMounted } from "vue";
+import { computed, onMounted, ref } from 'vue'
+
+/** `auto` is retained as a backwards-compatible alias for `system`. */
+export type ThemeMode = 'light' | 'dark' | 'system' | 'auto'
+export type ResolvedThemeMode = 'light' | 'dark'
+export type ThemePalette = 'recloud' | 'ocean' | 'violet' | 'slate'
+export type ThemeDensity = 'compact' | 'comfortable' | 'spacious'
+export type ThemeRadius = 'none' | 'sm' | 'md' | 'lg'
+export type ThemeShadow = 'none' | 'sm' | 'md' | 'lg'
+
+export interface ThemePreferences {
+  mode: ThemeMode
+  palette: ThemePalette
+  density: ThemeDensity
+  radius: ThemeRadius
+  shadow: ThemeShadow
+}
 
-export type ThemeMode = "light" | "dark" | "auto";
+export interface UseThemeOptions {
+  storageKey?: string
+  defaultMode?: ThemeMode
+  defaultPalette?: ThemePalette
+  defaultDensity?: ThemeDensity
+  defaultRadius?: ThemeRadius
+  defaultShadow?: ThemeShadow
+}
 
-const currentMode = ref<ThemeMode>("auto");
-const systemIsDark = ref(false);
+const defaults: ThemePreferences = {
+  mode: 'system',
+  palette: 'recloud',
+  density: 'comfortable',
+  radius: 'md',
+  shadow: 'sm'
+}
 
-let initialized = false;
+const preferences = ref<ThemePreferences>({ ...defaults })
+const systemIsDark = ref(false)
+let initialized = false
+let mediaQuery: MediaQueryList | undefined
+let storageKey = 'recloud-theme'
 
-function updateMediaListener() {
-  if (typeof window === "undefined" || !window.matchMedia) return;
-  const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
-  systemIsDark.value = mediaQuery.matches;
+function normalizeMode(mode: ThemeMode): 'light' | 'dark' | 'system' {
+  return mode === 'auto' ? 'system' : mode
+}
 
-  mediaQuery.addEventListener("change", (e) => {
-    systemIsDark.value = e.matches;
-    if (currentMode.value === "auto") {
-      applyTheme();
-    }
-  });
+function resolveTheme(mode = preferences.value.mode): ResolvedThemeMode {
+  return normalizeMode(mode) === 'dark' || (normalizeMode(mode) === 'system' && systemIsDark.value) ? 'dark' : 'light'
 }
 
 function applyTheme() {
-  if (typeof document === "undefined") return;
-
-  const isDark =
-    currentMode.value === "dark" ||
-    (currentMode.value === "auto" && systemIsDark.value);
+  if (typeof document === 'undefined') return
+  const root = document.documentElement
+  const resolved = resolveTheme()
+  root.classList.toggle('dark', resolved === 'dark')
+  root.dataset.theme = resolved
+  root.dataset.themeMode = normalizeMode(preferences.value.mode)
+  root.dataset.themePalette = preferences.value.palette
+  root.dataset.themeDensity = preferences.value.density
+  root.dataset.themeRadius = preferences.value.radius
+  root.dataset.themeShadow = preferences.value.shadow
+}
 
-  const root = document.documentElement;
-  const body = document.body;
+function persist() {
+  if (typeof window === 'undefined') return
+  window.localStorage.setItem(storageKey, JSON.stringify(preferences.value))
+}
 
-  if (isDark) {
-    root.classList.add("dark");
-    root.setAttribute("data-theme", "dark");
-    body?.classList.add("dark");
-    body?.setAttribute("data-theme", "dark");
-  } else {
-    root.classList.remove("dark");
-    root.setAttribute("data-theme", "light");
-    body?.classList.remove("dark");
-    body?.setAttribute("data-theme", "light");
+function hydrate(options: UseThemeOptions) {
+  if (initialized || typeof window === 'undefined') return
+  initialized = true
+  storageKey = options.storageKey ?? storageKey
+  const fallback: ThemePreferences = {
+    mode: options.defaultMode ?? defaults.mode,
+    palette: options.defaultPalette ?? defaults.palette,
+    density: options.defaultDensity ?? defaults.density,
+    radius: options.defaultRadius ?? defaults.radius,
+    shadow: options.defaultShadow ?? defaults.shadow
+  }
+  try {
+    const saved = JSON.parse(window.localStorage.getItem(storageKey) ?? '{}') as Partial<ThemePreferences>
+    preferences.value = { ...fallback, ...saved }
+  } catch {
+    preferences.value = fallback
   }
+  mediaQuery = window.matchMedia?.('(prefers-color-scheme: dark)')
+  systemIsDark.value = mediaQuery?.matches ?? false
+  mediaQuery?.addEventListener('change', (event) => {
+    systemIsDark.value = event.matches
+    if (normalizeMode(preferences.value.mode) === 'system') applyTheme()
+  })
+  applyTheme()
 }
 
-export function useTheme() {
-  onMounted(() => {
-    if (!initialized) {
-      initialized = true;
-      updateMediaListener();
-
-      const saved = localStorage.getItem("recloud-theme") as ThemeMode | null;
-      if (saved && (saved === "light" || saved === "dark" || saved === "auto")) {
-        currentMode.value = saved;
-      }
+export function useTheme(options: UseThemeOptions = {}) {
+  onMounted(() => hydrate(options))
 
-      applyTheme();
-    }
-  });
+  const resolvedMode = computed<ResolvedThemeMode>(() => resolveTheme())
+  const isDark = computed(() => resolvedMode.value === 'dark')
 
-  const isDark = computed(() => {
-    return (
-      currentMode.value === "dark" ||
-      (currentMode.value === "auto" && systemIsDark.value)
-    );
-  });
-
-  function setMode(mode: ThemeMode) {
-    currentMode.value = mode;
-    if (typeof localStorage !== "undefined") {
-      localStorage.setItem("recloud-theme", mode);
-    }
-    applyTheme();
+  function update(next: Partial<ThemePreferences>) {
+    preferences.value = { ...preferences.value, ...next }
+    persist()
+    applyTheme()
   }
 
-  function toggle() {
-    setMode(isDark.value ? "light" : "dark");
-  }
+  function setMode(mode: ThemeMode) { update({ mode: normalizeMode(mode) }) }
+  function setPalette(palette: ThemePalette) { update({ palette }) }
+  function setDensity(density: ThemeDensity) { update({ density }) }
+  function setRadius(radius: ThemeRadius) { update({ radius }) }
+  function setShadow(shadow: ThemeShadow) { update({ shadow }) }
+  function toggle() { setMode(isDark.value ? 'light' : 'dark') }
 
   return {
-    mode: currentMode,
+    mode: computed(() => preferences.value.mode),
+    resolvedMode,
+    palette: computed(() => preferences.value.palette),
+    density: computed(() => preferences.value.density),
+    radius: computed(() => preferences.value.radius),
+    shadow: computed(() => preferences.value.shadow),
+    preferences: computed(() => preferences.value),
     isDark,
     setMode,
-    toggle,
-  };
+    setPalette,
+    setDensity,
+    setRadius,
+    setShadow,
+    update,
+    toggle
+  }
 }
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index a428731..d11b735 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -63,3 +63,4 @@ export * from './components/timeline'
 export * from './composables/useTheme'
 export * from './utils/cn'
 export * from './utils/theme'
+export * from './utils/themeScript'
diff --git a/packages/ui/src/nuxt/index.ts b/packages/ui/src/nuxt/index.ts
index c783a94..8d9bd8c 100644
--- a/packages/ui/src/nuxt/index.ts
+++ b/packages/ui/src/nuxt/index.ts
@@ -1,6 +1,7 @@
 import { addComponentExports, addImportsSources, createResolver, defineNuxtModule, addTypeTemplate } from '@nuxt/kit'
 import type { NuxtModule } from '@nuxt/schema'
 import type { ModuleOptions } from './types'
+import { createThemeInitScript } from '../utils/themeScript'
 
 export * from './types'
 
@@ -14,7 +15,9 @@ const module: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({
     },
     defaults: {
       prefix: 'Re',
-      injectTheme: true
+      injectTheme: true,
+      themeStorageKey: 'recloud-theme',
+      injectThemeScript: true
     },
     setup(options, nuxt) {
       const resolver = createResolver(import.meta.url)
@@ -37,6 +40,15 @@ export {}`
         nuxt.options.css.push(resolver.resolve('../style.css'))
       }
 
+      if (options.injectThemeScript) {
+        nuxt.options.app.head.script ||= []
+        nuxt.options.app.head.script.unshift({
+          key: 'recloud-theme-init',
+          innerHTML: createThemeInitScript(options.themeStorageKey),
+          tagPosition: 'head'
+        })
+      }
+
       addComponentExports({
         filePath: resolver.resolve('../index.js'),
         prefix: options.prefix,
diff --git a/packages/ui/src/nuxt/types.ts b/packages/ui/src/nuxt/types.ts
index 0542799..d633900 100644
--- a/packages/ui/src/nuxt/types.ts
+++ b/packages/ui/src/nuxt/types.ts
@@ -10,9 +10,17 @@ export interface ModuleOptions {
    * @default true
    */
   injectTheme?: boolean
+
+  /** Storage key shared by the SSR initialization script and `useTheme`. */
+  themeStorageKey?: string
+
+  /** Apply saved theme attributes before Vue hydrates to prevent a color-mode flash. */
+  injectThemeScript?: boolean
 }
 
 export const defaultOptions: ModuleOptions = {
   prefix: 'Re',
-  injectTheme: true
+  injectTheme: true,
+  themeStorageKey: 'recloud-theme',
+  injectThemeScript: true
 }
diff --git a/packages/ui/src/theme.css b/packages/ui/src/theme.css
index 84dcd46..1b42fb1 100644
--- a/packages/ui/src/theme.css
+++ b/packages/ui/src/theme.css
@@ -1,186 +1,190 @@
+/* ReCloud design tokens: primitives → semantics → component aliases. */
 :root {
-  /* ReCloud Studio 品牌蓝主调 (50-950) */
-  --color-primary-50: #EFF6FF;
-  --color-primary-100: #DBEAFE;
-  --color-primary-200: #BFDBFE;
-  --color-primary-300: #93C5FD;
-  --color-primary-400: #60A5FA;
-  --color-primary-500: #3B82F6;
-  --color-primary-600: #2563EB;
-  --color-primary-700: #1D4ED8;
-  --color-primary-800: #1E40AF;
-  --color-primary-900: #1E3A8A;
-  --color-primary-950: #172554;
-
-  /* 品牌规范对应档位 */
-  --brand-50: #C8E0FD;
-  --brand-100: #9BC5FE;
-  --brand-200: #70ACFE;
-  --brand-300: #417BDF;
-  --brand-600: #3069C9;
-  --brand-700: #1E63CE;
-
-  /* 垂直单调蓝渐变规范 (严格自顶向下 180deg) */
-  --brand-gradient: linear-gradient(180deg, #C8E0FD 0%, #9BC5FE 25%, #70ACFE 50%, #417BDF 75%, #3069C9 100%);
-  --brand-gradient-compact: linear-gradient(180deg, #C8E0FD 0%, #3069C9 100%);
-  --brand-gradient-card: linear-gradient(180deg, #70ACFE 0%, #3069C9 100%);
-  --brand-gradient-button: linear-gradient(180deg, #417BDF 0%, #1E63CE 100%);
-
-  /* Nuxt UI 语义背景与层级 (浅色模式) */
-  --ui-bg: #FFFFFF;
-  --ui-bg-muted: #F8FAFC;
-  --ui-bg-elevated: #F1F5F9;
-  --ui-bg-accented: #E2E8F0;
-  --ui-bg-inverted: #0F172A;
-
-  /* Nuxt UI 语义文字体系 */
-  --ui-text-highlighted: #0F172A;
+  /* Primitive color scales */
+  --rc-blue-50: #eff6ff;
+  --rc-blue-100: #dbeafe;
+  --rc-blue-200: #bfdbfe;
+  --rc-blue-300: #93c5fd;
+  --rc-blue-400: #60a5fa;
+  --rc-blue-500: #3b82f6;
+  --rc-blue-600: #2563eb;
+  --rc-blue-700: #1d4ed8;
+  --rc-blue-800: #1e40af;
+  --rc-blue-900: #1e3a8a;
+  --rc-blue-950: #172554;
+
+  --rc-radius-none: 0;
+  --rc-radius-sm: 0.375rem;
+  --rc-radius-md: 0.5rem;
+  --rc-radius-lg: 0.75rem;
+  --rc-shadow-none: none;
+  --rc-shadow-sm: 0 1px 2px rgb(15 23 42 / 0.06), 0 1px 1px rgb(15 23 42 / 0.04);
+  --rc-shadow-md: 0 4px 10px rgb(15 23 42 / 0.10), 0 2px 4px rgb(15 23 42 / 0.05);
+  --rc-shadow-lg: 0 16px 32px rgb(15 23 42 / 0.14), 0 6px 12px rgb(15 23 42 / 0.08);
+
+  /* Semantic tokens */
+  --background: #ffffff;
+  --foreground: #0f172a;
+  --card: #ffffff;
+  --card-foreground: #0f172a;
+  --surface-muted: #f8fafc;
+  --surface-elevated: #f1f5f9;
+  --muted: #f1f5f9;
+  --muted-foreground: #64748b;
+  --border: #e2e8f0;
+  --border-muted: #f1f5f9;
+  --primary: var(--rc-blue-600);
+  --primary-hover: var(--rc-blue-700);
+  --primary-foreground: #ffffff;
+  --ring: var(--rc-blue-600);
+  --success: #059669;
+  --success-foreground: #ffffff;
+  --warning: #d97706;
+  --warning-foreground: #ffffff;
+  --destructive: #dc2626;
+  --destructive-foreground: #ffffff;
+  --info: var(--rc-blue-600);
+
+  --radius-sm: var(--rc-radius-sm);
+  --radius-md: var(--rc-radius-md);
+  --radius-lg: var(--rc-radius-lg);
+  --shadow-xs: var(--rc-shadow-sm);
+  --shadow-sm: var(--rc-shadow-sm);
+  --shadow-md: var(--rc-shadow-md);
+  --shadow-lg: var(--rc-shadow-lg);
+  --shadow-xl: var(--rc-shadow-lg);
+
+  /* Brand tokens are emphasis-only: use in primary actions and hero surfaces. */
+  --brand-50: #c8e0fd;
+  --brand-100: #9bc5fe;
+  --brand-200: #70acfe;
+  --brand-300: #417bdf;
+  --brand-600: #3069c9;
+  --brand-700: #1e63ce;
+  --brand-gradient: linear-gradient(180deg, var(--brand-50) 0%, var(--brand-100) 25%, var(--brand-200) 50%, var(--brand-300) 75%, var(--brand-600) 100%);
+  --brand-gradient-compact: linear-gradient(180deg, var(--brand-50), var(--brand-600));
+  --brand-gradient-card: linear-gradient(180deg, var(--brand-200), var(--brand-600));
+
+  /* Legacy aliases */
+  --ui-bg: var(--background);
+  --ui-bg-muted: var(--surface-muted);
+  --ui-bg-elevated: var(--surface-elevated);
+  --ui-bg-accented: #e2e8f0;
+  --ui-bg-inverted: var(--foreground);
+  --ui-text-highlighted: var(--foreground);
   --ui-text: #334155;
-  --ui-text-muted: #64748B;
-  --ui-text-dimmed: #94A3B8;
-  --ui-text-inverted: #FFFFFF;
-
-  /* Nuxt UI 语义边框与环线 */
-  --ui-border: #E2E8F0;
-  --ui-border-muted: #F1F5F9;
-  --ui-border-accented: #CBD5E1;
+  --ui-text-muted: var(--muted-foreground);
+  --ui-text-dimmed: #94a3b8;
+  --ui-text-inverted: var(--primary-foreground);
+  --ui-border: var(--border);
+  --ui-border-muted: var(--border-muted);
+  --ui-border-accented: #cbd5e1;
   --ui-border-inverted: #334155;
-
-  /* 焦点外发光环 */
-  --ui-ring: #3069C9;
-
-  /* 语义状态色 */
-  --ui-success: #10B981;
-  --ui-warning: #F59E0B;
-  --ui-error: #EF4444;
-  --ui-info: #3069C9;
-
-  /* 兼容旧别名 */
-  --surface: var(--ui-bg);
-  --surface-soft: var(--ui-bg-muted);
-  --surface-raised: var(--ui-bg-elevated);
-  --ink: var(--ui-text-highlighted);
+  --ui-ring: var(--ring);
+  --ui-success: var(--success);
+  --ui-warning: var(--warning);
+  --ui-error: var(--destructive);
+  --ui-info: var(--info);
+  --surface: var(--background);
+  --surface-soft: var(--surface-muted);
+  --surface-raised: var(--surface-elevated);
+  --ink: var(--foreground);
   --text: var(--ui-text);
-  --text-muted: var(--ui-text-muted);
-  --border: var(--ui-border);
-  --border-subtle: var(--ui-border-muted);
-  --ring: var(--ui-ring);
-
-  /* 精致内阴影与外阴影 */
-  --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.05);
-  --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
-  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
-  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
-  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
+  --text-muted: var(--muted-foreground);
+  --border-subtle: var(--border-muted);
 }
 
-/* Nuxt UI 语义背景与层级 (暗色模式) */
-.dark,
-[data-theme="dark"] {
-  --ui-bg: #090E17;
-  --ui-bg-muted: #0F172A;
-  --ui-bg-elevated: #1E293B;
+[data-theme='dark'] {
+  --background: #090e17;
+  --foreground: #f8fafc;
+  --card: #0f172a;
+  --card-foreground: #f8fafc;
+  --surface-muted: #0f172a;
+  --surface-elevated: #1e293b;
+  --muted: #1e293b;
+  --muted-foreground: #94a3b8;
+  --border: #1e293b;
+  --border-muted: #141e30;
+  --primary: #70acfe;
+  --primary-hover: #9bc5fe;
+  --primary-foreground: #0f172a;
+  --ring: #70acfe;
+  --success: #34d399;
+  --warning: #fbbf24;
+  --destructive: #f87171;
+  --info: #70acfe;
   --ui-bg-accented: #334155;
-  --ui-bg-inverted: #FFFFFF;
-
-  --ui-text-highlighted: #F8FAFC;
-  --ui-text: #E2E8F0;
-  --ui-text-muted: #94A3B8;
-  --ui-text-dimmed: #64748B;
-  --ui-text-inverted: #0F172A;
-
-  --ui-border: #1E293B;
-  --ui-border-muted: #141E30;
   --ui-border-accented: #334155;
-  --ui-border-inverted: #CBD5E1;
-
-  --ui-ring: #70ACFE;
-
-  /* 兼容旧别名 */
-  --surface: var(--ui-bg);
-  --surface-soft: var(--ui-bg-muted);
-  --surface-raised: var(--ui-bg-elevated);
-  --ink: var(--ui-text-highlighted);
+  --ui-border-inverted: #cbd5e1;
+  --ui-text: #e2e8f0;
+  --ui-text-dimmed: #64748b;
+  --surface: var(--background);
+  --surface-soft: var(--surface-muted);
+  --surface-raised: var(--surface-elevated);
+  --ink: var(--foreground);
   --text: var(--ui-text);
-  --text-muted: var(--ui-text-muted);
-  --border: var(--ui-border);
-  --border-subtle: var(--ui-border-muted);
-  --ring: var(--ui-ring);
-
-  --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.5);
-  --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.6), 0 1px 2px -1px rgb(0 0 0 / 0.6);
-  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.6), 0 2px 4px -2px rgb(0 0 0 / 0.6);
-  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.7), 0 4px 6px -4px rgb(0 0 0 / 0.7);
-  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.8), 0 8px 10px -6px rgb(0 0 0 / 0.8);
+  --text-muted: var(--muted-foreground);
+  --border-subtle: var(--border-muted);
+  --shadow-xs: 0 1px 2px rgb(0 0 0 / 0.45);
+  --shadow-sm: 0 2px 5px rgb(0 0 0 / 0.45);
+  --shadow-md: 0 8px 18px rgb(0 0 0 / 0.48);
+  --shadow-lg: 0 20px 38px rgb(0 0 0 / 0.55);
+  --shadow-xl: var(--shadow-lg);
 }
 
-@theme {
-  /* ReCloud 品牌字体栈：西文 Plus Jakarta Sans（需应用侧自托管 @fontsource 或等效），中文走原生 CJK 回退，代码 JetBrains Mono */
-  --font-sans: 'Plus Jakarta Sans Variable', 'Plus Jakarta Sans', 'Segoe UI', -apple-system, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Source Han Sans SC', 'Sarasa Gothic CL', 'Noto Sans CJK SC', sans-serif;
-  --font-mono: 'JetBrains Mono', 'Sarasa Mono CL', 'Maple Mono NF CN', 'Noto Sans Mono CJK SC', ui-monospace, 'DejaVu Sans Mono', monospace;
+/* Palette values only override semantics; component APIs remain stable. */
+[data-theme-palette='ocean'] { --primary: #0284c7; --primary-hover: #0369a1; --ring: #0284c7; --info: #0284c7; }
+[data-theme-palette='violet'] { --primary: #7c3aed; --primary-hover: #6d28d9; --ring: #7c3aed; --info: #7c3aed; }
+[data-theme-palette='slate'] { --primary: #334155; --primary-hover: #1e293b; --ring: #475569; --info: #475569; }
+[data-theme='dark'][data-theme-palette='ocean'] { --primary: #38bdf8; --primary-hover: #7dd3fc; --ring: #38bdf8; --info: #38bdf8; }
+[data-theme='dark'][data-theme-palette='violet'] { --primary: #a78bfa; --primary-hover: #c4b5fd; --ring: #a78bfa; --info: #a78bfa; }
+[data-theme='dark'][data-theme-palette='slate'] { --primary: #cbd5e1; --primary-hover: #e2e8f0; --ring: #cbd5e1; --info: #cbd5e1; }
+
+[data-theme-density='compact'] { --rc-control-height: 2rem; --rc-space-scale: 0.875; }
+[data-theme-density='comfortable'] { --rc-control-height: 2.5rem; --rc-space-scale: 1; }
+[data-theme-density='spacious'] { --rc-control-height: 2.75rem; --rc-space-scale: 1.125; }
+[data-theme-radius='none'] { --radius-sm: var(--rc-radius-none); --radius-md: var(--rc-radius-none); --radius-lg: var(--rc-radius-none); }
+[data-theme-radius='sm'] { --radius-sm: 0.25rem; --radius-md: var(--rc-radius-sm); --radius-lg: var(--rc-radius-md); }
+[data-theme-radius='lg'] { --radius-sm: var(--rc-radius-md); --radius-md: var(--rc-radius-lg); --radius-lg: 1rem; }
+[data-theme-shadow='none'] { --shadow-xs: none; --shadow-sm: none; --shadow-md: none; --shadow-lg: none; --shadow-xl: none; }
+[data-theme-shadow='md'] { --shadow-xs: var(--rc-shadow-md); --shadow-sm: var(--rc-shadow-md); --shadow-md: var(--rc-shadow-md); --shadow-lg: var(--rc-shadow-lg); --shadow-xl: var(--rc-shadow-lg); }
+[data-theme-shadow='lg'] { --shadow-xs: var(--rc-shadow-lg); --shadow-sm: var(--rc-shadow-lg); --shadow-md: var(--rc-shadow-lg); --shadow-lg: var(--rc-shadow-lg); --shadow-xl: var(--rc-shadow-lg); }
 
-  --color-primary-50: var(--color-primary-50);
-  --color-primary-100: var(--color-primary-100);
-  --color-primary-200: var(--color-primary-200);
-  --color-primary-300: var(--color-primary-300);
-  --color-primary-400: var(--color-primary-400);
-  --color-primary-500: var(--color-primary-500);
-  --color-primary-600: var(--color-primary-600);
-  --color-primary-700: var(--color-primary-700);
-  --color-primary-800: var(--color-primary-800);
-  --color-primary-900: var(--color-primary-900);
-  --color-primary-950: var(--color-primary-950);
-
-  --color-brand-50: var(--brand-50);
-  --color-brand-100: var(--brand-100);
-  --color-brand-200: var(--brand-200);
-  --color-brand-300: var(--brand-300);
-  --color-brand-600: var(--brand-600);
-  --color-brand-700: var(--brand-700);
-
-  --color-ui-bg: var(--ui-bg);
-  --color-ui-bg-muted: var(--ui-bg-muted);
-  --color-ui-bg-elevated: var(--ui-bg-elevated);
-  --color-ui-bg-accented: var(--ui-bg-accented);
-  --color-ui-bg-inverted: var(--ui-bg-inverted);
-
-  --color-ui-text-highlighted: var(--ui-text-highlighted);
-  --color-ui-text: var(--ui-text);
-  --color-ui-text-muted: var(--ui-text-muted);
-  --color-ui-text-dimmed: var(--ui-text-dimmed);
-  --color-ui-text-inverted: var(--ui-text-inverted);
-
-  --color-ui-border: var(--ui-border);
-  --color-ui-border-muted: var(--ui-border-muted);
-  --color-ui-border-accented: var(--ui-border-accented);
-  --color-ui-border-inverted: var(--ui-border-inverted);
-
-  --color-ui-ring: var(--ui-ring);
-  --color-ui-success: var(--ui-success);
-  --color-ui-warning: var(--ui-warning);
-  --color-ui-error: var(--ui-error);
-  --color-ui-info: var(--ui-info);
-
-  /* 兼容旧 token */
-  --color-surface: var(--surface);
-  --color-surface-soft: var(--surface-soft);
-  --color-surface-raised: var(--surface-raised);
-  --color-ink: var(--ink);
-  --color-text: var(--text);
-  --color-text-muted: var(--text-muted);
+@theme {
+  --font-sans: 'Plus Jakarta Sans Variable', 'Plus Jakarta Sans', 'Segoe UI', -apple-system, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Source Han Sans SC', 'Noto Sans CJK SC', sans-serif;
+  --font-mono: 'JetBrains Mono', 'Sarasa Mono CL', 'Maple Mono NF CN', 'Noto Sans Mono CJK SC', ui-monospace, monospace;
+  --color-primary-50: var(--rc-blue-50);
+  --color-primary-100: var(--rc-blue-100);
+  --color-primary-200: var(--rc-blue-200);
+  --color-primary-300: var(--rc-blue-300);
+  --color-primary-400: var(--rc-blue-400);
+  --color-primary-500: var(--primary);
+  --color-primary-600: var(--primary);
+  --color-primary-700: var(--primary-hover);
+  --color-ui-bg: var(--background);
+  --color-ui-bg-muted: var(--surface-muted);
+  --color-ui-bg-elevated: var(--surface-elevated);
+  --color-surface: var(--background);
+  --color-surface-soft: var(--surface-muted);
+  --color-surface-raised: var(--surface-elevated);
+  --color-ink: var(--foreground);
+  --color-text: var(--ui-text);
+  --color-text-muted: var(--muted-foreground);
   --color-border: var(--border);
-  --color-border-subtle: var(--border-subtle);
-  --color-ring: var(--ring);
-}
-
-.rc-gradient-vertical {
-  background-image: var(--brand-gradient);
-}
-
-.rc-gradient-compact {
-  background-image: var(--brand-gradient-compact);
+  --color-border-subtle: var(--border-muted);
+  --color-ui-text-highlighted: var(--foreground);
+  --color-ui-text: var(--ui-text);
+  --color-ui-text-muted: var(--muted-foreground);
+  --color-ui-border: var(--border);
+  --color-ui-ring: var(--ring);
+  --color-ui-success: var(--success);
+  --color-ui-warning: var(--warning);
+  --color-ui-error: var(--destructive);
 }
 
-.rc-gradient-card {
-  background-image: var(--brand-gradient-card);
-}
+:where(html) { font-family: var(--font-sans); }
+:where(code, kbd, pre, samp) { font-family: var(--font-mono); font-variant-numeric: tabular-nums; }
+:where(.rc-tabular-nums, table, [data-numeric]) { font-variant-numeric: tabular-nums; }
+.rc-gradient-vertical { background-image: var(--brand-gradient); }
+.rc-gradient-compact { background-image: var(--brand-gradient-compact); }
+.rc-gradient-card { background-image: var(--brand-gradient-card); }
diff --git a/packages/ui/src/utils/themeScript.ts b/packages/ui/src/utils/themeScript.ts
new file mode 100644
index 0000000..6439418
--- /dev/null
+++ b/packages/ui/src/utils/themeScript.ts
@@ -0,0 +1,10 @@
+import type { ThemePreferences } from '../composables/useTheme'
+
+/**
+ * Inline this before application markup to apply persisted theme attributes before Vue hydrates.
+ * Nuxt users receive it automatically through the module when `injectTheme` is enabled.
+ */
+export function createThemeInitScript(storageKey = 'recloud-theme', defaults: Partial<ThemePreferences> = {}): string {
+  const fallback = JSON.stringify({ mode: 'system', palette: 'recloud', density: 'comfortable', radius: 'md', shadow: 'sm', ...defaults })
+  return `(function(){try{var fallback=${fallback};var saved=JSON.parse(localStorage.getItem(${JSON.stringify(storageKey)})||'{}');var p=Object.assign({},fallback,saved);var mode=p.mode==='auto'?'system':p.mode;var dark=mode==='dark'||(mode==='system'&&matchMedia('(prefers-color-scheme: dark)').matches);var root=document.documentElement;root.classList.toggle('dark',dark);root.dataset.theme=dark?'dark':'light';root.dataset.themeMode=mode;root.dataset.themePalette=p.palette;root.dataset.themeDensity=p.density;root.dataset.themeRadius=p.radius;root.dataset.themeShadow=p.shadow}catch(e){}})();`
+}

From b3a472f3214938d1a20bb34a4d87b438d3411258 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 04:56:01 +0800
Subject: [PATCH 14/26] fix(code-block): adapt highlighting to theme

---
 .changeset/light-code-blocks-adapt.md         |  5 ++
 .../src/components/code-block/CodeBlock.vue   | 55 +++++++++++++------
 packages/ui/src/theme.css                     | 14 +++++
 3 files changed, 57 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/light-code-blocks-adapt.md

diff --git a/.changeset/light-code-blocks-adapt.md b/.changeset/light-code-blocks-adapt.md
new file mode 100644
index 0000000..75072be
--- /dev/null
+++ b/.changeset/light-code-blocks-adapt.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Match code block surfaces and syntax highlighting to the active light or dark theme.
diff --git a/packages/ui/src/components/code-block/CodeBlock.vue b/packages/ui/src/components/code-block/CodeBlock.vue
index 3b8fe28..a52f0f8 100644
--- a/packages/ui/src/components/code-block/CodeBlock.vue
+++ b/packages/ui/src/components/code-block/CodeBlock.vue
@@ -7,21 +7,21 @@
         :class="titleClasses"
         @click="toggleCollapsed"
       >
-        <svg v-if="collapsible" :class="cn('h-3.5 w-3.5 shrink-0 text-slate-400 transition-transform duration-200', !isCollapsed && 'rotate-90')" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg>
-        <span v-else class="h-2 w-2 shrink-0 rounded-full bg-blue-400 shadow-[0_0_0_3px_rgba(96,165,250,0.12)]" aria-hidden="true" />
-        <span v-if="filename" class="truncate font-mono text-xs font-medium text-slate-200">{{ filename }}</span>
-        <span v-if="language" class="font-mono text-[11px] font-semibold uppercase tracking-[0.1em] text-slate-400">{{ language }}</span>
-        <span v-if="collapsible" class="shrink-0 text-xs font-medium text-slate-400">{{ isCollapsed ? '展开代码' : '收起代码' }}</span>
+        <svg v-if="collapsible" :class="cn('h-3.5 w-3.5 shrink-0 text-[var(--code-muted)] transition-transform duration-200', !isCollapsed && 'rotate-90')" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg>
+        <span v-else class="h-2 w-2 shrink-0 rounded-full bg-[var(--code-accent)] shadow-[0_0_0_3px_rgb(59_130_246_/_0.12)]" aria-hidden="true" />
+        <span v-if="filename" class="truncate font-mono text-xs font-medium text-[var(--code-foreground)]">{{ filename }}</span>
+        <span v-if="language" class="font-mono text-[11px] font-semibold uppercase tracking-[0.1em] text-[var(--code-muted)]">{{ language }}</span>
+        <span v-if="collapsible" class="shrink-0 text-xs font-medium text-[var(--code-muted)]">{{ isCollapsed ? '展开代码' : '收起代码' }}</span>
       </component>
       <button
         v-if="copyable"
         type="button"
-        class="inline-flex shrink-0 items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium text-slate-400 transition-colors hover:bg-slate-800 hover:text-slate-100 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-400"
+        class="inline-flex shrink-0 items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium text-[var(--code-muted)] transition-colors hover:bg-[var(--code-hover)] hover:text-[var(--code-foreground)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ring)]"
         :aria-label="copied ? '代码已复制' : '复制代码'"
         @click="copyCode"
       >
         <svg v-if="!copied" class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" /><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" /></svg>
-        <svg v-else class="h-3.5 w-3.5 text-emerald-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 13 4 4L19 7" /></svg>
+        <svg v-else class="h-3.5 w-3.5 text-[var(--success)]" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 13 4 4L19 7" /></svg>
         {{ copied ? '已复制' : '复制' }}
       </button>
     </header>
@@ -37,7 +37,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, onBeforeUnmount, shallowRef, useId, watch } from 'vue'
+import { computed, onBeforeUnmount, onMounted, shallowRef, useId, watch } from 'vue'
 import { cn } from '../../utils/cn'
 
 export interface CodeBlockProps {
@@ -72,8 +72,10 @@ const bodyId = useId()
 const copied = shallowRef(false)
 /** Highlight result tagged with the source it was produced for, so stale output is never shown. */
 const highlighted = shallowRef<{ key: string; html: string } | null>(null)
+const colorTheme = shallowRef<'github-dark' | 'github-light'>(getColorTheme())
 let copyTimer: ReturnType<typeof setTimeout> | undefined
 let highlighterPromise: Promise<Awaited<ReturnType<typeof createHighlighter>>> | undefined
+let themeObserver: MutationObserver | undefined
 let highlightVersion = 0
 
 const languageAliases: Record<string, string> = {
@@ -94,12 +96,12 @@ const PRE_CLASS = 'rc-code-block-pre'
 
 const isCollapsed = computed(() => props.collapsible && collapsed.value)
 const hasHeader = computed(() => Boolean(props.filename || props.language || props.copyable || props.collapsible))
-const sourceKey = computed(() => `${props.language}\u0000${props.code}`)
+const sourceKey = computed(() => `${colorTheme.value}\u0000${props.language}\u0000${props.code}`)
 
 const headerClasses = computed(() => {
   return cn(
     'flex min-h-10 items-center justify-between gap-3 px-3.5',
-    !isCollapsed.value && 'border-b border-slate-800/80'
+    !isCollapsed.value && 'border-b border-[var(--code-border)]'
   )
 })
 
@@ -107,13 +109,13 @@ const titleClasses = computed(() => {
   return cn(
     'flex min-w-0 items-center gap-2',
     props.collapsible &&
-      '-ml-1.5 rounded-md px-1.5 py-1 text-left transition-colors hover:bg-slate-800/60 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-400'
+      '-ml-1.5 rounded-md px-1.5 py-1 text-left transition-colors hover:bg-[var(--code-hover)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ring)]'
   )
 })
 
 const codeBlockClasses = computed(() => {
   return cn(
-    'overflow-hidden rounded-xl border border-slate-800 bg-[#0b1220] shadow-sm dark:border-slate-700 dark:bg-[#080d16]',
+    'overflow-hidden rounded-xl border border-[var(--code-border)] bg-[var(--code-background)] text-[var(--code-foreground)] shadow-sm',
     props.class
   )
 })
@@ -126,14 +128,14 @@ const codeBlockClasses = computed(() => {
 const contentClasses = computed(() => {
   return cn(
     'overflow-auto',
-    '[&>pre]:m-0 [&>pre]:rounded-none [&>pre]:p-4 [&>pre]:bg-transparent! [&>pre]:text-[#e1e4e8] [&>pre]:shadow-none!',
+    '[&>pre]:m-0 [&>pre]:rounded-none [&>pre]:p-4 [&>pre]:bg-transparent! [&>pre]:text-[var(--code-foreground)] [&>pre]:shadow-none!',
     '[&>pre]:font-mono [&>pre]:text-[13px] [&>pre]:leading-6',
     '[&_code]:block [&_code]:bg-transparent [&_code]:p-0 [&_code]:[font:inherit]',
     props.wrap
       ? '[&>pre]:whitespace-pre-wrap [&>pre]:[overflow-wrap:anywhere]'
       : '[&>pre]:min-w-max [&>pre]:whitespace-pre',
     props.showLineNumbers &&
-      '[&>pre]:[counter-reset:line] [&_.line]:before:inline-block [&_.line]:before:w-6 [&_.line]:before:mr-5 [&_.line]:before:text-right [&_.line]:before:text-slate-500 [&_.line]:before:select-none [&_.line]:before:[counter-increment:line] [&_.line]:before:content-[counter(line)]'
+      '[&>pre]:[counter-reset:line] [&_.line]:before:inline-block [&_.line]:before:w-6 [&_.line]:before:mr-5 [&_.line]:before:text-right [&_.line]:before:text-[var(--code-muted)] [&_.line]:before:select-none [&_.line]:before:[counter-increment:line] [&_.line]:before:content-[counter(line)]'
   )
 })
 
@@ -152,10 +154,22 @@ function toggleCollapsed() {
   if (props.collapsible) collapsed.value = !collapsed.value
 }
 
+onMounted(() => {
+  const root = document.documentElement
+  const updateColorTheme = () => {
+    colorTheme.value = getColorTheme()
+  }
+
+  updateColorTheme()
+  themeObserver = new MutationObserver(updateColorTheme)
+  themeObserver.observe(root, { attributes: true, attributeFilter: ['data-theme'] })
+})
+
 onBeforeUnmount(() => {
   if (copyTimer !== undefined) {
     clearTimeout(copyTimer)
   }
+  themeObserver?.disconnect()
   // Invalidate any in-flight highlight so it won't write to an unmounted ref.
   highlightVersion++
 })
@@ -175,12 +189,14 @@ async function createHighlighter() {
   const [
     { createHighlighterCore },
     { createJavaScriptRegexEngine },
-    { default: theme },
+    { default: darkTheme },
+    { default: lightTheme },
     ...languages
   ] = await Promise.all([
     import('shiki/core'),
     import('shiki/engine/javascript'),
     import('shiki/dist/themes/github-dark.mjs'),
+    import('shiki/dist/themes/github-light.mjs'),
     import('shiki/dist/langs/css.mjs'),
     import('shiki/dist/langs/html.mjs'),
     import('shiki/dist/langs/javascript.mjs'),
@@ -193,7 +209,7 @@ async function createHighlighter() {
   ])
 
   return createHighlighterCore({
-    themes: [theme],
+    themes: [darkTheme, lightTheme],
     langs: languages.map(({ default: lang }) => lang),
     engine: createJavaScriptRegexEngine()
   })
@@ -225,7 +241,7 @@ watch(
       if (version !== highlightVersion) return
       const html = highlighter.codeToHtml(props.code, {
         lang: resolveLanguage(props.language, props.code),
-        theme: 'github-dark',
+        theme: colorTheme.value,
         transformers: [
           {
             pre(node) {
@@ -242,6 +258,11 @@ watch(
   { immediate: true }
 )
 
+function getColorTheme() {
+  if (typeof document === 'undefined') return 'github-light'
+  return document.documentElement.dataset.theme === 'dark' ? 'github-dark' : 'github-light'
+}
+
 function escapeHtml(value: string) {
   return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
 }
diff --git a/packages/ui/src/theme.css b/packages/ui/src/theme.css
index 1b42fb1..049e050 100644
--- a/packages/ui/src/theme.css
+++ b/packages/ui/src/theme.css
@@ -44,6 +44,13 @@
   --destructive: #dc2626;
   --destructive-foreground: #ffffff;
   --info: var(--rc-blue-600);
+  --code-background: #f8fafc;
+  --code-header: #f1f5f9;
+  --code-foreground: #334155;
+  --code-muted: #64748b;
+  --code-border: #e2e8f0;
+  --code-hover: #e2e8f0;
+  --code-accent: var(--rc-blue-500);
 
   --radius-sm: var(--rc-radius-sm);
   --radius-md: var(--rc-radius-md);
@@ -113,6 +120,13 @@
   --warning: #fbbf24;
   --destructive: #f87171;
   --info: #70acfe;
+  --code-background: #080d16;
+  --code-header: #0b1220;
+  --code-foreground: #e2e8f0;
+  --code-muted: #94a3b8;
+  --code-border: #334155;
+  --code-hover: #1e293b;
+  --code-accent: #60a5fa;
   --ui-bg-accented: #334155;
   --ui-border-accented: #334155;
   --ui-border-inverted: #cbd5e1;

From 8382379ae5ebca31f0033c05ff8ffddd6e347746 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 05:04:48 +0800
Subject: [PATCH 15/26] feat(app-shell): add responsive navigation

---
 .changeset/shell-navigation-adapts.md         |   5 +
 .../playground/pages/components/app-shell.vue | 187 +++++++++++++++---
 .../ui/src/components/app-shell/AppShell.vue  |  81 +++++++-
 .../ui/src/components/app-shell/Sidebar.vue   |  34 +++-
 4 files changed, 271 insertions(+), 36 deletions(-)
 create mode 100644 .changeset/shell-navigation-adapts.md

diff --git a/.changeset/shell-navigation-adapts.md b/.changeset/shell-navigation-adapts.md
new file mode 100644
index 0000000..316b1d3
--- /dev/null
+++ b/.changeset/shell-navigation-adapts.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add collapsible desktop sidebars, mobile menu trigger slots, and content width conventions to AppShell. Document responsive Sheet navigation and AppShell, Sidebar, and NavigationMenu responsibilities.
diff --git a/apps/playground/pages/components/app-shell.vue b/apps/playground/pages/components/app-shell.vue
index 87e7a1b..eae004c 100644
--- a/apps/playground/pages/components/app-shell.vue
+++ b/apps/playground/pages/components/app-shell.vue
@@ -1,47 +1,182 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="AppShell 应用布局" description="为开发者控制台提供稳定的侧栏、顶栏与内容区骨架；小屏下自动收起桌面侧栏。" />
-
-    <DocExample title="控制台骨架" description="AppShell 负责页面结构，Sidebar 专注可滚动的导航内容与固定底部操作。" :code="rcCode0">
-      <div class="h-[28rem] overflow-hidden rounded-xl ring-1 ring-slate-200 dark:ring-slate-800">
-        <AppShell sidebar-width="13rem">
-          <template #sidebar>
-            <Sidebar>
-              <template #header><span class="text-sm font-semibold text-slate-900 dark:text-slate-100">ReCloud Console</span></template>
-              <div class="space-y-1">
-                <a v-for="item in navItems" :key="item" href="#" class="block rounded-lg px-3 py-2 text-sm font-medium text-slate-600 hover:bg-slate-100 hover:text-slate-950 dark:text-slate-300 dark:hover:bg-slate-800 dark:hover:text-white" @click.prevent>{{ item }}</a>
-              </div>
-              <template #footer><Button class="w-full" size="sm" variant="outline" color="neutral">工作区设置</Button></template>
+    <DocPageHeader
+      title="AppShell 应用布局"
+      description="为开发者控制台提供桌面侧栏、移动端抽屉入口与受约束的内容区骨架。"
+    />
+
+    <DocExample
+      title="响应式控制台骨架"
+      description="桌面端可收起侧栏；小于 lg 时使用 mobile-menu-trigger 插槽将同一导航放入 Sheet。"
+      :code="responsiveCode"
+    >
+      <div class="h-[30rem] overflow-hidden rounded-xl ring-1 ring-[var(--border)]">
+        <AppShell
+          v-model:collapsed="collapsed"
+          sidebar-width="13rem"
+          collapsed-sidebar-width="4rem"
+          content-width="wide"
+        >
+          <template #sidebar="{ collapsed: sidebarCollapsed }">
+            <Sidebar :collapsed="sidebarCollapsed">
+              <template #header="{ collapsed: headerCollapsed }">
+                <div class="flex items-center justify-between gap-2">
+                  <span class="truncate text-sm font-semibold text-[var(--foreground)]">
+                    {{ headerCollapsed ? 'RC' : 'ReCloud Console' }}
+                  </span>
+                  <button
+                    class="hidden rounded-md p-1.5 text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)] lg:inline-flex"
+                    type="button"
+                    :aria-label="collapsed ? '展开侧边栏' : '收起侧边栏'"
+                    @click="collapsed = !collapsed"
+                  >
+                    <PanelLeftClose v-if="!collapsed" class="size-4" />
+                    <PanelLeftOpen v-else class="size-4" />
+                  </button>
+                </div>
+              </template>
+
+              <nav class="space-y-1">
+                <a
+                  v-for="item in navItems"
+                  :key="item.label"
+                  href="#"
+                  :aria-label="item.label"
+                  :title="sidebarCollapsed ? item.label : undefined"
+                  :class="[
+                    'flex items-center rounded-lg py-2 text-sm font-medium transition-colors hover:bg-[var(--muted)] hover:text-[var(--foreground)]',
+                    sidebarCollapsed ? 'justify-center px-2' : 'gap-2.5 px-3',
+                    item.active
+                      ? 'bg-[var(--muted)] text-[var(--foreground)]'
+                      : 'text-[var(--muted-foreground)]'
+                  ]"
+                  @click.prevent
+                >
+                  <component :is="item.icon" class="size-4 shrink-0" />
+                  <span v-if="!sidebarCollapsed" class="truncate">{{ item.label }}</span>
+                </a>
+              </nav>
+
+              <template #footer="{ collapsed: footerCollapsed }">
+                <Button
+                  class="w-full"
+                  size="sm"
+                  variant="outline"
+                  color="neutral"
+                  :aria-label="footerCollapsed ? '工作区设置' : undefined"
+                >
+                  <Settings class="size-4" :class="!footerCollapsed && 'mr-1.5'" />
+                  <span v-if="!footerCollapsed">工作区设置</span>
+                </Button>
+              </template>
             </Sidebar>
           </template>
-          <template #header><div class="flex h-12 items-center px-5 text-sm font-medium text-slate-700 dark:text-slate-200">Webhook 投递记录</div></template>
-          <div class="p-5"><Card title="近 24 小时投递"><p class="text-sm text-slate-500 dark:text-slate-400">这里是控制台主内容区。</p></Card></div>
+
+          <template #mobile-menu-trigger>
+            <Sheet v-model:open="mobileNavigationOpen" side="left" size="17rem" title="ReCloud Console">
+              <template #trigger>
+                <Button variant="ghost" color="neutral" size="sm" aria-label="打开导航">
+                  <Menu class="size-4" />
+                </Button>
+              </template>
+              <nav class="space-y-1">
+                <a
+                  v-for="item in navItems"
+                  :key="item.label"
+                  href="#"
+                  class="flex items-center gap-2.5 rounded-lg px-3 py-2 text-sm font-medium text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+                  @click.prevent="mobileNavigationOpen = false"
+                >
+                  <component :is="item.icon" class="size-4" />
+                  {{ item.label }}
+                </a>
+              </nav>
+            </Sheet>
+          </template>
+
+          <template #header>
+            <div class="text-sm font-medium text-[var(--foreground)]">Webhook 投递记录</div>
+          </template>
+
+          <div class="p-5">
+            <Card title="近 24 小时投递">
+              <p class="text-sm text-[var(--muted-foreground)]">内容区使用 wide 宽度约束，页面仍可按需提供自己的内边距。</p>
+            </Card>
+          </div>
         </AppShell>
       </div>
     </DocExample>
 
+    <section class="space-y-4">
+      <h2 class="text-xl font-semibold tracking-tight text-[var(--foreground)]">导航职责边界</h2>
+      <div class="grid gap-4 lg:grid-cols-3">
+        <Card title="AppShell">
+          <p class="text-sm leading-6 text-[var(--muted-foreground)]">负责应用级骨架：桌面侧栏宽度、收起状态、顶部区域、移动端菜单入口和内容宽度。不拥有路由或菜单数据。</p>
+        </Card>
+        <Card title="Sidebar">
+          <p class="text-sm leading-6 text-[var(--muted-foreground)]">负责控制台的纵向导航容器：固定头尾、可滚动主体和折叠时的呈现。将同一导航数据复用于 Sheet，避免维护两套导航来源。</p>
+        </Card>
+        <Card title="NavigationMenu">
+          <p class="text-sm leading-6 text-[var(--muted-foreground)]">负责页面内或顶栏中的水平导航与可展开面板。不要用它替代 Sidebar，也不要让同一层级的路由同时由两者渲染。</p>
+        </Card>
+      </div>
+    </section>
+
     <DocApiTable :rows="apiRows" />
     <DocPageNav name="app-shell" />
   </div>
 </template>
 
 <script setup lang="ts">
-const navItems = ['概览', 'Webhooks', '投递记录', '通知规则']
-const rcCode0 = `<AppShell sidebar-width="16rem">
-  <template #sidebar>
-    <Sidebar>
-      <template #header>ReCloud Console</template>
-      <nav><!-- navigation items --></nav>
-      <template #footer><Button>工作区设置</Button></template>
-    </Sidebar>
+import {
+  LayoutDashboard,
+  Menu,
+  PanelLeftClose,
+  PanelLeftOpen,
+  Settings,
+  Webhook
+} from '@recloudstudio/ui/icons'
+
+const collapsed = ref(false)
+const mobileNavigationOpen = ref(false)
+
+const navItems = [
+  { label: '概览', icon: LayoutDashboard, active: false },
+  { label: 'Webhooks', icon: Webhook, active: false },
+  { label: '投递记录', icon: Webhook, active: true },
+  { label: '通知规则', icon: Settings, active: false }
+]
+
+const responsiveCode = `<AppShell
+  v-model:collapsed="sidebarCollapsed"
+  sidebar-width="16rem"
+  collapsed-sidebar-width="4.5rem"
+  content-width="wide"
+>
+  <template #sidebar="{ collapsed }">
+    <Sidebar :collapsed="collapsed"><!-- desktop navigation --></Sidebar>
   </template>
+
+  <template #mobile-menu-trigger>
+    <Sheet side="left" title="Navigation">
+      <template #trigger><Button aria-label="Open navigation">Menu</Button></template>
+      <!-- render the same navigation data here -->
+    </Sheet>
+  </template>
+
   <template #header><ConsoleHeader /></template>
   <main><!-- page content --></main>
 </AppShell>`
+
 const apiRows = [
-  { name: 'AppShell sidebarWidth', type: 'string', default: "'16rem'", description: '桌面端侧栏宽度，可传任意 CSS 尺寸。' },
-  { name: 'AppShell sidebar / header / default', type: 'slot', default: '—', description: '分别为桌面侧栏、粘性顶栏与主内容区。' },
-  { name: 'Sidebar label', type: 'string', default: "'侧边导航'", description: '导航语义的无障碍标签。' },
-  { name: 'Sidebar header / default / footer', type: 'slot', default: '—', description: '固定头部、可滚动导航区与固定底部区域。' }
+  { name: 'v-model:collapsed', type: 'boolean', default: 'false', description: '桌面侧栏是否以 collapsedSidebarWidth 收起。侧栏内容通过 sidebar 插槽参数和 Sidebar collapsed prop 自行呈现精简状态。' },
+  { name: 'sidebarWidth', type: 'string', default: "'16rem'", description: '展开时的桌面侧栏宽度，可传任意 CSS 尺寸。' },
+  { name: 'collapsedSidebarWidth', type: 'string', default: "'4.5rem'", description: '收起时的桌面侧栏宽度，通常应容纳导航图标。' },
+  { name: 'contentWidth', type: "'full' | 'wide' | 'default' | 'narrow'", default: "'full'", description: '默认内容槽的最大宽度约定：full 不约束、wide 为 90rem、default 为 76rem、narrow 为 64rem。' },
+  { name: 'sidebarLabel', type: 'string', default: "'应用侧边栏'", description: '桌面侧栏 landmark 的无障碍标签。' },
+  { name: 'sidebar', type: 'slot', default: '—', description: '桌面侧栏。插槽参数为 collapsed 和 toggleCollapsed。' },
+  { name: 'mobile-menu-trigger', type: 'slot', default: '—', description: '仅在 lg 以下显示。将 Sheet trigger 放在这里，并复用与桌面 Sidebar 相同的导航数据。' },
+  { name: 'header / default', type: 'slot', default: '—', description: '粘性顶栏和主内容区。header 插槽同样接收 collapsed 与 toggleCollapsed。' },
+  { name: 'Sidebar collapsed', type: 'boolean', default: 'false', description: '传递给 Sidebar 的折叠状态；所有三个 Sidebar 插槽都可读取 collapsed 参数。' }
 ]
 </script>
diff --git a/packages/ui/src/components/app-shell/AppShell.vue b/packages/ui/src/components/app-shell/AppShell.vue
index 580f7b2..e833089 100644
--- a/packages/ui/src/components/app-shell/AppShell.vue
+++ b/packages/ui/src/components/app-shell/AppShell.vue
@@ -1,20 +1,91 @@
 <template>
-  <div :class="cn('flex min-h-dvh bg-slate-50 text-slate-800 dark:bg-[#090E17] dark:text-slate-100', props.class)" :style="{ '--app-sidebar-width': props.sidebarWidth }">
-    <aside v-if="$slots.sidebar" class="hidden w-[var(--app-sidebar-width)] shrink-0 border-r border-slate-200 bg-white dark:border-slate-800 dark:bg-[#0F172A] lg:block"><slot name="sidebar" /></aside>
+  <div
+    :class="cn('flex min-h-dvh bg-[var(--background)] text-[var(--foreground)]', props.class)"
+    :style="shellStyle"
+  >
+    <aside
+      v-if="$slots.sidebar"
+      :class="sidebarClasses"
+      :aria-label="props.sidebarLabel"
+    >
+      <slot name="sidebar" :collapsed="collapsed" :toggle-collapsed="toggleCollapsed" />
+    </aside>
+
     <div class="flex min-w-0 grow flex-col">
-      <header v-if="$slots.header" class="sticky top-0 z-30 shrink-0 border-b border-slate-200 bg-white/90 backdrop-blur-md dark:border-slate-800 dark:bg-[#090E17]/90"><slot name="header" /></header>
-      <main class="min-w-0 grow"><slot /></main>
+      <header v-if="$slots.header || $slots['mobile-menu-trigger']" :class="headerClasses">
+        <div
+          v-if="$slots['mobile-menu-trigger']"
+          class="flex shrink-0 items-center lg:hidden"
+        >
+          <slot name="mobile-menu-trigger" />
+        </div>
+        <slot name="header" :collapsed="collapsed" :toggle-collapsed="toggleCollapsed" />
+      </header>
+
+      <main class="min-w-0 grow">
+        <div :class="contentClasses"><slot /></div>
+      </main>
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue'
 import { cn } from '../../utils/cn'
 
 export interface AppShellProps {
+  /** Expanded desktop sidebar width. */
   sidebarWidth?: string
+  /** Desktop sidebar width when `v-model:collapsed` is true. */
+  collapsedSidebarWidth?: string
+  /** Accessible label for the desktop navigation landmark. */
+  sidebarLabel?: string
+  /** Constrain the default content slot without adding page-specific wrappers. */
+  contentWidth?: 'full' | 'wide' | 'default' | 'narrow'
   class?: string
 }
 
-const props = withDefaults(defineProps<AppShellProps>(), { sidebarWidth: '16rem', class: '' })
+const props = withDefaults(defineProps<AppShellProps>(), {
+  sidebarWidth: '16rem',
+  collapsedSidebarWidth: '4.5rem',
+  sidebarLabel: '应用侧边栏',
+  contentWidth: 'full',
+  class: ''
+})
+
+const collapsed = defineModel<boolean>('collapsed', { default: false })
+
+const contentWidths = {
+  full: 'none',
+  wide: '90rem',
+  default: '76rem',
+  narrow: '64rem'
+} as const
+
+const shellStyle = computed(() => ({
+  '--app-sidebar-width': collapsed.value
+    ? props.collapsedSidebarWidth
+    : props.sidebarWidth,
+  '--app-content-width': contentWidths[props.contentWidth]
+}))
+
+const sidebarClasses = computed(() => {
+  return cn(
+    'hidden w-[var(--app-sidebar-width)] shrink-0 overflow-hidden border-r border-[var(--border)] bg-[var(--card)] transition-[width] duration-200 lg:block'
+  )
+})
+
+const headerClasses = computed(() => {
+  return cn(
+    'sticky top-0 z-30 flex min-h-12 shrink-0 items-center gap-3 border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--background)_92%,transparent)] px-4 backdrop-blur-md lg:px-5'
+  )
+})
+
+const contentClasses = computed(() => {
+  return cn('mx-auto min-w-0 w-full max-w-[var(--app-content-width)]')
+})
+
+function toggleCollapsed() {
+  collapsed.value = !collapsed.value
+}
 </script>
diff --git a/packages/ui/src/components/app-shell/Sidebar.vue b/packages/ui/src/components/app-shell/Sidebar.vue
index 2438d92..25e17be 100644
--- a/packages/ui/src/components/app-shell/Sidebar.vue
+++ b/packages/ui/src/components/app-shell/Sidebar.vue
@@ -1,8 +1,26 @@
 <template>
-  <nav :aria-label="props.label" :class="cn('flex h-full flex-col', props.class)">
-    <div v-if="$slots.header" class="shrink-0 border-b border-slate-200 px-4 py-4 dark:border-slate-800"><slot name="header" /></div>
-    <div class="min-h-0 grow overflow-y-auto px-3 py-4"><slot /></div>
-    <div v-if="$slots.footer" class="shrink-0 border-t border-slate-200 px-3 py-3 dark:border-slate-800"><slot name="footer" /></div>
+  <nav
+    :aria-label="props.label"
+    :class="cn('flex h-full min-w-0 flex-col', props.class)"
+    :data-collapsed="props.collapsed || undefined"
+  >
+    <div
+      v-if="$slots.header"
+      class="shrink-0 border-b border-[var(--border)] px-4 py-4"
+    >
+      <slot name="header" :collapsed="props.collapsed" />
+    </div>
+
+    <div class="min-h-0 grow overflow-y-auto px-3 py-4">
+      <slot :collapsed="props.collapsed" />
+    </div>
+
+    <div
+      v-if="$slots.footer"
+      class="shrink-0 border-t border-[var(--border)] px-3 py-3"
+    >
+      <slot name="footer" :collapsed="props.collapsed" />
+    </div>
   </nav>
 </template>
 
@@ -11,8 +29,14 @@ import { cn } from '../../utils/cn'
 
 export interface SidebarProps {
   label?: string
+  /** Passed from AppShell to let navigation items render icon-only affordances. */
+  collapsed?: boolean
   class?: string
 }
 
-const props = withDefaults(defineProps<SidebarProps>(), { label: '侧边导航', class: '' })
+const props = withDefaults(defineProps<SidebarProps>(), {
+  label: '侧边导航',
+  collapsed: false,
+  class: ''
+})
 </script>

From cb1828a2827bcb51712daed5782c37f3656c5dc6 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 05:19:58 +0800
Subject: [PATCH 16/26] feat(tree-view): add highlight and async loading

---
 .changeset/calm-trees-highlight.md            |   5 +
 .../playground/pages/components/tree-view.vue | 331 ++++++++++++++++--
 .../ui/src/components/tree-view/TreeView.vue  | 278 ++++++++++++++-
 .../src/components/tree-view/TreeViewNode.vue | 249 ++++++++++++-
 packages/ui/src/components/tree-view/types.ts |  14 +
 5 files changed, 816 insertions(+), 61 deletions(-)
 create mode 100644 .changeset/calm-trees-highlight.md

diff --git a/.changeset/calm-trees-highlight.md b/.changeset/calm-trees-highlight.md
new file mode 100644
index 0000000..6b1b78b
--- /dev/null
+++ b/.changeset/calm-trees-highlight.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add highlight-variant customization, active selection badges, asynchronous child node loading, multi-selection mode, drag-and-drop reordering, and icon/label slots to TreeView.
diff --git a/apps/playground/pages/components/tree-view.vue b/apps/playground/pages/components/tree-view.vue
index 04ba7d6..7b79529 100644
--- a/apps/playground/pages/components/tree-view.vue
+++ b/apps/playground/pages/components/tree-view.vue
@@ -1,14 +1,139 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="TreeView 树形视图" description="用于权限继承、云资源拓扑与目录管理的层级浏览控件。" />
-    <DocExample title="资源目录" description="可通过鼠标或键盘展开节点；方向键浏览可见节点，Enter 选中当前项。" :code="rcCode0">
-      <TreeView v-model="selectedResource" v-model:expanded-ids="expandedResources" :nodes="resources" label="云资源目录" class="max-w-md" />
-      <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">当前资源：{{ selectedResource || '未选择' }}</p>
+    <DocPageHeader
+      title="TreeView 树形视图"
+      description="面向云资源拓扑、文件树及细粒度权限的多层级树控件，支持异步懒加载、多选、图标插槽、拖拽重排与清晰的选中高亮提示。"
+    />
+
+    <!-- Example 1: Async loading + Icon slots + v-model:expanded + Highlighting -->
+    <DocExample
+      title="资源拓扑与选中高亮"
+      description="使用 highlight-variant 配置选中的视觉高亮风格（subtle / solid / bar），配合状态徽标提供即时反馈。"
+      :code="asyncCode"
+    >
+      <div class="space-y-4">
+        <div class="flex flex-wrap items-center gap-2">
+          <div class="flex items-center gap-1.5 rounded-lg border border-[var(--border)] p-1 text-xs">
+            <span class="px-2 text-[var(--muted-foreground)]">高亮风格:</span>
+            <button
+              v-for="v in highlightVariants"
+              :key="v"
+              type="button"
+              :class="[
+                'rounded px-2 py-1 font-medium transition-colors',
+                activeVariant === v
+                  ? 'bg-[var(--primary)] text-[var(--primary-foreground)]'
+                  : 'text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]'
+              ]"
+              @click="activeVariant = v"
+            >
+              {{ v }}
+            </button>
+          </div>
+
+          <Button
+            size="sm"
+            variant="outline"
+            color="neutral"
+            @click="expandedResources = ['prod-cluster', 'k8s-pods']"
+          >
+            展开核心服务
+          </Button>
+          <Button
+            size="sm"
+            variant="outline"
+            color="neutral"
+            @click="expandedResources = []"
+          >
+            折叠全部
+          </Button>
+        </div>
+
+        <TreeView
+          v-model="selectedResource"
+          v-model:expanded="expandedResources"
+          :nodes="asyncNodes"
+          :highlight-variant="activeVariant"
+          :load-children="mockFetchChildren"
+          label="Kubernetes 资源拓扑"
+          class="max-w-md"
+        >
+          <template #icon="{ node }">
+            <Server v-if="node.id.includes('cluster')" class="size-4 text-[var(--rc-blue-500)]" />
+            <Boxes v-else-if="node.id.includes('pods')" class="size-4 text-[var(--rc-emerald-500)]" />
+            <Box v-else-if="node.id.includes('pod-')" class="size-4 text-[var(--muted-foreground)]" />
+            <HardDrive v-else class="size-4 text-[var(--rc-amber-500)]" />
+          </template>
+        </TreeView>
+
+        <p class="text-xs text-[var(--muted-foreground)]">
+          当前选中：<span class="font-mono font-medium text-[var(--primary)]">{{ selectedResource || '未选择' }}</span>；
+          展开节点：<span class="font-mono text-[var(--foreground)]">{{ expandedResources.join(', ') || '无' }}</span>
+        </p>
+      </div>
+    </DocExample>
+
+    <!-- Example 2: Multi-select mode -->
+    <DocExample
+      title="多选模式 (Multiple)"
+      description="开启 multiple 支持复选节点集合，通过 v-model:selected-ids 受控管理已选节点集合。"
+      :code="multiSelectCode"
+    >
+      <div class="space-y-3">
+        <TreeView
+          v-model:selected-ids="selectedPods"
+          multiple
+          highlight-variant="subtle"
+          :nodes="multiNodes"
+          :default-expanded-ids="['workloads']"
+          label="节点多选"
+          class="max-w-md"
+        />
+        <div class="flex items-center justify-between text-xs text-[var(--muted-foreground)]">
+          <span>已选节点数：{{ selectedPods.length }}</span>
+          <span class="font-mono">{{ selectedPods.join(', ') || '未选择' }}</span>
+        </div>
+      </div>
+    </DocExample>
+
+    <!-- Example 3: Drag & Drop ordering -->
+    <DocExample
+      title="拖拽排序与重排 (Draggable)"
+      description="开启 draggable 允许在树内移动节点层级或顺序；触发 @drop 事件返回拖拽源、目标与插入位置。"
+      :code="dragCode"
+    >
+      <div class="space-y-3">
+        <TreeView
+          :nodes="reorderNodes"
+          draggable
+          :default-expanded-ids="['services']"
+          label="服务执行流水线"
+          class="max-w-md"
+          @drop="onDrop"
+        />
+        <p v-if="lastDropInfo" class="rounded-md bg-[var(--muted)] p-2 text-xs font-mono text-[var(--foreground)]">
+          {{ lastDropInfo }}
+        </p>
+      </div>
     </DocExample>
-    <DocExample title="权限范围" description="勾选父节点会级联选择子节点；半选状态反映部分已授权的目录。" :code="rcCode1">
-      <TreeView v-model:checked-ids="grants" :nodes="permissions" checkable :default-expanded-ids="['project', 'production']" label="项目权限" class="max-w-md" />
-      <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">授权项：{{ grants.length }}</p>
+
+    <!-- Example 4: Permissions Cascade Checkbox -->
+    <DocExample
+      title="权限级联复选"
+      description="checkable 模式适用于细粒度访问策略分配，勾选状态自动向后代节点级联。"
+      :code="rcCode1"
+    >
+      <TreeView
+        v-model:checked-ids="grants"
+        :nodes="permissions"
+        checkable
+        :default-expanded-ids="['project', 'production']"
+        label="项目权限"
+        class="max-w-md"
+      />
+      <p class="mt-3 text-xs text-[var(--muted-foreground)]">已授权项数量：{{ grants.length }}</p>
     </DocExample>
+
     <DocApiTable :rows="apiRows" />
     <DocPageNav name="tree-view" />
   </div>
@@ -16,37 +141,185 @@
 
 <script setup lang="ts">
 import { ref } from 'vue'
-const selectedResource = ref('api')
-const expandedResources = ref(['production', 'services'])
+import { Box, Boxes, HardDrive, Server } from '@recloudstudio/ui/icons'
+import type { TreeDropEvent, TreeHighlightVariant, TreeNode } from '@recloudstudio/ui'
+
+const highlightVariants: TreeHighlightVariant[] = ['subtle', 'solid', 'bar']
+const activeVariant = ref<TreeHighlightVariant>('subtle')
+
+const selectedResource = ref('prod-cluster')
+const expandedResources = ref(['prod-cluster'])
+const selectedPods = ref(['gateway', 'auth'])
 const grants = ref(['logs-read'])
-const resources = [
-  { id: 'production', label: '生产环境', children: [
-    { id: 'services', label: '服务', children: [{ id: 'api', label: 'gateway-api' }, { id: 'worker', label: 'event-worker' }] },
-    { id: 'storage', label: '对象存储' }
-  ] },
-  { id: 'staging', label: '预发布环境', children: [{ id: 'preview', label: 'preview-api' }] }
+const lastDropInfo = ref('')
+
+const asyncNodes = ref<TreeNode[]>([
+  {
+    id: 'prod-cluster',
+    label: 'hk-prod-01 (集群)',
+    children: [
+      { id: 'k8s-pods', label: 'Pods', isLeaf: false },
+      { id: 'storage-pvc', label: '持久卷 (PVC)', isLeaf: false }
+    ]
+  },
+  {
+    id: 'sg-cluster',
+    label: 'sg-edge-02 (边缘节点)',
+    isLeaf: false
+  }
+])
+
+async function mockFetchChildren(node: TreeNode): Promise<TreeNode[]> {
+  await new Promise((resolve) => setTimeout(resolve, 800))
+  if (node.id === 'k8s-pods') {
+    return [
+      { id: 'pod-api-1', label: 'ingress-gateway-6f98d' },
+      { id: 'pod-api-2', label: 'ingress-gateway-9bd32' },
+      { id: 'pod-worker', label: 'async-worker-74f4b' }
+    ]
+  }
+  if (node.id === 'storage-pvc') {
+    return [
+      { id: 'pvc-data', label: 'redis-stateful-volume' },
+      { id: 'pvc-logs', label: 'system-audit-log-disk' }
+    ]
+  }
+  return [
+    { id: `${node.id}-sub`, label: `${node.label} 子服务` }
+  ]
+}
+
+const multiNodes: TreeNode[] = [
+  {
+    id: 'workloads',
+    label: '工作负载',
+    children: [
+      { id: 'gateway', label: 'API 网关服务' },
+      { id: 'auth', label: '统一鉴权中心' },
+      { id: 'payment', label: '支付网关核心' },
+      { id: 'notification', label: '消息投递中心' }
+    ]
+  }
 ]
-const permissions = [{ id: 'project', label: 'recloud-console', children: [{ id: 'production', label: '生产环境', children: [{ id: 'logs-read', label: '查看日志' }, { id: 'deploy', label: '部署服务' }] }, { id: 'billing', label: '账单管理', disabled: true }] }]
-const rcCode0 = `<TreeView
+
+const reorderNodes = ref<TreeNode[]>([
+  {
+    id: 'services',
+    label: '部署步骤',
+    children: [
+      { id: 'step-lint', label: '1. 代码规约检查' },
+      { id: 'step-build', label: '2. 镜像构建与缓存' },
+      { id: 'step-deploy', label: '3. 金丝雀灰度发布' },
+      { id: 'step-verify', label: '4. 存活探针健康校验' }
+    ]
+  }
+])
+
+function onDrop(event: TreeDropEvent) {
+  lastDropInfo.value = `拖拽 [${event.draggedNode.label}] 到 [${event.targetNode.label}] (${event.position})`
+
+  function remove(list: TreeNode[]): TreeNode | null {
+    for (let i = 0; i < list.length; i++) {
+      if (list[i].id === event.draggedNode.id) {
+        return list.splice(i, 1)[0]
+      }
+      if (list[i].children) {
+        const found = remove(list[i].children!)
+        if (found) return found
+      }
+    }
+    return null
+  }
+
+  const removed = remove(reorderNodes.value)
+  if (!removed) return
+
+  function insert(list: TreeNode[]): boolean {
+    for (let i = 0; i < list.length; i++) {
+      if (list[i].id === event.targetNode.id) {
+        if (event.position === 'before') {
+          list.splice(i, 0, removed)
+        } else if (event.position === 'after') {
+          list.splice(i + 1, 0, removed)
+        } else {
+          list[i].children = list[i].children || []
+          list[i].children!.push(removed)
+        }
+        return true
+      }
+      if (list[i].children && insert(list[i].children!)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  insert(reorderNodes.value)
+}
+
+const permissions = [
+  {
+    id: 'project',
+    label: 'recloud-console',
+    children: [
+      {
+        id: 'production',
+        label: '生产环境',
+        children: [
+          { id: 'logs-read', label: '查看审计日志' },
+          { id: 'deploy', label: '发布与回滚服务' }
+        ]
+      },
+      { id: 'billing', label: '企业账单', disabled: true }
+    ]
+  }
+]
+
+const asyncCode = `<TreeView
   v-model="selectedResource"
-  v-model:expanded-ids="expandedResources"
-  :nodes="resources"
-  label="云资源目录"
+  v-model:expanded="expandedResources"
+  highlight-variant="subtle"
+  :nodes="asyncNodes"
+  :load-children="fetchChildren"
+>
+  <template #icon="{ node }">
+    <ServerIcon v-if="node.id.includes('cluster')" />
+  </template>
+</TreeView>`
+
+const multiSelectCode = `<TreeView
+  v-model:selected-ids="selectedPods"
+  multiple
+  highlight-variant="subtle"
+  :nodes="nodes"
+/>`
+
+const dragCode = `<TreeView
+  :nodes="nodes"
+  draggable
+  @drop="handleDrop"
 />`
+
 const rcCode1 = `<TreeView
   v-model:checked-ids="grants"
   :nodes="permissions"
-  :default-expanded-ids="['project', 'production']"
   checkable
-  label="项目权限"
+  :default-expanded-ids="['project', 'production']"
 />`
+
 const apiRows = [
-  { name: 'nodes', type: 'TreeNode[]', default: '—', description: '节点数据，节点包含 id、label、children? 和 disabled?。' },
-  { name: 'v-model', type: 'string', default: '—', description: '当前选中节点的 id。' },
-  { name: 'v-model:expanded-ids', type: 'string[]', default: '—', description: '受控的展开节点集合。' },
-  { name: 'default-expanded-ids', type: 'string[]', default: '[]', description: '非受控模式下的初始展开节点。' },
-  { name: 'checkable / v-model:checked-ids', type: 'boolean / string[]', default: 'false / []', description: '启用勾选并受控管理已授权节点。' },
-  { name: 'cascade', type: 'boolean', default: 'true', description: '勾选父节点时是否级联子节点。' },
-  { name: 'select / toggle / check', type: 'event', default: '—', description: '节点选中、展开与勾选变化事件。' }
+  { name: 'nodes', type: 'TreeNode[]', default: '—', description: '树节点列表，支持 id、label、children、disabled、isLeaf、icon。' },
+  { name: 'v-model', type: 'string', default: '—', description: '单选模式下当前选中节点的 id。' },
+  { name: 'multiple', type: 'boolean', default: 'false', description: '是否启用多选模式。' },
+  { name: 'v-model:selected-ids', type: 'string[]', default: '[]', description: '多选模式下受控的已选节点 ID 列表。' },
+  { name: 'v-model:expanded', type: 'string[]', default: '—', description: '受控的展开节点 ID 列表（同时兼容 v-model:expanded-ids）。' },
+  { name: 'default-expanded-ids', type: 'string[]', default: '[]', description: '非受控模式下的默认展开集合。' },
+  { name: 'highlight-variant', type: "'subtle' | 'solid' | 'bar'", default: "'subtle'", description: '选中的高亮样式变体：subtle 为柔和浅底色与边框环、solid 为强对比主题填充、bar 为左侧重点竖条与弱底色。' },
+  { name: 'load-children', type: '(node: TreeNode) => Promise<TreeNode[] | void>', default: '—', description: '异步拉取子节点的方法。设置 isLeaf: false 时展开会触发 loading 动效并调用该回调。' },
+  { name: 'draggable', type: 'boolean', default: 'false', description: '启用 HTML5 拖拽重排与层级调整。' },
+  { name: 'checkable / v-model:checked-ids', type: 'boolean / string[]', default: 'false / []', description: '启用复选框并受控绑定勾选项。' },
+  { name: 'cascade', type: 'boolean', default: 'true', description: '勾选父节点时是否自动级联子节点。' },
+  { name: '#icon / #label', type: 'slot', default: '—', description: '自定义节点前缀图标与文本标签的插槽，接收 { node, expanded, selected }。' },
+  { name: 'drop', type: 'event (TreeDropEvent)', default: '—', description: '拖拽落点事件，包含 draggedNode、targetNode 与 position (before | inside | after)。' }
 ]
 </script>
diff --git a/packages/ui/src/components/tree-view/TreeView.vue b/packages/ui/src/components/tree-view/TreeView.vue
index ce43c37..e0dc535 100644
--- a/packages/ui/src/components/tree-view/TreeView.vue
+++ b/packages/ui/src/components/tree-view/TreeView.vue
@@ -1,6 +1,36 @@
 <template>
-  <ul role="tree" :aria-label="props.label" :class="cn('space-y-0.5 rounded-xl bg-white p-2 ring-1 ring-inset ring-slate-200 dark:bg-[#0F172A] dark:ring-slate-800', props.class)">
-    <TreeViewNode v-for="node in props.nodes" :key="node.id" :node="node" :level="1" :expanded-ids="expandedIds" :selected-id="props.modelValue" :checked-ids="props.checkedIds" :checkable="props.checkable" @toggle="toggle" @select="select" @check="toggleChecked" @navigate="navigate" />
+  <ul
+    role="tree"
+    :aria-label="props.label"
+    :aria-multiselectable="props.multiple || undefined"
+    :class="cn('space-y-0.5 rounded-xl bg-[var(--card)] p-2 ring-1 ring-[var(--border)]', props.class)"
+  >
+    <TreeViewNode
+      v-for="node in props.nodes"
+      :key="node.id"
+      :node="node"
+      :level="1"
+      :expanded-ids="effectiveExpandedIds"
+      :selected-ids="effectiveSelectedIds"
+      :checked-ids="props.checkedIds"
+      :checkable="props.checkable"
+      :draggable="props.draggable"
+      :loading-ids="loadingIds"
+      :highlight-variant="props.highlightVariant"
+      @toggle="toggle"
+      @select="select"
+      @check="toggleChecked"
+      @navigate="navigate"
+      @node-drag-start="handleDragStart"
+      @node-drop="handleDrop"
+    >
+      <template #icon="slotProps">
+        <slot name="icon" v-bind="slotProps" />
+      </template>
+      <template #label="slotProps">
+        <slot name="label" v-bind="slotProps" />
+      </template>
+    </TreeViewNode>
   </ul>
 </template>
 
@@ -8,30 +38,246 @@
 import { computed, ref, watch } from 'vue'
 import { cn } from '../../utils/cn'
 import TreeViewNode from './TreeViewNode.vue'
-import type { TreeNode } from './types'
+import type { TreeDropEvent, TreeHighlightVariant, TreeNode } from './types'
 
 export interface TreeViewProps {
   nodes: TreeNode[]
+  /** Single selection mode value. When `multiple` is true, use `selectedIds` instead. */
   modelValue?: string
+  /** Multi-select mode enabled. */
+  multiple?: boolean
+  /** Selected node IDs for multi-select mode. */
+  selectedIds?: string[]
+  /** Controlled expanded node IDs (alias v-model:expandedIds). */
   expandedIds?: string[]
+  /** Controlled expanded node IDs (v-model:expanded). */
+  expanded?: string[]
   defaultExpandedIds?: string[]
   checkedIds?: string[]
   checkable?: boolean
   cascade?: boolean
+  /** Enable HTML5 drag-and-drop reordering between nodes. */
+  draggable?: boolean
+  /** Visual highlight appearance for selected nodes: subtle, solid, or bar. */
+  highlightVariant?: TreeHighlightVariant
+  /** Asynchronous loader for fetching dynamic children when expanding an unloaded branch. */
+  loadChildren?: (node: TreeNode) => Promise<TreeNode[] | void>
   label?: string
   class?: string
 }
-const props = withDefaults(defineProps<TreeViewProps>(), { modelValue: undefined, expandedIds: undefined, defaultExpandedIds: () => [], checkedIds: () => [], checkable: false, cascade: true, label: '树形目录', class: '' })
-const emit = defineEmits<{ (event: 'update:modelValue', value: string): void; (event: 'update:expandedIds', value: string[]): void; (event: 'update:checkedIds', value: string[]): void; (event: 'select', node: TreeNode): void; (event: 'toggle', node: TreeNode): void; (event: 'check', payload: { node: TreeNode; checked: boolean }): void }>()
-const internalExpanded = ref([...props.defaultExpandedIds])
-const isControlledExpanded = computed(() => props.expandedIds !== undefined)
-const expandedIds = computed(() => isControlledExpanded.value ? props.expandedIds! : internalExpanded.value)
-const visibleNodes = computed(() => { const list: TreeNode[] = []; const visit = (nodes: TreeNode[]) => nodes.forEach((node) => { list.push(node); if (node.children?.length && expandedIds.value.includes(node.id)) visit(node.children) }); visit(props.nodes); return list })
-watch(() => props.defaultExpandedIds, (value) => { if (!isControlledExpanded.value) internalExpanded.value = [...value] })
-function toggle(id: string) { const node = findNode(id); if (!node || node.disabled) return; const next = expandedIds.value.includes(id) ? expandedIds.value.filter((value) => value !== id) : [...expandedIds.value, id]; if (!isControlledExpanded.value) internalExpanded.value = next; emit('update:expandedIds', next); emit('toggle', node) }
-function select(id: string) { const node = findNode(id); if (!node || node.disabled) return; emit('update:modelValue', id); emit('select', node) }
-function toggleChecked(node: TreeNode) { if (node.disabled) return; const affected = props.cascade ? [node.id, ...descendants(node)] : [node.id]; const allChecked = affected.every((id) => props.checkedIds.includes(id)); const next = allChecked ? props.checkedIds.filter((id) => !affected.includes(id)) : [...new Set([...props.checkedIds, ...affected])]; emit('update:checkedIds', next); emit('check', { node, checked: !allChecked }) }
-function descendants(node: TreeNode): string[] { const ids: string[] = []; node.children?.forEach((child) => { ids.push(child.id, ...descendants(child)) }); return ids }
-function findNode(id: string): TreeNode | undefined { const visit = (nodes: TreeNode[]): TreeNode | undefined => { for (const node of nodes) { if (node.id === id) return node; const match = node.children && visit(node.children); if (match) return match } }; return visit(props.nodes) }
-function navigate({ event, node }: { event: KeyboardEvent; node: TreeNode }) { const index = visibleNodes.value.findIndex((entry) => entry.id === node.id); if (event.key === 'ArrowRight' && node.children?.length && !expandedIds.value.includes(node.id)) { event.preventDefault(); toggle(node.id); return } if (event.key === 'ArrowLeft' && expandedIds.value.includes(node.id)) { event.preventDefault(); toggle(node.id); return } const target = event.key === 'ArrowDown' ? visibleNodes.value[index + 1] : event.key === 'ArrowUp' ? visibleNodes.value[index - 1] : event.key === 'Home' ? visibleNodes.value[0] : event.key === 'End' ? visibleNodes.value.at(-1) : undefined; if (target) { event.preventDefault(); document.getElementById(`tree-item-${target.id}`)?.focus() } else if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); select(node.id) } }
+
+const props = withDefaults(defineProps<TreeViewProps>(), {
+  modelValue: undefined,
+  multiple: false,
+  selectedIds: undefined,
+  expandedIds: undefined,
+  expanded: undefined,
+  defaultExpandedIds: () => [],
+  checkedIds: () => [],
+  checkable: false,
+  cascade: true,
+  draggable: false,
+  highlightVariant: 'subtle',
+  loadChildren: undefined,
+  label: '树形目录',
+  class: ''
+})
+
+const emit = defineEmits<{
+  (event: 'update:modelValue', value: string): void
+  (event: 'update:selectedIds', values: string[]): void
+  (event: 'update:expandedIds', values: string[]): void
+  (event: 'update:expanded', values: string[]): void
+  (event: 'update:checkedIds', values: string[]): void
+  (event: 'select', node: TreeNode): void
+  (event: 'toggle', node: TreeNode): void
+  (event: 'check', payload: { node: TreeNode; checked: boolean }): void
+  (event: 'drop', payload: TreeDropEvent): void
+}>()
+
+const internalExpanded = ref<string[]>([...props.defaultExpandedIds])
+const internalSelectedIds = ref<string[]>([])
+const loadingIds = ref<string[]>([])
+
+const isControlledExpanded = computed(() => {
+  return props.expanded !== undefined || props.expandedIds !== undefined
+})
+
+const effectiveExpandedIds = computed<string[]>(() => {
+  if (props.expanded !== undefined) return props.expanded
+  if (props.expandedIds !== undefined) return props.expandedIds
+  return internalExpanded.value
+})
+
+const effectiveSelectedIds = computed<string[]>(() => {
+  if (props.multiple) {
+    return props.selectedIds !== undefined ? props.selectedIds : internalSelectedIds.value
+  }
+  return props.modelValue !== undefined ? [props.modelValue] : []
+})
+
+const visibleNodes = computed(() => {
+  const list: TreeNode[] = []
+  const visit = (nodes: TreeNode[]) => {
+    nodes.forEach((node) => {
+      list.push(node)
+      if (node.children?.length && effectiveExpandedIds.value.includes(node.id)) {
+        visit(node.children)
+      }
+    })
+  }
+  visit(props.nodes)
+  return list
+})
+
+watch(
+  () => props.defaultExpandedIds,
+  (value) => {
+    if (!isControlledExpanded.value) {
+      internalExpanded.value = [...value]
+    }
+  }
+)
+
+async function toggle(id: string) {
+  const node = findNode(id)
+  if (!node || node.disabled) return
+
+  const isExpanding = !effectiveExpandedIds.value.includes(id)
+
+  if (isExpanding && props.loadChildren && (!node.children || node.children.length === 0) && node.isLeaf === false) {
+    if (!loadingIds.value.includes(id)) {
+      loadingIds.value.push(id)
+      try {
+        const loaded = await props.loadChildren(node)
+        if (Array.isArray(loaded)) {
+          node.children = loaded
+        }
+      } finally {
+        loadingIds.value = loadingIds.value.filter((loadingId) => loadingId !== id)
+      }
+    }
+  }
+
+  const next = isExpanding
+    ? [...effectiveExpandedIds.value, id]
+    : effectiveExpandedIds.value.filter((value) => value !== id)
+
+  if (!isControlledExpanded.value) {
+    internalExpanded.value = next
+  }
+
+  emit('update:expandedIds', next)
+  emit('update:expanded', next)
+  emit('toggle', node)
+}
+
+function select(id: string) {
+  const node = findNode(id)
+  if (!node || node.disabled) return
+
+  if (props.multiple) {
+    const current = effectiveSelectedIds.value
+    const next = current.includes(id)
+      ? current.filter((item) => item !== id)
+      : [...current, id]
+    if (props.selectedIds === undefined) {
+      internalSelectedIds.value = next
+    }
+    emit('update:selectedIds', next)
+  } else {
+    emit('update:modelValue', id)
+  }
+
+  emit('select', node)
+}
+
+function toggleChecked(node: TreeNode) {
+  if (node.disabled) return
+  const affected = props.cascade ? [node.id, ...descendants(node)] : [node.id]
+  const allChecked = affected.every((id) => props.checkedIds.includes(id))
+  const next = allChecked
+    ? props.checkedIds.filter((id) => !affected.includes(id))
+    : [...new Set([...props.checkedIds, ...affected])]
+
+  emit('update:checkedIds', next)
+  emit('check', { node, checked: !allChecked })
+}
+
+function descendants(node: TreeNode): string[] {
+  const ids: string[] = []
+  node.children?.forEach((child) => {
+    ids.push(child.id, ...descendants(child))
+  })
+  return ids
+}
+
+function findNode(id: string): TreeNode | undefined {
+  const visit = (nodes: TreeNode[]): TreeNode | undefined => {
+    for (const node of nodes) {
+      if (node.id === id) return node
+      const match = node.children && visit(node.children)
+      if (match) return match
+    }
+  }
+  return visit(props.nodes)
+}
+
+function navigate({ event, node }: { event: KeyboardEvent; node: TreeNode }) {
+  const index = visibleNodes.value.findIndex((entry) => entry.id === node.id)
+  const isBranch = (node.children && node.children.length > 0) || node.isLeaf === false
+
+  if (event.key === 'ArrowRight' && isBranch && !effectiveExpandedIds.value.includes(node.id)) {
+    event.preventDefault()
+    toggle(node.id)
+    return
+  }
+
+  if (event.key === 'ArrowLeft' && effectiveExpandedIds.value.includes(node.id)) {
+    event.preventDefault()
+    toggle(node.id)
+    return
+  }
+
+  const target =
+    event.key === 'ArrowDown'
+      ? visibleNodes.value[index + 1]
+      : event.key === 'ArrowUp'
+        ? visibleNodes.value[index - 1]
+        : event.key === 'Home'
+          ? visibleNodes.value[0]
+          : event.key === 'End'
+            ? visibleNodes.value.at(-1)
+            : undefined
+
+  if (target) {
+    event.preventDefault()
+    document.getElementById(`tree-item-${target.id}`)?.focus()
+  } else if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    select(node.id)
+  }
+}
+
+let activeDraggedId: string | null = null
+
+function handleDragStart(node: TreeNode) {
+  activeDraggedId = node.id
+}
+
+function handleDrop(payload: { targetNode: TreeNode; position: 'before' | 'inside' | 'after' }) {
+  if (!activeDraggedId) return
+  const dragged = findNode(activeDraggedId)
+  if (!dragged || dragged.id === payload.targetNode.id) return
+
+  // Prevent dragging a parent into its own descendants
+  if (descendants(dragged).includes(payload.targetNode.id)) return
+
+  emit('drop', {
+    draggedNode: dragged,
+    targetNode: payload.targetNode,
+    position: payload.position
+  })
+  activeDraggedId = null
+}
 </script>
diff --git a/packages/ui/src/components/tree-view/TreeViewNode.vue b/packages/ui/src/components/tree-view/TreeViewNode.vue
index b64db34..80561f4 100644
--- a/packages/ui/src/components/tree-view/TreeViewNode.vue
+++ b/packages/ui/src/components/tree-view/TreeViewNode.vue
@@ -1,40 +1,257 @@
 <template>
-  <li role="none">
+  <li
+    role="none"
+    class="relative"
+    @dragover.prevent="onDragOver"
+    @dragleave="onDragLeave"
+    @drop.prevent="onDrop"
+  >
     <div
       :id="`tree-item-${node.id}`"
       role="treeitem"
       :aria-level="level"
-      :aria-expanded="hasChildren ? expanded : undefined"
+      :aria-expanded="isBranch ? expanded : undefined"
       :aria-selected="selected"
       :aria-disabled="node.disabled || undefined"
       :aria-checked="checkable ? (checkState === 'partial' ? 'mixed' : checkState === 'checked') : undefined"
-      :class="cn('group flex min-h-8 items-center gap-1 rounded-md pr-2 text-sm outline-none transition-colors', selected ? 'bg-blue-50 text-[#1E63CE] dark:bg-blue-950/50 dark:text-[#70ACFE]' : 'text-slate-700 hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-800', node.disabled && 'pointer-events-none opacity-45')"
+      :draggable="draggable && !node.disabled"
+      :class="nodeClasses"
       :style="{ paddingLeft: `${(level - 1) * 1.25 + 0.375}rem` }"
       tabindex="0"
       @click="selectNode"
       @keydown="onKeydown"
+      @dragstart="onDragStart"
     >
-      <button v-if="hasChildren" type="button" class="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded text-slate-400 hover:bg-slate-200 hover:text-slate-700 dark:hover:bg-slate-700 dark:hover:text-slate-200" :aria-label="expanded ? `收起 ${node.label}` : `展开 ${node.label}`" @click.stop="emit('toggle', node.id)"><svg :class="cn('h-3.5 w-3.5 transition-transform', expanded && 'rotate-90')" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="m9 18 6-6-6-6" /></svg></button><span v-else class="w-6 shrink-0" />
-      <input v-if="checkable" type="checkbox" :checked="checkState === 'checked'" :indeterminate="checkState === 'partial'" :aria-label="`选择 ${node.label}`" class="h-4 w-4 shrink-0 accent-[#2563EB]" @click.stop @change="emit('check', node)" />
-      <span class="truncate">{{ node.label }}</span>
+      <!-- Visual accent bar when highlight-variant is 'bar' -->
+      <span
+        v-if="highlightVariant === 'bar' && selected"
+        class="absolute top-1 bottom-1 left-0.5 w-1 rounded-full bg-[var(--primary)]"
+        aria-hidden="true"
+      />
+
+      <!-- Expand / Collapse chevron or Loading spinner -->
+      <button
+        v-if="isBranch"
+        type="button"
+        class="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+        :aria-label="expanded ? `收起 ${node.label}` : `展开 ${node.label}`"
+        @click.stop="emit('toggle', node.id)"
+      >
+        <svg
+          v-if="isLoading"
+          class="h-3.5 w-3.5 animate-spin"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+        >
+          <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+        </svg>
+        <svg
+          v-else
+          :class="cn('h-3.5 w-3.5 transition-transform duration-150', expanded && 'rotate-90')"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+        >
+          <path stroke-linecap="round" stroke-linejoin="round" d="m9 18 6-6-6-6" />
+        </svg>
+      </button>
+      <span v-else class="w-6 shrink-0" />
+
+      <!-- Checkbox -->
+      <input
+        v-if="checkable"
+        type="checkbox"
+        :checked="checkState === 'checked'"
+        :indeterminate="checkState === 'partial'"
+        :aria-label="`选择 ${node.label}`"
+        class="h-4 w-4 shrink-0 rounded accent-[var(--primary)]"
+        @click.stop
+        @change="emit('check', node)"
+      >
+
+      <!-- Icon slot / default icon -->
+      <div v-if="$slots.icon || node.icon" class="flex shrink-0 items-center text-[var(--muted-foreground)]">
+        <slot name="icon" :node="node" :expanded="expanded" :selected="selected">
+          <component :is="node.icon" class="size-4" />
+        </slot>
+      </div>
+
+      <!-- Label slot / default label -->
+      <div class="min-w-0 grow truncate">
+        <slot name="label" :node="node" :expanded="expanded" :selected="selected">
+          <span>{{ node.label }}</span>
+        </slot>
+      </div>
+
+      <!-- Active selection badge/indicator -->
+      <span
+        v-if="selected"
+        class="ml-auto inline-flex shrink-0 items-center rounded-full bg-[var(--primary)]/10 px-1.5 py-0.5 text-[10px] font-semibold text-[var(--primary)] ring-1 ring-[var(--primary)]/20"
+        aria-hidden="true"
+      >
+        已选
+      </span>
     </div>
-    <ul v-if="hasChildren && expanded" role="group"><TreeViewNode v-for="child in node.children" :key="child.id" :node="child" :level="level + 1" :expanded-ids="expandedIds" :selected-id="selectedId" :checked-ids="checkedIds" :checkable="checkable" @toggle="emit('toggle', $event)" @select="emit('select', $event)" @check="emit('check', $event)" @navigate="emit('navigate', $event)" /></ul>
+
+    <!-- Drop indicator lines -->
+    <div
+      v-if="dropPosition === 'before'"
+      class="pointer-events-none absolute top-0 right-0 left-0 h-0.5 bg-[var(--primary)]"
+    />
+    <div
+      v-if="dropPosition === 'after'"
+      class="pointer-events-none absolute right-0 bottom-0 left-0 h-0.5 bg-[var(--primary)]"
+    />
+
+    <!-- Children branch -->
+    <ul v-if="hasChildren && expanded" role="group">
+      <TreeViewNode
+        v-for="child in node.children"
+        :key="child.id"
+        :node="child"
+        :level="level + 1"
+        :expanded-ids="expandedIds"
+        :selected-ids="selectedIds"
+        :checked-ids="checkedIds"
+        :checkable="checkable"
+        :draggable="draggable"
+        :loading-ids="loadingIds"
+        :highlight-variant="highlightVariant"
+        @toggle="emit('toggle', $event)"
+        @select="emit('select', $event)"
+        @check="emit('check', $event)"
+        @navigate="emit('navigate', $event)"
+        @node-drag-start="emit('node-drag-start', $event)"
+        @node-drop="emit('node-drop', $event)"
+      >
+        <template #icon="slotProps: any">
+          <slot name="icon" v-bind="slotProps" />
+        </template>
+        <template #label="slotProps: any">
+          <slot name="label" v-bind="slotProps" />
+        </template>
+      </TreeViewNode>
+    </ul>
   </li>
 </template>
 
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, ref } from 'vue'
 import { cn } from '../../utils/cn'
-import type { TreeNode } from './types'
+import type { TreeHighlightVariant, TreeNode } from './types'
 
 defineOptions({ name: 'TreeViewNode' })
-const props = defineProps<{ node: TreeNode; level: number; expandedIds: string[]; selectedId?: string; checkedIds: string[]; checkable: boolean }>()
-const emit = defineEmits<{ (event: 'toggle', id: string): void; (event: 'select', id: string): void; (event: 'check', node: TreeNode): void; (event: 'navigate', payload: { event: KeyboardEvent; node: TreeNode }): void }>()
+
+const props = defineProps<{
+  node: TreeNode
+  level: number
+  expandedIds: string[]
+  selectedIds: string[]
+  checkedIds: string[]
+  checkable: boolean
+  draggable: boolean
+  loadingIds: string[]
+  highlightVariant: TreeHighlightVariant
+}>()
+
+const emit = defineEmits<{
+  (event: 'toggle', id: string): void
+  (event: 'select', id: string): void
+  (event: 'check', node: TreeNode): void
+  (event: 'navigate', payload: { event: KeyboardEvent; node: TreeNode }): void
+  (event: 'node-drag-start', node: TreeNode): void
+  (event: 'node-drop', payload: { targetNode: TreeNode; position: 'before' | 'inside' | 'after' }): void
+}>()
+
+const dropPosition = ref<'before' | 'inside' | 'after' | null>(null)
+
 const hasChildren = computed(() => Boolean(props.node.children?.length))
+const isBranch = computed(() => hasChildren.value || props.node.isLeaf === false)
 const expanded = computed(() => props.expandedIds.includes(props.node.id))
-const selected = computed(() => props.selectedId === props.node.id)
-const descendantIds = computed(() => { const ids: string[] = []; const visit = (entry: TreeNode) => entry.children?.forEach((child) => { ids.push(child.id); visit(child) }); visit(props.node); return ids })
-const checkState = computed(() => { const ids = [props.node.id, ...descendantIds.value]; const count = ids.filter((id) => props.checkedIds.includes(id)).length; return count === 0 ? 'unchecked' : count === ids.length ? 'checked' : 'partial' })
-function selectNode() { if (!props.node.disabled) emit('select', props.node.id) }
-function onKeydown(event: KeyboardEvent) { if (!props.node.disabled) emit('navigate', { event, node: props.node }) }
+const selected = computed(() => props.selectedIds.includes(props.node.id))
+const isLoading = computed(() => props.loadingIds.includes(props.node.id))
+
+const descendantIds = computed(() => {
+  const ids: string[] = []
+  const visit = (entry: TreeNode) => {
+    entry.children?.forEach((child) => {
+      ids.push(child.id)
+      visit(child)
+    })
+  }
+  visit(props.node)
+  return ids
+})
+
+const checkState = computed(() => {
+  const ids = [props.node.id, ...descendantIds.value]
+  const count = ids.filter((id) => props.checkedIds.includes(id)).length
+  return count === 0 ? 'unchecked' : count === ids.length ? 'checked' : 'partial'
+})
+
+const nodeClasses = computed(() => {
+  const highlightStyles = {
+    subtle: selected.value
+      ? 'bg-[var(--rc-blue-50)] text-[var(--rc-blue-700)] ring-1 ring-[var(--rc-blue-200)] font-medium dark:bg-[var(--rc-blue-950)]/50 dark:text-[var(--rc-blue-300)] dark:ring-[var(--rc-blue-800)]'
+      : 'text-[var(--foreground)] hover:bg-[var(--muted)]',
+    solid: selected.value
+      ? 'bg-[var(--primary)] text-[var(--primary-foreground)] font-semibold shadow-xs [&_button]:text-[var(--primary-foreground)] [&_svg]:text-[var(--primary-foreground)] [&_span]:text-[var(--primary-foreground)]'
+      : 'text-[var(--foreground)] hover:bg-[var(--muted)]',
+    bar: selected.value
+      ? 'bg-[var(--muted)] text-[var(--primary)] font-semibold pl-2 dark:bg-[var(--muted)]'
+      : 'text-[var(--foreground)] hover:bg-[var(--muted)]'
+  }[props.highlightVariant]
+
+  return cn(
+    'relative group flex min-h-8 items-center gap-2 rounded-md pr-2 text-sm outline-none transition-all select-none',
+    highlightStyles,
+    dropPosition.value === 'inside' && 'ring-2 ring-inset ring-[var(--primary)] bg-[var(--muted)]',
+    props.node.disabled && 'pointer-events-none opacity-45'
+  )
+})
+
+function selectNode() {
+  if (!props.node.disabled) emit('select', props.node.id)
+}
+
+function onKeydown(event: KeyboardEvent) {
+  if (!props.node.disabled) emit('navigate', { event, node: props.node })
+}
+
+function onDragStart(event: DragEvent) {
+  if (!props.draggable || props.node.disabled) return
+  event.dataTransfer?.setData('text/plain', props.node.id)
+  emit('node-drag-start', props.node)
+}
+
+function onDragOver(event: DragEvent) {
+  if (!props.draggable || props.node.disabled) return
+  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect()
+  const offset = event.clientY - rect.top
+  const height = rect.height
+
+  if (offset < height * 0.25) {
+    dropPosition.value = 'before'
+  } else if (offset > height * 0.75) {
+    dropPosition.value = 'after'
+  } else {
+    dropPosition.value = 'inside'
+  }
+}
+
+function onDragLeave() {
+  dropPosition.value = null
+}
+
+function onDrop() {
+  if (!props.draggable || !dropPosition.value) return
+  emit('node-drop', {
+    targetNode: props.node,
+    position: dropPosition.value
+  })
+  dropPosition.value = null
+}
 </script>
diff --git a/packages/ui/src/components/tree-view/types.ts b/packages/ui/src/components/tree-view/types.ts
index e342830..a191818 100644
--- a/packages/ui/src/components/tree-view/types.ts
+++ b/packages/ui/src/components/tree-view/types.ts
@@ -1,6 +1,20 @@
+import type { Component } from 'vue'
+
 export interface TreeNode {
   id: string
   label: string
   disabled?: boolean
   children?: TreeNode[]
+  /** True when node has dynamic children that haven't been fetched yet. */
+  isLeaf?: boolean
+  /** Optional icon component or icon name rendered before node label. */
+  icon?: Component
 }
+
+export interface TreeDropEvent {
+  draggedNode: TreeNode
+  targetNode: TreeNode
+  position: 'before' | 'inside' | 'after'
+}
+
+export type TreeHighlightVariant = 'subtle' | 'solid' | 'bar'

From 6e23ed01d3d7b96b350c6a4179f5e744488bc6c4 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 05:33:20 +0800
Subject: [PATCH 17/26] feat(locale): add i18n locale injection context

---
 .changeset/calm-locales-flow.md               |   5 +
 apps/playground/pages/components/locale.vue   | 128 +++++++++++++
 apps/playground/utils/catalog.ts              |   1 +
 .../command-palette/CommandPalette.vue        |  20 ++-
 .../ui/src/components/empty/EmptyState.vue    |  28 ++-
 .../src/components/file-upload/FileUpload.vue |  33 +++-
 .../src/components/pagination/Pagination.vue  |  53 +++++-
 .../ui/src/components/table/DataTable.vue     |  15 +-
 .../ui/src/components/tree-view/TreeView.vue  |   8 +-
 .../src/components/tree-view/TreeViewNode.vue |   8 +-
 packages/ui/src/index.ts                      |   2 +
 packages/ui/src/locale/index.ts               |  94 ++++++++++
 packages/ui/src/locale/locale.test.ts         |  47 +++++
 packages/ui/src/locale/messages.ts            | 169 ++++++++++++++++++
 14 files changed, 573 insertions(+), 38 deletions(-)
 create mode 100644 .changeset/calm-locales-flow.md
 create mode 100644 apps/playground/pages/components/locale.vue
 create mode 100644 packages/ui/src/locale/index.ts
 create mode 100644 packages/ui/src/locale/locale.test.ts
 create mode 100644 packages/ui/src/locale/messages.ts

diff --git a/.changeset/calm-locales-flow.md b/.changeset/calm-locales-flow.md
new file mode 100644
index 0000000..e6dc959
--- /dev/null
+++ b/.changeset/calm-locales-flow.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add lightweight i18n locale injection context with default zh-CN/en-US messages, adapt Pagination, EmptyState, DataTable, FileUpload, and TreeView to consume contextual translations, and document usage in Playground.
diff --git a/apps/playground/pages/components/locale.vue b/apps/playground/pages/components/locale.vue
new file mode 100644
index 0000000..8fe74e2
--- /dev/null
+++ b/apps/playground/pages/components/locale.vue
@@ -0,0 +1,128 @@
+<template>
+  <div class="space-y-12">
+    <div>
+      <h1 class="text-3xl font-bold tracking-tight text-slate-900 dark:text-slate-100">i18n 国际化</h1>
+      <p class="mt-2 text-base text-slate-600 dark:text-slate-400">
+        ReCloud UI 提供全局上下文注入与按组件提取的轻量国际化机制。支持开箱即用的简体中文（<code>zh-CN</code>）与英文（<code>en-US</code>），无需引入沉重外部框架，也可与 vue-i18n 深度打通。
+      </p>
+    </div>
+
+    <DocExample title="动态切换语言与组件即时生效">
+      <template #description>
+        点击切换语言环境，观察 Pagination、EmptyState、DataTable、FileUpload 与 TreeView 的文案即时响应。
+      </template>
+
+      <div class="space-y-6">
+        <div class="flex items-center gap-3">
+          <span class="text-sm font-medium text-slate-700 dark:text-slate-300">当前语言：</span>
+          <Button
+            size="sm"
+            :variant="locale === 'zh-CN' ? 'primary' : 'outline'"
+            @click="setLocale('zh-CN')"
+          >
+            中文 (zh-CN)
+          </Button>
+          <Button
+            size="sm"
+            :variant="locale === 'en-US' ? 'primary' : 'outline'"
+            @click="setLocale('en-US')"
+          >
+            English (en-US)
+          </Button>
+          <Button
+            size="sm"
+            variant="ghost"
+            @click="setCustomOverride"
+          >
+            应用自定义文案覆盖
+          </Button>
+        </div>
+
+        <div class="grid grid-cols-1 gap-6 lg:grid-cols-2">
+          <!-- Pagination -->
+          <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
+            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">Pagination 分页导航</h3>
+            <Pagination
+              :model-value="page"
+              :total="80"
+              :page-size="10"
+              @update:model-value="page = $event"
+            />
+          </div>
+
+          <!-- EmptyState -->
+          <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
+            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">EmptyState 缺省状态</h3>
+            <EmptyState description="请调整筛选条件或稍后重试" />
+          </div>
+        </div>
+
+        <!-- DataTable -->
+        <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
+          <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">DataTable 分页与空态</h3>
+          <DataTable
+            :columns="[
+              { key: 'name', label: '服务' },
+              { key: 'status', label: '状态' }
+            ]"
+            :rows="[]"
+            :page-size="5"
+          />
+        </div>
+
+        <!-- FileUpload -->
+        <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
+          <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">FileUpload 上传拖拽与提示</h3>
+          <FileUpload accept=".png,.jpg" :max-size="1024 * 1024 * 5" />
+        </div>
+      </div>
+    </DocExample>
+
+    <div class="space-y-4">
+      <h2 class="text-xl font-semibold text-slate-900 dark:text-slate-100">使用方式</h2>
+      <CodeBlock :code="usageCode" language="ts" filename="app.vue" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { provideLocale } from '@recloudstudio/ui'
+
+const { locale, setLocale } = provideLocale('zh-CN')
+const page = ref(2)
+
+function setCustomOverride() {
+  setLocale('zh-CN', {
+    pagination: {
+      prev: '往回翻',
+      next: '往前翻'
+    },
+    empty: {
+      defaultTitle: '这里什么也没有找到呢'
+    }
+  })
+}
+
+const usageCode = `// 1. 在根组件或插件中注入语言包
+import { provideLocale, zhCN, enUS } from '@recloudstudio/ui'
+
+// 提供默认语言
+const { locale, setLocale } = provideLocale('zh-CN')
+
+// 动态切换语言
+setLocale('en-US')
+
+// 支持部分文案深度覆盖
+setLocale('zh-CN', {
+  pagination: {
+    prev: '前一页',
+    next: '后一页'
+  }
+})
+
+// 2. 组件内部如果需要消费当前国际化消息：
+import { useComponentLocale } from '@recloudstudio/ui'
+const loc = useComponentLocale('pagination')
+console.log(loc.value.prev)`
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index b4d331e..854ae1f 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -109,6 +109,7 @@ const groups: DocGroup[] = [
   {
     label: '工具',
     items: [
+      { name: 'locale', title: 'i18n 国际化', description: '组件库内置文案注入、双语包与动态切换。' },
       { name: 'scroll-area', title: 'ScrollArea 滚动区', description: '自定义滚动条容器。' },
       { name: 'aspect-ratio', title: 'AspectRatio 宽高比', description: '固定比例容器。' },
       { name: 'visually-hidden', title: 'VisuallyHidden 隐藏文本', description: '屏幕阅读器专用。' }
diff --git a/packages/ui/src/components/command-palette/CommandPalette.vue b/packages/ui/src/components/command-palette/CommandPalette.vue
index 91a09bb..a71ffc8 100644
--- a/packages/ui/src/components/command-palette/CommandPalette.vue
+++ b/packages/ui/src/components/command-palette/CommandPalette.vue
@@ -7,7 +7,7 @@
         :class="props.class"
         @open-auto-focus="focusInput"
       >
-        <DialogTitle class="sr-only">{{ props.label }}</DialogTitle>
+        <DialogTitle class="sr-only">{{ effectiveLabel }}</DialogTitle>
         <div class="flex items-center gap-3 border-b border-slate-200 px-4 dark:border-slate-800">
           <svg class="h-4 w-4 shrink-0 text-slate-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7" /><path stroke-linecap="round" d="m20 20-3.5-3.5" /></svg>
           <input
@@ -18,7 +18,7 @@
             aria-autocomplete="list"
             aria-controls="command-palette-list"
             :aria-activedescendant="activeItem ? itemDomId(activeItem) : undefined"
-            :placeholder="props.placeholder"
+            :placeholder="effectivePlaceholder"
             class="h-14 min-w-0 grow bg-transparent text-sm text-slate-900 outline-none placeholder:text-slate-400 dark:text-slate-100"
             @input="setQuery(($event.target as HTMLInputElement).value)"
             @keydown.down.prevent="moveActive(1)"
@@ -29,7 +29,7 @@
           <kbd v-if="props.shortcut" class="rounded border border-slate-200 bg-slate-50 px-1.5 py-0.5 font-mono text-[10px] text-slate-500 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-400">{{ displayShortcut }}</kbd>
         </div>
 
-        <div id="command-palette-list" role="listbox" :aria-label="props.label" class="max-h-[min(60vh,30rem)] overflow-y-auto p-2">
+        <div id="command-palette-list" role="listbox" :aria-label="effectiveLabel" class="max-h-[min(60vh,30rem)] overflow-y-auto p-2">
           <template v-for="group in filteredGroups" :key="group.key">
             <div v-if="group.heading" class="px-2 pt-3 pb-1 text-[11px] font-semibold tracking-wider text-slate-400 uppercase dark:text-slate-500">{{ group.heading }}</div>
             <button
@@ -58,7 +58,7 @@
             </button>
           </template>
           <div v-if="!filteredItems.length" class="px-3 py-10 text-center text-sm text-slate-500 dark:text-slate-400">
-            <slot name="empty" :query="query">{{ props.emptyText }}</slot>
+            <slot name="empty" :query="query">{{ effectiveEmptyText }}</slot>
           </div>
         </div>
       </DialogContent>
@@ -70,6 +70,7 @@
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTitle } from 'reka-ui'
 import { filterCommands } from './commandMatcher'
+import { useComponentLocale } from '../../locale'
 import type { CommandFilter, CommandGroup, CommandItem } from './types'
 
 export interface CommandPaletteProps {
@@ -89,9 +90,9 @@ export interface CommandPaletteProps {
 const props = withDefaults(defineProps<CommandPaletteProps>(), {
   open: false,
   query: undefined,
-  placeholder: '搜索命令…',
-  emptyText: '没有找到匹配的命令。',
-  label: '命令面板',
+  placeholder: undefined,
+  emptyText: undefined,
+  label: undefined,
   shortcut: undefined,
   shortcutInEditable: false,
   filter: undefined,
@@ -104,6 +105,11 @@ const emit = defineEmits<{
   (event: 'select', item: CommandItem): void
 }>()
 
+const loc = useComponentLocale('command')
+const effectiveLabel = computed(() => props.label ?? loc.value.label)
+const effectivePlaceholder = computed(() => props.placeholder ?? loc.value.searchPlaceholder)
+const effectiveEmptyText = computed(() => props.emptyText ?? loc.value.emptyText)
+
 const input = ref<HTMLInputElement>()
 const internalQuery = ref('')
 const activeId = ref<string>()
diff --git a/packages/ui/src/components/empty/EmptyState.vue b/packages/ui/src/components/empty/EmptyState.vue
index f91e832..c28f6fc 100644
--- a/packages/ui/src/components/empty/EmptyState.vue
+++ b/packages/ui/src/components/empty/EmptyState.vue
@@ -1,25 +1,43 @@
 <template>
-  <div :class="cn('flex flex-col items-center justify-center rounded-xl border border-dashed border-slate-300 px-6 py-10 text-center dark:border-slate-700', props.class)">
-    <div v-if="$slots.icon" class="mb-3 flex h-10 w-10 items-center justify-center rounded-lg bg-slate-100 text-slate-500 dark:bg-slate-800 dark:text-slate-400">
+  <div
+    :class="cn('flex flex-col items-center justify-center rounded-xl border border-dashed border-[var(--border)] px-6 py-10 text-center', props.class)"
+  >
+    <div
+      v-if="$slots.icon"
+      class="mb-3 flex h-10 w-10 items-center justify-center rounded-lg bg-[var(--muted)] text-[var(--muted-foreground)]"
+    >
       <slot name="icon" />
     </div>
-    <h3 class="text-sm font-semibold text-slate-900 dark:text-slate-100">{{ props.title }}</h3>
-    <p v-if="props.description" class="mt-1 max-w-sm text-sm leading-6 text-slate-500 dark:text-slate-400">{{ props.description }}</p>
+    <h3 class="text-sm font-semibold text-[var(--foreground)]">
+      {{ displayTitle }}
+    </h3>
+    <p
+      v-if="props.description"
+      class="mt-1 max-w-sm text-sm leading-6 text-[var(--muted-foreground)]"
+    >
+      {{ props.description }}
+    </p>
     <div v-if="$slots.default" class="mt-4"><slot /></div>
   </div>
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface EmptyStateProps {
-  title: string
+  title?: string
   description?: string
   class?: string
 }
 
 const props = withDefaults(defineProps<EmptyStateProps>(), {
+  title: undefined,
   description: '',
   class: ''
 })
+
+const loc = useComponentLocale('empty')
+const displayTitle = computed(() => props.title ?? loc.value.defaultTitle)
 </script>
diff --git a/packages/ui/src/components/file-upload/FileUpload.vue b/packages/ui/src/components/file-upload/FileUpload.vue
index 5a9bb8f..a822b40 100644
--- a/packages/ui/src/components/file-upload/FileUpload.vue
+++ b/packages/ui/src/components/file-upload/FileUpload.vue
@@ -4,7 +4,7 @@
     <div
       role="button"
       tabindex="0"
-      :aria-label="props.label"
+      :aria-label="effectiveLabel"
       :class="cn('group relative flex min-h-44 cursor-pointer flex-col items-center justify-center overflow-hidden rounded-xl border border-dashed px-6 py-8 text-center transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] focus-visible:ring-offset-2 dark:focus-visible:ring-[#70ACFE] dark:focus-visible:ring-offset-[#090E17]', isDragging ? 'border-[#2563EB] bg-blue-50/70 dark:border-[#70ACFE] dark:bg-blue-950/30' : 'border-slate-300 bg-slate-50/50 hover:border-blue-400 hover:bg-blue-50/40 dark:border-slate-700 dark:bg-slate-900/30 dark:hover:border-blue-700 dark:hover:bg-blue-950/20')"
       @click="openPicker"
       @keydown.enter.prevent="openPicker"
@@ -15,11 +15,11 @@
       @drop.prevent="onDrop"
     >
       <div class="mb-3 flex h-11 w-11 items-center justify-center rounded-xl bg-white text-[#2563EB] shadow-xs ring-1 ring-slate-200 transition-transform group-hover:-translate-y-0.5 dark:bg-slate-800 dark:text-[#70ACFE] dark:ring-slate-700"><svg class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><path d="M12 16V4m0 0L7.5 8.5M12 4l4.5 4.5M5 14v4.5A1.5 1.5 0 0 0 6.5 20h11a1.5 1.5 0 0 0 1.5-1.5V14" stroke-linecap="round" stroke-linejoin="round" /></svg></div>
-      <p class="text-sm font-semibold text-slate-800 dark:text-slate-100"><span class="text-[#2563EB] dark:text-[#70ACFE]">选择文件</span> 或拖放到这里</p>
+      <p class="text-sm font-semibold text-slate-800 dark:text-slate-100"><span class="text-[#2563EB] dark:text-[#70ACFE]">{{ loc.dropzonePrefix }}</span> {{ loc.dropzoneSuffix }}</p>
       <p class="mt-1 text-xs leading-5 text-slate-500 dark:text-slate-400">{{ helpText }}</p>
     </div>
 
-    <ul v-if="items.length" class="space-y-2" aria-label="上传文件列表">
+    <ul v-if="items.length" class="space-y-2" :aria-label="effectiveLabel">
       <li v-for="item in items" :key="item.id" class="flex items-center gap-3 rounded-xl border border-slate-200 bg-white p-3 dark:border-slate-800 dark:bg-[#0F172A]">
         <img v-if="item.previewUrl" :src="item.previewUrl" :alt="item.file.name" class="h-10 w-10 rounded-lg object-cover ring-1 ring-slate-200 dark:ring-slate-700" />
         <div v-else class="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-slate-100 text-xs font-bold uppercase text-slate-500 dark:bg-slate-800 dark:text-slate-400">{{ fileExtension(item.file.name) }}</div>
@@ -33,6 +33,7 @@
 <script setup lang="ts">
 import { computed, onBeforeUnmount, ref } from 'vue'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 import type { FileUploadHandler, FileUploadItem } from './types'
 
 export interface FileUploadProps {
@@ -45,27 +46,41 @@ export interface FileUploadProps {
   class?: string
 }
 
-const props = withDefaults(defineProps<FileUploadProps>(), { accept: '', multiple: true, maxSize: undefined, maxFiles: undefined, label: '上传文件', upload: undefined, class: '' })
+const props = withDefaults(defineProps<FileUploadProps>(), { accept: '', multiple: true, maxSize: undefined, maxFiles: undefined, label: undefined, upload: undefined, class: '' })
 const emit = defineEmits<{ (event: 'change', items: FileUploadItem[]): void; (event: 'reject', payload: { file: File; reason: string }): void; (event: 'upload', item: FileUploadItem): void; (event: 'success', item: FileUploadItem): void; (event: 'error', item: FileUploadItem): void; (event: 'cancel', item: FileUploadItem): void }>()
+const loc = useComponentLocale('fileUpload')
+const effectiveLabel = computed(() => props.label ?? loc.value.label)
 const input = ref<HTMLInputElement>()
 const items = ref<FileUploadItem[]>([])
 const isDragging = ref(false)
 const controllers = new Map<string, AbortController>()
-const helpText = computed(() => [props.accept ? `支持 ${props.accept}` : '支持任意文件类型', props.maxSize ? `单个文件最大 ${formatSize(props.maxSize)}` : ''].filter(Boolean).join(' · '))
+const helpText = computed(() => [
+  props.accept ? loc.value.acceptRule(props.accept) : loc.value.anyFiles,
+  props.maxSize ? loc.value.maxSizeRule(formatSize(props.maxSize)) : ''
+].filter(Boolean).join(' · '))
 
 function openPicker() { input.value?.click() }
 function onInputChange(event: Event) { addFiles(Array.from((event.target as HTMLInputElement).files ?? [])); if (input.value) input.value.value = '' }
 function onDrop(event: DragEvent) { isDragging.value = false; addFiles(Array.from(event.dataTransfer?.files ?? [])) }
 function matchesAccept(file: File) { if (!props.accept) return true; return props.accept.split(',').some((rule) => { const value = rule.trim().toLowerCase(); return value.startsWith('.') ? file.name.toLowerCase().endsWith(value) : value.endsWith('/*') ? file.type.startsWith(value.slice(0, -1)) : file.type === value }) }
-function addFiles(files: File[]) { const accepted = props.multiple ? files : files.slice(0, 1); for (const file of accepted) { if (props.maxFiles && items.value.length >= props.maxFiles) { emit('reject', { file, reason: `最多上传 ${props.maxFiles} 个文件` }); continue } if (!matchesAccept(file)) { emit('reject', { file, reason: '文件类型不受支持' }); continue } if (props.maxSize && file.size > props.maxSize) { emit('reject', { file, reason: `文件不能超过 ${formatSize(props.maxSize)}` }); continue } const item: FileUploadItem = { id: crypto.randomUUID(), file, status: props.upload ? 'uploading' : 'pending', progress: props.upload ? 0 : undefined, previewUrl: file.type.startsWith('image/') ? URL.createObjectURL(file) : undefined }; items.value.push(item); notify(); if (props.upload) runUpload(item) } }
-async function runUpload(item: FileUploadItem) { const controller = new AbortController(); controllers.set(item.id, controller); emit('upload', item); try { await props.upload!({ file: item.file, signal: controller.signal, setProgress: (progress) => { item.progress = Math.min(Math.max(progress, 0), 100); notify() } }); if (controller.signal.aborted) return; item.status = 'success'; item.progress = 100; emit('success', item) } catch (error) { if (controller.signal.aborted) return; item.status = 'error'; item.error = error instanceof Error ? error.message : '上传失败，请重试'; emit('error', item) } finally { controllers.delete(item.id); notify() } }
-function cancel(id: string) { const item = items.value.find((entry) => entry.id === id); if (!item) return; controllers.get(id)?.abort(); controllers.delete(id); item.status = 'cancelled'; item.error = '上传已取消'; emit('cancel', item); notify() }
+function addFiles(files: File[]) { const accepted = props.multiple ? files : files.slice(0, 1); for (const file of accepted) { if (props.maxFiles && items.value.length >= props.maxFiles) { emit('reject', { file, reason: loc.value.fileLimitReject(props.maxFiles) }); continue } if (!matchesAccept(file)) { emit('reject', { file, reason: loc.value.typeReject }); continue } if (props.maxSize && file.size > props.maxSize) { emit('reject', { file, reason: loc.value.sizeReject(formatSize(props.maxSize)) }); continue } const item: FileUploadItem = { id: crypto.randomUUID(), file, status: props.upload ? 'uploading' : 'pending', progress: props.upload ? 0 : undefined, previewUrl: file.type.startsWith('image/') ? URL.createObjectURL(file) : undefined }; items.value.push(item); notify(); if (props.upload) runUpload(item) } }
+async function runUpload(item: FileUploadItem) { const controller = new AbortController(); controllers.set(item.id, controller); emit('upload', item); try { await props.upload!({ file: item.file, signal: controller.signal, setProgress: (progress) => { item.progress = Math.min(Math.max(progress, 0), 100); notify() } }); if (controller.signal.aborted) return; item.status = 'success'; item.progress = 100; emit('success', item) } catch (error) { if (controller.signal.aborted) return; item.status = 'error'; item.error = error instanceof Error ? error.message : loc.value.failedDefault; emit('error', item) } finally { controllers.delete(item.id); notify() } }
+function cancel(id: string) { const item = items.value.find((entry) => entry.id === id); if (!item) return; controllers.get(id)?.abort(); controllers.delete(id); item.status = 'cancelled'; item.error = loc.value.cancelled; emit('cancel', item); notify() }
 function retry(id: string) { const item = items.value.find((entry) => entry.id === id); if (!item || !props.upload) return; item.status = 'uploading'; item.progress = 0; item.error = undefined; runUpload(item); notify() }
 function remove(id: string) { const item = items.value.find((entry) => entry.id === id); controllers.get(id)?.abort(); if (item?.previewUrl) URL.revokeObjectURL(item.previewUrl); items.value = items.value.filter((entry) => entry.id !== id); notify() }
 function notify() { emit('change', [...items.value]) }
 function fileExtension(name: string) { return name.split('.').pop()?.slice(0, 4) || 'file' }
 function formatSize(bytes: number) { if (bytes < 1024) return `${bytes} B`; if (bytes < 1024 ** 2) return `${(bytes / 1024).toFixed(1)} KB`; return `${(bytes / 1024 ** 2).toFixed(1)} MB` }
-function statusLabel(status: FileUploadItem['status']) { return ({ pending: '等待上传', uploading: '上传中', success: '已完成', error: '失败', cancelled: '已取消' })[status] }
+function statusLabel(status: FileUploadItem['status']) {
+  const map: Record<FileUploadItem['status'], string> = {
+    pending: loc.value.statusPending,
+    uploading: loc.value.statusUploading,
+    success: loc.value.statusSuccess,
+    error: loc.value.statusError,
+    cancelled: loc.value.statusCancelled
+  }
+  return map[status]
+}
 function statusClass(status: FileUploadItem['status']) { return cn('rounded-md px-1.5 py-0.5 text-[10px] font-semibold', status === 'success' && 'bg-emerald-50 text-emerald-700 dark:bg-emerald-950/50 dark:text-emerald-400', status === 'error' && 'bg-red-50 text-red-700 dark:bg-red-950/50 dark:text-red-400', status === 'cancelled' && 'bg-slate-100 text-slate-600 dark:bg-slate-800 dark:text-slate-400', status === 'uploading' && 'bg-blue-50 text-blue-700 dark:bg-blue-950/50 dark:text-blue-300', status === 'pending' && 'bg-amber-50 text-amber-700 dark:bg-amber-950/50 dark:text-amber-400') }
 onBeforeUnmount(() => { controllers.forEach((controller) => controller.abort()); items.value.forEach((item) => { if (item.previewUrl) URL.revokeObjectURL(item.previewUrl) }) })
 </script>
diff --git a/packages/ui/src/components/pagination/Pagination.vue b/packages/ui/src/components/pagination/Pagination.vue
index 3180680..253b10f 100644
--- a/packages/ui/src/components/pagination/Pagination.vue
+++ b/packages/ui/src/components/pagination/Pagination.vue
@@ -1,10 +1,43 @@
 <template>
-  <nav class="flex items-center justify-between gap-3" aria-label="分页导航">
-    <p v-if="showSummary" class="text-sm text-slate-500 dark:text-slate-400">第 {{ modelValue }} / {{ totalPages }} 页</p>
+  <nav
+    :class="cn('flex items-center justify-between gap-3', props.class)"
+    :aria-label="loc.ariaLabel"
+  >
+    <p v-if="showSummary" class="text-sm text-[var(--muted-foreground)]">
+      {{ loc.pageSummary(modelValue, totalPages) }}
+    </p>
     <div class="flex items-center gap-1" :class="!showSummary && 'w-full justify-center'">
-      <button :class="buttonClasses" :disabled="modelValue <= 1" aria-label="上一页" @click="updatePage(modelValue - 1)">上一页</button>
-      <button v-for="page in pages" :key="page" :class="cn(buttonClasses, page === modelValue && 'bg-[#2563EB] text-white ring-[#2563EB] dark:bg-[#70ACFE] dark:text-slate-950 dark:ring-[#70ACFE]')" :aria-current="page === modelValue ? 'page' : undefined" @click="updatePage(page)">{{ page }}</button>
-      <button :class="buttonClasses" :disabled="modelValue >= totalPages" aria-label="下一页" @click="updatePage(modelValue + 1)">下一页</button>
+      <button
+        :class="buttonClasses"
+        :disabled="modelValue <= 1"
+        :aria-label="loc.prev"
+        type="button"
+        @click="updatePage(modelValue - 1)"
+      >
+        {{ loc.prev }}
+      </button>
+      <button
+        v-for="page in pages"
+        :key="page"
+        type="button"
+        :class="cn(
+          buttonClasses,
+          page === modelValue && 'bg-[var(--primary)] text-[var(--primary-foreground)] ring-[var(--primary)] font-semibold shadow-xs'
+        )"
+        :aria-current="page === modelValue ? 'page' : undefined"
+        @click="updatePage(page)"
+      >
+        {{ page }}
+      </button>
+      <button
+        :class="buttonClasses"
+        :disabled="modelValue >= totalPages"
+        :aria-label="loc.next"
+        type="button"
+        @click="updatePage(modelValue + 1)"
+      >
+        {{ loc.next }}
+      </button>
     </div>
   </nav>
 </template>
@@ -12,6 +45,7 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface PaginationProps {
   modelValue?: number
@@ -19,6 +53,7 @@ export interface PaginationProps {
   pageSize?: number
   siblingCount?: number
   showSummary?: boolean
+  class?: string
 }
 
 const props = withDefaults(defineProps<PaginationProps>(), {
@@ -26,16 +61,20 @@ const props = withDefaults(defineProps<PaginationProps>(), {
   total: 0,
   pageSize: 10,
   siblingCount: 1,
-  showSummary: true
+  showSummary: true,
+  class: ''
 })
 
 const emit = defineEmits<{ (event: 'update:modelValue', page: number): void }>()
+const loc = useComponentLocale('pagination')
+
 const totalPages = computed(() => Math.max(1, Math.ceil(props.total / props.pageSize)))
 const pages = computed(() => Array.from({ length: Math.min(totalPages.value, props.siblingCount * 2 + 3) }, (_, index) => {
   const start = Math.min(Math.max(props.modelValue - props.siblingCount, 1), Math.max(totalPages.value - (props.siblingCount * 2 + 2), 1))
   return start + index
 }))
-const buttonClasses = 'inline-flex h-8 min-w-8 items-center justify-center rounded-lg px-2 text-sm font-medium text-slate-600 ring-1 ring-inset ring-transparent transition-colors hover:bg-slate-100 hover:text-slate-950 disabled:pointer-events-none disabled:opacity-40 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-white'
+
+const buttonClasses = 'inline-flex h-8 min-w-8 items-center justify-center rounded-lg px-2 text-sm font-medium text-[var(--muted-foreground)] ring-1 ring-inset ring-transparent transition-colors hover:bg-[var(--muted)] hover:text-[var(--foreground)] disabled:pointer-events-none disabled:opacity-40'
 
 function updatePage(page: number) {
   emit('update:modelValue', Math.min(Math.max(page, 1), totalPages.value))
diff --git a/packages/ui/src/components/table/DataTable.vue b/packages/ui/src/components/table/DataTable.vue
index d663d47..11defcf 100644
--- a/packages/ui/src/components/table/DataTable.vue
+++ b/packages/ui/src/components/table/DataTable.vue
@@ -18,10 +18,10 @@
         </tbody>
       </table>
     </div>
-    <div v-if="loading" class="space-y-3 p-4" aria-label="加载中" role="status"><div v-for="row in 4" :key="row" class="flex gap-4"><Skeleton v-for="column in visibleColumns.length + Number(selectable)" :key="column" height="1.5rem" /></div></div>
-    <div v-else-if="error" class="p-4"><slot name="error"><EmptyState title="数据加载失败" :description="error"><template #icon><svg class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"/><path d="M12 8v4M12 16h.01"/></svg></template></EmptyState></slot></div>
-    <div v-else-if="!pagedRows.length" class="p-4"><slot name="empty"><EmptyState :title="emptyText" /></slot></div>
-    <div v-if="showPagination" class="flex flex-wrap items-center justify-between gap-3 border-t border-slate-200 px-4 py-3 dark:border-slate-800"><span class="text-xs text-slate-500 dark:text-slate-400">第 {{ currentPage }} / {{ pageCount }} 页，共 {{ total }} 条</span><div class="flex gap-1"><button :disabled="currentPage <= 1" class="inline-flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium text-slate-600 transition-colors hover:bg-slate-100 disabled:pointer-events-none disabled:opacity-40 dark:text-slate-300 dark:hover:bg-slate-800" @click="setPage(currentPage - 1)">上一页</button><button :disabled="currentPage >= pageCount" class="inline-flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium text-slate-600 transition-colors hover:bg-slate-100 disabled:pointer-events-none disabled:opacity-40 dark:text-slate-300 dark:hover:bg-slate-800" @click="setPage(currentPage + 1)">下一页</button></div></div>
+    <div v-if="loading" class="space-y-3 p-4" :aria-label="commonLoc.loading" role="status"><div v-for="row in 4" :key="row" class="flex gap-4"><Skeleton v-for="column in visibleColumns.length + Number(selectable)" :key="column" height="1.5rem" /></div></div>
+    <div v-else-if="error" class="p-4"><slot name="error"><EmptyState :title="emptyLoc.loadFailed" :description="error"><template #icon><svg class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"/><path d="M12 8v4M12 16h.01"/></svg></template></EmptyState></slot></div>
+    <div v-else-if="!pagedRows.length" class="p-4"><slot name="empty"><EmptyState :title="effectiveEmptyText" /></slot></div>
+    <div v-if="showPagination" class="flex flex-wrap items-center justify-between gap-3 border-t border-slate-200 px-4 py-3 dark:border-slate-800"><span class="text-xs text-slate-500 dark:text-slate-400">{{ paginationLoc.totalSummary(currentPage, pageCount, total) }}</span><div class="flex gap-1"><button :disabled="currentPage <= 1" class="inline-flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium text-slate-600 transition-colors hover:bg-slate-100 disabled:pointer-events-none disabled:opacity-40 dark:text-slate-300 dark:hover:bg-slate-800" @click="setPage(currentPage - 1)">{{ paginationLoc.prev }}</button><button :disabled="currentPage >= pageCount" class="inline-flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium text-slate-600 transition-colors hover:bg-slate-100 disabled:pointer-events-none disabled:opacity-40 dark:text-slate-300 dark:hover:bg-slate-800" @click="setPage(currentPage + 1)">{{ paginationLoc.next }}</button></div></div>
   </div>
 </template>
 
@@ -30,6 +30,7 @@ import { computed } from 'vue'
 import EmptyState from '../empty/EmptyState.vue'
 import Skeleton from '../skeleton/Skeleton.vue'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 import type { DataTableColumn, DataTableSort } from './types'
 
 export interface DataTableProps<T extends Record<string, unknown> = Record<string, unknown>> {
@@ -52,8 +53,12 @@ export interface DataTableProps<T extends Record<string, unknown> = Record<strin
   class?: string
 }
 
-const props = withDefaults(defineProps<DataTableProps<T>>(), { columns: () => [], rows: () => [], rowKey: undefined, selected: () => [], visibleColumnKeys: undefined, sortable: undefined, page: 1, pageSize: 0, total: undefined, loading: false, error: '', selectable: false, hoverable: true, divide: true, emptyText: '暂无数据', class: '' })
+const props = withDefaults(defineProps<DataTableProps<T>>(), { columns: () => [], rows: () => [], rowKey: undefined, selected: () => [], visibleColumnKeys: undefined, sortable: undefined, page: 1, pageSize: 0, total: undefined, loading: false, error: '', selectable: false, hoverable: true, divide: true, emptyText: undefined, class: '' })
 const emit = defineEmits<{ (event: 'update:selected', value: Array<string | number>): void; (event: 'update:visibleColumnKeys', value: string[]): void; (event: 'update:sortable', value: DataTableSort | undefined): void; (event: 'update:page', value: number): void }>()
+const emptyLoc = useComponentLocale('empty')
+const paginationLoc = useComponentLocale('pagination')
+const commonLoc = useComponentLocale('common')
+const effectiveEmptyText = computed(() => props.emptyText ?? emptyLoc.value.defaultTitle)
 const visibleColumns = computed(() => props.visibleColumnKeys ? props.columns.filter((column) => props.visibleColumnKeys!.includes(column.key)) : props.columns)
 const showPagination = computed(() => props.pageSize > 0)
 const total = computed(() => props.total ?? props.rows.length)
diff --git a/packages/ui/src/components/tree-view/TreeView.vue b/packages/ui/src/components/tree-view/TreeView.vue
index e0dc535..95e3806 100644
--- a/packages/ui/src/components/tree-view/TreeView.vue
+++ b/packages/ui/src/components/tree-view/TreeView.vue
@@ -1,7 +1,7 @@
 <template>
   <ul
     role="tree"
-    :aria-label="props.label"
+    :aria-label="effectiveLabel"
     :aria-multiselectable="props.multiple || undefined"
     :class="cn('space-y-0.5 rounded-xl bg-[var(--card)] p-2 ring-1 ring-[var(--border)]', props.class)"
   >
@@ -37,6 +37,7 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 import TreeViewNode from './TreeViewNode.vue'
 import type { TreeDropEvent, TreeHighlightVariant, TreeNode } from './types'
 
@@ -79,7 +80,7 @@ const props = withDefaults(defineProps<TreeViewProps>(), {
   draggable: false,
   highlightVariant: 'subtle',
   loadChildren: undefined,
-  label: '树形目录',
+  label: undefined,
   class: ''
 })
 
@@ -95,6 +96,9 @@ const emit = defineEmits<{
   (event: 'drop', payload: TreeDropEvent): void
 }>()
 
+const loc = useComponentLocale('tree')
+const effectiveLabel = computed(() => props.label ?? loc.value.label)
+
 const internalExpanded = ref<string[]>([...props.defaultExpandedIds])
 const internalSelectedIds = ref<string[]>([])
 const loadingIds = ref<string[]>([])
diff --git a/packages/ui/src/components/tree-view/TreeViewNode.vue b/packages/ui/src/components/tree-view/TreeViewNode.vue
index 80561f4..7d94a0f 100644
--- a/packages/ui/src/components/tree-view/TreeViewNode.vue
+++ b/packages/ui/src/components/tree-view/TreeViewNode.vue
@@ -34,7 +34,7 @@
         v-if="isBranch"
         type="button"
         class="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
-        :aria-label="expanded ? `收起 ${node.label}` : `展开 ${node.label}`"
+        :aria-label="expanded ? loc.collapseNode(node.label) : loc.expandNode(node.label)"
         @click.stop="emit('toggle', node.id)"
       >
         <svg
@@ -66,7 +66,7 @@
         type="checkbox"
         :checked="checkState === 'checked'"
         :indeterminate="checkState === 'partial'"
-        :aria-label="`选择 ${node.label}`"
+        :aria-label="loc.selectNode(node.label)"
         class="h-4 w-4 shrink-0 rounded accent-[var(--primary)]"
         @click.stop
         @change="emit('check', node)"
@@ -92,7 +92,7 @@
         class="ml-auto inline-flex shrink-0 items-center rounded-full bg-[var(--primary)]/10 px-1.5 py-0.5 text-[10px] font-semibold text-[var(--primary)] ring-1 ring-[var(--primary)]/20"
         aria-hidden="true"
       >
-        已选
+        {{ loc.selectedBadge }}
       </span>
     </div>
 
@@ -141,6 +141,7 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 import type { TreeHighlightVariant, TreeNode } from './types'
 
 defineOptions({ name: 'TreeViewNode' })
@@ -166,6 +167,7 @@ const emit = defineEmits<{
   (event: 'node-drop', payload: { targetNode: TreeNode; position: 'before' | 'inside' | 'after' }): void
 }>()
 
+const loc = useComponentLocale('tree')
 const dropPosition = ref<'before' | 'inside' | 'after' | null>(null)
 
 const hasChildren = computed(() => Boolean(props.node.children?.length))
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index d11b735..e10f685 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -61,6 +61,8 @@ export * from './components/timeline'
 
 // Composables & Utilities
 export * from './composables/useTheme'
+export * from './locale'
+export * from './locale/messages'
 export * from './utils/cn'
 export * from './utils/theme'
 export * from './utils/themeScript'
diff --git a/packages/ui/src/locale/index.ts b/packages/ui/src/locale/index.ts
new file mode 100644
index 0000000..d16f14a
--- /dev/null
+++ b/packages/ui/src/locale/index.ts
@@ -0,0 +1,94 @@
+import { computed, inject, provide, type InjectionKey, type Ref, shallowRef } from 'vue'
+import { enUS, zhCN, type DeepPartial, type LocaleMessages } from './messages'
+
+export interface LocaleContext {
+  locale: Ref<string>
+  messages: Ref<LocaleMessages>
+  setLocale: (name: string, customMessages?: DeepPartial<LocaleMessages>) => void
+}
+
+export const LOCALE_INJECTION_KEY: InjectionKey<LocaleContext> = Symbol('recloud:locale')
+
+const builtInLocales: Record<string, LocaleMessages> = {
+  'zh-CN': zhCN,
+  zh: zhCN,
+  'en-US': enUS,
+  en: enUS
+}
+
+function mergeDeep<T extends Record<string, unknown>>(target: T, source?: Record<string, unknown>): T {
+  if (!source) return target
+  const output: Record<string, unknown> = { ...target }
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key]
+    const targetVal = output[key]
+    if (
+      sourceVal !== null &&
+      sourceVal !== undefined &&
+      typeof sourceVal === 'object' &&
+      !Array.isArray(sourceVal) &&
+      targetVal !== null &&
+      targetVal !== undefined &&
+      typeof targetVal === 'object' &&
+      !Array.isArray(targetVal)
+    ) {
+      output[key] = mergeDeep(
+        targetVal as Record<string, unknown>,
+        sourceVal as Record<string, unknown>
+      )
+    } else if (sourceVal !== undefined) {
+      output[key] = sourceVal
+    }
+  }
+  return output as T
+}
+
+export function provideLocale(
+  initialLocale: string = 'zh-CN',
+  customMessages?: DeepPartial<LocaleMessages>
+): LocaleContext {
+  const currentLocale = shallowRef(initialLocale)
+  const base = builtInLocales[initialLocale] ?? zhCN
+  const currentMessages = shallowRef<LocaleMessages>(
+    customMessages ? mergeDeep({ ...base }, customMessages as Record<string, unknown>) : base
+  )
+
+  const context: LocaleContext = {
+    locale: currentLocale,
+    messages: currentMessages,
+    setLocale(name: string, override?: DeepPartial<LocaleMessages>) {
+      currentLocale.value = name
+      const fallback = builtInLocales[name] ?? zhCN
+      currentMessages.value = override
+        ? mergeDeep({ ...fallback }, override as Record<string, unknown>)
+        : fallback
+    }
+  }
+
+  provide(LOCALE_INJECTION_KEY, context)
+  return context
+}
+
+export function useLocale() {
+  const injected = inject(LOCALE_INJECTION_KEY, null)
+  if (injected) return injected
+
+  const defaultLocale = shallowRef('zh-CN')
+  const defaultMessages = shallowRef(zhCN)
+  return {
+    locale: defaultLocale,
+    messages: defaultMessages,
+    setLocale(name: string, override?: DeepPartial<LocaleMessages>) {
+      defaultLocale.value = name
+      const fallback = builtInLocales[name] ?? zhCN
+      defaultMessages.value = override
+        ? mergeDeep({ ...fallback }, override as Record<string, unknown>)
+        : fallback
+    }
+  }
+}
+
+export function useComponentLocale<K extends keyof LocaleMessages>(componentKey: K) {
+  const { messages } = useLocale()
+  return computed(() => messages.value[componentKey])
+}
diff --git a/packages/ui/src/locale/locale.test.ts b/packages/ui/src/locale/locale.test.ts
new file mode 100644
index 0000000..198689d
--- /dev/null
+++ b/packages/ui/src/locale/locale.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { provideLocale, useComponentLocale, useLocale } from './index'
+import { zhCN, enUS } from './messages'
+
+describe('i18n locale injection system', () => {
+  it('returns default zhCN messages when no context is active', () => {
+    const { locale, messages } = useLocale()
+    expect(locale.value).toBe('zh-CN')
+    expect(messages.value.pagination.prev).toBe('上一页')
+    expect(messages.value.empty.defaultTitle).toBe('暂无数据')
+    expect(messages.value.command.emptyText).toBe('没有找到匹配的命令。')
+  })
+
+  it('switches between locales dynamically', () => {
+    const { locale, messages, setLocale } = useLocale()
+    setLocale('en-US')
+    expect(locale.value).toBe('en-US')
+    expect(messages.value.pagination.prev).toBe('Previous')
+    expect(messages.value.empty.defaultTitle).toBe('No data available')
+
+    setLocale('zh-CN')
+    expect(locale.value).toBe('zh-CN')
+    expect(messages.value.pagination.prev).toBe('上一页')
+  })
+
+  it('supports custom message overrides', () => {
+    const { locale, messages, setLocale } = useLocale()
+    setLocale('en-US', {
+      pagination: {
+        prev: 'Go Back'
+      }
+    })
+    expect(locale.value).toBe('en-US')
+    expect(messages.value.pagination.prev).toBe('Go Back')
+    expect(messages.value.pagination.next).toBe('Next')
+  })
+
+  it('formats parameterized pagination and rules correctly', () => {
+    expect(zhCN.pagination.pageSummary(2, 10)).toBe('第 2 / 10 页')
+    expect(enUS.pagination.pageSummary(2, 10)).toBe('Page 2 of 10')
+    expect(zhCN.pagination.totalSummary(1, 5, 50)).toBe('第 1 / 5 页，共 50 条')
+    expect(enUS.pagination.totalSummary(1, 5, 50)).toBe('Page 1 of 5, 50 total')
+
+    expect(zhCN.fileUpload.fileLimitReject(3)).toBe('最多上传 3 个文件')
+    expect(enUS.fileUpload.fileLimitReject(3)).toBe('Maximum 3 files allowed')
+  })
+})
diff --git a/packages/ui/src/locale/messages.ts b/packages/ui/src/locale/messages.ts
new file mode 100644
index 0000000..6a5cb87
--- /dev/null
+++ b/packages/ui/src/locale/messages.ts
@@ -0,0 +1,169 @@
+export interface LocaleMessages {
+  common: {
+    close: string
+    cancel: string
+    confirm: string
+    retry: string
+    remove: string
+    search: string
+    loading: string
+    noData: string
+  }
+  pagination: {
+    prev: string
+    next: string
+    pageSummary: (page: number, totalPages: number) => string
+    totalSummary: (page: number, totalPages: number, total: number) => string
+    ariaLabel: string
+  }
+  empty: {
+    defaultTitle: string
+    loadFailed: string
+  }
+  command: {
+    searchPlaceholder: string
+    emptyText: string
+    label: string
+  }
+  fileUpload: {
+    label: string
+    dropzonePrefix: string
+    dropzoneSuffix: string
+    anyFiles: string
+    acceptRule: (accept: string) => string
+    maxSizeRule: (size: string) => string
+    fileLimitReject: (max: number) => string
+    typeReject: string
+    sizeReject: (size: string) => string
+    failedDefault: string
+    cancelled: string
+    statusPending: string
+    statusUploading: string
+    statusSuccess: string
+    statusError: string
+    statusCancelled: string
+  }
+  tree: {
+    selectedBadge: string
+    collapseNode: (label: string) => string
+    expandNode: (label: string) => string
+    selectNode: (label: string) => string
+    label: string
+  }
+}
+
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends (...args: never[]) => unknown
+    ? T[P]
+    : T[P] extends object
+      ? DeepPartial<T[P]>
+      : T[P]
+}
+
+export const zhCN: LocaleMessages = {
+  common: {
+    close: '关闭',
+    cancel: '取消',
+    confirm: '确认',
+    retry: '重试',
+    remove: '移除',
+    search: '搜索',
+    loading: '加载中',
+    noData: '暂无数据'
+  },
+  pagination: {
+    prev: '上一页',
+    next: '下一页',
+    pageSummary: (page, totalPages) => `第 ${page} / ${totalPages} 页`,
+    totalSummary: (page, totalPages, total) => `第 ${page} / ${totalPages} 页，共 ${total} 条`,
+    ariaLabel: '分页导航'
+  },
+  empty: {
+    defaultTitle: '暂无数据',
+    loadFailed: '数据加载失败'
+  },
+  command: {
+    searchPlaceholder: '搜索命令…',
+    emptyText: '没有找到匹配的命令。',
+    label: '命令面板'
+  },
+  fileUpload: {
+    label: '上传文件',
+    dropzonePrefix: '选择文件',
+    dropzoneSuffix: '或拖放到这里',
+    anyFiles: '支持任意文件类型',
+    acceptRule: (accept) => `支持 ${accept}`,
+    maxSizeRule: (size) => `单个文件最大 ${size}`,
+    fileLimitReject: (max) => `最多上传 ${max} 个文件`,
+    typeReject: '文件类型不受支持',
+    sizeReject: (size) => `文件不能超过 ${size}`,
+    failedDefault: '上传失败，请重试',
+    cancelled: '上传已取消',
+    statusPending: '等待上传',
+    statusUploading: '上传中',
+    statusSuccess: '已完成',
+    statusError: '失败',
+    statusCancelled: '已取消'
+  },
+  tree: {
+    selectedBadge: '已选',
+    collapseNode: (label) => `收起 ${label}`,
+    expandNode: (label) => `展开 ${label}`,
+    selectNode: (label) => `选择 ${label}`,
+    label: '树形目录'
+  }
+}
+
+export const enUS: LocaleMessages = {
+  common: {
+    close: 'Close',
+    cancel: 'Cancel',
+    confirm: 'Confirm',
+    retry: 'Retry',
+    remove: 'Remove',
+    search: 'Search',
+    loading: 'Loading',
+    noData: 'No data'
+  },
+  pagination: {
+    prev: 'Previous',
+    next: 'Next',
+    pageSummary: (page, totalPages) => `Page ${page} of ${totalPages}`,
+    totalSummary: (page, totalPages, total) => `Page ${page} of ${totalPages}, ${total} total`,
+    ariaLabel: 'Pagination'
+  },
+  empty: {
+    defaultTitle: 'No data available',
+    loadFailed: 'Failed to load data'
+  },
+  command: {
+    searchPlaceholder: 'Search commands…',
+    emptyText: 'No matching commands found.',
+    label: 'Command palette'
+  },
+  fileUpload: {
+    label: 'Upload files',
+    dropzonePrefix: 'Choose a file',
+    dropzoneSuffix: 'or drag and drop here',
+    anyFiles: 'Supports any file type',
+    acceptRule: (accept) => `Supports ${accept}`,
+    maxSizeRule: (size) => `Max file size ${size}`,
+    fileLimitReject: (max) => `Maximum ${max} files allowed`,
+    typeReject: 'File type not supported',
+    sizeReject: (size) => `File must not exceed ${size}`,
+    failedDefault: 'Upload failed, please retry',
+    cancelled: 'Upload cancelled',
+    statusPending: 'Pending',
+    statusUploading: 'Uploading',
+    statusSuccess: 'Completed',
+    statusError: 'Failed',
+    statusCancelled: 'Cancelled'
+  },
+  tree: {
+    selectedBadge: 'Selected',
+    collapseNode: (label) => `Collapse ${label}`,
+    expandNode: (label) => `Expand ${label}`,
+    selectNode: (label) => `Select ${label}`,
+    label: 'Tree View'
+  }
+}

From 62cf1b55ff6907cea785c348780c677e6a756fa1 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 05:43:41 +0800
Subject: [PATCH 18/26] feat(locale): eliminate hardcoded strings across
 components

---
 .changeset/calm-locales-expand.md             |   5 +
 apps/playground/pages/components/locale.vue   |  96 +++++++++---
 .../components/alert-dialog/AlertDialog.vue   |  13 +-
 .../src/components/code-block/CodeBlock.vue   |   8 +-
 .../ui/src/components/combobox/Combobox.vue   |  15 +-
 .../src/components/date-picker/DatePicker.vue |  13 +-
 .../date-picker/DateRangePicker.vue           |  15 +-
 packages/ui/src/components/dialog/Dialog.vue  |   5 +-
 .../ui/src/components/editable/Editable.vue   |  15 +-
 .../src/components/file-upload/FileUpload.vue |   2 +-
 .../components/multi-select/MultiSelect.vue   |  14 +-
 packages/ui/src/components/select/Select.vue  |   8 +-
 packages/ui/src/components/sheet/Sheet.vue    |   5 +-
 .../ui/src/components/table/DataTable.vue     |   5 +-
 .../ui/src/components/tag-input/TagInput.vue  |  12 +-
 packages/ui/src/locale/messages.ts            | 140 +++++++++++++++++-
 16 files changed, 302 insertions(+), 69 deletions(-)
 create mode 100644 .changeset/calm-locales-expand.md

diff --git a/.changeset/calm-locales-expand.md b/.changeset/calm-locales-expand.md
new file mode 100644
index 0000000..faba255
--- /dev/null
+++ b/.changeset/calm-locales-expand.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Expand i18n localization coverage across components (Select, Combobox, MultiSelect, DatePicker, DateRangePicker, CodeBlock, Editable, TagInput, AlertDialog, DataTable) and eliminate hardcoded Chinese fallbacks.
diff --git a/apps/playground/pages/components/locale.vue b/apps/playground/pages/components/locale.vue
index 8fe74e2..7deae57 100644
--- a/apps/playground/pages/components/locale.vue
+++ b/apps/playground/pages/components/locale.vue
@@ -14,7 +14,7 @@
 
       <div class="space-y-6">
         <div class="flex items-center gap-3">
-          <span class="text-sm font-medium text-slate-700 dark:text-slate-300">当前语言：</span>
+          <span class="text-sm font-medium text-slate-700 dark:text-slate-300">{{ isEn ? 'Current language:' : '当前语言：' }}</span>
           <Button
             size="sm"
             :variant="locale === 'zh-CN' ? 'primary' : 'outline'"
@@ -34,14 +34,16 @@
             variant="ghost"
             @click="setCustomOverride"
           >
-            应用自定义文案覆盖
+            {{ isEn ? 'Apply custom override' : '应用自定义文案覆盖' }}
           </Button>
         </div>
 
         <div class="grid grid-cols-1 gap-6 lg:grid-cols-2">
           <!-- Pagination -->
           <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
-            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">Pagination 分页导航</h3>
+            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">
+              {{ isEn ? 'Pagination' : 'Pagination 分页导航' }}
+            </h3>
             <Pagination
               :model-value="page"
               :total="80"
@@ -52,19 +54,20 @@
 
           <!-- EmptyState -->
           <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
-            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">EmptyState 缺省状态</h3>
-            <EmptyState description="请调整筛选条件或稍后重试" />
+            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">
+              {{ isEn ? 'EmptyState' : 'EmptyState 缺省状态' }}
+            </h3>
+            <EmptyState :description="emptyDescription" />
           </div>
         </div>
 
         <!-- DataTable -->
         <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
-          <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">DataTable 分页与空态</h3>
+          <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">
+            {{ isEn ? 'DataTable (Empty & pagination)' : 'DataTable 分页与空态' }}
+          </h3>
           <DataTable
-            :columns="[
-              { key: 'name', label: '服务' },
-              { key: 'status', label: '状态' }
-            ]"
+            :columns="tableColumns"
             :rows="[]"
             :page-size="5"
           />
@@ -72,9 +75,28 @@
 
         <!-- FileUpload -->
         <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
-          <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">FileUpload 上传拖拽与提示</h3>
+          <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">
+            {{ isEn ? 'FileUpload' : 'FileUpload 上传拖拽与提示' }}
+          </h3>
           <FileUpload accept=".png,.jpg" :max-size="1024 * 1024 * 5" />
         </div>
+
+        <!-- DatePicker & Combobox demo -->
+        <div class="grid grid-cols-1 gap-6 lg:grid-cols-2">
+          <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
+            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">
+              {{ isEn ? 'DatePicker' : 'DatePicker 日期选择' }}
+            </h3>
+            <DatePicker />
+          </div>
+
+          <div class="rounded-xl border border-slate-200 bg-white p-4 dark:border-slate-800 dark:bg-[#0F172A]">
+            <h3 class="mb-3 text-sm font-semibold text-slate-800 dark:text-slate-200">
+              {{ isEn ? 'Combobox' : 'Combobox 组合下拉框' }}
+            </h3>
+            <Combobox :options="[]" />
+          </div>
+        </div>
       </div>
     </DocExample>
 
@@ -86,22 +108,54 @@
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { provideLocale } from '@recloudstudio/ui'
 
 const { locale, setLocale } = provideLocale('zh-CN')
 const page = ref(2)
 
+const isEn = computed(() => locale.value === 'en-US')
+
+const emptyDescription = computed(() => {
+  return isEn.value
+    ? 'Please adjust filters or try again later.'
+    : '请调整筛选条件或稍后重试'
+})
+
+const tableColumns = computed(() => {
+  return isEn.value
+    ? [
+        { key: 'name', label: 'Service' },
+        { key: 'status', label: 'Status' }
+      ]
+    : [
+        { key: 'name', label: '服务' },
+        { key: 'status', label: '状态' }
+      ]
+})
+
 function setCustomOverride() {
-  setLocale('zh-CN', {
-    pagination: {
-      prev: '往回翻',
-      next: '往前翻'
-    },
-    empty: {
-      defaultTitle: '这里什么也没有找到呢'
-    }
-  })
+  if (isEn.value) {
+    setLocale('en-US', {
+      pagination: {
+        prev: 'Back',
+        next: 'Forward'
+      },
+      empty: {
+        defaultTitle: 'Nothing found here'
+      }
+    })
+  } else {
+    setLocale('zh-CN', {
+      pagination: {
+        prev: '往回翻',
+        next: '往前翻'
+      },
+      empty: {
+        defaultTitle: '这里什么也没有找到呢'
+      }
+    })
+  }
 }
 
 const usageCode = `// 1. 在根组件或插件中注入语言包
diff --git a/packages/ui/src/components/alert-dialog/AlertDialog.vue b/packages/ui/src/components/alert-dialog/AlertDialog.vue
index e8dd623..1a3eb50 100644
--- a/packages/ui/src/components/alert-dialog/AlertDialog.vue
+++ b/packages/ui/src/components/alert-dialog/AlertDialog.vue
@@ -19,12 +19,12 @@
         <div class="flex justify-end gap-2.5">
           <AlertDialogCancel as-child>
             <button class="inline-flex h-10 items-center justify-center rounded-lg px-4 text-sm font-medium text-slate-700 ring-1 ring-inset ring-slate-300 dark:text-slate-200 dark:ring-slate-700 transition-colors hover:bg-slate-50 dark:hover:bg-slate-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]">
-              {{ props.cancelText }}
+              {{ effectiveCancelText }}
             </button>
           </AlertDialogCancel>
           <AlertDialogAction as-child>
             <button :class="actionClasses">
-              {{ props.actionText }}
+              {{ effectiveActionText }}
             </button>
           </AlertDialogAction>
         </div>
@@ -40,6 +40,7 @@ import {
   AlertDialogTitle, AlertDialogDescription, AlertDialogCancel, AlertDialogAction
 } from 'reka-ui'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface AlertDialogProps {
   title?: string
@@ -53,12 +54,16 @@ export interface AlertDialogProps {
 const props = withDefaults(defineProps<AlertDialogProps>(), {
   title: '',
   description: '',
-  actionText: '确认',
-  cancelText: '取消',
+  actionText: undefined,
+  cancelText: undefined,
   destructive: false,
   class: ''
 })
 
+const alertLoc = useComponentLocale('alertDialog')
+const effectiveActionText = computed(() => props.actionText ?? alertLoc.value.confirm)
+const effectiveCancelText = computed(() => props.cancelText ?? alertLoc.value.cancel)
+
 const open = defineModel<boolean>('open', { default: false })
 
 const actionClasses = computed(() => {
diff --git a/packages/ui/src/components/code-block/CodeBlock.vue b/packages/ui/src/components/code-block/CodeBlock.vue
index a52f0f8..3f7f77a 100644
--- a/packages/ui/src/components/code-block/CodeBlock.vue
+++ b/packages/ui/src/components/code-block/CodeBlock.vue
@@ -11,18 +11,18 @@
         <span v-else class="h-2 w-2 shrink-0 rounded-full bg-[var(--code-accent)] shadow-[0_0_0_3px_rgb(59_130_246_/_0.12)]" aria-hidden="true" />
         <span v-if="filename" class="truncate font-mono text-xs font-medium text-[var(--code-foreground)]">{{ filename }}</span>
         <span v-if="language" class="font-mono text-[11px] font-semibold uppercase tracking-[0.1em] text-[var(--code-muted)]">{{ language }}</span>
-        <span v-if="collapsible" class="shrink-0 text-xs font-medium text-[var(--code-muted)]">{{ isCollapsed ? '展开代码' : '收起代码' }}</span>
+        <span v-if="collapsible" class="shrink-0 text-xs font-medium text-[var(--code-muted)]">{{ isCollapsed ? commonLoc.expandCode : commonLoc.collapseCode }}</span>
       </component>
       <button
         v-if="copyable"
         type="button"
         class="inline-flex shrink-0 items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium text-[var(--code-muted)] transition-colors hover:bg-[var(--code-hover)] hover:text-[var(--code-foreground)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--ring)]"
-        :aria-label="copied ? '代码已复制' : '复制代码'"
+        :aria-label="copied ? commonLoc.copied : commonLoc.copy"
         @click="copyCode"
       >
         <svg v-if="!copied" class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" /><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" /></svg>
         <svg v-else class="h-3.5 w-3.5 text-[var(--success)]" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 13 4 4L19 7" /></svg>
-        {{ copied ? '已复制' : '复制' }}
+        {{ copied ? commonLoc.copied : commonLoc.copy }}
       </button>
     </header>
 
@@ -39,6 +39,7 @@
 <script setup lang="ts">
 import { computed, onBeforeUnmount, onMounted, shallowRef, useId, watch } from 'vue'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface CodeBlockProps {
   code?: string
@@ -67,6 +68,7 @@ const props = withDefaults(defineProps<CodeBlockProps>(), {
 
 /** Collapsed state; only takes effect when `collapsible` is set. Works uncontrolled without v-model. */
 const collapsed = defineModel<boolean>('collapsed', { default: false })
+const commonLoc = useComponentLocale('common')
 
 const bodyId = useId()
 const copied = shallowRef(false)
diff --git a/packages/ui/src/components/combobox/Combobox.vue b/packages/ui/src/components/combobox/Combobox.vue
index 3f666f2..2a348c6 100644
--- a/packages/ui/src/components/combobox/Combobox.vue
+++ b/packages/ui/src/components/combobox/Combobox.vue
@@ -16,7 +16,7 @@
       >
         <ComboboxInput
           class="min-w-0 grow bg-transparent text-sm text-slate-900 outline-none placeholder:text-slate-400 disabled:cursor-not-allowed dark:text-slate-100"
-          :placeholder="placeholder"
+          :placeholder="effectivePlaceholder"
           :disabled="disabled"
           :id="field.id"
           :required="required"
@@ -27,7 +27,7 @@
         <ComboboxCancel
           v-if="!noClear"
           class="shrink-0 cursor-pointer text-slate-400 hover:text-slate-600 dark:hover:text-slate-200"
-          aria-label="清除"
+          :aria-label="comboboxLoc.clearAria"
         >
           <svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg>
         </ComboboxCancel>
@@ -64,7 +64,7 @@
               </ComboboxItem>
             </ComboboxGroup>
             <ComboboxEmpty class="px-3 py-6 text-center text-sm text-slate-400 dark:text-slate-500">
-              {{ emptyText }}
+              {{ effectiveEmptyText }}
             </ComboboxEmpty>
           </ComboboxViewport>
         </ComboboxContent>
@@ -92,23 +92,28 @@ import {
   ComboboxEmpty
 } from 'reka-ui'
 import Field from '../field/Field.vue'
+import { useComponentLocale } from '../../locale'
 import type { ComboboxOption, ComboboxProps } from './types'
 
 const props = withDefaults(defineProps<ComboboxProps>(), {
   modelValue: '',
   multiple: false,
-  placeholder: '搜索或选择...',
+  placeholder: undefined,
   id: undefined,
   label: '',
   hint: '',
   error: '',
   required: false,
-  emptyText: '无匹配项',
+  emptyText: undefined,
   noClear: false,
   disabled: false,
   class: ''
 })
 
+const comboboxLoc = useComponentLocale('combobox')
+const effectivePlaceholder = computed(() => props.placeholder ?? comboboxLoc.value.placeholder)
+const effectiveEmptyText = computed(() => props.emptyText ?? comboboxLoc.value.emptyText)
+
 defineEmits<{
   (e: 'update:modelValue', value: string | string[]): void
 }>()
diff --git a/packages/ui/src/components/date-picker/DatePicker.vue b/packages/ui/src/components/date-picker/DatePicker.vue
index 2a07281..c0fa169 100644
--- a/packages/ui/src/components/date-picker/DatePicker.vue
+++ b/packages/ui/src/components/date-picker/DatePicker.vue
@@ -5,15 +5,15 @@
       <PopoverTrigger as-child>
         <button type="button" :disabled="disabled" class="flex h-10 w-full items-center gap-2 rounded-lg bg-white px-3.5 text-left text-sm text-slate-900 shadow-xs ring-1 ring-inset ring-slate-300 transition-all hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] disabled:cursor-not-allowed disabled:opacity-50 dark:bg-[#0F172A] dark:text-slate-100 dark:ring-slate-700 dark:hover:bg-slate-900 dark:focus-visible:ring-[#70ACFE]">
           <svg class="h-4 w-4 shrink-0 text-slate-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="5" width="18" height="16" rx="2"/><path d="M16 3v4M8 3v4M3 11h18" /></svg>
-          <span :class="displayValue ? '' : 'text-slate-400 dark:text-slate-500'">{{ displayValue || placeholder }}</span>
+          <span :class="displayValue ? '' : 'text-slate-400 dark:text-slate-500'">{{ displayValue || effectivePlaceholder }}</span>
         </button>
       </PopoverTrigger>
       <PopoverPortal>
         <PopoverContent side="bottom" align="start" :side-offset="6" class="z-50 w-[19rem] rounded-xl bg-white p-3 shadow-xl ring-1 ring-slate-200 outline-none dark:bg-[#0F172A] dark:ring-slate-800">
           <div class="mb-3 flex items-center justify-between">
-            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 hover:text-slate-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100" aria-label="上个月" @click="visibleMonth = addMonths(visibleMonth, -1)">‹</button>
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 hover:text-slate-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100" :aria-label="dateLoc.prevMonthAria" @click="visibleMonth = addMonths(visibleMonth, -1)">‹</button>
             <span class="text-sm font-semibold text-slate-800 dark:text-slate-100">{{ monthLabel }}</span>
-            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 hover:text-slate-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100" aria-label="下个月" @click="visibleMonth = addMonths(visibleMonth, 1)">›</button>
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 hover:text-slate-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100" :aria-label="dateLoc.nextMonthAria" @click="visibleMonth = addMonths(visibleMonth, 1)">›</button>
           </div>
           <div class="mb-1 grid grid-cols-7 text-center text-[11px] font-medium text-slate-400 dark:text-slate-500"><span v-for="day in weekdays" :key="day">{{ day }}</span></div>
           <div role="grid" :aria-label="monthLabel" class="grid grid-cols-7 gap-0.5">
@@ -30,6 +30,7 @@ import { computed, ref, watch } from 'vue'
 import { PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger } from 'reka-ui'
 import { addMonths, formatDate, monthDays, parseDateKey, toDateKey } from './dateUtils'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface DatePickerProps {
   modelValue?: string
@@ -42,11 +43,13 @@ export interface DatePickerProps {
   class?: string
 }
 
-const props = withDefaults(defineProps<DatePickerProps>(), { modelValue: '', placeholder: '选择日期', label: '', min: '', max: '', disabledDates: undefined, disabled: false, class: '' })
+const props = withDefaults(defineProps<DatePickerProps>(), { modelValue: '', placeholder: undefined, label: '', min: '', max: '', disabledDates: undefined, disabled: false, class: '' })
 const emit = defineEmits<{ (event: 'update:modelValue', value: string): void }>()
 const open = ref(false)
+const dateLoc = useComponentLocale('datePicker')
+const effectivePlaceholder = computed(() => props.placeholder ?? dateLoc.value.placeholder)
 const visibleMonth = ref(parseDateKey(props.modelValue) ?? new Date())
-const weekdays = ['一', '二', '三', '四', '五', '六', '日']
+const weekdays = computed(() => dateLoc.value.weekdays)
 const days = computed(() => monthDays(visibleMonth.value))
 const monthLabel = computed(() => new Intl.DateTimeFormat(undefined, { year: 'numeric', month: 'long' }).format(visibleMonth.value))
 const displayValue = computed(() => formatDate(props.modelValue))
diff --git a/packages/ui/src/components/date-picker/DateRangePicker.vue b/packages/ui/src/components/date-picker/DateRangePicker.vue
index 05240bf..8caab49 100644
--- a/packages/ui/src/components/date-picker/DateRangePicker.vue
+++ b/packages/ui/src/components/date-picker/DateRangePicker.vue
@@ -5,7 +5,7 @@
       <PopoverTrigger as-child>
         <button type="button" :disabled="disabled" class="flex h-10 w-full items-center gap-2 rounded-lg bg-white px-3.5 text-left text-sm text-slate-900 shadow-xs ring-1 ring-inset ring-slate-300 transition-all hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] disabled:cursor-not-allowed disabled:opacity-50 dark:bg-[#0F172A] dark:text-slate-100 dark:ring-slate-700 dark:hover:bg-slate-900 dark:focus-visible:ring-[#70ACFE]">
           <svg class="h-4 w-4 shrink-0 text-slate-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="5" width="18" height="16" rx="2"/><path d="M16 3v4M8 3v4M3 11h18" /></svg>
-          <span :class="displayValue ? '' : 'text-slate-400 dark:text-slate-500'">{{ displayValue || placeholder }}</span>
+          <span :class="displayValue ? '' : 'text-slate-400 dark:text-slate-500'">{{ displayValue || effectivePlaceholder }}</span>
         </button>
       </PopoverTrigger>
       <PopoverPortal>
@@ -14,15 +14,15 @@
             <button v-for="preset in presets" :key="preset.label" type="button" class="rounded-md px-2 py-1 text-xs font-medium text-slate-600 hover:bg-slate-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-300 dark:hover:bg-slate-800" @click="applyPreset(preset.value)">{{ preset.label }}</button>
           </div>
           <div class="mb-3 flex items-center justify-between">
-            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 dark:text-slate-400 dark:hover:bg-slate-800" aria-label="上个月" @click="visibleMonth = addMonths(visibleMonth, -1)">‹</button>
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 dark:text-slate-400 dark:hover:bg-slate-800" :aria-label="dateLoc.prevMonthAria" @click="visibleMonth = addMonths(visibleMonth, -1)">‹</button>
             <span class="text-sm font-semibold text-slate-800 dark:text-slate-100">{{ monthLabel }}</span>
-            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 dark:text-slate-400 dark:hover:bg-slate-800" aria-label="下个月" @click="visibleMonth = addMonths(visibleMonth, 1)">›</button>
+            <button type="button" class="grid h-8 w-8 place-items-center rounded-md text-slate-500 hover:bg-slate-100 dark:text-slate-400 dark:hover:bg-slate-800" :aria-label="dateLoc.nextMonthAria" @click="visibleMonth = addMonths(visibleMonth, 1)">›</button>
           </div>
           <div class="mb-1 grid grid-cols-7 text-center text-[11px] font-medium text-slate-400 dark:text-slate-500"><span v-for="day in weekdays" :key="day">{{ day }}</span></div>
           <div role="grid" :aria-label="monthLabel" class="grid grid-cols-7 gap-0.5">
             <button v-for="day in days" :key="day.key" type="button" role="gridcell" :disabled="isDisabled(day.key)" :aria-selected="isSelected(day.key)" :class="dayClasses(day)" @click="selectDay(day.key)">{{ day.date.getDate() }}</button>
           </div>
-          <p v-if="pendingStart" class="mt-3 text-center text-xs text-slate-500 dark:text-slate-400">已选择开始日期，请选择结束日期。</p>
+          <p v-if="pendingStart" class="mt-3 text-center text-xs text-slate-500 dark:text-slate-400">{{ dateLoc.pendingRangeEnd }}</p>
         </PopoverContent>
       </PopoverPortal>
     </PopoverRoot>
@@ -34,6 +34,7 @@ import { computed, ref, watch } from 'vue'
 import { PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger } from 'reka-ui'
 import { addMonths, compareDateKeys, formatDate, monthDays, parseDateKey, toDateKey, type DateRangeValue } from './dateUtils'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface DateRangePreset { label: string; value: DateRangeValue }
 export interface DateRangePickerProps {
@@ -48,12 +49,14 @@ export interface DateRangePickerProps {
   class?: string
 }
 
-const props = withDefaults(defineProps<DateRangePickerProps>(), { modelValue: undefined, placeholder: '选择日期范围', label: '', min: '', max: '', disabledDates: undefined, presets: () => [], disabled: false, class: '' })
+const props = withDefaults(defineProps<DateRangePickerProps>(), { modelValue: undefined, placeholder: undefined, label: '', min: '', max: '', disabledDates: undefined, presets: () => [], disabled: false, class: '' })
 const emit = defineEmits<{ (event: 'update:modelValue', value: DateRangeValue | undefined): void }>()
 const open = ref(false)
 const pendingStart = ref<string>()
+const dateLoc = useComponentLocale('datePicker')
+const effectivePlaceholder = computed(() => props.placeholder ?? dateLoc.value.rangePlaceholder)
 const visibleMonth = ref(parseDateKey(props.modelValue?.start) ?? new Date())
-const weekdays = ['一', '二', '三', '四', '五', '六', '日']
+const weekdays = computed(() => dateLoc.value.weekdays)
 const days = computed(() => monthDays(visibleMonth.value))
 const monthLabel = computed(() => new Intl.DateTimeFormat(undefined, { year: 'numeric', month: 'long' }).format(visibleMonth.value))
 const displayValue = computed(() => props.modelValue ? `${formatDate(props.modelValue.start)} — ${formatDate(props.modelValue.end)}` : '')
diff --git a/packages/ui/src/components/dialog/Dialog.vue b/packages/ui/src/components/dialog/Dialog.vue
index 733f0d9..db87265 100644
--- a/packages/ui/src/components/dialog/Dialog.vue
+++ b/packages/ui/src/components/dialog/Dialog.vue
@@ -25,7 +25,7 @@
           <slot name="footer" />
         </div>
 
-        <DialogClose aria-label="关闭" class="absolute right-3.5 top-3.5 rounded-md p-1 text-slate-400 hover:text-slate-600 hover:bg-slate-100 dark:text-slate-500 dark:hover:text-slate-300 dark:hover:bg-slate-800 transition-colors">
+        <DialogClose :aria-label="commonLoc.close" class="absolute right-3.5 top-3.5 rounded-md p-1 text-slate-400 hover:text-slate-600 hover:bg-slate-100 dark:text-slate-500 dark:hover:text-slate-300 dark:hover:bg-slate-800 transition-colors">
           <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
             <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
           </svg>
@@ -48,6 +48,7 @@ import {
   DialogTrigger
 } from 'reka-ui'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface DialogProps {
   open?: boolean
@@ -63,6 +64,8 @@ const props = withDefaults(defineProps<DialogProps>(), {
   class: ''
 })
 
+const commonLoc = useComponentLocale('common')
+
 defineEmits<{
   (e: 'update:open', value: boolean): void
 }>()
diff --git a/packages/ui/src/components/editable/Editable.vue b/packages/ui/src/components/editable/Editable.vue
index e68a211..61135a3 100644
--- a/packages/ui/src/components/editable/Editable.vue
+++ b/packages/ui/src/components/editable/Editable.vue
@@ -2,7 +2,7 @@
   <EditableRoot
     v-slot="{ isEditing }"
     :model-value="modelValue"
-    :placeholder="placeholder"
+    :placeholder="effectivePlaceholder"
     :disabled="disabled"
     :readonly="readonly"
     select-on-focus
@@ -23,13 +23,13 @@
       <template v-if="isEditing">
         <EditableSubmitTrigger
           class="inline-flex size-6 cursor-pointer items-center justify-center rounded-md text-emerald-600 transition-colors hover:bg-emerald-50 dark:text-emerald-400 dark:hover:bg-emerald-500/10"
-          aria-label="保存"
+          :aria-label="commonLoc.save"
         >
           <svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7" /></svg>
         </EditableSubmitTrigger>
         <EditableCancelTrigger
           class="inline-flex size-6 cursor-pointer items-center justify-center rounded-md text-slate-400 transition-colors hover:bg-slate-100 dark:hover:bg-slate-800"
-          aria-label="取消"
+          :aria-label="commonLoc.cancel"
         >
           <svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg>
         </EditableCancelTrigger>
@@ -37,7 +37,7 @@
       <EditTrigger
         v-else
         class="inline-flex size-6 cursor-pointer items-center justify-center rounded-md text-slate-400 opacity-0 transition-all group-hover:opacity-100 hover:bg-slate-100 dark:hover:bg-slate-800"
-        aria-label="编辑"
+        :aria-label="commonLoc.edit"
       >
         <svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M12 20h9M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z" /></svg>
       </EditTrigger>
@@ -46,6 +46,7 @@
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue'
 import {
   EditableRoot,
   EditableArea,
@@ -55,6 +56,7 @@ import {
   EditableCancelTrigger,
   EditableEditTrigger as EditTrigger
 } from 'reka-ui'
+import { useComponentLocale } from '../../locale'
 
 export interface EditableProps {
   modelValue?: string
@@ -66,7 +68,7 @@ export interface EditableProps {
 
 const props = withDefaults(defineProps<EditableProps>(), {
   modelValue: '',
-  placeholder: '点击编辑...',
+  placeholder: undefined,
   disabled: false,
   readonly: false,
   class: ''
@@ -75,4 +77,7 @@ const props = withDefaults(defineProps<EditableProps>(), {
 defineEmits<{
   (e: 'update:modelValue', value: string): void
 }>()
+
+const commonLoc = useComponentLocale('common')
+const effectivePlaceholder = computed(() => props.placeholder ?? commonLoc.value.edit)
 </script>
diff --git a/packages/ui/src/components/file-upload/FileUpload.vue b/packages/ui/src/components/file-upload/FileUpload.vue
index a822b40..eb3d1db 100644
--- a/packages/ui/src/components/file-upload/FileUpload.vue
+++ b/packages/ui/src/components/file-upload/FileUpload.vue
@@ -24,7 +24,7 @@
         <img v-if="item.previewUrl" :src="item.previewUrl" :alt="item.file.name" class="h-10 w-10 rounded-lg object-cover ring-1 ring-slate-200 dark:ring-slate-700" />
         <div v-else class="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-slate-100 text-xs font-bold uppercase text-slate-500 dark:bg-slate-800 dark:text-slate-400">{{ fileExtension(item.file.name) }}</div>
         <div class="min-w-0 grow"><div class="flex items-center gap-2"><p class="truncate text-sm font-medium text-slate-800 dark:text-slate-100">{{ item.file.name }}</p><span :class="statusClass(item.status)">{{ statusLabel(item.status) }}</span></div><p v-if="item.error" class="mt-0.5 text-xs text-red-600 dark:text-red-400">{{ item.error }}</p><p v-else class="mt-0.5 text-xs text-slate-500 dark:text-slate-400">{{ formatSize(item.file.size) }}</p><div v-if="item.status === 'uploading'" class="mt-2 h-1.5 overflow-hidden rounded-full bg-slate-100 dark:bg-slate-800"><div class="h-full rounded-full bg-[#2563EB] transition-[width] duration-200 dark:bg-[#70ACFE]" :style="{ width: `${item.progress ?? 0}%` }" /></div></div>
-        <div class="flex shrink-0 items-center gap-1"><button v-if="item.status === 'uploading'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-slate-500 transition-colors hover:bg-slate-100 hover:text-red-600 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-red-400" :aria-label="`取消上传 ${item.file.name}`" @click="cancel(item.id)"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 6 12 12M18 6 6 18"/></svg></button><button v-else-if="item.status === 'error' || item.status === 'cancelled'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-[#2563EB] transition-colors hover:bg-slate-100 dark:text-[#70ACFE] dark:hover:bg-slate-800" :aria-label="`重试上传 ${item.file.name}`" @click="retry(item.id)"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="h-4 w-4"><path d="M20 11a8 8 0 1 0 2 5.5"/><path d="M20 4v7h-7"/></svg></button><button v-if="item.status !== 'uploading'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-slate-400 transition-colors hover:bg-slate-100 hover:text-red-600 dark:hover:bg-slate-800 dark:hover:text-red-400" :aria-label="`移除 ${item.file.name}`" @click="remove(item.id)"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 6 12 12M18 6 6 18"/></svg></button></div>
+        <div class="flex shrink-0 items-center gap-1"><button v-if="item.status === 'uploading'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-slate-500 transition-colors hover:bg-slate-100 hover:text-red-600 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-red-400" :aria-label="loc.cancelAria(item.file.name)" @click="cancel(item.id)"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 6 12 12M18 6 6 18"/></svg></button><button v-else-if="item.status === 'error' || item.status === 'cancelled'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-[#2563EB] transition-colors hover:bg-slate-100 dark:text-[#70ACFE] dark:hover:bg-slate-800" :aria-label="loc.retryAria(item.file.name)" @click="retry(item.id)"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="h-4 w-4"><path d="M20 11a8 8 0 1 0 2 5.5"/><path d="M20 4v7h-7"/></svg></button><button v-if="item.status !== 'uploading'" type="button" class="inline-flex h-8 w-8 items-center justify-center rounded-lg text-slate-400 transition-colors hover:bg-slate-100 hover:text-red-600 dark:hover:bg-slate-800 dark:hover:text-red-400" :aria-label="loc.removeAria(item.file.name)" @click="remove(item.id)"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 6 12 12M18 6 6 18"/></svg></button></div>
       </li>
     </ul>
   </div>
diff --git a/packages/ui/src/components/multi-select/MultiSelect.vue b/packages/ui/src/components/multi-select/MultiSelect.vue
index 387d3b9..2638151 100644
--- a/packages/ui/src/components/multi-select/MultiSelect.vue
+++ b/packages/ui/src/components/multi-select/MultiSelect.vue
@@ -3,12 +3,12 @@
     <template #default="field">
       <ComboboxRoot v-model:open="open" :model-value="props.modelValue" :multiple="true" :disabled="props.disabled" class="w-full" @update:model-value="updateValue">
         <ComboboxAnchor :class="cn('flex min-h-10 w-full flex-wrap items-center gap-1.5 rounded-lg bg-white px-2 py-1.5 text-sm shadow-xs ring-1 ring-inset transition-all focus-within:ring-2 dark:bg-[#0F172A]', props.error ? 'ring-red-500 focus-within:ring-red-500' : 'ring-slate-300 focus-within:ring-[#2563EB] dark:ring-slate-700 dark:focus-within:ring-[#70ACFE]', props.disabled && 'cursor-not-allowed bg-slate-50 opacity-50 dark:bg-slate-900/60', props.class)" :aria-describedby="field.describedby" :aria-invalid="field.invalid || undefined">
-          <span v-for="option in selectedOptions" :key="option.value" class="inline-flex max-w-full items-center gap-1 rounded-md bg-blue-50 px-2 py-0.5 text-xs font-medium text-[#1E63CE] dark:bg-blue-950/60 dark:text-[#70ACFE]">{{ option.label }}<button type="button" :disabled="props.disabled" :aria-label="`移除 ${option.label}`" class="inline-flex h-3.5 w-3.5 items-center justify-center rounded-full text-blue-400 hover:bg-blue-100 hover:text-blue-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-blue-500 dark:hover:bg-blue-900" @click.stop="remove(option.value)"><svg class="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg></button></span>
-          <ComboboxInput :id="field.id" :required="props.required && !props.modelValue.length" :placeholder="props.modelValue.length ? '' : props.placeholder" :disabled="props.disabled" class="min-w-24 grow bg-transparent px-1 py-0.5 text-sm text-slate-900 outline-none placeholder:text-slate-400 disabled:cursor-not-allowed dark:text-slate-100" :display-value="() => ''" />
-          <button v-if="props.clearable && props.modelValue.length" type="button" :disabled="props.disabled" class="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-slate-400 hover:bg-slate-100 hover:text-slate-600 dark:hover:bg-slate-800 dark:hover:text-slate-200" aria-label="清除所有选择" @click.stop="clear"><svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg></button>
+          <span v-for="option in selectedOptions" :key="option.value" class="inline-flex max-w-full items-center gap-1 rounded-md bg-blue-50 px-2 py-0.5 text-xs font-medium text-[#1E63CE] dark:bg-blue-950/60 dark:text-[#70ACFE]">{{ option.label }}<button type="button" :disabled="props.disabled" :aria-label="multiLoc.removeAria(option.label)" class="inline-flex h-3.5 w-3.5 items-center justify-center rounded-full text-blue-400 hover:bg-blue-100 hover:text-blue-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-blue-500 dark:hover:bg-blue-900" @click.stop="remove(option.value)"><svg class="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg></button></span>
+          <ComboboxInput :id="field.id" :required="props.required && !props.modelValue.length" :placeholder="props.modelValue.length ? '' : effectivePlaceholder" :disabled="props.disabled" class="min-w-24 grow bg-transparent px-1 py-0.5 text-sm text-slate-900 outline-none placeholder:text-slate-400 disabled:cursor-not-allowed dark:text-slate-100" :display-value="() => ''" />
+          <button v-if="props.clearable && props.modelValue.length" type="button" :disabled="props.disabled" class="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-slate-400 hover:bg-slate-100 hover:text-slate-600 dark:hover:bg-slate-800 dark:hover:text-slate-200" :aria-label="multiLoc.clearAria" @click.stop="clear"><svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" /></svg></button>
           <ComboboxTrigger class="shrink-0 text-slate-400 dark:text-slate-500"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="m7 15 5 5 5-5M7 9l5-5 5 5" /></svg></ComboboxTrigger>
         </ComboboxAnchor>
-        <ComboboxPortal><ComboboxContent position="popper" :side-offset="4" class="z-50 max-h-72 w-[var(--reka-combobox-trigger-width,280px)] overflow-hidden rounded-lg bg-white text-slate-900 shadow-md ring-1 ring-inset ring-slate-200 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:bg-[#0F172A] dark:text-slate-100 dark:ring-slate-800"><ComboboxViewport class="p-1"><ComboboxGroup v-for="group in groupedOptions" :key="group.name ?? '__default__'"><ComboboxLabel v-if="group.name" class="px-2 pt-2 pb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400 dark:text-slate-500">{{ group.name }}</ComboboxLabel><ComboboxItem v-for="option in group.options" :key="option.value" :value="option.value" :disabled="option.disabled" class="relative flex w-full cursor-pointer select-none items-center rounded-md py-1.5 pr-8 pl-3 text-sm outline-none transition-colors hover:bg-slate-100 focus:bg-slate-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-50 dark:hover:bg-slate-800 dark:focus:bg-slate-800">{{ option.label }}<ComboboxItemIndicator class="absolute right-2 text-[#2563EB] dark:text-[#70ACFE]"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7" /></svg></ComboboxItemIndicator></ComboboxItem></ComboboxGroup><ComboboxEmpty class="px-3 py-6 text-center text-sm text-slate-400 dark:text-slate-500">{{ props.emptyText }}</ComboboxEmpty></ComboboxViewport></ComboboxContent></ComboboxPortal>
+        <ComboboxPortal><ComboboxContent position="popper" :side-offset="4" class="z-50 max-h-72 w-[var(--reka-combobox-trigger-width,280px)] overflow-hidden rounded-lg bg-white text-slate-900 shadow-md ring-1 ring-inset ring-slate-200 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:bg-[#0F172A] dark:text-slate-100 dark:ring-slate-800"><ComboboxViewport class="p-1"><ComboboxGroup v-for="group in groupedOptions" :key="group.name ?? '__default__'"><ComboboxLabel v-if="group.name" class="px-2 pt-2 pb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400 dark:text-slate-500">{{ group.name }}</ComboboxLabel><ComboboxItem v-for="option in group.options" :key="option.value" :value="option.value" :disabled="option.disabled" class="relative flex w-full cursor-pointer select-none items-center rounded-md py-1.5 pr-8 pl-3 text-sm outline-none transition-colors hover:bg-slate-100 focus:bg-slate-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-50 dark:hover:bg-slate-800 dark:focus:bg-slate-800">{{ option.label }}<ComboboxItemIndicator class="absolute right-2 text-[#2563EB] dark:text-[#70ACFE]"><svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7" /></svg></ComboboxItemIndicator></ComboboxItem></ComboboxGroup><ComboboxEmpty class="px-3 py-6 text-center text-sm text-slate-400 dark:text-slate-500">{{ effectiveEmptyText }}</ComboboxEmpty></ComboboxViewport></ComboboxContent></ComboboxPortal>
       </ComboboxRoot>
     </template>
   </Field>
@@ -19,9 +19,13 @@ import { computed, ref } from 'vue'
 import { ComboboxAnchor, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxLabel, ComboboxPortal, ComboboxRoot, ComboboxTrigger, ComboboxViewport } from 'reka-ui'
 import { cn } from '../../utils/cn'
 import Field from '../field/Field.vue'
+import { useComponentLocale } from '../../locale'
 import type { MultiSelectOption, MultiSelectProps } from './types'
-const props = withDefaults(defineProps<MultiSelectProps>(), { modelValue: () => [], placeholder: '搜索并选择...', id: undefined, label: '', hint: '', error: '', required: false, emptyText: '无匹配项', clearable: true, disabled: false, class: '' })
+const props = withDefaults(defineProps<MultiSelectProps>(), { modelValue: () => [], placeholder: undefined, id: undefined, label: '', hint: '', error: '', required: false, emptyText: undefined, clearable: true, disabled: false, class: '' })
 const emit = defineEmits<{ (event: 'update:modelValue', value: string[]): void; (event: 'clear'): void }>()
+const multiLoc = useComponentLocale('multiSelect')
+const effectivePlaceholder = computed(() => props.placeholder ?? multiLoc.value.placeholder)
+const effectiveEmptyText = computed(() => props.emptyText ?? multiLoc.value.emptyText)
 const open = ref(false)
 const selectedOptions = computed(() => props.modelValue.map((value) => props.options.find((option) => option.value === value)).filter((option): option is MultiSelectOption => Boolean(option)))
 const groupedOptions = computed(() => { const groups: { name?: string; options: MultiSelectOption[] }[] = []; for (const option of props.options) { const previous = groups.at(-1); if (previous && previous.name === option.group) previous.options.push(option); else groups.push({ name: option.group, options: [option] }) } return groups })
diff --git a/packages/ui/src/components/select/Select.vue b/packages/ui/src/components/select/Select.vue
index 70eb8f0..bb36c9e 100644
--- a/packages/ui/src/components/select/Select.vue
+++ b/packages/ui/src/components/select/Select.vue
@@ -13,7 +13,7 @@
         :aria-required="required || undefined"
         :class="triggerClasses"
       >
-        <SelectValue :placeholder="placeholder" />
+        <SelectValue :placeholder="effectivePlaceholder" />
         <SelectIcon class="text-slate-400 dark:text-slate-500">
           <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
             <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
@@ -66,6 +66,7 @@ import {
 } from 'reka-ui'
 import { cn } from '../../utils/cn'
 import Field from '../field/Field.vue'
+import { useComponentLocale } from '../../locale'
 
 export interface SelectOption {
   label: string
@@ -88,7 +89,7 @@ export interface SelectProps {
 
 const props = withDefaults(defineProps<SelectProps>(), {
   modelValue: '',
-  placeholder: '请选择...',
+  placeholder: undefined,
   id: undefined,
   label: '',
   hint: '',
@@ -98,6 +99,9 @@ const props = withDefaults(defineProps<SelectProps>(), {
   class: ''
 })
 
+const selectLoc = useComponentLocale('select')
+const effectivePlaceholder = computed(() => props.placeholder ?? selectLoc.value.placeholder)
+
 defineEmits<{
   (e: 'update:modelValue', value: string): void
 }>()
diff --git a/packages/ui/src/components/sheet/Sheet.vue b/packages/ui/src/components/sheet/Sheet.vue
index aa51f08..93d326e 100644
--- a/packages/ui/src/components/sheet/Sheet.vue
+++ b/packages/ui/src/components/sheet/Sheet.vue
@@ -15,7 +15,7 @@
 
         <div v-if="$slots.footer" class="shrink-0 border-t border-slate-200 px-5 py-4 dark:border-slate-800"><slot name="footer" /></div>
 
-        <DialogClose aria-label="关闭" class="absolute top-3.5 right-3.5 rounded-md p-1 text-slate-400 transition-colors hover:bg-slate-100 hover:text-slate-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-500 dark:hover:bg-slate-800 dark:hover:text-slate-300">
+        <DialogClose :aria-label="commonLoc.close" class="absolute top-3.5 right-3.5 rounded-md p-1 text-slate-400 transition-colors hover:bg-slate-100 hover:text-slate-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-500 dark:hover:bg-slate-800 dark:hover:text-slate-300">
           <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" /></svg>
         </DialogClose>
       </DialogContent>
@@ -27,6 +27,7 @@
 import { computed } from 'vue'
 import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from 'reka-ui'
 import { cn } from '../../utils/cn'
+import { useComponentLocale } from '../../locale'
 
 export interface SheetProps {
   open?: boolean
@@ -47,6 +48,8 @@ const props = withDefaults(defineProps<SheetProps>(), {
   class: ''
 })
 
+const commonLoc = useComponentLocale('common')
+
 defineEmits<{
   (event: 'update:open', value: boolean): void
 }>()
diff --git a/packages/ui/src/components/table/DataTable.vue b/packages/ui/src/components/table/DataTable.vue
index 11defcf..98e8a69 100644
--- a/packages/ui/src/components/table/DataTable.vue
+++ b/packages/ui/src/components/table/DataTable.vue
@@ -4,7 +4,7 @@
     <div class="overflow-x-auto">
       <table class="w-full border-collapse text-left text-sm">
         <thead><tr class="border-b border-slate-200 bg-slate-50/80 dark:border-slate-800 dark:bg-slate-900/60">
-          <th v-if="selectable" class="w-11 px-4 py-2.5"><input type="checkbox" :checked="allPageSelected" :indeterminate="somePageSelected" aria-label="选择当前页所有行" class="h-4 w-4 accent-[#2563EB]" @change="togglePageSelection" /></th>
+          <th v-if="selectable" class="w-11 px-4 py-2.5"><input type="checkbox" :checked="allPageSelected" :indeterminate="somePageSelected" :aria-label="tableLoc.selectAllAria" class="h-4 w-4 accent-[#2563EB]" @change="togglePageSelection" /></th>
           <th v-for="col in visibleColumns" :key="col.key" :style="col.width ? { width: col.width } : undefined" :class="cn('px-4 py-2.5 text-xs font-semibold uppercase tracking-wider text-slate-500 dark:text-slate-400 whitespace-nowrap', alignClass(col.align))">
             <button v-if="col.sortable" type="button" class="inline-flex items-center gap-1 hover:text-slate-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:hover:text-slate-100" @click="toggleSort(col.key)">{{ col.label }}<span aria-hidden="true" class="text-slate-400">{{ sortIcon(col.key) }}</span></button>
             <span v-else>{{ col.label }}</span>
@@ -12,7 +12,7 @@
         </tr></thead>
         <tbody v-if="!loading && !error && pagedRows.length" :class="props.divide ? 'divide-y divide-slate-100 dark:divide-slate-800' : ''">
           <tr v-for="(row, index) in pagedRows" :key="rowKey(row, index)" :class="cn('transition-colors', hoverable ? 'hover:bg-slate-50/70 dark:hover:bg-slate-900/40' : '', isSelected(row, index) && 'bg-blue-50/70 dark:bg-blue-950/20')">
-            <td v-if="selectable" class="px-4 py-3"><input type="checkbox" :checked="isSelected(row, index)" :aria-label="`选择第 ${index + 1} 行`" class="h-4 w-4 accent-[#2563EB]" @change="toggleRow(row, index)" /></td>
+            <td v-if="selectable" class="px-4 py-3"><input type="checkbox" :checked="isSelected(row, index)" :aria-label="tableLoc.selectRowAria(index + 1)" class="h-4 w-4 accent-[#2563EB]" @change="toggleRow(row, index)" /></td>
             <td v-for="col in visibleColumns" :key="col.key" :class="cn('px-4 py-3 align-middle text-slate-700 dark:text-slate-300', alignClass(col.align))"><slot v-if="col.slot" :name="`cell-${col.key}`" :row="row" :value="row[col.key]" :index="index" /><span v-else class="whitespace-nowrap">{{ formatCell(row[col.key]) }}</span></td>
           </tr>
         </tbody>
@@ -58,6 +58,7 @@ const emit = defineEmits<{ (event: 'update:selected', value: Array<string | numb
 const emptyLoc = useComponentLocale('empty')
 const paginationLoc = useComponentLocale('pagination')
 const commonLoc = useComponentLocale('common')
+const tableLoc = useComponentLocale('table')
 const effectiveEmptyText = computed(() => props.emptyText ?? emptyLoc.value.defaultTitle)
 const visibleColumns = computed(() => props.visibleColumnKeys ? props.columns.filter((column) => props.visibleColumnKeys!.includes(column.key)) : props.columns)
 const showPagination = computed(() => props.pageSize > 0)
diff --git a/packages/ui/src/components/tag-input/TagInput.vue b/packages/ui/src/components/tag-input/TagInput.vue
index a145e23..0f4eedf 100644
--- a/packages/ui/src/components/tag-input/TagInput.vue
+++ b/packages/ui/src/components/tag-input/TagInput.vue
@@ -22,7 +22,7 @@
             <button
               type="button"
               class="inline-flex h-3.5 w-3.5 items-center justify-center rounded-full text-blue-400 hover:bg-blue-100 hover:text-blue-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-blue-500 dark:hover:bg-blue-900 dark:hover:text-blue-300"
-              :aria-label="`移除 ${tag}`"
+              :aria-label="multiLoc.removeAria(tag)"
               :disabled="disabled"
               @click="removeTag(index)"
             >
@@ -34,13 +34,13 @@
           <input
             ref="inputRef"
             :value="draft"
-            :placeholder="modelValue.length === 0 ? placeholder : ''"
+            :placeholder="modelValue.length === 0 ? effectivePlaceholder : ''"
             :disabled="disabled"
             :required="required && modelValue.length === 0"
             :id="field.id"
             :aria-describedby="field.describedby"
             :aria-invalid="field.invalid || undefined"
-            :aria-label="label || placeholder"
+            :aria-label="label || effectivePlaceholder"
             class="min-w-20 grow bg-transparent px-1.5 py-1 text-slate-900 outline-none placeholder:text-slate-400 disabled:cursor-not-allowed dark:text-slate-100"
             @input="onInput"
             @keydown="onKeydown"
@@ -57,6 +57,7 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import Field from '../field/Field.vue'
+import { useComponentLocale } from '../../locale'
 
 export interface TagInputProps {
   modelValue?: string[]
@@ -77,7 +78,7 @@ export interface TagInputProps {
 
 const props = withDefaults(defineProps<TagInputProps>(), {
   modelValue: () => [],
-  placeholder: '输入标签...',
+  placeholder: undefined,
   separator: ',',
   id: undefined,
   label: '',
@@ -92,6 +93,9 @@ const props = withDefaults(defineProps<TagInputProps>(), {
   class: ''
 })
 
+const multiLoc = useComponentLocale('multiSelect')
+const effectivePlaceholder = computed(() => props.placeholder ?? multiLoc.value.placeholder)
+
 const emit = defineEmits<{
   (e: 'update:modelValue', value: string[]): void
   (e: 'focus', event: FocusEvent): void
diff --git a/packages/ui/src/locale/messages.ts b/packages/ui/src/locale/messages.ts
index 6a5cb87..819af4a 100644
--- a/packages/ui/src/locale/messages.ts
+++ b/packages/ui/src/locale/messages.ts
@@ -8,6 +8,13 @@ export interface LocaleMessages {
     search: string
     loading: string
     noData: string
+    clear: string
+    save: string
+    edit: string
+    copy: string
+    copied: string
+    expandCode: string
+    collapseCode: string
   }
   pagination: {
     prev: string
@@ -42,6 +49,9 @@ export interface LocaleMessages {
     statusSuccess: string
     statusError: string
     statusCancelled: string
+    cancelAria: (name: string) => string
+    retryAria: (name: string) => string
+    removeAria: (name: string) => string
   }
   tree: {
     selectedBadge: string
@@ -50,6 +60,40 @@ export interface LocaleMessages {
     selectNode: (label: string) => string
     label: string
   }
+  table: {
+    selectAllAria: string
+    selectRowAria: (index: number) => string
+  }
+  select: {
+    placeholder: string
+  }
+  combobox: {
+    placeholder: string
+    emptyText: string
+    clearAria: string
+  }
+  multiSelect: {
+    placeholder: string
+    emptyText: string
+    clearAria: string
+    removeAria: (label: string) => string
+  }
+  datePicker: {
+    placeholder: string
+    rangePlaceholder: string
+    prevMonthAria: string
+    nextMonthAria: string
+    pendingRangeEnd: string
+    weekdays: string[]
+  }
+  appShell: {
+    sidebarLabel: string
+    resizeHandleAria: string
+  }
+  alertDialog: {
+    confirm: string
+    cancel: string
+  }
 }
 
 export type DeepPartial<T> = {
@@ -69,7 +113,14 @@ export const zhCN: LocaleMessages = {
     remove: '移除',
     search: '搜索',
     loading: '加载中',
-    noData: '暂无数据'
+    noData: '暂无数据',
+    clear: '清除',
+    save: '保存',
+    edit: '编辑',
+    copy: '复制',
+    copied: '已复制',
+    expandCode: '展开代码',
+    collapseCode: '收起代码'
   },
   pagination: {
     prev: '上一页',
@@ -103,7 +154,10 @@ export const zhCN: LocaleMessages = {
     statusUploading: '上传中',
     statusSuccess: '已完成',
     statusError: '失败',
-    statusCancelled: '已取消'
+    statusCancelled: '已取消',
+    cancelAria: (name) => `取消上传 ${name}`,
+    retryAria: (name) => `重试上传 ${name}`,
+    removeAria: (name) => `移除 ${name}`
   },
   tree: {
     selectedBadge: '已选',
@@ -111,6 +165,40 @@ export const zhCN: LocaleMessages = {
     expandNode: (label) => `展开 ${label}`,
     selectNode: (label) => `选择 ${label}`,
     label: '树形目录'
+  },
+  table: {
+    selectAllAria: '选择当前页所有行',
+    selectRowAria: (index) => `选择第 ${index} 行`
+  },
+  select: {
+    placeholder: '请选择...'
+  },
+  combobox: {
+    placeholder: '搜索或选择...',
+    emptyText: '无匹配项',
+    clearAria: '清除'
+  },
+  multiSelect: {
+    placeholder: '搜索并选择...',
+    emptyText: '无匹配项',
+    clearAria: '清除所有选择',
+    removeAria: (label) => `移除 ${label}`
+  },
+  datePicker: {
+    placeholder: '选择日期',
+    rangePlaceholder: '选择日期范围',
+    prevMonthAria: '上个月',
+    nextMonthAria: '下个月',
+    pendingRangeEnd: '已选择开始日期，请选择结束日期。',
+    weekdays: ['一', '二', '三', '四', '五', '六', '日']
+  },
+  appShell: {
+    sidebarLabel: '侧边导航',
+    resizeHandleAria: '调整面板大小'
+  },
+  alertDialog: {
+    confirm: '确认',
+    cancel: '取消'
   }
 }
 
@@ -123,7 +211,14 @@ export const enUS: LocaleMessages = {
     remove: 'Remove',
     search: 'Search',
     loading: 'Loading',
-    noData: 'No data'
+    noData: 'No data',
+    clear: 'Clear',
+    save: 'Save',
+    edit: 'Edit',
+    copy: 'Copy',
+    copied: 'Copied',
+    expandCode: 'Expand code',
+    collapseCode: 'Collapse code'
   },
   pagination: {
     prev: 'Previous',
@@ -157,7 +252,10 @@ export const enUS: LocaleMessages = {
     statusUploading: 'Uploading',
     statusSuccess: 'Completed',
     statusError: 'Failed',
-    statusCancelled: 'Cancelled'
+    statusCancelled: 'Cancelled',
+    cancelAria: (name) => `Cancel upload for ${name}`,
+    retryAria: (name) => `Retry upload for ${name}`,
+    removeAria: (name) => `Remove ${name}`
   },
   tree: {
     selectedBadge: 'Selected',
@@ -165,5 +263,39 @@ export const enUS: LocaleMessages = {
     expandNode: (label) => `Expand ${label}`,
     selectNode: (label) => `Select ${label}`,
     label: 'Tree View'
+  },
+  table: {
+    selectAllAria: 'Select all rows on current page',
+    selectRowAria: (index) => `Select row ${index}`
+  },
+  select: {
+    placeholder: 'Please select...'
+  },
+  combobox: {
+    placeholder: 'Search or select...',
+    emptyText: 'No matching results',
+    clearAria: 'Clear'
+  },
+  multiSelect: {
+    placeholder: 'Search and select...',
+    emptyText: 'No matching items',
+    clearAria: 'Clear all selections',
+    removeAria: (label) => `Remove ${label}`
+  },
+  datePicker: {
+    placeholder: 'Select date',
+    rangePlaceholder: 'Select date range',
+    prevMonthAria: 'Previous month',
+    nextMonthAria: 'Next month',
+    pendingRangeEnd: 'Start date selected, please choose end date.',
+    weekdays: ['Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa', 'Su']
+  },
+  appShell: {
+    sidebarLabel: 'Sidebar navigation',
+    resizeHandleAria: 'Resize panel'
+  },
+  alertDialog: {
+    confirm: 'Confirm',
+    cancel: 'Cancel'
   }
 }

From 5fa3aee200a2a342ef9d372cc8e61902a77334e4 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 05:46:12 +0800
Subject: [PATCH 19/26] feat(playground): add non-production environment banner

---
 apps/playground/app.vue                      |  1 +
 apps/playground/components/PreviewBanner.vue | 91 ++++++++++++++++++++
 apps/playground/nuxt.config.ts               |  8 ++
 3 files changed, 100 insertions(+)
 create mode 100644 apps/playground/components/PreviewBanner.vue

diff --git a/apps/playground/app.vue b/apps/playground/app.vue
index 2ae358a..87a9eaa 100644
--- a/apps/playground/app.vue
+++ b/apps/playground/app.vue
@@ -1,5 +1,6 @@
 <template>
   <ToastProvider />
+  <PreviewBanner />
   <div class="min-h-screen flex flex-col bg-slate-50 dark:bg-[#090E17] text-slate-700 dark:text-slate-200 transition-colors">
     <!-- 顶部导航栏 -->
     <header class="sticky top-0 z-40 border-b border-slate-200/80 dark:border-slate-800/80 bg-white/90 dark:bg-[#090E17]/90 backdrop-blur-md">
diff --git a/apps/playground/components/PreviewBanner.vue b/apps/playground/components/PreviewBanner.vue
new file mode 100644
index 0000000..f65b9b3
--- /dev/null
+++ b/apps/playground/components/PreviewBanner.vue
@@ -0,0 +1,91 @@
+<template>
+  <div
+    v-if="showBanner"
+    class="relative z-50 border-b border-amber-500/20 bg-gradient-to-r from-amber-500/10 via-amber-500/15 to-amber-500/10 px-4 py-2 text-xs font-medium text-amber-900 dark:border-amber-400/20 dark:text-amber-200"
+    role="region"
+    aria-label="环境预览提示"
+  >
+    <div class="mx-auto flex max-w-7xl items-center justify-between gap-3">
+      <div class="flex items-center gap-2 overflow-hidden">
+        <span class="inline-flex items-center gap-1.5 rounded-full bg-amber-500/20 px-2 py-0.5 text-[11px] font-semibold text-amber-800 dark:bg-amber-400/20 dark:text-amber-200">
+          <span class="h-1.5 w-1.5 rounded-full bg-amber-500 animate-pulse" />
+          {{ envBadge }}
+        </span>
+        <span class="truncate">
+          当前处于{{ envTitle }}环境
+          <span v-if="branch" class="font-mono opacity-80">({{ branch }})</span>
+          <span v-if="shortSha" class="ml-1 font-mono opacity-60">@{{ shortSha }}</span>
+          ，部分未发布的组件或实验性功能可能会在此预览测试。
+        </span>
+      </div>
+
+      <div class="flex shrink-0 items-center gap-2">
+        <a
+          v-if="commitUrl"
+          :href="commitUrl"
+          target="_blank"
+          rel="noopener noreferrer"
+          class="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[11px] text-amber-800 underline decoration-amber-500/50 underline-offset-2 transition-colors hover:text-amber-950 dark:text-amber-200 dark:hover:text-amber-100"
+        >
+          查看提交
+        </a>
+        <button
+          type="button"
+          class="rounded p-1 text-amber-700 transition-colors hover:bg-amber-500/20 hover:text-amber-950 dark:text-amber-300 dark:hover:text-amber-100"
+          aria-label="关闭提示"
+          @click="dismissed = true"
+        >
+          <svg class="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path stroke-linecap="round" d="M18 6 6 18M6 6l12 12" />
+          </svg>
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { useRuntimeConfig } from '#app'
+
+const config = useRuntimeConfig()
+const dismissed = ref(false)
+
+const cfPages = computed(() => Boolean(config.public.cfPages))
+const branch = computed(() => String(config.public.cfPagesBranch || ''))
+const commitSha = computed(() => String(config.public.cfPagesCommitSha || ''))
+const shortSha = computed(() => commitSha.value ? commitSha.value.slice(0, 7) : '')
+
+const isDev = process.dev || process.env.NODE_ENV !== 'production'
+const isPreviewBranch = computed(() => {
+  if (!branch.value) return false
+  // 生产主分支一般为 main 或 master，其他分支（如 dev、preview、pr 等）均为非生产预览
+  return branch.value !== 'main' && branch.value !== 'master'
+})
+
+const showBanner = computed(() => {
+  if (dismissed.value) return false
+  // 1. 本地开发环境展示 dev 提示
+  if (isDev) return true
+  // 2. Cloudflare Pages 非主分支预览部署展示 preview 提示
+  if (cfPages.value && isPreviewBranch.value) return true
+  return false
+})
+
+const envBadge = computed(() => {
+  if (isDev) return 'Local Dev'
+  if (cfPages.value) return 'Cloudflare Preview'
+  return 'Preview'
+})
+
+const envTitle = computed(() => {
+  if (isDev) return '本地开发'
+  if (cfPages.value) return 'Cloudflare Pages 分支预览'
+  return '预览'
+})
+
+const commitUrl = computed(() => {
+  if (!commitSha.value) return ''
+  return `https://github.com/ReCloudStudio/UI/commit/${commitSha.value}`
+})
+</script>
diff --git a/apps/playground/nuxt.config.ts b/apps/playground/nuxt.config.ts
index ead15c4..ee77171 100644
--- a/apps/playground/nuxt.config.ts
+++ b/apps/playground/nuxt.config.ts
@@ -34,5 +34,13 @@ export default defineNuxtConfig({
     plugins: [tailwindcss()]
   },
   devtools: { enabled: true },
+  runtimeConfig: {
+    public: {
+      cfPages: process.env.CF_PAGES || '',
+      cfPagesBranch: process.env.CF_PAGES_BRANCH || '',
+      cfPagesCommitSha: process.env.CF_PAGES_COMMIT_SHA || '',
+      cfPagesUrl: process.env.CF_PAGES_URL || ''
+    }
+  },
   compatibilityDate: '2026-10-02'
 })

From d21e891f7410faf25e22f448c60f77d567b077ea Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 05:58:54 +0800
Subject: [PATCH 20/26] fix(playground): refine preview banner style and
 resolve strict type errors

---
 apps/playground/components/PreviewBanner.vue  | 61 ++++++++++++-------
 .../pages/components/file-upload.vue          |  2 +-
 .../playground/pages/components/tree-view.vue | 33 +++++-----
 packages/ui/src/components/tree-view/index.ts |  2 +-
 packages/ui/src/locale/locale.test.ts         |  2 +-
 5 files changed, 62 insertions(+), 38 deletions(-)

diff --git a/apps/playground/components/PreviewBanner.vue b/apps/playground/components/PreviewBanner.vue
index f65b9b3..9c8fea5 100644
--- a/apps/playground/components/PreviewBanner.vue
+++ b/apps/playground/components/PreviewBanner.vue
@@ -1,22 +1,40 @@
 <template>
   <div
     v-if="showBanner"
-    class="relative z-50 border-b border-amber-500/20 bg-gradient-to-r from-amber-500/10 via-amber-500/15 to-amber-500/10 px-4 py-2 text-xs font-medium text-amber-900 dark:border-amber-400/20 dark:text-amber-200"
+    class="relative z-50 border-b border-blue-500/15 bg-slate-900/[0.03] backdrop-blur-md px-4 py-2 text-xs text-slate-700 transition-colors dark:border-blue-400/15 dark:bg-slate-950/40 dark:text-slate-300"
     role="region"
     aria-label="环境预览提示"
   >
-    <div class="mx-auto flex max-w-7xl items-center justify-between gap-3">
-      <div class="flex items-center gap-2 overflow-hidden">
-        <span class="inline-flex items-center gap-1.5 rounded-full bg-amber-500/20 px-2 py-0.5 text-[11px] font-semibold text-amber-800 dark:bg-amber-400/20 dark:text-amber-200">
-          <span class="h-1.5 w-1.5 rounded-full bg-amber-500 animate-pulse" />
+    <div class="mx-auto flex max-w-7xl items-center justify-between gap-4">
+      <div class="flex min-w-0 items-center gap-2.5">
+        <span
+          class="inline-flex shrink-0 items-center gap-1.5 rounded-full px-2 py-0.5 text-[11px] font-semibold tracking-wide ring-1 ring-inset"
+          :class="isDev
+            ? 'bg-amber-500/10 text-amber-700 ring-amber-500/25 dark:bg-amber-400/10 dark:text-amber-300 dark:ring-amber-400/25'
+            : 'bg-[#2563EB]/10 text-[#1D4ED8] ring-[#2563EB]/25 dark:bg-[#70ACFE]/10 dark:text-[#70ACFE] dark:ring-[#70ACFE]/25'"
+        >
+          <span
+            class="h-1.5 w-1.5 rounded-full"
+            :class="isDev ? 'bg-amber-500 animate-pulse' : 'bg-[#2563EB] dark:bg-[#70ACFE] animate-pulse'"
+          />
           {{ envBadge }}
         </span>
-        <span class="truncate">
-          当前处于{{ envTitle }}环境
-          <span v-if="branch" class="font-mono opacity-80">({{ branch }})</span>
-          <span v-if="shortSha" class="ml-1 font-mono opacity-60">@{{ shortSha }}</span>
-          ，部分未发布的组件或实验性功能可能会在此预览测试。
-        </span>
+
+        <p class="truncate text-xs leading-none">
+          <span class="font-medium text-slate-900 dark:text-slate-100">{{ envTitle }}</span>
+          <span v-if="branch" class="ml-1.5 inline-flex items-center gap-1 rounded bg-slate-200/60 px-1.5 py-0.5 font-mono text-[11px] text-slate-800 dark:bg-slate-800 dark:text-slate-200">
+            <svg class="h-3 w-3 opacity-60" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <line x1="6" y1="3" x2="6" y2="15" />
+              <circle cx="18" cy="6" r="3" />
+              <circle cx="6" cy="18" r="3" />
+              <path d="M18 9a9 9 0 0 1-9 9" />
+            </svg>
+            {{ branch }}
+          </span>
+          <span v-if="shortSha" class="ml-1 font-mono text-[11px] text-slate-500 dark:text-slate-400">@{{ shortSha }}</span>
+          <span class="mx-2 hidden text-slate-300 sm:inline dark:text-slate-700">·</span>
+          <span class="hidden text-slate-500 sm:inline dark:text-slate-400">此环境包含未发布的组件与实验性功能。</span>
+        </p>
       </div>
 
       <div class="flex shrink-0 items-center gap-2">
@@ -25,13 +43,17 @@
           :href="commitUrl"
           target="_blank"
           rel="noopener noreferrer"
-          class="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[11px] text-amber-800 underline decoration-amber-500/50 underline-offset-2 transition-colors hover:text-amber-950 dark:text-amber-200 dark:hover:text-amber-100"
+          class="inline-flex items-center gap-1 rounded-md px-2 py-1 text-[11px] font-medium text-slate-600 transition-colors hover:bg-slate-200/60 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-200"
         >
-          查看提交
+          <span>提交记录</span>
+          <svg class="h-3 w-3 opacity-70" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M7 17L17 7M17 7H7M17 7V17" />
+          </svg>
         </a>
+
         <button
           type="button"
-          class="rounded p-1 text-amber-700 transition-colors hover:bg-amber-500/20 hover:text-amber-950 dark:text-amber-300 dark:hover:text-amber-100"
+          class="inline-flex h-6 w-6 items-center justify-center rounded-md text-slate-400 transition-colors hover:bg-slate-200/60 hover:text-slate-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-500 dark:hover:bg-slate-800 dark:hover:text-slate-200"
           aria-label="关闭提示"
           @click="dismissed = true"
         >
@@ -59,29 +81,26 @@ const shortSha = computed(() => commitSha.value ? commitSha.value.slice(0, 7) :
 const isDev = process.dev || process.env.NODE_ENV !== 'production'
 const isPreviewBranch = computed(() => {
   if (!branch.value) return false
-  // 生产主分支一般为 main 或 master，其他分支（如 dev、preview、pr 等）均为非生产预览
   return branch.value !== 'main' && branch.value !== 'master'
 })
 
 const showBanner = computed(() => {
   if (dismissed.value) return false
-  // 1. 本地开发环境展示 dev 提示
   if (isDev) return true
-  // 2. Cloudflare Pages 非主分支预览部署展示 preview 提示
   if (cfPages.value && isPreviewBranch.value) return true
   return false
 })
 
 const envBadge = computed(() => {
   if (isDev) return 'Local Dev'
-  if (cfPages.value) return 'Cloudflare Preview'
+  if (cfPages.value) return 'Preview'
   return 'Preview'
 })
 
 const envTitle = computed(() => {
-  if (isDev) return '本地开发'
-  if (cfPages.value) return 'Cloudflare Pages 分支预览'
-  return '预览'
+  if (isDev) return '本地开发环境'
+  if (cfPages.value) return 'Cloudflare Pages 预览环境'
+  return '预览环境'
 })
 
 const commitUrl = computed(() => {
diff --git a/apps/playground/pages/components/file-upload.vue b/apps/playground/pages/components/file-upload.vue
index b31745a..784c546 100644
--- a/apps/playground/pages/components/file-upload.vue
+++ b/apps/playground/pages/components/file-upload.vue
@@ -9,7 +9,7 @@
 
     <DocExample title="配置文件校验" description="不传 upload 时，组件作为文件选择与校验控件使用；通过 change 获取当前文件项。" :code="rcCode1">
       <FileUpload accept=".json,.yaml,.yml" :multiple="false" :max-size="256 * 1024" @change="configFiles = $event" />
-      <p v-if="configFiles.length" class="text-xs text-slate-500 dark:text-slate-400">已选择 {{ configFiles[0].file.name }}</p>
+      <p v-if="configFiles.length && configFiles[0]" class="text-xs text-slate-500 dark:text-slate-400">已选择 {{ configFiles[0].file.name }}</p>
     </DocExample>
 
     <DocApiTable :rows="apiRows" />
diff --git a/apps/playground/pages/components/tree-view.vue b/apps/playground/pages/components/tree-view.vue
index 7b79529..0aa9005 100644
--- a/apps/playground/pages/components/tree-view.vue
+++ b/apps/playground/pages/components/tree-view.vue
@@ -220,41 +220,46 @@ function onDrop(event: TreeDropEvent) {
 
   function remove(list: TreeNode[]): TreeNode | null {
     for (let i = 0; i < list.length; i++) {
-      if (list[i].id === event.draggedNode.id) {
-        return list.splice(i, 1)[0]
+      const item = list[i]
+      if (!item) continue
+      if (item.id === event.draggedNode.id) {
+        const [deleted] = list.splice(i, 1)
+        return deleted ?? null
       }
-      if (list[i].children) {
-        const found = remove(list[i].children!)
+      if (item.children) {
+        const found = remove(item.children)
         if (found) return found
       }
     }
     return null
   }
 
-  const removed = remove(reorderNodes.value)
-  if (!removed) return
+  const removedNode = remove(reorderNodes.value)
+  if (!removedNode) return
 
-  function insert(list: TreeNode[]): boolean {
+  function insert(list: TreeNode[], toInsert: TreeNode): boolean {
     for (let i = 0; i < list.length; i++) {
-      if (list[i].id === event.targetNode.id) {
+      const item = list[i]
+      if (!item) continue
+      if (item.id === event.targetNode.id) {
         if (event.position === 'before') {
-          list.splice(i, 0, removed)
+          list.splice(i, 0, toInsert)
         } else if (event.position === 'after') {
-          list.splice(i + 1, 0, removed)
+          list.splice(i + 1, 0, toInsert)
         } else {
-          list[i].children = list[i].children || []
-          list[i].children!.push(removed)
+          item.children = item.children || []
+          item.children.push(toInsert)
         }
         return true
       }
-      if (list[i].children && insert(list[i].children!)) {
+      if (item.children && insert(item.children, toInsert)) {
         return true
       }
     }
     return false
   }
 
-  insert(reorderNodes.value)
+  insert(reorderNodes.value, removedNode)
 }
 
 const permissions = [
diff --git a/packages/ui/src/components/tree-view/index.ts b/packages/ui/src/components/tree-view/index.ts
index aae7efb..3d5437b 100644
--- a/packages/ui/src/components/tree-view/index.ts
+++ b/packages/ui/src/components/tree-view/index.ts
@@ -1,2 +1,2 @@
 export { default as TreeView } from './TreeView.vue'
-export type { TreeNode } from './types'
+export type { TreeDropEvent, TreeHighlightVariant, TreeNode } from './types'
diff --git a/packages/ui/src/locale/locale.test.ts b/packages/ui/src/locale/locale.test.ts
index 198689d..5545c04 100644
--- a/packages/ui/src/locale/locale.test.ts
+++ b/packages/ui/src/locale/locale.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { provideLocale, useComponentLocale, useLocale } from './index'
+import { useLocale } from './index'
 import { zhCN, enUS } from './messages'
 
 describe('i18n locale injection system', () => {

From a9d63bd8b3fa422d1c0588901ab905e751e5466b Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 06:23:37 +0800
Subject: [PATCH 21/26] feat(docs-suite): add Callout, InlineCode, Steps,
 AnchorHeading, Toc, PrevNext, NavTree, CodeGroup

---
 .changeset/calm-docs-suite-arrive.md          |   5 +
 .../pages/components/anchor-heading.vue       |  36 ++++
 apps/playground/pages/components/callout.vue  |  49 +++++
 .../pages/components/code-group.vue           |  46 +++++
 .../pages/components/inline-code.vue          |  39 ++++
 apps/playground/pages/components/nav-tree.vue |  54 ++++++
 .../playground/pages/components/prev-next.vue |  45 +++++
 apps/playground/pages/components/steps.vue    |  46 +++++
 apps/playground/pages/components/toc.vue      |  50 +++++
 apps/playground/utils/catalog.ts              |  13 ++
 .../anchor-heading/AnchorHeading.vue          |  98 ++++++++++
 .../ui/src/components/anchor-heading/index.ts |   2 +
 .../ui/src/components/anchor-heading/types.ts |   8 +
 .../ui/src/components/callout/Callout.vue     | 147 +++++++++++++++
 .../ui/src/components/callout/callout.test.ts |   9 +
 packages/ui/src/components/callout/index.ts   |   2 +
 packages/ui/src/components/callout/types.ts   |   9 +
 .../src/components/code-group/CodeGroup.vue   |  88 +++++++++
 .../ui/src/components/code-group/index.ts     |   2 +
 .../ui/src/components/code-group/types.ts     |  11 ++
 .../src/components/inline-code/InlineCode.vue |  74 ++++++++
 .../ui/src/components/inline-code/index.ts    |   2 +
 .../ui/src/components/inline-code/types.ts    |   6 +
 .../ui/src/components/nav-tree/NavTree.vue    | 124 +++++++++++++
 packages/ui/src/components/nav-tree/index.ts  |   2 +
 packages/ui/src/components/nav-tree/types.ts  |  25 +++
 .../ui/src/components/prev-next/PrevNext.vue  |  68 +++++++
 packages/ui/src/components/prev-next/index.ts |   2 +
 packages/ui/src/components/prev-next/types.ts |  14 ++
 packages/ui/src/components/steps/StepItem.vue |  53 ++++++
 packages/ui/src/components/steps/Steps.vue    |  25 +++
 packages/ui/src/components/steps/index.ts     |   3 +
 packages/ui/src/components/steps/types.ts     |  19 ++
 packages/ui/src/components/toc/Toc.vue        | 171 ++++++++++++++++++
 packages/ui/src/components/toc/index.ts       |   2 +
 packages/ui/src/components/toc/types.ts       |  16 ++
 packages/ui/src/index.ts                      |   8 +
 packages/ui/src/locale/messages.ts            |  24 +++
 38 files changed, 1397 insertions(+)
 create mode 100644 .changeset/calm-docs-suite-arrive.md
 create mode 100644 apps/playground/pages/components/anchor-heading.vue
 create mode 100644 apps/playground/pages/components/callout.vue
 create mode 100644 apps/playground/pages/components/code-group.vue
 create mode 100644 apps/playground/pages/components/inline-code.vue
 create mode 100644 apps/playground/pages/components/nav-tree.vue
 create mode 100644 apps/playground/pages/components/prev-next.vue
 create mode 100644 apps/playground/pages/components/steps.vue
 create mode 100644 apps/playground/pages/components/toc.vue
 create mode 100644 packages/ui/src/components/anchor-heading/AnchorHeading.vue
 create mode 100644 packages/ui/src/components/anchor-heading/index.ts
 create mode 100644 packages/ui/src/components/anchor-heading/types.ts
 create mode 100644 packages/ui/src/components/callout/Callout.vue
 create mode 100644 packages/ui/src/components/callout/callout.test.ts
 create mode 100644 packages/ui/src/components/callout/index.ts
 create mode 100644 packages/ui/src/components/callout/types.ts
 create mode 100644 packages/ui/src/components/code-group/CodeGroup.vue
 create mode 100644 packages/ui/src/components/code-group/index.ts
 create mode 100644 packages/ui/src/components/code-group/types.ts
 create mode 100644 packages/ui/src/components/inline-code/InlineCode.vue
 create mode 100644 packages/ui/src/components/inline-code/index.ts
 create mode 100644 packages/ui/src/components/inline-code/types.ts
 create mode 100644 packages/ui/src/components/nav-tree/NavTree.vue
 create mode 100644 packages/ui/src/components/nav-tree/index.ts
 create mode 100644 packages/ui/src/components/nav-tree/types.ts
 create mode 100644 packages/ui/src/components/prev-next/PrevNext.vue
 create mode 100644 packages/ui/src/components/prev-next/index.ts
 create mode 100644 packages/ui/src/components/prev-next/types.ts
 create mode 100644 packages/ui/src/components/steps/StepItem.vue
 create mode 100644 packages/ui/src/components/steps/Steps.vue
 create mode 100644 packages/ui/src/components/steps/index.ts
 create mode 100644 packages/ui/src/components/steps/types.ts
 create mode 100644 packages/ui/src/components/toc/Toc.vue
 create mode 100644 packages/ui/src/components/toc/index.ts
 create mode 100644 packages/ui/src/components/toc/types.ts

diff --git a/.changeset/calm-docs-suite-arrive.md b/.changeset/calm-docs-suite-arrive.md
new file mode 100644
index 0000000..00f4853
--- /dev/null
+++ b/.changeset/calm-docs-suite-arrive.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add documentation and typography component suite: Callout, InlineCode, Steps, AnchorHeading, Toc, PrevNext, NavTree, and CodeGroup with accessibility and locale support.
diff --git a/apps/playground/pages/components/anchor-heading.vue b/apps/playground/pages/components/anchor-heading.vue
new file mode 100644
index 0000000..385253c
--- /dev/null
+++ b/apps/playground/pages/components/anchor-heading.vue
@@ -0,0 +1,36 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="AnchorHeading 锚点标题" description="悬停时展示 # 锚点图标，点击自动复制指向该小节的直接链接。" />
+
+    <DocExample title="各级标题示例" description="支持 as 属性配置 h1 到 h6 各级标题，且自动根据标题正文生成 URL-friendly 的 ID。" :code="codeBasic">
+      <div class="space-y-6 max-w-2xl pl-8">
+        <AnchorHeading as="h2">快速上手指南</AnchorHeading>
+        <p class="text-sm text-slate-600 dark:text-slate-400">本小节介绍如何将组件库快速接入现有项目。</p>
+
+        <AnchorHeading as="h3">前置要求</AnchorHeading>
+        <p class="text-sm text-slate-600 dark:text-slate-400">请确保 Node.js >= 18 或使用 Bun 运行时。</p>
+
+        <AnchorHeading as="h4">可选依赖项</AnchorHeading>
+        <p class="text-sm text-slate-600 dark:text-slate-400">如需使用代码块高亮，可按需集成 Shiki。</p>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="anchor-heading" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const codeBasic = `<AnchorHeading as="h2">快速上手指南</AnchorHeading>
+<p>本小节介绍如何将组件库快速接入现有项目。</p>
+
+<AnchorHeading as="h3">前置要求</AnchorHeading>
+<p>请确保 Node.js >= 18 或使用 Bun 运行时。</p>`
+
+const apiRows = [
+  { name: 'as', type: "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'", default: "'h2'", description: 'HTML 标题语义级别。' },
+  { name: 'id', type: 'string', default: '依文本自动 slugify', description: '标题的 DOM 唯一标识符，用作 URL Hash。' },
+  { name: 'copyable', type: 'boolean', default: 'true', description: '是否在点击锚点符号时复制链接到剪贴板。' },
+  { name: 'slot: default', type: 'slot', default: '—', description: '标题展示文本。' }
+]
+</script>
diff --git a/apps/playground/pages/components/callout.vue b/apps/playground/pages/components/callout.vue
new file mode 100644
index 0000000..469359a
--- /dev/null
+++ b/apps/playground/pages/components/callout.vue
@@ -0,0 +1,49 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Callout 提示块" description="用于文档中的重点强调、操作建议、版本注意与破坏性警示。" />
+
+    <DocExample title="基础类型" description="内置 info、tip、note、warning、danger 五种类型，包含匹配的图标与色彩。" :code="codeBasic">
+      <div class="space-y-3 max-w-2xl">
+        <Callout type="info">系统会在夜间进行自动冷备份，此期间集群读写不会中断。</Callout>
+        <Callout type="tip" title="专业建议">在生产环境中建议将副本数量设置为至少 3，以保障高可用。</Callout>
+        <Callout type="note" title="版本记录">该选项自 v1.2.0 起默认开启。</Callout>
+        <Callout type="warning" title="注意事项">修改该网络端口将导致现存客户端重连。</Callout>
+        <Callout type="danger" title="破坏性操作">删除命名空间将级联清理所有关联的秘密卷和无状态服务，操作无法撤回。</Callout>
+      </div>
+    </DocExample>
+
+    <DocExample title="可折叠提示块" description="设置 collapsible 允许用户收起或展开详细内容。" :code="codeCollapsible">
+      <div class="max-w-2xl">
+        <Callout type="info" title="展开查看排查指南" :collapsible="true" :default-open="false">
+          <p>1. 确认 VPC 对等连接路由表已发布。</p>
+          <p class="mt-1">2. 执行 <InlineCode code="ping" /> 验证网关连通性。</p>
+        </Callout>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="callout" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const codeBasic = `<Callout type="info">系统会在夜间进行自动冷备份。</Callout>
+<Callout type="tip" title="专业建议">建议将副本数量设置为至少 3。</Callout>
+<Callout type="warning" title="注意事项">修改网络端口会导致客户端重连。</Callout>
+<Callout type="danger" title="破坏性操作">删除命名空间将级联清理所有资源。</Callout>`
+
+const codeCollapsible = `<Callout type="info" title="展开查看排查指南" :collapsible="true" :default-open="false">
+  <p>1. 确认 VPC 对等连接路由表已发布。</p>
+</Callout>`
+
+const apiRows = [
+  { name: 'type', type: "'info' | 'tip' | 'note' | 'warning' | 'danger'", default: "'info'", description: '提示块的语义类型与视觉风格。' },
+  { name: 'title', type: 'string', default: '依类型默认', description: '提示块顶部标题。' },
+  { name: 'collapsible', type: 'boolean', default: 'false', description: '是否允许点击折叠与展开。' },
+  { name: 'defaultOpen', type: 'boolean', default: 'true', description: '折叠模式下的初始展开状态。' },
+  { name: 'slot: default', type: 'slot', default: '—', description: '提示块主体正文。' },
+  { name: 'slot: title', type: 'slot', default: '—', description: '自定义标题区域内容。' },
+  { name: 'slot: icon', type: 'slot', default: '—', description: '自定义前置图标。' },
+  { name: 'slot: action', type: 'slot', default: '—', description: '右上角附加操作按钮。' }
+]
+</script>
diff --git a/apps/playground/pages/components/code-group.vue b/apps/playground/pages/components/code-group.vue
new file mode 100644
index 0000000..bb9c7e0
--- /dev/null
+++ b/apps/playground/pages/components/code-group.vue
@@ -0,0 +1,46 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="CodeGroup 代码分组" description="专为文档与教程设计的选项卡式代码块容器，常用于多包管理器安装命令与不同语言代码对比。" />
+
+    <DocExample title="包管理器切换" description="结合 CodeBlock 展示不同包管理器的命令。" :code="codeBasic">
+      <div class="max-w-2xl">
+        <CodeGroup v-model="activePm" :tabs="['bun', 'pnpm', 'npm', 'yarn']">
+          <div v-if="activePm === 'bun'" class="p-4 font-mono text-xs bg-slate-950 text-slate-100 rounded-b-xl">
+            bun add @recloudstudio/ui
+          </div>
+          <div v-else-if="activePm === 'pnpm'" class="p-4 font-mono text-xs bg-slate-950 text-slate-100 rounded-b-xl">
+            pnpm add @recloudstudio/ui
+          </div>
+          <div v-else-if="activePm === 'npm'" class="p-4 font-mono text-xs bg-slate-950 text-slate-100 rounded-b-xl">
+            npm install @recloudstudio/ui
+          </div>
+          <div v-else class="p-4 font-mono text-xs bg-slate-950 text-slate-100 rounded-b-xl">
+            yarn add @recloudstudio/ui
+          </div>
+        </CodeGroup>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="code-group" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const activePm = ref('bun')
+
+const codeBasic = `<CodeGroup v-model="activePm" :tabs="['bun', 'pnpm', 'npm', 'yarn']">
+  <div v-if="activePm === 'bun'">bun add @recloudstudio/ui</div>
+  <div v-else-if="activePm === 'pnpm'">pnpm add @recloudstudio/ui</div>
+  ...
+</CodeGroup>`
+
+const apiRows = [
+  { name: 'modelValue / v-model', type: 'string | number', default: '首个选项卡', description: '当前选中的选项卡 key。' },
+  { name: 'tabs', type: '(string | CodeGroupTab)[]', default: '[]', description: '选项卡列表配置：可为字符串或对象 { label, key?, icon? }。' },
+  { name: 'slot: default', type: 'slot', default: '—', description: '默认插槽，接收 activeKey 与 activeIndex。' },
+  { name: 'slot: [key]', type: 'slot', default: '—', description: '支持按 tab key 名称命名的具名插槽。' }
+]
+</script>
diff --git a/apps/playground/pages/components/inline-code.vue b/apps/playground/pages/components/inline-code.vue
new file mode 100644
index 0000000..ef54a78
--- /dev/null
+++ b/apps/playground/pages/components/inline-code.vue
@@ -0,0 +1,39 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="InlineCode 行内代码" description="针对行内短代码、配置字段、CLI 命令与按键的高亮与一键复制。" />
+
+    <DocExample title="基础与风格" description="支持 subtle（默认）、solid 与 outline 三种风格外观。" :code="codeBasic">
+      <div class="space-y-3 max-w-2xl text-sm leading-relaxed text-slate-700 dark:text-slate-300">
+        <p>通过 <InlineCode code="bun add @recloudstudio/ui" /> 安装依赖包。</p>
+        <p>深色高亮模式：<InlineCode code="POST /api/v1/auth" variant="solid" /> 接口需要鉴权头。</p>
+        <p>边框轮廓模式：<InlineCode code="config.resolve.alias" variant="outline" /> 支持别名映射。</p>
+      </div>
+    </DocExample>
+
+    <DocExample title="支持一键复制" description="设置 copyable 为 true，用户点击即可快捷复制行内文本到剪贴板。" :code="codeCopy">
+      <div class="space-y-3 max-w-2xl text-sm leading-relaxed text-slate-700 dark:text-slate-300">
+        <p>试着点击右侧的命令：<InlineCode code="curl -sSL https://recloud.sh | bash" :copyable="true" /></p>
+        <p>插槽形式定义：<InlineCode :copyable="true">VITE_API_BASE_URL=https://api.recloud.io</InlineCode></p>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="inline-code" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const codeBasic = `<InlineCode code="bun add @recloudstudio/ui" />
+<InlineCode code="POST /api/v1/auth" variant="solid" />
+<InlineCode code="config.resolve.alias" variant="outline" />`
+
+const codeCopy = `<InlineCode code="curl -sSL https://recloud.sh | bash" :copyable="true" />
+<InlineCode :copyable="true">VITE_API_BASE_URL=https://api.recloud.io</InlineCode>`
+
+const apiRows = [
+  { name: 'code', type: 'string', default: "''", description: '行内代码文本，也可通过默认插槽传入。' },
+  { name: 'copyable', type: 'boolean', default: 'false', description: '是否开启一键点击复制功能。' },
+  { name: 'variant', type: "'subtle' | 'solid' | 'outline'", default: "'subtle'", description: '视觉样式变体。' },
+  { name: 'slot: default', type: 'slot', default: '—', description: '自定义行内内容。' }
+]
+</script>
diff --git a/apps/playground/pages/components/nav-tree.vue b/apps/playground/pages/components/nav-tree.vue
new file mode 100644
index 0000000..bb5e053
--- /dev/null
+++ b/apps/playground/pages/components/nav-tree.vue
@@ -0,0 +1,54 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="NavTree 文档树侧栏" description="用于文档站点与多层级内容目录的侧边栏组件，支持分组折叠、徽标与实时搜索过滤。" />
+
+    <DocExample title="文档分组与过滤" description="支持多级分组、折叠展开与搜索实时过滤文档条目。" :code="codeBasic">
+      <div class="max-w-xs rounded-xl border border-slate-200/80 bg-white p-4 shadow-sm dark:border-slate-800 dark:bg-[#0B1220]">
+        <NavTree
+          :groups="sampleGroups"
+          active-href="/components/callout"
+          :searchable="true"
+        />
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="nav-tree" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const sampleGroups = [
+  {
+    title: '基础组件',
+    collapsible: true,
+    items: [
+      { title: 'Button 按钮', href: '/components/button' },
+      { title: 'Badge 徽标', href: '/components/badge', badge: 'Hot' },
+      { title: 'Callout 提示块', href: '/components/callout', badge: 'New' }
+    ]
+  },
+  {
+    title: '排版导航',
+    collapsible: true,
+    items: [
+      { title: 'Steps 步骤', href: '/components/steps' },
+      { title: 'AnchorHeading 锚点标题', href: '/components/anchor-heading' },
+      { title: 'Toc 页内目录', href: '/components/toc' }
+    ]
+  }
+]
+
+const codeBasic = `<NavTree
+  :groups="sampleGroups"
+  active-href="/components/callout"
+  :searchable="true"
+/>`
+
+const apiRows = [
+  { name: 'groups', type: 'NavTreeGroup[]', default: '[]', description: '文档分组列表：title、collapsible?、items（包含 title、href、to、badge、icon）。' },
+  { name: 'activeHref', type: 'string', default: "''", description: '当前高亮激活的页面路径。' },
+  { name: 'searchable', type: 'boolean', default: 'false', description: '是否在顶部展示即时过滤搜索框。' },
+  { name: 'searchPlaceholder', type: 'string', default: '依国际化配置', description: '搜索框占位文本。' }
+]
+</script>
diff --git a/apps/playground/pages/components/prev-next.vue b/apps/playground/pages/components/prev-next.vue
new file mode 100644
index 0000000..c106f31
--- /dev/null
+++ b/apps/playground/pages/components/prev-next.vue
@@ -0,0 +1,45 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="PrevNext 翻页导航" description="用于长篇指南、API 手册与教程底部的上下篇连续导航卡片。" />
+
+    <DocExample title="基础双向导航" description="提供左右两侧卡片，支持上一篇与下一篇标题与描述。" :code="codeBasic">
+      <div class="max-w-2xl">
+        <PrevNext
+          :prev="{ title: 'TreeView 树形视图', to: '/components/tree-view', description: '层级结构导航与资源树。' }"
+          :next="{ title: 'Callout 提示块', to: '/components/callout', description: '多种语义状态的信息提示卡片。' }"
+        />
+      </div>
+    </DocExample>
+
+    <DocExample title="单侧导航（首末篇）" description="当只有上一篇或下一篇时，空缺侧保持布局优雅对齐。" :code="codeSingle">
+      <div class="space-y-4 max-w-2xl">
+        <PrevNext
+          :next="{ title: '开始快速上手', to: '/components/steps' }"
+          next-label="下一章"
+        />
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="prev-next" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const codeBasic = `<PrevNext
+  :prev="{ title: 'TreeView 树形视图', to: '/components/tree-view' }"
+  :next="{ title: 'Callout 提示块', to: '/components/callout' }"
+/>`
+
+const codeSingle = `<PrevNext
+  :next="{ title: '开始快速上手', to: '/components/steps' }"
+  next-label="下一章"
+/>`
+
+const apiRows = [
+  { name: 'prev', type: 'PrevNextItem', default: '—', description: '上一篇配置：title、href?、to?、description?。' },
+  { name: 'next', type: 'PrevNextItem', default: '—', description: '下一篇配置：title、href?、to?、description?。' },
+  { name: 'prevLabel', type: 'string', default: '依国际化配置', description: '上一篇小标签文本。' },
+  { name: 'nextLabel', type: 'string', default: '依国际化配置', description: '下一篇小标签文本。' }
+]
+</script>
diff --git a/apps/playground/pages/components/steps.vue b/apps/playground/pages/components/steps.vue
new file mode 100644
index 0000000..33e7e06
--- /dev/null
+++ b/apps/playground/pages/components/steps.vue
@@ -0,0 +1,46 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Steps 文档步骤" description="面向快速上手、环境部署与排错排查文档的垂直向导步骤列表。" />
+
+    <DocExample title="自动编号步骤" description="Steps 自动管理子项的序号索引与连接线。" :code="codeBasic">
+      <Steps class="max-w-2xl">
+        <StepItem title="安装组件库依赖" description="通过 Bun 或 npm 将 ReCloud UI 引入项目。">
+          <p>在工程根目录运行：</p>
+          <InlineCode code="bun add @recloudstudio/ui" :copyable="true" />
+        </StepItem>
+        <StepItem title="引入样式与设计令牌" description="在应用入口导入全局样式。">
+          <p>在你的应用入口文件顶部引入：</p>
+          <InlineCode code="import '@recloudstudio/ui/style.css'" :copyable="true" />
+        </StepItem>
+        <StepItem title="使用组件" description="直接在 Vue 模板中声明组件即可。">
+          <p>例如：引入 <InlineCode code="<Button>点击操作</Button>" />。</p>
+        </StepItem>
+      </Steps>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="steps" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const codeBasic = `<Steps>
+  <StepItem title="安装依赖" description="引入 ReCloud UI">
+    <InlineCode code="bun add @recloudstudio/ui" :copyable="true" />
+  </StepItem>
+  <StepItem title="引入样式">
+    <InlineCode code="import '@recloudstudio/ui/style.css'" />
+  </StepItem>
+  <StepItem title="使用组件">
+    <Button>开始体验</Button>
+  </StepItem>
+</Steps>`
+
+const apiRows = [
+  { name: 'startIndex', type: 'number', default: '1', description: 'Steps 容器的起始序号。' },
+  { name: 'StepItem.title', type: 'string', default: "''", description: '步骤标题。' },
+  { name: 'StepItem.description', type: 'string', default: "''", description: '步骤辅助说明。' },
+  { name: 'StepItem.step', type: 'number | string', default: '自动计算', description: '手动覆盖当前步骤的标记字符或数字。' },
+  { name: 'slot: default', type: 'slot', default: '—', description: '步骤主体内容。' }
+]
+</script>
diff --git a/apps/playground/pages/components/toc.vue b/apps/playground/pages/components/toc.vue
new file mode 100644
index 0000000..2598e8e
--- /dev/null
+++ b/apps/playground/pages/components/toc.vue
@@ -0,0 +1,50 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Toc 页内目录" description="从当前页面或指定容器中收集多级标题并生成导航，支持平滑滚动与滚动监听。" />
+
+    <DocExample title="基础目录导航" description="通过数据传入或自动提取页面中的 h2/h3 标题。" :code="codeBasic">
+      <div class="grid grid-cols-1 md:grid-cols-3 gap-8 max-w-4xl">
+        <div class="md:col-span-2 space-y-6 rounded-xl border border-slate-200/80 p-6 dark:border-slate-800" id="toc-demo-content">
+          <AnchorHeading as="h2" id="demo-intro">1. 系统介绍</AnchorHeading>
+          <p class="text-sm text-slate-600 dark:text-slate-400">ReCloud UI 是一套专注于开发运维控制台与内部工具的现代化组件库。</p>
+
+          <AnchorHeading as="h3" id="demo-features">核心特性</AnchorHeading>
+          <p class="text-sm text-slate-600 dark:text-slate-400">提供无障碍基础底座与高度定制的设计令牌系统。</p>
+
+          <AnchorHeading as="h2" id="demo-install">2. 安装与配置</AnchorHeading>
+          <p class="text-sm text-slate-600 dark:text-slate-400">支持在 Vue 3 与 Nuxt 4 环境中直接使用。</p>
+
+          <AnchorHeading as="h3" id="demo-nuxt">Nuxt 模块集成</AnchorHeading>
+          <p class="text-sm text-slate-600 dark:text-slate-400">开箱即用的主题注水与组件自动导入支持。</p>
+        </div>
+
+        <div class="md:col-span-1">
+          <div class="sticky top-20 rounded-xl border border-slate-200/80 bg-slate-50/50 p-4 dark:border-slate-800 dark:bg-slate-900/50">
+            <Toc container="#toc-demo-content" />
+          </div>
+        </div>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="toc" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const codeBasic = `<div id="doc-content">
+  <AnchorHeading as="h2" id="intro">介绍</AnchorHeading>
+  <p>内容...</p>
+</div>
+
+<!-- 目录导航 -->
+<Toc container="#doc-content" />`
+
+const apiRows = [
+  { name: 'container', type: 'string', default: 'document', description: '用于收集标题的容器 CSS 选择器。' },
+  { name: 'selector', type: 'string', default: "'h2, h3'", description: '目标收集的标题 CSS 选择器。' },
+  { name: 'items', type: 'TocItem[]', default: '—', description: '手动指定目录项（覆盖自动提取）：id、title、level?。' },
+  { name: 'scrollSpy', type: 'boolean', default: 'true', description: '是否在页面滚动时自动高亮当前所在视口的小节。' },
+  { name: 'offset', type: 'number', default: '80', description: '滚动定位与 IntersectionObserver 计算时的顶部偏移量 (px)。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 854ae1f..80fa848 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -106,6 +106,19 @@ const groups: DocGroup[] = [
       { name: 'sheet', title: 'Sheet 抽屉面板', description: '资源详情、配置与辅助操作面板。' }
     ]
   },
+  {
+    label: '文档排版',
+    items: [
+      { name: 'callout', title: 'Callout 提示块', description: '注意、提示、警告、危险语义提示块。' },
+      { name: 'inline-code', title: 'InlineCode 行内代码', description: '与 CodeBlock 成套的等宽行内代码标记，可选一键复制。' },
+      { name: 'steps', title: 'Steps 文档步骤', description: '长文指南与安装教程的垂直序列步骤。' },
+      { name: 'anchor-heading', title: 'AnchorHeading 锚点标题', description: '悬停显现锚点符号并支持复制链接的标题。' },
+      { name: 'toc', title: 'Toc 页内目录', description: '多级标题目录导航，支持滚动高亮与平滑跳转。' },
+      { name: 'prev-next', title: 'PrevNext 翻页导航', description: '文章与文档的上一篇/下一篇双向卡片导航。' },
+      { name: 'nav-tree', title: 'NavTree 文档树侧栏', description: '带分组、折叠、徽标与实时过滤的文档树侧栏。' },
+      { name: 'code-group', title: 'CodeGroup 代码分组', description: '多包管理器与多语言代码块选项卡容器。' }
+    ]
+  },
   {
     label: '工具',
     items: [
diff --git a/packages/ui/src/components/anchor-heading/AnchorHeading.vue b/packages/ui/src/components/anchor-heading/AnchorHeading.vue
new file mode 100644
index 0000000..7e8bb2b
--- /dev/null
+++ b/packages/ui/src/components/anchor-heading/AnchorHeading.vue
@@ -0,0 +1,98 @@
+<template>
+  <component
+    :is="as"
+    :id="effectiveId"
+    :class="[
+      'group relative flex items-center scroll-mt-20 tracking-tight font-semibold text-slate-900 dark:text-slate-100',
+      sizeClasses,
+      props.class
+    ]"
+  >
+    <a
+      v-if="effectiveId"
+      :href="`#${effectiveId}`"
+      class="absolute -left-6 top-1/2 -translate-y-1/2 p-1 text-slate-400 opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100 focus-visible:outline-none hover:text-[#2563EB] dark:hover:text-[#70ACFE]"
+      :aria-label="docsLoc.copyLink"
+      @click="handleClick"
+    >
+      <span class="font-mono text-base font-medium select-none">#</span>
+    </a>
+    <slot />
+    <span
+      v-if="justCopied"
+      class="ml-2 inline-flex items-center rounded bg-emerald-500/10 px-1.5 py-0.5 text-xs font-normal text-emerald-600 dark:bg-emerald-500/20 dark:text-emerald-400"
+    >
+      {{ docsLoc.copiedLink }}
+    </span>
+  </component>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, useSlots } from 'vue'
+import { useComponentLocale } from '../../locale'
+import type { AnchorHeadingProps } from './types'
+
+const props = withDefaults(defineProps<AnchorHeadingProps>(), {
+  as: 'h2',
+  id: undefined,
+  copyable: true,
+  class: ''
+})
+
+const docsLoc = useComponentLocale('docs')
+const slots = useSlots()
+const justCopied = ref(false)
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[\s\W-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+const effectiveId = computed(() => {
+  if (props.id) return props.id
+  const defaultSlot = slots.default?.()
+  if (!defaultSlot || defaultSlot.length === 0) return undefined
+  const text = defaultSlot
+    .map((vnode) => (typeof vnode.children === 'string' ? vnode.children : ''))
+    .join('')
+  return text ? slugify(text) : undefined
+})
+
+const sizeClasses = computed(() => {
+  switch (props.as) {
+    case 'h1':
+      return 'text-2xl sm:text-3xl font-bold my-6'
+    case 'h2':
+      return 'text-xl sm:text-2xl font-semibold mt-10 mb-4 pb-2 border-b border-slate-200 dark:border-slate-800'
+    case 'h3':
+      return 'text-lg sm:text-xl font-semibold mt-8 mb-3'
+    case 'h4':
+      return 'text-base font-semibold mt-6 mb-2'
+    case 'h5':
+    case 'h6':
+      return 'text-sm font-semibold mt-4 mb-2'
+    default:
+      return 'text-xl font-semibold'
+  }
+})
+
+async function handleClick(e: MouseEvent) {
+  if (!props.copyable || !effectiveId.value) return
+  if (typeof window !== 'undefined') {
+    const url = new URL(window.location.href)
+    url.hash = effectiveId.value
+    try {
+      await navigator.clipboard.writeText(url.toString())
+      justCopied.value = true
+      setTimeout(() => {
+        justCopied.value = false
+      }, 1600)
+    } catch {
+      // ignore
+    }
+  }
+}
+</script>
diff --git a/packages/ui/src/components/anchor-heading/index.ts b/packages/ui/src/components/anchor-heading/index.ts
new file mode 100644
index 0000000..628a9f9
--- /dev/null
+++ b/packages/ui/src/components/anchor-heading/index.ts
@@ -0,0 +1,2 @@
+export { default as AnchorHeading } from './AnchorHeading.vue'
+export type { AnchorHeadingProps, HeadingLevel } from './types'
diff --git a/packages/ui/src/components/anchor-heading/types.ts b/packages/ui/src/components/anchor-heading/types.ts
new file mode 100644
index 0000000..34d6a56
--- /dev/null
+++ b/packages/ui/src/components/anchor-heading/types.ts
@@ -0,0 +1,8 @@
+export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+export interface AnchorHeadingProps {
+  as?: HeadingLevel
+  id?: string
+  copyable?: boolean
+  class?: string
+}
diff --git a/packages/ui/src/components/callout/Callout.vue b/packages/ui/src/components/callout/Callout.vue
new file mode 100644
index 0000000..5f98599
--- /dev/null
+++ b/packages/ui/src/components/callout/Callout.vue
@@ -0,0 +1,147 @@
+<template>
+  <div
+    :class="[
+      'my-5 rounded-xl border text-sm transition-colors',
+      styleConfig.container,
+      props.class
+    ]"
+    role="region"
+    :aria-label="title || type"
+  >
+    <div
+      :class="[
+        'flex items-start gap-3 p-4',
+        collapsible ? 'cursor-pointer select-none' : ''
+      ]"
+      @click="collapsible && toggle()"
+    >
+      <div class="mt-0.5 shrink-0" :class="styleConfig.iconClass">
+        <slot name="icon">
+          <!-- note -->
+          <svg v-if="type === 'note'" class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M16.862 4.487l1.687-1.688a1.875 1.875 0 112.652 2.652L6.832 19.82a4.5 4.5 0 01-1.897 1.13l-2.685.8.8-2.685a4.5 4.5 0 011.13-1.897L16.863 4.487zm0 0L19.5 7.125" />
+          </svg>
+          <!-- tip -->
+          <svg v-else-if="type === 'tip'" class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M12 18v-5.25m0 0a6.01 6.01 0 001.5-.189m-1.5.189a6.01 6.01 0 01-1.5-.189m3.75 7.439a8.966 8.966 0 01-4.5 0m4.5 0v.75A2.25 2.25 0 0112 23.25h0A2.25 2.25 0 019.75 21v-.75m6-12a6 6 0 10-12 0c0 2.22 1.206 4.16 3 5.197V15a1.5 1.5 0 001.5 1.5h3A1.5 1.5 0 0015 15v-1.553c1.794-1.037 3-2.977 3-5.197z" />
+          </svg>
+          <!-- warning -->
+          <svg v-else-if="type === 'warning'" class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
+          </svg>
+          <!-- danger -->
+          <svg v-else-if="type === 'danger'" class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m9-.75a9 9 0 11-18 0 9 9 0 0118 0zm-9 3.75h.008v.008H12v-.008z" />
+          </svg>
+          <!-- info (default) -->
+          <svg v-else class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M11.25 11.25l.041-.02a.75.75 0 011.063.852l-.708 2.836a.75.75 0 001.063.853l.041-.021M21 12a9 9 0 11-18 0 9 9 0 0118 0zm-9-3.75h.008v.008H12V8.25z" />
+          </svg>
+        </slot>
+      </div>
+
+      <div class="min-w-0 flex-1">
+        <div class="flex items-center justify-between gap-2">
+          <div :class="['font-semibold tracking-tight', styleConfig.titleClass]">
+            <slot name="title">{{ computedTitle }}</slot>
+          </div>
+          <div v-if="$slots.action" class="shrink-0" @click.stop>
+            <slot name="action" />
+          </div>
+          <button
+            v-if="collapsible"
+            type="button"
+            class="rounded p-0.5 text-slate-400 hover:text-slate-600 dark:hover:text-slate-300"
+            :aria-label="isOpen ? '收起' : '展开'"
+          >
+            <svg
+              class="h-4 w-4 transition-transform duration-200"
+              :class="isOpen ? 'rotate-180' : ''"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+            >
+              <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 8.25l-7.5 7.5-7.5-7.5" />
+            </svg>
+          </button>
+        </div>
+
+        <div
+          v-show="!collapsible || isOpen"
+          :class="[
+            'leading-relaxed transition-opacity',
+            styleConfig.contentClass,
+            (title || $slots.title) ? 'mt-1.5' : ''
+          ]"
+        >
+          <slot />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { CalloutProps, CalloutType } from './types'
+
+const props = withDefaults(defineProps<CalloutProps>(), {
+  type: 'info',
+  title: undefined,
+  collapsible: false,
+  defaultOpen: true,
+  class: ''
+})
+
+const isOpen = ref(props.defaultOpen)
+
+function toggle() {
+  isOpen.value = !isOpen.value
+}
+
+const defaultTitles: Record<CalloutType, string> = {
+  note: 'Note',
+  tip: 'Tip',
+  info: 'Info',
+  warning: 'Warning',
+  danger: 'Danger'
+}
+
+const computedTitle = computed(() => props.title ?? defaultTitles[props.type])
+
+const styleMap: Record<CalloutType, { container: string; iconClass: string; titleClass: string; contentClass: string }> = {
+  note: {
+    container: 'border-slate-300/80 bg-slate-100/70 dark:border-slate-800 dark:bg-slate-900/60',
+    iconClass: 'text-slate-600 dark:text-slate-300',
+    titleClass: 'text-slate-900 dark:text-slate-100',
+    contentClass: 'text-slate-700 dark:text-slate-300'
+  },
+  tip: {
+    container: 'border-emerald-500/25 bg-emerald-500/[0.06] dark:border-emerald-500/30 dark:bg-emerald-500/10',
+    iconClass: 'text-emerald-600 dark:text-emerald-400',
+    titleClass: 'text-emerald-900 dark:text-emerald-200',
+    contentClass: 'text-emerald-950/90 dark:text-emerald-200/90'
+  },
+  info: {
+    container: 'border-[#2563EB]/25 bg-[#2563EB]/[0.05] dark:border-[#70ACFE]/30 dark:bg-[#2563EB]/10',
+    iconClass: 'text-[#2563EB] dark:text-[#70ACFE]',
+    titleClass: 'text-[#1D4ED8] dark:text-[#70ACFE]',
+    contentClass: 'text-slate-800 dark:text-slate-200'
+  },
+  warning: {
+    container: 'border-amber-500/30 bg-amber-500/[0.07] dark:border-amber-400/30 dark:bg-amber-400/10',
+    iconClass: 'text-amber-600 dark:text-amber-400',
+    titleClass: 'text-amber-900 dark:text-amber-200',
+    contentClass: 'text-amber-950/90 dark:text-amber-200/90'
+  },
+  danger: {
+    container: 'border-rose-500/30 bg-rose-500/[0.07] dark:border-rose-500/30 dark:bg-rose-500/10',
+    iconClass: 'text-rose-600 dark:text-rose-400',
+    titleClass: 'text-rose-900 dark:text-rose-200',
+    contentClass: 'text-rose-950/90 dark:text-rose-200/90'
+  }
+}
+
+const styleConfig = computed(() => styleMap[props.type] ?? styleMap.info)
+</script>
diff --git a/packages/ui/src/components/callout/callout.test.ts b/packages/ui/src/components/callout/callout.test.ts
new file mode 100644
index 0000000..29e3ce0
--- /dev/null
+++ b/packages/ui/src/components/callout/callout.test.ts
@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { Callout } from './index'
+
+describe('Callout component', () => {
+  it('is exported as a Vue component', () => {
+    expect(Callout).toBeDefined()
+    expect(Callout.name || Callout.__name).toBeDefined()
+  })
+})
diff --git a/packages/ui/src/components/callout/index.ts b/packages/ui/src/components/callout/index.ts
new file mode 100644
index 0000000..85fdc54
--- /dev/null
+++ b/packages/ui/src/components/callout/index.ts
@@ -0,0 +1,2 @@
+export { default as Callout } from './Callout.vue'
+export type { CalloutProps, CalloutType } from './types'
diff --git a/packages/ui/src/components/callout/types.ts b/packages/ui/src/components/callout/types.ts
new file mode 100644
index 0000000..d9cd3b7
--- /dev/null
+++ b/packages/ui/src/components/callout/types.ts
@@ -0,0 +1,9 @@
+export type CalloutType = 'note' | 'tip' | 'info' | 'warning' | 'danger'
+
+export interface CalloutProps {
+  type?: CalloutType
+  title?: string
+  collapsible?: boolean
+  defaultOpen?: boolean
+  class?: string
+}
diff --git a/packages/ui/src/components/code-group/CodeGroup.vue b/packages/ui/src/components/code-group/CodeGroup.vue
new file mode 100644
index 0000000..ba32bc5
--- /dev/null
+++ b/packages/ui/src/components/code-group/CodeGroup.vue
@@ -0,0 +1,88 @@
+<template>
+  <div :class="['overflow-hidden rounded-xl border border-slate-200/80 bg-white dark:border-slate-800 dark:bg-[#090E17]', props.class]">
+    <!-- Header Tabs Bar -->
+    <div class="flex items-center gap-1 border-b border-slate-200/80 bg-slate-50/80 px-2 pt-1.5 dark:border-slate-800 dark:bg-slate-900/50">
+      <button
+        v-for="(tab, index) in normalizedTabs"
+        :key="tab.key"
+        type="button"
+        :class="[
+          'relative flex items-center gap-1.5 rounded-t-lg px-3 py-1.5 text-xs font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]',
+          activeKey === tab.key
+            ? 'border-t border-x border-slate-200/80 bg-white text-slate-900 font-semibold dark:border-slate-800 dark:bg-[#090E17] dark:text-slate-100 -mb-px'
+            : 'text-slate-500 hover:text-slate-800 dark:text-slate-400 dark:hover:text-slate-200'
+        ]"
+        @click="selectTab(tab.key)"
+      >
+        <span>{{ tab.label }}</span>
+      </button>
+    </div>
+
+    <!-- Active Tab Content -->
+    <div class="p-0">
+      <slot :active-key="activeKey" :active-index="activeIndex">
+        <slot :name="activeKey" />
+      </slot>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import type { CodeGroupProps, CodeGroupTab } from './types'
+
+const props = withDefaults(defineProps<CodeGroupProps>(), {
+  modelValue: undefined,
+  tabs: () => [],
+  class: ''
+})
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', val: string | number): void
+  (e: 'change', val: string | number): void
+}>()
+
+interface InternalTab {
+  label: string
+  key: string
+  icon?: string
+}
+
+const normalizedTabs = computed<InternalTab[]>(() => {
+  return props.tabs.map((tab) => {
+    if (typeof tab === 'string') {
+      return { label: tab, key: tab }
+    }
+    return {
+      label: tab.label,
+      key: tab.key || tab.label,
+      icon: tab.icon
+    }
+  })
+})
+
+const internalActiveKey = ref<string | number>(
+  props.modelValue ?? (normalizedTabs.value[0]?.key || 0)
+)
+
+watch(
+  () => props.modelValue,
+  (val) => {
+    if (val !== undefined) {
+      internalActiveKey.value = val
+    }
+  }
+)
+
+const activeKey = computed(() => internalActiveKey.value)
+
+const activeIndex = computed(() => {
+  return normalizedTabs.value.findIndex((t) => t.key === activeKey.value)
+})
+
+function selectTab(key: string | number) {
+  internalActiveKey.value = key
+  emit('update:modelValue', key)
+  emit('change', key)
+}
+</script>
diff --git a/packages/ui/src/components/code-group/index.ts b/packages/ui/src/components/code-group/index.ts
new file mode 100644
index 0000000..d0477a1
--- /dev/null
+++ b/packages/ui/src/components/code-group/index.ts
@@ -0,0 +1,2 @@
+export { default as CodeGroup } from './CodeGroup.vue'
+export type { CodeGroupProps, CodeGroupTab } from './types'
diff --git a/packages/ui/src/components/code-group/types.ts b/packages/ui/src/components/code-group/types.ts
new file mode 100644
index 0000000..4438763
--- /dev/null
+++ b/packages/ui/src/components/code-group/types.ts
@@ -0,0 +1,11 @@
+export interface CodeGroupTab {
+  label: string
+  key?: string
+  icon?: string
+}
+
+export interface CodeGroupProps {
+  modelValue?: string | number
+  tabs?: (string | CodeGroupTab)[]
+  class?: string
+}
diff --git a/packages/ui/src/components/inline-code/InlineCode.vue b/packages/ui/src/components/inline-code/InlineCode.vue
new file mode 100644
index 0000000..943a553
--- /dev/null
+++ b/packages/ui/src/components/inline-code/InlineCode.vue
@@ -0,0 +1,74 @@
+<template>
+  <span
+    :class="[
+      'inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 font-mono text-[0.875em] transition-colors',
+      variantClasses,
+      copyable ? 'cursor-pointer select-none hover:bg-slate-200/80 dark:hover:bg-slate-700/80' : '',
+      props.class
+    ]"
+    :role="copyable ? 'button' : undefined"
+    :tabindex="copyable ? 0 : undefined"
+    :aria-label="copyable ? (copied ? '已复制' : '点击复制代码') : undefined"
+    @click="copyable && handleCopy()"
+    @keydown.enter.prevent="copyable && handleCopy()"
+    @keydown.space.prevent="copyable && handleCopy()"
+  >
+    <slot>{{ code }}</slot>
+    <span v-if="copyable" class="inline-flex shrink-0 items-center opacity-70">
+      <svg v-if="copied" class="h-3 w-3 text-emerald-600 dark:text-emerald-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+      </svg>
+      <svg v-else class="h-3 w-3 text-slate-400 hover:text-slate-600 dark:text-slate-500 dark:hover:text-slate-300" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M15.75 17.25v3.375c0 .621-.504 1.125-1.125 1.125h-9.75a1.125 1.125 0 01-1.125-1.125V7.875c0-.621.504-1.125 1.125-1.125H6.75a9.06 9.06 0 011.5.124m7.5 10.376h3.375c.621 0 1.125-.504 1.125-1.125V11.25c0-4.46-3.243-8.161-7.5-8.876a9.06 9.06 0 00-1.5-.124H9.375c-.621 0-1.125.504-1.125 1.125v3.5m7.5 10.375H9.375a1.125 1.125 0 01-1.125-1.125v-9.25m12 6.625v-1.875a3.375 3.375 0 00-3.375-3.375h-1.5a1.125 1.125 0 01-1.125-1.125v-1.5a3.375 3.375 0 00-3.375-3.375H9.75" />
+      </svg>
+    </span>
+  </span>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, useSlots } from 'vue'
+import type { InlineCodeProps } from './types'
+
+const props = withDefaults(defineProps<InlineCodeProps>(), {
+  code: '',
+  copyable: false,
+  variant: 'subtle',
+  class: ''
+})
+
+const slots = useSlots()
+const copied = ref(false)
+
+const variantClasses = computed(() => {
+  switch (props.variant) {
+    case 'solid':
+      return 'bg-slate-900 text-slate-100 dark:bg-slate-100 dark:text-slate-900'
+    case 'outline':
+      return 'border border-slate-300 bg-transparent text-slate-800 dark:border-slate-700 dark:text-slate-200'
+    case 'subtle':
+    default:
+      return 'border border-slate-200/80 bg-slate-100/80 text-[#1D4ED8] dark:border-slate-800 dark:bg-slate-800/80 dark:text-[#70ACFE]'
+  }
+})
+
+function getTextToCopy(): string {
+  if (props.code) return props.code
+  const defaultSlot = slots.default?.()
+  if (!defaultSlot || defaultSlot.length === 0) return ''
+  return defaultSlot.map((v) => (typeof v.children === 'string' ? v.children : '')).join('')
+}
+
+async function handleCopy() {
+  const text = getTextToCopy()
+  if (!text) return
+  try {
+    await navigator.clipboard.writeText(text)
+    copied.value = true
+    setTimeout(() => {
+      copied.value = false
+    }, 1800)
+  } catch {
+    // clipboard failure fallback
+  }
+}
+</script>
diff --git a/packages/ui/src/components/inline-code/index.ts b/packages/ui/src/components/inline-code/index.ts
new file mode 100644
index 0000000..62e5ab9
--- /dev/null
+++ b/packages/ui/src/components/inline-code/index.ts
@@ -0,0 +1,2 @@
+export { default as InlineCode } from './InlineCode.vue'
+export type { InlineCodeProps } from './types'
diff --git a/packages/ui/src/components/inline-code/types.ts b/packages/ui/src/components/inline-code/types.ts
new file mode 100644
index 0000000..86e8dcc
--- /dev/null
+++ b/packages/ui/src/components/inline-code/types.ts
@@ -0,0 +1,6 @@
+export interface InlineCodeProps {
+  code?: string
+  copyable?: boolean
+  variant?: 'subtle' | 'solid' | 'outline'
+  class?: string
+}
diff --git a/packages/ui/src/components/nav-tree/NavTree.vue b/packages/ui/src/components/nav-tree/NavTree.vue
new file mode 100644
index 0000000..353e3ce
--- /dev/null
+++ b/packages/ui/src/components/nav-tree/NavTree.vue
@@ -0,0 +1,124 @@
+<template>
+  <nav :class="['w-full space-y-4 text-sm', props.class]" aria-label="文档侧栏导航">
+    <!-- Optional Search Input -->
+    <div v-if="searchable" class="relative">
+      <input
+        v-model="query"
+        type="search"
+        :placeholder="searchPlaceholder || docsLoc.searchPlaceholder"
+        class="w-full rounded-lg border border-slate-200/80 bg-white px-3 py-1.5 pl-8 text-xs text-slate-900 placeholder:text-slate-400 focus:border-[#2563EB] focus:outline-none focus:ring-1 focus:ring-[#2563EB] dark:border-slate-800 dark:bg-slate-900 dark:text-slate-100 dark:placeholder:text-slate-500"
+      />
+      <svg class="absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-slate-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <circle cx="11" cy="11" r="8" />
+        <path stroke-linecap="round" d="m21 21-4.35-4.35" />
+      </svg>
+    </div>
+
+    <!-- Groups list -->
+    <div class="space-y-6">
+      <div v-for="(group, gIdx) in filteredGroups" :key="group.title + gIdx" class="space-y-2">
+        <!-- Group Header -->
+        <div
+          :class="[
+            'flex items-center justify-between px-2 text-xs font-semibold tracking-wider text-slate-500 uppercase dark:text-slate-400',
+            group.collapsible ? 'cursor-pointer select-none hover:text-slate-800 dark:hover:text-slate-200' : ''
+          ]"
+          @click="group.collapsible && toggleGroup(group.title)"
+        >
+          <span>{{ group.title }}</span>
+          <button
+            v-if="group.collapsible"
+            type="button"
+            class="rounded p-0.5 text-slate-400 hover:text-slate-600 dark:hover:text-slate-200"
+          >
+            <svg
+              class="h-3.5 w-3.5 transition-transform duration-200"
+              :class="isGroupCollapsed(group.title) ? '-rotate-90' : ''"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+            >
+              <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 8.25l-7.5 7.5-7.5-7.5" />
+            </svg>
+          </button>
+        </div>
+
+        <!-- Group items -->
+        <ul v-show="!isGroupCollapsed(group.title)" class="space-y-0.5">
+          <li v-for="item in group.items" :key="item.href || item.to || item.title">
+            <component
+              :is="item.to ? 'RouterLink' : 'a'"
+              v-bind="item.to ? { to: item.to } : { href: item.href || '#' }"
+              :class="[
+                'group flex items-center justify-between rounded-lg px-2.5 py-1.5 text-xs font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[#2563EB]',
+                isItemActive(item)
+                  ? 'bg-[#2563EB]/10 font-semibold text-[#1D4ED8] dark:bg-[#2563EB]/20 dark:text-[#70ACFE]'
+                  : 'text-slate-600 hover:bg-slate-100 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-800/60 dark:hover:text-slate-200'
+              ]"
+            >
+              <div class="flex items-center gap-2 truncate">
+                <component :is="item.icon" v-if="item.icon" class="h-3.5 w-3.5 shrink-0" />
+                <span class="truncate">{{ item.title }}</span>
+              </div>
+              <span
+                v-if="item.badge"
+                class="ml-2 inline-flex shrink-0 items-center rounded px-1.5 py-0.2 text-[10px] font-semibold text-[#1D4ED8] bg-[#2563EB]/10 dark:text-[#70ACFE] dark:bg-[#70ACFE]/10"
+              >
+                {{ item.badge }}
+              </span>
+            </component>
+          </li>
+        </ul>
+      </div>
+    </div>
+  </nav>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { useComponentLocale } from '../../locale'
+import type { NavTreeGroup, NavTreeItem, NavTreeProps } from './types'
+
+const props = withDefaults(defineProps<NavTreeProps>(), {
+  groups: () => [],
+  activeHref: '',
+  searchable: false,
+  searchPlaceholder: undefined,
+  class: ''
+})
+
+const docsLoc = useComponentLocale('docs')
+const query = ref('')
+const collapsedGroups = ref<Set<string>>(new Set())
+
+function isGroupCollapsed(title: string): boolean {
+  return collapsedGroups.value.has(title)
+}
+
+function toggleGroup(title: string) {
+  if (collapsedGroups.value.has(title)) {
+    collapsedGroups.value.delete(title)
+  } else {
+    collapsedGroups.value.add(title)
+  }
+}
+
+function isItemActive(item: NavTreeItem): boolean {
+  if (!props.activeHref) return false
+  const target = item.to || item.href
+  return target === props.activeHref
+}
+
+const filteredGroups = computed<NavTreeGroup[]>(() => {
+  const q = query.value.trim().toLowerCase()
+  if (!q) return props.groups
+
+  return props.groups
+    .map((g) => ({
+      ...g,
+      items: g.items.filter((item) => item.title.toLowerCase().includes(q))
+    }))
+    .filter((g) => g.items.length > 0)
+})
+</script>
diff --git a/packages/ui/src/components/nav-tree/index.ts b/packages/ui/src/components/nav-tree/index.ts
new file mode 100644
index 0000000..df463aa
--- /dev/null
+++ b/packages/ui/src/components/nav-tree/index.ts
@@ -0,0 +1,2 @@
+export { default as NavTree } from './NavTree.vue'
+export type { NavTreeGroup, NavTreeItem, NavTreeProps } from './types'
diff --git a/packages/ui/src/components/nav-tree/types.ts b/packages/ui/src/components/nav-tree/types.ts
new file mode 100644
index 0000000..cb97d5d
--- /dev/null
+++ b/packages/ui/src/components/nav-tree/types.ts
@@ -0,0 +1,25 @@
+import type { Component } from 'vue'
+
+export interface NavTreeItem {
+  title: string
+  href?: string
+  to?: string
+  badge?: string
+  icon?: Component
+  disabled?: boolean
+}
+
+export interface NavTreeGroup {
+  title: string
+  collapsible?: boolean
+  defaultOpen?: boolean
+  items: NavTreeItem[]
+}
+
+export interface NavTreeProps {
+  groups: NavTreeGroup[]
+  activeHref?: string
+  searchable?: boolean
+  searchPlaceholder?: string
+  class?: string
+}
diff --git a/packages/ui/src/components/prev-next/PrevNext.vue b/packages/ui/src/components/prev-next/PrevNext.vue
new file mode 100644
index 0000000..120c04a
--- /dev/null
+++ b/packages/ui/src/components/prev-next/PrevNext.vue
@@ -0,0 +1,68 @@
+<template>
+  <nav
+    v-if="prev || next"
+    :class="[
+      'grid grid-cols-1 gap-4 pt-6 sm:grid-cols-2',
+      props.class
+    ]"
+    aria-label="文档分页导航"
+  >
+    <!-- Previous link card -->
+    <component
+      :is="prev?.to ? 'RouterLink' : 'a'"
+      v-if="prev"
+      v-bind="prev.to ? { to: prev.to } : { href: prev.href || '#' }"
+      class="group relative flex flex-col items-start rounded-xl border border-slate-200/80 bg-white p-4 transition-all hover:border-[#2563EB]/40 hover:shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:border-slate-800 dark:bg-[#0F172A] dark:hover:border-[#70ACFE]/40"
+    >
+      <span class="inline-flex items-center gap-1 text-xs font-medium text-slate-500 transition-colors group-hover:text-[#2563EB] dark:text-slate-400 dark:group-hover:text-[#70ACFE]">
+        <svg class="h-3.5 w-3.5 transition-transform group-hover:-translate-x-0.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M15.75 19.5L8.25 12l7.5-7.5" />
+        </svg>
+        <span>{{ prevLabel || docsLoc.prev }}</span>
+      </span>
+      <span class="mt-1 text-sm font-semibold text-slate-900 group-hover:text-[#2563EB] dark:text-slate-100 dark:group-hover:text-[#70ACFE]">
+        {{ prev.title }}
+      </span>
+      <span v-if="prev.description" class="mt-0.5 line-clamp-1 text-xs text-slate-500 dark:text-slate-400">
+        {{ prev.description }}
+      </span>
+    </component>
+    <div v-else class="hidden sm:block" />
+
+    <!-- Next link card -->
+    <component
+      :is="next?.to ? 'RouterLink' : 'a'"
+      v-if="next"
+      v-bind="next.to ? { to: next.to } : { href: next.href || '#' }"
+      class="group relative flex flex-col items-end rounded-xl border border-slate-200/80 bg-white p-4 text-right transition-all hover:border-[#2563EB]/40 hover:shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:border-slate-800 dark:bg-[#0F172A] dark:hover:border-[#70ACFE]/40"
+    >
+      <span class="inline-flex items-center gap-1 text-xs font-medium text-slate-500 transition-colors group-hover:text-[#2563EB] dark:text-slate-400 dark:group-hover:text-[#70ACFE]">
+        <span>{{ nextLabel || docsLoc.next }}</span>
+        <svg class="h-3.5 w-3.5 transition-transform group-hover:translate-x-0.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M8.25 4.5l7.5 7.5-7.5 7.5" />
+        </svg>
+      </span>
+      <span class="mt-1 text-sm font-semibold text-slate-900 group-hover:text-[#2563EB] dark:text-slate-100 dark:group-hover:text-[#70ACFE]">
+        {{ next.title }}
+      </span>
+      <span v-if="next.description" class="mt-0.5 line-clamp-1 text-xs text-slate-500 dark:text-slate-400">
+        {{ next.description }}
+      </span>
+    </component>
+  </nav>
+</template>
+
+<script setup lang="ts">
+import { useComponentLocale } from '../../locale'
+import type { PrevNextProps } from './types'
+
+const props = withDefaults(defineProps<PrevNextProps>(), {
+  prev: undefined,
+  next: undefined,
+  prevLabel: undefined,
+  nextLabel: undefined,
+  class: ''
+})
+
+const docsLoc = useComponentLocale('docs')
+</script>
diff --git a/packages/ui/src/components/prev-next/index.ts b/packages/ui/src/components/prev-next/index.ts
new file mode 100644
index 0000000..40eedfe
--- /dev/null
+++ b/packages/ui/src/components/prev-next/index.ts
@@ -0,0 +1,2 @@
+export { default as PrevNext } from './PrevNext.vue'
+export type { PrevNextItem, PrevNextProps } from './types'
diff --git a/packages/ui/src/components/prev-next/types.ts b/packages/ui/src/components/prev-next/types.ts
new file mode 100644
index 0000000..4832ee6
--- /dev/null
+++ b/packages/ui/src/components/prev-next/types.ts
@@ -0,0 +1,14 @@
+export interface PrevNextItem {
+  title: string
+  href?: string
+  to?: string
+  description?: string
+}
+
+export interface PrevNextProps {
+  prev?: PrevNextItem
+  next?: PrevNextItem
+  prevLabel?: string
+  nextLabel?: string
+  class?: string
+}
diff --git a/packages/ui/src/components/steps/StepItem.vue b/packages/ui/src/components/steps/StepItem.vue
new file mode 100644
index 0000000..3a1c1d3
--- /dev/null
+++ b/packages/ui/src/components/steps/StepItem.vue
@@ -0,0 +1,53 @@
+<template>
+  <div :class="['relative border-l-2 border-slate-200 pl-8 pb-2 dark:border-slate-800 last:border-transparent', props.class]">
+    <!-- Step Badge / Number indicator -->
+    <div
+      class="absolute -left-[17px] top-0 flex h-8 w-8 items-center justify-center rounded-full border-2 border-white bg-[#2563EB] text-xs font-semibold text-white shadow-sm ring-1 ring-slate-900/5 dark:border-[#090E17] dark:bg-[#2563EB] dark:ring-white/10"
+    >
+      <slot name="step">
+        {{ computedStep }}
+      </slot>
+    </div>
+
+    <!-- Title & Description Header -->
+    <div v-if="title || description || $slots.title || $slots.description" class="mb-3">
+      <h3 v-if="title || $slots.title" class="text-base font-semibold tracking-tight text-slate-900 dark:text-slate-100">
+        <slot name="title">{{ title }}</slot>
+      </h3>
+      <p v-if="description || $slots.description" class="mt-1 text-sm text-slate-600 dark:text-slate-400">
+        <slot name="description">{{ description }}</slot>
+      </p>
+    </div>
+
+    <!-- Step Body -->
+    <div class="space-y-4 text-sm leading-relaxed text-slate-700 dark:text-slate-300">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, inject, onMounted, ref } from 'vue'
+import { stepsInjectionKey, type StepItemProps } from './types'
+
+const props = withDefaults(defineProps<StepItemProps>(), {
+  title: '',
+  description: '',
+  step: undefined,
+  class: ''
+})
+
+const context = inject(stepsInjectionKey, null)
+const autoStepIndex = ref<number>(1)
+
+onMounted(() => {
+  if (context && props.step === undefined) {
+    autoStepIndex.value = context.registerStep()
+  }
+})
+
+const computedStep = computed(() => {
+  if (props.step !== undefined) return props.step
+  return autoStepIndex.value
+})
+</script>
diff --git a/packages/ui/src/components/steps/Steps.vue b/packages/ui/src/components/steps/Steps.vue
new file mode 100644
index 0000000..3475641
--- /dev/null
+++ b/packages/ui/src/components/steps/Steps.vue
@@ -0,0 +1,25 @@
+<template>
+  <div :class="['space-y-8 pl-4', props.class]">
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { provide, ref } from 'vue'
+import { stepsInjectionKey, type StepsProps } from './types'
+
+const props = withDefaults(defineProps<StepsProps>(), {
+  startIndex: 1,
+  class: ''
+})
+
+const counter = ref(props.startIndex)
+
+provide(stepsInjectionKey, {
+  registerStep: () => {
+    const current = counter.value
+    counter.value += 1
+    return current
+  }
+})
+</script>
diff --git a/packages/ui/src/components/steps/index.ts b/packages/ui/src/components/steps/index.ts
new file mode 100644
index 0000000..e1db8ed
--- /dev/null
+++ b/packages/ui/src/components/steps/index.ts
@@ -0,0 +1,3 @@
+export { default as Steps } from './Steps.vue'
+export { default as StepItem } from './StepItem.vue'
+export type { StepItemProps, StepsProps } from './types'
diff --git a/packages/ui/src/components/steps/types.ts b/packages/ui/src/components/steps/types.ts
new file mode 100644
index 0000000..1064753
--- /dev/null
+++ b/packages/ui/src/components/steps/types.ts
@@ -0,0 +1,19 @@
+import type { InjectionKey } from 'vue'
+
+export interface StepsProps {
+  startIndex?: number
+  class?: string
+}
+
+export interface StepItemProps {
+  title?: string
+  description?: string
+  step?: number | string
+  class?: string
+}
+
+export interface StepsContext {
+  registerStep: () => number
+}
+
+export const stepsInjectionKey: InjectionKey<StepsContext> = Symbol('re-steps')
diff --git a/packages/ui/src/components/toc/Toc.vue b/packages/ui/src/components/toc/Toc.vue
new file mode 100644
index 0000000..f023abf
--- /dev/null
+++ b/packages/ui/src/components/toc/Toc.vue
@@ -0,0 +1,171 @@
+<template>
+  <nav
+    :class="[
+      'space-y-3 text-sm',
+      props.class
+    ]"
+    :aria-label="title || docsLoc.toc"
+  >
+    <!-- Header / Title -->
+    <div class="flex items-center gap-2 font-medium text-slate-900 dark:text-slate-100">
+      <svg class="h-4 w-4 text-[#2563EB] dark:text-[#70ACFE]" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25H12" />
+      </svg>
+      <slot name="title">
+        <span>{{ title || docsLoc.toc }}</span>
+      </slot>
+    </div>
+
+    <!-- Empty fallback -->
+    <div v-if="parsedItems.length === 0" class="text-xs text-slate-400 dark:text-slate-500 py-1">
+      暂无目录
+    </div>
+
+    <!-- Tree items -->
+    <ul v-else class="space-y-1.5 border-l border-slate-200/80 dark:border-slate-800">
+      <li
+        v-for="item in parsedItems"
+        :key="item.id"
+        :class="[
+          'relative text-xs leading-relaxed transition-colors',
+          item.level === 3 ? 'pl-6' : 'pl-3'
+        ]"
+      >
+        <!-- Active indicator line -->
+        <span
+          v-if="activeId === item.id"
+          class="absolute -left-px top-1 bottom-1 w-0.5 rounded-full bg-[#2563EB] dark:bg-[#70ACFE]"
+        />
+        <a
+          :href="`#${item.id}`"
+          :class="[
+            'block truncate transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[#2563EB]',
+            activeId === item.id
+              ? 'font-medium text-[#2563EB] dark:text-[#70ACFE]'
+              : 'text-slate-600 hover:text-slate-900 dark:text-slate-400 dark:hover:text-slate-200'
+          ]"
+          @click.prevent="scrollTo(item.id)"
+        >
+          {{ item.title }}
+        </a>
+      </li>
+    </ul>
+  </nav>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useComponentLocale } from '../../locale'
+import type { TocItem, TocProps } from './types'
+
+const props = withDefaults(defineProps<TocProps>(), {
+  items: undefined,
+  selector: 'h2, h3',
+  container: undefined,
+  scrollSpy: true,
+  title: undefined,
+  offset: 80,
+  class: ''
+})
+
+const docsLoc = useComponentLocale('docs')
+const dynamicItems = ref<TocItem[]>([])
+const activeId = ref<string>('')
+
+const parsedItems = computed<TocItem[]>(() => {
+  if (props.items && props.items.length > 0) return props.items
+  return dynamicItems.value
+})
+
+function collectHeadings() {
+  if (typeof document === 'undefined') return
+  if (props.items && props.items.length > 0) return
+
+  const root = props.container ? document.querySelector(props.container) : document
+  if (!root) return
+
+  const elements = root.querySelectorAll(props.selector)
+  const items: TocItem[] = []
+
+  elements.forEach((el) => {
+    const id = el.id
+    const title = el.textContent?.replace(/^#\s*/, '').trim() || ''
+    const tagName = el.tagName.toLowerCase()
+    const level = tagName === 'h3' ? 3 : 2
+
+    if (id && title) {
+      items.push({ id, title, level })
+    }
+  })
+
+  dynamicItems.value = items
+  if (items.length > 0 && !activeId.value) {
+    activeId.value = items[0]?.id ?? ''
+  }
+}
+
+function scrollTo(id: string) {
+  if (typeof document === 'undefined') return
+  const el = document.getElementById(id)
+  if (!el) return
+
+  activeId.value = id
+  const targetTop = el.getBoundingClientRect().top + window.scrollY - props.offset
+  window.scrollTo({
+    top: Math.max(0, targetTop),
+    behavior: 'smooth'
+  })
+
+  if (history.pushState) {
+    history.pushState(null, '', `#${id}`)
+  }
+}
+
+let observer: IntersectionObserver | null = null
+
+function setupObserver() {
+  if (typeof window === 'undefined' || !props.scrollSpy) return
+  if (!('IntersectionObserver' in window)) return
+
+  observer?.disconnect()
+
+  observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          activeId.value = entry.target.id
+          break
+        }
+      }
+    },
+    {
+      rootMargin: `-${props.offset}px 0px -60% 0px`,
+      threshold: 0
+    }
+  )
+
+  const ids = parsedItems.value.map((i) => i.id)
+  ids.forEach((id) => {
+    const el = document.getElementById(id)
+    if (el) observer?.observe(el)
+  })
+}
+
+onMounted(() => {
+  collectHeadings()
+  setupObserver()
+})
+
+watch(
+  () => [props.items, props.selector, props.container],
+  () => {
+    collectHeadings()
+    setupObserver()
+  },
+  { deep: true }
+)
+
+onBeforeUnmount(() => {
+  observer?.disconnect()
+})
+</script>
diff --git a/packages/ui/src/components/toc/index.ts b/packages/ui/src/components/toc/index.ts
new file mode 100644
index 0000000..7ed8f19
--- /dev/null
+++ b/packages/ui/src/components/toc/index.ts
@@ -0,0 +1,2 @@
+export { default as Toc } from './Toc.vue'
+export type { TocItem, TocProps } from './types'
diff --git a/packages/ui/src/components/toc/types.ts b/packages/ui/src/components/toc/types.ts
new file mode 100644
index 0000000..c99dd84
--- /dev/null
+++ b/packages/ui/src/components/toc/types.ts
@@ -0,0 +1,16 @@
+export interface TocItem {
+  id: string
+  title: string
+  level?: number
+  children?: TocItem[]
+}
+
+export interface TocProps {
+  items?: TocItem[]
+  selector?: string
+  container?: string
+  scrollSpy?: boolean
+  title?: string
+  offset?: number
+  class?: string
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index e10f685..075a331 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -58,6 +58,14 @@ export * from './components/file-upload'
 export * from './components/multi-select'
 export * from './components/tree-view'
 export * from './components/timeline'
+export * from './components/callout'
+export * from './components/inline-code'
+export * from './components/steps'
+export * from './components/anchor-heading'
+export * from './components/toc'
+export * from './components/prev-next'
+export * from './components/nav-tree'
+export * from './components/code-group'
 
 // Composables & Utilities
 export * from './composables/useTheme'
diff --git a/packages/ui/src/locale/messages.ts b/packages/ui/src/locale/messages.ts
index 819af4a..120f387 100644
--- a/packages/ui/src/locale/messages.ts
+++ b/packages/ui/src/locale/messages.ts
@@ -94,6 +94,14 @@ export interface LocaleMessages {
     confirm: string
     cancel: string
   }
+  docs: {
+    toc: string
+    prev: string
+    next: string
+    copyLink: string
+    copiedLink: string
+    searchPlaceholder: string
+  }
 }
 
 export type DeepPartial<T> = {
@@ -199,6 +207,14 @@ export const zhCN: LocaleMessages = {
   alertDialog: {
     confirm: '确认',
     cancel: '取消'
+  },
+  docs: {
+    toc: '本页目录',
+    prev: '上一篇',
+    next: '下一篇',
+    copyLink: '复制链接',
+    copiedLink: '已复制链接',
+    searchPlaceholder: '搜索文档...'
   }
 }
 
@@ -297,5 +313,13 @@ export const enUS: LocaleMessages = {
   alertDialog: {
     confirm: 'Confirm',
     cancel: 'Cancel'
+  },
+  docs: {
+    toc: 'On this page',
+    prev: 'Previous',
+    next: 'Next',
+    copyLink: 'Copy link',
+    copiedLink: 'Link copied',
+    searchPlaceholder: 'Search documentation...'
   }
 }

From 10457fd477b2ed1359dd96ced86c5dd8f85a03ed Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 06:34:35 +0800
Subject: [PATCH 22/26] feat(landing): add Navbar, Footer, and Hero components

---
 .changeset/calm-landing-suite-arrive.md       |   5 +
 apps/playground/pages/components/footer.vue   |  75 ++++++++
 apps/playground/pages/components/hero.vue     |  95 ++++++++++
 apps/playground/pages/components/navbar.vue   |  60 ++++++
 apps/playground/utils/catalog.ts              |   8 +
 packages/ui/src/components/footer/Footer.vue  |  97 ++++++++++
 .../ui/src/components/footer/footer.test.ts   |   9 +
 packages/ui/src/components/footer/index.ts    |   2 +
 packages/ui/src/components/footer/types.ts    |  27 +++
 packages/ui/src/components/hero/Hero.vue      | 179 ++++++++++++++++++
 packages/ui/src/components/hero/hero.test.ts  |   9 +
 packages/ui/src/components/hero/index.ts      |   2 +
 packages/ui/src/components/hero/types.ts      |  11 ++
 packages/ui/src/components/navbar/Navbar.vue  | 147 ++++++++++++++
 packages/ui/src/components/navbar/index.ts    |   2 +
 .../ui/src/components/navbar/navbar.test.ts   |   9 +
 packages/ui/src/components/navbar/types.ts    |  18 ++
 packages/ui/src/index.ts                      |   3 +
 18 files changed, 758 insertions(+)
 create mode 100644 .changeset/calm-landing-suite-arrive.md
 create mode 100644 apps/playground/pages/components/footer.vue
 create mode 100644 apps/playground/pages/components/hero.vue
 create mode 100644 apps/playground/pages/components/navbar.vue
 create mode 100644 packages/ui/src/components/footer/Footer.vue
 create mode 100644 packages/ui/src/components/footer/footer.test.ts
 create mode 100644 packages/ui/src/components/footer/index.ts
 create mode 100644 packages/ui/src/components/footer/types.ts
 create mode 100644 packages/ui/src/components/hero/Hero.vue
 create mode 100644 packages/ui/src/components/hero/hero.test.ts
 create mode 100644 packages/ui/src/components/hero/index.ts
 create mode 100644 packages/ui/src/components/hero/types.ts
 create mode 100644 packages/ui/src/components/navbar/Navbar.vue
 create mode 100644 packages/ui/src/components/navbar/index.ts
 create mode 100644 packages/ui/src/components/navbar/navbar.test.ts
 create mode 100644 packages/ui/src/components/navbar/types.ts

diff --git a/.changeset/calm-landing-suite-arrive.md b/.changeset/calm-landing-suite-arrive.md
new file mode 100644
index 0000000..349fe09
--- /dev/null
+++ b/.changeset/calm-landing-suite-arrive.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add landing page components: Navbar (SiteHeader), Footer, and Hero with layout variants, responsive mobile drawer, and CTA slots.
diff --git a/apps/playground/pages/components/footer.vue b/apps/playground/pages/components/footer.vue
new file mode 100644
index 0000000..f74de8c
--- /dev/null
+++ b/apps/playground/pages/components/footer.vue
@@ -0,0 +1,75 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Footer 站点页脚" description="多列链接分组、产品定位说明、版权声明与社交媒体图标插槽。" />
+
+    <DocExample title="多列站点页脚" description="包含品牌简述、4 列导航分组与底部版权条。" :code="codeBasic">
+      <div class="overflow-hidden rounded-xl border border-slate-200/80 bg-white dark:border-slate-800 dark:bg-[#0B1220]">
+        <Footer
+          brand-title="ReCloud Studio"
+          brand-description="面向开发者工具、自动化服务与现代运维控制台的 Vue 3 & Nuxt 4 界面系统。"
+          :columns="sampleColumns"
+          :socials="sampleSocials"
+        />
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="footer" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const sampleColumns = [
+  {
+    title: '产品',
+    links: [
+      { label: '组件总览', to: '/components/button' },
+      { label: '设计令牌', to: '/components/callout' },
+      { label: '更新日志', to: '/components/timeline' }
+    ]
+  },
+  {
+    title: '开发者',
+    links: [
+      { label: '快速上手', to: '/components/steps' },
+      { label: 'GitHub 仓库', href: 'https://github.com/ReCloudStudio/UI', target: '_blank' },
+      { label: '代码规范', href: '#' }
+    ]
+  },
+  {
+    title: '资源',
+    links: [
+      { label: 'Figma 设计稿', href: '#' },
+      { label: '技术博客', href: '#' }
+    ]
+  }
+]
+
+const sampleSocials = [
+  { name: 'GitHub', href: 'https://github.com/ReCloudStudio/UI' },
+  { name: 'Discord', href: '#' },
+  { name: 'X / Twitter', href: '#' }
+]
+
+const codeBasic = `<Footer
+  brand-title="ReCloud Studio"
+  brand-description="面向开发者工具与现代运维控制台的 UI 系统。"
+  :columns="sampleColumns"
+  :socials="sampleSocials"
+/>`
+
+const apiRows = [
+  { name: 'brandTitle', type: 'string', default: "''", description: '品牌名称。' },
+  { name: 'brandDescription', type: 'string', default: "''", description: '品牌描述正文。' },
+  { name: 'columns', type: 'FooterColumn[]', default: '[]', description: '导航列配置数组：title、links（label、href?、to?、target?）。' },
+  { name: 'copyright', type: 'string', default: '依当前年份自动生成', description: '底部版权文案。' },
+  { name: 'socials', type: 'FooterSocial[]', default: '[]', description: '社交媒体链接数组：name、href、icon?。' },
+  { name: 'bordered', type: 'boolean', default: 'true', description: '是否展示顶部边框。' },
+  { name: 'slot: logo', type: 'slot', default: '—', description: '自定义品牌 Logo。' },
+  { name: 'slot: brand', type: 'slot', default: '—', description: '自定义品牌名称。' },
+  { name: 'slot: description', type: 'slot', default: '—', description: '自定义品牌描述区域。' },
+  { name: 'slot: newsletter', type: 'slot', default: '—', description: '品牌下方的订阅表单区域。' },
+  { name: 'slot: socials', type: 'slot', default: '—', description: '底部社交媒体插槽。' },
+  { name: 'slot: copyright', type: 'slot', default: '—', description: '底部版权声明插槽。' }
+]
+</script>
diff --git a/apps/playground/pages/components/hero.vue b/apps/playground/pages/components/hero.vue
new file mode 100644
index 0000000..ac06fd8
--- /dev/null
+++ b/apps/playground/pages/components/hero.vue
@@ -0,0 +1,95 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Hero 首屏横幅" description="面向落地页、官网门户与产品首页的首屏大横幅，支持居中排版、左右图文分栏及紧凑极简模式。" />
+
+    <DocExample title="居中主视觉模式 (center)" description="适合配合徽标、醒目标题、副标题、双 CTA 与下方预览画面。" :code="codeCenter">
+      <div class="overflow-hidden rounded-xl border border-slate-200/80 bg-white dark:border-slate-800 dark:bg-[#0B1220]">
+        <Hero
+          layout="center"
+          badge="v0.2.0 已正式发布"
+          title="专为运维控制台打造的 UI 系统"
+          description="基于 Vue 3、Nuxt 4 与 Reka UI 构建，提供无障碍基础底座与分层设计令牌，助力高效交付开发者工具。"
+          primary-action-text="快速上手"
+          secondary-action-text="浏览组件"
+          @primary-click="onStart"
+          @secondary-click="onDocs"
+        >
+          <template #media>
+            <div class="mx-auto max-w-2xl rounded-xl border border-slate-200/80 bg-slate-50 p-6 shadow-sm dark:border-slate-800 dark:bg-slate-900/60 text-center font-mono text-xs text-slate-500">
+              [产品控制台界面预览交互展示区]
+            </div>
+          </template>
+        </Hero>
+      </div>
+    </DocExample>
+
+    <DocExample title="图文分栏模式 (split)" description="左侧文本导流，右侧展示交互模型或媒体卡片。" :code="codeSplit">
+      <div class="overflow-hidden rounded-xl border border-slate-200/80 bg-white dark:border-slate-800 dark:bg-[#0B1220]">
+        <Hero
+          layout="split"
+          badge="云原生时代"
+          title="下一代基础设施控制台"
+          description="轻量、确定性、高可访问性，专为工程师与自动化服务深度打磨。"
+          primary-action-text="免费试用"
+          secondary-action-text="查看架构"
+        >
+          <template #media>
+            <div class="aspect-video w-full rounded-xl border border-slate-200 bg-slate-100 flex items-center justify-center font-mono text-xs text-slate-400 dark:border-slate-800 dark:bg-slate-900">
+              架构拓扑插槽
+            </div>
+          </template>
+        </Hero>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="hero" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const codeCenter = `<Hero
+  layout="center"
+  badge="v0.2.0 已正式发布"
+  title="专为运维控制台打造的 UI 系统"
+  description="基于 Vue 3、Nuxt 4 构建，提供无障碍底座与分层设计令牌。"
+  primary-action-text="快速上手"
+  secondary-action-text="浏览组件"
+>
+  <template #media>
+    <!-- 控制台预览图或演示窗口 -->
+  </template>
+</Hero>`
+
+const codeSplit = `<Hero
+  layout="split"
+  badge="云原生时代"
+  title="下一代基础设施控制台"
+  description="轻量、确定性、高可访问性。"
+  primary-action-text="免费试用"
+  secondary-action-text="查看架构"
+>
+  <template #media>
+    <!-- 拓扑插图或架构图 -->
+  </template>
+</Hero>`
+
+const apiRows = [
+  { name: 'layout', type: "'center' | 'split' | 'minimal'", default: "'center'", description: '横幅排版结构变体。' },
+  { name: 'badge', type: 'string', default: 'undefined', description: '顶部小胶囊徽标文本。' },
+  { name: 'title', type: 'string', default: "''", description: '主标题文本。' },
+  { name: 'description', type: 'string', default: 'undefined', description: '副标题/介绍段落。' },
+  { name: 'primaryActionText', type: 'string', default: 'undefined', description: '主要按钮文本。' },
+  { name: 'secondaryActionText', type: 'string', default: 'undefined', description: '次要按钮文本。' },
+  { name: 'event: primary-click', type: 'event', default: '—', description: '点击主要按钮时触发。' },
+  { name: 'event: secondary-click', type: 'event', default: '—', description: '点击次要按钮时触发。' },
+  { name: 'slot: title', type: 'slot', default: '—', description: '自定义主标题。' },
+  { name: 'slot: description', type: 'slot', default: '—', description: '自定义介绍副标题。' },
+  { name: 'slot: badge', type: 'slot', default: '—', description: '自定义顶部徽标。' },
+  { name: 'slot: actions', type: 'slot', default: '—', description: '自定义全部 CTA 按钮组。' },
+  { name: 'slot: media', type: 'slot', default: '—', description: '产品交互或媒体预览插槽。' }
+]
+
+function onStart() {}
+function onDocs() {}
+</script>
diff --git a/apps/playground/pages/components/navbar.vue b/apps/playground/pages/components/navbar.vue
new file mode 100644
index 0000000..b2489c4
--- /dev/null
+++ b/apps/playground/pages/components/navbar.vue
@@ -0,0 +1,60 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader title="Navbar 导航顶栏" description="面向站点与文档门户的全局导航顶栏，支持品牌 Logo、桌面链接、快捷 CTA 与移动端折叠抽屉。" />
+
+    <DocExample title="基础顶栏" description="集成品牌、徽标链接、操作按钮及移动端抽屉。" :code="codeBasic">
+      <div class="overflow-hidden rounded-xl border border-slate-200/80 bg-slate-50/50 dark:border-slate-800 dark:bg-slate-900/30">
+        <Navbar
+          brand-title="ReCloud"
+          :links="navLinks"
+          :sticky="false"
+        >
+          <template #actions>
+            <Button size="sm" variant="ghost">登录</Button>
+            <Button size="sm">快速开始</Button>
+          </template>
+        </Navbar>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="navbar" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const navLinks = [
+  { label: '功能特性', href: '#features' },
+  { label: '组件文档', to: '/components/button' },
+  { label: '更新日志', to: '/components/timeline', badge: 'v0.2.0' },
+  { label: '定价', href: '#pricing' }
+]
+
+const codeBasic = `<Navbar
+  brand-title="ReCloud"
+  :links="[
+    { label: '功能特性', href: '#features' },
+    { label: '组件文档', to: '/components/button' },
+    { label: '更新日志', to: '/components/timeline', badge: 'v0.2.0' }
+  ]"
+>
+  <template #actions>
+    <Button size="sm" variant="ghost">登录</Button>
+    <Button size="sm">快速开始</Button>
+  </template>
+</Navbar>`
+
+const apiRows = [
+  { name: 'brandTitle', type: 'string', default: "''", description: '品牌标题文本。' },
+  { name: 'brandHref', type: 'string', default: "'/'", description: '品牌 Logo 的普通外链目标。' },
+  { name: 'brandTo', type: 'string', default: 'undefined', description: '品牌 Logo 的路由跳转目标（Vue Router / Nuxt）。' },
+  { name: 'links', type: 'NavbarLink[]', default: '[]', description: '导航链接列表：label、href?、to?、badge?、active?。' },
+  { name: 'sticky', type: 'boolean', default: 'true', description: '是否在页面顶部粘性吸顶固定。' },
+  { name: 'bordered', type: 'boolean', default: 'true', description: '是否展示底部微边框。' },
+  { name: 'slot: logo', type: 'slot', default: '—', description: '自定义品牌 Logo 图标。' },
+  { name: 'slot: brand', type: 'slot', default: '—', description: '自定义品牌标题区域。' },
+  { name: 'slot: links', type: 'slot', default: '—', description: '自定义桌面端链接。' },
+  { name: 'slot: actions', type: 'slot', default: '—', description: '右侧 CTA 操作按钮组。' },
+  { name: 'slot: extra', type: 'slot', default: '—', description: '右侧辅助组件（如主题切换、搜索）。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 80fa848..562ee46 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -119,6 +119,14 @@ const groups: DocGroup[] = [
       { name: 'code-group', title: 'CodeGroup 代码分组', description: '多包管理器与多语言代码块选项卡容器。' }
     ]
   },
+  {
+    label: '营销与门户',
+    items: [
+      { name: 'navbar', title: 'Navbar 导航顶栏', description: '站点级全局顶栏，集成品牌标识、链接、操作与移动端抽屉。' },
+      { name: 'footer', title: 'Footer 站点页脚', description: '多列分组链接、版权信息与社交链接插槽。' },
+      { name: 'hero', title: 'Hero 首屏横幅', description: '落地页与产品首页主视觉横幅，支持居中、图文左右分栏及极简模式。' }
+    ]
+  },
   {
     label: '工具',
     items: [
diff --git a/packages/ui/src/components/footer/Footer.vue b/packages/ui/src/components/footer/Footer.vue
new file mode 100644
index 0000000..c9fca03
--- /dev/null
+++ b/packages/ui/src/components/footer/Footer.vue
@@ -0,0 +1,97 @@
+<template>
+  <footer
+    :class="[
+      'w-full bg-white dark:bg-[#0B1220] text-slate-600 dark:text-slate-400 text-sm transition-colors',
+      bordered ? 'border-t border-slate-200/80 dark:border-slate-800' : '',
+      props.class
+    ]"
+  >
+    <div class="mx-auto max-w-7xl px-4 py-12 sm:px-6 lg:px-8 lg:py-16">
+      <div class="grid grid-cols-1 gap-8 md:grid-cols-2 lg:grid-cols-5">
+        <!-- Brand Info / Left Column -->
+        <div class="lg:col-span-2 space-y-4 pr-4">
+          <div class="flex items-center gap-2.5 font-bold text-slate-900 dark:text-slate-100">
+            <slot name="logo">
+              <div class="flex h-7 w-7 items-center justify-center rounded-lg bg-[#2563EB] text-white font-black text-xs">
+                RC
+              </div>
+            </slot>
+            <span v-if="brandTitle || $slots.brand" class="text-base tracking-tight">
+              <slot name="brand">{{ brandTitle }}</slot>
+            </span>
+          </div>
+
+          <p v-if="brandDescription || $slots.description" class="text-xs sm:text-sm leading-relaxed text-slate-500 dark:text-slate-400 max-w-sm">
+            <slot name="description">{{ brandDescription }}</slot>
+          </p>
+
+          <div v-if="$slots.newsletter" class="pt-2">
+            <slot name="newsletter" />
+          </div>
+        </div>
+
+        <!-- Link Columns / Navigation Groups -->
+        <div
+          v-for="col in columns"
+          :key="col.title"
+          class="space-y-3"
+        >
+          <h4 class="text-xs font-semibold tracking-wider text-slate-900 uppercase dark:text-slate-100">
+            {{ col.title }}
+          </h4>
+          <ul class="space-y-2">
+            <li v-for="link in col.links" :key="link.label + (link.to || link.href)">
+              <component
+                :is="link.to ? 'RouterLink' : 'a'"
+                v-bind="link.to ? { to: link.to } : { href: link.href || '#', target: link.target }"
+                class="text-xs sm:text-sm text-slate-500 transition-colors hover:text-[#2563EB] dark:text-slate-400 dark:hover:text-[#70ACFE]"
+              >
+                {{ link.label }}
+              </component>
+            </li>
+          </ul>
+        </div>
+      </div>
+
+      <!-- Bottom Bar: Copyright & Socials -->
+      <div class="mt-12 flex flex-col items-center justify-between gap-4 border-t border-slate-200/80 pt-8 sm:flex-row dark:border-slate-800">
+        <p class="text-xs text-slate-400 dark:text-slate-500">
+          <slot name="copyright">
+            {{ copyright || `© ${new Date().getFullYear()} ReCloud Studio. All rights reserved.` }}
+          </slot>
+        </p>
+
+        <!-- Social Icons / Links -->
+        <div class="flex items-center gap-4">
+          <slot name="socials">
+            <a
+              v-for="s in socials"
+              :key="s.name"
+              :href="s.href"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="text-slate-400 transition-colors hover:text-slate-600 dark:hover:text-slate-300"
+              :aria-label="s.name"
+            >
+              <span class="text-xs font-medium">{{ s.name }}</span>
+            </a>
+          </slot>
+        </div>
+      </div>
+    </div>
+  </footer>
+</template>
+
+<script setup lang="ts">
+import type { FooterProps } from './types'
+
+const props = withDefaults(defineProps<FooterProps>(), {
+  brandTitle: '',
+  brandDescription: '',
+  columns: () => [],
+  copyright: undefined,
+  socials: () => [],
+  bordered: true,
+  class: ''
+})
+</script>
diff --git a/packages/ui/src/components/footer/footer.test.ts b/packages/ui/src/components/footer/footer.test.ts
new file mode 100644
index 0000000..f04ba82
--- /dev/null
+++ b/packages/ui/src/components/footer/footer.test.ts
@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { Footer } from './index'
+
+describe('Footer component', () => {
+  it('is exported as a Vue component', () => {
+    expect(Footer).toBeDefined()
+    expect(Footer.name || Footer.__name).toBeDefined()
+  })
+})
diff --git a/packages/ui/src/components/footer/index.ts b/packages/ui/src/components/footer/index.ts
new file mode 100644
index 0000000..538720d
--- /dev/null
+++ b/packages/ui/src/components/footer/index.ts
@@ -0,0 +1,2 @@
+export { default as Footer } from './Footer.vue'
+export type { FooterColumn, FooterLink, FooterProps, FooterSocial } from './types'
diff --git a/packages/ui/src/components/footer/types.ts b/packages/ui/src/components/footer/types.ts
new file mode 100644
index 0000000..6132283
--- /dev/null
+++ b/packages/ui/src/components/footer/types.ts
@@ -0,0 +1,27 @@
+export interface FooterLink {
+  label: string
+  href?: string
+  to?: string
+  target?: string
+}
+
+export interface FooterColumn {
+  title: string
+  links: FooterLink[]
+}
+
+export interface FooterSocial {
+  name: string
+  href: string
+  icon?: string
+}
+
+export interface FooterProps {
+  brandTitle?: string
+  brandDescription?: string
+  columns?: FooterColumn[]
+  copyright?: string
+  socials?: FooterSocial[]
+  bordered?: boolean
+  class?: string
+}
diff --git a/packages/ui/src/components/hero/Hero.vue b/packages/ui/src/components/hero/Hero.vue
new file mode 100644
index 0000000..de98c83
--- /dev/null
+++ b/packages/ui/src/components/hero/Hero.vue
@@ -0,0 +1,179 @@
+<template>
+  <section
+    :class="[
+      'relative overflow-hidden py-16 sm:py-24 transition-colors',
+      props.class
+    ]"
+  >
+    <div class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+      <!-- Layout: Center (Default) -->
+      <div v-if="layout === 'center'" class="mx-auto max-w-3xl text-center">
+        <!-- Badge -->
+        <div v-if="badge || $slots.badge" class="mb-4 inline-flex items-center">
+          <slot name="badge">
+            <span class="inline-flex items-center gap-1.5 rounded-full border border-[#2563EB]/20 bg-[#2563EB]/5 px-3 py-1 text-xs font-medium text-[#2563EB] dark:border-[#70ACFE]/20 dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]">
+              {{ badge }}
+            </span>
+          </slot>
+        </div>
+
+        <!-- Title / Heading -->
+        <h1 class="text-3xl font-extrabold tracking-tight text-slate-900 sm:text-5xl lg:text-6xl dark:text-slate-100">
+          <slot name="title">{{ title }}</slot>
+        </h1>
+
+        <!-- Subtitle / Description -->
+        <p v-if="description || $slots.description" class="mx-auto mt-6 max-w-2xl text-base text-slate-600 sm:text-lg lg:text-xl dark:text-slate-400 leading-relaxed">
+          <slot name="description">{{ description }}</slot>
+        </p>
+
+        <!-- CTA Actions -->
+        <div v-if="hasActions" class="mt-8 flex flex-wrap items-center justify-center gap-4">
+          <slot name="actions">
+            <slot name="primary-action">
+              <button
+                v-if="primaryActionText"
+                type="button"
+                class="rounded-xl bg-[#2563EB] px-5 py-3 text-sm font-semibold text-white shadow-sm hover:bg-[#1D4ED8] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:bg-[#2563EB] dark:hover:bg-[#1D4ED8]"
+                @click="$emit('primary-click')"
+              >
+                {{ primaryActionText }}
+              </button>
+            </slot>
+            <slot name="secondary-action">
+              <button
+                v-if="secondaryActionText"
+                type="button"
+                class="rounded-xl border border-slate-300 bg-white px-5 py-3 text-sm font-semibold text-slate-700 shadow-sm hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 dark:border-slate-800 dark:bg-[#0F172A] dark:text-slate-200 dark:hover:bg-slate-800"
+                @click="$emit('secondary-click')"
+              >
+                {{ secondaryActionText }}
+              </button>
+            </slot>
+          </slot>
+        </div>
+
+        <!-- Center Media / Preview slot -->
+        <div v-if="$slots.media" class="mt-12 w-full">
+          <slot name="media" />
+        </div>
+      </div>
+
+      <!-- Layout: Split (Left text, Right media) -->
+      <div v-else-if="layout === 'split'" class="grid grid-cols-1 items-center gap-12 lg:grid-cols-2">
+        <div class="space-y-6">
+          <div v-if="badge || $slots.badge" class="inline-flex items-center">
+            <slot name="badge">
+              <span class="inline-flex items-center gap-1.5 rounded-full border border-[#2563EB]/20 bg-[#2563EB]/5 px-3 py-1 text-xs font-medium text-[#2563EB] dark:border-[#70ACFE]/20 dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]">
+                {{ badge }}
+              </span>
+            </slot>
+          </div>
+
+          <h1 class="text-3xl font-extrabold tracking-tight text-slate-900 sm:text-5xl lg:text-5xl dark:text-slate-100">
+            <slot name="title">{{ title }}</slot>
+          </h1>
+
+          <p v-if="description || $slots.description" class="text-base text-slate-600 sm:text-lg dark:text-slate-400 leading-relaxed">
+            <slot name="description">{{ description }}</slot>
+          </p>
+
+          <div v-if="hasActions" class="flex flex-wrap items-center gap-4 pt-2">
+            <slot name="actions">
+              <slot name="primary-action">
+                <button
+                  v-if="primaryActionText"
+                  type="button"
+                  class="rounded-xl bg-[#2563EB] px-5 py-3 text-sm font-semibold text-white shadow-sm hover:bg-[#1D4ED8] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:bg-[#2563EB] dark:hover:bg-[#1D4ED8]"
+                  @click="$emit('primary-click')"
+                >
+                  {{ primaryActionText }}
+                </button>
+              </slot>
+              <slot name="secondary-action">
+                <button
+                  v-if="secondaryActionText"
+                  type="button"
+                  class="rounded-xl border border-slate-300 bg-white px-5 py-3 text-sm font-semibold text-slate-700 shadow-sm hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 dark:border-slate-800 dark:bg-[#0F172A] dark:text-slate-200 dark:hover:bg-slate-800"
+                  @click="$emit('secondary-click')"
+                >
+                  {{ secondaryActionText }}
+                </button>
+              </slot>
+            </slot>
+          </div>
+        </div>
+
+        <div v-if="$slots.media" class="w-full">
+          <slot name="media" />
+        </div>
+      </div>
+
+      <!-- Layout: Minimal (Clean, left-aligned, low vertical height) -->
+      <div v-else class="max-w-3xl space-y-4">
+        <h1 class="text-2xl font-bold tracking-tight text-slate-900 sm:text-4xl dark:text-slate-100">
+          <slot name="title">{{ title }}</slot>
+        </h1>
+        <p v-if="description || $slots.description" class="text-sm sm:text-base text-slate-600 dark:text-slate-400 leading-relaxed">
+          <slot name="description">{{ description }}</slot>
+        </p>
+        <div v-if="hasActions" class="flex flex-wrap items-center gap-3 pt-2">
+          <slot name="actions">
+            <slot name="primary-action">
+              <button
+                v-if="primaryActionText"
+                type="button"
+                class="rounded-lg bg-[#2563EB] px-4 py-2 text-xs font-semibold text-white shadow-sm hover:bg-[#1D4ED8] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]"
+                @click="$emit('primary-click')"
+              >
+                {{ primaryActionText }}
+              </button>
+            </slot>
+            <slot name="secondary-action">
+              <button
+                v-if="secondaryActionText"
+                type="button"
+                class="rounded-lg border border-slate-300 bg-white px-4 py-2 text-xs font-semibold text-slate-700 shadow-sm hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 dark:border-slate-800 dark:bg-[#0F172A] dark:text-slate-200"
+                @click="$emit('secondary-click')"
+              >
+                {{ secondaryActionText }}
+              </button>
+            </slot>
+          </slot>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+import { computed, useSlots } from 'vue'
+import type { HeroProps } from './types'
+
+const props = withDefaults(defineProps<HeroProps>(), {
+  layout: 'center',
+  badge: undefined,
+  title: '',
+  description: undefined,
+  primaryActionText: undefined,
+  secondaryActionText: undefined,
+  class: ''
+})
+
+defineEmits<{
+  (e: 'primary-click'): void
+  (e: 'secondary-click'): void
+}>()
+
+const slots = useSlots()
+
+const hasActions = computed(() => {
+  return (
+    !!props.primaryActionText ||
+    !!props.secondaryActionText ||
+    !!slots.actions ||
+    !!slots['primary-action'] ||
+    !!slots['secondary-action']
+  )
+})
+</script>
diff --git a/packages/ui/src/components/hero/hero.test.ts b/packages/ui/src/components/hero/hero.test.ts
new file mode 100644
index 0000000..c2b3388
--- /dev/null
+++ b/packages/ui/src/components/hero/hero.test.ts
@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { Hero } from './index'
+
+describe('Hero component', () => {
+  it('is exported as a Vue component', () => {
+    expect(Hero).toBeDefined()
+    expect(Hero.name || Hero.__name).toBeDefined()
+  })
+})
diff --git a/packages/ui/src/components/hero/index.ts b/packages/ui/src/components/hero/index.ts
new file mode 100644
index 0000000..1152ed0
--- /dev/null
+++ b/packages/ui/src/components/hero/index.ts
@@ -0,0 +1,2 @@
+export { default as Hero } from './Hero.vue'
+export type { HeroLayout, HeroProps } from './types'
diff --git a/packages/ui/src/components/hero/types.ts b/packages/ui/src/components/hero/types.ts
new file mode 100644
index 0000000..68170c0
--- /dev/null
+++ b/packages/ui/src/components/hero/types.ts
@@ -0,0 +1,11 @@
+export type HeroLayout = 'center' | 'split' | 'minimal'
+
+export interface HeroProps {
+  layout?: HeroLayout
+  badge?: string
+  title?: string
+  description?: string
+  primaryActionText?: string
+  secondaryActionText?: string
+  class?: string
+}
diff --git a/packages/ui/src/components/navbar/Navbar.vue b/packages/ui/src/components/navbar/Navbar.vue
new file mode 100644
index 0000000..75d335c
--- /dev/null
+++ b/packages/ui/src/components/navbar/Navbar.vue
@@ -0,0 +1,147 @@
+<template>
+  <header
+    :class="[
+      'w-full bg-white/80 backdrop-blur-md dark:bg-[#0B1220]/80 z-40 transition-colors',
+      sticky ? 'sticky top-0' : 'relative',
+      bordered ? 'border-b border-slate-200/80 dark:border-slate-800' : '',
+      props.class
+    ]"
+  >
+    <div class="mx-auto flex h-16 max-w-7xl items-center justify-between px-4 sm:px-6 lg:px-8">
+      <!-- Left: Brand / Logo -->
+      <div class="flex items-center gap-6">
+        <component
+          :is="brandTo ? 'RouterLink' : 'a'"
+          v-bind="brandTo ? { to: brandTo } : { href: brandHref || '/' }"
+          class="flex items-center gap-2.5 font-bold text-slate-900 transition-colors hover:opacity-90 dark:text-slate-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]"
+        >
+          <slot name="logo">
+            <div class="flex h-8 w-8 items-center justify-center rounded-lg bg-[#2563EB] text-white font-black text-sm shadow-sm">
+              RC
+            </div>
+          </slot>
+          <span v-if="brandTitle || $slots.brand" class="text-base tracking-tight">
+            <slot name="brand">{{ brandTitle }}</slot>
+          </span>
+        </component>
+
+        <!-- Desktop Navigation Links -->
+        <nav v-if="links.length > 0 || $slots.links" class="hidden md:flex md:items-center md:gap-1" aria-label="主站导航">
+          <slot name="links">
+            <component
+              :is="link.to ? 'RouterLink' : 'a'"
+              v-for="link in links"
+              :key="link.label + (link.to || link.href)"
+              v-bind="link.to ? { to: link.to } : { href: link.href || '#', target: link.target }"
+              :class="[
+                'relative flex items-center gap-1.5 rounded-lg px-3 py-1.5 text-xs sm:text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]',
+                link.active
+                  ? 'text-[#2563EB] font-semibold dark:text-[#70ACFE]'
+                  : 'text-slate-600 hover:bg-slate-100 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-800/60 dark:hover:text-slate-100'
+              ]"
+            >
+              <span>{{ link.label }}</span>
+              <span
+                v-if="link.badge"
+                class="rounded bg-[#2563EB]/10 px-1.5 py-0.5 text-[10px] font-semibold text-[#1D4ED8] dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]"
+              >
+                {{ link.badge }}
+              </span>
+            </component>
+          </slot>
+        </nav>
+      </div>
+
+      <!-- Right: Action CTAs + Mobile Burger -->
+      <div class="flex items-center gap-2 sm:gap-3">
+        <!-- Custom action/extra slot (e.g. ThemeToggle, Search, Github) -->
+        <slot name="extra" />
+
+        <!-- Actions / CTAs -->
+        <div v-if="$slots.actions" class="hidden sm:flex sm:items-center sm:gap-2">
+          <slot name="actions" />
+        </div>
+
+        <!-- Mobile hamburger trigger -->
+        <div class="flex md:hidden">
+          <button
+            type="button"
+            class="inline-flex items-center justify-center rounded-lg p-2 text-slate-500 hover:bg-slate-100 hover:text-slate-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100"
+            :aria-label="mobileOpen ? '关闭菜单' : '打开菜单'"
+            @click="mobileOpen = !mobileOpen"
+          >
+            <svg v-if="!mobileOpen" class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5" />
+            </svg>
+            <svg v-else class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <!-- Mobile Drawer / Sheet -->
+    <Sheet
+      :open="mobileOpen"
+      side="right"
+      size="20rem"
+      :title="brandTitle || '导航'"
+      @update:open="mobileOpen = $event"
+    >
+      <div class="flex flex-col h-full justify-between py-2">
+        <!-- Mobile Links -->
+        <nav class="space-y-1" aria-label="移动端主站导航">
+          <slot name="mobile-links">
+            <component
+              :is="link.to ? 'RouterLink' : 'a'"
+              v-for="link in links"
+              :key="'m-' + link.label"
+              v-bind="link.to ? { to: link.to } : { href: link.href || '#', target: link.target }"
+              :class="[
+                'flex items-center justify-between rounded-lg px-3 py-2.5 text-sm font-medium transition-colors',
+                link.active
+                  ? 'bg-[#2563EB]/10 font-semibold text-[#1D4ED8] dark:bg-[#2563EB]/20 dark:text-[#70ACFE]'
+                  : 'text-slate-700 hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-800'
+              ]"
+              @click="mobileOpen = false"
+            >
+              <span>{{ link.label }}</span>
+              <span
+                v-if="link.badge"
+                class="rounded bg-[#2563EB]/10 px-1.5 py-0.5 text-xs font-semibold text-[#1D4ED8] dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]"
+              >
+                {{ link.badge }}
+              </span>
+            </component>
+          </slot>
+        </nav>
+
+        <!-- Mobile Actions -->
+        <div v-if="$slots.actions" class="mt-6 border-t border-slate-200 pt-4 dark:border-slate-800">
+          <div class="flex flex-col gap-2" @click="mobileOpen = false">
+            <slot name="actions" />
+          </div>
+        </div>
+      </div>
+    </Sheet>
+  </header>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Sheet } from '../sheet'
+import type { NavbarProps } from './types'
+
+const props = withDefaults(defineProps<NavbarProps>(), {
+  brandTitle: '',
+  brandHref: '/',
+  brandTo: undefined,
+  links: () => [],
+  sticky: true,
+  bordered: true,
+  class: ''
+})
+
+const mobileOpen = ref(false)
+</script>
diff --git a/packages/ui/src/components/navbar/index.ts b/packages/ui/src/components/navbar/index.ts
new file mode 100644
index 0000000..aae6961
--- /dev/null
+++ b/packages/ui/src/components/navbar/index.ts
@@ -0,0 +1,2 @@
+export { default as Navbar } from './Navbar.vue'
+export type { NavbarLink, NavbarProps } from './types'
diff --git a/packages/ui/src/components/navbar/navbar.test.ts b/packages/ui/src/components/navbar/navbar.test.ts
new file mode 100644
index 0000000..48f5df2
--- /dev/null
+++ b/packages/ui/src/components/navbar/navbar.test.ts
@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { Navbar } from './index'
+
+describe('Navbar component', () => {
+  it('is exported as a Vue component', () => {
+    expect(Navbar).toBeDefined()
+    expect(Navbar.name || Navbar.__name).toBeDefined()
+  })
+})
diff --git a/packages/ui/src/components/navbar/types.ts b/packages/ui/src/components/navbar/types.ts
new file mode 100644
index 0000000..2b41866
--- /dev/null
+++ b/packages/ui/src/components/navbar/types.ts
@@ -0,0 +1,18 @@
+export interface NavbarLink {
+  label: string
+  href?: string
+  to?: string
+  target?: string
+  badge?: string
+  active?: boolean
+}
+
+export interface NavbarProps {
+  brandTitle?: string
+  brandHref?: string
+  brandTo?: string
+  links?: NavbarLink[]
+  sticky?: boolean
+  bordered?: boolean
+  class?: string
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 075a331..06d0754 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -66,6 +66,9 @@ export * from './components/toc'
 export * from './components/prev-next'
 export * from './components/nav-tree'
 export * from './components/code-group'
+export * from './components/navbar'
+export * from './components/footer'
+export * from './components/hero'
 
 // Composables & Utilities
 export * from './composables/useTheme'

From 789f5123d7da6e4cd22545f3d76b7d2e9e3a1278 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 07:20:05 +0800
Subject: [PATCH 23/26] fix(landing): address review findings for Navbar,
 Footer, and Hero

---
 apps/playground/pages/components/footer.vue   | 10 +--
 apps/playground/pages/components/hero.vue     |  2 +
 apps/playground/pages/components/navbar.vue   |  1 +
 packages/ui/src/components/footer/Footer.vue  | 65 +++++++++++++++----
 .../ui/src/components/footer/footer.test.ts   | 30 ++++++++-
 packages/ui/src/components/footer/types.ts    |  1 +
 packages/ui/src/components/hero/Hero.vue      | 28 ++++----
 packages/ui/src/components/hero/hero.test.ts  | 27 ++++++--
 packages/ui/src/components/navbar/Navbar.vue  | 28 ++++----
 .../ui/src/components/navbar/navbar.test.ts   | 21 ++++--
 10 files changed, 157 insertions(+), 56 deletions(-)

diff --git a/apps/playground/pages/components/footer.vue b/apps/playground/pages/components/footer.vue
index f74de8c..50a74cd 100644
--- a/apps/playground/pages/components/footer.vue
+++ b/apps/playground/pages/components/footer.vue
@@ -46,9 +46,9 @@ const sampleColumns = [
 ]
 
 const sampleSocials = [
-  { name: 'GitHub', href: 'https://github.com/ReCloudStudio/UI' },
-  { name: 'Discord', href: '#' },
-  { name: 'X / Twitter', href: '#' }
+  { name: 'GitHub', href: 'https://github.com/ReCloudStudio/UI', icon: 'github' },
+  { name: 'Discord', href: '#', icon: 'discord' },
+  { name: 'X / Twitter', href: '#', icon: 'x' }
 ]
 
 const codeBasic = `<Footer
@@ -62,8 +62,8 @@ const apiRows = [
   { name: 'brandTitle', type: 'string', default: "''", description: '品牌名称。' },
   { name: 'brandDescription', type: 'string', default: "''", description: '品牌描述正文。' },
   { name: 'columns', type: 'FooterColumn[]', default: '[]', description: '导航列配置数组：title、links（label、href?、to?、target?）。' },
-  { name: 'copyright', type: 'string', default: '依当前年份自动生成', description: '底部版权文案。' },
-  { name: 'socials', type: 'FooterSocial[]', default: '[]', description: '社交媒体链接数组：name、href、icon?。' },
+  { name: 'copyright', type: 'string', default: "'© ReCloud Studio. All rights reserved.'", description: '底部版权文案；默认值为固定文本以确保 SSR hydration 一致。' },
+  { name: 'socials', type: 'FooterSocial[]', default: '[]', description: '社交媒体链接数组：name、href、icon?。内置图标支持 github、discord、twitter 与 x（不区分大小写）；未知值回退为名称文本。使用 #socials 可完全自定义。' },
   { name: 'bordered', type: 'boolean', default: 'true', description: '是否展示顶部边框。' },
   { name: 'slot: logo', type: 'slot', default: '—', description: '自定义品牌 Logo。' },
   { name: 'slot: brand', type: 'slot', default: '—', description: '自定义品牌名称。' },
diff --git a/apps/playground/pages/components/hero.vue b/apps/playground/pages/components/hero.vue
index ac06fd8..d842a85 100644
--- a/apps/playground/pages/components/hero.vue
+++ b/apps/playground/pages/components/hero.vue
@@ -87,6 +87,8 @@ const apiRows = [
   { name: 'slot: description', type: 'slot', default: '—', description: '自定义介绍副标题。' },
   { name: 'slot: badge', type: 'slot', default: '—', description: '自定义顶部徽标。' },
   { name: 'slot: actions', type: 'slot', default: '—', description: '自定义全部 CTA 按钮组。' },
+  { name: 'slot: primary-action', type: 'slot', default: '—', description: '自定义主要 CTA；提供时覆盖默认主要按钮。' },
+  { name: 'slot: secondary-action', type: 'slot', default: '—', description: '自定义次要 CTA；提供时覆盖默认次要按钮。' },
   { name: 'slot: media', type: 'slot', default: '—', description: '产品交互或媒体预览插槽。' }
 ]
 
diff --git a/apps/playground/pages/components/navbar.vue b/apps/playground/pages/components/navbar.vue
index b2489c4..a51fd0c 100644
--- a/apps/playground/pages/components/navbar.vue
+++ b/apps/playground/pages/components/navbar.vue
@@ -54,6 +54,7 @@ const apiRows = [
   { name: 'slot: logo', type: 'slot', default: '—', description: '自定义品牌 Logo 图标。' },
   { name: 'slot: brand', type: 'slot', default: '—', description: '自定义品牌标题区域。' },
   { name: 'slot: links', type: 'slot', default: '—', description: '自定义桌面端链接。' },
+  { name: 'slot: mobile-links', type: 'slot', default: '—', description: '自定义移动端抽屉内的导航内容；桌面端 #links 不会自动复用至移动端。' },
   { name: 'slot: actions', type: 'slot', default: '—', description: '右侧 CTA 操作按钮组。' },
   { name: 'slot: extra', type: 'slot', default: '—', description: '右侧辅助组件（如主题切换、搜索）。' }
 ]
diff --git a/packages/ui/src/components/footer/Footer.vue b/packages/ui/src/components/footer/Footer.vue
index c9fca03..997ff09 100644
--- a/packages/ui/src/components/footer/Footer.vue
+++ b/packages/ui/src/components/footer/Footer.vue
@@ -1,8 +1,8 @@
 <template>
   <footer
     :class="[
-      'w-full bg-white dark:bg-[#0B1220] text-slate-600 dark:text-slate-400 text-sm transition-colors',
-      bordered ? 'border-t border-slate-200/80 dark:border-slate-800' : '',
+      'w-full bg-[color:var(--background)] text-[color:var(--muted-foreground)] text-sm transition-colors',
+      bordered ? 'border-t border-[color:var(--border)]/80' : '',
       props.class
     ]"
   >
@@ -10,9 +10,9 @@
       <div class="grid grid-cols-1 gap-8 md:grid-cols-2 lg:grid-cols-5">
         <!-- Brand Info / Left Column -->
         <div class="lg:col-span-2 space-y-4 pr-4">
-          <div class="flex items-center gap-2.5 font-bold text-slate-900 dark:text-slate-100">
+          <div class="flex items-center gap-2.5 font-bold text-[color:var(--foreground)]">
             <slot name="logo">
-              <div class="flex h-7 w-7 items-center justify-center rounded-lg bg-[#2563EB] text-white font-black text-xs">
+              <div class="flex h-7 w-7 items-center justify-center rounded-lg bg-[color:var(--primary)] text-[color:var(--primary-foreground)] font-black text-xs">
                 RC
               </div>
             </slot>
@@ -21,7 +21,7 @@
             </span>
           </div>
 
-          <p v-if="brandDescription || $slots.description" class="text-xs sm:text-sm leading-relaxed text-slate-500 dark:text-slate-400 max-w-sm">
+          <p v-if="brandDescription || $slots.description" class="max-w-sm text-xs leading-relaxed text-[color:var(--muted-foreground)] sm:text-sm">
             <slot name="description">{{ brandDescription }}</slot>
           </p>
 
@@ -36,7 +36,7 @@
           :key="col.title"
           class="space-y-3"
         >
-          <h4 class="text-xs font-semibold tracking-wider text-slate-900 uppercase dark:text-slate-100">
+          <h4 class="text-xs font-semibold tracking-wider text-[color:var(--foreground)] uppercase">
             {{ col.title }}
           </h4>
           <ul class="space-y-2">
@@ -44,7 +44,7 @@
               <component
                 :is="link.to ? 'RouterLink' : 'a'"
                 v-bind="link.to ? { to: link.to } : { href: link.href || '#', target: link.target }"
-                class="text-xs sm:text-sm text-slate-500 transition-colors hover:text-[#2563EB] dark:text-slate-400 dark:hover:text-[#70ACFE]"
+                class="text-xs text-[color:var(--muted-foreground)] transition-colors hover:text-[color:var(--primary)] sm:text-sm"
               >
                 {{ link.label }}
               </component>
@@ -54,10 +54,10 @@
       </div>
 
       <!-- Bottom Bar: Copyright & Socials -->
-      <div class="mt-12 flex flex-col items-center justify-between gap-4 border-t border-slate-200/80 pt-8 sm:flex-row dark:border-slate-800">
-        <p class="text-xs text-slate-400 dark:text-slate-500">
+      <div class="mt-12 flex flex-col items-center justify-between gap-4 border-t border-[color:var(--border)]/80 pt-8 sm:flex-row">
+        <p class="text-xs text-[color:var(--muted-foreground)]">
           <slot name="copyright">
-            {{ copyright || `© ${new Date().getFullYear()} ReCloud Studio. All rights reserved.` }}
+            {{ copyright || '© ReCloud Studio. All rights reserved.' }}
           </slot>
         </p>
 
@@ -70,10 +70,37 @@
               :href="s.href"
               target="_blank"
               rel="noopener noreferrer"
-              class="text-slate-400 transition-colors hover:text-slate-600 dark:hover:text-slate-300"
+              class="text-[color:var(--muted-foreground)] transition-colors hover:text-[color:var(--foreground)]"
               :aria-label="s.name"
             >
-              <span class="text-xs font-medium">{{ s.name }}</span>
+              <svg
+                v-if="socialIcon(s.icon) === 'github'"
+                class="h-4 w-4"
+                viewBox="0 0 24 24"
+                fill="currentColor"
+                aria-hidden="true"
+              >
+                <path d="M12 2C6.477 2 2 6.477 2 12c0 4.418 2.865 8.166 6.839 9.489.5.092.683-.217.683-.483 0-.237-.009-1.025-.013-1.86-2.782.604-3.369-1.18-3.369-1.18-.455-1.156-1.11-1.464-1.11-1.464-.908-.62.069-.608.069-.608 1.004.071 1.532 1.031 1.532 1.031.892 1.529 2.341 1.087 2.91.831.091-.646.349-1.087.635-1.337-2.221-.253-4.556-1.111-4.556-4.944 0-1.092.39-1.984 1.029-2.683-.103-.253-.446-1.271.098-2.65 0 0 .84-.269 2.75 1.025A9.56 9.56 0 0 1 12 6.756a9.59 9.59 0 0 1 2.504.337c1.909-1.294 2.748-1.025 2.748-1.025.546 1.379.203 2.397.1 2.65.64.699 1.027 1.591 1.027 2.683 0 3.842-2.339 4.688-4.566 4.936.359.31.678.92.678 1.855 0 1.34-.012 2.419-.012 2.749 0 .268.18.579.688.481A10.002 10.002 0 0 0 22 12c0-5.523-4.477-10-10-10Z" />
+              </svg>
+              <svg
+                v-else-if="socialIcon(s.icon) === 'discord'"
+                class="h-4 w-4"
+                viewBox="0 0 24 24"
+                fill="currentColor"
+                aria-hidden="true"
+              >
+                <path d="M19.54 4.37A16.32 16.32 0 0 0 15.5 3.1a11.4 11.4 0 0 0-.52 1.07 15.12 15.12 0 0 0-5.96 0A11.3 11.3 0 0 0 8.5 3.1a16.4 16.4 0 0 0-4.04 1.28C1.9 8.18 1.2 11.89 1.55 15.55a16.56 16.56 0 0 0 4.96 2.5c.4-.55.76-1.13 1.07-1.73a10.55 10.55 0 0 1-1.69-.81c.14-.1.28-.2.41-.31 3.26 1.53 6.79 1.53 10.01 0 .14.11.28.21.42.31-.54.32-1.1.59-1.7.81.31.6.67 1.18 1.07 1.73a16.5 16.5 0 0 0 4.96-2.5c.41-4.24-.7-7.92-2.54-11.18ZM8.68 13.3c-.98 0-1.78-.9-1.78-2s.78-2 1.78-2c1 0 1.79.9 1.78 2 0 1.1-.78 2-1.78 2Zm6.64 0c-.98 0-1.78-.9-1.78-2s.78-2 1.78-2c1 0 1.79.9 1.78 2 0 1.1-.78 2-1.78 2Z" />
+              </svg>
+              <svg
+                v-else-if="socialIcon(s.icon) === 'twitter'"
+                class="h-4 w-4"
+                viewBox="0 0 24 24"
+                fill="currentColor"
+                aria-hidden="true"
+              >
+                <path d="M18.9 2H22l-6.77 7.74L23.2 22h-6.24l-4.89-6.57L6.32 22H3.2l7.24-8.27L2.8 2h6.36l4.42 5.94L18.9 2Zm-1.1 18h1.73L8.22 3.9H6.36L17.8 20Z" />
+              </svg>
+              <span v-else class="text-xs font-medium">{{ s.name }}</span>
             </a>
           </slot>
         </div>
@@ -94,4 +121,18 @@ const props = withDefaults(defineProps<FooterProps>(), {
   bordered: true,
   class: ''
 })
+
+const socialIcon = (icon?: string) => {
+  const normalizedIcon = icon?.toLowerCase()
+
+  if (normalizedIcon === 'github' || normalizedIcon === 'discord') {
+    return normalizedIcon
+  }
+
+  if (normalizedIcon === 'twitter' || normalizedIcon === 'x') {
+    return 'twitter'
+  }
+
+  return undefined
+}
 </script>
diff --git a/packages/ui/src/components/footer/footer.test.ts b/packages/ui/src/components/footer/footer.test.ts
index f04ba82..3f3b091 100644
--- a/packages/ui/src/components/footer/footer.test.ts
+++ b/packages/ui/src/components/footer/footer.test.ts
@@ -1,9 +1,35 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { Footer } from './index'
 
-describe('Footer component', () => {
+const source = readFileSync(fileURLToPath(new URL('./Footer.vue', import.meta.url)), 'utf8')
+const types = readFileSync(fileURLToPath(new URL('./types.ts', import.meta.url)), 'utf8')
+
+describe('Footer component contract', () => {
   it('is exported as a Vue component', () => {
     expect(Footer).toBeDefined()
-    expect(Footer.name || Footer.__name).toBeDefined()
+  })
+
+  it('renders configured footer links and keeps the default copyright SSR-safe', () => {
+    expect(source).toContain('v-for="link in col.links"')
+    expect(source).toContain("'© ReCloud Studio. All rights reserved.'")
+    expect(source).not.toContain('new Date()')
+  })
+
+  it('uses semantic tokens and exposes social customization through its slot', () => {
+    expect(source).toContain('hover:text-[color:var(--primary)]')
+    expect(source).toContain('<slot name="socials">')
+  })
+
+  it('maps supported social icon names and falls back to the accessible text name', () => {
+    expect(types).toContain('icon?: string')
+    expect(source).toContain("normalizedIcon === 'github' || normalizedIcon === 'discord'")
+    expect(source).toContain("normalizedIcon === 'twitter' || normalizedIcon === 'x'")
+    expect(source).toContain("socialIcon(s.icon) === 'github'")
+    expect(source).toContain("socialIcon(s.icon) === 'discord'")
+    expect(source).toContain("socialIcon(s.icon) === 'twitter'")
+    expect(source).toContain('<span v-else class="text-xs font-medium">{{ s.name }}</span>')
+    expect(source).toContain(':aria-label="s.name"')
   })
 })
diff --git a/packages/ui/src/components/footer/types.ts b/packages/ui/src/components/footer/types.ts
index 6132283..27be639 100644
--- a/packages/ui/src/components/footer/types.ts
+++ b/packages/ui/src/components/footer/types.ts
@@ -13,6 +13,7 @@ export interface FooterColumn {
 export interface FooterSocial {
   name: string
   href: string
+  /** Built-in icon name: github, discord, twitter, or x. Unknown values render the name text. */
   icon?: string
 }
 
diff --git a/packages/ui/src/components/hero/Hero.vue b/packages/ui/src/components/hero/Hero.vue
index de98c83..7b7107b 100644
--- a/packages/ui/src/components/hero/Hero.vue
+++ b/packages/ui/src/components/hero/Hero.vue
@@ -11,19 +11,19 @@
         <!-- Badge -->
         <div v-if="badge || $slots.badge" class="mb-4 inline-flex items-center">
           <slot name="badge">
-            <span class="inline-flex items-center gap-1.5 rounded-full border border-[#2563EB]/20 bg-[#2563EB]/5 px-3 py-1 text-xs font-medium text-[#2563EB] dark:border-[#70ACFE]/20 dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]">
+            <span class="inline-flex items-center gap-1.5 rounded-full border border-[color:var(--primary)]/20 bg-[color:var(--primary)]/5 px-3 py-1 text-xs font-medium text-[color:var(--primary)]">
               {{ badge }}
             </span>
           </slot>
         </div>
 
         <!-- Title / Heading -->
-        <h1 class="text-3xl font-extrabold tracking-tight text-slate-900 sm:text-5xl lg:text-6xl dark:text-slate-100">
+        <h1 class="text-3xl font-extrabold tracking-tight text-[color:var(--foreground)] sm:text-5xl lg:text-6xl">
           <slot name="title">{{ title }}</slot>
         </h1>
 
         <!-- Subtitle / Description -->
-        <p v-if="description || $slots.description" class="mx-auto mt-6 max-w-2xl text-base text-slate-600 sm:text-lg lg:text-xl dark:text-slate-400 leading-relaxed">
+        <p v-if="description || $slots.description" class="mx-auto mt-6 max-w-2xl text-base leading-relaxed text-[color:var(--muted-foreground)] sm:text-lg lg:text-xl">
           <slot name="description">{{ description }}</slot>
         </p>
 
@@ -34,7 +34,7 @@
               <button
                 v-if="primaryActionText"
                 type="button"
-                class="rounded-xl bg-[#2563EB] px-5 py-3 text-sm font-semibold text-white shadow-sm hover:bg-[#1D4ED8] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:bg-[#2563EB] dark:hover:bg-[#1D4ED8]"
+                class="rounded-xl bg-[color:var(--primary)] px-5 py-3 text-sm font-semibold text-[color:var(--primary-foreground)] shadow-sm hover:bg-[color:var(--primary-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
                 @click="$emit('primary-click')"
               >
                 {{ primaryActionText }}
@@ -44,7 +44,7 @@
               <button
                 v-if="secondaryActionText"
                 type="button"
-                class="rounded-xl border border-slate-300 bg-white px-5 py-3 text-sm font-semibold text-slate-700 shadow-sm hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 dark:border-slate-800 dark:bg-[#0F172A] dark:text-slate-200 dark:hover:bg-slate-800"
+                class="rounded-xl border border-[color:var(--border)] bg-[color:var(--card)] px-5 py-3 text-sm font-semibold text-[color:var(--foreground)] shadow-sm hover:bg-[color:var(--surface-muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
                 @click="$emit('secondary-click')"
               >
                 {{ secondaryActionText }}
@@ -64,17 +64,17 @@
         <div class="space-y-6">
           <div v-if="badge || $slots.badge" class="inline-flex items-center">
             <slot name="badge">
-              <span class="inline-flex items-center gap-1.5 rounded-full border border-[#2563EB]/20 bg-[#2563EB]/5 px-3 py-1 text-xs font-medium text-[#2563EB] dark:border-[#70ACFE]/20 dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]">
+              <span class="inline-flex items-center gap-1.5 rounded-full border border-[color:var(--primary)]/20 bg-[color:var(--primary)]/5 px-3 py-1 text-xs font-medium text-[color:var(--primary)]">
                 {{ badge }}
               </span>
             </slot>
           </div>
 
-          <h1 class="text-3xl font-extrabold tracking-tight text-slate-900 sm:text-5xl lg:text-5xl dark:text-slate-100">
+          <h1 class="text-3xl font-extrabold tracking-tight text-[color:var(--foreground)] sm:text-5xl lg:text-5xl">
             <slot name="title">{{ title }}</slot>
           </h1>
 
-          <p v-if="description || $slots.description" class="text-base text-slate-600 sm:text-lg dark:text-slate-400 leading-relaxed">
+          <p v-if="description || $slots.description" class="text-base leading-relaxed text-[color:var(--muted-foreground)] sm:text-lg">
             <slot name="description">{{ description }}</slot>
           </p>
 
@@ -84,7 +84,7 @@
                 <button
                   v-if="primaryActionText"
                   type="button"
-                  class="rounded-xl bg-[#2563EB] px-5 py-3 text-sm font-semibold text-white shadow-sm hover:bg-[#1D4ED8] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:bg-[#2563EB] dark:hover:bg-[#1D4ED8]"
+                  class="rounded-xl bg-[color:var(--primary)] px-5 py-3 text-sm font-semibold text-[color:var(--primary-foreground)] shadow-sm hover:bg-[color:var(--primary-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
                   @click="$emit('primary-click')"
                 >
                   {{ primaryActionText }}
@@ -94,7 +94,7 @@
                 <button
                   v-if="secondaryActionText"
                   type="button"
-                  class="rounded-xl border border-slate-300 bg-white px-5 py-3 text-sm font-semibold text-slate-700 shadow-sm hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 dark:border-slate-800 dark:bg-[#0F172A] dark:text-slate-200 dark:hover:bg-slate-800"
+                  class="rounded-xl border border-[color:var(--border)] bg-[color:var(--card)] px-5 py-3 text-sm font-semibold text-[color:var(--foreground)] shadow-sm hover:bg-[color:var(--surface-muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
                   @click="$emit('secondary-click')"
                 >
                   {{ secondaryActionText }}
@@ -111,10 +111,10 @@
 
       <!-- Layout: Minimal (Clean, left-aligned, low vertical height) -->
       <div v-else class="max-w-3xl space-y-4">
-        <h1 class="text-2xl font-bold tracking-tight text-slate-900 sm:text-4xl dark:text-slate-100">
+        <h1 class="text-2xl font-bold tracking-tight text-[color:var(--foreground)] sm:text-4xl">
           <slot name="title">{{ title }}</slot>
         </h1>
-        <p v-if="description || $slots.description" class="text-sm sm:text-base text-slate-600 dark:text-slate-400 leading-relaxed">
+        <p v-if="description || $slots.description" class="text-sm leading-relaxed text-[color:var(--muted-foreground)] sm:text-base">
           <slot name="description">{{ description }}</slot>
         </p>
         <div v-if="hasActions" class="flex flex-wrap items-center gap-3 pt-2">
@@ -123,7 +123,7 @@
               <button
                 v-if="primaryActionText"
                 type="button"
-                class="rounded-lg bg-[#2563EB] px-4 py-2 text-xs font-semibold text-white shadow-sm hover:bg-[#1D4ED8] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]"
+                class="rounded-lg bg-[color:var(--primary)] px-4 py-2 text-xs font-semibold text-[color:var(--primary-foreground)] shadow-sm hover:bg-[color:var(--primary-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
                 @click="$emit('primary-click')"
               >
                 {{ primaryActionText }}
@@ -133,7 +133,7 @@
               <button
                 v-if="secondaryActionText"
                 type="button"
-                class="rounded-lg border border-slate-300 bg-white px-4 py-2 text-xs font-semibold text-slate-700 shadow-sm hover:bg-slate-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 dark:border-slate-800 dark:bg-[#0F172A] dark:text-slate-200"
+                class="rounded-lg border border-[color:var(--border)] bg-[color:var(--card)] px-4 py-2 text-xs font-semibold text-[color:var(--foreground)] shadow-sm hover:bg-[color:var(--surface-muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
                 @click="$emit('secondary-click')"
               >
                 {{ secondaryActionText }}
diff --git a/packages/ui/src/components/hero/hero.test.ts b/packages/ui/src/components/hero/hero.test.ts
index c2b3388..6d818f7 100644
--- a/packages/ui/src/components/hero/hero.test.ts
+++ b/packages/ui/src/components/hero/hero.test.ts
@@ -1,9 +1,26 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
-import { Hero } from './index'
 
-describe('Hero component', () => {
-  it('is exported as a Vue component', () => {
-    expect(Hero).toBeDefined()
-    expect(Hero.name || Hero.__name).toBeDefined()
+const source = readFileSync(fileURLToPath(new URL('./Hero.vue', import.meta.url)), 'utf8')
+
+describe('Hero component contract', () => {
+  it('supports center, split, and minimal layouts', () => {
+    expect(source).toContain("layout === 'center'")
+    expect(source).toContain("layout === 'split'")
+    expect(source).toContain("layout: 'center'")
+  })
+
+  it('renders CTA controls with public click events and action overrides', () => {
+    expect(source).toContain("@click=\"$emit('primary-click')\"")
+    expect(source).toContain("@click=\"$emit('secondary-click')\"")
+    expect(source).toContain('<slot name="primary-action">')
+    expect(source).toContain('<slot name="secondary-action">')
+  })
+
+  it('uses semantic primary tokens for badges and primary CTAs', () => {
+    expect(source).toContain('bg-[color:var(--primary)]')
+    expect(source).toContain('hover:bg-[color:var(--primary-hover)]')
+    expect(source).not.toContain('#2563EB')
   })
 })
diff --git a/packages/ui/src/components/navbar/Navbar.vue b/packages/ui/src/components/navbar/Navbar.vue
index 75d335c..69a2406 100644
--- a/packages/ui/src/components/navbar/Navbar.vue
+++ b/packages/ui/src/components/navbar/Navbar.vue
@@ -1,9 +1,9 @@
 <template>
   <header
     :class="[
-      'w-full bg-white/80 backdrop-blur-md dark:bg-[#0B1220]/80 z-40 transition-colors',
+      'w-full bg-[color:var(--background)]/80 backdrop-blur-md z-40 transition-colors',
       sticky ? 'sticky top-0' : 'relative',
-      bordered ? 'border-b border-slate-200/80 dark:border-slate-800' : '',
+      bordered ? 'border-b border-[color:var(--border)]/80' : '',
       props.class
     ]"
   >
@@ -13,10 +13,10 @@
         <component
           :is="brandTo ? 'RouterLink' : 'a'"
           v-bind="brandTo ? { to: brandTo } : { href: brandHref || '/' }"
-          class="flex items-center gap-2.5 font-bold text-slate-900 transition-colors hover:opacity-90 dark:text-slate-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]"
+          class="flex items-center gap-2.5 font-bold text-[color:var(--foreground)] transition-colors hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
         >
           <slot name="logo">
-            <div class="flex h-8 w-8 items-center justify-center rounded-lg bg-[#2563EB] text-white font-black text-sm shadow-sm">
+            <div class="flex h-8 w-8 items-center justify-center rounded-lg bg-[color:var(--primary)] text-[color:var(--primary-foreground)] font-black text-sm shadow-sm">
               RC
             </div>
           </slot>
@@ -34,16 +34,16 @@
               :key="link.label + (link.to || link.href)"
               v-bind="link.to ? { to: link.to } : { href: link.href || '#', target: link.target }"
               :class="[
-                'relative flex items-center gap-1.5 rounded-lg px-3 py-1.5 text-xs sm:text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB]',
+                'relative flex items-center gap-1.5 rounded-lg px-3 py-1.5 text-xs sm:text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]',
                 link.active
-                  ? 'text-[#2563EB] font-semibold dark:text-[#70ACFE]'
-                  : 'text-slate-600 hover:bg-slate-100 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-800/60 dark:hover:text-slate-100'
+                  ? 'text-[color:var(--primary)] font-semibold'
+                  : 'text-[color:var(--muted-foreground)] hover:bg-[color:var(--surface-muted)] hover:text-[color:var(--foreground)]'
               ]"
             >
               <span>{{ link.label }}</span>
               <span
                 v-if="link.badge"
-                class="rounded bg-[#2563EB]/10 px-1.5 py-0.5 text-[10px] font-semibold text-[#1D4ED8] dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]"
+                class="rounded bg-[color:var(--primary)]/10 px-1.5 py-0.5 text-[10px] font-semibold text-[color:var(--primary)]"
               >
                 {{ link.badge }}
               </span>
@@ -66,8 +66,10 @@
         <div class="flex md:hidden">
           <button
             type="button"
-            class="inline-flex items-center justify-center rounded-lg p-2 text-slate-500 hover:bg-slate-100 hover:text-slate-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100"
+            class="inline-flex items-center justify-center rounded-lg p-2 text-[color:var(--muted-foreground)] hover:bg-[color:var(--surface-muted)] hover:text-[color:var(--foreground)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)]"
             :aria-label="mobileOpen ? '关闭菜单' : '打开菜单'"
+            :aria-expanded="mobileOpen"
+            aria-haspopup="dialog"
             @click="mobileOpen = !mobileOpen"
           >
             <svg v-if="!mobileOpen" class="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
@@ -101,15 +103,15 @@
               :class="[
                 'flex items-center justify-between rounded-lg px-3 py-2.5 text-sm font-medium transition-colors',
                 link.active
-                  ? 'bg-[#2563EB]/10 font-semibold text-[#1D4ED8] dark:bg-[#2563EB]/20 dark:text-[#70ACFE]'
-                  : 'text-slate-700 hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-800'
+                  ? 'bg-[color:var(--primary)]/10 font-semibold text-[color:var(--primary)]'
+                  : 'text-[color:var(--foreground)] hover:bg-[color:var(--surface-muted)]'
               ]"
               @click="mobileOpen = false"
             >
               <span>{{ link.label }}</span>
               <span
                 v-if="link.badge"
-                class="rounded bg-[#2563EB]/10 px-1.5 py-0.5 text-xs font-semibold text-[#1D4ED8] dark:bg-[#70ACFE]/10 dark:text-[#70ACFE]"
+                class="rounded bg-[color:var(--primary)]/10 px-1.5 py-0.5 text-xs font-semibold text-[color:var(--primary)]"
               >
                 {{ link.badge }}
               </span>
@@ -118,7 +120,7 @@
         </nav>
 
         <!-- Mobile Actions -->
-        <div v-if="$slots.actions" class="mt-6 border-t border-slate-200 pt-4 dark:border-slate-800">
+        <div v-if="$slots.actions" class="mt-6 border-t border-[color:var(--border)] pt-4">
           <div class="flex flex-col gap-2" @click="mobileOpen = false">
             <slot name="actions" />
           </div>
diff --git a/packages/ui/src/components/navbar/navbar.test.ts b/packages/ui/src/components/navbar/navbar.test.ts
index 48f5df2..1a7befe 100644
--- a/packages/ui/src/components/navbar/navbar.test.ts
+++ b/packages/ui/src/components/navbar/navbar.test.ts
@@ -1,9 +1,20 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
-import { Navbar } from './index'
 
-describe('Navbar component', () => {
-  it('is exported as a Vue component', () => {
-    expect(Navbar).toBeDefined()
-    expect(Navbar.name || Navbar.__name).toBeDefined()
+const source = readFileSync(fileURLToPath(new URL('./Navbar.vue', import.meta.url)), 'utf8')
+
+describe('Navbar component contract', () => {
+  it('exposes dialog state to the mobile menu trigger', () => {
+    expect(source).toContain(':aria-expanded="mobileOpen"')
+    expect(source).toContain('aria-haspopup="dialog"')
+    expect(source).toContain('@click="mobileOpen = !mobileOpen"')
+    expect(source).toContain(':open="mobileOpen"')
+  })
+
+  it('uses semantic primary and ring tokens for brand and interactive states', () => {
+    expect(source).toContain('bg-[color:var(--primary)]')
+    expect(source).toContain('focus-visible:ring-[color:var(--ring)]')
+    expect(source).not.toContain('#2563EB')
   })
 })

From cb1839b211a59e2fac96397a4a5bd2ebd66e6fec Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 08:16:48 +0800
Subject: [PATCH 24/26] feat(icon): implement universal Icon component and
 language icon support for CodeBlock

---
 .changeset/calm-icons-arrive.md               |   5 +
 .../pages/components/code-block.vue           |  35 ++-
 apps/playground/pages/components/icon.vue     | 235 ++++++++++++++++++
 apps/playground/utils/catalog.ts              |   3 +-
 .../src/components/code-block/CodeBlock.vue   |  23 +-
 .../ui/src/components/code-block/index.ts     |   3 +-
 .../code-block/languageIcons.test.ts          |  52 ++++
 .../components/code-block/languageIcons.ts    | 126 ++++++++++
 .../ui/src/components/code-block/types.ts     |  22 ++
 .../src/components/code-group/CodeGroup.vue   |   4 +-
 .../ui/src/components/code-group/types.ts     |   4 +-
 .../command-palette/CommandPalette.vue        |   3 +-
 .../src/components/command-palette/types.ts   |   4 +-
 .../components/context-menu/ContextMenu.vue   |   5 +-
 .../src/components/dropdown/DropdownMenu.vue  |   5 +-
 packages/ui/src/components/icon/Icon.vue      |  74 ++++++
 packages/ui/src/components/icon/icon.test.ts  |  30 +++
 packages/ui/src/components/icon/index.ts      |   4 +
 .../ui/src/components/icon/lucideResolver.ts  |  55 ++++
 .../ui/src/components/icon/registry.test.ts   | 134 ++++++++++
 packages/ui/src/components/icon/registry.ts   | 186 ++++++++++++++
 packages/ui/src/components/icon/types.ts      |  47 ++++
 .../ui/src/components/nav-tree/NavTree.vue    |   3 +-
 packages/ui/src/components/nav-tree/types.ts  |   4 +-
 packages/ui/src/components/tabs/Tabs.vue      |   5 +-
 .../components/toggle-group/ToggleGroup.vue   |   5 +-
 .../src/components/tree-view/TreeViewNode.vue |   3 +-
 packages/ui/src/components/tree-view/types.ts |   6 +-
 packages/ui/src/index.ts                      |   1 +
 29 files changed, 1039 insertions(+), 47 deletions(-)
 create mode 100644 .changeset/calm-icons-arrive.md
 create mode 100644 apps/playground/pages/components/icon.vue
 create mode 100644 packages/ui/src/components/code-block/languageIcons.test.ts
 create mode 100644 packages/ui/src/components/code-block/languageIcons.ts
 create mode 100644 packages/ui/src/components/code-block/types.ts
 create mode 100644 packages/ui/src/components/icon/Icon.vue
 create mode 100644 packages/ui/src/components/icon/icon.test.ts
 create mode 100644 packages/ui/src/components/icon/index.ts
 create mode 100644 packages/ui/src/components/icon/lucideResolver.ts
 create mode 100644 packages/ui/src/components/icon/registry.test.ts
 create mode 100644 packages/ui/src/components/icon/registry.ts
 create mode 100644 packages/ui/src/components/icon/types.ts

diff --git a/.changeset/calm-icons-arrive.md b/.changeset/calm-icons-arrive.md
new file mode 100644
index 0000000..0122ee5
--- /dev/null
+++ b/.changeset/calm-icons-arrive.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add universal `Icon` component and multi-library icon resolution registry with `IconSource` integration across TreeView, NavTree, CommandPalette, Tabs, CodeBlock, and menus.
diff --git a/apps/playground/pages/components/code-block.vue b/apps/playground/pages/components/code-block.vue
index 3b1cd3f..e4f9b5a 100644
--- a/apps/playground/pages/components/code-block.vue
+++ b/apps/playground/pages/components/code-block.vue
@@ -1,9 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="CodeBlock 代码块" description="带文件标识、复制操作、行号和自动换行的深色代码展示容器。" />
+    <DocPageHeader title="CodeBlock 代码块" description="带编程语言图标、文件标识、复制操作、行号和自动换行的深色代码展示容器。" />
 
-    <DocExample title="文件代码" description="默认提供复制操作，可标记语言和文件名。" :code="exampleCode">
-      <CodeBlock :code="componentCode" language="vue" filename="StatusCard.vue" class="max-w-2xl" />
+    <DocExample title="编程语言图标显示" description="默认根据 language 或 filename 自动匹配内置编程语言图标；亦可显式关闭（icon: false）或自定义传入图标源。" :code="iconExampleCode">
+      <div class="space-y-4">
+        <!-- 自动匹配 Vue / TypeScript / Bash / Python / SQL 图标 -->
+        <CodeBlock :code="componentCode" language="vue" filename="StatusCard.vue" class="max-w-2xl" />
+        <CodeBlock :code="configCode" language="ts" filename="config.ts" class="max-w-2xl" />
+        <CodeBlock :code="shellCode" language="bash" filename="deploy.sh" class="max-w-2xl" />
+        <!-- 显式禁用图标（保留小圆点） -->
+        <CodeBlock :code="logCode" language="log" filename="output.log" :icon="false" class="max-w-2xl" />
+      </div>
     </DocExample>
 
     <DocExample title="行号与换行" description="长内容可保留行号，并按需自动换行。" :code="lineNumberCode">
@@ -37,17 +44,24 @@ const configCode = `export default defineConfig({
   retry: 3
 })`
 
+const shellCode = `#!/usr/bin/env bash
+set -euo pipefail
+bun run build
+docker build -t app:latest .`
+
 const logCode = `[10:12:01] Building application
 [10:12:04] Validating types
 [10:12:08] Uploading assets
 [10:12:12] Deploying to production
 [10:12:16] Deployment complete`
 
-const exampleCode = `<CodeBlock
-  :code="componentCode"
-  language="vue"
-  filename="StatusCard.vue"
-/>`
+const iconExampleCode = `<!-- 自动根据 language 或 filename 渲染对应语言图标 -->
+<CodeBlock :code="componentCode" language="vue" filename="StatusCard.vue" />
+<CodeBlock :code="configCode" language="ts" filename="config.ts" />
+<CodeBlock :code="shellCode" language="bash" filename="deploy.sh" />
+
+<!-- 禁用图标，回退至圆点指示器 -->
+<CodeBlock :code="logCode" language="log" filename="output.log" :icon="false" />`
 
 const lineNumberCode = `<CodeBlock
   :code="configCode"
@@ -75,8 +89,9 @@ const collapsibleCode = `<CodeBlock
 
 const apiRows = [
   { name: 'code', type: 'string', default: "''", description: '要展示和复制的源代码。' },
-  { name: 'language', type: 'string', default: "''", description: '语言标识，用于展示与高亮；vue 片段未包含 <template> 等顶层块时按模板语法高亮。' },
-  { name: 'filename', type: 'string', default: "''", description: '标题栏中的文件名。' },
+  { name: 'language', type: 'string', default: "''", description: '语言标识，用于展示、高亮以及默认匹配语言图标。' },
+  { name: 'filename', type: 'string', default: "''", description: '标题栏中的文件名，其扩展名亦可参与语言图标自动匹配。' },
+  { name: 'icon', type: 'IconSource | boolean', default: 'undefined', description: '编程语言图标。true 强制显示；false 禁用显示；支持自定义传入 IconSource。缺省时自动尝试匹配。' },
   { name: 'copyable', type: 'boolean', default: 'true', description: '是否显示复制按钮。' },
   { name: 'showLineNumbers', type: 'boolean', default: 'false', description: '是否显示行号。' },
   { name: 'wrap', type: 'boolean', default: 'false', description: '是否自动换行。' },
diff --git a/apps/playground/pages/components/icon.vue b/apps/playground/pages/components/icon.vue
new file mode 100644
index 0000000..d98045e
--- /dev/null
+++ b/apps/playground/pages/components/icon.vue
@@ -0,0 +1,235 @@
+<template>
+  <div class="space-y-12">
+    <!-- Header -->
+    <header class="space-y-3">
+      <div class="flex items-center gap-2">
+        <h1 class="text-3xl font-bold tracking-tight text-slate-900 dark:text-slate-100">Icon 图标</h1>
+        <Badge variant="subtle" size="sm">Universal</Badge>
+      </div>
+      <p class="text-base text-slate-600 dark:text-slate-400">
+        通用图标显示组件，支持直接传入 Vue 组件、注册的前缀库（如 <code>lucide:settings</code>、<code>custom:logo</code>）、内联 SVG 字符串及图片 URL，并具备无障碍标记与响应式尺寸继承能力。
+      </p>
+    </header>
+
+    <!-- 1. 多类型图标源解析展示 -->
+    <DocExample
+      title="多种图标源类型"
+      description="无缝解析 Vue 组件对象、内置前缀名称、纯图标名、内联 SVG 片段以及图片/矢量资源路径。"
+      :code="sourcesCode"
+    >
+      <div class="flex flex-wrap items-center gap-6 p-4 rounded-lg bg-slate-50 dark:bg-slate-900 border border-slate-200 dark:border-slate-800">
+        <div class="flex flex-col items-center gap-2">
+          <Icon :icon="Settings" class="text-primary text-xl" />
+          <span class="text-xs text-slate-500">Vue 组件</span>
+        </div>
+        <div class="flex flex-col items-center gap-2">
+          <Icon icon="lucide:server" class="text-emerald-500 text-xl" />
+          <span class="text-xs text-slate-500">前缀: lucide:server</span>
+        </div>
+        <div class="flex flex-col items-center gap-2">
+          <Icon icon="terminal" class="text-amber-500 text-xl" />
+          <span class="text-xs text-slate-500">内置: terminal</span>
+        </div>
+        <div class="flex flex-col items-center gap-2">
+          <Icon :icon="svgSnippet" class="text-purple-500 text-xl" />
+          <span class="text-xs text-slate-500">内联 SVG</span>
+        </div>
+        <div class="flex flex-col items-center gap-2">
+          <Icon icon="/icon.svg" size="1.25rem" />
+          <span class="text-xs text-slate-500">图片/SVG 文件路径</span>
+        </div>
+      </div>
+    </DocExample>
+
+    <!-- 2. 尺寸控制 -->
+    <DocExample
+      title="尺寸与文字排版继承"
+      description="size 默认继承 '1em'，随周围文字字体大小自动缩放；亦可显式指定数值（px）或任意 CSS 尺寸单位。"
+      :code="sizesCode"
+    >
+      <div class="space-y-4 p-4 rounded-lg bg-slate-50 dark:bg-slate-900 border border-slate-200 dark:border-slate-800">
+        <div class="flex items-center gap-6">
+          <div class="flex items-center gap-1.5 text-xs text-slate-600 dark:text-slate-300">
+            <Icon icon="lucide:activity" />
+            <span>跟随小号正文 (text-xs)</span>
+          </div>
+          <div class="flex items-center gap-2 text-base font-medium text-slate-800 dark:text-slate-200">
+            <Icon icon="lucide:activity" />
+            <span>跟随常规文字 (text-base)</span>
+          </div>
+          <div class="flex items-center gap-2.5 text-xl font-bold text-slate-900 dark:text-slate-100">
+            <Icon icon="lucide:activity" />
+            <span>跟随大标题 (text-xl)</span>
+          </div>
+        </div>
+
+        <div class="flex items-center gap-6 pt-3 border-t border-slate-200 dark:border-slate-800">
+          <div class="flex items-center gap-2">
+            <Icon icon="lucide:shield-check" :size="16" class="text-emerald-500" />
+            <span class="text-xs text-slate-500">16px</span>
+          </div>
+          <div class="flex items-center gap-2">
+            <Icon icon="lucide:shield-check" :size="24" class="text-emerald-500" />
+            <span class="text-xs text-slate-500">24px</span>
+          </div>
+          <div class="flex items-center gap-2">
+            <Icon icon="lucide:shield-check" :size="32" class="text-emerald-500" />
+            <span class="text-xs text-slate-500">32px</span>
+          </div>
+          <div class="flex items-center gap-2">
+            <Icon icon="lucide:shield-check" size="2.5rem" class="text-emerald-500" />
+            <span class="text-xs text-slate-500">2.5rem</span>
+          </div>
+        </div>
+      </div>
+    </DocExample>
+
+    <!-- 3. 自定义图标库注册与前缀解析器 -->
+    <DocExample
+      title="自定义图标库与前缀解析器"
+      description="使用 registerIconResolver 注册外部图标体系，例如 mdi、remixicon、FontAwesome 或公司私有资产池。"
+      :code="customResolverCode"
+    >
+      <div class="flex items-center gap-6 p-4 rounded-lg bg-slate-50 dark:bg-slate-900 border border-slate-200 dark:border-slate-800">
+        <div class="flex items-center gap-2">
+          <Icon icon="cloud:database" size="1.5rem" class="text-blue-500" />
+          <span class="text-sm font-medium text-slate-700 dark:text-slate-300">cloud:database</span>
+        </div>
+        <div class="flex items-center gap-2">
+          <Icon icon="cloud:kubernetes" size="1.5rem" class="text-indigo-500" />
+          <span class="text-sm font-medium text-slate-700 dark:text-slate-300">cloud:kubernetes</span>
+        </div>
+      </div>
+    </DocExample>
+
+    <!-- 4. 无障碍可访问性与回退插槽 -->
+    <DocExample
+      title="无障碍描述与回退插槽"
+      description="未提供 label 时自动应用 aria-hidden='true' 充当装饰图标；提供 label 时自动设置 role='img' 与 aria-label；当图标源未能解析时回退显示默认插槽内容。"
+      :code="a11yCode"
+    >
+      <div class="flex items-center gap-6 p-4 rounded-lg bg-slate-50 dark:bg-slate-900 border border-slate-200 dark:border-slate-800">
+        <div class="flex items-center gap-2">
+          <Icon icon="lucide:bell" label="系统提醒通知" class="text-slate-700 dark:text-slate-200 text-lg" />
+          <span class="text-xs text-slate-500">带 aria-label 屏幕朗读</span>
+        </div>
+        <div class="flex items-center gap-2">
+          <Icon icon="unknown:missing-icon" size="1.25rem" class="text-slate-400">
+            <span class="text-xs font-mono border border-dashed border-slate-300 dark:border-slate-700 px-1.5 py-0.5 rounded">N/A</span>
+          </Icon>
+          <span class="text-xs text-slate-500">解析失败触发 fallback 插槽</span>
+        </div>
+      </div>
+    </DocExample>
+
+    <!-- 5. 在其他组件中的复用体验 -->
+    <DocExample
+      title="在控制台树与下拉菜单中无缝组合"
+      description="现有 TreeView、NavTree、CommandPalette 等组件的 icon 属性已全面拓宽支持 IconSource，既可以直接使用字符串前缀，也可使用组件。"
+      :code="integrationCode"
+    >
+      <div class="max-w-xs rounded-lg border border-slate-200 dark:border-slate-800 p-2 bg-white dark:bg-slate-950">
+        <NavTree :groups="sampleNavGroups" active-href="/pods" />
+      </div>
+    </DocExample>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Settings } from 'lucide-vue-next'
+import { registerIconResolver } from '@recloudstudio/ui'
+
+// 注册示范用前缀解析器
+registerIconResolver('cloud', (name) => {
+  if (name === 'database') {
+    return `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5V19A9 3 0 0 0 21 19V5"/><path d="M3 12A9 3 0 0 0 21 12"/></svg>`
+  }
+  if (name === 'kubernetes') {
+    return `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"/></svg>`
+  }
+  return null
+})
+
+const svgSnippet = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m4.93 4.93 4.24 4.24"/><path d="m14.83 9.17 4.24-4.24"/><path d="m14.83 14.83 4.24 4.24"/><path d="m9.17 14.83-4.24 4.24"/></svg>`
+
+const sampleNavGroups = [
+  {
+    title: '集群资源',
+    items: [
+      { title: 'Pods 实例', href: '/pods', icon: 'lucide:box' },
+      { title: '数据库服务', href: '/db', icon: 'cloud:database' },
+      { title: '路由网关', href: '/gateway', icon: 'lucide:network' }
+    ]
+  }
+]
+
+const sourcesCode = `<template>
+  <div class="flex items-center gap-4">
+    <!-- 1. 直接传入 Vue 组件 -->
+    <Icon :icon="Settings" class="text-primary text-xl" />
+
+    <!-- 2. 带库前缀的字符串 (内置 lucide 支持) -->
+    <Icon icon="lucide:server" class="text-emerald-500 text-xl" />
+
+    <!-- 3. 纯名称匹配 -->
+    <Icon icon="terminal" class="text-amber-500 text-xl" />
+
+    <!-- 4. 直接传入 SVG 标记代码 -->
+    <Icon :icon="svgSnippet" class="text-purple-500 text-xl" />
+
+    <!-- 5. 图像路径或网络资源 -->
+    <Icon icon="/icon.svg" size="1.25rem" />
+  </div>
+</template>`
+
+const sizesCode = `<template>
+  <!-- 跟随父级字号 1em 自动适配 -->
+  <span class="text-xs"><Icon icon="lucide:activity" /> 小号</span>
+  <span class="text-base"><Icon icon="lucide:activity" /> 中号</span>
+  <span class="text-xl"><Icon icon="lucide:activity" /> 大号</span>
+
+  <!-- 显式传入数值(px)或单位字符 -->
+  <Icon icon="lucide:shield-check" :size="16" />
+  <Icon icon="lucide:shield-check" :size="24" />
+  <Icon icon="lucide:shield-check" size="2.5rem" />
+</template>`
+
+const customResolverCode = `import { registerIconResolver } from '@recloudstudio/ui'
+
+// 注册自定义前缀
+registerIconResolver('cloud', (name) => {
+  if (name === 'database') {
+    return '<svg viewBox="0 0 24 24">...</svg>'
+  }
+  return null
+})
+
+// 模板中直接调用
+<Icon icon="cloud:database" size="1.5rem" />`
+
+const a11yCode = `<template>
+  <!-- 装饰图标：自动输出 aria-hidden="true" -->
+  <Icon icon="lucide:bell" />
+
+  <!-- 具有语义的操作图标：设置 role="img" 与 aria-label -->
+  <Icon icon="lucide:bell" label="系统提醒通知" />
+
+  <!-- 回退插槽：当资源不存在时呈现 -->
+  <Icon icon="unknown:missing-icon">
+    <span>N/A</span>
+  </Icon>
+</template>`
+
+const integrationCode = `<template>
+  <!-- NavTree、TreeView、CommandPalette 等原生无缝接收统一 IconSource -->
+  <NavTree :groups="[
+    {
+      title: '集群资源',
+      items: [
+        { title: 'Pods 实例', href: '/pods', icon: 'lucide:box' },
+        { title: '数据库服务', href: '/db', icon: 'cloud:database' }
+      ]
+    }
+  ]" />
+</template>`
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 562ee46..f2b4d4f 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -32,7 +32,8 @@ const groups: DocGroup[] = [
       { name: 'avatar', title: 'Avatar 头像', description: '图像、降级文本与在线状态。' },
       { name: 'kbd', title: 'Kbd 按键提示', description: '快捷键视觉化展示。' },
       { name: 'code-block', title: 'CodeBlock 代码块', description: '带复制、行号和文件标识的代码展示。' },
-      { name: 'spinner', title: 'Spinner 加载', description: '环形加载指示器。' }
+      { name: 'spinner', title: 'Spinner 加载', description: '环形加载指示器。' },
+      { name: 'icon', title: 'Icon 图标', description: '支持组件、图标库前缀、内联 SVG 与图片的多源图标渲染体系。' }
     ]
   },
   {
diff --git a/packages/ui/src/components/code-block/CodeBlock.vue b/packages/ui/src/components/code-block/CodeBlock.vue
index 3f7f77a..4fe5658 100644
--- a/packages/ui/src/components/code-block/CodeBlock.vue
+++ b/packages/ui/src/components/code-block/CodeBlock.vue
@@ -8,7 +8,8 @@
         @click="toggleCollapsed"
       >
         <svg v-if="collapsible" :class="cn('h-3.5 w-3.5 shrink-0 text-[var(--code-muted)] transition-transform duration-200', !isCollapsed && 'rotate-90')" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg>
-        <span v-else class="h-2 w-2 shrink-0 rounded-full bg-[var(--code-accent)] shadow-[0_0_0_3px_rgb(59_130_246_/_0.12)]" aria-hidden="true" />
+        <Icon v-if="effectiveIcon" :icon="effectiveIcon" size="1rem" class="shrink-0" />
+        <span v-else-if="!collapsible" class="h-2 w-2 shrink-0 rounded-full bg-[var(--code-accent)] shadow-[0_0_0_3px_rgb(59_130_246_/_0.12)]" aria-hidden="true" />
         <span v-if="filename" class="truncate font-mono text-xs font-medium text-[var(--code-foreground)]">{{ filename }}</span>
         <span v-if="language" class="font-mono text-[11px] font-semibold uppercase tracking-[0.1em] text-[var(--code-muted)]">{{ language }}</span>
         <span v-if="collapsible" class="shrink-0 text-xs font-medium text-[var(--code-muted)]">{{ isCollapsed ? commonLoc.expandCode : commonLoc.collapseCode }}</span>
@@ -38,26 +39,17 @@
 
 <script setup lang="ts">
 import { computed, onBeforeUnmount, onMounted, shallowRef, useId, watch } from 'vue'
+import { Icon } from '../icon'
+import { resolveCodeBlockIcon } from './languageIcons'
 import { cn } from '../../utils/cn'
 import { useComponentLocale } from '../../locale'
-
-export interface CodeBlockProps {
-  code?: string
-  language?: string
-  filename?: string
-  copyable?: boolean
-  showLineNumbers?: boolean
-  wrap?: boolean
-  maxHeight?: string
-  /** Show a toggle in the header that collapses the code body. Use `v-model:collapsed` to control it. */
-  collapsible?: boolean
-  class?: string
-}
+import type { CodeBlockProps } from './types'
 
 const props = withDefaults(defineProps<CodeBlockProps>(), {
   code: '',
   language: '',
   filename: '',
+  icon: undefined,
   copyable: true,
   showLineNumbers: false,
   wrap: false,
@@ -97,7 +89,8 @@ const SFC_BLOCK_RE = /^<(template|script|style)[\s>]/m
 const PRE_CLASS = 'rc-code-block-pre'
 
 const isCollapsed = computed(() => props.collapsible && collapsed.value)
-const hasHeader = computed(() => Boolean(props.filename || props.language || props.copyable || props.collapsible))
+const effectiveIcon = computed(() => resolveCodeBlockIcon(props.icon, props.language, props.filename))
+const hasHeader = computed(() => Boolean(props.filename || props.language || props.copyable || props.collapsible || effectiveIcon.value))
 const sourceKey = computed(() => `${colorTheme.value}\u0000${props.language}\u0000${props.code}`)
 
 const headerClasses = computed(() => {
diff --git a/packages/ui/src/components/code-block/index.ts b/packages/ui/src/components/code-block/index.ts
index a503383..bed1425 100644
--- a/packages/ui/src/components/code-block/index.ts
+++ b/packages/ui/src/components/code-block/index.ts
@@ -1,2 +1,3 @@
 export { default as CodeBlock } from './CodeBlock.vue'
-export type { CodeBlockProps } from './CodeBlock.vue'
+export type { CodeBlockProps } from './types'
+export * from './languageIcons'
diff --git a/packages/ui/src/components/code-block/languageIcons.test.ts b/packages/ui/src/components/code-block/languageIcons.test.ts
new file mode 100644
index 0000000..389cd0f
--- /dev/null
+++ b/packages/ui/src/components/code-block/languageIcons.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import {
+  DEFAULT_CODE_ICON,
+  LANGUAGE_ICONS,
+  extractExtension,
+  resolveCodeBlockIcon
+} from './languageIcons'
+
+describe('languageIcons', () => {
+  it('extracts extensions from filenames correctly', () => {
+    expect(extractExtension('App.vue')).toBe('vue')
+    expect(extractExtension('config.test.ts')).toBe('ts')
+    expect(extractExtension('style.min.css')).toBe('css')
+    expect(extractExtension('Dockerfile')).toBe('dockerfile')
+    expect(extractExtension('README.md')).toBe('md')
+    expect(extractExtension('file-without-ext')).toBe('')
+    expect(extractExtension('')).toBe('')
+  })
+
+  it('resolves icons based on language accurately', () => {
+    expect(resolveCodeBlockIcon(undefined, 'ts', undefined)).toBe(LANGUAGE_ICONS.ts)
+    expect(resolveCodeBlockIcon(undefined, 'typescript', undefined)).toBe(LANGUAGE_ICONS.typescript)
+    expect(resolveCodeBlockIcon(undefined, 'vue', undefined)).toBe(LANGUAGE_ICONS.vue)
+    expect(resolveCodeBlockIcon(undefined, 'bash', undefined)).toBe(LANGUAGE_ICONS.bash)
+    expect(resolveCodeBlockIcon(undefined, 'python', undefined)).toBe(LANGUAGE_ICONS.python)
+    expect(resolveCodeBlockIcon(undefined, 'rust', undefined)).toBe(LANGUAGE_ICONS.rust)
+    expect(resolveCodeBlockIcon(undefined, 'json', undefined)).toBe(LANGUAGE_ICONS.json)
+    expect(resolveCodeBlockIcon(undefined, 'sql', undefined)).toBe(LANGUAGE_ICONS.sql)
+  })
+
+  it('resolves icons based on filename extension when language is not provided', () => {
+    expect(resolveCodeBlockIcon(undefined, undefined, 'deploy.sh')).toBe(LANGUAGE_ICONS.sh)
+    expect(resolveCodeBlockIcon(undefined, undefined, 'schema.prisma.sql')).toBe(LANGUAGE_ICONS.sql)
+    expect(resolveCodeBlockIcon(undefined, undefined, 'config.yaml')).toBe(LANGUAGE_ICONS.yaml)
+    expect(resolveCodeBlockIcon(undefined, undefined, 'Dockerfile')).toBe(LANGUAGE_ICONS.dockerfile)
+  })
+
+  it('respects explicit icon overrides', () => {
+    // icon: false explicitly disables icon
+    expect(resolveCodeBlockIcon(false, 'ts', 'main.ts')).toBeNull()
+
+    // icon: custom string or component overrides matched language
+    const customIcon = 'lucide:file-code'
+    expect(resolveCodeBlockIcon(customIcon, 'ts', 'main.ts')).toBe(customIcon)
+
+    // icon: true falls back to DEFAULT_CODE_ICON when language is unrecognized
+    expect(resolveCodeBlockIcon(true, 'unknown-lang-xyz', 'data.unknown')).toBe(DEFAULT_CODE_ICON)
+
+    // icon: undefined returns null when language/filename is unrecognized
+    expect(resolveCodeBlockIcon(undefined, 'unknown-lang-xyz', 'data.unknown')).toBeNull()
+  })
+})
diff --git a/packages/ui/src/components/code-block/languageIcons.ts b/packages/ui/src/components/code-block/languageIcons.ts
new file mode 100644
index 0000000..81db0ad
--- /dev/null
+++ b/packages/ui/src/components/code-block/languageIcons.ts
@@ -0,0 +1,126 @@
+import type { IconSource } from '../icon'
+
+/**
+ * 语言与文件扩展名到内置 SVG 图标的规范化映射。
+ */
+export const LANGUAGE_ICONS: Record<string, string> = {
+  // TypeScript
+  ts: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#3178C6"/><path d="M4 8h8M8 8v11" stroke="#fff" stroke-width="2" stroke-linecap="round"/><path d="M19 11.5c-1-1-3-1-4 0s0 2.5 1.5 3 2.5 1 2.5 2.5-1.5 2-3 1.5" stroke="#fff" stroke-width="2" stroke-linecap="round"/></svg>`,
+  typescript: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#3178C6"/><path d="M4 8h8M8 8v11" stroke="#fff" stroke-width="2" stroke-linecap="round"/><path d="M19 11.5c-1-1-3-1-4 0s0 2.5 1.5 3 2.5 1 2.5 2.5-1.5 2-3 1.5" stroke="#fff" stroke-width="2" stroke-linecap="round"/></svg>`,
+  tsx: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#3178C6"/><path d="M4 8h8M8 8v11" stroke="#fff" stroke-width="2" stroke-linecap="round"/><path d="M19 11.5c-1-1-3-1-4 0s0 2.5 1.5 3 2.5 1 2.5 2.5-1.5 2-3 1.5" stroke="#fff" stroke-width="2" stroke-linecap="round"/></svg>`,
+
+  // JavaScript
+  js: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#F7DF1E"/><path d="M8 12v5a2 2 0 0 1-2 2H5" stroke="#000" stroke-width="2" stroke-linecap="round"/><path d="M18 13c-1-1-3-1-4 0s0 2.5 1.5 3 2.5 1 2.5 2.5-1.5 2-3 1.5" stroke="#000" stroke-width="2" stroke-linecap="round"/></svg>`,
+  javascript: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#F7DF1E"/><path d="M8 12v5a2 2 0 0 1-2 2H5" stroke="#000" stroke-width="2" stroke-linecap="round"/><path d="M18 13c-1-1-3-1-4 0s0 2.5 1.5 3 2.5 1 2.5 2.5-1.5 2-3 1.5" stroke="#000" stroke-width="2" stroke-linecap="round"/></svg>`,
+  jsx: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#F7DF1E"/><path d="M8 12v5a2 2 0 0 1-2 2H5" stroke="#000" stroke-width="2" stroke-linecap="round"/><path d="M18 13c-1-1-3-1-4 0s0 2.5 1.5 3 2.5 1 2.5 2.5-1.5 2-3 1.5" stroke="#000" stroke-width="2" stroke-linecap="round"/></svg>`,
+
+  // Vue
+  vue: `<svg viewBox="0 0 24 24" fill="none"><path d="M2 3h4.5L12 13 17.5 3H22L12 20 2 3z" fill="#41B883"/><path d="M6.5 3h4L12 5.5 13.5 3h4L12 12 6.5 3z" fill="#35495E"/></svg>`,
+  'vue-html': `<svg viewBox="0 0 24 24" fill="none"><path d="M2 3h4.5L12 13 17.5 3H22L12 20 2 3z" fill="#41B883"/><path d="M6.5 3h4L12 5.5 13.5 3h4L12 12 6.5 3z" fill="#35495E"/></svg>`,
+
+  // HTML
+  html: `<svg viewBox="0 0 24 24" fill="none"><path d="M4 2l1.6 18 6.4 2 6.4-2L20 2H4z" fill="#E34F26"/><path d="M12 4v16.1l4.9-1.5 1.2-13.6H12z" fill="#EF652A"/><path d="M8 7h8m-8 4h7.5m-7.5 4h5l-.5 2.5-2.5.7-2.5-.7-.2-1.5" stroke="#fff" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+
+  // CSS
+  css: `<svg viewBox="0 0 24 24" fill="none"><path d="M4 2l1.6 18 6.4 2 6.4-2L20 2H4z" fill="#1572B6"/><path d="M12 4v16.1l4.9-1.5 1.2-13.6H12z" fill="#33A9DC"/><path d="M8 7h8m-8 4h7.5m-7.5 4h5l-.5 2.5-2.5.7-2.5-.7-.2-1.5" stroke="#fff" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+
+  // JSON
+  json: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#292929"/><path d="M8 7c-1.5 0-2 1-2 2.5v1c0 1-.5 1.5-1.5 1.5 1 0 1.5.5 1.5 1.5v1c0 1.5.5 2.5 2 2.5m8-10c1.5 0 2 1 2 2.5v1c0 1 .5 1.5 1.5 1.5-1 0-1.5.5-1.5 1.5v1c0 1.5-.5 2.5-2 2.5" stroke="#CBCB41" stroke-width="1.8" stroke-linecap="round"/></svg>`,
+
+  // Shell / Bash / Sh / Zsh
+  bash: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#293138"/><path d="M6 8l4 4-4 4m6 1h6" stroke="#4EAA25" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  sh: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#293138"/><path d="M6 8l4 4-4 4m6 1h6" stroke="#4EAA25" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  shell: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#293138"/><path d="M6 8l4 4-4 4m6 1h6" stroke="#4EAA25" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  shellscript: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#293138"/><path d="M6 8l4 4-4 4m6 1h6" stroke="#4EAA25" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  zsh: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#293138"/><path d="M6 8l4 4-4 4m6 1h6" stroke="#4EAA25" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+
+  // Log
+  log: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#334155"/><path d="M7 7h10M7 11h10M7 15h6" stroke="#94A3B8" stroke-width="2" stroke-linecap="round"/></svg>`,
+
+  // Python
+  python: `<svg viewBox="0 0 24 24" fill="none"><path d="M11.8 3c-4.2 0-3.9 1.8-3.9 1.8l.04 1.9h4v.6H6.3s-2.5.3-2.5 3.9 2.2 3.8 2.2 3.8h1.3v-1.9c0-2.2 1.9-2.1 1.9-2.1h3.9s1.8 0 1.8-1.8V5.3s.3-2.3-3.1-2.3zm-1.2 1.2a.7.7 0 1 1 0 1.4.7.7 0 0 1 0-1.4z" fill="#3776AB"/><path d="M12.2 21c4.2 0 3.9-1.8 3.9-1.8l-.04-1.9h-4v-.6h5.6s2.5-.3 2.5-3.9-2.2-3.8-2.2-3.8h-1.3v1.9c0 2.2-1.9 2.1-1.9 2.1h-3.9s-1.8 0-1.8 1.8v3.9s-.3 2.3 3.1 2.3zm1.2-1.2a.7.7 0 1 1 0-1.4.7.7 0 0 1 0 1.4z" fill="#FFD43B"/></svg>`,
+  py: `<svg viewBox="0 0 24 24" fill="none"><path d="M11.8 3c-4.2 0-3.9 1.8-3.9 1.8l.04 1.9h4v.6H6.3s-2.5.3-2.5 3.9 2.2 3.8 2.2 3.8h1.3v-1.9c0-2.2 1.9-2.1 1.9-2.1h3.9s1.8 0 1.8-1.8V5.3s.3-2.3-3.1-2.3zm-1.2 1.2a.7.7 0 1 1 0 1.4.7.7 0 0 1 0-1.4z" fill="#3776AB"/><path d="M12.2 21c4.2 0 3.9-1.8 3.9-1.8l-.04-1.9h-4v-.6h5.6s2.5-.3 2.5-3.9-2.2-3.8-2.2-3.8h-1.3v1.9c0 2.2-1.9 2.1-1.9 2.1h-3.9s-1.8 0-1.8 1.8v3.9s-.3 2.3 3.1 2.3zm1.2-1.2a.7.7 0 1 1 0-1.4.7.7 0 0 1 0 1.4z" fill="#FFD43B"/></svg>`,
+
+  // Rust
+  rust: `<svg viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="9" fill="#000"/><path d="M8 8h5a2 2 0 0 1 0 4H8v4m5-4l3 4" stroke="#DEA584" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  rs: `<svg viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="9" fill="#000"/><path d="M8 8h5a2 2 0 0 1 0 4H8v4m5-4l3 4" stroke="#DEA584" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+
+  // Go
+  go: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#00ADD8"/><path d="M6 12h5a4 4 0 1 1-4-4" stroke="#fff" stroke-width="2" stroke-linecap="round"/><path d="M14 12a3 3 0 1 0 6 0 3 3 0 0 0-6 0z" stroke="#fff" stroke-width="2"/></svg>`,
+  golang: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#00ADD8"/><path d="M6 12h5a4 4 0 1 1-4-4" stroke="#fff" stroke-width="2" stroke-linecap="round"/><path d="M14 12a3 3 0 1 0 6 0 3 3 0 0 0-6 0z" stroke="#fff" stroke-width="2"/></svg>`,
+
+  // Markdown
+  md: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#083FA1"/><path d="M4 16V8l3.5 4.5L11 8v8m5-6v6m-2.5-3.5L16 14l2.5-3.5" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  markdown: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#083FA1"/><path d="M4 16V8l3.5 4.5L11 8v8m5-6v6m-2.5-3.5L16 14l2.5-3.5" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+
+  // YAML / TOML
+  yaml: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#CB171E"/><path d="M6 7l3.5 5.5L13 7m-3.5 5.5V17" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  yml: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#CB171E"/><path d="M6 7l3.5 5.5L13 7m-3.5 5.5V17" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+  toml: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#9C4121"/><path d="M6 8h8M10 8v8" stroke="#fff" stroke-width="2" stroke-linecap="round"/></svg>`,
+
+  // SQL
+  sql: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#00758F"/><ellipse cx="12" cy="7" rx="6" ry="3" stroke="#fff" stroke-width="1.8"/><path d="M6 7v10c0 1.7 2.7 3 6 3s6-1.3 6-3V7" stroke="#fff" stroke-width="1.8"/><path d="M6 12c0 1.7 2.7 3 6 3s6-1.3 6-3" stroke="#fff" stroke-width="1.8"/></svg>`,
+
+  // Docker
+  docker: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#2496ED"/><path d="M4 14c1-4 5-5 12-4 1-2 3-3 5-3-.3 2 .2 3-.5 4 1 2 0 5-6 5-4 0-8-1-10.5-2z" fill="#fff"/></svg>`,
+  dockerfile: `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#2496ED"/><path d="M4 14c1-4 5-5 12-4 1-2 3-3 5-3-.3 2 .2 3-.5 4 1 2 0 5-6 5-4 0-8-1-10.5-2z" fill="#fff"/></svg>`
+}
+
+/**
+ * 默认通用代码文件图标（当无法匹配到具体语言时使用）。
+ */
+export const DEFAULT_CODE_ICON = `<svg viewBox="0 0 24 24" fill="none"><rect width="24" height="24" rx="4" fill="#475569"/><path d="M8 9l-3 3 3 3m8-6l3 3-3 3m-4-7l-2 8" stroke="#F1F5F9" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg>`
+
+/**
+ * 从文件名提取可能的文件扩展名（不带点，小写）。
+ * 例如：`App.vue` -> `vue`，`config.test.ts` -> `ts`，`Dockerfile` -> `dockerfile`。
+ */
+export function extractExtension(filename: string): string {
+  if (!filename) return ''
+  const trimmed = filename.trim().toLowerCase()
+  if (trimmed === 'dockerfile') return 'dockerfile'
+
+  const lastDot = trimmed.lastIndexOf('.')
+  if (lastDot === -1 || lastDot === trimmed.length - 1) return ''
+  return trimmed.slice(lastDot + 1)
+}
+
+/**
+ * 根据语言或文件名解析对应的编程语言图标源。
+ */
+export function resolveCodeBlockIcon(
+  explicitIcon: IconSource | boolean | undefined,
+  language: string | undefined,
+  filename: string | undefined
+): IconSource | null {
+  // 显式为 false 时禁用图标
+  if (explicitIcon === false) {
+    return null
+  }
+
+  // 显式提供了自定义图标（非 boolean），优先使用
+  if (explicitIcon && typeof explicitIcon !== 'boolean') {
+    return explicitIcon
+  }
+
+  // 尝试根据 language 匹配
+  const normLang = language?.trim().toLowerCase()
+  if (normLang && LANGUAGE_ICONS[normLang]) {
+    return LANGUAGE_ICONS[normLang]
+  }
+
+  // 尝试根据 filename 扩展名匹配
+  if (filename) {
+    const ext = extractExtension(filename)
+    if (ext && LANGUAGE_ICONS[ext]) {
+      return LANGUAGE_ICONS[ext]
+    }
+  }
+
+  // 如果显式设置了 icon === true，但未匹配到具体语言，使用通用代码文件图标兜底
+  if (explicitIcon === true) {
+    return DEFAULT_CODE_ICON
+  }
+
+  return null
+}
diff --git a/packages/ui/src/components/code-block/types.ts b/packages/ui/src/components/code-block/types.ts
new file mode 100644
index 0000000..8ac6f6f
--- /dev/null
+++ b/packages/ui/src/components/code-block/types.ts
@@ -0,0 +1,22 @@
+import type { IconSource } from '../icon'
+
+export interface CodeBlockProps {
+  code?: string
+  language?: string
+  filename?: string
+  /**
+   * 编程语言或代码文件图标。
+   * - `true`: 根据 `language` 或 `filename` 自动匹配图标（未匹配到时显示通用代码图标）；
+   * - `false`: 禁用图标（保留小圆点或折叠指示器）；
+   * - `IconSource`（组件、SVG 代码或前缀名）：自定义显示指定图标。
+   * 默认情况下，当传入非空的 `language` 或 `filename` 时自动尝试匹配语言图标。
+   */
+  icon?: IconSource | boolean
+  copyable?: boolean
+  showLineNumbers?: boolean
+  wrap?: boolean
+  maxHeight?: string
+  /** Show a toggle in the header that collapses the code body. Use `v-model:collapsed` to control it. */
+  collapsible?: boolean
+  class?: string
+}
diff --git a/packages/ui/src/components/code-group/CodeGroup.vue b/packages/ui/src/components/code-group/CodeGroup.vue
index ba32bc5..31d9bae 100644
--- a/packages/ui/src/components/code-group/CodeGroup.vue
+++ b/packages/ui/src/components/code-group/CodeGroup.vue
@@ -14,6 +14,7 @@
         ]"
         @click="selectTab(tab.key)"
       >
+        <Icon v-if="tab.icon" :icon="tab.icon" size="0.875rem" class="shrink-0" />
         <span>{{ tab.label }}</span>
       </button>
     </div>
@@ -29,6 +30,7 @@
 
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
+import { Icon, type IconSource } from '../icon'
 import type { CodeGroupProps, CodeGroupTab } from './types'
 
 const props = withDefaults(defineProps<CodeGroupProps>(), {
@@ -45,7 +47,7 @@ const emit = defineEmits<{
 interface InternalTab {
   label: string
   key: string
-  icon?: string
+  icon?: IconSource
 }
 
 const normalizedTabs = computed<InternalTab[]>(() => {
diff --git a/packages/ui/src/components/code-group/types.ts b/packages/ui/src/components/code-group/types.ts
index 4438763..410572e 100644
--- a/packages/ui/src/components/code-group/types.ts
+++ b/packages/ui/src/components/code-group/types.ts
@@ -1,7 +1,9 @@
+import type { IconSource } from '../icon'
+
 export interface CodeGroupTab {
   label: string
   key?: string
-  icon?: string
+  icon?: IconSource
 }
 
 export interface CodeGroupProps {
diff --git a/packages/ui/src/components/command-palette/CommandPalette.vue b/packages/ui/src/components/command-palette/CommandPalette.vue
index a71ffc8..404f703 100644
--- a/packages/ui/src/components/command-palette/CommandPalette.vue
+++ b/packages/ui/src/components/command-palette/CommandPalette.vue
@@ -45,7 +45,7 @@
               @mouseenter="setActive(item.id)"
               @click="selectItem(item)"
             >
-              <component :is="item.icon" v-if="item.icon" class="h-4 w-4 shrink-0 text-slate-500 dark:text-slate-400" aria-hidden="true" />
+              <Icon :icon="item.icon" v-if="item.icon" size="1rem" class="shrink-0 text-slate-500 dark:text-slate-400" />
               <slot name="item" :item="item" :active="activeItem?.id === item.id">
                 <span class="min-w-0 grow">
                   <span class="block truncate text-sm font-medium text-slate-800 dark:text-slate-100">{{ item.label }}</span>
@@ -69,6 +69,7 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTitle } from 'reka-ui'
+import { Icon } from '../icon'
 import { filterCommands } from './commandMatcher'
 import { useComponentLocale } from '../../locale'
 import type { CommandFilter, CommandGroup, CommandItem } from './types'
diff --git a/packages/ui/src/components/command-palette/types.ts b/packages/ui/src/components/command-palette/types.ts
index 674e461..1072088 100644
--- a/packages/ui/src/components/command-palette/types.ts
+++ b/packages/ui/src/components/command-palette/types.ts
@@ -1,4 +1,4 @@
-import type { Component } from 'vue'
+import type { IconSource } from '../icon'
 
 export interface CommandItem {
   /** Stable identifier returned with the select event. */
@@ -7,7 +7,7 @@ export interface CommandItem {
   description?: string
   keywords?: string[]
   shortcut?: string[]
-  icon?: Component
+  icon?: IconSource
   disabled?: boolean
   /** Keep the palette open after this item is selected. */
   keepOpen?: boolean
diff --git a/packages/ui/src/components/context-menu/ContextMenu.vue b/packages/ui/src/components/context-menu/ContextMenu.vue
index 3ff3396..964ce1f 100644
--- a/packages/ui/src/components/context-menu/ContextMenu.vue
+++ b/packages/ui/src/components/context-menu/ContextMenu.vue
@@ -18,7 +18,7 @@
             ]"
             @select="item.onSelect && item.onSelect()"
           >
-            <component :is="item.icon" v-if="item.icon" class="mr-2 h-3.5 w-3.5" />
+            <Icon :icon="item.icon" v-if="item.icon" size="0.875rem" class="mr-2" />
             <span>{{ item.label }}</span>
           </ContextMenuItem>
         </template>
@@ -33,11 +33,12 @@ import { computed } from 'vue'
 import {
   ContextMenuRoot, ContextMenuTrigger, ContextMenuPortal, ContextMenuContent, ContextMenuItem, ContextMenuSeparator
 } from 'reka-ui'
+import { Icon, type IconSource } from '../icon'
 import { cn } from '../../utils/cn'
 
 export interface ContextMenuItemData {
   label?: string
-  icon?: any
+  icon?: IconSource
   disabled?: boolean
   destructive?: boolean
   separator?: boolean
diff --git a/packages/ui/src/components/dropdown/DropdownMenu.vue b/packages/ui/src/components/dropdown/DropdownMenu.vue
index b111856..43fccca 100644
--- a/packages/ui/src/components/dropdown/DropdownMenu.vue
+++ b/packages/ui/src/components/dropdown/DropdownMenu.vue
@@ -25,7 +25,7 @@
             ]"
             @select="item.onSelect && item.onSelect()"
           >
-            <component :is="item.icon" v-if="item.icon" class="mr-2 h-3.5 w-3.5" />
+            <Icon :icon="item.icon" v-if="item.icon" size="0.875rem" class="mr-2" />
             <span>{{ item.label }}</span>
           </DropdownMenuItem>
         </template>
@@ -45,11 +45,12 @@ import {
   DropdownMenuItem,
   DropdownMenuSeparator
 } from 'reka-ui'
+import { Icon, type IconSource } from '../icon'
 import { cn } from '../../utils/cn'
 
 export interface DropdownMenuItemType {
   label?: string
-  icon?: any
+  icon?: IconSource
   disabled?: boolean
   destructive?: boolean
   separator?: boolean
diff --git a/packages/ui/src/components/icon/Icon.vue b/packages/ui/src/components/icon/Icon.vue
new file mode 100644
index 0000000..cbd643c
--- /dev/null
+++ b/packages/ui/src/components/icon/Icon.vue
@@ -0,0 +1,74 @@
+<template>
+  <span
+    class="inline-flex shrink-0 items-center justify-center align-middle"
+    :style="sizeStyle"
+    :role="label ? 'img' : undefined"
+    :aria-label="label || undefined"
+    :aria-hidden="label ? undefined : 'true'"
+  >
+    <component
+      :is="resolved.component"
+      v-if="resolved?.kind === 'component'"
+      class="h-full w-full"
+    />
+    <span
+      v-else-if="resolved?.kind === 'svg'"
+      class="inline-flex h-full w-full items-center justify-center [&>svg]:h-full [&>svg]:w-full"
+      v-html="resolved.markup"
+    />
+    <img
+      v-else-if="resolved?.kind === 'image'"
+      :src="resolved.src"
+      alt=""
+      class="h-full w-full object-contain"
+    />
+    <slot v-else />
+  </span>
+</template>
+
+<script setup lang="ts">
+import { computed, shallowRef, watch } from 'vue'
+import { iconRegistryVersion, resolveIconSource } from './registry'
+import type { IconProps, ResolvedIcon } from './types'
+
+defineOptions({
+  name: 'ReIcon'
+})
+
+const props = withDefaults(defineProps<IconProps>(), {
+  size: '1em'
+})
+
+const resolved = shallowRef<ResolvedIcon | null>(null)
+let currentToken = 0
+
+function updateIcon(): void {
+  const token = ++currentToken
+  const outcome = resolveIconSource(props.icon)
+
+  if (outcome && typeof (outcome as Promise<unknown>).then === 'function') {
+    resolved.value = null
+    // SAFETY: outcome is checked as a thenable Promise yielding ResolvedIcon | null.
+    ;(outcome as Promise<ResolvedIcon | null>).then((result) => {
+      if (token === currentToken) {
+        resolved.value = result
+      }
+    })
+  } else {
+    // SAFETY: outcome is synchronous ResolvedIcon | null when not a thenable.
+    resolved.value = outcome as ResolvedIcon | null
+  }
+}
+
+watch([() => props.icon, () => iconRegistryVersion.value], updateIcon, {
+  immediate: true
+})
+
+const sizeStyle = computed(() => {
+  if (props.size === undefined || props.size === null) {
+    return { width: '1em', height: '1em' }
+  }
+  const sizeValue = typeof props.size === 'number' ? `${props.size}px` : props.size
+  return { width: sizeValue, height: sizeValue }
+})
+</script>
diff --git a/packages/ui/src/components/icon/icon.test.ts b/packages/ui/src/components/icon/icon.test.ts
new file mode 100644
index 0000000..ab6785d
--- /dev/null
+++ b/packages/ui/src/components/icon/icon.test.ts
@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { Icon } from './index'
+
+describe('Icon component', () => {
+  it('is exported as a Vue component', () => {
+    expect(Icon).toBeDefined()
+    expect(Icon.name || Icon.__name).toBe('ReIcon')
+  })
+
+  it('implements accessibility semantics, sizing, and slot fallbacks in template', () => {
+    const sfcPath = resolve(__dirname, './Icon.vue')
+    const source = readFileSync(sfcPath, 'utf-8')
+
+    // Accessibility: label given sets role="img" and aria-label; absent sets aria-hidden="true"
+    expect(source).toContain(':role="label ? \'img\' : undefined"')
+    expect(source).toContain(':aria-label="label || undefined"')
+    expect(source).toContain(':aria-hidden="label ? undefined : \'true\'"')
+
+    // Rendering branches: component, svg markup, image src, slot fallback
+    expect(source).toContain("resolved?.kind === 'component'")
+    expect(source).toContain("resolved?.kind === 'svg'")
+    expect(source).toContain("resolved?.kind === 'image'")
+    expect(source).toContain('<slot v-else />')
+
+    // Size binding
+    expect(source).toContain(':style="sizeStyle"')
+  })
+})
diff --git a/packages/ui/src/components/icon/index.ts b/packages/ui/src/components/icon/index.ts
new file mode 100644
index 0000000..27940d2
--- /dev/null
+++ b/packages/ui/src/components/icon/index.ts
@@ -0,0 +1,4 @@
+export { default as Icon } from './Icon.vue'
+export * from './types'
+export * from './registry'
+export { lookupLucideIcon, toPascalCase } from './lucideResolver'
diff --git a/packages/ui/src/components/icon/lucideResolver.ts b/packages/ui/src/components/icon/lucideResolver.ts
new file mode 100644
index 0000000..5629d3e
--- /dev/null
+++ b/packages/ui/src/components/icon/lucideResolver.ts
@@ -0,0 +1,55 @@
+import type { Component } from 'vue'
+
+/**
+ * 将 kebab-case、snake_case 或空格分隔的命名转换为 PascalCase。
+ * 例如：'settings' -> 'Settings', 'arrow-left' -> 'ArrowLeft', 'circle-alert' -> 'CircleAlert'。
+ */
+export function toPascalCase(name: string): string {
+  if (!name) return ''
+  const trimmed = name.trim()
+  if (!trimmed) return ''
+
+  const parts = trimmed.split(/[-_\s]+/).filter(Boolean)
+  if (parts.length === 0) return ''
+
+  return parts
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+/**
+ * 缓存已加载的 lucide-vue-next 模块，避免重复动态导入。
+ */
+let lucideModulePromise: Promise<Record<string, unknown>> | null = null
+
+function loadLucideModule(): Promise<Record<string, unknown>> {
+  if (!lucideModulePromise) {
+    lucideModulePromise = import('lucide-vue-next').then((m) => {
+      // SAFETY: lucide-vue-next exports named Vue components under icon identifier keys.
+      return m as Record<string, unknown>
+    })
+  }
+  return lucideModulePromise
+}
+
+/**
+ * 从 lucide-vue-next 中查找指定名称的图标组件。
+ */
+export async function lookupLucideIcon(name: string): Promise<Component | null> {
+  if (!name) return null
+  const mod = await loadLucideModule()
+  const pascal = toPascalCase(name)
+
+  const candidate =
+    mod[pascal] ??
+    mod[`${pascal}Icon`] ??
+    mod[name] ??
+    mod[`${name}Icon`]
+
+  if (candidate && (typeof candidate === 'object' || typeof candidate === 'function')) {
+    // SAFETY: the resolved candidate is a Vue component function or options object.
+    return candidate as Component
+  }
+
+  return null
+}
diff --git a/packages/ui/src/components/icon/registry.test.ts b/packages/ui/src/components/icon/registry.test.ts
new file mode 100644
index 0000000..f672d14
--- /dev/null
+++ b/packages/ui/src/components/icon/registry.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest'
+import { toPascalCase } from './lucideResolver'
+import {
+  classifyIconSource,
+  looksLikeImage,
+  looksLikeSvg,
+  parsePrefixedName,
+  registerIconResolver,
+  resolveIconSource,
+  setDefaultIconResolver,
+  unregisterIconResolver
+} from './registry'
+
+describe('Icon registry and classification', () => {
+  it('correctly converts naming conventions to PascalCase', () => {
+    expect(toPascalCase('settings')).toBe('Settings')
+    expect(toPascalCase('arrow-left')).toBe('ArrowLeft')
+    expect(toPascalCase('circle_alert')).toBe('CircleAlert')
+    expect(toPascalCase('folder open')).toBe('FolderOpen')
+    expect(toPascalCase('ChevronRight')).toBe('ChevronRight')
+    expect(toPascalCase('')).toBe('')
+  })
+
+  it('classifies SVG markup, image paths, and named icons accurately', () => {
+    expect(looksLikeSvg('<svg viewBox="0 0 24 24"><path /></svg>')).toBe(true)
+    expect(looksLikeSvg('  <svg class="h-4">')).toBe(true)
+    expect(looksLikeSvg('settings')).toBe(false)
+
+    expect(looksLikeImage('/icons/app.svg')).toBe(true)
+    expect(looksLikeImage('./logo.png')).toBe(true)
+    expect(looksLikeImage('../assets/hero.webp')).toBe(true)
+    expect(looksLikeImage('https://example.com/icon.svg')).toBe(true)
+    expect(looksLikeImage('data:image/svg+xml;base64,PHN2Zz4...')).toBe(true)
+    expect(looksLikeImage('lucide:settings')).toBe(false)
+
+    expect(classifyIconSource('<svg></svg>')).toBe('svg')
+    expect(classifyIconSource('/brand.png')).toBe('image')
+    expect(classifyIconSource('lucide:settings')).toBe('named')
+    expect(classifyIconSource({ render: () => null })).toBe('component')
+  })
+
+  it('parses prefixed names accurately', () => {
+    expect(parsePrefixedName('lucide:settings')).toEqual({
+      prefix: 'lucide',
+      name: 'settings'
+    })
+    expect(parsePrefixedName('MDI:home-outline')).toEqual({
+      prefix: 'mdi',
+      name: 'home-outline'
+    })
+    expect(parsePrefixedName('plain-name')).toBeNull()
+  })
+
+  it('resolves direct Vue component sources synchronously', () => {
+    const dummyComponent = { name: 'DummyIcon' }
+    const result = resolveIconSource(dummyComponent)
+    expect(result).toEqual({ kind: 'component', component: dummyComponent })
+  })
+
+  it('resolves inline SVG markup synchronously', () => {
+    const svgCode = '<svg viewBox="0 0 16 16"><circle cx="8" cy="8" r="4" /></svg>'
+    const result = resolveIconSource(svgCode)
+    expect(result).toEqual({ kind: 'svg', markup: svgCode })
+  })
+
+  it('resolves image URLs synchronously', () => {
+    const url = 'https://ui.worldexecute.me/icon.svg'
+    const result = resolveIconSource(url)
+    expect(result).toEqual({ kind: 'image', src: url })
+  })
+
+  it('supports registering and unregistering custom prefix resolvers', async () => {
+    const customSvg = '<svg viewBox="0 0 24 24"><path d="M0 0h24v24H0z" /></svg>'
+    registerIconResolver('testcustom', (name) => {
+      if (name === 'check') return customSvg
+      if (name === 'image') return '/resolved.png'
+      return null
+    })
+
+    const checkResult = resolveIconSource('testcustom:check')
+    expect(checkResult).toEqual({ kind: 'svg', markup: customSvg })
+
+    const imgResult = resolveIconSource('testcustom:image')
+    expect(imgResult).toEqual({ kind: 'image', src: '/resolved.png' })
+
+    const unknownResult = resolveIconSource('testcustom:missing')
+    expect(unknownResult).toBeNull()
+
+    unregisterIconResolver('testcustom')
+    const unregistered = resolveIconSource('testcustom:check')
+    // After unregistration, unregistered prefix with no default resolver resolves to null
+    expect(unregistered).toBeNull()
+  })
+
+  it('supports asynchronous custom resolvers', async () => {
+    registerIconResolver('testasync', async (name) => {
+      if (name === 'rocket') {
+        return '<svg id="rocket"></svg>'
+      }
+      return null
+    })
+
+    const promise = resolveIconSource('testasync:rocket')
+    expect(promise).toBeInstanceOf(Promise)
+    const resolved = await promise
+    expect(resolved).toEqual({ kind: 'svg', markup: '<svg id="rocket"></svg>' })
+
+    unregisterIconResolver('testasync')
+  })
+
+  it('falls back to default resolver for unknown prefixes and bare names', async () => {
+    setDefaultIconResolver((name) => {
+      if (name === 'app-logo') return '/logo.svg'
+      if (name === 'unknown:test') return '<svg id="fallback"></svg>'
+      return null
+    })
+
+    const bareResult = resolveIconSource('app-logo')
+    expect(bareResult).toEqual({ kind: 'image', src: '/logo.svg' })
+
+    const prefixResult = resolveIconSource('unknown:test')
+    expect(prefixResult).toEqual({ kind: 'svg', markup: '<svg id="fallback"></svg>' })
+
+    setDefaultIconResolver(null)
+  })
+
+  it('resolves lucide icons asynchronously via built-in resolver', async () => {
+    const outcome = resolveIconSource('lucide:settings')
+    expect(outcome).toBeInstanceOf(Promise)
+    const resolved = await outcome
+    expect(resolved).not.toBeNull()
+    expect(resolved?.kind).toBe('component')
+  })
+})
diff --git a/packages/ui/src/components/icon/registry.ts b/packages/ui/src/components/icon/registry.ts
new file mode 100644
index 0000000..92d2102
--- /dev/null
+++ b/packages/ui/src/components/icon/registry.ts
@@ -0,0 +1,186 @@
+import { ref } from 'vue'
+import { lookupLucideIcon } from './lucideResolver'
+import type { IconResolver, IconSource, ResolvedIcon } from './types'
+
+/**
+ * 响应式版本号计数器，供 Icon 组件监听动态注册变更。
+ */
+export const iconRegistryVersion = ref(0)
+
+const prefixResolvers = new Map<string, IconResolver>()
+let defaultIconResolver: IconResolver | null = null
+
+/**
+ * 注册指定前缀的图标库解析器（前缀不区分大小写）。
+ * 例如：`registerIconResolver('mdi', (name) => ...)`
+ */
+export function registerIconResolver(prefix: string, resolver: IconResolver): void {
+  const normalized = prefix.trim().toLowerCase()
+  if (!normalized) return
+  prefixResolvers.set(normalized, resolver)
+  iconRegistryVersion.value++
+}
+
+/**
+ * 注销指定前缀的图标库解析器。
+ */
+export function unregisterIconResolver(prefix: string): void {
+  const normalized = prefix.trim().toLowerCase()
+  if (prefixResolvers.delete(normalized)) {
+    iconRegistryVersion.value++
+  }
+}
+
+/**
+ * 设置未带前缀图标名称的默认解析器。
+ */
+export function setDefaultIconResolver(resolver: IconResolver | null | undefined): void {
+  defaultIconResolver = resolver ?? null
+  iconRegistryVersion.value++
+}
+
+/**
+ * 判断字符串是否为内联 SVG 代码片段。
+ */
+export function looksLikeSvg(value: string): boolean {
+  return /^\s*<svg[\s>]/i.test(value)
+}
+
+/**
+ * 判断字符串是否为图像路径、网络 URL 或 Data URL。
+ */
+export function looksLikeImage(value: string): boolean {
+  const trimmed = value.trim()
+  if (
+    /^(?:https?:)?\/\//i.test(trimmed) ||
+    trimmed.startsWith('/') ||
+    trimmed.startsWith('./') ||
+    trimmed.startsWith('../') ||
+    trimmed.startsWith('data:image/')
+  ) {
+    return true
+  }
+  return /\.(svg|png|jpe?g|gif|webp|avif|ico)([?#].*)?$/i.test(trimmed)
+}
+
+/**
+ * 解析带前缀的名称（例如 `'lucide:settings'` -> `{ prefix: 'lucide', name: 'settings' }`）。
+ */
+export function parsePrefixedName(
+  value: string
+): { prefix: string; name: string } | null {
+  const trimmed = value.trim()
+  const match = /^([a-zA-Z0-9_-]+):(.*)$/.exec(trimmed)
+  if (!match) return null
+  return {
+    prefix: match[1].toLowerCase(),
+    name: match[2].trim()
+  }
+}
+
+/**
+ * 分析给定的图标源类型归类。
+ */
+export function classifyIconSource(
+  source: IconSource
+): 'component' | 'svg' | 'image' | 'named' {
+  if (typeof source !== 'string') {
+    return 'component'
+  }
+  if (looksLikeSvg(source)) {
+    return 'svg'
+  }
+  if (looksLikeImage(source)) {
+    return 'image'
+  }
+  return 'named'
+}
+
+function isPromise<T>(value: unknown): value is Promise<T> {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+  // SAFETY: duck-typing thenable checks whether `then` is callable.
+  const candidate = value as { then?: unknown }
+  return typeof candidate.then === 'function'
+}
+
+function normalizeResolved(result: IconSource | null | undefined): ResolvedIcon | null {
+  if (!result) return null
+  if (typeof result !== 'string') {
+    return { kind: 'component', component: result }
+  }
+  const trimmed = result.trim()
+  if (!trimmed) return null
+  if (looksLikeSvg(trimmed)) {
+    return { kind: 'svg', markup: trimmed }
+  }
+  if (looksLikeImage(trimmed)) {
+    return { kind: 'image', src: trimmed }
+  }
+  return null
+}
+
+/**
+ * 解析任意图标源为已规范化形态（支持同步返回或异步 Promise）。
+ */
+export function resolveIconSource(
+  source: IconSource | null | undefined
+): ResolvedIcon | Promise<ResolvedIcon | null> | null {
+  if (!source) return null
+
+  if (typeof source !== 'string') {
+    return { kind: 'component', component: source }
+  }
+
+  const trimmed = source.trim()
+  if (!trimmed) return null
+
+  if (looksLikeSvg(trimmed)) {
+    return { kind: 'svg', markup: trimmed }
+  }
+
+  if (looksLikeImage(trimmed)) {
+    return { kind: 'image', src: trimmed }
+  }
+
+  const prefixed = parsePrefixedName(trimmed)
+  if (prefixed) {
+    const resolver = prefixResolvers.get(prefixed.prefix)
+    if (resolver) {
+      const outcome = resolver(prefixed.name)
+      if (isPromise<IconSource | null | undefined>(outcome)) {
+        return outcome.then(normalizeResolved)
+      }
+      return normalizeResolved(outcome)
+    }
+
+    if (prefixed.prefix === 'lucide') {
+      return lookupLucideIcon(prefixed.name).then((comp) => {
+        return comp ? { kind: 'component', component: comp } : null
+      })
+    }
+
+    if (defaultIconResolver) {
+      const outcome = defaultIconResolver(trimmed)
+      if (isPromise<IconSource | null | undefined>(outcome)) {
+        return outcome.then(normalizeResolved)
+      }
+      return normalizeResolved(outcome)
+    }
+
+    return null
+  }
+
+  if (defaultIconResolver) {
+    const outcome = defaultIconResolver(trimmed)
+    if (isPromise<IconSource | null | undefined>(outcome)) {
+      return outcome.then(normalizeResolved)
+    }
+    return normalizeResolved(outcome)
+  }
+
+  return lookupLucideIcon(trimmed).then((comp) => {
+    return comp ? { kind: 'component', component: comp } : null
+  })
+}
diff --git a/packages/ui/src/components/icon/types.ts b/packages/ui/src/components/icon/types.ts
new file mode 100644
index 0000000..e5adcb0
--- /dev/null
+++ b/packages/ui/src/components/icon/types.ts
@@ -0,0 +1,47 @@
+import type { Component } from 'vue'
+
+/**
+ * 支持的图标源类型：
+ * - Vue 组件（来自 `lucide-vue-next`、`@heroicons/vue` 或自定义 SVG 组件）
+ * - 字符串：
+ *   - 以 `<svg` 开头的内联 SVG 标记代码
+ *   - 图片路径或 URL（如 `/icon.svg`、`https://...`、`data:image/...`）
+ *   - 注册前缀名称（如 `lucide:settings`、`custom:logo`）
+ *   - 纯图标名称（通过默认解析器或内置 lucide 处理）
+ */
+export type IconSource = string | Component
+
+/**
+ * 已规范化为具体渲染形态的结构。
+ */
+export type ResolvedIcon =
+  | { kind: 'component'; component: Component }
+  | { kind: 'svg'; markup: string }
+  | { kind: 'image'; src: string }
+
+/**
+ * 图标解析器函数签名。
+ * 接收去除前缀后的名称（或无前缀时的完整名称），返回图标组件、SVG 代码、图片路径或其异步 Promise。
+ */
+export type IconResolver = (
+  name: string
+) => IconSource | null | undefined | Promise<IconSource | null | undefined>
+
+export interface IconProps {
+  /**
+   * 图标源：支持 Vue 组件、内联 SVG 字符串、图片 URL 或注册前缀名称。
+   */
+  icon?: IconSource
+
+  /**
+   * 图标尺寸，默认 `'1em'`。
+   * 传入数字时自动添加 `px`（例如 `16` -> `'16px'`）；传入字符串按 CSS 属性原样生效。
+   */
+  size?: number | string
+
+  /**
+   * 无障碍描述文本。
+   * 提供时赋予 `role="img"` 与 `aria-label`；缺省时应用 `aria-hidden="true"` 标记为装饰图标。
+   */
+  label?: string
+}
diff --git a/packages/ui/src/components/nav-tree/NavTree.vue b/packages/ui/src/components/nav-tree/NavTree.vue
index 353e3ce..b00f3ab 100644
--- a/packages/ui/src/components/nav-tree/NavTree.vue
+++ b/packages/ui/src/components/nav-tree/NavTree.vue
@@ -58,7 +58,7 @@
               ]"
             >
               <div class="flex items-center gap-2 truncate">
-                <component :is="item.icon" v-if="item.icon" class="h-3.5 w-3.5 shrink-0" />
+                <Icon :icon="item.icon" v-if="item.icon" size="0.875rem" />
                 <span class="truncate">{{ item.title }}</span>
               </div>
               <span
@@ -77,6 +77,7 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue'
+import { Icon } from '../icon'
 import { useComponentLocale } from '../../locale'
 import type { NavTreeGroup, NavTreeItem, NavTreeProps } from './types'
 
diff --git a/packages/ui/src/components/nav-tree/types.ts b/packages/ui/src/components/nav-tree/types.ts
index cb97d5d..f2aa57b 100644
--- a/packages/ui/src/components/nav-tree/types.ts
+++ b/packages/ui/src/components/nav-tree/types.ts
@@ -1,11 +1,11 @@
-import type { Component } from 'vue'
+import type { IconSource } from '../icon'
 
 export interface NavTreeItem {
   title: string
   href?: string
   to?: string
   badge?: string
-  icon?: Component
+  icon?: IconSource
   disabled?: boolean
 }
 
diff --git a/packages/ui/src/components/tabs/Tabs.vue b/packages/ui/src/components/tabs/Tabs.vue
index e643853..b04954f 100644
--- a/packages/ui/src/components/tabs/Tabs.vue
+++ b/packages/ui/src/components/tabs/Tabs.vue
@@ -12,7 +12,7 @@
         :disabled="tab.disabled"
         class="inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-xs font-medium text-slate-600 dark:text-slate-400 transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-white dark:data-[state=active]:bg-[#0F172A] data-[state=active]:text-slate-900 dark:data-[state=active]:text-slate-100 data-[state=active]:shadow-xs cursor-pointer select-none"
       >
-        <component :is="tab.icon" v-if="tab.icon" class="mr-1.5 h-3.5 w-3.5" />
+        <Icon :icon="tab.icon" v-if="tab.icon" size="0.875rem" class="mr-1.5" />
         {{ tab.label }}
       </TabsTrigger>
     </TabsList>
@@ -27,12 +27,13 @@ import {
   TabsList,
   TabsTrigger
 } from 'reka-ui'
+import { Icon, type IconSource } from '../icon'
 import { cn } from '../../utils/cn'
 
 export interface TabItem {
   label: string
   value: string
-  icon?: any
+  icon?: IconSource
   disabled?: boolean
 }
 
diff --git a/packages/ui/src/components/toggle-group/ToggleGroup.vue b/packages/ui/src/components/toggle-group/ToggleGroup.vue
index 7c07844..e9e69a7 100644
--- a/packages/ui/src/components/toggle-group/ToggleGroup.vue
+++ b/packages/ui/src/components/toggle-group/ToggleGroup.vue
@@ -15,7 +15,7 @@
       :title="opt.label"
       class="relative inline-flex h-10 flex-1 select-none items-center justify-center gap-1.5 rounded-md px-2.5 text-sm font-medium text-slate-600 transition-colors hover:bg-slate-100 hover:text-slate-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#2563EB] disabled:cursor-not-allowed disabled:opacity-50 data-[state=on]:bg-white data-[state=on]:text-slate-900 data-[state=on]:shadow-xs dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-200 dark:data-[state=on]:bg-slate-800 dark:data-[state=on]:text-white"
     >
-      <component :is="opt.icon" v-if="opt.icon" class="h-4 w-4" />
+      <Icon :icon="opt.icon" v-if="opt.icon" size="1rem" />
       <span>{{ opt.label }}</span>
     </ToggleGroupItem>
   </ToggleGroupRoot>
@@ -24,12 +24,13 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { ToggleGroupRoot, ToggleGroupItem } from 'reka-ui'
+import { Icon, type IconSource } from '../icon'
 import { cn } from '../../utils/cn'
 
 export interface ToggleGroupOption {
   label: string
   value: string
-  icon?: any
+  icon?: IconSource
   disabled?: boolean
 }
 
diff --git a/packages/ui/src/components/tree-view/TreeViewNode.vue b/packages/ui/src/components/tree-view/TreeViewNode.vue
index 7d94a0f..f8c48a9 100644
--- a/packages/ui/src/components/tree-view/TreeViewNode.vue
+++ b/packages/ui/src/components/tree-view/TreeViewNode.vue
@@ -75,7 +75,7 @@
       <!-- Icon slot / default icon -->
       <div v-if="$slots.icon || node.icon" class="flex shrink-0 items-center text-[var(--muted-foreground)]">
         <slot name="icon" :node="node" :expanded="expanded" :selected="selected">
-          <component :is="node.icon" class="size-4" />
+          <Icon :icon="node.icon" size="1rem" />
         </slot>
       </div>
 
@@ -140,6 +140,7 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue'
+import { Icon } from '../icon'
 import { cn } from '../../utils/cn'
 import { useComponentLocale } from '../../locale'
 import type { TreeHighlightVariant, TreeNode } from './types'
diff --git a/packages/ui/src/components/tree-view/types.ts b/packages/ui/src/components/tree-view/types.ts
index a191818..4e5c99f 100644
--- a/packages/ui/src/components/tree-view/types.ts
+++ b/packages/ui/src/components/tree-view/types.ts
@@ -1,4 +1,4 @@
-import type { Component } from 'vue'
+import type { IconSource } from '../icon'
 
 export interface TreeNode {
   id: string
@@ -7,8 +7,8 @@ export interface TreeNode {
   children?: TreeNode[]
   /** True when node has dynamic children that haven't been fetched yet. */
   isLeaf?: boolean
-  /** Optional icon component or icon name rendered before node label. */
-  icon?: Component
+  /** Optional icon component, icon name or SVG source rendered before node label. */
+  icon?: IconSource
 }
 
 export interface TreeDropEvent {
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 06d0754..6ff588b 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -69,6 +69,7 @@ export * from './components/code-group'
 export * from './components/navbar'
 export * from './components/footer'
 export * from './components/hero'
+export * from './components/icon'
 
 // Composables & Utilities
 export * from './composables/useTheme'

From ceb4fb2a29375c2fe8a6c4053189dfdcaeb058ed Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 08:24:46 +0800
Subject: [PATCH 25/26] fix(playground): import icon from
 @recloudstudio/ui/icons and clean test assertion

---
 apps/playground/pages/components/icon.vue                | 2 +-
 packages/ui/src/components/date-picker/dateUtils.test.ts | 6 +++++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/apps/playground/pages/components/icon.vue b/apps/playground/pages/components/icon.vue
index d98045e..3a4b121 100644
--- a/apps/playground/pages/components/icon.vue
+++ b/apps/playground/pages/components/icon.vue
@@ -136,7 +136,7 @@
 </template>
 
 <script setup lang="ts">
-import { Settings } from 'lucide-vue-next'
+import { Settings } from '@recloudstudio/ui/icons'
 import { registerIconResolver } from '@recloudstudio/ui'
 
 // 注册示范用前缀解析器
diff --git a/packages/ui/src/components/date-picker/dateUtils.test.ts b/packages/ui/src/components/date-picker/dateUtils.test.ts
index be435bc..b19c8ef 100644
--- a/packages/ui/src/components/date-picker/dateUtils.test.ts
+++ b/packages/ui/src/components/date-picker/dateUtils.test.ts
@@ -3,7 +3,11 @@ import { addMonths, monthDays, parseDateKey, toDateKey } from './dateUtils'
 
 describe('dateUtils', () => {
   it('parses only valid ISO date keys', () => {
-    expect(toDateKey(parseDateKey('2026-02-28')!)).toBe('2026-02-28')
+    const parsed = parseDateKey('2026-02-28')
+    expect(parsed).toBeDefined()
+    if (parsed) {
+      expect(toDateKey(parsed)).toBe('2026-02-28')
+    }
     expect(parseDateKey('2026-02-30')).toBeUndefined()
   })
 

From 22cd4ec127967d18ca45155024ff138a0f9b11aa Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 08:34:44 +0800
Subject: [PATCH 26/26] fix(playground): point icon demo NavTree links to real
 routes

---
 apps/playground/pages/components/icon.vue | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/apps/playground/pages/components/icon.vue b/apps/playground/pages/components/icon.vue
index 3a4b121..b330d41 100644
--- a/apps/playground/pages/components/icon.vue
+++ b/apps/playground/pages/components/icon.vue
@@ -129,7 +129,7 @@
       :code="integrationCode"
     >
       <div class="max-w-xs rounded-lg border border-slate-200 dark:border-slate-800 p-2 bg-white dark:bg-slate-950">
-        <NavTree :groups="sampleNavGroups" active-href="/pods" />
+        <NavTree :groups="sampleNavGroups" active-href="/components/button" />
       </div>
     </DocExample>
   </div>
@@ -154,11 +154,11 @@ const svgSnippet = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" s
 
 const sampleNavGroups = [
   {
-    title: '集群资源',
+    title: '示例导航',
     items: [
-      { title: 'Pods 实例', href: '/pods', icon: 'lucide:box' },
-      { title: '数据库服务', href: '/db', icon: 'cloud:database' },
-      { title: '路由网关', href: '/gateway', icon: 'lucide:network' }
+      { title: 'Button 按钮', href: '/components/button', icon: 'lucide:box' },
+      { title: 'Card 卡片', href: '/components/card', icon: 'cloud:database' },
+      { title: 'Dialog 对话框', href: '/components/dialog', icon: 'lucide:network' }
     ]
   }
 ]
@@ -224,12 +224,12 @@ const integrationCode = `<template>
   <!-- NavTree、TreeView、CommandPalette 等原生无缝接收统一 IconSource -->
   <NavTree :groups="[
     {
-      title: '集群资源',
+      title: '组件导航',
       items: [
-        { title: 'Pods 实例', href: '/pods', icon: 'lucide:box' },
-        { title: '数据库服务', href: '/db', icon: 'cloud:database' }
+        { title: 'Button 按钮', href: '/components/button', icon: 'lucide:box' },
+        { title: 'Card 卡片', href: '/components/card', icon: 'cloud:database' }
       ]
     }
-  ]" />
+  ]" active-href="/components/button" />
 </template>`
 </script>