CSS und LayoutsKI

Altes CSS mit KI refaktorieren – ohne visuelle Regressionen

Das Theme des Shops ist zehn Jahre alt. Ein Grid von Bootstrap 3 mit .row und .col-md-4, Produktkarten mit float: left und Clearfix, ein Menü mit display: inline-block, Abstände über Margins, die einmal jemand nach Augenmaß gewählt hat. Es funktioniert, aber jede Änderung ist ein Risiko, also fasst es niemand an. Bis zu dem Tag, an dem du einen KI-Assistenten bittest: „Schreib das Layout auf Flex und Grid um, ohne das Aussehen zu ändern.“

Zehn Minuten später hast du einen Diff mit fünfzehnhundert Zeilen. Die Startseite sieht auf deinem Laptop identisch aus. Die Produktliste auch. Du deployst. Am nächsten Tag kommen drei Meldungen: In der Produktkarte sind die Abstände zwischen Preis, Name und Button doppelt so groß wie vorher; Produkte mit einem langen Namen ohne Leerzeichen – „Bueroleuchte-LED-mit-Regelung-3000K–6500K“ – drücken ihre Kachel aus dem Raster; und das Menü bricht auf dem Tablet in eine zweite Zeile um, obwohl es vorher passte.

Keine dieser Änderungen war beabsichtigt. Das Modell hat genau das getan, worum du gebeten hast – es hat das CSS umgeschrieben und „das Aussehen nicht verändert“, auf den Bildschirmen, die es sich selbst vorgestellt hat. Niemand, auch du nicht, hat die übrigen geprüft.

Warum sich ein CSS-Refactoring so schwer prüfen lässt

Ein JavaScript-Refactoring hat Sicherheitsnetze: Typen in TypeScript melden, dass eine Funktion ein anderes Argument bekommt, Unit-Tests, dass sie ein anderes Ergebnis liefert. CSS hat weder das eine noch das andere. Die Korrektheit eines Stylesheets ist ausschließlich, wie die Seite aussieht: Pixel in einem bestimmten Viewport, mit bestimmtem Inhalt, in einem bestimmten Browser.

Dazu ist CSS nicht lokal. Eine Änderung an einer Regel wirkt sich auf Elemente an einer ganz anderen Stelle aus – über die Kaskade, Vererbung, kollabierende Margins oder eine geänderte Größe des Elternelements. Im Artikel über natives Nesting habe ich gezeigt, wie das Verschieben von Code aus SCSS in CSS, ohne ein einziges Zeichen in den Selektoren zu ändern, die Farbe eines Buttons am anderen Ende der Seite verändert hat – durch die andere Spezifität von :is(). Der Diff zeigt das nicht. Das zeigt erst die gerenderte Seite.

Das KI-Modell hat hier noch ein Problem: Es sieht die Seite nicht, bis du sie ihm zeigst. Es beurteilt sein Refactoring nach dem Code, und im Code sieht „Flex mit gap: 16px“ aus wie ein exaktes Gegenstück zu „Floats mit margin: 16px“. Auf dem Bildschirm – nicht immer.

Das Sicherheitsnetz: Screenshots vor der Änderung

Die Lösung ist alt und bewährt: visuelle Regressionstests. Vor dem Refactoring machst du Screenshots der wichtigsten Seiten in mehreren Breiten, nach jeder Änderung machst du sie erneut und vergleichst Pixel für Pixel. Playwright hat das mit toHaveScreenshot() eingebaut.

tsx

// playwright.config.ts
import { defineConfig } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
use: { baseURL: "http://localhost:3000" },
expect: {
toHaveScreenshot: { maxDiffPixelRatio: 0.001 },
},
projects: [
{ name: "mobile", use: { viewport: { width: 390, height: 844 } } },
{ name: "tablet", use: { viewport: { width: 820, height: 1180 } } },
{ name: "desktop", use: { viewport: { width: 1440, height: 900 } } },
],
})

tsx

