⚡

MUI无头UI组件库最佳实践Skill mui-base

这个技能提供了MUI Base UI的最佳实践指南，专为构建无头React组件库设计。它涵盖了组件模式、命名约定、组织方式、错误处理和样式规则，帮助开发者创建无样式UI组件、复合组件、实现无障碍优先模式，并支持受控和非受控组件模式。关键词：MUI, React, 组件库, 无头UI, 前端开发, 最佳实践。

前端开发 0 次安装 0 次浏览 更新于 3/18/2026

name: mui-base description: MUI 基础 UI 风格指南，用于构建无头 React 组件库（以前称为 headless-ui-style）。此技能应用于创建无样式 UI 组件、具有渲染属性的复合组件、无障碍优先模式或分离逻辑与样式的组件库。提取自 MUI Base UI 代码库 (github.com/mui/base-ui)。

MUI 无头UI最佳实践

构建遵循 MUI Base UI 模式的无头 React 组件库的全面风格指南。包含 5 个类别的 48 条规则，按影响优先级排序。

何时应用

参考这些指南当：

  • 构建无头/无样式组件库
  • 创建基于上下文组合的复合组件
  • 实现具有 ARIA 模式的无障碍 UI 原语
  • 使用渲染属性和 className 回调以实现样式灵活性
  • 编写支持受控和非受控模式的组件

按优先级分类的规则类别

优先级 类别 影响 前缀
1 组件模式 关键 comp-
2 命名约定 高 name-
3 组织 高 org-
4 错误处理 高 err-
5 样式 中等 style-

快速参考

1. 组件模式 (关键)

  • comp-forward-ref-named - 使用带命名函数的 forwardRef
  • comp-props-parameter-naming - 命名 Props 参数为 componentProps
  • comp-use-render-element - 使用 useRenderElement 进行 DOM 渲染
  • comp-context-undefined-default - 创建具有未定义默认值的上下文
  • comp-context-error-message - 具有层次结构的上下文错误消息
  • comp-use-controlled - 使用 useControlled Hook 用于双重模式
  • comp-state-memoization - 记忆状态对象
  • comp-context-value-memo - 记忆上下文提供者值
  • comp-plain-function-root - 用于非DOM根部的普通函数
  • comp-hook-namespace-exports - Hook 命名空间导出
  • comp-props-destructure-order - Props 解构顺序
  • comp-use-client-directive - 添加 use client 指令

2. 命名约定 (高)

  • name-component-naming - 组件命名为 ParentPart
  • name-file-matches-export - 文件名匹配主要导出
  • name-directory-kebab-case - 目录命名使用 kebab-case
  • name-part-directory-lowercase - 部件目录命名使用小写
  • name-context-suffix - 上下文命名使用后缀
  • name-context-hook - 上下文 Hook 作为 useComponentContext
  • name-props-interface - Props 接口作为 ComponentProps
  • name-state-interface - State 接口作为 ComponentState
  • name-namespace-type-exports - 命名空间类型导出
  • name-event-type - 事件类型命名约定
  • name-constants - 常量命名使用 SCREAMING_SNAKE_CASE
  • name-data-attributes - 数据属性命名使用小写
  • name-hooks - Hook 命名使用 use 前缀
  • name-refs - Ref 变量命名使用后缀
  • name-handlers - 处理程序命名约定

3. 组织 (高)

  • org-component-directory - 组件目录结构
  • org-dual-barrel-exports - 双桶导出模式
  • org-test-colocation - 测试文件共置
  • org-context-placement - 上下文文件放置
  • org-data-attributes-file - 数据属性文档文件
  • org-state-attributes-mapping - 状态属性映射文件
  • org-css-vars-file - CSS 变量文档文件
  • org-package-exports - 包级别通配符导出

4. 错误处理 (高)

  • err-dev-only-warnings - 仅开发警告
  • err-deduplicated-warnings - 去重警告消息
  • err-message-prefix - 消息前缀标准
  • err-context-error-guidance - 上下文错误指导
  • err-prop-validation-timing - Prop 验证时机
  • err-cancelable-events - 可取消事件模式
  • err-event-reason-constants - 事件原因常量
  • err-typed-event-reasons - 类型安全的事件原因

5. 样式 (中等)

  • style-react-import - React 导入作为命名空间
  • style-internal-imports - 内部导入路径
  • style-explicit-undefined - 在 Prop 类型中显式未定义
  • style-default-values - 解构中的默认值
  • style-jsdoc-documentation - JSDoc 文档

如何使用

阅读单个参考文件以获取详细解释和代码示例：

来源

提取自 MUI Base UI 代码库于 2026-01-17。

完整编译文档

完整指南，所有规则展开：AGENTS.md