@payfit/unity-icons/skills/unity-icons/SKILL.md

---
name: unity-icons
description: Use when selecting or migrating a Unity icon, checking Filled/Outlined variants, typing an icon prop, or rendering an icon in Unity code. Search the canonical icon catalog first and use the source implementation only for usage details.
metadata:
  type: core
  library: '@payfit/unity-icons'
---

## Source of truth

Read [src/agent-references/icons-catalog.json](../../src/agent-references/icons-catalog.json) first. It contains one entry per `baseName` and a `variants` list with the exact sprite names. Do not use the Storybook MCP projection for discovery when the JSON catalog is available.

For a targeted lookup, search the full JSON rather than reading an arbitrary slice:

```sh
jq '.icons[] | select(.baseName | test("search|glass"; "i"))' \
  libs/shared/unity/icons/src/agent-references/icons-catalog.json
```

## Standard operating procedure

1. Extract the user's intent and likely synonyms, then search the complete catalog.
2. Compare all plausible `baseName` matches and their available variants.
3. Return the exact icon name, preserving its PascalCase spelling and suffix.
4. Only inspect `src/components/icon/Icon.tsx`, `src/components/icon/parts/IconSprite.tsx`, or `src/components/icons-provider/UnityIconsProvider.tsx` when usage or API details are needed.
5. Prefer `Icon` from `@payfit/unity-icons` for product UI. Use `IconSprite` from `@payfit/unity-icons` when the lower-level sprite API is specifically required.

```tsx
import { Icon } from '@payfit/unity-icons'
;<Icon src="MagnifyingGlassOutlined" size={20} />
```

Do not guess lowercase or kebab-case names, and do not cast arbitrary strings to `UnityIcon`; both bypass the typed sprite-id guard and can render an empty SVG.

When an icon name crosses a component boundary, type it as `UnityIcon` rather
than widening it to `string`:

```tsx
import type { UnityIcon } from '@payfit/unity-icons'

type Props = { icon: UnityIcon }
```

## Migrate from Midnight

Map both `Icon` and `v2/Icon` to the Unity `Icon` component. Treat the old
name as search input, not as a guaranteed Unity sprite id: search the catalog,
select the closest semantic match, and preserve the exact PascalCase
`Filled`/`Outlined` variant. Never retain a Midnight string through an
`as UnityIcon` cast.

Use `unity-migrate-from-midnight` for the surrounding screen migration and
return here whenever the target icon is unclear.

For broader browsing, use the [Unity icon catalog](https://unity-icons.payfit.io/?path=/docs/reference-find-my-icon--docs).