// tests/visual.spec.ts
import { test, expect } from "@playwright/test"
const pages = [
"/",
"/kategorie/leuchten",
"/produkt/led-bueroleuchte",
"/produkt/produkt-mit-sehr-langem-namen",
"/warenkorb",
]
for (const path of pages) {
test("Aussehen " + path, async ({ page }) => {
await page.goto(path)
await page.evaluate(async () => {
await document.fonts.ready
})
await expect(page).toHaveScreenshot({
fullPage: true,
mask: [page.locator("[data-dynamic]")],
})
})
}

Der erste Lauf – auf dem Code vor dem Refactoring – speichert Referenz-Screenshots in einem Ordner neben dem Test. Jeder weitere Lauf vergleicht das aktuelle Aussehen damit und schlägt fehl, wenn sich mehr als 0,1 % der Pixel unterscheiden. Bei einem Fehler speichert Playwright in test-results drei Bilder: die Referenz, den aktuellen Screenshot und eine Differenzkarte, auf der geänderte Pixel rot markiert sind.

Beachte die Liste der Seiten. Darin steht ein Produkt „mit sehr langem Namen“ – das ist kein Zufall. Screenshots prüfen nur, was sie zeigen, also müssen die Testseiten Randfälle enthalten: lange Wörter, ein fehlendes Bild, ein reduziertes Produkt mit zwei Preisen, ein leerer Warenkorb. Eine einzige Seite mit typischem Inhalt lässt die meisten Regressionen aus der Einleitung durch.

Stabile Screenshots: bevor du ihnen vertraust

Ein Test, der mal besteht und mal nicht, ist schlimmer als gar kein Test – nach dem dritten Fehlalarm liest niemand mehr die Ergebnisse. Vier Quellen der Instabilität sollte man sofort beseitigen:

  • Fonts. Ein Screenshot, der vor dem Laden des Webfonts entsteht, zeigt die Ersatzschrift. document.fonts.ready im Test wartet, bis die Fonts bereit sind.
  • Animationen. toHaveScreenshot() hält CSS-Animationen und -Transitions standardmäßig an, aber per JavaScript gesteuerte Animationen – Karussells, Zähler – muss man selbst anhalten oder maskieren.
  • Dynamische Inhalte. Datum, ein Zähler „diese Woche 14-mal gekauft“, zufällig empfohlene Produkte. Markiere sie mit einem Attribut und übergib sie an mask – Playwright verdeckt sie mit einem einfarbigen Rechteck.
  • Betriebssystem. Dasselbe CSS wird unter macOS, Windows und Linux leicht unterschiedlich gerendert – anderes Font-Antialiasing, andere Scrollleisten. Playwright hängt den Plattformnamen an die Dateinamen der Referenzen, in der Praxis ist es aber am einfachsten, Screenshots immer in derselben Umgebung zu machen, etwa im offiziellen Docker-Image von Playwright, lokal und im CI.

Refactoring in kleinen Schritten

Mit visuellen Tests ändert sich, wie du die KI um ein Refactoring bittest. Statt „schreib das ganze Layout um“ führst du sie durch eine Schleife: eine Komponente, Tests, Differenzen prüfen, nächste Komponente.

markdown

## CSS-Refactoring
- Vor der ersten Änderung: npx playwright test – alle Tests müssen bestehen.
- Eine Komponente pro Schritt (z. B. Produktkarte, dann Listenraster, dann Menü).
- Nach jedem Schritt: npx playwright test.
- Tests nie mit --update-snapshots ausführen und keine Dateien in
*-snapshots-Ordnern löschen oder überschreiben.
- Wenn ein Test fehlschlägt: Seite und Breite nennen, die Differenz anhand
des Diff-Bildes in test-results beschreiben und die Ursache im CSS angeben.
Nicht weiter ändern, bis ich bestätige, ob die Differenz beabsichtigt ist.

Ein solcher Abschnitt in CLAUDE.md oder einer anderen Regeldatei – darüber habe ich im Artikel geschrieben, warum KI CSS wie 2015 schreibt – verändert die Art der Zusammenarbeit. Ein Agent, der die Tests selbst ausführen und sich das Differenzbild ansehen kann, liefert keinen Code mehr ab, der „gleich aussehen sollte“. Er liefert Code, von dem er weiß, dass er gleich aussieht – oder eine konkrete Liste von Stellen, an denen das nicht so ist, mit einer Erklärung, warum.

