0005 — Bildmetadaten im Asset-Manifest statt am Einsatzort

Status: angenommen · Milestone: M3

Kontext

Ein Bild bringt Angaben mit, die nicht im Bild stehen: Alternativtext, Bildnachweis, welcher Ausschnitt der wichtige ist. Der naheliegende Ort dafür ist die Seite, die das Bild einbindet:

<Image src={hero} alt="Zwei Personen an einem Schreibtisch" />

Der Audit des Referenzprojekts zeigt, wohin das führt. Dort lagen Bilder in public/, wurden also gar nicht optimiert, und Alt-Texte standen verstreut in den Seiten — dasselbe Motiv trug an zwei Stellen zwei verschiedene Beschreibungen, eine davon leer. OG-Bild-Angaben zeigten auf Dateien, die nie existierten, weil ein Pfad als Zeichenkette niemand prüft.

Entscheidung

Originale liegen unter src/assets/ nach dem Schema bereich-motiv-variante.ext. Alle Metadaten stehen in src/content/assets.yaml, einer Content Collection mit file()-Loader. Seiten sprechen Bilder über ihren Schlüssel an:

<Pic asset="startseite-hero" priority />

<Pic /> führt Manifest und Preset zusammen. Die Presets in src/lib/images.ts bündeln widths, sizes, layout und Güte je Einsatzort.

Vier Dinge brechen den Build ab:

1. fehlender Alt-Text (Zod im Collection-Schema)
2. unbekanntes Preset (Zod-Enum)
3. Bilddatei nicht vorhanden (image() im Schema)
4. unbekannter Schlüssel am Einsatzort (getAsset() wirft beim Rendern)

Begründung

Der Schlüssel trennt zwei Dinge, die sich unabhängig ändern: den Einsatzort und die Datei. Wird ein Foto ausgetauscht, bleibt der Schlüssel und keine Seite muss angefasst werden.

Entscheidend ist aber die Richtung der Verantwortung. Steht der Alt-Text am Einsatzort, ist er eine Eigenschaft dieser Seite — und beim zweiten Einbinden erfindet ihn jemand neu. Steht er am Bild, ist er eine Eigenschaft des Bildes und gilt überall. Dasselbe gilt für den Bildnachweis: Als Manifest-Feld wird er von <Pic /> ausgegeben, sobald er gesetzt ist. Ein Nachweis, den man am Einsatzort vergessen kann, ist bei fremdem Bildmaterial ein rechtliches Risiko.

Presets statt Einzelwerte, weil widths und sizes nur zusammen richtig sind. Eine falsche sizes-Angabe lädt zuverlässig die falsche Datei und fällt ohne Netzwerkprofil niemandem auf.

Verworfene Alternativen

Alt-Text und Nachweis als Props am Einsatzort. Der vertraute Weg und der aus dem Referenzprojekt bekannte Fehler: Dieselbe Datei bekommt an zwei Stellen zwei Beschreibungen.

Frontmatter je Bild in einer Datei neben dem Bild. Verteilt dieselbe Information auf so viele Dateien, wie es Bilder gibt, und macht eine Gesamtprüfung („welche Alt-Texte sind noch Vorschläge?") zu einem Suchlauf über das Dateisystem.

Bilder in public/. Keine Optimierung, keine Maße im HTML, keine Prüfbarkeit — der Audit-Befund des Referenzprojekts.

Ein leerer Alt-Text für dekorative Bilder. Wäre bequem, würde aber die Pflichtregel aufweichen. Dekoratives gehört als Hintergrund ins CSS und nicht ins Manifest.

Konsequenzen

• sharp ist eine Projektabhängigkeit. Astros Bildpipeline verlangt sie ausdrücklich; unter pnpm ist Astros eigene Kopie nicht auflösbar.
• image.responsiveStyles ist aktiviert. Ohne diese Option bliebe das layout der Presets wirkungslos.
• Das Feld altApproved unterscheidet vorgeschlagene von freigegebenen Alt-Texten. Der import-assets-Skill (M9) setzt es auf false, ein Mensch auf true.
• seo.defaultOgImage verweist auf einen Manifest-Schlüssel. Der Styleguide löst ihn auf, wodurch ein toter Verweis heute schon den Build bricht; ab M4 übernimmt das die <Seo />-Komponente an prominenterer Stelle.
• Post-Build-Prüfungen laufen über tests/dist/ in einem eigenen Vitest-Lauf, weil sie einen fertigen Build voraussetzen.