@marioschmidt/design-system-tokens 1.0.69 → 1.0.70

package/README.icons.md

@@ -1,570 +0,0 @@
-# 🖼️ BILD Design System Icons
-
-> **Part of the [BILD Design Ops Pipeline](./README.md)** | [Token Documentation](./README.tokens.md)
-
-Multi-platform icon transformation pipeline for the BILD Design System.
-
-[![npm version](https://img.shields.io/npm/v/@marioschmidt/design-system-icons.svg)](https://www.npmjs.com/package/@marioschmidt/design-system-icons)
-[![Build Status](https://github.com/UXWizard25/vv-token-test-v3/workflows/Build%20Icons/badge.svg)](https://github.com/UXWizard25/vv-token-test-v3/actions)
-
----
-
-## 📋 Table of Contents
-
-- [🎯 Overview](#-overview)
-- [🏗️ Architecture](#️-architecture)
-- [📦 Installation](#-installation)
-- [🚀 Usage](#-usage)
-- [📁 File Structure](#-file-structure)
-- [⚙️ Build Commands](#️-build-commands)
-- [➕ Adding New Icons](#-adding-new-icons)
-- [📝 Naming Conventions](#-naming-conventions)
-- [✅ SVG Requirements](#-svg-requirements)
-- [♿ Accessibility](#-accessibility)
-- [🎨 Theming](#-theming)
-- [🔄 CI/CD Workflows](#-cicd-workflows)
-- [🔢 Codepoint Stability (Flutter)](#-codepoint-stability-flutter)
-- [🆘 Troubleshooting](#-troubleshooting)
-- [📚 Dependencies](#-dependencies)
-- [🔗 Related](#-related)
-- [🤝 Contributing](#-contributing)
-- [📄 License](#-license)
-
----
-
-## 🎯 Overview
-
-This pipeline transforms SVG icons from Figma into optimized, production-ready assets for 5 platforms:
-
-| Platform | Output | Format | Status |
-|----------|--------|--------|--------|
-| **🌐 Web** | `dist/icons/svg/` | Optimized SVG | ✅ Production |
-| **⚛️ React** | `dist/icons/react/` | ESM JavaScript + TypeScript Declarations | ✅ Production |
-| **🤖 Android** | `dist/icons/android/` | Vector Drawable XML | ✅ Production |
-| **💙 Flutter** | `dist/icons/flutter/` | TTF Font + Dart Class | ✅ Production |
-| **🍎 iOS** | `dist/icons/ios/` | Asset Catalog + Swift | ✅ Production |
-
----
-
-## 🏗️ Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                          FIGMA                                  │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │  🖼️ Icon Components                                      │   │
-│  │  • 24x24 viewBox                                         │   │
-│  │  • Single color (converted to currentColor)              │   │
-│  └────────────────────────────┬────────────────────────────┘   │
-└───────────────────────────────┼─────────────────────────────────┘
-                                │
-                                │  TokenSync Plugin Export
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  📁 figma-icons Branch                                          │
-│  src/icons/icon-*.svg                                           │
-└───────────────────────────────┬─────────────────────────────────┘
-                                │
-                                │  GitHub Actions Trigger
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  🔧 BUILD PIPELINE                                              │
-│                                                                 │
-│  ┌───────────────────────────────────────────────────────────┐ │
-│  │ 1️⃣ SVG Validation                                          │ │
-│  │    • Security checks (no scripts, no external refs)       │ │
-│  │    • Structure validation (viewBox, valid SVG)            │ │
-│  └───────────────────────────┬───────────────────────────────┘ │
-│                              │                                  │
-│                              ▼                                  │
-│  ┌───────────────────────────────────────────────────────────┐ │
-│  │ 2️⃣ SVGO Optimization                                       │ │
-│  │    • Convert colors to currentColor                       │ │
-│  │    • Remove metadata & editor data                        │ │
-│  │    • Optimize paths                                       │ │
-│  └───────────────────────────┬───────────────────────────────┘ │
-│                              │                                  │
-│                              ▼                                  │
-│  ┌───────────────────────────────────────────────────────────┐ │
-│  │ 3️⃣ Platform Generation                                     │ │
-│  │                                                           │ │
-│  │  ┌─────────────────────────────────────────────────────┐ │ │
-│  │  │ React: TSX → TypeScript Compilation → ESM + d.ts    │ │ │
-│  │  └─────────────────────────────────────────────────────┘ │ │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐               │ │
-│  │  │ Android  │  │ Flutter  │  │   iOS    │               │ │
-│  │  │   XML    │  │ TTF+Dart │  │ xcassets │               │ │
-│  │  └──────────┘  └──────────┘  └──────────┘               │ │
-│  └───────────────────────────────────────────────────────────┘ │
-└───────────────────────────────┬─────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  📤 OUTPUT: dist/icons/                                         │
-│                                                                 │
-│  ├── svg/           ← Optimized SVGs                           │
-│  ├── react-src/     ← TSX Source (intermediate)                │
-│  ├── react/         ← Compiled ESM + .d.ts + .js.map           │
-│  ├── android/       ← Vector Drawables + attrs                 │
-│  ├── flutter/       ← TTF font + Dart class                    │
-│  └── ios/           ← Asset Catalog + Swift extension          │
-└───────────────────────────────┬─────────────────────────────────┘
-                                │
-                                │  npm publish
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  📦 @marioschmidt/design-system-icons                           │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 📦 Installation
-
-```bash
-npm install @marioschmidt/design-system-icons
-```
-
----
-
-## 🚀 Usage
-
-### ⚛️ React
-
-```tsx
-import { Add, Menu, Search } from '@marioschmidt/design-system-icons';
-
-// Default (decorative icon - hidden from screen readers)
-<Add />
-
-// With size
-<Add size={32} />
-
-// Accessible (visible to screen readers)
-<Add aria-label="Add new item" />
-
-// With tooltip
-<Add title="Add new item" aria-label="Add" />
-
-// Custom styling
-<Add className="text-primary" style={{ color: 'red' }} />
-```
-
-### 🤖 Android
-
-```xml
-<ImageView
-    android:src="@drawable/ic_add"
-    android:layout_width="24dp"
-    android:layout_height="24dp"
-    app:tint="?attr/colorOnSurface" />
-```
-
-Icons automatically use `?attr/colorOnSurface` for Material theming.
-
-### 💙 Flutter
-
-```dart
-import 'package:bild_design_system_icons/icons.dart';
-
-// Static access
-Icon(BildIcons.add)
-Icon(BildIcons.menu, size: 32)
-
-// Dynamic access by name
-Icon(BildIcons.byName('add'))
-
-// List all available icons
-BildIcons.names.forEach((name) => print(name));
-```
-
-### 🍎 iOS (SwiftUI)
-
-```swift
-import BildDesignSystemIcons
-
-// Using enum
-BildIcon.add.image
-    .foregroundColor(.primary)
-
-// With size
-BildIcon.menu.image
-    .font(.system(size: 32))
-
-// Iterate all icons
-ForEach(BildIcon.allCases, id: \.self) { icon in
-    icon.image
-}
-```
-
-### 🌐 SVG (Direct)
-
-```html
-<img src="node_modules/@marioschmidt/design-system-icons/dist/icons/svg/add.svg" alt="Add">
-```
-
----
-
-## 📁 File Structure
-
-```
-src/icons/
-├── icon-add.svg           ← Source SVGs from Figma
-├── icon-menu.svg
-├── icon-search.svg
-└── .codepoints.json       ← Flutter codepoint registry (auto-managed)
-
-scripts/icons/
-├── build-icons.js         ← Main orchestrator
-├── optimize-svg.js        ← SVGO optimization + SVG validation
-├── generate-react.js      ← React TSX generation → react-src/
-├── compile-react.js       ← TypeScript compilation → react/
-├── generate-android.js    ← Android XML generation
-├── generate-flutter.js    ← Flutter font generation
-├── generate-ios.js        ← iOS asset generation
-├── compare-icon-builds.js ← Diff detection for PRs
-└── generate-icon-release-notes.js
-
-build-config/icons/
-└── svgo.config.js         ← SVG optimization config
-
-dist/icons/                 ← Generated output (gitignored)
-├── svg/                   ← Optimized SVGs
-├── react-src/             ← TSX source (intermediate)
-├── react/                 ← Compiled ESM JavaScript
-│   ├── *.js               ← ESM modules
-│   ├── *.d.ts             ← TypeScript declarations
-│   ├── *.js.map           ← Source maps
-│   └── package.json       ← Module configuration
-├── android/
-│   ├── drawable/          ← ic_*.xml files
-│   └── values/            ← attrs_icons.xml
-├── flutter/
-│   ├── fonts/             ← BildIcons.ttf
-│   └── lib/               ← icons.dart
-└── ios/
-    ├── Assets.xcassets/   ← Xcode asset catalog
-    └── Sources/           ← BildIcons.swift
-```
-
----
-
-## ⚙️ Build Commands
-
-```bash
-# Build all platforms
-npm run build:icons
-
-# Build specific platforms
-npm run build:icons:svg      # Only SVGO optimization
-npm run build:icons:react    # Only React components
-npm run build:icons:android  # Only Android drawables
-npm run build:icons:flutter  # Only Flutter font
-npm run build:icons:ios      # Only iOS assets
-
-# Clean build output
-npm run clean:icons
-```
-
----
-
-## ➕ Adding New Icons
-
-### Via Figma (Recommended)
-
-1. Export SVGs from Figma using the **TokenSync Plugin**
-2. Plugin pushes to `figma-icons` branch
-3. CI automatically builds and creates PR
-4. Review and merge PR
-
-### Manual
-
-1. Add SVG to `src/icons/` with naming convention:
-   ```
-   icon-{name}.svg
-
-   Examples:
-   icon-add.svg
-   icon-arrow-left.svg
-   icon-chevron-down.svg
-   ```
-
-2. Run build:
-   ```bash
-   npm run build:icons
-   ```
-
-3. Commit and push
-
----
-
-## 📝 Naming Conventions
-
-### Source Files
-
-| Pattern | Example | Valid |
-|---------|---------|-------|
-| `icon-{name}.svg` | `icon-add.svg` | ✅ |
-| `icon-{name}-{variant}.svg` | `icon-arrow-left.svg` | ✅ |
-| Lowercase only | `icon-add.svg` | ✅ |
-| Kebab-case | `icon-chevron-down.svg` | ✅ |
-| No prefix | `add.svg` | ❌ |
-| Uppercase | `icon-Add.svg` | ❌ |
-| Underscore | `icon_add.svg` | ❌ |
-
-### Generated Output
-
-| Platform | Input | Output |
-|----------|-------|--------|
-| SVG | `icon-add.svg` | `add.svg` |
-| React | `icon-add.svg` | `Add.js` + `Add.d.ts` |
-| Android | `icon-add.svg` | `ic_add.xml` |
-| Flutter | `icon-add.svg` | `BildIcons.add` |
-| iOS | `icon-add.svg` | `BildIcon.add` |
-
----
-
-## ✅ SVG Requirements
-
-### Must Have
-- ✅ `viewBox` attribute (e.g., `viewBox="0 0 24 24"`)
-- ✅ Single color (will be converted to `currentColor`)
-- ✅ Vector paths only (no raster images)
-
-### Recommended
-- 📐 24x24 viewBox (standard icon size)
-- 📏 Centered content with 2px padding
-- 🖌️ Stroke-based or fill-based (not mixed)
-- 📏 Stroke width: 2px for outline icons
-
-### Will Be Removed
-- `width` and `height` attributes
-- Figma/Sketch/Illustrator metadata
-- Comments and doctype
-- Unused definitions
-- Hardcoded colors (replaced with `currentColor`)
-
-### 🔒 Security Validation
-
-The build pipeline validates all SVGs before processing:
-
-| Check | Action |
-|-------|--------|
-| Missing `<svg>` element | ❌ Build fails |
-| Missing `</svg>` tag | ❌ Build fails |
-| `<script>` elements | ❌ Blocked (XSS risk) |
-| `<foreignObject>`, `<iframe>`, `<embed>` | ❌ Blocked |
-| Event handlers (`onclick`, etc.) | ❌ Blocked |
-| `javascript:` URLs | ❌ Blocked |
-| External `xlink:href` | ❌ Blocked |
-| Missing `viewBox` | ⚠️ Warning (continues with default) |
-
----
-
-## ♿ Accessibility
-
-### React Components
-
-```tsx
-// Decorative icon (default)
-// Hidden from screen readers
-<Add />
-// Renders: <svg aria-hidden="true" role="img" ...>
-
-// Meaningful icon
-// Visible to screen readers with label
-<Add aria-label="Add new item" />
-// Renders: <svg aria-label="Add new item" role="img" ...>
-
-// With tooltip
-<Add title="Add new item" aria-label="Add" />
-// Renders: <svg aria-label="Add"><title>Add new item</title>...
-```
-
-### Guidelines
-
-| Use Case | Props | Screen Reader |
-|----------|-------|---------------|
-| Decorative (next to text) | None (default) | Hidden |
-| Standalone button | `aria-label="Action"` | Reads label |
-| With tooltip | `title="..." aria-label="..."` | Reads label |
-
----
-
-## 🎨 Theming
-
-All icons use `currentColor` and inherit the parent's text color:
-
-```css
-/* CSS */
-.icon-container {
-  color: var(--color-icon-primary);
-}
-```
-
-```tsx
-/* React / Tailwind */
-<Add className="text-blue-500" />
-
-/* Inline */
-<Add style={{ color: '#1a73e8' }} />
-```
-
-### Platform-Specific Theming
-
-| Platform | Mechanism |
-|----------|-----------|
-| 🌐 Web/React | CSS `color` property |
-| 🤖 Android | `?attr/colorOnSurface` or `app:tint` |
-| 💙 Flutter | `IconTheme` or `color` parameter |
-| 🍎 iOS | `.foregroundColor()` modifier |
-
----
-
-## 🔄 CI/CD Workflows
-
-### build-icons.yml
-- **Trigger**: Push to `main`, `develop`, `figma-icons`, `claude/**`
-- **Action**: Builds all platforms, uploads artifacts (30-day retention)
-- **PR Comment**: Build summary with download link
-
-### auto-pr-from-figma-icons.yml
-- **Trigger**: Push to `figma-icons` branch
-- **Action**: Builds icons, compares with main, generates release notes
-- **Output**: Creates/updates PR automatically
-
-### publish-icons-on-merge.yml
-- **Trigger**: Merge to `main` with icon changes
-- **Action**: Bumps version (patch), publishes to npm, creates GitHub release
-
----
-
-## 🔢 Codepoint Stability (Flutter)
-
-Flutter icons use a TTF font with stable codepoints. The `.codepoints.json` registry ensures:
-
-- ✅ Existing icons keep their codepoint forever
-- ✅ New icons get the next available codepoint
-- ✅ No breaking changes between versions
-
-```json
-{
-  "nextCodepoint": "e007",
-  "icons": {
-    "add": "e001",
-    "arrow-left": "e002",
-    "arrow-right": "e003"
-  }
-}
-```
-
----
-
-## 🆘 Troubleshooting
-
-### Build fails with "No SVG files found"
-- ✅ Check that SVGs are in `src/icons/`
-- ✅ Verify naming convention: `icon-{name}.svg`
-
-### React components have wrong attribute names
-- Attributes are auto-converted to camelCase
-- `stroke-width` → `strokeWidth`
-
-### Android icons are wrong color
-- Icons use `?attr/colorOnSurface` by default
-- Override with `app:tint="@color/your_color"`
-
-### Flutter font not generating
-- Ensure `fantasticon` is installed
-- Check `dist/icons/flutter/fonts/` for TTF file
-
-### iOS assets not showing
-- Verify `Assets.xcassets` structure
-- Check `Contents.json` has correct filenames
-
----
-
-## 📚 Dependencies
-
-Build-time only (not shipped with package):
-
-| Package | Version | Purpose |
-|---------|---------|---------|
-| svgo | ^3.2.0 | SVG optimization |
-| @svgr/core | ^8.1.0 | React component generation |
-| svg2vectordrawable | ^2.9.1 | Android conversion |
-| fantasticon | ^3.0.0 | Flutter font generation |
-| typescript | ^5.3.0 | React TypeScript compilation |
-| @types/react | ^18.2.0 | React type definitions |
-
----
-
-## 📦 Package Exports
-
-```javascript
-// Main entry (React)
-import { Add } from '@marioschmidt/design-system-icons';
-
-// Platform-specific
-import { Add } from '@marioschmidt/design-system-icons/react';
-
-// Individual icon
-import Add from '@marioschmidt/design-system-icons/react/Add';
-
-// Raw SVG path
-import addSvg from '@marioschmidt/design-system-icons/svg/add.svg';
-```
-
----
-
-## 🔗 Related
-
-| Document | Description |
-|----------|-------------|
-| [📖 README.md](./README.md) | Main project overview |
-| [📖 README.tokens.md](./README.tokens.md) | Token pipeline documentation |
-
----
-
-## 🤝 Contributing
-
-> **⚠️ IMPORTANT: Figma is the Single Source of Truth**
->
-> Icons must **NOT** be edited directly in the repository. All icon changes must be made in Figma and exported via the TokenSync Plugin.
-
-**Workflow:**
-1. Edit/create icons in Figma
-2. Export with TokenSync Plugin
-3. Review and merge PR
-
-**NOT Allowed:**
-- ❌ Direct SVG changes in `src/icons/`
-- ❌ Manual commits to `figma-icons` branch
-- ❌ Changes to generated files
-
-**Allowed (Pipeline Development):**
-- ✅ Changes to build scripts (`scripts/icons/`)
-- ✅ Changes to configuration (`build-config/`)
-- ✅ Workflow adjustments (`.github/workflows/`)
-- ✅ Documentation
-
----
-
-## 📄 License
-
-MIT License - See [LICENSE](./LICENSE) file.
-
----
-
-**Built with ❤️ for the BILD Design System**
-
-| Feature | Status |
-|---------|--------|
-| 5 Platforms | ✅ |
-| TypeScript Support | ✅ |
-| Accessibility | ✅ |
-| Security Validation | ✅ |
-| Stable Codepoints | ✅ |