@iconix/icons 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,833 @@
-# Temporary Holding Version
+# Iconix
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**1695 clean, consistent SVG icons for websites and apps, from everyday UI to industrial automation, electrical and electronics.**
+
+```bash
+npm install @iconix/icons
+```
+
+Iconix gives you icons as code. Each one is a crisp SVG that scales to any size, follows your text color and can be styled in one line. Use them in plain HTML, React, Vue, Next.js or any server, or export them as ordinary `.svg` files.
+
+- **1695 icons in 45 categories**, including rare ones like `ladder-logic`, `contactor`, `plc`, `vfd-drive`, `resistor` and `op-amp`.
+- **One consistent style**: 24×24 grid, 2px rounded lines. Icons always look good together.
+- **Easy to customize**: size, color, line thickness, circle and square badges, background, rotation, mirroring and animation.
+- **Small bundles**: you only ship the icons you use (~6 KB for the first icon).
+- **TypeScript built in**: your editor suggests every icon name, and a typo is caught before you run the code.
+- **No dependencies**. MIT licensed.
+
+---
+
+## Contents
+
+1. [Install](#install)
+2. [Your first icon (pick your setup)](#your-first-icon)
+3. [Customizing icons](#customizing-icons)
+4. [Recipes: copy-paste examples](#recipes)
+5. [Finding icons](#finding-icons)
+6. [API reference](#api-reference)
+7. [React reference](#react-reference)
+8. [Vue reference](#vue-reference)
+9. [Web Component reference](#web-component-reference)
+10. [CLI reference](#cli-reference)
+11. [TypeScript](#typescript)
+12. [Bundle size and performance](#bundle-size-and-performance)
+13. [Troubleshooting / FAQ](#troubleshooting--faq)
+14. [Categories](#categories)
+15. [Development](#development)
+
+---
+
+## Install
+
+```bash
+npm install @iconix/icons
+# or
+pnpm add @iconix/icons
+# or
+yarn add @iconix/icons
+```
+
+No build tools? You can also load it straight from a CDN (see [plain HTML](#plain-html-no-build-step)) or export plain `.svg` files with the [CLI](#cli-reference).
+
+**Requirements:** any modern browser, Node.js 18+, React 16.8+ (optional), Vue 3.2+ (optional).
+
+---
+
+## Your first icon
+
+Pick the setup that matches your project. Each one works on its own.
+
+### Plain HTML (no build step)
+
+Load the Web Component once, then write `<iconix-icon>` tags anywhere on the page:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <script type="module">
+      import { defineIconElement } from 'https://cdn.jsdelivr.net/npm/@iconix/icons/dist/element.js';
+      defineIconElement();
+    </script>
+  </head>
+  <body>
+    <iconix-icon name="home"></iconix-icon>
+    <iconix-icon name="cart" size="32" color="#2563eb"></iconix-icon>
+  </body>
+</html>
+```
+
+The same approach works in WordPress, PHP or Django templates, or any CMS that lets you add HTML.
+
+### JavaScript with a bundler (Vite, Webpack, Parcel)
+
+```js
+import { toSvg } from '@iconix/icons';
+
+const button = document.querySelector('#save');
+button.innerHTML = toSvg('save', { size: 18 }) + ' Save';
+```
+
+### React
+
+```jsx
+import { IconHome, IconSettings } from '@iconix/icons/react';
+
+export function Navbar() {
+  return (
+    <nav>
+      <a href="/"><IconHome /> Home</a>
+      <a href="/settings"><IconSettings /> Settings</a>
+    </nav>
+  );
+}
+```
+
+Every icon has a component named `Icon` + its name in PascalCase: `home` → `IconHome`, `ladder-logic` → `IconLadderLogic`, `3d-printer` → `Icon3dPrinter`.
+
+### Next.js (App Router)
+
+The icon components work in **Server Components** too, so no `"use client"` is needed just to show an icon:
+
+```tsx
+// app/page.tsx (a Server Component)
+import { IconFactory } from '@iconix/icons/react';
+
+export default function Page() {
+  return <h1><IconFactory size={28} /> Plant overview</h1>;
+}
+```
+
+Only `<IconProvider>` (shared defaults) uses React context, so put it in a file that starts with `"use client"`.
+
+### Vue 3
+
+```vue
+<script setup>
+import { IconHome, IconSettings } from '@iconix/icons/vue';
+</script>
+
+<template>
+  <nav>
+    <a href="/"><IconHome /> Home</a>
+    <a href="/settings"><IconSettings :size="20" /> Settings</a>
+  </nav>
+</template>
+```
+
+### Node.js / server-side rendering
+
+`toSvg()` returns a plain string, so it works in Express, Fastify, email templates or a static site generator:
+
+```js
+import express from 'express';
+import { toSvg, hasIcon } from '@iconix/icons';
+
+const app = express();
+
+// GET /icons/plc.svg?color=%232563eb&size=48
+app.get('/icons/:name.svg', (req, res) => {
+  if (!hasIcon(req.params.name)) return res.sendStatus(404);
+  res.type('image/svg+xml').send(
+    toSvg(req.params.name, { color: req.query.color || '#000', size: Number(req.query.size) || 24 }),
+  );
+});
+
+app.listen(3000);
+```
+
+### No JavaScript at all: plain SVG files
+
+The package includes every icon as a file in `svg/`, plus ready-made sprites. You can also generate files with your own colors and sizes:
+
+```bash
+npx @iconix/icons export home cart user --size 24 --color "#2563eb" -o public/icons
+```
+
+```html
+<img src="/icons/home.svg" width="24" height="24" alt="Home">
+```
+
+---
+
+## Customizing icons
+
+Every option works the same way everywhere. In JavaScript you pass an object, in React and Vue you use props, and in HTML you use attributes (written with dashes: `stroke-width`).
+
+```js
+toSvg('bell', {
+  size: 32,            // 32×32 px
+  color: '#dc2626',    // red lines
+  strokeWidth: 1.5,    // thinner lines
+  variant: 'circle',   // inside a circle
+  background: '#fee2e2', // light red circle fill
+  title: 'Notifications', // read aloud by screen readers
+});
+```
+
+```jsx
+<IconBell size={32} color="#dc2626" strokeWidth={1.5} variant="circle" background="#fee2e2" title="Notifications" />
+```
+
+```html
+<iconix-icon name="bell" size="32" color="#dc2626" stroke-width="1.5" variant="circle" background="#fee2e2" label="Notifications"></iconix-icon>
+```
+
+### All options
+
+| Option | What it does | Type | Default |
+|---|---|---|---|
+| `size` | Width and height. A number means pixels; strings like `"2em"` or `"100%"` work too | `number \| string` | `24` |
+| `width` / `height` | Set one dimension separately | `number \| string` | `size` |
+| `color` | Line color. By default it follows the surrounding text color | `string` (any CSS color) | `"currentColor"` |
+| `strokeWidth` | Line thickness, in units of the 24×24 grid | `number` | `2` |
+| `absoluteStrokeWidth` | Keep the line thickness in real pixels, so big icons don't get chunky | `boolean` | `false` |
+| `fill` | Fill shapes with a color | `string` | `"none"` |
+| `variant` | `"circle"` or `"square"` puts the icon inside a badge | `"default" \| "circle" \| "square"` | `"default"` |
+| `background` | Badge fill color (or a rounded tile behind a default icon) | `string` | `"none"` |
+| `rotate` | Rotate by degrees | `number` | `0` |
+| `flip` | Mirror: `"horizontal"`, `"vertical"` or `"both"` (`true` = horizontal) | `string \| boolean` | – |
+| `spin` | Rotate continuously, e.g. a loading indicator (needs the [CSS file](#animations)) | `boolean` | `false` |
+| `pulse` | Rotate in 8 steps, the classic loader look (needs the CSS file) | `boolean` | `false` |
+| `title` | Text for screen readers. Adds `role="img"`, `aria-label` and `<title>` | `string` | – |
+| `strokeLinecap` | Line ends: `"round"`, `"butt"`, `"square"` | `string` | `"round"` |
+| `strokeLinejoin` | Corners: `"round"`, `"miter"`, `"bevel"` | `string` | `"round"` |
+| `className` | Extra CSS classes (in React use `className`, in Vue use `class`) | `string` | – |
+| `style` | Inline styles, as a string or an object | `string \| object` | – |
+| `attrs` | Any extra `<svg>` attribute; `null` or `false` removes one | `object` | – |
+
+If you pass an invalid value, such as `size: -1` or `variant: "triangle"`, Iconix throws a clear error instead of drawing something broken.
+
+### Styling with CSS
+
+Each `<svg>` has the classes `iconix` and `iconix-<name>` (plus `iconix-circle` / `iconix-square` for badges). Because the default color is `currentColor`, the usual CSS `color` property controls it:
+
+```css
+.iconix {
+  vertical-align: -0.125em; /* line up nicely with text */
+}
+
+a:hover .iconix {
+  color: #2563eb;           /* icon turns blue on hover */
+}
+
+.iconix-trash {
+  color: #dc2626;           /* every trash icon is red */
+}
+```
+
+### Animations
+
+`spin` and `pulse` use a small optional stylesheet. Import it once:
+
+```js
+import '@iconix/icons/css';
+```
+
+or link it in HTML: `<link rel="stylesheet" href="node_modules/@iconix/icons/iconix.css">`.
+
+Animations turn off automatically for visitors who enable "reduce motion" in their system settings.
+
+---
+
+## Recipes
+
+Short, practical examples for common tasks. Copy them and adjust.
+
+### 1. A button with an icon and text
+
+```jsx
+import { IconDownload } from '@iconix/icons/react';
+
+<button className="btn">
+  <IconDownload size={18} /> Download report
+</button>
+```
+
+```css
+.btn { display: inline-flex; align-items: center; gap: .5rem; }
+```
+
+`inline-flex` with `gap` keeps the icon and text vertically centered and evenly spaced.
+
+### 2. An icon-only button that screen readers understand
+
+When there is no visible text, give the icon a `title`:
+
+```jsx
+import { IconTrash } from '@iconix/icons/react';
+
+<button onClick={deleteRow} aria-label="Delete row">
+  <IconTrash size={18} />
+</button>
+```
+
+Putting `aria-label` on the **button** is the best practice. Alternatively, `<IconTrash title="Delete row" />` labels the icon itself. Icons without a title are automatically hidden from screen readers (`aria-hidden="true"`), so decorative icons never add noise.
+
+### 3. Status badges (success / warning / error)
+
+```jsx
+import { IconCheck, IconAlertTriangle, IconClose } from '@iconix/icons/react';
+
+const badge = { size: 28, variant: 'circle' };
+
+<IconCheck {...badge} color="#15803d" background="#dcfce7" title="Running" />
+<IconAlertTriangle {...badge} color="#b45309" background="#fef3c7" title="Warning" />
+<IconClose {...badge} color="#b91c1c" background="#fee2e2" title="Fault" />
+```
+
+This works well for dashboards, for example PLC or pump status on a SCADA-style page.
+
+### 4. A loading spinner
+
+```jsx
+import '@iconix/icons/css';
+import { IconLoader } from '@iconix/icons/react';
+
+{isLoading && <IconLoader spin title="Loading" />}
+```
+
+### 5. An accordion arrow that rotates when opened
+
+```jsx
+import { IconChevronDown } from '@iconix/icons/react';
+
+<button onClick={() => setOpen(!open)}>
+  Details
+  <IconChevronDown
+    style={{ transition: 'transform .2s', transform: open ? 'rotate(180deg)' : 'none' }}
+  />
+</button>
+```
+
+For a smooth animation, rotate with CSS `transform`. For a fixed rotation (an arrow that always points left, for example), use the `rotate` option.
+
+### 6. A menu built from data
+
+```tsx
+import { Icon } from '@iconix/icons/react';
+import type { IconName } from '@iconix/icons';
+
+const menu: { label: string; icon: IconName; href: string }[] = [
+  { label: 'Dashboard', icon: 'dashboard', href: '/' },
+  { label: 'PLC tags', icon: 'plc', href: '/tags' },
+  { label: 'Alarms', icon: 'bell-ring', href: '/alarms' },
+  { label: 'Reports', icon: 'file-chart', href: '/reports' },
+];
+
+export function Sidebar() {
+  return (
+    <ul>
+      {menu.map((item) => (
+        <li key={item.href}>
+          <a href={item.href}><Icon name={item.icon} size={20} /> {item.label}</a>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Typing `icon` as `IconName` means a misspelled icon name is a compile error. Note that `<Icon name>` includes all icons in your bundle; see [bundle size](#bundle-size-and-performance) if that matters.
+
+### 7. Same look across the whole app (defaults)
+
+Set sizes and line thickness in one place instead of on every icon:
+
+```jsx
+// React ("use client" in Next.js)
+import { IconProvider } from '@iconix/icons/react';
+
+<IconProvider size={20} strokeWidth={1.5}>
+  <App />
+</IconProvider>
+```
+
+```js
+// Vue
+import { createApp } from 'vue';
+import { IconixPlugin } from '@iconix/icons/vue';
+import App from './App.vue';
+
+createApp(App).use(IconixPlugin, { size: 20, strokeWidth: 1.5 }).mount('#app');
+```
+
+```js
+// Plain JS / Web Component
+import { setDefaults } from '@iconix/icons';
+setDefaults({ size: 20, strokeWidth: 1.5 });
+```
+
+An option set directly on an icon always wins over the defaults.
+
+### 8. Crisp lines at every size
+
+A 64px icon with `strokeWidth: 2` has lines that are visually 5px thick. Use `absoluteStrokeWidth` to keep them at a fixed pixel width:
+
+```jsx
+<IconCog size={16} strokeWidth={1.5} absoluteStrokeWidth />
+<IconCog size={64} strokeWidth={1.5} absoluteStrokeWidth />  {/* both have 1.5px lines */}
+```
+
+### 9. Dark mode
+
+Because icons follow `color`, dark mode needs no extra code:
+
+```css
+body { color: #1c1917; }
+@media (prefers-color-scheme: dark) {
+  body { color: #f5f5f4; }   /* all icons switch automatically */
+}
+```
+
+### 10. Turn existing HTML into icons
+
+Write simple placeholders in your markup and call `replace()` once:
+
+```html
+<i data-icon="phone" data-size="20"></i> +1 555 0100
+<i data-icon="mail" data-size="20" data-color="#2563eb"></i> hello@example.com
+<i data-icon="map-pin" class="footer-icon" aria-label="Address"></i> Main Street 1
+
+<script type="module">
+  import { replace } from 'https://cdn.jsdelivr.net/npm/@iconix/icons/dist/index.js';
+  replace(); // swaps every [data-icon] element for an <svg>
+</script>
+```
+
+`class`, `id`, `style`, `aria-*` and other `data-*` attributes are carried over to the `<svg>`.
+
+### 11. Icons in CSS (backgrounds, list bullets)
+
+```js
+import { toDataUri } from '@iconix/icons';
+
+document.documentElement.style.setProperty(
+  '--check-icon',
+  `url("${toDataUri('check', { color: '#16a34a', size: 16 })}")`,
+);
+```
+
+```css
+ul.features li {
+  list-style: none;
+  padding-left: 1.5rem;
+  background: var(--check-icon) no-repeat left center;
+}
+```
+
+Inside CSS backgrounds and `<img>`, SVGs can't inherit `currentColor`, so pass an explicit `color`. Iconix falls back to black if you don't.
+
+### 12. A favicon from any icon
+
+```js
+import { toDataUri } from '@iconix/icons';
+
+const link = document.querySelector('link[rel="icon"]') ?? document.head.appendChild(
+  Object.assign(document.createElement('link'), { rel: 'icon' }),
+);
+link.href = toDataUri('zap', { color: '#f59e0b', size: 32, strokeWidth: 2.5 });
+```
+
+### 13. One sprite file for a static website
+
+A sprite stores many icons in one file, and each page references them by id:
+
+```bash
+npx @iconix/icons sprite home phone mail map-pin --stroke-width 1.5 -o public/icons.svg
+```
+
+```html
+<svg class="icon" width="24" height="24"><use href="/icons.svg#i-home"/></svg>
+<svg class="icon" width="24" height="24"><use href="/icons.svg#i-phone"/></svg>
+```
+
+```css
+.icon { color: #2563eb; }  /* color comes from CSS */
+```
+
+The package also ships complete sprites: `sprites/iconix.svg`, `sprites/iconix-circle.svg` and `sprites/iconix-square.svg`.
+
+### 14. Mirrored arrows for right-to-left languages
+
+```jsx
+<IconArrowRight flip={isRtl} />
+```
+
+### 15. Your own custom icon in the same style
+
+```jsx
+import { createIconComponent } from '@iconix/icons/react';   // or '@iconix/icons/vue'
+
+export const IconCompanyLogo = createIconComponent({
+  name: 'company-logo',
+  nodes: [
+    ['circle', { cx: 12, cy: 12, r: 9 }],
+    ['path', { d: 'M8 12h8M12 8v8' }],
+  ],
+});
+
+<IconCompanyLogo size={40} color="#7c3aed" variant="square" />
+```
+
+Draw your icon on a 24×24 grid with 2px strokes, and it gets every Iconix option for free.
+
+---
+
+## Finding icons
+
+The quickest way is the command line:
+
+```bash
+npx @iconix/icons search valve          # by name
+npx @iconix/icons list --category automation
+npx @iconix/icons categories            # all 45 categories with counts
+```
+
+Or in code:
+
+```js
+import { searchIcons, getIconsByCategory, iconNames } from '@iconix/icons';
+
+searchIcons('folder').map((i) => i.name);   // ['folder', 'folder-check', 'folder-clock', ...]
+getIconsByCategory('electrical').length;     // 32
+iconNames.length;                            // 1695
+```
+
+In TypeScript editors (VS Code, WebStorm), start typing an icon name inside `toSvg('` or `<Icon name="` and you get the full list as autocomplete.
+
+---
+
+## API reference
+
+Import from `@iconix/icons`. Functions marked "name or icon" accept either a string name (`'home'`) or an icon object (`iconHome`).
+
+### Rendering
+
+| Function | Returns | Description |
+|---|---|---|
+| `toSvg(nameOrIcon, options?)` | `string` | SVG markup |
+| `createElement(nameOrIcon, options?, document?)` | `SVGSVGElement` | A DOM element, ready to `append()` |
+| `replace({ root?, attribute?, ...options })` | `number` | Replaces `[data-icon]` placeholders (or your own `attribute`) inside `root` (default: `document`); returns how many were replaced |
+| `toDataUri(nameOrIcon, options?)` | `string` | `data:image/svg+xml,...` for `<img>` and CSS |
+| `toSprite(names?, { idPrefix?, ...options })` | `string` | A hidden `<svg>` with `<symbol id="i-…">` entries; no list = all icons |
+
+### Looking up icons
+
+| Function / value | Description |
+|---|---|
+| `getIcon(name)` | The icon object, or `undefined` |
+| `hasIcon(name)` | `true` if the icon exists (also a TypeScript type guard) |
+| `searchIcons(query, { category?, limit? })` | Best matches first: exact name, then prefix, word and substring matches |
+| `getIconsByCategory(category)` | All icons in a category |
+| `suggestIcons(name, limit?)` | Closest names, useful for "did you mean…" |
+| `iconNames` | All 1695 names, sorted |
+| `categories` | All 45 category names |
+| `icons` | `{ [name]: iconObject }` registry |
+| `iconHome`, `iconPlc`, … | Each icon as its own export (`icon` + PascalCase name) |
+
+### Defaults and advanced
+
+| Function | Description |
+|---|---|
+| `setDefaults(options)` | Change defaults for `toSvg`, `createElement`, `replace` and `<iconix-icon>` |
+| `getDefaults()` / `resetDefaults()` | Read or reset them |
+| `resolveOptions(options)` | Validate and merge options (throws `TypeError` on invalid values) |
+| `buildIconTree(icon, options)` | The SVG as a plain object tree, useful for writing your own renderer |
+| `treeToString(tree)` / `treeToElement(tree)` | Render a tree to a string or a DOM element |
+| `isIcon(value)` | Checks if a value is an icon object |
+
+Unknown names throw a helpful error, for example `[iconix] unknown icon "hom". Did you mean: home, atm, atom?`
+
+### `@iconix/icons/lite`
+
+The same rendering functions (`toSvg`, `createElement`, `toDataUri`, `toSprite`, `replaceElements`) plus all `iconXxx` objects, **without** name lookup. Use it when bundle size matters:
+
+```js
+import { toSvg, iconHome, iconPlc } from '@iconix/icons/lite';
+toSvg(iconHome, { size: 20 });
+```
+
+---
+
+## React reference
+
+```jsx
+import { IconHome, Icon, IconProvider, useIconDefaults, createIconComponent } from '@iconix/icons/react';
+```
+
+- **`<IconXxx {...options} />`**: one component per icon. It accepts all [options](#all-options) as props, plus every normal `<svg>` prop (`onClick`, `id`, `aria-*`, `data-*`, `tabIndex`, …). `ref` gives you the `<svg>` element. `style` accepts an object or a string.
+- **`<Icon name="plc" />`**: picks the icon by name at runtime (bundles all icons). `name` also accepts an icon object.
+- **`<IconProvider {...options}>`**: defaults for every icon inside. Nested providers merge, and props on an icon win. In Next.js, use it in a `"use client"` file.
+- **`useIconDefaults()`**: reads the current defaults.
+- **`createIconComponent(icon)`**: turns your own icon object into a component.
+- Each component exposes `.icon` (its data) and a `displayName` like `IconHome` for React DevTools.
+
+Types: `IconProps`, `IconixIcon`, `NamedIconProps`, `IconProviderProps`.
+
+---
+
+## Vue reference
+
+```js
+import { IconHome, Icon, IconixPlugin, provideIconDefaults, createIconComponent } from '@iconix/icons/vue';
+```
+
+- **`<IconXxx />`**: one component per icon, with all options as props (`:size="20"`, `stroke-width="1.5"`, `variant="circle"`, …). `class`, `style` and listeners such as `@click` are passed to the `<svg>`.
+- **`<Icon name="plc" />`**: icon by name (bundles all icons).
+- **`app.use(IconixPlugin, defaults)`**: app-wide defaults.
+- **`provideIconDefaults(defaults)`**: defaults for one component subtree, called inside `setup()`.
+- **`createIconComponent(icon)`**: a component for your own icon.
+
+Boolean props work as attributes: `<IconLoader spin />`, `<IconArrowRight flip />`.
+
+---
+
+## Web Component reference
+
+```js
+import { defineIconElement } from '@iconix/icons/element';
+defineIconElement();                      // registers <iconix-icon>
+defineIconElement('my-icon');             // or use your own tag name
+defineIconElement('app-icon', { registry: { home: iconHome } }); // only specific icons
+```
+
+```html
+<iconix-icon name="valve" size="32" color="teal" stroke-width="1.5"
+             variant="square" background="#ccfbf1" rotate="90" flip="horizontal"
+             absolute-stroke-width spin label="Main valve"></iconix-icon>
+```
+
+- Attributes: `name`, `size`, `width`, `height`, `color`, `fill`, `stroke-width`, `absolute-stroke-width`, `stroke-linecap`, `stroke-linejoin`, `variant`, `background`, `rotate`, `flip`, `spin`, `pulse`, `label`.
+- `label` is the accessible title. We use `label` rather than `title` so the browser doesn't show a duplicate tooltip.
+- Changing any attribute (or `element.name = 'cart'`) re-renders immediately.
+- The element respects `setDefaults()`.
+
+---
+
+## CLI reference
+
+Run it without installing (`npx @iconix/icons <command>`), or after installing (`npx iconix <command>`).
+
+| Command | Description |
+|---|---|
+| `list [--category <cat>] [--json]` | List icon names |
+| `categories` | List categories with icon counts |
+| `search <query> [--category <cat>]` | Search icons |
+| `svg <name> [options]` | Print one SVG to the terminal |
+| `export <names...> [options] -o <dir>` | Write `.svg` files |
+| `sprite <names...> [options] -o <file>` | Write one sprite file |
+
+Select icons with names, `--category <cat>` (repeatable) or `--all`.
+
+| Option | Short | Description |
+|---|---|---|
+| `--size <n>` | `-s` | Size in px or CSS units |
+| `--width <n>`, `--height <n>` | | Separate dimensions |
+| `--color <color>` | | Line color |
+| `--fill <color>` | | Fill color |
+| `--stroke-width <n>` | `-w` | Line thickness |
+| `--absolute-stroke-width` | | Constant px line thickness |
+| `--linecap <butt\|round\|square>` | | Line ends |
+| `--linejoin <miter\|round\|bevel>` | | Line corners |
+| `--variant <default\|circle\|square>` | `-v` | Badge style |
+| `--background <color>` | `-b` | Badge background |
+| `--rotate <degrees>` | `-r` | Rotation |
+| `--flip <horizontal\|vertical\|both>` | | Mirroring |
+| `--title <text>` | | Accessible title |
+| `--prefix <text>` | | Sprite symbol id prefix (default `i-`) |
+| `--out <path>` | `-o` | Output directory (export) or file (sprite) |
+
+Examples:
+
+```bash
+# All electrical and electronics icons as blue circle badges
+npx @iconix/icons export --category electrical --category electronics -v circle --color "#1d4ed8" -b "#dbeafe" -o icons
+
+# Every icon at 48px with 1.5px lines
+npx @iconix/icons export --all --size 48 -w 1.5 --absolute-stroke-width -o icons-48
+
+# Print one icon to paste somewhere
+npx @iconix/icons svg emergency-stop --color red --size 32
+```
+
+---
+
+## TypeScript
+
+Iconix is written in TypeScript (`strict` mode) and ships its own types. You don't need `@types/...`.
+
+```ts
+import { toSvg, hasIcon, type IconName, type IconOptions, type IconLike } from '@iconix/icons';
+
+toSvg('ladder-logic');      // ✓ autocompleted
+toSvg('ladder-logik');      // ✗ compile error: not a valid IconName
+
+// Narrow an unknown string (e.g. from an API or a URL)
+function render(name: string) {
+  return hasIcon(name) ? toSvg(name) : '';
+}
+
+// Reusable option sets are type-checked too
+const badge: IconOptions = { size: 28, variant: 'circle', background: '#dbeafe' };
+
+// Custom icons
+const logo: IconLike = { name: 'logo', nodes: [['circle', { cx: 12, cy: 12, r: 6 }]] };
+toSvg(logo, badge);
+```
+
+Main types: `IconName` (union of all 1695 names), `IconCategory`, `IconData`, `IconLike`, `IconNode`, `IconOptions`, `IconVariant`, `IconFlip`, `IconixTree`; in React `IconProps` and `IconixIcon`; in Vue `IconVueProps` and `IconixVueIcon`. Hovering over any option in your editor shows its description.
+
+Works with every `moduleResolution` setting (`bundler`, `node16`/`nodenext`, `node10`), from both ESM and CommonJS.
+
+---
+
+## Bundle size and performance
+
+| What you import | Added to your bundle (minified) |
+|---|---|
+| `import { IconHome } from '@iconix/icons/react'` | ~6 KB (shared renderer + 1 icon) |
+| `import { toSvg, iconHome } from '@iconix/icons/lite'` | ~5.5 KB |
+| each additional icon | ~0.2–0.5 KB |
+| `toSvg('home')`, `<Icon name>`, `replace()`, `<iconix-icon>` (by name) | ~350 KB (all 1695 icons) |
+
+Rule of thumb: **import icons by component or object (`IconHome`, `iconHome`) and only the ones you use end up in your bundle.** Name-based APIs are convenient for CMS content, user-chosen icons or quick prototypes, but they include every icon.
+
+Rendering is fast: all 1695 icons in all three variants render as strings in well under a second.
+
+---
+
+## Troubleshooting / FAQ
+
+**My icon is black instead of my brand color.**
+Icons use `currentColor`, the text color of their parent. Set `color` on the parent in CSS, or pass the `color` option.
+
+**The icon is invisible in an `<img>` tag or CSS background.**
+`<img>` and CSS backgrounds don't inherit text color. Export the file with an explicit color (`--color` in the CLI, or `toDataUri(name, { color })`).
+
+**The icon is squashed inside a flex container.**
+`iconix.css` adds `flex-shrink: 0`. Without the stylesheet, add `.iconix { flex-shrink: 0; }` yourself.
+
+**The icon doesn't line up with the text.**
+Use `display: inline-flex; align-items: center` on the parent (see [recipe 1](#1-a-button-with-an-icon-and-text)), or `vertical-align: -0.125em` on `.iconix`.
+
+**`spin` does nothing.**
+Import the stylesheet: `import '@iconix/icons/css'`.
+
+**Next.js says IconProvider must be a client component.**
+Move `<IconProvider>` into a file that starts with `"use client"`. Individual icons work in Server Components without it.
+
+**My bundle got big.**
+You probably use a name-based API (`<Icon name>`, `toSvg('…')`). Switch to `IconXxx` components or `@iconix/icons/lite`.
+
+**`<use href="sprite.svg#i-home">` shows nothing.**
+The sprite must be served from the same origin as your page. External sprites don't work across domains in most browsers.
+
+---
+
+## Categories
+
+| Category | Icons | Examples |
+|---|---|---|
+| agriculture | 34 | `barn`, `wheat`, `greenhouse`, `fence`, `windmill` |
+| animals | 32 | `paw`, `cat`, `bear`, `bee`, `owl` |
+| arrows | 57 | `arrow-up`, `chevron-down`, `refresh`, `swap`, `expand` |
+| automation | 46 | `ladder-logic`, `contact-no`, `coil`, `contactor`, `hmi-panel` |
+| automotive | 42 | `car-front`, `engine`, `brake-disc`, `ev-charger`, `turbo` |
+| aviation | 13 | `plane-departure`, `control-tower`, `runway`, `boarding-pass`, `quadcopter` |
+| charts-data | 12 | `chart-gantt`, `chart-funnel`, `chart-radar`, `kpi`, `pivot-table` |
+| clothing | 36 | `tshirt`, `shoe`, `glasses`, `tie`, `jacket` |
+| communication | 51 | `mail`, `phone`, `message-square`, `send`, `wifi` |
+| construction | 37 | `bricks`, `blueprint`, `brick-wall`, `ladder`, `traffic-cone` |
+| development | 45 | `code`, `terminal`, `git-branch`, `api`, `braces` |
+| editor | 46 | `align-left`, `bold`, `code-block`, `heading-1`, `list-checks` |
+| education-security-design | 44 | `atom`, `brain`, `key`, `shield-lock`, `palette` |
+| electrical | 43 | `bulb-on`, `cable`, `circuit-breaker`, `fuse`, `socket`, `ground` |
+| electronics | 47 | `resistor`, `capacitor`, `diode`, `led`, `transistor`, `op-amp` |
+| energy | 34 | `battery-full`, `cooling-tower`, `energy-storage`, `wind-farm` |
+| files | 70 | `file`, `folder`, `file-code`, `folder-lock`, `archive` |
+| finance | 50 | `atm`, `bank`, `bar-chart`, `candlestick`, `invoice` |
+| gaming | 12 | `sword`, `treasure-chest`, `crosshair`, `level-up`, `arcade` |
+| health-sport-food | 60 | `heart-pulse`, `pill`, `hospital`, `dumbbell`, `coffee` |
+| hobby | 37 | `aquarium`, `chess-rook`, `dice`, `puzzle`, `rocket` |
+| holidays | 36 | `christmas-tree`, `candle`, `easter-egg`, `gift`, `confetti` |
+| household | 38 | `bathtub`, `ceiling-lamp`, `chair`, `door`, `sofa` |
+| industry | 52 | `factory`, `cog`, `plc`, `valve`, `pump`, `gauge` |
+| instrumentation | 12 | `pressure-gauge`, `caliper`, `data-logger`, `load-cell`, `clamp-meter` |
+| interface | 80 | `home`, `menu`, `search`, `settings`, `user`, `bell` |
+| kitchen | 13 | `frying-pan`, `knife`, `whisk`, `blender`, `teapot` |
+| legal-government | 34 | `paragraph`, `gavel`, `stamp`, `certificate`, `town-hall` |
+| logistics | 35 | `pallet`, `boxes`, `container-ship`, `delivery-done`, `fragile` |
+| marine | 12 | `submarine`, `propeller`, `buoy`, `sonar`, `ship-wheel` |
+| media | 49 | `play`, `camera`, `music`, `podcast`, `equalizer` |
+| networking | 14 | `network-switch`, `server-rack`, `firewall`, `vpn`, `access-point` |
+| office | 12 | `stapler`, `office-chair`, `binder`, `filing-cabinet`, `shredder` |
+| people | 37 | `team`, `id-badge`, `org-chart`, `family`, `face-id` |
+| plumbing-hvac | 37 | `air-conditioner`, `ball-valve`, `boiler`, `faucet`, `radiator` |
+| school | 34 | `chalkboard`, `school`, `abacus`, `diploma`, `timetable` |
+| science-space | 37 | `beaker`, `molecule`, `telescope`, `magnet`, `planet` |
+| shapes | 13 | `circle`, `hexagon`, `cube`, `cylinder`, `pyramid` |
+| shopping | 41 | `cart`, `basket`, `barcode`, `discount`, `gift-card` |
+| status | 40 | `loader`, `spinner`, `sync`, `ban`, `alert-octagon` |
+| technology | 51 | `cpu`, `server`, `database`, `usb`, `ai-chip` |
+| time | 38 | `alarm`, `calendar`, `calendar-check`, `clock`, `timer` |
+| travel-maps | 48 | `map-pin`, `plane`, `bike`, `hotel`, `compass` |
+| water-wastewater | 14 | `water-tower`, `fire-hydrant`, `manhole`, `pump-station`, `clarifier` |
+| weather-nature | 70 | `sun`, `cloud-rain`, `leaf`, `tree`, `mountain` |
+
+The full machine-readable list (name, category, component name, export name) is in `@iconix/icons/icons.json`.
+
+---
+
+## Development
+
+Requires Node.js 22.18+ (the `.ts` build scripts run directly). The published library runs on Node 18+.
+
+```
+src/             library source (TypeScript, strict)
+  core.ts        rendering engine shared by every integration
+  index.ts       name-based API          lite.ts    API without the name registry
+  react-core.ts  vue-core.ts  element.ts  cli.ts
+  generated/     generated from data/icons.json (icon data, names, components)
+test/            vitest tests (.ts/.tsx) + test/types (published type declarations)
+scripts/         build.ts, test-package.ts, test-visual.ts
+data/icons.json  icon source of truth
+```
+
+```bash
+npm install
+npm run build          # src/generated, dist/ (ESM + CJS + .d.ts/.d.cts), svg/, sprites/
+npm run typecheck      # strict type check of sources, tests and scripts
+npm test               # build + typecheck + unit tests + published type tests
+npm run test:package   # pack → install into a clean project → ESM, CJS, RSC, types, tree-shaking, CLI
+npm run test:browser   # real Chromium: geometry of every icon, pixel colors, Web Component, CSS
+npm run test:all       # everything
+```
+
+The browser test needs Playwright: `npm i -D playwright && npx playwright install chromium`.
+
+To add or change an icon, edit `data/icons.json` (SVG body on a 24×24 grid, 2px stroke) and run `npm run build`. The browser test checks that every icon stays inside the grid.
+
+## License
+
+MIT © Bartek Figatowski