Screenshot baselines captured on a developer's macOS laptop fail on the Linux CI runner with tiny anti-aliasing differences across every piece of text. Why does that happen, and how would you set the suite up so baselines are portable?

## Why identical code produces different pixels A browser does not draw glyphs itself in a vacuum; it hands work to the platform's text stack. On macOS that means Core Text with its particular hinting and gamma-corrected anti-aliasing; on Linux it is FreeType plus fontconfig, whose hinting and subpixel settings depend on the distribution's configuration; on Windows it is DirectWrite. The result is that the same font at the same size legitimately produces different pixel coverage on each — thicker or thinner stems, slightly different sub-pixel positioning, sometimes a one-pixel difference in where a line wraps. That is enough to fail a pixel comparison on essentially every text-bearing element on the page, which is exactly the symptom described: not one broken component, but a faint haze of differences everywhere. Three further environment-dependent inputs compound it: - **Fallback fonts.** Any family the page does not ship itself is resolved against what the machine has installed. A Linux CI container typically has a very short font list, so text you assumed was in one face renders in DejaVu Sans instead. Emoji are a particularly visible case: colour emoji fonts differ per OS and may be absent entirely from a minimal container. - **`system-ui` and similar keywords.** These are *specified* to resolve to the platform UI font — San Francisco, Segoe UI, whatever the distro ships. A design system built on `system-ui` cannot have a cross-platform pixel baseline by definition. - **Scrollbars and form controls.** Native scrollbar width and the default appearance of `<select>`, checkboxes and date inputs are platform-specific, and a scrollbar that occupies width on one platform and overlays on another changes the layout of everything beside it. ## The fix is parity, not tolerance The wrong response is to raise the pixel tolerance until the noise fits underneath it. Anti-aliasing differences are spread thinly across the whole image, so a tolerance large enough to absorb them is large enough to absorb a genuinely shifted element or a changed colour, and the suite stops detecting the class of bug it exists to catch. The right response is to make sure that every image the suite ever compares was produced in the same environment: 1. **Pin the environment in an image.** A container with a pinned base image, a pinned browser build, and an explicit list of installed font packages. Every capture — CI or local — runs inside it. 2. **Make baseline updates go through the same image.** The update command should be a container run, not a local invocation. If a developer can regenerate baselines natively, someone eventually will, and the suite goes red for everyone else. 3. **Treat the image version as part of the baseline contract.** A browser upgrade changes rasterization, so bumping it is a deliberate change that regenerates and re-reviews all baselines. Doing that as its own commit keeps the noise separate from feature diffs. 4. **Reduce the surface that depends on the OS at all.** Self-host and embed the fonts the design uses so nothing falls back; avoid `system-ui` in components under visual test; force a consistent scrollbar treatment for the capture; keep the viewport and scale factor fixed for the run. A hosted visual-testing service is the same strategy bought rather than built: all rendering happens on the vendor's fixed infrastructure, so the developer's OS never enters the comparison. The tradeoff is cost and the fact that your baselines now live outside your repository. ## What good practice looks like day to day The healthy state is that a developer who changes a component runs the visual suite locally *through the container*, sees the same diffs CI will see, updates baselines through the same path, and commits the new images alongside the code. The unhealthy state — and the one most abandoned visual suites passed through — is that local runs and CI runs disagree systematically, so developers stop running them locally, baselines are only ever regenerated by re-running CI until it is green, and nobody actually reviews what changed. Worth saying explicitly: this is about *consistency*, not about which platform is correct. Nothing here says Linux rendering is more right than macOS rendering. It says the comparison is only meaningful between two images produced the same way, so a suite must pick one way and enforce it. If you additionally care that the UI looks right on several platforms, that is a deliberate matrix decision with its own cost, not something you get by accident from developers having different laptops.