---
name: fractal-components
description: "Choose, compose, or extend reusable Fractal UI components. Use for component-level UX and package work; exact APIs come from the installed package."
---

# Choose or extend components

Read [core](../../../../core.md) and [component selection](../../references/components/selection.md). Use bundle `component-use` for existing components and `component-create` for new reusable behavior.

## Choose the ownership and component

Inspect the actual `@mirror-physics/fractal-ui` package and consumers. Prefer an existing export, then a composition of exports, then a product-local composition. A new reusable component needs distinct recurring behavior; one unusual screen is not enough.

Select controls by semantics: navigation uses links, actions use buttons, immediate binary settings use toggles, committed form choices use checkboxes, peer views use tabs, optional detail uses disclosure, and object-focused work uses an inspector. Component names in the reference are selection guidance; verify availability in the installed version.

Use supported composition/styling APIs for spacing. Do not reconstruct a shared component to change an inset. Preserve persistent accessible names, floating-title rules and their search-field exception, focus behavior, and consistent control metrics.

## When extending the package

Read [interface](../../references/interface.md), [color](../../references/color.md), [typography](../../references/typography.md), [layout](../../references/layout.md), and [motion](../../references/motion.md) before designing new anatomy or states. Inspect consumers and compatibility before modifying existing behavior. Implement runtime behavior, props, CSS, and stories in the separate `fractal-ui` repository. Add design evidence only for a new UX decision, rather than duplicating API documentation.

For icons, use [icon guidance](../fractal-icons/SKILL.md). Read [SidePanel](../../references/components/side-panel.md) or [Textarea](../../references/components/textarea.md) when using or changing those patterns. Load [motion](../../references/motion.md) for any moving component even in use mode.

## Verify

Check representative consumers, accessible names, focus/keyboard behavior, relevant states, enlarged text, and adjacent control alignment. New shared behavior needs package-level validation appropriate to its risk. Releasing is a separate action under the owning package's trusted-publishing workflow; choosing a component never requires a release.