Ein kleiner Schritt hat noch einen zweiten Vorteil: Schlägt ein Test nach der Änderung einer Komponente fehl, weiß man, wo man die Ursache suchen muss. Nach dem Umschreiben des ganzen Themes auf einmal kann eine rote Differenzkarte auf der Produktseite zehn unabhängige Ursachen haben.

Die Falle: Die KI repariert den Test statt das CSS

Das ist der wichtigste Grund, warum die Regel zu --update-snapshots gesondert und ohne Ausnahmen in den Regeln steht. Ein Modell, dem du sagst „bring die Tests zum Bestehen“, hat zwei Wege: das CSS korrigieren oder die Referenzen aktualisieren. Der zweite ist kürzer, gelingt immer und ist aus Sicht der Anfrage korrekt – die Tests bestehen.

bash

# Dieser Befehl speichert das aktuelle Aussehen als neue Referenz.
# Danach wird jede Regression zum „erwarteten Aussehen“.
npx playwright test --update-snapshots

Nach einer solchen „Reparatur“ garantieren grüne Tests gar nichts mehr, und die Regression aus der Einleitung liegt als Referenz im Repository. Das Modell tut das nicht böswillig – es unterscheidet von sich aus einfach nicht zwischen einer beabsichtigten Änderung des Aussehens und einem Fehler, denn das ist eine Designentscheidung, keine technische.

Deshalb trifft die Entscheidung über das Aktualisieren der Referenzen immer ein Mensch, nachdem er sich die Differenzkarte angesehen hat. Es lohnt sich, das auch außerhalb der Regeldatei abzusichern: Im Code-Review sollte jede Änderung in *-snapshots-Ordnern sichtbar und begründet sein, und im CI laufen die visuellen Tests ohne Möglichkeit, Referenzen zu aktualisieren. Ist eine Änderung des Aussehens beabsichtigt – etwa ein neuer Abstand in der Karte –, aktualisiere die Referenzen in einem eigenen Commit, der nur diese Änderung enthält.

Was sich beim Umstieg von Floats auf Flex und Grid am häufigsten verschiebt

Die meisten Regressionen aus einem solchen Refactoring haben einige wiederkehrende Quellen. Es lohnt sich, sie zu kennen, weil man damit eine Differenzkarte schnell lesen kann – und sie in die Regeln aufnehmen kann, damit das Modell sie von Anfang an vermeidet.

Margins kollabieren nicht mehr. Im normalen Blockfluss kollabieren die vertikalen Margins benachbarter Elemente: Zwei Elemente mit margin-block: 16px sind 16px voneinander entfernt, nicht 32px. In einem Flex- oder Grid-Container gibt es dieses Kollabieren nicht.

css

/* Vorher: Blockelemente, 16px Abstand dazwischen */
.product-info > * {
margin-block: 16px;
}
/* Nachdem das Elternelement Flex geworden ist: 32px */
.product-info {
display: flex;
flex-direction: column;
}
/* Richtig: Abstand per gap, Margins zurückgesetzt */
.product-info {
display: flex;
flex-direction: column;
gap: 16px;
}
.product-info > * {
margin-block: 0;
}

Das sind genau die „doppelt so großen Abstände in der Produktkarte“ aus der Einleitung. Dieselbe Regel gilt auch zwischen einem Elternelement und seinem ersten Kind: Der obere Margin einer Überschrift, der vorher aus dem Container „herausragte“, bleibt in einem Flex-Container drin und schiebt den Inhalt nach unten.

Flex-Elemente wollen nicht unter ihren Inhalt schrumpfen. Das standardmäßige min-width: auto bei Flex-Elementen bedeutet, dass ein Element nicht schmaler wird als sein längstes unumbrechbares Stück – ein langes Wort, eine URL, ein Bild. Floats und Blöcke ließen den Text einfach aus dem Kasten ragen, Flex drückt die ganze Kachel breiter.

