---
name: unity-find-component
description: >
Load when selecting a Unity component is unclear or before creating a custom
UI primitive that may already exist in @payfit/unity-components. Use it to
find the existing component, then fall back to React Aria plus uy: classes
only when Unity has no fit.
metadata:
type: core
library: '@payfit/unity-components'
library_version: '2.x'
---
Routing skill for selecting a Unity component before writing UI code. Walk
the catalog, then the decision tree, then the commonly-confused pairs.
## Component catalog
Inspect the canonical [component catalog](../../src/agent-references/component-catalog.json)
before searching component source. It contains exact component ids, titles,
descriptions, keywords, sections, tags, related entries, and Storybook preview
metadata. There is no separate canonical Markdown catalog.
For a targeted lookup, search the full JSON and compare all plausible matches. Use whatever reliable local search tool is available (for example `rg`, a JSON-aware CLI, or a short Node script); do not assume `jq` is installed:
```sh
rg -i -C 2 'dialog|confirmation|modal' \
libs/shared/unity/components/src/agent-references/component-catalog.json
```
## Standard operating procedure
1. Extract the user's intent and expand it into synonyms, interaction patterns, and adjacent component terms.
2. Search the complete catalog; do not stop at the first slice or plausible hit.
3. Rank candidates by intent fit, description, keywords, tags, section, and related entries.
4. Return the best match first. Mention an alternative only when the evidence is genuinely ambiguous.
5. Search `libs/shared/unity/components/src` to confirm implementation details or locate nearby source.
6. Inspect Storybook stories only for props, API details, or usage examples after a likely component has been identified. When the Storybook MCP is available, use its curated component manifest or matching Storybook entry as a complementary source for rendered examples; the canonical JSON catalog remains the source of truth for discovery.
7. Walk the decision tree below before creating a custom primitive.
## Decision Tree
For every UI need, walk these three levels in order. Stop at the first that
fits.
### Level 1 — Use Unity directly
If a named export covers the use case, import it. No abstractions over the
top.
```tsx
import {
Button,
Dialog,
DialogActions,
DialogContent,
Pill,
} from '@payfit/unity-components'
export function ConfirmDelete({
isOpen,
onClose,
}: {
isOpen: boolean
onClose: () => void
}) {
return (
)
}
```
### Level 2 — Fall back to React Aria + uy:\* classes
Build your own primitive only when Unity has no equivalent. Compose React
Aria primitives, style with the `uy:` prefix, and merge classes with
`uyMerge` / `uyTv`.
```tsx
import { uyTv } from '@payfit/unity-themes'
import { ToggleButton } from 'react-aria-components'
const toggleStyles = uyTv({
base: 'uy:inline-flex uy:items-center uy:gap-100 uy:rounded-100 uy:px-200 uy:py-100',
variants: {
isSelected: {
true: 'uy:bg-surface-action uy:text-content-on-action',
false: 'uy:bg-surface-secondary uy:text-content-neutral',
},
},
})
export function CustomPivot({ label }: { label: string }) {
return (
toggleStyles({ isSelected })}>
{label}
)
}
```
### Level 3 — Midnight (last resort, deprecated)
Only when (a) Unity has no equivalent, (b) React Aria + `uy:*` cannot
realistically rebuild it, and (c) the feature ships against a deadline. Open
a follow-up to migrate. Per `AGENTS.md`, Midnight is deprecated; never
import it into a new module.
## Commonly Confused Pairs
- `Badge` vs `Pill`: `Badge` is a numeric/dot indicator anchored to another
element (notification count). `Pill` is a standalone label/status chip
with text content.
- `Card` vs `SelectableCard...` vs `NavigationCard`: `Card` is the generic
container. `SelectableCardCheckboxGroup` / `SelectableCardRadioGroup`
wrap cards as form inputs. `NavigationCard` wraps a card as a router-aware
link.
- `Button` vs `IconButton` vs `RawLinkButton`: `Button` for actions with
text. `IconButton` / `CircularIconButton` for icon-only actions
(requires `aria-label`). `RawLinkButton` renders as an anchor but styled
like a button — use when the action navigates.
- `Menu` vs `Popover`: `Menu` is a list of actionable items keyed by
keyboard (Enter/Arrow). `Popover` is a free-form floating panel and
requires a `title`.
- `Dialog` vs `PromoDialog`: `Dialog` for confirmation / edit flows.
`PromoDialog` for marketing / onboarding announcements; requires
`PromoDialogHero`.
- `Table` vs `DataTable`: `Table` is the layout primitive (header, body,
rows, cells) with no behavior. `DataTable` wires Tanstack Table for
sorting, filtering, pagination, virtualization, bulk actions.
- `ErrorState` vs `Alert`: `ErrorState` is a full-area empty-replacement
for "this section failed to load." `Alert` is an inline banner that
coexists with surrounding content.
## Icon Source Convention
`Icon` takes a typed `src` prop of type `UnityIcon` — a literal union of
PascalCase names with a `Filled` or `Outlined` suffix (~310 values, from
`@payfit/unity-icons`). Strings outside that union are a type error. Do
not cast to `UnityIcon`; the cast bypasses the sprite-id guard and the
icon silently renders empty.
```tsx
import type { UnityIcon } from '@payfit/unity-icons'
import { Icon } from '@payfit/unity-components'
const icon: UnityIcon = 'MagnifyingGlassOutlined'
;
```
## Forms Notice
Tanstack Form (`useTanstackUnityForm`) is the only supported form system.
The React Hook Form path — `useUnityForm` plus the legacy `TextField` /
`SelectField` / `NumberField` etc. RHF wrappers exported from the same
index — is deprecated. Do not author new code with `useUnityForm`. See
`unity-tanstack-form`.
## Common Mistakes
### HIGH Hand-roll component that already exists
Wrong:
```tsx
const Tag = ({ children }) => (
{children}
)
```
Correct:
```tsx
import { Pill } from '@payfit/unity-components'
;{children}
```
The hand-rolled span re-derives Pill's tokens by guesswork and drifts from
the design-system source-of-truth on every theme update.
Source: libs/shared/unity/components/src/components/pill/Pill.tsx
### HIGH Use React Aria primitive directly when Unity wraps it
Wrong:
```tsx
import { Button as AriaButton } from 'react-aria-components'
;Click
```
Correct:
```tsx
import { Button } from '@payfit/unity-components'
;
```
The bare React Aria Button has no Unity theming, intl, or styling
defaults; you ship an unstyled element with no `uy:*` classes.
Source: libs/shared/unity/components/src/components/button/Button.tsx
### HIGH Reach for Midnight when Unity has an equivalent
Wrong:
```tsx
import { Button, Modal } from '@payfit/midnight'
```
Correct:
```tsx
import { Button, Dialog } from '@payfit/unity-components'
```
Midnight is deprecated; new screens that import it cannot match the Unity
theme tokens and will require a migration pass later anyway.
Source: AGENTS.md "Do NOT use (deprecated)"
### MEDIUM Combine Input + FormField when \*Field exists
Wrong:
```tsx
```
Correct:
```tsx
{field => }
```
Manual `FormField` + `Input` skips the label-for/aria-describedby wiring,
the `field.state.meta` error plumbing, and the required-state inference
that the `*Field` components handle.
Source: libs/shared/unity/components/src/components/form-field/FormField.tsx; index.ts:205-223
### HIGH Pass an untyped string to Icon src and guess the name
Wrong:
```tsx
const name: string = 'trash'
```
Correct:
```tsx
import { Icon } from '@payfit/unity-components'
import type { UnityIcon } from '@payfit/unity-icons'
type Props = { icon: UnityIcon }
```
The `UnityIcon` literal union encodes the exact sprite ids; lowercase or
kebab-case strings have no matching `` in the injected sprite,
so `