Hero images: one enforced size/aspect standard + lint gate; plus a shared shortcut definitions registry

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

Closed feature request

John Lauer · 7d ago ·closed by Colby Knox

Two pieces of feedback, both about raising the quality bar on wiki pages.

1. Hero images need a real standard, and real enforcement

The size/aspect free-for-all is breaking the index pages. Heroes keep getting cropped and cut off in the wiki index/grid views because there is no specified size or aspect ratio. The grid clearly wants uniform heights and widths so the cards look good ganged up together. We should pick a standard the way the industry picked 1080p (1920x1080) and 16:9: one canonical pixel size and aspect ratio for heroes, published in the hero skill and enforced by the wiki. The hero-image skill currently says 16:10; whatever we settle on (16:10 or 16:9), it should be ONE exact spec (e.g. 1920x1200 @ 16:10) that every surface (page header, index grid, installer, screensaver, homepage promos) is designed around, so nothing crops.

Cropping is not a cosmetic nitpick. I am particular about margins in my hero images because humans need them: breathing room is what makes an image feel at peace. When a surface crops a hero to force a width or height on it, the margins are the first thing to die, and that ruins the whole aesthetic of the image. A single enforced aspect standard means the composition (and its margins) survives on every surface exactly as designed.

Heroes should be linted, not just suggested. The adom-wiki-hero-image skill already defines what a good hero contains: the logo placed in the image, a title, a sub-title, an actual screenshot of the real UI, the wiki URL in the form wiki.adom.inc/<user>/<slug>, and the other requirements. Today none of that is checked. Proposal:

When the AI publishes a hero, it must ALSO publish the structured fields it filled out per the hero skill (title, subtitle, screenshot source, logo placement, URL string, etc.) as metadata alongside the image. That gives the wiki codebase something machine-checkable, so it can lint and verify each required element instead of trying to reverse-engineer a PNG.
The wiki rejects or flags heroes that fail the lint, same spirit as the existing component publish gates.

Too many pages have no hero at all, and that is actually the deeper problem. The hero is meant to be a cost. It forces the AI to slow down and think about how many wiki pages it is randomly creating. Requiring a correct, linted hero before (or as) a page is created puts a real price on posting a page. And when the wiki reprimands the AI for submitting without a hero, the message should include the estimated token cost of making a good hero image, plus a nudge to reconsider the page itself: should this skill just live in the app repo instead of being a standalone page? Would a skillpack be better than N standalone skills? The hero becomes a natural limiter against the AI being too happy-go-lucky about spinning up ten pages where one would suffice.

2. We need a "definitions" standard (a shortcut registry)

People use shorthand constantly: ad = adom-desktop, hd = hydrogen-desktop, abe = adom-browser-extension. The AI needs to know what a user means when they type ad, so we need a canonical lookup list that every agent can consult.

It also needs collision handling: if somebody starts using an existing shortcut for something else, the AI should push back. "ad is already taken by adom-desktop, so you can't call adom-dealmaker ad now, pick a new shortcut."

This feels like a shared wiki page/skill (adom org) with claim semantics: first definition wins, new claims on a taken shortcut get rejected with the existing meaning shown.

1 Reply

Colby Knox · 5d ago

Closing: the hero half of this is shipped end-to-end, and the registry half lives in #43.

Shipped (all on prod):

One standard: 16:10 at 1920x1200, applied to every surface (grid cards, marquee tiles, page headers, the billboard composer itself now outputs 1920x1200 with full-bleed background), so compositions and their margins survive uncropped.
Enforcement: HERO_REQUIRED at publish (with the 16:10 spec in data), plus a HERO_ASPECT lint on repo push that measures the actual image and warns when it is off-standard by more than 3%, saying which way it will crop.
The no-hero problem: the publish gate made heroes required, and the gate carries the cost nudge (a good hero costs real tokens; spend them, or reconsider whether the page should exist).

Not built from the original text: publishing the structured hero fields (logo placement, screenshot source, URL string) as machine-checkable metadata for a content-level lint. The aspect lint plus the required gate cover the failure modes we actually saw (crops and absent heroes); if content-level lint still matters after living with these, say so and it can reopen or split.