css i układyAI

Refaktor starego CSS z AI bez regresji wizualnych

Motyw sklepu ma dziesięć lat. Siatka Bootstrapa 3 z .row i .col-md-4, karty produktów na float: left z clearfixem, menu na display: inline-block, odstępy ustawiane marginesami, które ktoś kiedyś dobrał na oko. Działa, ale każda zmiana to ryzyko, więc nikt go nie rusza. Aż do dnia, w którym prosisz asystenta AI: „przepisz layout na flex i grid, bez zmiany wyglądu”.

Dziesięć minut później masz diff na półtora tysiąca linii. Strona główna na twoim laptopie wygląda identycznie. Lista produktów też. Wdrażasz. Następnego dnia przychodzą trzy zgłoszenia: w karcie produktu odstępy między ceną, nazwą i przyciskiem są dwa razy większe niż wcześniej; produkty z długą nazwą bez spacji – „Lampa-biurowa-LED-z-regulacją-3000K–6500K” – rozpychają kafelek poza siatkę; a menu na tablecie zawija się do drugiej linii, choć wcześniej się mieściło.

Żadna z tych zmian nie była zamierzona. Model zrobił dokładnie to, o co prosiłeś – przepisał CSS i „nie zmienił wyglądu” na tych ekranach, które sam sobie wyobraził. Nikt, łącznie z tobą, nie sprawdził pozostałych.

Dlaczego refaktor CSS tak trudno sprawdzić

Refaktor JavaScriptu ma siatki bezpieczeństwa: typy w TypeScripcie zgłaszają, że funkcja dostaje inny argument, testy jednostkowe – że zwraca inny wynik. CSS nie ma ani jednego, ani drugiego. Poprawność arkusza stylów to wyłącznie to, jak wygląda strona: piksele w konkretnym oknie, z konkretną treścią, w konkretnej przeglądarce.

Do tego CSS jest nielokalny. Zmiana w jednej regule wpływa na elementy w zupełnie innym miejscu – przez kaskadę, dziedziczenie, zapadanie się marginesów albo zmianę rozmiaru rodzica. W artykule o natywnym nestingu pokazywałem, jak przeniesienie kodu z SCSS do CSS bez zmiany ani jednego znaku w selektorach zmieniło kolor przycisku na drugim końcu strony – przez inną specyficzność :is(). Diff tego nie pokazuje. Pokazuje to dopiero wyrenderowana strona.

Model AI ma tu jeszcze jeden problem: nie widzi strony, dopóki mu jej nie pokażesz. Ocenia swój refaktor po kodzie, a w kodzie „flex z gap: 16px” wygląda jak dokładny odpowiednik „floatów z margin: 16px”. Na ekranie – nie zawsze.

Siatka bezpieczeństwa: zrzuty ekranu przed zmianą

Rozwiązanie jest stare i sprawdzone: testy regresji wizualnej. Przed refaktorem robisz zrzuty ekranu kluczowych stron w kilku szerokościach, po każdej zmianie robisz je ponownie i porównujesz piksel po pikselu. Playwright ma to wbudowane w toHaveScreenshot().

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 = [
"/",
"/kategoria/lampy",
"/produkt/lampa-biurowa-led",
"/produkt/produkt-z-bardzo-dluga-nazwa",
"/koszyk",
]
for (const path of pages) {
test("wygląd " + 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]")],
})
})
}

Pierwsze uruchomienie – na kodzie sprzed refaktoru – zapisuje wzorcowe zrzuty w katalogu obok testu. Każde kolejne porównuje z nimi aktualny wygląd i kończy się błędem, jeśli różni się więcej niż 0,1% pikseli. Przy błędzie Playwright zapisuje w test-results trzy obrazy: wzorzec, aktualny zrzut i mapę różnic, na której zmienione piksele są zaznaczone na czerwono.

Zwróć uwagę na listę stron. Jest w niej produkt „z bardzo długą nazwą” – to nie przypadek. Zrzuty sprawdzają tylko to, co pokazują, więc strona testowa musi zawierać przypadki brzegowe: długie słowa, brak zdjęcia, produkt na promocji z dwiema cenami, pusty koszyk. Jedna strona z typową treścią przepuści większość regresji z wstępu.

Stabilne zrzuty: zanim zaczniesz im ufać

