# BS5Theme - kostra používateľskej príručky

> Pracovná kostra budúcej používateľskej príručky. Dokument slúži ako spoločný rám pre písanie, testovanie a dopĺňanie screenshotov. Texty kapitol zatiaľ nemajú byť finálne; každá časť obsahuje cieľ, navrhovaný obsah a poznámky pre dopracovanie.

## 1. Úvod

### 1.1 Komu je príručka určená

Táto príručka je určená každému, kto chce vytvoriť vlastnú Bootstrap 5 tému cez vizuálne rozhranie BS5Theme. Nemusíte začínať v editore kódu ani poznať všetky Sass premenné Bootstrapu. Aplikácia vám umožní meniť farby, typografiu, rozstupy a vzhľad komponentov priamo v náhľade.

Dizajnérom pomôže rýchlo vyskúšať farebné a typografické smerovanie webu. Tvorcom webov uľahčí prípravu konzistentného základu pre landing page, administráciu, e-shop alebo inú Bootstrap stránku. Frontend vývojárom poslúži ako praktický generátor témy, ktorú môžu ďalej zapojiť do projektu.

Príručka predpokladá iba základnú orientáciu v tom, čo je Bootstrap téma: sada pravidiel, ktoré ovplyvňujú farby, písma, tlačidlá, formuláre, karty, navigáciu a ďalšie opakované prvky rozhrania. Ak Bootstrap poznáte len z používateľskej strany, stále sa viete pohodlne zorientovať.

### 1.2 Čo aplikácia umožňuje

BS5Theme je nástroj na návrh a doladenie Bootstrap 5 témy. Základom práce je živý náhľad: keď zmeníte farbu, písmo alebo nastavenie komponentu, výsledok vidíte priamo na ukážkových obrazovkách.

V aplikácii môžete upraviť hlavnú Bootstrap paletu, teda farby ako `primary`, `secondary`, `success`, `warning` alebo `danger`. Farby viete vyberať ručne, skúšať pripravené palety alebo ich získať z obrázka, napríklad z loga, produktovej fotografie alebo vizuálnej inšpirácie.

Okrem farieb môžete nastaviť typografiu, veľkosti textov, riadkovanie, mierku nadpisov a vybrané fonty. Samostatné panely slúžia na rozstupy a komponenty, aby téma nebola len farebne iná, ale pôsobila vyvážene aj v reálnom rozhraní.

Hotovú alebo rozpracovanú tému môžete uložiť, vyskúšať ju na vlastnom HTML náhľade a exportovať ju na ďalšie použitie mimo aplikácie.

**Miesto pre screenshot:**

- Hlavná obrazovka aplikácie s označenými časťami rozhrania: náhľad, panel farieb, panel typografie, panel komponentov, uloženie a export.

### 1.3 Ako čítať túto príručku

Ak chcete aplikáciu najprv rýchlo vyskúšať, začnite kapitolou **Rýchly štart**. Prevedie vás základným pracovným tokom od prvej úpravy farby až po uloženie alebo export témy.

Ak už viete, ktorú časť témy potrebujete riešiť, môžete preskočiť rovno na príslušnú kapitolu. Kapitola **Práca s farbami** vysvetľuje paletu a kontrast, **Typografia** sa venuje písmam a mierke textu, **Rozstupy a layout rytmus** pomáha doladiť hustotu rozhrania a **Komponenty** popisujú nastavenia tlačidiel, formulárov, navigácie, kariet a ďalších prvkov.

Pred odovzdaním témy alebo jej použitím vo vlastnom projekte si prečítajte aj časti **Ukladanie tém** a **Export témy**. Pomôžu vám rozlíšiť, kedy pracujete s uloženou témou, kedy iba so zmenami v náhľade a čo očakávať od exportného balíčka.

Príručku nemusíte čítať od začiatku do konca. Je navrhnutá tak, aby slúžila aj ako referenčný materiál pri konkrétnej otázke: kde zmeniť farbu, ako upraviť font, prečo sa niečo neprejavilo v náhľade alebo ako pripraviť tému na export.

## 2. Zakladna orientacia v rozhrani

### 2.1 Hlavne casti obrazovky

- Hlavny nahlad temy.
- Bocne alebo vysuvne panely nastaveni.
- Panel farieb.
- Panel typografie.
- Panel rozstupov.
- Panel komponentov.
- Nastavenia temy, ulozenie a export.

