Der erste Tag

Vom leeren Repository bis zur ersten echten Seite — in der Reihenfolge, in der es tatsächlich passiert.

Diese Seite ist für den ersten Durchgang gedacht und setzt keine Astro-Erfahrung voraus. Sie erklärt jeden Schritt so weit, dass er ausführbar ist, und verlinkt für alles Weitere in die Referenz. Wer den Starter schon kennt, ist mit dem Einstieg schneller.

Am Ende des Tages steht: ein initialisiertes Projekt, gefülltes Briefing, die Marke in den Design Tokens, eine selbst gebaute Seite — und eine grüne Qualitätskette.

Was hier anders ist als in Joomla

Die technischen Details sind lernbar. Was am Anfang wirklich stolpern lässt, sind drei Annahmen, die aus dem CMS-Alltag mitkommen und hier nicht gelten.

Es gibt kein Backend. Keine Anmeldung, keine Oberfläche, in der Inhalte gepflegt werden. Alles — Texte, Bilder, Menü, Einstellungen — liegt als Datei im Repository und wird im Editor geändert. Das klingt nach Rückschritt und ist der Grund, warum ein Projekt Jahre später noch baut: Es gibt nichts, was sich hinter der Oberfläche unbemerkt verstellt.

Es gibt keinen Server, der die Seite zusammenbaut. Joomla setzt jede Seite bei jedem Aufruf neu zusammen. Hier passiert das einmal, beim Bauen, auf deinem Rechner oder in der CI. Ausgeliefert werden fertige HTML-Dateien. Deshalb gibt es keine Datenbank, kein PHP im Frontend und nichts, was gehackt werden könnte — und deshalb muss nach jeder Änderung gebaut werden, bevor sie online steht.

Fehler passieren beim Bauen, nicht beim Besuchen. Ein Tippfehler in einem Bildnamen bricht den Build ab, statt der Besucherin ein kaputtes Bild zu zeigen. Das fühlt sich zunächst streng an. Es ist die Absicht: Was hier scheitert, scheitert vor dem Livegang.

Übersetzungstabelle

In Joomla / YOOtheme	Hier
Artikel anlegen	Datei unter src/pages/ anlegen
Menüpunkt setzen	Eintrag in navigation.main in project.config.ts
Template / Theme	src/layouts/BaseLayout.astro plus src/components/
YOOtheme Customizer, Farben	Design Tokens in src/styles/theme.css
Module und Positionen	Komponenten, die eine Seite selbst einbindet
Medienverwaltung	src/assets/ plus das Manifest src/content/assets.yaml
Globale Konfiguration	project.config.ts
Erweiterung installieren	Paket über pnpm add — mit Begründung im Pull Request
Änderung ist sofort live	Änderung → pnpm verify → Commit → Tag → Deployment
Backup der Datenbank	Git-Historie; ein Rollback ist ein Deployment eines früheren Tags

Eine .astro-Datei lesen

Das ist die einzige Syntax, die du für heute brauchst. Eine Seite hat zwei Teile, getrennt durch drei Bindestriche:

---
// Oben: Vorbereitung. Läuft beim Bauen, nie im Browser.
import BaseLayout from '../layouts/BaseLayout.astro';

const jahr = new Date().getFullYear();
---

<!-- Unten: das Markup. Ganz normales HTML. -->
<BaseLayout title="Beispiel">
  <p>Wir schreiben das Jahr {jahr}.</p>
</BaseLayout>

Der obere Teil ist TypeScript und läuft ausschließlich beim Bauen. Der untere ist HTML, in dem {...} einen Wert von oben einsetzt. Mehr ist es für eine Inhaltsseite nicht.

Wer tiefer einsteigen will: die Astro-Dokumentation erklärt die Sprache vollständig. Für diesen Starter reicht das Obige.

Vorbereitung

Node 24, pnpm und Git müssen da sein; PHP 8.3 und Composer nur, wenn das Projekt den PHP-Formular-Handler bekommt. Die genauen Versionen und die Installation stehen im Einstieg.

1. Das Repository anlegen

Der Starter ist ein Template. Aus ihm entsteht ein neues Repository mit eigener, leerer Historie — die Commits des Starters gehören nicht in ein Kundenprojekt.

