Eine Komponente braucht einen Vertrag, nicht nur eine Vorschau

Die Vorschau kann stimmen und trotzdem lügen

Ein Komponenten-Explorer vermittelt schnell ein beruhigendes Bild: Buttons, Karten und Navigationen stehen ordentlich nebeneinander, Varianten lassen sich auswählen und responsive Breiten ausprobieren. Trotzdem kann die eigentliche TYPO3-Seite anders aussehen. Vielleicht verwendet der Styleguide nachgebautes HTML, veraltete Beispieldaten oder eine eigene Rendering-Umgebung. Vielleicht existiert eine Variante nur in der Dokumentation, während das produktive Template längst andere Argumente erwartet.

Dann ist die Vorschau keine verlässliche Beschreibung des Systems, sondern eine zweite Implementierung. Je attraktiver sie aussieht, desto leichter wird dieser Unterschied übersehen.

Ein belastbarer Living Styleguide sollte deshalb nicht fragen: „Wie können wir die Komponente möglichst ähnlich darstellen?“ Die bessere Frage lautet: „Welchen Vertrag können Vorschau, TYPO3-Laufzeit, Tests und externe Werkzeuge gemeinsam verwenden?“

Dieser Vertrag besteht aus mehr als HTML. Er umfasst die öffentliche Komponenten-API, kontrollierte Beispieldaten, Renderingbedingungen, Zustände und ein versionierbares Exportformat.

Das Fluid-Template ist die ausführbare Quelle

Der naheliegende Schutz gegen Abweichungen besteht darin, dass Vorschau und Anwendung dasselbe Template rendern. Für Fluid-Komponenten ist das inzwischen besonders gut greifbar: Komponenten definieren ihre Eingaben mit <f:argument> und nehmen verschachtelte Inhalte über <f:slot> entgegen. Die TYPO3-Dokumentation beschreibt diese Argumente als typisierte API und empfiehlt seit TYPO3 14 konfigurationsbasierte Component Collections gegenüber der früheren klassenbasierten Registrierung. (Fluid in TYPO3 14.3)

Eine kleine Komponente könnte so beginnen:

<f:argument name="title" type="string" />
<f:argument name="variant" type="string" optional="{true}" default="default" />
<f:argument name="url" type="string" optional="{true}" />

<article class="card card--{variant}">
    <h2>{title}</h2>
    <f:slot />
</article>

Schon diese wenigen Zeilen enthalten mehr Architektur als eine isolierte HTML-Demo:

• title ist erforderlich und als String vereinbart.
• variant ist optional und besitzt einen definierten Standardwert.
• url gehört zur öffentlichen API, auch wenn seine konkrete Verarbeitung noch geprüft werden muss.
• Der Standard-Slot erlaubt Inhalt, ohne dessen Struktur vollständig vorzuschreiben.

Der Styleguide sollte diese Deklarationen lesen und daraus seine Bedienelemente sowie Validierung ableiten. Eine zusätzlich gepflegte Liste von Props wäre nur eine weitere mögliche Abweichungsquelle.

Das bedeutet nicht, dass jede fachliche Regel direkt aus dem Template extrahiert werden kann. Ein String-Typ sagt beispielsweise noch nicht, welche Varianten erlaubt sind oder ob eine URL intern bleiben muss. Solche Einschränkungen benötigen ergänzende Metadaten oder Tests. Entscheidend ist, dass es für dieselbe Information nicht mehrere gleichberechtigte Wahrheiten gibt.

Strenge Eingaben machen Änderungen sichtbar

Komponenten sind besonders wartbar, wenn unbekannte Argumente nicht still akzeptiert werden. Ein Tippfehler wie varaint="compact" sollte nicht zu einer scheinbar normalen Standardkarte führen. Er sollte beim Rendern, in der Analyse oder spätestens in der Pipeline auffallen.

TYPO3 erlaubt bei der Registrierung einer Component Collection ausdrücklich zu konfigurieren, ob zusätzliche Argumente zulässig sind. Für öffentliche, wiederverwendbare Komponenten ist ein geschlossener Vertrag meist die sicherere Voreinstellung. Offenheit kann sinnvoll sein, etwa für bewusst durchgereichte HTML-Attribute; sie sollte jedoch eine dokumentierte Entscheidung sein und nicht aus Bequemlichkeit entstehen.

Auch eine Änderung der API braucht eine erkennbare Bedeutung:

