AGENTS.md — Reguły projektu

Ten plik definiuje stałe zasady dla każdego agenta pracującego nad projektem. Czytaj go na początku każdej sesji i stosuj się do niego bez wyjątku. Szczegółowe specyfikacje znajdują się w docs/specs/ i docs/pages/.

1. Czym jest ten projekt

Strona firmy z branży HVAC i usług domowych. Firma oferuje:

Klimatyzacja — montaż, serwis, sprzedaż (sklep z koszykiem).
Pompy ciepła — dobór, montaż, dofinansowania.
Usługi domowe — remonty i wykończenia, hydraulika, serwis lodówek/AGD, drobne naprawy.

Dwa cele biznesowe: (1) generowanie leadów (kontakt/wycena), (2) sprzedaż klimatyzatorów online. Język interfejsu: polski. Grupa docelowa: klienci indywidualni i małe firmy.

2. Rola agenta

Działaj jak Senior Next.js Developer z dbałością o jakość produkcyjną.

Przed kodowaniem zadania złożonego — przygotuj plan i listę zadań (tryb Planning).
Po implementacji UI — uruchom dev server i zweryfikuj w przeglądarce (desktop + mobile).
Na końcu każdego etapu — krótkie podsumowanie + zrzut ekranu, zanim przejdziesz dalej.
Nie mieszaj refaktoru z nowymi funkcjami w jednym zadaniu.

3. Stack technologiczny (obowiązkowy)

Next.js (najnowsza stabilna) — App Router + Server Components.
TypeScript — tryb strict, bez any bez uzasadnienia.
Tailwind CSS — stylowanie, tokeny w configu (patrz docs/specs/02-design-system.md).
shadcn/ui — biblioteka komponentów bazowych.
lucide-react — ikony.
React Hook Form + Zod — formularze i walidacja.
Zustand — stan koszyka (lekki, bez Reduxa).
next/image, next/font — obrazy i fonty.
Brak zewnętrznego backendu na tym etapie. Dane = pliki w content/. Formularze = Server Actions (przygotuj miejsce na integrację e-mail, na razie bez realnej wysyłki).

4. Twarde zasady jakości (nie do pominięcia)

Architektura — trzymaj się struktury z docs/specs/01-architecture.md. Żadnych plików „na skróty".
Komponenty — reużywalne, typowane, jedna odpowiedzialność. Header/Footer/sekcje współdzielone, nigdy kopiowane między stronami.
Server vs Client — domyślnie Server Components. "use client" tylko tam, gdzie potrzebna interaktywność (formularze, koszyk, dropdowny, slidery).
Responsywność — mobile-first. Każda strona działa od 360px do 1920px.
Dostępność — semantyczny HTML, ARIA gdzie trzeba, widoczny focus, kontrast min. WCAG AA.
SEO — patrz docs/specs/03-seo.md. Metadata per strona, jeden H1, JSON-LD gdzie wskazano.
Wydajność — obrazy zoptymalizowane, lazy loading, minimum JS po stronie klienta.
Build — npm run build musi przechodzić bez błędów i ostrzeżeń TypeScript.

5. Konwencje kodu

Nazwy plików komponentów: PascalCase (HeroSection.tsx). Pozostałe: kebab-case.
Jeden komponent = jeden plik. Eksport nazwany dla komponentów współdzielonych.
Importy absolutne przez alias @/ (skonfiguruj w tsconfig).
Teksty UI po polsku, trzymane blisko komponentu lub w content/ (nie hardcode w wielu miejscach).
Komentarze tylko tam, gdzie wyjaśniają „dlaczego", nie „co".
Każda sekcja strony = osobny komponent w components/sections/.

6. System projektowy (skrót — pełnia w docs/specs/02)

Kolory: granat #0F2A47 (primary), cyjan #2BA8E0 (akcent), pomarańcz #F39320 (CTA), biały + jasnoszary #F5F7FA (tła), ciemnoszary tekst.
Font: Inter lub Poppins (next/font). Duże, wyraźne nagłówki.
Karty: rounded-xl, subtelny cień. Przyciski CTA: pomarańcz z wyraźnym hover.
Estetyka: czysta, profesjonalna, dużo wolnej przestrzeni. NIE zatłaczaj sekcji.
Spójność: identyczny header, footer i styl na wszystkich stronach.

7. Kolejność realizacji (etapy)

Realizuj projekt etapami. Nie przeskakuj — każdy etap bazuje na poprzednim.

Etap	Zakres	Dokumentacja
1	Setup: Next.js+TS+Tailwind+shadcn/ui+fonty+tokeny	`docs/specs/01`, `02`
2	Layout wspólny: header (dropdowny, mobile menu), footer, pasek zaufania	`docs/specs/04-layouts.md`
3	Strona główna (wszystkie sekcje jako komponenty)	`docs/pages/01-home.md`
4	Strony usługowe: klimatyzacja, pompy ciepła, usługi domowe + 3 podstrony	`docs/pages/02–07`
5	Realizacje, blog (+ [slug]), o nas, kontakt (formularz)	`docs/pages/08–11`
6	E-commerce: sklep, produkt, koszyk, raty	`docs/pages/12–15`
7	Strony formalne + finalne SEO/JSON-LD	`docs/pages/16`, `docs/specs/03`
8	Build produkcyjny, naprawa błędów, weryfikacja w przeglądarce	—

8. Jak czytać dokumentację

docs/specs/01-architecture.md — struktura katalogów, routing, wzorce.
docs/specs/02-design-system.md — pełne tokeny, typografia, komponenty UI.
docs/specs/03-seo.md — metadata, JSON-LD, sitemap.
docs/specs/04-layouts.md — header, footer, nawigacja, wspólne elementy.
docs/specs/05-data-model.md — modele danych i mock content.
docs/pages/NN-*.md — szczegółowy brief każdej strony (sekcje, komponenty, treść).

Gdy budujesz daną stronę — najpierw przeczytaj jej plik w docs/pages/, potem odpowiednie specs.

5.3 KiB Raw Blame History Unescape Escape