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).
|