@denariusfinancees/icons-ui/dist/README.md

Library containing Denarius brand UI icons

# Denarius Icons UI

A comprehensive icon library with support for multiple categories, sizes, and modifiers. Built with SASS and optimized for performance and accessibility.

## Features

- **Multiple Icon Categories**: archive, arrow, basic, brand, building, business, call, cars, computers, content, crypto, delivery, design, emails, files, flags, grid, location, money, notifications, programing, school, search, security, settings, shop, support, time, type, users, video, weather
- **Size Variants**: 16px (`.icon--sm`) and 24px (`.icon--md`)
- **Big Picture Modifier**: `.icon--big-picture` for prominent display (94px container with 58px icon)
- **Optimized Output**: Minimal CSS duplication with efficient selectors
- **Flag Support**: Special handling for flag icons with original colors
- **Mask-based Icons**: Color inheritance via `currentColor`
- **Responsive & Accessible**: Touch-friendly and screen reader compatible
- **Development Tools**: Prettier + ESLint for consistent code formatting

## Quick Start

### Basic Usage

```html
<!-- Standard icon -->
<div class="icon-basic-home"></div>

<!-- Small size -->
<div class="icon-basic-home icon--sm"></div>

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

<!-- Big picture modifier -->
<div
  class="icon icon-basic-heart icon--big-picture"
  style="--icon-bg-color: #ff6b6b; color: white;"
></div>
```

### CSS Customization

```css
/* Change icon color */
.icon-basic-home {
  color: #007bff;
}

/* Flag icons don't inherit colors */
.icon-flags-us {
  /* Original colors preserved */
}
```

## Icon Modifiers

### Size Modifiers

- `.icon--sm`: 16px × 16px
- `.icon--md`: 24px × 24px (default)

### Big Picture Modifier

The `.icon--big-picture` modifier creates a prominent circular display:

```html
<div
  class="icon icon-basic-star icon--big-picture"
  style="--icon-bg-color: #feca57; color: white;"
></div>
```

**Features:**

- 94×94px circular background
- 58×58px centered icon
- Dynamic colors via `--icon-bg-color` CSS variable
- Works with all icon categories
- Perfect for CTAs, feature highlights, and dashboard widgets

## Icon Categories

| Category          | Description                            | Color Support      |
| ----------------- | -------------------------------------- | ------------------ |
| **basic**         | Common UI icons (home, settings, etc.) | ✅ Inherits color  |
| **flags**         | Country flags                          | ❌ Original colors |
| **brand**         | Company logos                          | ✅ Inherits color  |
| **arrow**         | Directional arrows                     | ✅ Inherits color  |
| **money**         | Financial icons                        | ✅ Inherits color  |
| **users**         | User-related icons                     | ✅ Inherits color  |
| _...and 20+ more_ |                                        |                    |

## Advanced Usage

### Theme Integration

```scss
// Dark mode support
.icon-theme {
  color: #333;

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

// CSS variables for theming
.theme-system {
  --icon-primary: #007bff;
  --icon-secondary: #6c757d;

  .icon-basic-home {
    color: var(--icon-primary);

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

### Responsive Patterns

```scss
// Mobile-first responsive sizing
.icon-responsive {
  width: 16px;
  height: 16px;

  @media (min-width: 768px) {
    width: 24px;
    height: 24px;
  }

  @media (min-width: 1024px) {
    width: 32px;
    height: 32px;
  }
}
```

### Animation Integration

```scss
// Spinning icon
.icon-spinner {
  animation: spin 1s linear infinite;
}

// Pulse effect
.icon-notification {
  animation: pulse 2s ease infinite;
}

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

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

## Development

### Project Structure

```
denarius-Icons-UI/
├── assets/                      # Icon source files
│ ├── icons/svg/                # SVG icons by category
│ └── animations/               # Animation files
├── src/styles/mixins/          # SASS source files
│ ├── _denarius-ui-icons.scss   # Main icon library
│ ├── _denarius-ui-icon-helpers.scss # Helper mixins
│ └── _icon-map.scss            # Auto-generated icon map
├── scripts/                    # Build automation
│ ├── generate-icon-map.js      # Icon discovery
│ ├── generate-demo.js          # Demo generation
│ └── copy-files.js             # Asset copying
├── dist/                       # Distribution files
│ ├── css/                      # Compiled CSS
│ ├── scss/                     # SASS files
│ └── assets/                   # Copied assets
└── demo/                       # Auto-generated demo
```

### Build Commands

