mui-base

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MUI Headless UI Best Practices

MUI 无头UI最佳实践

Comprehensive style guide for building headless React component libraries following MUI Base UI patterns. Contains 48 rules across 5 categories, prioritized by impact.

遵循MUI Base UI模式构建无头React组件库的综合风格指南。包含5个类别共48条规则，按影响程度划分优先级。

When to Apply

适用场景

Reference these guidelines when:

Building headless/unstyled component libraries
Creating compound components with context-based composition
Implementing accessible UI primitives with ARIA patterns
Using render props and className callbacks for styling flexibility
Writing components that support both controlled and uncontrolled modes

在以下场景中参考本指南：

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

Rule Categories by Priority

按优先级划分的规则类别


comp-
name-
org-
err-
style-

Priority	Category	Impact	Prefix
1	Component Patterns	CRITICAL	`comp-`
2	Naming Conventions	HIGH	`name-`
3	Organization	HIGH	`org-`
4	Error Handling	HIGH	`err-`
5	Style	MEDIUM	`style-`


comp-
name-
org-
err-
style-

优先级	类别	影响程度	前缀
1	组件模式	关键	`comp-`
2	命名规范	高	`name-`
3	组织架构	高	`org-`
4	错误处理	高	`err-`
5	代码风格	中	`style-`

Quick Reference

快速参考

1. Component Patterns (CRITICAL)

1. 组件模式（关键）

```
comp-forward-ref-named
```
- Use forwardRef with Named Function
```
comp-props-parameter-naming
```
- Name Props Parameter componentProps
```
comp-use-render-element
```
- Use useRenderElement for DOM Rendering
```
comp-context-undefined-default
```
- Create Context with Undefined Default
```
comp-context-error-message
```
- Context Error Messages with Hierarchy
```
comp-use-controlled
```
- Use useControlled Hook for Dual Modes
```
comp-state-memoization
```
- Memoize State Objects
```
comp-context-value-memo
```
- Memoize Context Provider Values
```
comp-plain-function-root
```
- Plain Function for Non-DOM Roots
```
comp-hook-namespace-exports
```
- Hook Namespace Exports
```
comp-props-destructure-order
```
- Props Destructuring Order
```
comp-use-client-directive
```
- Add use client Directive

```
comp-forward-ref-named
```
- 使用带命名函数的forwardRef
```
comp-props-parameter-naming
```
- 将Props参数命名为componentProps
```
comp-use-render-element
```
- 使用useRenderElement进行DOM渲染
```
comp-context-undefined-default
```
- 创建默认值为undefined的Context
```
comp-context-error-message
```
- 带层级结构的Context错误提示
```
comp-use-controlled
```
- 使用useControlled Hook实现双模式
```
comp-state-memoization
```
- 对状态对象进行记忆化处理
```
comp-context-value-memo
```
- 对Context Provider的值进行记忆化处理
```
comp-plain-function-root
```
- 非DOM根节点使用普通函数
```
comp-hook-namespace-exports
```
- Hook命名空间导出
```
comp-props-destructure-order
```
- Props解构顺序规范
```
comp-use-client-directive
```
- 添加use client指令

2. Naming Conventions (HIGH)

2. 命名规范（高）

```
name-component-naming
```
- Component Naming as ParentPart
```
name-file-matches-export
```
- File Name Matches Primary Export
```
name-directory-kebab-case
```
- Directory Naming kebab-case
```
name-part-directory-lowercase
```
- Part Directory Naming lowercase
```
name-context-suffix
```
- Context Naming with Suffix
```
name-context-hook
```
- Context Hook as useComponentContext
```
name-props-interface
```
- Props Interface as ComponentProps
```
name-state-interface
```
- State Interface as ComponentState
```
name-namespace-type-exports
```
- Namespace Type Exports
```
name-event-type
```
- Event Type Naming Convention
```
name-constants
```
- Constant Naming SCREAMING_SNAKE_CASE
```
name-data-attributes
```
- Data Attribute Naming lowercase
```
name-hooks
```
- Hook Naming with use Prefix
```
name-refs
```
- Ref Variable Naming with Suffix
```
name-handlers
```
- Handler Naming Convention

