Iconics

A semantic icon library with intelligent tagging and discovery

Quick Start | For AI Assistants

---

Overview

Iconics is a locally managed, semantically tagged icon library designed for instant use across projects. Use professional icons instead of emojis in documentation, GitHub READMEs, product docs, and UI guides.

Core goals:

• SQLite as the runtime catalog authority
• Semantic search with metadata fallback when CLIP is unavailable
• One-command export with ready-to-paste markdown
• Local-first usage tracking with no network telemetry

---

Quick Start

Use the CLI directly from the repo:

cd /home/zack/dev/iconics
uv run python iconics.py search security
uv run python iconics.py use lock-24x24 shield-security-protection-24x24

Recommended convenience alias:

alias iconics='uv run python /home/zack/dev/iconics/iconics.py'

Example workflow:

iconics suggest authentication
iconics use lock-24x24 shield-security-protection-24x24

Markdown output example:

## ![lock](.github/assets/icons/lock-24x24.png) Security Features
### ![shield](.github/assets/icons/shield-security-protection-24x24.png) Encryption

---

Command Reference

• iconics search <query>: semantic search with metadata fallback
• iconics query <text>: direct CLIP query with metadata fallback
• iconics suggest <context>: context-aware suggestions
• iconics info <name>: icon metadata
• iconics use <name...>: export icons + markdown snippets
• iconics md <name...>: markdown only (no export)
• iconics cat <category> [--limit N|--all]: export an entire category
• iconics categories: list allowed categories
• iconics recent --limit N: show most recent catalog additions
• iconics history [project]: show usage history from local logs
• iconics popular --limit N: show most-used icons from local analytics
• iconics stats: library stats summary
• iconics validate: integrity checks
• iconics db migrate|verify: SQLite catalog operations
• iconics provision icons|query|manifest|imports: copy icons or generate framework imports
• iconics emoji scan|convert: scan and replace emoji usage
• iconics sync: reconcile raw files, catalog entries, and embeddings
• iconics relabel: re-run vision labeling for taxonomy cleanup
• iconics tui: launch the Rust TUI2

---

Project Provisioning

Copy only the icons you need into a project and keep a manifest:

iconics provision icons lock-24x24 shield-security-protection-24x24 --dest ./

Provision via semantic query:

iconics provision query "security lock" --dest ./ --k 2

Generate framework imports from a manifest:

iconics provision imports ./iconics-manifest.json --format react --output ./src/icons.tsx

---

Emoji Cleanup

Scan a repository for emoji usage and convert to icon markdown:

iconics emoji scan --path ./docs --output emoji-report.json
iconics emoji convert --report emoji-report.json --apply

---

Catalog Management

Manual add:

iconics add lock-24x24 --semantic lock --tags security,auth --category security --desc "Lock icon"

Bulk import from CSV:

iconics import ./icons-to-import.csv

Expected CSV headers:

id,semantic,tags,category,description
Lock,lock,"security,auth,access",security,Lock icon

Usage tracking logs are local only and are ignored via .gitignore:

• icon-usage-history.json
• icon-usage-analytics.json

---

Optional Dependencies

Some commands require extra dependencies:

• watch: file watcher support (iconics watch)
• dedupe: duplicate detection (iconics dedupe)

Install with uv:

cd /home/zack/dev/iconics
uv sync --extra watch --extra dedupe

---

Directory Structure

iconics/
|-- raw/                 # Original icon files
|-- catalog/             # Categorized symlinks
|-- embeddings/          # CLIP embeddings and subspace artifacts
|-- iconics.sqlite3      # SQLite catalog (runtime default)
|-- icon-catalog.json    # Export/bootstrap catalog snapshot
|-- iconics.py           # Unified CLI
`-- deprecated/          # Archived tools and references

---

License

MIT