Test, który czasem przechodzi, a czasem nie, jest gorszy niż brak testu – po trzecim fałszywym alarmie wszyscy przestają czytać wyniki. Cztery źródła niestabilności warto wyeliminować od razu:

  • Fonty. Zrzut zrobiony, zanim załaduje się webfont, pokazuje font zastępczy. document.fonts.ready w teście czeka, aż fonty będą gotowe.
  • Animacje. toHaveScreenshot() domyślnie zatrzymuje animacje i przejścia CSS, ale animacje sterowane JavaScriptem – karuzele, liczniki – trzeba zatrzymać samemu albo zamaskować.
  • Dynamiczna treść. Data, licznik „kupiono 14 razy w tym tygodniu”, losowe polecane produkty. Oznacz je atrybutem i przekaż do mask – Playwright zasłoni je jednolitym prostokątem.
  • System operacyjny. Ten sam CSS renderuje się nieco inaczej na macOS, Windowsie i Linuksie – inny antyaliasing fontów, inne paski przewijania. Playwright dopisuje nazwę platformy do nazw plików wzorców, ale w praktyce najprościej robić zrzuty zawsze w tym samym środowisku, na przykład w oficjalnym obrazie Dockera Playwrighta, lokalnie i w CI.

Refaktor małymi krokami

Z testami wizualnymi zmienia się sposób, w jaki prosisz AI o refaktor. Zamiast „przepisz cały layout”, prowadzisz go przez pętlę: jeden komponent, testy, przegląd różnic, następny komponent.

markdown

## Refaktor CSS
- Przed pierwszą zmianą: npx playwright test – wszystkie testy muszą przejść.
- Jeden komponent na krok (np. karta produktu, potem siatka listy, potem menu).
- Po każdym kroku: npx playwright test.
- Nigdy nie uruchamiaj testów z --update-snapshots i nie usuwaj ani nie
nadpisuj plików w katalogach *-snapshots.
- Jeśli test nie przechodzi: wskaż stronę i szerokość, opisz różnicę
na podstawie obrazu diff z test-results i podaj przyczynę w CSS.
Nie poprawiaj dalej, dopóki nie potwierdzę, czy różnica jest zamierzona.

Taki fragment w CLAUDE.md albo innym pliku z zasadami – o którym pisałem w artykule o tym, dlaczego AI pisze CSS jak w 2015 roku – zmienia charakter współpracy. Agent, który może sam uruchomić testy i obejrzeć obraz różnic, przestaje oddawać kod, który „powinien wyglądać tak samo”. Oddaje kod, o którym wie, że wygląda tak samo – albo konkretną listę miejsc, gdzie nie wygląda, z wyjaśnieniem dlaczego.

Mały krok ma też drugą zaletę: gdy test nie przechodzi po zmianie jednego komponentu, wiadomo, gdzie szukać przyczyny. Po przepisaniu całego motywu naraz czerwona mapa różnic na stronie produktu może mieć dziesięć niezależnych źródeł.

Pułapka: AI naprawia test zamiast CSS

To najważniejszy powód, dla którego reguła o --update-snapshots stoi w zasadach osobno i bez wyjątków. Model, któremu każesz „doprowadzić do przechodzących testów”, ma dwie drogi: poprawić CSS albo zaktualizować wzorce. Druga jest krótsza, zawsze się udaje i z punktu widzenia polecenia jest poprawna – testy przechodzą.

bash

# To polecenie zapisuje aktualny wygląd jako nowy wzorzec.
# Po nim każda regresja staje się „oczekiwanym wyglądem”.
npx playwright test --update-snapshots

Po takiej „naprawie” zielone testy niczego już nie gwarantują, a regresja z wstępu jest zapisana w repozytorium jako wzorzec. Model nie robi tego złośliwie – po prostu nie odróżnia sam z siebie zamierzonej zmiany wyglądu od błędu, bo to decyzja projektowa, a nie techniczna.

Dlatego decyzję o aktualizacji wzorców zawsze podejmuje człowiek, po obejrzeniu mapy różnic. Warto to też zabezpieczyć poza plikiem z zasadami: w code review każda zmiana w katalogach *-snapshots powinna być widoczna i uzasadniona, a w CI testy wizualne uruchamiaj bez możliwości aktualizacji wzorców. Gdy zmiana wyglądu jest zamierzona – na przykład nowy odstęp w karcie – zaktualizuj wzorce w osobnym commicie, który zawiera tylko tę zmianę.

Co najczęściej się przesuwa przy przejściu z floatów na flex i grid

Większość regresji z takiego refaktoru ma kilka powtarzalnych źródeł. Warto je znać, bo pozwalają szybko przeczytać mapę różnic – i dopisać je do zasad, żeby model unikał ich od początku.

Marginesy przestają się zapadać. W zwykłym przepływie blokowym pionowe marginesy sąsiednich elementów się zapadają: dwa elementy z margin-block: 16px są od siebie oddalone o 16px, nie 32px. W kontenerze flex i grid zapadanie nie występuje.

css

