What you are actually building: a canvas of positioned icon SVGs, not a fixed badge template
Every icon added gets its own x, y, and size on an internal canvas — not a slot in a predefined badge layout. That is why dragging an icon anywhere on the canvas just works, and why the final export is a single SVG assembled directly from those coordinates rather than from a template with fixed icon positions. The icon artwork itself comes from the simple-icons library, loaded and cached in the browser the first time the picker opens, and searched by title or slug while typing.
Search ranks results before it filters by popularity: an exact title or slug match scores highest, then a prefix match, then a plain substring match, then a match against one word inside a multi-word title, and only within a tie does a fixed popularity table (JavaScript, TypeScript, and React sit at the top) break the order. Category chips along the top of the picker swap the whole result list for a curated set of slugs in that category instead of running a text search at all.
Five arrangement algorithms, and how Scatter stays reproducible
Applying an arrangement recomputes every icon's position from scratch using the current icon order: Row lines everything up left to right at a fixed size and gap; Grid wraps into however many columns are set; Arc bends the row into a semicircle whose radius grows with the icon count; Bento packs icons into a 4-column grid where some cells span two columns or two rows for a magazine-style mix of sizes, following one of five sizing presets (Auto, Hero First, Hero Last, Balanced, Pyramid).
Scatter looks the most random of the five, but it is not actually random on each click — it seeds a small pseudo-random generator from a hash of the exact icon slugs selected, so the same set of icons in the same order always spreads into the identical organic layout, run after run. Changing one icon changes the seed with it, which is why removing and re-adding the same icon can shift the whole arrangement even though nothing else changed.
- Row — a single horizontal line, evenly spaced
- Grid — wraps into a fixed number of columns
- Arc — bends the same row into a semicircle
- Bento — a 4-column grid with some cells enlarged per preset
- Scatter — a deterministic pseudo-random spread seeded from the exact icon selection
Four color themes, and the one that allows a single icon override
Color theme uses each icon's actual simple-icons brand hex value — the same color the company itself specifies for its logo, not an approximation. Monochrome instead uses currentColor, meaning the icons render in whatever color the surrounding context provides (and export as literal SVG fill="currentColor", not a baked-in hex). Dark and Light are fixed near-black and near-white fills meant for placing icons against the opposite background.
Per-icon color overrides only appear in the interface when the theme is set to Monochrome — selecting an icon on the canvas then reveals a color picker that replaces that one icon's fill directly, independent of every other icon's color, with a Reset button that removes the override and lets the icon fall back to the theme's color again.
Export formats: what Markdown and HTML actually have in common
SVG export is the raw vector markup, generated straight from the canvas's current placements. Data URI is that same SVG base64-encoded into a data:image/svg+xml;base64,... string. Markdown and HTML are presented as two separate export options, with different descriptions in the interface, but as implemented today they produce exactly the same output: an <img src="data:..." alt="..."> tag built from that same base64 data URI. Neither one currently emits actual Markdown image syntax — picking either button gives an identical HTML tag.
The alt text for both is generated automatically from the titles of every icon currently on the canvas, joined by commas, so a stack of TypeScript, React, and PostgreSQL exports with alt="TypeScript, React, PostgreSQL" with no extra typing required.
The share link is the save file
There is no server-side save — every setting (which icons, their exact positions, the layout, theme, background, spacing) is continuously encoded into the page's own URL while working, replacing the browser's address bar entry without adding new history entries. The Share button copies that live URL to the clipboard; opening it later, in any browser, on any device, reconstructs the identical canvas from scratch by parsing those same URL parameters back into a configuration on load.
Building a three-icon stack end to end
Adding TypeScript, React, and PostgreSQL in that order under the default Row layout (48px icons, 12px gaps) places them at x=0, x=60, and x=120 — each icon offset from the last by exactly size-plus-gap — producing a single 168×48 SVG with no background. Each icon renders with its real brand fill pulled straight from simple-icons: #3178C6 for TypeScript, #61DAFB for React, #4169E1 for PostgreSQL. Switching the theme to Monochrome replaces all three fills with currentColor in one step; switching layout to Bento instead rearranges the same three icons into differently sized cells without changing which colors or which icons are on the canvas.