# 🎨 Beam Icons

2,700+ professionally designed React icon components for the Beam Design System. Includes UI icons, illustrative icons, brand logos, country flags, and payment method icons.

## 🔖 Table of Contents

1. [✨ Features](#features)
2. [💻 Installation](#installation)
3. [🛠️ Usage](#usage)
4. [🎨 Icon Gallery](#icon-gallery)
5. [✅ Best Practices](#best-practices)
6. [🌲 Tree-Shaking](#tree-shaking)

## Features

- **2,700+ UI Icons** - Comprehensive set of interface icons for every use case
- **380+ Illustrative Icons** - Detailed illustrations for empty states and onboarding
- **650+ Logo Icons** - Airlines, banks, payment methods, flags, and Viasat branding
- **Tree-Shakable** - Only bundle the icons you use
- **TypeScript** - Full type definitions included
- **Accessible** - ARIA labels and semantic markup
- **Customizable** - Size, color, and styling props

## Installation

```bash
npm install @viasat/beam-icons
```

```bash
yarn add @viasat/beam-icons
```

```bash
pnpm add @viasat/beam-icons
```

## Usage

### Basic Usage

```tsx
import { Check, Close, ChevronDown } from '@viasat/beam-icons';

function MyComponent() {
  return (
    <div>
      <Check />
      <Close />
      <ChevronDown />
    </div>
  );
}
```

### Direct Component Import

For maximum tree-shaking efficiency:

```tsx
import Check from '@viasat/beam-icons/Check';
import Close from '@viasat/beam-icons/Close';
```

### Using with Beam Icon Component

For standardized sizing, theming, and accessibility, use icons with the `Icon` component from `@viasat/beam-react`:

```tsx
import { Icon } from '@viasat/beam-react/Icon';
import { Check, Settings, User } from '@viasat/beam-icons';

function MyComponent() {
  return (
    <div>
      <Icon icon={Check} size="sm" color="success" />
      <Icon icon={Settings} size="md" ariaLabel="Settings" />
      <Icon icon={User} customIconSize={32} customIconColor="#0066cc" />
    </div>
  );
}
```

The `Icon` component provides:

- Consistent sizing (`xs`, `sm`, `md`, `lg`, `xl`)
- Semantic color tokens (`primary`, `success`, `danger`, `warning`)
- Built-in accessibility features
- Theme support
- Custom size and color overrides

### Icon Categories

#### UI Icons

Standard interface icons for buttons, navigation, forms, and general UI elements:

```tsx
import { Home, Settings, Search, User, Calendar, Mail } from '@viasat/beam-icons';
```

#### Illustrative Icons

Detailed illustrations perfect for empty states, onboarding, and feature highlights:

```tsx
import {
  EmptyStateSearch,
  OnboardingWelcome,
  ErrorState,
} from '@viasat/beam-icons/illustrative-icons';
```

#### Payment Method Logos

```tsx
import {
  Visa,
  Mastercard,
  Amex,
  PayPal,
  ApplePay,
} from '@viasat/beam-icons/logos/payments';
```

#### Bank Logos

```tsx
import { BankOfAmerica, Chase, WellsFargo } from '@viasat/beam-icons/logos/banks';
```

#### Airline Logos

```tsx
import { Delta, United, AmericanAirlines } from '@viasat/beam-icons/logos/airlines';
```

#### Country Flags

```tsx
import { UnitedStates, Canada, Mexico } from '@viasat/beam-icons/logos/flags';
```

#### Viasat Branding

```tsx
import {
  ViasatLogoDefault,
  ViasatLogoWhite,
  ViasatLogomarkColor,
} from '@viasat/beam-icons/logos/viasat';
```

## Props

All icon components accept standard SVG props:

```tsx
<Check
  width={24}
  height={24}
  color="currentColor"
  className="my-icon"
  aria-label="Success"
/>
```

### Common Props

- `width` / `height` - Size in pixels (default: 24)
- `color` - Fill color (default: currentColor)
- `className` - CSS class for styling
- `aria-label` - Accessibility label
- Standard HTML/SVG attributes

## Icon Gallery

Browse and search the complete icon library in Storybook:

### Core Icons

- **[UI Icons](https://storybook-beam.vega.viasat.com/?path=/story/components-icon--all-variants)** - 2,700+ interface icons
- **[Illustrative Icons](https://storybook-beam.vega.viasat.com/?path=/story/components-illustrativeicon--all-variants)** - 380+ detailed illustrations

### Logo Icons

- **[Airlines](https://storybook-beam.vega.viasat.com/?path=/story/components-logo-airlines--all-variants)** - Major airline logos
- **[Banks](https://storybook-beam.vega.viasat.com/?path=/docs/components-logo-banks--docs)** - Banking institution logos
- **[Payments](https://storybook-beam.vega.viasat.com/?path=/story/components-logo-payments--all-variants)** - Credit cards and payment method logos
- **[Flags](https://storybook-beam.vega.viasat.com/?path=/story/components-logo-flags--all-variants)** - Country flag icons
- **[Viasat](https://storybook-beam.vega.viasat.com/?path=/story/components-logo-viasat--all-variants)** - Viasat brand assets

## Best Practices

### Sizing

Use consistent icon sizes throughout your application:

```tsx
// Small (16px)
<Icon width={16} height={16} />

// Medium (24px) - Default
<Icon width={24} height={24} />

// Large (32px)
<Icon width={32} height={32} />
```

### Accessibility

Always provide meaningful labels for icons used as interactive elements:

```tsx
// Good
<button aria-label="Close dialog">
  <Close />
</button>

// Better - use with screen reader text
<button>
  <Close aria-hidden="true" />
  <span className="sr-only">Close dialog</span>
</button>
```

### Color

Icons inherit color from their parent by default:

```tsx
// Inherits text color
<div style={{ color: 'blue' }}>
  <Check /> {/* Will be blue */}
</div>

// Explicit color
<Check color="red" />
```

## Tree-Shaking

Beam Icons is fully tree-shakable. Import only what you need:

```tsx
// ✅ Good - Only bundles Check and Close
import { Check, Close } from '@viasat/beam-icons';

// ✅ Better - Most explicit
import Check from '@viasat/beam-icons/Check';
import Close from '@viasat/beam-icons/Close';

// ❌ Avoid - Imports entire library
import * as Icons from '@viasat/beam-icons';
```

## SVG Assets

Access raw SVG files directly:

```ts
import checkSvg from '@viasat/beam-icons/assets/icons/check.svg';
```

## Contributing

This package is part of the Beam Design System monorepo. For contribution guidelines, please refer to the main repository documentation.

## License

MIT © Viasat
