核心用法
本技能提供了一套基于 CVA (class-variance-authority) 和 Surface 原语的设计系统组件构建模式，涵盖六大核心模式：
1. Surface Primitive — 统一的分层表面组件，通过 layer 变体（panel/tile/chip/deep/metric/glass）实现一致的视觉层级，支持交互状态与发光效果
2. CVA Button Variants — 完整的按钮变体系统，包含 default/destructive/outline/ghost/link/cyber 等样式及 sm/default/lg/icon 尺寸
3. Metric Display — 数据指标展示组件，支持 lg/md/sm 尺寸与 positive/negative/neutral 趋势状态
4. Card with Header — 基于 Surface 封装的卡片组件，集成标题、描述与操作区域
5. Badge/Chip Variants — 标签徽章系统，覆盖 default/success/warning/destructive/outline 变体
6. 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（纯代码模式，无外部依赖执行风险）。