用途：为 React 界面中的卡片、按钮、输入框等元素添加边缘光束动画，作为加载、处理中、选中、当前、聚焦和按下等状态的装饰性强调。核心原则是光束只做视觉点缀，状态本身仍需通过文字、形状、对比度和正确的语义属性表达。
主要能力：border-beam 提供五种尺寸预设——sm（紧凑移动边框，适合图标按钮与胶囊控件）、md（完整移动边框，适合选中卡片与当前面板）、line（底部移动边线，适合搜索、输入、进度或命令栏）、pulse-inner（内部呼吸光，适合加载卡片与持续选中态）、pulse-outside（向外呼吸光晕，适合单一突出任务）。配色变体有 colorful、mono、ocean、sunset；主题支持 dark、light、auto；还可设置 strength、duration、active、borderRadius、brightness、saturation、hueRange、staticColors 等。active 淡入约 0.6 秒、淡出约 0.5 秒，并提供 onActivate、onDeactivate 回调。
使用方式：用仓库所用包管理器安装 border-beam（npm install border-beam、pnpm add border-beam、yarn add border-beam 或 bun add border-beam），要求 React 与 React DOM 18 及以上。推荐具名导入 import { BorderBeam } from "border-beam"，也支持默认导入。组件会注入作用域样式，无需单独引入 CSS。在 Next.js App Router 中需放在客户端组件内使用。建议保持组件挂载、通过 active 切换状态，而不是在状态为 false 时卸载，否则会跳过内置淡出。
适用场景与限制：适合加载、处理、选中、当前、聚焦和短时激活反馈。加载态应显示可见状态文字或进度值，约 150ms 内完成的操作不建议显示光束，显示后保持约 400ms 至 600ms 避免闪烁。选中态需配合 aria-selected、aria-current 或 aria-pressed，并保留静态选中样式。聚焦态应保留 :focus-visible 轮廓。需处理 prefers-reduced-motion，脉冲预设会自动停止动画，旋转与 line 预设需由使用方禁用，并提供静态回退样式。组件渲染为 div，应放在 li、td、label 等语义父元素内部；sm、md、line、pulse-inner 会裁剪溢出，菜单或提示框不应放在其中；pulse-outside 使用 overflow: visible，子元素需不透明且布局需允许光晕外溢。每屏建议只用一个主导动画光束。API 基于 border-beam 1.3.0 验证，版本变化时应重新核对官方 README 与导出类型。