npm package: @photosynthesic/nubui
Description: Custom SVG icons instantly usable with Tailwind CSS. Framework-agnostic with mask/inline/img modes.
Author: Photosynthesic
Latest version: 0.1.8

# @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

```bash
npm install @photosynthesic/nubui
```

## Quick Start

### 1. Generate Icons

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

```bash
npx nubui build
```

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

### 2. Use Icons in HTML

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

## CLI Commands

### Main Command

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

### Individual Commands (for fine-grained control)

```bash
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

```bash
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:

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

Import in your main CSS file:

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

### Using SCSS Format

If your project uses SCSS, generate in SCSS format:

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

Import in your main SCSS file:

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

### Customizing Icon Directory

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

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

## Framework Integration

### Astro

Example: Create a reusable Icon component

```astro
---
// 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:

```astro
---
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)

```html
<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](https://github.com/photosynthesic/nubui).