# 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)

1. **Architektura** — trzymaj się struktury z `docs/specs/01-architecture.md`. Żadnych plików „na skróty".
2. **Komponenty** — reużywalne, typowane, jedna odpowiedzialność. Header/Footer/sekcje współdzielone,
   nigdy kopiowane między stronami.
3. **Server vs Client** — domyślnie Server Components. `"use client"` tylko tam, gdzie potrzebna
   interaktywność (formularze, koszyk, dropdowny, slidery).
4. **Responsywność** — mobile-first. Każda strona działa od 360px do 1920px.
5. **Dostępność** — semantyczny HTML, ARIA gdzie trzeba, widoczny focus, kontrast min. WCAG AA.
6. **SEO** — patrz `docs/specs/03-seo.md`. Metadata per strona, jeden H1, JSON-LD gdzie wskazano.
7. **Wydajność** — obrazy zoptymalizowane, lazy loading, minimum JS po stronie klienta.
8. **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.