From da825d256af96f0891b99d7fea68effc453ee3e0 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 21:41:53 +0800
Subject: [PATCH 01/17] feat(code-block): lazy loading, line numbers, a11y

Consolidate language metadata into a single registry with grammar loaders, load shiki grammars on demand with retryable failures, and keep the initial bundle free of grammar code.

Add an accessible scroll region with live copy announcements, gutter-based line numbers, collapse animation with reduced-motion support, and a scroll-aware fade for max-height limits.

Replace the removed languageIcons module with languages.ts and cover the registry and component contracts with vitest.
---
 .changeset/lazy-code-blocks-improve.md        |   5 +
 .../src/components/code-block/CodeBlock.vue   | 147 +++++------
 .../components/code-block/codeBlock.test.ts   |  52 ++++
 .../src/components/code-block/highlighter.ts  |  63 +++++
 .../ui/src/components/code-block/index.ts     |   7 +-
 .../code-block/languageIcons.test.ts          |  52 ----
 .../components/code-block/languageIcons.ts    | 126 ----------
 .../components/code-block/languages.test.ts   | 130 ++++++++++
 .../ui/src/components/code-block/languages.ts | 231 ++++++++++++++++++
 packages/ui/src/locale/messages.ts            |   9 +
 10 files changed, 570 insertions(+), 252 deletions(-)
 create mode 100644 .changeset/lazy-code-blocks-improve.md
 create mode 100644 packages/ui/src/components/code-block/codeBlock.test.ts
 create mode 100644 packages/ui/src/components/code-block/highlighter.ts
 delete mode 100644 packages/ui/src/components/code-block/languageIcons.test.ts
 delete mode 100644 packages/ui/src/components/code-block/languageIcons.ts
 create mode 100644 packages/ui/src/components/code-block/languages.test.ts
 create mode 100644 packages/ui/src/components/code-block/languages.ts

diff --git a/.changeset/lazy-code-blocks-improve.md b/.changeset/lazy-code-blocks-improve.md
new file mode 100644
index 0000000..62531bf
--- /dev/null
+++ b/.changeset/lazy-code-blocks-improve.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Expand CodeBlock language support with on-demand syntax loading, resilient retries, accessible scrolling, adaptive line numbers, and smoother collapsed and height-limited states.
diff --git a/packages/ui/src/components/code-block/CodeBlock.vue b/packages/ui/src/components/code-block/CodeBlock.vue
index 4fe5658..941b378 100644
--- a/packages/ui/src/components/code-block/CodeBlock.vue
+++ b/packages/ui/src/components/code-block/CodeBlock.vue
@@ -11,7 +11,7 @@
         <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="language" class="shrink-0 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>
       </component>
       <button
@@ -25,24 +25,35 @@
         <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 ? commonLoc.copied : commonLoc.copy }}
       </button>
+      <span v-if="copyable" class="sr-only" role="status" aria-live="polite">
+        {{ copied ? commonLoc.copied : '' }}
+      </span>
     </header>
 
-    <div
-      v-show="!isCollapsed"
-      :id="bodyId"
-      :class="contentClasses"
-      :style="maxHeight ? { maxHeight } : undefined"
-      v-html="renderedHtml"
-    />
+    <div :class="bodyWrapperClasses">
+      <div
+        :id="bodyId"
+        ref="contentElement"
+        :class="contentClasses"
+        :style="contentStyle"
+        :tabindex="isCollapsed ? -1 : 0"
+        role="region"
+        :aria-label="regionLabel"
+        :aria-hidden="isCollapsed || undefined"
+        @scroll.passive="syncBottomFade"
+        v-html="renderedHtml"
+      />
+    </div>
   </section>
 </template>
 
 <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 { computed, nextTick, onBeforeUnmount, onMounted, shallowRef, useId, watch } from 'vue'
 import { useComponentLocale } from '../../locale'
+import { cn } from '../../utils/cn'
+import { Icon } from '../icon'
+import { getCodeBlockHighlighter } from './highlighter'
+import { resolveCodeBlockGrammar, resolveCodeBlockIcon } from './languages'
 import type { CodeBlockProps } from './types'
 
 const props = withDefaults(defineProps<CodeBlockProps>(), {
@@ -61,27 +72,18 @@ 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 codeBlockLoc = useComponentLocale('codeBlock')
 
 const bodyId = useId()
 const copied = shallowRef(false)
+const contentElement = shallowRef<HTMLElement | null>(null)
+const showBottomFade = 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> = {
-  bash: 'shellscript',
-  js: 'javascript',
-  sh: 'shellscript',
-  shell: 'shellscript',
-  ts: 'typescript'
-}
-const supportedLanguages = new Set(['css', 'html', 'javascript', 'json', 'log', 'shellscript', 'typescript', 'vue', 'vue-html'])
-/** A Vue SFC has at least one top-level block; anything else is a template fragment. */
-const SFC_BLOCK_RE = /^<(template|script|style)[\s>]/m
 /**
  * Component-owned class for the rendered <pre>. Shiki's default `shiki` class is replaced so
  * host-app global rules (e.g. `pre.shiki { background: ... !important }`) cannot override it.
@@ -92,11 +94,20 @@ const isCollapsed = computed(() => props.collapsible && collapsed.value)
 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 regionLabel = computed(() => props.filename || props.language || codeBlockLoc.value.region)
 
 const headerClasses = computed(() => {
   return cn(
-    'flex min-h-10 items-center justify-between gap-3 px-3.5',
-    !isCollapsed.value && 'border-b border-[var(--code-border)]'
+    'flex min-h-10 items-center justify-between gap-3 border-b px-3.5',
+    isCollapsed.value ? 'border-transparent' : 'border-[var(--code-border)]'
+  )
+})
+
+const bodyWrapperClasses = computed(() => {
+  if (!props.collapsible) return undefined
+  return cn(
+    'grid overflow-hidden transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none',
+    isCollapsed.value ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]'
   )
 })
 
@@ -130,10 +141,22 @@ const contentClasses = computed(() => {
       ? '[&>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-[var(--code-muted)] [&_.line]:before:select-none [&_.line]:before:[counter-increment:line] [&_.line]:before:content-[counter(line)]'
+      '[&>pre]:[counter-reset:line] [&>pre]:[padding-left:calc(2rem+var(--rc-ln-w))] [&_.line]:relative [&_.line]:before:absolute [&_.line]:before:left-[calc(-1*(var(--rc-ln-w)+1rem))] [&_.line]:before:w-[var(--rc-ln-w)] [&_.line]:before:text-right [&_.line]:before:text-[var(--code-muted)] [&_.line]:before:select-none [&_.line]:before:[counter-increment:line] [&_.line]:before:content-[counter(line)]',
+    showBottomFade.value &&
+      '[mask-image:linear-gradient(to_bottom,#000_calc(100%_-_2.5rem),transparent)]'
   )
 })
 
+const contentStyle = computed(() => {
+  const style: Record<string, string> = {}
+  if (props.maxHeight) style.maxHeight = props.maxHeight
+  if (props.showLineNumbers) {
+    const digits = String(props.code.split('\n').length).length
+    style['--rc-ln-w'] = `max(1.5rem, ${digits}ch)`
+  }
+  return Object.keys(style).length ? style : undefined
+})
+
 /** Show raw escaped code (same line structure as Shiki) while the highlighter loads or on error. */
 const fallbackHtml = computed(() => {
   const lines = props.code.split('\n').map((line) => `<span class="line">${escapeHtml(line)}</span>`)
@@ -149,6 +172,25 @@ function toggleCollapsed() {
   if (props.collapsible) collapsed.value = !collapsed.value
 }
 
+function syncBottomFade() {
+  const element = contentElement.value
+  showBottomFade.value = Boolean(
+    props.maxHeight &&
+      !isCollapsed.value &&
+      element &&
+      element.scrollHeight - element.scrollTop - element.clientHeight > 4
+  )
+}
+
+watch(
+  [renderedHtml, isCollapsed, () => props.maxHeight],
+  async () => {
+    await nextTick()
+    syncBottomFade()
+  },
+  { flush: 'post' }
+)
+
 onMounted(() => {
   const root = document.documentElement
   const updateColorTheme = () => {
@@ -156,6 +198,7 @@ onMounted(() => {
   }
 
   updateColorTheme()
+  syncBottomFade()
   themeObserver = new MutationObserver(updateColorTheme)
   themeObserver.observe(root, { attributes: true, attributeFilter: ['data-theme'] })
 })
@@ -180,50 +223,6 @@ async function copyCode() {
   }
 }
 
-async function createHighlighter() {
-  const [
-    { createHighlighterCore },
-    { createJavaScriptRegexEngine },
-    { 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'),
-    import('shiki/dist/langs/json.mjs'),
-    import('shiki/dist/langs/log.mjs'),
-    import('shiki/dist/langs/shellscript.mjs'),
-    import('shiki/dist/langs/typescript.mjs'),
-    import('shiki/dist/langs/vue.mjs'),
-    import('shiki/dist/langs/vue-html.mjs')
-  ])
-
-  return createHighlighterCore({
-    themes: [darkTheme, lightTheme],
-    langs: languages.map(({ default: lang }) => lang),
-    engine: createJavaScriptRegexEngine()
-  })
-}
-
-function getHighlighter() {
-  highlighterPromise ??= createHighlighter()
-  return highlighterPromise
-}
-
-function resolveLanguage(language: string, code: string) {
-  const normalized = languageAliases[language.toLowerCase()] ?? language.toLowerCase()
-  if (!supportedLanguages.has(normalized)) return 'log'
-  // The `vue` grammar only tokenizes inside SFC blocks; bare template snippets
-  // (e.g. `<div><Button v-model="x" /></div>`) need the template grammar instead.
-  if (normalized === 'vue' && !SFC_BLOCK_RE.test(code)) return 'vue-html'
-  return normalized
-}
-
 watch(
   [sourceKey, isCollapsed],
   async ([key, hidden]) => {
@@ -231,16 +230,18 @@ watch(
     if (hidden || highlighted.value?.key === key) return
     const version = ++highlightVersion
     try {
-      const highlighter = await getHighlighter()
+      const grammar = resolveCodeBlockGrammar(props.language, props.code)
+      const highlighter = await getCodeBlockHighlighter(grammar)
       // Guard against stale async results when props changed during await.
       if (version !== highlightVersion) return
       const html = highlighter.codeToHtml(props.code, {
-        lang: resolveLanguage(props.language, props.code),
+        lang: grammar,
         theme: colorTheme.value,
         transformers: [
           {
             pre(node) {
               node.properties.class = PRE_CLASS
+              delete node.properties.tabindex
             }
           }
         ]
diff --git a/packages/ui/src/components/code-block/codeBlock.test.ts b/packages/ui/src/components/code-block/codeBlock.test.ts
new file mode 100644
index 0000000..387a73f
--- /dev/null
+++ b/packages/ui/src/components/code-block/codeBlock.test.ts
@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(fileURLToPath(new URL('./CodeBlock.vue', import.meta.url)), 'utf8')
+const highlighter = readFileSync(
+  fileURLToPath(new URL('./highlighter.ts', import.meta.url)),
+  'utf8'
+)
+
+describe('CodeBlock component contract', () => {
+  it('keeps the actual scrolling region keyboard and screen-reader accessible', () => {
+    expect(source).toContain(':tabindex="isCollapsed ? -1 : 0"')
+    expect(source).toContain('role="region"')
+    expect(source).toContain(':aria-label="regionLabel"')
+    expect(source).toContain(':aria-hidden="isCollapsed || undefined"')
+    expect(source).toContain('role="status" aria-live="polite"')
+    expect(source).toContain('delete node.properties.tabindex')
+  })
+
+  it('uses adaptive line-number gutters that keep wrapped continuations out of the gutter', () => {
+    expect(source).toContain('[padding-left:calc(2rem+var(--rc-ln-w))]')
+    expect(source).toContain('[&_.line]:relative')
+    expect(source).toContain('before:left-[calc(-1*(var(--rc-ln-w)+1rem))]')
+    expect(source).toContain("style['--rc-ln-w']")
+    expect(source).toContain('max(1.5rem, ')
+  })
+
+  it('animates collapsible content without moving the header border', () => {
+    expect(source).toContain('border-b px-3.5')
+    expect(source).toContain("isCollapsed.value ? 'border-transparent'")
+    expect(source).toContain("isCollapsed.value ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]'")
+    expect(source).toContain('transition-[grid-template-rows]')
+    expect(source).not.toContain('v-show="!isCollapsed"')
+  })
+
+  it('shows a scroll-aware fade only while max-height content remains below', () => {
+    expect(source).toContain('@scroll.passive="syncBottomFade"')
+    expect(source).toContain('element.scrollHeight - element.scrollTop - element.clientHeight > 4')
+    expect(source).toContain(
+      '[mask-image:linear-gradient(to_bottom,#000_calc(100%_-_2.5rem),transparent)]'
+    )
+  })
+
+  it('loads the core and individual grammars lazily with retryable caches', () => {
+    expect(highlighter).toContain('langs: []')
+    expect(highlighter).toContain('loadCodeBlockGrammar(grammar)')
+    expect(highlighter).toContain('highlighter.loadLanguage(language)')
+    expect(highlighter).toContain('highlighterPromise = undefined')
+    expect(highlighter).toContain('grammarPromises.delete(grammar)')
+  })
+})
diff --git a/packages/ui/src/components/code-block/highlighter.ts b/packages/ui/src/components/code-block/highlighter.ts
new file mode 100644
index 0000000..b546834
--- /dev/null
+++ b/packages/ui/src/components/code-block/highlighter.ts
@@ -0,0 +1,63 @@
+import type { HighlighterCore } from 'shiki/core'
+
+import { loadCodeBlockGrammar } from './languages'
+
+let highlighterPromise: Promise<HighlighterCore> | undefined
+const grammarPromises = new Map<string, Promise<void>>()
+
+const createHighlighter = async (): Promise<HighlighterCore> => {
+  const [
+    { createHighlighterCore },
+    { createJavaScriptRegexEngine },
+    { default: darkTheme },
+    { default: lightTheme }
+  ] = await Promise.all([
+    import('shiki/core'),
+    import('shiki/engine/javascript'),
+    import('shiki/dist/themes/github-dark.mjs'),
+    import('shiki/dist/themes/github-light.mjs')
+  ])
+
+  return createHighlighterCore({
+    themes: [darkTheme, lightTheme],
+    langs: [],
+    engine: createJavaScriptRegexEngine()
+  })
+}
+
+const getHighlighter = (): Promise<HighlighterCore> => {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter().catch((error: unknown) => {
+      highlighterPromise = undefined
+      grammarPromises.clear()
+      throw error
+    })
+  }
+  return highlighterPromise
+}
+
+const loadGrammar = (grammar: string): Promise<void> => {
+  const existing = grammarPromises.get(grammar)
+  if (existing) return existing
+
+  const promise = getHighlighter().then(async (highlighter) => {
+    if (highlighter.getLoadedLanguages().includes(grammar)) return
+
+    const language = loadCodeBlockGrammar(grammar)
+    if (!language) throw new Error(`Unsupported CodeBlock grammar: ${grammar}`)
+    await highlighter.loadLanguage(language)
+  })
+
+  grammarPromises.set(grammar, promise)
+  promise.catch(() => {
+    if (grammarPromises.get(grammar) === promise) grammarPromises.delete(grammar)
+  })
+  return promise
+}
+
+/** Return the shared highlighter after its requested grammar has loaded. */
+export const getCodeBlockHighlighter = async (grammar: string): Promise<HighlighterCore> => {
+  const highlighter = await getHighlighter()
+  await loadGrammar(grammar)
+  return highlighter
+}
diff --git a/packages/ui/src/components/code-block/index.ts b/packages/ui/src/components/code-block/index.ts
index bed1425..45a7aa2 100644
--- a/packages/ui/src/components/code-block/index.ts
+++ b/packages/ui/src/components/code-block/index.ts
@@ -1,3 +1,8 @@
 export { default as CodeBlock } from './CodeBlock.vue'
 export type { CodeBlockProps } from './types'
-export * from './languageIcons'
+export {
+  DEFAULT_CODE_ICON,
+  LANGUAGE_ICONS,
+  extractExtension,
+  resolveCodeBlockIcon
+} from './languages'
diff --git a/packages/ui/src/components/code-block/languageIcons.test.ts b/packages/ui/src/components/code-block/languageIcons.test.ts
deleted file mode 100644
index 389cd0f..0000000
--- a/packages/ui/src/components/code-block/languageIcons.test.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-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
deleted file mode 100644
index 81db0ad..0000000
--- a/packages/ui/src/components/code-block/languageIcons.ts
+++ /dev/null
@@ -1,126 +0,0 @@
-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/languages.test.ts b/packages/ui/src/components/code-block/languages.test.ts
new file mode 100644
index 0000000..26c9126
--- /dev/null
+++ b/packages/ui/src/components/code-block/languages.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest'
+import {
+  CODE_BLOCK_GRAMMARS,
+  CODE_BLOCK_GRAMMAR_IDS,
+  DEFAULT_CODE_ICON,
+  loadCodeBlockGrammar,
+  LANGUAGE_ICONS,
+  extractExtension,
+  resolveCodeBlockGrammar,
+  resolveCodeBlockIcon
+} from './languages'
+
+const LEGACY_LANGUAGE_KEYS = [
+  'bash',
+  'css',
+  'docker',
+  'dockerfile',
+  'go',
+  'golang',
+  'html',
+  'javascript',
+  'js',
+  'json',
+  'jsx',
+  'log',
+  'markdown',
+  'md',
+  'py',
+  'python',
+  'rs',
+  'rust',
+  'sh',
+  'shell',
+  'shellscript',
+  'sql',
+  'toml',
+  'ts',
+  'tsx',
+  'typescript',
+  'vue',
+  'vue-html',
+  'yaml',
+  'yml',
+  'zsh'
+]
+
+describe('CodeBlock languages', () => {
+  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 from canonical ids and aliases', () => {
+    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 from filename extensions when language is absent', () => {
+    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', () => {
+    expect(resolveCodeBlockIcon(false, 'ts', 'main.ts')).toBeNull()
+
+    const customIcon = 'lucide:file-code'
+    expect(resolveCodeBlockIcon(customIcon, 'ts', 'main.ts')).toBe(customIcon)
+
+    expect(resolveCodeBlockIcon(true, 'unknown-lang-xyz', 'data.unknown')).toBe(
+      DEFAULT_CODE_ICON
+    )
+    expect(resolveCodeBlockIcon(undefined, 'unknown-lang-xyz', 'data.unknown')).toBeNull()
+  })
+
+  it('resolves aliases, Vue snippets and unknown languages to loadable grammars', () => {
+    expect(resolveCodeBlockGrammar('ts', 'const value = 1')).toBe('typescript')
+    expect(resolveCodeBlockGrammar('bash', 'echo hello')).toBe('shellscript')
+    expect(resolveCodeBlockGrammar('dockerfile', 'FROM oven/bun')).toBe('docker')
+    expect(resolveCodeBlockGrammar('vue', '<template><div /></template>')).toBe('vue')
+    expect(resolveCodeBlockGrammar('vue', '<div><Button /></div>')).toBe('vue-html')
+    expect(resolveCodeBlockGrammar('unknown', 'plain text')).toBe('log')
+    expect(resolveCodeBlockGrammar('', 'plain text')).toBe('log')
+  })
+
+  it('keeps every registered grammar paired with exactly one lazy loader', () => {
+    expect([...CODE_BLOCK_GRAMMARS].sort()).toEqual([...CODE_BLOCK_GRAMMAR_IDS].sort())
+  })
+
+  it('loads a registered grammar in the format accepted by shiki', async () => {
+    const language = loadCodeBlockGrammar('python')
+    expect(language).not.toBeNull()
+    if (!language) throw new Error('Python grammar loader is missing')
+
+    const { createHighlighterCore } = await import('shiki/core')
+    const { createJavaScriptRegexEngine } = await import('shiki/engine/javascript')
+    const highlighter = await createHighlighterCore({
+      themes: [],
+      langs: [],
+      engine: createJavaScriptRegexEngine()
+    })
+    await highlighter.loadLanguage(language)
+
+    expect(highlighter.getLoadedLanguages()).toEqual(expect.arrayContaining(['python', 'py']))
+  })
+
+  it('preserves every previously published language icon key', () => {
+    expect(Object.keys(LANGUAGE_ICONS)).toEqual(expect.arrayContaining(LEGACY_LANGUAGE_KEYS))
+  })
+})
diff --git a/packages/ui/src/components/code-block/languages.ts b/packages/ui/src/components/code-block/languages.ts
new file mode 100644
index 0000000..4c4ebba
--- /dev/null
+++ b/packages/ui/src/components/code-block/languages.ts
@@ -0,0 +1,231 @@
+import type { LanguageInput } from 'shiki/core'
+
+import type { IconSource } from '../icon'
+
+/* -------------------------------------------------------------------------- */
+/* Inline SVG icons                                                            */
+/* -------------------------------------------------------------------------- */
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+const ICON_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>`
+
+/** Generic fallback shown when `icon` is `true` but no language can be matched. */
+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>`
+
+/* -------------------------------------------------------------------------- */
+/* Single language registry                                                    */
+/* -------------------------------------------------------------------------- */
+
+interface CodeBlockLanguage {
+  /** shiki grammar id; this is the grammar actually loaded for the language. */
+  grammar: string
+  /** Inline SVG markup rendered in the header. */
+  icon: string
+  /** Additional spellings accepted by the `language` prop and by file extensions. */
+  aliases?: readonly string[]
+}
+
+/**
+ * The single source of truth for CodeBlock languages. Because an entry owns its icon,
+ * its shiki grammar and every accepted spelling, a language can never be advertised
+ * with an icon that the highlighter cannot back up.
+ */
+const LANGUAGES: Record<string, CodeBlockLanguage> = {
+  css: { grammar: 'css', icon: ICON_CSS },
+  docker: { grammar: 'docker', icon: ICON_DOCKER, aliases: ['dockerfile'] },
+  go: { grammar: 'go', icon: ICON_GO, aliases: ['golang'] },
+  html: { grammar: 'html', icon: ICON_HTML },
+  javascript: { grammar: 'javascript', icon: ICON_JAVASCRIPT, aliases: ['cjs', 'js', 'mjs'] },
+  json: { grammar: 'json', icon: ICON_JSON },
+  jsx: { grammar: 'jsx', icon: ICON_JAVASCRIPT },
+  log: { grammar: 'log', icon: ICON_LOG },
+  markdown: { grammar: 'markdown', icon: ICON_MARKDOWN, aliases: ['md'] },
+  python: { grammar: 'python', icon: ICON_PYTHON, aliases: ['py'] },
+  rust: { grammar: 'rust', icon: ICON_RUST, aliases: ['rs'] },
+  shellscript: {
+    grammar: 'shellscript',
+    icon: ICON_SHELL,
+    aliases: ['bash', 'sh', 'shell', 'zsh']
+  },
+  sql: { grammar: 'sql', icon: ICON_SQL },
+  toml: { grammar: 'toml', icon: ICON_TOML },
+  tsx: { grammar: 'tsx', icon: ICON_TYPESCRIPT },
+  typescript: {
+    grammar: 'typescript',
+    icon: ICON_TYPESCRIPT,
+    aliases: ['cts', 'mts', 'ts']
+  },
+  vue: { grammar: 'vue', icon: ICON_VUE },
+  'vue-html': { grammar: 'vue-html', icon: ICON_VUE },
+  yaml: { grammar: 'yaml', icon: ICON_YAML, aliases: ['yml'] },
+}
+
+/** Every spelling (canonical id plus aliases) mapped to its canonical language id. */
+const LANGUAGE_INDEX: Record<string, string> = {}
+
+/** Every spelling mapped to its header icon, derived from `LANGUAGES` so it cannot drift. */
+const LANGUAGE_ICON_INDEX: Record<string, string> = {}
+
+Object.entries(LANGUAGES).forEach(([id, entry]) => {
+  const spellings = [id, ...(entry.aliases ?? [])]
+  spellings.forEach((spelling) => {
+    LANGUAGE_INDEX[spelling] = id
+    LANGUAGE_ICON_INDEX[spelling] = entry.icon
+  })
+})
+
+/**
+ * Language and file-extension to built-in SVG icon lookup, covering every canonical
+ * id and every alias of the registry.
+ */
+export const LANGUAGE_ICONS: Record<string, string> = LANGUAGE_ICON_INDEX
+
+/** Grammar ids referenced by the registry; kept in sync with `GRAMMAR_LOADERS` by tests. */
+export const CODE_BLOCK_GRAMMARS: readonly string[] = [
+  ...new Set(Object.values(LANGUAGES).map((entry) => entry.grammar))
+]
+
+/* -------------------------------------------------------------------------- */
+/* Resolvers                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const SFC_BLOCK_RE = /^<(template|script|style)[\s>]/m
+
+/** Normalize a spelling, returning `''` when nothing usable was provided. */
+const normalizeSpelling = (value: string | undefined): string => value?.trim().toLowerCase() ?? ''
+
+/** Resolve an arbitrary spelling to its canonical language id, or `null` when unknown. */
+const canonicalLanguage = (value: string | undefined): string | null => {
+  const spelling = normalizeSpelling(value)
+  return LANGUAGE_INDEX[spelling] ?? null
+}
+
+/** Look up the icon for a spelling, or `null` when the language is unknown. */
+const lookupIcon = (value: string | undefined): string | null => {
+  const spelling = normalizeSpelling(value)
+  if (!spelling) return null
+  return LANGUAGE_ICON_INDEX[spelling] ?? null
+}
+
+/**
+ * Extract a lowercase file extension without the leading dot.
+ * `App.vue` -> `vue`, `config.test.ts` -> `ts`, `Dockerfile` -> `dockerfile`.
+ */
+export const 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)
+}
+
+/**
+ * Resolve the header icon from an explicit `icon` prop, the `language` prop or the
+ * `filename` extension, in that order.
+ */
+export const resolveCodeBlockIcon = (
+  explicitIcon: IconSource | boolean | undefined,
+  language: string | undefined,
+  filename: string | undefined
+): IconSource | null => {
+  // Explicitly disabled.
+  if (explicitIcon === false) return null
+
+  // An explicit icon source always wins.
+  if (explicitIcon && typeof explicitIcon !== 'boolean') return explicitIcon
+
+  const extension = filename ? extractExtension(filename) : ''
+  const icon = lookupIcon(language) ?? lookupIcon(extension)
+  if (icon) return icon
+
+  // `icon: true` promises an icon even when the language stays unknown.
+  if (explicitIcon === true) return DEFAULT_CODE_ICON
+
+  return null
+}
+
+/**
+ * Resolve the shiki grammar for a `language` value and code snippet.
+ * Unknown languages fall back to `log` instead of guessing a highlighter they cannot load.
+ */
+export const resolveCodeBlockGrammar = (language: string | undefined, code: string): string => {
+  const canonical = canonicalLanguage(language)
+  if (!canonical) return 'log'
+  // The `vue` grammar only tokenizes inside SFC blocks; bare template snippets
+  // (e.g. `<div><Button v-model="x" /></div>`) need the template grammar instead.
+  if (canonical === 'vue' && !SFC_BLOCK_RE.test(code)) return 'vue-html'
+  return LANGUAGES[canonical].grammar
+}
+
+/* -------------------------------------------------------------------------- */
+/* shiki grammar loading                                                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Lazy loaders for every grammar the registry can resolve. Kept in sync with
+ * `LANGUAGES` by `languages.test.ts`.
+ */
+const GRAMMAR_LOADERS: Record<string, () => LanguageInput> = {
+  css: () => import('shiki/dist/langs/css.mjs'),
+  docker: () => import('shiki/dist/langs/docker.mjs'),
+  go: () => import('shiki/dist/langs/go.mjs'),
+  html: () => import('shiki/dist/langs/html.mjs'),
+  javascript: () => import('shiki/dist/langs/javascript.mjs'),
+  json: () => import('shiki/dist/langs/json.mjs'),
+  jsx: () => import('shiki/dist/langs/jsx.mjs'),
+  log: () => import('shiki/dist/langs/log.mjs'),
+  markdown: () => import('shiki/dist/langs/markdown.mjs'),
+  python: () => import('shiki/dist/langs/python.mjs'),
+  rust: () => import('shiki/dist/langs/rust.mjs'),
+  shellscript: () => import('shiki/dist/langs/shellscript.mjs'),
+  sql: () => import('shiki/dist/langs/sql.mjs'),
+  toml: () => import('shiki/dist/langs/toml.mjs'),
+  tsx: () => import('shiki/dist/langs/tsx.mjs'),
+  typescript: () => import('shiki/dist/langs/typescript.mjs'),
+  vue: () => import('shiki/dist/langs/vue.mjs'),
+  'vue-html': () => import('shiki/dist/langs/vue-html.mjs'),
+  yaml: () => import('shiki/dist/langs/yaml.mjs'),
+}
+
+/** Grammar ids covered by `GRAMMAR_LOADERS`, exported so tests can assert full coverage. */
+export const CODE_BLOCK_GRAMMAR_IDS: readonly string[] = Object.keys(GRAMMAR_LOADERS)
+
+/**
+ * Import a single shiki grammar on demand. Returns `null` for an unknown grammar;
+ * callers cache the promise so each grammar is fetched at most once per session.
+ */
+export const loadCodeBlockGrammar = (grammar: string): LanguageInput | null => {
+  const loader = GRAMMAR_LOADERS[grammar]
+  return loader ? loader() : null
+}
diff --git a/packages/ui/src/locale/messages.ts b/packages/ui/src/locale/messages.ts
index 120f387..d374d90 100644
--- a/packages/ui/src/locale/messages.ts
+++ b/packages/ui/src/locale/messages.ts
@@ -94,6 +94,9 @@ export interface LocaleMessages {
     confirm: string
     cancel: string
   }
+  codeBlock: {
+    region: string
+  }
   docs: {
     toc: string
     prev: string
@@ -208,6 +211,9 @@ export const zhCN: LocaleMessages = {
     confirm: '确认',
     cancel: '取消'
   },
+  codeBlock: {
+    region: '代码区域'
+  },
   docs: {
     toc: '本页目录',
     prev: '上一篇',
@@ -314,6 +320,9 @@ export const enUS: LocaleMessages = {
     confirm: 'Confirm',
     cancel: 'Cancel'
   },
+  codeBlock: {
+    region: 'Code region'
+  },
   docs: {
     toc: 'On this page',
     prev: 'Previous',

From 58ff2ac77667e4fd83734070663ebe6bf87f4b5a Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 21:42:03 +0800
Subject: [PATCH 02/17] refactor(playground): use stock CodeBlock for examples

Stop stripping CodeBlock chrome in DocExample so example panels match the built-in component look (border, shadow, radius), expand them by default, and infer ts for module-style snippets.

Replace the hand-written code panels in the code-group and resizable-panel demos with CodeBlock.

Playground-only change; no consumer-visible package output.
---
 apps/playground/components/DocExample.vue     | 19 ++++---------
 .../pages/components/code-group.vue           | 28 +++++++++----------
 .../pages/components/resizable-panel.vue      |  9 +++---
 3 files changed, 23 insertions(+), 33 deletions(-)

diff --git a/apps/playground/components/DocExample.vue b/apps/playground/components/DocExample.vue
index 582cdd8..7b23fad 100644
--- a/apps/playground/components/DocExample.vue
+++ b/apps/playground/components/DocExample.vue
@@ -16,25 +16,15 @@
           <slot />
         </div>
       </div>
-
-      <CodeBlock
-        v-if="props.code"
-        v-model:collapsed="codeCollapsed"
-        collapsible
-        :code="props.code"
-        :language="codeLanguage"
-        class="rounded-t-none rounded-b-xl border-x-0 border-b-0 shadow-none"
-      />
     </div>
 
-    <!-- Code-only examples skip the empty preview area. -->
+    <!-- Code panels use the stock CodeBlock look (border, shadow, rounded, collapsible). -->
     <CodeBlock
-      v-else-if="props.code"
+      v-if="props.code"
       v-model:collapsed="codeCollapsed"
       collapsible
       :code="props.code"
       :language="codeLanguage"
-      class="shadow-none"
     />
   </section>
 </template>
@@ -47,7 +37,7 @@ export interface DocExampleProps {
   description?: string
   code?: string
   badge?: string
-  /** Show the code expanded on first render. */
+  /** Show the code expanded on first render (default). */
   expanded?: boolean
 }
 
@@ -56,7 +46,7 @@ const props = withDefaults(defineProps<DocExampleProps>(), {
   description: '',
   code: '',
   badge: '',
-  expanded: false
+  expanded: true
 })
 
 const codeCollapsed = ref(!props.expanded)
@@ -67,6 +57,7 @@ const codeLanguage = computed(() => {
   const first = code.trimStart().slice(0, 40)
   if (/^(# |npm |bun |pnpm |yarn |npx )/.test(first)) return 'bash'
   if (/^\/\//.test(first) && /defineNuxtConfig|export default/.test(code)) return 'ts'
+  if (/^(import |export |const |let |function |interface |type |async )/.test(first)) return 'ts'
   if (/^[{[]/.test(first)) return 'json'
   return 'vue'
 })
diff --git a/apps/playground/pages/components/code-group.vue b/apps/playground/pages/components/code-group.vue
index bb9c7e0..8d92e8b 100644
--- a/apps/playground/pages/components/code-group.vue
+++ b/apps/playground/pages/components/code-group.vue
@@ -5,18 +5,11 @@
     <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>
+          <CodeBlock
+            :code="pmCommands[activePm] ?? ''"
+            language="bash"
+            class="rounded-none border-x-0 border-b-0 shadow-none"
+          />
         </CodeGroup>
       </div>
     </DocExample>
@@ -31,10 +24,15 @@ import { ref } from 'vue'
 
 const activePm = ref('bun')
 
+const pmCommands: Record<string, string> = {
+  bun: 'bun add @recloudstudio/ui',
+  pnpm: 'pnpm add @recloudstudio/ui',
+  npm: 'npm install @recloudstudio/ui',
+  yarn: 'yarn add @recloudstudio/ui'
+}
+
 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>
-  ...
+<CodeBlock :code="pmCommands[activePm]" language="bash" />
 </CodeGroup>`
 
 const apiRows = [
diff --git a/apps/playground/pages/components/resizable-panel.vue b/apps/playground/pages/components/resizable-panel.vue
index b26c473..83f337c 100644
--- a/apps/playground/pages/components/resizable-panel.vue
+++ b/apps/playground/pages/components/resizable-panel.vue
@@ -5,10 +5,7 @@
     <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>
+        <template #second><div class="flex h-full flex-col bg-white p-5 dark:bg-[#0F172A]"><p class="text-xs font-semibold uppercase tracking-wider text-slate-500">部署日志</p><CodeBlock :code="deployLog" language="log" filename="deploy.log" :icon="false" max-height="11rem" class="mt-4 flex-1" /><p class="mt-3 text-xs text-slate-500">左侧宽度：{{ panelSize }}px</p></div></template>
       </ResizablePanel>
     </DocExample>
 
@@ -21,6 +18,10 @@
 import { ref } from 'vue'
 const panelSize = ref(240)
 const resources = ['production', 'staging', 'preview-482']
+const deployLog = `$ deploy production
+✓ Building image
+✓ Migrating database
+✓ Service healthy`
 const rcCode0 = `<ResizablePanel v-model="sidebarWidth" :min="160" :max="480">
   <template #first><ResourceSidebar /></template>
   <template #second><LogViewer /></template>

From 2cdcdfa529bc4e31302a2d9de18829e2856a1846 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 21:42:11 +0800
Subject: [PATCH 03/17] build(dev): serve playground from library source

Point the playground at packages/ui/src during nuxt dev via vite aliases and a source-loaded Nuxt module, with ssr.noExternal so the server shares the same module graph. The module now probes for ../index.ts when resolving the library entry, keeping dist behavior intact for published consumers.

Drop the ^build prerequisite from the turbo dev task and scope the root dev script to the playground. bun run dev now starts in about 13 seconds and library edits hot-update the playground directly. Production builds and generate still consume dist unchanged.
---
 apps/playground/nuxt.config.ts | 30 ++++++++++++++++++++++++++++--
 package.json                   |  2 +-
 packages/ui/src/nuxt/index.ts  |  5 ++++-
 turbo.json                     |  1 -
 4 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/apps/playground/nuxt.config.ts b/apps/playground/nuxt.config.ts
index ee77171..a778484 100644
--- a/apps/playground/nuxt.config.ts
+++ b/apps/playground/nuxt.config.ts
@@ -1,13 +1,26 @@
+import { fileURLToPath } from 'node:url'
 import { defineNuxtConfig } from 'nuxt/config'
 import tailwindcss from '@tailwindcss/vite'
 import { createThemeInitScript } from '../../packages/ui/src/utils/themeScript'
 
+// Dev 直连源码：模块、组件、组合式函数与图标都指向 packages/ui/src，
+// 源码改动即时 HMR，无需先构建 dist。生产构建仍消费 dist（与发布产物一致）。
+const isDev = process.env.NODE_ENV === 'development'
+const uiSrc = (path: string) =>
+  fileURLToPath(new URL(`../../packages/ui/src/${path}`, import.meta.url))
+
 export default defineNuxtConfig({
   // 固定 buildDir：Nuxt 4 生产构建会在 .nuxt 已存在时自动切到 node_modules/.cache，
   // 导致 tsconfig extends 在干净环境（CI/Pages）与本地行为不一致
   buildDir: '.nuxt',
   css: ['~/src/style.css'],
-  modules: [['@recloudstudio/ui/nuxt', { prefix: '', injectTheme: false }]],
+  modules: [
+    [
+      // Dev 加载 Nuxt 模块源码，组件自动注册随之指向 packages/ui/src。
+      isDev ? uiSrc('nuxt/index.ts') : '@recloudstudio/ui/nuxt',
+      { prefix: '', injectTheme: false }
+    ]
+  ],
   app: {
     head: {
       title: 'ReCloud UI · ReCloud Studio 设计系统',
@@ -31,7 +44,20 @@ export default defineNuxtConfig({
     }
   },
   vite: {
-    plugins: [tailwindcss()]
+    plugins: [tailwindcss()],
+    ...(isDev
+      ? {
+          resolve: {
+            // 子路径必须排在包名之前：字符串别名按前缀匹配，顺序即优先级。
+            alias: {
+              '@recloudstudio/ui/icons': uiSrc('icons/index.ts'),
+              '@recloudstudio/ui': uiSrc('index.ts')
+            }
+          },
+          // Dev 下 SSR 同样走源码，避免服务端 external 到 dist 造成双实例。
+          ssr: { noExternal: [/^@recloudstudio\/ui(\/.*)?$/] }
+        }
+      : {})
   },
   devtools: { enabled: true },
   runtimeConfig: {
diff --git a/package.json b/package.json
index 6f90487..6d3a2e9 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,7 @@
   "scripts": {
     "build": "bunx turbo run build",
     "generate": "bunx turbo run generate --filter=playground",
-    "dev": "bunx turbo run dev",
+    "dev": "bunx turbo run dev --filter=playground",
     "typecheck": "bunx turbo run typecheck",
     "test": "bunx turbo run test",
     "lint": "biome lint apps packages .github .changeset package.json turbo.json biome.json tsconfig.json",
diff --git a/packages/ui/src/nuxt/index.ts b/packages/ui/src/nuxt/index.ts
index 8d9bd8c..cc1986a 100644
--- a/packages/ui/src/nuxt/index.ts
+++ b/packages/ui/src/nuxt/index.ts
@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs'
 import { addComponentExports, addImportsSources, createResolver, defineNuxtModule, addTypeTemplate } from '@nuxt/kit'
 import type { NuxtModule } from '@nuxt/schema'
 import type { ModuleOptions } from './types'
@@ -49,8 +50,10 @@ export {}`
         })
       }
 
+      // 从源码加载时（monorepo dev）入口是 ../index.ts；发布包 dist 中为 ../index.js。
+      const libraryEntry = existsSync(resolver.resolve('../index.ts')) ? '../index.ts' : '../index.js'
       addComponentExports({
-        filePath: resolver.resolve('../index.js'),
+        filePath: resolver.resolve(libraryEntry),
         prefix: options.prefix,
       })
 
diff --git a/turbo.json b/turbo.json
index f8960c5..adaa9cd 100644
--- a/turbo.json
+++ b/turbo.json
@@ -6,7 +6,6 @@
       "outputs": ["dist/**", ".output/**", ".nuxt/**"]
     },
     "dev": {
-      "dependsOn": ["^build"],
       "cache": false,
       "persistent": true
     },

From 8f0b46b0dc405dfca47b9765cfd4cbb8a1c905c5 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 22:08:21 +0800
Subject: [PATCH 04/17] fix(inline-code): decorate wrapped lines independently

Use an inline formatting box with overflow-wrap:anywhere and cloned box decorations so long values wrap inside narrow containers without an oversized background fragment.

Add a component contract test and a patch Changeset for the consumer-visible responsive fix.
---
 .changeset/fair-inline-code-wraps.md              |  5 +++++
 .../ui/src/components/inline-code/InlineCode.vue  |  2 +-
 .../src/components/inline-code/inlineCode.test.ts | 15 +++++++++++++++
 3 files changed, 21 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/fair-inline-code-wraps.md
 create mode 100644 packages/ui/src/components/inline-code/inlineCode.test.ts

diff --git a/.changeset/fair-inline-code-wraps.md b/.changeset/fair-inline-code-wraps.md
new file mode 100644
index 0000000..c7945cf
--- /dev/null
+++ b/.changeset/fair-inline-code-wraps.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Wrap long InlineCode values into independently decorated line fragments in narrow containers instead of overflowing or leaving trailing background space.
diff --git a/packages/ui/src/components/inline-code/InlineCode.vue b/packages/ui/src/components/inline-code/InlineCode.vue
index 943a553..34d6b3d 100644
--- a/packages/ui/src/components/inline-code/InlineCode.vue
+++ b/packages/ui/src/components/inline-code/InlineCode.vue
@@ -1,7 +1,7 @@
 <template>
   <span
     :class="[
-      'inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 font-mono text-[0.875em] transition-colors',
+      'inline rounded-md px-1.5 py-0.5 font-mono text-[0.875em] [overflow-wrap:anywhere] [box-decoration-break:clone] [-webkit-box-decoration-break:clone] transition-colors',
       variantClasses,
       copyable ? 'cursor-pointer select-none hover:bg-slate-200/80 dark:hover:bg-slate-700/80' : '',
       props.class
diff --git a/packages/ui/src/components/inline-code/inlineCode.test.ts b/packages/ui/src/components/inline-code/inlineCode.test.ts
new file mode 100644
index 0000000..86a85c1
--- /dev/null
+++ b/packages/ui/src/components/inline-code/inlineCode.test.ts
@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(fileURLToPath(new URL('./InlineCode.vue', import.meta.url)), 'utf8')
+
+describe('InlineCode component contract', () => {
+  it('decorates each wrapped line independently without overflowing narrow containers', () => {
+    expect(source).toContain("'inline rounded-md")
+    expect(source).toContain('[overflow-wrap:anywhere]')
+    expect(source).toContain('[box-decoration-break:clone]')
+    expect(source).toContain('[-webkit-box-decoration-break:clone]')
+    expect(source).not.toContain("'inline-flex min-w-0")
+  })
+})

From 0db57ac8af327af88ab6c2876900a1125e48390c Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 22:08:30 +0800
Subject: [PATCH 05/17] fix(nuxt): externalize node builtins in library build

Keep node:fs external for the Nuxt module entry so its existsSync probe remains a native Node import instead of a browser stub in dist.
---
 packages/ui/vite.config.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/ui/vite.config.ts b/packages/ui/vite.config.ts
index 32cb8cd..82f24ff 100644
--- a/packages/ui/vite.config.ts
+++ b/packages/ui/vite.config.ts
@@ -26,6 +26,7 @@ export default defineConfig({
         "@nuxt/kit",
         "reka-ui",
         "lucide-vue-next",
+        /^node:/,
         /^shiki(\/.*)?$/,
         "tailwind-merge",
         "clsx",

From fa83af6ade9ea4739cd1662dd0c52134952c7db9 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 22:41:02 +0800
Subject: [PATCH 06/17] docs(agents): require complete pre-commit verification

---
 AGENTS.md | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index cc76829..5ddd949 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,11 +41,25 @@ Read only the standard required for the current work; do not preload all three t
 
 ## Verification
 
-- For a library-only change, run `bun run --cwd packages/ui typecheck`, `bun run --cwd packages/ui test`, and `bun run --cwd packages/ui build`.
-- For component, export, Nuxt-module, or documentation changes, also run `bun run --cwd apps/playground build`.
+### Mandatory pre-commit gate
+
+**Before every `git commit` or push, run the complete verification sequence from the repository root. Do not skip a command because a subset was run earlier, and do not commit or push when any command fails.**
+
+1. Run `bun run format`. This command writes formatting changes; inspect and intentionally include or revert every resulting diff before continuing.
+2. Run `git diff --check`.
+3. Run `bun run lint`.
+4. Run `bun run typecheck`.
+5. Run `bun run test`.
+6. Run `bun run build`.
+7. Run `bun run ci` as the final aggregate gate, even though it repeats lint, typecheck, test, and build.
+
+For changes that affect component rendering, exports, the Nuxt module, Playground configuration, documentation pages, or static routes, also run `bun run --cwd apps/playground generate` after the mandatory gate. Stop any Playground dev server first because it holds `apps/playground/.nuxt`.
+
+Record the commands and their passing results in the handoff, PR, or final status report. If a formatter, build, test, or validation command changes files, repeat every affected verification command before committing.
+
+- `bun run ci` is the full workspace gate: `lint`, `typecheck`, `test`, then `build`. It does not replace the explicit commands above; the redundancy is intentional.
+- Biome intentionally excludes `.vue` files, so do not treat a passing root lint as Vue validation. The Playground build/generate gate provides the required Vue and Nuxt coverage.
 - Put `--cwd` after `run`. Bun 1.4.2 treats `bun --cwd <dir> run <script>` as `bun run` with no script: it prints usage and exits 0, so the check silently passes without running anything.
-- 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
 

From b0f351d01087ca1ebc185060af8a542e7328019d Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 22:41:17 +0800
Subject: [PATCH 07/17] perf(code-block): share Shiki pipeline during SSR

---
 .changeset/calm-shiki-pipeline.md             |  5 +
 .../components/code-block/highlighter.test.ts | 31 ++++++
 .../src/components/code-block/highlighter.ts  | 94 +++++++++++--------
 3 files changed, 93 insertions(+), 37 deletions(-)
 create mode 100644 .changeset/calm-shiki-pipeline.md
 create mode 100644 packages/ui/src/components/code-block/highlighter.test.ts

diff --git a/.changeset/calm-shiki-pipeline.md b/.changeset/calm-shiki-pipeline.md
new file mode 100644
index 0000000..5b21571
--- /dev/null
+++ b/.changeset/calm-shiki-pipeline.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": patch
+---
+
+Reuse one process-wide Shiki highlighting pipeline during Nuxt SSR and prerendering while retaining on-demand grammar loading.
diff --git a/packages/ui/src/components/code-block/highlighter.test.ts b/packages/ui/src/components/code-block/highlighter.test.ts
new file mode 100644
index 0000000..4a58e0c
--- /dev/null
+++ b/packages/ui/src/components/code-block/highlighter.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { getCodeBlockHighlighter } from "./highlighter";
+
+describe("CodeBlock highlighter", () => {
+  it("shares one process-wide Shiki core while loading requested grammars", async () => {
+    const [typescript, repeatedTypescript, python] = await Promise.all([
+      getCodeBlockHighlighter("typescript"),
+      getCodeBlockHighlighter("typescript"),
+      getCodeBlockHighlighter("python"),
+    ]);
+
+    expect(repeatedTypescript).toBe(typescript);
+    expect(python).toBe(typescript);
+    expect(typescript.getLoadedLanguages()).toEqual(
+      expect.arrayContaining(["typescript", "ts", "python", "py"]),
+    );
+  });
+
+  it("reuses the same pipeline after a separate SSR chunk evaluates the module", async () => {
+    const first = await getCodeBlockHighlighter("typescript");
+
+    vi.resetModules();
+    const { getCodeBlockHighlighter: getHighlighterFromSeparateChunk } = await import(
+      "./highlighter"
+    );
+    const second = await getHighlighterFromSeparateChunk("typescript");
+
+    expect(second).toBe(first);
+  });
+});
diff --git a/packages/ui/src/components/code-block/highlighter.ts b/packages/ui/src/components/code-block/highlighter.ts
index b546834..f08c90e 100644
--- a/packages/ui/src/components/code-block/highlighter.ts
+++ b/packages/ui/src/components/code-block/highlighter.ts
@@ -1,63 +1,83 @@
-import type { HighlighterCore } from 'shiki/core'
+import type { HighlighterCore } from "shiki/core";
 
-import { loadCodeBlockGrammar } from './languages'
+import { loadCodeBlockGrammar } from "./languages";
 
-let highlighterPromise: Promise<HighlighterCore> | undefined
-const grammarPromises = new Map<string, Promise<void>>()
+interface HighlighterCache {
+  highlighterPromise?: Promise<HighlighterCore>;
+  grammarPromises: Map<string, Promise<void>>;
+}
+
+/**
+ * Nuxt may emit auto-imported components into separate SSR chunks. A Symbol.for-backed cache
+ * gives every module instance in the same prerender process one Shiki pipeline and grammar cache.
+ */
+const CACHE_KEY = Symbol.for("@recloudstudio/ui/code-block-highlighter");
+const globalCache = globalThis as typeof globalThis & Record<symbol, HighlighterCache | undefined>;
+
+const getCache = (): HighlighterCache => {
+  const existing = globalCache[CACHE_KEY];
+  if (existing) return existing;
+
+  const cache: HighlighterCache = { grammarPromises: new Map() };
+  globalCache[CACHE_KEY] = cache;
+  return cache;
+};
 
 const createHighlighter = async (): Promise<HighlighterCore> => {
   const [
     { createHighlighterCore },
     { createJavaScriptRegexEngine },
     { default: darkTheme },
-    { default: lightTheme }
+    { default: lightTheme },
   ] = 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/core"),
+    import("shiki/engine/javascript"),
+    import("shiki/dist/themes/github-dark.mjs"),
+    import("shiki/dist/themes/github-light.mjs"),
+  ]);
 
   return createHighlighterCore({
     themes: [darkTheme, lightTheme],
     langs: [],
-    engine: createJavaScriptRegexEngine()
-  })
-}
+    engine: createJavaScriptRegexEngine(),
+  });
+};
 
 const getHighlighter = (): Promise<HighlighterCore> => {
-  if (!highlighterPromise) {
-    highlighterPromise = createHighlighter().catch((error: unknown) => {
-      highlighterPromise = undefined
-      grammarPromises.clear()
-      throw error
-    })
+  const cache = getCache();
+  if (!cache.highlighterPromise) {
+    cache.highlighterPromise = createHighlighter().catch((error: unknown) => {
+      cache.highlighterPromise = undefined;
+      cache.grammarPromises.clear();
+      throw error;
+    });
   }
-  return highlighterPromise
-}
+  return cache.highlighterPromise;
+};
 
 const loadGrammar = (grammar: string): Promise<void> => {
-  const existing = grammarPromises.get(grammar)
-  if (existing) return existing
+  const cache = getCache();
+  const existing = cache.grammarPromises.get(grammar);
+  if (existing) return existing;
 
   const promise = getHighlighter().then(async (highlighter) => {
-    if (highlighter.getLoadedLanguages().includes(grammar)) return
+    if (highlighter.getLoadedLanguages().includes(grammar)) return;
 
-    const language = loadCodeBlockGrammar(grammar)
-    if (!language) throw new Error(`Unsupported CodeBlock grammar: ${grammar}`)
-    await highlighter.loadLanguage(language)
-  })
+    const language = loadCodeBlockGrammar(grammar);
+    if (!language) throw new Error(`Unsupported CodeBlock grammar: ${grammar}`);
+    await highlighter.loadLanguage(language);
+  });
 
-  grammarPromises.set(grammar, promise)
+  cache.grammarPromises.set(grammar, promise);
   promise.catch(() => {
-    if (grammarPromises.get(grammar) === promise) grammarPromises.delete(grammar)
-  })
-  return promise
-}
+    if (cache.grammarPromises.get(grammar) === promise) cache.grammarPromises.delete(grammar);
+  });
+  return promise;
+};
 
 /** Return the shared highlighter after its requested grammar has loaded. */
 export const getCodeBlockHighlighter = async (grammar: string): Promise<HighlighterCore> => {
-  const highlighter = await getHighlighter()
-  await loadGrammar(grammar)
-  return highlighter
-}
+  const highlighter = await getHighlighter();
+  await loadGrammar(grammar);
+  return highlighter;
+};

From f413b99c1b87d302dbf0bde2e78d241e4c70edb9 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 23:30:48 +0800
Subject: [PATCH 08/17] feat(markdown): add Markdown rendering system

---
 .changeset/calm-markdown-renderer.md          |   5 +
 bun.lock                                      | 129 +++-
 packages/ui/package.json                      |  16 +-
 packages/ui/src/index.ts                      | 155 +++--
 packages/ui/src/markdown/MarkdownRenderer.vue | 440 ++++++++++++
 packages/ui/src/markdown/compile.test.ts      | 141 ++++
 packages/ui/src/markdown/compile.ts           | 657 ++++++++++++++++++
 packages/ui/src/markdown/index.ts             |   3 +
 .../ui/src/markdown/markdownRenderer.test.ts  |  17 +
 packages/ui/src/markdown/types.ts             | 240 +++++++
 packages/ui/vite.config.ts                    |   7 +
 11 files changed, 1730 insertions(+), 80 deletions(-)
 create mode 100644 .changeset/calm-markdown-renderer.md
 create mode 100644 packages/ui/src/markdown/MarkdownRenderer.vue
 create mode 100644 packages/ui/src/markdown/compile.test.ts
 create mode 100644 packages/ui/src/markdown/compile.ts
 create mode 100644 packages/ui/src/markdown/index.ts
 create mode 100644 packages/ui/src/markdown/markdownRenderer.test.ts
 create mode 100644 packages/ui/src/markdown/types.ts

diff --git a/.changeset/calm-markdown-renderer.md b/.changeset/calm-markdown-renderer.md
new file mode 100644
index 0000000..6261511
--- /dev/null
+++ b/.changeset/calm-markdown-renderer.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add Markdown rendering system with GFM, TOC heading extraction, Shiki code blocks, and documentation directive extensions.
diff --git a/bun.lock b/bun.lock
index 4eaeb85..0b74a14 100644
--- a/bun.lock
+++ b/bun.lock
@@ -28,19 +28,27 @@
     },
     "packages/ui": {
       "name": "@recloudstudio/ui",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "dependencies": {
         "clsx": "^2.1.1",
         "lucide-vue-next": "^1.0.0",
+        "mdast-util-to-string": "^4.0.0",
         "reka-ui": "^2.10.5",
+        "remark-directive": "^3.0.1",
+        "remark-gfm": "^4.0.1",
+        "remark-parse": "^11.0.0",
         "shiki": "^4.5.0",
         "tailwind-merge": "^3.0.2",
+        "unified": "^11.0.5",
+        "unist-util-visit": "^5.0.0",
       },
       "devDependencies": {
         "@nuxt/kit": "^4.0.0",
         "@nuxt/schema": "^4.0.0",
         "@tailwindcss/cli": "^4.1.17",
+        "@types/mdast": "^4.0.4",
         "@types/node": "^22.13.9",
+        "@types/unist": "^3.0.3",
         "@vitejs/plugin-vue": "^6.0.9",
         "tailwindcss": "^4.0.9",
         "typescript": "^5.7.3",
@@ -56,6 +64,7 @@
       },
       "optionalPeers": [
         "@nuxt/kit",
+        "@nuxt/schema",
       ],
     },
   },
@@ -518,6 +527,8 @@
 
     "@types/chai": ["@types/chai@5.2.3", "", { "dependencies": { "@types/deep-eql": "*", "assertion-error": "^2.0.1" } }, "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA=="],
 
+    "@types/debug": ["@types/debug@4.1.13", "", { "dependencies": { "@types/ms": "*" } }, "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw=="],
+
     "@types/deep-eql": ["@types/deep-eql@4.0.2", "", {}, "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw=="],
 
     "@types/estree": ["@types/estree@1.0.9", "", {}, "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg=="],
@@ -526,6 +537,8 @@
 
     "@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA=="],
 
+    "@types/ms": ["@types/ms@2.1.0", "", {}, "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA=="],
+
     "@types/node": ["@types/node@22.20.4", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-zJRE40jpHtKqE/C4fgHrAKQLJuSpzEnP9ff9Y7YtoR3Wd2pwqzlekDeEuUQXjRd+QCYnVnNwuJYmhdk9XV8gvA=="],
 
     "@types/resolve": ["@types/resolve@1.20.2", "", {}, "sha512-60BCwRFOZCQhDncwQdxxeOEEkbc5dIMccYLwbxsS4TUNeVECQ/pBJ0j09mrHOl/JJvpRPGwO9SvE4nR2Nb/a4Q=="],
@@ -640,6 +653,8 @@
 
     "b4a": ["b4a@1.9.0", "", { "peerDependencies": { "react-native-b4a": "*" }, "optionalPeers": ["react-native-b4a"] }, "sha512-dpfcF9fDNR6++cthXR67iyhgqWy9CBouAvIWhIntzBG6cvK/cnIPiZQjBwi/ZqjjBEDGfoNDtmB0kTjroOJ3pQ=="],
 
+    "bail": ["bail@2.0.2", "", {}, "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw=="],
+
     "balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
 
     "bare-events": ["bare-events@2.9.2", "", { "peerDependencies": { "bare-abort-controller": "*" }, "optionalPeers": ["bare-abort-controller"] }, "sha512-AIPKioV7/Y/8KfZ3AAhjPJxLLbY49S64Ym5DakZlUg75qQiTgUq9hEJoEwa4eUezPUlXRy/i5NpsKvo9jgKmoA=="],
@@ -688,10 +703,14 @@
 
     "chai": ["chai@6.3.0", "", {}, "sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg=="],
 
+    "character-entities": ["character-entities@2.0.2", "", {}, "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ=="],
+
     "character-entities-html4": ["character-entities-html4@2.1.0", "", {}, "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA=="],
 
     "character-entities-legacy": ["character-entities-legacy@3.0.0", "", {}, "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ=="],
 
+    "character-reference-invalid": ["character-reference-invalid@2.0.1", "", {}, "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw=="],
+
     "chokidar": ["chokidar@5.0.0", "", { "dependencies": { "readdirp": "^5.0.0" } }, "sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw=="],
 
     "chownr": ["chownr@3.0.0", "", {}, "sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g=="],
@@ -764,6 +783,8 @@
 
     "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
 
+    "decode-named-character-reference": ["decode-named-character-reference@1.3.0", "", { "dependencies": { "character-entities": "^2.0.0" } }, "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q=="],
+
     "deepmerge": ["deepmerge@4.3.1", "", {}, "sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A=="],
 
     "default-browser": ["default-browser@5.5.1", "", { "dependencies": { "bundle-name": "^4.1.0", "default-browser-id": "^5.0.0" } }, "sha512-m1pAzaJgZ/gssEqlOhJkPJp8Xly7QyW6xcrkUa2KKcDeDSEMP7X8xipU3snUcfisTQx0w1AGae+9UtJSfVnXGw=="],
@@ -850,6 +871,8 @@
 
     "exsolve": ["exsolve@1.1.1", "", {}, "sha512-9U/jZUgjnSGyntRr6y5Muu1MJcwFl6kPu7k8qLF0IMNfLqvw0NZ4nnVDq0RVoZ0RvCyumib4Ez3KYrVfilrw+g=="],
 
+    "extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="],
+
     "fast-fifo": ["fast-fifo@1.3.2", "", {}, "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ=="],
 
     "fast-glob": ["fast-glob@3.3.3", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.8" } }, "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg=="],
@@ -958,8 +981,14 @@
 
     "iron-webcrypto": ["iron-webcrypto@1.2.1", "", {}, "sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg=="],
 
+    "is-alphabetical": ["is-alphabetical@2.0.1", "", {}, "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ=="],
+
+    "is-alphanumerical": ["is-alphanumerical@2.0.1", "", { "dependencies": { "is-alphabetical": "^2.0.0", "is-decimal": "^2.0.0" } }, "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw=="],
+
     "is-core-module": ["is-core-module@2.17.0", "", { "dependencies": { "hasown": "^2.0.4" } }, "sha512-J/vG0zBCbIKOQFfufSwyXdMrsohyJIUNkrnmo6WZGzoM7tr/lsbfW5b2BvisL6zsyMzK9UxV9L6c7AoFbyXHOA=="],
 
+    "is-decimal": ["is-decimal@2.0.1", "", {}, "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A=="],
+
     "is-docker": ["is-docker@3.0.0", "", { "bin": { "is-docker": "cli.js" } }, "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ=="],
 
     "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
@@ -968,6 +997,8 @@
 
     "is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
 
+    "is-hexadecimal": ["is-hexadecimal@2.0.1", "", {}, "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg=="],
+
     "is-in-ssh": ["is-in-ssh@1.0.0", "", {}, "sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw=="],
 
     "is-inside-container": ["is-inside-container@1.0.0", "", { "dependencies": { "is-docker": "^3.0.0" }, "bin": { "is-inside-container": "cli.js" } }, "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA=="],
@@ -980,6 +1011,8 @@
 
     "is-path-inside": ["is-path-inside@4.0.0", "", {}, "sha512-lJJV/5dYS+RcL8uQdBDW9c9uWFLLBNRyFhnAKXw5tVqLlKZ4RMGZKv+YQ/IA3OhD+RpbJa1LLFM1FQPGyIXvOA=="],
 
+    "is-plain-obj": ["is-plain-obj@4.1.0", "", {}, "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg=="],
+
     "is-reference": ["is-reference@1.2.1", "", { "dependencies": { "@types/estree": "*" } }, "sha512-U82MsXXiFIrjCK4otLT+o2NA2Cd2g5MLoOVXUZjIOhLurrRxpEXzI8O0KZHr3IjLvlAH1kTPYSuqer5T9ZVBKQ=="],
 
     "is-stream": ["is-stream@3.0.0", "", {}, "sha512-LnQR4bZ9IADDRSkvpqMGvt/tEJWclzklNgSw48V5EAaAeDd6qGvN8ei6k5p0tvxSR171VmGyHuTiAOfxAbr8kA=="],
@@ -1050,6 +1083,8 @@
 
     "lodash": ["lodash@4.18.1", "", {}, "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q=="],
 
+    "longest-streak": ["longest-streak@3.1.0", "", {}, "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g=="],
+
     "lru-cache": ["lru-cache@11.5.3", "", {}, "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg=="],
 
     "lucide-vue-next": ["lucide-vue-next@1.0.0", "", { "peerDependencies": { "vue": ">=3.0.1" } }, "sha512-V6SPvx1IHTj/UY+FrIYWV5faISsPSb8BnWSFDxAtezWKvWc9ZZ40PDrdu1/Qb5vg4lHWr1hs1BAMGVGm6V1Xdg=="],
@@ -1060,20 +1095,96 @@
 
     "magicast": ["magicast@0.5.5", "", { "dependencies": { "@babel/parser": "^7.29.7", "@babel/types": "^7.29.7", "source-map-js": "^1.2.1" } }, "sha512-UicdXN8zQ3JHlxVq+28afMXPr1z7WNY6+7EJnzTdQWkTAlMLF5fNCCKxJHBQwGaNGR11581EiQmQzx73+MvszA=="],
 
+    "markdown-table": ["markdown-table@3.0.4", "", {}, "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw=="],
+
+    "mdast-util-directive": ["mdast-util-directive@3.1.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "devlop": "^1.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0", "micromark-util-character": "^2.0.0", "parse-entities": "^4.0.0", "stringify-entities": "^4.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-Gqpa3MHorXYEZ0VfbroyvBlVKUfz371V6mIERqOYMcb0W1D3LwmFq1ZW4O2TDrbn+4ZmGLwMWeFRJgYZ+bc5fQ=="],
+
+    "mdast-util-find-and-replace": ["mdast-util-find-and-replace@3.0.3", "", { "dependencies": { "@types/mdast": "^4.0.0", "escape-string-regexp": "^5.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-xPgpDNl0/OXHsI7TlaIs22lWnH3KlpvZdXG1ET/m/YT2Hhdkx8lJV4kLphE6l9simyM4KPDFBwas08BgEob6Jw=="],
+
+    "mdast-util-from-markdown": ["mdast-util-from-markdown@2.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "mdast-util-to-string": "^4.0.0", "micromark": "^4.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-decode-string": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-KRLgmPaP2H1ul2bpoJkOS+9pAcDAAj9Nu1mqLnh8NLeJG5tlvj42TH80PIGBpROWlRXLk0lDrWNuZCFy/tsB4A=="],
+
+    "mdast-util-gfm": ["mdast-util-gfm@3.1.0", "", { "dependencies": { "mdast-util-from-markdown": "^2.0.0", "mdast-util-gfm-autolink-literal": "^2.0.0", "mdast-util-gfm-footnote": "^2.0.0", "mdast-util-gfm-strikethrough": "^2.0.0", "mdast-util-gfm-table": "^2.0.0", "mdast-util-gfm-task-list-item": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ=="],
+
+    "mdast-util-gfm-autolink-literal": ["mdast-util-gfm-autolink-literal@2.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "ccount": "^2.0.0", "devlop": "^1.0.0", "mdast-util-find-and-replace": "^3.0.0", "micromark-util-character": "^2.0.0" } }, "sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ=="],
+
+    "mdast-util-gfm-footnote": ["mdast-util-gfm-footnote@2.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "devlop": "^1.1.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0" } }, "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ=="],
+
+    "mdast-util-gfm-strikethrough": ["mdast-util-gfm-strikethrough@2.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-OuJHqvr455pwu2OaOrir7dbzqs4jlWKOtlu9L6GjcIjjQwNyw02VntQsr/Ek6/A13vgnXfUhBekWRUP1OkNivw=="],
+
+    "mdast-util-gfm-table": ["mdast-util-gfm-table@2.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "devlop": "^1.0.0", "markdown-table": "^3.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg=="],
+
+    "mdast-util-gfm-task-list-item": ["mdast-util-gfm-task-list-item@2.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "devlop": "^1.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ=="],
+
+    "mdast-util-phrasing": ["mdast-util-phrasing@4.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "unist-util-is": "^6.0.0" } }, "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w=="],
+
     "mdast-util-to-hast": ["mdast-util-to-hast@13.2.1", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/mdast": "^4.0.0", "@ungap/structured-clone": "^1.0.0", "devlop": "^1.0.0", "micromark-util-sanitize-uri": "^2.0.0", "trim-lines": "^3.0.0", "unist-util-position": "^5.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA=="],
 
+    "mdast-util-to-markdown": ["mdast-util-to-markdown@2.2.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "longest-streak": "^3.0.0", "mdast-util-phrasing": "^4.0.0", "mdast-util-to-string": "^4.0.0", "micromark-util-character": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-decode-string": "^2.0.0", "micromark-util-html-tag-name": "^2.0.0", "unist-util-visit": "^5.0.0", "zwitch": "^2.0.0" } }, "sha512-2Jn/ADrHFFyyniBMi0bncTbJqU78K3/TEYvzvwrWWzD9MYPUa/Gm4r3nOeKFQg/PDM5BsbDYdc8ackW4NTY6NA=="],
+
+    "mdast-util-to-string": ["mdast-util-to-string@4.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0" } }, "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg=="],
+
     "mdn-data": ["mdn-data@2.27.1", "", {}, "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ=="],
 
     "merge-stream": ["merge-stream@2.0.0", "", {}, "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w=="],
 
     "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="],
 
+    "micromark": ["micromark@4.0.3", "", { "dependencies": { "@types/debug": "^4.0.0", "debug": "^4.0.0", "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-core-commonmark": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-combine-extensions": "^2.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-edit-map": "^1.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-oGYfQzHSG5dOMovQcJ3fyTmZlWAWpi0XA0sJwJs+i6OT88o1+Jtw/8z0CmdowSLxGhhFK89rQ/oXph/wN02PNw=="],
+
+    "micromark-core-commonmark": ["micromark-core-commonmark@2.0.4", "", { "dependencies": { "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-factory-destination": "^2.0.0", "micromark-factory-label": "^2.0.0", "micromark-factory-space": "^2.1.0", "micromark-factory-title": "^2.0.0", "micromark-factory-whitespace": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-edit-map": "^1.0.0", "micromark-util-html-tag-name": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.3" } }, "sha512-wxEeE8v8XVvOrxn1TZj74qYhAtTQsSqufHVS3uNVyT1MupXxhyaHk8/9xDNPh9BmL77QNDgWTkZ3RsYHB2ry7w=="],
+
+    "micromark-extension-directive": ["micromark-extension-directive@3.0.2", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-factory-whitespace": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0", "parse-entities": "^4.0.0" } }, "sha512-wjcXHgk+PPdmvR58Le9d7zQYWy+vKEU9Se44p2CrCDPiLr2FMyiT4Fyb5UFKFC66wGB3kPlgD7q3TnoqPS7SZA=="],
+
+    "micromark-extension-gfm": ["micromark-extension-gfm@3.0.0", "", { "dependencies": { "micromark-extension-gfm-autolink-literal": "^2.0.0", "micromark-extension-gfm-footnote": "^2.0.0", "micromark-extension-gfm-strikethrough": "^2.0.0", "micromark-extension-gfm-table": "^2.0.0", "micromark-extension-gfm-tagfilter": "^2.0.0", "micromark-extension-gfm-task-list-item": "^2.0.0", "micromark-util-combine-extensions": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w=="],
+
+    "micromark-extension-gfm-autolink-literal": ["micromark-extension-gfm-autolink-literal@2.1.0", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw=="],
+
+    "micromark-extension-gfm-footnote": ["micromark-extension-gfm-footnote@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-core-commonmark": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw=="],
+
+    "micromark-extension-gfm-strikethrough": ["micromark-extension-gfm-strikethrough@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw=="],
+
+    "micromark-extension-gfm-table": ["micromark-extension-gfm-table@2.1.2", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-pRzm4kDTu0MjlmBkxmS9yYhw60nncfcEwu9NNdPFSQEFXS95ZKyIIyTSHu/o3ReBUrLKYEq+7YaXCRn/bPB4MA=="],
+
+    "micromark-extension-gfm-tagfilter": ["micromark-extension-gfm-tagfilter@2.0.0", "", { "dependencies": { "micromark-util-types": "^2.0.0" } }, "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg=="],
+
+    "micromark-extension-gfm-task-list-item": ["micromark-extension-gfm-task-list-item@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw=="],
+
+    "micromark-factory-destination": ["micromark-factory-destination@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA=="],
+
+    "micromark-factory-label": ["micromark-factory-label@2.0.1", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg=="],
+
+    "micromark-factory-space": ["micromark-factory-space@2.1.0", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-fS8hnLIjnjvdQIj39Geug8wWsR0HrYZ43KShKxNfwT7t2LOHo/LbWZEzEaSOjwtjdCsjoE6syHhonEzW0zv0+Q=="],
+
+    "micromark-factory-title": ["micromark-factory-title@2.0.1", "", { "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw=="],
+
+    "micromark-factory-whitespace": ["micromark-factory-whitespace@2.0.1", "", { "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ=="],
+
     "micromark-util-character": ["micromark-util-character@2.1.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q=="],
 
+    "micromark-util-chunked": ["micromark-util-chunked@2.0.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA=="],
+
+    "micromark-util-classify-character": ["micromark-util-classify-character@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q=="],
+
+    "micromark-util-combine-extensions": ["micromark-util-combine-extensions@2.0.1", "", { "dependencies": { "micromark-util-chunked": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg=="],
+
+    "micromark-util-decode-numeric-character-reference": ["micromark-util-decode-numeric-character-reference@2.0.2", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw=="],
+
+    "micromark-util-decode-string": ["micromark-util-decode-string@2.0.1", "", { "dependencies": { "decode-named-character-reference": "^1.0.0", "micromark-util-character": "^2.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ=="],
+
+    "micromark-util-edit-map": ["micromark-util-edit-map@1.0.0", "", { "dependencies": { "micromark-util-types": "^2.0.0" } }, "sha512-Pa2ljlsEL6sVwFaYeyrOLSYbQt73JvGbPOYFq+9AElXiSnfI5Q4465RRZ1sHv7lDjDOnGRDDaqPXqClqWK/q1Q=="],
+
     "micromark-util-encode": ["micromark-util-encode@2.0.1", "", {}, "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw=="],
 
+    "micromark-util-html-tag-name": ["micromark-util-html-tag-name@2.0.1", "", {}, "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA=="],
+
+    "micromark-util-normalize-identifier": ["micromark-util-normalize-identifier@2.0.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q=="],
+
+    "micromark-util-resolve-all": ["micromark-util-resolve-all@2.0.1", "", { "dependencies": { "micromark-util-types": "^2.0.0" } }, "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg=="],
+
     "micromark-util-sanitize-uri": ["micromark-util-sanitize-uri@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ=="],
 
+    "micromark-util-subtokenize": ["micromark-util-subtokenize@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA=="],
+
     "micromark-util-symbol": ["micromark-util-symbol@2.0.1", "", {}, "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q=="],
 
     "micromark-util-types": ["micromark-util-types@2.0.3", "", {}, "sha512-oxB2Ik03hI0gv+VNn9tnh1t1YEe9MDPptViAEgfdf3YQHsn0pzGTgCdlSCJXcwhqm8phaEuM7zeEu3QQzVBrPg=="],
@@ -1166,6 +1277,8 @@
 
     "package-manager-detector": ["package-manager-detector@1.8.0", "", {}, "sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A=="],
 
+    "parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw=="],
+
     "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
 
     "path-browserify": ["path-browserify@1.0.1", "", {}, "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g=="],
@@ -1288,6 +1401,14 @@
 
     "reka-ui": ["reka-ui@2.10.5", "", { "dependencies": { "@floating-ui/dom": "^1.6.13", "@floating-ui/vue": "^1.1.6", "@internationalized/date": "^3.5.0", "@internationalized/number": "^3.5.0", "@tanstack/vue-virtual": "^3.12.0", "@vueuse/core": "^14.1.0", "@vueuse/shared": "^14.1.0", "aria-hidden": "^1.2.4", "defu": "^6.1.5", "ohash": "^2.0.11" }, "peerDependencies": { "vue": ">= 3.4.0" } }, "sha512-/8o0y9BThE0hcHKFg+3770tWcJh3qKdOEFxLOPb9HIajXeFoH/J530cZH62jUJunbqwBgpSBL9v7nB8LJ5pDXA=="],
 
+    "remark-directive": ["remark-directive@3.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-directive": "^3.0.0", "micromark-extension-directive": "^3.0.0", "unified": "^11.0.0" } }, "sha512-gwglrEQEZcZYgVyG1tQuA+h58EZfq5CSULw7J90AFuCTyib1thgHPoqQ+h9iFvU6R+vnZ5oNFQR5QKgGpk741A=="],
+
+    "remark-gfm": ["remark-gfm@4.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-gfm": "^3.0.0", "micromark-extension-gfm": "^3.0.0", "remark-parse": "^11.0.0", "remark-stringify": "^11.0.0", "unified": "^11.0.0" } }, "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg=="],
+
+    "remark-parse": ["remark-parse@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-from-markdown": "^2.0.0", "micromark-util-types": "^2.0.0", "unified": "^11.0.0" } }, "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA=="],
+
+    "remark-stringify": ["remark-stringify@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-to-markdown": "^2.0.0", "unified": "^11.0.0" } }, "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw=="],
+
     "resolve": ["resolve@1.22.12", "", { "dependencies": { "es-errors": "^1.3.0", "is-core-module": "^2.16.1", "path-parse": "^1.0.7", "supports-preserve-symlinks-flag": "^1.0.0" }, "bin": { "resolve": "bin/resolve" } }, "sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA=="],
 
     "resolve-from": ["resolve-from@5.0.0", "", {}, "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw=="],
@@ -1432,6 +1553,8 @@
 
     "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
 
+    "trough": ["trough@2.2.0", "", {}, "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw=="],
+
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
     "turbo": ["turbo@2.11.6", "", { "optionalDependencies": { "@turbo/darwin-64": "2.11.6", "@turbo/darwin-arm64": "2.11.6", "@turbo/linux-64": "2.11.6", "@turbo/linux-arm64": "2.11.6", "@turbo/windows-64": "2.11.6", "@turbo/windows-arm64": "2.11.6" }, "bin": { "turbo": "bin/turbo" } }, "sha512-UppAr5XEHLfVdVp75nd+tzPp/wVEwS7Ken9aYjMlBnHqXynKn9IcQHd6GDOXBxDViSjpS+SzJcOF86v9Hf8GfQ=="],
@@ -1458,6 +1581,8 @@
 
     "unicorn-magic": ["unicorn-magic@0.4.1", "", {}, "sha512-lzlXPoVB0Uy/FvTaUgX39RbixYiSKoc3JSoSf01+0c2B6FR3qdYIPN7Qjo/AV7n6sqLCk0509cT3LRj1oSZ1+A=="],
 
+    "unified": ["unified@11.0.5", "", { "dependencies": { "@types/unist": "^3.0.0", "bail": "^2.0.0", "devlop": "^1.0.0", "extend": "^3.0.0", "is-plain-obj": "^4.0.0", "trough": "^2.0.0", "vfile": "^6.0.0" } }, "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA=="],
+
     "unimport": ["unimport@6.5.0", "", { "dependencies": { "acorn": "^8.18.0", "escape-string-regexp": "^5.0.0", "estree-walker": "^3.0.3", "local-pkg": "^1.2.1", "magic-string": "^1.2.3", "mlly": "^1.8.2", "pathe": "^2.0.3", "picomatch": "^4.0.7", "pkg-types": "^2.3.3", "scule": "^1.3.0", "strip-literal": "^4.0.0", "tinyglobby": "^0.2.17", "unplugin": "^3.3.0", "unplugin-utils": "^0.3.2" }, "peerDependencies": { "oxc-parser": "*", "rolldown": "^1.0.0" }, "optionalPeers": ["oxc-parser", "rolldown"] }, "sha512-t0KLJLRbebz3f7NrQe+vy2ObeugVeM1XqI2oeYnauddmHSglYj3U6bxOJ65IbXmOFkcAGFJK2OyGH7aqHPM6Ug=="],
 
     "unist-util-is": ["unist-util-is@6.0.1", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g=="],
@@ -1682,6 +1807,8 @@
 
     "nypm/citty": ["citty@0.2.2", "", {}, "sha512-+6vJA3L98yv+IdfKGZHBNiGW5KHn22e/JwID0Strsz8h4S/csAu/OuICwxrg44k5MRiZHWIo8XXuJgQTriRP4w=="],
 
+    "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
+
     "pkg-types/confbox": ["confbox@0.3.1", "", {}, "sha512-cKUSoKa8YxFZZSmraVi7onONx3amu77ngK3kGpsYHDH7drPwCRkQE1RYMPlLRrMtnciRj274XNRxcHxnKmDSnA=="],
 
     "proper-lockfile/signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
diff --git a/packages/ui/package.json b/packages/ui/package.json
index b30049f..abfe937 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -21,6 +21,10 @@
       "types": "./dist/icons/index.d.ts",
       "import": "./dist/icons/index.js"
     },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.ts",
+      "import": "./dist/markdown/index.js"
+    },
     "./nuxt": {
       "types": "./dist/nuxt/index.d.ts",
       "import": "./dist/nuxt/index.js"
@@ -44,9 +48,15 @@
   "dependencies": {
     "clsx": "^2.1.1",
     "lucide-vue-next": "^1.0.0",
+    "mdast-util-to-string": "^4.0.0",
     "reka-ui": "^2.10.5",
+    "remark-directive": "^3.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
     "shiki": "^4.5.0",
-    "tailwind-merge": "^3.0.2"
+    "tailwind-merge": "^3.0.2",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0"
   },
   "peerDependencies": {
     "@nuxt/kit": "^4.0.0",
@@ -64,9 +74,11 @@
   "devDependencies": {
     "@nuxt/kit": "^4.0.0",
     "@nuxt/schema": "^4.0.0",
+    "@tailwindcss/cli": "^4.1.17",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.9",
+    "@types/unist": "^3.0.3",
     "@vitejs/plugin-vue": "^6.0.9",
-    "@tailwindcss/cli": "^4.1.17",
     "tailwindcss": "^4.0.9",
     "typescript": "^5.7.3",
     "vite": "^8.0.0",
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 6ff588b..5d92700 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -1,80 +1,81 @@
 // Components
-export * from './components/button'
-export * from './components/badge'
-export * from './components/card'
-export * from './components/banner'
-export * from './components/input'
-export * from './components/tag-input'
-export * from './components/field'
-export * from './components/form'
-export * from './components/textarea'
-export * from './components/switch'
-export * from './components/checkbox'
-export * from './components/select'
-export * from './components/dialog'
-export * from './components/dropdown'
-export * from './components/tooltip'
-export * from './components/tabs'
-export * from './components/toast'
-export * from './components/avatar'
-export * from './components/progress'
-export * from './components/skeleton'
-export * from './components/separator'
-export * from './components/empty'
-export * from './components/pagination'
-export * from './components/label'
-export * from './components/radio'
-export * from './components/toggle'
-export * from './components/toggle-group'
-export * from './components/accordion'
-export * from './components/collapsible'
-export * from './components/stepper'
-export * from './components/scroll-area'
-export * from './components/table'
-export * from './components/breadcrumb'
-export * from './components/kbd'
-export * from './components/code-block'
-export * from './components/spinner'
-export * from './components/popover'
-export * from './components/context-menu'
-export * from './components/alert-dialog'
-export * from './components/slider'
-export * from './components/rating'
-export * from './components/pin-input'
-export * from './components/number-field'
-export * from './components/combobox'
-export * from './components/editable'
-export * from './components/hover-card'
-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'
-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'
-export * from './components/navbar'
-export * from './components/footer'
-export * from './components/hero'
-export * from './components/icon'
+export * from "./components/button";
+export * from "./components/badge";
+export * from "./components/card";
+export * from "./components/banner";
+export * from "./components/input";
+export * from "./components/tag-input";
+export * from "./components/field";
+export * from "./components/form";
+export * from "./components/textarea";
+export * from "./components/switch";
+export * from "./components/checkbox";
+export * from "./components/select";
+export * from "./components/dialog";
+export * from "./components/dropdown";
+export * from "./components/tooltip";
+export * from "./components/tabs";
+export * from "./components/toast";
+export * from "./components/avatar";
+export * from "./components/progress";
+export * from "./components/skeleton";
+export * from "./components/separator";
+export * from "./components/empty";
+export * from "./components/pagination";
+export * from "./components/label";
+export * from "./components/radio";
+export * from "./components/toggle";
+export * from "./components/toggle-group";
+export * from "./components/accordion";
+export * from "./components/collapsible";
+export * from "./components/stepper";
+export * from "./components/scroll-area";
+export * from "./components/table";
+export * from "./components/breadcrumb";
+export * from "./components/kbd";
+export * from "./components/code-block";
+export * from "./components/spinner";
+export * from "./components/popover";
+export * from "./components/context-menu";
+export * from "./components/alert-dialog";
+export * from "./components/slider";
+export * from "./components/rating";
+export * from "./components/pin-input";
+export * from "./components/number-field";
+export * from "./components/combobox";
+export * from "./components/editable";
+export * from "./components/hover-card";
+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";
+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";
+export * from "./components/navbar";
+export * from "./components/footer";
+export * from "./components/hero";
+export * from "./components/icon";
+export * from "./markdown";
 
 // 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'
+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/markdown/MarkdownRenderer.vue b/packages/ui/src/markdown/MarkdownRenderer.vue
new file mode 100644
index 0000000..ae57014
--- /dev/null
+++ b/packages/ui/src/markdown/MarkdownRenderer.vue
@@ -0,0 +1,440 @@
+<template>
+  <div
+    :class="[
+      'recloud-markdown leading-relaxed text-slate-800 dark:text-slate-200 selection:bg-[#2563EB]/15 dark:selection:bg-[#70ACFE]/20',
+      props.class
+    ]"
+  >
+    <template v-for="(block, index) in compiledDocument.children" :key="index">
+      <component :is="renderBlock(block)" />
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, h, type VNode, watch } from 'vue'
+import { AnchorHeading } from '../components/anchor-heading'
+import { Callout } from '../components/callout'
+import { CodeBlock } from '../components/code-block'
+import { CodeGroup } from '../components/code-group'
+import { InlineCode } from '../components/inline-code'
+import { StepItem, Steps } from '../components/steps'
+import { compileMarkdown } from './compile'
+import type {
+  MarkdownBlockNode,
+  MarkdownCalloutNode,
+  MarkdownCodeBlockNode,
+  MarkdownCodeGroupNode,
+  MarkdownDocument,
+  MarkdownHeading,
+  MarkdownHeadingNode,
+  MarkdownInlineNode,
+  MarkdownListNode,
+  MarkdownParagraphNode,
+  MarkdownRendererProps,
+  MarkdownStepsNode,
+  MarkdownTableNode
+} from './types'
+
+const props = withDefaults(defineProps<MarkdownRendererProps>(), {
+  content: '',
+  ast: undefined,
+  components: () => ({}),
+  baseUrl: undefined,
+  features: () => ({}),
+  sanitize: () => ({}),
+  class: ''
+})
+
+const emit = defineEmits<{
+  (e: 'headings', headings: MarkdownHeading[]): void
+}>()
+
+const compiledDocument = computed<MarkdownDocument>(() => {
+  if (props.ast) return props.ast
+  return compileMarkdown(props.content || '', {
+    baseUrl: props.baseUrl,
+    features: props.features,
+    sanitize: props.sanitize
+  })
+})
+
+watch(
+  () => compiledDocument.value.headings,
+  (headings) => {
+    emit('headings', headings)
+  },
+  { immediate: true }
+)
+
+const renderInline = (node: MarkdownInlineNode): VNode | string => {
+  switch (node.type) {
+    case 'text':
+      return node.value
+    case 'inlineCode':
+      if (props.components?.inlineCode) {
+        return h(props.components.inlineCode, { code: node.value }, () => node.value)
+      }
+      return h(InlineCode, { code: node.value })
+    case 'emphasis':
+      return h('em', { class: 'italic' }, node.children.map(renderInline))
+    case 'strong':
+      return h('strong', { class: 'font-semibold text-slate-900 dark:text-slate-100' }, node.children.map(renderInline))
+    case 'delete':
+      return h('del', { class: 'line-through opacity-75' }, node.children.map(renderInline))
+    case 'break':
+      return h('br')
+    case 'link': {
+      if (props.components?.link) {
+        return h(
+          props.components.link,
+          { href: node.url, title: node.title, external: node.external },
+          () => node.children.map(renderInline)
+        )
+      }
+      return h(
+        'a',
+        {
+          href: node.url,
+          title: node.title,
+          target: node.external ? '_blank' : undefined,
+          rel: node.external ? 'noopener noreferrer' : undefined,
+          class:
+            'font-medium text-[#2563EB] dark:text-[#70ACFE] underline underline-offset-4 decoration-[#2563EB]/40 hover:decoration-[#2563EB] dark:decoration-[#70ACFE]/40 dark:hover:decoration-[#70ACFE] transition-colors'
+        },
+        node.children.map(renderInline)
+      )
+    }
+    case 'image': {
+      if (props.components?.image) {
+        return h(props.components.image, { src: node.url, alt: node.alt, title: node.title })
+      }
+      return h('img', {
+        src: node.url,
+        alt: node.alt || '',
+        title: node.title,
+        loading: 'lazy',
+        class: 'my-6 rounded-xl border border-slate-200/80 shadow-sm dark:border-slate-800'
+      })
+    }
+    default:
+      return ''
+  }
+}
+
+const renderHeading = (block: MarkdownHeadingNode): VNode => {
+  const asTag = `h${block.level}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+  if (props.components?.heading) {
+    return h(
+      props.components.heading,
+      { level: block.level, id: block.id, title: block.title },
+      () => block.children.map(renderInline)
+    )
+  }
+  return h(
+    AnchorHeading,
+    {
+      as: asTag,
+      id: block.id
+    },
+    () => block.children.map(renderInline)
+  )
+}
+
+const renderParagraph = (block: MarkdownParagraphNode): VNode => {
+  if (props.components?.paragraph) {
+    return h(props.components.paragraph, null, () => block.children.map(renderInline))
+  }
+  return h(
+    'p',
+    { class: 'my-4 text-base leading-7 text-slate-700 dark:text-slate-300' },
+    block.children.map(renderInline)
+  )
+}
+
+const renderList = (block: MarkdownListNode): VNode => {
+  const tag = block.ordered ? 'ol' : 'ul'
+  const listClass = block.ordered
+    ? 'my-4 ml-6 list-decimal space-y-2 text-slate-700 dark:text-slate-300'
+    : 'my-4 ml-6 list-disc space-y-2 text-slate-700 dark:text-slate-300'
+
+  if (props.components?.list) {
+    return h(
+      props.components.list,
+      { ordered: block.ordered, start: block.start },
+      () =>
+        block.children.map((item) =>
+          props.components?.listItem
+            ? h(props.components.listItem, { checked: item.checked }, () =>
+                item.children.map(renderBlock)
+              )
+            : h(
+                'li',
+                { class: 'leading-7 pl-1' },
+                item.children.map(renderBlock)
+              )
+        )
+    )
+  }
+
+  return h(
+    tag,
+    {
+      start: block.start,
+      class: listClass
+    },
+    block.children.map((item) =>
+      h(
+        'li',
+        {
+          class: [
+            'leading-7 pl-1',
+            item.checked !== null && item.checked !== undefined ? 'list-none -ml-5 flex items-start gap-2' : ''
+          ]
+        },
+        [
+          item.checked !== null && item.checked !== undefined
+            ? h('input', {
+                type: 'checkbox',
+                checked: item.checked,
+                disabled: true,
+                class:
+                  'mt-1.5 h-4 w-4 rounded border-slate-300 text-[#2563EB] focus:ring-0 dark:border-slate-700'
+              })
+            : null,
+          h('div', { class: 'flex-1' }, item.children.map(renderBlock))
+        ]
+      )
+    )
+  )
+}
+
+const renderTable = (block: MarkdownTableNode): VNode => {
+  if (props.components?.table) {
+    return h(props.components.table, { table: block })
+  }
+
+  return h(
+    'div',
+    { class: 'my-6 w-full overflow-x-auto rounded-xl border border-slate-200/80 dark:border-slate-800' },
+    h('table', { class: 'w-full border-collapse text-left text-sm' }, [
+      ...(block.children[0]
+        ? [
+            h(
+              'thead',
+              { class: 'bg-slate-50/75 dark:bg-slate-900/50' },
+              [
+                h(
+                  'tr',
+                  null,
+                  block.children[0].children.map((cell) =>
+                    h(
+                      'th',
+                      {
+                        class: [
+                          'border-b border-slate-200/80 px-4 py-3 font-semibold text-slate-900 dark:border-slate-800 dark:text-slate-100',
+                          cell.align === 'center'
+                            ? 'text-center'
+                            : cell.align === 'right'
+                              ? 'text-right'
+                              : 'text-left'
+                        ]
+                      },
+                      cell.children.map(renderInline)
+                    )
+                  )
+                )
+              ]
+            )
+          ]
+        : []),
+      h(
+        'tbody',
+        { class: 'divide-y divide-slate-200/70 dark:divide-slate-800/70' },
+        block.children.slice(1).map((row) =>
+          h(
+            'tr',
+            { class: 'hover:bg-slate-50/50 dark:hover:bg-slate-900/30 transition-colors' },
+            row.children.map((cell) =>
+              h(
+                'td',
+                {
+                  class: [
+                    'px-4 py-3 text-slate-700 dark:text-slate-300 align-top',
+                    cell.align === 'center'
+                      ? 'text-center'
+                      : cell.align === 'right'
+                        ? 'text-right'
+                        : 'text-left'
+                  ]
+                },
+                cell.children.map(renderInline)
+              )
+            )
+          )
+        )
+      )
+    ])
+  )
+}
+
+const renderCodeBlock = (block: MarkdownCodeBlockNode): VNode => {
+  if (props.components?.codeBlock) {
+    return h(props.components.codeBlock, { ...block })
+  }
+
+  return h(CodeBlock, {
+    code: block.code,
+    language: block.language,
+    copyable: block.copyable,
+    collapsible: block.collapsible,
+    collapsed: block.collapsed,
+    highlightLines: block.highlightLines,
+    class: 'my-5'
+  })
+}
+
+const renderCallout = (block: MarkdownCalloutNode): VNode => {
+  if (props.components?.callout) {
+    return h(
+      props.components.callout,
+      {
+        type: block.calloutType,
+        title: block.title,
+        collapsible: block.collapsible,
+        defaultOpen: block.defaultOpen
+      },
+      () => block.children.map(renderBlock)
+    )
+  }
+
+  return h(
+    Callout,
+    {
+      type: block.calloutType,
+      title: block.title,
+      collapsible: block.collapsible,
+      defaultOpen: block.defaultOpen,
+      class: 'my-6'
+    },
+    () => block.children.map(renderBlock)
+  )
+}
+
+const renderSteps = (block: MarkdownStepsNode): VNode => {
+  if (props.components?.steps) {
+    return h(
+      props.components.steps,
+      { startIndex: block.startIndex },
+      () =>
+        block.children.map((item) =>
+          props.components?.stepItem
+            ? h(
+                props.components.stepItem,
+                { title: item.title, description: item.description, step: item.step },
+                () => item.children.map(renderBlock)
+              )
+            : h(
+                StepItem,
+                { title: item.title, description: item.description, step: item.step },
+                () => item.children.map(renderBlock)
+              )
+        )
+    )
+  }
+
+  return h(
+    Steps,
+    {
+      startIndex: block.startIndex,
+      class: 'my-6'
+    },
+    () =>
+      block.children.map((item) =>
+        h(
+          StepItem,
+          {
+            title: item.title,
+            description: item.description,
+            step: item.step
+          },
+          () => item.children.map(renderBlock)
+        )
+      )
+  )
+}
+
+const renderCodeGroup = (block: MarkdownCodeGroupNode): VNode => {
+  if (props.components?.codeGroup) {
+    return h(props.components.codeGroup, { tabs: block.tabs }, () =>
+      block.children.map(renderCodeBlock)
+    )
+  }
+
+  const defaultKey = block.tabs[0]?.key
+
+  return h(
+    CodeGroup,
+    {
+      tabs: block.tabs,
+      modelValue: defaultKey,
+      class: 'my-6'
+    },
+    {
+      default: (slotProps: { activeKey?: string | number; activeIndex?: number }) => {
+        const activeIndex = slotProps?.activeIndex ?? 0
+        const activeBlock = block.children[activeIndex] ?? block.children[0]
+        if (!activeBlock) return null
+
+        return h(CodeBlock, {
+          code: activeBlock.code,
+          language: activeBlock.language,
+          copyable: activeBlock.copyable,
+          collapsible: activeBlock.collapsible,
+          collapsed: activeBlock.collapsed,
+          highlightLines: activeBlock.highlightLines,
+          class: 'rounded-none border-x-0 border-b-0 shadow-none'
+        })
+      }
+    }
+  )
+}
+
+const renderBlock = (block: MarkdownBlockNode): VNode => {
+  switch (block.type) {
+    case 'heading':
+      return renderHeading(block)
+    case 'paragraph':
+      return renderParagraph(block)
+    case 'blockquote':
+      return props.components?.blockquote
+        ? h(props.components.blockquote, null, () => block.children.map(renderBlock))
+        : h(
+            'blockquote',
+            {
+              class:
+                'my-5 border-l-4 border-slate-300 pl-4 italic text-slate-700 dark:border-slate-700 dark:text-slate-300'
+            },
+            block.children.map(renderBlock)
+          )
+    case 'list':
+      return renderList(block)
+    case 'table':
+      return renderTable(block)
+    case 'codeBlock':
+      return renderCodeBlock(block)
+    case 'thematicBreak':
+      return props.components?.thematicBreak
+        ? h(props.components.thematicBreak)
+        : h('hr', { class: 'my-8 border-slate-200/80 dark:border-slate-800' })
+    case 'callout':
+      return renderCallout(block)
+    case 'steps':
+      return renderSteps(block)
+    case 'codeGroup':
+      return renderCodeGroup(block)
+    default:
+      return h('div')
+  }
+}
+</script>
diff --git a/packages/ui/src/markdown/compile.test.ts b/packages/ui/src/markdown/compile.test.ts
new file mode 100644
index 0000000..9ac720b
--- /dev/null
+++ b/packages/ui/src/markdown/compile.test.ts
@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { compileMarkdown, slugifyHeading } from "./compile";
+
+describe("compileMarkdown", () => {
+  it("compiles commonmark blocks, inlines, and headings metadata", () => {
+    const md = `
+# Installation
+
+Install the package via bun:
+
+Here is an [example link](https://example.com).
+
+\`\`\`bash
+bun add @recloudstudio/ui
+\`\`\`
+`;
+
+    const doc = compileMarkdown(md);
+    expect(doc.headings).toEqual([{ id: "installation", title: "Installation", level: 1 }]);
+    expect(doc.links).toEqual([{ href: "https://example.com", title: undefined, external: true }]);
+    expect(doc.codeBlocks).toHaveLength(1);
+    expect(doc.codeBlocks[0]?.language).toBe("bash");
+    expect(doc.codeBlocks[0]?.code.trim()).toBe("bun add @recloudstudio/ui");
+  });
+
+  it("slugifies headings with duplicate deduplication", () => {
+    expect(slugifyHeading("Quick Start Guide!")).toBe("quick-start-guide");
+
+    const md = `
+## Overview
+### Overview
+#### Overview
+`;
+    const doc = compileMarkdown(md);
+    expect(doc.headings.map((h) => h.id)).toEqual(["overview", "overview-1", "overview-2"]);
+  });
+
+  it("compiles GFM tables and task lists", () => {
+    const md = `
+| Prop | Type | Default |
+| :--- | :---: | ---: |
+| content | string | '' |
+
+- [x] Done task
+- [ ] Todo task
+`;
+
+    const doc = compileMarkdown(md);
+    const table = doc.children.find((child) => child.type === "table");
+    expect(table).toBeDefined();
+    if (table && table.type === "table") {
+      expect(table.align).toEqual(["left", "center", "right"]);
+      expect(table.children).toHaveLength(2);
+    }
+
+    const list = doc.children.find((child) => child.type === "list");
+    expect(list).toBeDefined();
+    if (list && list.type === "list") {
+      expect(list.children[0]?.checked).toBe(true);
+      expect(list.children[1]?.checked).toBe(false);
+    }
+  });
+
+  it("compiles callout directives", () => {
+    const md = `
+:::warning{title="Sensitive Credential" collapsible="true"}
+Never commit your secret token.
+:::
+`;
+
+    const doc = compileMarkdown(md);
+    const callout = doc.children.find((child) => child.type === "callout");
+    expect(callout).toBeDefined();
+    if (callout && callout.type === "callout") {
+      expect(callout.calloutType).toBe("warning");
+      expect(callout.title).toBe("Sensitive Credential");
+      expect(callout.collapsible).toBe(true);
+    }
+  });
+
+  it("compiles steps directives with deterministic step numbering", () => {
+    const md = `
+:::steps{startIndex="1"}
+:::step{title="Install"}
+Run bun add.
+:::
+:::step{title="Configure"}
+Edit nuxt.config.ts.
+:::
+:::
+`;
+
+    const doc = compileMarkdown(md);
+    const steps = doc.children.find((child) => child.type === "steps");
+    expect(steps).toBeDefined();
+    if (steps && steps.type === "steps") {
+      expect(steps.children).toHaveLength(2);
+      expect(steps.children[0]?.step).toBe(1);
+      expect(steps.children[1]?.step).toBe(2);
+      expect(steps.children[0]?.title).toBe("Install");
+    }
+  });
+
+  it("compiles code-group directives into multi-tab structures", () => {
+    const md = `
+:::code-group
+
+\`\`\`bash [bun]
+bun add @recloudstudio/ui
+\`\`\`
+
+\`\`\`bash [pnpm]
+pnpm add @recloudstudio/ui
+\`\`\`
+
+:::
+`;
+
+    const doc = compileMarkdown(md);
+    const group = doc.children.find((child) => child.type === "codeGroup");
+    expect(group).toBeDefined();
+    if (group && group.type === "codeGroup") {
+      expect(group.tabs.map((tab) => tab.label)).toEqual(["bun", "pnpm"]);
+      expect(group.children).toHaveLength(2);
+      expect(group.children[0]?.code.trim()).toBe("bun add @recloudstudio/ui");
+    }
+  });
+
+  it("filters unsafe javascript protocols by default", () => {
+    const md = `
+[Click me](javascript:alert(1))
+![Malicious](javascript:evil())
+[Safe Link](https://worldexecute.me)
+`;
+
+    const doc = compileMarkdown(md);
+    expect(doc.links).toEqual([
+      { href: "https://worldexecute.me", title: undefined, external: true },
+    ]);
+  });
+});
diff --git a/packages/ui/src/markdown/compile.ts b/packages/ui/src/markdown/compile.ts
new file mode 100644
index 0000000..f141581
--- /dev/null
+++ b/packages/ui/src/markdown/compile.ts
@@ -0,0 +1,657 @@
+import { toString as nodeToString } from "mdast-util-to-string";
+import type {
+  BlockContent,
+  Blockquote,
+  Code,
+  DefinitionContent,
+  Heading,
+  Html,
+  Image,
+  InlineCode,
+  Link,
+  List,
+  ListItem,
+  Paragraph,
+  PhrasingContent,
+  Root,
+  Table,
+  TableCell,
+  TableRow,
+} from "mdast";
+import remarkDirective from "remark-directive";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import type { CalloutType } from "../components/callout";
+import type { CodeGroupTab } from "../components/code-group";
+import type {
+  CompileMarkdownOptions,
+  MarkdownBlockNode,
+  MarkdownCalloutNode,
+  MarkdownCodeBlockMeta,
+  MarkdownCodeBlockNode,
+  MarkdownCodeGroupNode,
+  MarkdownDocument,
+  MarkdownHeading,
+  MarkdownHeadingLevel,
+  MarkdownInlineNode,
+  MarkdownLinkMeta,
+  MarkdownListItemNode,
+  MarkdownSanitizeOptions,
+  MarkdownStepItemNode,
+  MarkdownStepsNode,
+  MarkdownTableCellNode,
+  MarkdownTableNode,
+  MarkdownTableRowNode,
+} from "./types";
+
+const DEFAULT_PROTOCOLS = ["http:", "https:", "mailto:", "tel:"];
+
+interface DirectiveNode {
+  type: "containerDirective" | "leafDirective" | "textDirective";
+  name: string;
+  attributes?: Record<string, string | number | boolean | null | undefined>;
+  children?: (BlockContent | DefinitionContent | PhrasingContent)[];
+}
+
+const isSafeUrl = (url: string, allowedProtocols = DEFAULT_PROTOCOLS): boolean => {
+  const trimmed = url.trim();
+  if (!trimmed) return false;
+  if (
+    trimmed.startsWith("#") ||
+    trimmed.startsWith("/") ||
+    trimmed.startsWith("./") ||
+    trimmed.startsWith("../")
+  ) {
+    return true;
+  }
+
+  try {
+    const parsed = new URL(trimmed, "https://example.com");
+    return allowedProtocols.includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+};
+
+const resolveUrl = (url: string, baseUrl?: string): string => {
+  const trimmed = url.trim();
+  if (!baseUrl || !trimmed) return trimmed;
+  if (trimmed.startsWith("#") || /^[a-z]+:/i.test(trimmed)) return trimmed;
+
+  try {
+    return new URL(trimmed, baseUrl).toString();
+  } catch {
+    return trimmed;
+  }
+};
+
+export const slugifyHeading = (text: string): string => {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[\s\W-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+};
+
+const parseCodeMeta = (
+  rawLang = "",
+  rawMeta = "",
+): {
+  language: string;
+  title?: string;
+  copyable?: boolean;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  highlightLines?: number[];
+} => {
+  const [langToken] = rawLang.trim().split(/\s+/);
+  const language = langToken || "text";
+  const meta = `${rawLang.slice(language.length)} ${rawMeta}`.trim();
+
+  const titleMatch = meta.match(/title=(?:"([^"]+)"|'([^']+)'|([^\s]+))/);
+  const labelMatch = meta.match(/\[([^\]]+)\]/);
+  const copyable = !meta.includes("no-copy");
+  const collapsible = meta.includes("collapsible");
+  const collapsed = meta.includes("collapsed");
+
+  let highlightLines: number[] | undefined;
+  const linesMatch = meta.match(/\{([\d,\s-]+)\}/);
+  if (linesMatch?.[1]) {
+    const lines = new Set<number>();
+    const parts = linesMatch[1].split(",");
+    for (const part of parts) {
+      const trimmed = part.trim();
+      if (trimmed.includes("-")) {
+        const [start, end] = trimmed.split("-").map((v) => Number.parseInt(v, 10));
+        if (!Number.isNaN(start) && !Number.isNaN(end)) {
+          for (let i = Math.min(start, end); i <= Math.max(start, end); i += 1) {
+            lines.add(i);
+          }
+        }
+      } else {
+        const line = Number.parseInt(trimmed, 10);
+        if (!Number.isNaN(line)) lines.add(line);
+      }
+    }
+    highlightLines = Array.from(lines).sort((a, b) => a - b);
+  }
+
+  return {
+    language,
+    title: titleMatch?.[1] ?? titleMatch?.[2] ?? titleMatch?.[3] ?? labelMatch?.[1],
+    copyable,
+    collapsible,
+    collapsed,
+    highlightLines,
+  };
+};
+
+class MarkdownCompilerContext {
+  headings: MarkdownHeading[] = [];
+  links: MarkdownLinkMeta[] = [];
+  codeBlocks: MarkdownCodeBlockMeta[] = [];
+  private headingCounts = new Map<string, number>();
+
+  constructor(
+    public readonly baseUrl?: string,
+    public readonly sanitize: MarkdownSanitizeOptions | false = {},
+  ) {}
+
+  createHeadingId(rawText: string): string {
+    const base = slugifyHeading(rawText) || "section";
+    const count = this.headingCounts.get(base) ?? 0;
+    this.headingCounts.set(base, count + 1);
+    return count === 0 ? base : `${base}-${count}`;
+  }
+
+  filterUrl(rawUrl: string): { url: string; safe: boolean; external: boolean } {
+    const resolved = resolveUrl(rawUrl, this.baseUrl);
+    if (this.sanitize === false) {
+      return {
+        url: resolved,
+        safe: true,
+        external: /^https?:\/\//i.test(resolved),
+      };
+    }
+
+    const protocols = this.sanitize.allowedProtocols ?? DEFAULT_PROTOCOLS;
+    const safe = isSafeUrl(resolved, protocols);
+    const external = /^https?:\/\//i.test(resolved);
+    return {
+      url: safe ? resolved : "",
+      safe,
+      external,
+    };
+  }
+}
+
+const compileInlineNodes = (
+  nodes: PhrasingContent[],
+  context: MarkdownCompilerContext,
+): MarkdownInlineNode[] => {
+  const result: MarkdownInlineNode[] = [];
+
+  for (const node of nodes) {
+    switch (node.type) {
+      case "text":
+        result.push({ type: "text", value: node.value });
+        break;
+      case "inlineCode":
+        result.push({ type: "inlineCode", value: (node as InlineCode).value });
+        break;
+      case "emphasis":
+        result.push({
+          type: "emphasis",
+          children: compileInlineNodes(node.children, context),
+        });
+        break;
+      case "strong":
+        result.push({
+          type: "strong",
+          children: compileInlineNodes(node.children, context),
+        });
+        break;
+      case "delete":
+        result.push({
+          type: "delete",
+          children: compileInlineNodes(node.children, context),
+        });
+        break;
+      case "break":
+        result.push({ type: "break" });
+        break;
+      case "link": {
+        const linkNode = node as Link;
+        const { url, safe, external } = context.filterUrl(linkNode.url);
+        if (!safe && linkNode.url) {
+          result.push(...compileInlineNodes(linkNode.children, context));
+          break;
+        }
+        const title = linkNode.title ?? undefined;
+        context.links.push({ href: url, title, external });
+        result.push({
+          type: "link",
+          url,
+          title,
+          external,
+          children: compileInlineNodes(linkNode.children, context),
+        });
+        break;
+      }
+      case "image": {
+        const imageNode = node as Image;
+        const { url, safe } = context.filterUrl(imageNode.url);
+        if (!safe) break;
+        result.push({
+          type: "image",
+          url,
+          alt: imageNode.alt ?? undefined,
+          title: imageNode.title ?? undefined,
+        });
+        break;
+      }
+      case "html": {
+        if (context.sanitize === false || context.sanitize.allowRawHtml) {
+          result.push({ type: "text", value: (node as Html).value });
+        }
+        break;
+      }
+      default:
+        if (
+          "children" in node &&
+          Array.isArray((node as { children: PhrasingContent[] }).children)
+        ) {
+          result.push(
+            ...compileInlineNodes((node as { children: PhrasingContent[] }).children, context),
+          );
+        }
+        break;
+    }
+  }
+
+  return result;
+};
+
+const compileCalloutDirective = (
+  node: DirectiveNode,
+  context: MarkdownCompilerContext,
+): MarkdownCalloutNode => {
+  const validTypes: CalloutType[] = ["note", "tip", "info", "warning", "danger"];
+  const calloutType = validTypes.includes(node.name as CalloutType)
+    ? (node.name as CalloutType)
+    : "info";
+
+  const attrs = node.attributes ?? {};
+  const title = typeof attrs.title === "string" ? attrs.title : undefined;
+  const collapsible = attrs.collapsible === true || attrs.collapsible === "true";
+  const defaultOpen = !(attrs.defaultOpen === false || attrs.defaultOpen === "false");
+
+  const children = compileBlockNodes(
+    (node.children ?? []) as (BlockContent | DefinitionContent)[],
+    context,
+  );
+
+  return {
+    type: "callout",
+    calloutType,
+    title,
+    collapsible,
+    defaultOpen,
+    children,
+  };
+};
+
+const compileStepsDirective = (
+  node: DirectiveNode,
+  context: MarkdownCompilerContext,
+): MarkdownStepsNode => {
+  const attrs = node.attributes ?? {};
+  const startIndex =
+    typeof attrs.startIndex === "number"
+      ? attrs.startIndex
+      : typeof attrs.startIndex === "string"
+        ? Number.parseInt(attrs.startIndex, 10) || 1
+        : 1;
+
+  const children: MarkdownStepItemNode[] = [];
+  let stepIndex = startIndex;
+
+  for (const child of node.children ?? []) {
+    const isDirective = child.type === "containerDirective" || child.type === "leafDirective";
+    if (!isDirective) continue;
+
+    const dir = child as DirectiveNode;
+    if (dir.name === "step") {
+      const childAttrs = dir.attributes ?? {};
+      const title = typeof childAttrs.title === "string" ? childAttrs.title : `Step ${stepIndex}`;
+      const description =
+        typeof childAttrs.description === "string" ? childAttrs.description : undefined;
+      const stepValue =
+        typeof childAttrs.step === "number"
+          ? childAttrs.step
+          : typeof childAttrs.step === "string"
+            ? Number.parseInt(childAttrs.step, 10) || stepIndex
+            : stepIndex;
+
+      const stepChildren = compileBlockNodes(
+        (dir.children ?? []) as (BlockContent | DefinitionContent)[],
+        context,
+      );
+
+      children.push({
+        type: "step",
+        title,
+        description,
+        step: stepValue,
+        children: stepChildren,
+      });
+
+      stepIndex += 1;
+    }
+  }
+
+  return {
+    type: "steps",
+    startIndex,
+    children,
+  };
+};
+
+const compileCodeGroupDirective = (
+  node: DirectiveNode,
+  context: MarkdownCompilerContext,
+): MarkdownCodeGroupNode => {
+  const tabs: CodeGroupTab[] = [];
+  const children: MarkdownCodeBlockNode[] = [];
+
+  let index = 0;
+  for (const child of node.children ?? []) {
+    if (child.type === "code") {
+      const codeNode = child as Code;
+      const meta = parseCodeMeta(codeNode.lang ?? "", codeNode.meta ?? "");
+      const codeMeta: MarkdownCodeBlockMeta = {
+        code: codeNode.value,
+        language: meta.language,
+        title: meta.title,
+        copyable: meta.copyable,
+        collapsible: meta.collapsible,
+        collapsed: meta.collapsed,
+        highlightLines: meta.highlightLines,
+      };
+
+      context.codeBlocks.push(codeMeta);
+      children.push({
+        type: "codeBlock",
+        ...codeMeta,
+      });
+
+      const tabLabel = meta.title || meta.language || `Tab ${index + 1}`;
+      tabs.push({
+        label: tabLabel,
+        key: `${index}-${tabLabel}`,
+      });
+      index += 1;
+    }
+  }
+
+  return {
+    type: "codeGroup",
+    tabs,
+    children,
+  };
+};
+
+const compileTableNode = (node: Table, context: MarkdownCompilerContext): MarkdownTableNode => {
+  const align = node.align ?? [];
+  const children: MarkdownTableRowNode[] = [];
+
+  node.children.forEach((rowNode: TableRow, rowIndex: number) => {
+    const isHeader = rowIndex === 0;
+    const cells: MarkdownTableCellNode[] = rowNode.children.map(
+      (cell: TableCell, colIndex: number) => ({
+        type: "tableCell",
+        isHeader,
+        align: align[colIndex] ?? null,
+        children: compileInlineNodes(cell.children, context),
+      }),
+    );
+
+    children.push({
+      type: "tableRow",
+      children: cells,
+    });
+  });
+
+  return {
+    type: "table",
+    align,
+    children,
+  };
+};
+
+const compileBlockNodes = (
+  nodes: (BlockContent | DefinitionContent)[],
+  context: MarkdownCompilerContext,
+): MarkdownBlockNode[] => {
+  const result: MarkdownBlockNode[] = [];
+
+  let index = 0;
+  while (index < nodes.length) {
+    const node = nodes[index];
+    if (!node) {
+      index += 1;
+      continue;
+    }
+
+    // SAFETY: remark-directive registers custom container/leaf directives in unist AST
+    const candidateDirectiveNode = node as unknown as DirectiveNode;
+    const isStepsDirective =
+      (node.type === "containerDirective" || node.type === "leafDirective") &&
+      candidateDirectiveNode.name === "steps";
+
+    if (isStepsDirective) {
+      const stepsDir = candidateDirectiveNode;
+      const compiledSteps = compileStepsDirective(stepsDir, context);
+
+      // Fallback for flat fence syntax where step directives sit next to steps container
+      if (compiledSteps.children.length <= 1) {
+        let peek = index + 1;
+        let autoStepIndex = compiledSteps.children.length + (compiledSteps.startIndex ?? 1);
+        while (peek < nodes.length) {
+          const nextNode = nodes[peek];
+          // SAFETY: remark-directive registers custom container/leaf directives in unist AST
+          const candidateDirective = nextNode as unknown as DirectiveNode;
+          const isStepDirective =
+            Boolean(nextNode) &&
+            (nextNode?.type === "containerDirective" || nextNode?.type === "leafDirective") &&
+            candidateDirective.name === "step";
+
+          if (isStepDirective && nextNode) {
+            const stepDir = candidateDirective;
+            const childAttrs = stepDir.attributes ?? {};
+            const title =
+              typeof childAttrs.title === "string" ? childAttrs.title : `Step ${autoStepIndex}`;
+            const description =
+              typeof childAttrs.description === "string" ? childAttrs.description : undefined;
+            const stepValue =
+              typeof childAttrs.step === "number"
+                ? childAttrs.step
+                : typeof childAttrs.step === "string"
+                  ? Number.parseInt(childAttrs.step, 10) || autoStepIndex
+                  : autoStepIndex;
+
+            const stepChildren = compileBlockNodes(
+              (stepDir.children ?? []) as (BlockContent | DefinitionContent)[],
+              context,
+            );
+
+            compiledSteps.children.push({
+              type: "step",
+              title,
+              description,
+              step: stepValue,
+              children: stepChildren,
+            });
+
+            autoStepIndex += 1;
+            peek += 1;
+            continue;
+          }
+
+          // SAFETY: checking raw trailing directive fence artifacts emitted as paragraphs by unist
+          const rawParagraph = nextNode as unknown as { children?: { value?: string }[] };
+          const isOrphanDirectiveFence =
+            Boolean(nextNode) &&
+            nextNode?.type === "paragraph" &&
+            rawParagraph.children?.[0]?.value?.trim() === ":::";
+
+          if (isOrphanDirectiveFence) {
+            peek += 1;
+          }
+          break;
+        }
+        index = peek - 1;
+      }
+
+      result.push(compiledSteps);
+      index += 1;
+      continue;
+    }
+
+    switch (node.type) {
+      case "heading": {
+        const headingNode = node as Heading;
+        const text = nodeToString(headingNode).trim();
+        const id = context.createHeadingId(text);
+        const level = Math.min(Math.max(headingNode.depth, 1), 6) as MarkdownHeadingLevel;
+        const headingMeta: MarkdownHeading = { id, title: text, level };
+        context.headings.push(headingMeta);
+        result.push({
+          type: "heading",
+          level,
+          id,
+          title: text,
+          children: compileInlineNodes(headingNode.children, context),
+        });
+        break;
+      }
+      case "paragraph": {
+        const paragraphNode = node as Paragraph;
+        result.push({
+          type: "paragraph",
+          children: compileInlineNodes(paragraphNode.children, context),
+        });
+        break;
+      }
+      case "blockquote": {
+        const quoteNode = node as Blockquote;
+        result.push({
+          type: "blockquote",
+          children: compileBlockNodes(quoteNode.children, context),
+        });
+        break;
+      }
+      case "list": {
+        const listNode = node as List;
+        const items: MarkdownListItemNode[] = listNode.children.map((item: ListItem) => ({
+          type: "listItem",
+          checked: item.checked ?? null,
+          children: compileBlockNodes(item.children, context),
+        }));
+        result.push({
+          type: "list",
+          ordered: listNode.ordered ?? false,
+          start: listNode.start ?? undefined,
+          spread: listNode.spread ?? false,
+          children: items,
+        });
+        break;
+      }
+      case "table": {
+        result.push(compileTableNode(node as Table, context));
+        break;
+      }
+      case "code": {
+        const codeNode = node as Code;
+        const meta = parseCodeMeta(codeNode.lang ?? "", codeNode.meta ?? "");
+        const codeMeta: MarkdownCodeBlockMeta = {
+          code: codeNode.value,
+          language: meta.language,
+          title: meta.title,
+          copyable: meta.copyable,
+          collapsible: meta.collapsible,
+          collapsed: meta.collapsed,
+          highlightLines: meta.highlightLines,
+        };
+        context.codeBlocks.push(codeMeta);
+        result.push({
+          type: "codeBlock",
+          ...codeMeta,
+        });
+        break;
+      }
+      case "thematicBreak": {
+        result.push({ type: "thematicBreak" });
+        break;
+      }
+      case "html": {
+        if (context.sanitize === false || context.sanitize.allowRawHtml) {
+          result.push({
+            type: "paragraph",
+            children: [{ type: "text", value: (node as Html).value }],
+          });
+        }
+        break;
+      }
+      case "containerDirective":
+      case "leafDirective": {
+        // SAFETY: remark-directive registers custom AST node types that are not part of standard mdast BlockContent
+        const directiveNode = node as unknown as DirectiveNode;
+        if (directiveNode.name === "steps") {
+          result.push(compileStepsDirective(directiveNode, context));
+        } else if (directiveNode.name === "code-group") {
+          result.push(compileCodeGroupDirective(directiveNode, context));
+        } else {
+          result.push(compileCalloutDirective(directiveNode, context));
+        }
+        break;
+      }
+      default:
+        break;
+    }
+    index += 1;
+  }
+
+  return result;
+};
+
+export const compileMarkdown = (
+  rawMarkdown: string,
+  options: CompileMarkdownOptions = {},
+): MarkdownDocument => {
+  const processor = unified().use(remarkParse);
+
+  if (options.features?.gfm !== false) {
+    processor.use(remarkGfm);
+  }
+
+  if (options.features?.directives !== false) {
+    processor.use(remarkDirective);
+  }
+
+  const rootAst = processor.parse(rawMarkdown || "") as Root;
+  const context = new MarkdownCompilerContext(options.baseUrl, options.sanitize);
+  const children = compileBlockNodes(
+    rootAst.children as (BlockContent | DefinitionContent)[],
+    context,
+  );
+
+  return {
+    type: "document",
+    children,
+    headings: context.headings,
+    links: context.links,
+    codeBlocks: context.codeBlocks,
+  };
+};
diff --git a/packages/ui/src/markdown/index.ts b/packages/ui/src/markdown/index.ts
new file mode 100644
index 0000000..4d37552
--- /dev/null
+++ b/packages/ui/src/markdown/index.ts
@@ -0,0 +1,3 @@
+export { default as MarkdownRenderer } from "./MarkdownRenderer.vue";
+export * from "./compile";
+export * from "./types";
diff --git a/packages/ui/src/markdown/markdownRenderer.test.ts b/packages/ui/src/markdown/markdownRenderer.test.ts
new file mode 100644
index 0000000..ee47047
--- /dev/null
+++ b/packages/ui/src/markdown/markdownRenderer.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import MarkdownRenderer from "./MarkdownRenderer.vue";
+import { compileMarkdown } from "./compile";
+
+describe("MarkdownRenderer component", () => {
+  it("is exported as a valid Vue component", () => {
+    expect(MarkdownRenderer).toBeDefined();
+    expect(MarkdownRenderer.__name || MarkdownRenderer.name).toBe("MarkdownRenderer");
+  });
+
+  it("compiles AST and exposes metadata ready for renderer consumption", () => {
+    const doc = compileMarkdown('# Hello ReCloud\n\n:::info{title="Doc"}\nBody\n:::');
+    expect(doc.type).toBe("document");
+    expect(doc.headings).toEqual([{ id: "hello-recloud", title: "Hello ReCloud", level: 1 }]);
+    expect(doc.children).toHaveLength(2);
+  });
+});
diff --git a/packages/ui/src/markdown/types.ts b/packages/ui/src/markdown/types.ts
new file mode 100644
index 0000000..d7b22df
--- /dev/null
+++ b/packages/ui/src/markdown/types.ts
@@ -0,0 +1,240 @@
+import type { Component } from "vue";
+import type { CalloutType } from "../components/callout";
+import type { CodeGroupTab } from "../components/code-group";
+
+export interface MarkdownSourcePosition {
+  start: { line: number; column: number; offset?: number };
+  end: { line: number; column: number; offset?: number };
+}
+
+export type MarkdownHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface MarkdownHeading {
+  id: string;
+  title: string;
+  level: MarkdownHeadingLevel;
+}
+
+export interface MarkdownLinkMeta {
+  href: string;
+  title?: string;
+  external: boolean;
+}
+
+export interface MarkdownCodeBlockMeta {
+  code: string;
+  language: string;
+  title?: string;
+  copyable?: boolean;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  highlightLines?: number[];
+}
+
+export interface MarkdownTextNode {
+  type: "text";
+  value: string;
+}
+
+export interface MarkdownInlineCodeNode {
+  type: "inlineCode";
+  value: string;
+}
+
+export interface MarkdownEmphasisNode {
+  type: "emphasis";
+  children: MarkdownInlineNode[];
+}
+
+export interface MarkdownStrongNode {
+  type: "strong";
+  children: MarkdownInlineNode[];
+}
+
+export interface MarkdownDeleteNode {
+  type: "delete";
+  children: MarkdownInlineNode[];
+}
+
+export interface MarkdownLinkNode {
+  type: "link";
+  url: string;
+  title?: string;
+  external: boolean;
+  children: MarkdownInlineNode[];
+}
+
+export interface MarkdownImageNode {
+  type: "image";
+  url: string;
+  alt?: string;
+  title?: string;
+}
+
+export interface MarkdownBreakNode {
+  type: "break";
+}
+
+export type MarkdownInlineNode =
+  | MarkdownTextNode
+  | MarkdownInlineCodeNode
+  | MarkdownEmphasisNode
+  | MarkdownStrongNode
+  | MarkdownDeleteNode
+  | MarkdownLinkNode
+  | MarkdownImageNode
+  | MarkdownBreakNode;
+
+export interface MarkdownHeadingNode {
+  type: "heading";
+  level: MarkdownHeadingLevel;
+  id: string;
+  title: string;
+  children: MarkdownInlineNode[];
+}
+
+export interface MarkdownParagraphNode {
+  type: "paragraph";
+  children: MarkdownInlineNode[];
+}
+
+export interface MarkdownBlockquoteNode {
+  type: "blockquote";
+  children: MarkdownBlockNode[];
+}
+
+export interface MarkdownListNode {
+  type: "list";
+  ordered: boolean;
+  start?: number;
+  spread?: boolean;
+  children: MarkdownListItemNode[];
+}
+
+export interface MarkdownListItemNode {
+  type: "listItem";
+  checked?: boolean | null;
+  children: MarkdownBlockNode[];
+}
+
+export interface MarkdownTableNode {
+  type: "table";
+  align?: ("left" | "right" | "center" | null)[];
+  children: MarkdownTableRowNode[];
+}
+
+export interface MarkdownTableRowNode {
+  type: "tableRow";
+  children: MarkdownTableCellNode[];
+}
+
+export interface MarkdownTableCellNode {
+  type: "tableCell";
+  isHeader?: boolean;
+  align?: "left" | "right" | "center" | null;
+  children: MarkdownInlineNode[];
+}
+
+export interface MarkdownCodeBlockNode extends MarkdownCodeBlockMeta {
+  type: "codeBlock";
+}
+
+export interface MarkdownThematicBreakNode {
+  type: "thematicBreak";
+}
+
+export interface MarkdownCalloutNode {
+  type: "callout";
+  calloutType: CalloutType;
+  title?: string;
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+  children: MarkdownBlockNode[];
+}
+
+export interface MarkdownStepsNode {
+  type: "steps";
+  startIndex?: number;
+  children: MarkdownStepItemNode[];
+}
+
+export interface MarkdownStepItemNode {
+  type: "step";
+  title: string;
+  description?: string;
+  step?: number;
+  children: MarkdownBlockNode[];
+}
+
+export interface MarkdownCodeGroupNode {
+  type: "codeGroup";
+  tabs: CodeGroupTab[];
+  children: MarkdownCodeBlockNode[];
+}
+
+export type MarkdownBlockNode =
+  | MarkdownHeadingNode
+  | MarkdownParagraphNode
+  | MarkdownBlockquoteNode
+  | MarkdownListNode
+  | MarkdownTableNode
+  | MarkdownCodeBlockNode
+  | MarkdownThematicBreakNode
+  | MarkdownCalloutNode
+  | MarkdownStepsNode
+  | MarkdownCodeGroupNode;
+
+export interface MarkdownDocument {
+  type: "document";
+  children: MarkdownBlockNode[];
+  headings: MarkdownHeading[];
+  links: MarkdownLinkMeta[];
+  codeBlocks: MarkdownCodeBlockMeta[];
+}
+
+export interface MarkdownSanitizeOptions {
+  allowRawHtml?: boolean;
+  allowedProtocols?: string[];
+}
+
+export interface MarkdownFeatures {
+  gfm?: boolean;
+  directives?: boolean;
+  codeGroups?: boolean;
+  callouts?: boolean;
+  steps?: boolean;
+}
+
+export interface CompileMarkdownOptions {
+  baseUrl?: string;
+  features?: MarkdownFeatures;
+  sanitize?: MarkdownSanitizeOptions | false;
+}
+
+export interface MarkdownComponentRegistry {
+  heading?: Component;
+  paragraph?: Component;
+  inlineCode?: Component;
+  codeBlock?: Component;
+  link?: Component;
+  image?: Component;
+  blockquote?: Component;
+  list?: Component;
+  listItem?: Component;
+  table?: Component;
+  thematicBreak?: Component;
+  callout?: Component;
+  steps?: Component;
+  stepItem?: Component;
+  codeGroup?: Component;
+}
+
+export interface MarkdownRendererProps {
+  content?: string;
+  ast?: MarkdownDocument;
+  components?: MarkdownComponentRegistry;
+  baseUrl?: string;
+  features?: MarkdownFeatures;
+  sanitize?: MarkdownSanitizeOptions | false;
+  class?: string;
+}
diff --git a/packages/ui/vite.config.ts b/packages/ui/vite.config.ts
index 82f24ff..5f4fc9d 100644
--- a/packages/ui/vite.config.ts
+++ b/packages/ui/vite.config.ts
@@ -16,6 +16,7 @@ export default defineConfig({
       entry: {
         index: resolve(__dirname, "src/index.ts"),
         "icons/index": resolve(__dirname, "src/icons/index.ts"),
+        "markdown/index": resolve(__dirname, "src/markdown/index.ts"),
         "nuxt/index": resolve(__dirname, "src/nuxt/index.ts"),
       },
       formats: ["es"],
@@ -30,6 +31,12 @@ export default defineConfig({
         /^shiki(\/.*)?$/,
         "tailwind-merge",
         "clsx",
+        "unified",
+        "remark-parse",
+        "remark-gfm",
+        "remark-directive",
+        "unist-util-visit",
+        "mdast-util-to-string",
       ],
       output: {
         chunkFileNames: "chunks/[name]-[hash].js",

From 2db047519dc79cf77230cc7350163808f9874c1b Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 23:31:08 +0800
Subject: [PATCH 09/17] docs(playground): document Markdown renderer and
 catalog

---
 apps/playground/nuxt.config.ts                |  71 ++--
 apps/playground/pages/components/markdown.vue | 121 +++++++
 apps/playground/utils/catalog.ts              | 330 ++++++++++++------
 3 files changed, 377 insertions(+), 145 deletions(-)
 create mode 100644 apps/playground/pages/components/markdown.vue

diff --git a/apps/playground/nuxt.config.ts b/apps/playground/nuxt.config.ts
index a778484..91a5140 100644
--- a/apps/playground/nuxt.config.ts
+++ b/apps/playground/nuxt.config.ts
@@ -1,47 +1,47 @@
-import { fileURLToPath } from 'node:url'
-import { defineNuxtConfig } from 'nuxt/config'
-import tailwindcss from '@tailwindcss/vite'
-import { createThemeInitScript } from '../../packages/ui/src/utils/themeScript'
+import { fileURLToPath } from "node:url";
+import { defineNuxtConfig } from "nuxt/config";
+import tailwindcss from "@tailwindcss/vite";
+import { createThemeInitScript } from "../../packages/ui/src/utils/themeScript";
 
 // Dev 直连源码：模块、组件、组合式函数与图标都指向 packages/ui/src，
 // 源码改动即时 HMR，无需先构建 dist。生产构建仍消费 dist（与发布产物一致）。
-const isDev = process.env.NODE_ENV === 'development'
+const isDev = process.env.NODE_ENV === "development";
 const uiSrc = (path: string) =>
-  fileURLToPath(new URL(`../../packages/ui/src/${path}`, import.meta.url))
+  fileURLToPath(new URL(`../../packages/ui/src/${path}`, import.meta.url));
 
 export default defineNuxtConfig({
   // 固定 buildDir：Nuxt 4 生产构建会在 .nuxt 已存在时自动切到 node_modules/.cache，
   // 导致 tsconfig extends 在干净环境（CI/Pages）与本地行为不一致
-  buildDir: '.nuxt',
-  css: ['~/src/style.css'],
+  buildDir: ".nuxt",
+  css: ["~/src/style.css"],
   modules: [
     [
       // Dev 加载 Nuxt 模块源码，组件自动注册随之指向 packages/ui/src。
-      isDev ? uiSrc('nuxt/index.ts') : '@recloudstudio/ui/nuxt',
-      { prefix: '', injectTheme: false }
-    ]
+      isDev ? uiSrc("nuxt/index.ts") : "@recloudstudio/ui/nuxt",
+      { prefix: "", injectTheme: false },
+    ],
   ],
   app: {
     head: {
-      title: 'ReCloud UI · ReCloud Studio 设计系统',
+      title: "ReCloud UI · ReCloud Studio 设计系统",
       script: [
         {
           // 首屏应用完整的主题偏好，避免 Vue hydration 前的颜色、密度与圆角闪烁。
-          innerHTML: createThemeInitScript()
-        }
+          innerHTML: createThemeInitScript(),
+        },
       ],
       link: [
-        { rel: 'icon', type: 'image/svg+xml', href: '/icon.svg' },
-        { rel: 'apple-touch-icon', href: '/icon.svg' },
+        { rel: "icon", type: "image/svg+xml", href: "/icon.svg" },
+        { rel: "apple-touch-icon", href: "/icon.svg" },
         // 全站字体：Maple Mono NF CN（OFL-1.1，v7.9），由 ZeoSeven FontsAPI 按 unicode-range 分包提供。
         // 四个字重同属 "Maple Mono NF CN" 族，对应 font-normal / medium / semibold / bold。
-        { rel: 'preconnect', href: 'https://fontsapi.zeoseven.com', crossorigin: '' },
-        ...['main', 'medium', 'semi-bold', 'bold'].map((style) => ({
-          rel: 'stylesheet' as const,
-          href: `https://fontsapi.zeoseven.com/442/${style}/result.css`
-        }))
-      ]
-    }
+        { rel: "preconnect", href: "https://fontsapi.zeoseven.com", crossorigin: "" },
+        ...["main", "medium", "semi-bold", "bold"].map((style) => ({
+          rel: "stylesheet" as const,
+          href: `https://fontsapi.zeoseven.com/442/${style}/result.css`,
+        })),
+      ],
+    },
   },
   vite: {
     plugins: [tailwindcss()],
@@ -50,23 +50,24 @@ export default defineNuxtConfig({
           resolve: {
             // 子路径必须排在包名之前：字符串别名按前缀匹配，顺序即优先级。
             alias: {
-              '@recloudstudio/ui/icons': uiSrc('icons/index.ts'),
-              '@recloudstudio/ui': uiSrc('index.ts')
-            }
+              "@recloudstudio/ui/icons": uiSrc("icons/index.ts"),
+              "@recloudstudio/ui/markdown": uiSrc("markdown/index.ts"),
+              "@recloudstudio/ui": uiSrc("index.ts"),
+            },
           },
           // Dev 下 SSR 同样走源码，避免服务端 external 到 dist 造成双实例。
-          ssr: { noExternal: [/^@recloudstudio\/ui(\/.*)?$/] }
+          ssr: { noExternal: [/^@recloudstudio\/ui(\/.*)?$/] },
         }
-      : {})
+      : {}),
   },
   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 || ''
-    }
+      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'
-})
+  compatibilityDate: "2026-10-02",
+});
diff --git a/apps/playground/pages/components/markdown.vue b/apps/playground/pages/components/markdown.vue
new file mode 100644
index 0000000..689924a
--- /dev/null
+++ b/apps/playground/pages/components/markdown.vue
@@ -0,0 +1,121 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader
+      title="Markdown 渲染系统"
+      description="基于 unified/remark 与 ReCloud UI 内容原语的受控 Markdown/GFM 渲染系统，内置锚点标题、Shiki 代码高亮、表格、任务列表以及 :::info / :::steps / :::code-group 等文档扩展指令。"
+    />
+
+    <DocExample
+      title="全功能示例文档"
+      description="直接将 Markdown 字符串渲染为 ReCloud 设计系统的富文本、代码块与扩展容器，同时支持目录（TOC）联动。"
+      :code="sampleMarkdown"
+    >
+      <div class="grid grid-cols-1 gap-8 lg:grid-cols-4">
+        <div class="lg:col-span-3">
+          <div class="rounded-xl border border-slate-200/80 bg-white p-6 shadow-sm dark:border-slate-800 dark:bg-[#0B1220]">
+            <MarkdownRenderer :content="sampleMarkdown" @headings="headings = $event" />
+          </div>
+        </div>
+        <div class="lg:col-span-1">
+          <div class="sticky top-20 rounded-xl border border-slate-200/80 bg-white p-4 shadow-sm dark:border-slate-800 dark:bg-[#0B1220]">
+            <Toc :items="headings" />
+          </div>
+        </div>
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="安全策略与协议过滤"
+      description="默认开启严格的协议过滤与安全策略，阻止 javascript: 协议并规范化外部链接。"
+      :code="unsafeSample"
+    >
+      <div class="rounded-xl border border-slate-200/80 bg-white p-6 shadow-sm dark:border-slate-800 dark:bg-[#0B1220]">
+        <MarkdownRenderer :content="unsafeSample" />
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="markdown" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { MarkdownRenderer, type MarkdownHeading } from '@recloudstudio/ui/markdown'
+
+const headings = ref<MarkdownHeading[]>([])
+
+const sampleMarkdown = `# 快速上手 ReCloud UI
+
+ReCloud UI 提供面向开发者控制台与文档系统的全套高保真组件。
+
+## 安装指南
+
+你可以通过常用的包管理器安装核心库与样式：
+
+:::code-group
+
+\`\`\`bash [bun]
+bun add @recloudstudio/ui
+\`\`\`
+
+\`\`\`bash [pnpm]
+pnpm add @recloudstudio/ui
+\`\`\`
+
+\`\`\`bash [npm]
+npm install @recloudstudio/ui
+\`\`\`
+
+:::
+
+:::info{title="Nuxt 4 兼容性"}
+该渲染系统完整支持 Nuxt 4 SSR 与客户端 Hydration，静态预渲染期间共享同一个 Shiki 高亮器。
+:::
+
+## 配置步骤
+
+跟随下方步骤完成初始化：
+
+:::steps{startIndex="1"}
+
+:::step{title="注册模块"}
+在 \`nuxt.config.ts\` 中将模块加入 \`modules\` 列表。
+:::
+
+:::step{title="导入样式"}
+如果未使用模块注入，请手动在入口引入 \`@recloudstudio/ui/style.css\`。
+:::
+
+:::step{title="启动开发服务器"}
+运行 \`bun dev\` 打开 Playground 预览。
+:::
+
+:::
+
+## 特性对比
+
+| 特性 | 普通 Markdown | ReCloud Markdown 系统 |
+| :--- | :---: | ---: |
+| 标题锚点 | 否 | 是（支持一键复制） |
+| 代码高亮 | 纯文本/基础样式 | Shiki 进程级多语言高亮 |
+| 交互式指令 | 无 | :::callout, :::steps, :::code-group |
+`
+
+const unsafeSample = `### 安全测试
+
+- [正常链接（新窗口打开）](https://worldexecute.me)
+- [被过滤的恶意脚本链接](javascript:alert('XSS'))
+- 内联代码如 \`const safe = true\` 正确安全呈现。
+`
+
+const apiRows = [
+  { name: 'content', type: 'string', default: "''", description: '原始 Markdown 字符串。' },
+  { name: 'ast', type: 'MarkdownDocument', default: 'undefined', description: '预编译的 AST 树，适用于构建期预解析与静态站缓存。' },
+  { name: 'components', type: 'MarkdownComponentRegistry', default: '{}', description: '自定义节点渲染组件注册表，覆盖标题、段落、代码块、链接等。' },
+  { name: 'baseUrl', type: 'string', default: 'undefined', description: '相对 URL 解析基准路径。' },
+  { name: 'features', type: 'MarkdownFeatures', default: '{}', description: '特性开关，如 gfm、directives、steps、codeGroups。' },
+  { name: 'sanitize', type: 'MarkdownSanitizeOptions | false', default: '{}', description: '安全净化配置，支持自定义允许协议与 HTML 放行策略。' },
+  { name: '@headings', type: '(headings: MarkdownHeading[]) => void', default: '—', description: '提取标题元数据事件，可直接绑定至 Toc 组件。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index f2b4d4f..f66483d 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -1,160 +1,270 @@
 export interface DocItem {
-  name: string
-  title: string
-  description: string
+  name: string;
+  title: string;
+  description: string;
 }
 
 export interface DocGroup {
-  label: string
-  items: DocItem[]
+  label: string;
+  items: DocItem[];
 }
 
 const groups: DocGroup[] = [
   {
-    label: '指南',
-    items: [
-      { name: 'index', title: '介绍', description: 'ReCloud UI 设计哲学与快速开始。' }
-    ]
+    label: "指南",
+    items: [{ name: "index", title: "介绍", description: "ReCloud UI 设计哲学与快速开始。" }],
   },
   {
-    label: 'Design Tokens',
+    label: "Design Tokens",
     items: [
-      { name: 'colors', title: '色彩与渐变', description: '品牌色度刻度与 180° 垂直天蓝渐变。' }
-    ]
+      { name: "colors", title: "色彩与渐变", description: "品牌色度刻度与 180° 垂直天蓝渐变。" },
+    ],
   },
   {
-    label: '通用',
+    label: "通用",
     items: [
-      { name: 'button', title: 'Button 按钮', description: '六种视觉层级，覆盖主操作与低干扰链接。' },
-      { name: 'badge', title: 'Badge 徽章', description: '轻量状态标签与版本标记。' },
-      { name: 'banner', title: 'Banner 横幅', description: '维护预警与安全事件通告条。' },
-      { name: 'card', title: 'Card 卡片', description: '内容容器与分割线层级。' },
-      { name: 'avatar', title: 'Avatar 头像', description: '图像、降级文本与在线状态。' },
-      { name: 'kbd', title: 'Kbd 按键提示', description: '快捷键视觉化展示。' },
-      { name: 'code-block', title: 'CodeBlock 代码块', description: '带复制、行号和文件标识的代码展示。' },
-      { name: 'spinner', title: 'Spinner 加载', description: '环形加载指示器。' },
-      { name: 'icon', title: 'Icon 图标', description: '支持组件、图标库前缀、内联 SVG 与图片的多源图标渲染体系。' }
-    ]
+      {
+        name: "button",
+        title: "Button 按钮",
+        description: "六种视觉层级，覆盖主操作与低干扰链接。",
+      },
+      { name: "badge", title: "Badge 徽章", description: "轻量状态标签与版本标记。" },
+      { name: "banner", title: "Banner 横幅", description: "维护预警与安全事件通告条。" },
+      { name: "card", title: "Card 卡片", description: "内容容器与分割线层级。" },
+      { name: "avatar", title: "Avatar 头像", description: "图像、降级文本与在线状态。" },
+      { name: "kbd", title: "Kbd 按键提示", description: "快捷键视觉化展示。" },
+      {
+        name: "code-block",
+        title: "CodeBlock 代码块",
+        description: "带复制、行号和文件标识的代码展示。",
+      },
+      { name: "spinner", title: "Spinner 加载", description: "环形加载指示器。" },
+      {
+        name: "icon",
+        title: "Icon 图标",
+        description: "支持组件、图标库前缀、内联 SVG 与图片的多源图标渲染体系。",
+      },
+    ],
   },
   {
-    label: '表单',
+    label: "表单",
     items: [
-      { name: 'field', title: 'Field / Form 表单布局', description: '统一关联标签、说明、错误信息与表单间距。' },
-      { name: 'input', title: 'Input 输入框', description: '带标签、提示与错误态的文本输入。' },
-      { name: 'tag-input', title: 'TagInput 标签输入', description: '可添加、删除与粘贴多个标签。' },
-      { name: 'textarea', title: 'Textarea 文本域', description: '多行文本输入。' },
-      { name: 'select', title: 'Select 选择器', description: '无障碍下拉选择。' },
-      { name: 'checkbox', title: 'Checkbox 复选框', description: '布尔开关复选项。' },
-      { name: 'switch', title: 'Switch 开关', description: '即时生效的切换开关。' },
-      { name: 'radio-group', title: 'RadioGroup 单选组', description: '带描述的选项组。' },
-      { name: 'slider', title: 'Slider 滑块', description: '单值/区间滑动输入。' },
-      { 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: '按压态工具按钮与分组。' },
-      { name: 'label', title: 'Label 标签', description: '表单控件关联标签。' },
-      { name: 'date-picker', title: 'DatePicker 日期选择', description: '单日期与日期范围筛选。' }
-    ]
+      {
+        name: "field",
+        title: "Field / Form 表单布局",
+        description: "统一关联标签、说明、错误信息与表单间距。",
+      },
+      { name: "input", title: "Input 输入框", description: "带标签、提示与错误态的文本输入。" },
+      {
+        name: "tag-input",
+        title: "TagInput 标签输入",
+        description: "可添加、删除与粘贴多个标签。",
+      },
+      { name: "textarea", title: "Textarea 文本域", description: "多行文本输入。" },
+      { name: "select", title: "Select 选择器", description: "无障碍下拉选择。" },
+      { name: "checkbox", title: "Checkbox 复选框", description: "布尔开关复选项。" },
+      { name: "switch", title: "Switch 开关", description: "即时生效的切换开关。" },
+      { name: "radio-group", title: "RadioGroup 单选组", description: "带描述的选项组。" },
+      { name: "slider", title: "Slider 滑块", description: "单值/区间滑动输入。" },
+      { 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: "按压态工具按钮与分组。" },
+      { name: "label", title: "Label 标签", description: "表单控件关联标签。" },
+      { name: "date-picker", title: "DatePicker 日期选择", description: "单日期与日期范围筛选。" },
+    ],
   },
   {
-    label: '数据展示',
+    label: "数据展示",
     items: [
-      { name: 'data-table', title: 'DataTable 数据表', description: '列插槽富单元格渲染。' },
-      { 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: '水平与垂直分隔。' },
-      { name: 'timeline', title: 'Timeline 时间线', description: '操作日志与变更历史。' }
-    ]
+      { name: "data-table", title: "DataTable 数据表", description: "列插槽富单元格渲染。" },
+      { 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: "水平与垂直分隔。" },
+      { name: "timeline", title: "Timeline 时间线", description: "操作日志与变更历史。" },
+    ],
   },
   {
-    label: '导航',
+    label: "导航",
     items: [
-      { name: 'tabs', title: 'Tabs 标签页', description: '视图切换标签。' },
-      { name: 'pagination', title: 'Pagination 分页', description: '页码与前后翻页。' },
-      { name: 'breadcrumb', title: 'Breadcrumb 面包屑', description: '层级路径导航。' },
-      { 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: '可拖拽、可键盘调整的工作区分栏。' }
-    ]
+      { name: "tabs", title: "Tabs 标签页", description: "视图切换标签。" },
+      { name: "pagination", title: "Pagination 分页", description: "页码与前后翻页。" },
+      { name: "breadcrumb", title: "Breadcrumb 面包屑", description: "层级路径导航。" },
+      { 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: "可拖拽、可键盘调整的工作区分栏。",
+      },
+    ],
   },
   {
-    label: '折叠披露',
+    label: "折叠披露",
     items: [
-      { name: 'accordion', title: 'Accordion 手风琴', description: '单开/多开问答折叠。' },
-      { name: 'collapsible', title: 'CollapsiblePanel 折叠面板', description: '高级选项渐进披露。' }
-    ]
+      { name: "accordion", title: "Accordion 手风琴", description: "单开/多开问答折叠。" },
+      {
+        name: "collapsible",
+        title: "CollapsiblePanel 折叠面板",
+        description: "高级选项渐进披露。",
+      },
+    ],
   },
   {
-    label: '浮层反馈',
+    label: "浮层反馈",
     items: [
-      { name: 'dialog', title: 'Dialog 对话框', description: '模态确认与表单弹层。' },
-      { name: 'alert-dialog', title: 'AlertDialog 警示对话框', description: '破坏性操作二次确认。' },
-      { name: 'dropdown-menu', title: 'DropdownMenu 下拉菜单', description: '操作菜单与快捷键提示。' },
-      { name: 'context-menu', title: 'ContextMenu 右键菜单', description: '区域右键操作。' },
-      { name: 'tooltip', title: 'Tooltip 文字提示', description: '悬停即时提示。' },
-      { name: 'popover', title: 'Popover 浮层', description: '轻量内容弹层。' },
-      { name: 'hover-card', title: 'HoverCard 悬停卡片', description: '预览用户信息卡。' },
-      { name: 'toast', title: 'Toast 吐司提示', description: '全局操作反馈队列。' },
-      { name: 'sheet', title: 'Sheet 抽屉面板', description: '资源详情、配置与辅助操作面板。' }
-    ]
+      { name: "dialog", title: "Dialog 对话框", description: "模态确认与表单弹层。" },
+      {
+        name: "alert-dialog",
+        title: "AlertDialog 警示对话框",
+        description: "破坏性操作二次确认。",
+      },
+      {
+        name: "dropdown-menu",
+        title: "DropdownMenu 下拉菜单",
+        description: "操作菜单与快捷键提示。",
+      },
+      { name: "context-menu", title: "ContextMenu 右键菜单", description: "区域右键操作。" },
+      { name: "tooltip", title: "Tooltip 文字提示", description: "悬停即时提示。" },
+      { name: "popover", title: "Popover 浮层", description: "轻量内容弹层。" },
+      { name: "hover-card", title: "HoverCard 悬停卡片", description: "预览用户信息卡。" },
+      { name: "toast", title: "Toast 吐司提示", description: "全局操作反馈队列。" },
+      { name: "sheet", title: "Sheet 抽屉面板", description: "资源详情、配置与辅助操作面板。" },
+    ],
   },
   {
-    label: '文档排版',
+    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: '多包管理器与多语言代码块选项卡容器。' }
-    ]
+      {
+        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: "多包管理器与多语言代码块选项卡容器。",
+      },
+      {
+        name: "markdown",
+        title: "Markdown 渲染系统",
+        description: "面向开发者文档的受控 Markdown/GFM 与扩展指令渲染器。",
+      },
+    ],
   },
   {
-    label: '营销与门户',
+    label: "营销与门户",
     items: [
-      { name: 'navbar', title: 'Navbar 导航顶栏', description: '站点级全局顶栏，集成品牌标识、链接、操作与移动端抽屉。' },
-      { name: 'footer', title: 'Footer 站点页脚', description: '多列分组链接、版权信息与社交链接插槽。' },
-      { name: 'hero', title: 'Hero 首屏横幅', description: '落地页与产品首页主视觉横幅，支持居中、图文左右分栏及极简模式。' }
-    ]
+      {
+        name: "navbar",
+        title: "Navbar 导航顶栏",
+        description: "站点级全局顶栏，集成品牌标识、链接、操作与移动端抽屉。",
+      },
+      {
+        name: "footer",
+        title: "Footer 站点页脚",
+        description: "多列分组链接、版权信息与社交链接插槽。",
+      },
+      {
+        name: "hero",
+        title: "Hero 首屏横幅",
+        description: "落地页与产品首页主视觉横幅，支持居中、图文左右分栏及极简模式。",
+      },
+    ],
   },
   {
-    label: '工具',
+    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: '屏幕阅读器专用。' }
-    ]
-  }
-]
+      {
+        name: "locale",
+        title: "i18n 国际化",
+        description: "组件库内置文案注入、双语包与动态切换。",
+      },
+      { name: "scroll-area", title: "ScrollArea 滚动区", description: "自定义滚动条容器。" },
+      { name: "aspect-ratio", title: "AspectRatio 宽高比", description: "固定比例容器。" },
+      {
+        name: "visually-hidden",
+        title: "VisuallyHidden 隐藏文本",
+        description: "屏幕阅读器专用。",
+      },
+    ],
+  },
+];
 
 /** 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'))
-}))
+  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 const flatDocs = docGroups.flatMap((g) => g.items.map((i) => ({ ...i, group: g.label })));
 
 export function docPath(name: string): string {
-  return name === 'index' ? '/' : `/components/${name}`
+  return name === "index" ? "/" : `/components/${name}`;
 }
 
-export function adjacentDocs(name: string): { prev?: { name: string; title: string }; next?: { name: string; title: string } } {
-  const idx = flatDocs.findIndex((d) => d.name === name)
+export function adjacentDocs(name: string): {
+  prev?: { name: string; title: string };
+  next?: { name: string; title: string };
+} {
+  const idx = flatDocs.findIndex((d) => d.name === name);
   return {
     prev: idx > 0 ? flatDocs[idx - 1] : undefined,
-    next: idx >= 0 && idx < flatDocs.length - 1 ? flatDocs[idx + 1] : undefined
-  }
+    next: idx >= 0 && idx < flatDocs.length - 1 ? flatDocs[idx + 1] : undefined,
+  };
 }

From a1748e5241f27f1b6d353ac083115653cecbd9a7 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 23:31:18 +0800
Subject: [PATCH 10/17] fix(playground): remove max-width constraint on main
 container

---
 apps/playground/app.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/playground/app.vue b/apps/playground/app.vue
index 87a9eaa..6f98729 100644
--- a/apps/playground/app.vue
+++ b/apps/playground/app.vue
@@ -72,7 +72,7 @@
         </nav>
       </div>
 
-      <main class="flex-1 min-w-0 max-w-3xl">
+      <main class="flex-1 min-w-0">
         <NuxtPage />
       </main>
     </div>

From 643e59fa88bd5f909ab9d932265acb0c890b2539 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 23:54:32 +0800
Subject: [PATCH 11/17] feat(ui): add Container, Section, and ThemeToggle

---
 .changeset/calm-containers-toggle.md          |   5 +
 .../ui/src/components/container/Container.vue |  32 +++++
 .../components/container/container.test.ts    |  21 +++
 packages/ui/src/components/container/index.ts |   2 +
 packages/ui/src/components/container/types.ts |  29 ++++
 .../ui/src/components/section/Section.vue     |  85 +++++++++++
 packages/ui/src/components/section/index.ts   |   2 +
 .../ui/src/components/section/section.test.ts |  24 ++++
 packages/ui/src/components/section/types.ts   |  59 ++++++++
 .../components/theme-toggle/ThemeToggle.vue   | 134 ++++++++++++++++++
 .../ui/src/components/theme-toggle/index.ts   |   2 +
 .../theme-toggle/themeToggle.test.ts          |  26 ++++
 .../ui/src/components/theme-toggle/types.ts   |  38 +++++
 packages/ui/src/index.ts                      |   3 +
 14 files changed, 462 insertions(+)
 create mode 100644 .changeset/calm-containers-toggle.md
 create mode 100644 packages/ui/src/components/container/Container.vue
 create mode 100644 packages/ui/src/components/container/container.test.ts
 create mode 100644 packages/ui/src/components/container/index.ts
 create mode 100644 packages/ui/src/components/container/types.ts
 create mode 100644 packages/ui/src/components/section/Section.vue
 create mode 100644 packages/ui/src/components/section/index.ts
 create mode 100644 packages/ui/src/components/section/section.test.ts
 create mode 100644 packages/ui/src/components/section/types.ts
 create mode 100644 packages/ui/src/components/theme-toggle/ThemeToggle.vue
 create mode 100644 packages/ui/src/components/theme-toggle/index.ts
 create mode 100644 packages/ui/src/components/theme-toggle/themeToggle.test.ts
 create mode 100644 packages/ui/src/components/theme-toggle/types.ts

diff --git a/.changeset/calm-containers-toggle.md b/.changeset/calm-containers-toggle.md
new file mode 100644
index 0000000..f64d186
--- /dev/null
+++ b/.changeset/calm-containers-toggle.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add Container, Section, and ThemeToggle components for unified responsive page layouts and ready-to-use theme toggles.
diff --git a/packages/ui/src/components/container/Container.vue b/packages/ui/src/components/container/Container.vue
new file mode 100644
index 0000000..7a9b59a
--- /dev/null
+++ b/packages/ui/src/components/container/Container.vue
@@ -0,0 +1,32 @@
+<template>
+  <component
+    :is="as"
+    :class="[
+      'mx-auto w-full',
+      sizeClasses[size],
+      padded ? 'px-4 sm:px-6 lg:px-8' : '',
+      props.class
+    ]"
+  >
+    <slot />
+  </component>
+</template>
+
+<script setup lang="ts">
+import type { ContainerProps, ContainerSize } from './types'
+
+const props = withDefaults(defineProps<ContainerProps>(), {
+  as: 'div',
+  size: 'xl',
+  padded: true
+})
+
+const sizeClasses: Record<ContainerSize, string> = {
+  sm: 'max-w-2xl',
+  md: 'max-w-4xl',
+  lg: 'max-w-6xl',
+  xl: 'max-w-7xl',
+  '2xl': 'max-w-screen-2xl',
+  full: 'max-w-none'
+}
+</script>
diff --git a/packages/ui/src/components/container/container.test.ts b/packages/ui/src/components/container/container.test.ts
new file mode 100644
index 0000000..c14d673
--- /dev/null
+++ b/packages/ui/src/components/container/container.test.ts
@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = readFileSync(fileURLToPath(new URL("./Container.vue", import.meta.url)), "utf8");
+
+describe("Container component contract", () => {
+  it("supports max-width size options and padding rhythm", () => {
+    expect(source).toContain("sizeClasses[size]");
+    expect(source).toContain("padded ? 'px-4 sm:px-6 lg:px-8' : ''");
+    expect(source).toContain("size: 'xl'");
+    expect(source).toContain("as: 'div'");
+  });
+
+  it("provides comprehensive size maps", () => {
+    expect(source).toContain("max-w-2xl");
+    expect(source).toContain("max-w-4xl");
+    expect(source).toContain("max-w-7xl");
+    expect(source).toContain("max-w-screen-2xl");
+  });
+});
diff --git a/packages/ui/src/components/container/index.ts b/packages/ui/src/components/container/index.ts
new file mode 100644
index 0000000..baaa9c2
--- /dev/null
+++ b/packages/ui/src/components/container/index.ts
@@ -0,0 +1,2 @@
+export { default as Container } from "./Container.vue";
+export * from "./types";
diff --git a/packages/ui/src/components/container/types.ts b/packages/ui/src/components/container/types.ts
new file mode 100644
index 0000000..2e91777
--- /dev/null
+++ b/packages/ui/src/components/container/types.ts
@@ -0,0 +1,29 @@
+export type ContainerSize = "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+
+export interface ContainerProps {
+  /**
+   * HTML element to render the container as.
+   * @default 'div'
+   */
+  as?: string;
+  /**
+   * Max width constraint of the container.
+   * - `sm`: max-w-screen-sm (~640px)
+   * - `md`: max-w-screen-md (~768px)
+   * - `lg`: max-w-screen-lg (~1024px)
+   * - `xl`: max-w-screen-xl (~1280px / 7xl)
+   * - `2xl`: max-w-screen-2xl (~1536px)
+   * - `full`: max-w-none (full width)
+   * @default 'xl'
+   */
+  size?: ContainerSize;
+  /**
+   * Horizontal padding rhythm.
+   * @default true
+   */
+  padded?: boolean;
+  /**
+   * Additional classes.
+   */
+  class?: string;
+}
diff --git a/packages/ui/src/components/section/Section.vue b/packages/ui/src/components/section/Section.vue
new file mode 100644
index 0000000..ac969e4
--- /dev/null
+++ b/packages/ui/src/components/section/Section.vue
@@ -0,0 +1,85 @@
+<template>
+  <component
+    :is="as"
+    :class="[
+      'w-full transition-colors relative',
+      variantClasses[variant],
+      spacingClasses[spacing],
+      props.class
+    ]"
+  >
+    <!-- Built-in Container wrap -->
+    <Container v-if="container" :size="containerSize">
+      <!-- Section Header if title / description / slots present -->
+      <div
+        v-if="title || description || $slots.header || $slots.title || $slots.description"
+        :class="[
+          'mb-8 sm:mb-12',
+          align === 'center' ? 'mx-auto max-w-3xl text-center' : 'max-w-3xl text-left'
+        ]"
+      >
+        <slot name="header">
+          <h2 v-if="title || $slots.title" class="text-2xl font-bold tracking-tight text-[color:var(--foreground)] sm:text-3xl lg:text-4xl">
+            <slot name="title">{{ title }}</slot>
+          </h2>
+          <p v-if="description || $slots.description" class="mt-3 text-base text-[color:var(--muted-foreground)] sm:text-lg">
+            <slot name="description">{{ description }}</slot>
+          </p>
+        </slot>
+      </div>
+
+      <slot />
+    </Container>
+
+    <!-- Raw content slot without Container -->
+    <template v-else>
+      <div
+        v-if="title || description || $slots.header || $slots.title || $slots.description"
+        :class="[
+          'mb-8 sm:mb-12 px-4 sm:px-6 lg:px-8',
+          align === 'center' ? 'mx-auto max-w-3xl text-center' : 'max-w-3xl text-left'
+        ]"
+      >
+        <slot name="header">
+          <h2 v-if="title || $slots.title" class="text-2xl font-bold tracking-tight text-[color:var(--foreground)] sm:text-3xl lg:text-4xl">
+            <slot name="title">{{ title }}</slot>
+          </h2>
+          <p v-if="description || $slots.description" class="mt-3 text-base text-[color:var(--muted-foreground)] sm:text-lg">
+            <slot name="description">{{ description }}</slot>
+          </p>
+        </slot>
+      </div>
+
+      <slot />
+    </template>
+  </component>
+</template>
+
+<script setup lang="ts">
+import Container from '../container/Container.vue'
+import type { SectionProps, SectionSpacing, SectionVariant } from './types'
+
+const props = withDefaults(defineProps<SectionProps>(), {
+  as: 'section',
+  variant: 'default',
+  spacing: 'md',
+  container: true,
+  containerSize: 'xl',
+  align: 'center'
+})
+
+const variantClasses: Record<SectionVariant, string> = {
+  default: 'bg-transparent',
+  muted: 'bg-[color:var(--surface-muted)]/50',
+  card: 'bg-[color:var(--card)] border-y border-[color:var(--border)]',
+  brand: 'bg-gradient-to-b from-[color:var(--primary)]/10 via-[color:var(--primary)]/5 to-transparent'
+}
+
+const spacingClasses: Record<SectionSpacing, string> = {
+  none: 'py-0',
+  sm: 'py-8 sm:py-12',
+  md: 'py-12 sm:py-16',
+  lg: 'py-16 sm:py-24',
+  xl: 'py-20 sm:py-32'
+}
+</script>
diff --git a/packages/ui/src/components/section/index.ts b/packages/ui/src/components/section/index.ts
new file mode 100644
index 0000000..18e0649
--- /dev/null
+++ b/packages/ui/src/components/section/index.ts
@@ -0,0 +1,2 @@
+export { default as Section } from "./Section.vue";
+export * from "./types";
diff --git a/packages/ui/src/components/section/section.test.ts b/packages/ui/src/components/section/section.test.ts
new file mode 100644
index 0000000..a3125f3
--- /dev/null
+++ b/packages/ui/src/components/section/section.test.ts
@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = readFileSync(fileURLToPath(new URL("./Section.vue", import.meta.url)), "utf8");
+
+describe("Section component contract", () => {
+  it("supports spacing and variant tokens", () => {
+    expect(source).toContain("variantClasses[variant]");
+    expect(source).toContain("spacingClasses[spacing]");
+    expect(source).toContain("spacing: 'md'");
+  });
+
+  it("embeds Container when enabled", () => {
+    expect(source).toContain('<Container v-if="container"');
+    expect(source).toContain(':size="containerSize"');
+  });
+
+  it("provides header and title slot customization", () => {
+    expect(source).toContain('<slot name="header">');
+    expect(source).toContain('<slot name="title">{{ title }}</slot>');
+    expect(source).toContain('<slot name="description">{{ description }}</slot>');
+  });
+});
diff --git a/packages/ui/src/components/section/types.ts b/packages/ui/src/components/section/types.ts
new file mode 100644
index 0000000..a700d11
--- /dev/null
+++ b/packages/ui/src/components/section/types.ts
@@ -0,0 +1,59 @@
+import type { ContainerSize } from "../container/types";
+
+export type SectionSpacing = "none" | "sm" | "md" | "lg" | "xl";
+export type SectionVariant = "default" | "muted" | "card" | "brand";
+
+export interface SectionProps {
+  /**
+   * HTML element to render the section as.
+   * @default 'section'
+   */
+  as?: string;
+  /**
+   * Background and surface variant of the section.
+   * - `default`: transparent / semantic canvas
+   * - `muted`: subtle surface background (`--surface-muted`)
+   * - `card`: card surface with border (`--card`)
+   * - `brand`: primary brand gradient / tint
+   * @default 'default'
+   */
+  variant?: SectionVariant;
+  /**
+   * Vertical padding rhythm.
+   * - `none`: py-0
+   * - `sm`: py-8 sm:py-12
+   * - `md`: py-12 sm:py-16
+   * - `lg`: py-16 sm:py-24
+   * - `xl`: py-20 sm:py-32
+   * @default 'md'
+   */
+  spacing?: SectionSpacing;
+  /**
+   * Whether to wrap children in a built-in `<Container>`.
+   * Pass `false` if the section needs full-bleed custom layout.
+   * @default true
+   */
+  container?: boolean;
+  /**
+   * Container max-width size when `container` is true.
+   * @default 'xl'
+   */
+  containerSize?: ContainerSize;
+  /**
+   * Optional section title in a built-in header.
+   */
+  title?: string;
+  /**
+   * Optional section subtitle or description.
+   */
+  description?: string;
+  /**
+   * Text alignment for built-in section header.
+   * @default 'center'
+   */
+  align?: "left" | "center";
+  /**
+   * Additional classes for the outer section element.
+   */
+  class?: string;
+}
diff --git a/packages/ui/src/components/theme-toggle/ThemeToggle.vue b/packages/ui/src/components/theme-toggle/ThemeToggle.vue
new file mode 100644
index 0000000..951d963
--- /dev/null
+++ b/packages/ui/src/components/theme-toggle/ThemeToggle.vue
@@ -0,0 +1,134 @@
+<template>
+  <!-- Variant: Dropdown Menu (Light / Dark / System) -->
+  <div v-if="variant === 'dropdown'" :class="['relative inline-flex items-center', props.class]">
+    <select
+      :value="currentMode"
+      :aria-label="ariaLabel || '选择主题模式'"
+      :class="[
+        'rounded-lg border border-[color:var(--border)] bg-[color:var(--card)] text-[color:var(--foreground)] transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)] cursor-pointer',
+        dropdownSizeClasses[size]
+      ]"
+      @change="onSelectMode(($event.target as HTMLSelectElement).value as ThemeMode)"
+    >
+      <option value="light">浅色模式</option>
+      <option value="dark">深色模式</option>
+      <option value="system">跟随系统</option>
+    </select>
+  </div>
+
+  <!-- Variant: Icon Button (Default) -->
+  <button
+    v-else
+    type="button"
+    :class="[
+      'inline-flex items-center justify-center rounded-lg border border-transparent text-[color:var(--muted-foreground)] hover:bg-[color:var(--surface-muted)] hover:text-[color:var(--foreground)] transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ring)] cursor-pointer',
+      buttonSizeClasses[size],
+      props.class
+    ]"
+    :aria-label="computedAriaLabel"
+    :title="computedAriaLabel"
+    @click="handleToggle"
+  >
+    <slot :mode="currentMode" :is-dark="effectiveIsDark" :resolved-mode="effectiveResolvedMode">
+      <!-- Sun icon (when dark, clicking switches to light) -->
+      <Sun v-if="effectiveIsDark" :class="iconSizeClasses[size]" class="text-amber-400" />
+      <!-- Moon icon (when light, clicking switches to dark) -->
+      <Moon v-else :class="iconSizeClasses[size]" class="text-slate-600 dark:text-slate-300" />
+    </slot>
+  </button>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Sun, Moon } from '../../icons'
+import { useTheme, type ThemeMode, type ResolvedThemeMode } from '../../composables/useTheme'
+import type { ThemeToggleProps, ThemeToggleSize } from './types'
+
+const props = withDefaults(defineProps<ThemeToggleProps>(), {
+  variant: 'button',
+  size: 'md',
+  cycleSystem: false
+})
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', value: ThemeMode): void
+  (e: 'change', value: ThemeMode): void
+}>()
+
+const theme = useTheme()
+
+const isControlled = computed(() => props.modelValue !== undefined)
+
+const currentMode = computed<ThemeMode>(() => {
+  if (isControlled.value) {
+    return props.modelValue ?? 'system'
+  }
+  return theme.mode.value
+})
+
+const effectiveResolvedMode = computed<ResolvedThemeMode>(() => {
+  if (isControlled.value) {
+    if (currentMode.value === 'dark') return 'dark'
+    if (currentMode.value === 'light') return 'light'
+    return theme.resolvedMode.value
+  }
+  return theme.resolvedMode.value
+})
+
+const effectiveIsDark = computed<boolean>(() => effectiveResolvedMode.value === 'dark')
+
+const computedAriaLabel = computed(() => {
+  if (props.ariaLabel) return props.ariaLabel
+  if (props.cycleSystem) {
+    return `当前主题：${currentMode.value === 'dark' ? '深色' : currentMode.value === 'light' ? '浅色' : '系统'}，点击切换`
+  }
+  return effectiveIsDark.value ? '切换至浅色模式' : '切换至深色模式'
+})
+
+const buttonSizeClasses: Record<ThemeToggleSize, string> = {
+  sm: 'h-8 w-8 p-1.5 text-xs',
+  md: 'h-9 w-9 p-2 text-sm',
+  lg: 'h-10 w-10 p-2.5 text-base'
+}
+
+const iconSizeClasses: Record<ThemeToggleSize, string> = {
+  sm: 'w-3.5 h-3.5',
+  md: 'w-4 h-4',
+  lg: 'w-5 h-5'
+}
+
+const dropdownSizeClasses: Record<ThemeToggleSize, string> = {
+  sm: 'px-2 py-1 text-xs',
+  md: 'px-2.5 py-1.5 text-sm',
+  lg: 'px-3 py-2 text-base'
+}
+
+function setNextMode(nextMode: ThemeMode) {
+  if (isControlled.value) {
+    emit('update:modelValue', nextMode)
+  } else {
+    theme.setMode(nextMode)
+  }
+  emit('change', nextMode)
+}
+
+function handleToggle() {
+  if (props.cycleSystem) {
+    const cycleMap: Record<string, ThemeMode> = {
+      light: 'dark',
+      dark: 'system',
+      system: 'light',
+      auto: 'light'
+    }
+    const next = cycleMap[currentMode.value] ?? 'light'
+    setNextMode(next)
+  } else {
+    const next: ThemeMode = effectiveIsDark.value ? 'light' : 'dark'
+    setNextMode(next)
+  }
+}
+
+function onSelectMode(mode: ThemeMode) {
+  setNextMode(mode)
+}
+</script>
diff --git a/packages/ui/src/components/theme-toggle/index.ts b/packages/ui/src/components/theme-toggle/index.ts
new file mode 100644
index 0000000..82c4f9b
--- /dev/null
+++ b/packages/ui/src/components/theme-toggle/index.ts
@@ -0,0 +1,2 @@
+export { default as ThemeToggle } from "./ThemeToggle.vue";
+export * from "./types";
diff --git a/packages/ui/src/components/theme-toggle/themeToggle.test.ts b/packages/ui/src/components/theme-toggle/themeToggle.test.ts
new file mode 100644
index 0000000..c312f08
--- /dev/null
+++ b/packages/ui/src/components/theme-toggle/themeToggle.test.ts
@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = readFileSync(fileURLToPath(new URL("./ThemeToggle.vue", import.meta.url)), "utf8");
+
+describe("ThemeToggle component contract", () => {
+  it("supports button, dropdown, and custom slots", () => {
+    expect(source).toContain("variant === 'dropdown'");
+    expect(source).toContain("<select");
+    expect(source).toContain("<button");
+    expect(source).toContain('<Sun v-if="effectiveIsDark"');
+    expect(source).toContain("<Moon v-else");
+  });
+
+  it("handles controlled and uncontrolled mode resolution", () => {
+    expect(source).toContain("isControlled");
+    expect(source).toContain("emit('update:modelValue', nextMode)");
+    expect(source).toContain("theme.setMode(nextMode)");
+  });
+
+  it("supports cycleSystem mode and accessible aria-label", () => {
+    expect(source).toContain("props.cycleSystem");
+    expect(source).toContain(':aria-label="computedAriaLabel"');
+  });
+});
diff --git a/packages/ui/src/components/theme-toggle/types.ts b/packages/ui/src/components/theme-toggle/types.ts
new file mode 100644
index 0000000..ffa51a3
--- /dev/null
+++ b/packages/ui/src/components/theme-toggle/types.ts
@@ -0,0 +1,38 @@
+import type { ThemeMode } from "../../composables/useTheme";
+
+export type ThemeToggleVariant = "button" | "dropdown" | "switch";
+export type ThemeToggleSize = "sm" | "md" | "lg";
+
+export interface ThemeToggleProps {
+  /**
+   * Component display variant.
+   * - `button`: Icon button toggling between light and dark (or cycling system).
+   * - `dropdown`: Dropdown selecting light, dark, or system.
+   * - `switch`: Switch/toggle style.
+   * @default 'button'
+   */
+  variant?: ThemeToggleVariant;
+  /**
+   * Size of the button or switch.
+   * @default 'md'
+   */
+  size?: ThemeToggleSize;
+  /**
+   * Controlled mode value (`v-model`). If omitted, uses global `useTheme()`.
+   */
+  modelValue?: ThemeMode;
+  /**
+   * Whether clicking button cycles between 'light' -> 'dark' -> 'system'.
+   * If false, toggles between 'light' and 'dark'.
+   * @default false
+   */
+  cycleSystem?: boolean;
+  /**
+   * Custom aria-label override.
+   */
+  ariaLabel?: string;
+  /**
+   * Additional classes.
+   */
+  class?: string;
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 5d92700..2f0f69b 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -69,6 +69,9 @@ export * from "./components/code-group";
 export * from "./components/navbar";
 export * from "./components/footer";
 export * from "./components/hero";
+export * from "./components/container";
+export * from "./components/section";
+export * from "./components/theme-toggle";
 export * from "./components/icon";
 export * from "./markdown";
 

From 25bcfed3c8652ff58c8d853553719139e7ba1c0f Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 5 Oct 2026 23:54:42 +0800
Subject: [PATCH 12/17] docs(playground): document layout and toggle

---
 .../playground/pages/components/container.vue | 66 +++++++++++++
 apps/playground/pages/components/section.vue  | 99 +++++++++++++++++++
 .../pages/components/theme-toggle.vue         | 66 +++++++++++++
 apps/playground/utils/catalog.ts              | 15 +++
 4 files changed, 246 insertions(+)
 create mode 100644 apps/playground/pages/components/container.vue
 create mode 100644 apps/playground/pages/components/section.vue
 create mode 100644 apps/playground/pages/components/theme-toggle.vue

diff --git a/apps/playground/pages/components/container.vue b/apps/playground/pages/components/container.vue
new file mode 100644
index 0000000..19ab2f3
--- /dev/null
+++ b/apps/playground/pages/components/container.vue
@@ -0,0 +1,66 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader
+      title="Container 页面容器"
+      description="规范响应式最大宽度（sm、md、lg、xl、2xl、full）与水平内边距节奏的页面级排版容器，常与 Section、Navbar 或文档主体配合使用。"
+    />
+
+    <DocExample
+      title="基础容器与尺寸对比"
+      description="内置 max-w 尺寸预设与响应式水平 padding（px-4 sm:px-6 lg:px-8），保持全站对齐统一。"
+      :code="rcCode0"
+    >
+      <div class="space-y-4">
+        <Container size="sm" class="rounded-xl border border-dashed border-slate-300 bg-white p-4 text-center text-sm font-medium dark:border-slate-700 dark:bg-[#0B1220]">
+          Container (sm · max-w-2xl)
+        </Container>
+        <Container size="md" class="rounded-xl border border-dashed border-slate-300 bg-white p-4 text-center text-sm font-medium dark:border-slate-700 dark:bg-[#0B1220]">
+          Container (md · max-w-4xl)
+        </Container>
+        <Container size="lg" class="rounded-xl border border-dashed border-slate-300 bg-white p-4 text-center text-sm font-medium dark:border-slate-700 dark:bg-[#0B1220]">
+          Container (lg · max-w-6xl)
+        </Container>
+        <Container size="xl" class="rounded-xl border border-dashed border-primary-500/50 bg-primary-500/5 p-4 text-center text-sm font-medium text-primary-600 dark:bg-primary-500/10 dark:text-primary-400">
+          Container (xl · max-w-7xl · 默认推荐)
+        </Container>
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="自定义标签与无内边距模式"
+      description="可通过 as 属性渲染为 main/article/section 等语义化标签，并支持 padded: false 实现完全贴边。"
+      :code="rcCode1"
+    >
+      <Container as="article" :padded="false" size="md" class="rounded-xl border border-slate-200 bg-white p-6 shadow-sm dark:border-slate-800 dark:bg-[#0B1220]">
+        <h3 class="text-base font-semibold text-slate-900 dark:text-white">无内边距容器包裹卡片</h3>
+        <p class="mt-2 text-sm text-slate-600 dark:text-slate-400">
+          当内部子元素已具备自身内边距时，禁用容器内边距以避免层叠 padding。
+        </p>
+      </Container>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="container" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Container } from '@recloudstudio/ui'
+
+const rcCode0 = `<Container size="sm">Small Container</Container>
+<Container size="md">Medium Container</Container>
+<Container size="lg">Large Container</Container>
+<Container size="xl">Default XL Container</Container>`
+
+const rcCode1 = `<Container as="article" :padded="false" size="md">
+  <h3>无内边距容器包裹卡片</h3>
+  <p>内容...</p>
+</Container>`
+
+const apiRows = [
+  { name: 'as', type: 'string', default: "'div'", description: '渲染出的底层 HTML 标签。' },
+  { name: 'size', type: "'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'", default: "'xl'", description: '响应式最大宽度限制。' },
+  { name: 'padded', type: 'boolean', default: 'true', description: '是否添加响应式水平内边距（px-4 sm:px-6 lg:px-8）。' },
+  { name: 'class', type: 'any', default: 'undefined', description: '自定义样式类名。' }
+]
+</script>
diff --git a/apps/playground/pages/components/section.vue b/apps/playground/pages/components/section.vue
new file mode 100644
index 0000000..98ee87b
--- /dev/null
+++ b/apps/playground/pages/components/section.vue
@@ -0,0 +1,99 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader
+      title="Section 门户区块"
+      description="具备标准化垂直间距节奏（sm、md、lg、xl）、背景变体（default、muted、card、brand）以及内置标题/副标题的营销与控制台区块容器。"
+    />
+
+    <DocExample
+      title="基础区块与垂直节奏"
+      description="内置 Container 包裹与自适应标题区域，快速搭建规格统一的落地页区块。"
+      :code="rcCode0"
+    >
+      <div class="space-y-6">
+        <Section
+          title="核心能力一览"
+          description="构建现代化多云服务与微服务基础设施的高性能组件套件"
+          variant="muted"
+          spacing="sm"
+          class="rounded-xl border border-slate-200 dark:border-slate-800"
+        >
+          <div class="grid grid-cols-1 gap-4 sm:grid-cols-3">
+            <div class="rounded-lg bg-white p-4 shadow-sm dark:bg-[#0B1220]">
+              <h4 class="font-semibold text-slate-900 dark:text-white">高可靠架构</h4>
+              <p class="mt-1 text-xs text-slate-500">毫秒级故障自动切流与状态恢复</p>
+            </div>
+            <div class="rounded-lg bg-white p-4 shadow-sm dark:bg-[#0B1220]">
+              <h4 class="font-semibold text-slate-900 dark:text-white">开箱即用</h4>
+              <p class="mt-1 text-xs text-slate-500">设计 Tokens 与深浅模式完美契合</p>
+            </div>
+            <div class="rounded-lg bg-white p-4 shadow-sm dark:bg-[#0B1220]">
+              <h4 class="font-semibold text-slate-900 dark:text-white">全栈支持</h4>
+              <p class="mt-1 text-xs text-slate-500">Nuxt 4 / Vue 3 与静态站点一键集成</p>
+            </div>
+          </div>
+        </Section>
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="背景变体与左对齐排版"
+      description="支持 brand 渐变与 card 边框模式，支持左对齐 header。"
+      :code="rcCode1"
+    >
+      <div class="space-y-6">
+        <Section
+          title="开发者至上的 API"
+          description="TypeScript 严格强类型、ARIA 无障碍与完全受控的状态模型"
+          variant="card"
+          align="left"
+          spacing="sm"
+          class="rounded-xl"
+        >
+          <p class="text-sm text-slate-600 dark:text-slate-400">
+            每一个组件都经历了完整的属性校验与键盘交互测试。
+          </p>
+        </Section>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="section" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Section } from '@recloudstudio/ui'
+
+const rcCode0 = `<Section
+  title="核心能力一览"
+  description="构建现代化多云服务与微服务基础设施的高性能组件套件"
+  variant="muted"
+  spacing="sm"
+>
+  <div class="grid grid-cols-3 gap-4">
+    <!-- 子内容 -->
+  </div>
+</Section>`
+
+const rcCode1 = `<Section
+  title="开发者至上的 API"
+  description="TypeScript 严格强类型、ARIA 无障碍与完全受控的状态模型"
+  variant="card"
+  align="left"
+  spacing="sm"
+>
+  <p>内容...</p>
+</Section>`
+
+const apiRows = [
+  { name: 'as', type: 'string', default: "'section'", description: '渲染出的底层 HTML 标签。' },
+  { name: 'variant', type: "'default' | 'muted' | 'card' | 'brand'", default: "'default'", description: '背景底色与边框变体。' },
+  { name: 'spacing', type: "'none' | 'sm' | 'md' | 'lg' | 'xl'", default: "'md'", description: '垂直内边距节奏。' },
+  { name: 'container', type: 'boolean', default: 'true', description: '是否内置 Container 包裹子元素。' },
+  { name: 'containerSize', type: 'ContainerSize', default: "'xl'", description: '内置 Container 的尺寸。' },
+  { name: 'title', type: 'string', default: 'undefined', description: '区块标题文案。' },
+  { name: 'description', type: 'string', default: 'undefined', description: '区块副标题文案。' },
+  { name: 'align', type: "'left' | 'center'", default: "'center'", description: '标题区域文本对齐方向。' }
+]
+</script>
diff --git a/apps/playground/pages/components/theme-toggle.vue b/apps/playground/pages/components/theme-toggle.vue
new file mode 100644
index 0000000..ec97af9
--- /dev/null
+++ b/apps/playground/pages/components/theme-toggle.vue
@@ -0,0 +1,66 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader
+      title="ThemeToggle 主题切换开关"
+      description="开箱即用的主题明暗切换开关，已封装 Sun / Moon 图标、aria-label 状态播报，支持图标按钮、下拉选择以及系统偏好三态轮换模式，可直接嵌入 Navbar 顶栏。"
+    />
+
+    <DocExample
+      title="基础图标切换按钮"
+      description="默认非受控模式，自动与全局 useTheme() 同步并持久化，支持深浅模式互切。"
+      :code="rcCode0"
+    >
+      <div class="flex items-center gap-4">
+        <ThemeToggle size="sm" />
+        <ThemeToggle size="md" />
+        <ThemeToggle size="lg" />
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="循环系统偏好 (cycleSystem)"
+      description="开启 cycleSystem 后，点击将在「浅色 -> 深色 -> 跟随系统」三态之间循环轮播。"
+      :code="rcCode1"
+    >
+      <div class="flex items-center gap-4">
+        <ThemeToggle cycle-system size="md" />
+        <span class="text-sm text-slate-500">点击查看 tooltip 或 aria-label 提示的三态轮换</span>
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="下拉选择变体 (variant=dropdown)"
+      description="以规范的下拉菜单形式明确选择浅色、深色或跟随系统。"
+      :code="rcCode2"
+    >
+      <div class="flex items-center gap-4">
+        <ThemeToggle variant="dropdown" size="sm" />
+        <ThemeToggle variant="dropdown" size="md" />
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="theme-toggle" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ThemeToggle } from '@recloudstudio/ui'
+
+const rcCode0 = `<ThemeToggle size="sm" />
+<ThemeToggle size="md" />
+<ThemeToggle size="lg" />`
+
+const rcCode1 = `<ThemeToggle cycle-system size="md" />`
+
+const rcCode2 = `<ThemeToggle variant="dropdown" size="md" />`
+
+const apiRows = [
+  { name: 'variant', type: "'button' | 'dropdown'", default: "'button'", description: '外观形式，提供按钮式或下拉选择式。' },
+  { name: 'size', type: "'sm' | 'md' | 'lg'", default: "'md'", description: '控件尺寸。' },
+  { name: 'modelValue', type: 'ThemeMode', default: 'undefined', description: '受控模式下的主题值（v-model）。留空则使用全局 useTheme()。' },
+  { name: 'cycleSystem', type: 'boolean', default: 'false', description: '按钮点击是否在 light -> dark -> system 之间三态循环。' },
+  { name: 'ariaLabel', type: 'string', default: 'undefined', description: '自定义无障碍 aria-label 标签。' },
+  { name: '@change', type: '(mode: ThemeMode) => void', default: '—', description: '主题改变事件。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index f66483d..350ff5a 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -225,6 +225,21 @@ const groups: DocGroup[] = [
         title: "Hero 首屏横幅",
         description: "落地页与产品首页主视觉横幅，支持居中、图文左右分栏及极简模式。",
       },
+      {
+        name: "container",
+        title: "Container 页面容器",
+        description: "规范响应式最大宽度与内边距的页面级排版容器。",
+      },
+      {
+        name: "section",
+        title: "Section 门户区块",
+        description: "具备标准垂直间距节奏、背景底色与内置标题插槽的营销区块容器。",
+      },
+      {
+        name: "theme-toggle",
+        title: "ThemeToggle 主题切换开关",
+        description: "可直接嵌入 Navbar 顶栏的主题明暗切换按钮与下拉组件。",
+      },
     ],
   },
   {

From ab2a510c6beb1d28cfcb84051830e484a80022f6 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Tue, 6 Oct 2026 00:16:34 +0800
Subject: [PATCH 13/17] feat(ui): add SearchInput and SearchBox components

---
 .changeset/green-search-inputs.md             |   5 +
 .../components/search-input/SearchInput.vue   | 404 ++++++++++++++++++
 .../ui/src/components/search-input/index.ts   |   3 +
 .../search-input/searchInput.test.ts          |  50 +++
 .../ui/src/components/search-input/types.ts   | 121 ++++++
 packages/ui/src/index.ts                      |   1 +
 6 files changed, 584 insertions(+)
 create mode 100644 .changeset/green-search-inputs.md
 create mode 100644 packages/ui/src/components/search-input/SearchInput.vue
 create mode 100644 packages/ui/src/components/search-input/index.ts
 create mode 100644 packages/ui/src/components/search-input/searchInput.test.ts
 create mode 100644 packages/ui/src/components/search-input/types.ts

diff --git a/.changeset/green-search-inputs.md b/.changeset/green-search-inputs.md
new file mode 100644
index 0000000..dbfda81
--- /dev/null
+++ b/.changeset/green-search-inputs.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add SearchInput and SearchBox components with debounced querying, clearable input, loading state, shortcuts, and suggestions flyout.
diff --git a/packages/ui/src/components/search-input/SearchInput.vue b/packages/ui/src/components/search-input/SearchInput.vue
new file mode 100644
index 0000000..9b3385c
--- /dev/null
+++ b/packages/ui/src/components/search-input/SearchInput.vue
@@ -0,0 +1,404 @@
+<template>
+  <div
+    ref="containerRef"
+    :class="[
+      'group relative inline-flex w-full items-center transition-all',
+      sizeContainerClasses[size],
+      variantClasses[variant],
+      disabled ? 'cursor-not-allowed opacity-50' : '',
+      props.class
+    ]"
+  >
+    <!-- Leading element (Icon or Slot) -->
+    <div class="pointer-events-none flex shrink-0 items-center justify-center text-[color:var(--muted-foreground)]">
+      <slot name="leading">
+        <Search :class="iconSizeClasses[size]" />
+      </slot>
+    </div>
+
+    <!-- Main Input -->
+    <input
+      ref="inputRef"
+      :value="modelValue"
+      type="text"
+      role="searchbox"
+      :aria-label="ariaLabel || placeholder || '搜索'"
+      :placeholder="placeholder"
+      :disabled="disabled"
+      :readonly="readonly"
+      :autocomplete="autocomplete"
+      :aria-expanded="hasDropdown ? isOpen : undefined"
+      :aria-haspopup="hasDropdown ? 'listbox' : undefined"
+      :aria-activedescendant="activeItemId"
+      class="min-w-0 grow bg-transparent font-normal text-[color:var(--foreground)] placeholder:text-[color:var(--muted-foreground)] outline-none disabled:cursor-not-allowed"
+      :class="sizeInputClasses[size]"
+      @input="handleInput"
+      @keydown="handleKeydown"
+      @focus="handleFocus"
+      @blur="handleBlur"
+    />
+
+    <!-- Trailing element (Loading, Clear, Shortcut, or Slot) -->
+    <div class="flex shrink-0 items-center gap-1.5 text-[color:var(--muted-foreground)]">
+      <slot name="trailing">
+        <!-- Loading state -->
+        <slot v-if="loading" name="loading">
+          <Loader2 :class="[iconSizeClasses[size], 'animate-spin text-[color:var(--primary)]']" />
+        </slot>
+
+        <!-- Clear button (when has text and not loading) -->
+        <button
+          v-else-if="clearable && hasValue && !disabled && !readonly"
+          type="button"
+          tabindex="-1"
+          :aria-label="ariaLabel ? `清空${ariaLabel}` : '清空搜索内容'"
+          class="inline-flex items-center justify-center rounded p-0.5 text-[color:var(--muted-foreground)] transition-colors hover:text-[color:var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[color:var(--ring)] cursor-pointer"
+          @click.stop="handleClear"
+        >
+          <slot name="clear">
+            <X :class="iconSizeClasses[size]" />
+          </slot>
+        </button>
+
+        <!-- Shortcut key badge -->
+        <slot v-else-if="shortcut" name="shortcut">
+          <kbd
+            class="inline-flex items-center rounded border border-[color:var(--border)] bg-[color:var(--surface-muted)] px-1.5 py-0.5 font-mono text-[10px] text-[color:var(--muted-foreground)] select-none cursor-pointer hover:border-[color:var(--ring)]"
+            @click="focus"
+          >
+            {{ shortcut }}
+          </kbd>
+        </slot>
+      </slot>
+    </div>
+
+    <!-- Dropdown Results / Suggestions Flyout -->
+    <div
+      v-if="hasDropdown && isOpen"
+      class="absolute left-0 right-0 top-full mt-1.5 z-50 max-h-72 overflow-y-auto rounded-lg border border-[color:var(--border)] bg-[color:var(--card)] p-1.5 shadow-lg backdrop-blur-sm"
+    >
+      <slot name="dropdown" :suggestions="suggestions" :active-index="activeIndex">
+        <!-- Suggestions List -->
+        <div v-if="hasSuggestions" role="listbox" class="space-y-0.5">
+          <button
+            v-for="(item, idx) in suggestions"
+            :id="`search-item-${idx}`"
+            :key="item.id ?? idx"
+            type="button"
+            role="option"
+            :aria-selected="activeIndex === idx"
+            :disabled="item.disabled"
+            :class="[
+              'flex w-full items-center justify-between gap-3 rounded-md px-2.5 py-1.5 text-left text-sm transition-colors outline-none cursor-pointer disabled:pointer-events-none disabled:opacity-50',
+              activeIndex === idx
+                ? 'bg-[color:var(--surface-muted)] text-[color:var(--foreground)]'
+                : 'text-[color:var(--foreground)] hover:bg-[color:var(--surface-muted)]'
+            ]"
+            @mouseenter="activeIndex = idx"
+            @click="handleSelect(item)"
+          >
+            <slot name="item" :item="item" :index="idx" :active="activeIndex === idx">
+              <div class="flex min-w-0 items-center gap-2">
+                <span class="truncate font-medium">{{ item.label }}</span>
+                <span v-if="item.description" class="truncate text-xs text-[color:var(--muted-foreground)]">
+                  {{ item.description }}
+                </span>
+              </div>
+              <span
+                v-if="item.category"
+                class="shrink-0 rounded bg-[color:var(--surface-subtle,var(--surface-muted))] px-1.5 py-0.5 text-[11px] font-normal text-[color:var(--muted-foreground)]"
+              >
+                {{ item.category }}
+              </span>
+            </slot>
+          </button>
+        </div>
+
+        <!-- Empty State -->
+        <div v-else-if="showEmpty" class="px-3 py-6 text-center text-xs text-[color:var(--muted-foreground)]">
+          <slot name="empty">
+            {{ emptyText || '未找到匹配结果' }}
+          </slot>
+        </div>
+
+        <!-- Custom Dropdown Footer -->
+        <div v-if="$slots.footer" class="mt-1 border-t border-[color:var(--border)] pt-1.5 text-xs text-[color:var(--muted-foreground)]">
+          <slot name="footer" />
+        </div>
+      </slot>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { Search, X, Loader2 } from '../../icons'
+import type {
+  SearchInputProps,
+  SearchInputEmits,
+  SearchInputSize,
+  SearchInputVariant,
+  SearchSuggestion
+} from './types'
+
+const props = withDefaults(defineProps<SearchInputProps>(), {
+  modelValue: '',
+  placeholder: '搜索...',
+  size: 'md',
+  variant: 'default',
+  clearable: true,
+  clearOnEsc: true,
+  loading: false,
+  debounce: 300,
+  shortcut: undefined,
+  enableGlobalShortcut: false,
+  ariaLabel: undefined,
+  disabled: false,
+  readonly: false,
+  autocomplete: 'off',
+  suggestions: undefined,
+  open: undefined,
+  emptyText: '未找到匹配结果',
+  showDropdownOnFocus: true,
+  class: ''
+})
+
+const emit = defineEmits<SearchInputEmits>()
+
+const containerRef = ref<HTMLDivElement | null>(null)
+const inputRef = ref<HTMLInputElement | null>(null)
+const internalOpen = ref(false)
+const activeIndex = ref(-1)
+
+let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+const hasValue = computed(() => Boolean(props.modelValue && props.modelValue.trim().length > 0))
+const hasSuggestions = computed(() => Array.isArray(props.suggestions) && props.suggestions.length > 0)
+const hasDropdown = computed(() => props.suggestions !== undefined)
+const showEmpty = computed(() => hasDropdown.value && !hasSuggestions.value && hasValue.value)
+
+const isOpen = computed({
+  get: () => (props.open !== undefined ? props.open : internalOpen.value),
+  set: (val: boolean) => {
+    internalOpen.value = val
+    emit('update:open', val)
+  }
+})
+
+const activeItemId = computed(() => {
+  if (isOpen.value && activeIndex.value >= 0) {
+    return `search-item-${activeIndex.value}`
+  }
+  return undefined
+})
+
+const sizeContainerClasses: Record<SearchInputSize, string> = {
+  sm: 'h-8 px-2.5 gap-2 text-xs',
+  md: 'h-9.5 px-3 gap-2.5 text-sm',
+  lg: 'h-11 px-3.5 gap-3 text-base'
+}
+
+const sizeInputClasses: Record<SearchInputSize, string> = {
+  sm: 'text-xs',
+  md: 'text-sm',
+  lg: 'text-base'
+}
+
+const iconSizeClasses: Record<SearchInputSize, string> = {
+  sm: 'h-3.5 w-3.5',
+  md: 'h-4 w-4',
+  lg: 'h-5 w-5'
+}
+
+const variantClasses: Record<SearchInputVariant, string> = {
+  default:
+    'rounded-lg border border-[color:var(--border)] bg-[color:var(--card)] hover:border-[color:var(--ring)] focus-within:ring-2 focus-within:ring-[color:var(--ring)] focus-within:border-transparent shadow-xs',
+  filled:
+    'rounded-lg border border-transparent bg-[color:var(--surface-muted)] hover:bg-[color:var(--surface-subtle,var(--surface-muted))] focus-within:bg-[color:var(--card)] focus-within:ring-2 focus-within:ring-[color:var(--ring)] focus-within:border-transparent',
+  pill:
+    'rounded-full border border-[color:var(--border)] bg-[color:var(--card)] hover:border-[color:var(--ring)] focus-within:ring-2 focus-within:ring-[color:var(--ring)] focus-within:border-transparent shadow-xs'
+}
+
+const handleInput = (event: Event) => {
+  const val = (event.target as HTMLInputElement).value
+  emit('update:modelValue', val)
+
+  if (hasDropdown.value) {
+    isOpen.value = true
+    activeIndex.value = -1
+  }
+
+  if (debounceTimer) {
+    clearTimeout(debounceTimer)
+  }
+
+  if (props.debounce && props.debounce > 0) {
+    debounceTimer = setTimeout(() => {
+      emit('search', val)
+    }, props.debounce)
+  } else {
+    emit('search', val)
+  }
+}
+
+const handleClear = () => {
+  if (debounceTimer) {
+    clearTimeout(debounceTimer)
+  }
+  emit('update:modelValue', '')
+  emit('clear')
+  emit('search', '')
+  activeIndex.value = -1
+  if (hasDropdown.value) {
+    isOpen.value = false
+  }
+  inputRef.value?.focus()
+}
+
+const handleSelect = (item: SearchSuggestion) => {
+  if (item.disabled) return
+  emit('update:modelValue', item.label)
+  emit('select', item)
+  isOpen.value = false
+  activeIndex.value = -1
+}
+
+const handleKeydown = (event: KeyboardEvent) => {
+  emit('keydown', event)
+
+  if (hasDropdown.value && isOpen.value) {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      if (hasSuggestions.value) {
+        activeIndex.value = (activeIndex.value + 1) % props.suggestions!.length
+      }
+      return
+    }
+
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      if (hasSuggestions.value) {
+        activeIndex.value =
+          (activeIndex.value - 1 + props.suggestions!.length) % props.suggestions!.length
+      }
+      return
+    }
+  }
+
+  if (event.key === 'Enter') {
+    if (isOpen.value && activeIndex.value >= 0 && hasSuggestions.value) {
+      event.preventDefault()
+      const selected = props.suggestions![activeIndex.value]
+      if (selected) {
+        handleSelect(selected)
+        return
+      }
+    }
+
+    if (debounceTimer) {
+      clearTimeout(debounceTimer)
+    }
+    const currentVal = props.modelValue || ''
+    emit('search', currentVal)
+    emit('submit', currentVal)
+    if (hasDropdown.value) {
+      isOpen.value = false
+    }
+    return
+  }
+
+  if (event.key === 'Escape') {
+    if (isOpen.value) {
+      event.preventDefault()
+      isOpen.value = false
+      activeIndex.value = -1
+    } else if (props.clearOnEsc && hasValue.value) {
+      event.preventDefault()
+      handleClear()
+    }
+  }
+}
+
+const handleFocus = (event: FocusEvent) => {
+  emit('focus', event)
+  if (props.showDropdownOnFocus && hasDropdown.value && (hasSuggestions.value || showEmpty.value)) {
+    isOpen.value = true
+  }
+}
+
+const handleBlur = (event: FocusEvent) => {
+  emit('blur', event)
+}
+
+const handlePointerDownOutside = (event: PointerEvent) => {
+  if (!containerRef.value) return
+  if (!containerRef.value.contains(event.target as Node)) {
+    isOpen.value = false
+    activeIndex.value = -1
+  }
+}
+
+const handleGlobalShortcut = (event: KeyboardEvent) => {
+  if (!props.enableGlobalShortcut || !props.shortcut) return
+
+  const target = event.target as HTMLElement | null
+  const isInputTarget =
+    target &&
+    (target.tagName === 'INPUT' ||
+      target.tagName === 'TEXTAREA' ||
+      target.tagName === 'SELECT' ||
+      target.isContentEditable)
+
+  if (isInputTarget) return
+
+  const normalizedShortcut = props.shortcut.trim().toLowerCase()
+
+  if (normalizedShortcut === '/' && event.key === '/') {
+    event.preventDefault()
+    inputRef.value?.focus()
+    return
+  }
+
+  const isK = event.key.toLowerCase() === 'k'
+  const isModifier = event.metaKey || event.ctrlKey
+  if (isK && isModifier && (normalizedShortcut.includes('k') || normalizedShortcut.includes('cmd'))) {
+    event.preventDefault()
+    inputRef.value?.focus()
+  }
+}
+
+watch(
+  () => props.suggestions,
+  () => {
+    activeIndex.value = -1
+  }
+)
+
+onMounted(() => {
+  document.addEventListener('pointerdown', handlePointerDownOutside)
+  if (props.enableGlobalShortcut) {
+    window.addEventListener('keydown', handleGlobalShortcut)
+  }
+})
+
+onBeforeUnmount(() => {
+  if (debounceTimer) {
+    clearTimeout(debounceTimer)
+  }
+  document.removeEventListener('pointerdown', handlePointerDownOutside)
+  if (props.enableGlobalShortcut) {
+    window.removeEventListener('keydown', handleGlobalShortcut)
+  }
+})
+
+const focus = () => inputRef.value?.focus()
+const blur = () => inputRef.value?.blur()
+const clear = () => handleClear()
+
+defineExpose({
+  focus,
+  blur,
+  clear,
+  input: inputRef
+})
+</script>
diff --git a/packages/ui/src/components/search-input/index.ts b/packages/ui/src/components/search-input/index.ts
new file mode 100644
index 0000000..f4c0d1c
--- /dev/null
+++ b/packages/ui/src/components/search-input/index.ts
@@ -0,0 +1,3 @@
+export { default as SearchInput } from "./SearchInput.vue";
+export { default as SearchBox } from "./SearchInput.vue";
+export * from "./types";
diff --git a/packages/ui/src/components/search-input/searchInput.test.ts b/packages/ui/src/components/search-input/searchInput.test.ts
new file mode 100644
index 0000000..b95f491
--- /dev/null
+++ b/packages/ui/src/components/search-input/searchInput.test.ts
@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = readFileSync(fileURLToPath(new URL("./SearchInput.vue", import.meta.url)), "utf8");
+const indexSource = readFileSync(fileURLToPath(new URL("./index.ts", import.meta.url)), "utf8");
+
+describe("SearchInput & SearchBox component contract", () => {
+  it("exports SearchInput and SearchBox aliases", () => {
+    expect(indexSource).toContain("export { default as SearchInput }");
+    expect(indexSource).toContain("export { default as SearchBox }");
+    expect(indexSource).toContain("types");
+  });
+
+  it("supports sizes, variants, and debounce", () => {
+    expect(source).toContain("sizeContainerClasses[size]");
+    expect(source).toContain("variantClasses[variant]");
+    expect(source).toContain("debounce: 300");
+    expect(source).toContain("variant: 'default'");
+  });
+
+  it("provides accessible role and search interaction", () => {
+    expect(source).toContain('role="searchbox"');
+    expect(source).toContain(":aria-label=\"ariaLabel || placeholder || '搜索'\"");
+    expect(source).toContain("emit('search', val)");
+    expect(source).toContain("emit('submit', currentVal)");
+  });
+
+  it("supports clearable button and loading state", () => {
+    expect(source).toContain('v-else-if="clearable && hasValue && !disabled && !readonly"');
+    expect(source).toContain("emit('clear')");
+    expect(source).toContain('v-if="loading"');
+  });
+
+  it("supports suggestions dropdown and keyboard navigation", () => {
+    expect(source).toContain('role="listbox"');
+    expect(source).toContain('role="option"');
+    expect(source).toContain("event.key === 'ArrowDown'");
+    expect(source).toContain("event.key === 'ArrowUp'");
+    expect(source).toContain("event.key === 'Enter'");
+    expect(source).toContain("event.key === 'Escape'");
+    expect(source).toContain("emit('select', item)");
+  });
+
+  it("supports shortcut key and global focus trigger", () => {
+    expect(source).toContain("shortcut");
+    expect(source).toContain("enableGlobalShortcut");
+    expect(source).toContain("window.addEventListener('keydown', handleGlobalShortcut)");
+  });
+});
diff --git a/packages/ui/src/components/search-input/types.ts b/packages/ui/src/components/search-input/types.ts
new file mode 100644
index 0000000..93056d6
--- /dev/null
+++ b/packages/ui/src/components/search-input/types.ts
@@ -0,0 +1,121 @@
+export type SearchInputSize = "sm" | "md" | "lg";
+export type SearchInputVariant = "default" | "filled" | "pill";
+
+export interface SearchSuggestion {
+  id?: string | number;
+  label: string;
+  description?: string;
+  category?: string;
+  icon?: string;
+  disabled?: boolean;
+  [key: string]: unknown;
+}
+
+export interface SearchInputProps {
+  /**
+   * Current search query string (v-model).
+   */
+  modelValue?: string;
+
+  /**
+   * Placeholder text when search query is empty.
+   */
+  placeholder?: string;
+
+  /**
+   * Search input size.
+   */
+  size?: SearchInputSize;
+
+  /**
+   * Visual variant: default (bordered), filled (muted background), pill (fully rounded).
+   */
+  variant?: SearchInputVariant;
+
+  /**
+   * Whether to show a clear (X) button when query is not empty.
+   */
+  clearable?: boolean;
+
+  /**
+   * Whether pressing Escape clears the search text (when dropdown is closed).
+   */
+  clearOnEsc?: boolean;
+
+  /**
+   * Shows a loading spinner when search request or backend fetch is in progress.
+   */
+  loading?: boolean;
+
+  /**
+   * Debounce time in milliseconds before emitting `@search`. Default: 300.
+   */
+  debounce?: number;
+
+  /**
+   * Keyboard shortcut hint to display (e.g., '⌘K', '/', 'Ctrl+K').
+   */
+  shortcut?: string;
+
+  /**
+   * If true, pressing the shortcut globally focuses this search input.
+   */
+  enableGlobalShortcut?: boolean;
+
+  /**
+   * Accessible ARIA label for the input.
+   */
+  ariaLabel?: string;
+
+  /**
+   * Disabled state.
+   */
+  disabled?: boolean;
+
+  /**
+   * Readonly state.
+   */
+  readonly?: boolean;
+
+  /**
+   * Autocomplete attribute for the HTML input.
+   */
+  autocomplete?: string;
+
+  /**
+   * Suggestions / backend results to display in the dropdown.
+   */
+  suggestions?: SearchSuggestion[];
+
+  /**
+   * Controlled open state for the suggestions dropdown (v-model:open).
+   */
+  open?: boolean;
+
+  /**
+   * Empty state text when suggestions array is empty while dropdown is open.
+   */
+  emptyText?: string;
+
+  /**
+   * Whether to automatically show the dropdown on focus when suggestions exist.
+   */
+  showDropdownOnFocus?: boolean;
+
+  /**
+   * Additional CSS classes for the container.
+   */
+  class?: string;
+}
+
+export interface SearchInputEmits {
+  (e: "update:modelValue", value: string): void;
+  (e: "update:open", open: boolean): void;
+  (e: "search", query: string): void;
+  (e: "submit", query: string): void;
+  (e: "clear"): void;
+  (e: "select", item: SearchSuggestion): void;
+  (e: "focus", event: FocusEvent): void;
+  (e: "blur", event: FocusEvent): void;
+  (e: "keydown", event: KeyboardEvent): void;
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 2f0f69b..0076b71 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -72,6 +72,7 @@ export * from "./components/hero";
 export * from "./components/container";
 export * from "./components/section";
 export * from "./components/theme-toggle";
+export * from "./components/search-input";
 export * from "./components/icon";
 export * from "./markdown";
 

From c19aca043c8d61d56da6f9e98cc59b774f3e07dc Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Tue, 6 Oct 2026 00:16:41 +0800
Subject: [PATCH 14/17] docs(playground): document SearchInput component

---
 .../pages/components/search-input.vue         | 176 ++++++++++++++++++
 apps/playground/utils/catalog.ts              |   5 +
 2 files changed, 181 insertions(+)
 create mode 100644 apps/playground/pages/components/search-input.vue

diff --git a/apps/playground/pages/components/search-input.vue b/apps/playground/pages/components/search-input.vue
new file mode 100644
index 0000000..366a26f
--- /dev/null
+++ b/apps/playground/pages/components/search-input.vue
@@ -0,0 +1,176 @@
+<template>
+  <div class="space-y-10">
+    <DocPageHeader
+      title="SearchInput 搜索框"
+      description="通用纯前端搜索框组件（同时提供 SearchBox 别名导出），内置搜索图标、一键清除、Loading 状态、快捷键徽标（如 ⌘K 或 /）、防抖触发与可选的联想词/结果浮层，后端可任意对接 Elasticsearch、Meilisearch、SQL 或本地内存检索。"
+    />
+
+    <DocExample
+      title="基础搜索输入框"
+      description="支持 v-model 双向绑定，内置 300ms 防抖并暴露 @search 与 @submit 事件。"
+      :code="rcCode0"
+    >
+      <div class="max-w-md space-y-3">
+        <SearchInput
+          v-model="basicQuery"
+          placeholder="搜索实例、集群或配置项..."
+          @search="lastSearch = $event"
+          @submit="lastSubmit = $event"
+          @clear="lastSearch = ''"
+        />
+        <div class="flex items-center gap-4 text-xs text-slate-500">
+          <span>防抖查询 (@search): <strong class="text-slate-800 dark:text-slate-200">{{ lastSearch || '（空）' }}</strong></span>
+          <span>提交 (@submit): <strong class="text-primary-600 dark:text-primary-400">{{ lastSubmit || '（无）' }}</strong></span>
+        </div>
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="视觉变体与尺寸规格"
+      description="提供 default（线框卡片）、filled（静音填充）与 pill（胶囊圆角）三种变体，并支持 sm、md、lg 尺寸。"
+      :code="rcCode1"
+    >
+      <div class="grid max-w-xl gap-4">
+        <div class="space-y-1.5">
+          <span class="text-xs font-medium text-slate-500">小尺寸胶囊 (size="sm" variant="pill")</span>
+          <SearchInput size="sm" variant="pill" placeholder="快捷筛选..." />
+        </div>
+        <div class="space-y-1.5">
+          <span class="text-xs font-medium text-slate-500">标准填充态 (size="md" variant="filled")</span>
+          <SearchInput size="md" variant="filled" placeholder="搜索资源组..." />
+        </div>
+        <div class="space-y-1.5">
+          <span class="text-xs font-medium text-slate-500">大尺寸线框 (size="lg" variant="default")</span>
+          <SearchInput size="lg" variant="default" placeholder="在全网知识库中搜索..." />
+        </div>
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="快捷键与异步 Loading 状态"
+      description="支持展示 shortcut 快捷键（支持全局聚焦监听），支持 loading 模拟后端异步请求状态。"
+      :code="rcCode2"
+    >
+      <div class="max-w-md space-y-4">
+        <SearchInput
+          shortcut="⌘K"
+          enable-global-shortcut
+          placeholder="按 ⌘K 或 Ctrl+K 聚焦此输入框..."
+        />
+        <SearchInput
+          :loading="isLoading"
+          placeholder="异步搜索中..."
+          model-value="kubernetes-node-01"
+        />
+        <button
+          type="button"
+          class="rounded-md border border-slate-300 px-3 py-1 text-xs font-medium text-slate-700 hover:bg-slate-50 dark:border-slate-700 dark:text-slate-300 dark:hover:bg-slate-800 cursor-pointer"
+          @click="isLoading = !isLoading"
+        >
+          切换 Loading 状态: {{ isLoading ? '开启' : '关闭' }}
+        </button>
+      </div>
+    </DocExample>
+
+    <DocExample
+      title="联想结果与后端对接展示"
+      description="传入 suggestions 列表即可展开下拉结果面板，支持键盘上下箭头高亮、Enter 选中或点击选择。"
+      :code="rcCode3"
+    >
+      <div class="max-w-md space-y-3">
+        <SearchInput
+          v-model="backendQuery"
+          :suggestions="filteredSuggestions"
+          placeholder="输入微服务名称（如 auth、gateway）..."
+          @select="handleSelectSuggestion"
+        />
+        <div v-if="selectedItem" class="rounded-lg border border-slate-200 bg-slate-50 p-3 text-xs dark:border-slate-800 dark:bg-slate-900">
+          已选中项: <span class="font-semibold text-slate-900 dark:text-white">{{ selectedItem.label }}</span>
+          <span class="ml-2 text-slate-500">({{ selectedItem.category }})</span>
+        </div>
+      </div>
+    </DocExample>
+
+    <DocApiTable :rows="apiRows" />
+    <DocPageNav name="search-input" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { SearchInput, type SearchSuggestion } from '@recloudstudio/ui'
+
+const basicQuery = ref('')
+const lastSearch = ref('')
+const lastSubmit = ref('')
+const isLoading = ref(true)
+
+const backendQuery = ref('')
+const selectedItem = ref<SearchSuggestion | null>(null)
+
+const mockBackendData: SearchSuggestion[] = [
+  { id: '1', label: 'auth-service', description: 'OAuth2 / RBAC 认证授权中心', category: '核心网关' },
+  { id: '2', label: 'gateway-ingress', description: '基于 Envoy 的多集群边缘流量网关', category: '网络' },
+  { id: '3', label: 'billing-api', description: '用量计量与多租户账单结算引擎', category: '财务' },
+  { id: '4', label: 'monitor-prometheus', description: '分布式时序监控与指标采集探针', category: '可观测性' },
+  { id: '5', label: 'storage-s3-gateway', description: '兼容 S3 协议的对象存储加速节点', category: '存储' }
+]
+
+const filteredSuggestions = computed(() => {
+  if (!backendQuery.value.trim()) return mockBackendData
+  const q = backendQuery.value.toLowerCase()
+  return mockBackendData.filter(
+    item => item.label.toLowerCase().includes(q) || item.description?.toLowerCase().includes(q)
+  )
+})
+
+const handleSelectSuggestion = (item: SearchSuggestion) => {
+  selectedItem.value = item
+}
+
+const rcCode0 = `<SearchInput
+  v-model="query"
+  placeholder="搜索实例、集群或配置项..."
+  @search="onSearch"
+  @submit="onSubmit"
+  @clear="onClear"
+/>`
+
+const rcCode1 = `<SearchInput size="sm" variant="pill" placeholder="快捷筛选..." />
+<SearchInput size="md" variant="filled" placeholder="搜索资源组..." />
+<SearchInput size="lg" variant="default" placeholder="在全网知识库中搜索..." />`
+
+const rcCode2 = `<SearchInput
+  shortcut="⌘K"
+  enable-global-shortcut
+  placeholder="按 ⌘K 聚焦..."
+/>
+<SearchInput :loading="isLoading" placeholder="异步请求中..." />`
+
+const rcCode3 = `<SearchInput
+  v-model="query"
+  :suggestions="resultsFromBackend"
+  placeholder="输入微服务名称..."
+  @select="onSelect"
+/>`
+
+const apiRows = [
+  { name: 'modelValue', type: 'string', default: "''", description: '搜索框文本输入值（v-model）。' },
+  { name: 'placeholder', type: 'string', default: "'搜索...'", description: '占位提示文字。' },
+  { name: 'size', type: "'sm' | 'md' | 'lg'", default: "'md'", description: '输入框尺寸规格。' },
+  { name: 'variant', type: "'default' | 'filled' | 'pill'", default: "'default'", description: '外观形态：线框卡片、静音填充、圆角胶囊。' },
+  { name: 'debounce', type: 'number', default: '300', description: '防抖延迟毫秒数，触发 @search 事件。' },
+  { name: 'clearable', type: 'boolean', default: 'true', description: '有输入内容时是否展示一键清空按钮。' },
+  { name: 'clearOnEsc', type: 'boolean', default: 'true', description: '按 Escape 键是否清空输入内容。' },
+  { name: 'loading', type: 'boolean', default: 'false', description: '是否处于加载/搜索中状态，展示转圈动画。' },
+  { name: 'shortcut', type: 'string', default: 'undefined', description: '显示的按键提示（如 ⌘K 或 /）。' },
+  { name: 'enableGlobalShortcut', type: 'boolean', default: 'false', description: '是否在全局监听按键并自动聚焦输入框。' },
+  { name: 'suggestions', type: 'SearchSuggestion[]', default: 'undefined', description: '后端返回的联想建议或检索结果列表。' },
+  { name: 'open', type: 'boolean', default: 'undefined', description: '受控的下拉浮层展开状态（v-model:open）。' },
+  { name: 'emptyText', type: 'string', default: "'未找到匹配结果'", description: '搜索无匹配项时的空态文案。' },
+  { name: '@search', type: '(query: string) => void', default: '—', description: '防抖触发或回车触发的搜索事件。' },
+  { name: '@submit', type: '(query: string) => void', default: '—', description: '按回车提交搜索事件。' },
+  { name: '@clear', type: '() => void', default: '—', description: '点击清空按钮时触发。' },
+  { name: '@select', type: '(item: SearchSuggestion) => void', default: '—', description: '选中联想建议项时触发。' }
+]
+</script>
diff --git a/apps/playground/utils/catalog.ts b/apps/playground/utils/catalog.ts
index 350ff5a..0908ea1 100644
--- a/apps/playground/utils/catalog.ts
+++ b/apps/playground/utils/catalog.ts
@@ -74,6 +74,11 @@ const groups: DocGroup[] = [
       { name: "editable", title: "Editable 行内编辑", description: "点击即改的文本。" },
       { name: "toggle", title: "Toggle / ToggleGroup", description: "按压态工具按钮与分组。" },
       { name: "label", title: "Label 标签", description: "表单控件关联标签。" },
+      {
+        name: "search-input",
+        title: "SearchInput 搜索框",
+        description: "带图标、清空、加载、快捷键与联想结果下拉的通用前端搜索框。",
+      },
       { name: "date-picker", title: "DatePicker 日期选择", description: "单日期与日期范围筛选。" },
     ],
   },

From eade8adf38c2facfeb0acc53096760ee25f7652b Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Tue, 6 Oct 2026 00:45:37 +0800
Subject: [PATCH 15/17] docs(playground): align release and product copy

---
 apps/playground/app.vue                     | 2 +-
 apps/playground/components/DocFooter.vue    | 4 ++--
 apps/playground/pages/components/hero.vue   | 4 ++--
 apps/playground/pages/components/navbar.vue | 4 ++--
 apps/playground/pages/index.vue             | 9 +++++++--
 5 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/apps/playground/app.vue b/apps/playground/app.vue
index 6f98729..6fd2a44 100644
--- a/apps/playground/app.vue
+++ b/apps/playground/app.vue
@@ -7,7 +7,7 @@
       <div class="max-w-7xl mx-auto px-5 sm:px-8 h-16 flex items-center justify-between">
         <NuxtLink to="/" class="flex items-center gap-3">
           <BrandWordmark :height="28" />
-          <Badge variant="subtle" color="primary" size="xs">v0.1.0-alpha</Badge>
+          <Badge variant="subtle" color="primary" size="xs">v0.3.0</Badge>
         </NuxtLink>
 
         <div class="flex items-center gap-2">
diff --git a/apps/playground/components/DocFooter.vue b/apps/playground/components/DocFooter.vue
index 42b8d84..ad893a5 100644
--- a/apps/playground/components/DocFooter.vue
+++ b/apps/playground/components/DocFooter.vue
@@ -7,7 +7,7 @@
             <BrandWordmark :height="26" />
           </NuxtLink>
           <p class="text-sm leading-6 text-slate-500 dark:text-slate-400">
-            为 ReCloud Studio 控制台而生的 <span class="whitespace-nowrap">Vue 3 / Nuxt 4</span> 组件库，遵循官方品牌设计规范。
+            为 ReCloud Studio 控制台与文档门户而生的 <span class="whitespace-nowrap">Vue 3 / Nuxt 4</span> 组件库，遵循官方品牌设计规范。
           </p>
           <div class="flex items-center gap-2 pt-1">
             <a href="https://github.com/ReCloudStudio" target="_blank" rel="noopener" aria-label="GitHub">
@@ -58,7 +58,7 @@
           © 2026 ReCloud Studio · 代码以 AGPL-3.0 协议开源
         </p>
         <div class="flex items-center gap-2">
-          <Badge variant="subtle" color="primary" size="xs">v0.1.0-alpha</Badge>
+          <Badge variant="subtle" color="primary" size="xs">v0.3.0</Badge>
           <span class="text-xs text-slate-500 dark:text-slate-400">Vue 3 · Nuxt 4 · Reka UI · Tailwind v4</span>
         </div>
       </div>
diff --git a/apps/playground/pages/components/hero.vue b/apps/playground/pages/components/hero.vue
index d842a85..d42ac95 100644
--- a/apps/playground/pages/components/hero.vue
+++ b/apps/playground/pages/components/hero.vue
@@ -6,7 +6,7 @@
       <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 已正式发布"
+          badge="v0.3.0 已正式发布"
           title="专为运维控制台打造的 UI 系统"
           description="基于 Vue 3、Nuxt 4 与 Reka UI 构建，提供无障碍基础底座与分层设计令牌，助力高效交付开发者工具。"
           primary-action-text="快速上手"
@@ -50,7 +50,7 @@
 <script setup lang="ts">
 const codeCenter = `<Hero
   layout="center"
-  badge="v0.2.0 已正式发布"
+  badge="v0.3.0 已正式发布"
   title="专为运维控制台打造的 UI 系统"
   description="基于 Vue 3、Nuxt 4 构建，提供无障碍底座与分层设计令牌。"
   primary-action-text="快速上手"
diff --git a/apps/playground/pages/components/navbar.vue b/apps/playground/pages/components/navbar.vue
index a51fd0c..7def88a 100644
--- a/apps/playground/pages/components/navbar.vue
+++ b/apps/playground/pages/components/navbar.vue
@@ -26,7 +26,7 @@
 const navLinks = [
   { label: '功能特性', href: '#features' },
   { label: '组件文档', to: '/components/button' },
-  { label: '更新日志', to: '/components/timeline', badge: 'v0.2.0' },
+  { label: '更新日志', to: '/components/timeline', badge: 'v0.3.0' },
   { label: '定价', href: '#pricing' }
 ]
 
@@ -35,7 +35,7 @@ const codeBasic = `<Navbar
   :links="[
     { label: '功能特性', href: '#features' },
     { label: '组件文档', to: '/components/button' },
-    { label: '更新日志', to: '/components/timeline', badge: 'v0.2.0' }
+    { label: '更新日志', to: '/components/timeline', badge: 'v0.3.0' }
   ]"
 >
   <template #actions>
diff --git a/apps/playground/pages/index.vue b/apps/playground/pages/index.vue
index 1ad7f27..f038431 100644
--- a/apps/playground/pages/index.vue
+++ b/apps/playground/pages/index.vue
@@ -10,10 +10,10 @@
           <Badge variant="outline" color="neutral" size="xs">Nuxt 4 · Vue 3 · Tailwind v4</Badge>
         </div>
         <h1 class="text-4xl sm:text-5xl font-bold tracking-tight text-slate-950 dark:text-white max-w-xl leading-[1.1]">
-          为 ReCloud Studio 控制台而生的组件库
+          为 ReCloud Studio 控制台与文档门户而生的组件库
         </h1>
         <p class="text-base text-slate-600 dark:text-slate-300 leading-7 max-w-xl">
-          47 个工业级 Vue 3 组件，基于 Reka UI 无障碍底层，严格遵循 ReCloud Studio 品牌垂直天蓝渐变规范与 Nuxt UI 的精致内嵌环线设计语言。
+          {{ componentCount }} 个工业级 Vue 3 组件，覆盖控制台、文档站与营销门户场景；基于 Reka UI 无障碍底层，严格遵循 ReCloud Studio 品牌设计规范。
         </p>
         <div class="flex flex-wrap items-center gap-3 pt-1">
           <NuxtLink to="/components/button">
@@ -68,6 +68,11 @@
 import { BrandLogo } from '@recloudstudio/ui/icons'
 import { docGroups, docPath } from '~/utils/catalog'
 
+const componentCount = docGroups
+  .filter(group => group.label !== '指南' && group.label !== 'Design Tokens')
+  .flatMap(group => group.items)
+  .filter(item => item.name !== 'locale').length
+
 const installNuxt = `// nuxt.config.ts
 export default defineNuxtConfig({
   modules: [['@recloudstudio/ui/nuxt', { prefix: '' }]],

From 4bf303a44e5e9e395628bcfdbada6ab61bc98edc Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Tue, 6 Oct 2026 02:01:06 +0800
Subject: [PATCH 16/17] feat(ui): add documentation primitives

---
 .changeset/bright-docs-primitives.md          |   5 +
 .changeset/config.json                        |  18 +-
 apps/playground/app.vue                       | 122 ++---
 apps/playground/components/DocApiTable.vue    |  40 --
 apps/playground/components/DocFooter.vue      | 120 ++---
 apps/playground/components/DocPageHeader.vue  |  28 --
 apps/playground/components/DocPageNav.vue     |  35 +-
 apps/playground/package.json                  |   7 +-
 .../playground/pages/components/accordion.vue |   8 +-
 .../pages/components/alert-dialog.vue         |   8 +-
 .../pages/components/anchor-heading.vue       |   8 +-
 .../playground/pages/components/app-shell.vue |   8 +-
 .../pages/components/aspect-ratio.vue         |   8 +-
 apps/playground/pages/components/avatar.vue   |  12 +-
 apps/playground/pages/components/badge.vue    |   8 +-
 apps/playground/pages/components/banner.vue   |  12 +-
 .../pages/components/breadcrumb.vue           |   8 +-
 apps/playground/pages/components/button.vue   |  20 +-
 apps/playground/pages/components/callout.vue  |  12 +-
 apps/playground/pages/components/card.vue     |  12 +-
 apps/playground/pages/components/checkbox.vue |   8 +-
 .../pages/components/code-block.vue           |  20 +-
 .../pages/components/code-group.vue           |   8 +-
 .../pages/components/collapsible.vue          |   8 +-
 apps/playground/pages/components/colors.vue   |  12 +-
 apps/playground/pages/components/combobox.vue |   8 +-
 .../pages/components/command-palette.vue      |   8 +-
 .../playground/pages/components/container.vue |  12 +-
 .../pages/components/context-menu.vue         |   8 +-
 .../pages/components/data-table.vue           |   8 +-
 .../pages/components/date-picker.vue          |   8 +-
 apps/playground/pages/components/dialog.vue   |   8 +-
 .../pages/components/dropdown-menu.vue        |   8 +-
 apps/playground/pages/components/editable.vue |   8 +-
 .../pages/components/empty-state.vue          |   8 +-
 apps/playground/pages/components/field.vue    |   8 +-
 .../pages/components/file-upload.vue          |  12 +-
 apps/playground/pages/components/footer.vue   |   8 +-
 apps/playground/pages/components/hero.vue     |  12 +-
 .../pages/components/hover-card.vue           |   8 +-
 apps/playground/pages/components/icon.vue     |  20 +-
 .../pages/components/inline-code.vue          |  12 +-
 apps/playground/pages/components/input.vue    |  12 +-
 apps/playground/pages/components/kbd.vue      |   8 +-
 apps/playground/pages/components/label.vue    |   8 +-
 apps/playground/pages/components/locale.vue   |   4 +-
 apps/playground/pages/components/markdown.vue |  12 +-
 .../pages/components/multi-select.vue         |  12 +-
 apps/playground/pages/components/nav-tree.vue |   8 +-
 apps/playground/pages/components/navbar.vue   |   8 +-
 .../pages/components/navigation-menu.vue      |   8 +-
 .../pages/components/number-field.vue         |   8 +-
 .../pages/components/pagination.vue           |   8 +-
 .../playground/pages/components/pin-input.vue |   8 +-
 apps/playground/pages/components/popover.vue  |   8 +-
 .../playground/pages/components/prev-next.vue |  12 +-
 apps/playground/pages/components/progress.vue |   8 +-
 .../pages/components/radio-group.vue          |   8 +-
 apps/playground/pages/components/rating.vue   |   8 +-
 .../pages/components/resizable-panel.vue      |   8 +-
 .../pages/components/scroll-area.vue          |   8 +-
 .../pages/components/search-input.vue         |  20 +-
 apps/playground/pages/components/section.vue  |  12 +-
 apps/playground/pages/components/select.vue   |   8 +-
 .../playground/pages/components/separator.vue |   8 +-
 apps/playground/pages/components/sheet.vue    |   8 +-
 apps/playground/pages/components/skeleton.vue |   8 +-
 apps/playground/pages/components/slider.vue   |   8 +-
 apps/playground/pages/components/spinner.vue  |   8 +-
 apps/playground/pages/components/stepper.vue  |  12 +-
 apps/playground/pages/components/steps.vue    |   8 +-
 apps/playground/pages/components/switch.vue   |   8 +-
 apps/playground/pages/components/tabs.vue     |   8 +-
 .../playground/pages/components/tag-input.vue |  12 +-
 apps/playground/pages/components/textarea.vue |   8 +-
 .../pages/components/theme-toggle.vue         |  16 +-
 apps/playground/pages/components/timeline.vue |  12 +-
 apps/playground/pages/components/toast.vue    |   8 +-
 apps/playground/pages/components/toc.vue      |   8 +-
 apps/playground/pages/components/toggle.vue   |  12 +-
 apps/playground/pages/components/toolbar.vue  |   8 +-
 apps/playground/pages/components/tooltip.vue  |   8 +-
 .../playground/pages/components/tree-view.vue |  20 +-
 .../pages/components/visually-hidden.vue      |   8 +-
 apps/playground/pages/index.vue               |   6 +-
 apps/playground/src/style.css                 |  19 +-
 bun.lock                                      |  19 +-
 packages/ui/src/components/accordion/index.ts |   4 +-
 .../ui/src/components/alert-dialog/index.ts   |   4 +-
 .../ui/src/components/anchor-heading/index.ts |   4 +-
 .../ui/src/components/anchor-heading/types.ts |  10 +-
 .../ui/src/components/api-table/ApiTable.vue  |  41 ++
 .../src/components/api-table/apiTable.test.ts |  19 +
 packages/ui/src/components/api-table/index.ts |   2 +
 packages/ui/src/components/api-table/types.ts |  12 +
 packages/ui/src/components/app-shell/index.ts |   4 +-
 .../ui/src/components/aspect-ratio/index.ts   |   4 +-
 packages/ui/src/components/avatar/index.ts    |   4 +-
 packages/ui/src/components/badge/index.ts     |   4 +-
 packages/ui/src/components/banner/index.ts    |   4 +-
 .../ui/src/components/breadcrumb/index.ts     |   4 +-
 packages/ui/src/components/button/index.ts    |   4 +-
 .../ui/src/components/callout/callout.test.ts |  16 +-
 packages/ui/src/components/callout/index.ts   |   4 +-
 packages/ui/src/components/callout/types.ts   |  12 +-
 packages/ui/src/components/card/index.ts      |   4 +-
 packages/ui/src/components/checkbox/index.ts  |   4 +-
 .../components/code-block/codeBlock.test.ts   |  88 ++--
 .../ui/src/components/code-block/index.ts     |   8 +-
 .../components/code-block/languages.test.ts   | 206 ++++----
 .../ui/src/components/code-block/languages.ts | 216 ++++-----
 .../ui/src/components/code-block/types.ts     |  22 +-
 .../ui/src/components/code-group/index.ts     |   4 +-
 .../ui/src/components/code-group/types.ts     |  14 +-
 .../ui/src/components/collapsible/index.ts    |   4 +-
 packages/ui/src/components/combobox/index.ts  |   4 +-
 packages/ui/src/components/combobox/types.ts  |  34 +-
 .../command-palette/CommandPalette.vue        |   6 +-
 .../command-palette/commandMatcher.test.ts    |  38 +-
 .../command-palette/commandMatcher.ts         |  44 +-
 .../src/components/command-palette/index.ts   |   4 +-
 .../src/components/command-palette/types.ts   |  26 +-
 .../component-example/ComponentExample.vue    |  40 +-
 .../componentExample.test.ts                  |  24 +
 .../src/components/component-example/index.ts |   2 +
 .../src/components/component-example/types.ts |   9 +
 .../ui/src/components/context-menu/index.ts   |   4 +-
 .../components/date-picker/dateUtils.test.ts  |  36 +-
 .../src/components/date-picker/dateUtils.ts   |  50 +-
 .../ui/src/components/date-picker/index.ts    |   6 +-
 packages/ui/src/components/dialog/index.ts    |   4 +-
 packages/ui/src/components/dropdown/index.ts  |   4 +-
 packages/ui/src/components/editable/index.ts  |   4 +-
 packages/ui/src/components/empty/index.ts     |   4 +-
 packages/ui/src/components/field/index.ts     |   4 +-
 .../ui/src/components/file-upload/index.ts    |   9 +-
 .../ui/src/components/file-upload/types.ts    |  22 +-
 .../ui/src/components/footer/footer.test.ts   |  60 +--
 packages/ui/src/components/footer/index.ts    |   4 +-
 packages/ui/src/components/footer/types.ts    |  32 +-
 packages/ui/src/components/form/index.ts      |   4 +-
 packages/ui/src/components/hero/hero.test.ts  |  44 +-
 packages/ui/src/components/hero/index.ts      |   4 +-
 packages/ui/src/components/hero/types.ts      |  16 +-
 .../ui/src/components/hover-card/index.ts     |   4 +-
 packages/ui/src/components/icon/icon.test.ts  |  44 +-
 packages/ui/src/components/icon/index.ts      |   8 +-
 .../ui/src/components/icon/lucideResolver.ts  |  44 +-
 .../ui/src/components/icon/registry.test.ts   | 238 ++++-----
 packages/ui/src/components/icon/registry.ts   | 148 +++---
 packages/ui/src/components/icon/types.ts      |  20 +-
 .../ui/src/components/inline-code/index.ts    |   4 +-
 .../components/inline-code/inlineCode.test.ts |  26 +-
 .../ui/src/components/inline-code/types.ts    |   8 +-
 packages/ui/src/components/input/index.ts     |   4 +-
 packages/ui/src/components/kbd/index.ts       |   4 +-
 packages/ui/src/components/label/index.ts     |   4 +-
 .../ui/src/components/multi-select/index.ts   |   4 +-
 .../ui/src/components/multi-select/types.ts   |  32 +-
 .../ui/src/components/nav-tree/NavTree.vue    |   4 +-
 packages/ui/src/components/nav-tree/index.ts  |   4 +-
 packages/ui/src/components/nav-tree/types.ts  |  34 +-
 packages/ui/src/components/navbar/index.ts    |   4 +-
 .../ui/src/components/navbar/navbar.test.ts   |  34 +-
 packages/ui/src/components/navbar/types.ts    |  26 +-
 .../src/components/navigation-menu/index.ts   |   6 +-
 .../ui/src/components/number-field/index.ts   |   4 +-
 .../src/components/page-header/PageHeader.vue |  26 +
 .../ui/src/components/page-header/index.ts    |   2 +
 .../components/page-header/pageHeader.test.ts |  14 +
 .../ui/src/components/page-header/types.ts    |   7 +
 .../ui/src/components/pagination/index.ts     |   4 +-
 packages/ui/src/components/pin-input/index.ts |   4 +-
 packages/ui/src/components/popover/index.ts   |   4 +-
 packages/ui/src/components/prev-next/index.ts |   4 +-
 packages/ui/src/components/prev-next/types.ts |  18 +-
 packages/ui/src/components/progress/index.ts  |   4 +-
 packages/ui/src/components/radio/index.ts     |   4 +-
 packages/ui/src/components/rating/index.ts    |   4 +-
 .../src/components/resizable-panel/index.ts   |   2 +-
 .../ui/src/components/scroll-area/index.ts    |   4 +-
 packages/ui/src/components/select/index.ts    |   4 +-
 packages/ui/src/components/separator/index.ts |   4 +-
 packages/ui/src/components/sheet/index.ts     |   2 +-
 packages/ui/src/components/skeleton/index.ts  |   4 +-
 packages/ui/src/components/slider/index.ts    |   4 +-
 packages/ui/src/components/spinner/index.ts   |   4 +-
 packages/ui/src/components/stepper/index.ts   |   4 +-
 packages/ui/src/components/steps/index.ts     |   6 +-
 packages/ui/src/components/steps/types.ts     |  18 +-
 packages/ui/src/components/switch/index.ts    |   4 +-
 packages/ui/src/components/table/index.ts     |   4 +-
 packages/ui/src/components/table/types.ts     |  18 +-
 packages/ui/src/components/tabs/index.ts      |   6 +-
 .../ui/src/components/tag-input/TagInput.vue  |   2 +-
 packages/ui/src/components/tag-input/index.ts |   4 +-
 packages/ui/src/components/textarea/index.ts  |   4 +-
 packages/ui/src/components/timeline/index.ts  |   4 +-
 packages/ui/src/components/timeline/types.ts  |  18 +-
 packages/ui/src/components/toast/index.ts     |   4 +-
 packages/ui/src/components/toast/useToast.ts  |  36 +-
 packages/ui/src/components/toc/index.ts       |   4 +-
 packages/ui/src/components/toc/types.ts       |  22 +-
 .../ui/src/components/toggle-group/index.ts   |   4 +-
 packages/ui/src/components/toggle/index.ts    |   4 +-
 packages/ui/src/components/toolbar/index.ts   |  10 +-
 packages/ui/src/components/tooltip/index.ts   |   4 +-
 packages/ui/src/components/tree-view/index.ts |   4 +-
 packages/ui/src/components/tree-view/types.ts |  22 +-
 .../src/components/visually-hidden/index.ts   |   4 +-
 packages/ui/src/composables/useTheme.ts       | 162 ++++---
 packages/ui/src/env.d.ts                      |   8 +-
 packages/ui/src/icons/index.ts                |   6 +-
 packages/ui/src/index.ts                      |   3 +
 packages/ui/src/locale/index.ts               |  93 ++--
 packages/ui/src/locale/locale.test.ts         |  80 +--
 packages/ui/src/locale/messages.ts            | 454 +++++++++---------
 packages/ui/src/markdown/compile.ts           |   4 +-
 packages/ui/src/nuxt/index.ts                 | 109 +++--
 packages/ui/src/nuxt/types.ts                 |  16 +-
 packages/ui/src/theme.css                     | 145 +++++-
 packages/ui/src/utils/cn.test.ts              |   6 +-
 packages/ui/src/utils/theme.ts                |   3 +-
 packages/ui/src/utils/themeScript.ts          |  18 +-
 224 files changed, 2378 insertions(+), 2201 deletions(-)
 create mode 100644 .changeset/bright-docs-primitives.md
 delete mode 100644 apps/playground/components/DocApiTable.vue
 delete mode 100644 apps/playground/components/DocPageHeader.vue
 create mode 100644 packages/ui/src/components/api-table/ApiTable.vue
 create mode 100644 packages/ui/src/components/api-table/apiTable.test.ts
 create mode 100644 packages/ui/src/components/api-table/index.ts
 create mode 100644 packages/ui/src/components/api-table/types.ts
 rename apps/playground/components/DocExample.vue => packages/ui/src/components/component-example/ComponentExample.vue (52%)
 create mode 100644 packages/ui/src/components/component-example/componentExample.test.ts
 create mode 100644 packages/ui/src/components/component-example/index.ts
 create mode 100644 packages/ui/src/components/component-example/types.ts
 create mode 100644 packages/ui/src/components/page-header/PageHeader.vue
 create mode 100644 packages/ui/src/components/page-header/index.ts
 create mode 100644 packages/ui/src/components/page-header/pageHeader.test.ts
 create mode 100644 packages/ui/src/components/page-header/types.ts

diff --git a/.changeset/bright-docs-primitives.md b/.changeset/bright-docs-primitives.md
new file mode 100644
index 0000000..7f0bb26
--- /dev/null
+++ b/.changeset/bright-docs-primitives.md
@@ -0,0 +1,5 @@
+---
+"@recloudstudio/ui": minor
+---
+
+Add reusable ComponentExample, ApiTable, and PageHeader primitives for documentation interfaces.
diff --git a/.changeset/config.json b/.changeset/config.json
index 38a3feb..b821332 100644
--- a/.changeset/config.json
+++ b/.changeset/config.json
@@ -1,11 +1,11 @@
 {
-	"$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
-	"changelog": "@changesets/cli/changelog",
-	"commit": false,
-	"fixed": [],
-	"linked": [],
-	"access": "public",
-	"baseBranch": "main",
-	"updateInternalDependencies": "patch",
-	"ignore": []
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
 }
diff --git a/apps/playground/app.vue b/apps/playground/app.vue
index 6fd2a44..906f5aa 100644
--- a/apps/playground/app.vue
+++ b/apps/playground/app.vue
@@ -2,75 +2,40 @@
   <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">
-      <div class="max-w-7xl mx-auto px-5 sm:px-8 h-16 flex items-center justify-between">
-        <NuxtLink to="/" class="flex items-center gap-3">
-          <BrandWordmark :height="28" />
-          <Badge variant="subtle" color="primary" size="xs">v0.3.0</Badge>
-        </NuxtLink>
+    <Navbar brand-to="/" :links="topLinks">
+      <template #logo>
+        <BrandWordmark :height="28" />
+        <Badge variant="subtle" color="primary" size="xs">v0.3.0</Badge>
+      </template>
+      <template #extra>
+        <Button
+          variant="ghost"
+          color="neutral"
+          size="icon"
+          :aria-label="isDark ? '切换至浅色模式' : '切换至深色模式'"
+          class="rounded-lg"
+          @click="toggle"
+        >
+          <Sun v-if="isDark" class="h-4 w-4 text-amber-400" />
+          <Moon v-else class="h-4 w-4 text-slate-600" />
+        </Button>
+      </template>
+      <template #actions>
+        <a href="https://github.com/ReCloudStudio" target="_blank" rel="noopener">
+          <Button variant="outline" color="neutral" size="sm">GitHub</Button>
+        </a>
+      </template>
+    </Navbar>
 
-        <div class="flex items-center gap-2">
-          <Button
-            variant="ghost"
-            color="neutral"
-            size="icon"
-            :aria-label="isDark ? '切换至浅色模式' : '切换至深色模式'"
-            class="rounded-lg"
-            @click="toggle"
-          >
-            <Sun v-if="isDark" class="w-4 h-4 text-amber-400" />
-            <Moon v-else class="w-4 h-4 text-slate-600" />
-          </Button>
-          <a
-            href="https://github.com/ReCloudStudio"
-            target="_blank"
-            rel="noopener"
-            aria-label="在 GitHub 上查看 ReCloud Studio"
-            class="inline-flex h-7 items-center justify-center gap-1.5 rounded-lg bg-transparent px-2.5 text-xs font-semibold tracking-[-0.01em] text-slate-800 ring-1 ring-inset ring-slate-300 shadow-xs transition-all duration-150 ease-out hover:bg-slate-100/70 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 dark:text-slate-200 dark:ring-slate-700 dark:hover:bg-slate-800/60"
-          >
-            <svg class="w-3.5 h-3.5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
-              <path fill-rule="evenodd" clip-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.53 1.032 1.53 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" />
-            </svg>
-            GitHub
-          </a>
-        </div>
-      </div>
-    </header>
-
-    <div class="w-full max-w-7xl mx-auto px-5 sm:px-8 py-10 lg:py-12 flex gap-12 pb-24 lg:pb-12 flex-1">
+    <div class="mx-auto flex w-full max-w-[90rem] flex-1 gap-[clamp(1.25rem,3vw,3rem)] px-[clamp(0.75rem,1.8vw,2rem)] py-10 pb-24 lg:py-12 lg:pb-12">
       <!-- 分组侧边导航 -->
-      <aside class="hidden lg:block w-60 shrink-0 sticky top-24 max-h-[calc(100vh-7rem)] overflow-y-auto pr-3 pb-8">
-        <nav class="space-y-6">
-          <div v-for="group in docGroups" :key="group.label" class="space-y-1">
-            <span class="block px-3 py-1 text-xs font-semibold uppercase tracking-[0.08em] text-slate-500 dark:text-slate-400">{{ group.label }}</span>
-            <NuxtLink
-              v-for="item in group.items"
-              :key="item.name"
-              :to="docPath(item.name)"
-              class="block px-3 py-1.5 text-sm rounded-lg transition-colors"
-              :class="isActive(item.name)
-                ? 'font-semibold bg-blue-600/10 dark:bg-[#70ACFE]/15 text-blue-700 dark:text-[#70ACFE]'
-                : 'font-medium text-slate-600 dark:text-slate-400 hover:text-slate-950 dark:hover:text-white hover:bg-slate-200/60 dark:hover:bg-slate-800/70'"
-            >{{ item.title }}</NuxtLink>
-          </div>
-        </nav>
+      <aside class="hidden max-h-[calc(100vh-7rem)] w-[clamp(13rem,18vw,16rem)] shrink-0 overflow-y-auto pb-8 pr-2 lg:sticky lg:top-24 lg:block">
+        <NavTree :groups="navigationGroups" :active-href="route.path" size="comfortable" />
       </aside>
 
-      <!-- 移动端横向分类导航 -->
-      <div class="lg:hidden fixed bottom-0 inset-x-0 z-30 bg-white/95 dark:bg-[#090E17]/95 backdrop-blur-md border-t border-slate-200/80 dark:border-slate-800/80">
-        <nav class="flex gap-1 overflow-x-auto px-4 py-2.5 no-scrollbar">
-          <NuxtLink
-            v-for="item in flatDocs"
-            :key="item.name"
-            :to="docPath(item.name)"
-            class="shrink-0 rounded-lg px-3 py-1.5 text-xs font-medium whitespace-nowrap transition-colors"
-            :class="isActive(item.name)
-              ? 'bg-blue-600/10 dark:bg-[#70ACFE]/15 text-blue-700 dark:text-[#70ACFE]'
-              : 'text-slate-600 dark:text-slate-400 hover:bg-slate-200/60 dark:hover:bg-slate-800/70'"
-          >{{ item.title }}</NuxtLink>
-        </nav>
-      </div>
+      <aside class="fixed inset-x-0 bottom-0 z-30 max-h-52 overflow-y-auto border-t border-[color:var(--border)] bg-[color:var(--background)]/95 p-4 backdrop-blur-md lg:hidden">
+        <NavTree :groups="navigationGroups" :active-href="route.path" searchable />
+      </aside>
 
       <main class="flex-1 min-w-0">
         <NuxtPage />
@@ -85,20 +50,25 @@
 import { computed } from 'vue'
 import { useRoute } from 'vue-router'
 import { BrandWordmark, Sun, Moon } from '@recloudstudio/ui/icons'
-import { useTheme } from '@recloudstudio/ui'
-import { docGroups, docPath, flatDocs } from '~/utils/catalog'
+import { useTheme, type NavTreeGroup } from '@recloudstudio/ui'
+import { docGroups, docPath } from '~/utils/catalog'
 
 const route = useRoute()
 const { isDark, toggle } = useTheme()
 
-const currentName = computed(() => {
-  const path = route.path
-  if (path === '/' || path === '') return 'index'
-  const m = path.match(/^\/components\/([^/]+)/)
-  return m ? m[1] : ''
-})
+// 顶栏只放精选入口；完整目录由侧边栏与移动端 NavTree 承载，避免 74 项链接撑爆顶栏
+const topLinks = computed(() => [
+  { label: '介绍', to: '/', active: route.path === '/' },
+  { label: '快速开始', to: '/#quick-start', active: false },
+  { label: '组件总览', to: '/#components', active: false },
+  { label: '色彩与渐变', to: '/components/colors', active: route.path === '/components/colors' }
+])
 
-function isActive(name: string): boolean {
-  return currentName.value === name
-}
+const navigationGroups = computed<NavTreeGroup[]>(() => docGroups.map(group => ({
+  title: group.label,
+  items: group.items.map(item => ({
+    title: item.title,
+    to: docPath(item.name)
+  }))
+})))
 </script>
diff --git a/apps/playground/components/DocApiTable.vue b/apps/playground/components/DocApiTable.vue
deleted file mode 100644
index fe418e8..0000000
--- a/apps/playground/components/DocApiTable.vue
+++ /dev/null
@@ -1,40 +0,0 @@
-<template>
-  <section class="space-y-3">
-    <h3 class="text-base font-semibold tracking-tight text-slate-900 dark:text-white">API 参考</h3>
-    <div class="overflow-x-auto rounded-xl ring-1 ring-inset ring-slate-200/80 dark:ring-slate-800/80 bg-white dark:bg-[#0B1220]">
-      <table class="w-full text-left text-sm">
-        <thead>
-          <tr class="border-b border-slate-200/80 dark:border-slate-800/80 text-xs font-semibold text-slate-500 dark:text-slate-400">
-            <th class="px-4 py-2.5">属性</th>
-            <th class="px-4 py-2.5">类型</th>
-            <th class="px-4 py-2.5">默认值</th>
-            <th class="px-4 py-2.5">说明</th>
-          </tr>
-        </thead>
-        <tbody class="divide-y divide-slate-100 dark:divide-slate-800/70">
-          <tr v-for="row in props.rows" :key="row.name" class="align-top">
-            <td class="px-4 py-2.5 font-mono text-[13px] font-medium text-[#2563EB] dark:text-[#70ACFE] whitespace-nowrap">{{ row.name }}</td>
-            <td class="px-4 py-2.5 font-mono text-[12px] text-slate-600 dark:text-slate-300">{{ row.type }}</td>
-            <td class="px-4 py-2.5 font-mono text-[12px] text-slate-500 dark:text-slate-400 whitespace-nowrap">{{ row.default || '—' }}</td>
-            <td class="px-4 py-2.5 text-[13px] leading-6 text-slate-600 dark:text-slate-300">{{ row.description }}</td>
-          </tr>
-        </tbody>
-      </table>
-    </div>
-  </section>
-</template>
-
-<script setup lang="ts">
-export interface DocApiRow {
-  name: string
-  type: string
-  default?: string
-  description: string
-}
-
-export interface DocApiTableProps {
-  rows: DocApiRow[]
-}
-
-const props = withDefaults(defineProps<DocApiTableProps>(), {})
-</script>
diff --git a/apps/playground/components/DocFooter.vue b/apps/playground/components/DocFooter.vue
index ad893a5..99b96cd 100644
--- a/apps/playground/components/DocFooter.vue
+++ b/apps/playground/components/DocFooter.vue
@@ -1,88 +1,46 @@
 <template>
-  <footer class="border-t border-slate-200/80 dark:border-slate-800/80 bg-white dark:bg-[#0B1220]">
-    <div class="max-w-7xl mx-auto px-5 sm:px-8 pt-12 pb-28 lg:pb-12">
-      <div class="flex flex-col gap-10 md:flex-row md:items-start md:justify-between">
-        <div class="max-w-sm space-y-3">
-          <NuxtLink to="/" class="inline-flex items-center">
-            <BrandWordmark :height="26" />
-          </NuxtLink>
-          <p class="text-sm leading-6 text-slate-500 dark:text-slate-400">
-            为 ReCloud Studio 控制台与文档门户而生的 <span class="whitespace-nowrap">Vue 3 / Nuxt 4</span> 组件库，遵循官方品牌设计规范。
-          </p>
-          <div class="flex items-center gap-2 pt-1">
-            <a href="https://github.com/ReCloudStudio" target="_blank" rel="noopener" aria-label="GitHub">
-              <Button variant="ghost" color="neutral" size="icon" class="rounded-lg">
-                <svg class="w-4 h-4" viewBox="0 0 24 24" fill="currentColor">
-                  <path fill-rule="evenodd" clip-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.53 1.032 1.53 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" />
-                </svg>
-              </Button>
-            </a>
-            <a href="https://docs.worldexecute.me/brand/design/" target="_blank" rel="noopener" aria-label="设计规范">
-              <Button variant="ghost" color="neutral" size="icon" class="rounded-lg">
-                <BookOpen class="w-4 h-4" />
-              </Button>
-            </a>
-            <a href="https://icon.worldexecute.me" target="_blank" rel="noopener" aria-label="品牌图标">
-              <Button variant="ghost" color="neutral" size="icon" class="rounded-lg">
-                <Cloud class="w-4 h-4" />
-              </Button>
-            </a>
-          </div>
-        </div>
-
-        <div class="grid grid-cols-2 gap-x-12 gap-y-10 sm:grid-cols-3">
-          <div v-for="group in groups" :key="group.label" class="space-y-2.5">
-            <span class="block text-xs font-semibold uppercase tracking-[0.08em] text-slate-500 dark:text-slate-400">{{ group.label }}</span>
-            <ul class="space-y-2">
-              <li v-for="link in group.links" :key="link.label">
-                <NuxtLink
-                  v-if="link.to"
-                  :to="link.to"
-                  class="text-sm font-medium text-slate-600 dark:text-slate-400 hover:text-slate-950 dark:hover:text-white transition-colors"
-                >{{ link.label }}</NuxtLink>
-                <a
-                  v-else
-                  :href="link.href"
-                  target="_blank"
-                  rel="noopener"
-                  class="text-sm font-medium text-slate-600 dark:text-slate-400 hover:text-slate-950 dark:hover:text-white transition-colors"
-                >{{ link.label }}</a>
-              </li>
-            </ul>
-          </div>
-        </div>
-      </div>
-
-      <div class="mt-12 pt-6 border-t border-slate-200/80 dark:border-slate-800/80 flex flex-col sm:flex-row items-center justify-between gap-3">
-        <p class="text-xs text-slate-500 dark:text-slate-400">
-          © 2026 ReCloud Studio · 代码以 AGPL-3.0 协议开源
-        </p>
-        <div class="flex items-center gap-2">
-          <Badge variant="subtle" color="primary" size="xs">v0.3.0</Badge>
-          <span class="text-xs text-slate-500 dark:text-slate-400">Vue 3 · Nuxt 4 · Reka UI · Tailwind v4</span>
-        </div>
-      </div>
-    </div>
-  </footer>
+  <Footer
+    :columns="columns"
+    copyright="© 2026 ReCloud Studio · 代码以 AGPL-3.0 协议开源"
+    :socials="socials"
+    class="pb-16 lg:pb-0"
+  >
+    <template #logo>
+      <NuxtLink to="/" class="inline-flex items-center">
+        <BrandWordmark :height="26" />
+      </NuxtLink>
+    </template>
+    <template #description>
+      为 ReCloud Studio 控制台与文档门户而生的 <span class="whitespace-nowrap">Vue 3 / Nuxt 4</span> 组件库，遵循官方品牌设计规范。
+    </template>
+    <template #socials>
+      <a href="https://github.com/ReCloudStudio" target="_blank" rel="noopener" aria-label="GitHub">
+        <Button variant="ghost" color="neutral" size="icon" class="rounded-lg">
+          GitHub
+        </Button>
+      </a>
+      <a href="https://docs.worldexecute.me/brand/design/" target="_blank" rel="noopener" aria-label="设计规范">
+        <Button variant="ghost" color="neutral" size="icon" class="rounded-lg">
+          <BookOpen class="h-4 w-4" />
+        </Button>
+      </a>
+      <a href="https://icon.worldexecute.me" target="_blank" rel="noopener" aria-label="品牌图标">
+        <Button variant="ghost" color="neutral" size="icon" class="rounded-lg">
+          <Cloud class="h-4 w-4" />
+        </Button>
+      </a>
+      <Badge variant="subtle" color="primary" size="xs">v0.3.0</Badge>
+    </template>
+  </Footer>
 </template>
 
 <script setup lang="ts">
+import type { FooterColumn, FooterSocial } from '@recloudstudio/ui'
 import { BrandWordmark, BookOpen, Cloud } from '@recloudstudio/ui/icons'
 
-type FooterLink = {
-  label: string
-  to?: string
-  href?: string
-}
-
-type FooterGroup = {
-  label: string
-  links: FooterLink[]
-}
-
-const groups: FooterGroup[] = [
+const columns: FooterColumn[] = [
   {
-    label: '文档',
+    title: '文档',
     links: [
       { label: '快速开始', to: '/' },
       { label: '色彩与渐变', to: '/components/colors' },
@@ -91,7 +49,7 @@ const groups: FooterGroup[] = [
     ]
   },
   {
-    label: '品牌',
+    title: '品牌',
     links: [
       { label: '设计规范', href: 'https://docs.worldexecute.me/brand/design/' },
       { label: '官方图标库', href: 'https://icon.worldexecute.me' },
@@ -99,7 +57,7 @@ const groups: FooterGroup[] = [
     ]
   },
   {
-    label: '资源',
+    title: '资源',
     links: [
       { label: 'GitHub', href: 'https://github.com/ReCloudStudio' },
       { label: 'AGPL-3.0 协议', href: 'https://www.gnu.org/licenses/agpl-3.0.html' },
@@ -108,4 +66,6 @@ const groups: FooterGroup[] = [
     ]
   }
 ]
+
+const socials: FooterSocial[] = []
 </script>
diff --git a/apps/playground/components/DocPageHeader.vue b/apps/playground/components/DocPageHeader.vue
deleted file mode 100644
index 41c3f68..0000000
--- a/apps/playground/components/DocPageHeader.vue
+++ /dev/null
@@ -1,28 +0,0 @@
-<template>
-  <div class="space-y-3 pb-8 border-b border-slate-200 dark:border-slate-800/80">
-    <div class="flex flex-wrap items-center gap-2.5">
-      <span class="text-xs font-bold uppercase tracking-[0.16em] text-[#2563EB] dark:text-[#70ACFE]">{{ props.group }}</span>
-      <Badge v-if="props.badge" variant="outline" color="neutral" size="xs">{{ props.badge }}</Badge>
-    </div>
-    <h1 class="text-3xl sm:text-4xl font-bold tracking-tight text-slate-950 dark:text-white">
-      {{ props.title }}
-    </h1>
-    <p class="text-base text-slate-600 dark:text-slate-300 leading-7 max-w-2xl">
-      {{ props.description }}
-    </p>
-  </div>
-</template>
-
-<script setup lang="ts">
-export interface DocPageHeaderProps {
-  title: string
-  description: string
-  group?: string
-  badge?: string
-}
-
-const props = withDefaults(defineProps<DocPageHeaderProps>(), {
-  group: 'Components',
-  badge: ''
-})
-</script>
diff --git a/apps/playground/components/DocPageNav.vue b/apps/playground/components/DocPageNav.vue
index 520fe4d..cd2f513 100644
--- a/apps/playground/components/DocPageNav.vue
+++ b/apps/playground/components/DocPageNav.vue
@@ -1,28 +1,21 @@
 <template>
-  <nav v-if="adjacent.prev || adjacent.next" class="flex items-stretch gap-4 pt-2" aria-label="文档翻页">
-    <NuxtLink
-      v-if="adjacent.prev"
-      :to="docPath(adjacent.prev.name)"
-      class="group flex-1 rounded-xl ring-1 ring-inset ring-slate-200/80 dark:ring-slate-800/80 bg-white dark:bg-[#0B1220] px-5 py-4 hover:ring-[#2563EB]/40 dark:hover:ring-[#70ACFE]/40 transition-all"
-    >
-      <span class="block text-xs text-slate-500 dark:text-slate-400 mb-1">上一页</span>
-      <span class="text-sm font-semibold text-slate-800 dark:text-slate-100 group-hover:text-[#2563EB] dark:group-hover:text-[#70ACFE] transition-colors">{{ adjacent.prev.title }}</span>
-    </NuxtLink>
-    <div v-else class="flex-1" />
-    <NuxtLink
-      v-if="adjacent.next"
-      :to="docPath(adjacent.next.name)"
-      class="group flex-1 rounded-xl ring-1 ring-inset ring-slate-200/80 dark:ring-slate-800/80 bg-white dark:bg-[#0B1220] px-5 py-4 text-right hover:ring-[#2563EB]/40 dark:hover:ring-[#70ACFE]/40 transition-all"
-    >
-      <span class="block text-xs text-slate-500 dark:text-slate-400 mb-1">下一页</span>
-      <span class="text-sm font-semibold text-slate-800 dark:text-slate-100 group-hover:text-[#2563EB] dark:group-hover:text-[#70ACFE] transition-colors">{{ adjacent.next.title }}</span>
-    </NuxtLink>
-  </nav>
+  <PrevNext :prev="previous" :next="following" />
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue'
 import { adjacentDocs, docPath } from '~/utils/catalog'
 
-const props = withDefaults(defineProps<{ name: string }>(), {})
-const adjacent = adjacentDocs(props.name)
+const props = defineProps<{ name: string }>()
+const adjacent = computed(() => adjacentDocs(props.name))
+
+const previous = computed(() => {
+  const item = adjacent.value.prev
+  return item ? { title: item.title, to: docPath(item.name) } : undefined
+})
+
+const following = computed(() => {
+  const item = adjacent.value.next
+  return item ? { title: item.title, to: docPath(item.name) } : undefined
+})
 </script>
diff --git a/apps/playground/package.json b/apps/playground/package.json
index d61f45b..ad21163 100644
--- a/apps/playground/package.json
+++ b/apps/playground/package.json
@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "nuxt dev",
+    "dev": "nuxt dev --host 0.0.0.0 --port 3100",
     "build": "nuxt build",
     "generate": "nuxt generate",
     "preview": "nuxt preview",
@@ -12,13 +12,14 @@
   },
   "dependencies": {
     "@recloudstudio/ui": "workspace:*",
-    "nuxt": "^4.0.0"
+    "nuxt": "^4.0.0",
+    "vue-router": "^5.3.1"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.0.0",
     "shiki": "^4.5.0",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.2",
-    "vue-tsc": "^2.2.8"
+    "vue-tsc": "^3.3.12"
   }
 }
diff --git a/apps/playground/pages/components/accordion.vue b/apps/playground/pages/components/accordion.vue
index 08bc33d..497e996 100644
--- a/apps/playground/pages/components/accordion.vue
+++ b/apps/playground/pages/components/accordion.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Accordion 手风琴" description="单开 / 多开折叠问答，chevron 旋转与展开动画。" />
+    <PageHeader title="Accordion 手风琴" description="单开 / 多开折叠问答，chevron 旋转与展开动画。" />
 
-    <DocExample title="单开模式" description="type=multiple 允许多项同时展开。" :code="rcCode0">
+    <ComponentExample title="单开模式" description="type=multiple 允许多项同时展开。" :code="rcCode0">
       <Accordion v-model="value" :items="[
         { value: 'quota', title: '配额与限额', content: '每个账户默认包含 256 个边缘节点、50 Gbps 突发带宽与 3 个可用区冗余组。' },
         { value: 'billing', title: '计费口径', content: '按小时粒度结算，入站流量免费，出站 Anycast 流量按阶梯单价计费。' },
         { value: 'compliance', title: '合规与审计', content: '全量操作审计日志保留 180 天，支持导出至对象存储归档。' }
       ]" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="accordion" />
   </div>
diff --git a/apps/playground/pages/components/alert-dialog.vue b/apps/playground/pages/components/alert-dialog.vue
index f00d221..93cf4a6 100644
--- a/apps/playground/pages/components/alert-dialog.vue
+++ b/apps/playground/pages/components/alert-dialog.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="AlertDialog 警示对话框" description="破坏性操作的强确认流：无法点击遮罩关闭，取消 / 确认双按钮。" />
+    <PageHeader title="AlertDialog 警示对话框" description="破坏性操作的强确认流：无法点击遮罩关闭，取消 / 确认双按钮。" />
 
-    <DocExample title="终止实例" description="destructive 将确认按钮转为红色。" :code="rcCode0">
+    <ComponentExample title="终止实例" description="destructive 将确认按钮转为红色。" :code="rcCode0">
       <AlertDialog
         title="终止实例 hkg-edge-07？"
         description="该操作不可撤销，实例上的所有活跃连接将立即断开。"
@@ -14,9 +14,9 @@
           <Button variant="soft" color="error">危险确认 (Alert Dialog)</Button>
         </template>
       </AlertDialog>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="alert-dialog" />
   </div>
diff --git a/apps/playground/pages/components/anchor-heading.vue b/apps/playground/pages/components/anchor-heading.vue
index 385253c..d247253 100644
--- a/apps/playground/pages/components/anchor-heading.vue
+++ b/apps/playground/pages/components/anchor-heading.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="AnchorHeading 锚点标题" description="悬停时展示 # 锚点图标，点击自动复制指向该小节的直接链接。" />
+    <PageHeader title="AnchorHeading 锚点标题" description="悬停时展示 # 锚点图标，点击自动复制指向该小节的直接链接。" />
 
-    <DocExample title="各级标题示例" description="支持 as 属性配置 h1 到 h6 各级标题，且自动根据标题正文生成 URL-friendly 的 ID。" :code="codeBasic">
+    <ComponentExample 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>
@@ -13,9 +13,9 @@
         <AnchorHeading as="h4">可选依赖项</AnchorHeading>
         <p class="text-sm text-slate-600 dark:text-slate-400">如需使用代码块高亮，可按需集成 Shiki。</p>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="anchor-heading" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/app-shell.vue b/apps/playground/pages/components/app-shell.vue
index eae004c..19a1d5d 100644
--- a/apps/playground/pages/components/app-shell.vue
+++ b/apps/playground/pages/components/app-shell.vue
@@ -1,11 +1,11 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader
+    <PageHeader
       title="AppShell 应用布局"
       description="为开发者控制台提供桌面侧栏、移动端抽屉入口与受约束的内容区骨架。"
     />
 
-    <DocExample
+    <ComponentExample
       title="响应式控制台骨架"
       description="桌面端可收起侧栏；小于 lg 时使用 mobile-menu-trigger 插槽将同一导航放入 Sheet。"
       :code="responsiveCode"
@@ -105,7 +105,7 @@
           </div>
         </AppShell>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <section class="space-y-4">
       <h2 class="text-xl font-semibold tracking-tight text-[var(--foreground)]">导航职责边界</h2>
@@ -122,7 +122,7 @@
       </div>
     </section>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="app-shell" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/aspect-ratio.vue b/apps/playground/pages/components/aspect-ratio.vue
index 3a1852d..c622867 100644
--- a/apps/playground/pages/components/aspect-ratio.vue
+++ b/apps/playground/pages/components/aspect-ratio.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="AspectRatio 宽高比" description="固定比例容器，用于视频、截图与封面占位。" />
+    <PageHeader title="AspectRatio 宽高比" description="固定比例容器，用于视频、截图与封面占位。" />
 
-    <DocExample title="16:9 媒体区" description="缩放宽度时高度自动保持比例。" :code="rcCode0">
+    <ComponentExample title="16:9 媒体区" description="缩放宽度时高度自动保持比例。" :code="rcCode0">
       <AspectRatio :ratio="16 / 9" class="max-w-md">
         <div class="flex h-full w-full items-center justify-center bg-gradient-to-b from-[#C8E0FD] via-[#70ACFE] to-[#3069C9] text-sm font-semibold text-white">
           16 : 9 品牌渐变媒体区
         </div>
       </AspectRatio>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="aspect-ratio" />
   </div>
diff --git a/apps/playground/pages/components/avatar.vue b/apps/playground/pages/components/avatar.vue
index e041d86..5f4d85b 100644
--- a/apps/playground/pages/components/avatar.vue
+++ b/apps/playground/pages/components/avatar.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Avatar 头像" description="图像、降级文本与在线状态四态圆点，覆盖团队成员与操作人头像场景。" />
+    <PageHeader title="Avatar 头像" description="图像、降级文本与在线状态四态圆点，覆盖团队成员与操作人头像场景。" />
 
-    <DocExample title="尺寸与状态" description="xs 到 xl 五档，状态点位于右上角，浮出头像边界并带描边。" :code="rcCode0">
+    <ComponentExample title="尺寸与状态" description="xs 到 xl 五档，状态点位于右上角，浮出头像边界并带描边。" :code="rcCode0">
       <div class="demo-grid">
         <Avatar fallback="RC" size="xs" />
         <Avatar fallback="RC" size="sm" status="online" />
@@ -10,9 +10,9 @@
         <Avatar fallback="OP" size="lg" status="away" />
         <Avatar fallback="GU" size="xl" status="offline" class="bg-slate-100 text-slate-500 dark:bg-slate-800" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="团队行场景" description="与 Badge 组合的标准运维人员行。" :code="rcCode1">
+    <ComponentExample title="团队行场景" description="与 Badge 组合的标准运维人员行。" :code="rcCode1">
       <div class="flex items-center justify-between gap-4 max-w-sm">
         <div class="flex items-center gap-3">
           <Avatar fallback="RS" size="lg" status="online" class="bg-blue-100 text-[#1E63CE] dark:bg-blue-950/60 dark:text-[#70ACFE]" />
@@ -23,9 +23,9 @@
         </div>
         <Badge color="success" variant="soft" dot>健康</Badge>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="avatar" />
   </div>
diff --git a/apps/playground/pages/components/badge.vue b/apps/playground/pages/components/badge.vue
index c15bd1b..46dcd58 100644
--- a/apps/playground/pages/components/badge.vue
+++ b/apps/playground/pages/components/badge.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Badge 徽章" description="轻量状态标签，适合版本、运行状态和不打断阅读的辅助信息。支持微光状态圆点与四档尺寸。" />
+    <PageHeader title="Badge 徽章" description="轻量状态标签，适合版本、运行状态和不打断阅读的辅助信息。支持微光状态圆点与四档尺寸。" />
 
-    <DocExample title="变体与色彩" description="主色、中性与语义状态色，dot 属性渲染呼吸圆点。" :code="rcCode0">
+    <ComponentExample title="变体与色彩" description="主色、中性与语义状态色，dot 属性渲染呼吸圆点。" :code="rcCode0">
       <div class="demo-grid">
         <Badge variant="solid" color="primary">Solid</Badge>
         <Badge variant="outline" color="primary">Outline</Badge>
@@ -16,9 +16,9 @@
         <Badge variant="soft" color="warning" dot>Degraded</Badge>
         <Badge variant="soft" color="error" dot>Outage</Badge>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="badge" />
   </div>
diff --git a/apps/playground/pages/components/banner.vue b/apps/playground/pages/components/banner.vue
index 28c9b67..045803a 100644
--- a/apps/playground/pages/components/banner.vue
+++ b/apps/playground/pages/components/banner.vue
@@ -1,23 +1,23 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Banner 横幅" description="用于发布网络变更、维护窗口和安全事件等需要被及时理解的信息，左侧图标自动映射语义色。" />
+    <PageHeader title="Banner 横幅" description="用于发布网络变更、维护窗口和安全事件等需要被及时理解的信息，左侧图标自动映射语义色。" />
 
-    <DocExample title="语义等级" description="primary / success / warning / error 四级通告。" :code="rcCode0">
+    <ComponentExample title="语义等级" description="primary / success / warning / error 四级通告。" :code="rcCode0">
       <div class="space-y-2.5">
         <Banner color="primary" title="全球边缘网络更新" description="亚太与欧洲区域节点现已全面启用 Anycast 智能链路分发。" />
         <Banner color="success" title="访问凭据轮转就绪" description="租户安全密钥已由 KMS 服务无感知轮换完成。" />
         <Banner color="warning" title="网络维护预警" description="法兰克福可用区将于北京时间凌晨 03:00 进行例行交换机固件维护。" />
         <Banner color="error" title="节点异常" description="gru-edge-07 连续健康检查失败，流量已自动切换至备用节点。" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="带操作按钮" description="通过 action 插槽追加低干扰操作。" :code="rcCode1">
+    <ComponentExample title="带操作按钮" description="通过 action 插槽追加低干扰操作。" :code="rcCode1">
       <Banner color="neutral" title="账单周期提醒" description="本月用量报表已生成，请及时核对出站流量费用。">
         <template #action><Button size="xs" variant="outline" color="neutral">查看报表</Button></template>
       </Banner>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="banner" />
   </div>
diff --git a/apps/playground/pages/components/breadcrumb.vue b/apps/playground/pages/components/breadcrumb.vue
index d7d2fd6..a6cf6da 100644
--- a/apps/playground/pages/components/breadcrumb.vue
+++ b/apps/playground/pages/components/breadcrumb.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Breadcrumb 面包屑" description="层级路径导航，末项自动加粗并标记 aria-current。" />
+    <PageHeader title="Breadcrumb 面包屑" description="层级路径导航，末项自动加粗并标记 aria-current。" />
 
-    <DocExample title="控制台路径" description="传 to 渲染 NuxtLink，末项无 to 即当前页。" :code="rcCode0">
+    <ComponentExample title="控制台路径" description="传 to 渲染 NuxtLink，末项无 to 即当前页。" :code="rcCode0">
       <BreadcrumbNav :items="[
         { label: '文档首页', to: '/' },
         { label: '组件总览', to: '/components/button' },
         { label: '面包屑' }
       ]" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="breadcrumb" />
   </div>
diff --git a/apps/playground/pages/components/button.vue b/apps/playground/pages/components/button.vue
index 24b646d..4d1e61d 100644
--- a/apps/playground/pages/components/button.vue
+++ b/apps/playground/pages/components/button.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Button 按钮" description="六种清晰的视觉层级，配合主色、中性与语义色，覆盖核心操作、次要操作与低干扰链接。" />
+    <PageHeader title="Button 按钮" description="六种清晰的视觉层级，配合主色、中性与语义色，覆盖核心操作、次要操作与低干扰链接。" />
 
-    <DocExample title="变体" description="solid / outline / soft / subtle / ghost / link 六种层级。" :code="variantCode">
+    <ComponentExample title="变体" description="solid / outline / soft / subtle / ghost / link 六种层级。" :code="variantCode">
       <div class="demo-grid">
         <Button variant="solid" color="primary">Solid</Button>
         <Button variant="outline" color="primary">Outline</Button>
@@ -11,9 +11,9 @@
         <Button variant="ghost" color="primary">Ghost</Button>
         <Button variant="link" color="primary">Link</Button>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="色彩" description="主色、中性与语义错误 / 警告 / 成功色。" :code="colorCode">
+    <ComponentExample title="色彩" description="主色、中性与语义错误 / 警告 / 成功色。" :code="colorCode">
       <div class="demo-grid">
         <Button variant="solid" color="primary">Primary</Button>
         <Button variant="solid" color="neutral">Neutral</Button>
@@ -23,9 +23,9 @@
         <Button variant="soft" color="success">Success</Button>
         <Button variant="soft" color="warning">Warning</Button>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="尺寸与状态" description="从 xs 到 lg 四档高度，内置 loading 与 disabled 态。" :code="sizeCode">
+    <ComponentExample title="尺寸与状态" description="从 xs 到 lg 四档高度，内置 loading 与 disabled 态。" :code="sizeCode">
       <div class="demo-grid">
         <Button variant="solid" size="xs">Extra Small</Button>
         <Button variant="solid" size="sm">Small</Button>
@@ -34,9 +34,9 @@
         <Button variant="solid" loading>Loading</Button>
         <Button variant="solid" disabled>Disabled</Button>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="带图标" description="使用 leading / trailing 图标插槽。" :code="iconCode">
+    <ComponentExample title="带图标" description="使用 leading / trailing 图标插槽。" :code="iconCode">
       <div class="demo-grid">
         <Button variant="solid" color="primary">
           <template #leading><Cloud class="h-4 w-4" /></template>
@@ -50,9 +50,9 @@
           <Settings class="h-4 w-4" />
         </Button>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="button" />
   </div>
diff --git a/apps/playground/pages/components/callout.vue b/apps/playground/pages/components/callout.vue
index 469359a..1bedaef 100644
--- a/apps/playground/pages/components/callout.vue
+++ b/apps/playground/pages/components/callout.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Callout 提示块" description="用于文档中的重点强调、操作建议、版本注意与破坏性警示。" />
+    <PageHeader title="Callout 提示块" description="用于文档中的重点强调、操作建议、版本注意与破坏性警示。" />
 
-    <DocExample title="基础类型" description="内置 info、tip、note、warning、danger 五种类型，包含匹配的图标与色彩。" :code="codeBasic">
+    <ComponentExample 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>
@@ -10,18 +10,18 @@
         <Callout type="warning" title="注意事项">修改该网络端口将导致现存客户端重连。</Callout>
         <Callout type="danger" title="破坏性操作">删除命名空间将级联清理所有关联的秘密卷和无状态服务，操作无法撤回。</Callout>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="可折叠提示块" description="设置 collapsible 允许用户收起或展开详细内容。" :code="codeCollapsible">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="callout" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/card.vue b/apps/playground/pages/components/card.vue
index 66cefa6..3bf67fb 100644
--- a/apps/playground/pages/components/card.vue
+++ b/apps/playground/pages/components/card.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Card 卡片" description="控制台内容的标准容器：标题、描述、操作区与主体分割层级，内嵌环线取代厚重描边。" />
+    <PageHeader title="Card 卡片" description="控制台内容的标准容器：标题、描述、操作区与主体分割层级，内嵌环线取代厚重描边。" />
 
-    <DocExample title="结构层级" description="header 的 action 插槽与 footer 分割线自动生成。" :code="rcCode0">
+    <ComponentExample title="结构层级" description="header 的 action 插槽与 footer 分割线自动生成。" :code="rcCode0">
       <Card title="集群健康检查" description="过去 24 小时的可用性遥测" padding="md">
         <template #action><Badge color="success" variant="soft" dot>99.99%</Badge></template>
         <div class="space-y-2">
@@ -16,17 +16,17 @@
           </div>
         </template>
       </Card>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="变体与交互" description="outline / soft / subtle 三种表面与 hoverable 微交互。" :code="rcCode1">
+    <ComponentExample title="变体与交互" description="outline / soft / subtle 三种表面与 hoverable 微交互。" :code="rcCode1">
       <div class="grid gap-4 sm:grid-cols-3">
         <Card variant="outline" title="Outline" description="默认内嵌环线"><p class="text-sm text-slate-500 dark:text-slate-400">最通用的表面。</p></Card>
         <Card variant="soft" title="Soft" description="柔和底色"><p class="text-sm text-slate-500 dark:text-slate-400">用于嵌套层级。</p></Card>
         <Card variant="subtle" hoverable title="Hoverable" description="悬停抬升"><p class="text-sm text-slate-500 dark:text-slate-400">可点击的卡片入口。</p></Card>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="card" />
   </div>
diff --git a/apps/playground/pages/components/checkbox.vue b/apps/playground/pages/components/checkbox.vue
index 9a70596..1007bf0 100644
--- a/apps/playground/pages/components/checkbox.vue
+++ b/apps/playground/pages/components/checkbox.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Checkbox 复选框" description="布尔复选项，勾选动画与焦点环线跟随品牌色。" />
+    <PageHeader title="Checkbox 复选框" description="布尔复选项，勾选动画与焦点环线跟随品牌色。" />
 
-    <DocExample title="状态" :code="rcCode0">
+    <ComponentExample title="状态" :code="rcCode0">
       <div class="flex flex-wrap items-center gap-6">
         <Checkbox v-model="checked" label="跨可用区冗余" />
         <Checkbox :model-value="true" disabled label="已锁定策略" />
         <Checkbox v-model="checked" disabled label="禁用未选" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="checkbox" />
   </div>
diff --git a/apps/playground/pages/components/code-block.vue b/apps/playground/pages/components/code-block.vue
index e4f9b5a..23f4852 100644
--- a/apps/playground/pages/components/code-block.vue
+++ b/apps/playground/pages/components/code-block.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="CodeBlock 代码块" description="带编程语言图标、文件标识、复制操作、行号和自动换行的深色代码展示容器。" />
+    <PageHeader title="CodeBlock 代码块" description="带编程语言图标、文件标识、复制操作、行号和自动换行的深色代码展示容器。" />
 
-    <DocExample title="编程语言图标显示" description="默认根据 language 或 filename 自动匹配内置编程语言图标；亦可显式关闭（icon: false）或自定义传入图标源。" :code="iconExampleCode">
+    <ComponentExample 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" />
@@ -11,21 +11,21 @@
         <!-- 显式禁用图标（保留小圆点） -->
         <CodeBlock :code="logCode" language="log" filename="output.log" :icon="false" class="max-w-2xl" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="行号与换行" description="长内容可保留行号，并按需自动换行。" :code="lineNumberCode">
+    <ComponentExample title="行号与换行" description="长内容可保留行号，并按需自动换行。" :code="lineNumberCode">
       <CodeBlock :code="configCode" language="ts" filename="config.ts" show-line-numbers wrap class="max-w-2xl" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="受限高度" description="使用 max-height 为长日志保留滚动区域。" :code="scrollCode">
+    <ComponentExample title="受限高度" description="使用 max-height 为长日志保留滚动区域。" :code="scrollCode">
       <CodeBlock :code="logCode" language="log" filename="deploy.log" show-line-numbers max-height="12rem" class="max-w-2xl" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="可折叠" description="开启 collapsible 后可点击标题栏展开 / 收起，折叠状态可通过 v-model:collapsed 受控。收起时不会触发高亮。" :code="collapsibleCode">
+    <ComponentExample title="可折叠" description="开启 collapsible 后可点击标题栏展开 / 收起，折叠状态可通过 v-model:collapsed 受控。收起时不会触发高亮。" :code="collapsibleCode">
       <CodeBlock v-model:collapsed="collapsed" :code="componentCode" language="vue" filename="StatusCard.vue" collapsible class="max-w-2xl" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="code-block" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/code-group.vue b/apps/playground/pages/components/code-group.vue
index 8d92e8b..08d63df 100644
--- a/apps/playground/pages/components/code-group.vue
+++ b/apps/playground/pages/components/code-group.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="CodeGroup 代码分组" description="专为文档与教程设计的选项卡式代码块容器，常用于多包管理器安装命令与不同语言代码对比。" />
+    <PageHeader title="CodeGroup 代码分组" description="专为文档与教程设计的选项卡式代码块容器，常用于多包管理器安装命令与不同语言代码对比。" />
 
-    <DocExample title="包管理器切换" description="结合 CodeBlock 展示不同包管理器的命令。" :code="codeBasic">
+    <ComponentExample title="包管理器切换" description="结合 CodeBlock 展示不同包管理器的命令。" :code="codeBasic">
       <div class="max-w-2xl">
         <CodeGroup v-model="activePm" :tabs="['bun', 'pnpm', 'npm', 'yarn']">
           <CodeBlock
@@ -12,9 +12,9 @@
           />
         </CodeGroup>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="code-group" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/collapsible.vue b/apps/playground/pages/components/collapsible.vue
index c7a9d64..3e414c0 100644
--- a/apps/playground/pages/components/collapsible.vue
+++ b/apps/playground/pages/components/collapsible.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="CollapsiblePanel 折叠面板" description="单区块渐进披露，适合高级选项与附加参数。" />
+    <PageHeader title="CollapsiblePanel 折叠面板" description="单区块渐进披露，适合高级选项与附加参数。" />
 
-    <DocExample title="高级选项" description="统一的箭头图标会平滑旋转表示展开态，trigger-extra 插槽可在标题行右侧追加徽标。" :code="rcCode0">
+    <ComponentExample title="高级选项" description="统一的箭头图标会平滑旋转表示展开态，trigger-extra 插槽可在标题行右侧追加徽标。" :code="rcCode0">
       <CollapsiblePanel v-model:open="open" title="高级网络参数">
         <div class="flex flex-wrap items-center gap-2">
           <Badge variant="soft" color="neutral">MTU 1500</Badge>
@@ -11,9 +11,9 @@
           <Badge variant="outline" color="neutral">GRE Tunnel: 关闭</Badge>
         </div>
       </CollapsiblePanel>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="collapsible" />
   </div>
diff --git a/apps/playground/pages/components/colors.vue b/apps/playground/pages/components/colors.vue
index 04dcc57..1559361 100644
--- a/apps/playground/pages/components/colors.vue
+++ b/apps/playground/pages/components/colors.vue
@@ -1,17 +1,17 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader group="Design Tokens" title="色彩与渐变" description="ReCloud Studio 品牌色度刻度与 180° 垂直天蓝渐变，配合克制的中性语义色层级，构成整个组件库的视觉基底。" />
+    <PageHeader group="Design Tokens" title="色彩与渐变" description="ReCloud Studio 品牌色度刻度与 180° 垂直天蓝渐变，配合克制的中性语义色层级，构成整个组件库的视觉基底。" />
 
-    <DocExample title="品牌色刻度" description="从天蓝到深品牌蓝的连续刻度，用于渐变节点与强调背景。">
+    <ComponentExample title="品牌色刻度" description="从天蓝到深品牌蓝的连续刻度，用于渐变节点与强调背景。">
       <div class="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-6 gap-2.5">
         <div v-for="c in swatches" :key="c.name" class="p-3 rounded-lg ring-1 ring-inset ring-black/5" :style="{ backgroundColor: c.hex, color: c.text }">
           <span class="block text-xs font-mono font-semibold">{{ c.name }}</span>
           <span class="text-[11px] font-mono">{{ c.hex }}</span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="垂直渐变" description="规范定义的 180° 渐变，用于品牌区、卡片头与英雄背景。" :code="gradientCode">
+    <ComponentExample title="垂直渐变" description="规范定义的 180° 渐变，用于品牌区、卡片头与英雄背景。" :code="gradientCode">
       <div class="space-y-3">
         <div class="p-4 rounded-xl bg-gradient-to-b from-[#C8E0FD] via-[#70ACFE] to-[#3069C9] text-[#0E1726] flex items-center justify-between shadow-xs">
           <div>
@@ -26,9 +26,9 @@
           卡片头渐变 --brand-gradient-card：0% #70ACFE → 100% #3069C9
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="tokenRows" />
+    <ApiTable :rows="tokenRows" />
 
     <DocPageNav name="colors" />
   </div>
diff --git a/apps/playground/pages/components/combobox.vue b/apps/playground/pages/components/combobox.vue
index a031ca0..5d2fb6a 100644
--- a/apps/playground/pages/components/combobox.vue
+++ b/apps/playground/pages/components/combobox.vue
@@ -1,13 +1,13 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Combobox 组合框" description="可搜索的下拉选择，支持分组、多选与清除按钮。" />
+    <PageHeader title="Combobox 组合框" description="可搜索的下拉选择，支持分组、多选与清除按钮。" />
 
-    <DocExample title="分组搜索" description="输入即过滤，分组标题自动聚合。" :code="rcCode0">
+    <ComponentExample title="分组搜索" description="输入即过滤，分组标题自动聚合。" :code="rcCode0">
       <Combobox v-model="value" :options="options" label="边缘节点" placeholder="搜索节点…" />
       <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">当前值：{{ value }}</p>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="combobox" />
   </div>
diff --git a/apps/playground/pages/components/command-palette.vue b/apps/playground/pages/components/command-palette.vue
index 3e4592c..ce411a9 100644
--- a/apps/playground/pages/components/command-palette.vue
+++ b/apps/playground/pages/components/command-palette.vue
@@ -1,14 +1,14 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="CommandPalette 命令面板" description="面向开发者工具的全局导航与操作入口；支持分组、模糊检索、键盘导航与可选快捷键。" />
+    <PageHeader title="CommandPalette 命令面板" description="面向开发者工具的全局导航与操作入口；支持分组、模糊检索、键盘导航与可选快捷键。" />
 
-    <DocExample title="命令与导航" description="按下 Ctrl/⌘ K 或点击按钮，使用方向键和 Enter 选择命令。" :code="rcCode0">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="command-palette" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/container.vue b/apps/playground/pages/components/container.vue
index 19ab2f3..7da67f3 100644
--- a/apps/playground/pages/components/container.vue
+++ b/apps/playground/pages/components/container.vue
@@ -1,11 +1,11 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader
+    <PageHeader
       title="Container 页面容器"
       description="规范响应式最大宽度（sm、md、lg、xl、2xl、full）与水平内边距节奏的页面级排版容器，常与 Section、Navbar 或文档主体配合使用。"
     />
 
-    <DocExample
+    <ComponentExample
       title="基础容器与尺寸对比"
       description="内置 max-w 尺寸预设与响应式水平 padding（px-4 sm:px-6 lg:px-8），保持全站对齐统一。"
       :code="rcCode0"
@@ -24,9 +24,9 @@
           Container (xl · max-w-7xl · 默认推荐)
         </Container>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="自定义标签与无内边距模式"
       description="可通过 as 属性渲染为 main/article/section 等语义化标签，并支持 padded: false 实现完全贴边。"
       :code="rcCode1"
@@ -37,9 +37,9 @@
           当内部子元素已具备自身内边距时，禁用容器内边距以避免层叠 padding。
         </p>
       </Container>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="container" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/context-menu.vue b/apps/playground/pages/components/context-menu.vue
index ed6323d..a029639 100644
--- a/apps/playground/pages/components/context-menu.vue
+++ b/apps/playground/pages/components/context-menu.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="ContextMenu 右键菜单" description="在指定区域右键唤起的上下文操作菜单，与 DropdownMenu 共享 item 协议。" />
+    <PageHeader title="ContextMenu 右键菜单" description="在指定区域右键唤起的上下文操作菜单，与 DropdownMenu 共享 item 协议。" />
 
-    <DocExample title="拓扑区域右键" description="默认插槽即右键触发区。" :code="rcCode0">
+    <ComponentExample title="拓扑区域右键" description="默认插槽即右键触发区。" :code="rcCode0">
       <ContextMenu :items="[
         { label: '刷新拓扑', onSelect: () => toast({ title: '拓扑数据已刷新', variant: 'success' }) },
         { label: '导出配置', onSelect: () => toast({ title: '配置导出中…' }) },
@@ -13,9 +13,9 @@
           在此区域点击右键
         </div>
       </ContextMenu>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="context-menu" />
   </div>
diff --git a/apps/playground/pages/components/data-table.vue b/apps/playground/pages/components/data-table.vue
index 12129e1..643a941 100644
--- a/apps/playground/pages/components/data-table.vue
+++ b/apps/playground/pages/components/data-table.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="DataTable 数据表" description="面向控制台的受控增强表格：排序、分页、行选择与一致状态。" />
+    <PageHeader title="DataTable 数据表" description="面向控制台的受控增强表格：排序、分页、行选择与一致状态。" />
 
-    <DocExample title="可控表格状态" description="排序、分页、选择状态由调用方保存；slot: true 的列查找 #cell-<key> 作用域插槽。" :code="rcCode0">
+    <ComponentExample 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>
@@ -14,9 +14,9 @@
           <Button size="xs" variant="ghost" color="neutral">管理</Button>
         </template>
       </DataTable>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="data-table" />
   </div>
diff --git a/apps/playground/pages/components/date-picker.vue b/apps/playground/pages/components/date-picker.vue
index e374c09..da73bc2 100644
--- a/apps/playground/pages/components/date-picker.vue
+++ b/apps/playground/pages/components/date-picker.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="DatePicker 日期选择" description="适用于备份、事件和任务记录的单日期与日期范围筛选，采用稳定的 YYYY-MM-DD 值。" />
+    <PageHeader title="DatePicker 日期选择" description="适用于备份、事件和任务记录的单日期与日期范围筛选，采用稳定的 YYYY-MM-DD 值。" />
 
-    <DocExample title="日期范围筛选" description="范围选择器内置快捷范围；日期禁用和边界由调用方以本地日期键控制。" :code="rcCode0">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="date-picker" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/dialog.vue b/apps/playground/pages/components/dialog.vue
index 01927d6..54897a3 100644
--- a/apps/playground/pages/components/dialog.vue
+++ b/apps/playground/pages/components/dialog.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Dialog 对话框" description="模态弹层：遮罩模糊、焦点圈闭与 Esc 关闭，支持 header/footer 结构插槽。" />
+    <PageHeader title="Dialog 对话框" description="模态弹层：遮罩模糊、焦点圈闭与 Esc 关闭，支持 header/footer 结构插槽。" />
 
-    <DocExample title="表单弹层" description="trigger 插槽或受控 open 均可。" :code="rcCode0">
+    <ComponentExample title="表单弹层" description="trigger 插槽或受控 open 均可。" :code="rcCode0">
       <Button variant="solid" color="primary" @click="open = true">打开对话框</Button>
       <Dialog v-model:open="open" title="配置虚拟网络网段" description="更新当前 VPC 的 CIDR 规则，此操作将同步至边界安全网关。">
         <div class="space-y-3 py-1">
@@ -14,9 +14,9 @@
           <Button variant="solid" color="primary" @click="open = false">确认应用</Button>
         </template>
       </Dialog>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="dialog" />
   </div>
diff --git a/apps/playground/pages/components/dropdown-menu.vue b/apps/playground/pages/components/dropdown-menu.vue
index 6a79950..f615ac5 100644
--- a/apps/playground/pages/components/dropdown-menu.vue
+++ b/apps/playground/pages/components/dropdown-menu.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="DropdownMenu 下拉菜单" description="操作菜单：图标、快捷键提示、分隔线与破坏性项，全键盘可达。" />
+    <PageHeader title="DropdownMenu 下拉菜单" description="操作菜单：图标、快捷键提示、分隔线与破坏性项，全键盘可达。" />
 
-    <DocExample title="实例操作" description="items 数组声明式定义，separator 项仅渲染分隔线。" :code="rcCode0">
+    <ComponentExample title="实例操作" description="items 数组声明式定义，separator 项仅渲染分隔线。" :code="rcCode0">
       <DropdownMenu :items="[
         { label: '查看拓扑分析', onSelect: () => toast({ title: '导航至拓扑分析视图' }) },
         { label: '复制连接字符串', onSelect: () => toast({ title: '已复制凭证至剪贴板', variant: 'success' }) },
@@ -13,9 +13,9 @@
           <Button variant="outline" color="neutral">选项菜单</Button>
         </template>
       </DropdownMenu>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="dropdown-menu" />
   </div>
diff --git a/apps/playground/pages/components/editable.vue b/apps/playground/pages/components/editable.vue
index cf33e08..1c9c5d6 100644
--- a/apps/playground/pages/components/editable.vue
+++ b/apps/playground/pages/components/editable.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Editable 行内编辑" description="点击即改的文本：虚线预览、进入编辑自动全选、Enter 提交 Esc 取消。" />
+    <PageHeader title="Editable 行内编辑" description="点击即改的文本：虚线预览、进入编辑自动全选、Enter 提交 Esc 取消。" />
 
-    <DocExample title="基础" description="失焦或取消恢复原值。" :code="rcCode0">
+    <ComponentExample title="基础" description="失焦或取消恢复原值。" :code="rcCode0">
       <div class="flex items-center gap-3">
         <Editable v-model="name" placeholder="点击编辑集群名称" />
         <Badge variant="outline" color="neutral" size="xs">集群别名</Badge>
       </div>
       <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">当前值：{{ name || '（空）' }}</p>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="editable" />
   </div>
diff --git a/apps/playground/pages/components/empty-state.vue b/apps/playground/pages/components/empty-state.vue
index 3a86728..368958a 100644
--- a/apps/playground/pages/components/empty-state.vue
+++ b/apps/playground/pages/components/empty-state.vue
@@ -1,15 +1,15 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="EmptyState 空状态" description="空数据页面的引导容器：图标、标题、描述与操作区。" />
+    <PageHeader title="EmptyState 空状态" description="空数据页面的引导容器：图标、标题、描述与操作区。" />
 
-    <DocExample title="基础" description="icon 插槽与默认操作区插槽。" :code="rcCode0">
+    <ComponentExample title="基础" description="icon 插槽与默认操作区插槽。" :code="rcCode0">
       <EmptyState title="暂无待处理告警" description="新的网络事件和可用性告警将在这里出现。" class="py-7">
         <template #icon><BrandLogo :size="20" /></template>
         <Button size="sm" variant="outline" color="neutral">查看事件中心</Button>
       </EmptyState>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="empty-state" />
   </div>
diff --git a/apps/playground/pages/components/field.vue b/apps/playground/pages/components/field.vue
index 50b685f..d0cfcbf 100644
--- a/apps/playground/pages/components/field.vue
+++ b/apps/playground/pages/components/field.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Field / Form 表单布局" description="Field 将标签、说明与错误信息关联到控件；Form 提供一致的字段垂直间距。" />
+    <PageHeader title="Field / Form 表单布局" description="Field 将标签、说明与错误信息关联到控件；Form 提供一致的字段垂直间距。" />
 
-    <DocExample title="关联输入框" description="传入 id 后，Field 的 label 与说明文本会自动关联到插槽内控件。" :code="rcCode0">
+    <ComponentExample title="关联输入框" description="传入 id 后，Field 的 label 与说明文本会自动关联到插槽内控件。" :code="rcCode0">
       <Form class="max-w-md">
         <Field id="cluster-name" label="集群名称" hint="仅可使用小写字母、数字和连字符" required>
           <template #default="field">
@@ -17,9 +17,9 @@
         </Field>
         <Input v-model="endpoint" label="API 端点" error="该端点未通过 TLS 证书校验" required />
       </Form>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="field" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/file-upload.vue b/apps/playground/pages/components/file-upload.vue
index 784c546..e9a8383 100644
--- a/apps/playground/pages/components/file-upload.vue
+++ b/apps/playground/pages/components/file-upload.vue
@@ -1,18 +1,18 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="FileUpload 文件上传" description="为资源、头像、镜像与配置导入提供可拖放的多文件上传工作流，状态始终由文件列表清晰呈现。" />
+    <PageHeader title="FileUpload 文件上传" description="为资源、头像、镜像与配置导入提供可拖放的多文件上传工作流，状态始终由文件列表清晰呈现。" />
 
-    <DocExample title="带进度的资源上传" description="可拖放多张图片；演示请求会显示进度，并随机模拟一次可重试的失败。" :code="rcCode0">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocExample title="配置文件校验" description="不传 upload 时，组件作为文件选择与校验控件使用；通过 change 获取当前文件项。" :code="rcCode1">
+    <ComponentExample 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 && configFiles[0]" class="text-xs text-slate-500 dark:text-slate-400">已选择 {{ configFiles[0].file.name }}</p>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="file-upload" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/footer.vue b/apps/playground/pages/components/footer.vue
index 50a74cd..482785a 100644
--- a/apps/playground/pages/components/footer.vue
+++ b/apps/playground/pages/components/footer.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Footer 站点页脚" description="多列链接分组、产品定位说明、版权声明与社交媒体图标插槽。" />
+    <PageHeader title="Footer 站点页脚" description="多列链接分组、产品定位说明、版权声明与社交媒体图标插槽。" />
 
-    <DocExample title="多列站点页脚" description="包含品牌简述、4 列导航分组与底部版权条。" :code="codeBasic">
+    <ComponentExample 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"
@@ -11,9 +11,9 @@
           :socials="sampleSocials"
         />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="footer" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/hero.vue b/apps/playground/pages/components/hero.vue
index d42ac95..e53536b 100644
--- a/apps/playground/pages/components/hero.vue
+++ b/apps/playground/pages/components/hero.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Hero 首屏横幅" description="面向落地页、官网门户与产品首页的首屏大横幅，支持居中排版、左右图文分栏及紧凑极简模式。" />
+    <PageHeader title="Hero 首屏横幅" description="面向落地页、官网门户与产品首页的首屏大横幅，支持居中排版、左右图文分栏及紧凑极简模式。" />
 
-    <DocExample title="居中主视觉模式 (center)" description="适合配合徽标、醒目标题、副标题、双 CTA 与下方预览画面。" :code="codeCenter">
+    <ComponentExample 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"
@@ -21,9 +21,9 @@
           </template>
         </Hero>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="图文分栏模式 (split)" description="左侧文本导流，右侧展示交互模型或媒体卡片。" :code="codeSplit">
+    <ComponentExample 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"
@@ -40,9 +40,9 @@
           </template>
         </Hero>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="hero" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/hover-card.vue b/apps/playground/pages/components/hover-card.vue
index a7ce3d8..71f7dff 100644
--- a/apps/playground/pages/components/hover-card.vue
+++ b/apps/playground/pages/components/hover-card.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="HoverCard 悬停卡片" description="悬停预览卡片：人员信息、节点详情等低承诺交互。" />
+    <PageHeader title="HoverCard 悬停卡片" description="悬停预览卡片：人员信息、节点详情等低承诺交互。" />
 
-    <DocExample title="人员卡片" description="openDelay / closeDelay 可调。" :code="rcCode0">
+    <ComponentExample title="人员卡片" description="openDelay / closeDelay 可调。" :code="rcCode0">
       <HoverCard>
         <template #trigger>
           <Button variant="outline" color="neutral">悬停查看</Button>
@@ -18,9 +18,9 @@
           <p class="text-xs leading-relaxed text-slate-600 dark:text-slate-400">悬停 300ms 后自动展开，离开 200ms 后关闭。</p>
         </div>
       </HoverCard>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="hover-card" />
   </div>
diff --git a/apps/playground/pages/components/icon.vue b/apps/playground/pages/components/icon.vue
index b330d41..9c7718c 100644
--- a/apps/playground/pages/components/icon.vue
+++ b/apps/playground/pages/components/icon.vue
@@ -12,7 +12,7 @@
     </header>
 
     <!-- 1. 多类型图标源解析展示 -->
-    <DocExample
+    <ComponentExample
       title="多种图标源类型"
       description="无缝解析 Vue 组件对象、内置前缀名称、纯图标名、内联 SVG 片段以及图片/矢量资源路径。"
       :code="sourcesCode"
@@ -39,10 +39,10 @@
           <span class="text-xs text-slate-500">图片/SVG 文件路径</span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <!-- 2. 尺寸控制 -->
-    <DocExample
+    <ComponentExample
       title="尺寸与文字排版继承"
       description="size 默认继承 '1em'，随周围文字字体大小自动缩放；亦可显式指定数值（px）或任意 CSS 尺寸单位。"
       :code="sizesCode"
@@ -82,10 +82,10 @@
           </div>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <!-- 3. 自定义图标库注册与前缀解析器 -->
-    <DocExample
+    <ComponentExample
       title="自定义图标库与前缀解析器"
       description="使用 registerIconResolver 注册外部图标体系，例如 mdi、remixicon、FontAwesome 或公司私有资产池。"
       :code="customResolverCode"
@@ -100,10 +100,10 @@
           <span class="text-sm font-medium text-slate-700 dark:text-slate-300">cloud:kubernetes</span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <!-- 4. 无障碍可访问性与回退插槽 -->
-    <DocExample
+    <ComponentExample
       title="无障碍描述与回退插槽"
       description="未提供 label 时自动应用 aria-hidden='true' 充当装饰图标；提供 label 时自动设置 role='img' 与 aria-label；当图标源未能解析时回退显示默认插槽内容。"
       :code="a11yCode"
@@ -120,10 +120,10 @@
           <span class="text-xs text-slate-500">解析失败触发 fallback 插槽</span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <!-- 5. 在其他组件中的复用体验 -->
-    <DocExample
+    <ComponentExample
       title="在控制台树与下拉菜单中无缝组合"
       description="现有 TreeView、NavTree、CommandPalette 等组件的 icon 属性已全面拓宽支持 IconSource，既可以直接使用字符串前缀，也可使用组件。"
       :code="integrationCode"
@@ -131,7 +131,7 @@
       <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="/components/button" />
       </div>
-    </DocExample>
+    </ComponentExample>
   </div>
 </template>
 
diff --git a/apps/playground/pages/components/inline-code.vue b/apps/playground/pages/components/inline-code.vue
index ef54a78..a2a4aa5 100644
--- a/apps/playground/pages/components/inline-code.vue
+++ b/apps/playground/pages/components/inline-code.vue
@@ -1,23 +1,23 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="InlineCode 行内代码" description="针对行内短代码、配置字段、CLI 命令与按键的高亮与一键复制。" />
+    <PageHeader title="InlineCode 行内代码" description="针对行内短代码、配置字段、CLI 命令与按键的高亮与一键复制。" />
 
-    <DocExample title="基础与风格" description="支持 subtle（默认）、solid 与 outline 三种风格外观。" :code="codeBasic">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocExample title="支持一键复制" description="设置 copyable 为 true，用户点击即可快捷复制行内文本到剪贴板。" :code="codeCopy">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="inline-code" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/input.vue b/apps/playground/pages/components/input.vue
index 8e69ab7..5ee35cd 100644
--- a/apps/playground/pages/components/input.vue
+++ b/apps/playground/pages/components/input.vue
@@ -1,15 +1,15 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Input 输入框" description="带标签、提示文案与错误态的文本输入；标签、说明和错误状态会自动关联至原生控件。" />
+    <PageHeader title="Input 输入框" description="带标签、提示文案与错误态的文本输入；标签、说明和错误状态会自动关联至原生控件。" />
 
-    <DocExample title="基础用法" description="hint 与 error 互斥，error 时环线转为红色。" :code="rcCode0">
+    <ComponentExample title="基础用法" description="hint 与 error 互斥，error 时环线转为红色。" :code="rcCode0">
       <div class="grid gap-5 sm:grid-cols-2">
         <Input v-model="text" label="集群标识符" placeholder="请输入节点名称…" hint="由小写字母、数字及横线组成" />
         <Input v-model="err" label="API 端点" error="该端点未通过 TLS 证书校验" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="尺寸与前后缀" description="leading / trailing 插槽嵌入更醒目的预设前后缀、图标与单位。" :code="rcCode1">
+    <ComponentExample title="尺寸与前后缀" description="leading / trailing 插槽嵌入更醒目的预设前后缀、图标与单位。" :code="rcCode1">
       <div class="grid gap-5 sm:grid-cols-2">
         <Input v-model="s1" size="sm" placeholder="Small" />
         <Input v-model="s2" size="lg" placeholder="Large" />
@@ -18,9 +18,9 @@
         </Input>
         <Input v-model="s4" placeholder="搜索节点…" disabled />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="input" />
   </div>
diff --git a/apps/playground/pages/components/kbd.vue b/apps/playground/pages/components/kbd.vue
index d145b3b..3e9866d 100644
--- a/apps/playground/pages/components/kbd.vue
+++ b/apps/playground/pages/components/kbd.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Kbd 按键提示" description="等宽键帽样式的快捷键展示，自动适配深浅色。" />
+    <PageHeader title="Kbd 按键提示" description="等宽键帽样式的快捷键展示，自动适配深浅色。" />
 
-    <DocExample title="组合键" description="xs / sm / md 三档尺寸。" :code="rcCode0">
+    <ComponentExample title="组合键" description="xs / sm / md 三档尺寸。" :code="rcCode0">
       <div class="flex flex-wrap items-center gap-2 text-sm text-slate-600 dark:text-slate-400">
         <span>全局搜索</span><Kbd>Ctrl</Kbd><Kbd>K</Kbd>
         <span class="ml-3">部署</span><Kbd>⌘</Kbd><Kbd>Enter</Kbd>
         <span class="ml-3">帮助</span><Kbd size="xs">?</Kbd>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="kbd" />
   </div>
diff --git a/apps/playground/pages/components/label.vue b/apps/playground/pages/components/label.vue
index 392c767..70494e7 100644
--- a/apps/playground/pages/components/label.vue
+++ b/apps/playground/pages/components/label.vue
@@ -1,15 +1,15 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Label 标签" description="与表单控件关联的无障碍标签，required 自动追加红色星号。" />
+    <PageHeader title="Label 标签" description="与表单控件关联的无障碍标签，required 自动追加红色星号。" />
 
-    <DocExample title="基础" description="for 绑定控件 id，点击聚焦。" :code="rcCode0">
+    <ComponentExample title="基础" description="for 绑定控件 id，点击聚焦。" :code="rcCode0">
       <div class="flex items-center gap-3 max-w-xs">
         <Label for="api-key" required>API Key</Label>
         <Input id="api-key" v-model="key" class="flex-1" placeholder="rc_live_…" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="label" />
   </div>
diff --git a/apps/playground/pages/components/locale.vue b/apps/playground/pages/components/locale.vue
index 7deae57..20f0c8d 100644
--- a/apps/playground/pages/components/locale.vue
+++ b/apps/playground/pages/components/locale.vue
@@ -7,7 +7,7 @@
       </p>
     </div>
 
-    <DocExample title="动态切换语言与组件即时生效">
+    <ComponentExample title="动态切换语言与组件即时生效">
       <template #description>
         点击切换语言环境，观察 Pagination、EmptyState、DataTable、FileUpload 与 TreeView 的文案即时响应。
       </template>
@@ -98,7 +98,7 @@
           </div>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <div class="space-y-4">
       <h2 class="text-xl font-semibold text-slate-900 dark:text-slate-100">使用方式</h2>
diff --git a/apps/playground/pages/components/markdown.vue b/apps/playground/pages/components/markdown.vue
index 689924a..f9137d2 100644
--- a/apps/playground/pages/components/markdown.vue
+++ b/apps/playground/pages/components/markdown.vue
@@ -1,11 +1,11 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader
+    <PageHeader
       title="Markdown 渲染系统"
       description="基于 unified/remark 与 ReCloud UI 内容原语的受控 Markdown/GFM 渲染系统，内置锚点标题、Shiki 代码高亮、表格、任务列表以及 :::info / :::steps / :::code-group 等文档扩展指令。"
     />
 
-    <DocExample
+    <ComponentExample
       title="全功能示例文档"
       description="直接将 Markdown 字符串渲染为 ReCloud 设计系统的富文本、代码块与扩展容器，同时支持目录（TOC）联动。"
       :code="sampleMarkdown"
@@ -22,9 +22,9 @@
           </div>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="安全策略与协议过滤"
       description="默认开启严格的协议过滤与安全策略，阻止 javascript: 协议并规范化外部链接。"
       :code="unsafeSample"
@@ -32,9 +32,9 @@
       <div class="rounded-xl border border-slate-200/80 bg-white p-6 shadow-sm dark:border-slate-800 dark:bg-[#0B1220]">
         <MarkdownRenderer :content="unsafeSample" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="markdown" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/multi-select.vue b/apps/playground/pages/components/multi-select.vue
index e72a6cd..5c7a814 100644
--- a/apps/playground/pages/components/multi-select.vue
+++ b/apps/playground/pages/components/multi-select.vue
@@ -1,17 +1,17 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="MultiSelect 多选" description="为告警渠道、区域、标签与成员分配提供可搜索、多标签的选择体验。" />
+    <PageHeader title="MultiSelect 多选" description="为告警渠道、区域、标签与成员分配提供可搜索、多标签的选择体验。" />
 
-    <DocExample title="按区域筛选节点" description="已选项显示为可移除标签；可输入过滤、从分组选项中多选，或一键清除。" :code="rcCode0">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocExample title="禁用与校验状态" description="继承 Field 的标签、提示、必填和错误信息能力。" :code="rcCode1">
+    <ComponentExample title="禁用与校验状态" description="继承 Field 的标签、提示、必填和错误信息能力。" :code="rcCode1">
       <MultiSelect v-model="reviewers" :options="reviewerOptions" label="变更审批人" error="至少指定一位审批人" required />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="multi-select" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/nav-tree.vue b/apps/playground/pages/components/nav-tree.vue
index bb5e053..16d5a58 100644
--- a/apps/playground/pages/components/nav-tree.vue
+++ b/apps/playground/pages/components/nav-tree.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="NavTree 文档树侧栏" description="用于文档站点与多层级内容目录的侧边栏组件，支持分组折叠、徽标与实时搜索过滤。" />
+    <PageHeader title="NavTree 文档树侧栏" description="用于文档站点与多层级内容目录的侧边栏组件，支持分组折叠、徽标与实时搜索过滤。" />
 
-    <DocExample title="文档分组与过滤" description="支持多级分组、折叠展开与搜索实时过滤文档条目。" :code="codeBasic">
+    <ComponentExample 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"
@@ -10,9 +10,9 @@
           :searchable="true"
         />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="nav-tree" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/navbar.vue b/apps/playground/pages/components/navbar.vue
index 7def88a..a257e94 100644
--- a/apps/playground/pages/components/navbar.vue
+++ b/apps/playground/pages/components/navbar.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Navbar 导航顶栏" description="面向站点与文档门户的全局导航顶栏，支持品牌 Logo、桌面链接、快捷 CTA 与移动端折叠抽屉。" />
+    <PageHeader title="Navbar 导航顶栏" description="面向站点与文档门户的全局导航顶栏，支持品牌 Logo、桌面链接、快捷 CTA 与移动端折叠抽屉。" />
 
-    <DocExample title="基础顶栏" description="集成品牌、徽标链接、操作按钮及移动端抽屉。" :code="codeBasic">
+    <ComponentExample 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"
@@ -15,9 +15,9 @@
           </template>
         </Navbar>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="navbar" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/navigation-menu.vue b/apps/playground/pages/components/navigation-menu.vue
index 82856da..0edfa46 100644
--- a/apps/playground/pages/components/navigation-menu.vue
+++ b/apps/playground/pages/components/navigation-menu.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="NavigationMenu 导航菜单" description="基于 Reka UI 的无障碍顶部导航，支持键盘导航、焦点管理和可选内容面板。" />
+    <PageHeader title="NavigationMenu 导航菜单" description="基于 Reka UI 的无障碍顶部导航，支持键盘导航、焦点管理和可选内容面板。" />
 
-    <DocExample title="控制台顶部导航" description="带面板的项目会由 Reka UI 管理键盘导航、焦点和展开状态。" :code="rcCode0">
+    <ComponentExample title="控制台顶部导航" description="带面板的项目会由 Reka UI 管理键盘导航、焦点和展开状态。" :code="rcCode0">
       <NavigationMenu :items="[
         { label: '概览', value: 'overview' },
         { label: '节点管理', value: 'nodes' },
@@ -16,9 +16,9 @@
           <p v-else class="px-2.5 py-1.5 text-sm text-slate-500">{{ item.label }} 面板</p>
         </template>
       </NavigationMenu>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="navigation-menu" />
   </div>
diff --git a/apps/playground/pages/components/number-field.vue b/apps/playground/pages/components/number-field.vue
index 47d9fbb..3758cfb 100644
--- a/apps/playground/pages/components/number-field.vue
+++ b/apps/playground/pages/components/number-field.vue
@@ -1,15 +1,15 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="NumberField 数字输入" description="带步进按钮的数字输入，支持边界与只读模式。" />
+    <PageHeader title="NumberField 数字输入" description="带步进按钮的数字输入，支持边界与只读模式。" />
 
-    <DocExample title="基础与尺寸" description="左右步进按钮，超界自动夹取。" :code="rcCode0">
+    <ComponentExample title="基础与尺寸" description="左右步进按钮，超界自动夹取。" :code="rcCode0">
       <div class="grid gap-5 sm:grid-cols-2 max-w-lg">
         <NumberField v-model="n1" label="节点数量" :min="1" :max="99" />
         <NumberField v-model="n2" label="批量步长" :min="0" :max="1000" :step="10" size="lg" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="number-field" />
   </div>
diff --git a/apps/playground/pages/components/pagination.vue b/apps/playground/pages/components/pagination.vue
index 0fa1ff5..bd523c6 100644
--- a/apps/playground/pages/components/pagination.vue
+++ b/apps/playground/pages/components/pagination.vue
@@ -1,13 +1,13 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Pagination 分页" description="页码折叠窗口 + 前后翻页 + 汇总文案，v-model 双向绑定当前页。" />
+    <PageHeader title="Pagination 分页" description="页码折叠窗口 + 前后翻页 + 汇总文案，v-model 双向绑定当前页。" />
 
-    <DocExample title="基础" description="siblingCount 控制当前页两侧暴露页码数。" :code="rcCode0">
+    <ComponentExample title="基础" description="siblingCount 控制当前页两侧暴露页码数。" :code="rcCode0">
       <Pagination v-model="page" :total="128" :page-size="10" />
       <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">第 {{ page }} / 13 页</p>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="pagination" />
   </div>
diff --git a/apps/playground/pages/components/pin-input.vue b/apps/playground/pages/components/pin-input.vue
index 403e7ae..92ba372 100644
--- a/apps/playground/pages/components/pin-input.vue
+++ b/apps/playground/pages/components/pin-input.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="PinInput 验证码" description="分段验证码 / OTP 输入，自动跳格与退格回退。" />
+    <PageHeader title="PinInput 验证码" description="分段验证码 / OTP 输入，自动跳格与退格回退。" />
 
-    <DocExample title="OTP 与掩码" description="otp 模式 6 位，mask 隐藏输入。" :code="rcCode0">
+    <ComponentExample title="OTP 与掩码" description="otp 模式 6 位，mask 隐藏输入。" :code="rcCode0">
       <div class="flex flex-wrap items-end gap-8">
         <div class="space-y-2">
           <Label>短信验证码 (OTP)</Label>
@@ -14,9 +14,9 @@
         </div>
       </div>
       <p class="mt-3 text-xs text-slate-500 dark:text-slate-400">OTP 值：{{ otp.join('') || '—' }}</p>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="pin-input" />
   </div>
diff --git a/apps/playground/pages/components/popover.vue b/apps/playground/pages/components/popover.vue
index 2b41239..3aff2a8 100644
--- a/apps/playground/pages/components/popover.vue
+++ b/apps/playground/pages/components/popover.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Popover 浮层" description="轻量内容弹层：标题、关闭按钮与表单友好焦点管理。" />
+    <PageHeader title="Popover 浮层" description="轻量内容弹层：标题、关闭按钮与表单友好焦点管理。" />
 
-    <DocExample title="限流设置" description="受控时 v-model:open。" :code="rcCode0">
+    <ComponentExample title="限流设置" description="受控时 v-model:open。" :code="rcCode0">
       <Popover title="速率限制设置" show-close align="center">
         <template #trigger>
           <Button variant="outline" color="neutral">气泡面板</Button>
@@ -13,9 +13,9 @@
           <Badge variant="subtle" color="neutral">Burst 20,000</Badge>
         </div>
       </Popover>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="popover" />
   </div>
diff --git a/apps/playground/pages/components/prev-next.vue b/apps/playground/pages/components/prev-next.vue
index c106f31..b9a083f 100644
--- a/apps/playground/pages/components/prev-next.vue
+++ b/apps/playground/pages/components/prev-next.vue
@@ -1,26 +1,26 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="PrevNext 翻页导航" description="用于长篇指南、API 手册与教程底部的上下篇连续导航卡片。" />
+    <PageHeader title="PrevNext 翻页导航" description="用于长篇指南、API 手册与教程底部的上下篇连续导航卡片。" />
 
-    <DocExample title="基础双向导航" description="提供左右两侧卡片，支持上一篇与下一篇标题与描述。" :code="codeBasic">
+    <ComponentExample 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>
+    </ComponentExample>
 
-    <DocExample title="单侧导航（首末篇）" description="当只有上一篇或下一篇时，空缺侧保持布局优雅对齐。" :code="codeSingle">
+    <ComponentExample title="单侧导航（首末篇）" description="当只有上一篇或下一篇时，空缺侧保持布局优雅对齐。" :code="codeSingle">
       <div class="space-y-4 max-w-2xl">
         <PrevNext
           :next="{ title: '开始快速上手', to: '/components/steps' }"
           next-label="下一章"
         />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="prev-next" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/progress.vue b/apps/playground/pages/components/progress.vue
index 7d0e8ad..4197f4d 100644
--- a/apps/playground/pages/components/progress.vue
+++ b/apps/playground/pages/components/progress.vue
@@ -1,17 +1,17 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Progress 进度条" description="任务进度、百分比与完成数量，带标签行与语义色。" />
+    <PageHeader title="Progress 进度条" description="任务进度、百分比与完成数量，带标签行与语义色。" />
 
-    <DocExample title="数值显示、色彩与尺寸" description="可单独显示百分比、完成数量，或同时显示两者。" :code="rcCode0">
+    <ComponentExample title="数值显示、色彩与尺寸" description="可单独显示百分比、完成数量，或同时显示两者。" :code="rcCode0">
       <div class="space-y-4 max-w-md">
         <Progress :value="72" label="节点同步进度" value-display="percentage" color="primary" />
         <Progress :value="8" :max="12" label="健康检查" value-display="fraction" color="success" size="sm" />
         <Progress :value="34" :max="50" label="存储用量" value-display="both" color="warning" size="sm" />
         <Progress :value="12" label="异常实例" color="error" size="sm" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="progress" />
   </div>
diff --git a/apps/playground/pages/components/radio-group.vue b/apps/playground/pages/components/radio-group.vue
index 78e2630..11d8443 100644
--- a/apps/playground/pages/components/radio-group.vue
+++ b/apps/playground/pages/components/radio-group.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="RadioGroup 单选组" description="带描述文本的选项组，支持纵向与横向排布。" />
+    <PageHeader title="RadioGroup 单选组" description="带描述文本的选项组，支持纵向与横向排布。" />
 
-    <DocExample title="调度策略选择" description="description 渲染在选项下方，disabled 项灰化。" :code="rcCode0">
+    <ComponentExample title="调度策略选择" description="description 渲染在选项下方，disabled 项灰化。" :code="rcCode0">
       <RadioGroup v-model="mode" label="调度模式" :options="[
         { label: '自动就近接入', value: 'auto', description: '按实时网络质量选择最优边缘节点' },
         { label: '固定地域锁定', value: 'pinned', description: '始终使用指定地域节点' },
         { label: '自定义权重', value: 'custom', disabled: true }
       ]" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="radio-group" />
   </div>
diff --git a/apps/playground/pages/components/rating.vue b/apps/playground/pages/components/rating.vue
index a8f8899..76cba20 100644
--- a/apps/playground/pages/components/rating.vue
+++ b/apps/playground/pages/components/rating.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Rating 评分" description="星级评分，支持只读展示与语义色。" />
+    <PageHeader title="Rating 评分" description="星级评分，支持只读展示与语义色。" />
 
-    <DocExample title="交互与只读" description="点击任一星级会连续填充此前所有星标，支持方向键调整。" :code="rcCode0">
+    <ComponentExample title="交互与只读" description="点击任一星级会连续填充此前所有星标，支持方向键调整。" :code="rcCode0">
       <div class="flex items-center gap-6">
         <div class="space-y-1">
           <Rating v-model="val" />
@@ -13,9 +13,9 @@
           <p class="text-xs text-slate-500 dark:text-slate-400">客户满意度（只读）</p>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="rating" />
   </div>
diff --git a/apps/playground/pages/components/resizable-panel.vue b/apps/playground/pages/components/resizable-panel.vue
index 83f337c..1211258 100644
--- a/apps/playground/pages/components/resizable-panel.vue
+++ b/apps/playground/pages/components/resizable-panel.vue
@@ -1,15 +1,15 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="ResizablePanel 可调面板" description="为日志、资源详情和编辑器工作区提供可拖拽且可键盘操作的分栏布局。" />
+    <PageHeader title="ResizablePanel 可调面板" description="为日志、资源详情和编辑器工作区提供可拖拽且可键盘操作的分栏布局。" />
 
-    <DocExample title="双栏工作区" description="拖动中间分隔线，或聚焦后通过方向键调整左侧面板；Home / End 跳到最小或最大尺寸。" :code="rcCode0">
+    <ComponentExample 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="flex h-full flex-col bg-white p-5 dark:bg-[#0F172A]"><p class="text-xs font-semibold uppercase tracking-wider text-slate-500">部署日志</p><CodeBlock :code="deployLog" language="log" filename="deploy.log" :icon="false" max-height="11rem" class="mt-4 flex-1" /><p class="mt-3 text-xs text-slate-500">左侧宽度：{{ panelSize }}px</p></div></template>
       </ResizablePanel>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="resizable-panel" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/scroll-area.vue b/apps/playground/pages/components/scroll-area.vue
index 97d412e..ef9a891 100644
--- a/apps/playground/pages/components/scroll-area.vue
+++ b/apps/playground/pages/components/scroll-area.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="ScrollArea 滚动区" description="自定义纤细滚动条的受限视口，深浅色自动适配。" />
+    <PageHeader title="ScrollArea 滚动区" description="自定义纤细滚动条的受限视口，深浅色自动适配。" />
 
-    <DocExample title="节点列表" description="max-height 接受任意 CSS 长度。" :code="rcCode0">
+    <ComponentExample title="节点列表" description="max-height 接受任意 CSS 长度。" :code="rcCode0">
       <ScrollArea max-height="12rem" class="max-w-sm">
         <div class="space-y-1 pr-3">
           <div v-for="(node, i) in nodes" :key="node" class="flex items-center justify-between rounded-lg px-3 py-2 text-sm ring-1 ring-inset ring-slate-200/70 dark:ring-slate-800/70">
@@ -11,9 +11,9 @@
           </div>
         </div>
       </ScrollArea>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="scroll-area" />
   </div>
diff --git a/apps/playground/pages/components/search-input.vue b/apps/playground/pages/components/search-input.vue
index 366a26f..63dd086 100644
--- a/apps/playground/pages/components/search-input.vue
+++ b/apps/playground/pages/components/search-input.vue
@@ -1,11 +1,11 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader
+    <PageHeader
       title="SearchInput 搜索框"
       description="通用纯前端搜索框组件（同时提供 SearchBox 别名导出），内置搜索图标、一键清除、Loading 状态、快捷键徽标（如 ⌘K 或 /）、防抖触发与可选的联想词/结果浮层，后端可任意对接 Elasticsearch、Meilisearch、SQL 或本地内存检索。"
     />
 
-    <DocExample
+    <ComponentExample
       title="基础搜索输入框"
       description="支持 v-model 双向绑定，内置 300ms 防抖并暴露 @search 与 @submit 事件。"
       :code="rcCode0"
@@ -23,9 +23,9 @@
           <span>提交 (@submit): <strong class="text-primary-600 dark:text-primary-400">{{ lastSubmit || '（无）' }}</strong></span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="视觉变体与尺寸规格"
       description="提供 default（线框卡片）、filled（静音填充）与 pill（胶囊圆角）三种变体，并支持 sm、md、lg 尺寸。"
       :code="rcCode1"
@@ -44,9 +44,9 @@
           <SearchInput size="lg" variant="default" placeholder="在全网知识库中搜索..." />
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="快捷键与异步 Loading 状态"
       description="支持展示 shortcut 快捷键（支持全局聚焦监听），支持 loading 模拟后端异步请求状态。"
       :code="rcCode2"
@@ -70,9 +70,9 @@
           切换 Loading 状态: {{ isLoading ? '开启' : '关闭' }}
         </button>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="联想结果与后端对接展示"
       description="传入 suggestions 列表即可展开下拉结果面板，支持键盘上下箭头高亮、Enter 选中或点击选择。"
       :code="rcCode3"
@@ -89,9 +89,9 @@
           <span class="ml-2 text-slate-500">({{ selectedItem.category }})</span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="search-input" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/section.vue b/apps/playground/pages/components/section.vue
index 98ee87b..9b012d7 100644
--- a/apps/playground/pages/components/section.vue
+++ b/apps/playground/pages/components/section.vue
@@ -1,11 +1,11 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader
+    <PageHeader
       title="Section 门户区块"
       description="具备标准化垂直间距节奏（sm、md、lg、xl）、背景变体（default、muted、card、brand）以及内置标题/副标题的营销与控制台区块容器。"
     />
 
-    <DocExample
+    <ComponentExample
       title="基础区块与垂直节奏"
       description="内置 Container 包裹与自适应标题区域，快速搭建规格统一的落地页区块。"
       :code="rcCode0"
@@ -34,9 +34,9 @@
           </div>
         </Section>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="背景变体与左对齐排版"
       description="支持 brand 渐变与 card 边框模式，支持左对齐 header。"
       :code="rcCode1"
@@ -55,9 +55,9 @@
           </p>
         </Section>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="section" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/select.vue b/apps/playground/pages/components/select.vue
index cc9815c..e88b9f3 100644
--- a/apps/playground/pages/components/select.vue
+++ b/apps/playground/pages/components/select.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Select 选择器" description="基于 Reka UI 的无障碍下拉：键盘导航、类型高亮与品牌色选中标记。" />
+    <PageHeader title="Select 选择器" description="基于 Reka UI 的无障碍下拉：键盘导航、类型高亮与品牌色选中标记。" />
 
-    <DocExample title="基础" description="options 支持 disabled 项。" :code="rcCode0">
+    <ComponentExample title="基础" description="options 支持 disabled 项。" :code="rcCode0">
       <div class="grid gap-5 sm:grid-cols-2">
         <Select v-model="region" label="目标地域" :options="[
           { label: '中国香港 (HKG)', value: 'hkg' },
@@ -12,9 +12,9 @@
         ]" />
         <Select v-model="region" label="禁用示例" :options="[{ label: '不可选', value: 'x' }]" disabled />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="select" />
   </div>
diff --git a/apps/playground/pages/components/separator.vue b/apps/playground/pages/components/separator.vue
index e2606d7..66975a8 100644
--- a/apps/playground/pages/components/separator.vue
+++ b/apps/playground/pages/components/separator.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Separator 分隔线" description="水平与垂直方向分割线，自动适配主题。" />
+    <PageHeader title="Separator 分隔线" description="水平与垂直方向分割线，自动适配主题。" />
 
-    <DocExample title="方向" :code="rcCode0">
+    <ComponentExample title="方向" :code="rcCode0">
       <div class="space-y-4 max-w-md">
         <div class="space-y-1">
           <p class="text-sm text-slate-700 dark:text-slate-300">基础信息</p>
@@ -17,9 +17,9 @@
           <span>丢包 0%</span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="separator" />
   </div>
diff --git a/apps/playground/pages/components/sheet.vue b/apps/playground/pages/components/sheet.vue
index dcb6bc6..ee309e5 100644
--- a/apps/playground/pages/components/sheet.vue
+++ b/apps/playground/pages/components/sheet.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Sheet 抽屉面板" description="用于资源详情、配置编辑和辅助操作的可访问模态侧栏，支持四个展开方向。" />
+    <PageHeader title="Sheet 抽屉面板" description="用于资源详情、配置编辑和辅助操作的可访问模态侧栏，支持四个展开方向。" />
 
-    <DocExample title="实例详情" description="默认从右侧展开；使用 header、默认和 footer 插槽构建详情工作流。" :code="rcCode0">
+    <ComponentExample 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">
@@ -19,9 +19,9 @@
           </div>
         </template>
       </Sheet>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="sheet" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/skeleton.vue b/apps/playground/pages/components/skeleton.vue
index 502ce90..bd3cac0 100644
--- a/apps/playground/pages/components/skeleton.vue
+++ b/apps/playground/pages/components/skeleton.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Skeleton 骨架屏" description="内容加载占位，脉冲动画节奏统一。" />
+    <PageHeader title="Skeleton 骨架屏" description="内容加载占位，脉冲动画节奏统一。" />
 
-    <DocExample title="占位组合" description="width/height 接受任意 CSS 长度。" :code="rcCode0">
+    <ComponentExample title="占位组合" description="width/height 接受任意 CSS 长度。" :code="rcCode0">
       <div class="grid grid-cols-3 gap-3 max-w-md">
         <Skeleton height="4.5rem" />
         <Skeleton height="4.5rem" />
@@ -13,9 +13,9 @@
         <Skeleton width="100%" height="0.75rem" />
         <Skeleton width="80%" height="0.75rem" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="skeleton" />
   </div>
diff --git a/apps/playground/pages/components/slider.vue b/apps/playground/pages/components/slider.vue
index adebcf1..a09f966 100644
--- a/apps/playground/pages/components/slider.vue
+++ b/apps/playground/pages/components/slider.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Slider 滑块" description="单值或区间滑动输入，键盘方向键可调，焦点光环清晰。" />
+    <PageHeader title="Slider 滑块" description="单值或区间滑动输入，键盘方向键可调，焦点光环清晰。" />
 
-    <DocExample title="单值与区间" description="modelValue 传数组即进入双柄区间模式。" :code="rcCode0">
+    <ComponentExample title="单值与区间" description="modelValue 传数组即进入双柄区间模式。" :code="rcCode0">
       <div class="space-y-5 max-w-md">
         <div>
           <Label>带宽上限 · {{ cap }}%</Label>
@@ -13,9 +13,9 @@
           <Slider v-model="range" :min="10" :max="200" class="mt-3 pr-2" />
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="slider" />
   </div>
diff --git a/apps/playground/pages/components/spinner.vue b/apps/playground/pages/components/spinner.vue
index e3ec1d4..e18d99b 100644
--- a/apps/playground/pages/components/spinner.vue
+++ b/apps/playground/pages/components/spinner.vue
@@ -1,17 +1,17 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Spinner 加载" description="role=status 的环形加载指示器，颜色跟随文本继承。" />
+    <PageHeader title="Spinner 加载" description="role=status 的环形加载指示器，颜色跟随文本继承。" />
 
-    <DocExample title="尺寸" description="xs 到 lg 四档；color 语义色。" :code="rcCode0">
+    <ComponentExample title="尺寸" description="xs 到 lg 四档；color 语义色。" :code="rcCode0">
       <div class="demo-grid">
         <span class="flex items-center gap-2 text-sm text-slate-500 dark:text-slate-400"><Spinner size="xs" /> 校验中…</span>
         <span class="flex items-center gap-2 text-sm text-slate-500 dark:text-slate-400"><Spinner size="sm" color="primary" /> 部署中…</span>
         <span class="flex items-center gap-2 text-sm text-slate-500 dark:text-slate-400"><Spinner size="md" /> 同步中…</span>
         <Spinner size="lg" class="text-[#2563EB] dark:text-[#70ACFE]" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="spinner" />
   </div>
diff --git a/apps/playground/pages/components/stepper.vue b/apps/playground/pages/components/stepper.vue
index 77666f2..23da7a2 100644
--- a/apps/playground/pages/components/stepper.vue
+++ b/apps/playground/pages/components/stepper.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Stepper 步骤条" description="多步流程进度指示：当前步高亮、已完成打勾、支持点击跳步。" />
+    <PageHeader title="Stepper 步骤条" description="多步流程进度指示：当前步高亮、已完成打勾、支持点击跳步。" />
 
-    <DocExample title="部署向导" description="第 {{ step }} 步 / 共 4 步；linear 模式下必须按序完成。" :code="rcCode0">
+    <ComponentExample title="部署向导" description="第 {{ step }} 步 / 共 4 步；linear 模式下必须按序完成。" :code="rcCode0">
       <Stepper v-model="step" :steps="[
         { step: 1, title: '基础信息' },
         { step: 2, title: '网络拓扑' },
@@ -13,17 +13,17 @@
         <Button variant="outline" color="neutral" size="sm" :disabled="step <= 1" @click="step--">上一步</Button>
         <Button variant="solid" color="primary" size="sm" :disabled="step >= 4" @click="step++">下一步</Button>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="纵向布局" description="orientation=vertical 适合侧栏流程。" :code="rcCode1">
+    <ComponentExample title="纵向布局" description="orientation=vertical 适合侧栏流程。" :code="rcCode1">
       <Stepper :model-value="2" orientation="vertical" :steps="[
         { step: 1, title: '提交申请', description: '已创建工单 #4821' },
         { step: 2, title: '资源审批', description: '等待配额组确认' },
         { step: 3, title: '节点交付' }
       ]" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="stepper" />
   </div>
diff --git a/apps/playground/pages/components/steps.vue b/apps/playground/pages/components/steps.vue
index 33e7e06..542afdb 100644
--- a/apps/playground/pages/components/steps.vue
+++ b/apps/playground/pages/components/steps.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Steps 文档步骤" description="面向快速上手、环境部署与排错排查文档的垂直向导步骤列表。" />
+    <PageHeader title="Steps 文档步骤" description="面向快速上手、环境部署与排错排查文档的垂直向导步骤列表。" />
 
-    <DocExample title="自动编号步骤" description="Steps 自动管理子项的序号索引与连接线。" :code="codeBasic">
+    <ComponentExample title="自动编号步骤" description="Steps 自动管理子项的序号索引与连接线。" :code="codeBasic">
       <Steps class="max-w-2xl">
         <StepItem title="安装组件库依赖" description="通过 Bun 或 npm 将 ReCloud UI 引入项目。">
           <p>在工程根目录运行：</p>
@@ -16,9 +16,9 @@
           <p>例如：引入 <InlineCode code="<Button>点击操作</Button>" />。</p>
         </StepItem>
       </Steps>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="steps" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/switch.vue b/apps/playground/pages/components/switch.vue
index 26f6c8f..80d2449 100644
--- a/apps/playground/pages/components/switch.vue
+++ b/apps/playground/pages/components/switch.vue
@@ -1,17 +1,17 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Switch 开关" description="即时生效的切换开关，适合配置项的启停控制。" />
+    <PageHeader title="Switch 开关" description="即时生效的切换开关，适合配置项的启停控制。" />
 
-    <DocExample title="尺寸与状态" :code="rcCode0">
+    <ComponentExample title="尺寸与状态" :code="rcCode0">
       <div class="flex flex-wrap items-center gap-6">
         <Switch v-model="on" size="sm" label="紧凑开关" />
         <Switch v-model="on" label="标准开关" />
         <Switch v-model="on" size="lg" label="宽松开关" />
         <Switch :model-value="true" disabled label="强制开启" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="switch" />
   </div>
diff --git a/apps/playground/pages/components/tabs.vue b/apps/playground/pages/components/tabs.vue
index 24bb89e..1ccbb52 100644
--- a/apps/playground/pages/components/tabs.vue
+++ b/apps/playground/pages/components/tabs.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Tabs 标签页" description="视图切换标签，pill 风格容器与内容面板插槽，基于 Reka UI 键盘导航。" />
+    <PageHeader title="Tabs 标签页" description="视图切换标签，pill 风格容器与内容面板插槽，基于 Reka UI 键盘导航。" />
 
-    <DocExample title="基础与内容面板" description="items 定义标签，TabsContent 按 value 匹配面板。" :code="rcCode0">
+    <ComponentExample title="基础与内容面板" description="items 定义标签，TabsContent 按 value 匹配面板。" :code="rcCode0">
       <Tabs v-model="tab" :items="[
         { label: '拓扑概览', value: 'overview' },
         { label: '性能监控', value: 'monitoring' },
@@ -19,9 +19,9 @@
           </div>
         </TabsContent>
       </Tabs>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="tabs" />
   </div>
diff --git a/apps/playground/pages/components/tag-input.vue b/apps/playground/pages/components/tag-input.vue
index e4cbccf..807a1d7 100644
--- a/apps/playground/pages/components/tag-input.vue
+++ b/apps/playground/pages/components/tag-input.vue
@@ -1,15 +1,15 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="TagInput 标签输入" description="将逗号分隔的文本转为可编辑、可删除的标签集合。" />
+    <PageHeader title="TagInput 标签输入" description="将逗号分隔的文本转为可编辑、可删除的标签集合。" />
 
-    <DocExample title="筛选值" description="输入后按 Enter、逗号或失焦即可添加；支持粘贴多个值。" :code="basicCode">
+    <ComponentExample title="筛选值" description="输入后按 Enter、逗号或失焦即可添加；支持粘贴多个值。" :code="basicCode">
       <div class="max-w-xl space-y-3">
         <TagInput v-model="tags" label="筛选标签" placeholder="输入服务、地区或角色..." hint="支持 Enter、逗号与粘贴多个值。" />
         <p class="text-sm text-slate-500 dark:text-slate-400">当前值：{{ tags.join(', ') || '—' }}</p>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="自定义分隔符与数量限制" description="用多个分隔符接收批量角色 ID，并限制最多五项。" :code="advancedCode">
+    <ComponentExample title="自定义分隔符与数量限制" description="用多个分隔符接收批量角色 ID，并限制最多五项。" :code="advancedCode">
       <TagInput
         v-model="roleIds"
         label="Discord Role IDs"
@@ -17,9 +17,9 @@
         :separator="[',', ';', '\n']"
         :max="5"
       />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="tag-input" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/textarea.vue b/apps/playground/pages/components/textarea.vue
index 6a38fc8..2ad8c89 100644
--- a/apps/playground/pages/components/textarea.vue
+++ b/apps/playground/pages/components/textarea.vue
@@ -1,12 +1,12 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Textarea 文本域" description="多行文本输入，与 Input 共享标签与错误态体系。" />
+    <PageHeader title="Textarea 文本域" description="多行文本输入，与 Input 共享标签与错误态体系。" />
 
-    <DocExample title="基础" description="rows 控制初始高度。" :code="rcCode0">
+    <ComponentExample title="基础" description="rows 控制初始高度。" :code="rcCode0">
       <Textarea v-model="val" label="服务注释" placeholder="补充集群用途、负责人与回滚方案…" hint="最多 500 字" :rows="4" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="textarea" />
   </div>
diff --git a/apps/playground/pages/components/theme-toggle.vue b/apps/playground/pages/components/theme-toggle.vue
index ec97af9..6e7d3e5 100644
--- a/apps/playground/pages/components/theme-toggle.vue
+++ b/apps/playground/pages/components/theme-toggle.vue
@@ -1,11 +1,11 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader
+    <PageHeader
       title="ThemeToggle 主题切换开关"
       description="开箱即用的主题明暗切换开关，已封装 Sun / Moon 图标、aria-label 状态播报，支持图标按钮、下拉选择以及系统偏好三态轮换模式，可直接嵌入 Navbar 顶栏。"
     />
 
-    <DocExample
+    <ComponentExample
       title="基础图标切换按钮"
       description="默认非受控模式，自动与全局 useTheme() 同步并持久化，支持深浅模式互切。"
       :code="rcCode0"
@@ -15,9 +15,9 @@
         <ThemeToggle size="md" />
         <ThemeToggle size="lg" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="循环系统偏好 (cycleSystem)"
       description="开启 cycleSystem 后，点击将在「浅色 -> 深色 -> 跟随系统」三态之间循环轮播。"
       :code="rcCode1"
@@ -26,9 +26,9 @@
         <ThemeToggle cycle-system size="md" />
         <span class="text-sm text-slate-500">点击查看 tooltip 或 aria-label 提示的三态轮换</span>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample
+    <ComponentExample
       title="下拉选择变体 (variant=dropdown)"
       description="以规范的下拉菜单形式明确选择浅色、深色或跟随系统。"
       :code="rcCode2"
@@ -37,9 +37,9 @@
         <ThemeToggle variant="dropdown" size="sm" />
         <ThemeToggle variant="dropdown" size="md" />
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="theme-toggle" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/timeline.vue b/apps/playground/pages/components/timeline.vue
index 62a156a..768ed0f 100644
--- a/apps/playground/pages/components/timeline.vue
+++ b/apps/playground/pages/components/timeline.vue
@@ -1,15 +1,15 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Timeline 时间线" description="以清晰的状态脉络呈现部署、审计操作和资源变更历史。" />
-    <DocExample title="部署操作日志" description="内置成功、警告、失败和信息状态；支持操作者、时间、说明及元数据。" :code="rcCode0">
+    <PageHeader title="Timeline 时间线" description="以清晰的状态脉络呈现部署、审计操作和资源变更历史。" />
+    <ComponentExample title="部署操作日志" description="内置成功、警告、失败和信息状态；支持操作者、时间、说明及元数据。" :code="rcCode0">
       <Timeline :items="deploymentEvents" class="max-w-2xl" />
-    </DocExample>
-    <DocExample title="自定义标记" description="通过 marker 插槽将时间线节点替换为版本号、头像或业务图标。" :code="rcCode1">
+    </ComponentExample>
+    <ComponentExample 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" />
+    </ComponentExample>
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="timeline" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/toast.vue b/apps/playground/pages/components/toast.vue
index bc4a019..0df7afa 100644
--- a/apps/playground/pages/components/toast.vue
+++ b/apps/playground/pages/components/toast.vue
@@ -1,17 +1,17 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Toast 吐司提示" description="全局操作反馈队列：四类语义样式、自动堆叠与滑出动画。" />
+    <PageHeader title="Toast 吐司提示" description="全局操作反馈队列：四类语义样式、自动堆叠与滑出动画。" />
 
-    <DocExample title="触发反馈" description="toast(options) 由 useToast 提供，需在应用根部挂载 ToastProvider。" :code="rcCode0">
+    <ComponentExample title="触发反馈" description="toast(options) 由 useToast 提供，需在应用根部挂载 ToastProvider。" :code="rcCode0">
       <div class="demo-grid">
         <Button variant="soft" color="neutral" @click="fire('信息提示', 'info')">Info</Button>
         <Button variant="soft" color="success" @click="fire('操作已成功执行', 'success')">Success</Button>
         <Button variant="soft" color="warning" @click="fire('检测到配置预警', 'warning')">Warning</Button>
         <Button variant="soft" color="error" @click="fire('实例终止失败', 'destructive')">Destructive</Button>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="toast" />
   </div>
diff --git a/apps/playground/pages/components/toc.vue b/apps/playground/pages/components/toc.vue
index 2598e8e..7288bab 100644
--- a/apps/playground/pages/components/toc.vue
+++ b/apps/playground/pages/components/toc.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Toc 页内目录" description="从当前页面或指定容器中收集多级标题并生成导航，支持平滑滚动与滚动监听。" />
+    <PageHeader title="Toc 页内目录" description="从当前页面或指定容器中收集多级标题并生成导航，支持平滑滚动与滚动监听。" />
 
-    <DocExample title="基础目录导航" description="通过数据传入或自动提取页面中的 h2/h3 标题。" :code="codeBasic">
+    <ComponentExample 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>
@@ -24,9 +24,9 @@
           </div>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="toc" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/toggle.vue b/apps/playground/pages/components/toggle.vue
index c2cecef..d249dca 100644
--- a/apps/playground/pages/components/toggle.vue
+++ b/apps/playground/pages/components/toggle.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Toggle / ToggleGroup" description="按压态工具按钮：单个开关与互斥分组两种形态。" />
+    <PageHeader title="Toggle / ToggleGroup" description="按压态工具按钮：单个开关与互斥分组两种形态。" />
 
-    <DocExample title="Toggle 按钮组" description="pressed 状态反色，适合富文本工具栏。" :code="rcCode0">
+    <ComponentExample title="Toggle 按钮组" description="pressed 状态反色，适合富文本工具栏。" :code="rcCode0">
       <div class="flex items-center gap-2">
         <Toggle v-model="left"><AlignLeft class="h-4 w-4" /></Toggle>
         <Toggle v-model="center"><AlignCenter class="h-4 w-4" /></Toggle>
@@ -11,17 +11,17 @@
         <Toggle v-model="bold" size="sm"><Bold class="h-3.5 w-3.5" /></Toggle>
         <Toggle v-model="italic" size="sm"><Italic class="h-3.5 w-3.5" /></Toggle>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocExample title="ToggleGroup 互斥分组" description="单值互斥，选中项浮起白底。" :code="rcCode1">
+    <ComponentExample title="ToggleGroup 互斥分组" description="单值互斥，选中项浮起白底。" :code="rcCode1">
       <ToggleGroup v-model="view" :options="[
         { label: '网格', value: 'grid' },
         { label: '列表', value: 'list' },
         { label: '拓扑', value: 'topo' }
       ]" />
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="toggle" />
   </div>
diff --git a/apps/playground/pages/components/toolbar.vue b/apps/playground/pages/components/toolbar.vue
index a902146..1608d8a 100644
--- a/apps/playground/pages/components/toolbar.vue
+++ b/apps/playground/pages/components/toolbar.vue
@@ -1,8 +1,8 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Toolbar 工具条" description="编辑器式按钮组：role=toolbar、方向键循环焦点与分隔线。" />
+    <PageHeader title="Toolbar 工具条" description="编辑器式按钮组：role=toolbar、方向键循环焦点与分隔线。" />
 
-    <DocExample title="格式工具栏" description="ToolbarButton 包裹原生 button，ToolbarSeparator 自动方向感知。" :code="rcCode0">
+    <ComponentExample title="格式工具栏" description="ToolbarButton 包裹原生 button，ToolbarSeparator 自动方向感知。" :code="rcCode0">
       <div class="flex items-center gap-4">
         <Toolbar>
           <ToolbarButton aria-label="撤销">
@@ -19,9 +19,9 @@
         </Toolbar>
         <VisuallyHidden>仅供屏幕阅读器的工具条说明</VisuallyHidden>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="toolbar" />
   </div>
diff --git a/apps/playground/pages/components/tooltip.vue b/apps/playground/pages/components/tooltip.vue
index 49fccf6..128809b 100644
--- a/apps/playground/pages/components/tooltip.vue
+++ b/apps/playground/pages/components/tooltip.vue
@@ -1,17 +1,17 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="Tooltip 文字提示" description="悬停即时提示，自动避开视口边缘。" />
+    <PageHeader title="Tooltip 文字提示" description="悬停即时提示，自动避开视口边缘。" />
 
-    <DocExample title="四方向" :code="rcCode0">
+    <ComponentExample title="四方向" :code="rcCode0">
       <div class="demo-grid">
         <Tooltip content="上方提示" side="top"><Button variant="outline" color="neutral">Top</Button></Tooltip>
         <Tooltip content="右侧提示" side="right"><Button variant="outline" color="neutral">Right</Button></Tooltip>
         <Tooltip content="下方提示，延迟 400ms 出现" side="bottom" :delay-duration="400"><Button variant="outline" color="neutral">Bottom</Button></Tooltip>
         <Tooltip content="左侧提示" side="left"><Button variant="outline" color="neutral">Left</Button></Tooltip>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="tooltip" />
   </div>
diff --git a/apps/playground/pages/components/tree-view.vue b/apps/playground/pages/components/tree-view.vue
index 0aa9005..4278e31 100644
--- a/apps/playground/pages/components/tree-view.vue
+++ b/apps/playground/pages/components/tree-view.vue
@@ -1,12 +1,12 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader
+    <PageHeader
       title="TreeView 树形视图"
       description="面向云资源拓扑、文件树及细粒度权限的多层级树控件，支持异步懒加载、多选、图标插槽、拖拽重排与清晰的选中高亮提示。"
     />
 
     <!-- Example 1: Async loading + Icon slots + v-model:expanded + Highlighting -->
-    <DocExample
+    <ComponentExample
       title="资源拓扑与选中高亮"
       description="使用 highlight-variant 配置选中的视觉高亮风格（subtle / solid / bar），配合状态徽标提供即时反馈。"
       :code="asyncCode"
@@ -71,10 +71,10 @@
           展开节点：<span class="font-mono text-[var(--foreground)]">{{ expandedResources.join(', ') || '无' }}</span>
         </p>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <!-- Example 2: Multi-select mode -->
-    <DocExample
+    <ComponentExample
       title="多选模式 (Multiple)"
       description="开启 multiple 支持复选节点集合，通过 v-model:selected-ids 受控管理已选节点集合。"
       :code="multiSelectCode"
@@ -94,10 +94,10 @@
           <span class="font-mono">{{ selectedPods.join(', ') || '未选择' }}</span>
         </div>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <!-- Example 3: Drag & Drop ordering -->
-    <DocExample
+    <ComponentExample
       title="拖拽排序与重排 (Draggable)"
       description="开启 draggable 允许在树内移动节点层级或顺序；触发 @drop 事件返回拖拽源、目标与插入位置。"
       :code="dragCode"
@@ -115,10 +115,10 @@
           {{ lastDropInfo }}
         </p>
       </div>
-    </DocExample>
+    </ComponentExample>
 
     <!-- Example 4: Permissions Cascade Checkbox -->
-    <DocExample
+    <ComponentExample
       title="权限级联复选"
       description="checkable 模式适用于细粒度访问策略分配，勾选状态自动向后代节点级联。"
       :code="rcCode1"
@@ -132,9 +132,9 @@
         class="max-w-md"
       />
       <p class="mt-3 text-xs text-[var(--muted-foreground)]">已授权项数量：{{ grants.length }}</p>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
     <DocPageNav name="tree-view" />
   </div>
 </template>
diff --git a/apps/playground/pages/components/visually-hidden.vue b/apps/playground/pages/components/visually-hidden.vue
index b4a97ee..6e69677 100644
--- a/apps/playground/pages/components/visually-hidden.vue
+++ b/apps/playground/pages/components/visually-hidden.vue
@@ -1,16 +1,16 @@
 <template>
   <div class="space-y-10">
-    <DocPageHeader title="VisuallyHidden 隐藏文本" description="视觉隐藏但屏幕阅读器可读的辅助文本。" />
+    <PageHeader title="VisuallyHidden 隐藏文本" description="视觉隐藏但屏幕阅读器可读的辅助文本。" />
 
-    <DocExample title="用法" :code="rcCode0">
+    <ComponentExample title="用法" :code="rcCode0">
       <div class="flex items-center gap-3">
         <Spinner />
         <VisuallyHidden>正在同步集群配置，请勿刷新页面</VisuallyHidden>
         <span class="text-xs text-slate-500 dark:text-slate-400">（上方文本对屏幕阅读器可见，视觉上隐藏）</span>
       </div>
-    </DocExample>
+    </ComponentExample>
 
-    <DocApiTable :rows="apiRows" />
+    <ApiTable :rows="apiRows" />
 
     <DocPageNav name="visually-hidden" />
   </div>
diff --git a/apps/playground/pages/index.vue b/apps/playground/pages/index.vue
index f038431..a182269 100644
--- a/apps/playground/pages/index.vue
+++ b/apps/playground/pages/index.vue
@@ -34,13 +34,13 @@
       </p>
 
       <div class="grid gap-4 md:grid-cols-2">
-        <DocExample title="Nuxt 4 模块" description="自动导入全部组件、useTheme 与 useToast。" :code="installNuxt" expanded />
-        <DocExample title="Vue 3 显式导入" description="配合 Vite 或任意构建工具使用。" :code="installVue" expanded />
+        <ComponentExample title="Nuxt 4 模块" description="自动导入全部组件、useTheme 与 useToast。" :code="installNuxt" expanded />
+        <ComponentExample title="Vue 3 显式导入" description="配合 Vite 或任意构建工具使用。" :code="installVue" expanded />
       </div>
     </section>
 
     <!-- 组件总览 -->
-    <section class="space-y-6">
+    <section id="components" class="scroll-mt-24 space-y-6">
       <div>
         <h2 class="text-2xl font-bold tracking-tight text-slate-950 dark:text-white">组件总览</h2>
         <p class="text-sm text-slate-600 dark:text-slate-400 mt-1.5">按使用场景分组，点击进入每个组件的文档与交互示例。</p>
diff --git a/apps/playground/src/style.css b/apps/playground/src/style.css
index 8ba3cca..592b04d 100644
--- a/apps/playground/src/style.css
+++ b/apps/playground/src/style.css
@@ -5,8 +5,12 @@
 
 /* 字体：全站统一使用 Maple Mono NF CN，由 nuxt.config.ts 中的 CDN 样式表加载；其余为加载失败时的回退 */
 @theme {
-  --font-sans: 'Maple Mono NF CN', 'Maple Mono CN', 'Noto Sans Mono CJK SC', ui-monospace, 'PingFang SC', 'Microsoft YaHei', monospace;
-  --font-mono: 'Maple Mono NF CN', 'Maple Mono CN', 'Noto Sans Mono CJK SC', ui-monospace, 'DejaVu Sans Mono', monospace;
+  --font-sans:
+    "Maple Mono NF CN", "Maple Mono CN", "Noto Sans Mono CJK SC", ui-monospace, "PingFang SC",
+    "Microsoft YaHei", monospace;
+  --font-mono:
+    "Maple Mono NF CN", "Maple Mono CN", "Noto Sans Mono CJK SC", ui-monospace, "DejaVu Sans Mono",
+    monospace;
 }
 
 html {
@@ -28,7 +32,10 @@ body {
   text-rendering: optimizeLegibility;
 }
 
-h1, h2, h3, h4 {
+h1,
+h2,
+h3,
+h4 {
   text-wrap: balance;
   letter-spacing: normal;
 }
@@ -37,7 +44,10 @@ p {
   text-wrap: pretty;
 }
 
-code, pre, kbd, samp {
+code,
+pre,
+kbd,
+samp {
   font-family: var(--font-mono);
   font-variant-ligatures: none;
   letter-spacing: 0;
@@ -69,4 +79,3 @@ code, pre, kbd, samp {
 .no-scrollbar {
   scrollbar-width: none;
 }
-
diff --git a/bun.lock b/bun.lock
index 0b74a14..342e247 100644
--- a/bun.lock
+++ b/bun.lock
@@ -17,13 +17,14 @@
       "dependencies": {
         "@recloudstudio/ui": "workspace:*",
         "nuxt": "^4.0.0",
+        "vue-router": "^5.3.1",
       },
       "devDependencies": {
         "@tailwindcss/vite": "^4.0.0",
         "shiki": "^4.5.0",
         "tailwindcss": "^4.0.0",
         "typescript": "^5.7.2",
-        "vue-tsc": "^2.2.8",
+        "vue-tsc": "^3.3.12",
       },
     },
     "packages/ui": {
@@ -1811,6 +1812,8 @@
 
     "pkg-types/confbox": ["confbox@0.3.1", "", {}, "sha512-cKUSoKa8YxFZZSmraVi7onONx3amu77ngK3kGpsYHDH7drPwCRkQE1RYMPlLRrMtnciRj274XNRxcHxnKmDSnA=="],
 
+    "playground/vue-tsc": ["vue-tsc@3.3.12", "", { "dependencies": { "@volar/typescript": "2.4.28", "@vue/language-core": "3.3.12" }, "peerDependencies": { "typescript": ">=5.0.0" }, "bin": { "vue-tsc": "bin/vue-tsc.js" } }, "sha512-kbpaz18O9jPVkXVHD1BEjpUXM6WhXSu+62L1sGGr6Wbzd8GbvkBQWjoj3KZ/C0aq2MZllce7UdtWzwCIYsBMGA=="],
+
     "proper-lockfile/signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
 
     "readdir-glob/minimatch": ["minimatch@5.1.9", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw=="],
@@ -1893,6 +1896,10 @@
 
     "nitropack/unctx/unplugin": ["unplugin@2.3.11", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "acorn": "^8.15.0", "picomatch": "^4.0.3", "webpack-virtual-modules": "^0.6.2" } }, "sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww=="],
 
+    "playground/vue-tsc/@volar/typescript": ["@volar/typescript@2.4.28", "", { "dependencies": { "@volar/language-core": "2.4.28", "path-browserify": "^1.0.1", "vscode-uri": "^3.0.8" } }, "sha512-Ja6yvWrbis2QtN4ClAKreeUZPVYMARDYZl9LMEv1iQ1QdepB6wn0jTRxA9MftYmYa4DQ4k/DaSZpFPUfxl8giw=="],
+
+    "playground/vue-tsc/@vue/language-core": ["@vue/language-core@3.3.12", "", { "dependencies": { "@volar/language-core": "2.4.28", "@vue/compiler-dom": "^3.5.0", "@vue/shared": "^3.5.0", "alien-signals": "^3.2.1", "muggle-string": "^0.4.1", "path-browserify": "^1.0.1", "picomatch": "^4.0.4" } }, "sha512-k7uIKR0n4CBidk233y7cac9osnDQ5WRidTl6nsrNvpZ3nf8cx9iJxRVsRzVsoPRHbowT/iKgGMTS9RGov3jeIA=="],
+
     "string-width-cjs/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
     "unplugin-dts/@volar/typescript/@volar/language-core": ["@volar/language-core@2.4.28", "", { "dependencies": { "@volar/source-map": "2.4.28" } }, "sha512-w4qhIJ8ZSitgLAkVay6AbcnC7gP3glYM3fYwKV3srj8m494E3xtrCv6E+bWviiK/8hs6e6t1ij1s2Endql7vzQ=="],
@@ -1909,6 +1916,16 @@
 
     "glob/minimatch/brace-expansion/balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
+    "playground/vue-tsc/@volar/typescript/@volar/language-core": ["@volar/language-core@2.4.28", "", { "dependencies": { "@volar/source-map": "2.4.28" } }, "sha512-w4qhIJ8ZSitgLAkVay6AbcnC7gP3glYM3fYwKV3srj8m494E3xtrCv6E+bWviiK/8hs6e6t1ij1s2Endql7vzQ=="],
+
+    "playground/vue-tsc/@vue/language-core/@volar/language-core": ["@volar/language-core@2.4.28", "", { "dependencies": { "@volar/source-map": "2.4.28" } }, "sha512-w4qhIJ8ZSitgLAkVay6AbcnC7gP3glYM3fYwKV3srj8m494E3xtrCv6E+bWviiK/8hs6e6t1ij1s2Endql7vzQ=="],
+
+    "playground/vue-tsc/@vue/language-core/alien-signals": ["alien-signals@3.2.1", "", {}, "sha512-I8FjmltrfnDFoZedi5CG8DghVYNhzb/Ijluz7tCSJH0xpd0484Kowhbb1XDYOxfJpU1p5wnM2X54dA+IfGyD1g=="],
+
     "unplugin-dts/@volar/typescript/@volar/language-core/@volar/source-map": ["@volar/source-map@2.4.28", "", {}, "sha512-yX2BDBqJkRXfKw8my8VarTyjv48QwxdJtvRgUpNE5erCsgEUdI2DsLbpa+rOQVAJYshY99szEcRDmyHbF10ggQ=="],
+
+    "playground/vue-tsc/@volar/typescript/@volar/language-core/@volar/source-map": ["@volar/source-map@2.4.28", "", {}, "sha512-yX2BDBqJkRXfKw8my8VarTyjv48QwxdJtvRgUpNE5erCsgEUdI2DsLbpa+rOQVAJYshY99szEcRDmyHbF10ggQ=="],
+
+    "playground/vue-tsc/@vue/language-core/@volar/language-core/@volar/source-map": ["@volar/source-map@2.4.28", "", {}, "sha512-yX2BDBqJkRXfKw8my8VarTyjv48QwxdJtvRgUpNE5erCsgEUdI2DsLbpa+rOQVAJYshY99szEcRDmyHbF10ggQ=="],
   }
 }
diff --git a/packages/ui/src/components/accordion/index.ts b/packages/ui/src/components/accordion/index.ts
index 8bbc95b..e2b7797 100644
--- a/packages/ui/src/components/accordion/index.ts
+++ b/packages/ui/src/components/accordion/index.ts
@@ -1,2 +1,2 @@
-export { default as Accordion } from './Accordion.vue'
-export type { AccordionProps, AccordionItemData } from './Accordion.vue'
+export { default as Accordion } from "./Accordion.vue";
+export type { AccordionProps, AccordionItemData } from "./Accordion.vue";
diff --git a/packages/ui/src/components/alert-dialog/index.ts b/packages/ui/src/components/alert-dialog/index.ts
index 8a55d2c..eba5cd6 100644
--- a/packages/ui/src/components/alert-dialog/index.ts
+++ b/packages/ui/src/components/alert-dialog/index.ts
@@ -1,2 +1,2 @@
-export { default as AlertDialog } from './AlertDialog.vue'
-export type { AlertDialogProps } from './AlertDialog.vue'
+export { default as AlertDialog } from "./AlertDialog.vue";
+export type { AlertDialogProps } from "./AlertDialog.vue";
diff --git a/packages/ui/src/components/anchor-heading/index.ts b/packages/ui/src/components/anchor-heading/index.ts
index 628a9f9..f72032b 100644
--- a/packages/ui/src/components/anchor-heading/index.ts
+++ b/packages/ui/src/components/anchor-heading/index.ts
@@ -1,2 +1,2 @@
-export { default as AnchorHeading } from './AnchorHeading.vue'
-export type { AnchorHeadingProps, HeadingLevel } from './types'
+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
index 34d6a56..dc333df 100644
--- a/packages/ui/src/components/anchor-heading/types.ts
+++ b/packages/ui/src/components/anchor-heading/types.ts
@@ -1,8 +1,8 @@
-export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+export type HeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 
 export interface AnchorHeadingProps {
-  as?: HeadingLevel
-  id?: string
-  copyable?: boolean
-  class?: string
+  as?: HeadingLevel;
+  id?: string;
+  copyable?: boolean;
+  class?: string;
 }
diff --git a/packages/ui/src/components/api-table/ApiTable.vue b/packages/ui/src/components/api-table/ApiTable.vue
new file mode 100644
index 0000000..65e09da
--- /dev/null
+++ b/packages/ui/src/components/api-table/ApiTable.vue
@@ -0,0 +1,41 @@
+<template>
+  <section :class="cn('space-y-3', props.class)">
+    <h3 v-if="props.title || $slots.title" class="text-base font-semibold tracking-tight text-[color:var(--foreground)]">
+      <slot name="title">{{ props.title }}</slot>
+    </h3>
+    <DataTable :columns="columns" :rows="props.rows" :hoverable="false" :divide="true">
+      <template #cell-name="{ value }">
+        <code class="whitespace-nowrap font-mono text-[13px] font-medium text-[color:var(--primary)]">{{ value }}</code>
+      </template>
+      <template #cell-type="{ value }">
+        <code class="font-mono text-[12px] text-[color:var(--foreground)]">{{ value }}</code>
+      </template>
+      <template #cell-default="{ value }">
+        <code class="whitespace-nowrap font-mono text-[12px] text-[color:var(--muted-foreground)]">{{ value || '—' }}</code>
+      </template>
+      <template #cell-description="{ value }">
+        <span class="text-[13px] leading-6 text-[color:var(--muted-foreground)]">{{ value }}</span>
+      </template>
+    </DataTable>
+  </section>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { cn } from '../../utils/cn'
+import DataTable from '../table/DataTable.vue'
+import type { DataTableColumn } from '../table/types'
+import type { ApiTableProps } from './types'
+
+const props = withDefaults(defineProps<ApiTableProps>(), {
+  title: 'API 参考',
+  class: ''
+})
+
+const columns = computed<DataTableColumn[]>(() => [
+  { key: 'name', label: '属性', slot: true },
+  { key: 'type', label: '类型', slot: true },
+  { key: 'default', label: '默认值', slot: true },
+  { key: 'description', label: '说明', slot: true }
+])
+</script>
diff --git a/packages/ui/src/components/api-table/apiTable.test.ts b/packages/ui/src/components/api-table/apiTable.test.ts
new file mode 100644
index 0000000..c46d4f7
--- /dev/null
+++ b/packages/ui/src/components/api-table/apiTable.test.ts
@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = readFileSync(fileURLToPath(new URL("./ApiTable.vue", import.meta.url)), "utf8");
+
+describe("ApiTable component contract", () => {
+  it("renders API metadata through DataTable", () => {
+    expect(source).toContain('<DataTable :columns="columns" :rows="props.rows"');
+    expect(source).toContain("{ key: 'name', label: '属性', slot: true }");
+    expect(source).toContain("{ key: 'description', label: '说明', slot: true }");
+  });
+
+  it("formats names, types, defaults, and descriptions semantically", () => {
+    expect(source).toContain("template #cell-name");
+    expect(source).toContain("template #cell-type");
+    expect(source).toContain("value || '—'");
+  });
+});
diff --git a/packages/ui/src/components/api-table/index.ts b/packages/ui/src/components/api-table/index.ts
new file mode 100644
index 0000000..d3d5080
--- /dev/null
+++ b/packages/ui/src/components/api-table/index.ts
@@ -0,0 +1,2 @@
+export { default as ApiTable } from "./ApiTable.vue";
+export type { ApiTableProps, ApiTableRow } from "./types";
diff --git a/packages/ui/src/components/api-table/types.ts b/packages/ui/src/components/api-table/types.ts
new file mode 100644
index 0000000..eefa722
--- /dev/null
+++ b/packages/ui/src/components/api-table/types.ts
@@ -0,0 +1,12 @@
+export type ApiTableRow = Record<string, unknown> & {
+  name: string;
+  type: string;
+  default?: string;
+  description: string;
+};
+
+export interface ApiTableProps {
+  title?: string;
+  rows: ApiTableRow[];
+  class?: string;
+}
diff --git a/packages/ui/src/components/app-shell/index.ts b/packages/ui/src/components/app-shell/index.ts
index d9692fc..92b4511 100644
--- a/packages/ui/src/components/app-shell/index.ts
+++ b/packages/ui/src/components/app-shell/index.ts
@@ -1,2 +1,2 @@
-export { default as AppShell } from './AppShell.vue'
-export { default as Sidebar } from './Sidebar.vue'
+export { default as AppShell } from "./AppShell.vue";
+export { default as Sidebar } from "./Sidebar.vue";
diff --git a/packages/ui/src/components/aspect-ratio/index.ts b/packages/ui/src/components/aspect-ratio/index.ts
index 8b86aab..fe276eb 100644
--- a/packages/ui/src/components/aspect-ratio/index.ts
+++ b/packages/ui/src/components/aspect-ratio/index.ts
@@ -1,2 +1,2 @@
-export { default as AspectRatio } from './AspectRatio.vue'
-export type { AspectRatioProps } from './AspectRatio.vue'
+export { default as AspectRatio } from "./AspectRatio.vue";
+export type { AspectRatioProps } from "./AspectRatio.vue";
diff --git a/packages/ui/src/components/avatar/index.ts b/packages/ui/src/components/avatar/index.ts
index f407e96..98b9820 100644
--- a/packages/ui/src/components/avatar/index.ts
+++ b/packages/ui/src/components/avatar/index.ts
@@ -1,2 +1,2 @@
-export { default as Avatar } from './Avatar.vue'
-export type { AvatarProps } from './Avatar.vue'
+export { default as Avatar } from "./Avatar.vue";
+export type { AvatarProps } from "./Avatar.vue";
diff --git a/packages/ui/src/components/badge/index.ts b/packages/ui/src/components/badge/index.ts
index 3bf7fa5..0b716b8 100644
--- a/packages/ui/src/components/badge/index.ts
+++ b/packages/ui/src/components/badge/index.ts
@@ -1,2 +1,2 @@
-export { default as Badge } from './Badge.vue'
-export type { BadgeProps } from './Badge.vue'
+export { default as Badge } from "./Badge.vue";
+export type { BadgeProps } from "./Badge.vue";
diff --git a/packages/ui/src/components/banner/index.ts b/packages/ui/src/components/banner/index.ts
index 95e4f25..40929de 100644
--- a/packages/ui/src/components/banner/index.ts
+++ b/packages/ui/src/components/banner/index.ts
@@ -1,2 +1,2 @@
-export { default as Banner } from './Banner.vue'
-export type { BannerProps } from './Banner.vue'
+export { default as Banner } from "./Banner.vue";
+export type { BannerProps } from "./Banner.vue";
diff --git a/packages/ui/src/components/breadcrumb/index.ts b/packages/ui/src/components/breadcrumb/index.ts
index 0b7bb6a..4902add 100644
--- a/packages/ui/src/components/breadcrumb/index.ts
+++ b/packages/ui/src/components/breadcrumb/index.ts
@@ -1,2 +1,2 @@
-export { default as BreadcrumbNav } from './BreadcrumbNav.vue'
-export type { BreadcrumbNavProps, Crumb } from './BreadcrumbNav.vue'
+export { default as BreadcrumbNav } from "./BreadcrumbNav.vue";
+export type { BreadcrumbNavProps, Crumb } from "./BreadcrumbNav.vue";
diff --git a/packages/ui/src/components/button/index.ts b/packages/ui/src/components/button/index.ts
index 1e672d4..1dfcbf6 100644
--- a/packages/ui/src/components/button/index.ts
+++ b/packages/ui/src/components/button/index.ts
@@ -1,2 +1,2 @@
-export { default as Button } from './Button.vue'
-export type { ButtonProps } from './Button.vue'
+export { default as Button } from "./Button.vue";
+export type { ButtonProps } from "./Button.vue";
diff --git a/packages/ui/src/components/callout/callout.test.ts b/packages/ui/src/components/callout/callout.test.ts
index 29e3ce0..26885dd 100644
--- a/packages/ui/src/components/callout/callout.test.ts
+++ b/packages/ui/src/components/callout/callout.test.ts
@@ -1,9 +1,9 @@
-import { describe, expect, it } from 'vitest'
-import { Callout } from './index'
+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()
-  })
-})
+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
index 85fdc54..104a9bb 100644
--- a/packages/ui/src/components/callout/index.ts
+++ b/packages/ui/src/components/callout/index.ts
@@ -1,2 +1,2 @@
-export { default as Callout } from './Callout.vue'
-export type { CalloutProps, CalloutType } from './types'
+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
index d9cd3b7..8043dab 100644
--- a/packages/ui/src/components/callout/types.ts
+++ b/packages/ui/src/components/callout/types.ts
@@ -1,9 +1,9 @@
-export type CalloutType = 'note' | 'tip' | 'info' | 'warning' | 'danger'
+export type CalloutType = "note" | "tip" | "info" | "warning" | "danger";
 
 export interface CalloutProps {
-  type?: CalloutType
-  title?: string
-  collapsible?: boolean
-  defaultOpen?: boolean
-  class?: string
+  type?: CalloutType;
+  title?: string;
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+  class?: string;
 }
diff --git a/packages/ui/src/components/card/index.ts b/packages/ui/src/components/card/index.ts
index de88791..74bafb1 100644
--- a/packages/ui/src/components/card/index.ts
+++ b/packages/ui/src/components/card/index.ts
@@ -1,2 +1,2 @@
-export { default as Card } from './Card.vue'
-export type { CardProps } from './Card.vue'
+export { default as Card } from "./Card.vue";
+export type { CardProps } from "./Card.vue";
diff --git a/packages/ui/src/components/checkbox/index.ts b/packages/ui/src/components/checkbox/index.ts
index 3b70ac8..32e9380 100644
--- a/packages/ui/src/components/checkbox/index.ts
+++ b/packages/ui/src/components/checkbox/index.ts
@@ -1,2 +1,2 @@
-export { default as Checkbox } from './Checkbox.vue'
-export type { CheckboxProps } from './Checkbox.vue'
+export { default as Checkbox } from "./Checkbox.vue";
+export type { CheckboxProps } from "./Checkbox.vue";
diff --git a/packages/ui/src/components/code-block/codeBlock.test.ts b/packages/ui/src/components/code-block/codeBlock.test.ts
index 387a73f..0051e5e 100644
--- a/packages/ui/src/components/code-block/codeBlock.test.ts
+++ b/packages/ui/src/components/code-block/codeBlock.test.ts
@@ -1,52 +1,52 @@
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'vitest'
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
 
-const source = readFileSync(fileURLToPath(new URL('./CodeBlock.vue', import.meta.url)), 'utf8')
+const source = readFileSync(fileURLToPath(new URL("./CodeBlock.vue", import.meta.url)), "utf8");
 const highlighter = readFileSync(
-  fileURLToPath(new URL('./highlighter.ts', import.meta.url)),
-  'utf8'
-)
+  fileURLToPath(new URL("./highlighter.ts", import.meta.url)),
+  "utf8",
+);
 
-describe('CodeBlock component contract', () => {
-  it('keeps the actual scrolling region keyboard and screen-reader accessible', () => {
-    expect(source).toContain(':tabindex="isCollapsed ? -1 : 0"')
-    expect(source).toContain('role="region"')
-    expect(source).toContain(':aria-label="regionLabel"')
-    expect(source).toContain(':aria-hidden="isCollapsed || undefined"')
-    expect(source).toContain('role="status" aria-live="polite"')
-    expect(source).toContain('delete node.properties.tabindex')
-  })
+describe("CodeBlock component contract", () => {
+  it("keeps the actual scrolling region keyboard and screen-reader accessible", () => {
+    expect(source).toContain(':tabindex="isCollapsed ? -1 : 0"');
+    expect(source).toContain('role="region"');
+    expect(source).toContain(':aria-label="regionLabel"');
+    expect(source).toContain(':aria-hidden="isCollapsed || undefined"');
+    expect(source).toContain('role="status" aria-live="polite"');
+    expect(source).toContain("delete node.properties.tabindex");
+  });
 
-  it('uses adaptive line-number gutters that keep wrapped continuations out of the gutter', () => {
-    expect(source).toContain('[padding-left:calc(2rem+var(--rc-ln-w))]')
-    expect(source).toContain('[&_.line]:relative')
-    expect(source).toContain('before:left-[calc(-1*(var(--rc-ln-w)+1rem))]')
-    expect(source).toContain("style['--rc-ln-w']")
-    expect(source).toContain('max(1.5rem, ')
-  })
+  it("uses adaptive line-number gutters that keep wrapped continuations out of the gutter", () => {
+    expect(source).toContain("[padding-left:calc(2rem+var(--rc-ln-w))]");
+    expect(source).toContain("[&_.line]:relative");
+    expect(source).toContain("before:left-[calc(-1*(var(--rc-ln-w)+1rem))]");
+    expect(source).toContain("style['--rc-ln-w']");
+    expect(source).toContain("max(1.5rem, ");
+  });
 
-  it('animates collapsible content without moving the header border', () => {
-    expect(source).toContain('border-b px-3.5')
-    expect(source).toContain("isCollapsed.value ? 'border-transparent'")
-    expect(source).toContain("isCollapsed.value ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]'")
-    expect(source).toContain('transition-[grid-template-rows]')
-    expect(source).not.toContain('v-show="!isCollapsed"')
-  })
+  it("animates collapsible content without moving the header border", () => {
+    expect(source).toContain("border-b px-3.5");
+    expect(source).toContain("isCollapsed.value ? 'border-transparent'");
+    expect(source).toContain("isCollapsed.value ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]'");
+    expect(source).toContain("transition-[grid-template-rows]");
+    expect(source).not.toContain('v-show="!isCollapsed"');
+  });
 
-  it('shows a scroll-aware fade only while max-height content remains below', () => {
-    expect(source).toContain('@scroll.passive="syncBottomFade"')
-    expect(source).toContain('element.scrollHeight - element.scrollTop - element.clientHeight > 4')
+  it("shows a scroll-aware fade only while max-height content remains below", () => {
+    expect(source).toContain('@scroll.passive="syncBottomFade"');
+    expect(source).toContain("element.scrollHeight - element.scrollTop - element.clientHeight > 4");
     expect(source).toContain(
-      '[mask-image:linear-gradient(to_bottom,#000_calc(100%_-_2.5rem),transparent)]'
-    )
-  })
+      "[mask-image:linear-gradient(to_bottom,#000_calc(100%_-_2.5rem),transparent)]",
+    );
+  });
 
-  it('loads the core and individual grammars lazily with retryable caches', () => {
-    expect(highlighter).toContain('langs: []')
-    expect(highlighter).toContain('loadCodeBlockGrammar(grammar)')
-    expect(highlighter).toContain('highlighter.loadLanguage(language)')
-    expect(highlighter).toContain('highlighterPromise = undefined')
-    expect(highlighter).toContain('grammarPromises.delete(grammar)')
-  })
-})
+  it("loads the core and individual grammars lazily with retryable caches", () => {
+    expect(highlighter).toContain("langs: []");
+    expect(highlighter).toContain("loadCodeBlockGrammar(grammar)");
+    expect(highlighter).toContain("highlighter.loadLanguage(language)");
+    expect(highlighter).toContain("highlighterPromise = undefined");
+    expect(highlighter).toContain("grammarPromises.delete(grammar)");
+  });
+});
diff --git a/packages/ui/src/components/code-block/index.ts b/packages/ui/src/components/code-block/index.ts
index 45a7aa2..8c13198 100644
--- a/packages/ui/src/components/code-block/index.ts
+++ b/packages/ui/src/components/code-block/index.ts
@@ -1,8 +1,8 @@
-export { default as CodeBlock } from './CodeBlock.vue'
-export type { CodeBlockProps } from './types'
+export { default as CodeBlock } from "./CodeBlock.vue";
+export type { CodeBlockProps } from "./types";
 export {
   DEFAULT_CODE_ICON,
   LANGUAGE_ICONS,
   extractExtension,
-  resolveCodeBlockIcon
-} from './languages'
+  resolveCodeBlockIcon,
+} from "./languages";
diff --git a/packages/ui/src/components/code-block/languages.test.ts b/packages/ui/src/components/code-block/languages.test.ts
index 26c9126..c00a496 100644
--- a/packages/ui/src/components/code-block/languages.test.ts
+++ b/packages/ui/src/components/code-block/languages.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it } from "vitest";
 import {
   CODE_BLOCK_GRAMMARS,
   CODE_BLOCK_GRAMMAR_IDS,
@@ -7,124 +7,120 @@ import {
   LANGUAGE_ICONS,
   extractExtension,
   resolveCodeBlockGrammar,
-  resolveCodeBlockIcon
-} from './languages'
+  resolveCodeBlockIcon,
+} from "./languages";
 
 const LEGACY_LANGUAGE_KEYS = [
-  'bash',
-  'css',
-  'docker',
-  'dockerfile',
-  'go',
-  'golang',
-  'html',
-  'javascript',
-  'js',
-  'json',
-  'jsx',
-  'log',
-  'markdown',
-  'md',
-  'py',
-  'python',
-  'rs',
-  'rust',
-  'sh',
-  'shell',
-  'shellscript',
-  'sql',
-  'toml',
-  'ts',
-  'tsx',
-  'typescript',
-  'vue',
-  'vue-html',
-  'yaml',
-  'yml',
-  'zsh'
-]
+  "bash",
+  "css",
+  "docker",
+  "dockerfile",
+  "go",
+  "golang",
+  "html",
+  "javascript",
+  "js",
+  "json",
+  "jsx",
+  "log",
+  "markdown",
+  "md",
+  "py",
+  "python",
+  "rs",
+  "rust",
+  "sh",
+  "shell",
+  "shellscript",
+  "sql",
+  "toml",
+  "ts",
+  "tsx",
+  "typescript",
+  "vue",
+  "vue-html",
+  "yaml",
+  "yml",
+  "zsh",
+];
 
-describe('CodeBlock languages', () => {
-  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('')
-  })
+describe("CodeBlock languages", () => {
+  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 from canonical ids and aliases', () => {
-    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 from canonical ids and aliases", () => {
+    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 from filename extensions when language is absent', () => {
-    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("resolves icons from filename extensions when language is absent", () => {
+    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', () => {
-    expect(resolveCodeBlockIcon(false, 'ts', 'main.ts')).toBeNull()
+  it("respects explicit icon overrides", () => {
+    expect(resolveCodeBlockIcon(false, "ts", "main.ts")).toBeNull();
 
-    const customIcon = 'lucide:file-code'
-    expect(resolveCodeBlockIcon(customIcon, 'ts', 'main.ts')).toBe(customIcon)
+    const customIcon = "lucide:file-code";
+    expect(resolveCodeBlockIcon(customIcon, "ts", "main.ts")).toBe(customIcon);
 
-    expect(resolveCodeBlockIcon(true, 'unknown-lang-xyz', 'data.unknown')).toBe(
-      DEFAULT_CODE_ICON
-    )
-    expect(resolveCodeBlockIcon(undefined, 'unknown-lang-xyz', 'data.unknown')).toBeNull()
-  })
+    expect(resolveCodeBlockIcon(true, "unknown-lang-xyz", "data.unknown")).toBe(DEFAULT_CODE_ICON);
+    expect(resolveCodeBlockIcon(undefined, "unknown-lang-xyz", "data.unknown")).toBeNull();
+  });
 
-  it('resolves aliases, Vue snippets and unknown languages to loadable grammars', () => {
-    expect(resolveCodeBlockGrammar('ts', 'const value = 1')).toBe('typescript')
-    expect(resolveCodeBlockGrammar('bash', 'echo hello')).toBe('shellscript')
-    expect(resolveCodeBlockGrammar('dockerfile', 'FROM oven/bun')).toBe('docker')
-    expect(resolveCodeBlockGrammar('vue', '<template><div /></template>')).toBe('vue')
-    expect(resolveCodeBlockGrammar('vue', '<div><Button /></div>')).toBe('vue-html')
-    expect(resolveCodeBlockGrammar('unknown', 'plain text')).toBe('log')
-    expect(resolveCodeBlockGrammar('', 'plain text')).toBe('log')
-  })
+  it("resolves aliases, Vue snippets and unknown languages to loadable grammars", () => {
+    expect(resolveCodeBlockGrammar("ts", "const value = 1")).toBe("typescript");
+    expect(resolveCodeBlockGrammar("bash", "echo hello")).toBe("shellscript");
+    expect(resolveCodeBlockGrammar("dockerfile", "FROM oven/bun")).toBe("docker");
+    expect(resolveCodeBlockGrammar("vue", "<template><div /></template>")).toBe("vue");
+    expect(resolveCodeBlockGrammar("vue", "<div><Button /></div>")).toBe("vue-html");
+    expect(resolveCodeBlockGrammar("unknown", "plain text")).toBe("log");
+    expect(resolveCodeBlockGrammar("", "plain text")).toBe("log");
+  });
 
-  it('keeps every registered grammar paired with exactly one lazy loader', () => {
-    expect([...CODE_BLOCK_GRAMMARS].sort()).toEqual([...CODE_BLOCK_GRAMMAR_IDS].sort())
-  })
+  it("keeps every registered grammar paired with exactly one lazy loader", () => {
+    expect([...CODE_BLOCK_GRAMMARS].sort()).toEqual([...CODE_BLOCK_GRAMMAR_IDS].sort());
+  });
 
-  it('loads a registered grammar in the format accepted by shiki', async () => {
-    const language = loadCodeBlockGrammar('python')
-    expect(language).not.toBeNull()
-    if (!language) throw new Error('Python grammar loader is missing')
+  it("loads a registered grammar in the format accepted by shiki", async () => {
+    const language = loadCodeBlockGrammar("python");
+    expect(language).not.toBeNull();
+    if (!language) throw new Error("Python grammar loader is missing");
 
-    const { createHighlighterCore } = await import('shiki/core')
-    const { createJavaScriptRegexEngine } = await import('shiki/engine/javascript')
+    const { createHighlighterCore } = await import("shiki/core");
+    const { createJavaScriptRegexEngine } = await import("shiki/engine/javascript");
     const highlighter = await createHighlighterCore({
       themes: [],
       langs: [],
-      engine: createJavaScriptRegexEngine()
-    })
-    await highlighter.loadLanguage(language)
+      engine: createJavaScriptRegexEngine(),
+    });
+    await highlighter.loadLanguage(language);
 
-    expect(highlighter.getLoadedLanguages()).toEqual(expect.arrayContaining(['python', 'py']))
-  })
+    expect(highlighter.getLoadedLanguages()).toEqual(expect.arrayContaining(["python", "py"]));
+  });
 
-  it('preserves every previously published language icon key', () => {
-    expect(Object.keys(LANGUAGE_ICONS)).toEqual(expect.arrayContaining(LEGACY_LANGUAGE_KEYS))
-  })
-})
+  it("preserves every previously published language icon key", () => {
+    expect(Object.keys(LANGUAGE_ICONS)).toEqual(expect.arrayContaining(LEGACY_LANGUAGE_KEYS));
+  });
+});
diff --git a/packages/ui/src/components/code-block/languages.ts b/packages/ui/src/components/code-block/languages.ts
index 4c4ebba..567ef9d 100644
--- a/packages/ui/src/components/code-block/languages.ts
+++ b/packages/ui/src/components/code-block/languages.ts
@@ -1,45 +1,45 @@
-import type { LanguageInput } from 'shiki/core'
+import type { LanguageInput } from "shiki/core";
 
-import type { IconSource } from '../icon'
+import type { IconSource } from "../icon";
 
 /* -------------------------------------------------------------------------- */
 /* Inline SVG icons                                                            */
 /* -------------------------------------------------------------------------- */
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
-const ICON_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>`
+const ICON_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>`;
 
 /** Generic fallback shown when `icon` is `true` but no language can be matched. */
-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>`
+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>`;
 
 /* -------------------------------------------------------------------------- */
 /* Single language registry                                                    */
@@ -47,11 +47,11 @@ export const DEFAULT_CODE_ICON = `<svg viewBox="0 0 24 24" fill="none"><rect wid
 
 interface CodeBlockLanguage {
   /** shiki grammar id; this is the grammar actually loaded for the language. */
-  grammar: string
+  grammar: string;
   /** Inline SVG markup rendered in the header. */
-  icon: string
+  icon: string;
   /** Additional spellings accepted by the `language` prop and by file extensions. */
-  aliases?: readonly string[]
+  aliases?: readonly string[];
 }
 
 /**
@@ -60,95 +60,95 @@ interface CodeBlockLanguage {
  * with an icon that the highlighter cannot back up.
  */
 const LANGUAGES: Record<string, CodeBlockLanguage> = {
-  css: { grammar: 'css', icon: ICON_CSS },
-  docker: { grammar: 'docker', icon: ICON_DOCKER, aliases: ['dockerfile'] },
-  go: { grammar: 'go', icon: ICON_GO, aliases: ['golang'] },
-  html: { grammar: 'html', icon: ICON_HTML },
-  javascript: { grammar: 'javascript', icon: ICON_JAVASCRIPT, aliases: ['cjs', 'js', 'mjs'] },
-  json: { grammar: 'json', icon: ICON_JSON },
-  jsx: { grammar: 'jsx', icon: ICON_JAVASCRIPT },
-  log: { grammar: 'log', icon: ICON_LOG },
-  markdown: { grammar: 'markdown', icon: ICON_MARKDOWN, aliases: ['md'] },
-  python: { grammar: 'python', icon: ICON_PYTHON, aliases: ['py'] },
-  rust: { grammar: 'rust', icon: ICON_RUST, aliases: ['rs'] },
+  css: { grammar: "css", icon: ICON_CSS },
+  docker: { grammar: "docker", icon: ICON_DOCKER, aliases: ["dockerfile"] },
+  go: { grammar: "go", icon: ICON_GO, aliases: ["golang"] },
+  html: { grammar: "html", icon: ICON_HTML },
+  javascript: { grammar: "javascript", icon: ICON_JAVASCRIPT, aliases: ["cjs", "js", "mjs"] },
+  json: { grammar: "json", icon: ICON_JSON },
+  jsx: { grammar: "jsx", icon: ICON_JAVASCRIPT },
+  log: { grammar: "log", icon: ICON_LOG },
+  markdown: { grammar: "markdown", icon: ICON_MARKDOWN, aliases: ["md"] },
+  python: { grammar: "python", icon: ICON_PYTHON, aliases: ["py"] },
+  rust: { grammar: "rust", icon: ICON_RUST, aliases: ["rs"] },
   shellscript: {
-    grammar: 'shellscript',
+    grammar: "shellscript",
     icon: ICON_SHELL,
-    aliases: ['bash', 'sh', 'shell', 'zsh']
+    aliases: ["bash", "sh", "shell", "zsh"],
   },
-  sql: { grammar: 'sql', icon: ICON_SQL },
-  toml: { grammar: 'toml', icon: ICON_TOML },
-  tsx: { grammar: 'tsx', icon: ICON_TYPESCRIPT },
+  sql: { grammar: "sql", icon: ICON_SQL },
+  toml: { grammar: "toml", icon: ICON_TOML },
+  tsx: { grammar: "tsx", icon: ICON_TYPESCRIPT },
   typescript: {
-    grammar: 'typescript',
+    grammar: "typescript",
     icon: ICON_TYPESCRIPT,
-    aliases: ['cts', 'mts', 'ts']
+    aliases: ["cts", "mts", "ts"],
   },
-  vue: { grammar: 'vue', icon: ICON_VUE },
-  'vue-html': { grammar: 'vue-html', icon: ICON_VUE },
-  yaml: { grammar: 'yaml', icon: ICON_YAML, aliases: ['yml'] },
-}
+  vue: { grammar: "vue", icon: ICON_VUE },
+  "vue-html": { grammar: "vue-html", icon: ICON_VUE },
+  yaml: { grammar: "yaml", icon: ICON_YAML, aliases: ["yml"] },
+};
 
 /** Every spelling (canonical id plus aliases) mapped to its canonical language id. */
-const LANGUAGE_INDEX: Record<string, string> = {}
+const LANGUAGE_INDEX: Record<string, string> = {};
 
 /** Every spelling mapped to its header icon, derived from `LANGUAGES` so it cannot drift. */
-const LANGUAGE_ICON_INDEX: Record<string, string> = {}
+const LANGUAGE_ICON_INDEX: Record<string, string> = {};
 
 Object.entries(LANGUAGES).forEach(([id, entry]) => {
-  const spellings = [id, ...(entry.aliases ?? [])]
+  const spellings = [id, ...(entry.aliases ?? [])];
   spellings.forEach((spelling) => {
-    LANGUAGE_INDEX[spelling] = id
-    LANGUAGE_ICON_INDEX[spelling] = entry.icon
-  })
-})
+    LANGUAGE_INDEX[spelling] = id;
+    LANGUAGE_ICON_INDEX[spelling] = entry.icon;
+  });
+});
 
 /**
  * Language and file-extension to built-in SVG icon lookup, covering every canonical
  * id and every alias of the registry.
  */
-export const LANGUAGE_ICONS: Record<string, string> = LANGUAGE_ICON_INDEX
+export const LANGUAGE_ICONS: Record<string, string> = LANGUAGE_ICON_INDEX;
 
 /** Grammar ids referenced by the registry; kept in sync with `GRAMMAR_LOADERS` by tests. */
 export const CODE_BLOCK_GRAMMARS: readonly string[] = [
-  ...new Set(Object.values(LANGUAGES).map((entry) => entry.grammar))
-]
+  ...new Set(Object.values(LANGUAGES).map((entry) => entry.grammar)),
+];
 
 /* -------------------------------------------------------------------------- */
 /* Resolvers                                                                   */
 /* -------------------------------------------------------------------------- */
 
-const SFC_BLOCK_RE = /^<(template|script|style)[\s>]/m
+const SFC_BLOCK_RE = /^<(template|script|style)[\s>]/m;
 
 /** Normalize a spelling, returning `''` when nothing usable was provided. */
-const normalizeSpelling = (value: string | undefined): string => value?.trim().toLowerCase() ?? ''
+const normalizeSpelling = (value: string | undefined): string => value?.trim().toLowerCase() ?? "";
 
 /** Resolve an arbitrary spelling to its canonical language id, or `null` when unknown. */
 const canonicalLanguage = (value: string | undefined): string | null => {
-  const spelling = normalizeSpelling(value)
-  return LANGUAGE_INDEX[spelling] ?? null
-}
+  const spelling = normalizeSpelling(value);
+  return LANGUAGE_INDEX[spelling] ?? null;
+};
 
 /** Look up the icon for a spelling, or `null` when the language is unknown. */
 const lookupIcon = (value: string | undefined): string | null => {
-  const spelling = normalizeSpelling(value)
-  if (!spelling) return null
-  return LANGUAGE_ICON_INDEX[spelling] ?? null
-}
+  const spelling = normalizeSpelling(value);
+  if (!spelling) return null;
+  return LANGUAGE_ICON_INDEX[spelling] ?? null;
+};
 
 /**
  * Extract a lowercase file extension without the leading dot.
  * `App.vue` -> `vue`, `config.test.ts` -> `ts`, `Dockerfile` -> `dockerfile`.
  */
 export const extractExtension = (filename: string): string => {
-  if (!filename) return ''
-  const trimmed = filename.trim().toLowerCase()
-  if (trimmed === 'dockerfile') return 'dockerfile'
+  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)
-}
+  const lastDot = trimmed.lastIndexOf(".");
+  if (lastDot === -1 || lastDot === trimmed.length - 1) return "";
+  return trimmed.slice(lastDot + 1);
+};
 
 /**
  * Resolve the header icon from an explicit `icon` prop, the `language` prop or the
@@ -157,36 +157,36 @@ export const extractExtension = (filename: string): string => {
 export const resolveCodeBlockIcon = (
   explicitIcon: IconSource | boolean | undefined,
   language: string | undefined,
-  filename: string | undefined
+  filename: string | undefined,
 ): IconSource | null => {
   // Explicitly disabled.
-  if (explicitIcon === false) return null
+  if (explicitIcon === false) return null;
 
   // An explicit icon source always wins.
-  if (explicitIcon && typeof explicitIcon !== 'boolean') return explicitIcon
+  if (explicitIcon && typeof explicitIcon !== "boolean") return explicitIcon;
 
-  const extension = filename ? extractExtension(filename) : ''
-  const icon = lookupIcon(language) ?? lookupIcon(extension)
-  if (icon) return icon
+  const extension = filename ? extractExtension(filename) : "";
+  const icon = lookupIcon(language) ?? lookupIcon(extension);
+  if (icon) return icon;
 
   // `icon: true` promises an icon even when the language stays unknown.
-  if (explicitIcon === true) return DEFAULT_CODE_ICON
+  if (explicitIcon === true) return DEFAULT_CODE_ICON;
 
-  return null
-}
+  return null;
+};
 
 /**
  * Resolve the shiki grammar for a `language` value and code snippet.
  * Unknown languages fall back to `log` instead of guessing a highlighter they cannot load.
  */
 export const resolveCodeBlockGrammar = (language: string | undefined, code: string): string => {
-  const canonical = canonicalLanguage(language)
-  if (!canonical) return 'log'
+  const canonical = canonicalLanguage(language);
+  if (!canonical) return "log";
   // The `vue` grammar only tokenizes inside SFC blocks; bare template snippets
   // (e.g. `<div><Button v-model="x" /></div>`) need the template grammar instead.
-  if (canonical === 'vue' && !SFC_BLOCK_RE.test(code)) return 'vue-html'
-  return LANGUAGES[canonical].grammar
-}
+  if (canonical === "vue" && !SFC_BLOCK_RE.test(code)) return "vue-html";
+  return LANGUAGES[canonical]?.grammar ?? "log";
+};
 
 /* -------------------------------------------------------------------------- */
 /* shiki grammar loading                                                       */
@@ -197,35 +197,35 @@ export const resolveCodeBlockGrammar = (language: string | undefined, code: stri
  * `LANGUAGES` by `languages.test.ts`.
  */
 const GRAMMAR_LOADERS: Record<string, () => LanguageInput> = {
-  css: () => import('shiki/dist/langs/css.mjs'),
-  docker: () => import('shiki/dist/langs/docker.mjs'),
-  go: () => import('shiki/dist/langs/go.mjs'),
-  html: () => import('shiki/dist/langs/html.mjs'),
-  javascript: () => import('shiki/dist/langs/javascript.mjs'),
-  json: () => import('shiki/dist/langs/json.mjs'),
-  jsx: () => import('shiki/dist/langs/jsx.mjs'),
-  log: () => import('shiki/dist/langs/log.mjs'),
-  markdown: () => import('shiki/dist/langs/markdown.mjs'),
-  python: () => import('shiki/dist/langs/python.mjs'),
-  rust: () => import('shiki/dist/langs/rust.mjs'),
-  shellscript: () => import('shiki/dist/langs/shellscript.mjs'),
-  sql: () => import('shiki/dist/langs/sql.mjs'),
-  toml: () => import('shiki/dist/langs/toml.mjs'),
-  tsx: () => import('shiki/dist/langs/tsx.mjs'),
-  typescript: () => import('shiki/dist/langs/typescript.mjs'),
-  vue: () => import('shiki/dist/langs/vue.mjs'),
-  'vue-html': () => import('shiki/dist/langs/vue-html.mjs'),
-  yaml: () => import('shiki/dist/langs/yaml.mjs'),
-}
+  css: () => import("shiki/dist/langs/css.mjs"),
+  docker: () => import("shiki/dist/langs/docker.mjs"),
+  go: () => import("shiki/dist/langs/go.mjs"),
+  html: () => import("shiki/dist/langs/html.mjs"),
+  javascript: () => import("shiki/dist/langs/javascript.mjs"),
+  json: () => import("shiki/dist/langs/json.mjs"),
+  jsx: () => import("shiki/dist/langs/jsx.mjs"),
+  log: () => import("shiki/dist/langs/log.mjs"),
+  markdown: () => import("shiki/dist/langs/markdown.mjs"),
+  python: () => import("shiki/dist/langs/python.mjs"),
+  rust: () => import("shiki/dist/langs/rust.mjs"),
+  shellscript: () => import("shiki/dist/langs/shellscript.mjs"),
+  sql: () => import("shiki/dist/langs/sql.mjs"),
+  toml: () => import("shiki/dist/langs/toml.mjs"),
+  tsx: () => import("shiki/dist/langs/tsx.mjs"),
+  typescript: () => import("shiki/dist/langs/typescript.mjs"),
+  vue: () => import("shiki/dist/langs/vue.mjs"),
+  "vue-html": () => import("shiki/dist/langs/vue-html.mjs"),
+  yaml: () => import("shiki/dist/langs/yaml.mjs"),
+};
 
 /** Grammar ids covered by `GRAMMAR_LOADERS`, exported so tests can assert full coverage. */
-export const CODE_BLOCK_GRAMMAR_IDS: readonly string[] = Object.keys(GRAMMAR_LOADERS)
+export const CODE_BLOCK_GRAMMAR_IDS: readonly string[] = Object.keys(GRAMMAR_LOADERS);
 
 /**
  * Import a single shiki grammar on demand. Returns `null` for an unknown grammar;
  * callers cache the promise so each grammar is fetched at most once per session.
  */
 export const loadCodeBlockGrammar = (grammar: string): LanguageInput | null => {
-  const loader = GRAMMAR_LOADERS[grammar]
-  return loader ? loader() : null
-}
+  const loader = GRAMMAR_LOADERS[grammar];
+  return loader ? loader() : null;
+};
diff --git a/packages/ui/src/components/code-block/types.ts b/packages/ui/src/components/code-block/types.ts
index 8ac6f6f..2a3b08a 100644
--- a/packages/ui/src/components/code-block/types.ts
+++ b/packages/ui/src/components/code-block/types.ts
@@ -1,9 +1,9 @@
-import type { IconSource } from '../icon'
+import type { IconSource } from "../icon";
 
 export interface CodeBlockProps {
-  code?: string
-  language?: string
-  filename?: string
+  code?: string;
+  language?: string;
+  filename?: string;
   /**
    * 编程语言或代码文件图标。
    * - `true`: 根据 `language` 或 `filename` 自动匹配图标（未匹配到时显示通用代码图标）；
@@ -11,12 +11,12 @@ export interface CodeBlockProps {
    * - `IconSource`（组件、SVG 代码或前缀名）：自定义显示指定图标。
    * 默认情况下，当传入非空的 `language` 或 `filename` 时自动尝试匹配语言图标。
    */
-  icon?: IconSource | boolean
-  copyable?: boolean
-  showLineNumbers?: boolean
-  wrap?: boolean
-  maxHeight?: string
+  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
+  collapsible?: boolean;
+  class?: string;
 }
diff --git a/packages/ui/src/components/code-group/index.ts b/packages/ui/src/components/code-group/index.ts
index d0477a1..b8c2d8d 100644
--- a/packages/ui/src/components/code-group/index.ts
+++ b/packages/ui/src/components/code-group/index.ts
@@ -1,2 +1,2 @@
-export { default as CodeGroup } from './CodeGroup.vue'
-export type { CodeGroupProps, CodeGroupTab } from './types'
+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
index 410572e..94a79b6 100644
--- a/packages/ui/src/components/code-group/types.ts
+++ b/packages/ui/src/components/code-group/types.ts
@@ -1,13 +1,13 @@
-import type { IconSource } from '../icon'
+import type { IconSource } from "../icon";
 
 export interface CodeGroupTab {
-  label: string
-  key?: string
-  icon?: IconSource
+  label: string;
+  key?: string;
+  icon?: IconSource;
 }
 
 export interface CodeGroupProps {
-  modelValue?: string | number
-  tabs?: (string | CodeGroupTab)[]
-  class?: string
+  modelValue?: string | number;
+  tabs?: (string | CodeGroupTab)[];
+  class?: string;
 }
diff --git a/packages/ui/src/components/collapsible/index.ts b/packages/ui/src/components/collapsible/index.ts
index 143e4dd..74eb2f9 100644
--- a/packages/ui/src/components/collapsible/index.ts
+++ b/packages/ui/src/components/collapsible/index.ts
@@ -1,2 +1,2 @@
-export { default as CollapsiblePanel } from './CollapsiblePanel.vue'
-export type { CollapsiblePanelProps } from './CollapsiblePanel.vue'
+export { default as CollapsiblePanel } from "./CollapsiblePanel.vue";
+export type { CollapsiblePanelProps } from "./CollapsiblePanel.vue";
diff --git a/packages/ui/src/components/combobox/index.ts b/packages/ui/src/components/combobox/index.ts
index 6850713..10775f7 100644
--- a/packages/ui/src/components/combobox/index.ts
+++ b/packages/ui/src/components/combobox/index.ts
@@ -1,2 +1,2 @@
-export { default as Combobox } from './Combobox.vue'
-export type { ComboboxOption, ComboboxProps } from './types'
+export { default as Combobox } 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
index 08517fa..c1ac64f 100644
--- a/packages/ui/src/components/combobox/types.ts
+++ b/packages/ui/src/components/combobox/types.ts
@@ -1,22 +1,22 @@
 export interface ComboboxOption {
-  label: string
-  value: string
-  disabled?: boolean
-  group?: string
+  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
+  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/command-palette/CommandPalette.vue b/packages/ui/src/components/command-palette/CommandPalette.vue
index 404f703..46b90b3 100644
--- a/packages/ui/src/components/command-palette/CommandPalette.vue
+++ b/packages/ui/src/components/command-palette/CommandPalette.vue
@@ -157,8 +157,10 @@ function moveActive(direction: 1 | -1) {
   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' })
+  const nextItem = items[nextIndex]
+  if (!nextItem) return
+  activeId.value = nextItem.id
+  document.getElementById(itemDomId(nextItem))?.scrollIntoView({ block: 'nearest' })
 }
 
 function selectActive() {
diff --git a/packages/ui/src/components/command-palette/commandMatcher.test.ts b/packages/ui/src/components/command-palette/commandMatcher.test.ts
index f0abb23..5c7a75e 100644
--- a/packages/ui/src/components/command-palette/commandMatcher.test.ts
+++ b/packages/ui/src/components/command-palette/commandMatcher.test.ts
@@ -1,24 +1,24 @@
-import { describe, expect, it } from 'vitest'
-import { filterCommands, scoreCommand } from './commandMatcher'
-import type { CommandItem } from './types'
+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 }
-]
+  { 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()
-  })
+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("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))
-  })
-})
+  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
index f9d0141..81b0e44 100644
--- a/packages/ui/src/components/command-palette/commandMatcher.ts
+++ b/packages/ui/src/components/command-palette/commandMatcher.ts
@@ -1,9 +1,9 @@
-import type { CommandItem } from './types'
+import type { CommandItem } from "./types";
 
 export interface CommandMatch {
-  item: CommandItem
-  score: number
-  index: number
+  item: CommandItem;
+  score: number;
+  index: number;
 }
 
 /**
@@ -12,41 +12,41 @@ export interface CommandMatch {
  * for equally relevant commands.
  */
 export function scoreCommand(item: CommandItem, query: string): number | null {
-  const normalizedQuery = query.trim().toLocaleLowerCase()
-  if (!normalizedQuery) return 0
+  const normalizedQuery = query.trim().toLocaleLowerCase();
+  if (!normalizedQuery) return 0;
 
   const haystack = [item.label, item.description, ...(item.keywords ?? [])]
     .filter(Boolean)
-    .join(' ')
-    .toLocaleLowerCase()
+    .join(" ")
+    .toLocaleLowerCase();
 
-  let score = 0
-  let previousIndex = -2
-  let cursor = 0
+  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
+    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
+    score += 10;
+    if (index === previousIndex + 1) score += 8;
+    if (index === 0 || /[\s/._:-]/.test(haystack[index - 1] ?? "")) score += 5;
 
-    previousIndex = index
-    cursor = index + 1
+    previousIndex = index;
+    cursor = index + 1;
   }
 
   // Prefer concise labels when all other match characteristics are equal.
-  return score - haystack.length / 1000
+  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 }
+      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)
+    .map(({ item }) => item);
 }
diff --git a/packages/ui/src/components/command-palette/index.ts b/packages/ui/src/components/command-palette/index.ts
index 094fd16..3ea2067 100644
--- a/packages/ui/src/components/command-palette/index.ts
+++ b/packages/ui/src/components/command-palette/index.ts
@@ -1,2 +1,2 @@
-export { default as CommandPalette } from './CommandPalette.vue'
-export type { CommandFilter, CommandGroup, CommandItem } from './types'
+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
index 1072088..6b9d3b1 100644
--- a/packages/ui/src/components/command-palette/types.ts
+++ b/packages/ui/src/components/command-palette/types.ts
@@ -1,22 +1,22 @@
-import type { IconSource } from '../icon'
+import type { IconSource } from "../icon";
 
 export interface CommandItem {
   /** Stable identifier returned with the select event. */
-  id: string
-  label: string
-  description?: string
-  keywords?: string[]
-  shortcut?: string[]
-  icon?: IconSource
-  disabled?: boolean
+  id: string;
+  label: string;
+  description?: string;
+  keywords?: string[];
+  shortcut?: string[];
+  icon?: IconSource;
+  disabled?: boolean;
   /** Keep the palette open after this item is selected. */
-  keepOpen?: boolean
+  keepOpen?: boolean;
 }
 
 export interface CommandGroup {
-  id?: string
-  heading?: string
-  items: CommandItem[]
+  id?: string;
+  heading?: string;
+  items: CommandItem[];
 }
 
-export type CommandFilter = (items: CommandItem[], query: string) => CommandItem[]
+export type CommandFilter = (items: CommandItem[], query: string) => CommandItem[];
diff --git a/apps/playground/components/DocExample.vue b/packages/ui/src/components/component-example/ComponentExample.vue
similarity index 52%
rename from apps/playground/components/DocExample.vue
rename to packages/ui/src/components/component-example/ComponentExample.vue
index 7b23fad..bfc97e0 100644
--- a/apps/playground/components/DocExample.vue
+++ b/packages/ui/src/components/component-example/ComponentExample.vue
@@ -1,24 +1,23 @@
 <template>
-  <section class="space-y-3">
+  <section :class="cn('space-y-3', props.class)">
     <div v-if="props.title || $slots.header" class="flex items-baseline justify-between gap-4">
-      <h3 class="text-base font-semibold tracking-tight text-slate-900 dark:text-white">
+      <h3 class="text-base font-semibold tracking-tight text-[color:var(--foreground)]">
         <slot name="header">{{ props.title }}</slot>
       </h3>
-      <span v-if="props.badge" class="text-[11px] font-mono text-slate-500 dark:text-slate-400">{{ props.badge }}</span>
+      <span v-if="props.badge" class="font-mono text-[11px] text-[color:var(--muted-foreground)]">{{ props.badge }}</span>
     </div>
-    <p v-if="props.description" class="text-sm leading-6 text-slate-600 dark:text-slate-400 -mt-1 max-w-2xl">
+    <p v-if="props.description" class="-mt-1 max-w-2xl text-sm leading-6 text-[color:var(--muted-foreground)]">
       {{ props.description }}
     </p>
 
-    <div v-if="$slots.default" class="rounded-xl ring-1 ring-inset ring-slate-200/80 dark:ring-slate-800/80 bg-white dark:bg-[#0B1220]">
-      <div class="p-6 sm:p-8 bg-grid-pattern/40">
-        <div class="preview-area">
+    <Card v-if="$slots.default" variant="outline" padding="none">
+      <div class="bg-grid-pattern/40 p-6 sm:p-8">
+        <div class="rc-component-example-preview">
           <slot />
         </div>
       </div>
-    </div>
+    </Card>
 
-    <!-- Code panels use the stock CodeBlock look (border, shadow, rounded, collapsible). -->
     <CodeBlock
       v-if="props.code"
       v-model:collapsed="codeCollapsed"
@@ -31,41 +30,36 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue'
+import { cn } from '../../utils/cn'
+import Card from '../card/Card.vue'
+import CodeBlock from '../code-block/CodeBlock.vue'
+import type { ComponentExampleProps } from './types'
 
-export interface DocExampleProps {
-  title?: string
-  description?: string
-  code?: string
-  badge?: string
-  /** Show the code expanded on first render (default). */
-  expanded?: boolean
-}
-
-const props = withDefaults(defineProps<DocExampleProps>(), {
+const props = withDefaults(defineProps<ComponentExampleProps>(), {
   title: '',
   description: '',
   code: '',
   badge: '',
-  expanded: true
+  expanded: true,
+  class: ''
 })
 
 const codeCollapsed = ref(!props.expanded)
 
-/** Infer the snippet language; CodeBlock resolves aliases such as `ts` and `bash`. */
 const codeLanguage = computed(() => {
   const code = props.code
   const first = code.trimStart().slice(0, 40)
+
   if (/^(# |npm |bun |pnpm |yarn |npx )/.test(first)) return 'bash'
   if (/^\/\//.test(first) && /defineNuxtConfig|export default/.test(code)) return 'ts'
   if (/^(import |export |const |let |function |interface |type |async )/.test(first)) return 'ts'
   if (/^[{[]/.test(first)) return 'json'
   return 'vue'
 })
-
 </script>
 
 <style scoped>
-.preview-area :deep(.demo-grid) {
+.rc-component-example-preview :deep(.demo-grid) {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
diff --git a/packages/ui/src/components/component-example/componentExample.test.ts b/packages/ui/src/components/component-example/componentExample.test.ts
new file mode 100644
index 0000000..a34b675
--- /dev/null
+++ b/packages/ui/src/components/component-example/componentExample.test.ts
@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = readFileSync(
+  fileURLToPath(new URL("./ComponentExample.vue", import.meta.url)),
+  "utf8",
+);
+const types = readFileSync(fileURLToPath(new URL("./types.ts", import.meta.url)), "utf8");
+
+describe("ComponentExample component contract", () => {
+  it("composes Card and CodeBlock around the preview and source", () => {
+    expect(source).toContain('<Card v-if="$slots.default" variant="outline" padding="none">');
+    expect(source).toContain("<CodeBlock");
+    expect(source).toContain('v-model:collapsed="codeCollapsed"');
+  });
+
+  it("supports contextual metadata and expanded source control", () => {
+    expect(types).toContain("title?: string");
+    expect(types).toContain("description?: string");
+    expect(types).toContain("badge?: string");
+    expect(source).toContain("expanded: true");
+  });
+});
diff --git a/packages/ui/src/components/component-example/index.ts b/packages/ui/src/components/component-example/index.ts
new file mode 100644
index 0000000..9114f44
--- /dev/null
+++ b/packages/ui/src/components/component-example/index.ts
@@ -0,0 +1,2 @@
+export { default as ComponentExample } from "./ComponentExample.vue";
+export type { ComponentExampleProps } from "./types";
diff --git a/packages/ui/src/components/component-example/types.ts b/packages/ui/src/components/component-example/types.ts
new file mode 100644
index 0000000..164fb5d
--- /dev/null
+++ b/packages/ui/src/components/component-example/types.ts
@@ -0,0 +1,9 @@
+export interface ComponentExampleProps {
+  title?: string;
+  description?: string;
+  code?: string;
+  badge?: string;
+  /** Show the code expanded on first render. */
+  expanded?: boolean;
+  class?: string;
+}
diff --git a/packages/ui/src/components/context-menu/index.ts b/packages/ui/src/components/context-menu/index.ts
index 6407744..6a496d5 100644
--- a/packages/ui/src/components/context-menu/index.ts
+++ b/packages/ui/src/components/context-menu/index.ts
@@ -1,2 +1,2 @@
-export { default as ContextMenu } from './ContextMenu.vue'
-export type { ContextMenuProps, ContextMenuItemData } from './ContextMenu.vue'
+export { default as ContextMenu } from "./ContextMenu.vue";
+export type { ContextMenuProps, ContextMenuItemData } from "./ContextMenu.vue";
diff --git a/packages/ui/src/components/date-picker/dateUtils.test.ts b/packages/ui/src/components/date-picker/dateUtils.test.ts
index b19c8ef..cd9db12 100644
--- a/packages/ui/src/components/date-picker/dateUtils.test.ts
+++ b/packages/ui/src/components/date-picker/dateUtils.test.ts
@@ -1,23 +1,23 @@
-import { describe, expect, it } from 'vitest'
-import { addMonths, monthDays, parseDateKey, toDateKey } from './dateUtils'
+import { describe, expect, it } from "vitest";
+import { addMonths, monthDays, parseDateKey, toDateKey } from "./dateUtils";
 
-describe('dateUtils', () => {
-  it('parses only valid ISO date keys', () => {
-    const parsed = parseDateKey('2026-02-28')
-    expect(parsed).toBeDefined()
+describe("dateUtils", () => {
+  it("parses only valid ISO date keys", () => {
+    const parsed = parseDateKey("2026-02-28");
+    expect(parsed).toBeDefined();
     if (parsed) {
-      expect(toDateKey(parsed)).toBe('2026-02-28')
+      expect(toDateKey(parsed)).toBe("2026-02-28");
     }
-    expect(parseDateKey('2026-02-30')).toBeUndefined()
-  })
+    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("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')
-  })
-})
+  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
index 50108b8..372bd74 100644
--- a/packages/ui/src/components/date-picker/dateUtils.ts
+++ b/packages/ui/src/components/date-picker/dateUtils.ts
@@ -1,44 +1,50 @@
 export interface DateRangeValue {
-  start: string
-  end: string
+  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}`
+  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
+  if (!value || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return undefined;
+  const [year = 0, month = 0, day = 0] = 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)
+  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) : ''
+  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)
+  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() }
-  })
+    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)
+  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
index 7118089..ebbcecf 100644
--- a/packages/ui/src/components/date-picker/index.ts
+++ b/packages/ui/src/components/date-picker/index.ts
@@ -1,3 +1,3 @@
-export { default as DatePicker } from './DatePicker.vue'
-export { default as DateRangePicker } from './DateRangePicker.vue'
-export type { DateRangeValue } from './dateUtils'
+export { default as DatePicker } from "./DatePicker.vue";
+export { default as DateRangePicker } from "./DateRangePicker.vue";
+export type { DateRangeValue } from "./dateUtils";
diff --git a/packages/ui/src/components/dialog/index.ts b/packages/ui/src/components/dialog/index.ts
index 87a85b1..cddc4ed 100644
--- a/packages/ui/src/components/dialog/index.ts
+++ b/packages/ui/src/components/dialog/index.ts
@@ -1,2 +1,2 @@
-export { default as Dialog } from './Dialog.vue'
-export type { DialogProps } from './Dialog.vue'
+export { default as Dialog } from "./Dialog.vue";
+export type { DialogProps } from "./Dialog.vue";
diff --git a/packages/ui/src/components/dropdown/index.ts b/packages/ui/src/components/dropdown/index.ts
index 8558adf..c26bb5c 100644
--- a/packages/ui/src/components/dropdown/index.ts
+++ b/packages/ui/src/components/dropdown/index.ts
@@ -1,2 +1,2 @@
-export { default as DropdownMenu } from './DropdownMenu.vue'
-export type { DropdownMenuProps, DropdownMenuItemType } from './DropdownMenu.vue'
+export { default as DropdownMenu } from "./DropdownMenu.vue";
+export type { DropdownMenuProps, DropdownMenuItemType } from "./DropdownMenu.vue";
diff --git a/packages/ui/src/components/editable/index.ts b/packages/ui/src/components/editable/index.ts
index dece1bc..a767c75 100644
--- a/packages/ui/src/components/editable/index.ts
+++ b/packages/ui/src/components/editable/index.ts
@@ -1,2 +1,2 @@
-export { default as Editable } from './Editable.vue'
-export type { EditableProps } from './Editable.vue'
+export { default as Editable } from "./Editable.vue";
+export type { EditableProps } from "./Editable.vue";
diff --git a/packages/ui/src/components/empty/index.ts b/packages/ui/src/components/empty/index.ts
index c925b47..e9c5899 100644
--- a/packages/ui/src/components/empty/index.ts
+++ b/packages/ui/src/components/empty/index.ts
@@ -1,2 +1,2 @@
-export { default as EmptyState } from './EmptyState.vue'
-export type { EmptyStateProps } from './EmptyState.vue'
+export { default as EmptyState } from "./EmptyState.vue";
+export type { EmptyStateProps } from "./EmptyState.vue";
diff --git a/packages/ui/src/components/field/index.ts b/packages/ui/src/components/field/index.ts
index 78fbfcc..14a3a43 100644
--- a/packages/ui/src/components/field/index.ts
+++ b/packages/ui/src/components/field/index.ts
@@ -1,2 +1,2 @@
-export type { FieldProps } from './Field.vue'
-export { default as Field } from './Field.vue'
+export type { FieldProps } from "./Field.vue";
+export { default as Field } from "./Field.vue";
diff --git a/packages/ui/src/components/file-upload/index.ts b/packages/ui/src/components/file-upload/index.ts
index 223b211..2de97bf 100644
--- a/packages/ui/src/components/file-upload/index.ts
+++ b/packages/ui/src/components/file-upload/index.ts
@@ -1,2 +1,7 @@
-export { default as FileUpload } from './FileUpload.vue'
-export type { FileUploadHandler, FileUploadItem, FileUploadRequest, FileUploadStatus } from './types'
+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
index 3b8af8e..e745ca2 100644
--- a/packages/ui/src/components/file-upload/types.ts
+++ b/packages/ui/src/components/file-upload/types.ts
@@ -1,18 +1,18 @@
-export type FileUploadStatus = 'pending' | 'uploading' | 'success' | 'error' | 'cancelled'
+export type FileUploadStatus = "pending" | "uploading" | "success" | "error" | "cancelled";
 
 export interface FileUploadItem {
-  id: string
-  file: File
-  status: FileUploadStatus
-  progress?: number
-  error?: string
-  previewUrl?: string
+  id: string;
+  file: File;
+  status: FileUploadStatus;
+  progress?: number;
+  error?: string;
+  previewUrl?: string;
 }
 
 export interface FileUploadRequest {
-  file: File
-  signal: AbortSignal
-  setProgress: (value: number) => void
+  file: File;
+  signal: AbortSignal;
+  setProgress: (value: number) => void;
 }
 
-export type FileUploadHandler = (request: FileUploadRequest) => Promise<void>
+export type FileUploadHandler = (request: FileUploadRequest) => Promise<void>;
diff --git a/packages/ui/src/components/footer/footer.test.ts b/packages/ui/src/components/footer/footer.test.ts
index 3f3b091..e74e057 100644
--- a/packages/ui/src/components/footer/footer.test.ts
+++ b/packages/ui/src/components/footer/footer.test.ts
@@ -1,35 +1,35 @@
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'vitest'
-import { Footer } from './index'
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { Footer } from "./index";
 
-const source = readFileSync(fileURLToPath(new URL('./Footer.vue', import.meta.url)), 'utf8')
-const types = readFileSync(fileURLToPath(new URL('./types.ts', import.meta.url)), 'utf8')
+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()
-  })
+describe("Footer component contract", () => {
+  it("is exported as a Vue component", () => {
+    expect(Footer).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("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("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"')
-  })
-})
+  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/index.ts b/packages/ui/src/components/footer/index.ts
index 538720d..e69cb0a 100644
--- a/packages/ui/src/components/footer/index.ts
+++ b/packages/ui/src/components/footer/index.ts
@@ -1,2 +1,2 @@
-export { default as Footer } from './Footer.vue'
-export type { FooterColumn, FooterLink, FooterProps, FooterSocial } from './types'
+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
index 27be639..07b74af 100644
--- a/packages/ui/src/components/footer/types.ts
+++ b/packages/ui/src/components/footer/types.ts
@@ -1,28 +1,28 @@
 export interface FooterLink {
-  label: string
-  href?: string
-  to?: string
-  target?: string
+  label: string;
+  href?: string;
+  to?: string;
+  target?: string;
 }
 
 export interface FooterColumn {
-  title: string
-  links: FooterLink[]
+  title: string;
+  links: FooterLink[];
 }
 
 export interface FooterSocial {
-  name: string
-  href: string
+  name: string;
+  href: string;
   /** Built-in icon name: github, discord, twitter, or x. Unknown values render the name text. */
-  icon?: string
+  icon?: string;
 }
 
 export interface FooterProps {
-  brandTitle?: string
-  brandDescription?: string
-  columns?: FooterColumn[]
-  copyright?: string
-  socials?: FooterSocial[]
-  bordered?: boolean
-  class?: string
+  brandTitle?: string;
+  brandDescription?: string;
+  columns?: FooterColumn[];
+  copyright?: string;
+  socials?: FooterSocial[];
+  bordered?: boolean;
+  class?: string;
 }
diff --git a/packages/ui/src/components/form/index.ts b/packages/ui/src/components/form/index.ts
index 1e178e6..9c76ebf 100644
--- a/packages/ui/src/components/form/index.ts
+++ b/packages/ui/src/components/form/index.ts
@@ -1,2 +1,2 @@
-export type { FormProps } from './Form.vue'
-export { default as Form } from './Form.vue'
+export type { FormProps } from "./Form.vue";
+export { default as Form } from "./Form.vue";
diff --git a/packages/ui/src/components/hero/hero.test.ts b/packages/ui/src/components/hero/hero.test.ts
index 6d818f7..3e89542 100644
--- a/packages/ui/src/components/hero/hero.test.ts
+++ b/packages/ui/src/components/hero/hero.test.ts
@@ -1,26 +1,26 @@
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'vitest'
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
 
-const source = readFileSync(fileURLToPath(new URL('./Hero.vue', import.meta.url)), 'utf8')
+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'")
-  })
+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("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')
-  })
-})
+  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/hero/index.ts b/packages/ui/src/components/hero/index.ts
index 1152ed0..6100534 100644
--- a/packages/ui/src/components/hero/index.ts
+++ b/packages/ui/src/components/hero/index.ts
@@ -1,2 +1,2 @@
-export { default as Hero } from './Hero.vue'
-export type { HeroLayout, HeroProps } from './types'
+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
index 68170c0..3ee403f 100644
--- a/packages/ui/src/components/hero/types.ts
+++ b/packages/ui/src/components/hero/types.ts
@@ -1,11 +1,11 @@
-export type HeroLayout = 'center' | 'split' | 'minimal'
+export type HeroLayout = "center" | "split" | "minimal";
 
 export interface HeroProps {
-  layout?: HeroLayout
-  badge?: string
-  title?: string
-  description?: string
-  primaryActionText?: string
-  secondaryActionText?: string
-  class?: string
+  layout?: HeroLayout;
+  badge?: string;
+  title?: string;
+  description?: string;
+  primaryActionText?: string;
+  secondaryActionText?: string;
+  class?: string;
 }
diff --git a/packages/ui/src/components/hover-card/index.ts b/packages/ui/src/components/hover-card/index.ts
index 39b7eab..afcb8ea 100644
--- a/packages/ui/src/components/hover-card/index.ts
+++ b/packages/ui/src/components/hover-card/index.ts
@@ -1,2 +1,2 @@
-export { default as HoverCard } from './HoverCard.vue'
-export type { HoverCardProps } from './HoverCard.vue'
+export { default as HoverCard } from "./HoverCard.vue";
+export type { HoverCardProps } from "./HoverCard.vue";
diff --git a/packages/ui/src/components/icon/icon.test.ts b/packages/ui/src/components/icon/icon.test.ts
index ab6785d..e3f3a56 100644
--- a/packages/ui/src/components/icon/icon.test.ts
+++ b/packages/ui/src/components/icon/icon.test.ts
@@ -1,30 +1,30 @@
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { describe, expect, it } from 'vitest'
-import { Icon } from './index'
+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')
-  })
+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')
+  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\'"')
+    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 />')
+    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"')
-  })
-})
+    expect(source).toContain(':style="sizeStyle"');
+  });
+});
diff --git a/packages/ui/src/components/icon/index.ts b/packages/ui/src/components/icon/index.ts
index 27940d2..7caf3bf 100644
--- a/packages/ui/src/components/icon/index.ts
+++ b/packages/ui/src/components/icon/index.ts
@@ -1,4 +1,4 @@
-export { default as Icon } from './Icon.vue'
-export * from './types'
-export * from './registry'
-export { lookupLucideIcon, toPascalCase } from './lucideResolver'
+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
index 5629d3e..9fa9537 100644
--- a/packages/ui/src/components/icon/lucideResolver.ts
+++ b/packages/ui/src/components/icon/lucideResolver.ts
@@ -1,55 +1,49 @@
-import type { Component } from 'vue'
+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 ''
+  if (!name) return "";
+  const trimmed = name.trim();
+  if (!trimmed) return "";
 
-  const parts = trimmed.split(/[-_\s]+/).filter(Boolean)
-  if (parts.length === 0) 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('')
+  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
 
 /**
  * 缓存已加载的 lucide-vue-next 模块，避免重复动态导入。
  */
-let lucideModulePromise: Promise<Record<string, unknown>> | null = null
+let lucideModulePromise: Promise<Record<string, unknown>> | null = null;
 
 function loadLucideModule(): Promise<Record<string, unknown>> {
   if (!lucideModulePromise) {
-    lucideModulePromise = import('lucide-vue-next').then((m) => {
+    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 m as Record<string, unknown>;
+    });
   }
-  return lucideModulePromise
+  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)
+  if (!name) return null;
+  const mod = await loadLucideModule();
+  const pascal = toPascalCase(name);
 
-  const candidate =
-    mod[pascal] ??
-    mod[`${pascal}Icon`] ??
-    mod[name] ??
-    mod[`${name}Icon`]
+  const candidate = mod[pascal] ?? mod[`${pascal}Icon`] ?? mod[name] ?? mod[`${name}Icon`];
 
-  if (candidate && (typeof candidate === 'object' || typeof candidate === 'function')) {
+  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 candidate as Component;
   }
 
-  return null
+  return null;
 }
diff --git a/packages/ui/src/components/icon/registry.test.ts b/packages/ui/src/components/icon/registry.test.ts
index f672d14..c7bb20d 100644
--- a/packages/ui/src/components/icon/registry.test.ts
+++ b/packages/ui/src/components/icon/registry.test.ts
@@ -1,5 +1,5 @@
-import { describe, expect, it } from 'vitest'
-import { toPascalCase } from './lucideResolver'
+import { describe, expect, it } from "vitest";
+import { toPascalCase } from "./lucideResolver";
 import {
   classifyIconSource,
   looksLikeImage,
@@ -8,127 +8,127 @@ import {
   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')
+  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()
-  })
+    expect(unregistered).toBeNull();
+  });
 
-  it('supports asynchronous custom resolvers', async () => {
-    registerIconResolver('testasync', async (name) => {
-      if (name === 'rocket') {
-        return '<svg id="rocket"></svg>'
+  it("supports asynchronous custom resolvers", async () => {
+    registerIconResolver("testasync", async (name) => {
+      if (name === "rocket") {
+        return '<svg id="rocket"></svg>';
       }
-      return null
-    })
+      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>' })
+    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')
-  })
+    unregisterIconResolver("testasync");
+  });
 
-  it('falls back to default resolver for unknown prefixes and bare names', async () => {
+  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')
-  })
-})
+      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
index 92d2102..71e1bb5 100644
--- a/packages/ui/src/components/icon/registry.ts
+++ b/packages/ui/src/components/icon/registry.ts
@@ -1,33 +1,33 @@
-import { ref } from 'vue'
-import { lookupLucideIcon } from './lucideResolver'
-import type { IconResolver, IconSource, ResolvedIcon } from './types'
+import { ref } from "vue";
+import { lookupLucideIcon } from "./lucideResolver";
+import type { IconResolver, IconSource, ResolvedIcon } from "./types";
 
 /**
  * 响应式版本号计数器，供 Icon 组件监听动态注册变更。
  */
-export const iconRegistryVersion = ref(0)
+export const iconRegistryVersion = ref(0);
 
-const prefixResolvers = new Map<string, IconResolver>()
-let defaultIconResolver: IconResolver | null = null
+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++
+  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()
+  const normalized = prefix.trim().toLowerCase();
   if (prefixResolvers.delete(normalized)) {
-    iconRegistryVersion.value++
+    iconRegistryVersion.value++;
   }
 }
 
@@ -35,152 +35,148 @@ export function unregisterIconResolver(prefix: string): void {
  * 设置未带前缀图标名称的默认解析器。
  */
 export function setDefaultIconResolver(resolver: IconResolver | null | undefined): void {
-  defaultIconResolver = resolver ?? null
-  iconRegistryVersion.value++
+  defaultIconResolver = resolver ?? null;
+  iconRegistryVersion.value++;
 }
 
 /**
  * 判断字符串是否为内联 SVG 代码片段。
  */
 export function looksLikeSvg(value: string): boolean {
-  return /^\s*<svg[\s>]/i.test(value)
+  return /^\s*<svg[\s>]/i.test(value);
 }
 
 /**
  * 判断字符串是否为图像路径、网络 URL 或 Data URL。
  */
 export function looksLikeImage(value: string): boolean {
-  const trimmed = value.trim()
+  const trimmed = value.trim();
   if (
     /^(?:https?:)?\/\//i.test(trimmed) ||
-    trimmed.startsWith('/') ||
-    trimmed.startsWith('./') ||
-    trimmed.startsWith('../') ||
-    trimmed.startsWith('data:image/')
+    trimmed.startsWith("/") ||
+    trimmed.startsWith("./") ||
+    trimmed.startsWith("../") ||
+    trimmed.startsWith("data:image/")
   ) {
-    return true
+    return true;
   }
-  return /\.(svg|png|jpe?g|gif|webp|avif|ico)([?#].*)?$/i.test(trimmed)
+  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
+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()
-  }
+    prefix: match[1]?.toLowerCase() ?? "",
+    name: match[2]?.trim() ?? "",
+  };
 }
 
 /**
  * 分析给定的图标源类型归类。
  */
-export function classifyIconSource(
-  source: IconSource
-): 'component' | 'svg' | 'image' | 'named' {
-  if (typeof source !== 'string') {
-    return 'component'
+export function classifyIconSource(source: IconSource): "component" | "svg" | "image" | "named" {
+  if (typeof source !== "string") {
+    return "component";
   }
   if (looksLikeSvg(source)) {
-    return 'svg'
+    return "svg";
   }
   if (looksLikeImage(source)) {
-    return 'image'
+    return "image";
   }
-  return 'named'
+  return "named";
 }
 
 function isPromise<T>(value: unknown): value is Promise<T> {
-  if (value === null || typeof value !== 'object') {
-    return false
+  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'
+  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 }
+  if (!result) return null;
+  if (typeof result !== "string") {
+    return { kind: "component", component: result };
   }
-  const trimmed = result.trim()
-  if (!trimmed) return null
+  const trimmed = result.trim();
+  if (!trimmed) return null;
   if (looksLikeSvg(trimmed)) {
-    return { kind: 'svg', markup: trimmed }
+    return { kind: "svg", markup: trimmed };
   }
   if (looksLikeImage(trimmed)) {
-    return { kind: 'image', src: trimmed }
+    return { kind: "image", src: trimmed };
   }
-  return null
+  return null;
 }
 
 /**
  * 解析任意图标源为已规范化形态（支持同步返回或异步 Promise）。
  */
 export function resolveIconSource(
-  source: IconSource | null | undefined
+  source: IconSource | null | undefined,
 ): ResolvedIcon | Promise<ResolvedIcon | null> | null {
-  if (!source) return null
+  if (!source) return null;
 
-  if (typeof source !== 'string') {
-    return { kind: 'component', component: source }
+  if (typeof source !== "string") {
+    return { kind: "component", component: source };
   }
 
-  const trimmed = source.trim()
-  if (!trimmed) return null
+  const trimmed = source.trim();
+  if (!trimmed) return null;
 
   if (looksLikeSvg(trimmed)) {
-    return { kind: 'svg', markup: trimmed }
+    return { kind: "svg", markup: trimmed };
   }
 
   if (looksLikeImage(trimmed)) {
-    return { kind: 'image', src: trimmed }
+    return { kind: "image", src: trimmed };
   }
 
-  const prefixed = parsePrefixedName(trimmed)
+  const prefixed = parsePrefixedName(trimmed);
   if (prefixed) {
-    const resolver = prefixResolvers.get(prefixed.prefix)
+    const resolver = prefixResolvers.get(prefixed.prefix);
     if (resolver) {
-      const outcome = resolver(prefixed.name)
+      const outcome = resolver(prefixed.name);
       if (isPromise<IconSource | null | undefined>(outcome)) {
-        return outcome.then(normalizeResolved)
+        return outcome.then(normalizeResolved);
       }
-      return normalizeResolved(outcome)
+      return normalizeResolved(outcome);
     }
 
-    if (prefixed.prefix === 'lucide') {
+    if (prefixed.prefix === "lucide") {
       return lookupLucideIcon(prefixed.name).then((comp) => {
-        return comp ? { kind: 'component', component: comp } : null
-      })
+        return comp ? { kind: "component", component: comp } : null;
+      });
     }
 
     if (defaultIconResolver) {
-      const outcome = defaultIconResolver(trimmed)
+      const outcome = defaultIconResolver(trimmed);
       if (isPromise<IconSource | null | undefined>(outcome)) {
-        return outcome.then(normalizeResolved)
+        return outcome.then(normalizeResolved);
       }
-      return normalizeResolved(outcome)
+      return normalizeResolved(outcome);
     }
 
-    return null
+    return null;
   }
 
   if (defaultIconResolver) {
-    const outcome = defaultIconResolver(trimmed)
+    const outcome = defaultIconResolver(trimmed);
     if (isPromise<IconSource | null | undefined>(outcome)) {
-      return outcome.then(normalizeResolved)
+      return outcome.then(normalizeResolved);
     }
-    return normalizeResolved(outcome)
+    return normalizeResolved(outcome);
   }
 
   return lookupLucideIcon(trimmed).then((comp) => {
-    return comp ? { kind: 'component', component: comp } : null
-  })
+    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
index e5adcb0..7e15a9d 100644
--- a/packages/ui/src/components/icon/types.ts
+++ b/packages/ui/src/components/icon/types.ts
@@ -1,4 +1,4 @@
-import type { Component } from 'vue'
+import type { Component } from "vue";
 
 /**
  * 支持的图标源类型：
@@ -9,39 +9,39 @@ import type { Component } from 'vue'
  *   - 注册前缀名称（如 `lucide:settings`、`custom:logo`）
  *   - 纯图标名称（通过默认解析器或内置 lucide 处理）
  */
-export type IconSource = string | Component
+export type IconSource = string | Component;
 
 /**
  * 已规范化为具体渲染形态的结构。
  */
 export type ResolvedIcon =
-  | { kind: 'component'; component: Component }
-  | { kind: 'svg'; markup: string }
-  | { kind: 'image'; src: string }
+  | { 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>
+  name: string,
+) => IconSource | null | undefined | Promise<IconSource | null | undefined>;
 
 export interface IconProps {
   /**
    * 图标源：支持 Vue 组件、内联 SVG 字符串、图片 URL 或注册前缀名称。
    */
-  icon?: IconSource
+  icon?: IconSource;
 
   /**
    * 图标尺寸，默认 `'1em'`。
    * 传入数字时自动添加 `px`（例如 `16` -> `'16px'`）；传入字符串按 CSS 属性原样生效。
    */
-  size?: number | string
+  size?: number | string;
 
   /**
    * 无障碍描述文本。
    * 提供时赋予 `role="img"` 与 `aria-label`；缺省时应用 `aria-hidden="true"` 标记为装饰图标。
    */
-  label?: string
+  label?: string;
 }
diff --git a/packages/ui/src/components/inline-code/index.ts b/packages/ui/src/components/inline-code/index.ts
index 62e5ab9..02a46ba 100644
--- a/packages/ui/src/components/inline-code/index.ts
+++ b/packages/ui/src/components/inline-code/index.ts
@@ -1,2 +1,2 @@
-export { default as InlineCode } from './InlineCode.vue'
-export type { InlineCodeProps } from './types'
+export { default as InlineCode } from "./InlineCode.vue";
+export type { InlineCodeProps } from "./types";
diff --git a/packages/ui/src/components/inline-code/inlineCode.test.ts b/packages/ui/src/components/inline-code/inlineCode.test.ts
index 86a85c1..c3664a6 100644
--- a/packages/ui/src/components/inline-code/inlineCode.test.ts
+++ b/packages/ui/src/components/inline-code/inlineCode.test.ts
@@ -1,15 +1,15 @@
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'vitest'
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
 
-const source = readFileSync(fileURLToPath(new URL('./InlineCode.vue', import.meta.url)), 'utf8')
+const source = readFileSync(fileURLToPath(new URL("./InlineCode.vue", import.meta.url)), "utf8");
 
-describe('InlineCode component contract', () => {
-  it('decorates each wrapped line independently without overflowing narrow containers', () => {
-    expect(source).toContain("'inline rounded-md")
-    expect(source).toContain('[overflow-wrap:anywhere]')
-    expect(source).toContain('[box-decoration-break:clone]')
-    expect(source).toContain('[-webkit-box-decoration-break:clone]')
-    expect(source).not.toContain("'inline-flex min-w-0")
-  })
-})
+describe("InlineCode component contract", () => {
+  it("decorates each wrapped line independently without overflowing narrow containers", () => {
+    expect(source).toContain("'inline rounded-md");
+    expect(source).toContain("[overflow-wrap:anywhere]");
+    expect(source).toContain("[box-decoration-break:clone]");
+    expect(source).toContain("[-webkit-box-decoration-break:clone]");
+    expect(source).not.toContain("'inline-flex min-w-0");
+  });
+});
diff --git a/packages/ui/src/components/inline-code/types.ts b/packages/ui/src/components/inline-code/types.ts
index 86e8dcc..efc0130 100644
--- a/packages/ui/src/components/inline-code/types.ts
+++ b/packages/ui/src/components/inline-code/types.ts
@@ -1,6 +1,6 @@
 export interface InlineCodeProps {
-  code?: string
-  copyable?: boolean
-  variant?: 'subtle' | 'solid' | 'outline'
-  class?: string
+  code?: string;
+  copyable?: boolean;
+  variant?: "subtle" | "solid" | "outline";
+  class?: string;
 }
diff --git a/packages/ui/src/components/input/index.ts b/packages/ui/src/components/input/index.ts
index 5bbbd78..7162fb9 100644
--- a/packages/ui/src/components/input/index.ts
+++ b/packages/ui/src/components/input/index.ts
@@ -1,2 +1,2 @@
-export { default as Input } from './Input.vue'
-export type { InputProps } from './Input.vue'
+export { default as Input } from "./Input.vue";
+export type { InputProps } from "./Input.vue";
diff --git a/packages/ui/src/components/kbd/index.ts b/packages/ui/src/components/kbd/index.ts
index 37ec9e9..2d76834 100644
--- a/packages/ui/src/components/kbd/index.ts
+++ b/packages/ui/src/components/kbd/index.ts
@@ -1,2 +1,2 @@
-export { default as Kbd } from './Kbd.vue'
-export type { KbdProps } from './Kbd.vue'
+export { default as Kbd } from "./Kbd.vue";
+export type { KbdProps } from "./Kbd.vue";
diff --git a/packages/ui/src/components/label/index.ts b/packages/ui/src/components/label/index.ts
index ad9a11e..fa6097e 100644
--- a/packages/ui/src/components/label/index.ts
+++ b/packages/ui/src/components/label/index.ts
@@ -1,2 +1,2 @@
-export { default as Label } from './Label.vue'
-export type { LabelProps } from './Label.vue'
+export { default as Label } from "./Label.vue";
+export type { LabelProps } from "./Label.vue";
diff --git a/packages/ui/src/components/multi-select/index.ts b/packages/ui/src/components/multi-select/index.ts
index 92e9465..89c2550 100644
--- a/packages/ui/src/components/multi-select/index.ts
+++ b/packages/ui/src/components/multi-select/index.ts
@@ -1,2 +1,2 @@
-export { default as MultiSelect } from './MultiSelect.vue'
-export type { MultiSelectOption, MultiSelectProps } from './types'
+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
index ad54e47..7d172e0 100644
--- a/packages/ui/src/components/multi-select/types.ts
+++ b/packages/ui/src/components/multi-select/types.ts
@@ -1,21 +1,21 @@
 export interface MultiSelectOption {
-  label: string
-  value: string
-  disabled?: boolean
-  group?: string
+  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
+  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/components/nav-tree/NavTree.vue b/packages/ui/src/components/nav-tree/NavTree.vue
index b00f3ab..111a05e 100644
--- a/packages/ui/src/components/nav-tree/NavTree.vue
+++ b/packages/ui/src/components/nav-tree/NavTree.vue
@@ -51,7 +51,8 @@
               :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]',
+                'group flex items-center justify-between rounded-lg px-2.5 font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[#2563EB]',
+                props.size === 'comfortable' ? 'py-2 text-sm' : 'py-1.5 text-xs',
                 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'
@@ -86,6 +87,7 @@ const props = withDefaults(defineProps<NavTreeProps>(), {
   activeHref: '',
   searchable: false,
   searchPlaceholder: undefined,
+  size: 'compact',
   class: ''
 })
 
diff --git a/packages/ui/src/components/nav-tree/index.ts b/packages/ui/src/components/nav-tree/index.ts
index df463aa..5752990 100644
--- a/packages/ui/src/components/nav-tree/index.ts
+++ b/packages/ui/src/components/nav-tree/index.ts
@@ -1,2 +1,2 @@
-export { default as NavTree } from './NavTree.vue'
-export type { NavTreeGroup, NavTreeItem, NavTreeProps } from './types'
+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
index f2aa57b..b8b0aeb 100644
--- a/packages/ui/src/components/nav-tree/types.ts
+++ b/packages/ui/src/components/nav-tree/types.ts
@@ -1,25 +1,27 @@
-import type { IconSource } from '../icon'
+import type { IconSource } from "../icon";
 
 export interface NavTreeItem {
-  title: string
-  href?: string
-  to?: string
-  badge?: string
-  icon?: IconSource
-  disabled?: boolean
+  title: string;
+  href?: string;
+  to?: string;
+  badge?: string;
+  icon?: IconSource;
+  disabled?: boolean;
 }
 
 export interface NavTreeGroup {
-  title: string
-  collapsible?: boolean
-  defaultOpen?: boolean
-  items: NavTreeItem[]
+  title: string;
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+  items: NavTreeItem[];
 }
 
 export interface NavTreeProps {
-  groups: NavTreeGroup[]
-  activeHref?: string
-  searchable?: boolean
-  searchPlaceholder?: string
-  class?: string
+  groups: NavTreeGroup[];
+  activeHref?: string;
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  /** Controls item type scale and vertical rhythm. */
+  size?: "compact" | "comfortable";
+  class?: string;
 }
diff --git a/packages/ui/src/components/navbar/index.ts b/packages/ui/src/components/navbar/index.ts
index aae6961..f5b523e 100644
--- a/packages/ui/src/components/navbar/index.ts
+++ b/packages/ui/src/components/navbar/index.ts
@@ -1,2 +1,2 @@
-export { default as Navbar } from './Navbar.vue'
-export type { NavbarLink, NavbarProps } from './types'
+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
index 1a7befe..076f83d 100644
--- a/packages/ui/src/components/navbar/navbar.test.ts
+++ b/packages/ui/src/components/navbar/navbar.test.ts
@@ -1,20 +1,20 @@
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'vitest'
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
 
-const source = readFileSync(fileURLToPath(new URL('./Navbar.vue', import.meta.url)), 'utf8')
+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"')
-  })
+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')
-  })
-})
+  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");
+  });
+});
diff --git a/packages/ui/src/components/navbar/types.ts b/packages/ui/src/components/navbar/types.ts
index 2b41866..de83ad3 100644
--- a/packages/ui/src/components/navbar/types.ts
+++ b/packages/ui/src/components/navbar/types.ts
@@ -1,18 +1,18 @@
 export interface NavbarLink {
-  label: string
-  href?: string
-  to?: string
-  target?: string
-  badge?: string
-  active?: boolean
+  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
+  brandTitle?: string;
+  brandHref?: string;
+  brandTo?: string;
+  links?: NavbarLink[];
+  sticky?: boolean;
+  bordered?: boolean;
+  class?: string;
 }
diff --git a/packages/ui/src/components/navigation-menu/index.ts b/packages/ui/src/components/navigation-menu/index.ts
index ab489a9..55316e8 100644
--- a/packages/ui/src/components/navigation-menu/index.ts
+++ b/packages/ui/src/components/navigation-menu/index.ts
@@ -1,3 +1,3 @@
-export { default as NavigationMenu } from './NavigationMenu.vue'
-export type { NavigationMenuProps } from './NavigationMenu.vue'
-export type { NavigationMenuItem } from './NavigationMenu.vue'
+export { default as NavigationMenu } from "./NavigationMenu.vue";
+export type { NavigationMenuProps } from "./NavigationMenu.vue";
+export type { NavigationMenuItem } from "./NavigationMenu.vue";
diff --git a/packages/ui/src/components/number-field/index.ts b/packages/ui/src/components/number-field/index.ts
index 685c1d9..bdcec14 100644
--- a/packages/ui/src/components/number-field/index.ts
+++ b/packages/ui/src/components/number-field/index.ts
@@ -1,2 +1,2 @@
-export { default as NumberField } from './NumberField.vue'
-export type { NumberFieldProps } from './NumberField.vue'
+export { default as NumberField } from "./NumberField.vue";
+export type { NumberFieldProps } from "./NumberField.vue";
diff --git a/packages/ui/src/components/page-header/PageHeader.vue b/packages/ui/src/components/page-header/PageHeader.vue
new file mode 100644
index 0000000..00a10f9
--- /dev/null
+++ b/packages/ui/src/components/page-header/PageHeader.vue
@@ -0,0 +1,26 @@
+<template>
+  <header :class="cn('space-y-3 border-b border-[color:var(--border)] pb-8', props.class)">
+    <div class="flex flex-wrap items-center gap-2.5">
+      <span v-if="props.group" class="text-xs font-bold uppercase tracking-[0.16em] text-[color:var(--primary)]">{{ props.group }}</span>
+      <Badge v-if="props.badge" variant="outline" color="neutral" size="xs">{{ props.badge }}</Badge>
+    </div>
+    <h1 class="text-3xl font-bold tracking-tight text-[color:var(--foreground)] sm:text-4xl">
+      {{ props.title }}
+    </h1>
+    <p class="max-w-2xl text-base leading-7 text-[color:var(--muted-foreground)]">
+      {{ props.description }}
+    </p>
+  </header>
+</template>
+
+<script setup lang="ts">
+import { cn } from '../../utils/cn'
+import Badge from '../badge/Badge.vue'
+import type { PageHeaderProps } from './types'
+
+const props = withDefaults(defineProps<PageHeaderProps>(), {
+  group: 'Components',
+  badge: '',
+  class: ''
+})
+</script>
diff --git a/packages/ui/src/components/page-header/index.ts b/packages/ui/src/components/page-header/index.ts
new file mode 100644
index 0000000..2ff71ca
--- /dev/null
+++ b/packages/ui/src/components/page-header/index.ts
@@ -0,0 +1,2 @@
+export { default as PageHeader } from "./PageHeader.vue";
+export type { PageHeaderProps } from "./types";
diff --git a/packages/ui/src/components/page-header/pageHeader.test.ts b/packages/ui/src/components/page-header/pageHeader.test.ts
new file mode 100644
index 0000000..9d2b79c
--- /dev/null
+++ b/packages/ui/src/components/page-header/pageHeader.test.ts
@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = readFileSync(fileURLToPath(new URL("./PageHeader.vue", import.meta.url)), "utf8");
+
+describe("PageHeader component contract", () => {
+  it("renders documentation metadata with semantic heading hierarchy", () => {
+    expect(source).toContain("<header");
+    expect(source).toContain("<h1");
+    expect(source).toContain("props.group");
+    expect(source).toContain("<Badge");
+  });
+});
diff --git a/packages/ui/src/components/page-header/types.ts b/packages/ui/src/components/page-header/types.ts
new file mode 100644
index 0000000..aea2575
--- /dev/null
+++ b/packages/ui/src/components/page-header/types.ts
@@ -0,0 +1,7 @@
+export interface PageHeaderProps {
+  title: string;
+  description: string;
+  group?: string;
+  badge?: string;
+  class?: string;
+}
diff --git a/packages/ui/src/components/pagination/index.ts b/packages/ui/src/components/pagination/index.ts
index 84abbef..c7e0cd7 100644
--- a/packages/ui/src/components/pagination/index.ts
+++ b/packages/ui/src/components/pagination/index.ts
@@ -1,2 +1,2 @@
-export { default as Pagination } from './Pagination.vue'
-export type { PaginationProps } from './Pagination.vue'
+export { default as Pagination } from "./Pagination.vue";
+export type { PaginationProps } from "./Pagination.vue";
diff --git a/packages/ui/src/components/pin-input/index.ts b/packages/ui/src/components/pin-input/index.ts
index 7738f2e..d6310de 100644
--- a/packages/ui/src/components/pin-input/index.ts
+++ b/packages/ui/src/components/pin-input/index.ts
@@ -1,2 +1,2 @@
-export { default as PinInput } from './PinInput.vue'
-export type { PinInputProps } from './PinInput.vue'
+export { default as PinInput } from "./PinInput.vue";
+export type { PinInputProps } from "./PinInput.vue";
diff --git a/packages/ui/src/components/popover/index.ts b/packages/ui/src/components/popover/index.ts
index 9f4441b..c999d0f 100644
--- a/packages/ui/src/components/popover/index.ts
+++ b/packages/ui/src/components/popover/index.ts
@@ -1,2 +1,2 @@
-export { default as Popover } from './Popover.vue'
-export type { PopoverProps } from './Popover.vue'
+export { default as Popover } from "./Popover.vue";
+export type { PopoverProps } from "./Popover.vue";
diff --git a/packages/ui/src/components/prev-next/index.ts b/packages/ui/src/components/prev-next/index.ts
index 40eedfe..540d0d6 100644
--- a/packages/ui/src/components/prev-next/index.ts
+++ b/packages/ui/src/components/prev-next/index.ts
@@ -1,2 +1,2 @@
-export { default as PrevNext } from './PrevNext.vue'
-export type { PrevNextItem, PrevNextProps } from './types'
+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
index 4832ee6..af2c715 100644
--- a/packages/ui/src/components/prev-next/types.ts
+++ b/packages/ui/src/components/prev-next/types.ts
@@ -1,14 +1,14 @@
 export interface PrevNextItem {
-  title: string
-  href?: string
-  to?: string
-  description?: string
+  title: string;
+  href?: string;
+  to?: string;
+  description?: string;
 }
 
 export interface PrevNextProps {
-  prev?: PrevNextItem
-  next?: PrevNextItem
-  prevLabel?: string
-  nextLabel?: string
-  class?: string
+  prev?: PrevNextItem;
+  next?: PrevNextItem;
+  prevLabel?: string;
+  nextLabel?: string;
+  class?: string;
 }
diff --git a/packages/ui/src/components/progress/index.ts b/packages/ui/src/components/progress/index.ts
index eceb683..82e02d9 100644
--- a/packages/ui/src/components/progress/index.ts
+++ b/packages/ui/src/components/progress/index.ts
@@ -1,2 +1,2 @@
-export { default as Progress } from './Progress.vue'
-export type { ProgressProps } from './Progress.vue'
+export { default as Progress } from "./Progress.vue";
+export type { ProgressProps } from "./Progress.vue";
diff --git a/packages/ui/src/components/radio/index.ts b/packages/ui/src/components/radio/index.ts
index ac40b1f..74b095e 100644
--- a/packages/ui/src/components/radio/index.ts
+++ b/packages/ui/src/components/radio/index.ts
@@ -1,2 +1,2 @@
-export { default as RadioGroup } from './RadioGroup.vue'
-export type { RadioGroupProps, RadioOption } from './RadioGroup.vue'
+export { default as RadioGroup } from "./RadioGroup.vue";
+export type { RadioGroupProps, RadioOption } from "./RadioGroup.vue";
diff --git a/packages/ui/src/components/rating/index.ts b/packages/ui/src/components/rating/index.ts
index 0de50a3..0fe8608 100644
--- a/packages/ui/src/components/rating/index.ts
+++ b/packages/ui/src/components/rating/index.ts
@@ -1,2 +1,2 @@
-export { default as Rating } from './Rating.vue'
-export type { RatingProps } from './Rating.vue'
+export { default as Rating } from "./Rating.vue";
+export type { RatingProps } from "./Rating.vue";
diff --git a/packages/ui/src/components/resizable-panel/index.ts b/packages/ui/src/components/resizable-panel/index.ts
index cbe36bc..8e9de81 100644
--- a/packages/ui/src/components/resizable-panel/index.ts
+++ b/packages/ui/src/components/resizable-panel/index.ts
@@ -1 +1 @@
-export { default as ResizablePanel } from './ResizablePanel.vue'
+export { default as ResizablePanel } from "./ResizablePanel.vue";
diff --git a/packages/ui/src/components/scroll-area/index.ts b/packages/ui/src/components/scroll-area/index.ts
index 5f9f764..bbe879a 100644
--- a/packages/ui/src/components/scroll-area/index.ts
+++ b/packages/ui/src/components/scroll-area/index.ts
@@ -1,2 +1,2 @@
-export { default as ScrollArea } from './ScrollArea.vue'
-export type { ScrollAreaProps } from './ScrollArea.vue'
+export { default as ScrollArea } from "./ScrollArea.vue";
+export type { ScrollAreaProps } from "./ScrollArea.vue";
diff --git a/packages/ui/src/components/select/index.ts b/packages/ui/src/components/select/index.ts
index b4a9f3d..955429d 100644
--- a/packages/ui/src/components/select/index.ts
+++ b/packages/ui/src/components/select/index.ts
@@ -1,2 +1,2 @@
-export { default as Select } from './Select.vue'
-export type { SelectProps, SelectOption } from './Select.vue'
+export { default as Select } from "./Select.vue";
+export type { SelectProps, SelectOption } from "./Select.vue";
diff --git a/packages/ui/src/components/separator/index.ts b/packages/ui/src/components/separator/index.ts
index d30b90e..161ce13 100644
--- a/packages/ui/src/components/separator/index.ts
+++ b/packages/ui/src/components/separator/index.ts
@@ -1,2 +1,2 @@
-export { default as Separator } from './Separator.vue'
-export type { SeparatorProps } from './Separator.vue'
+export { default as Separator } from "./Separator.vue";
+export type { SeparatorProps } from "./Separator.vue";
diff --git a/packages/ui/src/components/sheet/index.ts b/packages/ui/src/components/sheet/index.ts
index a8c9060..ee501c2 100644
--- a/packages/ui/src/components/sheet/index.ts
+++ b/packages/ui/src/components/sheet/index.ts
@@ -1 +1 @@
-export { default as Sheet } from './Sheet.vue'
+export { default as Sheet } from "./Sheet.vue";
diff --git a/packages/ui/src/components/skeleton/index.ts b/packages/ui/src/components/skeleton/index.ts
index efbb63f..3d2158a 100644
--- a/packages/ui/src/components/skeleton/index.ts
+++ b/packages/ui/src/components/skeleton/index.ts
@@ -1,2 +1,2 @@
-export { default as Skeleton } from './Skeleton.vue'
-export type { SkeletonProps } from './Skeleton.vue'
+export { default as Skeleton } from "./Skeleton.vue";
+export type { SkeletonProps } from "./Skeleton.vue";
diff --git a/packages/ui/src/components/slider/index.ts b/packages/ui/src/components/slider/index.ts
index 1324775..f36a664 100644
--- a/packages/ui/src/components/slider/index.ts
+++ b/packages/ui/src/components/slider/index.ts
@@ -1,2 +1,2 @@
-export { default as Slider } from './Slider.vue'
-export type { SliderProps } from './Slider.vue'
+export { default as Slider } from "./Slider.vue";
+export type { SliderProps } from "./Slider.vue";
diff --git a/packages/ui/src/components/spinner/index.ts b/packages/ui/src/components/spinner/index.ts
index 596a614..28cbe29 100644
--- a/packages/ui/src/components/spinner/index.ts
+++ b/packages/ui/src/components/spinner/index.ts
@@ -1,2 +1,2 @@
-export { default as Spinner } from './Spinner.vue'
-export type { SpinnerProps } from './Spinner.vue'
+export { default as Spinner } from "./Spinner.vue";
+export type { SpinnerProps } from "./Spinner.vue";
diff --git a/packages/ui/src/components/stepper/index.ts b/packages/ui/src/components/stepper/index.ts
index e9bf5c5..3cf4417 100644
--- a/packages/ui/src/components/stepper/index.ts
+++ b/packages/ui/src/components/stepper/index.ts
@@ -1,2 +1,2 @@
-export { default as Stepper } from './Stepper.vue'
-export type { StepperProps, StepData } from './Stepper.vue'
+export { default as Stepper } from "./Stepper.vue";
+export type { StepperProps, StepData } from "./Stepper.vue";
diff --git a/packages/ui/src/components/steps/index.ts b/packages/ui/src/components/steps/index.ts
index e1db8ed..56bfc47 100644
--- a/packages/ui/src/components/steps/index.ts
+++ b/packages/ui/src/components/steps/index.ts
@@ -1,3 +1,3 @@
-export { default as Steps } from './Steps.vue'
-export { default as StepItem } from './StepItem.vue'
-export type { StepItemProps, StepsProps } from './types'
+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
index 1064753..3b89307 100644
--- a/packages/ui/src/components/steps/types.ts
+++ b/packages/ui/src/components/steps/types.ts
@@ -1,19 +1,19 @@
-import type { InjectionKey } from 'vue'
+import type { InjectionKey } from "vue";
 
 export interface StepsProps {
-  startIndex?: number
-  class?: string
+  startIndex?: number;
+  class?: string;
 }
 
 export interface StepItemProps {
-  title?: string
-  description?: string
-  step?: number | string
-  class?: string
+  title?: string;
+  description?: string;
+  step?: number | string;
+  class?: string;
 }
 
 export interface StepsContext {
-  registerStep: () => number
+  registerStep: () => number;
 }
 
-export const stepsInjectionKey: InjectionKey<StepsContext> = Symbol('re-steps')
+export const stepsInjectionKey: InjectionKey<StepsContext> = Symbol("re-steps");
diff --git a/packages/ui/src/components/switch/index.ts b/packages/ui/src/components/switch/index.ts
index c0e4da5..464e26b 100644
--- a/packages/ui/src/components/switch/index.ts
+++ b/packages/ui/src/components/switch/index.ts
@@ -1,2 +1,2 @@
-export { default as Switch } from './Switch.vue'
-export type { SwitchProps } from './Switch.vue'
+export { default as Switch } from "./Switch.vue";
+export type { SwitchProps } from "./Switch.vue";
diff --git a/packages/ui/src/components/table/index.ts b/packages/ui/src/components/table/index.ts
index 052485b..338903f 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 { DataTableColumn, DataTableSort } from './types'
+export { default as DataTable } 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
index ebe4ae6..626204b 100644
--- a/packages/ui/src/components/table/types.ts
+++ b/packages/ui/src/components/table/types.ts
@@ -1,14 +1,14 @@
 export interface DataTableColumn {
-  key: string
-  label: string
-  width?: string
-  align?: 'left' | 'center' | 'right'
-  slot?: boolean
-  sortable?: boolean
-  hideable?: boolean
+  key: string;
+  label: string;
+  width?: string;
+  align?: "left" | "center" | "right";
+  slot?: boolean;
+  sortable?: boolean;
+  hideable?: boolean;
 }
 
 export interface DataTableSort {
-  key: string
-  direction: 'asc' | 'desc'
+  key: string;
+  direction: "asc" | "desc";
 }
diff --git a/packages/ui/src/components/tabs/index.ts b/packages/ui/src/components/tabs/index.ts
index f4debe5..45621dc 100644
--- a/packages/ui/src/components/tabs/index.ts
+++ b/packages/ui/src/components/tabs/index.ts
@@ -1,3 +1,3 @@
-export { default as Tabs } from './Tabs.vue'
-export { default as TabsContent } from './TabsContent.vue'
-export type { TabsProps, TabItem } from './Tabs.vue'
+export { default as Tabs } from "./Tabs.vue";
+export { default as TabsContent } from "./TabsContent.vue";
+export type { TabsProps, TabItem } from "./Tabs.vue";
diff --git a/packages/ui/src/components/tag-input/TagInput.vue b/packages/ui/src/components/tag-input/TagInput.vue
index 0f4eedf..0700adf 100644
--- a/packages/ui/src/components/tag-input/TagInput.vue
+++ b/packages/ui/src/components/tag-input/TagInput.vue
@@ -163,7 +163,7 @@ function onInput(event: Event) {
   }
   const parts = value.split(pattern)
   const completed = parts.slice(0, -1)
-  draft.value = parts[parts.length - 1]
+  draft.value = parts[parts.length - 1] ?? ""
   target.value = draft.value
   commitMany(completed)
 }
diff --git a/packages/ui/src/components/tag-input/index.ts b/packages/ui/src/components/tag-input/index.ts
index b2cb9f2..43bd398 100644
--- a/packages/ui/src/components/tag-input/index.ts
+++ b/packages/ui/src/components/tag-input/index.ts
@@ -1,2 +1,2 @@
-export { default as TagInput } from './TagInput.vue'
-export type { TagInputProps } from './TagInput.vue'
+export { default as TagInput } from "./TagInput.vue";
+export type { TagInputProps } from "./TagInput.vue";
diff --git a/packages/ui/src/components/textarea/index.ts b/packages/ui/src/components/textarea/index.ts
index 5ba5914..c7ae5e9 100644
--- a/packages/ui/src/components/textarea/index.ts
+++ b/packages/ui/src/components/textarea/index.ts
@@ -1,2 +1,2 @@
-export { default as Textarea } from './Textarea.vue'
-export type { TextareaProps } from './Textarea.vue'
+export { default as Textarea } from "./Textarea.vue";
+export type { TextareaProps } from "./Textarea.vue";
diff --git a/packages/ui/src/components/timeline/index.ts b/packages/ui/src/components/timeline/index.ts
index a426a17..a662b6b 100644
--- a/packages/ui/src/components/timeline/index.ts
+++ b/packages/ui/src/components/timeline/index.ts
@@ -1,2 +1,2 @@
-export { default as Timeline } from './Timeline.vue'
-export type { TimelineItem, TimelineStatus } from './types'
+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
index ac7941f..ce078d9 100644
--- a/packages/ui/src/components/timeline/types.ts
+++ b/packages/ui/src/components/timeline/types.ts
@@ -1,12 +1,12 @@
-export type TimelineStatus = 'default' | 'info' | 'success' | 'warning' | 'error'
+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
+  id: string;
+  title: string;
+  description?: string;
+  timestamp?: string;
+  status?: TimelineStatus;
+  actor?: string;
+  avatar?: string;
+  metadata?: string;
 }
diff --git a/packages/ui/src/components/toast/index.ts b/packages/ui/src/components/toast/index.ts
index 165bf3f..c3e50c8 100644
--- a/packages/ui/src/components/toast/index.ts
+++ b/packages/ui/src/components/toast/index.ts
@@ -1,2 +1,2 @@
-export { default as ToastProvider } from './ToastProvider.vue'
-export * from './useToast'
+export { default as ToastProvider } from "./ToastProvider.vue";
+export * from "./useToast";
diff --git a/packages/ui/src/components/toast/useToast.ts b/packages/ui/src/components/toast/useToast.ts
index 966f0ee..5ff89c7 100644
--- a/packages/ui/src/components/toast/useToast.ts
+++ b/packages/ui/src/components/toast/useToast.ts
@@ -1,44 +1,44 @@
-import { ref } from 'vue'
+import { ref } from "vue";
 
 export interface ToastOptions {
-  id?: string
-  title?: string
-  description?: string
-  variant?: 'info' | 'success' | 'warning' | 'destructive'
-  duration?: number
+  id?: string;
+  title?: string;
+  description?: string;
+  variant?: "info" | "success" | "warning" | "destructive";
+  duration?: number;
 }
 
-const toasts = ref<ToastOptions[]>([])
+const toasts = ref<ToastOptions[]>([]);
 
 export function useToast() {
   function toast(options: ToastOptions) {
-    const id = options.id || Math.random().toString(36).substring(2, 9)
-    const duration = options.duration ?? 4000
+    const id = options.id || Math.random().toString(36).substring(2, 9);
+    const duration = options.duration ?? 4000;
 
     const newToast: ToastOptions = {
       ...options,
       id,
-      variant: options.variant || 'info'
-    }
+      variant: options.variant || "info",
+    };
 
-    toasts.value.push(newToast)
+    toasts.value.push(newToast);
 
     if (duration > 0) {
       setTimeout(() => {
-        dismiss(id)
-      }, duration)
+        dismiss(id);
+      }, duration);
     }
 
-    return id
+    return id;
   }
 
   function dismiss(id: string) {
-    toasts.value = toasts.value.filter(t => t.id !== id)
+    toasts.value = toasts.value.filter((t) => t.id !== id);
   }
 
   return {
     toasts,
     toast,
-    dismiss
-  }
+    dismiss,
+  };
 }
diff --git a/packages/ui/src/components/toc/index.ts b/packages/ui/src/components/toc/index.ts
index 7ed8f19..408d941 100644
--- a/packages/ui/src/components/toc/index.ts
+++ b/packages/ui/src/components/toc/index.ts
@@ -1,2 +1,2 @@
-export { default as Toc } from './Toc.vue'
-export type { TocItem, TocProps } from './types'
+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
index c99dd84..3354e09 100644
--- a/packages/ui/src/components/toc/types.ts
+++ b/packages/ui/src/components/toc/types.ts
@@ -1,16 +1,16 @@
 export interface TocItem {
-  id: string
-  title: string
-  level?: number
-  children?: 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
+  items?: TocItem[];
+  selector?: string;
+  container?: string;
+  scrollSpy?: boolean;
+  title?: string;
+  offset?: number;
+  class?: string;
 }
diff --git a/packages/ui/src/components/toggle-group/index.ts b/packages/ui/src/components/toggle-group/index.ts
index 535db28..97e4438 100644
--- a/packages/ui/src/components/toggle-group/index.ts
+++ b/packages/ui/src/components/toggle-group/index.ts
@@ -1,2 +1,2 @@
-export { default as ToggleGroup } from './ToggleGroup.vue'
-export type { ToggleGroupProps, ToggleGroupOption } from './ToggleGroup.vue'
+export { default as ToggleGroup } from "./ToggleGroup.vue";
+export type { ToggleGroupProps, ToggleGroupOption } from "./ToggleGroup.vue";
diff --git a/packages/ui/src/components/toggle/index.ts b/packages/ui/src/components/toggle/index.ts
index 3d329ad..c7274c5 100644
--- a/packages/ui/src/components/toggle/index.ts
+++ b/packages/ui/src/components/toggle/index.ts
@@ -1,2 +1,2 @@
-export { default as Toggle } from './Toggle.vue'
-export type { ToggleProps } from './Toggle.vue'
+export { default as Toggle } from "./Toggle.vue";
+export type { ToggleProps } from "./Toggle.vue";
diff --git a/packages/ui/src/components/toolbar/index.ts b/packages/ui/src/components/toolbar/index.ts
index 5f00e25..388a291 100644
--- a/packages/ui/src/components/toolbar/index.ts
+++ b/packages/ui/src/components/toolbar/index.ts
@@ -1,5 +1,5 @@
-export { default as Toolbar } from './Toolbar.vue'
-export type { ToolbarProps } from './Toolbar.vue'
-export { default as ToolbarButton } from './ToolbarButton.vue'
-export type { ToolbarButtonProps } from './ToolbarButton.vue'
-export { default as ToolbarSeparator } from './ToolbarSeparator.vue'
+export { default as Toolbar } from "./Toolbar.vue";
+export type { ToolbarProps } from "./Toolbar.vue";
+export { default as ToolbarButton } from "./ToolbarButton.vue";
+export type { ToolbarButtonProps } from "./ToolbarButton.vue";
+export { default as ToolbarSeparator } from "./ToolbarSeparator.vue";
diff --git a/packages/ui/src/components/tooltip/index.ts b/packages/ui/src/components/tooltip/index.ts
index 8ff1583..8003675 100644
--- a/packages/ui/src/components/tooltip/index.ts
+++ b/packages/ui/src/components/tooltip/index.ts
@@ -1,2 +1,2 @@
-export { default as Tooltip } from './Tooltip.vue'
-export type { TooltipProps } from './Tooltip.vue'
+export { default as Tooltip } from "./Tooltip.vue";
+export type { TooltipProps } from "./Tooltip.vue";
diff --git a/packages/ui/src/components/tree-view/index.ts b/packages/ui/src/components/tree-view/index.ts
index 3d5437b..5174407 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 { TreeDropEvent, TreeHighlightVariant, TreeNode } from './types'
+export { default as TreeView } from "./TreeView.vue";
+export type { TreeDropEvent, 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 4e5c99f..b9d7faa 100644
--- a/packages/ui/src/components/tree-view/types.ts
+++ b/packages/ui/src/components/tree-view/types.ts
@@ -1,20 +1,20 @@
-import type { IconSource } from '../icon'
+import type { IconSource } from "../icon";
 
 export interface TreeNode {
-  id: string
-  label: string
-  disabled?: boolean
-  children?: TreeNode[]
+  id: string;
+  label: string;
+  disabled?: boolean;
+  children?: TreeNode[];
   /** True when node has dynamic children that haven't been fetched yet. */
-  isLeaf?: boolean
+  isLeaf?: boolean;
   /** Optional icon component, icon name or SVG source rendered before node label. */
-  icon?: IconSource
+  icon?: IconSource;
 }
 
 export interface TreeDropEvent {
-  draggedNode: TreeNode
-  targetNode: TreeNode
-  position: 'before' | 'inside' | 'after'
+  draggedNode: TreeNode;
+  targetNode: TreeNode;
+  position: "before" | "inside" | "after";
 }
 
-export type TreeHighlightVariant = 'subtle' | 'solid' | 'bar'
+export type TreeHighlightVariant = "subtle" | "solid" | "bar";
diff --git a/packages/ui/src/components/visually-hidden/index.ts b/packages/ui/src/components/visually-hidden/index.ts
index d2dd955..96e41c6 100644
--- a/packages/ui/src/components/visually-hidden/index.ts
+++ b/packages/ui/src/components/visually-hidden/index.ts
@@ -1,2 +1,2 @@
-export { default as VisuallyHidden } from './VisuallyHidden.vue'
-export type { VisuallyHiddenProps } from './VisuallyHidden.vue'
+export { default as VisuallyHidden } from "./VisuallyHidden.vue";
+export type { VisuallyHiddenProps } from "./VisuallyHidden.vue";
diff --git a/packages/ui/src/composables/useTheme.ts b/packages/ui/src/composables/useTheme.ts
index 6ee32f3..959df09 100644
--- a/packages/ui/src/composables/useTheme.ts
+++ b/packages/ui/src/composables/useTheme.ts
@@ -1,114 +1,130 @@
-import { computed, onMounted, ref } 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 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
+  mode: ThemeMode;
+  palette: ThemePalette;
+  density: ThemeDensity;
+  radius: ThemeRadius;
+  shadow: ThemeShadow;
 }
 
 export interface UseThemeOptions {
-  storageKey?: string
-  defaultMode?: ThemeMode
-  defaultPalette?: ThemePalette
-  defaultDensity?: ThemeDensity
-  defaultRadius?: ThemeRadius
-  defaultShadow?: ThemeShadow
+  storageKey?: string;
+  defaultMode?: ThemeMode;
+  defaultPalette?: ThemePalette;
+  defaultDensity?: ThemeDensity;
+  defaultRadius?: ThemeRadius;
+  defaultShadow?: ThemeShadow;
 }
 
 const defaults: ThemePreferences = {
-  mode: 'system',
-  palette: 'recloud',
-  density: 'comfortable',
-  radius: 'md',
-  shadow: 'sm'
-}
+  mode: "system",
+  palette: "recloud",
+  density: "comfortable",
+  radius: "md",
+  shadow: "sm",
+};
 
-const preferences = ref<ThemePreferences>({ ...defaults })
-const systemIsDark = ref(false)
-let initialized = false
-let mediaQuery: MediaQueryList | undefined
-let storageKey = 'recloud-theme'
+const preferences = ref<ThemePreferences>({ ...defaults });
+const systemIsDark = ref(false);
+let initialized = false;
+let mediaQuery: MediaQueryList | undefined;
+let storageKey = "recloud-theme";
 
-function normalizeMode(mode: ThemeMode): 'light' | 'dark' | 'system' {
-  return mode === 'auto' ? 'system' : mode
+function normalizeMode(mode: ThemeMode): "light" | "dark" | "system" {
+  return mode === "auto" ? "system" : mode;
 }
 
 function resolveTheme(mode = preferences.value.mode): ResolvedThemeMode {
-  return normalizeMode(mode) === 'dark' || (normalizeMode(mode) === 'system' && systemIsDark.value) ? 'dark' : 'light'
+  return normalizeMode(mode) === "dark" || (normalizeMode(mode) === "system" && systemIsDark.value)
+    ? "dark"
+    : "light";
 }
 
 function applyTheme() {
-  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
+  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;
 }
 
 function persist() {
-  if (typeof window === 'undefined') return
-  window.localStorage.setItem(storageKey, JSON.stringify(preferences.value))
+  if (typeof window === "undefined") return;
+  window.localStorage.setItem(storageKey, JSON.stringify(preferences.value));
 }
 
 function hydrate(options: UseThemeOptions) {
-  if (initialized || typeof window === 'undefined') return
-  initialized = true
-  storageKey = options.storageKey ?? storageKey
+  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
-  }
+    shadow: options.defaultShadow ?? defaults.shadow,
+  };
   try {
-    const saved = JSON.parse(window.localStorage.getItem(storageKey) ?? '{}') as Partial<ThemePreferences>
-    preferences.value = { ...fallback, ...saved }
+    const saved = JSON.parse(
+      window.localStorage.getItem(storageKey) ?? "{}",
+    ) as Partial<ThemePreferences>;
+    preferences.value = { ...fallback, ...saved };
   } catch {
-    preferences.value = fallback
+    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()
+  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(options: UseThemeOptions = {}) {
-  onMounted(() => hydrate(options))
+  onMounted(() => hydrate(options));
 
-  const resolvedMode = computed<ResolvedThemeMode>(() => resolveTheme())
-  const isDark = computed(() => resolvedMode.value === 'dark')
+  const resolvedMode = computed<ResolvedThemeMode>(() => resolveTheme());
+  const isDark = computed(() => resolvedMode.value === "dark");
 
   function update(next: Partial<ThemePreferences>) {
-    preferences.value = { ...preferences.value, ...next }
-    persist()
-    applyTheme()
+    preferences.value = { ...preferences.value, ...next };
+    persist();
+    applyTheme();
   }
 
-  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') }
+  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: computed(() => preferences.value.mode),
@@ -125,6 +141,6 @@ export function useTheme(options: UseThemeOptions = {}) {
     setRadius,
     setShadow,
     update,
-    toggle
-  }
+    toggle,
+  };
 }
diff --git a/packages/ui/src/env.d.ts b/packages/ui/src/env.d.ts
index 5006088..92c5507 100644
--- a/packages/ui/src/env.d.ts
+++ b/packages/ui/src/env.d.ts
@@ -1,5 +1,5 @@
-declare module '*.vue' {
-  import type { DefineComponent } from 'vue'
-  const component: DefineComponent<Record<string, never>, Record<string, never>, unknown>
-  export default component
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<Record<string, never>, Record<string, never>, unknown>;
+  export default component;
 }
diff --git a/packages/ui/src/icons/index.ts b/packages/ui/src/icons/index.ts
index de82c34..edf516a 100644
--- a/packages/ui/src/icons/index.ts
+++ b/packages/ui/src/icons/index.ts
@@ -1,5 +1,5 @@
-export { default as BrandLogo } from './BrandLogo.vue'
-export { default as BrandWordmark } from './BrandWordmark.vue'
+export { default as BrandLogo } from "./BrandLogo.vue";
+export { default as BrandWordmark } from "./BrandWordmark.vue";
 
 // Re-export Lucide Icons for convenience
-export * from 'lucide-vue-next'
+export * from "lucide-vue-next";
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 0076b71..89a5f66 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -2,6 +2,9 @@
 export * from "./components/button";
 export * from "./components/badge";
 export * from "./components/card";
+export * from "./components/component-example";
+export * from "./components/api-table";
+export * from "./components/page-header";
 export * from "./components/banner";
 export * from "./components/input";
 export * from "./components/tag-input";
diff --git a/packages/ui/src/locale/index.ts b/packages/ui/src/locale/index.ts
index d16f14a..eb53694 100644
--- a/packages/ui/src/locale/index.ts
+++ b/packages/ui/src/locale/index.ts
@@ -1,94 +1,97 @@
-import { computed, inject, provide, type InjectionKey, type Ref, shallowRef } from 'vue'
-import { enUS, zhCN, type DeepPartial, type LocaleMessages } from './messages'
+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
+  locale: Ref<string>;
+  messages: Ref<LocaleMessages>;
+  setLocale: (name: string, customMessages?: DeepPartial<LocaleMessages>) => void;
 }
 
-export const LOCALE_INJECTION_KEY: InjectionKey<LocaleContext> = Symbol('recloud:locale')
+export const LOCALE_INJECTION_KEY: InjectionKey<LocaleContext> = Symbol("recloud:locale");
 
 const builtInLocales: Record<string, LocaleMessages> = {
-  'zh-CN': zhCN,
+  "zh-CN": zhCN,
   zh: zhCN,
-  'en-US': enUS,
-  en: enUS
-}
+  "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 }
+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]
+    const sourceVal = source[key];
+    const targetVal = output[key];
     if (
       sourceVal !== null &&
       sourceVal !== undefined &&
-      typeof sourceVal === 'object' &&
+      typeof sourceVal === "object" &&
       !Array.isArray(sourceVal) &&
       targetVal !== null &&
       targetVal !== undefined &&
-      typeof targetVal === 'object' &&
+      typeof targetVal === "object" &&
       !Array.isArray(targetVal)
     ) {
       output[key] = mergeDeep(
         targetVal as Record<string, unknown>,
-        sourceVal as Record<string, unknown>
-      )
+        sourceVal as Record<string, unknown>,
+      );
     } else if (sourceVal !== undefined) {
-      output[key] = sourceVal
+      output[key] = sourceVal;
     }
   }
-  return output as T
+  return output as T;
 }
 
 export function provideLocale(
-  initialLocale: string = 'zh-CN',
-  customMessages?: DeepPartial<LocaleMessages>
+  initialLocale: string = "zh-CN",
+  customMessages?: DeepPartial<LocaleMessages>,
 ): LocaleContext {
-  const currentLocale = shallowRef(initialLocale)
-  const base = builtInLocales[initialLocale] ?? zhCN
+  const currentLocale = shallowRef(initialLocale);
+  const base = builtInLocales[initialLocale] ?? zhCN;
   const currentMessages = shallowRef<LocaleMessages>(
-    customMessages ? mergeDeep({ ...base }, customMessages as Record<string, unknown>) : base
-  )
+    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
+      currentLocale.value = name;
+      const fallback = builtInLocales[name] ?? zhCN;
       currentMessages.value = override
         ? mergeDeep({ ...fallback }, override as Record<string, unknown>)
-        : fallback
-    }
-  }
+        : fallback;
+    },
+  };
 
-  provide(LOCALE_INJECTION_KEY, context)
-  return context
+  provide(LOCALE_INJECTION_KEY, context);
+  return context;
 }
 
 export function useLocale() {
-  const injected = inject(LOCALE_INJECTION_KEY, null)
-  if (injected) return injected
+  const injected = inject(LOCALE_INJECTION_KEY, null);
+  if (injected) return injected;
 
-  const defaultLocale = shallowRef('zh-CN')
-  const defaultMessages = shallowRef(zhCN)
+  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
+      defaultLocale.value = name;
+      const fallback = builtInLocales[name] ?? zhCN;
       defaultMessages.value = override
         ? mergeDeep({ ...fallback }, override as Record<string, unknown>)
-        : fallback
-    }
-  }
+        : fallback;
+    },
+  };
 }
 
 export function useComponentLocale<K extends keyof LocaleMessages>(componentKey: K) {
-  const { messages } = useLocale()
-  return computed(() => messages.value[componentKey])
+  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
index 5545c04..d64041c 100644
--- a/packages/ui/src/locale/locale.test.ts
+++ b/packages/ui/src/locale/locale.test.ts
@@ -1,47 +1,47 @@
-import { describe, expect, it } from 'vitest'
-import { useLocale } from './index'
-import { zhCN, enUS } from './messages'
+import { describe, expect, it } from "vitest";
+import { 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('没有找到匹配的命令。')
-  })
+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')
+  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('上一页')
-  })
+    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', {
+  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')
-  })
+        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')
+  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')
-  })
-})
+    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
index d374d90..8a8e3d0 100644
--- a/packages/ui/src/locale/messages.ts
+++ b/packages/ui/src/locale/messages.ts
@@ -1,110 +1,110 @@
 export interface LocaleMessages {
   common: {
-    close: string
-    cancel: string
-    confirm: string
-    retry: string
-    remove: string
-    search: string
-    loading: string
-    noData: string
-    clear: string
-    save: string
-    edit: string
-    copy: string
-    copied: string
-    expandCode: string
-    collapseCode: string
-  }
+    close: string;
+    cancel: string;
+    confirm: string;
+    retry: string;
+    remove: string;
+    search: string;
+    loading: string;
+    noData: string;
+    clear: string;
+    save: string;
+    edit: string;
+    copy: string;
+    copied: string;
+    expandCode: string;
+    collapseCode: string;
+  };
   pagination: {
-    prev: string
-    next: string
-    pageSummary: (page: number, totalPages: number) => string
-    totalSummary: (page: number, totalPages: number, total: number) => string
-    ariaLabel: string
-  }
+    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
-  }
+    defaultTitle: string;
+    loadFailed: string;
+  };
   command: {
-    searchPlaceholder: string
-    emptyText: string
-    label: string
-  }
+    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
-    cancelAria: (name: string) => string
-    retryAria: (name: string) => string
-    removeAria: (name: string) => string
-  }
+    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;
+    cancelAria: (name: string) => string;
+    retryAria: (name: string) => string;
+    removeAria: (name: string) => string;
+  };
   tree: {
-    selectedBadge: string
-    collapseNode: (label: string) => string
-    expandNode: (label: string) => string
-    selectNode: (label: string) => string
-    label: string
-  }
+    selectedBadge: string;
+    collapseNode: (label: string) => string;
+    expandNode: (label: string) => string;
+    selectNode: (label: string) => string;
+    label: string;
+  };
   table: {
-    selectAllAria: string
-    selectRowAria: (index: number) => string
-  }
+    selectAllAria: string;
+    selectRowAria: (index: number) => string;
+  };
   select: {
-    placeholder: string
-  }
+    placeholder: string;
+  };
   combobox: {
-    placeholder: string
-    emptyText: string
-    clearAria: string
-  }
+    placeholder: string;
+    emptyText: string;
+    clearAria: string;
+  };
   multiSelect: {
-    placeholder: string
-    emptyText: string
-    clearAria: string
-    removeAria: (label: string) => string
-  }
+    placeholder: string;
+    emptyText: string;
+    clearAria: string;
+    removeAria: (label: string) => string;
+  };
   datePicker: {
-    placeholder: string
-    rangePlaceholder: string
-    prevMonthAria: string
-    nextMonthAria: string
-    pendingRangeEnd: string
-    weekdays: string[]
-  }
+    placeholder: string;
+    rangePlaceholder: string;
+    prevMonthAria: string;
+    nextMonthAria: string;
+    pendingRangeEnd: string;
+    weekdays: string[];
+  };
   appShell: {
-    sidebarLabel: string
-    resizeHandleAria: string
-  }
+    sidebarLabel: string;
+    resizeHandleAria: string;
+  };
   alertDialog: {
-    confirm: string
-    cancel: string
-  }
+    confirm: string;
+    cancel: string;
+  };
   codeBlock: {
-    region: string
-  }
+    region: string;
+  };
   docs: {
-    toc: string
-    prev: string
-    next: string
-    copyLink: string
-    copiedLink: string
-    searchPlaceholder: string
-  }
+    toc: string;
+    prev: string;
+    next: string;
+    copyLink: string;
+    copiedLink: string;
+    searchPlaceholder: string;
+  };
 }
 
 export type DeepPartial<T> = {
@@ -112,223 +112,223 @@ export type DeepPartial<T> = {
     ? T[P]
     : T[P] extends object
       ? DeepPartial<T[P]>
-      : T[P]
-}
+      : T[P];
+};
 
 export const zhCN: LocaleMessages = {
   common: {
-    close: '关闭',
-    cancel: '取消',
-    confirm: '确认',
-    retry: '重试',
-    remove: '移除',
-    search: '搜索',
-    loading: '加载中',
-    noData: '暂无数据',
-    clear: '清除',
-    save: '保存',
-    edit: '编辑',
-    copy: '复制',
-    copied: '已复制',
-    expandCode: '展开代码',
-    collapseCode: '收起代码'
+    close: "关闭",
+    cancel: "取消",
+    confirm: "确认",
+    retry: "重试",
+    remove: "移除",
+    search: "搜索",
+    loading: "加载中",
+    noData: "暂无数据",
+    clear: "清除",
+    save: "保存",
+    edit: "编辑",
+    copy: "复制",
+    copied: "已复制",
+    expandCode: "展开代码",
+    collapseCode: "收起代码",
   },
   pagination: {
-    prev: '上一页',
-    next: '下一页',
+    prev: "上一页",
+    next: "下一页",
     pageSummary: (page, totalPages) => `第 ${page} / ${totalPages} 页`,
     totalSummary: (page, totalPages, total) => `第 ${page} / ${totalPages} 页，共 ${total} 条`,
-    ariaLabel: '分页导航'
+    ariaLabel: "分页导航",
   },
   empty: {
-    defaultTitle: '暂无数据',
-    loadFailed: '数据加载失败'
+    defaultTitle: "暂无数据",
+    loadFailed: "数据加载失败",
   },
   command: {
-    searchPlaceholder: '搜索命令…',
-    emptyText: '没有找到匹配的命令。',
-    label: '命令面板'
+    searchPlaceholder: "搜索命令…",
+    emptyText: "没有找到匹配的命令。",
+    label: "命令面板",
   },
   fileUpload: {
-    label: '上传文件',
-    dropzonePrefix: '选择文件',
-    dropzoneSuffix: '或拖放到这里',
-    anyFiles: '支持任意文件类型',
+    label: "上传文件",
+    dropzonePrefix: "选择文件",
+    dropzoneSuffix: "或拖放到这里",
+    anyFiles: "支持任意文件类型",
     acceptRule: (accept) => `支持 ${accept}`,
     maxSizeRule: (size) => `单个文件最大 ${size}`,
     fileLimitReject: (max) => `最多上传 ${max} 个文件`,
-    typeReject: '文件类型不受支持',
+    typeReject: "文件类型不受支持",
     sizeReject: (size) => `文件不能超过 ${size}`,
-    failedDefault: '上传失败，请重试',
-    cancelled: '上传已取消',
-    statusPending: '等待上传',
-    statusUploading: '上传中',
-    statusSuccess: '已完成',
-    statusError: '失败',
-    statusCancelled: '已取消',
+    failedDefault: "上传失败，请重试",
+    cancelled: "上传已取消",
+    statusPending: "等待上传",
+    statusUploading: "上传中",
+    statusSuccess: "已完成",
+    statusError: "失败",
+    statusCancelled: "已取消",
     cancelAria: (name) => `取消上传 ${name}`,
     retryAria: (name) => `重试上传 ${name}`,
-    removeAria: (name) => `移除 ${name}`
+    removeAria: (name) => `移除 ${name}`,
   },
   tree: {
-    selectedBadge: '已选',
+    selectedBadge: "已选",
     collapseNode: (label) => `收起 ${label}`,
     expandNode: (label) => `展开 ${label}`,
     selectNode: (label) => `选择 ${label}`,
-    label: '树形目录'
+    label: "树形目录",
   },
   table: {
-    selectAllAria: '选择当前页所有行',
-    selectRowAria: (index) => `选择第 ${index} 行`
+    selectAllAria: "选择当前页所有行",
+    selectRowAria: (index) => `选择第 ${index} 行`,
   },
   select: {
-    placeholder: '请选择...'
+    placeholder: "请选择...",
   },
   combobox: {
-    placeholder: '搜索或选择...',
-    emptyText: '无匹配项',
-    clearAria: '清除'
+    placeholder: "搜索或选择...",
+    emptyText: "无匹配项",
+    clearAria: "清除",
   },
   multiSelect: {
-    placeholder: '搜索并选择...',
-    emptyText: '无匹配项',
-    clearAria: '清除所有选择',
-    removeAria: (label) => `移除 ${label}`
+    placeholder: "搜索并选择...",
+    emptyText: "无匹配项",
+    clearAria: "清除所有选择",
+    removeAria: (label) => `移除 ${label}`,
   },
   datePicker: {
-    placeholder: '选择日期',
-    rangePlaceholder: '选择日期范围',
-    prevMonthAria: '上个月',
-    nextMonthAria: '下个月',
-    pendingRangeEnd: '已选择开始日期，请选择结束日期。',
-    weekdays: ['一', '二', '三', '四', '五', '六', '日']
+    placeholder: "选择日期",
+    rangePlaceholder: "选择日期范围",
+    prevMonthAria: "上个月",
+    nextMonthAria: "下个月",
+    pendingRangeEnd: "已选择开始日期，请选择结束日期。",
+    weekdays: ["一", "二", "三", "四", "五", "六", "日"],
   },
   appShell: {
-    sidebarLabel: '侧边导航',
-    resizeHandleAria: '调整面板大小'
+    sidebarLabel: "侧边导航",
+    resizeHandleAria: "调整面板大小",
   },
   alertDialog: {
-    confirm: '确认',
-    cancel: '取消'
+    confirm: "确认",
+    cancel: "取消",
   },
   codeBlock: {
-    region: '代码区域'
+    region: "代码区域",
   },
   docs: {
-    toc: '本页目录',
-    prev: '上一篇',
-    next: '下一篇',
-    copyLink: '复制链接',
-    copiedLink: '已复制链接',
-    searchPlaceholder: '搜索文档...'
-  }
-}
+    toc: "本页目录",
+    prev: "上一篇",
+    next: "下一篇",
+    copyLink: "复制链接",
+    copiedLink: "已复制链接",
+    searchPlaceholder: "搜索文档...",
+  },
+};
 
 export const enUS: LocaleMessages = {
   common: {
-    close: 'Close',
-    cancel: 'Cancel',
-    confirm: 'Confirm',
-    retry: 'Retry',
-    remove: 'Remove',
-    search: 'Search',
-    loading: 'Loading',
-    noData: 'No data',
-    clear: 'Clear',
-    save: 'Save',
-    edit: 'Edit',
-    copy: 'Copy',
-    copied: 'Copied',
-    expandCode: 'Expand code',
-    collapseCode: 'Collapse code'
+    close: "Close",
+    cancel: "Cancel",
+    confirm: "Confirm",
+    retry: "Retry",
+    remove: "Remove",
+    search: "Search",
+    loading: "Loading",
+    noData: "No data",
+    clear: "Clear",
+    save: "Save",
+    edit: "Edit",
+    copy: "Copy",
+    copied: "Copied",
+    expandCode: "Expand code",
+    collapseCode: "Collapse code",
   },
   pagination: {
-    prev: 'Previous',
-    next: 'Next',
+    prev: "Previous",
+    next: "Next",
     pageSummary: (page, totalPages) => `Page ${page} of ${totalPages}`,
     totalSummary: (page, totalPages, total) => `Page ${page} of ${totalPages}, ${total} total`,
-    ariaLabel: 'Pagination'
+    ariaLabel: "Pagination",
   },
   empty: {
-    defaultTitle: 'No data available',
-    loadFailed: 'Failed to load data'
+    defaultTitle: "No data available",
+    loadFailed: "Failed to load data",
   },
   command: {
-    searchPlaceholder: 'Search commands…',
-    emptyText: 'No matching commands found.',
-    label: 'Command palette'
+    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',
+    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',
+    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',
+    failedDefault: "Upload failed, please retry",
+    cancelled: "Upload cancelled",
+    statusPending: "Pending",
+    statusUploading: "Uploading",
+    statusSuccess: "Completed",
+    statusError: "Failed",
+    statusCancelled: "Cancelled",
     cancelAria: (name) => `Cancel upload for ${name}`,
     retryAria: (name) => `Retry upload for ${name}`,
-    removeAria: (name) => `Remove ${name}`
+    removeAria: (name) => `Remove ${name}`,
   },
   tree: {
-    selectedBadge: 'Selected',
+    selectedBadge: "Selected",
     collapseNode: (label) => `Collapse ${label}`,
     expandNode: (label) => `Expand ${label}`,
     selectNode: (label) => `Select ${label}`,
-    label: 'Tree View'
+    label: "Tree View",
   },
   table: {
-    selectAllAria: 'Select all rows on current page',
-    selectRowAria: (index) => `Select row ${index}`
+    selectAllAria: "Select all rows on current page",
+    selectRowAria: (index) => `Select row ${index}`,
   },
   select: {
-    placeholder: 'Please select...'
+    placeholder: "Please select...",
   },
   combobox: {
-    placeholder: 'Search or select...',
-    emptyText: 'No matching results',
-    clearAria: 'Clear'
+    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}`
+    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']
+    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'
+    sidebarLabel: "Sidebar navigation",
+    resizeHandleAria: "Resize panel",
   },
   alertDialog: {
-    confirm: 'Confirm',
-    cancel: 'Cancel'
+    confirm: "Confirm",
+    cancel: "Cancel",
   },
   codeBlock: {
-    region: 'Code region'
+    region: "Code region",
   },
   docs: {
-    toc: 'On this page',
-    prev: 'Previous',
-    next: 'Next',
-    copyLink: 'Copy link',
-    copiedLink: 'Link copied',
-    searchPlaceholder: 'Search documentation...'
-  }
-}
+    toc: "On this page",
+    prev: "Previous",
+    next: "Next",
+    copyLink: "Copy link",
+    copiedLink: "Link copied",
+    searchPlaceholder: "Search documentation...",
+  },
+};
diff --git a/packages/ui/src/markdown/compile.ts b/packages/ui/src/markdown/compile.ts
index f141581..7da39ec 100644
--- a/packages/ui/src/markdown/compile.ts
+++ b/packages/ui/src/markdown/compile.ts
@@ -123,7 +123,9 @@ const parseCodeMeta = (
     for (const part of parts) {
       const trimmed = part.trim();
       if (trimmed.includes("-")) {
-        const [start, end] = trimmed.split("-").map((v) => Number.parseInt(v, 10));
+        const [start = Number.NaN, end = Number.NaN] = trimmed
+          .split("-")
+          .map((v) => Number.parseInt(v, 10));
         if (!Number.isNaN(start) && !Number.isNaN(end)) {
           for (let i = Math.min(start, end); i <= Math.max(start, end); i += 1) {
             lines.add(i);
diff --git a/packages/ui/src/nuxt/index.ts b/packages/ui/src/nuxt/index.ts
index cc1986a..6b8cb98 100644
--- a/packages/ui/src/nuxt/index.ts
+++ b/packages/ui/src/nuxt/index.ts
@@ -1,31 +1,37 @@
-import { existsSync } from 'node:fs'
-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'
+import { existsSync } from "node:fs";
+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'
+export * from "./types";
 
 const module: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({
-    meta: {
-      name: '@recloudstudio/ui',
-      configKey: 'recloudUI',
-      compatibility: {
-        nuxt: '^4.0.0'
-      }
+  meta: {
+    name: "@recloudstudio/ui",
+    configKey: "recloudUI",
+    compatibility: {
+      nuxt: "^4.0.0",
     },
-    defaults: {
-      prefix: 'Re',
-      injectTheme: true,
-      themeStorageKey: 'recloud-theme',
-      injectThemeScript: true
-    },
-    setup(options, nuxt) {
-      const resolver = createResolver(import.meta.url)
+  },
+  defaults: {
+    prefix: "Re",
+    injectTheme: true,
+    themeStorageKey: "recloud-theme",
+    injectThemeScript: true,
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
 
-      addTypeTemplate({
-        filename: 'types/recloud-ui.d.ts',
-        getContents: () => `declare module 'nuxt/schema' {
+    addTypeTemplate({
+      filename: "types/recloud-ui.d.ts",
+      getContents: () => `declare module 'nuxt/schema' {
   interface NuxtConfig {
     recloudUI?: import('@recloudstudio/ui/nuxt').ModuleOptions
   }
@@ -33,36 +39,37 @@ const module: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({
     recloudUI?: import('@recloudstudio/ui/nuxt').ModuleOptions
   }
 }
-export {}`
-      })
+export {}`,
+    });
 
-      if (options.injectTheme) {
-        nuxt.options.css = nuxt.options.css || []
-        nuxt.options.css.push(resolver.resolve('../style.css'))
-      }
+    if (options.injectTheme) {
+      nuxt.options.css = nuxt.options.css || [];
+      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'
-        })
-      }
+    if (options.injectThemeScript) {
+      nuxt.options.app.head.script ||= [];
+      nuxt.options.app.head.script.unshift({
+        key: "recloud-theme-init",
+        innerHTML: createThemeInitScript(options.themeStorageKey),
+        tagPosition: "head",
+      });
+    }
 
-      // 从源码加载时（monorepo dev）入口是 ../index.ts；发布包 dist 中为 ../index.js。
-      const libraryEntry = existsSync(resolver.resolve('../index.ts')) ? '../index.ts' : '../index.js'
-      addComponentExports({
-        filePath: resolver.resolve(libraryEntry),
-        prefix: options.prefix,
-      })
+    // 从源码加载时（monorepo dev）入口是 ../index.ts；发布包 dist 中为 ../index.js。
+    const libraryEntry = existsSync(resolver.resolve("../index.ts"))
+      ? "../index.ts"
+      : "../index.js";
+    addComponentExports({
+      filePath: resolver.resolve(libraryEntry),
+      prefix: options.prefix,
+    });
 
-      addImportsSources({
-        from: '@recloudstudio/ui',
-        imports: ['useTheme', 'useToast']
-      })
-    }
-  }
-)
+    addImportsSources({
+      from: "@recloudstudio/ui",
+      imports: ["useTheme", "useToast"],
+    });
+  },
+});
 
-export default module
+export default module;
diff --git a/packages/ui/src/nuxt/types.ts b/packages/ui/src/nuxt/types.ts
index d633900..859e463 100644
--- a/packages/ui/src/nuxt/types.ts
+++ b/packages/ui/src/nuxt/types.ts
@@ -3,24 +3,24 @@ export interface ModuleOptions {
    * Prefix for components (e.g. 'Re' -> <ReButton />)
    * @default 'Re'
    */
-  prefix?: string
+  prefix?: string;
 
   /**
    * Whether to auto inject theme.css
    * @default true
    */
-  injectTheme?: boolean
+  injectTheme?: boolean;
 
   /** Storage key shared by the SSR initialization script and `useTheme`. */
-  themeStorageKey?: string
+  themeStorageKey?: string;
 
   /** Apply saved theme attributes before Vue hydrates to prevent a color-mode flash. */
-  injectThemeScript?: boolean
+  injectThemeScript?: boolean;
 }
 
 export const defaultOptions: ModuleOptions = {
-  prefix: 'Re',
+  prefix: "Re",
   injectTheme: true,
-  themeStorageKey: 'recloud-theme',
-  injectThemeScript: true
-}
+  themeStorageKey: "recloud-theme",
+  injectThemeScript: true,
+};
diff --git a/packages/ui/src/theme.css b/packages/ui/src/theme.css
index 049e050..834bbcb 100644
--- a/packages/ui/src/theme.css
+++ b/packages/ui/src/theme.css
@@ -19,7 +19,7 @@
   --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-md: 0 4px 10px rgb(15 23 42 / 0.1), 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 */
@@ -68,7 +68,14 @@
   --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: 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));
 
@@ -101,7 +108,7 @@
   --border-subtle: var(--border-muted);
 }
 
-[data-theme='dark'] {
+[data-theme="dark"] {
   --background: #090e17;
   --foreground: #f8fafc;
   --card: #0f172a;
@@ -147,26 +154,99 @@
 }
 
 /* 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-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); }
+[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);
+}
 
 @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;
+  --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);
@@ -196,9 +276,22 @@
   --color-ui-error: var(--destructive);
 }
 
-: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); }
+: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/cn.test.ts b/packages/ui/src/utils/cn.test.ts
index 6fc4b6e..6932099 100644
--- a/packages/ui/src/utils/cn.test.ts
+++ b/packages/ui/src/utils/cn.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import { cn } from "./cn";
 
 describe("cn", () => {
-	it("merges conflicting Tailwind classes", () => {
-		expect(cn("px-2", false, "px-4", "text-sm")).toBe("px-4 text-sm");
-	});
+  it("merges conflicting Tailwind classes", () => {
+    expect(cn("px-2", false, "px-4", "text-sm")).toBe("px-4 text-sm");
+  });
 });
diff --git a/packages/ui/src/utils/theme.ts b/packages/ui/src/utils/theme.ts
index c6ec8b0..3ec8843 100644
--- a/packages/ui/src/utils/theme.ts
+++ b/packages/ui/src/utils/theme.ts
@@ -24,7 +24,8 @@ export const DARK_COLORS = {
 } as const;
 
 export const BRAND_GRADIENTS = {
-  vertical: "linear-gradient(180deg, #C8E0FD 0%, #9BC5FE 25%, #70ACFE 50%, #417BDF 75%, #3069C9 100%)",
+  vertical:
+    "linear-gradient(180deg, #C8E0FD 0%, #9BC5FE 25%, #70ACFE 50%, #417BDF 75%, #3069C9 100%)",
   compact: "linear-gradient(180deg, #C8E0FD 0%, #3069C9 100%)",
   card: "linear-gradient(180deg, #70ACFE 0%, #3069C9 100%)",
 } as const;
diff --git a/packages/ui/src/utils/themeScript.ts b/packages/ui/src/utils/themeScript.ts
index 6439418..1835e02 100644
--- a/packages/ui/src/utils/themeScript.ts
+++ b/packages/ui/src/utils/themeScript.ts
@@ -1,10 +1,20 @@
-import type { ThemePreferences } from '../composables/useTheme'
+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){}})();`
+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 db980c95e9a005bb4b0763a13062592f1a929c44 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Tue, 6 Oct 2026 02:17:20 +0800
Subject: [PATCH 17/17] fix: repair release lockfile

---
 bun.lock | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/bun.lock b/bun.lock
index b7ec416..9cc4a14 100644
--- a/bun.lock
+++ b/bun.lock
@@ -29,8 +29,7 @@
     },
     "packages/ui": {
       "name": "@recloudstudio/ui",
-<<<<<<< HEAD
-      "version": "0.3.0"
+      "version": "0.3.0",
       "dependencies": {
         "clsx": "^2.1.1",
         "lucide-vue-next": "^1.0.0",