核心原则

组合性与可重用性

倾向于使用组合而非继承 —— 构建可以组合和嵌套以创建更复杂 UI 的组件，而不是依赖于深层类层级。

可组合的组件通过清晰的 API（通过 props/slots）暴露出来，允许开发者通过插入子元素或回调来自定义行为和外观。

这使得组件在不同上下文中高度可重用。（React 的设计强化了这一点：“Props 和 组合为你以明确且安全的方式自定义组件外观和行为提供了所需的全部灵活性。”）

默认可访问性

组件必须对所有用户可用。使用与组件角色相匹配的语义 HTML 元素（例如用于可点击操作的 <button>、用于列表的 <ul>/<li> 等），并在必要时使用 WAI-ARIA 属性进行增强。

确保支持键盘导航和焦点管理（例如菜单中的方向键导航、模态框中的焦点陷阱）。每个组件应开箱即用地遵守可访问性标准和指南。

这意味着要提供适当的 ARIA 角色/状态并使用屏幕阅读器进行测试。可访问性不是可选项——它是每个组件的基础功能。

可定制性与主题化

组件应该易于重新样式化或适配不同的设计需求。避免硬编码且无法覆盖的视觉样式。

提供主题和样式化机制，例如 CSS 变量、清楚记录的类名或样式 props。理想情况下，组件应带有合理的默认样式，但允许开发者以最小的代价自定义外观（例如通过传入 className 或使用设计令牌）。

这一原则确保组件能融入任何品牌或设计系统，而不会与默认样式“相互冲突”。

轻量且高性能

在资源和依赖方面，组件应尽可能精简。避免使用大型库依赖或过于复杂的逻辑来使组件膨胀，尤其是在这些逻辑并非总是需要的情况下。

通过最小化不必要的重渲染并为繁重任务使用高效算法，力求在渲染和交互方面都具有良好性能。如果组件是数据密集型（例如大型列表或表格），可以考虑虚拟化或增量渲染等模式，但应将此类功能作为可选项。

轻量组件更易维护，并为最终用户提供更快的体验。

透明性与代码所有权

在开源环境中，使用者通常受益于对组件代码的完全可见性和控制权。本规范鼓励“以开源为先”的心态：组件不应是黑盒。

当开发者导入或复制你的组件时，应能够检查其工作原理并在需要时修改它。该原则是新兴“复制粘贴”分发模型（后文讨论）的基础，在该模型中，开发者将组件代码直接集成到他们的项目中。

通过赋予用户代码所有权，可以增加信任并允许更深入的定制。

即使你通过包分发，也应通过提供 source maps、可读代码和详尽的文档来践行透明性。

文档完善且对开发者体验 (DX) 友好

优秀的组件不仅仅是代码——它还应附带清晰的文档和示例。从开发者体验（DX）的角度来看，你的组件应易于学习和集成。

记录每个组件的用途、props 和使用示例。包含关于可访问性的说明（例如使用的键盘控制或 ARIA 属性）以及任何自定义选项。

良好的文档可减少误用并降低采用门槛。我们将在发布部分讨论文档期望，但在此将其列为一项原则，因为规划良好的文档和 DX 应在设计/构建阶段进行。