核心用法
本技能提供系统化的前端组件设计方法论，主要服务于 React/Vue 组件的 API 设计与架构决策。核心使用场景包括：从零设计新组件、重构现有组件 API、判断组件拆分时机、制定 Props 命名规范等。
使用时需先判断用户所处阶段：
- 从零设计：先澄清使用场景（通用 vs 业务）、调用方、技术栈约束，区分通用组件（中性、可覆盖、不自取数据）与业务组件（可带语义、样式可写死）的设计原则
- 改造现有组件：先阅读代码定位问题（props 过多？职责不清？），再针对性给出改法
- 具体决策：直接给出场景化建议并附理由
Props 设计决策规则
| 场景 | 建议 |
|------|------|
| 能用 children 表达 | 不加 prop（如 `<Button icon={<Icon />}>` 优于 `iconName` 字符串） || 仅一处使用的特殊行为 | 调用方处理，不加 prop |
| 三处以上需要 | 加 prop |
| 两种状态 | 布尔（`disabled`） |
| 三种及以上 | 枚举（`variant="primary\|secondary"`） |
| 需外部控制 | 受控模式 `value` + `onChange` |
| 独立使用 | 非受控 `defaultValue` |
| 表单/按钮类 | 必须透传 HTML 属性（`...rest`）支持 `aria-*`、`data-*` |
文件结构规范
- <150 行无子组件：单
.tsx文件 - 有样式/子组件：目录化结构（
index.tsx+ 实现 +types.ts+ 样式） - 避免过早拆分，按需演进
显著优点
1. 决策框架清晰：将模糊的「怎么设计好」转化为可执行的判断规则（3 处以上才加 prop、布尔 vs 枚举的量化标准）
2. 反例驱动教学：每个正确做法配对错误示例，降低理解成本
3. 场景化区分：通用组件与业务组件的双轨设计原则，避免一刀切
4. 工程实践完整：涵盖 TypeScript 类型、受控/非受控、无障碍透传、文件结构等落地细节
潜在局限
1. 框架偏向：示例以 React 为主，Vue 开发者需自行映射（slots ↔ render props，emit ↔ onXxx）
2. 生态依赖：Radix/shadcn/Tailwind 的建议需根据实际项目调整
3. 复杂度边界：对超大型组件库（如 Ant Design 级别）的跨组件依赖、版本兼容性等未深入涉及
适合人群
- 中级前端工程师：系统提升组件设计能力，摆脱「凭感觉设计」
- 技术负责人：建立团队组件规范，统一代码评审标准
- 全栈开发者：快速产出可维护的 UI 层代码
常规风险
- 过度设计陷阱：技能虽强调「职责单一」，但初学者可能在业务组件上套用通用组件的「绝对中性」原则，导致不必要的抽象层
- 透传滥用：盲目
...rest可能引入非预期的 HTML 属性，需配合类型约束（Omit<HTMLAttributes, 'customProp'>） - 受控/非受控混淆：同时支持两种模式时，内部状态管理复杂度上升，需确保
useControllableState类实现无 bug