58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
# 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).
|