neues optionales Argument       → in der Regel kompatibel
neue Variante                   → kompatibel, aber visuell zu prüfen
geänderter Standardwert         → potenziell brechende Darstellung
umbenanntes Pflichtargument     → brechende Änderung
entfernter Slot                 → brechende Strukturänderung
geänderte HTML-Semantik         → möglicherweise brechend für CSS, JS und Barrierefreiheit

Semantische Versionierung allein löst diese Fragen nicht. Sie zwingt aber dazu, Änderungen als Vertrag und nicht nur als Template-Diff zu betrachten.

Slots sind kontrollierte Erweiterungspunkte

Slots lösen ein echtes Wiederverwendungsproblem: Nicht jeder Inhalt lässt sich sinnvoll auf einfache Argumente reduzieren. Ein Teaser kann Text, Medien oder eine Aktionsgruppe aufnehmen, ohne dass die Komponente alle möglichen Kindstrukturen kennen muss.

Diese Flexibilität hat eine Grenze. Ein Slot ist kein Freibrief für beliebige Abhängigkeiten vom äußeren Renderingkontext. Fluid-Komponenten arbeiten mit einem eigenen Kontext; ViewHelper, die einen Eltern-ViewHelper suchen, können deshalb an Komponentengrenzen scheitern. Die aktuelle TYPO3-Referenz nennt Formularfelder als konkretes Beispiel und empfiehlt, das eigentliche Feld über einen Slot in eine darstellende Komponente zu geben. (TYPO3 Form ViewHelper 14.3)

Das ist eine hilfreiche architektonische Trennung:

• Die Komponente verantwortet Beschriftung, Abstand, Fehlerdarstellung und Layout.
• Der Aufrufer verantwortet das zustandsgebundene Formularfeld.
• Der Slot verbindet beide, ohne den Formularvertrag vorzutäuschen.

Benannte Slots sollten wie Argumente dokumentiert werden. Für jeden Slot braucht es mindestens einen Zweck, einen erwarteten Inhalt und ein Verhalten bei fehlender Belegung. Andernfalls wird die sichtbare Flexibilität später durch implizite CSS- und JavaScript-Annahmen eingeschränkt.

Varianten sind Beispiele, keine parallelen Templates

Eine Variante sollte einen relevanten Zustand demonstrieren, nicht die Komponente kopieren. Typische Varianten zeigen:

• kurze und sehr lange Inhalte,
• fehlende optionale Medien,
• unterschiedliche Sprachen,
• leere oder maximale Listen,
• Fokus-, Fehler- und deaktivierte Zustände,
• schmale und breite Container,
• helle und dunkle Farbschemata.

Für jede Variante braucht es reproduzierbaren Kontext. Dieser Kontext sollte klein, verständlich und frei von produktiven Daten sein. Ein vollständiger Datenbankexport macht eine Vorschau weder portabel noch gut prüfbar.

Sinnvoll ist ein deklaratives Modell, das nur die öffentliche API bedient:

{
  "component": "Molecule.TeaserCard",
  "variant": "long-title-without-image",
  "arguments": {
    "title": "Eine bewusst lange Überschrift für einen schmalen Container",
    "variant": "highlighted"
  },
  "slots": {
    "default": "<p>Kontrollierter Beispielinhalt.</p>"
  },
  "viewport": {
    "width": 360,
    "height": 640
  }
}

Dabei muss klar bleiben, welche Slot-Inhalte als vertrauenswürdig gelten und wie sie bereinigt werden. Ein Styleguide darf nicht dadurch zur HTML-Ausführungsoberfläche werden, dass editierbarer Beispielinhalt ungefiltert in die Vorschau gelangt.

Eine Vorschau benötigt definierte Laufzeitbedingungen

Dasselbe Template reicht noch nicht aus, wenn Umgebung und Abhängigkeiten unterschiedlich bleiben. Schriftdateien, CSS, JavaScript, Übersetzungen, Asset-Pfade und ViewHelper beeinflussen das Ergebnis ebenso wie die Argumente.

Deshalb sollte jede Vorschau ihren Laufzeitvertrag sichtbar machen:

1. Welche Fluid- und TYPO3-Version wird verwendet?
2. Welche Component Collections und Namespaces sind registriert?
3. Welche Stylesheets und Skripte werden geladen?
4. Welche Sprache, Locale und Schreibrichtung gelten?
5. Welche Basis-URL wird für Assets verwendet?
6. Welche globalen Variablen stehen zur Verfügung?
7. Welche Abhängigkeiten werden bewusst nicht unterstützt?