gh repo create Kicktemp/kunde-projekt --private --template Kicktemp/astro-boilerplate
git clone git@github.com:Kicktemp/kunde-projekt.git
cd kunde-projekt
pnpm install

pnpm install lädt die Abhängigkeiten. Das dauert beim ersten Mal ein bis zwei Minuten.

2. Den Init laufen lassen

pnpm starter:init

Ein Dialog stellt rund fünfzehn Fragen — Projektname, Domain, Auftraggeber, Deploymentziel, Formular-Backend, Tracking — und schreibt daraus die Projektkonfiguration. Nach Geheimnissen fragt er nirgends; alles, was er erhebt, ist öffentlich.

Sieh dir vorher an, was passieren wird:

pnpm starter:init --dry-run

Das gibt den vollständigen Plan aus und schreibt nichts. Danach ohne --dry-run ausführen, und anschließend:

git diff          # der Init als eine einzige, überprüfbare Änderung
pnpm verify       # muss grün sein

pnpm verify ist die Qualitätskette: Formatierung, Typen, Tests, Builds, Barrierefreiheit. Sie läuft in der CI identisch und muss vor jedem Commit grün sein. Beim ersten Mal dauert sie einige Minuten.

Was der Init im Einzelnen ändert, steht im Einstieg. Begleiten lassen kann man ihn vom Skill project-init (Claude Code).

3. Das Briefing füllen

Unter project/ liegen sieben Dateien mit Leitfragen. brief.md hat der Init bereits mit den Angaben aus dem Dialog gefüllt; die übrigen sechs sind noch leer.

Das ist kein Papierkram, sondern die Grundlage der nächsten Schritte: brand.md entscheidet über die Design Tokens, content-plan.md über die Seiten, forms-plan.md über die Felder. Wer hier schludert, rät später.

Offenes bleibt offen. Jede Datei hat einen Abschnitt „Offen" — dort gehört hinein, was noch niemand beantwortet hat. Eine plausible Erfindung wird beim nächsten Lesen für eine abgestimmte Antwort gehalten.

Der Skill project-brief füllt die Dateien aus Gesprächsnotizen, einer Mail oder einem Bestandsaudit — und schreibt dabei ausschließlich unter project/, nie Code.

4. Marke und Design Tokens

Jetzt bekommt das Projekt sein Aussehen. Alle Werte — Farben, Schriften, Abstände, Radien — stehen an einer Stelle: src/styles/theme.css.

--color-brand-600: oklch(0.54 0.17 254); /* Standardfläche */
--color-brand-700: oklch(0.46 0.15 254); /* Hover */

Die Namen bleiben, nur die Werte werden getauscht. Das ist der Punkt: Komponenten benutzen bg-brand-600 und wissen nichts von der konkreten Farbe. Ein Rebranding ist dadurch eine Änderung an dieser Datei statt an achtzig anderen.

Zwei Bedingungen gelten unabhängig vom Geschmack: brand-600 und brand-700 müssen gegen Weiß lesbar bleiben (Kontrast 4,5:1), und Farbe allein darf nie eine Information tragen.

Danach /styleguide im Browser durchgehen — dort steht jedes Bedienelement in allen Zuständen. Was dort gut aussieht, sieht überall gut aus.

Mehr dazu: Design Tokens. Der Skill design-foundation führt den Schritt komplett durch.

5. Bilder aufnehmen

Bilder liegen unter src/assets/ und werden über einen Schlüssel angesprochen, nicht über einen Dateipfad. Der Schlüssel und alles, was zum Bild gehört, stehen in src/content/assets.yaml:

leistungen-hero:
  file: ../assets/leistungen-hero-werkstatt.jpg
  alt: Zwei Personen an einer Werkbank, im Vordergrund ein aufgeklapptes Notebook.
  altApproved: false
  preset: hero

alt ist der Text für Menschen, die das Bild nicht sehen — Pflicht, ein fehlender bricht den Build ab. altApproved: false heißt „vorgeschlagen, noch nicht von einem Menschen geprüft"; auf true setzt es niemand nebenbei. preset ist eines von hero, card, logo, og.

