Akceptacja wizualna przed implementacją frontendu

Akceptacja wizualna to bramka między intent.md a kodem frontendu. Agent zamienia intencję w makietę, którą można obejrzeć, imienny właściciel produktu lub designu podpisuje wersjonowany plik acceptance.md, a zbudowany ekran jest potem sprawdzany względem zaakceptowanych klatek zrzutami ekranu i osobnym przeglądem. Makietę poprawisz w kilka minut; zmergowanego ekranu już nie.

Ta strona jest dla developera, który buduje interfejsy z Claude Code, Codeksem albo Cursorem, oraz dla tech leada, który chce, żeby ta pętla wyglądała tak samo w całym zespole. Problem, który rozwiązuje: prosisz agenta o ekran ustawień, po 20 minutach dostajesz dopracowaną stronę, a przegląd produktowy ją odrzuca, bo hierarchia jest zła, stan błędu jest pusty, a układu mobilnego nikt nie uzgodnił. Jeśli nie masz jeszcze intent.md, zacznij od Plan: zapisz intent.md.

Pytanie Q7 scorecardu: Jak prototypujesz i walidujesz interfejsy użytkownika przed pisaniem kodu?

Odpowiedź za maksimum punktów: pętla wizualna, w której intent.md tworzy makietę do obejrzenia w zatwierdzonym narzędziu projektowym, iterowaną przed generowaniem kodu.

Co daje ci akceptacja wizualna

• Sposób doboru medium makiety (klatka w Figmie, prototyp HTML w repozytorium, wygenerowany obraz albo trasa prototypowa na danych testowych (fixtures)) do ryzyka projektowego, które chcesz wyeliminować
• Konfigurację dostępu do materiałów projektowych w Claude Code, Codeksie i Cursorze, z serwerami MCP Figmy i Playwrighta tam, gdzie pomagają
• Trzy prompty do skopiowania: zaproponuj kierunki, zbuduj prototyp do obejrzenia i porównaj implementację z zaakceptowanymi klatkami
• Szablon acceptance.md ze stanami, breakpointami, kryteriami, osobą akceptującą i datą
• Ścieżkę weryfikacji, która dowodzi zgodności zbudowanego ekranu z makietą bez czytania kodu komponentu
• Typowe awarie makiet tworzonych przez agenta i sposób wyjścia z każdej z nich

Przy dużych zmianach obejmujących wiele ekranów ten jeden artefakt rozrasta się w pipeline design-to-code z czterema artefaktami. Ta strona opisuje lżejszą wersję, która daje maksimum w Q7 przy codziennych funkcjach.

Jak punktowane jest Q7 i co podnosi wynik?

Scorecard developera przyznaje od zera do trzech punktów. Każdy poziom dodaje coś, co może obejrzeć ktoś inny niż agent.

Punkty	Twoja odpowiedź dziś	Następny krok
0	Brak prototypowania; kod trafia od razu do plików frontendu	Przy następnej zmianie UI poproś agenta o makietę, zanim powstanie kod komponentu
1	Statyczne zrzuty ekranu wklejane do czatu jako jednorazowy podgląd	Zapisuj referencje w design/<feature>/, żeby kolejna sesja i recenzent widzieli te same materiały
2	Designy z Figmy sprawdzane przez serwer MCP Figmy lub załączniki obrazów	Dodaj brakującą połowę: stany, breakpointy i imienną osobę akceptującą w acceptance.md przed startem kodu
3	intent.md tworzy makietę do obejrzenia w zatwierdzonym narzędziu projektowym, iterowaną przed generowaniem kodu	Nie oceniaj na oko: sprawdzaj implementację względem zaakceptowanych klatek na dowodach

Które medium makiety pasuje do ryzyka projektowego?

Wybierz najtańsze medium, które odpowiada na pytanie, co do którego nie masz pewności. Makieta, która wygląda na skończoną, ale odpowiada na złe pytanie, jest najdroższą opcją.

Medium	Odpowiada na	Słabe w	Użyj, gdy
Klatka w Figmie czytana przez serwer MCP Figmy	Zgodność z design systemem: komponenty, tokeny, odstępy	Prawdziwa interakcja; limity miejsc (seats) w części planów	Zespół projektuje w Figmie, a klatka już istnieje
Prototyp HTML w repozytorium, zbudowany z twoich prawdziwych tokenów	Interakcja, kolejność fokusu, zachowanie responsywne	Dopracowanie co do piksela; idzie do kosza	Ryzyko dotyczy zachowania ekranu, nie wyglądu
Wygenerowany obraz (image_generation w Codeksie, dowolny model obrazowy)	Kierunek wizualny i hierarchia	Cała reszta: teksty, stany, wykonalność	Potrzebujesz trzech różnych kierunków w kilka minut, zanim ktokolwiek się zobowiąże
Trasa prototypowa w aplikacji (/prototype/...)	Wysoka wierność z prawdziwymi komponentami	Koszt; z czasem zamienia się w kod produkcyjny	Ekran to głównie istniejące komponenty w nowym układzie

