# Favicon Builder
> Design and ship a brand favicon that survives 16×16 — one recognizable shape, substantial strokes, and the Next.js App Router auto-detection pipeline so the asset actually appears in the browser tab. Use when replacing a default framework favicon, when the brand has a logo or wordmark too complex for 16×16, or when the user mentions "favicon", "site icon", "browser tab icon", or "the little icon next to the URL".
- Skill: `devotts/favicon-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add devotts/favicon-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/devotts/favicon-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: devotts (https://skillmd.com/u/devotts)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/devotts/favicon-builder
---
# Favicon Builder
Design and ship a brand favicon that survives 16×16 — one recognizable shape, substantial strokes, and the Next.js App Router auto-detection pipeline so the asset actually appears in the browser tab.
---
## When to use this skill
- Replacing the default Next.js / Vite / CRA favicon with something brand-aligned
- A brand launch where the tab icon is one of the last details still showing the framework default
- The brand has a complex logo or wordmark that's unreadable at small sizes and needs to be reduced to a single mark
- The user types `/favicon-builder` or mentions "favicon", "site icon", "browser tab icon", "tab logo", or "the little icon next to the URL"
Do NOT use for: full logo design (use `/design` or `/brand`), marketing imagery, social share previews (those need `opengraph-image.png`, not favicons), or app store icons (different ratios and rules).
---
## 1. Implementation patterns (Next.js 15 App Router)
Next.js App Router auto-detects icon files in `src/app/` and emits the correct `"` for screen readers and Lighthouse
- One `` element, no external references, no embedded raster images
- Inline everything (gradients, masks) inside `` — no external CSS
**`apple-icon.svg`:** the canonical size is 180×180, but the same SVG file works because Next resamples it. You can keep one source of truth for both files (or symlink them if you're feeling clever — but a plain copy is fine and survives `git mv` operations better).
**Working code example** — the favicon shipped for Profits Guru:
```svg
```
Notice: the chart-line stroke is `11` (4.3% of 256, the minimum that survives 16px), the arrow stroke is `22` (8.6%, much safer). The arrow is the dominant element on purpose — at 16px the chart line nearly disappears, but the chevron still reads as "up and to the right."
---
## 2. Design rules
These are not opinions. These are the rules that decide whether your favicon reads at 16×16 or turns into a gray smudge.
**ONE recognizable element from the brand mark.** Pick the most distinctive shape and drop everything else. An arrow. A chart spike. A single dot. A letterform. Full logos with wordmarks die at 16px — they become a horizontal smear of pixels.
**Round background = strong visual containment.** A filled circle gives the icon a clean silhouette against any browser chrome (light Safari toolbar, dark Chrome incognito, Firefox sidebar). Square-rounded works too. Avoid transparent backgrounds — they look weak on light chrome and disappear on dark.
**Stroke widths must be substantial.** Target 8–10% of the viewBox dimension. For `viewBox="0 0 256 256"`, that's strokes between 20 and 25. Anything below 11px will visually vanish at 16×16 — the rasterizer rounds it to under a pixel. If you must use a thin stroke for a secondary detail (like the Profits Guru chart line at 11), make sure the primary element is at 8%+ so the icon still reads when the thin stroke disappears.
**NEVER text.** Not initials. Not a single letter. Not even a stylized monogram. By the time the browser rasterizes it to 16px, the letter shapes are mush. Use the brand's logomark instead, or a geometric stand-in.
**2–3 colors max.** Brand color + background + one accent. More than that and the favicon looks like a Christmas ornament at small sizes.
**Linear gradients OK** for life and dimension — 2 stops max, kept inside a single shape. Gradients survive rasterization better than fine details because the eye reads the color shift even if individual pixels blur.
**Test at 16×16 and 32×32.** Open the SVG in a browser, zoom out, squint. If you can't tell what it is at 16px from arm's length, redesign.
---
## 3. Common pitfalls
- **Shipping the full marketing logo as a PNG** — wordmarks unreadable, file 50× bigger than needed
- **Stroke widths under 8% of viewBox** — primary shapes vanish at 16px
- **Too many elements** — five icons stacked into one space, all illegible
- **Text inside the favicon** — initials, "A", any letterform, any abbreviation
- **Missing `aria-label`** — Lighthouse accessibility warning, screen readers announce nothing
- **Manual `` element, inline defs, no external refs
5. **Write to `src/app/icon.svg`** — confirm the path before writing; if it's a non-standard Next layout (e.g., `app/` at repo root, or `frontend/src/app/`), adapt
6. **Create matching `apple-icon.svg`** — same content, same file. Copy, don't symlink (better git/deploy behavior)
7. **Remove any old manual `"` on the root ``
- ✅ Always simplify to ONE recognizable element from the brand mark
- ✅ Always use `viewBox="0 0 256 256"` unless there's a specific reason not to
- ✅ Always copy `icon.svg` to `apple-icon.svg` so iOS Safari and Add-to-Home-Screen get a clean asset
---
## Sibling skill
`/landing-page-builder` is a sibling skill that includes a favicon step as part of the full LP shipping checklist. If you're building a landing page end-to-end, start there and this skill will be invoked at the right moment. If you only need to fix or design the favicon on an existing site, invoke this skill directly.