pixel-and-stroke-geometry

Pixel and Stroke Geometry

If your app draws on a grid, canvas, or any pixel-aligned surface, the rendering rules below are non-obvious and produce a class of bugs that are otherwise mysterious. This skill covers the rules and the recipes that prevent the bugs.

When to Use

• Building a pattern editor, illustration tool, or any pixel-grid drawing app
• Implementing selection rectangles, marching ants, or grid overlays
• Drawing custom gauges, dials, charts, or progress rings
• Stroking paths in SwiftUI.Canvas or as Shape overlays
• Diagnosing "phantom pixel flicker" or "selection edge looks wrong" bugs

If your app is purely text-and-form-based, you can skip this skill.

The One Rule That Causes 80 % of Stroke Bugs

SwiftUI's .stroke(lineWidth: N) paints CENTERED on the path. A 2pt stroke covers 1pt INSIDE the path and 1pt OUTSIDE.

For Rectangle().path(in: rect).stroke(lineWidth: 2):

• Inside the rect: 1pt of stroke covers the rect's edge cells
• Outside the rect: 1pt of stroke extends past the rect's edge

This is correct rendering — exactly what CGPath does — but it's almost never what you want when you draw a border around a region.

Outset vs Inset — Which to Use

You have three choices for where the stroke sits relative to the rect's logical boundary:

You Want	Recipe
Stroke entirely OUTSIDE the rect	rect.insetBy(dx: -lineWidth/2, dy: -lineWidth/2) then stroke
Stroke entirely INSIDE the rect	rect.insetBy(dx: lineWidth/2, dy: lineWidth/2) then stroke
Stroke centered on the rect's edge (default)	No inset — .stroke(lineWidth: N)

The most common case for app developers: a selection border that should NOT visually overlap the cells inside the selection. That's "stroke entirely outside" — insetBy(dx: -lineWidth/2, dy: -lineWidth/2) to outset before stroking.

let strokeWidth: CGFloat = 2
let strokeRect = cellRect.insetBy(
    dx: -strokeWidth / 2,
    dy: -strokeWidth / 2
)
Rectangle()
    .path(in: strokeRect)
    .stroke(Color.white, lineWidth: strokeWidth)