compound-ui

Compound UI

使用此技能创建由源代码拥有的 React 组件，使其组合方式类似 shadcn/ui：由小型命名部件、显式的子元素、无障碍原语、类名合并和稳定的样式钩子组成。

工作流

1. 编写代码前检查本地 UI 技术栈：
   • 阅读项目附近的指导文档、现有组件文件、软件包版本、样式工具、原语库以及测试／故事约定。
   • 优先遵循项目现有的导出、文件、样式、图标和无障碍模式。
2. 在精确 API 很重要时更新文档：
   • 使用 references/source-map.md 获取当前源码链接和已收集的指导。
   • 在修改与框架相关的代码前，优先查阅当前 React、shadcn/ui 和本地原语文档（Radix UI、Base UI 或 React Aria）。
   • 首先确认项目使用的原语基础：components.json 中的 style，或对 radix-ui、@base-ui/react、react-aria-components 的导入。遵循其组合 API，不要混用不同基础。
3. 实现前设计公共 API：
   • 阅读 references/component-contract.md。
   • 定义根组件、命名子组件、合法嵌套方式、受控／非受控状态以及必需的无障碍部件。
4. 按 shadcn 风格实现：
   • 阅读 references/authoring-patterns.md。
   • 导出由源代码拥有的命名部件，并提供 data-slot、className 合并、属性／ref 透传以及最少的行为属性。
5. 完成前进行检查：
   • 使用 references/review-checklist.md。
   • 在适用时验证类型检查、lint、故事／浏览器行为、键盘支持、焦点、无障碍名称和响应式状态。

强制规则

• 优先使用复合部件和 children，而非属性繁多的包装器 API。如果命名子组件能更好地表达相同结构，就不要创建 title、description、actions、icon、isLoading 或布局属性。
• 将可接受的属性范围限定为：DOM 属性、className、children、项目原语基础的元素替换属性（Radix 使用 asChild，Base UI 使用 render）、受控状态、事件处理程序、无障碍属性，以及有意设置的变体（例如 variant 或 size）。
• 对话框、菜单、弹出层、标签页、选择器、工具提示、组合框、手风琴和焦点循环等复杂行为，应使用现有的无障碍原语。
• 保留原语契约。自定义插槽子元素必须展开传入的属性，并根据项目使用的 React 版本支持 ref。
• 为每个导出的部件添加 data-slot，并在有助于样式设置和测试时添加状态／变体数据属性。
• 除非部件之间必须协调，否则让状态保持在本地。仅在复合协调时使用作用域上下文；必需部件在根组件之外使用时，应明确报错。
• 仅当组件使用钩子、事件、浏览器 API 或仅限客户端的原语时，才添加 "use client"。
• 不要通过调用方无法检查或覆盖的便捷默认值，隐藏必需的无障碍支持。