playbooks

home / skills / pproenca / dot-skills / mui-base

mui-base skill

/skills/.curated/mui-base

This skill helps you build unstyled UI components and accessible primitives by applying MUI Base guidelines for headless patterns.

npx playbooks add skill pproenca/dot-skills --skill mui-base

Review the files below or copy the command above to add this skill to your agents.

Files (54)
SKILL.md
4.7 KB
---
name: mui-base
description: MUI Base UI style guidelines for building headless React component libraries (formerly headless-ui-style). This skill should be used when creating unstyled UI components, compound components with render props, accessibility-first patterns, or component libraries that separate logic from styling. Extracted from the MUI Base UI codebase (github.com/mui/base-ui).
---

# MUI Headless UI Best Practices

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

## 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

## Rule Categories by Priority

| 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-` |

## Quick Reference

### 1. Component Patterns (CRITICAL)

- `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

### 2. Naming Conventions (HIGH)

- `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

### 3. Organization (HIGH)

- `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

### 4. Error Handling (HIGH)

- `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

### 5. Style (MEDIUM)

- `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

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules
- Example: [comp-forward-ref-named](references/comp-forward-ref-named.md)
- Example: [org-component-directory](references/org-component-directory.md)

## Source

Extracted from [MUI Base UI](https://github.com/mui/base-ui) codebase on 2026-01-17.

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

Overview

This skill packages the MUI Base headless UI style guidelines for building unstyled, accessibility-first React component libraries. It documents prioritized rules and patterns for component APIs, naming, organization, error handling, and style to help teams separate logic from presentation and deliver reusable primitives.

How this skill works

The skill summarizes 48 rules across five priority categories and provides actionable patterns such as forwardRef usage, controlled/uncontrolled support, context conventions, and memoization strategies. It points to reference files and examples that show canonical implementations and export patterns to follow when authoring headless components.

When to use it

  • When creating unstyled or headless React components intended for styling by consumers
  • When designing compound components that use context and render props
  • When implementing accessible primitives with ARIA patterns and keyboard handling
  • When supporting both controlled and uncontrolled component modes
  • When establishing repository conventions for a component library (naming, layout, exports)

Best practices

  • Use named forwardRef functions and standard prop parameter names (componentProps) for clarity and debuggability
  • Create context with an undefined default and provide clear dev-time context error messages
  • Memoize state objects and context provider values to avoid unnecessary renders
  • Follow consistent naming: ParentPart component names, use-prefixed hooks, and SCREAMING_SNAKE_CASE constants
  • Co-locate tests, use dual-barrel exports for package boundaries, and document data/state attributes separately

Example use cases

  • Authoring an unstyled select/menu primitive that exposes render props and className callbacks
  • Building a compound widget (e.g., Tabs or Accordion) that shares state via context with strict error guidance
  • Refactoring a component to support both controlled and uncontrolled props using a useControlled hook
  • Creating a package layout with dual barrel exports and clear file-to-export name matching
  • Adding development-only, deduplicated warnings for improper API usage and context misuse

FAQ

Do these guidelines require a particular styling solution?

No. The rules focus on separating logic from styling; consumers can use any styling system (CSS, CSS-in-JS, utility classes).

Are the conventions mandatory for all components?

They are recommended best practices aimed at consistency and accessibility; adopt what fits your library goals and iterate where needed.