Wygenerowany obraz to kierunek, nigdy zaakceptowany artefakt. Tekst bywa w nim błędny, a komponenty rzadko istnieją w twoim design systemie, więc akceptuj zbudowany na jego podstawie prototyp HTML albo klatkę w Figmie.

Podłącz materiały projektowe (Figma, zrzuty) w Claude Code, Codeksie i Cursorze

Wszystkie trzy narzędzia czytają pliki obrazów i wszystkie mogą korzystać z oficjalnego serwera MCP Figmy oraz Playwright MCP. Różnią się polecenia instalacji; pętla poniżej jest taka sama.

Claude Code

# Figma: the plugin bundles the remote MCP server and Figma's skills
claude plugin install figma@claude-plugins-official
# or the server alone, then run /mcp in a session to log in
claude mcp add --transport http figma https://mcp.figma.com/mcp

# Playwright, so the agent can open and screenshot the prototype
claude mcp add playwright -- npx @playwright/mcp@latest --isolated

Wyeksportowane klatki wskazuj w prompcie ścieżką (design/settings/refs/current.png); Claude Code czyta pliki obrazów bezpośrednio. Wersja 2.1.283 zawiera też wbudowany skill /design, oznaczony w dokumentacji skills jako research preview. Traktuj to, co wygeneruje, jako makietę do akceptacji, a nie jako zapis akceptacji. Flaga --chrome włącza integrację Claude in Chrome do eksplorowania działającej aplikacji.

Codex

codex mcp add figma --url https://mcp.figma.com/mcp
codex mcp login figma

codex mcp add playwright -- npx @playwright/mcp@latest --isolated

Obrazy dołączasz przez -i / --image, interaktywnie albo w codex exec (0.157.1). image_generation, view_image i in_app_browser są w codex features list dla 0.157.1 stabilne i włączone, więc Codex bez dodatkowej konfiguracji szkicuje obrazy kierunków i otwiera prototyp.

Cursor

Dodaj oba serwery do .cursor/mcp.json w repozytorium, żeby cały zespół miał je wspólne:

{
  "mcpServers": {
    "figma": { "url": "https://mcp.figma.com/mcp" },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--isolated"] }
  }
}

Ten kształt pochodzi z README dostawców i nie był testowany w binarce Cursora na potrzeby tej strony (2026-09-26). Klatki i zrzuty wskazujesz przez @ w prompcie Agenta.

Sprawdź miejsce w Figmie, zanim oprzesz plan na serwerze MCP

Przewodnik Figmy ogranicza plany Starter oraz miejsca View i Collab w planach płatnych do „up to 6 tool calls per month”; miejsca Dev i Full w planach płatnych mają zamiast tego limity minutowe (odczyt 2026-09-26). Bez odpowiedniego miejsca wyeksportuj klatki jako PNG i pracuj na plikach.

Przeprowadź pętlę akceptacji wizualnej

Pętla tworzy jeden folder na funkcję. Wszystko, czego potrzebują osoba akceptująca i implementujący agent, jest w nim:

design/settings/
  refs/           # current screen, competitor references, brand examples
  directions/     # two or three direction mocks, rejected ones kept
  prototype.html  # the inspectable mock
  accepted/       # frames captured from the accepted prototype, per breakpoint and state
  acceptance.md   # the signed record

1. Dodaj sekcję wizualną do intent.md. Zanim agent cokolwiek narysuje, zapisz trzy fakty, których nie zgadnie: jedno zadanie, które ekran ma uczynić oczywistym, stany, które istnieją (pusty, ładowanie, błąd, sukces, brak uprawnień, potwierdzenie operacji destrukcyjnej), i breakpointy, które mają znaczenie. Jeśli nie potrafisz nazwać stanów, makieta pokaże tylko ścieżkę szczęśliwą.

