Assets

Optimierbare Originalbilder liegen unter src/assets/ und laufen durch die Bildpipeline von Astro. public/ ist nur für Dateien gedacht, die unverändert ausgeliefert werden müssen.

Die Regel

Bilder werden über ihren Schlüssel im Manifest angesprochen, nicht über einen Dateipfad.

---
import Pic from '../components/media/Pic.astro';
---

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

Alt-Text, Bildnachweis, Fokuspunkt und Preset stehen in src/content/assets.yaml. Ein zweiter Einsatzort erbt dadurch denselben Alt-Text, statt einen neuen zu erfinden. Ein Tippfehler im Schlüssel bricht den Build ab — Seiten werden beim Bauen gerendert, und getAsset() wirft bei einem unbekannten Schlüssel.

Das Manifest

src/content/assets.yaml ist eine Content Collection mit file()-Loader. Das Schema in src/content.config.ts wird beim Bauen ausgewertet.

startseite-hero:
  file: ../assets/startseite-hero-arbeitsplatz.jpg
  alt: Platzhalterbild des Starters mit diagonalem Streifenmuster in der Markenfarbe.
  altApproved: true
  preset: hero
  focalPoint:
    x: 0.35
    y: 0.4

Feld	Pflicht	Bedeutung
file	ja	Pfad relativ zur YAML-Datei; wird beim Bauen aufgelöst
alt	ja	Alternativtext, nicht leer
preset	ja	hero, card, logo oder og
altApproved	nein	false heißt: Vorschlag, noch nicht menschlich geprüft
credit	nein	Bildnachweis; ist er gesetzt, wird er sichtbar ausgegeben
focalPoint	nein	Anteile 0–1; Vorgabe Mitte

Drei Dinge brechen den Build ab: ein fehlender Alt-Text, ein unbekanntes Preset und eine Bilddatei, die es nicht gibt. Das letzte kommt von image() im Schema — ein Tippfehler im Dateinamen scheitert beim Bauen und nicht erst als fehlendes Bild auf der fertigen Seite.

Alt-Texte

Ein Sprachmodell darf Alt-Texte vorschlagen. Bis zur menschlichen Freigabe gelten sie als Vorschlag, nicht als endgültige Wahrheit — dafür ist altApproved da. Ein Modell sieht das Bild, kennt aber nicht seine Rolle im Text.

Dekorative Bilder

Ein leerer Alt-Text ist nicht vorgesehen. Rein dekorative Bilder gehören nicht ins Manifest, sondern als Hintergrund ins CSS.

Benennung

bereich-motiv-variante.ext — etwa startseite-hero-arbeitsplatz.jpg. Der Dateiname beschreibt das Bild, der Manifest-Schlüssel seinen Einsatzort. Beide dürfen sich unabhängig ändern: Wird ein Foto getauscht, bleibt der Schlüssel und keine Seite muss angefasst werden.

Die Bilder im Starter sind Platzhalter und werden im Kundenprojekt ersetzt.

Presets

Ein Preset bündelt, was zusammengehört: erzeugte Breiten, die im Layout belegte Breite und das Skalierungsverhalten. widths ohne passendes sizes lädt zuverlässig die falsche Datei — und das fällt nur mit einem Netzwerkprofil auf. Deshalb wählen Seiten ein Preset, keine Einzelwerte.

Preset	Layout	Einsatz
hero	full-width	Bild über die volle Seitenbreite
card	constrained	Bild in Karte oder Raster
logo	constrained	Wort- oder Bildmarke, hohe Güte

Eine SVG-Datei durchläuft keine Rasterisierung: <Pic /> liefert sie unverändert als <img> mit Maßen aus, ohne AVIF und WebP. Logos sind deshalb als SVG am besten aufgehoben. | og | fixed | Vorschaubild für soziale Netzwerke |

Die Presets stehen in src/lib/images.ts. Am Einsatzort lässt sich das Preset des Manifests überschreiben (<Pic asset="…" preset="card" />), ebenso sizes.

Erzeugt werden AVIF und WebP plus eine Fallback-Datei im Ursprungsformat. Der Browser nimmt das erste Format, das er beherrscht.

Bilder über der Falz

Das LCP-Bild einer Seite bekommt priority:

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

Das setzt loading="eager", decoding="sync" und fetchpriority="high".

Genau eines pro Seite

Mehrere vorrangige Bilder konkurrieren um dieselbe Bandbreite und verschlechtern genau die Kennzahl, für die sie gesetzt wurden. Ein Post-Build-Test prüft das auf jeder Seite jeder Ausgabe.

Fokuspunkt

Bildausschnitte entstehen nicht beim Erzeugen der Datei, sondern erst im Layout: Ein Hero-Bild in einem flachen Container beschneidet der Browser. Ohne Angabe beschneidet er zur Mitte — und schneidet zuverlässig Köpfe ab.

focalPoint aus dem Manifest wird zu object-position. Der Styleguide zeigt den Effekt an einem sehr flachen Container.

Bildnachweis

Ist credit gesetzt, gibt <Pic /> ihn als <figcaption> aus — ohne Schalter am Einsatzort. Ein Nachweis, den man vergessen kann, ist bei fremdem Bildmaterial ein rechtliches Risiko. Wer keinen sichtbaren Nachweis will, trägt keinen ein.

Was geprüft wird

pnpm verify enthält mit test:dist Prüfungen auf dem ausgelieferten HTML — für alle drei Ausgaben, also auch die Fixtures:

• kein <img> ohne alt
• kein <img> ohne width und height (sonst springt der Text beim Nachladen)
• jedes <picture> bietet AVIF und WebP an
• höchstens ein Bild je Seite mit fetchpriority="high"
• alle übrigen Bilder laden verzögert
• der Fokuspunkt landet tatsächlich in object-position

Bilder aufnehmen

Der Skill import-assets (.claude/skills/import-assets/) führt den Weg von der gelieferten Datei bis zum Manifest-Eintrag: Ablage unter src/assets/, Benennung nach <seite>-<zweck>-<detail>, Eintrag mit Alt-Text, Bildnachweis und Fokuspunkt.

Vorgeschlagene Alt-Texte bekommen dabei altApproved: false. Die Zeile ist nicht optional — sie unterscheidet einen Vorschlag von einer Zusage, und auf true setzt sie ein Mensch (ADR 0005). Mehr zur Arbeitsweise unter Claude Code.