设计原则

组件库的价值不只在组件数量，还在于每个组件是否容易理解、组合和长期维护。Light Components 遵循以下原则。

契约先行

每个公开属性、事件和方法都必须进入 manifest.json。编辑器、运行时、AI 服务与文档站共同消费这份契约，避免不同模块对组件能力产生不同理解。

框架无关

物料以 Web Component 交付。业务页面只依赖标准自定义元素和原生事件，不要求宿主使用与组件相同的框架。

默认即可用

组件应提供安全、可理解的默认值。用户不设置非必要属性时，组件仍应完成基础渲染，并明确展示空状态或服务不可用状态。

样式隔离

物料通过 Shadow DOM 隔离样式。组件不得依赖宿主页面的全局 class，也不能让自身样式反向污染画布和其他物料。

示例就是验证

文档示例应尽量运行真实构建产物，而不是单独绘制一份外观相似的静态效果。这样示例既是使用说明，也是最小集成验证。

中文直接表达

面向使用者的标题、说明、空状态和错误提示直接使用中文。避免晦涩缩写，让产品、设计与开发可以在同一份文档中协作。