# Design system — PRODUCT.md, DESIGN.md, Impeccable

Ten plik to wejście do `/impeccable init` i `/impeccable document`. Zawiera
gotową treść obu plików kontekstowych, potwierdzone tokeny, system motion
„dokument urzędowy" (spójny w całej witrynie) oraz checklistę anty-slop
zawężoną do wzorców, na które ten konkretny projekt jest najbardziej narażony.

---

## 1. `PRODUCT.md` — wklej/wygeneruj i zatwierdź

```md
## Register
tax-advisory / professional services / trust-first landing site

## Platform
web (Next.js 16 SSR, Payload CMS 3 panel), responsywne od 360px do 4K,
PL i DE jako pełnoprawne wersje językowe (nie tylko tłumaczenie stringów UI)

## Users
Polacy pracujący w Niemczech (budowa, opieka, przemysł, sektor usługowy),
25-55 lat, rozliczają PIT/Einkommensteuererklärung raz w roku, często pierwszy
raz korzystają z doradcy podatkowego. Czytają po polsku, część zna niemiecki
na tyle, by porównać ofertę z niemiecką konkurencją (stąd wersja DE). Wchodzą
głównie z telefonu, często z linku od znajomego lub z Facebooka/grupy
polonijnej. Nieufni wobec formularzy z danymi osobowymi — WhatsApp jest dla
nich niższym progiem wejścia niż mail czy telefon.

## Product Purpose
Przekonać odwiedzającego w mniej niż 30 sekundach, że (a) to prawdziwa,
uprawniona firma (nie oszustwo), (b) obsługa jest w 100% po polsku,
(c) proces jest prosty i zdalny — i doprowadzić go do jednego działania:
napisania na WhatsApp. Strona to wizytówka + generator leadów, nie sklep,
nie panel klienta, nie blog (na start).

## Tone
Rzeczowy, spokojny, kompetentny — jak dobry doradca, nie jak reklama. Bez
zachwytów marketingowych („rewolucyjne", „najlepsze na rynku"). Konkret:
liczby, terminy ustawowe, realne dokumenty (Lohnsteuerbescheinigung, IdNr).
Zaufanie buduje precyzja, nie entuzjazm.

## Accessibility & Inclusion
WCAG 2.2 AA jako cel bazowy (patrz `wymagania-projektowe-strony.md` §4).
Duża część odbiorców to osoby starsze/niekorzystające na co dzień z
rozbudowanych interfejsów — tekst czytelny bez zoomu (min. 16px body),
kontrast pilnowany osobno dla ciepłego tła papieru (nie zakładaj, że jasne tło
= automatycznie OK), pełna obsługa klawiaturą, `prefers-reduced-motion`
respektowany na WSZYSTKICH animacjach z sekcji 4.
```

---

## 2. `DESIGN.md` — potwierdzenie tokenów już w `globals.css`

