Skip to content

SPEC.md

Latest commit

 

History

History
44 lines (29 loc) · 2.52 KB

SPEC.md

File metadata and controls

44 lines (29 loc) · 2.52 KB
Raw

Iconopolis — Spec

Goal: A local Mac desktop app giving offline access to the complete Iconify icon collection (https://github.com/iconify/icon-sets), with a Noun Project-style interface. Icons can leave the app as SVG or PNG via copy-paste, drag-and-drop into any Mac application, or Save As.

Built: 2026-08-09 for Stefanos Karagos.

Architecture

Component Tech
Shell Electron (Node 26, installed via npm on the Mac)
Icon data @iconify/json npm package: ~200 sets, 200,000+ icons, fully offline
SVG assembly @iconify/utils (getIconData + iconToSVG) in the main process
UI Vanilla HTML/CSS/JS, no build step
Search index data/index.json, built once by build-index.js (icon names + set metadata)

Data flow

  1. build-index.js scans every set JSON once and writes a compact index: per set {prefix, name, total, category, icons: [names]}. Runs automatically on first launch if missing.
  2. Renderer loads the index (a few MB) and searches it in memory: substring match on icon name and set name, ranked (exact > prefix > substring).
  3. The grid renders lazily (IntersectionObserver). Each visible icon asks the main process for its SVG body via IPC; set JSONs are lazy-loaded and LRU-cached in the main process.
  4. PNG is produced in the renderer by drawing the SVG onto a canvas at the selected size.

Getting icons out

  • Copy: SVG → clipboard as text; PNG → clipboard as image (Electron clipboard.writeImage).
  • Drag: on drag start the renderer pre-renders the file (SVG or PNG per current format), main writes it to a temp folder and calls webContents.startDrag — a real file lands in Finder/Keynote/Slack/anywhere.
  • Save As: native save dialog via dialog.showSaveDialog.

Color applies to monotone icons (they use currentColor); multicolor sets (flags, emoji) keep their own colors. PNG size options: 32–1024px.

UI

Modeled on the Noun Project mini-window but modernized: search bar on top, set-filter chips/dropdown, responsive icon grid, per-icon always-visible hover actions (Copy, Save), bottom bar with Color, Format (SVG/PNG), PNG Size, Zoom. Light/dark theme follows the system.

Launch

  • start.command (double-click): runs npx electron . with Homebrew Node on PATH.
  • First run builds the index (progress shown in-app).

Safety

  • No database. Everything derived from node_modules/@iconify/json; data/index.json is regenerable.
  • npm install was executed natively on the Mac (this session runs on darwin, not the Linux sandbox).