# Specyfikacja wykonawcza — „Akademia Claude CFS" > Dokumentacja do przekazania **wykonawcy** (developer + projektant). Opisuje, co i jak zbudować — bez domysłów. > Autor dokumentacji: Jacek Szybicki (proj. „Claude w CFS"). Data: 2026-07-14. > Powiązane: `Plan-Akademia-Claude-CFS.md` (koncepcja), `Akademia-Claude-mapa.mermaid` (mapa), `CLAUDE.md` (zasady firmy). --- ## 0. Podział pracy (kto co robi) - **Ja (dokumentacja):** ten dokument — architektura, design system, specyfikacje komponentów, treść modułów, brief wideo/animacji, kryteria odbioru. Na kolejnym etapie mogę dostarczyć pełne teksty lekcji i skrypty screencastów moduł po module. - **Wykonawca (realizacja):** implementacja hubu (HTML/CSS/JS), grafiki, montaż wideo, generacje fal.ai, hosting. Cel terminowy: hub gotowy **przed 30.09.2026**, by wspierał wdrożenia indywidualne. --- ## 1. Charakter produktu Interaktywny **hub webowy po polsku** — wewnętrzna „Akademia Claude CFS". Krótkie lekcje, dużo grafiki i animacji, ścieżki wg roli, kreator własnych workflow. Odbiorcy: kadra zarządzająca i biuro CFS o **różnym poziomie obycia z technologią i angielskim** — stąd prosty język, duży obraz, minimum żargonu. Zasady nadrzędne (twarde): jest to materiał szkoleniowy — **nie łączy się z żadnymi konektorami/danymi firmy**. Uczy zasad, m.in. zgody na narzędzia i poufności (patrz §9). --- ## 2. Design system ### 2.1 Kolory (tokeny) Paleta wywiedziona z brandingu CFS (kolor marki ze strony: `#35BA81`; industrialny akcent RAL 9006 „white aluminium"). Wykonawca potwierdza odcienie z aktualnym brandbookiem/CSS strony. ```css :root { /* Marka */ --cfs-green: #35BA81; /* primary — akcje, akcenty, aktywne stany */ --cfs-green-dark: #2A9668; /* hover / naciśnięcie */ --cfs-green-tint: #EAF8F1; /* tła sekcji, wyróżnienia */ /* Neutralne */ --cfs-ink: #14201C; /* tekst główny (near-black, lekko zielony) */ --cfs-graphite: #202826; /* ciemne sekcje / stopka */ --cfs-muted: #6B7A75; /* tekst drugorzędny */ --cfs-silver: #A5A5A5; /* akcent industrialny (RAL 9006) */ --cfs-line: #E2E8E5; /* linie, obramowania */ --cfs-bg: #FFFFFF; /* tło główne */ --cfs-bg-soft: #F6F8F7; /* tło alternatywne */ /* Statusy / semantyka */ --cfs-success: #35BA81; /* ukończone (= zieleń marki) */ --cfs-warning: #E5A100; /* uwaga / moduł obowiązkowy */ --cfs-info: #2F80ED; /* wskazówka */ --cfs-danger: #D64545; /* zakaz / dane wrażliwe */ } ``` Kontrast: tekst na tłach ma spełniać **WCAG AA** (≥ 4.5:1 dla tekstu). Zieleń `#35BA81` na białym nadaje się na akcenty i duże elementy, **nie** na drobny tekst — do tekstu używać `--cfs-ink`. ### 2.2 Typografia - **Font:** dopasować do carflowsystem.pl (wykonawca sprawdza w CSS strony). Bezpieczny fallback: **Inter** (UI/tekst) + opcjonalnie **Montserrat**/geometryczny sans na nagłówki. Tylko web-fonty z legalną licencją. - **Skala** (desktop): H1 40/48, H2 30/38, H3 22/30, body 17/28, small 14/22. Na mobile skalować w dół ~85%. - **Zasada:** krótkie akapity (max 3–4 linie), dużo światła. ### 2.3 Siatka, przestrzeń, kształty - Kontener treści: max-width **1120 px**, wyśrodkowany, padding boczny 24 px (16 px mobile). - Siatka kafli: 12-kolumnowa; kafle modułów 3-w-rzędzie (desktop), 2 (tablet), 1 (mobile). - Odstępy w skali 4 px (4/8/12/16/24/32/48/64). - Promienie: karty 16 px, przyciski 10 px, „pill"/tag 999 px. - Cień kart: miękki, np. `0 6px 24px rgba(20,32,28,.08)`. ### 2.4 Ikonografia i motion - Ikony: jeden spójny zestaw liniowy (np. Lucide), kolor `--cfs-ink`/`--cfs-green`. - Motion: subtelny i szybki (120–240 ms, `ease-out`). Pojawianie kart, płynne przejścia między lekcjami, mikro-interakcje na hover. **Uszanować `prefers-reduced-motion`** — wyłączać animacje dla osób, które tak ustawiły. - Motyw wizualny nawiązuje do domeny CFS: **przepływ / ruch** (linie, „bramki", płynne strzałki) — dyskretnie, nie dosłownie. ### 2.5 Assety marki - Logo: `https://carflowsystem.pl/images/front/logo.png` (wersja podstawowa), `.../logo-fb.png` (kwadrat/social). - Wykonawca pobiera logo w najwyższej dostępnej rozdzielczości; docelowo poprosić firmę o wektor (SVG) do ekranów Retina. - Zdjęcia realizacji (biurowce, galerie, szpitale, lotniska) ze strony CFS można wykorzystać jako subtelne tła sekcji ról — **za zgodą** i zgodnie z prawami do zdjęć. --- ## 3. Architektura informacji i routing Struktura wg `Akademia-Claude-mapa.mermaid`. Sześć poziomów: - **/** — Start (po co Claude + role picker) - **/podstawy** — M1–M4 (dla wszystkich; M3 obowiązkowy) - **/narzedzia** — M5–M7 (konektory CFS) - **/rola/{prezes|operacje|administracja|magazyn|handel}** — ścieżki wg roli - **/buduj** — M8–M10 + kreator workflow - **/zaplecze** — słowniczek, FAQ, kontakt Realizacja może być jako pojedyncze pliki HTML (jedna strona = jeden plik) lub SPA — patrz §6. Nawigacja stała u góry + „okruszki" (breadcrumbs). Widoczny **globalny pasek postępu** (ile modułów ukończonych). --- ## 4. Specyfikacje komponentów Każdy komponent: opis, stany, zachowanie. ### 4.1 Nagłówek / nawigacja Logo (link do Startu) + menu poziomów + wskaźnik postępu „X/Y ukończone". Sticky przy scrollu. Mobile: menu hamburger. ### 4.2 Strona startowa + role picker - Sekcja hero: krótkie hasło + przycisk „Zacznij od podstaw". - **Karty ról** (5): ikona + nazwa roli + 1 zdanie „co zyskujesz". Klik → ścieżka roli. Karta ma stan hover (uniesienie + cień) i focus (obrys `--cfs-green`). - Sekcja „Jak to działa" — 4 kroki metodyki (wywiad → workflow 1 → szkolenie → workflow 2). ### 4.3 Kafel modułu - Zawiera: numer + tytuł, 1-zdaniowy opis, czas („~5 min"), **status pill** (`do zrobienia` / `w toku` / `ukończone`), pasek postępu. - Moduł obowiązkowy (M3) oznaczony znacznikiem `--cfs-warning` („obowiązkowy"). - Stany: domyślny, hover, ukończony (znacznik ✓ w `--cfs-success`). ### 4.4 Widok lekcji Układ jednokolumnowy, szeroki na czytanie (max ~720 px tekst): 1. Nagłówek lekcji + czas + „cel lekcji" (1 zdanie). 2. Treść w krótkich blokach, przeplatana grafiką. 3. **Osadzone demo/animacja** (§4.5). 4. Blok **„Spróbuj sam"** (§4.6). 5. **Mikro-quiz** (§4.7). 6. Nawigacja: „poprzednia / następna lekcja" + „oznacz jako ukończone". ### 4.5 Osadzone demo / animacja Kontener 16:9 (lub 4:3) z animacją (HTML/SVG/CSS lub wideo). Sterowanie: odtwórz/pauza, opcjonalnie przewijanie. Autoodtwarzanie **wyciszone** i respektujące `prefers-reduced-motion`. Napisy/podpisy po polsku dla wideo. ### 4.6 Blok „Spróbuj sam" Pokazuje gotowy **przykładowy prompt po polsku** w ramce z przyciskiem **„Kopiuj"**. Cel: użytkownik wkleja go do Claude i od razu widzi efekt. Prompt musi być bezpieczny (bez danych wrażliwych, bez wywołań narzędzi bez zgody). ### 4.7 Mikro-quiz 1–2 pytania jednokrotnego wyboru na moduł. Natychmiastowy feedback („dobrze / prawie — bo…"). **Bez oceniania i zapisu wyników** — cel to utrwalenie, nie egzamin. ### 4.8 Postęp i stan Zapamiętywany **lokalnie w przeglądarce** (`localStorage`): ukończone moduły, wybrana rola. **Bez logowania, bez wysyłania danych na serwer** — zero kwestii poufności. Przycisk „wyczyść postęp". ### 4.9 Słowniczek / FAQ Słowniczek: lista haseł PL (prompt, konektor, MCP, workflow, artefakt, scheduled task…) z 1-zdaniową definicją; wyszukiwarka/filtr. FAQ: akordeon. --- ## 5. Treść modułów (konspekt dla wykonawcy) Format każdego modułu: **Cel → Kluczowe punkty → Demo/animacja → „Spróbuj sam" → Quiz.** Pełne teksty lekcji dostarczę osobno, moduł po module. ### Poziom 1 — Podstawy **M1 · Pierwsze kroki** - Cel: uruchomić Claude/Cowork i rozpoznać interfejs. - Punkty: aktywacja, gdzie pisać, historia rozmów, gdzie są pliki, jak zacząć nowy czat. - Demo: animowany „tour" po interfejsie (warstwa 1) lub screencast (warstwa 3). - Spróbuj sam: „Przywitaj się i poproś Claude, żeby wyjaśnił, co potrafi w 3 punktach." - Quiz: gdzie znajdziesz wcześniejsze rozmowy? **M2 · Jak rozmawiać z Claude** - Cel: pisać skuteczne polecenia po polsku. - Punkty: konkret + kontekst + oczekiwany format; podawanie przykładów; wrzucanie plików; iterowanie („popraw to tak, aby…"). - Demo: animacja „słaby prompt vs dobry prompt" obok siebie. - Spróbuj sam: prompt do streszczenia wklejonego tekstu w 5 punktach. - Quiz: co poprawia jakość odpowiedzi — dodanie kontekstu czy skrócenie do jednego słowa? **M3 · Bezpieczeństwo i poufność w CFS** — *obowiązkowy* - Cel: znać granice — co wolno, czego nie. - Punkty: **zgoda na narzędzia (§2.1)** — Claude nie sięga do poczty/kalendarza/Trello/Dysku bez wyraźnej zgody; **poufność (§2.2)** — nie wpisujemy danych wrażliwych, anonimizacja („Klient A", „kwota XXX"); smartinvoice = dane finansowe, operacje zmieniające tylko na polecenie. - Demo: animacja „przepływ zgody" — Claude prosi, użytkownik zatwierdza. - Spróbuj sam: (bezpieczne) poproś Claude o wyjaśnienie, dlaczego pyta o zgodę przed użyciem narzędzia. - Quiz: czy można wkleić do czatu kwotę umowy z klientem? (nie / tylko zanonimizowaną). **M4 · Co to jest „workflow"** - Cel: rozumieć pojęcie i po co je wdrażamy. - Punkty: workflow = powtarzalna rutyna; anatomia: **wyzwalacz → kroki → efekt**; przykład z życia biura. - Demo: animowana „anatomia workflow" (3 klocki łączące się w przepływ). - Spróbuj sam: opisz Claude jedną swoją cotygodniową czynność i poproś o rozbicie na kroki. - Quiz: który przykład to workflow — jednorazowe pytanie czy cotygodniowe podsumowanie? ### Poziom 2 — Narzędzia CFS **M5 · Podłączone narzędzia** — Gmail, Kalendarz, Trello (cfs-trello), Dysk: co Claude może i jak zawsze prosi o zgodę. Demo: mapka „narzędzie → co z niego wyciągamy". Quiz o regule zgody. **M6 · Nasze serwery MCP** — cfs-forms (ankiety), **smartinvoice** (faktury/cashflow — *dane wrażliwe*, odczyt swobodny, zmiany tylko na polecenie), cfs-watch (monitoring konkurencji — planowany). Demo: co robi każdy serwer w 1 zdaniu. Ostrzeżenie wizualne przy smartinvoice. **M7 · Dawanie dostępu w praktyce** — jak wygląda prośba o zgodę, logowanie per osoba (spójne z `Onboarding-Cowork.md`). Demo/screencast realnego ekranu zgody. ### Poziom 3 — Ścieżki wg roli Dla każdej roli: krótki wstęp „co Claude zmienia w Twojej pracy" + 1–2 przykładowe workflow z gotowym promptem. (Doprecyzujemy po wywiadach.) - **Prezes** (Konrad Bąbliński): poranny briefing; synteza materiałów przed decyzją. - **Dyr. Operacyjny** (Marcin Remiszewski): cotygodniowy przegląd Trello; podsumowania statusu. - **Kier. Administracji** (Katarzyna Księżak-Lis): ankiety (cfs-forms); porządkowanie kalendarza; szablony pism. - **Magazyn / zaopatrzenie** (Piotr Zondej): przegląd faktur i płatności (smartinvoice, odczyt); zestawienia dostawców. - **Dyr. Handlowy** (Filip Fuks): **krok 0 = aktywacja Claude**; briefy o klientach (research web); monitoring konkurencji (cfs-watch). ### Poziom 4 — Zbuduj własne workflow **M8** rozłóż rutynę na kroki · **M9** zapisz prompt, iteruj, zaplanuj cyklicznie (scheduled task / pulpit) · **M10** częste błędy. Plus **interaktywny kreator**: formularz „wyzwalacz → kroki → efekt", który generuje gotowy szablon promptu do skopiowania (czysto po stronie przeglądarki). ### Poziom 5 — Zaplecze Słowniczek PL, FAQ, kontakt/wsparcie (Jacek), lista materiałów źródłowych. --- ## 6. Wymagania techniczne - **Stos:** statyczny front (HTML/CSS/JS). Dozwolone: vanilla JS lub lekki framework wg wyboru wykonawcy. Bez backendu (materiał szkoleniowy, brak danych firmy). - **Struktura plików:** preferowane samodzielne strony (jedna strona = jeden plik) lub prosty SPA. Zasoby (grafika, wideo) w `/assets`. - **Stan/postęp:** wyłącznie `localStorage`. Zero cookies śledzących, zero analityki wysyłającej dane bez zgody firmy. - **Responsywność:** desktop-first, poprawne na tablecie; działające (nie „ładne za wszelką cenę") na telefonie. - **Dostępność:** WCAG AA — kontrast, nawigacja klawiaturą, focus states, `alt` na grafikach, `prefers-reduced-motion`, semantyczny HTML. - **Wydajność:** wideo lazy-load; obrazy zoptymalizowane (WebP/AVIF); pierwszy ekran < 2 s na typowym łączu biurowym. - **Przeglądarki:** aktualne Chrome/Edge/Firefox/Safari. - **Język/kodowanie:** UTF-8, `lang="pl"`. - **Hosting (do decyzji Jacka):** (a) plik lokalny dla każdej osoby, albo (b) hosting z jednym linkiem — proponowany ten sam Cloud Run / region UE co serwery MCP, dostęp ograniczony do firmy. Rekomendacja: (b) dla jednej, aktualizowalnej wersji. --- ## 7. Brief mediów: wideo, audio, animacje Rdzeniem są **filmy instruktażowe** (ktoś tłumaczy, do czego używać Claude), uzupełnione **darmowym audio z NotebookLM**, **animacjami w hubie** i — opcjonalnie — ozdobnymi wstawkami fal.ai. Pełne skrypty, lista odcinków i konwencje: `Wideo-instruktazowe-brief-i-skrypty.md`. ### 7.1 Wideo instruktażowe — RDZEŃ (awatar AI + screencast, głos AI) Miks dwóch formatów; narracja = **polski głos AI (TTS)**: - **Awatar AI** (np. Synthesia/HeyGen) — wirtualny prezenter tłumaczy „po co i do czego" (wprowadzenia, koncepcje, zasady). Łatwa aktualizacja: zmieniasz tekst → generujesz od nowa. - **Screencast + lektor AI** — nagranie realnego ekranu Claude z narracją: „jak krok po kroku". - **Skrypty dostarczam ja**; nagrywa/generuje wykonawca. Wszystko z polskimi napisami; ekran anonimizowany (bez danych wrażliwych). ### 7.2 Audio — NotebookLM Audio Overview (darmowe) Podcastowe podsumowanie audio (dwoje prowadzących AI) generowane z materiałów źródłowych. - **Zastosowanie:** companion „do posłuchania" per moduł / ścieżka roli — utrwalenie, słuchanie w drodze. - **Zalety:** za darmo, szybko, naturalny ton. - **Ograniczenia:** format swobodnej rozmowy (mniejsza kontrola niż skrypt), tylko audio; **jakość polskiego do potwierdzenia** (NotebookLM obsługuje wiele języków — sprawdzić PL). Uzupełnienie, nie zamiennik filmów. - **Wejście:** karmimy NotebookLM tekstami lekcji (tylko treści niewrażliwe — patrz §9); wynikowy plik audio osadzamy w module (odtwarzacz + transkrypcja PL). ### 7.3 Animacje HTML/SVG w hubie (interaktywne demo) Do zbudowania w hubie: 1. **Tour po interfejsie** (M1) — podświetlanie obszarów UI. 2. **Słaby vs dobry prompt** (M2) — dwa panele side-by-side z „wpisywaniem". 3. **Przepływ zgody na narzędzie** (M3) — Claude pyta → użytkownik zatwierdza → akcja. 4. **Anatomia workflow** (M4) — 3 klocki (wyzwalacz→kroki→efekt) składające się w linię. 5. **Mapa narzędzi** (M5) — konektory jako węzły z etykietami „co wyciągamy". Styl: linie i „przepływ", kolory z §2.1, tempo spokojne. ### 7.4 Wideo generatywne fal.ai — OPCJONALNE (tylko ozdoba) Krótkie akcenty (intro/hero, przerywniki), **nie** instruktaż. Nie nadaje się do „gadającej głowy" ani do wiernego UI. - Klip hero ~6–8 s, 16:9, 1080p; bez tekstu z modelu (napisy dokładamy w montażu); paleta z §2.1. - Przykładowy prompt (EN): *"Abstract flowing green light streams over a dark minimal background, smooth motion suggesting cars and data moving through a gateway, clean modern tech aesthetic, emerald #35BA81 accents, seamless loop, no text."* - Wybór modelu i **budżet** (rozliczenie per generacja) — po stronie wykonawcy. Klucz API — bezpiecznie, poza `CLAUDE.md`/pamięcią (§9). --- ## 8. Kryteria odbioru (Definition of Done) - [ ] Wszystkie poziomy 0–5 zaimplementowane, treść PL, żargon w słowniczku. - [ ] Design system wdrożony jako tokeny CSS; zgodność wizualna z brandingiem CFS. - [ ] Postęp działa (localStorage), „wyczyść postęp" działa. - [ ] Moduł M3 oznaczony jako obowiązkowy i merytorycznie zgodny z §2.1/§2.2. - [ ] Animacje w hubie działają i respektują `prefers-reduced-motion`. - [ ] Filmy instruktażowe (awatar + screencast) po polsku, z napisami, lazy-load, wyciszony autoplay. - [ ] Audio NotebookLM osadzone tam, gdzie zaplanowano, z transkrypcją PL. - [ ] WCAG AA: kontrast, klawiatura, focus, alt-y. - [ ] Responsywność: desktop + tablet + telefon. - [ ] Brak połączeń z konektorami/danymi firmy; brak śledzenia bez zgody. - [ ] Wydajność: pierwszy ekran < 2 s. --- ## 9. Zgodność z zasadami CFS - **§2.1 (zgoda na narzędzia):** hub nie łączy się z żadnym konektorem; *uczy* zasady zgody (M3, M5, M7). - **§2.2 (poufność):** brak danych wrażliwych; przykłady i prompty ogólne/anonimizowane; postęp tylko lokalnie w przeglądarce. - **§5.1 (sekrety):** klucz fal.ai i wszelkie tokeny — poza `CLAUDE.md` i pamięcią, przekazywane bezpiecznym kanałem. - **NotebookLM (ważne):** karmimy je **wyłącznie treściami niewrażliwymi** (teksty lekcji, ogólne przykłady). Nie wrzucamy danych osobowych, kwot, umów ani danych z narzędzi — źródła trafiają do zewnętrznej usługi. - **§7 (styl):** język polski, ton półformalny, zwięźle.