````bash
# Full build (generate map + copy files + compile SASS)
npm run build

# Generate demo site
npm run demo

### Code Quality Tools

```bash
# Format all code files
npm run format

# Check formatting without changes
npm run format:check

# Lint and fix JavaScript
npm run lint
````

## Technical Details

### Icon Implementation

The library uses two approaches for displaying icons:

1. **Mask-based Icons** (most categories):

   ```css
   .icon-basic-home {
     mask-image: url('../assets/icons/svg/basic/basic-24-home.svg');
     -webkit-mask-image: url('../assets/icons/svg/basic/basic-24-home.svg');
     background-color: currentColor;
   }
   ```

2. **Flag Icons** (flags category):
   ```css
   .icon-flags-us {
     background-image: url('../assets/icons/svg/flags/flags-24-us.svg');
     background-size: contain;
   }
   ```

### CSS Optimization

- **Shared Properties**: Common styles via SASS extends
- **Efficient Selectors**: Optimized for minimal CSS output
- **Vendor Prefixes**: Automatic webkit support for masks
- **File Size**: Compressed output with minimal duplication

### Browser Support

| Feature       | Chrome | Firefox | Safari | Edge |
| ------------- | ------ | ------- | ------ | ---- |
| CSS Masks     | 51+    | 53+     | 9.1+   | 79+  |
| CSS Variables | 49+    | 31+     | 9.1+   | 79+  |
| CSS Grid      | 57+    | 52+     | 10.1+  | 79+  |

## Best Practices

### Accessibility

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

<!-- Icon with descriptive text -->
<div class="icon-with-text">
  <span class="icon-basic-info" aria-hidden="true"></span>
  <span>Important information</span>
</div>
```

### Performance

- Use standard sizes (16px, 24px) for consistency
- Implement lazy loading for large icon sets
- Consider sprite sheets for multiple icons
- Optimize SVG files before adding to library

### Color Management

- Use CSS variables for theme colors
- Ensure sufficient color contrast (WCAG AA)
- Consider reduced motion preferences
- Use `currentColor` for inheriting text color

## Troubleshooting

### Common Issues

**Icons not displaying:**

- Verify SVG file paths are correct
- Check browser support for CSS masks
- Ensure no conflicting styles

**Colors not applying:**

- Confirm icon uses mask-based approach
- Check for conflicting `background-color` rules
- Verify CSS variable values

**Big picture modifier issues:**

- Ensure `--icon-bg-color` is set
- Check z-index conflicts
- Verify icon class is correct

## Contributing

### Adding New Icons

1. Add SVG file to `assets/icons/svg/[category]/`
2. Run `npm run build` to regenerate icon map
3. Test in demo site

### Creating New Modifiers

```scss
// Add to _denarius-ui-icons.scss
.icon--new-modifier {
  // Implementation
}
```

## Installation & Integration

### NPM Installation

```bash
# Using npm
npm install @denariusfinancees/icons-ui

# Using yarn
yarn add @denariusfinancees/icons-ui
```

### CSS Integration

```html
<!-- HTML -->
<link
  rel="stylesheet"
  href="node_modules/@denariusfinancees/icons-ui/dist/css/denarius-ui-icons.css"
/>
```

```javascript
// JavaScript/ES6
import '@denariusfinancees/icons-ui/dist/css/denarius-ui-icons.css';
```

```scss
// SASS
@import 'node_modules/@denariusfinancees/icons-ui/dist/css/denarius-ui-icons.css';
```

### Angular Integration

1. **Install the package:**

```bash
npm install @denariusfinancees/icons-ui
```

2. **Add to angular.json:**

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "node_modules/@denariusfinancees/icons-ui/dist/css/denarius-ui-icons.min.css"
            ],
            "assets": [
              {
                "glob": "**/*",
                "input": "node_modules/@denariusfinancees/icons-ui/dist/assets/",
                "output": "/assets/icons/"
              }
            ]
          }
        }
      }
    }
  }
}
```

3. **Use in components:**

```html
<div class="icon-basic-home"></div>
<div
  class="icon icon-basic-heart icon--big-picture"
  [style.--icon-bg-color]="'#ff6b6b'"
  style="color: white;"
></div>
```

## License

MIT License - see LICENSE file for details.

## Support

For issues, questions, or contributions:

- Repository: [Denarius Icons UI](https://dev.azure.com/DenariusEs/Design-System/_git/denarius-Icons-UI)
- Author: fernando.martinez@denarius.es

```

```