Colibri Icon Library

A comprehensive icon system for the Telesign Design System, built with Lit components and optimized SVG loading.

Table of Contents

• Installation
• Basic Usage
• Advanced Usage
• Component API
• Adding Icons
• Development
• Best Practices
• Troubleshooting
• Changelog
• Contributing
• License

Installation

npm install @telesign/colibri-icons

Basic Usage

Register the Component

import { ColIcon } from '@telesign/colibri-icons';

// Register the custom element
customElements.define('col-icon', ColIcon);

Use in HTML

<col-icon name="message" color="#000000" size="24px"></col-icon>

Use in JavaScript/TypeScript

import { html } from 'lit';

html` <col-icon name="lock" color="currentColor" size="20px"></col-icon> `;

Advanced Usage

Dynamic Color Inheritance

The icon component can inherit colors from its parent:

<div style="color: blue">
  <col-icon name="user" color="currentColor"></col-icon>
</div>

Size Variations

Supports both pixel and relative units:

<!-- Pixel sizes -->
<col-icon name="search" size="24px"></col-icon>

<!-- Number (automatically converted to pixels) -->
<col-icon name="menu" size="32"></col-icon>

<!-- Relative units -->
<col-icon name="settings" size="2rem"></col-icon>

Icon Caching

Icons are automatically cached for better performance:

// First load - fetches from file system
<col-icon name="user"></col-icon>

// Subsequent loads - uses cached version
<col-icon name="user"></col-icon>

Component API

Properties

| Property | Type | Default | Description | | -------- | ---------------- | ---------------- | -------------------- | | name | string | 'lock' | Icon name to display | | color | string | 'currentColor' | Icon color | | size | string\|number | '24px' | Icon size |

CSS Custom Properties

The component can be styled using CSS:

col-icon {
  display: inline-block;
  line-height: 0;
}

.icon-container {
  width: 100%;
  height: 100%;
}

Adding Icons

1. Prepare SVG Files

• Export SVG from design tools (e.g., Figma)
• Ensure proper naming convention
• Optimize SVG content

2. Add to Project

# Add SVG file to icons directory
src/
  icons/
    my-new-icon.svg

3. SVG Requirements

• Monochromatic design
• Clean, optimized markup
• Proper viewBox attribute
• No hardcoded colors (unless using currentColor)

Example of a proper SVG:

<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
  <path d="M12 2L2 7l10 5 10-5-10-5z" fill="currentColor"/>
</svg>

Development

Local Development

# Install dependencies
npm install

# Start development server
npm run dev

# Preview production build
npm run preview

Available Scripts

# Build package
npm run build

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run tests in headless mode (CI)
npm run test:headless

# Run tests with visual output
npm run test:visual

# Run tests in debug mode
npm run test:debug

# Run a specific test file
npm test -- --files="src/components/col-icon.test.ts"

# Run tests matching a pattern
npm test -- --files="src/components/**/*.test.ts"

Best Practices

1. Icon Naming

// Good
name = 'user-profile';
name = 'shopping-cart';

// Avoid
name = 'icon1';
name = 'newicon';

2. Color Management

// Good - Inherits from parent
<col-icon color="currentColor"></col-icon>

// Good - Specific color
<col-icon color="#FF0000"></col-icon>

// Avoid - Hardcoded colors in SVG
<svg fill="#000000">...</svg>

3. Size Handling

// Good - Clear sizing
<col-icon size="24px"></col-icon>
<col-icon size="2rem"></col-icon>

// Avoid - Unclear units
<col-icon size="24"></col-icon>

Troubleshooting

Common Issues

1. Icon Not Loading

// Check if icon exists in correct location
// Ensure proper name matching
<col-icon name="exact-file-name"></col-icon>

2. Color Not Applying

// Ensure SVG doesn't have hardcoded colors
// Use currentColor in SVG
<col-icon color="blue"></col-icon>

3. Size Issues

// Be explicit with units
<col-icon size="24px"></col-icon>  // Good
<col-icon size="24"></col-icon>    // May cause issues

Performance Considerations

1. Icon Caching

• Icons are cached automatically
• Cache is shared across instances
• Cache is keyed by icon name and color

2. SVG Optimization

• SVGs are minified during build
• Unnecessary attributes are removed
• Inline styles are optimized

3. Load Time

• Icons are loaded on demand
• Failed loads are handled gracefully
• Cache prevents unnecessary reloads

Changelog

See CHANGELOG.md for a detailed list of changes and version history.

Contributing

We welcome contributions to this icon library. Please feel free to submit pull requests with new icons or improvements.

License

This project is licensed under the MIT License - see the LICENSE file for details.

About Telesign

Telesign helps the world's largest brands connect, protect, and engage with their customers through powerful communication channels.