@photosynthesic/nubui

Custom SVG Icons with Tailwind CSS

A lightweight, framework-agnostic tool for managing custom SVG icons and generating Tailwind CSS utility classes. Perfect for teams managing custom icons from various sources and needing a simple, automated workflow.

🎯 Key Features

• 🎨 SVG → CSS Mask Conversion: Automatically convert icons to currentColor-compatible CSS masks
• ⚡ CLI Automation: icon:build command for one-step workflow with preview
• 👁️ Interactive Preview: Visual preview page for generated icons
• 🔍 SVGO Integration: Automatic SVG optimization (configurable)

Installation

npm install @photosynthesic/nubui

Quick Start

1. Generate Icons

Place your SVG files in src/assets/icon/ and run:

npx nubui build

This generates CSS mask utilities from your SVG icons and opens an interactive preview.

2. Use Icons in HTML

<span class="mask-icon-heart w-6 h-6 text-red-500"></span>

CLI Commands

Main Command

npx nubui build    # Generate masks + preview and open browser (recommended)

Individual Commands (for fine-grained control)

npx nubui icon:masks    # Generate icon mask CSS utilities only
npx nubui icon:preview  # Generate icon preview HTML only
npx nubui icon:clean    # Remove generated icon files
npx nubui --help        # Show all available commands

build & icon:masks Options

npx nubui build [OPTIONS]
npx nubui icon:masks [OPTIONS]

OPTIONS:
  -i, --icon-dir <path>   SVG icon directory path
                          (default: ./src/assets/icon)

  -o, --output <path>     Output CSS/SCSS file path
                          (default: ./src/assets/css/icon-masks.css)

  -f, --format <format>   Output format: 'css' or 'scss'
                          (default: css)

  --no-optimize           Skip SVG optimization (svgo)

  -h, --help              Show help message

EXAMPLES:
  # Generate CSS format (default)
  npx nubui build

  # Generate SCSS format
  npx nubui build --format scss --output ./src/assets/scss/_icon-masks.scss

Development Workflow

See Quick Start above for basic setup. For detailed integration with your build system:

Using CSS Format (Default)

The default CSS format works great with any build system that supports CSS imports:

npx nubui build
# Generates: src/assets/css/icon-masks.css

Import in your main CSS file:

@import "./assets/css/icon-masks.css";

Using SCSS Format

If your project uses SCSS, generate in SCSS format:

npx nubui build --format scss --output ./src/assets/scss/_icon-masks.scss

Import in your main SCSS file:

@import "./assets/scss/_icon-masks";

Customizing Icon Directory

By default, nubui looks for SVG files in src/assets/icon/. You can customize this:

npx nubui build --icon-dir ./my-custom-icons

Framework Integration

Astro

Example: Create a reusable Icon component

---
// components/Icon.astro
interface Props {
  name: string;
  size?: 'sm' | 'md' | 'lg';
  class?: string;
}

const { name, size = 'md', class: className } = Astro.props;
const sizeMap = { sm: 'w-4 h-4', md: 'w-6 h-6', lg: 'w-8 h-8' };
---

<span
  class:list={[
    `mask-icon-${name}`,
    sizeMap[size],
    'inline-block',
    className
  ]}
/>

Usage example:

---
import Icon from '../components/Icon.astro';
---

<button class="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded">
  <Icon name="star" size="md" class="text-white" />
  Favorite
</button>

Icon Rendering Modes

nubui supports three ways to use your icons. You can explore each mode interactively in the icon preview page (generated by icon:build):

1. Mask Mode (Default, Recommended)

<span class="mask-icon-star w-6 h-6 text-yellow-500"></span>

Features:

• currentColor support for dynamic theming
• Tailwind CSS text-* classes for color
• Single <span> element in DOM
• Perfect compatibility with pseudo-elements (::before, ::after)

Browser Support:

Uses CSS mask-image which is supported in all modern browsers:

• Chrome 55+ (2016)
• Firefox 53+ (2017)
• Safari 15.4+ (2022)
• Edge 79+ (2020)

Note: Ancient browsers (IE 11, Safari <15.4) are not supported. If you need to support older browsers, use Inline SVG or IMG Mode instead.

2. Inline Mode

Embed SVG directly in HTML for per-path styling and animations.

Features:

• Full control over SVG attributes
• Ability to animate individual paths
• Per-element color control

3. IMG Mode

Reference external SVG files via <img> tag for cleaner markup.

Features:

• Browser caching of SVG files
• Separate SVG file management
• CSS-based styling

Tip: Run npx nubui icon:build and check the generated preview page to see code examples for each mode with your actual icons.

Requirements

• Node.js: 18.0.0 or higher
• TypeScript: 5.0.0 or higher (for development)
• Tailwind CSS: 3.0.0 or higher

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

For issues and questions, please visit our GitHub repository.