aurora-admin/DOCS_GAP_ANALYSIS.md

Kole UI 对比现代主流组件库文档深度分析与演进方案

分析基准：对标 Ant Design 5.x、Element Plus、Shadcn UI / Radix UI、Arco Design、Semi Design、Mantine 等现代主流组件库文档体系。
审计对象：Kole UI 组件库文档站（site/）、规范集（组件1~10.txt）、实现集（frameworks/ 79 组件 × 5 端代码）。
制定时间：2026-09-07

---

1. 核心结论与横向对比矩阵

Kole UI 当前已经完成了极高完成度的**“资产沉淀”**：79 个组件涵盖 6 大类别、395 个多端文件（H5/CSS/JSX/Vue2/Vue3）、71 项设计 Token 以及 8 项自动化测试断言。

然而，以成熟企业级组件库的**“开发者消费”与“设计协作”视角**衡量，当前文档站与主流开源组件库之间存在以下六大结构性断层：

维度	主流组件库标配（AntD / Element / Shadcn）	Kole UI 现状	差距等级	影响分析
1. API 规范表	完整的 Props / Events / Slots / Methods / TS 类型表格	无任何参数表格（0/79 覆盖）	🔴 致命	开发者无法查阅属性与参数，只能肉眼翻看源码
2. 代码演示交互	场景化微用例（5~10个独立卡片） + 实时演练场（Playground）	单一静态全屏 iframe 粗暴嵌入，所有变体堆叠	🟠 严重	无法单独复制指定变体代码，缺少实时调节属性体验
3. 工程化与引入	NPM 包管理（import { X }）、自动按需导入、现代 CLI（npx add）	本地相对路径目录拷贝	🟡 中度	缺少标准包依赖体系与自动化脚手架消费方式
4. 设计系统指南	Do's & Don'ts 避坑对比、组件级 CSS Token 映射表、Figma Kit	仅全局 71 个 Token，无组件级定制变量与正反面图示	🟡 中度	业务团队易发生反模式设计滥用，二次换色定制困难
5. 无障碍 (A11y)	键盘交互行为表（Keyboard Navigation）、ARIA 角色与状态契约	测试页有自动化断言，但文档正文无任何使用指引	🟡 中度	开发者不知道该组件有哪些键盘快捷键与焦点规则
6. 浏览体验 (DX)	语法高亮着色、深色模式切换、FAQ 踩坑排查、小屏响应式	纯黑白 <pre> 代码块、浅色-only、无 FAQ	🟢 体验	开发者阅读体验单调，缺少实战排错参考

---

2. 六大断层深度剖析

2.1 断层一：缺失结构化组件 API 表格（Props / Events / Slots / Methods）

• 行业基准：
  • 开发者访问组件库文档 80% 的高频操作是直奔页面底部的 API 表。
  • 标准表项包含：
    1. 属性（Props）：参数名、中文说明、TypeScript 类型（精确联合类型，如 'primary' | 'default' | 'danger'）、默认值、必填项标记、支持版本。
    2. 事件（Events / Emits）：事件名（如 @click、@change）、触发时机、回调函数参数签名 (event: MouseEvent) => void。
    3. 插槽（Slots）：插槽名称（default、icon、header）、插槽上下文作用域（Slot Props）。
    4. 组件实例方法（Expose / Methods）：focus()、blur()、validate()。
