⚡ High-Performance Icon System - Generate lightning-fast CSS icon classes from SVG files. Dramatically improve your application's performance by replacing inline SVGs with cacheable, optimized CSS classes.

Traditional icon approaches hurt performance:

<!--  SLOW: Inline SVG (repeated 50 times = 50x the code) -->
<svg class="icon" viewBox="0 0 24 24">
  <path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25z"/>
</svg>

Stylicon generates cacheable CSS classes:

<!--  FAST: Single CSS class -->
<i class="icon-edit"></i>

I tested Stylicon against traditional SVG approaches to see if the performance claims hold up.

• Users table with 100 rows, 3 action icons per row (300 icons total)
• Tested with oha HTTP load tester: 100 requests, 10 concurrent connections
• Rails 7 development server, local environment
• Real-world scenario: Edit, Show, Delete icons

Server Performance Stylicon handles 3x more requests per second than the Rails image_tag approach. The difference comes from HTTP request overhead - serving 300 individual SVG files per page puts significant load on the Rails server.

Payload Size Stylicon generates the smallest payload at under 50 KiB. Inline SVG creates massive HTML files (256 KiB) because the same SVG markup gets repeated 100 times. This affects loading speed, especially on slower connections.

HTTP Requests The Rails image_tag approach creates 301 HTTP requests per page load (1 for HTML + 300 for individual SVGs). Stylicon uses just 2 requests - the HTML and one cacheable CSS file.

Caching Benefits The CSS file generated by Stylicon gets cached by browsers, so subsequent page loads and navigation only require the HTML request. This compounds the performance advantage over time

• 🎨 CSS Generation: Convert SVG files to optimized CSS classes with base64 encoding
• ⚡ Performance Focused: Cacheable CSS instead of bloated inline SVG
• 🔄 SVG Transformation: Transform individual or multiple SVG files with styling options
• 📁 Batch Processing: Process entire folders or glob patterns of SVG files
• 🛠️ Customizable: Apply fills, strokes, dimensions, styles, and classes
• 📦 Bundle Optimization: Generate single CSS file for all icons

Install the gem by executing:

gem install stylicon

Or add it to your Gemfile:

bundle add stylicon

Stylicon provides three main modes of operation:

Generate high-performance CSS classes from SVG files:

stylicon [config.yml] [output.css]

Example:

stylicon icons.yml stylicon.css

Create an icons.yml configuration file:

# icons.yml - Configuration for CSS generation
edit:
  path: icons/edit.svg
  class: ".icon-edit"
  background: "#333"

user:
  path: icons/user.svg
  class: [".icon-user", ".user-icon"] 
  background: "currentColor"

home:
  path: icons/home.svg
  class: ".icon-home"
  # background optional - will use mask mode

delete:
  path: icons/delete.svg
  class: ".icon-delete"
  background: "#e74c3c"

This creates a single cacheable CSS file with all your icons as base64-encoded background images:

.icon-edit {
  -webkit-mask-image: url("data:image/svg+xml;base64,PHN2Zy...");
  -webkit-mask-repeat: no-repeat;
  -webkit-mask-size: contain;
  -webkit-mask-position: center;
  display: inline-block;
  background-color: #333;
}

.icon-user, .user-icon {
  -webkit-mask-image: url("data:image/svg+xml;base64,PHN2Zy...");
  -webkit-mask-repeat: no-repeat;
  -webkit-mask-size: contain;
  -webkit-mask-position: center;
  display: inline-block;
  background-color: currentColor;
}

HTML Usage:

<!-- Lightning fast, cacheable icons -->
<i class="icon-user"></i>
<i class="icon-edit"></i>
<i class="icon-delete"></i>

Transform a single SVG file with custom styling:

stylicon --transform-svg input.svg --out output.svg [options]

Example:

stylicon --transform-svg icon.svg --out styled-icon.svg --fill red --width 32 --height 32 --classes "icon small"

Transform multiple SVG files at once for consistent theming:

stylicon --input-folder source/ --out destination/ [options]

-```bash stylicon --transform-svg "icons/*.svg" --out transformed/ [options]

**Examples:**
```bash
# Transform all SVGs in icons/ folder
stylicon --input-folder icons/ --out transformed/ --fill blue --width 48

# Transform specific pattern
stylicon --transform-svg "assets/icons/user-*.svg" --out output/ --stroke red --classes "icon user"

# Transform all SVGs recursively
stylicon --transform-svg "**/*.svg" --out flattened/ --height 24 --width 24

# Add red fill and resize to 24x24
stylicon --transform-svg icon.svg --out icon-red.svg --fill red --width 24 --height 24

