Teach the hero doctrine: ONE message, the message is the TITLE, white space is the design

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

Closed general

John Lauer · 2mo ago ·closed by Colby Knox

From John, 2026-08-11, after reviewing recent employee heroes: people keep making the vitrine fill the whole hero, and cramming 6 messages into the image. They think the hero is about the vitrine. It is not. Hero Studio currently nudges this direction (the layout is literally labeled 'Showcase (65% vitrine)') and never teaches the philosophy.

The doctrine the studio should actively teach at the gate:

THE GOLDEN RULE: a hero image gets across exactly ONE message. Six messages = zero messages.
That one message IS the title, ideally approaching one word. The vitrine is supporting evidence, not the message.
White space is not wasted space; it is what makes the one message land (standard graphic design theory: negative space directs the eye and creates hierarchy).
The subtitle's font size is deliberately downplayed BECAUSE it is assumed it won't get read. If the design only works when someone reads the subtitle, the hero has failed. Same reason the marquee band must stay calm.

Asks:

Walkthrough/checklist explainer text that teaches the above in one or two sentences per step ('this is your title: it is the ONLY message this image sends').
Lint: warn when the vitrine exceeds a coverage threshold of the hero area, and when a full-import's image zone contains multiple competing text messages (the edge-density scan already exists; extend it to count distinct text blocks).
Consider renaming or de-defaulting vitrine-maximal layouts so the title-first hierarchy is the path of least resistance.

1 Reply

Colby Knox · 2mo ago

Shipped in 0.17.0, all three asks.

The walkthrough now teaches the doctrine in place: the title step opens with "a hero gets across exactly ONE message, and this is it: the title, ideally approaching one word; six messages equal zero messages"; the subtitle step says it is deliberately small BECAUSE nobody is assumed to read it, and if the design needs it read the hero has failed; the vitrine step names it supporting evidence, NOT the message, and explains white space as what makes the message land. SKILL.md carries the four rules as "The hero doctrine" so driving AIs read it before posing.
Lint, both halves: vitrine coverage above 72% of the hero area warns with the hierarchy argument in the message; full imports get a 4x3 edge-density grid over the upper zone, and 6+ text-dense zones warns as several competing messages (labeled heuristic, like the band scan it extends).
Vitrine-maximal nudging removed: the layout button no longer sells "65% vitrine"; it is just Showcase, and its tooltip now says the title is STILL the message and the scrim exists to protect the text column's white space. The default layout was already title-first.

The fit solver (#40) reinforces rule 1 from the other side: when a headline cannot make 3 lines at any legible size, its warning says shorter copy reads bigger.