Guides

These guides are written by hand by people who build web interfaces. They are opinionated where there is a defensible default, explicit where something is a judgement call, and corrected when they turn out to be wrong.

If you are new to this, start with what is an SVG file and how to use SVG icons in HTML. If you are solving a specific problem, the groupings below will get you there faster.

Start here: the fundamentals

What is an SVG file?

How SVG stores an image as instructions rather than pixels, what is actually inside the file, and why that single difference produces every practical advantage SVG has. Read this first if the format is new to you.

SVG vs PNG

The real comparison, including where PNG wins. Covers file size crossover points, transparency, accessibility, and the security reason some platforms refuse SVG. Ends with a decision table for real situations.

SVG vs icon fonts

Why icon fonts dominated for a decade and why they should not be your default now. Covers render blocking, the missing-glyph failure mode, screen reader behaviour and the cases where a font is still defensible.

Icon licensing

What CC0, MIT, ISC, Apache 2.0 and CC-BY actually permit, when attribution is genuinely required, and the difference between copyright and trademark, which is where almost every logo question goes wrong.

Putting icons into a page

How to use SVG icons in HTML

The four methods, inline, img, sprite and CSS background, compared on what actually differs between them: whether CSS can reach inside, whether the browser can cache it, and how many requests you make.

How to change icon colour

currentColor, fill versus stroke, hover and focus states, dark mode with no extra files, CSS variables, multi-colour icons, and why an SVG in an img tag cannot be recoloured at all.

SVG icons in React

The JSX attribute traps, writing an icon component that forwards props properly, tree shaking and what breaks it, rendering icons chosen at runtime, SVGR configuration, and why icon components should not be client components.

SVG sprites

Building an icon sprite sheet, drawing icons with <use>, keeping them recolourable, inline versus external sprites, automating the build, and the cross-origin restriction that catches everyone once.

Getting the details right

Icon sizes

Why 24 by 24 became the standard, the UI size scale and what to use where, stroke weight and optical sizing, tap targets, favicon and app icon sizes, and why two icons at the same size can still look mismatched.

Accessible icons

When an icon needs a name and when it must be hidden, icon-only buttons, decorative icons, status indicators, contrast requirements for meaningful icons, and the patterns that get this wrong on most sites.

Optimising SVG files

What design tool exports actually contain, which SVGO settings help and which two will break your icons, precision and path data, when to convert text to paths, and how far the file size can realistically come down.

Adding a favicon

The full modern set: SVG favicon, PNG fallbacks, Apple touch icon, web manifest icons, and the sizes each platform actually asks for. Includes why the browser is still showing your old one.

Advanced and specialist

Animating SVG icons

CSS, SMIL and JavaScript compared, the line-drawing technique, morphing, which properties are cheap to animate and which force layout, and respecting reduced motion preferences properly.

Building an icon system

The icon inventory, semantic versus literal naming, choosing a size scale, defining states as tokens, who is allowed to add an icon, and how to audit a product that has already drifted.

SVG security

Why SVG uploads are a cross-site scripting vector, what can hide inside an SVG, when it actually executes, sanitising properly, and the separate-origin pattern that large platforms use.

Suggested reading paths

Found an error in any of these? Tell us. Corrections are the most useful thing you can send and they get acted on.