2. Poproś o istotnie różne kierunki. Kierunki mają się różnić hierarchią, gęstością albo nawigacją, a nie kolorem. Na tym etapie agent nie pisze kodu produkcyjnego.

   Prompt do skopiowania: trzy kierunki z intent.md

   Read intent.md, docs/design-system.md, and the images in design/settings/refs/.
   Propose three directions for the settings screen that differ in information
   hierarchy, density, or navigation, not only in colour.
   Save each as design/settings/directions/<letter>.png or .html.
   For each direction give: the trade-off it makes, the intent.md goal it serves
   best, which components from src/components/ui/ it reuses, and any component
   it would need that does not exist yet.
   Do not write or edit production code.

   Właściciel wybiera jeden. Zapisz wybór i po jednym zdaniu uzasadnienia dla każdego odrzuconego kierunku; te powody nie pozwolą, żeby ten sam pomysł wrócił w trakcie implementacji.

3. Zbuduj prototyp do obejrzenia. Zamień wybrany kierunek w prototype.html: jeden plik, który ładuje twój prawdziwy arkusz tokenów i pokazuje każdy stan za przełącznikiem. Można go obejrzeć, bo każdy otworzy go w przeglądarce, zmieni rozmiar okna i przejdzie po nim klawiszem Tab.

   Prompt do skopiowania: prototyp ze wszystkimi stanami

   Build design/settings/prototype.html from the accepted direction in
   design/settings/directions/b.html. Load src/styles/tokens.css and use only
   its custom properties for colour, spacing, and type; no raw hex values.
   Add a state switcher driven by ?state= with these states: ready, empty,
   loading, error, permission-denied, confirm-delete.
   Use realistic copy from intent.md, not lorem ipsum.
   Make it keyboard operable with a visible focus ring, and honour
   prefers-reduced-motion. Then serve the repository root with
   `python3 -m http.server 8123` and open
   http://localhost:8123/design/settings/prototype.html?state=<state> with the
   Playwright MCP server at 375px and 1280px. List any state that does not
   render or any control you could not reach with Tab. Do not touch files
   outside design/settings/.

   Prompt serwuje prototyp przez HTTP, bo Playwright MCP domyślnie blokuje nawigację do adresów file:// i ogranicza dostęp do plików do katalogów głównych przestrzeni roboczej (sprawdzone na @playwright/mcp 0.0.83). Serwowanie z katalogu głównego repozytorium pozwala prototypowi wczytać /src/styles/tokens.css dokładnie tak, jak robi to aplikacja, a ten sam adres służy do zrobienia podpisywanych klatek w kroku 4.

4. Zrób klatki, które podpisze osoba akceptująca. Zapisz zrzut każdego stanu w każdym breakpoincie do accepted/. Uruchom to w terminalu z katalogu głównego repozytorium, na tym samym serwerze co w kroku 3; npx playwright screenshot jest częścią Playwrighta (sprawdzone na 1.63.0). Przeglądarkę zainstaluj raz poleceniem npx playwright install chromium:

   python3 -m http.server 8123 &   # skip if the step 3 server is still running
   for state in ready empty loading error permission-denied confirm-delete; do
     for vp in "375,812" "1280,800"; do
       npx playwright screenshot --full-page --viewport-size="$vp" \
         "http://localhost:8123/design/settings/prototype.html?state=$state" \
         "design/settings/accepted/$state-${vp%%,*}.png"
     done
   done

   Dwanaście obrazów przegląda się szybciej niż jeden żywy prototyp, a do tego są stałym punktem odniesienia, z którym później porównasz implementację.