```
name-component-naming
```
- 组件命名采用ParentPart格式
```
name-file-matches-export
```
- 文件名与主导出内容匹配
```
name-directory-kebab-case
```
- 目录命名采用kebab-case格式
```
name-part-directory-lowercase
```
- 部件目录命名采用小写格式
```
name-context-suffix
```
- Context命名添加后缀
```
name-context-hook
```
- Context Hook命名为useComponentContext
```
name-props-interface
```
- Props接口命名为ComponentProps
```
name-state-interface
```
- 状态接口命名为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. Organization (HIGH)

3. 组织架构（高）

```
org-component-directory
```
- Component Directory Structure
```
org-dual-barrel-exports
```
- Dual Barrel Export Pattern
```
org-test-colocation
```
- Test File Colocation
```
org-context-placement
```
- Context File Placement
```
org-data-attributes-file
```
- Data Attributes Documentation File
```
org-state-attributes-mapping
```
- State Attributes Mapping File
```
org-css-vars-file
```
- CSS Variables Documentation File
```
org-package-exports
```
- Package-Level Wildcard Exports

```
org-component-directory
```
- 组件目录结构规范
```
org-dual-barrel-exports
```
- 双桶导出模式
```
org-test-colocation
```
- 测试文件与源码同目录
```
org-context-placement
```
- Context文件存放位置规范
```
org-data-attributes-file
```
- 数据属性文档文件
```
org-state-attributes-mapping
```
- 状态属性映射文件
```
org-css-vars-file
```
- CSS变量文档文件
```
org-package-exports
```
- 包级通配符导出

4. Error Handling (HIGH)

4. 错误处理（高）

```
err-dev-only-warnings
```
- Development-Only Warnings
```
err-deduplicated-warnings
```
- Deduplicated Warning Messages
```
err-message-prefix
```
- Message Prefix Standard
```
err-context-error-guidance
```
- Context Error Guidance
```
err-prop-validation-timing
```
- Prop Validation Timing
```
err-cancelable-events
```
- Cancelable Event Pattern
```
err-event-reason-constants
```
- Event Reason Constants
```
err-typed-event-reasons
```
- Type-Safe Event Reasons

```
err-dev-only-warnings
```
- 仅开发环境警告
```
err-deduplicated-warnings
```
- 去重警告提示
```
err-message-prefix
```
- 提示信息前缀标准
```
err-context-error-guidance
```
- Context错误指引
```
err-prop-validation-timing
```
- Props校验时机
```
err-cancelable-events
```
- 可取消事件模式
```
err-event-reason-constants
```
- 事件原因常量
```
err-typed-event-reasons
```
- 类型安全的事件原因

5. Style (MEDIUM)

5. 代码风格（中）

```
style-react-import
```
- React Import as Namespace
```
style-internal-imports
```
- Internal Import Paths
```
style-explicit-undefined
```
- Explicit Undefined in Prop Types
```
style-default-values
```
- Default Values in Destructuring
```
style-jsdoc-documentation
```
- JSDoc Documentation

```
style-react-import
```
- React导入使用命名空间
```
style-internal-imports
```
- 内部导入路径规范
```
style-explicit-undefined
```
- Prop类型中显式声明undefined
```
style-default-values
```
- 解构时设置默认值
```
style-jsdoc-documentation
```
- JSDoc文档规范

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules
Example: comp-forward-ref-named
Example: org-component-directory

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构与影响程度说明
规则模板 - 添加新规则的模板
示例：comp-forward-ref-named
示例：org-component-directory

Source

来源

Extracted from MUI Base UI codebase on 2026-01-17.

内容提取自MUI Base UI代码库，提取时间为2026-01-17。

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有规则详细说明的完整指南：

AGENTS.md