@nice2dev/icons 1.0.0

package/README.md

@@ -0,0 +1,581 @@
+# @nice2dev/icons
+
+Beautiful, lightweight, multi-color SVG icon library for React with 65+ CSS animations, four rendering variants, gradient fills, and a built-in icon picker component.
+
+[![npm](https://img.shields.io/npm/v/@nice2dev/icons)](https://www.npmjs.com/package/@nice2dev/icons)
+[![license](https://img.shields.io/npm/l/@nice2dev/icons)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [Icon Component Props (`NtdIconProps`)](#icon-component-props-ntdiconprops)
+  - [Size Presets (`IconSize`)](#size-presets-iconsize)
+  - [Variants (`IconVariant`)](#variants-iconvariant)
+  - [Colors & Opacity](#colors--opacity)
+  - [Animations (`IconAnimation`)](#animations-iconanimation)
+  - [Gradient Fills](#gradient-fills)
+  - [Accessibility](#accessibility)
+- [NiceIconPicker](#niceiconpicker)
+  - [IconPickerEntry](#iconpickerentry)
+  - [NiceIconPickerProps](#niceiconpickerprops)
+  - [NiceIconPickerHandle (imperative ref)](#niceiconpickerhandle-imperative-ref)
+- [Creating Custom Icons (`createIcon`)](#creating-custom-icons-createicon)
+  - [CreateIconOptions](#createiconoptions)
+  - [IconPathRenderer](#iconpathrenderer)
+  - [IconRenderProps](#iconrenderprops)
+- [Full Icon Catalog](#full-icon-catalog)
+- [Full Animation Catalog](#full-animation-catalog)
+- [CSS Theming Variables](#css-theming-variables)
+- [Tree Shaking](#tree-shaking)
+- [Storybook](#storybook)
+- [Build & Development](#build--development)
+- [License](#license)
+
+---
+
+## Features
+
+- **300+ icons** across 17 categories (navigation, actions, UI, media, files, fun, weather, shapes, business, social, devtech, health, brand, brand-studio, brand-lockup, brand-enterprise)
+- **4 variants** per icon — `solid`, `outline`, `duotone`, `flat` (badge-style)
+- **Multi-color** — `primaryColor`, `secondaryColor`, `accentColor` with per-channel opacity
+- **Gradient fills** — 12 built-in presets (sunset, ocean, aurora…), linear/radial, animated
+- **65+ CSS animations** — `spin`, `pulse`, `bounce`, `heartbeat`, `glitch`, `neon`, `explode`, and many more
+- **Tree-shakeable** — import only what you need; unused icons are eliminated at build time
+- **NiceIconPicker** — searchable, categorized dropdown component for icon selection
+- **createIcon()** factory — build your own icons following the same API
+- **Zero runtime dependencies** — only `react` and `react-dom` as peer deps
+- **Full TypeScript** — strict types, IntelliSense, TSDoc on every export
+- **Accessible** — `role`, `aria-hidden`, `aria-label`, `<title>` support
+- **CSS variable theming** — customize the picker with CSS custom properties
+
+---
+
+## Installation
+
+```bash
+npm install @nice2dev/icons
+```
+
+Peer dependencies: `react >= 17.0.0`, `react-dom >= 17.0.0`.
+
+---
+
+## Quick Start
+
+```tsx
+import { NtdHome, NtdSearch, NtdHeart } from '@nice2dev/icons';
+
+function App() {
+  return (
+    <>
+      {/* Solid blue home icon, large */}
+      <NtdHome size="lg" primaryColor="#3b82f6" />
+
+      {/* Animated search icon */}
+      <NtdSearch size="md" animation="pulse" />
+
+      {/* Duotone heart with custom colors */}
+      <NtdHeart
+        variant="duotone"
+        primaryColor="#e74c3c"
+        secondaryColor="#fca5a5"
+        animation="heartbeat"
+      />
+    </>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### Icon Component Props (`NtdIconProps`)
+
+Every icon component accepts these props (extends `SVGProps<SVGSVGElement>`):
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `IconSize` | `'md'` | Named preset or pixel number |
+| `variant` | `IconVariant` | `'solid'` | Rendering variant |
+| `primaryColor` | `string` | `'currentColor'` | Main icon color |
+| `secondaryColor` | `string` | `primaryColor` | Secondary color (duotone background) |
+| `accentColor` | `string` | `'#ffffff'` | Accent color for detail elements |
+| `primaryOpacity` | `number` | `1` | Opacity of primary elements (0–1) |
+| `secondaryOpacity` | `number` | `0.4` | Opacity of secondary elements (0–1) |
+| `accentOpacity` | `number` | `1` | Opacity of accent elements (0–1) |
+| `strokeWidth` | `number` | `2` | Base stroke width for outline/duotone |
+| `strokeLinecap` | `'round' \| 'square' \| 'butt'` | `'round'` | Stroke line cap style |
+| `strokeLinejoin` | `'round' \| 'miter' \| 'bevel'` | `'round'` | Stroke line join style |
+| `animation` | `IconAnimation` | `undefined` | CSS animation name |
+| `animationDuration` | `string` | CSS default | Duration override (e.g. `'0.5s'`) |
+| `gradient` | `GradientPreset` | `undefined` | Apply a gradient fill preset |
+| `gradientType` | `'linear' \| 'radial'` | `'linear'` | Gradient shape |
+| `gradientAngle` | `number` | `135` | Angle for linear gradients (degrees) |
+| `gradientAnimation` | `'shift' \| 'spin' \| 'pulse'` | `undefined` | Animate the gradient |
+| `title` | `string` | `undefined` | Accessible title for screen readers |
+| `className` | `string` | `undefined` | Custom CSS class |
+| `style` | `CSSProperties` | `undefined` | Inline styles |
+| `ref` | `Ref<SVGSVGElement>` | — | Forward ref to the `<svg>` element |
+
+Plus all standard `SVGProps<SVGSVGElement>` attributes (`onClick`, `id`, `data-*`, etc.).
+
+---
+
+### Size Presets (`IconSize`)
+
+```ts
+type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'xxl' | 'xxxl' | number;
+```
+
+| Preset | Pixels |
+|--------|--------|
+| `xs`   | 12     |
+| `sm`   | 16     |
+| `md`   | 24     |
+| `lg`   | 32     |
+| `xl`   | 48     |
+| `2xl`  | 64     |
+| `xxl`  | 96     |
+| `xxxl` | 128    |
+
+Pass a `number` for a custom pixel size: `<NtdStar size={20} />`.
+
+The pixel map is exported as `SIZE_MAP: Record<string, number>`.
+
+---
+
+### Variants (`IconVariant`)
+
+```ts
+type IconVariant = 'solid' | 'outline' | 'duotone' | 'flat';
+```
+
+| Variant | Description |
+|---------|-------------|
+| `solid` | Filled shapes using `fill` |
+| `outline` | Stroked paths with `fill="none"` |
+| `duotone` | Background shape at `secondaryOpacity` + foreground stroke |
+| `flat` | Colored badge background (`secondaryColor`, rounded rect) with solid content on top |
+
+```tsx
+<NtdHome variant="outline" primaryColor="#000" strokeWidth={1.5} />
+```
+
+---
+
+### Colors & Opacity
+
+```tsx
+<NtdHeart
+  variant="duotone"
+  primaryColor="#e74c3c"      // foreground stroke
+  secondaryColor="#fca5a5"    // background fill
+  secondaryOpacity={0.3}      // background opacity
+  accentColor="#fff"           // small details
+/>
+```
+
+- If `secondaryColor` is omitted, it defaults to `primaryColor`.
+- If `accentColor` is omitted, it defaults to `'#ffffff'`.
+
+---
+
+### Animations (`IconAnimation`)
+
+Apply an animation by name:
+
+```tsx
+<NtdBell animation="shake" />
+<NtdBell animation="shake" animationDuration="0.3s" />
+```
+
+Each animation maps to a CSS class `.ntd-anim-{name}` defined in `animations.css` (auto-imported).
+
+See [Full Animation Catalog](#full-animation-catalog) for the complete list.
+
+---
+
+### Gradient Fills
+
+Apply gradient fills using the `gradient` prop with one of 12 built-in presets:
+
+```tsx
+<NtdHeart gradient="sunset" />
+<NtdStar gradient="ocean" gradientType="radial" />
+<NtdZap gradient="neon" gradientAnimation="spin" />
+<NtdGlobe gradient="aurora" gradientAngle={45} />
+```
+
+#### Available Presets (`GradientPreset`)
+
+| Preset | Colors |
+|--------|--------|
+| `sunset` | `#ff6b6b` → `#feca57` → `#ff9ff3` |
+| `ocean` | `#0652DD` → `#1B9CFC` → `#38ada9` |
+| `forest` | `#0a3d0a` → `#1e8449` → `#58D68D` |
+| `fire` | `#e74c3c` → `#f39c12` → `#f1c40f` |
+| `ice` | `#74b9ff` → `#a29bfe` → `#dfe6e9` |
+| `neon` | `#6c5ce7` → `#fd79a8` → `#00cec9` |
+| `gold` | `#f9ca24` → `#f0932b` → `#e17055` |
+| `purple-haze` | `#6c5ce7` → `#a55eea` → `#e056a0` |
+| `aurora` | `#00b894` → `#00cec9` → `#0984e3` → `#6c5ce7` |
+| `midnight` | `#0c0c1d` → `#1e3a5f` → `#2c3e50` |
+| `candy` | `#ff6b81` → `#ffa502` → `#2ed573` |
+| `steel` | `#636e72` → `#b2bec3` → `#dfe6e9` |
+
+Color stops are exported as `GRADIENT_PRESETS: Record<GradientPreset, readonly string[]>`.
+
+#### Gradient Animations (`GradientAnimation`)
+
+| Animation | Effect |
+|-----------|--------|
+| `shift` | Slides gradient colors horizontally |
+| `spin` | Rotates the gradient around the icon center |
+| `pulse` | Pulsates between stop colors |
+
+Animations use SVG SMIL (`<animate>` / `<animateTransform>`) — no JavaScript runtime, works in all modern browsers.
+
+---
+
+### Accessibility
+
+- When `title` is provided → `role="img"`, `aria-label={title}`, `<title>` element inside SVG
+- When `title` is omitted → `aria-hidden="true"`, `role="presentation"` (decorative)
+
+```tsx
+<NtdSearch title="Search" />        {/* accessible */}
+<NtdStar />                         {/* decorative, hidden from AT */}
+```
+
+---
+
+## NiceIconPicker
+
+A fully-featured, searchable, categorized icon picker dropdown.
+
+```tsx
+import { NiceIconPicker, type IconPickerEntry } from '@nice2dev/icons';
+import { NtdHome, NtdSearch, NtdHeart } from '@nice2dev/icons';
+
+const icons: IconPickerEntry[] = [
+  { name: 'NtdHome',   Component: NtdHome,   category: 'UI' },
+  { name: 'NtdSearch', Component: NtdSearch,  category: 'Actions' },
+  { name: 'NtdHeart',  Component: NtdHeart,   category: 'UI' },
+];
+
+function App() {
+  const [selected, setSelected] = useState<string | null>(null);
+
+  return (
+    <NiceIconPicker
+      icons={icons}
+      value={selected}
+      onChange={(name) => setSelected(name)}
+      variant="solid"
+      placeholder="Pick an icon…"
+      clearable
+    />
+  );
+}
+```
+
+### IconPickerEntry
+
+```ts
+interface IconPickerEntry {
+  name: string;                              // unique identifier (e.g. 'NtdHome')
+  Component: ForwardRefExoticComponent<…>;   // the icon component
+  category: string;                          // grouping label
+}
+```
+
+### NiceIconPickerProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icons` | `IconPickerEntry[]` | **required** | Full icon registry |
+| `value` | `string \| null` | `null` | Currently selected icon name |
+| `onChange` | `(name: string \| null, entry: IconPickerEntry \| null) => void` | — | Selection callback |
+| `placeholder` | `string` | `'Select icon…'` | Placeholder text |
+| `variant` | `IconVariant` | `'solid'` | Variant for grid preview |
+| `gridIconSize` | `IconSize \| number` | `'md'` | Icon size in the grid |
+| `triggerIconSize` | `IconSize \| number` | `'sm'` | Icon size in trigger button |
+| `categories` | `string[]` | auto-detected | Ordered category tab names |
+| `className` | `string` | — | Additional CSS class |
+| `disabled` | `boolean` | `false` | Disable the picker |
+| `clearable` | `boolean` | `true` | Show "Clear selection" button |
+
+### NiceIconPickerHandle (imperative ref)
+
+```tsx
+const ref = useRef<NiceIconPickerHandle>(null);
+ref.current?.open();   // programmatically open
+ref.current?.close();  // programmatically close
+ref.current?.toggle(); // toggle open/closed
+```
+
+```ts
+interface NiceIconPickerHandle {
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+}
+```
+
+---
+
+## Creating Custom Icons (`createIcon`)
+
+Build icons following the same pattern as the built-in library:
+
+```tsx
+import { createIcon } from '@nice2dev/icons';
+
+export const NtdMyIcon = createIcon({
+  displayName: 'NtdMyIcon',
+  viewBox: '0 0 24 24',   // optional, defaults to '0 0 24 24'
+  paths: {
+    solid: ({ primaryColor }) => (
+      <path d="M12 2l10 20H2z" fill={primaryColor} />
+    ),
+    outline: ({ primaryColor, strokeWidth }) => (
+      <path d="M12 2l10 20H2z" stroke={primaryColor} strokeWidth={strokeWidth} fill="none" />
+    ),
+    duotone: ({ primaryColor, secondaryColor, secondaryOpacity, strokeWidth }) => (
+      <>
+        <path d="M12 2l10 20H2z" fill={secondaryColor} opacity={secondaryOpacity} />
+        <path d="M12 2l10 20H2z" stroke={primaryColor} strokeWidth={strokeWidth} fill="none" />
+      </>
+    ),
+    flat: ({ primaryColor, secondaryColor }) => (
+      <>
+        <rect x="2" y="2" width="20" height="20" rx="4" fill={secondaryColor} />
+        <path d="M12 2l10 20H2z" fill={primaryColor} />
+      </>
+    ),
+  },
+});
+
+// Usage — exactly like any built-in icon:
+<NtdMyIcon size="lg" variant="duotone" primaryColor="#8b5cf6" animation="pulse" />
+```
+
+### CreateIconOptions
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `displayName` | `string` | **required** | React display name |
+| `viewBox` | `string` | `'0 0 24 24'` | SVG viewBox |
+| `paths.solid` | `IconPathRenderer` | **required** | Solid variant renderer |
+| `paths.outline` | `IconPathRenderer` | **required** | Outline variant renderer |
+| `paths.duotone` | `IconPathRenderer` | **required** | Duotone variant renderer |
+| `paths.flat` | `IconPathRenderer` | **required** | Flat (badge) variant renderer |
+
+### IconPathRenderer
+
+```ts
+type IconPathRenderer = (props: IconRenderProps) => React.ReactNode;
+```
+
+### IconRenderProps
+
+Properties passed to every path renderer (pre-resolved from user props):
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `variant` | `IconVariant` | Active variant |
+| `primaryColor` | `string` | Resolved primary color |
+| `secondaryColor` | `string` | Resolved secondary color |
+| `accentColor` | `string` | Resolved accent color |
+| `primaryOpacity` | `number` | Primary opacity |
+| `secondaryOpacity` | `number` | Secondary opacity |
+| `accentOpacity` | `number` | Accent opacity |
+| `strokeWidth` | `number` | Stroke width |
+| `strokeLinecap` | `'round' \| 'square' \| 'butt'` | Stroke line cap |
+| `strokeLinejoin` | `'round' \| 'miter' \| 'bevel'` | Stroke line join |
+
+---
+
+## Full Icon Catalog
+
+### Navigation (14 icons)
+`NtdArrowUp` · `NtdArrowDown` · `NtdArrowLeft` · `NtdArrowRight` · `NtdChevronUp` · `NtdChevronDown` · `NtdChevronLeft` · `NtdChevronRight` · `NtdMenu` · `NtdClose` · `NtdMoreHorizontal` · `NtdMoreVertical` · `NtdExternalLink` · `NtdRefresh`
+
+### Actions (25 icons)
+`NtdSearch` · `NtdEdit` · `NtdTrash` · `NtdSave` · `NtdDownload` · `NtdUpload` · `NtdShare` · `NtdCopy` · `NtdClipboard` · `NtdPlus` · `NtdMinus` · `NtdCheck` · `NtdFilter` · `NtdSort` · `NtdPrint` · `NtdZoomIn` · `NtdZoomOut` · `NtdUndo` · `NtdRedo` · `NtdLink` · `NtdSettings` · `NtdLogIn` · `NtdLogOut` · `NtdLock` · `NtdUnlock`
+
+### UI & Status (26 icons)
+`NtdHome` · `NtdUser` · `NtdUsers` · `NtdHeart` · `NtdStar` · `NtdBell` · `NtdEye` · `NtdEyeOff` · `NtdInfo` · `NtdWarning` · `NtdError` · `NtdSuccess` · `NtdHelp` · `NtdClock` · `NtdCalendar` · `NtdTag` · `NtdBookmark` · `NtdFlag` · `NtdThumbUp` · `NtdThumbDown` · `NtdShield` · `NtdGlobe` · `NtdMap` · `NtdPin` · `NtdSun` · `NtdMoon`
+
+### Media & Communication (19 icons)
+`NtdPlay` · `NtdPause` · `NtdStop` · `NtdSkipForward` · `NtdSkipBack` · `NtdVolume` · `NtdVolumeMute` · `NtdImage` · `NtdCamera` · `NtdVideo` · `NtdMicrophone` · `NtdMusic` · `NtdMail` · `NtdPhone` · `NtdChat` · `NtdSend` · `NtdNotification` · `NtdWifi` · `NtdBluetooth`
+
+### Files & Misc (31 icons)
+`NtdFile` · `NtdFileText` · `NtdFolder` · `NtdFolderOpen` · `NtdArchive` · `NtdDatabase` · `NtdCloud` · `NtdCloudUpload` · `NtdCloudDownload` · `NtdTerminal` · `NtdCode` · `NtdGit` · `NtdPackage` · `NtdLayers` · `NtdGrid` · `NtdList` · `NtdTable` · `NtdSmartphone` · `NtdMonitor` · `NtdCpu` · `NtdZap` · `NtdKey` · `NtdAward` · `NtdCoffee` · `NtdCart` · `NtdCreditCard` · `NtdPieChart` · `NtdBarChart` · `NtdActivity` · `NtdTarget` · `NtdTruck`
+
+### Fun & Emoji (13 icons)
+`NtdDumpsterFire` · `NtdRocket` · `NtdGamepad` · `NtdPuzzle` · `NtdPartyPopper` · `NtdTrophy` · `NtdCrown` · `NtdDice` · `NtdSmiley` · `NtdSad` · `NtdSkull` · `NtdGhost` · `NtdLightning`
+
+### Weather & Nature (20 icons)
+`NtdSunrise` · `NtdSunset` · `NtdRain` · `NtdSnow` · `NtdThunderstorm` · `NtdWind` · `NtdDroplet` · `NtdThermometer` · `NtdUmbrella` · `NtdLeaf` · `NtdFlower` · `NtdTree` · `NtdMountain` · `NtdWave` · `NtdFire` · `NtdSnowflake` · `NtdCompass` · `NtdAnchor` · `NtdFeather` · `NtdBug`
+
+### Arrows & Shapes (22 icons)
+`NtdArrowUpCircle` · `NtdArrowDownCircle` · `NtdArrowLeftCircle` · `NtdArrowRightCircle` · `NtdSquare` · `NtdCircle` · `NtdTriangle` · `NtdHexagon` · `NtdOctagon` · `NtdDiamond` · `NtdPentagon` · `NtdCross` · `NtdStar4` · `NtdCornerUpLeft` · `NtdCornerUpRight` · `NtdCornerDownLeft` · `NtdCornerDownRight` · `NtdMaximize` · `NtdMinimize` · `NtdMove` · `NtdRepeat` · `NtdShuffle`
+
+### Business & Finance (16 icons)
+`NtdBriefcase` · `NtdDollar` · `NtdWallet` · `NtdReceipt` · `NtdBank` · `NtdTrendUp` · `NtdTrendDown` · `NtdPercent` · `NtdInvoice` · `NtdStore` · `NtdBarcode` · `NtdCalculator` · `NtdPresentation` · `NtdClipboardCheck` · `NtdPiggyBank` · `NtdCoins`
+
+### Social & Communication (8 icons)
+`NtdAtSign` · `NtdPhoneOff` · `NtdBubble` · `NtdThumbsUp` · `NtdThumbsDown` · `NtdBellRing` · `NtdMegaphone` · `NtdQrCode`
+
+### Dev & Tech (9 icons)
+`NtdBrackets` · `NtdServer` · `NtdGitBranch` · `NtdGitCommit` · `NtdGitMerge` · `NtdBattery` · `NtdSlash` · `NtdHash` · `NtdBugDev`
+
+### Food & Health (13 icons)
+`NtdApple` · `NtdPizza` · `NtdGlass` · `NtdHeartPulse` · `NtdPill` · `NtdSyringe` · `NtdStethoscope` · `NtdWeight` · `NtdBandaid` · `NtdCake` · `NtdEgg` · `NtdHamburger` · `NtdDna`
+
+### Brand & Logo (14 icons)
+`NtdNiceToDev` · `NtdNiceMonogram` · `NtdNiceOrbit` · `NtdNiceSpark` · `NtdNiceShield` · `NtdNiceBadge` · `NtdNiceCore` · `NtdNiceCrest` · `NtdNiceHelix` · `NtdNicePortal` · `NtdNicePulseMark` · `NtdNiceFlagship` · `NtdOmniVerk` · `NtdOmniVerkLogo`
+
+### Brand Studio (25 icons)
+`NtdStudioGrid` · `NtdStudioBlueprint` · `NtdStudioCursor` · `NtdStudioPrototype` · `NtdStudioComponent` · `NtdStudioToken` · `NtdStudioPalette` · `NtdStudioBrush` · `NtdStudioPenTool` · `NtdStudioLayerStack` · `NtdStudioSpline` · `NtdStudioNodes` · `NtdStudioFlow` · `NtdStudioRelease` · `NtdStudioRocketMark` · `NtdStudioAIBrain` · `NtdStudioNeural` · `NtdStudioChipmark` · `NtdStudioTerminalMark` · `NtdStudioForge` · `NtdStudioWireframe` · `NtdStudioPersona` · `NtdStudioBenchmark` · `NtdStudioStudio` · `NtdStudioBeacon`
+
+### Brand Lockups (4 icons)
+`NtdNiceLockupHorizontal` · `NtdNiceLockupStacked` · `NtdNiceWordmark` · `NtdNiceSymbolWordmark`
+
+### Brand Enterprise (18 icons)
+`NtdEnterpriseRoadmap` · `NtdEnterpriseBacklog` · `NtdEnterpriseKanban` · `NtdEnterpriseSprint` · `NtdEnterpriseMilestone` · `NtdEnterprisePipeline` · `NtdEnterpriseDeploy` · `NtdEnterpriseMonitor` · `NtdEnterpriseAlert` · `NtdEnterpriseSla` · `NtdEnterpriseKpi` · `NtdEnterpriseRevenue` · `NtdEnterpriseRisk` · `NtdEnterpriseCompliance` · `NtdEnterpriseGateway` · `NtdEnterpriseDataMesh` · `NtdEnterpriseFeatureFlag` · `NtdEnterpriseWorkspace`
+
+---
+
+## Full Animation Catalog
+
+### Core Transforms (13)
+`spin` · `spin-reverse` · `pulse` · `bounce` · `shake` · `float` · `flip` · `glow` · `wiggle` · `rubber` · `swing` · `tada` · `heartbeat`
+
+### Entrance Animations (22)
+`fade-in` · `slide-up` · `slide-down` · `slide-left` · `slide-right` · `drop` · `rise` · `roll-in` · `materialize` · `vortex` · `meteor` · `scale-in` · `signature` · `draw-sequence` · `stroke-order` · `glow-trace` · `seal-stamp` · `reveal` · `typewriter` · `unfold` · `assemble` · `draw` · `draw-from-dot`
+
+### Exit Animations (3)
+`scale-out` · `fold` · `dissolve`
+
+### Organic / Natural (10)
+`breathe` · `drift` · `orbit` · `sway` · `tilt` · `rock` · `pendulum` · `levitate` · `flap` · `skate`
+
+### Energetic / Impact (10)
+`jello` · `pop` · `squeeze` · `crush` · `stretch` · `stomp` · `snap` · `twist` · `dash` · `surge`
+
+### Effects / Digital (8)
+`flash` · `blink` · `flicker` · `vibrate` · `tremble` · `glitch` · `neon` · `earthquake`
+
+### Complex Transforms (7)
+`wobble` · `spiral` · `warp` · `morph` · `zoom-pulse` · `ripple` · `radar`
+
+### Dramatic (6)
+`ping` · `implode` · `explode` · `scatter` · `rotate-x` · `draw-loop`
+
+---
+
+## CSS Theming Variables
+
+### Icon Picker
+
+Override these CSS custom properties on a parent element to theme the picker:
+
+```css
+.my-theme {
+  --ntd-picker-bg: #1a1a2e;
+  --ntd-picker-border: #333;
+  --ntd-picker-text: #e0e0e0;
+  --ntd-picker-accent: #6366f1;
+  --ntd-picker-hover: rgba(99, 102, 241, 0.15);
+  --ntd-picker-radius: 8px;
+}
+```
+
+### Animation Classes
+
+All animation classes follow the pattern `.ntd-anim-{name}`. You can override timing in CSS:
+
+```css
+.ntd-anim-spin {
+  animation-duration: 0.5s !important;
+}
+```
+
+Or use the `animationDuration` prop inline:
+
+```tsx
+<NtdBell animation="spin" animationDuration="0.5s" />
+```
+
+---
+
+## Tree Shaking
+
+The library uses `sideEffects: ["*.css"]` in `package.json` and `preserveModules` in Rollup, so bundlers like webpack and vite can eliminate unused icons at build time.
+
+```tsx
+// Only NtdHome and NtdSearch (+ CSS) end up in your bundle
+import { NtdHome, NtdSearch } from '@nice2dev/icons';
+```
+
+---
+
+## Storybook
+
+Run the interactive component explorer:
+
+```bash
+npm run storybook        # dev server on http://localhost:6006
+npm run build-storybook  # static build to storybook-static/
+```
+
+Stories cover:
+- **Components/Icon** — all props, variants, sizes, colors, animations
+- **Components/NiceIconPicker** — controlled picker, disabled, outline variant
+- **Components/Animations** — full gallery of 65+ animations
+- **Guides/createIcon** — building custom icons with the factory
+
+---
+
+## Build & Development
+
+```bash
+npm install              # install dependencies
+npm run build            # tsc (types) + rollup (CJS + ESM)
+npm run dev              # rollup watch mode
+npm run demo             # vite dev server for the demo app
+npm run demo:build       # build the demo
+npm run lint             # eslint
+npm run storybook        # storybook dev
+npm run build-storybook  # build storybook
+```
+
+### Output Structure
+
+```
+dist/
+  cjs/          # CommonJS modules
+  esm/          # ES modules
+  types/        # TypeScript declarations (.d.ts)
+```
+
+Entry points in `package.json`:
+- `main` → `dist/cjs/index.js`
+- `module` → `dist/esm/index.js`
+- `types` → `dist/types/index.d.ts`
+
+---
+
+## License
+
+MIT © NiceToDev
+