Astro-Entwickler in Basel

#Vom fertigen Layout zur Komponentenliste

Sie haben ein Layout, vielleicht von einer Agentur in Basel, vielleicht aus Ihrem eigenen Haus: Startseite, Leistungsübersicht, Detailseite, Kontakt. Daraus soll eine Website werden, die Ihr Team später selbst erweitern kann. Genau dafür sind Astro-Komponenten gedacht. Ich bin Mariusz Szatkowski, ein einzelner Entwickler in Gdynia, und arbeite remote und schriftlich. Grafik, Mockups und Wireframes gehören nicht zu meinem Angebot: Das Layout kommt von Ihnen, ich setze es um.

Der Kanton Basel-Stadt beschreibt auf seinem Wirtschaftsportal auch eine regionale ICT-Landschaft, zu der neben Softwareunternehmen die sogenannten Creative Technologies gehören, die Computer, Design, Kunst und Geisteswissenschaften verbinden. Wer in so einem Umfeld eine Website baut, bekommt Entwürfe, die genau sind, und erwartet im Code dieselbe Genauigkeit. Auf dieser Seite steht, wie ich ein Layout in Komponenten zerlege. Sie behandelt nur diese Frage. Islands, Content Collections oder Formulare stehen auf den Seiten anderer Städte, die ich weiter unten verlinke.

Foto: Ermell, CC BY-SA 4.0, Wikimedia Commons.

#Was Sie mir für den Start liefern

• Das Layout je Ansicht, in Desktop und Mobil: als Figma-Export, PDF oder als Tabelle, in der Sie markieren, welche Elemente wohin gehören.
• Die Design-Entscheidungen als Werte: Farben, Schriften, Schriftgrössen, Abstände, Eckenradien. Fehlen sie, lese ich sie aus dem Layout aus und lege sie Ihnen zur Bestätigung vor.
• Texte und Bilder in der Sprache, in der die Seite erscheint. Sind es mehrere Sprachen, zeigt die Seite zu Astro in Zürich, wie ich das trenne.
• Zugänge zu Domain, DNS und Hosting, sobald es um das Deployment geht.

Ich schicke Ihnen danach eine Komponentenliste mit den offenen Fragen. Antworten Sie schriftlich, wann es Ihnen passt.

#Komponenten: Skript, Vorlage, Props

Laut Astro-Dokumentation sind Astro-Komponenten reine HTML-Vorlagen mit der Endung .astro und ohne Client-Laufzeit. Sie werden zur Build-Zeit oder auf Anfrage zu HTML gerendert. JavaScript im Komponentenskript, also zwischen den beiden ---, landet nicht im Browser. Für ein Layout heisst das: Ein Header, eine Karte oder ein Footer kostet im Browser kein JavaScript, solange Sie keine Interaktion dazubestellen.

Mein Zuschnitt folgt dem Layout, nicht einer Schablone:

• Was auf mehreren Ansichten gleich aussieht, wird eine Komponente: Button, Karte, Abschnittskopf, Kontaktblock.
• Was nur einmal vorkommt, bleibt in der Seite. Eine Komponente für ein einziges Element ist Ballast.
• Was sich nur im Inhalt unterscheidet, bekommt Props. Was sich im Aufbau unterscheidet, bekommt Slots.

Props lese ich aus Astro.props und beschreibe sie mit einem Props-Interface. Die Dokumentation zeigt, dass Astro das Interface erkennt und bei falschen Werten Warnungen oder Fehler meldet. Standardwerte setze ich beim Destrukturieren.

---
interface Props {
  title: string;
  level?: 2 | 3;
}
const { title, level = 2 } = Astro.props;
const Heading = `h${level}`;
---
<section class="teaser">
  <Heading>{title}</Heading>
  <slot />
</section>

Die Überschriftenebene als Prop ist keine Spielerei. Ein Layout fixiert das Aussehen einer Überschrift, aber nicht ihren Rang im Dokument. Der Rang ergibt sich aus der Stelle auf der Seite, und die Komponente muss ihn von aussen bekommen.

#Slots: wenn sich der Aufbau unterscheidet

Ein <slot /> ist laut Dokumentation der Platzhalter für HTML, das eine andere Datei in die Komponente schiebt. Benannte Slots nehmen nur Elemente mit dem passenden slot-Attribut auf, alles andere landet im Standard-Slot. Zwei Regeln aus der Dokumentation, die im Alltag helfen:

