# Design System — Portal Badania Kliniczne (wariant MEDYCZNY / NAUKOWY)

> **Wariant „Design_medical".** To osobna kopia bazowego designu o tym samym
> **układzie i podejściu**, ale przemalowana na ton **kliniczny / laboratoryjny /
> naukowy**. Zmienia się wyłącznie **warstwa tokenów** (`tokens.css`) oraz
> **typografia** — komponenty, makiety i struktura pozostają identyczne, bo
> wszystko odwołuje się do semantycznych tokenów.
>
> - **Marka:** głęboki **petrol / teal** (zamiast granatu) — chłód kliniczny, zaufanie.
> - **Akcent / CTA / linki:** **cyan diagnostyczny** (zamiast czerwieni z logo).
> - **Open access / free:** **zieleń** (sygnał „treść otwarta").
> - **Premium:** **indygo**, celowo odrębne od cyanowego CTA.
> - **Szarości:** chłodne, lekko teal-owe („lab"), drobniejsze promienie narożników.
> - **Typografia:** **IBM Plex Sans** (UI) + **IBM Plex Serif** (nagłówki / longform)
>   — para o charakterze technicznym/naukowym, zamiast Inter + Source Serif 4.
>
> Pozostała część dokumentu opisuje wspólny system; sekcje o kolorach z logo
> dotyczą bazowego wariantu i w tym wariancie są zastąpione paletą powyżej.

> **v0.3 — identyfikacja marki + strona numeru + mobile.** Wczytano oryginalne
> **logo** z [badaniaklinicznepolska.pl](https://badaniaklinicznepolska.pl/)
> (`assets/logo.png`) i dopasowano paletę do jego kolorów: **niebieski** (napis
> „BADANIA KLINICZNE") jako kolor marki + **czerwień** (znak „RD") jako akcent/CTA;
> premium przeniesiono na **fiolet**, by nie zlewał się z czerwonym CTA. Dodano
> **stronę numeru** (`numer.html`), baner „Masz już prenumeratę" **nad
> wyszukiwarką** (wyraźny, niebieski pasek z czerwonym obrysem) oraz poprawiono
> **widok mobilny** (logo zamiast łamiącego się tekstu, menu „hamburger",
> wymuszenie jednej kolumny dla siatek i kart poziomych).

Wizualny punkt wyjścia **przed implementacją**. Zgodny z kierunkiem z
[`docs/08-design-ux-ui.md`](../docs/08-design-ux-ui.md). Artefakty w tym
katalogu są makietami statycznymi (HTML+CSS) — **nie** finalnym kodem produkcyjnym.

> **v0.2 — łagodne przejście z e-wydań na online.** Po analizie obecnego serwisu
> [badaniaklinicznepolska.pl](https://badaniaklinicznepolska.pl/) makiety zostały
> przeprojektowane tak, by **nie zgubić stałych klientów**, którzy dziś głównie
> pobierają e-wydania PDF. E-wydania wróciły na pierwszy plan, a wyszukiwarka i
> artykuły online dochodzą jako wzbogacenie, nie zamiana.

## Analiza obecnego serwisu (punkt wyjścia)

| Element | Stan dzisiejszy | Wniosek dla nowego designu |
| --- | --- | --- |
| Główna akcja użytkownika | Pobranie / czytanie **e-wydania PDF** po zalogowaniu | E-wydania muszą być widoczne od razu, nie schowane |
| Strona główna | Siatka **okładek** ostatnich numerów + „warto przeczytać" | Zachować siatkę okładek; dołożyć wejście w artykuły online |
| Prenumerata | **Roczna**: druk 239 zł, elektroniczna 219 zł, student 99 zł (VAT 8%) | Zachować znany model i ceny; online dodać bez dopłat |
| e-Wydania | Gated: „treść dla zalogowanych e-Prenumeratorów" → login → czytanie | Dać czytelny ekran „Moje e-wydania" z szybkim „Pobierz PDF" |
| Nawigacja | Start, Prenumerata, Warto przeczytać, Aktualności, Ośrodki, Newsletter | Nowa nawigacja mostuje: Start · e-Wydania · Artykuły online · Szukaj · Prenumerata |
| Marka | „Badania Kliniczne", niezależny kwartalnik branżowy | Użyta w makietach (logo BK, kontakt biuro@rdbadania.pl) |

## Strategia mostu PDF ↔ online (load-bearing)

To główna decyzja UX v0.2. Stały klient nie może poczuć, że „zabrano mu PDF".

1. **Dwa wejścia, jedno czasopismo.** Każdy numer ma równolegle: `⤓ Pobierz PDF`
   oraz `Czytaj online`. Sekcja „dwóch drzwi" (`.bridge` / `.door`) tłumaczy różnicę.
2. **Szybka ścieżka do wykupionych PDF.** Pasek na stronie głównej
   („Masz już prenumeratę? Zaloguj się do e-wydań") + dedykowany ekran
   `ewydania.html` ze statusem prenumeraty i zakładką „Moje wydania".
3. **Wzajemne odnośniki.** Artykuł online linkuje do pełnego numeru PDF
   (`⤓ Pobierz pełny numer`), a kafel numeru linkuje do wersji online.
4. **Prenumerata bez straty.** Komunikat „nic nie tracisz — zyskujesz online";
   FAQ wprost odpowiada: *czy stracę dostęp do PDF?* → nie.

## Pliki

| Plik | Rola |
| --- | --- |
| `tokens.css` | Źródło prawdy: kolory (niebieski+czerwień z logo), typografia, spacing, cienie, **dark mode** |
| `styles.css` | Wspólne komponenty + most (okładki, biblioteka e-wydań, pasek statusu, „dwoje drzwi"), baner, mobilne menu |
| `app.js` | Wspólna obsługa mobilnego menu (hamburger) |
| `components.css` | Biblioteka primitywów: alert, avatar, skeleton, stany (empty/error), modal, toast, dropdown menu, tooltip, walidacja, checkbox/radio, tag-input, tabela (sort/zaznaczanie/bulk), paginacja |
| `components.js` | Logika primitywów (modal, toast `window.toast()`, menu, zaznaczanie wierszy → bulk bar, tag-input) |
| `components.html` | **Interaktywny katalog** wszystkich primitywów z ich stanami |
| `assets/logo.png` | Oryginalne logo „Badania Kliniczne" (pobrane z obecnego serwisu) |
| `index.html` | Galeria makiet + paleta + przegląd komponentów |
| `mockups/home.html` | Strona główna — baner nad wyszukiwarką, most PDF↔online, okładki numerów |
| `mockups/ewydania.html` | **e-Wydania / „Moje PDF"** — status prenumeraty, Moje wydania / Archiwum, pobieranie PDF |
| `mockups/numer.html` | **Strona numeru** — okładka, metadane, „Pobierz pełny numer PDF", spis treści artykułów, reklama |
| `mockups/article.html` | Artykuł — stan **premium-locked** + symulacja, link do pełnego PDF |
| `mockups/search.html` | Wyszukiwarka z facetami |
| `mockups/pricing.html` | Prenumerata: model roczny (jak dziś) + nowy dostęp online + B2B/ośrodki |
| `admin.css` | Komponenty panelu admina (sidebar, topbar, KPI, tabele, status badge, joby, split view) |
| `mockups/admin-dashboard.html` | **Panel admina — Dashboard**: KPI, kolejki pracy, zdrowie systemu (błędne joby, indeks) |
| `mockups/admin-pdf-review.html` | **Panel admina — Korekta PDF** (split view): strona · bloki + confidence · inspektor kandydata |
| `mockups/admin-article-editor.html` | **Panel admina — Edytor artykułu**: PL/EN (osobny status), rich-text, dostęp, numer, tagi, zdjęcie, SEO |
| `mockups/admin-translation-review.html` | **Panel admina — Korekta tłumaczenia**: PL źródło \| EN edytowalne, confidence per segment, regeneracja |

Otwórz `design/index.html` w przeglądarce. Makiety są połączone linkami —
działają jak klikalny prototyp. 🌙 przełącza dark mode.

## Strategia obrazów

Makiety używają zdjęć z [picsum.photos](https://picsum.photos) (seedowane URL-e,
np. `picsum.photos/seed/bk-2-2026/600/800`), aby lepiej oddać charakter strony niż
płaskie gradienty. Wzorzec: zdjęcie (`.img-fill`) leży **na** gradientowym
placeholderze (`.ph`); przy braku sieci `onerror` usuwa obraz i widoczny zostaje
gradient. W produkcji placeholdery zastępujemy realną fotografią kliniczną/branżową
oraz okładkami numerów (z importu PDF).

## Kierunek wizualny

Ekspercki, medyczny/branżowy, premium, redakcyjny, międzynarodowy, lekko naukowy.
Paleta **wyprowadzona z logo** „Badania Kliniczne":

* **Niebieski** (`--blue-500`, napis logo) + głęboki granat (`--navy-*`) — marka, wiarygodność, hero/stopka, przyciski marki.
* **Czerwień** (`--accent-500`, znak „RD" z logo) — akcent, CTA, linki, podświetlenia.
* **Fiolet** (`--status-premium-*`) — oznaczenie premium, celowo odrębne od czerwonego CTA.
* Biel (czytelność) + szarości (struktury) + delikatne statusy (free=zielony, sponsored=bursztyn, info=niebieski, error=czerwony).

Komponenty odwołują się wyłącznie do tokenów semantycznych, więc dark mode i zmiana
marki to remap tokenów, nie zmiana komponentów. **Logo** osadzone jako `assets/logo.png`
(w stopce wybielane filtrem na ciemnym tle).

### Typografia
- Nagłówki / longform: `Source Serif 4` (magazynowy, redakcyjny).
- UI / nawigacja / meta: `Inter` (neutralny, szybki w skanowaniu).
- Treść artykułu: serif, line-height 1.75, szerokość ~720px.

## Katalog komponentów

Bazowe (`docs/08` §13): header, footer, language switcher, search bar, article
card, premium/sponsored/free badge, tag, category label, author chip, locked
content block, related articles, TOC, pullquote, sidebar block, facet filters,
pricing plan, FAQ.

Mostu (v0.2+): **issue cover** (`.cover` + overlay), **issue card** z akcjami
PDF/online, **account / entitlement banner** (status prenumeraty), **„dwoje drzwi"**
(`.bridge`/`.door`), **tabs** (Moje wydania / Archiwum), **issue grid**, przycisk
„Pobierz PDF" (`.btn-pdf`), **notice bar** (`.notice-bar` — niebieski pasek z
czerwonym obrysem, nad wyszukiwarką), **strona numeru** (spis treści artykułów +
sidebar z PDF/reklamą), **mobilne menu** (`.menu-toggle` + `app.js`).

Admina (`admin.css`): **admin shell** (sidebar + topbar), **KPI cards**, **data
table**, **status badge** (`.st-draft/review/ready/published/failed/processing`),
**job rows** (błędy jobów „głośno"), **progress** i **confidence meter**,
**split view** korekty PDF (`.review-cols`), **detected block** (`.block` + typ +
confidence), **candidate inspector**. Panel używa sans (nie magazynowego serifu),
neutralnych szarości i minimum ozdobników — wg `docs/08` §9 (szybkość, czytelne
statusy, mało kliknięć).

### Kluczowe zasady odwzorowane w panelu

- **Human-in-the-loop** — ekran korekty wprost komunikuje, że bloki to *kandydaci (ExtractionCandidate)*, nie artykuły; „Utwórz szkic" tworzy szkic wymagający ręcznej publikacji; oryginalny PDF nie jest nadpisywany, surowy OCR zachowany (zgodnie z regułami domenowymi z CLAUDE.md / `docs/04`).
- **Confidence score** widoczny per blok (high/med/low) + ostrzeżenie przy niskiej pewności.
- **Reklama ≠ artykuł** — blok można oznaczyć jako reklamę i wykluczyć z treści / przenieść do modułu Reklam.
- **Joby w tle nie znikają po cichu** — błędne `pdf_ocr`/`ai_translation` itp. są eksponowane z akcją „Ponów" (`docs/02` §13 — fail loudly).
- **Osobny status publikacji per język** — edytor i translation review traktują PL i EN niezależnie (publikacja PL nie publikuje EN); EN to szkic AI wymagający korekty przed publikacją (CLAUDE.md — `ArticleTranslation`, `docs/02` §8).
- **Confidence przy tłumaczeniach** — pewność AI pokazywana per segment; segmenty zmienione ręcznie są oznaczane, z opcją „Przywróć AI" / „Regeneruj".

## Kluczowe decyzje UX odwzorowane w makietach

- **E-wydania na pierwszym planie** — pierwsza sekcja treści na home + dedykowany ekran.
- **Search jako wartość, nie dodatek** — duża wyszukiwarka w hero i osobny ekran z facetami.
- **Premium clarity** — lead widoczny → fade → blok blokady z CTA i ścieżką B2B (`docs/02` §6).
- **PL/EN** — przełącznik w headerze/stopce; wyniki EN oznaczone.
- **Mobile-first** — siatki kart/okładek i layouty składają się do 1–2 kolumn; nawigacja chowa się pod „hamburger", logo zastępuje łamiący się tekst marki, a siatki ustawione inline są wymuszane do jednej kolumny.
- **Wyszukiwarka na mobile** — facety/filtry są **domyślnie zwinięte** za przyciskiem „⚙ Filtry"; domyślny widok to sam search + aktywne chipy filtrów + wyniki. Belka wyszukiwania ma `input{min-width:0}` i `button{flex-shrink:0}`, żeby przycisk „Szukaj" nie wychodził poza zaokrąglone pole (dotyczyło search i hero na home).
- **Uwaga: `.header-search` jest celowo ukrywana na ≤960 px** (zastępuje ją hamburger). Wyszukiwarek w treści (np. „szukaj w numerze") **nie** budować na `.header-search` — użyć `.searchbar` lub lokalnej klasy (`numer.html` → `.issue-search`), inaczej znikną na mobile.
- **Baner stałego klienta nad wyszukiwarką** — wyraźny niebieski pasek (czerwony obrys) tak, by nie zlewał się z białym headerem; docelowo można go przesunąć niżej.
- **Dark mode w tokenach** + `prefers-color-scheme` (`docs/08` §11).
- **Dostępność** — skip-link, `:focus-visible`, role/aria (tabs, nav), hierarchia nagłówków.

## Biblioteka primitywów (`components.css` / `.js`)

Zestaw współdzielonych komponentów uzupełniających braki systemu (uzgodnione: stany
UX, primitywy interakcji, formularze/tabele złożone, spójność). Demo: `components.html`.

| Grupa | Komponenty |
| --- | --- |
| Stany UX | `.skeleton*` (ładowanie), `.state` / `.state.error` (empty/error/no-access), istniejący `.locked` (premium) |
| Interakcje | `.modal-overlay`/`.modal` (+ `data-modal-open/close`, Esc), `.toast` (`window.toast(msg,type)`), `.menu`/`.menu-trigger` (action menu), `[data-tooltip]` |
| Formularze/tabele | `.field.has-error/.has-success` + `.field-error/.field-hint`, `.check`/`.radioc`, `.tag-input`, sort/zaznaczanie/bulk na `.data-table`, `.pagination` |
| Spójność | `.alert` (info/success/warn/danger), `.avatar2` (sm/lg/square/group) |

### Plan ujednolicenia (retrofit — WYKONANY)

`components.css`/`.js` są **podpięte do wszystkich ekranów** (czytelnik + admin + galeria).
Stan migracji:

* ✅ `.alert` zastąpił UI-hinty: `candidate-note`, `review-hint` (admin-pdf-review, editor, translation-review).
* ✅ `.pagination` zastąpił doraźną paginację na `search.html`; `.tag-input` zastąpił statyczne tagi w edytorze.
* ✅ Interakcje wpięte: toasty (publikacja/zapis/ponów/regeneracja), modale potwierdzeń (publikuj PL, odrzuć kandydata), sortowalne nagłówki, tooltipy w pasku edytora.
* ✅ Linki nawigacji admina ujednolicone do zbudowanych ekranów (Dashboard ↔ Artykuły ↔ Tłumaczenia ↔ Korekta PDF).
* ⏸ **`sidebar-block` zostaje** jako komponent **redakcyjny** (ramka boczna w treści artykułu — to nie UI-alert; świadomie odrębny).
* ⏸ **Avatary** (`author-avatar` / `.who .avatar` / `.account-banner .avatar`) — `.avatar2` jest kanoniczny dla nowych użyć; migracja istniejących odłożona (różne rozmiary kontekstowe, niskie ryzyko/niski zysk).
* Badge'y: świadomie **dwa zestawy** — `.badge-*` (czytelnik) i `.st-*` (admin: statusy workflow).

## Świadome uproszczenia (makieta ≠ produkcja)

- Zdjęcia i okładki to placeholdery (picsum) do podmiany na realne materiały.
- Interakcje (filtry, paginacja, login, płatność, pobranie PDF) nie są funkcjonalne;
  „Symuluj dostęp" na stronie artykułu i przełączanie zakładek e-wydań to tylko podgląd.
- Fonty z Google Fonts (CDN) — offline fallback systemowy.
- Dane (autorzy, ceny, terminy) są przykładowe; ceny i kontakt odwzorowują obecny serwis.

## Co dalej (propozycja)

1. **Akceptacja kierunku** — kolor, typografia, ton, oraz balans e-wydania ↔ online.
2. Pozostałe ekrany czytelnika: ~~strona numeru~~ (gotowe — `numer.html`), logowanie/rejestracja, konto (faktury, prenumerata, organizacja).
3. Ekrany admina (desktop-first): ~~dashboard~~, ~~PDF review split-view~~, ~~edytor artykułu~~ (`admin-article-editor.html`), ~~translation review~~ (`admin-translation-review.html`); pozostają: lista artykułów, płatności/dostępy, użytkownicy, organizacje, reklamy/sponsorowane.
4. Przeniesienie tokenów do implementacji (CSS variables / Tailwind theme) przy scaffoldowaniu slice `issues`/`articles`/`search`.
5. Visual regression na kluczowych ekranach (`docs/08` §21).

> Zgodnie z `AGENTS.md`: to artefakt designu, nie zmiana architektury ani modelu
> domenowego — nie wymaga ADR. Decyzja „most PDF↔online / e-wydania first" została
> odnotowana w `docs/08-design-ux-ui.md` jako kierunek v0.2.