@denariusfinancees/icons-ui v1.0.0-beta.1

Icon Library

A comprehensive icon library with support for multiple categories and sizes.

Features

• Multiple icon categories (archive, arrow, basic, flags, etc.)
• Two size variants: 16px and 24px
• Optimized CSS output with minimal duplication
• Special handling for flag icons (displayed with original colors)
• Mask-based icons for color inheritance
• Responsive and accessible

Installation

npm install

NPM Installation

# Using npm
npm install @denarius/icons-ui

# Using yarn
yarn add @denarius/icons-ui

Usage

HTML

<!-- Basic icon -->
<div class="icon-basic-home"></div>

<!-- Icon with size modifier -->
<div class="icon-basic-home icon--sm"></div>

<!-- Flag icon (displays with original colors) -->
<div class="icon-flags-us"></div>

CSS

/* Custom styling for icons */
.icon-basic-home {
  color: blue; /* This will change the color of the icon */
}

/* Flag icons maintain their original colors */
.icon-flags-us {
  /* No color property needed for flags */
}

Icon Categories

The library includes the following icon categories:

• archive
• arrow
• basic
• flags (special handling with original colors)
• and many more...

Advanced Usage

Theme Integration

// Dark mode support
.icon-theme {
  @include icon-mask("../assets/icons/theme.svg", #333);

  @media (prefers-color-scheme: dark) {
    background-color: #fff;
  }
}

// Custom theme colors
.custom-theme {
  --icon-primary: #007bff;
  --icon-secondary: #6c757d;

  .icon-custom {
    @include icon-mask("../assets/icons/custom.svg", var(--icon-primary));

    &:hover {
      background-color: var(--icon-secondary);
    }
  }
}

Responsive Patterns

// Mobile-first approach
.icon-responsive {
  @include icon-complete(
    "../assets/icons/responsive.svg",
    (
      size: 16px,
      color: #007bff,
      responsive: true,
    )
  );
}

// Custom breakpoints
.icon-custom-responsive {
  @include icon-size(16px);

  @media (min-width: 576px) {
    @include icon-size(20px);
  }
  @media (min-width: 768px) {
    @include icon-size(24px);
  }
  @media (min-width: 992px) {
    @include icon-size(32px);
  }
}

Animation Integration

// Rotating icon
.icon-spinner {
  @include icon-complete(
    "../assets/icons/spinner.svg",
    (
      size: 24px,
      color: #007bff,
      transition: 0.3s,
    )
  );
  animation: spin 1s linear infinite;
}

// Pulse effect
.icon-notification {
  @include icon-complete(
    "../assets/icons/notification.svg",
    (
      size: 24px,
      color: #dc3545,
      transition: 0.3s,
    )
  );
  animation: pulse 2s ease infinite;
}

@keyframes spin {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

@keyframes pulse {
  0% {
    transform: scale(1);
  }
  50% {
    transform: scale(1.2);
  }
  100% {
    transform: scale(1);
  }
}

Best Practices

1. Icon Sizing

   • Use standard sizes (16px, 24px, 32px) for consistency
   • Implement responsive sizes based on viewport
   • Consider touch target sizes for interactive icons (minimum 44x44px)

2. Color Management

   • Use CSS variables for theme colors
   • Implement consistent hover states
   • Consider color contrast for accessibility
   • Use currentColor for icons that should inherit text color

3. Performance

   • Optimize SVG files before usage
   • Use appropriate caching strategies
   • Implement lazy loading for large icon sets
   • Consider using sprite sheets for multiple icons

4. Accessibility

   • Add appropriate aria-label attributes
   • Ensure sufficient color contrast
   • Provide text alternatives where needed
   • Consider reduced motion preferences

<!-- Accessible icon button -->
<button class="icon-button" aria-label="Close dialog">
  <span class="icon-close" aria-hidden="true"></span>
</button>

<!-- Icon with text -->
<div class="icon-with-text">
  <span class="icon-info" aria-hidden="true"></span>
  <span>Information</span>
</div>

Troubleshooting

Common issues and solutions:

1. Icons not displaying

   • Check if paths to SVG files are correct
   • Verify SVG files are properly optimized
   • Ensure mask properties are supported in target browsers

2. Colors not applying

   • Verify the icon is using icon-mask mixin
   • Check if color values are valid
   • Ensure no conflicting styles are present

3. Responsive issues

   • Verify media query breakpoints
   • Check if responsive option is enabled
   • Ensure parent container isn't restricting size

4. Performance concerns

   • Optimize SVG files
   • Use appropriate caching
   • Consider lazy loading
   • Implement sprite sheets for multiple icons

Browser Support

The library supports all modern browsers with the following features:

• CSS Masks
• CSS Custom Properties (variables)
• CSS Grid
• Flexbox
• CSS Animations

Contributing

1. Adding new icons

   # Add SVG file to assets/icons directory
   npm run build  # Regenerates icon map

2. Creating new mixins

   // Add to styles/mixins/_icon-helpers.scss
   @mixin icon-new-feature($param) {
     // Implementation
   }

Development

Project Structure

IconLibrary/
├── dist/                        # Distribution files
│ ├── assets/                    # Copied assets
│ │   └── icons/                 # SVG icons
│ └── css/                       # Compiled CSS
│ └── Scss/                      # Helper Mixins
│
├── assets/                      # Asset files
│ ├── icons/                     # SVG icons
│ └── animations/                # Animation files
│
├── styles/                      # SASS styles
│ └── mixins/                    # SASS mixins
│   ├── icon-library.scss        # Icon library mixins
│   ├── icon-helpers.scss        # Icon helper mixins
│   └── icon-map.scss            # Auto-generated icon map
│
├── scripts/                     # Build scripts
│ ├── generate-icon-map.js       # Generates the icon map
│ ├── generate-demo.js           # Generates demo HTML
│ └── copy-files.js              # Copies files to dist
│
├── demo/                        # Auto-generated Demo files and documentation
└── azure-pipelines.yml          # CI/CD pipeline configuration

Build Process

The project provides two main scripts:

1. Build the library:

   npm run build

   This script generates the icon map, builds the SASS files, and copies all necessary files to the distribution folder.

2. Generate demo:

   npm run demo

   This script generates a demo HTML page showcasing all available icons.

How It Works

Icon Implementation

The library uses two different approaches for displaying icons:

1. Mask-based Icons (most categories):

   • Uses CSS mask properties to display icons
   • Icons inherit the text color via currentColor
   • Allows for easy color customization

2. Flag Icons (flags category):

   • Uses regular background images
   • Icons display with their original colors
   • No color inheritance (flags maintain their design colors)

CSS Optimization

The generated CSS is optimized to minimize file size:

• Common properties are shared via SASS extends
• Separate base classes for different icon types
• Efficient selector structure

License

MIT

Usage with NPM

CSS Usage

<!-- In your HTML file -->
<link
  rel="stylesheet"
  href="node_modules/@denarius/icons-ui/dist/css/icon-library.min.css"
/>

// In your JavaScript file
import "@denarius/icons-ui/dist/css/icon-library.css";