Dokument projektu
ITL Design System
6 min čítaniaInterná knižnica UI komponentov firmy IT LEARNING SLOVAKIA, s.r.o.
HTML, CSS a JS šablóny pripravené na kopírovanie do našich interných informačných systémov. Nie je to hotová aplikácia ani náhrada Bootstrapu — je to menší, náš vlastný základ šitý na evidencie, formuláre, tabuľky a prehľady.
Stav projektu: 39 z 39 komponentov je hotových a od 30. 7. 2026 k nim patrí aj tmavý režim. Stojí jedenásť celých obrazoviek poskladaných výlučne z komponentov, bez jediného riadku vlastného CSS. Vzorom pre nový komponent je našepkávač — CSS, JS aj dokumentácia s plnou ARIA. Čo je ešte pred nami, je v TODO.md; hotová práca a zapísané rozhodnutia v HISTORY.md.
Kde to nájdeš
Systém beží na https://design.itl.sk — za firemným HAProxy, s certifikátom od Let's Encrypt. Neprihlasuje sa: kto sa naň sieťovo dostane, vidí produkčnú verziu repozitára.
| Adresa | Čo tam je |
|---|---|
| https://design.itl.sk/ | Rozcestník — úvodná stránka projektu |
| https://design.itl.sk/_site/ | Galéria komponentov |
| https://design.itl.sk/_site/tokens.html | Dizajnové tokeny — všetky premenné --itl-* |
| https://design.itl.sk/examples/ | Kompletné ukážky layoutov |
| https://design.itl.sk/components/ | Surové HTML fragmenty |
Nič sa nespúšťa, stačí prehliadač. Generovaný web _site/ sa commituje,
takže na serveri je vždy aktuálny bez toho, aby tam čokoľvek buildovalo.
Dokumenty v čitateľnej podobe
Každý .md v repozitári má aj vysádzanú stránku — vzniká pri npm run docs
a zoznam sa nepíše ručne, takže nový súbor sa objaví sám.
| Dokument | Stránka |
|---|---|
README.md |
https://design.itl.sk/_site/readme.html |
TODO.md |
https://design.itl.sk/_site/todo.html |
HISTORY.md |
https://design.itl.sk/_site/history.html |
CLAUDE.md |
https://design.itl.sk/_site/claude.html |
Surový markdown zostáva dostupný. Každá stránka má hore odkaz Zobraziť zdroj
aj Stiahnuť .md — do vlastného projektu si lepíš markdown, nie náš HTML obal.
Zobrazenie v prehliadači zabezpečuje AddType text/plain .md v .htaccess
(vyžaduje Apache so zapnutým AllowOverride); sťahovanie funguje bez ohľadu naň.
Odkazy medzi dokumentmi sa pri generovaní prepisujú, takže [TODO.md](TODO.md)
vedie z vysádzanej stránky na /_site/todo.html a v surovom súbore zostáva
odkazom na súbor. Zdroj sa kvôli webu needituje.
Rýchly štart pre vývojára
- Otvor galériu komponentov.
- Nájdi komponent, skopíruj HTML z jeho stránky.
- Do svojho projektu načítaj CSS (a JS, ak ho komponent potrebuje):
<link rel="stylesheet" href="dist/css/itl.css">
<script src="dist/js/itl.js"></script>
<script>ITL.autoInit();</script>
Alebo ako ES modul:
import { Modal } from './dist/js/itl.esm.js';
- Prečítaj si
docs/<nazov-komponentu>.md— obsahuje HTML API, JS API, prístupnosť a poznámky na integráciu.
Fonty
Nepoužívame Google Fonts CDN — interné systémy bežia často v uzavretej sieti. Manrope a JetBrains Mono sú lokálne ako WOFF2 a stačí načítať jeden stylesheet:
<link rel="stylesheet" href="/assets/fonts/fonts.css">
Subsety sú latin + latin-ext (slovenčina potrebuje oba — latin-ext obsahuje len
č ď ľ ĺ ň ŕ š ť ž, základná abeceda a á é í ó ú ý ä ô sú v latin). Vďaka
unicode-range si prehliadač stiahne len to, čo stránka reálne potrebuje: typická
slovenská stránka bez kurzívy v monospace ~93 kB zo 151 kB.
assets/fonts/fonts.css je generovaný — needituj ho ručne, ale obnov príkazom:
node tools/fetch-fonts.mjs
Používanie s AI agentom
Každý komponent má v dokumentácii sekciu Pre AI agenta s imperatívnymi inštrukciami
na integráciu. Odporúčaný postup: agentovi daj docs/<name>.md a components/<name>.html.
To spolu stačí na správnu implementáciu bez ďalšieho kontextu.
Štruktúra repozitára
| Adresár | Obsah |
|---|---|
assets/ |
Logo (SVG, PNG) a fonty — fonts.css + woff2/, ttf/ je len záloha |
components/ |
HTML fragmenty jednotlivých komponentov — zdroj pravdy pre copy-paste |
docs/ |
Dokumentácia ku každému komponentu (<name>.md) |
examples/ |
Kompletné ukážky layoutov (prihlásenie, dashboard, formulár…) |
scss/ |
Zdrojové SCSS súbory — tokeny, base, komponenty, utility |
js/ |
Zdrojové ES moduly |
dist/css/, dist/js/ |
Skompilované výstupy |
vendor/ |
Externé knižnice skopírované z node_modules — commituje sa |
tools/ |
Build skripty (generátor docs webu, ikon, palety, fontov) |
_site/ |
Vygenerovaný docs web — commituje sa, vzniká cez npm run docs |
Podrobný popis konvencií je v CLAUDE.md.
Build
Vyžaduje Node.js 20+.
npm install
| Príkaz | Čo robí |
|---|---|
npm run build |
SCSS → dist/css/itl.css, JS → dist/js/itl.js + itl.esm.js |
npm run dist |
To isté + minifikované .min.css a .min.js |
npm run docs |
Vygeneruje docs web do _site/ — komponenty, tokeny aj dokumenty z .md |
npm run vendor |
Skopíruje externé knižnice z node_modules do vendor/ |
npm run dev |
Watch mode — sleduje scss/ a js/; _site/ vygeneruje raz na začiatku |
Náhľad rozrobenej práce
Toto potrebuješ, len ak systém upravuješ. Na jeho používanie stačí design.itl.sk.
Repozitár je statický web bez backendu, takže si ho stačí obslúžiť ľubovoľným
webovým serverom s koreňom v roote repozitára. Odkazy vnútri stránok sú
root-relative (/dist/css/itl.css), takže z podadresára fungovať nebudú.
Zmena je na design.itl.sk vidieť až po nasadení — pokiaľ ju máš len lokálne,
pozeraj sa na lokálny náhľad.
Po zmene v scss/ alebo js/ spusti npm run build, po zmene v docs/,
components/ alebo v ktoromkoľvek .md spusti npm run docs. Alebo nechaj
bežať npm run dev a len refreshuj.
Galéria v _site/ si k CSS a JS pridáva odtlačok obsahu, takže tam stačí
obyčajný refresh. Pri index.html a examples/ daj Ctrl+F5 — tie majú
štýly inline a bežný web server ich servíruje bez cache hlavičiek.
Externé knižnice a vendor/
Dva komponenty stoja na externej knižnici — výber dátumu na Flatpickri a graf na Chart.js, obe pod licenciou MIT.
Knižnice sa nebundlujú do dist/js/itl.js. Stránka si ich načíta sama
z vendor/, ktorý sa commituje: interné systémy bežia často v uzavretej
sieti, takže CDN neprichádza do úvahy, a node_modules v repozitári nie je.
vendor/ je generovaný — needituj ho ručne, obnovíš ho príkazom
npm run vendor. Skript zapisuje všetko alebo nič, rovnako ako generátor
fontov a ikon.
Ako vytvoriť minifikované súbory
dist/**/*.min.css a dist/**/*.min.js nie sú v gite (viď .gitignore) — sú to
odvodené artefakty a v repozitári by len vytvárali konflikty pri merge. Vytvoríš ich
kedykoľvek lokálne:
npm run dist
Vzniknú:
dist/css/itl.min.css
dist/js/itl.min.js
Ekvivalentné príkazy bez npm skriptov, ak potrebuješ minifikovať ručne (PowerShell):
# CSS — Dart Sass
npx sass scss/itl.scss dist/css/itl.min.css --style=compressed --no-source-map
# JS — esbuild
npx esbuild js/index.js --bundle --minify --format=iife --global-name=ITL --outfile=dist/js/itl.min.js
Non-minifikované dist/css/itl.css, dist/js/itl.js a dist/js/itl.esm.js
commitujeme — cieľové projekty ich ťahajú priamo z repozitára a nemusia nič buildovať.
Preto po každej zmene v scss/ alebo js/ spusti npm run build a commitni aj dist/.
Prispievanie
Než pridáš komponent, prečítaj si CLAUDE.md — najmä §7 Definícia hotového komponentu. Komponent bez dokumentácie, bez slovenských example dát alebo neotestovaný na 360px šírke sa nemerguje.
Naplánované úlohy a otvorené otázky sú v TODO.md, hotová práca a zapísané dizajnové rozhodnutia v HISTORY.md. Hotovú položku presuň z TODO do HISTORY — nenechávaj ju v TODO odškrtnutú.
Licencie
Kód tohto repozitára je interné vlastníctvo IT LEARNING SLOVAKIA, s.r.o.
Fonty:
- Manrope — SIL Open Font License 1.1
- JetBrains Mono — SIL Open Font License 1.1
Externé knižnice sa pridávajú len s licenciou MIT, Apache-2.0, BSD alebo ISC. Každá je uvedená v dokumentácii komponentu, ktorý ju používa.