base-ui

name: base-ui description: Use this skill when working with Base UI (@base-ui-components/react) - MUI's unstyled React component library. This skill provides comprehensive API documentation, component references, and best practices for building accessible, composable UIs. Use it when: (1) Looking up Base UI component APIs and props, (2) Implementing specific components like Dialog, Menu, Form, Select, etc., (3) Styling and customizing Base UI components, (4) Following Base UI best practices for accessibility and composition, (5) Any task involving @base-ui-components/react package. The skill includes complete documentation for all 34+ components, handbook guides (styling, animation, composition, customization, TypeScript), and utility functions.

Base UI

Base UI 是 MUI 的无样式 React 组件库 (@base-ui-components/react)，提供了一套高质量、可访问、可组合的 UI 组件和工具。本 skill 提供完整的 API 文档、组件参考和最佳实践指南。

快速开始

当使用 Base UI 时，按以下流程操作：

搜索组件 - 使用搜索脚本查找所需组件
查阅文档 - 阅读组件的完整 API 文档和使用示例
参考指南 - 查看 Handbook 了解样式、动画、组合等最佳实践

搜索组件

使用搜索脚本快速查找组件和文档：

# 搜索关键词（支持中文和英文）
python scripts/search.py <query>

# 示例
python scripts/search.py button
python scripts/search.py 表单
python scripts/search.py dialog

# 列出所有组件
python scripts/search.py --list

# 列出指定类别的组件
python scripts/search.py --cat components
python scripts/search.py --cat handbook

组件分类

表单组件 (Form Components)

用于构建表单和收集用户输入的组件：

Form - 带有整合错误处理的表单组件
Field - 为表单控件提供标签和验证
Fieldset - 带有可轻松样式化图例的字段集
Input - 输入框组件
Checkbox - 复选框组件
Checkbox Group - 为一系列复选框提供共享状态
Radio - 单选按钮组件
Number Field - 带有增减按钮的数字字段
Select - 下拉选择器
Combobox - 输入与预定义项列表组合
Autocomplete - 带有过滤选项列表的自动完成输入
Switch - 开关组件
Slider - 滑块组件
Toggle - 两态按钮
Toggle Group - 切换按钮组

导航组件 (Navigation Components)

用于构建导航和菜单的组件：

Menu - 下拉菜单，增强键盘导航
Menubar - 应用程序的菜单栏
Navigation Menu - 网站导航菜单
Tabs - 标签页组件

反馈组件 (Feedback Components)

用于显示信息和状态的组件：

Dialog - 对话框/模态框
Alert Dialog - 警告对话框
Popover - 弹出框
Tooltip - 工具提示
Toast - 通知提示
Progress - 进度条
Meter - 仪表组件（显示数值）
Preview Card - 链接悬停时的预览卡片

布局组件 (Layout Components)

用于布局和分隔的组件：

Separator - 分隔符组件
Scroll Area - 自定义滚动条容器
Toolbar - 工具栏

展开组件 (Disclosure Components)

用于显示/隐藏内容的组件：

Accordion - 手风琴（可折叠面板）
Collapsible - 可折叠组件

其他组件 (Other Components)

Avatar - 头像组件
Context Menu - 右键上下文菜单

Handbook 指南

Base UI 的最佳实践和高级用法指南：

Styling (样式)

了解如何使用首选样式引擎为 Base UI 组件设置样式，包括 CSS、CSS-in-JS、Tailwind 等。

文档位置: references/base-ui-docs/handbook/styling.md

Animation (动画)

学习如何为 Base UI 组件添加动画效果，包括过渡、关键帧动画等。

文档位置: references/base-ui-docs/handbook/animation.md

Composition (组合)

了解如何将 Base UI 组件与自定义 React 组件组合使用，构建更复杂的 UI。

文档位置: references/base-ui-docs/handbook/composition.md

Customization (自定义)

学习如何自定义 Base UI 组件的行为，包括事件处理、状态管理等。

文档位置: references/base-ui-docs/handbook/customization.md

TypeScript

TypeScript 使用指南，包括类型定义、泛型、类型推断等。

文档位置: references/base-ui-docs/handbook/typescript.md

工具函数 (Utilities)

Direction Provider

为 Base UI 组件启用 RTL（从右到左）行为的方向提供者。

文档位置: references/base-ui-docs/utils/direction-provider.md

useRender

在自定义组件中启用渲染属性的钩子。

文档位置: references/base-ui-docs/utils/use-render.md

概述文档 (Overview)

Quick Start - 快速入门指南
- 文档位置: references/base-ui-docs/overview/quick-start.md
Accessibility - 无障碍访问功能和指南
- 文档位置: references/base-ui-docs/overview/accessibility.md
Releases - 各版本的更新日志
- 文档位置: references/base-ui-docs/overview/releases.md
About Base UI - 库的历史、团队和目标概述
- 文档位置: references/base-ui-docs/overview/about.md

使用示例

查找组件 API

当用户询问某个组件的 API 时：

使用搜索脚本查找组件
读取对应的文档文件
提供完整的 API 说明和示例

示例：

# 查找 Dialog 组件
python scripts/search.py dialog

# 读取文档
cat references/base-ui-docs/components/dialog.md

实现组件功能

当用户要求实现某个组件功能时：

搜索并找到相关组件
查阅文档了解 props 和用法
参考 Handbook 了解最佳实践
提供完整的实现代码

样式自定义

当用户需要自定义组件样式时：

查阅组件文档的样式部分
参考 handbook/styling.md 了解样式方法
根据用户使用的样式框架提供相应方案

核心特性

无障碍访问 (Accessibility)

Base UI 组件内置了完整的无障碍访问支持，遵循 WAI-ARIA 最佳实践。所有组件都支持键盘导航、屏幕阅读器等辅助技术。

可组合性 (Composition)

组件设计为高度可组合，可以轻松组合使用或与自定义组件结合。

样式无关 (Styling Agnostic)

Base UI 不强制任何样式方案，可以使用 CSS、CSS-in-JS、Tailwind 等任何样式引擎。

TypeScript 支持

完整的 TypeScript 类型定义，提供类型安全和优秀的开发体验。

文档结构

references/base-ui-docs/
├── overview/           # 概述文档
│   ├── quick-start.md
│   ├── accessibility.md
│   ├── releases.md
│   └── about.md
├── handbook/          # 指南文档
│   ├── styling.md
│   ├── animation.md
│   ├── composition.md
│   ├── customization.md
│   └── typescript.md
├── components/        # 组件文档（34个组件）
│   ├── accordion.md
│   ├── alert-dialog.md
│   ├── autocomplete.md
│   └── ...（更多组件）
└── utils/            # 工具函数
    ├── direction-provider.md
    └── use-render.md

最佳实践

优先使用 Base UI 组件 - 而不是手动实现，以获得内置的无障碍访问功能
遵循组合模式 - 使用组件的组合 API 而不是覆盖内部实现
保持样式独立 - 使用 className 或 style props 而不是修改组件内部样式
测试无障碍访问 - 使用屏幕阅读器和键盘导航测试组件
参考 Handbook - 在实现复杂功能前，先查看相关的 Handbook 指南