• Benannte Slots müssen direkte Kinder der Komponente sein. Sie lassen sich nicht durch verschachtelte Elemente durchreichen.
• Fallback-Inhalt erscheint nur, wenn kein passendes Element übergeben wird. Wird ein leerer Slot übergeben, bleibt er leer.

Ein Beispiel aus einem typischen Layout: Eine Teaserkarte hat einen Titel, einen Text und manchmal ein Bild oder einen Link. Das Bild wird zum benannten Slot, der Link auch. Fehlt der Slot, soll keine leere Fläche entstehen. Deshalb gebe ich das umgebende Element nur aus, wenn Inhalt übergeben wurde. Für Tabellenkörper oder Listen ohne zusätzliches Wrapper-Element nutzt die Dokumentation <Fragment slot="...">.

#Scoped Styles oder Tailwind

Astro bietet beides, und die Dokumentation beschreibt beides sauber. Die Entscheidung hängt an Ihrem Layout, nicht an Vorlieben.

Scoped Styles werden laut Dokumentation mit einem data-astro-cid-*-Attribut ausgespielt. Das hat Folgen: Stile einer Komponente wirken nicht auf eingebettete Kindkomponenten. Wer ein Kind stylen will, wickelt es in ein Element, das er selbst gestaltet. Eine class reicht Astro nicht automatisch an eine Kindkomponente durch. Die Dokumentation zeigt den Weg: class als className entgegennehmen und mit ...rest weitergeben. Globale Regeln stehen in is:global oder in :global(), etwa für Inhalte aus einem CMS, die Astro nicht selbst rendert. Die Dokumentation rät, globale Stile nur dort zu nutzen, wo es nötig ist.

Tailwind 4 kommt über das Vite-Plugin. In der Dokumentation heisst es: npx astro add tailwind, danach @import "tailwindcss" in einer globalen CSS-Datei, die das Layout einbindet. Mischen ist erlaubt. Sinnvoll ist oft eine Aufteilung: Das Raster steht mit Tailwind-Klassen, die wenigen Komponenten mit eigener Optik bekommen Scoped Styles. Dann steht in der Dokumentation Ihres Projekts, welche Regel wo gilt.

#Design-Tokens als CSS-Variablen

Ein Layout besteht aus Entscheidungen: ein Blau, eine Schrift, eine Abstandsreihe. Wer sie in zwanzig Komponenten ausschreibt, ändert sie später zwanzigmal. MDN beschreibt Custom Properties genau dafür: Ein Wert wird an einer Stelle definiert und an vielen referenziert, üblicherweise auf :root. Der Zugriff läuft über var(), mit einem optionalen Fallback als zweitem Argument.

:root {
  --farbe-akzent: #0b5ea8;
  --abstand-block: 2rem;
}
.teaser {
  padding-block: var(--abstand-block);
  border-color: var(--farbe-akzent);
}

Die Werte stehen hier als Beispiel, Ihre kommen aus Ihrem Layout. Zwei Grenzen nennt MDN: Variablen funktionieren nicht in Media Queries und Container Queries, und sie lassen sich nicht für Eigenschaftsnamen oder Selektoren verwenden. Breakpoints stehen deshalb als feste Werte im CSS oder, mit Tailwind, in der Theme-Konfiguration.

Mit Tailwind 4 haben die Tokens ein eigenes Zuhause: Laut Tailwind-Dokumentation sind Theme-Variablen CSS-Variablen aus der @theme-Direktive, die zusätzlich Utility-Klassen erzeugen. Aus --color-mint-500 werden bg-mint-500 und text-mint-500, und die normale CSS-Variable steht ebenfalls bereit. Variablen, die keine Klasse bekommen sollen, gehören weiter auf :root. Ich lege fest, welche Tokens zu welchem Namensraum gehören, und gebe Ihnen die Liste in der Dokumentation des Projekts.

Aus dem Astro-Komponentenskript lassen sich Werte mit define:vars an das CSS einer Komponente geben. Das ist bequem für einzelne Werte, aber kein Ersatz für ein zentrales Token-Set.

#Responsive Bilder in Komponenten

Bilder aus src/ laufen durch die Komponenten <Image /> und <Picture /> aus astro:assets. Laut Astro-Dokumentation gilt für <Image />:

• alt ist Pflicht. Ein leerer Wert (alt="") markiert ein rein dekoratives Bild.
• Breite und Höhe werden aus der Datei abgeleitet, um Cumulative Layout Shift zu vermeiden.
• Das Ergebnis trägt loading und decoding, das Bild wird zur Build-Zeit transformiert.
• <Picture /> erzeugt mehrere Formate, etwa AVIF und WebP, mit einem Fallback.

