@tramo-digital/icons

A comprehensive icon library for the Open Design System design system.

Installation

pnpm add @tramo-digital/icons
# or
npm install @tramo-digital/icons

Overview

This package provides a collection of SVG icons optimized for use across the Open Design System design system. Icons are available in five sizes: xs, small, medium, large, and xl.

Available Icons

The package includes unique icon types, each available in multiple sizes:

Navigation & Arrows

• arrow-down, arrow-left, arrow-right, arrow-up
• carat-down, carat-left, carat-right, carat-up
• click-left, click-right

UI Controls

• add, close, minimize
• checkbox, radio, checkmark
• menu, filters, search
• settings, bookmark, external

Social Media

• facebook, instagram, linkedin
• pinterest, reddit, tiktok
• youtube

Business & Industry

• biotech, manufacturing, heart-monitor
• camera, chart, devices
• eco, memory, vision
• rocket, lightbulb, partner
• community, contact, shop
• sync, video-play

Location & Settings

• home, location, language
• account-settings, share

🚀 Usage

Direct Import

Icons can be imported directly as SVG module URLs:

import { AddLarge, SearchMedium, CloseSmall } from '@tramo-digital/icons';

// Use as image source (works in any framework)
const imgElement = document.createElement('img');
imgElement.src = AddLarge;
imgElement.alt = 'Add icon';

Finding Icons Programmatically

import { findSvgIcon, type SvgIconName } from '@tramo-digital/icons';

const icon = findSvgIcon('AddLarge' as SvgIconName);
if (icon) {
  console.log(icon.svgComponent); // SVG file path/URL
}

📏 Icon Sizes

Icons are available in the following sizes:

| Size | Suffix | Typical Use | | ----------- | --------- | ----------- | ---------------------- | | Extra Small | -xs | 12px | Dense UIs, inline text | | Small | -small | 16px | Compact controls | | Medium | -medium | 20px | Default size | | Large | -large | 24px | Prominent actions | | Extra Large | -xl | 32px | Hero sections, CTAs |

🎨 Icon Naming Convention

Icons follow a consistent naming pattern:

{IconName}{Size}

Examples:

• add-small.svg → AddSmall type name
• arrow-right-large.svg → ArrowRightLarge type name
• checkmark-xl.svg → CheckmarkXl type name
• account-settings-medium.svg → AccountSettingsMedium type name

When using with findSvgIcon() or the Icon component, use PascalCase without dashes:

'AddSmall'; // ✅ Correct
'ArrowRightLarge'; // ✅ Correct
'AccountSettingsMedium'; // ✅ Correct
'svg-add-small'; // ❌ Incorrect
'add-small'; // ❌ Incorrect

🔍 TypeScript Support

The package includes full TypeScript definitions:

import type { SvgIconName, SvgIconComponent } from '@tramo-digital/icons';

// All available icon names are typed
const iconName: SvgIconName = 'AddLarge';

// Icon component interface
const icon: SvgIconComponent | undefined = findSvgIcon(iconName);

📁 Package Structure

libs/icons/
├── src/
│   ├── svg/              # SVG source files
│   │   ├── add-small.svg
│   │   ├── add-medium.svg
│   │   └── ...
│   ├── types/
│   │   └── svg.ts        # TypeScript definitions
│   ├── utils/
│   │   └── svgIcons.ts   # Icon lookup utilities
│   └── index.ts          # Main exports
├── dist/                 # Built package
│   └── assets/          # Copied SVG files
└── package.json

🛠️ Development

Building the Package

# Build TypeScript and copy assets
nx run @tramo-digital/icons:build

# Or using pnpm
pnpm nx build @tramo-digital/icons

Updating Icons from Figma

To pull new icons from Figma and regenerate TypeScript exports:

pnpm figma:icons-pull

This command will:

1. Download SVG files from Figma to src/svg/
2. Automatically regenerate src/svg/index.ts - Component imports/exports
3. Automatically regenerate src/types/svg.ts - TypeScript type definitions
4. Automatically regenerate src/utils/svgIcons.ts - Icon lookup utilities

Note: Make sure FIGMA_ACCESS_TOKEN and FIGMA_FILE_KEY are set in your environment or .env file.

📖 Examples

Basic Usage

import { HomeLarge, SearchMedium } from '@tramo-digital/icons';

// Create image elements
const homeIcon = new Image();
homeIcon.src = HomeLarge;
homeIcon.alt = 'Home';

const searchIcon = new Image();
searchIcon.src = SearchMedium;
searchIcon.alt = 'Search';

Dynamic Icon Selection

import { findSvgIcon, type SvgIconName } from '@tramo-digital/icons';

function createIconElement(iconName: SvgIconName): HTMLImageElement | null {
  const icon = findSvgIcon(iconName);

  if (!icon) {
    console.warn(`Icon "${iconName}" not found`);
    return null;
  }

  const img = document.createElement('img');
  img.src = icon.svgComponent;
  img.alt = iconName;
  return img;
}

// Usage
const addIcon = createIconElement('AddLarge');
if (addIcon) {
  document.body.appendChild(addIcon);
}

Using with CSS Background

import { ArrowRightLarge } from '@tramo-digital/icons';

// Set as CSS background image
const button = document.createElement('button');
button.style.backgroundImage = `url(${ArrowRightLarge})`;
button.style.backgroundRepeat = 'no-repeat';
button.style.backgroundPosition = 'center';

Framework Integration

This package is framework-agnostic and can be used with any framework:

• React/Vue: Import icons and use them in img tags or as CSS backgrounds
• Vanilla JS: Use directly with DOM APIs
• Design System Components: Framework-specific Icon components are available in @tramo-digital/react-ui, tramo-digital/vue-ui, and tramo-digital/ds/vanilla-ui`

🎯 Best Practices

1. Choose Appropriate Sizes: Match icon sizes to your UI context:

   • xs for inline text or dense lists
   • small/medium for buttons and controls
   • large/xl for hero sections or prominent CTAs

2. Type Safety: Always use the SvgIconName type when working with icon names to catch typos at compile time.

3. Accessibility: Always provide meaningful alt text or aria-label when using icons.

4. Framework Components: For design system integration, consider using framework-specific Icon components from @tramo-digital/react-ui, tramo-digital/vue-ui, or tramo-digital/ds/vanilla-ui` which provide consistent styling and theming.

5. Error Handling: Always check if findSvgIcon() returns a value before using it.

🔗 Related Packages

For framework-specific Icon components with design system integration:

• @tramo-digital/react-ui - React Icon component
• @tramo-digital/vue-ui - Vue Icon component
• @tramo-digital/vanilla-ui - Vanilla JS Icon component

📄 License

Part of the Open Design System design system. See the main repository for license information.

🤝 Contributing

When adding new icons:

1. Pull icons from Figma: pnpm figma:icons-pull
   • This downloads SVG files and automatically regenerates TypeScript exports
2. Build the package: nx run @tramo-digital/icons:build
3. Test in Storybook: nx run @tramo-digital/react-ui:storybook

Note: If adding SVG files manually, you'll need to run the SVG imports/exports generator separately. However, it's recommended to use pnpm figma:icons-pull which handles everything automatically.

📚 See Also

• Design System Documentation
• Demo Page - Visual catalog of all icons
• Framework-specific Icon components in @tramo-digital/react-ui, tramo-digital/vue-ui, and tramo-digital/ds/vanilla-ui`