css

.product-card__body {
min-width: 0; /* erlaubt es, das Element unter seinen Inhalt zu verkleinern */
}
.product-card__title {
overflow-wrap: anywhere; /* bricht lange Wörter ohne Leerzeichen um */
}
/* Im Grid löst minmax(0, 1fr) statt 1fr dasselbe Problem */
.product-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(min(240px, 100%), 1fr));
}

Die Abstände zwischen inline-block-Elementen verschwinden. Ein Menü mit display: inline-block hatte zwischen den Einträgen ein paar Pixel Abstand – nicht aus dem CSS, sondern aus Leerzeichen und Zeilenumbrüchen im HTML, die der Browser wie Text rendert. Flex ignoriert diese Leerzeichen, also ist das Menü nach dem Refactoring pro Eintrag ein paar Pixel schmaler – oder, falls das Modell das mit einem größeren gap „ausgeglichen“ hat, breiter, und es bricht auf dem Tablet um.

Die negativen Margins des Bootstrap-Grids. In Bootstrap 3 hat .row ein margin: 0 -15px und die Spalten haben padding: 0 15px, damit die Außenkanten des Inhalts mit dem Container fluchten. Der Wechsel zu einem Grid mit gap: 30px, ohne das Padding der Spalten zu entfernen oder den Container anzupassen, verschiebt die Außenkanten um 15px – ein kleiner, aber sichtbarer Unterschied in der Ausrichtung zu Header und Footer.

Fallen und Best Practices

  • Erst Referenzen, dann Refactoring. Screenshots müssen auf dem Code vor der Änderung entstehen. Nach dem Refactoring erstellte Referenzen schreiben seine Fehler fest.
  • Testseiten mit Randfällen. Lange Namen, fehlende Bilder, zwei Preise, ein leerer Warenkorb – Screenshots erfassen nur, was sie zeigen.
  • Stabilität vor Vertrauen. Auf Fonts warten, dynamische Inhalte maskieren, Screenshots immer in derselben Umgebung machen.
  • Eine Komponente pro Schritt. Eine kurze Schleife aus Änderung, Test und Prüfung lässt die Ursache jeder Differenz sofort erkennen.
  • Kein --update-snapshots für die KI. Ein Modell, das die Tests grün machen soll, schafft das am leichtesten, indem es die Referenzen aktualisiert. Diese Entscheidung trifft immer ein Mensch, in einem eigenen Commit.
  • Kenne die typischen Verschiebungen. Kein Kollabieren von Margins in Flex und Grid, min-width: auto, Leerzeichen zwischen inline-block-Elementen und die negativen Margins von .row erklären die meisten roten Differenzkarten.
  • Browser-Unterstützung. gap in Flexbox funktioniert seit Chrome 84, Firefox 63 und Safari 14.1, overflow-wrap: anywhere seit Chrome 80, Firefox 65 und Safari 15.4 – soll das Refactoring ältere Geräte unterstützen, prüfe das, bevor du Margins durch gap ersetzt.

Fazit

Das Refactoring von altem CSS ist eine Aufgabe, bei der die KI schnell und überzeugend ist und ihre Fehler im Diff unsichtbar sind – denn die Korrektheit von CSS ist das Aussehen der Seite, nicht der Code. Visuelle Regressionstests in Playwright geben ihr das fehlende Sicherheitsnetz: Referenz-Screenshots von vor der Änderung, einen Vergleich nach jedem Schritt und eine Differenzkarte, die sich Mensch und Agent ansehen können. Zwei Regeln entscheiden, ob dieses Netz trägt: Die Referenzen entstehen vor dem Refactoring, und nur ein Mensch entscheidet über ihre Aktualisierung – denn ein Modell, das um grüne Tests gebeten wird, erreicht sie am einfachsten, indem es die Regression als neue Referenz speichert. Und wird die Differenzkarte rot, ist die Ursache meist eine von wenigen bekannten: Margins, die in Flex nicht mehr kollabieren, min-width: auto, verschwundene Abstände zwischen inline-block-Elementen oder die negativen Margins des alten Grids.