Seit Astro 5.10 gibt es die Eigenschaft layout: Mit constrained, full-width oder fixed erzeugt Astro srcset und sizes selbst. constrained wächst nicht über die angegebene Grösse hinaus, full-width füllt die Containerbreite, fixed bleibt bei der gegebenen Grösse. Für ein Bild im oberen Seitenbereich gibt es priority, das loading="eager" und fetchpriority="high" setzt. Die Faustregel der Dokumentation: Bilder im Ordner public/ werden nie optimiert, responsive Layouts sind für sie nicht möglich. Bilder gehören deshalb nach src/.

In einer Komponente heisst das: Ich baue eine Teaser-Komponente, deren Bild-Slot eine <Image /> aufnimmt, mit alt als Pflicht-Prop. Eine Falle nennt die Dokumentation selbst: Astro-Bildkomponenten laufen nicht innerhalb von React- oder Vue-Komponenten. Man reicht das fertige Bild aus der .astro-Datei als Kind oder per Slot hinein. Wo Sie Interaktion brauchen, erkläre ich auf der Seite zu Islands in Wiesbaden, warum ich sie nur dort einsetze.

Die Core Web Vitals prüfe ich an den offiziellen Schwellen von web.dev: LCP bis 2,5 s, INP bis 200 ms und CLS bis 0,1 im 75. Perzentil (web.dev).

#Zugänglichkeit gehört in die Komponente

Barrierefreiheit entsteht nicht am Ende, sie entsteht beim Zuschnitt. Was ich in jeder Komponente prüfe:

• Das richtige Element: button für Aktionen, a für Ziele, nav, main und footer für Bereiche. Ein div mit Klick-Handler ist keine Schaltfläche.
• Die Überschriftenebene kommt als Prop, damit die Reihenfolge im Dokument stimmt.
• Jedes Bild hat einen alt-Text, der zum Inhalt passt, oder ein bewusst leeres Attribut.
• Der Fokus bleibt sichtbar. Eine Tastaturbedienung ohne sichtbaren Fokus ist unbenutzbar, auch wenn der Entwurf ihn nicht zeigt. Fehlt er im Layout, frage ich bei Ihnen nach.
• Kontraste und Schriftgrössen kommen aus den Tokens, nicht aus Einzelwerten.

Astro bringt in der Dev Toolbar eine Audit-App mit, die laufend Performance- und Zugänglichkeitsprobleme der aktuellen Seite markiert. Die Dokumentation sagt selbst, dass sie Werkzeuge wie Pa11y oder Lighthouse nicht ersetzt, und erst recht keine Menschen. Ich nutze sie als erste Stufe und prüfe danach von Hand mit der Tastatur.

#Datenschutz bei Einbettungen: eine Komponente, ein Anbieter

Karten, Videos und Terminbuchungen laden Inhalte von Dritten. In einer Komponentenstruktur bekommt jede dieser Einbettungen eine eigene Komponente, damit Sie an einer Stelle sehen, welche Anbieter angesprochen werden. Das erleichtert die Datenschutzerklärung. Nach Art. 19 des Schweizer Datenschutzgesetzes (Fassung vom 1. September 2023 auf Fedlex) informiert der Verantwortliche die betroffene Person angemessen über die Beschaffung von Personendaten, mindestens über Identität, Zweck und gegebenenfalls die Empfänger. Gehen Daten ins Ausland, nennt er auch den Staat. Die Aufsicht liegt beim Eidgenössischen Datenschutz- und Öffentlichkeitsbeauftragten (EDÖB). Den Text der Erklärung schreibt Ihre Rechtsberatung, ich liefere die technische Liste der Anbieter.

#Wo Komponenten auf andere Themen stossen

Eine Komponentenstruktur ist die Grundlage, nicht das ganze Projekt. Wo die Inhalte herkommen und wie die Seiten wechseln, klären andere Seiten:

• Texte und Daten als Content Collections: Astro in Stuttgart.
• Formulare und Server Actions: Astro in Wuppertal.
• Technische Dokumentation mit Starlight: Astro in Mannheim.
• Seitenübergänge: Astro in Münster.
• Inhalte aus einem CMS laden: Astro in Nürnberg und Astro mit WordPress als Headless-CMS in Wien.
• Mehrsprachigkeit mit hreflang und Sprachpfaden: Astro in Zürich und Migration von Next.js zu Astro in Basel.

