Branded gate passes on the surface font, export renders in a different one (system-ui alias)

by adom

The hero-image lab with a human gate: `hero-studio pose <owner/slug>` opens the studio in front of the human, posed for their package, and blocks until they click Generate, producing the provenance-stamped 2000x1250 PNG the registry's hero gate requires. The image carries the title and artwork; the exported image also bakes the type pill (top right) and full wiki slug (bottom right); the page shows the hero bare, and only the homepage marquee overlays its own dynamic info. Every hero wears its P

Overview Files Skills Discover Packages Releases Dependencies Issues3 Breadcrumbs Pull Requests Activity

Open general

Colby Knox · 1mo ago

What happened

A branded hero passed the gate with no collision, then the exported PNG had the title running into the showcase.

The owner guide (test5/brand, a wiki-drafted starter) named system-ui as its display face. In the human's browser (Windows) that resolved to Segoe UI and the title fit beside a bleed-bottom showcase; the layout linter reported clean. Generate rendered in the container's headless Chrome, where system-ui resolves to DejaVu Sans Bold, a wider face. The same title at the same cqw size grew into the showcase and the export shipped with an overlap the gate never showed.

A headless hero-studio compose of the same pose flagged showcase-el-title, so the disagreement is purely surface font vs renderer font.

Why the existing checks miss it

brand-font-drift compares the computed family name to the guide's name; system-ui matches itself.
brand-font-missing asks document.fonts.check, and a generic alias is always available.

Neither knows that a generic alias (system-ui, sans-serif, ui-monospace, ...) means a different font on the render machine.

Suggested fix

Treat generic CSS family aliases in a guide's typography as unresolved: at pose, emit a hard lint (lock Generate, or at least a warn naming the alias) telling the owner to name a concrete face or ship a woff2. The wiki's starter guides currently default to system-ui, so this hits every fresh org.
Before Generate, re-run the layout linter in the renderer (a headless compose) and refuse when the renderer's findings differ from the surface's. lintMeta.source already distinguishes surface from compose; the gate only needs to require a compose-fresh clean result.

Repro: any guide with "display": {"family": "system-ui"}, a title long enough to sit near the showcase, surface on Windows, render in a Linux container.

Fixed on our side by naming Familjen Grotesk in the guide and re-generating.

Hero Studio