Input:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25z"/>
</svg>

Output:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
  <path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25z" fill="red"/>
</svg>

# Transform all SVGs in icons/ folder with consistent styling
stylicon --input-folder icons/ --out themed/ --fill "#333" --classes "icon theme-dark" --width 20 --height 20

This will:

• Process all .svg files in the icons/ folder
• Apply dark fill color #333
• Add classes icon theme-dark
• Resize all icons to 20x20 pixels
• Save to themed/ directory with original filenames

# Transform only user-related icons
stylicon --transform-svg "icons/user-*.svg" --out user-icons/ --stroke blue --classes "user-icon"

# Transform all SVGs in any subdirectory
stylicon --transform-svg "**/social-*.svg" --out social/ --fill currentColor --width 16

# Apply multiple style attributes
stylicon --transform-svg logo.svg --out styled-logo.svg \
  --fill "#FF6B6B" \
  --stroke "#4ECDC4" \
  --width 64 \
  --height 64 \
  --style "filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.3));" \
  --classes "logo featured"

# Generate cacheable icon CSS for maximum performance
stylicon icons.yml icons.css

# Result: Single 45KB CSS file replaces 2MB of inline SVG

# Generate separate cached CSS files for each theme
stylicon --input-folder icons/ --out icons-dark.css --fill "#ffffff" --classes "icon dark"
stylicon --input-folder icons/ --out icons-light.css --fill "#000000" --classes "icon light"

# Users download only the theme they need, cached forever

# Small icons for mobile (minimal bandwidth)
stylicon --transform-svg "icons/*.svg" --out icons-sm/ --width 16 --height 16 --classes "icon icon-sm"

# Large icons for desktop (cached separately)
stylicon --transform-svg "icons/*.svg" --out icons-lg/ --width 48 --height 48 --classes "icon icon-lg"

# BEST: Single cached CSS file
stylicon icons.yml production-icons.css

# AVOID: Individual icon transformations for web use

# Generate size-specific CSS files for optimal caching
stylicon icons.yml icons-16.css --width 16 --height 16
stylicon icons.yml icons-24.css --width 24 --height 24  
stylicon icons.yml icons-32.css --width 32 --height 32

# Create production bundle
stylicon --input-folder src/icons/ --out dist/icons.css \
  --fill currentColor \
  --classes "icon" \
  --width 20 \
  --height 20

# Result: One cached file, infinite reuse, zero overhead

• Inline SVG: Each icon = new DOM node + XML parsing
• CSS Classes: Each icon = lightweight element + cached background

• Inline SVG: Repeated code on every page load
• CSS Classes: Download once, cached across entire app

• Inline SVG: Browser parses XML structure for each icon
• CSS Classes: Browser applies cached background image

• Inline SVG: Update icon = find/replace across entire codebase
• CSS Classes: Update icon = regenerate CSS file

# Create consistent icon set for UI library
stylicon --input-folder raw-icons/ --out ui-icons/ \
  --fill currentColor \
  --width 20 \
  --height 20 \
  --classes "ui-icon"

# Generate dark theme icons
stylicon --input-folder icons/ --out icons-dark/ --fill "#ffffff" --classes "icon dark"

# Generate light theme icons  
stylicon --input-folder icons/ --out icons-light/ --fill "#000000" --classes "icon light"

# Small icons (16px)
stylicon --transform-svg "icons/*.svg" --out icons-sm/ --width 16 --height 16 --classes "icon icon-sm"

# Large icons (48px)
stylicon --transform-svg "icons/*.svg" --out icons-lg/ --width 48 --height 48 --classes "icon icon-lg"

#!/bin/bash
# build-icons.sh

# Generate themed icon sets
stylicon --input-folder src/icons/ --out dist/icons/light/ --fill "#2c3e50" --classes "icon light-theme"
stylicon --input-folder src/icons/ --out dist/icons/dark/ --fill "#ecf0f1" --classes "icon dark-theme"

# Generate size variants
stylicon --input-folder src/icons/ --out dist/icons/sm/ --width 16 --height 16 --classes "icon icon-sm"
stylicon --input-folder src/icons/ --out dist/icons/lg/ --width 32 --height 32 --classes "icon icon-lg"

echo "Icon generation complete!"

# Process icons during deployment
stylicon --input-folder assets/raw-icons/ --out public/icons/ \
  --fill currentColor \
  --classes "app-icon" \
  --width 24 \
  --height 24

• Ruby >= 3.1.0
• Nokogiri gem (for XML processing)

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/stylicon. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Stylicon project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.