#Der Ablauf Schritt für Schritt

1. Sie schicken mir Layout, Werte und die URL der Seite, falls es schon eine gibt.
2. Ich schreibe die Komponentenliste mit Props und Slots und stelle offene Fragen.
3. Sie bestätigen oder korrigieren. Danach steht der Umfang mit Annahmen schriftlich.
4. Ich baue auf einer Testumgebung. Sie nehmen Ansicht für Ansicht ab, schriftlich.
5. Zur Übergabe bekommen Sie das Repository mit einer Datei, die Komponenten, Props, Tokens und Namensregeln erklärt.
6. Auf Wunsch betreue ich die Seite danach weiter. Das ist ein eigener, schriftlicher Auftrag.

#Checkliste: Ist Ihr Layout bereit für die Umsetzung?

• Gibt es zu jeder Ansicht eine Mobil- und eine Desktopfassung?
• Sind Farben, Schriften und Abstände als Werte angegeben, nicht nur als Bild?
• Ist erkennbar, welche Elemente sich wiederholen?
• Ist festgelegt, wie ein Element aussieht, wenn Inhalt fehlt (kein Bild, kein Link, langer Titel)?
• Gibt es einen Fokus- und einen Hover-Zustand für Links und Schaltflächen?
• Steht fest, welche Bilder dekorativ sind und welche Inhalt tragen?
• Ist klar, welche Einbettungen (Karte, Video) vorkommen?

Fehlt ein Punkt, ist das normal. Ich notiere die Lücken in der Komponentenliste und frage nach.

#Häufige Fragen

#Muss ich Ihnen ein fertiges Layout liefern?

Ja. Layout, Grafik und Wireframes kommen von Ihnen oder Ihrer Agentur, ich gestalte nichts. Ein Figma-Export, ein PDF oder eine Tabelle, in der Sie je Ansicht markieren, welche Elemente wohin gehören, reicht. Daraus mache ich die Komponentenliste.

#Scoped Styles oder Tailwind, was nehmen Sie?

Beides ist möglich. Tailwind passt, wenn Ihr Layout aus einem klaren Raster mit wiederkehrenden Abständen besteht. Scoped Styles passen für Komponenten mit eigener Logik im Aufbau. Ich lege das pro Projekt fest und schreibe es in den Umfang.

#Kann mein Team später selbst Komponenten ergänzen?

Ja. Komponenten, Props und Tokens sind in einer Datei erklärt und im Repository dokumentiert. Das Repository übergebe ich an Ihr Konto. Eine neue Komponente nach demselben Muster ist danach Routine.

#Wie gehen Sie mit Bildern aus dem Layout um?

Bilder, die im Projekt liegen, laufen durch die Image- oder Picture-Komponente von Astro: Breite und Höhe sind gesetzt, ein alt-Text ist Pflicht. Ob ein Bild dekorativ ist oder Inhalt trägt, klären Sie und ich schriftlich, bevor ich den Text eintrage.

#Was ist mit dem Datenschutz, wenn Komponenten Karten oder Videos einbetten?

Eine eingebettete Karte oder ein Video lädt Inhalte von einem Dritten. Ich baue solche Einbettungen als eigene Komponente, sodass Sie an einer Stelle sehen, welcher Anbieter angesprochen wird. Die Datenschutzerklärung nach Art. 19 des Schweizer Datenschutzgesetzes schreibt Ihre Rechtsberatung.

#Wie läuft die Zusammenarbeit, wenn Sie in Gdynia sitzen und ich in Basel?

Ausschliesslich schriftlich: Briefing, Rückfragen, Umfang mit Annahmen, Testumgebung zur Abnahme. Die Abstimmung läuft über Text, nicht über Telefon oder Video. Zum Umfang bekommen Sie zuerst eine schriftliche Einschätzung, ohne Berechnung.

#Schreiben Sie mir

Schicken Sie mir über das Kontaktformular die URL Ihrer Website, Ihr Ziel, Ihren Termin und den aktuellen Stack, dazu das Layout oder einen Link darauf. Ich sehe mir das Layout an, stelle Rückfragen schriftlich und antworte mit einer ersten Einschätzung zu Umfang und Annahmen, kostenlos. Falls Astro für Ihr Vorhaben die falsche Wahl ist, steht das in meiner Antwort, mit einer Alternative.