#系统设计：企业级组件库

#目标

组件库的核心不是“把按钮放进 npm”，而是让多个团队获得一致、稳定、可扩展的产品语言。

#分层设计

Design Tokens
    ↓
基础组件 Button / Input / Icon
    ↓
复合组件 Form / Table / Dialog
    ↓
业务模式 SearchPanel / UserPicker

• Token 描述颜色、字号、间距和动效等设计决策。
• 基础组件保持通用和稳定。
• 业务组件与通用组件分包，避免核心包被单一业务污染。

#API 设计原则

• 优先组合而不是堆积布尔属性。
• 同类组件使用一致的命名、受控模式和事件语义。
• 通过稳定扩展点满足自定义，不暴露内部 DOM 细节。
• 默认值解决主流场景，高级能力按需启用。
• 避免把后端字段和业务枚举写进通用组件。

#构建与发布

• 输出 ESM，并按需提供兼容格式。
• 保证 Tree Shaking，样式和组件支持按需加载。
• 使用语义化版本和变更日志。
• 破坏性更新提供迁移指南、codemod 和弃用周期。
• PR 中执行类型、lint、单测、视觉回归和产物体积检查。

#文档与测试

• 每个组件提供使用场景、边界、反例和在线示例。
• 单元测试关注状态和事件。
• 交互测试覆盖键盘、弹层和表单流程。
• 视觉回归检测颜色、间距和布局变化。
• 发布后保留可搜索的版本化文档。

#主题与多品牌

主题差异通过语义 Token 表达，例如 color-text-primary，而不是在组件中硬编码品牌颜色。运行时切换可使用 CSS 自定义属性；构建时主题可用于强隔离品牌包体。

#多团队治理

• 核心维护者负责 API 和发布质量。
• RFC 记录重大设计决策。
• 使用统计帮助判断组件是否能安全废弃。
• 设定响应周期，避免业务团队因等待而复制组件。

#高频追问

• 如何避免组件 API 越来越臃肿？
• 组件库升级如何防止一次性影响所有业务？
• 如何处理样式隔离和主题切换？
• 为什么组件库不应该依赖某个业务的全局状态？