/* Przed: elementy blokowe, odstęp między nimi 16px */
.product-info > * {
margin-block: 16px;
}
/* Po zmianie rodzica na flex: odstęp 32px */
.product-info {
display: flex;
flex-direction: column;
}
/* Poprawnie: odstęp z gap, marginesy wyzerowane */
.product-info {
display: flex;
flex-direction: column;
gap: 16px;
}
.product-info > * {
margin-block: 0;
}

To właśnie „dwa razy większe odstępy w karcie produktu” z wstępu. Ta sama zasada działa też między rodzicem a pierwszym dzieckiem: margines górny nagłówka, który wcześniej „wychodził” poza kontener, w kontenerze flex zostaje w środku i przesuwa treść w dół.

Elementy flex nie chcą się zwężać poniżej treści. Domyślne min-width: auto w elementach flexa oznacza, że element nie zmniejszy się poniżej szerokości swojego najdłuższego niełamliwego fragmentu – długiego słowa, adresu URL, obrazka. Floaty i bloki po prostu pozwalały tekstowi wyjść poza ramkę, flex rozpycha cały kafelek.

css

.product-card__body {
min-width: 0; /* pozwala zwęzić element poniżej treści */
}
.product-card__title {
overflow-wrap: anywhere; /* łamie długie słowa bez spacji */
}
/* W gridzie ten sam problem rozwiązuje minmax(0, 1fr) zamiast 1fr */
.product-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(min(240px, 100%), 1fr));
}

Znikają odstępy między elementami inline-block. Menu zbudowane na display: inline-block miało między pozycjami kilka pikseli odstępu – nie z CSS, tylko ze spacji i znaków nowej linii w HTML-u, które przeglądarka renderuje jak tekst. Flex ignoruje te białe znaki, więc menu po refaktorze jest węższe o kilka pikseli na każdej pozycji – albo, jeśli model „wyrównał” to większym gap, szersze i zawija się na tablecie.

Ujemne marginesy siatki Bootstrapa. .row w Bootstrapie 3 ma margin: 0 -15px, a kolumny padding: 0 15px, żeby zewnętrzne krawędzie treści pokrywały się z kontenerem. Zamiana na grid z gap: 30px bez usunięcia paddingu kolumn albo bez korekty kontenera przesuwa zewnętrzne krawędzie o 15px – drobna, ale widoczna różnica w wyrównaniu z nagłówkiem i stopką.

Pułapki i dobre praktyki

  • Najpierw wzorce, potem refaktor. Zrzuty ekranu muszą powstać na kodzie sprzed zmian. Wzorce zrobione po refaktorze utrwalają jego błędy.
  • Strony testowe z przypadkami brzegowymi. Długie nazwy, brak zdjęć, dwie ceny, pusty koszyk – zrzuty łapią tylko to, co pokazują.
  • Stabilność przed zaufaniem. Czekaj na fonty, maskuj dynamiczne treści, rób zrzuty zawsze w tym samym środowisku.
  • Jeden komponent na krok. Krótka pętla zmiana–test–przegląd pozwala od razu wskazać przyczynę każdej różnicy.
  • Zakaz --update-snapshots dla AI. Model, który ma doprowadzić testy do zielonego koloru, najłatwiej zrobi to, aktualizując wzorce. Tę decyzję zawsze podejmuje człowiek, w osobnym commicie.
  • Znaj typowe przesunięcia. Brak zapadania marginesów we flex i grid, min-width: auto, białe znaki między inline-block i ujemne marginesy .row tłumaczą większość czerwonych map różnic.
  • Wsparcie przeglądarek. gap we flexie działa od Chrome 84, Firefox 63 i Safari 14.1, a overflow-wrap: anywhere od Chrome 80, Firefox 65 i Safari 15.4 – jeśli refaktor ma wspierać starsze urządzenia, sprawdź to przed zamianą marginesów na gap.

Podsumowanie

Refaktor starego CSS to zadanie, w którym AI jest szybkie i przekonujące, a jego błędy są niewidoczne w diffie – bo poprawność CSS to wygląd strony, a nie kod. Testy regresji wizualnej w Playwright dają mu brakującą siatkę bezpieczeństwa: wzorcowe zrzuty sprzed zmian, porównanie po każdym kroku i mapę różnic, którą może obejrzeć zarówno człowiek, jak i agent. Dwie zasady decydują o tym, czy ta siatka działa: wzorce powstają przed refaktorem i tylko człowiek decyduje o ich aktualizacji – bo model poproszony o zielone testy najprościej osiągnie je, zapisując regresję jako nowy wzorzec. A gdy mapa różnic zrobi się czerwona, przyczyna zwykle jest jedną z kilku znanych: marginesy, które we flexie przestały się zapadać, min-width: auto, zniknięte odstępy między inline-block albo ujemne marginesy starej siatki.