# 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.
- URL: https://spoko.space/spoko-design-system/
- Published: 2025-01-20
- Tags: astro, vue3, unocss, typescript, design-system, pwa, open-source, npm
---## 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](https://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](https://catalog.polo.blue/) - VW Polo 6R parts catalog
- [polo.blue](https://polo.blue) - Main automotive website
- [polo6r.pl](https://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

The design system is open-source (MIT License) and actively maintained with automated dependency updates via Renovate and code quality checks via SonarQube.