Eine eigenständige Fluid-Laufzeit ist wertvoll, weil sie Komponenten schnell und ohne vollständiges CMS rendern kann. Sie beweist jedoch nur den unabhängigen Kern. Eine TYPO3-Fixture bleibt notwendig, wenn Integration, Namespaces, Asset-Auflösung oder Backend- und Frontendrouten Teil des Versprechens sind.

Die Testpyramide für einen Styleguide sollte daher nicht aus einem einzigen Screenshottest bestehen. Parser- und Renderingtests können den Kern schnell prüfen. Integrationstests belegen die Registrierung in TYPO3. Browsertests untersuchen Interaktion, Tastaturbedienung, responsive Vorschauen und reale Assets.

Screenshots sind Belege, aber kein Vertrag

Visuelle Regressionstests sind nützlich, wenn sie gezielt eingesetzt werden. Sie erkennen verschobene Abstände, abgeschnittene Inhalte und unbeabsichtigte Farbänderungen. Ein Screenshot erklärt jedoch nicht, warum eine Änderung erlaubt oder falsch ist. Er kann außerdem durch Schrift-Rendering, Betriebssystem und Browserumgebung instabil werden.

Deshalb sollten visuelle Vergleiche auf benannten Varianten und kontrollierten Laufzeitbedingungen beruhen. Für jede Abweichung braucht es eine fachliche Prüfung, nicht nur das pauschale Aktualisieren aller Referenzbilder.

Zusätzlich zu Screenshots sollten strukturelle Tests beantworten:

• Rendert die Komponente mit allen Pflichtargumenten?
• Werden unbekannte Argumente abgewiesen?
• Bleibt die Überschriften- und Landmark-Struktur korrekt?
• Ist die Variante per Tastatur bedienbar?
• Werden unsichere Links oder Dokumentationsinhalte verworfen?
• Existiert jede dokumentierte Variante tatsächlich?
• Sind exportierte Dateien über das Manifest erreichbar?

Der Screenshot zeigt eine konkrete Darstellung. Der strukturierte Vertrag erklärt, welches Verhalten erhalten bleiben muss.

Ein Export ist eine öffentliche Schnittstelle

Sobald Komponenten den Styleguide verlassen, reicht eine Sammlung gespeicherter HTML-Dateien nicht mehr. Andere Werkzeuge müssen wissen, welche Datei zu welcher Komponente gehört, mit welchem Kontext sie erzeugt wurde und welche Version des Formats vorliegt.

Ein portabler Export kann deshalb mehrere Artefakte verbinden:

manifest.json
components/
  molecule-teaser-card/
    default.html
    default.preview.json
    TeaserCard.fluid.html
    README.md
schema/
  manifest.schema.json
  preview.schema.json

Das Manifest bildet den Einstiegspunkt. Es enthält stabile Identifikatoren, Varianten, relative Pfade, Formatversion und gegebenenfalls Prüfsummen. Pfade müssen normalisiert und gegen Traversal abgesichert werden. Ein Importeur darf einen Eintrag wie ../../outside.html nie außerhalb des Exportverzeichnisses auflösen.

JSON Schema eignet sich dafür, Struktur, Pflichtfelder und zulässige Werte maschinenlesbar zu beschreiben. Die offizielle Spezifikationsseite führt Draft 2020-12 weiterhin als aktuelle Version; das Schema kann sowohl Exporte in der Pipeline prüfen als auch Konsumenten bei der Implementierung unterstützen. (JSON Schema Specification)

Wichtig ist die Richtung der Abhängigkeit: Das Schema beschreibt den Exportvertrag. Es sollte nicht interne PHP-Klassen oder zufällige Dateisystemdetails offenlegen. Sonst wird aus einem portablen Format ein Abbild der momentanen Implementierung.

Kompatibilität gehört in die Pipeline

Eine Pipeline kann den Komponentenvertrag in mehreren Schritten prüfen:

1. Alle Templates werden entdeckt und eindeutig benannt.
2. Argument- und Slot-Deklarationen lassen sich lesen.
3. Jede Variante referenziert eine existierende Komponente.
4. Varianten liefern alle erforderlichen Argumente und keine unbekannten Eingaben.
5. Die Komponenten rendern in der unabhängigen Laufzeit.
6. Eine reale TYPO3-Fixture prüft die Integration.
7. Struktur-, Barrierefreiheits- und ausgewählte visuelle Tests laufen im Browser.
8. Der statische Export wird erzeugt und gegen seine Schemas validiert.
9. Alle Manifestpfade werden in einem frischen Verzeichnis erneut aufgelöst.

