playbooks

home / skills / noklip-io / agent-skills / base-ui

base-ui skill

/skills/base-ui

This skill helps you navigate and reference Base UI documentation, components, and patterns to implement accessible, composable React UI efficiently.

npx playbooks add skill noklip-io/agent-skills --skill base-ui

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

Files (15)
SKILL.md
2.2 KB
---
name: base-ui
description: Base UI reference and workflows for @base-ui/react (unstyled, accessible React components, composition utilities, and form helpers). Use when implementing Base UI components, portals, styling/state hooks, render-prop composition, eventDetails customization, animations, forms/validation, TypeScript typing, CSP/RTL utilities, or checking Base UI docs, issues, or releases.
---

# Base UI

## Overview
Use this skill as a navigation hub for Base UI. Load the specific reference files when needed.

## Start Here
- Read `references/overview.md` for install, portal isolation, iOS 26 Safari, and LLM docs access.
- Pick components from `references/components.md`.
- Choose guidance by need: styling, composition, customization, animation, forms, TypeScript, or utils.

## Reference Map
- `references/overview.md`: install, portals, iOS 26 Safari, LLM docs, project context.
- `references/components.md`: full component and utility index with .md doc links.
- `references/styling.md`: className/state, data attributes, CSS variables, style prop, Tailwind/CSS Modules/CSS-in-JS patterns.
- `references/composition.md`: render prop usage, ref forwarding, nesting render props.
- `references/customization.md`: Base UI events, eventDetails, cancel/allowPropagation, preventBaseUIHandler, controlled vs uncontrolled.
- `references/animation.md`: data attributes, transitions vs animations, Motion/AnimatePresence, keepMounted, getAnimations.
- `references/forms.md`: Form/Field patterns, constraint validation, server-side errors, RHF/TanStack integration.
- `references/typescript.md`: Props/State namespaces, ChangeEventDetails/Reason, actionsRef types, useRender types.
- `references/utils.md`: CSPProvider, DirectionProvider/useDirection, mergeProps/mergePropsN, useRender patterns.
- `references/edge-cases.md`: common pitfalls and fixes.
- `references/examples.md`: concise, runnable examples.
- `references/links.md`: issues and changelog entry points.

## Use Pattern
1. Identify the component or utility.
2. Read the component docs in `references/components.md`.
3. Pull in the relevant handbook or utility reference.
4. Confirm edge cases in `references/edge-cases.md`.
5. Use `references/links.md` for issues and release notes before shipping.

Overview

This skill is a concise navigation hub for Base UI usage and reference material. It collects component indexes, patterns for styling and composition, animation and form workflows, TypeScript typings, and utility helpers. Use it to quickly find the right guidance, edge-case fixes, and links to issues or changelogs before shipping.

How this skill works

The skill maps common implementation needs to focused reference pages: components, styling, composition, customization, animation, forms, TypeScript, utilities, edge cases, and examples. Start by identifying the component or utility, consult the component index, then open the relevant handbook section for patterns, props, and implementation notes. It also directs you to troubleshooting entries and changelog/issue links when you need release context or bug reports.

When to use it

  • When implementing Base UI components or composing nested render-props and refs.
  • When choosing styling patterns (className, CSS variables, Tailwind, CSS Modules).
  • When integrating forms, validation, or server-side error flows with RHF/TanStack.
  • When adding animations, motion, or keep-mounted transitions.
  • When working with TypeScript types for props, state, and actionsRef.
  • When diagnosing edge cases, portal isolation, or platform-specific issues (e.g., iOS Safari quirks).

Best practices

  • Identify the exact component in the components index before reading specific guidance.
  • Prefer documented composition and ref-forwarding patterns to ensure accessibility and predictable behavior.
  • Use data attributes and CSS variables for predictable styling and animation triggers.
  • Validate controlled vs uncontrolled patterns and use provided eventDetails helpers to manage propagation.
  • Check edge-case notes and link to issue/changelog entries prior to release to avoid regressions.

Example use cases

  • Implementing an accessible dropdown with render-prop composition and portal isolation.
  • Adding motion to a modal using data attributes and AnimatePresence while keeping mount state predictable.
  • Integrating a Base UI form with React Hook Form and mapping server-side validation errors.
  • Applying Tailwind or CSS Modules patterns while preserving Base UI state-driven classNames.
  • Typing a component's actionsRef and ChangeEventDetails for TypeScript safety.

FAQ

Where do I start when adding a new Base UI component?

Find the component in the components index, read its dedicated reference, then follow composition, styling, and edge-case guidance before testing in the target environment.

How do I handle propagation and custom Base UI events?

Use the eventDetails utilities to inspect cancel/allow propagation, and prefer preventBaseUIHandler patterns where documented to avoid breaking internal handlers.