（8441期）Design System Components – CVA 驱动的设计系统组件工程

CVA 驱动的设计系统组件工程 基于 CVA 和 Surface 原语构建可复用的设计系统组件，提供类型安全的变体 API 与设计令牌一致性保障。 使用说明 核心用法 本技能提供了一套基于 CVA (class-variance-authority) 和 Surface 原语的设计系统组件构建模式，涵盖六大核心模式： Surface Primitive — 统一的分层表面组件，通过 layer 变体（panel/tile/chip/deep/metric/glass）实现一致的视觉层级，支持交互状态与发光效果 CVA Button Variants — 完整的按钮变体系统，包含 default/destructive/outline/ghost/link/cyber 等样式及 sm/default/lg/icon 尺寸 Metric Display — 数据指标展示组件，支持 lg/md/sm 尺寸与 positive/negative/neutral 趋势状态 Card with Header — 基于 Surface 封装的卡片组件，集成标题、描述与操作区域 Badge/Chip Variants — 标签徽章系统，覆盖 default/success/warning/destructive/outline 变体 Composing Variants — CVA 与条件类名组合模式，处理动态状态如在线指示器 显著优点 类型安全: CVA 自动生成 TypeScript 变体类型，IDE 智能提示完备 设计令牌一致性: 强制使用 bg-tone-、border-tone- 等语义化令牌，杜绝硬编码 组合灵活性: Surface 原语覆盖 90% 容器场景，减少自定义卡片实现 开发效率: cn() 工具函数处理类名合并，条件渲染简洁 可维护性: 变体逻辑集中管理，样式变更单点修改 潜在局限 学习曲线: 需理解 CVA 变体语法与 Tailwind 类名优先级规则 运行时开销: CVA 在运行时计算类名字符串，高频渲染场景（如大数据表格）需注意性能 设计令牌耦合: 强依赖预设的 tone-、glass- 等令牌，迁移至其他设计系统需重构 无障碍支持: 示例中未内置 ARIA 属性，需开发者自行补充 适合人群 使用 React + Tailwind CSS 构建组件库的前端工程师 需要建立企业级设计系统的技术负责人 追求类型安全与样式一致性的 TypeScript 开发者 熟悉 Shadcn UI 设计理念的开发者（模式高度兼容） 常规风险 | 风险类型 | 说明 | 缓解建议 ||---------|------|---------|| 类名冲突 | cn() 合并时 Tailwind 优先级可能非预期 | 使用 tailwind-merge 确保正确覆盖 || 令牌漂移 | 硬编码颜色绕过设计系统 | ESLint 规则强制 tone-* 前缀使用 || 过度抽象 | Surface 无法满足特殊场景时强行套用 | 文档明确「NEVER」条款，允许合理例外 || 无障碍缺陷 | 交互组件缺少键盘与屏幕阅读器支持 | 结合 @radix-ui 原语补充 A11y | 本技能属于 T2 来源（行业最佳实践聚合），安全性评级 A（纯代码模式，无外部依赖执行风险）。 原始说明 Patterns for building design system components using Surface primitives, CVA variants, and consistent styling. Use when building reusable UI components that follow design token architecture. Triggers on Surface component, CVA, class-variance-authority, component variants, design tokens.