Aktuelle TYPO3-Versionen unterstützen diesen Gedanken auch auf Entwicklungsebene: Seit TYPO3 14.2 kann fluid:schema:generate XSD-Dateien für verfügbare Fluid-Komponenten erzeugen und damit Autovervollständigung in unterstützenden IDEs ermöglichen. Voraussetzung ist, dass die Collection ihre Komponenten aufzählen kann; die TYPO3-eigene Integration unterstützt das direkt. (TYPO3 Feature #109114)

Damit wird die explizite Komponenten-API nicht erst im Styleguide nützlich. Sie verbessert bereits den Moment, in dem eine Komponente in einem Fluid-Template verwendet wird.

TYPO3 Fractal als konkrete Ausprägung

Nach den bereitgestellten Projektinformationen verfolgt TYPO3 Fractal genau diese Trennung zwischen Kern und Integration. Der unabhängige PHP-Kern verwendet typo3fluid/fluid, während Adapter die Einbindung in TYPO3 13 und 14 übernehmen. Eine DDEV-Fixture prüft die generierten Dateien über echte TYPO3-Routen und im Browser.

Der Runtime-Scanner entdeckt .fluid.html-Templates. <f:argument>- und <f:slot>-Deklarationen werden zu editierbaren Kontrollen, Varianten folgen einer Namenskonvention. Die Vorschau läuft in einem Sandbox-Iframe. Ergänzende Markdown-Dokumentation wird laut Projektbeschreibung konservativ verarbeitet; unsichere URLs und beliebiges HTML werden nicht übernommen.

Auch der Export ist dort als Vertrag angelegt: browserfähiges HTML, Preview-JSON, Fluid-Quelltemplate und optionale Dokumentation werden durch manifest.json verbunden. Eine JSON-Schema-Datei erlaubt Konsumenten die Validierung, relative Pfade werden gegen Traversal geschützt.

Das sind Eigenschaften des beschriebenen Projekts. Daraus folgt nicht, dass jede TYPO3-Installation genau dieses Format oder Werkzeug benötigt. Die allgemeine Lehre ist kleiner: Wenn eine Komponentenbibliothek mehrere Laufzeiten und Konsumenten bedienen soll, braucht sie eine explizite, prüfbare Grenze.

Die entscheidenden Fragen vor der Freigabe

Vor der Veröffentlichung oder Änderung einer Komponente sollten einige Fragen eindeutig beantwortet sein:

• Rendert die Vorschau das echte Fluid-Template?
• Sind Pflichtargumente, optionale Argumente und Standardwerte explizit?
• Werden unbekannte Eingaben abgewiesen oder bewusst zugelassen?
• Sind Slots dokumentierte Erweiterungspunkte statt versteckter Kontextabhängigkeiten?
• Besitzt jede Variante einen kleinen, reproduzierbaren Beispieldatensatz?
• Werden Sprache, Assets, Theme und Viewport kontrolliert?
• Gibt es neben dem Standalone-Test eine echte TYPO3-Integration?
• Prüfen Tests Struktur und Verhalten, nicht nur Pixel?
• Ist ein statischer Export versioniert und schema-validierbar?
• Können alle Manifestpfade sicher in einem frischen Verzeichnis aufgelöst werden?
• Wird eine brechende API-Änderung als solche behandelt?

Nicht jede Komponente benötigt dieselbe Testtiefe. Eine dekorative Trennlinie hat einen kleineren Vertrag als eine Navigation oder ein mehrstufiges Formular. Doch gerade bei den einfachen Bausteinen lohnt sich eine klare Grundstruktur: Sie verhindert, dass aus vielen kleinen Ausnahmen ein unwartbares System entsteht.

Der Styleguide ist ein Konsument des Systems

Ein Living Styleguide sollte nicht über der Anwendung stehen und ihr eine zweite Komponentenwelt vorschreiben. Er ist ein besonders anspruchsvoller Konsument derselben Verträge: Er muss Templates entdecken, Eingaben verstehen, kontrollierte Zustände erzeugen und Ergebnisse transportierbar machen.

Diese Perspektive verändert den Qualitätsmaßstab. Entscheidend ist nicht, wie vollständig die Galerie wirkt. Entscheidend ist, ob eine Änderung an Argumenten, Slots, Varianten oder Exporten dort sichtbar scheitert, bevor sie unbemerkt in mehrere Projekte gelangt.

Eine gute Vorschau zeigt eine Komponente. Ein guter Vertrag sorgt dafür, dass alle Beteiligten tatsächlich über dieselbe Komponente sprechen.