feat(a11y): improve core interaction accessibility and add audit guide

AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Overview
+
+This is a **Nova UI** monorepo — an enterprise React component library with two workspaces:
+
+- `packages/ui` — the publishable `@wuyangfan/nova-ui` NPM package (~80 source files, 6 component categories)
+- `docs` — a VitePress documentation site with live React playground (via `react-live`)
+
+No databases, Docker, or backend services are required. Only Node.js 20+ and npm.
+
+### Key commands
+
+All commands run from the workspace root. See `package.json` for the full list.
+This is an npm workspaces monorepo with two packages:
+
+- `packages/ui` — publishable React component library (`@wuyangfan/nova-ui`)
+- `docs` — VitePress documentation site with interactive playground
+
+### Key commands (run from workspace root)
+
+| Task | Command |
+|---|---|
+| Install deps | `npm install` |
+| Build UI lib | `npm run build:ui` |
+| Lint | `npm run lint:ui` |
+| Typecheck | `npm run typecheck:ui` |
+| Docs dev server | `npm run dev:docs` (port 5173) |
+| UI dev server | `cd packages/ui && npm run dev` (port 5174 if docs running) |
+| Full build | `npm run build` |
+
+### Important caveats
+
+- **Build order matters**: the docs workspace has a `file:` dependency on `../packages/ui`. You must run `npm run build:ui` before `npm run dev:docs` or `npm run build:docs` — otherwise the docs site will fail to resolve the component library.
+- **No test framework**: there are currently no automated tests (no Jest, Vitest, or testing-library). Lint (`npm run lint:ui`) and typecheck (`npm run typecheck:ui`) are the primary code-quality checks.
+- The docs dev server runs at `http://localhost:5173/react-ui-library/` (note the base path).
+- The standalone UI dev server at `packages/ui` uses Vite and serves at `http://localhost:5174/` (or the next available port).
+| Lint UI | `npm run lint:ui` |
+| Typecheck UI | `npm run typecheck:ui` |
+| Dev docs server | `npm run dev:docs` |
+| Build docs | `npm run build:docs` |
+| Build all | `npm run build` |
+
+### Caveats
+
+- You must run `npm run build:ui` before `npm run dev:docs` so the docs package can resolve `@wuyangfan/nova-ui` (it uses a `file:` reference to the local build output).
+- The docs dev server runs at `http://localhost:5173/react-ui-library/` (note the base path).
+- No databases, Docker, or external services are required.

docs/.vitepress/config.ts

