Headless UI 不生成任何 CSS，仅提供语义化 HTML、ARIA 属性和可访问性状态逻辑；所有样式由开发者通过 className 显式控制，Tailwind 状态变体可直接生效，核心价值在于封装键盘导航、焦点管理、屏幕阅读器支持等 WCAG 合规交互逻辑。
Headless UI不是“CSS插件”，它根本不输出CSS
很多人误以为 @headlessui/react 是 Tailwind 的一个“样式增强插件”，其实它连一行 CSS 都不生成。它只返回语义化 HTML + ARIA 属性 + 状态逻辑，所有 class 都由你通过 className 显式传入。所谓“解决复杂 CSS 交互”，本质是把原本要手写的状态切换、焦点管理、键盘响应等逻辑，全部封装进 React 组件的 render props 或 hooks 里。
常见错误现象：自己用 div + useState 实现下拉菜单，结果 ESC 不关闭、Tab 键跳不出、屏幕阅读器读不出展开状态——这不是 CSS 写得不对，是根本没实现可访问性状态机。
-
Menu组件内部用MenuMachine管理 open/closed/activeItem 等状态，你只需关注open布尔值和active项的渲染 - 键盘事件（↑↓EnterESC）全由组件捕获并触发对应状态变更，不需要你在
useEffect里手动监听 - 每个
MenuItem自动带role="menuitem"、aria-selected、tabIndex，且随焦点实时更新
为什么Tailwind类名能直接套在Headless UI组件上不冲突？
因为 Headless UI 组件本身不带任何 class，也不 inject 样式表。你写的 className="bg-blue-500 hover:bg-blue-600 focus:ring-2" 就是最终 DOM 上唯一的 class，不存在优先级打架或 !important 覆盖问题。
使用场景：当你需要按钮在 menu 打开时变色、在 disabled 时透明、在 active 时加边框——这些都不是靠组件内置逻辑，而是靠 Tailwind 的状态变体直接作用于你传入的 className。
立即学习“前端免费学习笔记（深入）”；
-
hover:、focus:、disabled:、data-[open]:（配合data-open属性）都能正常使用 - 注意：
data-[open]:这类变体需在tailwind.config.js中启用variants: ['data'] - 不要试图给
MenuButton加group类再用group-hover:——它的子元素不是传统 DOM 子节点，而是 Portal 渲染，group 不生效
哪些交互复杂度是Headless UI真正在意的？
它不关心“圆角多少”“阴影深浅”，只处理那些人眼看不见但对键盘用户、屏幕阅读器至关重要的逻辑链。比如：
- 点击
MenuButton后，焦点必须自动移到第一个MenuItem，而不是停留在按钮上 - 按 ↓ 键时，不仅要高亮下一项，还要确保该项可被
Enter触发，且滚动容器自动调整视口 - 点击菜单外部关闭时，必须恢复上一个聚焦元素的焦点（focus trap + restore），否则键盘用户会卡死
-
Dialog打开后，背景元素必须设aria-hidden="true"，且 ESC 关闭后焦点回到触发按钮
这些逻辑散落在几十个 WCAG 指南条目里，而 Headless UI 把它们打包成可复用的状态机——你调用 useMenuState() 或直接用组件，就默认获得整套行为。
容易忽略的集成细节：Tailwind插件不是必需的
官方有个 @headlessui-tailwindcss 插件，但它只提供两个东西：peer-data-[open] 变体支持，以及一组预设颜色 class（如 ui-active:bg-blue-100）。绝大多数项目根本用不到它。
真正关键的是你自己的 tailwind.config.js 配置：
- 确保启用了
plugins: [require('@headlessui/tailwindcss')]——仅当你想用ui-open:这类自定义变体时才需要 - 更常用的是在
theme.extend.colors里定义品牌色，然后直接写bg-brand-500，而非依赖插件提供的ui-primary - 别在组件上滥用
asChild：它会透传className到内部真实 DOM 元素，但若该元素是 Portal 渲染（如MenuItems），class 实际作用在 body 下的 div 上，布局可能错乱
最常被跳过的点：状态类名必须和组件内部状态严格同步。比如 MenuItem 的 active 是它自己算的，你不能用 useState 模拟一个“当前选中项”再去比对——那会导致键盘导航高亮失效。