Der Vorteil dieser Umständlichkeit: Dasselbe Bild trägt beim zweiten Einbinden denselben Alt-Text, statt einen neu erfundenen. Details unter Assets, automatisiert vom Skill import-assets.

6. Die erste echte Seite

Eine Datei unter src/pages/ wird zu einer Route: src/pages/leistungen.astro wird /leistungen. Mehr Konfiguration gibt es nicht.

---
import BaseLayout from '../layouts/BaseLayout.astro';
import Prose from '../components/ui/Prose.astro';
import Section from '../components/ui/Section.astro';
---

<BaseLayout
  title="Leistungen"
  description="Was wir anbieten und für wen."
  breadcrumbs={[{ label: 'Startseite', href: '/' }, { label: 'Leistungen' }]}
>
  <Section width="content">
    <h1 class="text-title">Leistungen</h1>

    <Prose class="mt-8">
      <p>Hier steht der Fließtext dieser Seite.</p>
    </Prose>
  </Section>
</BaseLayout>

Drei Dinge daran sind wichtig:

• title und description sind Props, keine Meta-Tags. Titel, Canonical, Open Graph und die strukturierten Daten entstehen daraus von selbst. Eine Seite schreibt nie selbst in den Dokumentkopf.
• Section und Prose sind vorhandene Bausteine. Alle liegen unter src/components/ui/ und sind im Styleguide zu sehen. Ein neuer Baustein entsteht erst, wenn wirklich keiner passt — und wandert dann in den Styleguide.
• breadcrumbs erzeugt beides: die sichtbare Brotkrumenleiste und ihre Auszeichnung für Suchmaschinen, aus derselben Liste.

Ansehen mit dem Entwicklungsserver, der bei jeder Speicherung neu lädt:

pnpm dev

Soll die Seite ins Menü, kommt ein Eintrag in navigation.main in project.config.ts — nicht in eine Navigationskomponente.

Ein Bild bindest du mit dem Schlüssel aus Schritt 5 ein. Genau ein Bild je Seite bekommt priority, nämlich das oberste:

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

Mehr dazu unter Layout und Komponenten, automatisiert vom Skill create-page.

7. Review

pnpm verify

Grün heißt: Formatierung, Typen, Tests, alle Builds und die Barrierefreiheitsprüfung stimmen. Rot heißt, dass etwas zu tun ist — die Meldung nennt die Datei.

Für den fachlichen Blick gibt es vier Review-Agents, die lesen und berichten, aber nichts ändern: Designsystem, SEO und Tracking, Barrierefreiheit und Performance, Formulare und Handler-Sicherheit. Was sie prüfen, steht unter Claude Code.

Dann committen — auf Deutsch und im Conventional-Commits-Format, weil daraus Changelog und Versionsnummer entstehen:

git add -A
git commit -m "feat: Leistungsseite"

Wenn etwas nicht funktioniert

Meldung	Meistens
Unknown asset key	Tippfehler im Schlüssel oder Eintrag in assets.yaml vergessen
Build bricht bei einem Bild ab	alt fehlt im Manifest
project.config.ts wird bemängelt	Widersprüchliche Kombination — die Meldung nennt Feld und Grund
Farbe ändert sich nicht	Wert direkt in der Komponente statt als Token in theme.css
Klasse wirkt nicht	Klassenname zusammengesetzt (bg-brand-${n}) — er muss vollständig sein
pnpm verify rot, lokal aber alles gut	Formatierung: pnpm format ausführen

Mehr Fälle unter Troubleshooting.

Wie es weitergeht

Der erste Tag endet hier. Was danach kommt, hängt vom Projekt ab:

• Formulare — Felder, Backend, Spamschutz: Formulare
• Tracking und Einwilligung — nur wenn das Projekt es wirklich braucht: Tracking & Consent
• Suchmaschinen — Titel, strukturierte Daten, Indexierung: SEO
• Livegang — Zielsystem, Serverregeln, Header: Deployment

Und einmal in Ruhe: die Regeln des Repositorys. Sie erklären, warum an den Stellen, an denen dieser Starter umständlich wirkt, genau das der Zweck ist.