• Kole 现状与潜力：
  • 现状：详情页只提供“何时使用”段落和静态源码查看器，未提炼属性。
  • 潜力：实际上 frameworks/*.vue3.vue 中已严格声明了 defineProps，frameworks/*.jsx 中声明了参数解构。文档站点只需挂载自动语法提取器即可全面补齐 79 个组件的 API 表。

---

2.2 断层二：场景化独立微用例（Demos）与演练场（Playground）

• 行业基准：
  • 拆解粒度：以 Button 为例，AntD 拆分为“按钮类型”、“图标按钮”、“按钮尺寸”、“加载中状态”、“禁用状态”、“幽灵按钮”、“危险按钮”等 7 个独立卡片。
  • 交互体验：每个卡片右下角具备「展开代码」、「复制代码」、「在 CodeSandbox / StackBlitz 打开」。
  • 属性演练场（Configurator / Playground）：Mantine、Chakra、Semi 标配交互式调试器。右侧是一排开关和下拉菜单，操作时上方组件实时响应，下方实时生成匹配的调用代码。
• Kole 现状：
  • 目前是一个生硬的单个 iframe 加载全量演示页。展开代码也是上百行的完整文件源码，无法快速复制某个特定场景（如只要一个小尺寸危险按钮的代码）。

---

2.3 断层三：现代包生态与 CLI 代码分发链路

• 行业基准：
  • 传统重型库模式：pnpm add @kole-ui/vue，配合 unplugin-vue-components 做到零导入按需打包。
  • 现代轻量库模式（Shadcn UI 范式）：npx kole-ui add button，将零依赖源码直接写入开发者的 src/components/ui/，开发者拥有 100% 的修改自由度。
• Kole 现状：
  • 目前仅提供文件下载与相对路径引用，缺乏标准 Package 发布规范（package.json、exports 字段、类型声明文件 .d.ts）与脚手架工具。

---

2.4 断层四：设计系统深度——Do's & Don'ts 避坑原则与组件级 Token

• 行业基准（Shopify Polaris / Ant Design）：
  • Do's & Don'ts：
    • ✅ 推荐：一个表单/操作区只配置一个主行动按钮（Primary Button）。
    • ❌ 避免：避免同时并列两个主按钮，避免在主要提交操作使用弱化文字按钮。
  • 组件级 Token 映射：
    • 全局 Token 是 --kole-color-brand，而组件级应映射为 --kole-button-primary-bg: var(--kole-color-brand)。开发者在定制某个按钮时无需侵入底层 CSS 规则。

---

2.5 断层五：无障碍（Accessibility / A11y）面向使用者的指引

• 行业基准（Radix UI / W3C WAI-ARIA）：
  • 每个交互组件均配有清晰的 键盘交互表：

    按键	说明
    Tab	将焦点移入当前组件
    Enter / Space	激活按钮或切换开关状态
    Esc	关闭弹窗或收起下拉选择器
    ↑ / ↓	在选项列表中上下切换聚焦

• Kole 现状：
  • 测试页中已建立 8 项自动化断言，但文档正文中未向开发者说明键盘交互契约。

---

2.6 断层六：文档站 DX / UX 基础细节打磨

• 行业基准：
  • 语法高亮（Syntax Highlighting）：代码块具有标签（红/粉）、属性（黄）、字符串（绿）、关键字（蓝/紫）等高辨识度着色。
  • 深色模式（Dark Mode）：支持 Light / Dark / System 三态自由切换。
  • FAQ 常见问题排查：列出实际集成中常见痛点（如表单校验不同步、层级穿透等）。

---

3. 渐进式演进与落地方案

针对上述六大断层，建议分三个阶段落地推进：

graph TD
  A[当前 Kole UI 文档站] --> B[P0: 核心突破 (本轮落地)]
  A --> C[P1: 体验与设计闭环]
  A --> D[P2: 生态与工程化]

  B --> B1[自动提取全组件 Props/Emits/Slots 表格]
  B --> B2[纯原生零依赖语法高亮着色]
  B --> B3[组件级无障碍键盘交互速查表]
  B --> B4[Do's & Don'ts 场景规范卡片]

  C --> C1[多场景微用例卡片拆分]
  C --> C2[深色模式/双主题适配]
  C --> C3[组件级 CSS 变量定制清单]

  D --> D1[npm 包发布规范与 TypeScript .d.ts]
  D --> D2[轻量 CLI 代码拉取工具]
  D --> D3[交互式 Playground 配置演练场]

---

4. 本次 P0 实施清单（已全面集成到工作区）

1. 自动 API 参数表生成器（集成至 site/app.js）：
   • 纯前端实时解析 frameworks/*.vue3.vue 与 *.jsx 中的参数声明；
   • 提取参数名、数据类型、默认值、必填标记、行内注释；
   • 生成响应式、美观的「组件 API 属性表」与「事件表」。
2. 轻量纯原生语法高亮系统（集成至 site/app.js 与 site/style.css）：
   • 保持 0 依赖，用精巧的词法正则对 HTML、Vue Template、JSX、CSS 进行着色；
   • 涵盖标签、属性名、字符串、注释、关键字高亮。
3. 无障碍键盘交互指引表（A11y Reference）：
   • 针对通用交互组件自动生成键盘操作标准规范。
4. 设计原则（Do's & Don'ts）标准卡片：
   • 为核心交互组件增加图文并茂的使用禁忌与最佳实践。