aurora-admin
f1fbfc2ddb
Regression / regression (push) Canceled after 0s
## 品牌标识（本次会话） 起因：品牌此前没有任何图形标识 —— 唯一 favicon 是内联 data-URI 里的字母「A」， 那是 v2.0.0「Aurora Admin → Kole UI」改名漏掉的一处（PC 顶栏也是「A」， 移动端站已是「K」；移动端文档站则完全没有 favicon）。 - 几何：24 网格三个互不接触的笔画（竖 + 两斜），圆头描边； 描边 2.25 → 16px 标签页尺寸下正好 1.5px = 规范原文「描边1.5px」 - 取色分两套（刻意）：favicon 硬编码品牌蓝/白（渲染在浏览器标签栏，不继承 kole-dark）； 顶栏标记走 currentColor（实测暗色下自动转 rgb(20,22,28)） - 新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg） - 修 site/app.js hero 标语 KOLE ADMIN → KOLE UI（改名变形残留） - 移动端 7 个模板补 favicon（此前计数 0） 验收：门禁 9 条全 OK（site-routing/site-routes/mobile-docs/mobile-site/isolation/ theme/nav/i18n/icons）；PC 回归 1464/1464 · 移动端 807/807，各连跑 8 次一致； 两端 favicon 405 字节逐字节一致；PC 站控制台错误 1→0。 ## 并行会话成果（本次一并入库） - 图标系统：2576 图标（TDesign/Element Plus，MIT）+ 11 端注入 + 5 个构建门禁工具 + IconPreview 预览页 + ICON-SPEC.md 冻结规格 - 移动端平台：47 组件 × 6 端 + 文档站 53 页 + 隔离门禁 - PC 组件：103 个大后台组件 / 组件11 批次 - uni-app：PC 端试点 + 移动端端实现 + 真实编译验证 ## 工程 - .gitignore 补 .scratch/ 与 .zcode-preexisting-*.txt（会话中间产物，实测 9.1MB，不入库） - CHANGELOG 补品牌标识条目 - ROADMAP 登 S8-P4（品牌标识任务包 + og:image/apple-touch-icon 未做部分）
132 lines
8.3 KiB
Markdown
132 lines
8.3 KiB
Markdown
# 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. 渐进式演进与落地方案
|
||
|
||
针对上述六大断层，建议分三个阶段落地推进：
|
||
|
||
```mermaid
|
||
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）标准卡片**：
|
||
- 为核心交互组件增加图文并茂的使用禁忌与最佳实践。
|