shadcn-vue-mcp

# 高质量UI组件标准定义 ## 概述 本文档定义了shadcn-vue UI组件生成MCP Server所生成组件必须达到的"高质量"标准。这些标准将作为组件生成、验证和优化的基准。**特别地，这些标准也适用于生成的包含内部Mock数据的纯展示型组件，其设计应便于开发者理解组件结构并能轻松替换为真实数据源。** ## 🎯 五大核心维度 ### 1. 可访问性 (Accessibility - A11y) #### 1.1 核心要求 - **WCAG 2.1 AA级别合规**：所有组件必须符合WCAG 2.1 AA级别的可访问性指南 - **语义化HTML**：使用正确的HTML5语义标签和ARIA属性 - **键盘导航**：支持完整的键盘操作，遵循标准的焦点管理模式 #### 1.2 具体标准 ```typescript // 可访问性检查清单 interface A11yStandards { // 语义化 semanticHTML: { properHTMLTags: boolean; // 使用正确的HTML标签 meaningfulHeadings: boolean; // 有意义的标题层级 landmarkRoles: boolean; // 正确的地标角色 }; // ARIA支持 ariaSupport: { ariaLabels: boolean; // 必要的aria-label ariaDescribedby: boolean; // 描述性关联 ariaStates: boolean; // 状态管理(aria-expanded, aria-selected等) ariaLive: boolean; // 动态内容公告 }; // 键盘导航 keyboardNavigation: { tabIndex: boolean; // 正确的tab索引 focusManagement: boolean; // 焦点管理 keyboardShortcuts: boolean; // 标准键盘快捷键支持 escapeKey: boolean; // ESC键退出支持 }; // 视觉设计 visualDesign: { colorContrast: number; // 最低4.5:1对比度 focusIndicators: boolean; // 清晰的焦点指示器 textSize: boolean; // 可调整文字大小 motionReduction: boolean; // 减少动画选项 }; } ``` #### 1.3 测试要求 - **自动化测试**：使用axe-core进行自动化A11y测试 - **屏幕阅读器测试**：确保与NVDA/JAWS/VoiceOver兼容 - **键盘测试**：所有功能可通过键盘完成 - **颜色对比度测试**：所有文字颜色组合符合WCAG标准 ### 2. 性能 (Performance) #### 2.1 核心要求 - **快速加载**：组件初始化时间 < 100ms - **高效渲染**：避免不必要的重新渲染 - **内存优化**：无内存泄漏，合理的内存使用 - **轻量化**：避免在生产环境中包含不必要的、仅用于初始展示的大量Mock数据。 #### 2.2 具体标准 ```typescript interface PerformanceStandards { // 加载性能 loading: { bundleSize: number; // 单个组件 < 50KB (gzipped) (生产构建中应注意剥离或优化Mock数据对体积的影响) initialRender: number; // 初始渲染 < 100ms codeReady: number; // 代码就绪时间 < 50ms }; // 运行时性能 runtime: { rerenderOptimization: boolean; // 使用Vue3响应式优化 lazyLoading: boolean; // 支持懒加载 virtualScrolling: boolean; // 大列表虚拟滚动(适用时) memoization: boolean; // 合理使用computed/memo }; // 内存管理 memory: { noMemoryLeaks: boolean; // 无内存泄漏 eventCleanup: boolean; // 事件监听器清理 observerCleanup: boolean; // Observer清理 timersCleanup: boolean; // 定时器清理 }; // 网络优化 network: { treeshaking: boolean; // 支持Tree-shaking codesplitting: boolean; // 支持代码分割 assetOptimization: boolean; // 资源优化 }; } ``` #### 2.3 性能基准 - **First Contentful Paint (FCP)**：< 1.5s - **Largest Contentful Paint (LCP)**：< 2.5s - **Cumulative Layout Shift (CLS)**：< 0.1 - **First Input Delay (FID)**：< 100ms ### 3. 一致性 (Consistency) #### 3.1 核心要求 - **设计一致性**：遵循shadcn-vue设计系统 - **行为一致性**：相似组件有相似的交互模式 - **API一致性**：统一的props命名和事件约定 #### 3.2 具体标准 ```typescript interface ConsistencyStandards { // 设计一致性 design: { designTokens: boolean; // 使用统一的设计Token colorPalette: boolean; // 遵循调色板 typography: boolean; // 一致的字体规范 spacing: boolean; // 统一的间距系统 borderRadius: boolean; // 一致的圆角规范 }; // 组件API一致性 api: { propsNaming: boolean; // 统一的props命名约定 eventNaming: boolean; // 统一的事件命名约定 slotNaming: boolean; // 统一的插槽命名约定 methodNaming: boolean; // 统一的方法命名约定 }; // 行为一致性 behavior: { interactionPatterns: boolean; // 一致的交互模式 stateManagement: boolean; // 一致的状态管理 errorHandling: boolean; // 一致的错误处理 loadingStates: boolean; // 一致的加载状态 }; // 代码风格一致性 codeStyle: { tsTypes: boolean; // TypeScript类型定义 documentation: boolean; // JSDoc文档注释 testCoverage: boolean; // 测试覆盖率 > 80% linting: boolean; // ESLint/Prettier规范 }; } ``` #### 3.3 设计系统集成 - **颜色系统**：使用CSS自定义属性定义的主题颜色 - **间距系统**：基于4px/8px网格的间距规范 - **字体系统**：定义的字体大小和行高比例 - **阴影系统**：统一的阴影层级定义 ### 4. 可维护性 (Maintainability) #### 4.1 核心要求 - **代码清晰**：易读易懂的代码结构 - **模块化设计**：良好的关注点分离 - **文档完整**：完善的文档和注释 #### 4.2 具体标准 ```typescript interface MaintainabilityStandards { // 代码结构 codeStructure: { singleResponsibility: boolean; // 单一职责原则 compositionAPI: boolean; // 使用Composition API customHooks: boolean; // 提取可复用逻辑 propValidation: boolean; // Props类型验证 (纯展示组件的核心数据接口) clearMockDataStructure: boolean; // 清晰的Mock数据结构，易于理解和替换 }; // 代码质量 codeQuality: { cyclomaticComplexity: number; // 圈复杂度 < 10 codeReusability: boolean; // 代码复用性 errorBoundaries: boolean; // 错误边界处理 gracefulDegradation: boolean; // 优雅降级 }; // 文档与注释 documentation: { jsdocComments: boolean; // JSDoc注释 propTypes: boolean; // Props类型文档 usageExamples: boolean; // 使用示例 migrationGuides: boolean; // 迁移指南(当需要时) }; // 版本管理 versioning: { semanticVersioning: boolean; // 语义化版本 changelog: boolean; // 变更日志 breakingChanges: boolean; // 破坏性变更警告 deprecationWarnings: boolean; // 弃用警告 }; } ``` #### 4.3 代码质量指标 - **圈复杂度**：< 10 - **代码重复率**：< 5% - **测试覆盖率**：> 80% - **技术债务比率**：< 10% ### 5. 开发者体验 (Developer Experience - DX) #### 5.1 核心要求 - **易于使用**：直观的API设计和清晰的文档 - **开发友好**：良好的TypeScript支持和开发工具集成 - **快速上手**：完整的示例和最佳实践指导 - **易于集成**：生成的包含Mock数据的组件代码片段，应能方便地适配和接入真实数据源。 #### 5.2 具体标准 ```typescript interface DeveloperExperienceStandards { // API设计 apiDesign: { intuitive: boolean; // 直观的API命名 predictable: boolean; // 可预测的行为 composable: boolean; // 可组合性 flexible: boolean; // 灵活的配置选项 }; // TypeScript支持 typeScript: { strictTypes: boolean; // 严格的类型定义 genericSupport: boolean; // 泛型支持 autocompletion: boolean; // IDE自动补全 typeInference: boolean; // 类型推断 }; // 开发工具 devTools: { hotReload: boolean; // 热重载支持 devtoolsIntegration: boolean; // Vue devtools集成 errorMessages: boolean; // 清晰的错误信息 warnings: boolean; // 有用的警告信息 }; // 学习曲线 learningCurve: { documentation: boolean; // 完整的文档 examples: boolean; // 丰富的示例 playground: boolean; // 在线演示 tutorials: boolean; // 教程指南 mockDataGuidance: boolean; // 清晰的Mock数据替换指引 }; } ``` #### 5.3 文档要求 - **API文档**：完整的props、events、slots、methods文档 - **使用示例**：基础用法、高级用法、自定义案例 - **最佳实践**：性能优化、可访问性、常见陷阱 - **故障排除**：常见问题和解决方案 - **Mock数据指引**：清晰说明内部Mock数据的结构、用途，以及如何通过Props传入真实数据进行替换。 ## 📏 质量评分系统 ### 评分标准 每个维度满分100分，总分500分： ```typescript interface QualityScore { accessibility: number; // 0-100分 performance: number; // 0-100分 consistency: number; // 0-100分 maintainability: number; // 0-100分 developerExperience: number; // 0-100分 totalScore: number; // 0-500分 grade: "A+" | "A" | "B+" | "B" | "C" | "F"; // 等级评定 } ``` ### 等级定义 - **A+ (450-500分)**：卓越级别，行业标杆 - **A (400-449分)**：优秀级别，高质量组件 - **B+ (350-399分)**：良好级别，符合基本要求 - **B (300-349分)**：及格级别，需要改进 - **C (200-299分)**：较差级别，需要大幅改进 - **F (0-199分)**：不合格，不可发布 ## 🔍 验证流程 ### 自动化检查 1. **ESLint/Prettier**：代码风格检查 2. **TypeScript**：类型检查 3. **Vitest**：单元测试 4. **axe-core**：可访问性测试 5. **Lighthouse**：性能测试 ### 手动检查 1. **代码审查**：人工代码质量检查 2. **可用性测试**：用户体验测试 3. **设计审查**：设计一致性检查 4. **文档审查**：文档完整性检查 ## 📋 实施计划 ### 立即执行 - [ ] 建立自动化质量检查流程 - [ ] 创建组件质量评分工具 - [ ] 制定代码审查清单 ### 短期目标 (1-2个月) - [ ] 所有新生成组件达到B+级别 - [ ] 建立持续集成质量门禁 - [ ] 完善文档模板和示例 ### 长期目标 (3-6个月) - [ ] 90%的组件达到A级别 - [ ] 建立质量趋势分析 - [ ] 社区反馈与改进机制 --- _本标准文档将随着shadcn-vue生态系统的发展而持续更新和完善。_