Spoko Design System

Spoko Design System (SDS) is an Astro-based design system with Vue 3 components and UnoCSS for styling. It's published as spoko-design-system on npm and serves as both a documentation site and a component library.

Live documentation: https://sds.spoko.space/

The project is still in the development phase, use at your own risk ;-)

Please feel free to fork it, edit it and let me know what do you think about it.

Requirements

• Node.js: >= 22.17.0
• Package Manager: pnpm >= 10.16.1 (v10.17.1 recommended)

Dual-Purpose Architecture

This project serves two purposes simultaneously:

1. Documentation Site: Astro-based documentation at https://sds.spoko.space/
2. npm Package: Component library exportable as spoko-design-system

Components must work in BOTH contexts - as part of the Astro site and as importable npm package components.

Getting Started

Installation

Install as a package:

pnpm add spoko-design-system

Or clone the repository for development:

git clone https://github.com/polo-blue/sds.git
cd sds
pnpm install

Development Commands

pnpm dev           # Start development server (runs on port 1234)
pnpm start         # Alias for dev
pnpm build         # Build production site
pnpm preview       # Preview production build
pnpm check         # Run Astro type checking

Code Quality

pnpm lint          # Lint all source files
pnpm lint:fix      # Lint and auto-fix issues
pnpm format        # Format code with Prettier
pnpm format:check  # Check code formatting

Publishing

This project uses automated semantic-release for version management and publishing.

pnpm semantic-release  # Manual release (usually automated via CI)
pnpm prepublishOnly    # Runs build before publish (automatic)

Semantic Release & Commit Conventions

All commits MUST follow conventional commits format:

<type>[optional scope]: <description>

Commit Types

• feat: New feature → MINOR version bump (0.1.0)
• fix: Bug fix → PATCH version bump (0.0.1)
• perf, refactor, style, docs: → PATCH version bump
• test, ci, chore: → No release

Breaking Changes: Add BREAKING CHANGE: footer → MAJOR version bump (1.0.0)

Examples

feat(components): add Modal component with accessibility features
fix(Input): resolve floating label positioning
docs: update Button component examples
chore: update dependencies [skip ci]

On merge to main, GitHub Actions automatically:

1. Analyzes commits
2. Determines version bump
3. Updates package.json and CHANGELOG.md
4. Creates GitHub release
5. Publishes to npm

Features

