feat: add queue management and terminal dashboard documentation in Chinese

- Introduced comprehensive documentation for the queue management feature, detailing its pain points, core functionalities, and component structure. - Added terminal dashboard documentation, highlighting its layout, core features, and usage examples. - Created an index page in Chinese for Claude Code Workflow, summarizing its purpose and core features, along with quick links to installation and guides.
2026-03-01 15:03:57 +08:00 · 2026-03-01 10:52:46 +08:00
parent a753327acc
commit 2fb93d20e0
34 changed files with 6908 additions and 257 deletions
--- a/docs/zh-CN/components/index.md
+++ b/docs/zh-CN/components/index.md
@@ -0,0 +1,600 @@
+# 组件库
+
+## 一句话概述
+**基于 Radix UI 原语和 Tailwind CSS 构建的可复用 UI 组件综合集合，遵循 shadcn/ui 模式，提供一致、可访问和可定制的界面。**
+
+---
+
+## 概述
+
+**位置**: `ccw/frontend/src/components/ui/`
+
+**用途**: 为构建 CCW 前端应用程序提供一致的 UI 组件集合。
+
+**技术栈**:
+- **Radix UI**: 无样式、可访问的组件原语
+- **Tailwind CSS**: 带自定义主题的实用优先样式
+- **class-variance-authority (CVA)**: 类型安全的变体 props 管理
+- **Lucide React**: 一致的图标系统
+
+---
+
+## 实时演示：组件库展示
+
+:::demo ComponentGallery
+# component-gallery.tsx
+/**
+ * 组件库展示演示
+ * 所有 UI 组件的交互式展示
+ */
+export function ComponentGallery() {
+  const [selectedCategory, setSelectedCategory] = React.useState('all')
+  const [buttonVariant, setButtonVariant] = React.useState('default')
+  const [switchState, setSwitchState] = React.useState(false)
+  const [checkboxState, setCheckboxState] = React.useState(false)
+  const [selectedTab, setSelectedTab] = React.useState('variants')
+
+  const categories = [
+    { id: 'all', label: '全部组件' },
+    { id: 'buttons', label: '按钮' },
+    { id: 'forms', label: '表单' },
+    { id: 'feedback', label: '反馈' },
+    { id: 'navigation', label: '导航' },
+    { id: 'overlays', label: '叠加层' },
+  ]
+
+  const components = {
+    buttons: [
+      { name: 'Button', variants: ['default', 'destructive', 'outline', 'secondary', 'ghost', 'link', 'gradient'] },
+    ],
+    forms: [
+      { name: 'Input', type: 'text' },
+      { name: 'Textarea', type: 'textarea' },
+      { name: 'Select', type: 'select' },
+      { name: 'Checkbox', type: 'checkbox' },
+      { name: 'Switch', type: 'switch' },
+    ],
+    feedback: [
+      { name: 'Badge', variants: ['default', 'secondary', 'success', 'warning', 'destructive'] },
+      { name: 'Progress', type: 'progress' },
+      { name: 'Alert', type: 'alert' },
+    ],
+    navigation: [
+      { name: 'Tabs', type: 'tabs' },
+      { name: 'Breadcrumb', type: 'breadcrumb' },
+    ],
+    overlays: [
+      { name: 'Dialog', type: 'dialog' },
+      { name: 'Drawer', type: 'drawer' },
+      { name: 'Dropdown', type: 'dropdown' },
+    ],
+  }
+
+  const buttonVariants = ['default', 'destructive', 'outline', 'secondary', 'ghost', 'link']
+
+  return (
+    <div className="p-6 bg-background space-y-8">
+      {/* 标题 */}
+      <div>
+        <h1 className="text-2xl font-bold">UI 组件库</h1>
+        <p className="text-muted-foreground">所有可用 UI 组件的交互式展示</p>
+      </div>
+
+      {/* 分类过滤 */}
+      <div className="flex flex-wrap gap-2">
+        {categories.map((cat) => (
+          <button
+            key={cat.id}
+            onClick={() => setSelectedCategory(cat.id)}
+            className={`px-4 py-2 rounded-md text-sm transition-colors ${
+              selectedCategory === cat.id
+                ? 'bg-primary text-primary-foreground'
+                : 'border hover:bg-accent'
+            }`}
+          >
+            {cat.label}
+          </button>
+        ))}
+      </div>
+
+      {/* 按钮部分 */}
+      {(selectedCategory === 'all' || selectedCategory === 'buttons') && (
+        <section className="space-y-4">
+          <h2 className="text-lg font-semibold">按钮</h2>
+          <div className="space-y-6">
+            {/* 变体选择器 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">变体</label>
+              <div className="flex flex-wrap gap-2">
+                {buttonVariants.map((variant) => (
+                  <button
+                    key={variant}
+                    onClick={() => setButtonVariant(variant)}
+                    className={`px-4 py-2 rounded-md text-sm capitalize transition-colors ${
+                      buttonVariant === variant
+                        ? 'bg-primary text-primary-foreground ring-2 ring-ring'
+                        : 'border hover:bg-accent'
+                    }`}
+                  >
+                    {variant}
+                  </button>
+                ))}
+              </div>
+            </div>
+
+            {/* 按钮尺寸 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">尺寸</label>
+              <div className="flex items-center gap-3 flex-wrap">
+                <button className={`h-8 rounded-md px-3 text-sm ${buttonVariant === 'default' ? 'bg-primary text-primary-foreground' : 'border'}`}>
+                  小
+                </button>
+                <button className={`h-10 px-4 py-2 rounded-md text-sm ${buttonVariant === 'default' ? 'bg-primary text-primary-foreground' : 'border'}`}>
+                  默认
+                </button>
+                <button className={`h-11 rounded-md px-8 text-sm ${buttonVariant === 'default' ? 'bg-primary text-primary-foreground' : 'border'}`}>
+                  大
+                </button>
+                <button className={`h-10 w-10 rounded-md flex items-center justify-center ${buttonVariant === 'default' ? 'bg-primary text-primary-foreground' : 'border'}`}>
+                  ⚙
+                </button>
+              </div>
+            </div>
+
+            {/* 所有按钮变体 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">所有变体</label>
+              <div className="flex flex-wrap gap-3 p-4 border rounded-lg bg-muted/20">
+                <button className="px-4 py-2 rounded-md text-sm bg-primary text-primary-foreground hover:opacity-90">默认</button>
+                <button className="px-4 py-2 rounded-md text-sm bg-destructive text-destructive-foreground hover:opacity-90">危险</button>
+                <button className="px-4 py-2 rounded-md text-sm border bg-background hover:bg-accent">轮廓</button>
+                <button className="px-4 py-2 rounded-md text-sm bg-secondary text-secondary-foreground hover:opacity-80">次要</button>
+                <button className="px-4 py-2 rounded-md text-sm hover:bg-accent">幽灵</button>
+                <button className="px-4 py-2 rounded-md text-sm text-primary underline-offset-4 hover:underline">链接</button>
+                <button className="px-4 py-2 rounded-md text-sm bg-gradient-to-r from-blue-500 to-purple-500 text-white hover:opacity-90">渐变</button>
+              </div>
+            </div>
+          </div>
+        </section>
+      )}
+
+      {/* 表单部分 */}
+      {(selectedCategory === 'all' || selectedCategory === 'forms') && (
+        <section className="space-y-4">
+          <h2 className="text-lg font-semibold">表单组件</h2>
+          <div className="grid md:grid-cols-2 gap-6">
+            {/* 输入框 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">输入框</label>
+              <input
+                type="text"
+                placeholder="输入文本..."
+                className="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
+              />
+              <input
+                type="text"
+                placeholder="错误状态"
+                className="flex h-10 w-full rounded-md border border-destructive bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-destructive"
+              />
+            </div>
+
+            {/* 文本区域 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">文本区域</label>
+              <textarea
+                placeholder="输入多行文本..."
+                className="flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
+              />
+            </div>
+
+            {/* 复选框 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">复选框</label>
+              <div className="space-y-2">
+                <label className="flex items-center gap-2 text-sm cursor-pointer">
+                  <input type="checkbox" className="h-4 w-4 rounded border border-primary" checked={checkboxState} onChange={(e) => setCheckboxState(e.target.checked)} />
+                  <span>接受条款和条件</span>
+                </label>
+                <label className="flex items-center gap-2 text-sm cursor-pointer opacity-50">
+                  <input type="checkbox" className="h-4 w-4 rounded border border-primary" />
+                  <span>订阅新闻通讯</span>
+                </label>
+              </div>
+            </div>
+
+            {/* 开关 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">开关</label>
+              <div className="space-y-3">
+                <label className="flex items-center gap-3 cursor-pointer">
+                  <div className="relative">
+                    <input type="checkbox" className="sr-only peer" checked={switchState} onChange={(e) => setSwitchState(e.target.checked)} />
+                    <div className="w-9 h-5 bg-input rounded-full peer peer-focus:ring-2 peer-focus:ring-ring peer-checked:bg-primary after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:bg-background after:rounded-full after:h-4 after:w-4 after:transition-all peer-checked:after:translate-x-full" />
+                  </div>
+                  <span className="text-sm">启用通知 {switchState ? '(开)' : '(关)'}</span>
+                </label>
+              </div>
+            </div>
+
+            {/* 下拉选择 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">下拉选择</label>
+              <select className="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring">
+                <option value="">选择一个选项</option>
+                <option value="1">选项 1</option>
+                <option value="2">选项 2</option>
+                <option value="3">选项 3</option>
+              </select>
+            </div>
+
+            {/* 表单操作 */}
+            <div className="space-y-3">
+              <label className="text-sm font-medium">表单操作</label>
+              <div className="flex gap-2">
+                <button className="px-4 py-2 rounded-md text-sm bg-primary text-primary-foreground hover:opacity-90">提交</button>
+                <button className="px-4 py-2 rounded-md text-sm border hover:bg-accent">取消</button>
+              </div>
+            </div>
+          </div>
+        </section>
+      )}
+
+      {/* 反馈部分 */}
+      {(selectedCategory === 'all' || selectedCategory === 'feedback') && (
+        <section className="space-y-4">
+          <h2 className="text-lg font-semibold">反馈组件</h2>
+
+          {/* 徽章 */}
+          <div className="space-y-3">
+            <label className="text-sm font-medium">徽章</label>
+            <div className="flex flex-wrap gap-2">
+              <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold bg-primary text-primary-foreground">默认</span>
+              <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold bg-secondary text-secondary-foreground">次要</span>
+              <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold bg-destructive text-destructive-foreground">危险</span>
+              <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold bg-success text-white">成功</span>
+              <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold bg-warning text-white">警告</span>
+              <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold bg-info text-white">信息</span>
+              <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold text-foreground">轮廓</span>
+            </div>
+          </div>
+
+          {/* 进度条 */}
+          <div className="space-y-3">
+            <label className="text-sm font-medium">进度条</label>
+            <div className="space-y-3 max-w-md">
+              <div>
+                <div className="flex justify-between text-xs mb-1">
+                  <span>处理中...</span>
+                  <span>65%</span>
+                </div>
+                <div className="h-2 bg-muted rounded-full overflow-hidden">
+                  <div className="h-full bg-primary rounded-full transition-all" style={{ width: '65%' }}/>
+                </div>
+              </div>
+              <div>
+                <div className="flex justify-between text-xs mb-1">
+                  <span>上传中...</span>
+                  <span>30%</span>
+                </div>
+                <div className="h-2 bg-muted rounded-full overflow-hidden">
+                  <div className="h-full bg-blue-500 rounded-full transition-all" style={{ width: '30%' }}/>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* 警告 */}
+          <div className="space-y-3">
+            <label className="text-sm font-medium">警告提示</label>
+            <div className="space-y-3">
+              <div className="flex items-start gap-3 p-4 border rounded-lg bg-destructive/10 border-destructive/20 text-destructive">
+                <span className="text-lg">⚠</span>
+                <div className="flex-1">
+                  <div className="font-medium text-sm">发生错误</div>
+                  <div className="text-xs mt-1 opacity-80">出现了一些问题，请重试。</div>
+                </div>
+              </div>
+              <div className="flex items-start gap-3 p-4 border rounded-lg bg-success/10 border-success/20 text-success">
+                <span className="text-lg">✓</span>
+                <div className="flex-1">
+                  <div className="font-medium text-sm">成功！</div>
+                  <div className="text-xs mt-1 opacity-80">您的更改已保存。</div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </section>
+      )}
+
+      {/* 导航部分 */}
+      {(selectedCategory === 'all' || selectedCategory === 'navigation') && (
+        <section className="space-y-4">
+          <h2 className="text-lg font-semibold">导航组件</h2>
+
+          {/* 标签页 */}
+          <div className="space-y-3">
+            <label className="text-sm font-medium">标签页</label>
+            <div className="border-b">
+              <div className="flex gap-4">
+                {['概览', '文档', 'API 参考', '示例'].map((tab) => (
+                  <button
+                    key={tab}
+                    onClick={() => setSelectedTab(tab.toLowerCase().replace(' ', '-'))}
+                    className={`pb-3 px-1 text-sm border-b-2 transition-colors ${
+                      selectedTab === tab.toLowerCase().replace(' ', '-')
+                        ? 'border-primary text-primary'
+                        : 'border-transparent text-muted-foreground hover:text-foreground'
+                    }`}
+                  >
+                    {tab}
+                  </button>
+                ))}
+              </div>
+            </div>
+          </div>
+
+          {/* 面包屑 */}
+          <div className="space-y-3">
+            <label className="text-sm font-medium">面包屑</label>
+            <nav className="flex items-center gap-2 text-sm text-muted-foreground">
+              <a href="#" className="hover:text-foreground">首页</a>
+              <span>/</span>
+              <a href="#" className="hover:text-foreground">组件</a>
+              <span>/</span>
+              <span className="text-foreground">库</span>
+            </nav>
+          </div>
+        </section>
+      )}
+
+      {/* 叠加层部分 */}
+      {(selectedCategory === 'all' || selectedCategory === 'overlays') && (
+        <section className="space-y-4">
+          <h2 className="text-lg font-semibold">叠加层组件</h2>
+
+          <div className="grid md:grid-cols-3 gap-4 text-sm">
+            <div className="p-4 border rounded-lg">
+              <h3 className="font-medium mb-2">对话框</h3>
+              <p className="text-muted-foreground text-xs">用于焦点用户交互的模态对话框。</p>
+              <button className="mt-3 px-3 py-1.5 text-xs bg-primary text-primary-foreground rounded">打开对话框</button>
+            </div>
+            <div className="p-4 border rounded-lg">
+              <h3 className="font-medium mb-2">抽屉</h3>
+              <p className="text-muted-foreground text-xs">从屏幕边缘滑入的侧边面板。</p>
+              <button className="mt-3 px-3 py-1.5 text-xs border rounded hover:bg-accent">打开抽屉</button>
+            </div>
+            <div className="p-4 border rounded-lg">
+              <h3 className="font-medium mb-2">下拉菜单</h3>
+              <p className="text-muted-foreground text-xs">上下文菜单和操作列表。</p>
+              <button className="mt-3 px-3 py-1.5 text-xs border rounded hover:bg-accent">▼ 打开菜单</button>
+            </div>
+          </div>
+        </section>
+      )}
+    </div>
+  )
+}
+:::
+
+---
+
+## 可用组件
+
+### 表单组件
+
+| 组件 | 描述 | Props |
+|------|------|------|
+| [Button](/components/ui/button) | 可点击的操作按钮，带变体和尺寸 | `variant`, `size`, `asChild` |
+| [Input](/components/ui/input) | 文本输入字段 | `error` |
+| [Textarea](/components/ui/textarea) | 多行文本输入 | `error` |
+| [Select](/components/ui/select) | 下拉选择（Radix） | Select 组件 |
+| [Checkbox](/components/ui/checkbox) | 布尔复选框（Radix） | `checked`, `onCheckedChange` |
+| [Switch](/components/ui/switch) | 切换开关 | `checked`, `onCheckedChange` |
+
+### 布局组件
+
+| 组件 | 描述 | Props |
+|------|------|------|
+| [Card](/components/ui/card) | 带标题/脚注的内容容器 | 嵌套组件 |
+| [Separator](/components/ui/separator) | 视觉分隔符 | `orientation` |
+| [ScrollArea](/components/ui/scroll-area) | 自定义滚动条容器 | - |
+
+### 反馈组件
+
+| 组件 | 描述 | Props |
+|------|------|------|
+| [Badge](/components/ui/badge) | 状态指示器标签 | `variant` |
+| [Progress](/components/ui/progress) | 进度条 | `value` |
+| [Alert](/components/ui/alert) | 通知消息 | `variant` |
+| [Toast](/components/ui/toast) | 临时通知（Radix） | Toast 组件 |
+
+### 导航组件
+
+| 组件 | 描述 | Props |
+|------|------|------|
+| [Tabs](/components/ui/tabs) | 标签页导航（Radix） | Tabs 组件 |
+| [TabsNavigation](/components/ui/tabs-navigation) | 自定义标签栏 | `tabs`, `value`, `onValueChange` |
+| [Breadcrumb](/components/ui/breadcrumb) | 导航面包屑 | Breadcrumb 组件 |
+
+### 叠加层组件
+
+| 组件 | 描述 | Props |
+|------|------|------|
+| [Dialog](/components/ui/dialog) | 模态对话框（Radix） | `open`, `onOpenChange` |
+| [Drawer](/components/ui/drawer) | 侧边面板（Radix） | `open`, `onOpenChange` |
+| [Dropdown Menu](/components/ui/dropdown) | 上下文菜单（Radix） | Dropdown 组件 |
+| [Popover](/components/ui/popover) | 浮动内容（Radix） | `open`, `onOpenChange` |
+| [Tooltip](/components/ui/tooltip) | 悬停工具提示（Radix） | `content` |
+| [AlertDialog](/components/ui/alert-dialog) | 确认对话框（Radix） | Dialog 组件 |
+
+### 展开组件
+
+| 组件 | 描述 | Props |
+|------|------|------|
+| [Collapsible](/components/ui/collapsible) | 展开/折叠内容（Radix） | `open`, `onOpenChange` |
+| [Accordion](/components/ui/accordion) | 可折叠部分（Radix） | Accordion 组件 |
+
+---
+
+## 按钮变体
+
+Button 组件通过 CVA（class-variance-authority）支持 8 种变体：
+
+| 变体 | 用途 | 预览 |
+|---------|----------|--------|
+| `default` | 主要操作 | <span className="inline-block px-3 py-1 rounded bg-primary text-primary-foreground text-xs">默认</span> |
+| `destructive` | 危险操作 | <span className="inline-block px-3 py-1 rounded bg-destructive text-destructive-foreground text-xs">危险</span> |
+| `outline` | 次要操作 | <span className="inline-block px-3 py-1 rounded border text-xs">轮廓</span> |
+| `secondary` | 较少强调 | <span className="inline-block px-3 py-1 rounded bg-secondary text-secondary-foreground text-xs">次要</span> |
+| `ghost` | 微妙操作 | <span className="inline-block px-3 py-1 rounded text-xs">幽灵</span> |
+| `link` | 文本链接 | <span className="inline-block px-3 py-1 underline text-primary text-xs">链接</span> |
+| `gradient` | 特色操作 | <span className="inline-block px-3 py-1 rounded bg-gradient-to-r from-blue-500 to-purple-500 text-white text-xs">渐变</span> |
+| `gradientPrimary` | 主要渐变 | <span className="inline-block px-3 py-1 rounded bg-gradient-to-r from-purple-500 to-pink-500 text-white text-xs">主要</span> |
+
+### 按钮尺寸
+
+| 尺寸 | 高度 | 内边距 |
+|------|--------|---------|
+| `sm` | 36px | 水平 12px |
+| `default` | 40px | 水平 16px |
+| `lg` | 44px | 水平 32px |
+| `icon` | 40px | 正方形（仅图标） |
+
+---
+
+## 徽章变体
+
+Badge 组件支持 9 种变体，用于不同的状态类型：
+
+| 变体 | 用途 | 颜色 |
+|---------|----------|-------|
+| `default` | 一般信息 | 主要主题 |
+| `secondary` | 较少强调 | 次要主题 |
+| `destructive` | 错误/危险 | 危险主题 |
+| `outline` | 微妙 | 仅文本颜色 |
+| `success` | 成功状态 | 绿色 |
+| `warning` | 警告状态 | 琥珀色 |
+| `info` | 信息 | 蓝色 |
+| `review` | 审查状态 | 紫色 |
+| `gradient` | 特色 | 品牌渐变 |
+
+---
+
+## 使用示例
+
+### Button
+
+```tsx
+import { Button } from '@/components/ui/Button'
+
+<Button variant="default" onClick={handleClick}>
+  点击我
+</Button>
+
+<Button variant="destructive" size="sm">
+  删除
+</Button>
+
+<Button variant="ghost" size="icon">
+  <SettingsIcon />
+</Button>
+```
+
+### Input with Error State
+
+```tsx
+import { Input } from '@/components/ui/Input'
+
+<Input
+  type="text"
+  error={hasError}
+  placeholder="输入您的名称"
+  value={name}
+  onChange={(e) => setName(e.target.value)}
+/>
+```
+
+### Checkbox
+
+```tsx
+import { Checkbox } from '@/components/ui/Checkbox'
+
+<Checkbox
+  checked={accepted}
+  onCheckedChange={setAccepted}
+/>
+<label>接受条款</label>
+```
+
+### Switch
+
+```tsx
+import { Switch } from '@/components/ui/Switch'
+
+<Switch
+  checked={enabled}
+  onCheckedChange={setEnabled}
+/>
+<span>启用功能</span>
+```
+
+### Card
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/Card'
+
+<Card>
+  <CardHeader>
+    <CardTitle>卡片标题</CardTitle>
+    <CardDescription>简短描述在这里</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>主要内容放在这里。</p>
+  </CardContent>
+  <CardFooter>
+    <Button>操作</Button>
+  </CardFooter>
+</Card>
+```
+
+### Badge
+
+```tsx
+import { Badge, badgeVariants } from '@/components/ui/Badge'
+
+<Badge variant="success">已完成</Badge>
+<Badge variant="warning">待处理</Badge>
+<Badge variant="destructive">失败</Badge>
+```
+
+---
+
+## 可访问性
+
+所有组件遵循 Radix UI 的可访问性标准：
+
+- **键盘导航**：所有交互组件完全可键盘访问
+- **ARIA 属性**：正确的角色、状态和属性
+- **屏幕阅读器支持**：语义化 HTML 和 ARIA 标签
+- **焦点管理**：可见的焦点指示器和逻辑 Tab 顺序
+- **颜色对比度**：符合 WCAG AA 标准的颜色组合
+
+### 键盘快捷键
+
+| 组件 | 按键 |
+|-----------|-------|
+| Button | <kbd>Enter</kbd>, <kbd>Space</kbd> |
+| Checkbox/Switch | <kbd>Space</kbd> 切换 |
+| Select | <kbd>Arrow</kbd> 键，<kbd>Enter</kbd> 选择，<kbd>Esc</kbd> 关闭 |
+| Dialog | <kbd>Esc</kbd> 关闭 |
+| Tabs | <kbd>Arrow</kbd> 键导航 |
+| Dropdown | <kbd>Arrow</kbd> 键，<kbd>Enter</kbd> 选择 |
+
+---
+
+## 相关链接
+
+- [Radix UI Primitives](https://www.radix-ui.com/) - 无头 UI 组件库
+- [Tailwind CSS](https://tailwindcss.com/) - 实用优先 CSS 框架
+- [shadcn/ui](https://ui.shadcn.com/) - 组件模式参考
+- [CVA Documentation](https://cva.style/) - Class Variance Authority
--- a/docs/zh-CN/components/ui/badge.md
+++ b/docs/zh-CN/components/ui/badge.md
@@ -0,0 +1,119 @@
+---
+title: Badge 徽章
+description: 用于视觉分类的小型状态或标签组件
+sidebar: auto
+---
+
+# Badge 徽章
+
+## 概述
+
+Badge 徽章组件用于以紧凑形式显示状态、类别或标签。它通常用于标签、状态指示器和计数。
+
+## 语法演示
+
+:::demo badge-variants
+展示所有可用的徽章变体，包括默认、次要、破坏性、轮廓、成功、警告、信息、审查和渐变样式
+:::
+
+## 属性
+
+<PropsTable :props="[
+  { name: 'variant', type: '\'default\' | \'secondary\' | \'destructive\' | \'outline\' | \'success\' | \'warning\' | \'info\' | \'review\' | \'gradient\'', required: false, default: '\'default\'', description: '视觉样式变体' },
+  { name: 'className', type: 'string', required: false, default: '-', description: '自定义 CSS 类名' },
+  { name: 'children', type: 'ReactNode', required: true, default: '-', description: '徽章内容' }
+]" />
+
+## 变体说明
+
+### Default（默认）
+
+主题色背景的主要徽章。用于主要标签和类别。
+
+### Secondary（次要）
+
+次要信息的灰色徽章。
+
+### Destructive（破坏性）
+
+红色徽章，用于错误、危险状态或负面状态指示。
+
+### Outline（轮廓）
+
+只有文本和边框、无背景的徽章。用于微妙的标签。
+
+### Success（成功）
+
+绿色徽章，用于成功状态、完成的操作或正面状态指示。
+
+### Warning（警告）
+
+黄色/琥珀色徽章，用于警告、待处理状态或注意事项。
+
+### Info（信息）
+
+蓝色徽章，用于信息内容或中性状态。
+
+### Review（审查）
+
+紫色徽章，用于审查状态、待审查或反馈指示器。
+
+### Gradient（渐变）
+
+带品牌渐变背景的徽章，用于特色或突出显示的项目。
+
+## 使用示例
+
+### 基础徽章
+
+```vue
+<Badge>默认</Badge>
+```
+
+### 状态指示器
+
+```vue
+<Badge variant="success">活跃</Badge>
+<Badge variant="warning">待处理</Badge>
+<Badge variant="destructive">失败</Badge>
+<Badge variant="info">草稿</Badge>
+```
+
+### 计数徽章
+
+```vue
+<div class="relative">
+  <Bell />
+  <Badge variant="destructive" class="absolute -top-2 -right-2 h-5 w-5 rounded-full p-0 flex items-center justify-center text-xs">
+    3
+  </Badge>
+</div>
+```
+
+### 分类标签
+
+```vue
+<div class="flex gap-2">
+  <Badge variant="outline">React</Badge>
+  <Badge variant="outline">TypeScript</Badge>
+  <Badge variant="outline">Tailwind</Badge>
+</div>
+```
+
+### 审查状态
+
+```vue
+<Badge variant="review">审查中</Badge>
+```
+
+### 渐变徽章
+
+```vue
+<Badge variant="gradient">特色</Badge>
+```
+
+## 相关组件
+
+- [Card 卡片](/zh-CN/components/ui/card)
+- [Button 按钮](/zh-CN/components/ui/button)
+- [Avatar 头像](/zh-CN/components/ui/avatar)
--- a/docs/zh-CN/components/ui/button.md
+++ b/docs/zh-CN/components/ui/button.md
@@ -0,0 +1,80 @@
+---
+title: Button 按钮
+description: 按钮组件用于触发操作或提交表单
+sidebar: auto
+---
+
+# Button 按钮
+
+## 概述
+
+按钮是最常用的交互元素之一，用于触发操作、提交表单或导航到其他页面。
+
+## 语法演示
+
+:::demo button-variants
+展示所有视觉变体的按钮组件
+:::
+
+## 属性
+
+<PropsTable :props="[
+  { name: 'variant', type: '\'default\' | \'destructive\' | \'outline\' | \'secondary\' | \'ghost\' | \'link\' | \'gradient\' | \'gradientPrimary\'', required: false, default: '\'default\'', description: '按钮的视觉变体' },
+  { name: 'size', type: '\'default\' | \'sm\' | \'lg\' | \'icon\'', required: false, default: '\'default\'', description: '按钮的大小' },
+  { name: 'asChild', type: 'boolean', required: false, default: 'false', description: '是否将 props 与子元素合并（用于 Radix UI 组合）' },
+  { name: 'disabled', type: 'boolean', required: false, default: 'false', description: '是否禁用按钮' },
+  { name: 'onClick', type: '() => void', required: false, default: '-', description: '点击事件回调函数' },
+  { name: 'className', type: 'string', required: false, default: '-', description: '自定义 CSS 类名' },
+  { name: 'children', type: 'ReactNode', required: true, default: '-', description: '按钮内容' }
+]" />
+
+## 变体说明
+
+### Default（默认）
+
+默认按钮用于主要的操作场景。
+
+### Destructive（破坏性）
+
+破坏性按钮用于删除、移除等不可逆的操作。
+
+### Outline（轮廓）
+
+轮廓按钮用于次要操作，视觉上更轻量。
+
+### Secondary（次要）
+
+次要按钮用于辅助操作。
+
+### Ghost（幽灵）
+
+幽灵按钮没有边框，视觉上最轻量。
+
+### Link（链接）
+
+链接按钮看起来像链接，但具有按钮的交互行为。
+
+### Gradient（渐变）
+
+渐变按钮使用品牌渐变色，悬停时带有发光效果。
+
+### Gradient Primary（主色渐变）
+
+主色渐变按钮使用主题主色渐变，悬停时带有增强的发光效果。
+
+## 使用场景
+
+| 场景 | 推荐变体 |
+|------|----------|
+| 主要操作（提交、保存） | default, gradientPrimary |
+| 危险操作（删除、移除） | destructive |
+| 次要操作 | outline, secondary |
+| 取消操作 | ghost, outline |
+| 导航链接 | link |
+| 促销/特色 CTA | gradient |
+
+## 相关组件
+
+- [Input 输入框](/zh-CN/components/ui/input)
+- [Select 选择器](/zh-CN/components/ui/select)
+- [Dialog 对话框](/zh-CN/components/ui/dialog)
--- a/docs/zh-CN/components/ui/card.md
+++ b/docs/zh-CN/components/ui/card.md
@@ -0,0 +1,107 @@
+---
+title: Card 卡片
+description: 用于分组相关内容的容器组件
+sidebar: auto
+---
+
+# Card 卡片
+
+## 概述
+
+卡片组件是一个通用的容器，用于分组相关的内容和操作。它由多个子组件组成，协同工作以创建连贯的卡片布局。
+
+## 语法演示
+
+:::demo card-variants
+展示不同的卡片布局，包括页眉、内容、页脚和渐变边框变体
+:::
+
+## 组件
+
+卡片组件包含以下子组件：
+
+| 组件 | 用途 |
+|------|------|
+| `Card` | 带有边框和背景的主容器 |
+| `CardHeader` | 带有内边距的页眉部分 |
+| `CardTitle` | 标题元素 |
+| `CardDescription` | 带有次要颜色的描述文本 |
+| `CardContent` | 带有顶部内边距的内容区域 |
+| `CardFooter` | 用于操作的页脚部分 |
+| `CardGradientBorder` | 带有渐变边框的卡片 |
+
+## 属性
+
+所有 Card 组件接受标准 HTML div 属性：
+
+| 组件 | 属性 |
+|------|------|
+| `Card` | `className?: string` |
+| `CardHeader` | `className?: string` |
+| `CardTitle` | `className?: string`, `children?: ReactNode` |
+| `CardDescription` | `className?: string`, `children?: ReactNode` |
+| `CardContent` | `className?: string` |
+| `CardFooter` | `className?: string` |
+| `CardGradientBorder` | `className?: string` |
+
+## 使用示例
+
+### 基础卡片
+
+```vue
+<Card>
+  <CardContent>
+    <p>这是一个带有内容的基础卡片。</p>
+  </CardContent>
+</Card>
+```
+
+### 带页眉的卡片
+
+```vue
+<Card>
+  <CardHeader>
+    <CardTitle>卡片标题</CardTitle>
+    <CardDescription>卡片描述放在这里</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>卡片内容放在这里。</p>
+  </CardContent>
+</Card>
+```
+
+### 带页脚的完整卡片
+
+```vue
+<Card>
+  <CardHeader>
+    <CardTitle>项目设置</CardTitle>
+    <CardDescription>管理您的项目配置</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>配置您的项目设置和偏好。</p>
+  </CardContent>
+  <CardFooter>
+    <Button>保存更改</Button>
+  </CardFooter>
+</Card>
+```
+
+### 带渐变边框的卡片
+
+```vue
+<CardGradientBorder>
+  <CardHeader>
+    <CardTitle>特色卡片</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <p>此卡片具有渐变边框效果。</p>
+  </CardContent>
+</CardGradientBorder>
+```
+
+## 相关组件
+
+- [Button 按钮](/zh-CN/components/ui/button)
+- [Badge 徽章](/zh-CN/components/ui/badge)
+- [Separator 分隔线](/zh-CN/components/ui/separator)
--- a/docs/zh-CN/components/ui/checkbox.md
+++ b/docs/zh-CN/components/ui/checkbox.md
@@ -0,0 +1,120 @@
+---
+title: Checkbox 复选框
+description: 用于二元选择的复选框组件
+sidebar: auto
+---
+
+# Checkbox 复选框
+
+## 概述
+
+Checkbox 复选框组件允许用户从一组选项中选择一个或多个选项。基于 Radix UI Checkbox Primitive 构建，提供完整的无障碍支持，包括键盘导航。
+
+## 语法演示
+
+:::demo checkbox-variants
+展示不同的复选框状态，包括选中、未选中、半选和禁用状态
+:::
+
+## 属性
+
+<PropsTable :props="[
+  { name: 'checked', type: 'boolean | \'indeterminate\'', required: false, default: 'false', description: '是否选中复选框' },
+  { name: 'defaultChecked', type: 'boolean', required: false, default: 'false', description: '初始选中状态（非受控）' },
+  { name: 'onCheckedChange', type: '(checked: boolean) => void', required: false, default: '-', description: '选中状态变化时的回调函数' },
+  { name: 'disabled', type: 'boolean', required: false, default: 'false', description: '是否禁用复选框' },
+  { name: 'required', type: 'boolean', required: false, default: 'false', description: '是否为必填项' },
+  { name: 'name', type: 'string', required: false, default: '-', description: '表单输入名称' },
+  { name: 'value', type: 'string', required: false, default: '-', description: '表单输入值' },
+  { name: 'className', type: 'string', required: false, default: '-', description: '自定义 CSS 类名' }
+]" />
+
+## 状态说明
+
+### Unchecked（未选中）
+
+复选框未被选择时的默认状态。
+
+### Checked（已选中）
+
+复选框被选择时显示勾选图标。
+
+### Indeterminate（半选）
+
+混合状态（部分选择），通常用于父级复选框，当部分但不是全部子项被选中时使用。
+
+### Disabled（禁用）
+
+禁用的复选框不可交互，并以降低的透明度显示。
+
+## 使用示例
+
+### 基础复选框
+
+```vue
+<Checkbox />
+```
+
+### 带标签的复选框
+
+```vue
+<div class="flex items-center space-x-2">
+  <Checkbox id="terms" />
+  <label for="terms">我同意条款和条件</label>
+</div>
+```
+
+### 受控复选框
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const checked = ref(false)
+</script>
+
+<template>
+  <div class="flex items-center space-x-2">
+    <Checkbox v-model:checked="checked" />
+    <span>{{ checked ? '已选中' : '未选中' }}</span>
+  </div>
+</template>
+```
+
+### 半选状态
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const state = ref('indeterminate')
+</script>
+
+<template>
+  <Checkbox :checked="state" />
+</template>
+```
+
+### 表单集成
+
+```vue
+<form @submit="handleSubmit">
+  <div class="space-y-2">
+    <div class="flex items-center space-x-2">
+      <Checkbox id="newsletter" name="newsletter" value="yes" />
+      <label for="newsletter">订阅新闻通讯</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <Checkbox id="updates" name="updates" value="yes" />
+      <label for="updates">接收产品更新</label>
+    </div>
+  </div>
+  <Button type="submit" class="mt-4">提交</Button>
+</form>
+```
+
+## 相关组件
+
+- [Input 输入框](/zh-CN/components/ui/input)
+- [Select 选择器](/zh-CN/components/ui/select)
+- [Radio Group 单选框组](/zh-CN/components/ui/radio-group)
--- a/docs/zh-CN/components/ui/input.md
+++ b/docs/zh-CN/components/ui/input.md
@@ -0,0 +1,118 @@
+---
+title: Input 输入框
+description: 用于表单和用户输入的文本输入组件
+sidebar: auto
+---
+
+# Input 输入框
+
+## 概述
+
+输入框组件提供了一个样式化的文本输入字段，扩展了原生 HTML input 元素，具有一致的样式和错误状态支持。
+
+## 语法演示
+
+:::demo input-variants
+展示所有输入框状态，包括默认、错误和禁用
+:::
+
+## 属性
+
+<PropsTable :props="[
+  { name: 'type', type: 'string', required: false, default: '\'text\'', description: 'HTML input 类型（text、password、email、number 等）' },
+  { name: 'error', type: 'boolean', required: false, default: 'false', description: '输入框是否处于错误状态（显示破坏性边框）' },
+  { name: 'disabled', type: 'boolean', required: false, default: 'false', description: '是否禁用输入框' },
+  { name: 'placeholder', type: 'string', required: false, default: '-', description: '输入框为空时显示的占位符文本' },
+  { name: 'value', type: 'string | number', required: false, default: '-', description: '受控输入框的值' },
+  { name: 'defaultValue', type: 'string | number', required: false, default: '-', description: '非受控输入框的默认值' },
+  { name: 'onChange', type: '(event: ChangeEvent) => void', required: false, default: '-', description: '变更事件回调函数' },
+  { name: 'className', type: 'string', required: false, default: '-', description: '自定义 CSS 类名' }
+]" />
+
+## 状态
+
+### Default（默认）
+
+带有边框和焦点环的标准输入框。
+
+### Error（错误）
+
+错误状态，显示破坏性边框颜色。将 `error` 属性设置为 `true`。
+
+### Disabled（禁用）
+
+禁用状态，透明度降低。将 `disabled` 属性设置为 `true`。
+
+### Focus（聚焦）
+
+聚焦状态，带有环形轮廓。
+
+## 使用示例
+
+### 基础输入框
+
+```tsx
+import { Input } from '@/components/ui/Input'
+
+function Example() {
+  return <input type="text" placeholder="输入文本..." />
+}
+```
+
+### 受控输入框
+
+```tsx
+import { Input } from '@/components/ui/Input'
+
+function Example() {
+  const [value, setValue] = useState('')
+
+  return (
+    <Input
+      type="text"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      placeholder="输入文本..."
+    />
+  )
+}
+```
+
+### 错误状态输入框
+
+```tsx
+import { Input } from '@/components/ui/Input'
+
+function Example() {
+  return (
+    <Input
+      type="text"
+      error
+      placeholder="无效输入..."
+    />
+  )
+}
+```
+
+### 密码输入框
+
+```tsx
+import { Input } from '@/components/ui/Input'
+
+function Example() {
+  return <Input type="password" placeholder="输入密码..." />
+}
+```
+
+## 无障碍访问
+
+- **键盘导航**：完全支持原生键盘操作
+- **ARIA 属性**：支持所有标准输入框 ARIA 属性
+- **焦点可见**：为键盘导航提供清晰的焦点指示器
+- **错误状态**：错误状态的视觉指示（与 `aria-invalid` 和 `aria-describedby` 配合使用）
+
+## 相关组件
+
+- [Button 按钮](/zh-CN/components/ui/button)
+- [Select 选择器](/zh-CN/components/ui/select)
+- [Checkbox 复选框](/zh-CN/components/ui/checkbox)
--- a/docs/zh-CN/components/ui/select.md
+++ b/docs/zh-CN/components/ui/select.md
@@ -0,0 +1,127 @@
+---
+title: Select 选择器
+description: 用于从选项列表中选择值的下拉选择组件
+sidebar: auto
+---
+
+# Select 选择器
+
+## 概述
+
+Select 选择器组件允许用户从选项列表中选择单个值。基于 Radix UI Select Primitive 构建，提供开箱即用的无障碍支持和键盘导航。
+
+## 语法演示
+
+:::demo select-variants
+展示不同的选择器配置，包括基础用法、带标签和带分隔线的示例
+:::
+
+## 子组件
+
+Select 选择器组件包含以下子组件：
+
+| 组件 | 用途 |
+|------|------|
+| `Select` | 管理状态的根组件 |
+| `SelectTrigger` | 打开下拉菜单的按钮 |
+| `SelectValue` | 显示选中的值 |
+| `SelectContent` | 下拉菜单内容容器 |
+| `SelectItem` | 单个可选项 |
+| `SelectLabel` | 用于分组的不可交互标签 |
+| `SelectGroup` | 将项目分组 |
+| `SelectSeparator` | 项目之间的视觉分隔线 |
+| `SelectScrollUpButton` | 长列表的向上滚动按钮 |
+| `SelectScrollDownButton` | 长列表的向下滚动按钮 |
+
+## 属性
+
+### Select 根组件
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string` | - | 当前选中的值（受控） |
+| `defaultValue` | `string` | - | 默认选中的值 |
+| `onValueChange` | `(value: string) => void` | - | 值变化时的回调函数 |
+| `disabled` | `boolean` | `false` | 是否禁用选择器 |
+| `required` | `boolean` | `false` | 是否必填 |
+| `name` | `string` | - | 表单输入名称 |
+
+### SelectTrigger
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 自定义 CSS 类名 |
+
+### SelectItem
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string` | - | 选项值 |
+| `disabled` | `boolean` | `false` | 是否禁用该选项 |
+| `className` | `string` | - | 自定义 CSS 类名 |
+
+## 使用示例
+
+### 基础选择器
+
+```vue
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="请选择一个选项" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">选项 1</SelectItem>
+    <SelectItem value="option2">选项 2</SelectItem>
+    <SelectItem value="option3">选项 3</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### 带标签和分组
+
+```vue
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="选择水果" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectLabel>水果</SelectLabel>
+    <SelectItem value="apple">苹果</SelectItem>
+    <SelectItem value="banana">香蕉</SelectItem>
+    <SelectItem value="orange">橙子</SelectItem>
+    <SelectSeparator />
+    <SelectLabel>蔬菜</SelectLabel>
+    <SelectItem value="carrot">胡萝卜</SelectItem>
+    <SelectItem value="broccoli">西兰花</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### 受控选择器
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const selectedValue = ref('')
+</script>
+
+<template>
+  <Select v-model="selectedValue">
+    <SelectTrigger>
+      <SelectValue placeholder="请选择..." />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="a">选项 A</SelectItem>
+      <SelectItem value="b">选项 B</SelectItem>
+      <SelectItem value="c">选项 C</SelectItem>
+    </SelectContent>
+  </Select>
+</template>
+```
+
+## 相关组件
+
+- [Input 输入框](/zh-CN/components/ui/input)
+- [Checkbox 复选框](/zh-CN/components/ui/checkbox)
+- [Button 按钮](/zh-CN/components/ui/button)