# Project images

```
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: docs/data/img/** — the three files and their sizes
Review trigger: A rebrand; any change to a required name, dimension or ceiling;
  any change to what the consumer accepts.
```

Three files, all **webp**, all **required**, at exactly these names:

| File | Dimensions | Aspect | Typical weight |
| --- | --- | --- | --- |
| `icon.webp` | **512 × 512** | 1:1 | 8–60 KB |
| `logo.webp` | **1024** on the long edge | whatever the lockup is | 20–190 KB |
| `banner.webp` | **2176 × 725** | 3:1 | 30–130 KB |

**Not `icon.ico`.** The consumer checks the file's magic bytes, not its name: a
`.ico`, or a PNG renamed to `.webp`, is refused with a 415 and the project falls
back to an initials tile. That signature check is what makes it safe to render
these inline, so it is not going to be relaxed.

**512 KB is a hard ceiling per file**, enforced in code — the size is read from
the listing before the bytes are fetched, so an oversized asset is never
downloaded and simply never appears. Nothing enforces the dimensions, which is
why they are written down.

## Making them

```bash
magick logo-source.png -resize 512x512 -quality 82 icon.webp
identify -format '%f  %wx%h  %b\n' *.webp      # check before committing
```

Quality 80–85 suits a flat mark. If a file lands over ~200 KB it is usually a
photographic banner that wants a lower quality rather than fewer pixels.

## Why these numbers

The icon renders small — a 44 px tile in a list, 58 px on a project header — so
512 covers the densest display several times over; the reference project
deliberately halved it from 1024. The banner spans a card about 760 px wide, so
~2176 covers it at 2×, and its 3:1 shape matters more than its width because the
header crops to fill. The logo has no fixed frame, so only its long edge is
specified.

Extra sizes and variants are welcome beside these — `icon-512.webp`,
`logo-dark.webp`. Only the three exact names are checked for.

No placeholders ship with this template. An empty file is the worst of the three
states: a check that asks whether the path exists calls it present, and anything
reading the bytes rejects it. Absent is honest, and the conformance check reports
it as absent — which is what gets it filled in.

Why the requirement exists, and what reads it: [`../README.md`](../README.md).
