npm package: @polarityio/pi-icon
Description: FontAwesome SVG icon component with configurable size, color, and spin animation
Latest version: 1.0.2

# Polarity Integration Component Library

## Icon Component

Renders FontAwesome SVG icons with named sizes, semantic colors, and optional spin animation.

## Installation

```bash
npm install @polarityio/pi-icon
```

### Peer Dependencies

- [lit](https://lit.dev/) ^3.0.0

## Usage

```javascript
import '@polarityio/pi-icon';
import { faStar, faShieldHalved, faSpinner, faBell } from '@polarityio/pi-icon';
```

### Basic Icon

```html
<pi-icon .icon=${faStar}></pi-icon>
```

### Sized and Colored Icon

```html
<pi-icon .icon=${faShieldHalved} size="lg" color="success"></pi-icon>
```

### Spinning Icon

```html
<pi-icon .icon=${faSpinner} spin></pi-icon>
```

### Accessible Icon with Label

```html
<pi-icon .icon=${faBell} label="Notifications"></pi-icon>
```

## Icons Export

The package re-exports all FontAwesome Free Solid SVG icons from `@fortawesome/free-solid-svg-icons`:

```javascript
import { faStar, faUser, faGear, faBell } from '@polarityio/pi-icon';
```

This is a convenience re-export — you can import any icon from the FontAwesome Free Solid set directly through this package.

## API Reference

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `IconDefinition \| undefined` | `undefined` | The FontAwesome icon definition to render. |
| `size` | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| undefined` | `undefined` | Named size of the icon. |
| `color` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'urgent' \| 'inverse' \| 'disabled' \| undefined` | `undefined` | Semantic color variant. |
| `label` | `string \| undefined` | `undefined` | Accessible label for screen readers. When set, the icon gets `role="img"`. |
| `spin` | `boolean` | `false` | Enables continuous rotation animation. Reflected to attribute. |
| `spinSpeed` | `string \| undefined` | `undefined` | CSS time value for animation duration (e.g., `'0.5s'`, `'2s'`). Set via `spin-speed` attribute. |

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--pi-icon-size` | `16px` | Override the default icon size. |
| `--pi-icon-color` | `currentColor` | Override the icon color. |
| `--pi-icon-spin-speed` | `2s` | Override the spin animation speed. |
| `--pi-icon-size-xs` | `12px` | Size for `size="xs"`. |
| `--pi-icon-size-sm` | `14px` | Size for `size="sm"`. |
| `--pi-icon-size-base` | `16px` | Size for `size="base"`. |
| `--pi-icon-size-lg` | `20px` | Size for `size="lg"`. |
| `--pi-icon-size-xl` | `24px` | Size for `size="xl"`. |
| `--pi-icon-size-2xl` | `32px` | Size for `size="2xl"`. |

### Color Token Mapping

When using the `color` property, the icon color is set via the corresponding design token:

| Color Value | CSS Token Used |
| --- | --- |
| `primary` | `--pi-color-font-primary` |
| `secondary` | `--pi-color-font-secondary` |
| `success` | `--pi-color-font-success` |
| `warning` | `--pi-color-font-warning` |
| `danger` | `--pi-color-font-danger` |
| `info` | `--pi-color-font-info` |
| `urgent` | `--pi-color-font-urgent` |
| `inverse` | `--pi-color-font-inverse` |
| `disabled` | `--pi-color-font-disabled` |

## Accessibility

- When no `label` is provided, the icon is decorative: `role="presentation"` and `aria-hidden="true"`.
- When `label` is provided, the icon is semantic: `role="img"` and `aria-label` is set.

## Theming

Customize the appearance using CSS custom properties. This component uses design tokens from `@polarityio/pi-shared` for consistent theming across the component library.

## License

MIT