You export an icon from Figma, drop it into your component, and it looks perfect at 24px. Then you render it at 20px on a retina display, and it’s subtly blurry. Or you use a stroke-based icon set and notice the strokes bleed outside the bounding box in Firefox but not Chrome. Or your icon library looks sharp on macOS and fuzzy on a 1x Windows display.
These are not random bugs. They follow predictable rules, and once you understand those rules, you can fix them permanently — or better yet, avoid them from the start.
This article is about the mechanics: SVG coordinate space, how stroke rendering actually works, what "optical sizing" means in practice, and the specific techniques that separate a crisp icon library from one that ships visual debt into every release.
The Coordinate System Is Not What You Think
SVG operates on an abstract coordinate system. When you write viewBox="0 0 24 24", you’re defining a 24×24 unit space. That space gets mapped to whatever pixel dimensions you assign via width and height. The mapping is straightforward when the ratio is 1:1, but it gets tricky everywhere else.
The critical insight: SVG units are not pixels. They become pixels only after the viewport transform is applied. A path at x=0.5 is perfectly valid in SVG — it represents a point halfway between two grid units. Whether that maps to a subpixel position in screen space depends on the final rendered size.
When you render a 24-unit viewBox at 24px, the transform is 1:1. A line drawn at y=1 lands on pixel row 1 exactly. Clean.
When you render that same viewBox at 48px, 1 SVG unit = 2 CSS pixels. Still clean — every unit maps to a whole number of pixels.
When you render it at 20px, 1 SVG unit = 0.833 CSS pixels. Now y=1 maps to y=0.833 in screen space. That’s a subpixel position, and the browser has to antialias it. Hello, blur.
This is why icon systems that only design for one size break at others. The coordinate system betrays you.
Stroke Alignment: The Feature SVG Doesn’t Have
If you’ve worked with design tools, you know stroke alignment — you can set a stroke to sit on the inside, outside, or center of a path. Figma has it. Illustrator has it.
SVG does not.
SVG strokes are always centered on the path. Half the stroke width goes inside the path, half goes outside. There is no stroke-alignment property in the SVG spec (there was a proposal, it went nowhere). vector-effect: non-scaling-stroke exists but solves a different problem.
This matters enormously for icons. Take a simple 24×24 icon with a 2px stroke on its bounding rectangle:
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" width="24" height="24" stroke="black" stroke-width="2" fill="none"/>
</svg>
The stroke is centered on the path edge, so 1px goes inside the viewBox and 1px goes outside. The outside portion is clipped by the SVG viewport. You’re losing half your stroke. The rendered rectangle has a 1px stroke, not 2px.
The fix is to inset your geometry by half the stroke width:
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
<!-- stroke-width=2, so inset by 1px on each side -->
<rect x="1" y="1" width="22" height="22" stroke="black" stroke-width="2" fill="none"/>
</svg>
Now the stroke is fully inside the viewBox. This is fundamental and virtually every icon library gets it wrong at least once.
Simulating Inner/Outer Stroke
When you genuinely need inner or outer stroke behavior, you fake it:
Inner stroke — double the stroke width and clip with the shape itself:
<defs>
<clipPath id="inner-clip">
<rect x="0" y="0" width="24" height="24"/>
</clipPath>
</defs>
<rect x="0" y="0" width="24" height="24"
stroke="black" stroke-width="4" fill="none"
clip-path="url(#inner-clip)"/>
Outer stroke — double the stroke width, use a mask to hide the interior:
<defs>
<mask id="outer-mask">
<rect width="24" height="24" fill="white"/>
<rect x="1" y="1" width="22" height="22" fill="black"/>
</mask>
</defs>
<rect x="0" y="0" width="24" height="24"
stroke="black" stroke-width="4" fill="none"
mask="url(#outer-mask)"/>
These are ugly but they work. Production icon libraries rarely need this — the simpler approach is to design with centered strokes from the start and just account for the inset.
The Half-Pixel Trap
Here’s a gotcha that ruins crisp icons even when everything else is correct.
A 1px-wide stroke in SVG is centered on the path. If that path sits on an integer coordinate — say y=12 — then the stroke occupies y=11.5 to y=12.5. On a 1x display, this straddles two pixel rows. The browser has to antialias it across both rows. Your crisp horizontal line becomes a blurry 2px line at half opacity.
The fix: offset paths by 0.5 units when drawing 1px strokes.
<!-- Blurry 1px stroke: centered on y=12, straddles two pixels -->
<line x1="0" y1="12" x2="24" y2="12" stroke="black" stroke-width="1"/>
<!-- Crisp 1px stroke: centered on y=12.5, sits exactly on one pixel -->
<line x1="0" y1="12.5" x2="24" y2="12.5" stroke="black" stroke-width="1"/>
The rule of thumb: for odd stroke widths (1px, 3px), offset the geometry by 0.5. For even stroke widths (2px, 4px), keep coordinates on integer values.
This only matters at 1:1 scale (the viewBox renders at its natural pixel size). At 2x (retina), both positions render cleanly because you have 2 device pixels per CSS pixel.
Adjust your SVG icon grid accordingly. If you’re using a 24px grid with 1px strokes, design on a 0.5-snapped grid.
Optical Sizing: Mathematics Lies, Eyes Don’t
Here’s something that trips up developers building icon systems: mathematically equal shapes do not look visually equal.
Take a circle and a square, both fitting inside a 24×24 bounding box. The circle will look smaller. This is a perceptual phenomenon — the corners of the square visually "push out" to the edges, while the circle only touches the edges at four points. The actual visual weight of the circle is less than the square.
Icon sets that naively pack every glyph into the same bounding box produce inconsistent visual rhythm. The circle feels like it belongs to a different size class.
Optical sizing is the practice of adjusting the geometry — not the mathematical bounding box — so that icons feel the same size. In practice:
- Circular icons should be drawn slightly larger than square icons (1-2px oversize in a 24px grid)
- Wide icons (arrows, hamburger menus) often need less height than tall icons to feel balanced
- Thin icons (lines, carets) may need visual weight added via slightly thicker strokes
This is borrowed from type design. Typographers have done this forever — the lowercase ‘o’ in a well-designed font is slightly oversized relative to the lowercase ‘x’ height, or it would look too small.
Building an Icon Grid That Handles This
Most professional icon systems use a keyline grid to enforce optical consistency. Google’s Material Icons uses this approach explicitly. The grid defines several shape templates:
- Square keyline: 20×20 (within 24×24 viewBox, 2px padding)
- Circle keyline: 20px diameter, centered
- Wide keyline: 22×18
- Tall keyline: 18×22
Icons are drawn to fit their respective keyline, not the full 24×24 box. The padding between keyline and viewBox edge is the optical buffer. You don’t fill it — but it’s there so the visual weight feels consistent across different shapes.
<!-- Icon grid helper (strip from production SVGs) -->
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
<!-- Debug keylines, delete before shipping -->
<rect x="2" y="2" width="20" height="20" fill="none" stroke="#f00" stroke-width="0.5" opacity="0.3"/>
<circle cx="12" cy="12" r="10" fill="none" stroke="#00f" stroke-width="0.5" opacity="0.3"/>
<!-- Your actual icon paths go here -->
</svg>
Rendering Hints That Actually Work
shape-rendering: crispEdges
This CSS property tells the browser to trade antialiasing for pixel alignment. Useful for icons with strict horizontal/vertical lines:
.icon {
shape-rendering: crispEdges;
}
The catch: it makes diagonals and curves look jagged. Use it only for icons that are exclusively rectilinear — grid icons, plus signs, basic UI controls. Never apply it globally.
text-rendering and image-rendering Are Different
Don’t confuse shape-rendering with image-rendering. They control different render pipelines. image-rendering: pixelated applies to raster images and canvas, not to SVG paths.
will-change and GPU Compositing
If your icons animate (spin, fade, scale), adding will-change: transform promotes them to their own compositor layer. This prevents pixel jitter during animation that comes from the browser recalculating subpixel positions on every frame. But don’t sprinkle will-change on static icons — it wastes GPU memory for no benefit.
Scaling Without Distortion: The preserveAspectRatio Trap
When you set an SVG to width: 100%, the browser scales it based on preserveAspectRatio, which defaults to xMidYMid meet. This centers the viewBox and letterboxes it if the container aspect ratio differs.
This is fine for icons in fixed-size containers. It becomes a problem when you use SVGs as background images or in contexts where the container is free-form.
For icons specifically, always provide both explicit width and height — either as attributes or via CSS. Let the SVG define its own aspect ratio via viewBox, and don’t let the container fight it:
.icon {
width: 24px;
height: 24px;
flex-shrink: 0; /* critical in flex containers */
}
The flex-shrink: 0 is not optional. Flex containers will happily squash your icons to 0×0 if there’s no space, and then you spend an hour debugging why your icon disappeared.
Gotchas
Gotcha: currentColor and stroke vs fill
currentColor is the right way to make icons inherit text color. But it applies to both fill and stroke — so if your icon uses both, setting color on the parent affects everything. Make sure your icon paths explicitly set fill="none" or stroke="none" where you don’t want color inherited. Don’t rely on defaults.
Gotcha: viewBox without explicit width/height
An SVG with only viewBox and no width/height attributes will render at its "intrinsic" size in most contexts, but in some browsers and some layout contexts it will render at 0×0 or collapse. Always set explicit width and height as fallbacks, even if CSS overrides them.
Gotcha: path data with absolute coordinates
When you export from Figma or Illustrator, paths often come with absolute coordinates baked in. Resizing the viewBox doesn’t rescale these paths — you need to either rescale the coordinates or rescale via transform. The safest approach is to always export with a clean viewBox that matches your coordinate space.
Gotcha: stroke-width and scaling
When an SVG scales via CSS, stroke-width scales with it unless you use vector-effect: non-scaling-stroke. A 1.5px stroke at 24px becomes a 3px stroke at 48px. This is usually what you want — but it means your half-pixel alignment rules depend on the rendered size, not the SVG coordinate space. Test at multiple sizes.
Gotcha: Safari and subpixel strokes
Safari rounds subpixel stroke widths differently than Chrome and Firefox. A stroke-width="1.5" that looks perfect on Chrome can render as a 1px or 2px stroke in Safari depending on the display’s pixel ratio. Stick to integer or half-integer stroke widths and test on actual Apple hardware, not just Chrome DevTools device simulation.
Gotcha: Icon sprites and use elements
SVG sprites via <use> are great for performance, but they inherit styles from the shadow DOM in a non-obvious way. Styles applied to the <use> element don’t automatically cascade into the referenced <symbol>. Use CSS custom properties (variables) inside the symbol definitions to allow external control:
<symbol id="icon-close" viewBox="0 0 24 24">
<path stroke="var(--icon-color, currentColor)" stroke-width="var(--icon-stroke, 1.5)" .../>
</symbol>
Production-Ready Checklist
Before shipping an icon to production, run through this:
- Stroke inset — if the icon has a stroke, is the geometry inset by
stroke-width / 2from the viewBox edge? - Half-pixel alignment — odd stroke widths on axis-aligned lines: are coordinates at
.5offsets? - Optical size — does this icon sit on the right keyline? Does it feel the same visual weight as adjacent icons?
currentColor— does it inherit color correctly? Isfill/strokeexplicitly set where not wanted?- Multi-size test — render at 16px, 20px, 24px, 32px, 48px. Any blurring?
- Retina and 1x — check on a 1x display (not just macOS retina). Subpixel issues are most visible at 1x.
- Firefox/Safari — stroke rendering differences are real. Cross-browser check is not optional.
flex-shrink: 0— icon in a flex container? Add it.- Stripped metadata — production SVGs shouldn’t carry editor comments, unused defs, or Figma-injected IDs.
Automating the Pixel-Perfect Rules
If you’re building an icon library at scale, hand-checking all of this is brutal. A few tools worth knowing:
SVGO cleans up SVG output from editors — removes metadata, collapses redundant transforms, rounds coordinates. Configure it carefully though: aggressive rounding can move your half-pixel offsets to integer positions, undoing your crisp-edge work. Set floatPrecision to at least 2.
{
"plugins": [
{ "name": "preset-default" },
{
"name": "convertPathData",
"params": { "floatPrecision": 2 }
}
]
}
svg-sprite or similar bundlers let you build sprite sheets automatically. Pair with a CI check that validates viewBox consistency, stroke-width values, and that no paths exceed the keyline boundary.
For design-to-code pipelines, write a small script that validates exported SVGs before they enter the repo. Check that viewBox is set, that width and height attributes exist, and that no strokes exceed the canvas. A 50-line Node script saves hours of bug hunting.
Getting SVG icons right is mostly understanding a handful of specific mechanics: how stroke centering works, when coordinates produce subpixel positions, and that visual consistency is not the same as mathematical consistency. None of this is guesswork once you know the rules. The tooling and browser rendering pipelines are predictable — you just have to work with them instead of against them.