Spoko Design System

Dokumentacja Pakiet npm Repozytorium GitHub

Spoko Design System

Stworzyłem open source’owy Design System, który łączy stronę dokumentacji z biblioteką komponentów wielokrotnego użytku w jednym pakiecie. System jest zbudowany z wykorzystaniem nowoczesnych technologii (Astro, Vue 3, UnoCSS) i opublikowany na npm, co ułatwia integrację z projektami.

Architektura podwójnego zastosowania

To unikalne podejście pozwala projektowi pełnić dwie funkcje jednocześnie:

Strona dokumentacji - Interaktywna dokumentacja na sds.spoko.space z podglądem komponentów na żywo, przykładami kodu i kompleksowymi przewodnikami dla:

Podstawowych tokenów designu (kolory, typografia, odstępy, cienie)
Ponad 20 gotowych komponentów (przyciski, modale, formularze, karuzele)
Wzorców projektowych i zaawansowanych komponentów
Pełnej funkcjonalności wyszukiwania przez Pagefind

Pakiet npm - Instalowalna biblioteka komponentów (spoko-design-system) oferująca:

Importowalne komponenty Vue 3 z obsługą TypeScript
Eksportowalną konfigurację UnoCSS dla spójnego stylowania
Konfigurację systemu ikon z ponad 10 wyselekcjonowanymi kolekcjami Iconify
Eksporty wspierające tree-shaking dla optymalnego rozmiaru paczki

Kluczowe funkcje

Nowoczesna biblioteka komponentów

System zawiera starannie przygotowane komponenty, które działają w obu kontekstach - jako część strony dokumentacji Astro i jako importowalne komponenty z pakietu npm:

Interaktywne elementy UI (przyciski, pola tekstowe, modale, dropdown’y)
Komponenty nawigacji (navbar, breadcrumbs, paginacja)
Komponenty treści (karty, zakładki, akordeony)
Specjalistyczne komponenty motoryzacyjne (używane produkcyjnie w projektach polo.blue)

Spójne stylowanie z UnoCSS

Konfiguracja UnoCSS jest podzielona na łatwe w utrzymaniu moduły:

System motywów - Kolory, typografia, breakpointy, wymiary
Skróty komponentów - Prekonfigurowane style komponentów zorganizowane według kategorii
Eksportowalna konfiguracja - Użytkownicy mogą rozszerzać bazową konfigurację przez createSdsConfig()

Takie podejście zapewnia spójność między projektami, jednocześnie umożliwiając dostosowanie do indywidualnych potrzeb.

Integracja systemu ikon

Design System zawiera dwa skoordynowane systemy ikon współpracujące ze sobą:

UnoCSS Icons - Statyczne importy przez klasy i-{kolekcja}-{nazwa}
astro-icon - Dynamiczne importy dla komponentów Astro

Wyselekcjonowane kolekcje obejmują Material Design Icons, Lucide, Carbon, Boxicons oraz specjalistyczne zestawy ikon motoryzacyjnych i technologicznych.

Zastosowanie w praktyce

Design System jest sprawdzony w boju na produkcji w wielu działających projektach:

catalog.polo.blue - Katalog części VW Polo 6R
polo.blue - Główna strona motoryzacyjna
polo6r.pl - Polska społeczność motoryzacyjna

Dzięki temu komponenty są gotowe do produkcji i radzą sobie z rzeczywistymi przypadkami brzegowymi.

Zautomatyzowany proces wydawniczy

Projekt wykorzystuje semantic-release do zarządzania wersjami:

Konwencjonalne commity określają zmiany wersji
Automatyczne generowanie CHANGELOG
Tworzenie wydań na GitHub
Publikacja na npm po merge do main

To zapewnia spójne wersjonowanie i niezawodne aktualizacje pakietu.

Wykorzystane technologie

Astro

Nowoczesny generator stron statycznych zapewniający szybką stronę dokumentacji z częściową hydratacją dla optymalnej wydajności i SEO.

Vue.js

Reaktywne komponenty z obsługą TypeScript, umożliwiające tworzenie interaktywnych elementów UI działających zarówno w dokumentacji, jak i jako importowalny pakiet npm.

UnoCSS

Błyskawiczny silnik CSS typu atomic on-demand z eksportowalną konfiguracją, zapewniający spójne stylowanie we wszystkich projektach korzystających z Design Systemu.

TypeScript

Pełne bezpieczeństwo typów dla komponentów i narzędzi, zapewniające lepsze doświadczenie programisty i wychwytywanie błędów na etapie kompilacji.

Progressive Web App (PWA)

Dokumentacja działająca offline z szybkim dostępem i zwiększoną wydajnością dla niezawodnego doświadczenia programisty nawet bez połączenia z internetem.

Pagefind

Wyszukiwarka dla stron statycznych umożliwiająca szybkie przeszukiwanie dokumentacji po stronie klienta bez zewnętrznych zależności czy wywołań API.

Swiper

Nowoczesny slider dotykowy z akceleracją sprzętową dla karuzel i galerii, zapewniający płynne działanie na urządzeniach mobilnych.

Iconify

Zunifikowany framework ikon z ponad 10 wyselekcjonowanymi kolekcjami, udostępniający tysiące ikon przez jeden, spójny interfejs.

Design System jest open source (licencja MIT) i aktywnie rozwijany z automatycznymi aktualizacjami zależności przez Renovate oraz kontrolą jakości kodu przez SonarQube.