• ⚡️ Vue 3, Vite, pnpm - born with fastness
• 🎨 UnoCSS - the instant on-demand atomic CSS engine
• 😃 astro-icon - for local icons, sprites and @iconify-json/* sets
• 🍔 astro-navbar - fully responsive and accessible headless navigation bar
• 🔎 astro-pagefind - Astro integration for Pagefind static site search
• 🗒 astrojs/mdx - markdown support
• 📦 Playform compression - compression utilities to your Astro project
• 📲 PWA - Zero-config PWA Integration for Astro
• 🏷️ astro-meta-tags - Meta Tags inside for Astro Dev Toolbar
• 🖨 Static-site generation (SSG)
• 🎡 Swiper - modern mobile touch slider with hardware accelerated transitions and amazing native behavior
• 🌠 View Transitions API - makes it easy to change the DOM in a single step, while creating an animated transition between the two states
• ☁️ Deploy on Netlify

Icon System

The design system uses two separate but coordinated icon systems:

1. UnoCSS Icons (configured in uno-config/index.ts)

• Static imports for all icon JSON files
• Used via i-{collection}-{name} classes (e.g., i-lucide-car)

2. astro-icon (configured in icon.config.ts)

• Lists specific icons to include from each collection
• Used in Astro components via <Icon name="collection:icon" />

Icon Collections

The design system includes carefully curated icon collections from Iconify:

• 🎨 Material Design Icons - comprehensive icon set for UI elements
• 🚗 Ant Design Icons - clean outlined icons
• 📱 Bootstrap Icons - simple and consistent icons
• 🎯 Boxicons - high quality web icons
• 🌍 Carbon Icons - IBM's design language icons
• 🎪 Lucide Icons - beautiful & consistent icon toolkit
• 🎨 Streamline Freehand Color - hand-drawn style colored icons
• 📟 VS Code Icons - file type and technology icons
• 🏢 Simple Icons - brand icons for popular services
• ⚡ Fluent UI Icons - Microsoft's design system icons

See the complete list and configuration in icon.config.ts.

Adding New Icons

1. Add icon name to icon.config.ts in the appropriate collection's array
2. Icon is automatically available in both UnoCSS (class) and astro-icon (component)

UnoCSS Configuration

Important: UnoCSS config is split across two locations:

1. Root uno.config.ts: Simple wrapper that imports the main config
2. uno-config/ directory: Main configuration system
   • uno-config/index.ts: Core config with createSdsConfig() function
   • uno-config/theme/: Theme definitions (colors, typography, breakpoints, etc.)
   • uno-config/theme/shortcuts/: Component shortcuts organized by category

When Modifying UnoCSS

• Theme changes: Modify files in uno-config/theme/
• Shortcut additions: Add to appropriate file in uno-config/theme/shortcuts/
• Never edit root uno.config.ts directly
• The createSdsConfig() function can be imported by consumers to extend the config

Customizing Core (Colors, Typography, Shadows)

Theme files in uno-config/theme/:

• colors.ts: Complete color palette
• typography.ts: Font families, sizes, weights
• breakpoints.ts: Responsive breakpoints
• dimensions.ts: Spacing, sizing scales
• effects.ts: Shadows, borders, transitions
• grid.ts: Grid template configurations
• container.ts: Container max-widths and padding

Feel free to add new pages to the Core section in the documentation.

Adding New Components

1. Create Component

Create component in appropriate location:

• Vue: src/components/ComponentName.vue
• Astro: src/components/ComponentName.astro

2. Export from Root

Export from root index.ts (note the ./src/ prefix):

// ✅ Correct
export { default as ComponentName } from './src/components/ComponentName.vue';

// ❌ Wrong
export { default as ComponentName } from './components/ComponentName.vue';

3. Add Documentation

Add documentation page in src/pages/components/component-name.mdx

4. Add to Navigation

Add to navigation in src/config.ts:

export const SIDEBAR = [
    { text: "Core", header: true },
    { text: "Introduction", link: "/core/introduction" },
    // ...
    { text: "Components", header: true },
    { text: "Component Name", link: "/components/component-name/" },
];

Adding New Sections

Although it's not required, you can create folders for new sections.

To show the section on the left side navigation, add it to the navigation config file at src/config.ts:

export const SIDEBAR = [
    { text: "Core", header: true },
    { text: "Introduction", link: "/core/introduction" },
    // ...
    { text: "Components", header: true },
    { text: "Buttons", link: "/components/buttons" },
    // ...
    { text: "New section", header: true },
    { text: "New component", link: "/new-section/new-component/" },
];

Adding New Pages

To add new pages just create an .astro or .mdx file in src/pages/[section]/my-page.mdx. Remember to add it to the navigation config in src/config.ts so it shows up in the left side navigation.

You're free to organize the pages however you want.

Component Preview Utility

There's a class called .component-preview that you can use to wrap your component in a grid:

<div class="component-preview">
    <button class="text-white bg-blue-lightest px-4 py-2 rounded-md">Your component</button>
</div>

Path Aliases

Three main path aliases defined in tsconfig.json:

• @components/* → src/components/*
• @utils/* → src/utils/*
• @types/* → src/types/*

Package Exports

The package provides multiple export paths:

import { Button, Input } from 'spoko-design-system'
import { createSdsConfig } from 'spoko-design-system/uno-config'
import { iconConfig } from 'spoko-design-system/icons'

Available exports:

• .: Main component exports
• ./styles/*: Direct style imports
• ./icons: Icon configuration
• ./icon-collections: Icon collection list
• ./uno-config: UnoCSS config for consumers

Customizing Page Layout

You can find the css for the pages in src/styles/content.css.

Examples

Documentation and live examples:

• https://sds.spoko.space/

Most of the components from this repository can be seen in production:

• https://catalog.polo.blue/
• https://polo.blue
• https://polo6r.pl

Have Fun!

Spoko Design System template was made in Poland by @spoko.space for personal and commercial use.

License

MIT