# ADR 050: Simple Icons and SVGL

- HTML version: https://robbiepalmer.me/projects/personal-site/adrs/050-simple-icons-and-svgl
- Project: Personal Site (https://robbiepalmer.me/projects/personal-site.md)
- Status: Accepted
- Date: 2026-06-30

# Context

The site uses technology and company logos to make experience, project, and stack information easier to scan. The logos need to identify real brands such as tools, platforms, employers, and services.

The current site already serves local logo assets from paths such as `/company-logos/*` and excludes those paths from Cloudflare Images rewriting. That keeps the page render independent of third-party logo APIs and avoids introducing runtime request, availability, privacy, and attribution concerns for a mostly static site.

The gap is sourcing and maintaining technology and brand logos consistently. A good source needs:

* **Broad coverage** for common technologies, services, libraries, and developer platforms.
* **Recognizable assets** that preserve the brand shape users expect.
* **Static export compatibility** so selected logos can be committed or generated into the site rather than fetched at runtime.
* **Clear provenance** so each logo can be traced back to a source and reviewed against brand guidelines or license notes.
* **Low dependency weight** because logo rendering should not pull a large icon platform into the client bundle.

# Decision

Use **[Simple Icons](https://simpleicons.org/)** and **[SVGL](https://svgl.app/)** as the primary logo sources for brand and technology logos.

The lookup order is:

1. Use **Simple Icons** first when a logo is available and a normalized single-color brand mark is appropriate.
2. Use **SVGL** when Simple Icons does not include the brand or when the site needs the full-color mark, wordmark, or light/dark variant.
3. Use the brand's official asset page manually when neither source has an acceptable current asset.

Selected SVGs should be stored locally in the repository for the site to serve statically. Runtime calls to the Simple Icons CDN, SVGL API, Logo.dev, Brandfetch, or similar services are not part of this decision.

## Why Both Are Needed

Simple Icons and SVGL overlap, but they are not interchangeable.

**Simple Icons** provides a large, structured library of popular brand SVGs with an npm package, CDN options, slugs, hex colors, source URLs, and optional license/guideline metadata. It is a good fit for technology chips, compact stack lists, and monochrome logo treatments.

**SVGL** provides a curated SVG logo library with a REST API, categories, routes to SVG assets, optional light/dark variants, optional wordmarks, and direct brand URLs. It is useful when the Simple Icons mark is unavailable, when a full-color logo is clearer than a one-color glyph, or when the brand is better represented as a wordmark.

Neither source fully covers the other:

* Some Simple Icons entries are absent from SVGL.
* Some SVGL entries are absent from Simple Icons.
* Simple Icons deliberately normalizes logos into compact 24x24-style marks, which is not always the best fit for a portfolio page.
* SVGL often carries additional SVG variants, but its catalog is smaller and less package-oriented than Simple Icons.

Using both keeps Simple Icons as the default source while leaving a fallback for missing or less suitable marks.

# Alternatives

## Simple Icons Only

* **Pros**: Very broad brand coverage, first-party npm package, CDN support, TypeScript-friendly data, consistent viewboxes, hex colors, source URLs, and a public contribution workflow. The Simple Icons repository is CC0, and the package includes metadata for individual icon sources, licenses, and brand guidelines when available.
* **Cons**: One-color normalized marks are not always the right asset. Wordmarks, full-color lockups, and light/dark variants are often unavailable. Simple Icons also warns that its CC0 repository license does not imply every underlying brand icon is CC0, so each logo still needs brand/license review.
* **Decision**: Rejected as the only source. It remains the default source, but it does not cover every logo need.

## SVGL Only

* **Pros**: Full-color SVGs, categories, direct SVG routes, API search, brand URLs, and support for light/dark routes or wordmarks on some entries. Good fit for logo grids where the full brand asset matters.
* **Cons**: Smaller and more curated than Simple Icons. It is API-first rather than a first-party npm data package for this stack. The API is open but rate-limited, and SVGL asks contributors to ensure they have the rights to add each SVG. That makes local provenance review important.
* **Decision**: Rejected as the only source. It is the fallback for missing or unsuitable Simple Icons entries, not the base registry.

## Iconify

* **Pros**: Huge icon platform with many open-source icon sets, including Simple Icons. Provides APIs, packages, framework integrations, cleanup tooling, and automatic updates. Useful if the project needs one abstraction across many icon sets.
* **Cons**: Adds an abstraction layer around Simple Icons rather than solving the SVGL gap. It can obscure source-specific metadata and license/guideline checks that matter for brands. The project already uses Lucide React for generic UI icons, so adopting Iconify for logos would add platform surface area without enough benefit.
* **Decision**: Rejected for brand and technology logos. Consider only if the site later needs many non-brand icon sets under one API.

## Devicon

* **Pros**: Focused on programming languages and development tools. Provides multiple variants such as original, plain, line, colored, wordmark, font, and SVG options.
* **Cons**: Narrower catalog than Simple Icons and SVGL for this site's broader brand needs. It is useful for developer technologies but less useful for SaaS products, employers, cloud services, AI tools, or non-developer brands.
* **Decision**: Rejected as a primary source. It can be used manually for a specific technology if both preferred sources are unsuitable.

## React Icons

* **Pros**: Easy React component imports for many popular icon packs, including Simple Icons. Tree-shakeable imports can keep client bundles focused on used icons.
* **Cons**: It is a React delivery wrapper, not a logo sourcing strategy. It does not solve missing SVGL logos, full-color SVGs, wordmarks, or local provenance. It also couples content assets to the React bundle rather than serving them as static content.
* **Decision**: Rejected. Use static SVG assets for logos; keep React icon packages for UI icons only.

## Logo.dev and Brandfetch

* **Pros**: Broad company-logo APIs with CDN delivery, search, brand metadata, and automatic updates. Strong fit for applications that need dynamic customer, merchant, or company enrichment at runtime.
* **Cons**: External service dependency, API keys or client identifiers, pricing and attribution requirements, request limits, caching terms, and runtime failure modes. The site has a small fixed set of logos, so dynamic enrichment is unnecessary. These platforms also optimize for company logos more than technology-stack icon consistency.
* **Decision**: Rejected. They solve a different problem: runtime enrichment for many unknown brands.

## Manual Official Logo Downloads Only

* **Pros**: Best legal and brand-guideline provenance. Gives the most authoritative asset for a specific brand.
* **Cons**: Slow, inconsistent, and hard to maintain across many technologies. Official asset pages vary widely in quality, format, naming, and permitted use. Without a registry, every update becomes bespoke research.
* **Decision**: Rejected as the default. It remains the fallback when Simple Icons and SVGL are missing or stale.

## Generic UI Icons

* **Pros**: Existing UI icon libraries such as Lucide React are consistent, accessible, and appropriate for actions, controls, and abstract concepts.
* **Cons**: Generic icons do not represent actual brands. Replacing a technology logo with a generic symbol loses the recognition benefit and can look like placeholder content.
* **Decision**: Rejected for brand identity. Continue using generic icons for UI controls and non-brand concepts.

# Consequences

## Positive

* **Better Coverage**: Combining Simple Icons and SVGL covers more technologies and brands than either source alone.
* **Consistent Default**: Simple Icons gives a normalized baseline for compact technology lists and stack badges.
* **Fallback Variants**: SVGL provides full-color, wordmark, and theme-aware variants where the normalized Simple Icons mark is missing or less recognizable.
* **Static Export Compatible**: Vendored SVGs keep logo rendering compatible with static export and avoid runtime third-party API calls.
* **Traceable Provenance**: Both sources expose enough metadata or URLs to record where each logo came from.
* **Low Platform Sprawl**: This avoids adopting a larger icon platform or paid logo API for a finite content set.

## Negative

* **Manual Review Still Required**: Brand marks remain trademarked assets. A source being open or convenient does not remove the need to check brand guidelines and license notes for each logo.
* **Two Catalogs to Search**: Contributors must check both Simple Icons and SVGL before falling back to official assets.
* **Visual Normalization Work**: Simple Icons and SVGL assets may have different viewboxes, padding, colors, and aspect ratios. The site may need local sizing rules or preprocessing to keep grids aligned.
* **Stale Logos**: Vendoring SVGs avoids runtime dependencies but means logo updates are not automatic.
* **Source Policy Changes**: Either project can change contribution criteria, catalog coverage, API shape, or metadata quality. The local asset cache reduces runtime risk but not maintenance risk.
* **Residual Gaps**: Some brands will still require official manual downloads or custom handling.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt