Impeccable: słownik projektowy dla twojego harnessu AI
Impeccable to darmowy pakiet Agent Skill autorstwa Paula Bakausa, który daje agentowi AI i jego użytkownikowi wspólny słownik — 23 wywoływalne polecenia, takie jak typeset, quieter i colorize — do opisywania hierarchii, kontrastu i powściągliwości w generowanych interfejsach. Działa wewnątrz repozytorium projektu, dziedzicząc jego tokeny i komponenty, a od v4 prowadzi też nowe buildy stron i redesigny.
Wygeneruj UI dowolnym narzędziem AI, a rozpoznasz je natychmiast: gradient od fioletu do błękitu, ciasny padding, sprężynujący easing, ciemna poświata na karcie. Frontendy AI wyglądają wszystkie tak samo — nie dlatego, że modele mają zły gust, ale dlatego, że nie mają słów na hierarchię, kontrast i powściągliwość. Poproś o „lepsze odstępy”, a dostaniesz zgadywankę.
Impeccable, autorstwa Paula Bakausa, to język projektowy, który naprawia problem słownictwa po obu stronach. Daje twojemu agentowi 23 wywoływalne polecenia i daje tobie te same terminy, więc możesz poprosić dokładnie o to, czego chcesz — typeset na nagłówki, quieter na tę sekcję, colorize strategicznie — zamiast to opisywać i mieć nadzieję. Działa wewnątrz twojego repo i dziedziczy twoje istniejące tokeny, komponenty i konwencje. A od wydania v4 (lipiec 2026) nie tylko poleruje to, co masz: potrafi też budować nowe strony i redesigny — poprzez kierunek wizualny, który zatwierdzasz, zanim powstanie jakikolwiek kod.
Co wyniesiesz z Impeccable
Dział zatytułowany „Co wyniesiesz z Impeccable”- Dlaczego UI generowane przez AI zbiegają się do tego samego wyglądu i co naprawia wspólny słownik
- Jak zainstalować Impeccable i skonfigurować pliki kontekstu, które czyta każde polecenie
- Każde z 23 poleceń — co robi, jak działa, kiedy po nie sięgnąć i jaki detal warto znać
- Jak „kierunek z kości” w v4 sprawia, że nowe buildy lądują tam, gdzie model sam by nie doszedł
- Live Mode do iteracji w przeglądarce i nakładka critique do przeglądów wizualnych
- CLI
detect, hooki projektowe idoctor— warstwa automatyzacji do CI i długowiecznych projektów - Kiedy sięgnąć po Impeccable, a kiedy po szerszy potok projektowy
Instalacja
Dział zatytułowany „Instalacja”Z katalogu głównego projektu:
npx impeccable installInstalator wykrywa, których narzędzi AI używasz, zapisuje pliki skilla we właściwych folderach (.claude/skills/, .cursor/skills/, …) i pyta, czy zainstalować lokalnie w projekcie, czy globalnie. Później sprawdzisz i zaktualizujesz go tak:
npx impeccable check # czy moja instalacja jest aktualna?npx impeccable update # pobierz najnowszy buildNastępnie uruchom jednorazową konfigurację wewnątrz swojego narzędzia AI:
/impeccable initPliki kontekstu, które czyta wszystko
Dział zatytułowany „Pliki kontekstu, które czyta wszystko”Odpowiedź Impeccable na pytanie „skąd AI ma wiedzieć, jak powinien wyglądać nasz produkt” to mały zestaw plików w twoim repo. init przeprowadza z tobą wywiad o produkcie — dla kogo jest, jak się pozycjonuje, jakie masz dowody, które zobowiązania brandowe są nienegocjowalne — i zapisuje pierwszy z nich. Reszta narasta w trakcie pracy:
| Plik | Zawiera | Zapisuje |
|---|---|---|
PRODUCT.md | Platformę, użytkowników, pozycjonowanie, dowody, zobowiązania brandowe | init (edytuj śmiało — jest twój) |
DESIGN.md | Kolory, typografię, komponenty, promienie, reguły projektowe | document (generowany z twojego kodu) |
.impeccable/design.json | Ustrukturyzowany sidecar tokenów dla automatyzacji | document — regeneruj, nigdy nie edytuj ręcznie |
.impeccable/surfaces/*.md | Strategię per strona: odbiorców, sekwencję dowodów, wybrany kierunek | Zapisywane automatycznie w trakcie pracy |
.impeccable/config.json | Ignory detektora, ustawienia hooków, korzenie monorepo | Ty (config.local.json na osobiste, git-ignorowane nadpisania) |
Dwie konsekwencje warto wypowiedzieć wprost. Po pierwsze, strony pamiętają swoją strategię: późniejsza sesja kontynuuje argument danej strony, zamiast wymyślać nowy. Po drugie, monorepa rozwiązują kontekst per workspace — każda aplikacja używa własnych PRODUCT.md/DESIGN.md i sięga do korzenia repo po wszystko, czego sama nie definiuje, a globy projectRoots w configu pomagają, gdy układ workspace’ów nie pokrywa się z granicami projektowymi.
Cztery tryby, wybierane per powierzchnia
Dział zatytułowany „Cztery tryby, wybierane per powierzchnia”v4 klasyfikuje każdą powierzchnię według tego, po co przyszedł odwiedzający, a nie według tego, co sprzedaje firma — i odpowiednio dostraja słownik oraz priorytety:
| Tryb | Powierzchnie | Co wygrywa |
|---|---|---|
| Persuade | Landing page’e, kampanie, cenniki | Wyrazista typografia, zdecydowane palety — design musi zapracować na uwagę |
| Operate | Aplikacje, dashboardy, panele admina | Skanowalność i natywne oczekiwania; brand żyje w precyzyjnych detalach |
| Read | Dokumentacja, przewodniki, changelogi | Szerokość łamu, rytm, cicha hierarchia — najpierw zrozumienie |
| Experience | Portfolia, galerie, showcase’y | Prowadzi artefakt; interfejs się wycofuje |
Tryb jest decydowany per powierzchnia, więc jeden projekt może mieścić wszystkie cztery: landing narzędzia to wciąż Persuade, nawet jeśli produkt to Operate; dokumentacja domu mody to wciąż Read.
23 polecenia
Dział zatytułowany „23 polecenia”Każde polecenie wywołuje się jako /impeccable <polecenie> <cel>. v4 przegrupowało je według intencji — nazywasz dyscyplinę, zamiast opisywać objaw:
| Grupa | Polecenia |
|---|---|
| Create | impeccable, shape |
| Evaluate | audit, critique |
| Refine | animate, bolder, colorize, delight, layout, overdrive, quieter, typeset |
| Simplify | adapt, clarify, distill |
| Harden | harden, onboard, optimize, polish |
| System | init, document, extract, live |
Polecenia są projektowane jako pary: bolder ↔ quieter to dwie połowy głosu; audit znajduje problemy techniczne, a harden je naprawia; critique recenzuje, a polish szlifuje; init uchwytuje produkt, a shape planuje powierzchnię. Przed wysyłką dokumentacja zaleca „przedwysyłkową rękawicę”: audit, clarify i harden.
Poniżej pełny katalog, polecenie po poleceniu — co każde robi, jak działa i jaki detal warto znać, zanim je uruchomisz.
impeccable — router i prośba w wolnym tekście
Dział zatytułowany „impeccable — router i prośba w wolnym tekście”Główne polecenie, używane na dwa sposoby. Samo /impeccable bada projekt — czy istnieją pliki kontekstu, w jakim stanie jest kod — i rekomenduje dwa-trzy następne ruchy, czekając na twój wybór. Z prośbą zwykłym językiem (/impeccable redo this hero section) wybiera właściwe polecenie specjalistyczne albo wykonuje pracę bezpośrednio, czytając wcześniej PRODUCT.md, DESIGN.md i tryb danej powierzchni.
Sięgnij po nie, gdy nie wiesz, od czego zacząć, gdy żadne polecenie specjalistyczne nie pasuje jednoznacznie, albo gdy praca obejmuje kilka dyscyplin naraz („przerób ten hero” dotyka layoutu, typografii, koloru i ruchu — żadne pojedyncze polecenie tego nie obejmie). Dokumentacja jasno określa właściwą postawę: to opiniotwórczy partner projektowy, nie linter. Jeśli masz prawdziwy powód, by się nie zgodzić — wytyczne brandu, ograniczenie dostępności, badania użytkowników — postaw się z uzasadnieniem, a skill będzie z tobą współpracował; ignorowanie jego opinii bez powodu daje gorsze wyniki.
shape — odkrywanie przed kodem
Dział zatytułowany „shape — odkrywanie przed kodem”Tu zaczyna się feature. shape prowadzi ustrukturyzowany wywiad odkrywczy — 5 do 10 konwersacyjnych pytań o cel i kontekst, treść i realistyczne zakresy danych, cele projektowe oraz ograniczenia — i odmawia pisania kodu w tej fazie. Wynikiem jest brief projektowy: cel, użytkownik i jego stan umysłu, treść, zamierzone odczucie, ograniczenia. „Kompas, nie specyfikacja” — uchwytuje intencję, nie UI.
Używaj go, gdy ticket jest mglisty albo gdy łapiesz się na pisaniu JSX-a po to, żeby dopiero ustalić, czym produkt ma być. Wywiad kosztuje może pięć minut; przepisywanie, którego unikasz, liczy się w godzinach. Pułapką jest odpowiadanie „standardowo” albo „normalnie” — konkret to cała wartość, a „w pośpiechu, na telefonie, w trakcie spotkania” zmienia wszystko dalej. Jeśli chcesz odkrywania i budowy za jednym zamachem, pomiń shape i po prostu opisz powierzchnię — przepływ new-work prowadzi ten sam wywiad, a jeśli shape już przeszedł, użyje jego potwierdzonych odpowiedzi.
Evaluate
Dział zatytułowany „Evaluate”audit — czy to się trzyma
Dział zatytułowany „audit — czy to się trzyma”Techniczny odpowiednik critique: tam, gdzie critique pyta „czy to dobrze działa na odbiorcę”, audit pyta „czy to się trzyma”. Skanuje pięć wymiarów — dostępność (kontrast WCAG, ARIA, nawigacja klawiaturą, etykiety formularzy), wydajność, theming (zahardkodowane kolory, pokrycie dark mode), zachowanie responsywne i anty-wzorce (te same deterministyczne sprawdzenia, które wykonuje detektor) — punktuje każdy 0–4 i taguje każde znalezisko od P0 (blokuje release) do P3 (szlif). Wraca jeden dokument, który można wkleić do trackera.
Decyzja projektowa warta zapamiętania: audit dokumentuje, nie naprawia. P0 kierujesz do harden, znaleziska wydajnościowe do optimize, resztę do polish. Na projekcie natywnym pięć webowych wymiarów wymienia się na zachowanie VoiceOver/TalkBack, Dynamic Type, platformowe minima celów dotykowych i zgodność z HIG/Material 3. Klasyczny błąd to pomijanie wymiarów, które „na pewno są w porządku” — theming i responsywność zwykle nie są.
critique — szczera druga opinia
Dział zatytułowany „critique — szczera druga opinia”Do pracy funkcjonalnie skończonej, gdy pytanie brzmi „czy to jest w ogóle dobre”. Critique uruchamia dwie niezależne oceny równolegle, żeby się wzajemnie nie skrzywiały: przegląd LLM (dziesięć heurystyk Nielsena punktowanych 0–4, licznik obciążenia poznawczego z ośmiu pozycji, emocjonalna podróż przez flow, zgodność z brandem z PRODUCT.md) oraz deterministyczny detektor. Testuje też przez soczewki person — „oceniający, porównujący nas z dwiema alternatywami we wtorkowy wieczór”, „sceptyk, który widział każdy SaaS-owy landing i się nudzi” — każda punktuje stronę osobno.
Scalony raport daje werdykt AI-slop (pass/fail z konkretnymi znamionami), punktacje heurystyk, trzy do pięciu priorytetowych problemów z „co/dlaczego/jak naprawić” oraz — część, którą według dokumentacji ludzie niesłusznie pomijają — prowokacyjne pytania, których interfejs sam nie rozstrzygnie, a które zwykle zmieniają projekt najmocniej. Nie uruchamiaj go na pracy w połowie drogi (punktuje wtedy nieskończoność, nie jakość) i traktuj wyniki diagnostycznie, nie jak ocenę.
animate — ruch, który komunikuje
Dział zatytułowany „animate — ruch, który komunikuje”Dla interfejsów, w których zmiany stanu są natychmiastowe i szarpane, a użytkownik nigdy do końca nie ufa, że jego klik zadziałał. Znajduje statyczne momenty wymagające ruchu — wejścia i wyjścia (fade 200–300 ms z subtelnym Y lub skalą), feedback stanów (hover, focus, ładowanie, sukces), przejścia między widokami, postęp — i aplikuje je z żelazną dyscypliną: easing zawsze wykładniczy ease-out („prawdziwe obiekty wyhamowują płynnie”), animowane są wyłącznie transform i opacity, a wysokość przez grid-template-rows.
Najciekawsze jest to, czego odmawia: poproś o sprężynki albo elastyczne odbicia „dla energii”, a ich nie dostaniesz — to dekoracja, a bounce easing to dosłownie reguła detektora. Każda animacja wychodzi z fallbackiem prefers-reduced-motion, bez negocjacji. To nie pokrętło: „więcej animacji” nie jest prośbą, którą honoruje.
bolder — od bezpiecznego do zdecydowanego
Dział zatytułowany „bolder — od bezpiecznego do zdecydowanego”Dla interfejsów wyglądających jak każdy inny: generyczny sans, średnie grubości, miękkie cienie, nieśmiały akcent, do zapomnienia. Bolder wzmacnia cztery osie — skalę (typografia display pchnięta do clamp(3rem, 6vw, 6rem) i dalej), kontrast grubości (300 przeciw 800 zamiast medium przeciw regular), zobowiązanie kolorystyczne (akcent w pełnej sile, tła, które zajmują stanowisko) i pewność kompozycyjną (asymetria, wyjście poza siatkę, skoki skali).
Jego zasada rdzenna: nie dodaje, tylko wzmacnia to, co już jest — projekt z trzema kolorami nie dostaje czwartego, dostaje mocniejsze zobowiązanie do tych trzech. A od v3.9, przy obecnym DESIGN.md, trzyma się twojego design systemu i pyta, zanim go poszerzy. Nie uruchamiaj go na dashboardach ani narzędziach operatorskich („śmiałość zarabia na swoje miejsce na stronach marketingowych, momentach hero i treściach”), a jeśli wynik krzyczy, zaprojektowaną kontynuacją jest quieter.
colorize — kolor strategiczny, nie tęcza
Dział zatytułowany „colorize — kolor strategiczny, nie tęcza”Przeciwwaga dla „wszystko jest szare”. Odczytuje twój kolor brandowy, daje akcji podstawowej jego najsilniejszy wyraz, wyprowadza stonowane warianty dla akcentów drugorzędnych i — najsprytniejszy ruch — barwi neutralne w stronę odcienia brandu przy chromie 0,005–0,01: niewidoczne piksel po pikselu, ale spaja całą stronę podprogowo.
Pracuje w OKLCH zamiast HSL, więc równe kroki jasności wyglądają na równe, a chroma automatycznie spada przy ekstremach — „kolor, który wygląda na przemyślany, a nie wyliczony”. Typowy diff: brandowy hex staje się --color-accent: oklch(62% 0.18 240), serie wykresów dostają trzy odrębne odcienie o wyrównanej jasności, żeby żadna wizualnie nie dominowała. Potrzebuje odcienia startowego (zapyta, jeśli nie ma go w PRODUCT.md) i wyłącznie dodaje — interfejs już jarmarczny potrzebuje najpierw quieter.
delight — osobowość, która przetrwa usunięcie
Dział zatytułowany „delight — osobowość, która przetrwa usunięcie”Skill wykańczający, nigdy pierwszy na nowym buildzie. Poluje na miejsca, które projektanci pomijają: puste stany („Twój dashboard jest cichy. Naprawmy to.”), momenty ładowania (trzyetapowy komunikat postępujący wraz z synchronizacją), feedback sukcesu (jednorazowy toast z celebracją — potem już tylko cichy znacznik), mikroteksty i easter eggi nagradzające uwagę.
Działają tu dwie zasady. Czyta ton brandu z PRODUCT.md i się do niego dopasowuje — kliniczne narzędzie analityczne dostaje suchą, precyzyjną błyskotliwość, nie żarty. I każdy moment delight musi działać perfekcyjnie także po usunięciu delight: nic funkcjonalnego nie zależy od uśmiechu. Jest celowo konserwatywny — jeden moment radości zapada w pamięć, dwadzieścia staje się szumem.
layout — odstępy, rytm, hierarchia
Dział zatytułowany „layout — odstępy, rytm, hierarchia”Dla stron, na których nic nie jest technicznie złe, ale nic też nie oddycha: równy padding wszędzie, monotonne siatki, hierarchia oparta na samym rozmiarze. Ocenia pięć wymiarów — spójność skali odstępów (czy są przypadkowe 13-pikselowe szczeliny), hierarchię wizualną (czy oko ląduje na akcji podstawowej w dwie sekundy), siatkę i wyrównanie, rytm (czy strona przeplata ciasne z hojnym, czy wszystko jest jednostajne) oraz gęstość.
Typowe poprawki: skala odstępów ujednolicona do 8/16/24/48/96, dekoracyjne obramowania zastąpione grupowaniem przez odstępy, akcje podstawowe wyciągnięte z flow z realnym buforem. Najcenniejsze, co może ci powiedzieć, jest zarazem najtrudniejsze do usłyszenia: jeśli werdykt brzmi „nic nie jest podstawowe”, żadna korekta odstępów tego nie naprawi — potrzebujesz decyzji o treści.
overdrive — jeden nadzwyczajny moment
Dział zatytułowany „overdrive — jeden nadzwyczajny moment”Przepustka do technicznej ambicji: hero na WebGL-owym shaderze, tabela obsługująca milion wierszy, dialog morfujący ze swojego przycisku, kinowe View Transitions. Dyscyplina polega na tym, że wybiera jeden moment i się mu poświęca, zamiast rozsmarowywać efekt po całym interfejsie — a wszystko jest budżetowane, profilowane w 60 fps i wysyłane z fallbackami reduced-motion.
Swój output ogłasza banerem ──── ⚡ OVERDRIVE ────, żebyś wiedział, że wchodzisz w ambitniejszy tryb: spodziewaj się większych diffów, nowych zależności i głębi implementacji ponad pozostałe polecenia. Działa, bo jest rzadki — „jeśli każda strona ma kinowe momenty, żaden nie jest kinowy” — i jest jawnie zły dla narzędzi operatorskich, gdzie niezawodność bije spektakl.
quieter — ścisz bez gubienia sensu
Dział zatytułowany „quieter — ścisz bez gubienia sensu”Przeciwwaga dla bolder, dla interfejsów krzyczących na cały regulator: neon na ciemnym, tekst gradientowy, sześć kolorów akcentowych, wszystko animowane. Redukuje wzdłuż czterech osi — kolor (do jednego koloru podstawowego plus stonowane wsparcie, desaturacja w OKLCH), kontrast (czysta biel i czerń ściągnięte do papieru i atramentu), dekorację (cienie i obramowania bez zadania usunięte) i ruch (spowolniony, bez auto-odtwarzania).
Obietnica odróżniająca go od hurtowego „zrób minimalistycznie”: zachowuje intencję. „Jeśli oryginał miał punkt widzenia, wersja cichsza ma ten sam punkt widzenia z większą pewnością — doszlifowanie, nie neutralizacja.” Diagnostyczna wskazówka z dokumentacji: „zbyt zatłoczone” zwykle znaczy za dużo rzeczy, czyli robota dla distill; quieter naprawia zbyt głośno.
typeset — typografia, która wygląda na zaprojektowaną
Dział zatytułowany „typeset — typografia, która wygląda na zaprojektowaną”Dla tekstu wyglądającego jak typografia domyślna: mętna hierarchia, trzy rozmiary czytające się tak samo, body 14 px, „font display”, który jest po prostu pogrubionym Interem. Ocenia dobór fontów (czy siedzisz na niewidzialnych domyślnych — Inter, Roboto, Arial), hierarchię (co najmniej 1,25× między krokami), spójność skali, czytelność (45–75 znaków w linii, minimum 16 px dla body) i konsekwencję (zero jednorazowych nadpisań font-size).
Rozróżnienie warte kradzieży, nawet jeśli nigdy nie uruchomisz polecenia: buduje stałe skale rem dla UI aplikacji i płynne skale clamp dla stron marketingowych — płynna typografia należy tam, gdzie długość linii dramatycznie się zmienia, nie na ekranie ustawień. Propozycje fontów biorą się z głosu brandu w PRODUCT.md; bez init będą generyczne.
Simplify
Dział zatytułowany „Simplify”adapt — inny kontekst, te same funkcje
Dział zatytułowany „adapt — inny kontekst, te same funkcje”Do przenoszenia projektu solidnego w jednym kontekście tak, żeby działał w innym: mobile z desktopu, tablet z mobile, druk z weba, e-mail z dashboardu. Pracuje przez breakpointy i płynny layout, cele dotykowe (minimum 44 px, strefy dotyku większe niż wizualne granice), wzorce nawigacji (sidebary stają się dolną nawigacją, stany hover dostają dotykowe odpowiedniki) i priorytet treści (co zostaje widoczne, co się zwija, co znika).
Zasada nienegocjowalna siedzi w nazwie: adaptuj, nie amputuj — jeśli wersja mobilna ukrywa to, co potrafi desktop, to regres, nie adaptacja. A mobile to nie mniejszy desktop, tylko inny kontekst („kciuki, przerywanie, krótkie sesje”). Na projektach natywnych wymienia cały słownik: telefon-tablet, konwencje jednej platformy na drugą. Dokumentacja zaleca po nim harden — responsywne layouty ujawniają przypadki brzegowe widoczne dopiero przy 320 px.
clarify — słowa, które tłumaczą się same
Dział zatytułowany „clarify — słowa, które tłumaczą się same”Dla tekstu interfejsu, przy którym ludzie się zatrzymują i myślą. Przepisuje powierzchnie, na których copy UX naprawdę zawodzi: etykiety i podpowiedzi (bezpośrednie, konkretne), teksty przycisków (czasownik na początku, opisuje wynik), komunikaty błędów (co poszło nie tak, czyja to wina, co zrobić dalej — nigdy nie obwinia użytkownika), puste stany (zorientuj, wyjaśnij, zaproponuj następny krok), tooltippy (dodają to, czego etykieta nie uniesie, nigdy jej nie powtarzają) i dialogi potwierdzenia (nazywają konsekwencje).
Przykłady przed/po mówią wszystko: „Invalid input” staje się „Numer karty ma 15 cyfr. Wpisałeś 14.”, a „Submit” — „Pobierz 29 USD i subskrybuj”. Głos stroi się do odbiorcy z PRODUCT.md — czytelnik techniczny dostaje precyzję, momenty lękowe (płatność, usuwanie) dostają otuchę. Dwie granice: to narzędzie do funkcjonalnego tekstu UX, nie do copy marketingowego; a jeśli tekst już jest jasny, chcesz delight, nie błyskotliwszej wersji.
distill — bezwzględne odejmowanie
Dział zatytułowany „distill — bezwzględne odejmowanie”Zaczyna od jednego pytania: jaka jest ta jedna robota, którą ten interfejs próbuje wykonać? Wszystko, co jej nie służy, ląduje na pieńku. Pracuje w dwóch przebiegach — nazwij źródła złożoności (za dużo elementów, nadmierna wariacja, szum wizualny, pełzanie funkcji), potem redaguj bezlitośnie: usuń, połącz, schowaj za rozwinięciem, skonsoliduj wariacje do jednego traktowania.
Typowy przebieg zwija cztery style kart do jednego, degraduje dwa z trzech wariantów przycisków do linków tekstowych i przegrupowuje 14-elementowy sidebar z pięciu sekcji do trzech. Zasada brzmi „mniej przeszkód, nie mniej funkcji” — distill usuwa to, co przeszkadza, nigdy to, na czym użytkownicy polegają codziennie. Timing ma znaczenie: uruchamiaj po tym, jak critique zgłosi obciążenie poznawcze, ale nie gdy feature wciąż rośnie, bo za tydzień będziesz destylował to samo.
harden — dzień, w którym interfejs spotyka rzeczywistość
Dział zatytułowany „harden — dzień, w którym interfejs spotyka rzeczywistość”Prawdziwe dane użytkowników są brudne: 60-znakowe nazwiska, niemieckie tytuły produktów, ceny w miliardach, błędy 500, tryby offline, tekst od prawej do lewej. Harden pracuje przez cztery wymiary — ekstrema tekstu i danych, scenariusze błędów (awarie sieci, 4xx/5xx, limity, operacje współbieżne), internacjonalizację (niemiecki bywa ~30% dłuższy od angielskiego; daty, waluty, RTL) i kontekst urządzenia (dotyk, wolne łącza, tryb oszczędzania energii) — i dla każdego znalezionego trybu awarii aplikuje konkretną poprawkę.
Typowy przebieg na stronie profilu: ellipsis z tooltippem na .user-name, bio przełączone na max-height z rozwinięciem „pokaż więcej”, dodany pusty stan, skeleton loader na asynchroniczny avatar, test przy długościach nazwiska 1/20/60/200. Uruchamiaj per strona, nie wszystko naraz — i nie pomijaj i18n, bo „na razie jesteśmy tylko po angielsku”: layouty bezpieczne dla i18n to po prostu lepsze layouty.
onboard — ścieżka do momentu aha
Dział zatytułowany „onboard — ścieżka do momentu aha”Wszystko zaczyna się od jednego pytania: co jest momentem aha i jak szybko nowy użytkownik może do niego dotrzeć? Projektuje powierzchnie decydujące o retencji — pierwsze uruchomienie (tour, puste płótno czy wypełniony przykład do modyfikacji), puste stany (gdzie jestem, czemu tu pusto, co robić dalej), setup (zminimalizowane pola, mądre domyślne, każdy krok tłumaczy po co), progresywne odkrywanie i zdarzenia aktywacji, oprzyrządowane i celebrowane po cichu.
Jawnie opiera się dwóm domyślnym trybom porażki: przetutorializowanej karuzeli, którą użytkownicy przeklikują, zanim czegokolwiek dotkną („większość produktów nie potrzebuje toura, potrzebuje lepszego pierwszego ekranu — toury to proteza”), i zerowemu onboardingowi, który wrzuca ludzi do pustej aplikacji. Jeśli nie umiesz w jednym zdaniu powiedzieć, co użytkownik ma poczuć w pierwsze 60 sekund, dokumentacja odsyła cię najpierw do shape.
optimize — wydajność z paragonami
Dział zatytułowany „optimize — wydajność z paragonami”Dla interfejsów, które czuć jako wolne: późny pierwszy paint, szarpiący scroll, bundle 800 KB. Pracuje przez pięć wymiarów — Web Vitals (LCP, INP, CLS), rendering (zbędne re-rendery, layout thrash), właściwości animacji, obrazy (lazy loading, srcset, AVIF, wymiary przeciw CLS) i rozmiar bundle’a (martwy kod, brakujący code-splitting).
Wiarygodność bierze się z księgowości: mierzy przed i po, kwantyfikuje każdą poprawkę i wycofuje zmiany, które nie ruszają metryki. Output czyta się jak rejestr — „LCP: 3,2 s → 1,4 s: preload obrazu hero (−800 ms), usunięty blokujący render arkusz fontów (−240 ms)”. Wie też, kiedy przestać: przy LCP 1,1 s i INP 80 ms mówi ci, że praca projektowa znaczy więcej.
polish — ostatni przebieg przed wysyłką
Dział zatytułowany „polish — ostatni przebieg przed wysyłką”Poluje na drobiazgi oddzielające wysłane od doszlifowanego: półpikselowe rozjazdy, zapomniane stany focus, migające przejścia ładowania, ton copy, który dryfuje. Najpierw odkrywa twój design system, potem pracuje przez sześć wymiarów — wyrównanie i odstępy, typografia (wdowy, kerning), kolor i kontrast, stany interakcji (hover, focus, active, disabled, loading, error, success — każdy rozliczony), ruch i copy — a przy okazji ściąga zdryfowane feature’y z powrotem do systemu, zamieniając zahardkodowane wartości na tokeny, a jednorazowe komponenty na współdzielone.
Dokumentacja definiuje, jak wygląda zdrowy przebieg, i to znamienne: „pięć małych poprawek, zero przepisywania”. Jeśli polish zamienia się w przemeblowanie layoutu, potrzebowałeś critique albo layout — a że polish łapie problemy z czucia, podczas gdy audit te mierzalne, przedwysyłkową parą są oba.
init — wywiad, który czyta wszystko inne
Dział zatytułowany „init — wywiad, który czyta wszystko inne”Uruchamiany raz na start (i ponownie, gdy zmienia się pozycjonowanie). Najpierw skanuje kod — README, package.json, komponenty, tokeny, zasoby brandu — i zamienia to w hipotezę zamiast ankiety, cytując z powrotem, co wywnioskował („z route’ów i pakietu Swift wynika, że to aplikacja iOS — zgadza się?”), i zadając najwyżej trzy pytania na rundę: kto jest głównym użytkownikiem i w jakiej sytuacji, co produkt umożliwia, czego sąsiad nie mógłby zgodnie z prawdą skopiować, oraz jakie trwałe ograniczenia i dowody przyszła praca musi zachować.
Kształtują go dwie celowe odmowy. Nie zapyta o estetykę — żadnych kolorów, fontów, referencji; te decyzje należą do pracy projektowej, gdzie powierzchnia i jej kierunek rozstrzygają się razem. A jego sekcja „Evidence on hand” zapisuje, co jest prawdziwe (łącznie z brakami: „na razie zero logotypów klientów, nie wymyślaj żadnych”), więc nic dalej nie sfabrykuje ściany logotypów ani zmyślonej metryki. PRODUCT.md zostaje czysto strategiczny; system wizualny mieszka w DESIGN.md, którego wygenerowanie init oferuje na końcu.
document — twój design system w formacie, który narzędzia sparsują
Dział zatytułowany „document — twój design system w formacie, który narzędzia sparsują”Skanuje kod w kolejności priorytetów — właściwości niestandardowe CSS, config Tailwinda, motywy CSS-in-JS, pliki tokenów, źródła komponentów, style wyliczone z wyrenderowanej strony — i zadaje dokładnie jedno zgrupowane pytanie o to, czego skan nie wywnioskuje: czemu ten system służy, łącznie z nazwaną metaforą całości („The Editorial Sanctuary”) i opisowymi nazwami kolorów („Deep Muted Teal-Navy”, nie „blue-800”).
Wynik trzyma się formatu DESIGN.md Google Stitch: dokładnie sześć sekcji (Overview, Colors, Typography, Elevation, Components, Do’s and Don’ts) z nagłówkami stałymi co do znaku, żeby inne narzędzia świadome DESIGN.md mogły plik sparsować, plus sidecar .impeccable/design.json zasilający Live Mode i design-aware reguły detektora. Plik jest przede wszystkim dla AI — jego stanowczy rejestr „never/always” jest zamierzony. Na świeżym projekcie bez kodu document --seed zadaje pięć pytań strategicznych i pisze uczciwy szkielet oznaczony <!-- SEED -->; fałszywa pełna specyfikacja jest gorsza niż żadna.
extract — gdy twój kod przypadkiem stał się design systemem
Dział zatytułowany „extract — gdy twój kod przypadkiem stał się design systemem”Na moment, w którym zauważasz ten sam styl przycisku w dwunastu miejscach i hexy rozsiane wszędzie. Wykonuje trzy kroki: odkryj dryf (powtarzające się wartości, warianty przycisków, odstępy przypadkiem pasujące do skali), zaproponuj prymitywy (nazwy tokenów, API komponentów z wariantem i rozmiarem) i zmigruj miejsca wywołań w tym samym przebiegu — ekstrakcja bez migracji tworzy tylko trzeci sposób robienia tego samego.
Jego powściągliwość to feature: ekstrahuje wyłącznie to, co użyte trzy lub więcej razy z tą samą intencją — „dwa użycia to nie wzorzec” — i nigdy „bo może się kiedyś przydać”, bo przedwczesna abstrakcja jest gorsza od duplikacji. Typowy przebieg: 14 instancji przycisków w 8 plikach staje się jednym komponentem Button z czterema wariantami, ~180 linii zduplikowanego CSS znika, dochodzą trzy brakujące tokeny.
live — przeglądarka jako płótno
Dział zatytułowany „live — przeglądarka jako płótno”Omówiony szczegółowo niżej — w skrócie: wskaż element na działającym serwerze deweloperskim, oznacz chipem, wolnym tekstem, pinezką albo kreską, a dostaniesz trzy produkcyjnej jakości warianty podmienione przez HMR, każdy zakotwiczony w naprawdę innym archetypie. Zaakceptuj jeden, a zapisze się do prawdziwego źródła.
Kluczowa rzecz do zrozumienia to zakres: Live Mode iteruje na jednym wskazanym elemencie. Na „przerób całą stronę cennika” rozmawiaj bezpośrednio z /impeccable. A jeśli liczy się zgodność z brandem, miej najpierw PRODUCT.md i DESIGN.md — DESIGN.md wygrywa w decyzjach wizualnych, PRODUCT.md w głosie, a bez nich warianty dryfują ku generycznym domyślnym.
Nowe buildy w v4: kierunek z kości
Dział zatytułowany „Nowe buildy w v4: kierunek z kości”Sztandarowa zmiana v4 dotyczy tego, jak Impeccable obsługuje nową pracę — greenfield, nową stronę, redesign. Zaczyna się od pomiaru: poproś model kodujący o coś kreatywnego, a zbuduje swój ulubiony pomysł, za każdym razem. W kampanii badawczej v4 (~200 próbkowanych konceptów, 2600 USD ewaluacji) 30 z 35 odpowiedzi wróciło jako identyczny koncept, nawet gdy prośbę sformułowano na szesnaście różnych sposobów. Modelom nie brakuje kreatywności, konkludują autorzy — brakuje im wariancji.
Rozwiązaniem jest odebranie wyboru kierunku rankingowi samego modelu:
-
Klasyfikacja. Opisujesz pracę konwersacyjnie (
/impeccable redesign the marketing site). Impeccable rozpoznaje rodzaj zadania — czysta karta, nowa strona w istniejącym produkcie, sekcja dodana do działającej strony, redesign albo wąska poprawka — i każdy dostaje inną ilość swobody. Dodatek dziedziczy wygląd otaczającej strony i decyduje tylko o tym, co sam wnosi; redesign traktuje stary wygląd jako materiał dowodowy do zastąpienia, a nie coś do polerowania. -
Rzut. Model wyprowadza ugruntowane kierunki z twojego produktu, a zewnętrzny seed rozdaje obok nich sześć „światów”-pretendentów z talii 188 ręcznie zatwierdzonych systemów graficznych (z 360 zrecenzowanych) — portrety danych Du Bois, tablice split-flap, czołówki Saula Bassa. Światy to pretendenci, nie szablony: przejmują build tylko wtedy, gdy pokonają kierunki wyprowadzone z produktu na merytorycznych zasadach. Każdy rzut drukuje klucz, który go odtwarza.
-
Ty decydujesz. W sesji z użytkownikiem Impeccable otwiera stronę decyzyjną: jeden zadeklarowany kierunek na czele, pretendenci jako alternatywy. Możesz zaakceptować, przelosować („deal again” — bez duplikatów) albo sterować jedną linijką („zbyt korporacyjnie”). Przypięty przez ciebie kierunek zawsze wygrywa, twoje jawne wybory („katalog hi-fi z lat 70., Futura”) blokują się i nadpisują wszystko, a odrzucenie całości jest pełnoprawną odpowiedzią — nic nie zostanie zbudowane, dopóki nie wybierzesz.
-
Narysowane przed zbudowaniem. Wybrany kierunek zostaje narysowany jako tablica design systemu (paleta, typografia, charakter komponentów) i makieta pierwszej powierzchni w realnym viewporcie, a build jest potem korygowany względem tych obrazów. Twój harness nie ma natywnego narzędzia graficznego? Ustaw
OPENAI_API_KEY, a wyrenderuje przez gpt-image-2, uprzedzając najpierw, że obciąży twój klucz. -
Kontrakt, potem kontrola. Przed kodem agent zapisuje pięcioblokowy kontrakt (teza, własny świat, historia, pierwszy viewport, forma — maksymalnie 150 słów) w otwierającym komentarzu artefaktu. Recenzja końcowa audytuje potem wynik względem niego, obietnica po obietnicy, we własnym subagencie tam, gdzie harness na to pozwala.
Kandydujące kierunki muszą też przejść pięć testów, zanim trafią do rozdania: Truth (relacje istnieją w prawdziwym produkcie), Translation (działa niezależnie od stylistyki źródła), Consequence (usunięcie najlepszego elementu osłabia stronę), Survival (działa na różnych urządzeniach i budżetach) i Fit (uczciwe kompromisy względem briefu). Pełna metodologia — łącznie z tym, dlaczego „wygeneruj pomysły i wybierz najlepszy” załamuje się na etapie selekcji, a nie ideacji — jest opisana na impeccable.style/research.
Live Mode
Dział zatytułowany „Live Mode”/impeccable live zamienia iterację w sesję przeglądarkową względem twojego działającego serwera deweloperskiego. Na porcie 8400 startuje helper, wstrzykuje picker do twojego dev entry, a na dole strony pojawia się mała pigułka:
- Wskaż element. Pojawia się pasek kontekstu: wybierz chip polecenia (
bolder,typeset,layout, …), wpisz dowolną instrukcję („more playful”, „less SaaS”), upuść pinezki z komentarzami na konkretne fragmenty (pinezka przy tytule dotyczy tytułu, nie całego elementu) albo rysuj kreski — zamknięta pętla oznacza ważność, strzałka kierunek, krzyżyk usunięcie. - Generuj. Trzy naprawdę różne warianty renderują się w miejscu, każdy zakotwiczony w innym archetypie —
colorizedaje trzy rodziny barw,animatetrzy słowniki ruchu,layouttrzy układy strukturalne. Przełączaj je strzałkami. - Zaakceptuj (Enter), a wariant zapisze się z powrotem do prawdziwego pliku źródłowego, z CSS skonsolidowanym do rzeczywistego arkusza stylów projektu, a nie zostawionym inline. Escape odrzuca wszystkie trzy.
Działa z każdym serwerem deweloperskim z hot-module reload — Vite, Next.js, SvelteKit, Astro, Nuxt, Bun, TanStack (Router i Start od v4.0.2) — albo ze zwykłym plikiem HTML. Ma etykietę beta: solidne na typowych ścieżkach, z przypadkami brzegowymi na nietypowych konfiguracjach. Na aplikacjach ze ścisłym CSP wykrywa blokadę i proponuje jednorazową, wyłącznie deweloperską łatkę chronioną warunkiem NODE_ENV === "development". Jeśli port zostanie zajęty, /impeccable live stop go zwalnia.
Critique z nakładką wizualną
Dział zatytułowany „Critique z nakładką wizualną”/impeccable critique the pricing page at localhost:3000/pricing uruchamia dwie niezależne oceny równolegle: przegląd LLM (dziesięć heurystyk Nielsena, checklista obciążenia poznawczego, zgodność z brandem czytana z PRODUCT.md) oraz deterministyczny detektor. Na harnessach z automatyzacją przeglądarki otwiera stronę z nakładką, która obrysowuje każde znalezisko w miejscu, z pływającą etykietą nazywającą regułę — bez mapowania zrzutów ekranu na akapity, a po poprawce odświeżasz i patrzysz, jak obrys znika, więc nigdy nie wysyłasz poprawki, która reguły faktycznie nie spełniła.
Raport punktuje trzy warstwy: heurystyki (cel: średnia 3,5+/4), obciążenie poznawcze (cel: mniej niż 2 porażki na checkliście) i binarny werdykt AI-slop. Ta sama nakładka jest dostępna jako rozszerzenie Chrome — jeden klik na dowolnej stronie, bez udziału harnessu.
CLI detect: bramka anty-slop do CI
Dział zatytułowany „CLI detect: bramka anty-slop do CI”Niezależnie od poleceń harnessu Impeccable dostarcza deterministyczny detektor — bez LLM, bez klucza API — który możesz uruchomić gdziekolwiek:
npx impeccable detect src/ # folder źródełnpx impeccable detect index.html # pojedynczy pliknpx impeccable detect https://example.com # wyrenderowana stronacat component.css | npx impeccable detect # stdinnpx impeccable detect --json . # format maszynowyKatalog wzorców rośnie szybko: 44 reguły, gdy opisywaliśmy go po raz pierwszy, 64 wzorce dziś, z czego 59 jest egzekwowanych deterministycznie (pozostałe pięć to osądy, które zostają w przeglądzie LLM polecenia critique). Każda reguła jest oznaczona sposobem działania: CLI (statycznie, bez przeglądarki), Browser (deterministycznie, ale wymaga prawdziwego layoutu — działa przez rozszerzenie albo Puppeteera) lub LLM-only. Katalog, przeglądalny na impeccable.style/slop z jedenastoma syntetycznymi stronami slopu do wypróbowania nakładki, obejmuje dziewięć kategorii:
| Kategoria | Reguły | Smak |
|---|---|---|
| Twój design system | 4 | Font, kolor, promień lub rozmiar pisma dryfujący od DESIGN.md |
| Detale wizualne | 8 | Boczne paski akcentowe na kartach, dekoracyjne siatki, glassmorphism, hairline z poświatą |
| Typografia | 10 | Płaska hierarchia, kafelki ikon nad nagłówkami, italic-serifowe hero, nadużywane fonty (Inter, Geist, Instrument Serif) |
| Kolor i kontrast | 6 | Palety fiolet/cyjan, radialne halo, tekst gradientowy, odruchowe kremowo-beżowe tło |
| Layout i przestrzeń | 13 | Zagnieżdżone karty, monotonne odstępy, za długie linie, overflow, przycięte popovery |
| Ruch | 6 | Pulsujące kropki statusu, migające sztuczne kursory, marquee, sprężynujący easing, animowanie właściwości layoutu |
| Copy | 5 | Nadużycie półpauz, marketingowe buzzwordy, aforystyczna kadencja, framing „teatru” |
| Obrazy | 2 | Hero sklejone z generycznych kształtów, zepsute lub placeholderowe obrazki |
| Jakość ogólna | 10 | Porażki kontrastu, ciasny padding, niezłapane błędy skryptów, treść uwięziona na opacity: 0 |
Pierwsza kategoria jest najciekawsza: z DESIGN.md w projekcie detektor przestaje być generyczny i zaczyna flagować dryf od twojego własnego systemu — font spoza udokumentowanego stacka, literalny kolor spoza palety, promień spoza skali kształtów.
Kończy się kodem 0 przy czystym wyniku, 2 przy znaleziskach, 1 przy błędzie, co wpada prosto w sprawdzenie PR. Zamierzone wyjątki nie muszą walczyć z bramką: zarządzaj nimi przez npx impeccable ignores list|add-value|add-file (zapisywane w .impeccable/config.json, z uzasadnieniami) albo inline:
/* impeccable-disable-next-line bounce-easing */Czyta JSX, TSX, Vue, Svelte, Astro, CSS i HTML od ręki, a szablony server-side (Blade, ERB, Twig, Handlebars), jeśli podasz ich rozszerzenia w configu. Przydatne flagi: --scope type zawęża do jednej domeny, --no-design-system pomija reguły spersonalizowane, --no-config działa na surowo. Jedno uczciwe ograniczenie: silnik czyta HTML i CSS, więc nie ma nic do powiedzenia o natywnym kodzie iOS ani Androida.
Hooki projektowe: detektor na autopilocie
Dział zatytułowany „Hooki projektowe: detektor na autopilocie”Zamiast pamiętać o uruchamianiu detect, możesz kazać mu działać automatycznie przy każdej edycji pliku UI przez agenta. /impeccable hooks on instaluje natywny dla providera manifest hooka — .claude/settings.local.json dla Claude Code, .github/hooks/impeccable.json dla Copilota (CLI i agent chmurowy), .codex/hooks.json dla Codexa, .cursor/hooks.json dla Cursora. Claude Code, Copilot i Codex sprawdzają po każdej edycji; Cursor recenzuje proponowane zapisy, zanim wylądują, i może je zablokować.
Sprytna część to raportowanie dwubiegowe. Nękanie modelu każdą regułą przy każdej edycji mierzalne skłaniało go do grania zachowawczo, więc sprawdzenia per edycja pokazują teraz tylko to, co jest obiektywnie zepsute — porażki kontrastu, wylewający się tekst, zepsute obrazki, poświatę, dryf od twojego własnego design systemu — a cała reszta czeka na jeden pełny przebieg po wszystkich dotkniętych plikach UI na końcu sesji. (Ustaw hook: { "perEditRules": "all" }, jeśli chcesz z powrotem pełny strumień.)
Steruj nim przez /impeccable hooks status|on|off, zapisuj potwierdzone wyjątki przez /impeccable hooks ignore-value overused-font Inter --shared --reason "Font brandowy" i konfiguruj pod kluczem hook w .impeccable/config.json (enabled, quiet, auditLog na debugowy log NDJSON). IMPECCABLE_HOOK_DISABLED=1 wyłącza go na jedną sesję shella.
Doctor: utrzymywanie starszego projektu w aktualności
Dział zatytułowany „Doctor: utrzymywanie starszego projektu w aktualności”v4 zmieniło zawartość PRODUCT.md, więc projekty skonfigurowane pod v3 noszą odpowiedzi, których bieżąca wersja już nie czyta. Impeccable uruchamia teraz tanie sprawdzenie świeżości na starcie sesji (każde znalezisko zgłaszane najwyżej raz w tygodniu; "stalenessCheck": false je wyłącza) i oferuje /impeccable doctor jako głęboki przebieg: ile pracy nad UI wyjechało od ostatniego dotknięcia DESIGN.md, ignorowane reguły detektora, które już nie istnieją, hook, którego ścieżka skryptu przestała się rozwiązywać i który nic nie skanuje, choć wygląda na zainstalowany. Mechaniczny dryf naprawia sam; decyzje wymagające osądu kieruje do init lub document z nazwaną konkretną luką. W monorepach drukuje tabelę, które aplikacje niosą własny kontekst, a które po cichu dziedziczą korzeń — łącznie z kosztownym w przeoczeniu przypadkiem aplikacji iOS dziedziczącej wytyczne wyłącznie webowe.
Natywny iOS i Android (alpha)
Dział zatytułowany „Natywny iOS i Android (alpha)”Jedna z najczęściej wnioskowanych funkcji wylądowała w v4 jako alpha: init rozpoznaje platformę z projektu, a na kodzie iOS, Android lub cross-platform ładuje regulamin Apple HIG albo Material 3 na wierzch wytycznych projektowych — audit i adapt stają się przebiegami natywnymi obejmującymi VoiceOver, TalkBack, cele dotykowe i zgodność z platformą zamiast CSS. Live Mode, detektor i hook projektowy czytają przeglądarkę albo parsują HTML, więc na projektach natywnych pauzują.
Kiedy po nie sięgnąć
Dział zatytułowany „Kiedy po nie sięgnąć”- Twój UI zbudowany przez AI jest funkcjonalny, ale generyczny i chcesz kierować konkretnymi poprawkami bez uczenia się dyrektorowania sztuką w prozie.
- Zaczynasz nową stronę albo redesign i chcesz, żeby wylądowały gdzie indziej niż ulubiony pomysł modelu — z kierunkiem zatwierdzanym przed kodem.
- Chcesz deterministycznej bramki jakości projektowej w CI (
detect) albo tego samego sprawdzenia działającego automatycznie przy każdej edycji agenta (hooki). - Polerujesz istniejący kod i potrzebujesz, by zmiany dziedziczyły twoje tokeny i komponenty, a nie z nimi walczyły.
Dla pełnej metodologii od projektu do kodu — makieta, prototyp, system projektowy, implementacja — Impeccable wpasowuje się w etapy budowy i polerowania czteroetapowego potoku projektowego, zamiast go zastępować. A tam, gdzie Impeccable audytuje projekt, shadcn/improve audytuje architekturę — to komplementarne skille.
Taste Skill od v4 pokrywa się z nim mocniej: oba ograniczają teraz generowanie z góry. Różnica leży w mechanizmie — Taste Skill narzuca jeden wyselekcjonowany kierunek z twardymi regułami; Impeccable wyprowadza kierunki z twojego produktu, rozdaje obok nich pretendentów i każe ci wybrać. Sięgnij po Taste Skill, gdy chcesz zdecydowanego stylu domu już przy pierwszym podejściu; po Impeccable, gdy chcesz wariancji ugruntowanej we własnym brandzie, plus słownika audytu i szlifu na wszystko później.