---
name: unity-illustrations
description: Use when selecting or migrating a Unity illustration or animation, checking its category and asset type, choosing eager versus lazy loading, or preserving illustration accessibility. Search the canonical illustration catalog first and inspect source usage only when needed.
metadata:
  type: core
  library: '@payfit/unity-illustrations'
---

## Source of truth

Read [src/agent-references/illustrations-catalog.json](../../src/agent-references/illustrations-catalog.json) first. Each entry contains `name`, `category`, `assetType`, and `qualifiedEagerImport`. The catalog is the authoritative index; the Storybook MCP projection is a secondary presentation of the same data.

Search the complete catalog and compare plausible matches:

```sh
jq '.illustrations[] | select(.name | test("empty|success"; "i"))' \
  libs/shared/unity/illustrations/src/agent-references/illustrations-catalog.json
```

## Standard operating procedure

1. Extract the visual intent and expand it into synonyms and adjacent concepts.
2. Search the full catalog; do not stop at the first plausible result.
3. Rank matches by semantic fit, `category`, and `assetType`. Distinguish static pictures from animations.
4. For eager loading, use the catalog's `qualifiedEagerImport` verbatim and pass the imported asset to `Illustration`.
5. Prefer `LazyIllustration` with the catalog `name` when the artwork is not immediately visible or should be code-split.
6. Read `src/docs/1-Introduction/3-Usage.mdx` and the component source only when props, loading behavior, or accessibility details are needed.
7. Always provide meaningful `alt` text for non-decorative artwork. Use `isDecorative` only when the image conveys no information.

```tsx
import { Illustration, LazyIllustration } from '@payfit/unity-illustrations'
import Accounting from '@payfit/unity-illustrations/assets/Accounting'
;<>
  <Illustration variant="picture" src={Accounting} alt="Accounting" />
  <LazyIllustration variant="picture" name="Accounting" alt="Accounting" />
</>
```

## Migrate from Midnight

Map both `Illustration` and `v2/Illustration` to `Illustration` or
`LazyIllustration`. Treat the previous asset name as search input and confirm
the target in the catalog instead of assuming a one-to-one name match.

- Use an eager catalog import for immediately visible artwork.
- Use `LazyIllustration` for below-the-fold or code-split artwork and for an
  asset that should load by catalog name.
- Re-evaluate `alt` and `isDecorative` from the artwork's role in the migrated
  screen; do not copy inaccessible legacy behavior.

Use `unity-migrate-from-midnight` for the surrounding screen migration and
return here to select and load the asset.

For broader browsing, use the [static illustration catalog](https://unity-illustrations.payfit.io/?path=/docs/reference-find-my-illustration--docs) or [animation catalog](https://unity-illustrations.payfit.io/?path=/docs/reference-find-my-animation--docs).