110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# 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.
|