Component Development · Vibe Coding

组件开发
AI 辅助设计→代码全流程

在 AI 工具（Cursor / Claude / v0）深度介入的今天，设计师与组件开发的边界已经模糊。一个拥有扎实组件思维、清晰规范文档和 Token 体系的设计师，可以通过 Vibe Coding 将组件从设计稿直接交付为可运行的 React 代码。

以下为组件开发规范文档展示，涵盖组件拆解方法论、原子设计理论在实际项目中的应用、组件状态机设计、与研发协同的交付标准，以及真实项目中的 100+ 组件库建设实践记录。

// 组件架构设计原则

好的组件设计不是"把界面切成块"，而是找到可复用单元的正确边界。这六条原则是我在 Pisell 100+ 组件库建设中反复验证的架构准则。

// Props 设计与 Variant 体系

Props 是组件的"对外 API"。好的 Props 设计让组件易用、可预期且 AI 友好——AI 工具通过 Props 类型定义理解组件能力边界。

interface ButtonProps {
  variant:   'primary' | 'secondary' | 'ghost' | 'danger';
  size:      'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?:  boolean;
  iconLeft?: ReactNode;       // 左图标（可选）
  iconRight?:ReactNode;       // 右图标（可选）
  fullWidth?:boolean;         // 撑满容器宽度
  onClick?:  () => void;
  children:  ReactNode;
}

// 组件文档规范模板

完整的组件文档是设计系统的"说明书"，也是 AI 理解组件意图的重要依据。以下是 Pisell 组件库使用的标准文档模板：

// ✓ 推荐写法
<Button variant="primary" size="md" onClick={handleSubmit}>
  提交订单
</Button>

// ✓ 含图标
<Button variant="ghost" iconLeft={<IconDownload />}>
  导出报表
</Button>

// ✗ 避免写法 — 直接传 style 破坏 Token 体系
<Button style={{ background: '#7239ff' }}>提交</Button>

// AI-Ready 组件设计思路

AI-Ready 组件是指"AI 工具能够准确理解并生成、修改的组件"。实现 AI-Ready 需要在设计阶段就做出一系列刻意的选择。

// React 组件 × Figma 组件双向对应

Figma Code Connect（2024 年发布）实现了 Figma 组件与 React 代码的精确映射，是设计-代码协作的重要里程碑。

variant: {
  'Primary':   'primary',
  'Secondary': 'secondary',
  'Ghost':     'ghost',
  'Danger':    'danger'
},
size: {
  'Small':  'sm',
  'Medium': 'md',
  'Large':  'lg'
}