**Doplnit neskor:**

- Presne nazvy tlacidiel podla finalnych prekladov.
- Rozdiely medzi desktop a mobilnym zobrazenim, ak budu podporene.

### 2.2 Zivy nahlad

- Co sa meni okamzite.
- Kedy sa zmena prejavi az po potvrdeni.
- Ako pouzivat prikladove obrazovky na kontrolu dizajnu.

**Kontrolne otazky:**

- Vidno zmenu farby vo vsetkych relevantnych prvkoch?
- Je tema citatelna na svetlom aj tmavom pozadi?
- Su tlacidla, formulare a navigacia dostatocne kontrastne?

## 3. Rychly start

### 3.1 Vytvorenie prvej temy

Navrhovany postup:

1. Otvorit aplikaciu.
2. Vybrat alebo ponechat vychodiskovu temu.
3. Upravit primarnu farbu.
4. Skontrolovat kontrast textu.
5. Vybrat pismo.
6. Skontrolovat komponenty v nahlade.
7. Ulozit alebo exportovat temu.

**Doplnit neskor:**

- Presny casovy scenar, napr. "tema za 5 minut".
- Ukazkovy vysledok pred a po.

### 3.2 Najcastejsi pracovny tok

- Najprv nastavit farby.
- Potom upravit typografiu.
- Nasledne doladit spacing a komponenty.
- Nakoniec overit temu na realnom alebo vlastnom nahlade.

## 4. Praca s farbami

### 4.1 Bootstrap farebne sloty

Popisat osem hlavnych farieb:

- `primary`
- `secondary`
- `light`
- `dark`
- `info`
- `success`
- `warning`
- `danger`

**Doplnit neskor:**

- Co kazdy slot ovplyvnuje v Bootstrap komponente.
- Odporucania pre vyber `primary` a `secondary` farby.

### 4.2 Vyber farby cez color picker

- Ako zvolit aktivny farebny slot.
- Ako nastavit farbu vizualne.
- Ako kopirovat alebo resetovat aktivnu farbu.

**Screenshoty:**

- Panel farieb s aktivnym slotom.
- Detail vyberaca farby.

### 4.3 Extrahovanie farieb z obrazka

- Pridanie obrazka z pocitaca.
- Vlozenie screenshotu.
- Vyber farby z obrazka.
- Zmazanie obrazka.

**Poznamky pre autora:**

- Overit, ci aplikacia vybera farbu kliknutim, kurzorom alebo lupou.
- Popisat odporucany typ obrazka: logo, produktova fotografia, brand moodboard.

### 4.4 Bootstrap paleta

- Vyber farieb z pripravenej Bootstrap palety.
- Kedy pouzit systemove farby a kedy vlastne farby.

### 4.5 Kontrast textu

- Vysvetlit prepnutie kontrastu pri farebnom slote.
- Ukazat rozdiel medzi predvolenym a invertovanym textom.
- Upozornit na citatelnost a pristupnost.

## 5. Typografia

### 5.1 Vyber fontu

- Vyhladavanie pisma.
- Rozdelenie na sans, serif a mono skupiny.
- Co sa stane po zvoleni fontu.
- Ako sa riesi nacitanie web fontu.

### 5.2 Velkosti a mierka textu

- Zakladna velkost textu.
- Riadkovanie.
- Mierka nadpisov.
- Mierka display nadpisov.
- Velkost lead textu, maleho textu, tlacidiel, badge prvkov a formularov.

### 5.3 Hrubky pisma

- Bezne texty.
- Nadpisy.
- Tlacidla a male UI prvky.

### 5.4 Reset typografie

- Reset celej typografie.
- Reset konkretnej sekcie.
- Kedy sa oplati vratit k vychodiskovym hodnotam.

## 6. Rozstupy a layout rytmus

### 6.1 Zakladny spacing

- Co znamena globalny spacing.
- Ako rozstupy ovplyvnuju karty, formulare, sekcie a komponenty.

### 6.2 Hustota rozhrania

- Kompaktne nastavenie.
- Predvolene nastavenie.
- Vzdusne nastavenie.

**Doplnit neskor:**

- Presne nazvy a rozsahy posuvnikov z aktualneho UI.
- Priklady, kedy vybrat hustsi alebo volnejsi layout.

## 7. Komponenty

### 7.1 Kategorie komponentov

Navrhovane kapitoly podla skupin v rozhrani:

- Layout
- Text
- Tlacidla
- Formulare
- Navigacia
- Spatna vazba
- Karty a zoznamy
- Media a tabulky
- Doplnkove komponenty

### 7.2 Globalne nastavenia komponentov

- Globalne rohy.
- Vplyv na tlacidla, karty, formulare a dialogy.

### 7.3 Tlacidla

- Velkost.
- Rohy.
- Vizualna vaha.
- Outline styl.

### 7.4 Formulare

- Velkost poli.
- Rohy poli.
- Checkbox a switch.
- Select, range slider, floating label a input group.

### 7.5 Navigacia

- Navbar.
- Tabs.
- Breadcrumb.
- Pagination.
- Dropdown.

### 7.6 Obsahove a systemove prvky

- Karty.
- List group.
- Alerty.
- Badge.
- Progress.
- Toast.
- Tooltip.
- Popover.
- Modal.
- Accordion.
- Table.
- Image thumbnail.
- Carousel.
- Offcanvas.
- Close button.
- Spinner.

**Poznamky pre autora:**

- Pri kazdom komponente doplnit: co nastavenie meni, kde to vidno v nahlade, odporucane pouzitie.
- Pri kazdom komponente pripravit minimalne jeden screenshot pred/po.

## 8. Vlastny nahlad

### 8.1 Vlozenie vlastneho HTML

- Otvorenie dialogu vlastneho nahladu.
- Vlozenie HTML kodu.
- Nacitanie HTML suboru.
- Pouzitie zmenenej temy na vlastny obsah.

### 8.2 Vlastne CSS subory

- Pridanie CSS odkazu.
- Zobrazenie zoznamu pouzitych CSS.
- Odstranenie alebo reset vlastneho CSS.

### 8.3 Reset nahladu

- Navrat k predvolenemu nahladu.
- Kedy reset pouzit.

**Upozornenia:**

- Vlastny HTML nahlad je urceny na vizualnu kontrolu, nie na plnohodnotny hosting stranky.
- Externe CSS moze prepisat cast nastaveni temy.

## 9. Ukladanie tem

### 9.1 Nazov a klucove slova

- Ako pomenovat temu.
- Ako pouzivat klucove slova.
- Odporucania pre hladatelne a zrozumitelne nazvy.

### 9.2 Sukromna a verejna tema

- Co znamena sukromna tema.
- Co znamena verejna alebo publikovana tema, ak je tato funkcia dostupna.
- Co treba skontrolovat pred zverejnenim.

### 9.3 Ulozit a ulozit ako

- Rozdiel medzi priebeznym ulozenim a ulozenim pod novym nazvom.
- Presne spravanie tlacidla "Ulozit ako" overit podla aktualnej implementacie.
- Kedy pouzit "Ulozit ako".

### 9.4 Nova tema

- Vytvorenie novej temy.
- Co sa stane s neulozenymi zmenami.

**Doplnit neskor:**

- Presne spravanie prihlaseneho a neprihlaseneho pouzivatela.
- Chybove stavy pri ukladani.

## 10. Export temy

### 10.1 Kedy exportovat

- Po finalnej kontrole dizajnu.
- Pred odovzdanim vyvojarovi.
- Pred nasadenim do vlastneho projektu.

### 10.2 Exportny balicek

Popisat ocakavany obsah exportu:

- CSS subory.
- Pripadne Sass alebo zdrojove nastavenia, ak su sucastou exportu.
- Metadata temy, ak su sucastou exportu.

**Doplnit neskor:**

- Presny zoznam suborov v ZIP exporte.
- Ako export pouzit v beznom Bootstrap projekte.

### 10.3 Export neulozenych zmien

- Ako aplikacia upozorni na neulozene zmeny.
- Rozdiel medzi ulozenim temy a jednorazovym exportom.

## 11. Praca s uctom a synchronizaciou

### 11.1 Prihlasenie

- Kde sa pouzivatel prihlasuje.
- Ako aplikacia rozpozna prihlaseny stav.
- Co je mozne bez prihlasenia.

### 11.2 Synchronizacia so serverom

- Kedy sa tema odosiela na server.
- Co sa deje pri chybe spojenia.
- Ako overit, ze tema bola ulozena.

**Doplnit neskor:**

- Prepojenie na technicky dokument `docs/ci4-central-server-api.md`, ak bude sucastou dokumentacie.

