HeroUI（原 NextUI）

HeroUI 是 NextUI 的新名称。当前 v3 文档将其定义为开源 React 组件库，要求 React 19+ 与 Tailwind CSS v4，并基于 React Aria Components 提供行为和可访问性。v3 采用复合组件、CSS-first 主题与样式/行为分离的架构，不能沿用旧 NextUI 或 HeroUI v2 的安装方式理解。

v3 的两个核心包分工

快速开始先安装两者，再在主 CSS 中依次导入 Tailwind 和 HeroUI 样式。

复合组件让内部结构可定制

v3 将许多控件拆成真实子部件，开发者可以移动、替换或单独设样式，而不是依赖大量配置 props。灵活性也意味着团队要规定合法组合，避免不同页面自行拼出不一致的 Label、Description、Control 与错误信息顺序。

React Aria 提供行为基础

键盘导航、焦点管理、屏幕阅读器关联与按压状态来自 React Aria Components。业务封装时不要删除 id、textValue、aria-label 等必要信息；带图标或复杂内容的集合项尤其要测试 type-ahead、选中状态和朗读结果。

CSS-first 主题不再依赖旧插件

v3 通过 CSS 变量、BEM 类和 Tailwind utilities 定制，官方迁移说明指出不再使用 v2 的 HeroUI Tailwind 插件。品牌主题应覆盖背景、前景、表面、强调、圆角和状态色，并分别测试浅色、暗色、RTL 与减少动态设置。

从 v2 升级属于结构迁移

• 升级 React 19 与 Tailwind v4；
• 移除旧插件并改为 CSS imports；
• 按组件迁移指南调整 compound API；
• 集合项区分 React key、状态 id 与 textValue；
• 替换被移除的 hooks 或组件；
• 逐页回归交互、样式和焦点。

只改包版本很可能产生无声的行为差异。

动画改为 CSS 后仍需验收

v3 将大量动画转为 CSS transitions 与 keyframes，并支持系统 prefers-reduced-motion 和页面 data 属性。检查 Popover、Accordion、Toast 等进入退出状态，保证关闭动画后内容和焦点仍正常；主题覆盖不要破坏 data 状态选择器。

开源库与 HeroUI Pro 分开管理

核心库按 Apache License 2.0 开源，HeroUI Pro 的高级组件、模板和工具属于另一产品线。采用前分别记录版本和许可；团队还应关注 v3 发布说明，因为复合结构和组件 API 仍可能在小版本中出现需要迁移的调整。