@payfit/unity-icons/README.md

# @payfit/unity-icons

A comprehensive icon library for the Unity design system, provided as React Components.

## Unity v3 compatibility

Unity Icons v3 is released under Unity's shared major version policy. No icon API breaking changes are introduced in this release. Upgrade it together with the other `@payfit/unity-*` packages and follow the [Unity Components 2.x to 3.x migration guide](../components/src/docs/guides/migration/Migrating%20from%202.x%20to%203.x.mdx) for component API changes.

## Installation

Install the package in your project. We recommend you use this package alongside `@payfit/unity-components`.

```bash
pnpm add @payfit/unity-icons @payfit/unity-components
```

Ensure that `react` and `react-dom` are also installed in your project:

```bash
pnpm add react react-dom
```

## Usage

This package provides two ways to import and use icons.

### 1. Import the provider

Wrap your application with the `IconProvider` to make all icons available in your application.

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

function App() {
  return (
    <UnityIconsProvider>
      <MyComponent />
    </UnityIconsProvider>
  )
}
```

### 2. Use the `IconSprite` component

Render any icon using the `IconSprite` component, passing the icon's name as the `src` prop.

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

function MyComponent() {
  return <IconSprite src="Icon1" />
}
```

### 3. Use the Icon component from unity components

You can also use the `Icon` component from `@payfit/unity-components` to render icons (recommended). The `Icon` component provides additional customization options that follow design system guidelines, and uses the `IconSprite` component internally.

```tsx
import { Icon } from '@payfit/unity-components'

function MyComponent() {
  return <Icon src="Icon1" size={20} />
}
```

## API

The icons library uses SVG sprites to render icons. All icons are referenced by their name, which is the filename in the `/svg` folder without the extension.
The `IconSprite` component accepts all the props of an SVG element.

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

function MyComponent() {
  return <IconSprite src="AirplaneFilled" width="32" height="32" fill="#000" />
}
```

We recommend you customize the icon's color, sizes, and other properties via the `Icon` component from `@payfit/unity-components`.

## Customization

All icons use `currentColor` for their fill or stroke, allowing you to easily customize the color using CSS or the `color` prop.

## TypeScript Support

This package includes TypeScript definitions, and a list of all the available icon names is exported as a type.

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

const myIcons: UnityIcon[] = ['AirplaneFilled', 'CakeOutlined']

console.log(iconNames) // ['AirplaneFilled', 'AirplaneOutlined', ...+309 icons more]
```

## Figma Code Connect

This package includes Figma Code Connect integration, which displays the correct `<Icon />` usage directly in Figma Dev Mode when inspecting icon components.

### How It Works

The `Icon.figma.tsx` file is auto-generated by the sync script and contains `figma.connect()` calls for all icons. Each icon maps:

- **Type variant** (Filled/Outlined) to the `src` prop
- **Size variant** (20/24) to the `size` prop

### Publishing Code Connect

After running the sync script, publish the Code Connect configuration to Figma:

```bash
cd libs/shared/unity/icons
npx figma connect publish
```

This requires `FIGMA_ACCESS_TOKEN` to be set in your environment.

## Syncing Icons from Figma

The icon library is synced from Figma using the `sync-unity-icons` script, which:

1. Downloads SVG icons from Figma (with breaking change detection)
2. Generates the Code Connect configuration file

To run the sync:

```bash
npx tsx libs/shared/unity/icons/scripts/sync-unity-icons.ts
```

Required environment variables:

- `FIGMA_UNITY_SYNC_ACCESS_TOKEN` - Figma access token (or use refresh token credentials)

## Browser Support

This package supports all modern evergreen browsers. It does not support IE.

## How to release manually

Add an emoji below:

- 🦄
- 🏰

In some cases, local hr-apps libraries are not published properly, which fails install for `@payfit/payslip-template` afterward.