@@ -6,7 +6,11 @@ export default defineConfig({
   title: 'Nova UI',
   description: 'Enterprise React component library with TypeScript and Tailwind CSS',
   lang: 'zh-CN',
+  appearance: true,
   themeConfig: {
+    darkModeSwitchLabel: '主题',
+    lightModeSwitchTitle: '切换到浅色模式',
+    darkModeSwitchTitle: '切换到深色模式',
     logo: '/favicon.svg',
     nav: [
       { text: '指南', link: '/guide/introduction' },
@@ -20,20 +24,120 @@ export default defineConfig({
           items: [
             { text: '项目介绍', link: '/guide/introduction' },
             { text: '快速开始', link: '/guide/getting-started' },
+            { text: '可访问性', link: '/guide/accessibility' },
+            { text: '文档优化 TODO', link: '/guide/docs-optimization-todo' },
           ],
         },
       ],
       '/components/': [
+        { text: '概览', link: '/components/overview' },
         {
-          text: '组件文档',
+          text: '布局',
+          collapsed: false,
           items: [
-            { text: '概览', link: '/components/overview' },
-            { text: '布局组件', link: '/components/layout' },
-            { text: '基础组件', link: '/components/basic' },
-            { text: '表单组件', link: '/components/form' },
-            { text: '反馈组件', link: '/components/feedback' },
-            { text: '数据组件', link: '/components/data' },
-            { text: '导航组件', link: '/components/navigation' },
+            { text: 'Container 布局容器', link: '/components/container' },
+            { text: 'Row 行', link: '/components/row' },
+            { text: 'Col 列', link: '/components/col' },
+            { text: 'Grid 网格', link: '/components/grid' },
+            { text: 'Flex 弹性布局', link: '/components/flex' },
+            { text: 'Space 间距', link: '/components/space' },
+            { text: 'Divider 分割线', link: '/components/divider' },
+            { text: 'SplitPane 分栏', link: '/components/split-pane' },
+          ],
+        },
+        {
+          text: '基础',
+          collapsed: false,
+          items: [
+            { text: 'Button 按钮', link: '/components/button' },
+            { text: 'Icon 图标', link: '/components/icon' },
+            { text: 'Typography 排版', link: '/components/typography' },
+          ],
+        },
+        {
+          text: '表单',
+          collapsed: false,
+          items: [
+            { text: 'Input 输入框', link: '/components/input' },
+            { text: 'InputNumber 数字输入框', link: '/components/input-number' },
+            { text: 'AutoComplete 自动完成', link: '/components/auto-complete' },
+            { text: 'Select 选择器', link: '/components/select' },
+            { text: 'Checkbox 多选框', link: '/components/checkbox' },
+            { text: 'Radio 单选框', link: '/components/radio' },
+            { text: 'Switch 开关', link: '/components/switch' },
+            { text: 'DatePicker 日期选择', link: '/components/date-picker' },
+            { text: 'TimePicker 时间选择', link: '/components/time-picker' },
+            { text: 'Slider 滑动条', link: '/components/slider' },
+            { text: 'Rate 评分', link: '/components/rate' },
+            { text: 'Upload 上传', link: '/components/upload' },
+            { text: 'Form 表单', link: '/components/form' },
+            { text: 'Calendar 日历', link: '/components/calendar' },
+            { text: 'Transfer 穿梭框', link: '/components/transfer' },
+            { text: 'Cascader 级联选择', link: '/components/cascader' },
+            { text: 'TreeSelect 树选择', link: '/components/tree-select' },
+            { text: 'ColorPicker 颜色选择', link: '/components/color-picker' },
+            { text: 'Segmented 分段控制器', link: '/components/segmented' },
+            { text: 'Mentions 提及', link: '/components/mentions' },
+          ],
+        },
+        {
+          text: '反馈',
+          collapsed: false,
+          items: [
+            { text: 'Alert 警告提示', link: '/components/alert' },
+            { text: 'Modal 对话框', link: '/components/modal' },
+            { text: 'Drawer 抽屉', link: '/components/drawer' },
+            { text: 'Toast 轻提示', link: '/components/toast' },
+            { text: 'Tooltip 文字提示', link: '/components/tooltip' },
+            { text: 'Popover 气泡卡片', link: '/components/popover' },
+            { text: 'Popconfirm 气泡确认', link: '/components/popconfirm' },
+            { text: 'Loading 加载中', link: '/components/loading' },
+            { text: 'Spin 加载动画', link: '/components/spin' },
+            { text: 'Skeleton 骨架屏', link: '/components/skeleton' },
+            { text: 'Notification 通知', link: '/components/notification' },
+            { text: 'Tour 漫游式引导', link: '/components/tour' },
+            { text: 'Watermark 水印', link: '/components/watermark' },
+          ],
+        },
+        {
+          text: '数据展示',
+          collapsed: false,
+          items: [
+            { text: 'Table 表格', link: '/components/table' },
+            { text: 'List 列表', link: '/components/list' },
+            { text: 'Card 卡片', link: '/components/card' },
+            { text: 'Carousel 走马灯', link: '/components/carousel' },
+            { text: 'Tag 标签', link: '/components/tag' },
+            { text: 'Badge 徽标', link: '/components/badge' },
+            { text: 'Avatar 头像', link: '/components/avatar' },
+            { text: 'Image 图片', link: '/components/image' },
+            { text: 'Pagination 分页', link: '/components/pagination' },
+            { text: 'Progress 进度条', link: '/components/progress' },
+            { text: 'Statistic 统计数值', link: '/components/statistic' },
+            { text: 'Descriptions 描述列表', link: '/components/descriptions' },
+            { text: 'Empty 空状态', link: '/components/empty' },
+            { text: 'Result 结果', link: '/components/result' },
+            { text: 'Timeline 时间轴', link: '/components/timeline' },
+            { text: 'QRCode 二维码', link: '/components/qrcode' },
+            { text: 'ImagePreview 图片预览', link: '/components/image-preview' },
+            { text: 'VirtualList 虚拟列表', link: '/components/virtual-list' },
+          ],
+        },
+        {
+          text: '导航',
+          collapsed: false,
+          items: [
+            { text: 'Tabs 标签页', link: '/components/tabs' },
+            { text: 'Menu 菜单', link: '/components/menu' },
+            { text: 'Breadcrumb 面包屑', link: '/components/breadcrumb' },
+            { text: 'Dropdown 下拉菜单', link: '/components/dropdown' },
+            { text: 'Steps 步骤条', link: '/components/steps' },
+            { text: 'Collapse 折叠面板', link: '/components/collapse' },
+            { text: 'Tree 树形控件', link: '/components/tree' },
+            { text: 'Anchor 锚点', link: '/components/anchor' },
+            { text: 'Affix 固钉', link: '/components/affix' },
+            { text: 'BackTop 回到顶部', link: '/components/back-top' },
+            { text: 'FloatButton 悬浮按钮', link: '/components/float-button' },
           ],
         },
       ],

docs/.vitepress/theme/custom.css

@@ -43,3 +43,43 @@
   background: #7f1d1d;
   color: #fff;
 }
+
+.comp-overview-grid {
+  display: grid;
+  gap: 12px;
+  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+  margin: 18px 0;
+}
+
+.comp-overview-card {
+  display: block;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 14px;
+  background: var(--vp-c-bg-soft);
+  text-decoration: none;
+  transition: border-color 0.2s ease, transform 0.2s ease;
+}
+
+.comp-overview-card:hover {
+  border-color: var(--vp-c-brand-1);
+  transform: translateY(-1px);
+}
+
+.comp-overview-card h3 {
+  margin: 0 0 6px;
+  color: var(--vp-c-text-1);
+}
+
+.comp-overview-card p {
+  margin: 0 0 8px;
+  color: var(--vp-c-brand-1);
+  font-size: 13px;
+}
+
+.comp-overview-card code {
+  display: block;
+  white-space: normal;
+  line-height: 1.6;
+  color: var(--vp-c-text-2);
+}

docs/components/affix.md

@@ -0,0 +1,22 @@
+# Affix 固钉
+
+将元素钉在可视范围内。
+
+## 示例
+
+<LivePlayground :code="`
+() => {
+  return (
+    <Affix offsetTop={10}>
+      <Button size='sm'>固钉按钮</Button>
+    </Affix>
+  )
+}
+`" />
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| offsetTop | 距顶偏移 | `number` | `0` |
+| children | 内容 | `ReactNode` | - |

docs/components/alert.md

@@ -0,0 +1,32 @@
+# Alert 警告提示
+
+警告提示组件，对齐 Ant Design Alert。
+
+## 示例
+
+<LivePlayground :code="`
+() => {
+  return (
+    <Space direction='vertical' size={8}>
+      <Alert type='info' message='提示信息' description='这是一条信息提示。' />
+      <Alert type='success' message='操作成功' closable />
+      <Alert type='warning' message='警告信息' showIcon />
+      <Alert type='error' message='错误信息' description='请检查后重试。' closable />
+    </Space>
+  )
+}
+`" />
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| type | 类型 | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` |
+| message | 提示内容 | `ReactNode` | - |
+| description | 描述文案 | `ReactNode` | - |
+| closable | 可关闭 | `boolean` | `false` |
+| showIcon | 显示图标 | `boolean` | `true` |
+| icon | 自定义图标 | `ReactNode` | - |
+| banner | 横幅模式 | `boolean` | `false` |
+| action | 操作区域 | `ReactNode` | - |
+| onClose | 关闭回调 | `() => void` | - |

docs/components/anchor.md

@@ -0,0 +1,22 @@
+# Anchor 锚点
+
+锚点导航组件。
+
+## 示例
+
+<LivePlayground :code="`
+() => {
+  return (
+    <Anchor items={[
+      { key: 'a1', href: '#section-a', title: 'Section A' },
+      { key: 'a2', href: '#section-b', title: 'Section B' },
+    ]} />
+  )
+}
+`" />
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| items | 锚点项 | `AnchorItem[]` | - |

docs/components/auto-complete.md

@@ -0,0 +1,37 @@
+# AutoComplete 自动完成
+
+输入框自动完成功能，对齐 Ant Design AutoComplete。
+
+## 示例
+
+<LivePlayground :code="`
+() => {
+  return (
+    <Space direction='vertical' size={8}>
+      <AutoComplete
+        placeholder='输入搜索'
+        options={[
+          { value: 'React' },
+          { value: 'Vue' },
+          { value: 'Angular' },
+          { value: 'Svelte' },
+        ]}
+        allowClear
+      />
+    </Space>
+  )
+}
+`" />
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| options | 选项数据 | `{ value: string; label?: string }[]` | `[]` |
+| value | 当前值 | `string` | - |
+| defaultValue | 默认值 | `string` | `''` |
+| onChange | 值变化回调 | `(value: string) => void` | - |
+| onSelect | 选中回调 | `(value: string) => void` | - |
+| filterOption | 过滤方式 | `boolean \| ((input, option) => boolean)` | `true` |
+| allowClear | 允许清除 | `boolean` | `false` |
+| placeholder | 占位文本 | `string` | - |

docs/components/avatar.md

@@ -0,0 +1,25 @@
+# Avatar 头像
+
+用户头像组件。
+
+## 示例
+
+<LivePlayground :code="`
+() => {
+  return (
+    <Space>
+      <Avatar name='Alice' />
+      <Avatar name='Bob' size='lg' />
+      <Avatar src='https://i.pravatar.cc/40' />
+    </Space>
+  )
+}
+`" />
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| name | 名称（显示首字母） | `string` | - |
+| src | 图片地址 | `string` | - |
+| size | 尺寸 | `'sm' \| 'md' \| 'lg'` | `'md'` |

docs/components/back-top.md

@@ -0,0 +1,19 @@
+# BackTop 回到顶部
+
+返回页面顶部的按钮。
+
+## 示例
+
+<LivePlayground :code="`
+() => {
+  return (
+    <BackTop visibilityHeight={0} />
+  )
+}
+`" />
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| visibilityHeight | 滚动高度达到此参数值才出现 | `number` | `400` |