tutti/docs/conventions/runtime-image-assets.md

Runtime Image Assets

Raster UI assets should be sized for their largest rendered CSS dimensions, not their design-source dimensions.

Resolution budget

Keep two physical image pixels for each CSS pixel at the largest supported display size:

runtime long edge >= largest rendered CSS long edge × 2

Include hover magnification, transforms, WebGL pixel ratio, and other presentation scaling in the CSS size. Round up to a practical bucket such as 64, 128, 192, or 256 pixels. Do not upscale a smaller source merely to fill a bucket.

Examples from the current desktop:

Surface	Largest CSS size	Runtime budget
Workbench Dock icon, including 1.7× magnification	73.4 px	192 px
AgentGUI hero and provider artwork	under 96 px	192 px
AgentGUI vinyl carousel texture	under 64 px	128 px
App update icon	20 px	64 px
Membership tier icon	14 px	64 px
Registration credits background	280 px wide	560 px wide
Onboarding section icon	20 px	64 px

Source and runtime ownership

Original-resolution masters for resized runtime assets live under design-assets/runtime-images/originals/, mirroring their former runtime paths. That directory is design input and must not be imported or packaged.

The optimized image at the normal apps/, packages/, or services/ path is the runtime asset. Preserve alpha, color profile, aspect ratio, and the existing file path when practical. If the runtime format changes, update every reference and package-asset check in the same change.

Convert indexed-color PNG sources to RGBA before resizing when they contain gradients or transparency. Scaling them as a palette can introduce visible dithering and can drop the tRNS transparency chunk.

Images that should not be reduced by this rule

Do not apply the icon budget to images whose rendered size follows the window or document width:

• desktop wallpapers;
• product and onboarding screenshots;
• recordings and animated walkthroughs;
• README and documentation media;
• platform packaging icons.

Audit those assets against their own maximum presentation width instead.

Enforcement

Run pnpm check:runtime-image-budgets after changing a bounded runtime image. The check rejects images above the committed pixel or file-size budget while leaving mirrored design masters and unbounded screenshots alone.

The staged form runs in pre-commit. The full form is selected by check:changed and pull-request CI when a governed asset or the policy itself changes. New Dock, AgentGUI agent, and AgentGUI vinyl images inherit their directory budget automatically.