# Icon Catalog

> 60+ icons organized by category for trust badges and UI elements

Canonical URL: https://fa7e86e3d553:3005/resources/icon-catalog

## Overview

The **Icon Catalog** is a JSON object containing 60+ icons organized by
category. Use it only for props whose current island schema accepts a
free-form icon name.

**URI**: `vibe://catalog/icons`  
**Format**: `application/json`  
**When to use**: After the selected island schema confirms an `icon` field.

## Structure

The catalog is a JSON object organized by category:

```typescript
{
  commerce: string[];      // Cart, checkout, payment icons
  trust: string[];         // Shields, locks, stars, awards
  shipping: string[];      // Trucks, boxes, delivery icons
  nature: string[];        // Organic/natural product icons
  ui: string[];            // Generic UI icons (arrows, check, x)
  navigation: string[];    // Menu, search, home, map
  people: string[];        // User, profile icons
  media: string[];         // Play, pause, camera, video
  misc: string[];          // Clock, calendar, settings, etc.
}
```

## Complete Icon List

### Commerce (5 icons)

- `cart` — Shopping cart
- `credit-card` — Credit card / payment
- `tag` — Price tag / discount
- `gift` — Gift / promotion
- `shopping-bag` — Shopping bag

### Trust (7 icons)

- `shield` — Security shield
- `shield-check` — Shield with checkmark (verified)
- `lock` — Padlock (secure)
- `check-circle` — Circle checkmark (verified)
- `star` — Star rating
- `award` — Award badge
- `heart` — Heart (favorite/loved)

### Shipping (3 icons)

- `truck` — Delivery truck
- `box` — Package box
- `refresh-cw` — Returns/exchanges (circular arrows)

### Nature (5 icons)

- `leaf` — Leaf (organic/natural)
- `sun` — Sun (brightness/energy)
- `moon` — Moon (night/sleep)
- `cloud` — Cloud (weather)
- `zap` — Lightning bolt (energy/fast)

### UI (16 icons)

- `x` — Close icon
- `check` — Checkmark
- `chevron-down` — Down arrow
- `chevron-up` — Up arrow
- `chevron-left` — Left arrow
- `chevron-right` — Right arrow
- `arrow-right` — Right arrow (different style)
- `arrow-left` — Left arrow (different style)
- `external-link` — External link icon
- `info` — Information circle
- `alert-circle` — Alert/warning circle
- `maximize` — Fullscreen expand
- `minimize` — Fullscreen collapse
- `minus` — Minus sign
- `plus` — Plus sign
- `filter` — Filter icon

### Navigation (4 icons)

- `menu` — Hamburger menu (3 lines)
- `search` — Search/magnifying glass
- `home` — Home icon
- `map-pin` — Location pin

### People (3 icons)

- `user` — Single user
- `users` — Multiple users (group)
- `user-check` — Verified user

### Media (5 icons)

- `play` — Play button
- `pause` — Pause button
- `volume` — Volume/speaker
- `camera` — Camera
- `image` — Image/photo

### Misc (12+ icons)

- `phone` — Phone
- `mail` — Email envelope
- `message-circle` — Chat bubble
- `clock` — Clock/time
- `calendar` — Calendar/date
- `globe` — Globe/web
- `download` — Download arrow
- `upload` — Upload arrow
- `settings` — Settings gear
- `trash` — Delete/trash
- `edit` — Edit pencil
- `share` — Share icon
- `link` — Link chain
- `bookmark` — Bookmark
- `flag` — Flag
- `bell` — Notification bell
- `eye` — Visible/show
- `eye-off` — Hidden/hide
- `grid` — Grid layout
- `list` — List layout

## How Icons Are Used

### In an icon-accepting record

The exact surrounding prop depends on the island schema:

```typescript
{
  items: Array<{
    icon: string;   // Icon name from catalog
    label: string;  // Display text
  }>
}
```

## Choosing the Right Icon

