/meta-design-composable-components

name: meta-design-composable-components
description: Composable component APIs — parts, state, polymorphism. Load when designing a reusable component's API, or aligning one that has grown boolean, renderX or style props.

Composable Component Patterns

> **Quick Guide:** The component owns behaviour, state and accessibility; the consumer owns markup, element type and styling. That line settles most API questions: variation becomes parts and children instead of booleans and `renderX` props, each exposed state ships as `value` + `defaultValue` + `onValueChange` with a details argument carrying the reason and a veto, every part can render as the consumer's element through one substitution shape, state is published as `data-*` attributes, and whatever the consumer passes — props, handlers, refs — is composed rather than replaced. Three React 19 facts change the code: `ref` is an ordinary prop, a callback ref may return a cleanup that a ref-composing helper has to collect, and `useId`'s format changed in both 19.1 and 19.2, with only 19.2's safe in both a CSS selector and an XML id.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — Patterns 1–3: compound parts, children with a descendant registry, context scoping
• [examples/state-contract.md](examples/state-contract.md) — Patterns 4–5: `useControllableState`, change details with reason and cancel, retrofitting the triple, state as `data-*` attributes
• [examples/polymorphism.md](examples/polymorphism.md) — Patterns 6–7: `asChild` and `render` built without a library, the merge they share, `composeEventHandlers`, `composeRefs`, prop ordering
• [examples/accessibility-structure.md](examples/accessibility-structure.md) — Pattern 8: id wiring, focus ownership, roving tabindex, typeahead, Escape
• [reference.md](reference.md) — prop-to-part translation, naming tables, substitution merge rules, attribute vocabulary, ARIA and keyboard contracts, the alignment checklist

---

Which path applies

• **Designing a new component** — settle the parts (Patterns 1–3), then the state contract (4–5); substitution and forwarding (6–7) apply to every part you defined. Start at [examples/core.md](examples/core.md).
• **Aligning an existing component** — read its call sites, run it through the [alignment checklist](reference.md#alignment-checklist), and fix API shape first, because the later axes depend on which parts exist. Migrate additively, as [retrofitting the triple](examples/state-contract.md#retrofitting-an-existing-component) shows.
• **Building on a headless library that already ships parts** — use its substitution shape and its merge helper on every part you add, so yours behave like its own; the library's API is its own skill's subject, and [examples/polymorphism.md](examples/polymorphism.md) shows what any merge has to guarantee.

---

<critical_requirements>

Before designing a component API

**Express variation as parts and children, never as configuration props.** A boolean or `renderX` prop is the component deciding the consumer's markup, so each design need becomes another prop and N booleans become 2^N layouts to render and test; a part lets the consumer's JSX make that decision once.

**Ship every exposed piece of state as `value` + `defaultValue` + `onValueChange`, resolved in one hook.** A controlled prop copied into `useState` is read once and then drifts from the consumer's store; resolving to the prop whenever it is defined leaves no second copy to drift.

**Compose what the consumer passes — props, handlers, refs — instead of replacing it.** Defaults go before the rest-spread and wiring after it, the consumer's handler runs first, and refs are merged; anything replaced disappears with no error and no type failure.

**Publish every state as a `data-*` attribute, and ship behaviour parts with no visual styling.** Attribute selectors let consumers style each state without the component knowing a class name or re-rendering; a default class, colour or transition is something every consumer has to out-specify.

**Read every call site before changing a component's API.** A removed prop whose name is also an HTML attribute — `title`, `hidden`, `color` — still type-checks once a part extends its element's props, and lands on the DOM node instead of failing the build.

</critical_requirements>

---

**Auto-detection:** compound components, namespaced parts, `asChild`, `render` prop, `useControllableState`, `defaultValue`, `onValueChange`, `onOpenChange`, change details, `data-state`, `data-disabled`, `composeRefs`, `composeEventHandlers`, out-of-Root error, descendant registry, roving tabindex, typeahead, focus trap, polymorphic component, boolean prop explosion, `renderX` props, `items` prop, headless component

**Applies to:**

• Deciding whether a new requirement becomes a prop, a part or children
• Designing the public API of a reusable component
• Aligning a component that has accumulated booleans, `renderX` props, style props or an `items` array
• Adding controlled/uncontrolled support, with a change callback that says why and can be refused
• Letting a part render as the consumer's element, and composing their props, handlers and refs onto it
• Publishing state for styling, and wiring ids, focus and keyboard behaviour across parts
• Reviewing a component change for API shape and forwarding discipline

**Handled elsewhere:**

• A headless library's own API — its parts, props, merge helper, escape hatch and version facts — is covered by that library's own skill. This skill settles the shape of what you build, on top of a library or without one.
• Which headless library to adopt.
• Accessibility conformance — WCAG audits, contrast, alt text, screen-reader testing. Accessibility appears here only where it decides which parts exist and what they share.
• Authoring styles — variant composition, tokens, theming. Styling appears here only as the contract a component exposes: `data-*` attributes, `className` and `st