5. Iteruj, a potem podpisz acceptance.md. Właściciel przegląda klatki i prototyp, a nie zapis czatu. Uwagi wracają do agenta jako ponumerowane zmiany; agent generuje klatki od nowa. Gdy właściciel akceptuje, zapisz to:

   # Visual acceptance: settings screen
   
   Intent: intent.md#settings (commit a1b2c3d)
   Accepted artifact: design/settings/prototype.html (commit e4f5a6b)
   Frames: design/settings/accepted/*.png (6 states x 2 breakpoints)
   Figma: none (or a version-pinned frame link)
   
   ## Acceptance criteria
   1. The primary action "Save changes" is the only filled button in every state.
   2. empty: explains how to add the first member and offers one action.
   3. error: keeps the user's input and names the failed field.
   4. permission-denied: shows who can grant access; no disabled form.
   5. confirm-delete: names the workspace and needs the typed name.
   6. 375px: no horizontal scroll; the primary action stays in view.
   7. Keyboard: every control reachable by Tab in visual order; focus visible.
   8. No serious or critical axe violations.
   
   Approved by: APPROVER_NAME (product design), 2026-09-26
   Out of scope: dark theme (next iteration)

   APPROVER_NAME to osoba, do której należy decyzja, a nie agent ani implementujący developer. Sednem są ponumerowane kryteria. Każde staje się kontrolą w następnym kroku albo wykonywalnym kryterium akceptacji w spec.md.

6. Przekaż folder do budowy. Zacommituj design/settings/ razem z gałęzią funkcji. Implementujący agent czyta acceptance.md i klatki z accepted/ podczas planowania, a plan wskazuje, które kryteria pokrywa każdy test.

Jak udowodnić, że zbudowany ekran zgadza się z makietą, bez czytania kodu?

Sprawdzasz ekran względem zaakceptowanych klatek i ponumerowanych kryteriów. Kod komponentu oceniają bramki, a nie człowiek czytający go linijka po linijce.

Uruchom porównanie w świeżym kontekście tylko do odczytu. Sesja, która zbudowała ekran, jest jego najgorszym sędzią. Osobny recenzent otwiera działającą aplikację w każdym stanie i breakpoincie, porównuje ją z accepted/ i zgłasza wyłącznie niezgodności, które potrafi pokazać.

Prompt do skopiowania: porównaj implementację z zaakceptowanymi klatkami

You are reviewing, not fixing. Read design/settings/acceptance.md.
Open http://localhost:4321/settings with each state listed there
(use the ?fixture= query the tests use) at 375px and 1280px.
Compare every screen with design/settings/accepted/<state>-<width>.png
and with each numbered acceptance criterion.
Report only mismatches you can show: criterion number, state, width,
a screenshot path under .evidence/, severity (blocker, major, minor),
and the smallest correction. Report a state you cannot produce as a blocker.
Do not edit files and do not create or update screenshot baselines.

Zapisz prompt jako design/settings/review-prompt.md. Najpierw uruchom aplikację z jej danymi testowymi w osobnym terminalu (na przykład npm run dev); recenzent nie ma powłoki i sam jej nie uruchomi. Potem uruchom przegląd bez prawa zapisu:

Claude Code

claude -p --permission-mode dontAsk \
  --allowedTools "Read Grep Glob mcp__playwright" \
  < design/settings/review-prompt.md

dontAsk odrzuca każde wywołanie narzędzia, które wymagałoby pytania i nie jest w --allowedTools, więc recenzent czyta pliki i steruje przeglądarką, ale nie może niczego edytować. Prompt trafia przez stdin, bo --allowedTools przyjmuje listę o zmiennej długości: prompt podany po tej fladze zostałby wczytany jako kolejna nazwa narzędzia, a claude -p zakończyłby się błędem „Input must be provided”.

Codex

codex exec -s read-only \
  -i design/settings/accepted/*.png \
  < design/settings/review-prompt.md

Glob powłoki dołącza wszystkie dwanaście klatek. Prompt idzie przez stdin, bo -i przyjmuje wiele plików i w przeciwnym razie potraktowałby prompt na końcu jako kolejną ścieżkę obrazu. Codex potrafi też czytać inne obrazy z dysku stabilnym narzędziem view_image, ale dołączenie klatek jawnie wskazuje punkt odniesienia.

Cursor

Otwórz nowy czat Agenta, nie ten, który zbudował ekran. Wklej prompt, wskaż przez @ plik acceptance.md i klatki z accepted/, a serwer Playwright MCP zostaw włączony, żeby recenzent mógł otworzyć aplikację.

Utrwal wynik we wzorcowych zrzutach ekranu. Zamień każdy stan w test Playwrighta z toHaveScreenshot() i skanem axe; pełny wzorzec specyfikacji jest w pipeline z czterema artefaktami. Pierwsze uruchomienie tworzy wzorce. Osoba akceptująca raz porównuje je z accepted/, obok siebie, a od tej pory każda zmiana wizualna oblewa CI, dopóki nie zatwierdzi jej człowiek.

Kto podpisuje co:

Kontrola	Dowodzi	Podpisuje
acceptance.md	Makieta odpowiada na intencję w każdym stanie i breakpoincie	Właściciel produktu lub designu
Raport z przeglądu w świeżym kontekście	Zbudowany ekran zgadza się z zaakceptowanymi klatkami, kryterium po kryterium	Osoba akceptująca przyjmuje lub odrzuca każde zgłoszenie
Wzorcowe zrzuty ekranu	Po merge nic nie zmienia się wizualnie bez zgody	Design (przez CODEOWNERS na katalogu zrzutów)
Skan axe i asercje fokusu	Kryteria 7 i 8 są spełnione	Właściciel kodu

Obejmij katalog zrzutów wpisem w CODEOWNERS należącym do designu, a npx playwright test --update-snapshots uruchomione przez agenta traktuj jako nieudane zadanie. Ogólna zasada jest na stronie o ochronie wyroczni przed agentem. Raport z przeglądu i zielone uruchomienie dołącz do pakietu dowodów pull requesta.

Makiety podlegają tej samej granicy danych co kod źródłowy

Makiety i zrzuty ekranu mogą zawierać nieogłoszoną strategię, dane klientów albo licencjonowane zasoby. Zanim podłączysz serwer MCP narzędzia projektowego albo wyślesz klatki do modelu obrazowego, potwierdź dostawcę, retencję i zakres konektora według zasad z prywatności i obsługi danych. W prototypach używaj danych testowych, nigdy rekordów produkcyjnych.

Co psuje się, gdy makietę robi agent?

Makieta pokazuje tylko ścieżkę szczęśliwą. Właściciel zatwierdził piękny stan gotowości, a stan błędu trafia na produkcję pusty. Wyjście: najpierw wypisz stany w intent.md, wygeneruj prototyp z przełącznikiem stanów od nowa i nie podpisuj acceptance.md, dopóki brakuje którejkolwiek klatki w accepted/.

Makieta używa komponentów, których nie masz. Wygenerowany kierunek pokazuje segmented control i kolor, których nie ma nigdzie w design systemie, a implementacja wymyśla oba. Wyjście: dodaj do promptu z kierunkami „reuse only src/components/ui/, flag anything new” i przeszukaj prototyp pod kątem surowych kolorów (rg -n ':\s*#[0-9a-fA-F]{3,8}\b' design/settings/prototype.html wyłapuje wartości właściwości zaczynające się od koloru hex i ma nic nie wypisać).

Zaakceptowana wersja istnieje tylko w czacie. Właściciel napisał w wątku „wariant B, ale ciaśniej”, a kolejna sesja tego nie widzi. Wyjście: wszystko, czego nie ma w acceptance.md, uznawaj za niezaakceptowane. Streść wątek w ponumerowane zmiany, wygeneruj klatki od nowa i podpisz plik.

Osoba akceptująca porównuje na oko. Przegląd w stylu „wygląda wystarczająco podobnie” przeoczy brakującą etykietę pola przy 375px. Wyjście: każde kryterium w acceptance.md ma dać się sprawdzić, a przegląd w świeżym kontekście ma zgłaszać niezgodności per kryterium zamiast ogólnego wrażenia.

Agent, który zbudował ekran, sam go recenzuje. Raportuje „zgodne z designem”, bo pamięta swoją intencję, a nie dlatego, że patrzył. Wyjście: uruchom prompt porównujący w nowej sesji tylko do odczytu i wymagaj ścieżki do zrzutu ekranu przy każdym zgłoszeniu.

Prototyp przeradza się w kod produkcyjny. Trasa prototypowa obrasta prawdziwymi wywołaniami danych i staje się funkcją. Wyjście: trzymaj prototypy w design/ albo za trasą /prototype/ wyłączoną z builda i zaczynaj implementację od acceptance.md, a nie od edycji prototypu.

Sprawdź akceptację wizualną przed merge

• intent.md nazywa zadanie, stany i breakpointy.
• accepted/ zawiera klatkę dla każdego stanu w każdym breakpoincie.
• acceptance.md ma ponumerowane kryteria, odwołanie do commita, osobę akceptującą i datę.
• Raport z przeglądu w świeżym kontekście nie ma otwartych blockerów.
• Wzorcowe zrzuty zatwierdził człowiek względem accepted/, a nie wygenerował i przyjął agent.
• Narzędzia projektowe i modele obrazowe pozostały w zatwierdzonej granicy danych.

Dokąd dalej z akceptacją wizualną

Pipeline design-to-code z czterema artefaktami Przeskaluj tę pętlę na wiele ekranów z kontraktem designu i testami macierzy stanów.

Weryfikacja w przeglądarce prowadzona przez agenta Udowodnij, że ścieżka użytkownika za ekranem działa, z powtarzalnymi dowodami (Q16).

Figma MCP i design-to-code Implementuj klatki z prawdziwymi komponentami przez Code Connect.

Etap Design Jakie miejsce zajmuje zaakceptowana makieta w cyklu życia i łańcuchu artefaktów.

Wróć do klucza odpowiedzi scorecardu developera.