**For trust signals:**
- `shield-check` — Best for "Verified" or "Certified"
- `lock` — Best for "Secure" or "Encrypted"
- `star` — Best for ratings or "Top Rated"
- `award` — Best for "Award Winning" or "Best Seller"

**For shipping:**
- `truck` — General delivery, "Fast Shipping"
- `box` — Package tracking, "Carefully Packed"
- `refresh-cw` — Returns, exchanges, "Easy Returns"

**For organic/natural:**
- `leaf` — Organic, natural, eco-friendly
- `sun` — Energy, vitality, daytime use
- `moon` — Night, sleep, relaxation

**For urgency:**
- `zap` — Fast, instant, energy
- `clock` — Time-sensitive, countdown

**For social proof:**
- `heart` — Loved by customers, "Customer Favorite"
- `star` — Highly rated, "5-Star Reviews"
- `users` — Popular, "Thousands of Happy Customers"

## Example Configurations

### E-commerce trust bar

```json
{
  "badges": [
    {"icon": "shield-check", "label": "SSL Secure"},
    {"icon": "truck", "label": "Free 2-Day Shipping"},
    {"icon": "refresh-cw", "label": "60-Day Returns"},
    {"icon": "award", "label": "Best Seller"}
  ]
}
```

### Organic/natural product

```json
{
  "badges": [
    {"icon": "leaf", "label": "100% Organic"},
    {"icon": "heart", "label": "Cruelty-Free"},
    {"icon": "shield", "label": "Dermatologist Tested"},
    {"icon": "zap", "label": "Fast Results"}
  ]
}
```

### Premium/luxury

```json
{
  "badges": [
    {"icon": "award", "label": "Award Winning"},
    {"icon": "star", "label": "5-Star Rated"},
    {"icon": "gift", "label": "Luxury Gift Box"},
    {"icon": "shield-check", "label": "Authenticity Guaranteed"}
  ]
}
```

## Reading the Catalog

**Full catalog:**
```typescript
const catalog = await readResource("vibe://catalog/icons");
const icons = JSON.parse(catalog);

// Access by category
console.log(icons.commerce); // ["cart", "credit-card", "tag", "gift", "shopping-bag"]
```

**Flatten all icons:**
```typescript
const allIcons = Object.values(icons).flat();
console.log(allIcons.length); // 60+
```

**Search for icon:**
```typescript
function findIcon(query: string): string[] {
  return Object.entries(icons)
    .flatMap(([category, names]) => 
      names.filter(n => n.includes(query))
    );
}

findIcon("shield"); // ["shield", "shield-check"]
findIcon("truck");  // ["truck"]
```

## Validation

When composing an icon-accepting prop:

1. **Icon name must be valid**: Must exist in the catalog
2. **Icon name is case-sensitive**: Use exact lowercase-kebab-case
3. **No file extensions**: Pass "shield", not "shield.svg"
4. **No custom icons**: Only catalog icons are supported

**Invalid:**
```json
{"icon": "Shield", "label": "..."}        // Wrong case
{"icon": "shield.svg", "label": "..."}    // File extension
{"icon": "custom-icon", "label": "..."}   // Not in catalog
```

**Valid:**
```json
{"icon": "shield", "label": "Secure"}
{"icon": "shield-check", "label": "Verified"}
{"icon": "truck", "label": "Free Shipping"}
```

## Icon Rendering

Icons are rendered as **Lucide React** components internally. The catalog names map directly to Lucide icon names. When you specify `"icon": "shield"`, the renderer imports and renders `` from `lucide-react`.

This means:
- Icons are **SVG** (scalable, crisp at any size)
- Icons are **accessible** (proper ARIA labels)
- Icons are **themeable** (inherit color via CSS)
- Icons are **lightweight** (tree-shaken, only used icons bundled)

## When to Read This Resource

**Read when:**
- Composing an island prop whose schema accepts a free-form icon
- Browsing available icons by category
- Unsure which icon fits your use case

**Don't read when:**
- You already know the icon name
- Working on non-icon content (most islands don't use icons)
- The generation guide already provided relevant examples

The icon catalog is a lookup table — reference it when you need to pick an icon.