## 12. Galeria a vyhladavanie tem

### 12.1 Verejna galeria

- Ako sa zobrazuju verejne temy.
- Co znamena viditelnost temy.

### 12.2 Filtrovanie podla farieb

- Hladanie podla primarnej farby.
- Rozdiel medzi presnym nazvom farby a podobnou farbou.

### 12.3 Buduce filtre

- Nalada temy.
- Svetla/tmava/miesana schema.
- Typ pisma.
- Popularita.

**Poznamka:**

- Tato kapitola ma vychadzat z buduceho stavu galerie a z dokumentu `docs/theme-search-index-claude-instructions.md`.

## 13. Odporucane postupy

### 13.1 Ako navrhnut dobru Bootstrap temu

- Zacat od brand farieb.
- Overit kontrast.
- Nepreplnit paletu prilis podobnymi farbami.
- Vybrat citatelnu typografiu.
- Testovat na viacerych komponentoch.

### 13.2 Kontrola pred exportom

Checklist:

- Primarna farba funguje na tlacidlach a odkazoch.
- Text je citatelny na svetlom aj tmavom pozadi.
- Formularove polia su zretelne.
- Alerty a stavove farby su odlisitelne.
- Typografia ma vhodnu mierku.
- Spacing nie je prilis stiesneny ani prilis riedky.
- Tema bola overena na realnom obsahu.

### 13.3 Caste chyby

- Prilis nizky kontrast.
- Prilis vela vyraznych farieb naraz.
- Nevyvazena velkost nadpisov.
- Komponenty vyzeraju dobre samostatne, ale nie v celej stranke.
- Export prebehne skor, nez su ulozene posledne zmeny.

## 14. Riesienie problemov

### 14.1 Zmena sa neprejavila v nahlade

- Skontrolovat, ci bola zmena potvrdena.
- Skusit prepnout prikladovy nahlad.
- Overit, ci vlastne CSS neprepisuje temu.

### 14.2 Font sa nenacital

- Skontrolovat internetove pripojenie.
- Vybrat iny font.
- Overit fallback pismo v nahlade.

### 14.3 Export sa nepodaril

- Skontrolovat nazov temy.
- Skusit ulozit temu a export zopakovat.
- Overit, ci sa nezobrazila chybova hlaska.

### 14.4 Tema sa neulozila

- Skontrolovat prihlasenie.
- Skontrolovat spojenie so serverom.
- Skusit ulozenie zopakovat.

## 15. Slovnik pojmov

- **Bootstrap 5** - CSS framework, pre ktory aplikacia vytvara temu.
- **Tema** - sada farieb, typografie, rozstupov a komponentovych nastaveni.
- **Farebny slot** - pomenovana Bootstrap farba, napr. `primary` alebo `danger`.
- **Nahlad** - ziva ukazka, na ktorej sa kontroluje vysledok temy.
- **Export** - stiahnutie hotovej temy ako subor alebo balicek.
- **Kontrast** - rozdiel medzi farbou textu a pozadia.
- **Komponent** - opakovatelny prvok rozhrania, napr. tlacidlo, karta alebo formular.

## 16. Prilohy

### 16.1 Zoznam planovanych screenshotov

- Hlavna obrazovka aplikacie.
- Panel farieb.
- Extraktor farieb z obrazka.
- Bootstrap paleta.
- Panel typografie.
- Panel rozstupov.
- Panel komponentov.
- Vlastny HTML nahlad.
- Dialog ulozenia.
- Dialog exportu.
- Ukazka exportneho balicka.

### 16.2 Styl pisania prirucky

- Pisat kratke, prakticke vety.
- Pouzivat oslovenie v druhej osobe, napr. "Vyberte farbu".
- Najprv vysvetlit ciel, potom postup.
- Pri kazdej kapitole doplnit aspon jednu situaciu, kedy ju pouzivatel realne potrebuje.
- Technicke pojmy vysvetlit pri prvom pouziti.

### 16.3 Otvorene otazky

- Bude prirucka iba po slovensky alebo aj po anglicky?
- Bude urcena pre verejnych pouzivatelov, interny tim alebo oboje?
- Ma byt vysledkom jeden dlhy dokument alebo viac kratkych kapitol?
- Ktore funkcie su uz stabilne a ktore su este experimentalne?
- Ako presne ma vyzerat kapitola o ucte, galerii a publikovani tem?