· Szymon Berski · Portfolio · 2 min read
Spoko Design System
An open-source Astro-based design system with Vue 3 components and UnoCSS styling. Published as npm package and serving as both documentation site and reusable component library.
Spoko Design System
I developed an open-source design system combining documentation site and reusable component library in a single package. The system is built with modern technologies (Astro, Vue 3, UnoCSS) and published on npm for easy integration into projects.
Dual-Purpose Architecture
The unique approach allows the project to serve two purposes simultaneously:
Documentation Site - Interactive documentation at sds.spoko.space with live component previews, code examples, and comprehensive guides for:
- Core design tokens (colors, typography, spacing, shadows)
- 20+ production-ready components (buttons, modals, forms, carousels)
- Design patterns and rich components
- Full search functionality via Pagefind
npm Package - Installable component library (spoko-design-system) providing:
- Importable Vue 3 components with TypeScript support
- Exportable UnoCSS configuration for consistent styling
- Icon system configuration with 10+ curated Iconify collections
- Tree-shakeable exports for optimal bundle size
Key Features
Modern Component Library
The system includes carefully crafted components that work in both contexts - as part of the Astro documentation site and as importable npm package components:
- Interactive UI elements (buttons, inputs, modals, dropdowns)
- Navigation components (navbar, breadcrumbs, pagination)
- Content components (cards, tabs, accordions)
- Specialized automotive components (used in production on polo.blue projects)
Unified Styling with UnoCSS
UnoCSS configuration is split into maintainable modules:
- Theme system - Colors, typography, breakpoints, dimensions
- Component shortcuts - Pre-configured component styles organized by category
- Exportable config - Consumers can extend the base configuration via
createSdsConfig()
This approach ensures consistency across projects while allowing customization.
Icon System Integration
The design system includes two coordinated icon systems working together:
- UnoCSS Icons - Static imports via
i-{collection}-{name}classes - astro-icon - Dynamic imports for Astro components
Curated collections include Material Design Icons, Lucide, Carbon, Boxicons, and specialized sets for automotive and technology icons.
Real-World Applications
The design system is battle-tested in production across multiple live projects:
- catalog.polo.blue - VW Polo 6R parts catalog
- polo.blue - Main automotive website
- polo6r.pl - Polish automotive community
This ensures components are production-ready and handle real-world edge cases.
Automated Release Pipeline
The project uses semantic-release for version management:
- Conventional commits determine version bumps
- Automatic CHANGELOG generation
- GitHub releases creation
- npm publishing on merge to main
This ensures consistent versioning and reliable package updates.
Used Technologies
Astro
Modern static site generator providing fast documentation site with partial hydration for optimal performance and SEO.
Vue.js
Reactive components with TypeScript support, enabling interactive UI elements that work both in documentation and as importable npm package.
UnoCSS
Instant on-demand atomic CSS engine with exportable configuration, providing consistent styling across all projects using the design system.
TypeScript
Full type safety for components and utilities, ensuring better developer experience and catching errors at compile time.
Progressive Web App (PWA)
Offline-capable documentation with quick access and enhanced performance for reliable developer experience even without internet connection.
Pagefind
Static site search enabling fast, client-side searching through documentation without external dependencies or API calls.
Swiper
Modern touch slider with hardware-accelerated transitions for carousels and galleries, providing smooth mobile experience.
Iconify
Unified icon framework with 10+ curated collections, providing thousands of icons through a single, consistent interface.
The design system is open-source (MIT License) and actively maintained with automated dependency updates via Renovate and code quality checks via SonarQube.