Impeccable powinien je wykryć sam przez `/impeccable document`. Poniższa
tabela to punkt odniesienia do weryfikacji wygenerowanego pliku — jeśli
wygenerowany `DESIGN.md` odbiega od tego, popraw go ręcznie przed dalszą pracą
(inaczej detektor „design system" będzie zgłaszał fałszywe alarmy).

### Kolor

| Token | Jasny motyw | Ciemny motyw | Użycie |
|---|---|---|---|
| `--bg-color` | `#F7F5F1` (ciepły papier) | `#17140F` | tło strony |
| `--fg-color` | `#1C1B1A` (atrament) | `#F5F1E8` | tekst podstawowy |
| `--card-color` | `#FFFFFF` | `#1F1B14` | karty, panele |
| `--border-color` | `#E2DDD3` | `#332C21` | linie, obramowania |
| `--accent-color` | `#A13D2C` (pieczęć) | `#D4634A` | CTA, linki, akcenty |
| `--accent-hover-color` | `#8A3324` | `#E17B62` | hover na akcencie |

Zasada: **maksymalnie jeden akcent** (pieczęć-czerwień). Żadnych dodatkowych
kolorów „na szybko" (niebieski link, zielony success) bez dopisania do
`DESIGN.md` — to jeden z 4 checków „Your design system" w Impeccable.

### Typografia

| Token | Wartość | Użycie |
|---|---|---|
| `--font-heading` | Fraunces (serif, wariant *opsz* wysoki dla nagłówków display) | H1–H3, cytaty |
| `--font-sans` | Public Sans | body, UI, nawigacja, przyciski |
| Skala | 16px body / 1.6 line-height minimum | patrz `wymagania-projektowe-strony.md` §4 — nie schodzić poniżej |

**Twardy zakaz z katalogu Impeccable:** brak kursywy jako domyślnego stylu
nagłówka display („italic serif display headline" — reguła #1 na liście
anty-slop, patrz sekcja 5). Fraunces ma piękną kursywę i pokusa jest duża —
używać jej WYŁĄCZNIE jako pojedynczego akcentu na jednym słowie w hero (np.
„**po polsku**" pochylone w podtytule), nigdy jako stylu całego H1.

### Kształt i głębia

| Token | Wartość |
|---|---|
| `--radius-button` | 6px (umiarkowane zaokrąglenie — NIE „pill", NIE 20px+ blob) |
| Karty | radius 8–10px, cień delikatny (`box-shadow` 1 warstwa, nie „hairline + wide shadow" — patrz sekcja 5) |
| Obramowania | 1px `--border-color`, nigdy grube kolorowe paski z boku karty |

### Motyw wizualny „dokument urzędowy" (charakter, nie tylko tokeny)

To jest to, co ma odróżnić tę stronę od typowego SaaS-landingu i uzasadnić
prompt „efekty pasujące do biura podatkowego" bez wpadania w kicz:

- **Tekstura papieru**: bardzo subtelny noise/grain na tle sekcji jasnych
  (opacity ~2-3%, `mix-blend-mode: multiply` lub SVG `feTurbulence` jako
  tło) — sugeruje fakturę papieru, nie plastik. Jeden globalny efekt, nie
  per-sekcja.
- **Linie jak w formularzu**: cienkie poziome linie `--border-color` jako
  separator sekcji zamiast pełnych kolorowych bloków tła — metafora liniatury
  dokumentu podatkowego.
- **Akcent „pieczęci"**: okrągły/owalny kształt w kolorze akcentu, używany
  OSZCZĘDNIE — np. jako tło pod floating-stat w hero (już jest w kodzie:
  `floatingStat`), jako marker przy cytatach klientów, jako obwódka wokół
  liczby „20+" w sekcji Stats. Nie na każdym elemencie.
- **Typografia numeryczna**: liczby (20+, 100%, §4 Nr. 11) w Fraunces, duże,
  z lekkim tabular-nums — czytają się jak wpis w rejestrze, nie jak KPI
  dashboardu.
- **Zdjęcia**: kolor, nie stockowy błysk korporacyjny — patrz `02-strona-glowna.md`
  §Hero i `05-o-nas.md` co do konkretnego kierunku (ciepłe światło, realne
  biuro/dokumenty, nie białe tło + uśmiech do kamery w garniturze).

---

## 3. Tryby stron (Impeccable dobiera automatycznie, ale potwierdź)

| Strona | Tryb | Uzasadnienie |
|---|---|---|
| Home, Usługi, Jak się umówić, Kontakt | **Persuade** | mają przekonać i doprowadzić do WhatsApp |
| O nas, Stowarzyszenie | **Persuade** (miękki) | budują zaufanie, ale bez twardego CTA co drugi ekran |
| FAQ, strony prawne | **Read** | czytelność i skanowalność ważniejsze niż perswazja — długie teksty, listy, akapity |
| Panel Payload (admin) | **Operate** | poza zakresem tego planu (panel dostarcza plugin), ale nie dotykać wizualnie |

---

## 4. System motion (spójny, jedna specyfikacja dla całej strony)

Zamiast wymyślać animacje per sekcja od zera w każdym pliku `02`–`09`, każdy z
tych plików odwołuje się do jednego z poniższych wzorców. To gwarantuje
spójność i chroni przed „motion slop" (reguły #48–53 w katalogu).

| Nazwa wzorca | Efekt | Kiedy używać | Kiedy NIE używać |
|---|---|---|---|
| `reveal-up` | Fade-in + translateY(16–24px), stagger dzieci co ~0.08–0.14s, ease `[0.22,1,0.36,1]` (już użyty w Hero — reużyj tę samą krzywą wszędzie) | wejście każdej sekcji przy scrollu (raz, `whileInView`, `viewport={{ once: true }}`) | nie powtarzać animacji przy każdym ponownym scrollu — meczy |
| `parallax-tilt` | Pointer-tracked rotateX/rotateY, już zaimplementowany jako `useParallax3D` w Hero | WYŁĄCZNIE hero — nie kopiować na każdą sekcję ze zdjęciem, bo traci efekt wyjątkowości | karty usług, avatary, ikony |
| `count-up` | Liczby w Stats (20+, 100%) liczą się od 0 do wartości docelowej przy wejściu w viewport, ~800ms, bez odbicia (`ease-out`, NIE elastic/bounce — reguła #52) | blok Stats na home | gdziekolwiek indziej |
| `line-draw` | Cienka linia (`--border-color` lub akcent) „rysuje się" (`stroke-dashoffset`) przy wejściu w viewport, jako separator lub podkreślenie nagłówka sekcji | separator między sekcjami zamiast twardej krawędzi | pod każdym nagłówkiem H2 z osobna — max 2-3 razy na stronę |
| `stamp-in` | Element „pieczęci" (floating stat, badge zaufania) pojawia się ze skalą 0.9→1 + rotate -3°→0°, ease-out, BEZ overshoot | floating stat w hero, badge „§4 Nr. 11 StBerG" | przyciski, pola formularza |
| `sticky-progress` | Cienka linia postępu czytania na górze strony (jak zakładka w dokumencie), tylko na stronach `Read` (FAQ, prawne) | FAQ, Impressum, Datenschutz | strony `Persuade` |

**Twarde zasady motion (z katalogu anty-slop, sekcja 5):**
- Zero pulsującej kropki statusu, zero migającego kursora, zero auto-scrolling
  marquee (loga/teksty), zero bounce/elastic easing na dialogach czy kartach.
- Zero „zoom on hover" na każdym zdjęciu z automatu — hover-zoom TYLKO tam,
  gdzie zdjęcie jest linkiem do czegoś (np. karta usługi), nigdy na zdjęciu Janusza
  w hero czy o-nas.
- Wszystkie animacje transform/opacity (nie animować `width`/`height`/`margin` —
  powoduje layout shift, reguła #51).
- `prefers-reduced-motion: reduce` → wszystkie warianty wyżej wyłączone,
  treść widoczna od razu (bez „utknięcia w opacity: 0" — reguła #56).

---

## 5. Checklista anty-slop — zawężona do realnego ryzyka tego projektu

Pełny katalog Impeccable ma 61 reguł w 9 kategoriach. Poniżej te, na które ten
konkretny brief (serif display font, dużo kart usług, dużo liczb, ciepła
paleta) jest szczególnie narażony — sprawdzić RĘCZNIE po każdym `/impeccable polish`,
niezależnie od automatycznego detektora:

| # | Ryzyko w tym projekcie | Dlaczego tu grozi | Test |
|---|---|---|---|
| Italic serif display headline | Fraunces zachęca do kursywy na całym H1 | H1 w hero i page-headerach ma być prosty, prosto stojący; kursywa max na 1 słowie |
| Cream/beige palette jako „domyślny wybór z automatu" | Nasze tło JEST ciepłe/kremowe | OK tylko dlatego, że jest to świadomy wybór spójny z metaforą „dokument" — ale reszta palety (akcent, kontrasty) musi być równie przemyślana, nie „zostawione domyślne" |
| Icon tile stacked above heading | ServicesList/ServicesDetailed mają ikony (fileText, calculator, shieldCheck...) | Ikona OBOK nagłówka albo bez zaokrąglonego „tile" w tle — nie kwadrat z zaokrąglonymi rogami nad każdym tytułem usługi |
| Identical card grids | 6-7 usług w ServicesDetailed, wszystkie tym samym wzorcem karty | Zróżnicować: pierwsza/najważniejsza usługa większa lub wyróżniona, reszta w siatce — nie 7× ta sama karta |
| Hero metric layout (duża liczba + mały label + statsy obok) | Blok Stats na home to dokładnie ten wzorzec (20+ / 100% / §4 Nr. 11) | Dopuszczalne TYLKO jeśli liczby mają realny kontekst (opis pod spodem już jest w danych) — nie ucinać opisów, nie zostawiać gołych liczb |
| Tiny numbered section labels (01/02/03) | Process ma 3 kroki | Numerować krokami z pełnym słowem („Krok 1"), nie małą cyfrą-ozdobnikiem obok nagłówka sekcji |
| Border accent / side-tab na kartach | Karty testimoniali, FAQ | Bez grubego kolorowego paska z boku — jeśli trzeba wyróżnić, użyć tła karty albo cienkiej górnej linii `line-draw`, nie side-tab |
| Nested cards | ContactInfo + PageHeader + karty usług mogą się złożyć w kartę-w-karcie | Maks. 1 poziom „karty" na sekcję |
| Generic marketing claims | Pokusa dopisania „najlepsza obsługa", „rewolucyjne rozliczenie" | Zero słów-wypełniaczy — patrz `PRODUCT.md` Tone. Każde zdanie ma nieść konkret (liczbę, termin, nazwę dokumentu) |
| Em-dash overuse | Ryzyko przy douzupełnianiu treści (FAQ, prawne) | Kropka między myślami, nie długi myślnik co zdanie |
| Gradient text / radial glow | Pokusa „unowocześnienia" hero przez glow za nagłówkiem | Zero gradientów na tekście, zero halo/spotlight za sekcją — kontrast i typografia robią robotę, nie poświata |

Procedura: po każdym `/impeccable polish` uruchom `npx impeccable detect` na
zbudowanej stronie, przejrzyj findings, DOPIERO wtedy przejdź przez tabelę
wyżej ręcznie (detektor łapie źródło/DOM, powyższe wymaga oceny projektowej —
kategoria „Design review" w Impeccable).