spoko-design-system 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.21.0](https://github.com/polo-blue/sds/compare/v1.20.1...v1.21.0) (2025-12-15)
+
+### Features
+
+* **category:** enhance CategoriesCarousel with Schema.org microdata ([903d81b](https://github.com/polo-blue/sds/commit/903d81b24c80d44f118e79c5496e9ea928b0e171))
+
+## [1.20.1](https://github.com/polo-blue/sds/compare/v1.20.0...v1.20.1) (2025-12-15)
+
+## [1.20.0](https://github.com/polo-blue/sds/compare/v1.19.0...v1.20.0) (2025-12-14)
+
+### Features
+
+* **category:** add microdata and update dependencies ([f5eadf3](https://github.com/polo-blue/sds/commit/f5eadf370bec9e8ef9ad2934e714302cd3e5d24d))
+
 ## [1.19.0](https://github.com/polo-blue/sds/compare/v1.18.1...v1.19.0) (2025-12-10)
 
 ### Features

package/README.md

@@ -2,48 +2,113 @@
 
 ![Version](https://img.shields.io/github/package-json/v/polo-blue/sds)
 
-SDS is the easiest way to start websites with simple design system. Since Astro is compatible with many frameworks, you can import your components and document them right in the markdown files.
+**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:
 
-| title       | Introduction                   |
-|-------------|--------------------------------|
-| description | Docs intro                     |
-| layout      | ../../layouts/MainLayout.astro |
+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
+## Getting Started
 
 ### Installation
 
-```js
+Install as a package:
+
+```bash
 pnpm add spoko-design-system
 ```
 
-or just clone the repository.
+Or clone the repository for development:
 
+```bash
+git clone https://github.com/polo-blue/sds.git
+cd sds
+pnpm install
+```
 
+### Development Commands
 
-### Example:
-- https://sds.spoko.space/
+```bash
+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
 
-#
+```bash
+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
+```
 
-Most of the components from this repository can be seen in my projects:
+### Publishing
 
-- https://catalog.polo.blue/
-- https://polo.blue
-- https://polo6r.pl
+This project uses automated **semantic-release** for version management and publishing.
+
+```bash
+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>
+```
 
-### Features
-- ⚡️[Vue 3](https://github.com/vuejs/core), [Vite](https://github.com/vitejs/vite), [pnpm](https://pnpm.io/) - born with fastness
+### 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
+
+```bash
+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](https://github.com/vuejs/core), [Vite](https://github.com/vitejs/vite), [pnpm](https://pnpm.io/) - born with fastness
 - 🎨 [UnoCSS](https://github.com/antfu/unocss) - the instant on-demand atomic CSS engine
 - 😃 [astro-icon](https://github.com/natemoo-re/astro-icon) - for local icons, sprites and `@iconify-json/*` sets
-- 🍔 [astro-navbar](https://github.com/surjithctly/astro-navbar) -  fully responsive and accessible headless navigation bar
+- 🍔 [astro-navbar](https://github.com/surjithctly/astro-navbar) - fully responsive and accessible headless navigation bar
 - 🔎 [astro-pagefind](https://github.com/shishkin/astro-pagefind) - Astro integration for Pagefind static site search
 - 🗒 [astrojs/mdx](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/) - markdown support
 - 📦 [Playform compression](https://github.com/Playform/compress) - compression utilities to your Astro project
@@ -51,9 +116,21 @@ Most of the components from this repository can be seen in my projects:
 - 🏷️ [astro-meta-tags](https://github.com/patrick91/astro-meta-tags) - Meta Tags inside for Astro Dev Toolbar
 - 🖨 Static-site generation (SSG)
 - 🎡 [Swiper](https://github.com/nolimits4web/swiper) - modern mobile touch slider with hardware accelerated transitions and amazing native behavior
-- 🌠 [View Transitions API](https://docs.astro.build/en/guides/view-transitions/#full-site-view-transitions-spa-mode) - [View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) - makes it easy to change the DOM in a single step, while creating an animated transition between the two states. It's available in Chrome 111+ ([more details](https://developer.chrome.com/docs/web-platform/view-transitions?hl=en))
+- 🌠 [View Transitions API](https://docs.astro.build/en/guides/view-transitions/#full-site-view-transitions-spa-mode) - 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:
@@ -71,62 +148,156 @@ The design system includes carefully curated icon collections from Iconify:
 
 See the complete list and configuration in [`icon.config.ts`](./icon.config.ts).
 
-### Adding new sections
+### Adding New Icons
 
-Although it's not required, you can create folders for new sections.
+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)
 
-To show the section on the left side navigation, add it to the navigation config file at `src/config.ts`.
+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.
 
-```js
+## 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):
+
+```typescript
+// ✅ 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`:
+
+```javascript
 export const SIDEBAR = [
     { text: "Core", header: true },
     { text: "Introduction", link: "/core/introduction" },
-    ...,
+    // ...
     { text: "Components", header: true },
-    { text: "Buttons", link: "/components/jumbotron" },
-    ...,
+    { 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`:
+
+```javascript
+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.md" },
+    { text: "New component", link: "/new-section/new-component/" },
 ];
 ```
 
-### Adding new pages
+## Adding New Pages
 
-To add new pages just create an .astro or markdown 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.
+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.
 
-### Customizing Core section (colors, typography, shadows...)
+## Component Preview Utility
 
-If you want to customize the default colors, typography or shadows you can find the configuration file at uno.config.ts`.  I think I have prepared enough shades of blue ;-)
+There's a class called `.component-preview` that you can use to wrap your component in a grid:
 
-Feel free to add new pages to the Core section
+```html
+<div class="component-preview">
+    <button class="text-white bg-blue-lightest px-4 py-2 rounded-md">Your component</button>
+</div>
+```
 
+## Path Aliases
 
-### Customizing the page layout
+Three main path aliases defined in `tsconfig.json`:
+- `@components/*` → `src/components/*`
+- `@utils/*` → `src/utils/*`
+- `@types/*` → `src/types/*`
 
-You can find the css for the pages in `src/styles/content.css`.
+## Package Exports
 
+The package provides multiple export paths:
 
-### Adding your components
+```javascript
+import { Button, Input } from 'spoko-design-system'
+import { createSdsConfig } from 'spoko-design-system/uno-config'
+import { iconConfig } from 'spoko-design-system/icons'
+```
 
-Astro is great for design systems because it allows you to import components from different frameworks like react, vue or svelte.
+Available exports:
+- `.`: Main component exports
+- `./styles/*`: Direct style imports
+- `./icons`: Icon configuration
+- `./icon-collections`: Icon collection list
+- `./uno-config`: UnoCSS config for consumers
 
-To get started check how the `MainButton` component is used in the `src/pages/buttons.mdx` file.
+## Customizing Page Layout
 
-You can import your component library or create your own and document it easily.
+You can find the css for the pages in `src/styles/content.css`.
 
+## Examples
 
-### `.component-preview` utility
+Documentation and live examples:
+- https://sds.spoko.space/
 
-There's a class called `.component-preview` that you can use to wrap your component in a grid, and it will look like this:
+Most of the components from this repository can be seen in production:
+- https://catalog.polo.blue/
+- https://polo.blue
+- https://polo6r.pl
 
-<div class="component-preview">
-    <button class="text-white bg-blue-lightest px-4 py-2 rounded-md">Your component</button>
-</div>
+## Have Fun!
 
+Spoko Design System template was made in Poland by **[@spoko.space](https://spoko.space)** for personal and commercial use.
 
-### Have fun!
+## License
 
-Spoko Design System template was made in Poland by **[@spoko.space](https://spoko.space)** for personal and commercial use.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoko-design-system",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "type": "module",
   "private": false,
   "main": "./index.ts",
@@ -55,7 +55,7 @@
   ],
   "dependencies": {
     "@algolia/client-search": "^5.46.0",
-    "@astrojs/mdx": "^4.3.12",
+    "@astrojs/mdx": "^4.3.13",
     "@astrojs/node": "^9.5.1",
     "@astrojs/sitemap": "^3.6.0",
     "@astrojs/ts-plugin": "^1.10.6",
@@ -77,20 +77,20 @@
     "@iconify-json/ic": "^1.2.4",
     "@iconify-json/icon-park-outline": "^1.2.4",
     "@iconify-json/la": "^1.2.1",
-    "@iconify-json/lucide": "^1.2.79",
-    "@iconify-json/material-symbols-light": "^1.2.49",
+    "@iconify-json/lucide": "^1.2.81",
+    "@iconify-json/material-symbols-light": "^1.2.50",
     "@iconify-json/mdi": "^1.2.3",
     "@iconify-json/noto-v1": "^1.2.5",
     "@iconify-json/octicon": "^1.2.19",
     "@iconify-json/ph": "^1.2.2",
-    "@iconify-json/simple-icons": "^1.2.62",
+    "@iconify-json/simple-icons": "^1.2.63",
     "@iconify-json/streamline": "^1.2.5",
     "@iconify-json/streamline-emojis": "^1.2.4",
     "@iconify-json/streamline-freehand-color": "^1.2.2",
     "@iconify-json/system-uicons": "^1.2.4",
     "@iconify-json/uil": "^1.2.3",
     "@iconify-json/vscode-icons": "^1.2.37",
-    "@iconify/json": "^2.2.416",
+    "@iconify/json": "^2.2.418",
     "@iconify/vue": "^5.0.0",
     "@playform/compress": "^0.2.0",
     "@playform/inline": "^0.1.2",
@@ -121,16 +121,16 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/gtag.js": "^0.0.20",
-    "@types/node": "^24.10.2",
+    "@types/node": "^25.0.2",
     "@typescript-eslint/eslint-plugin": "^8.49.0",
     "@typescript-eslint/parser": "^8.49.0",
     "@unocss/transformer-variant-group": "66.5.10",
-    "@vitejs/plugin-vue": "^6.0.2",
+    "@vitejs/plugin-vue": "^6.0.3",
     "@vue/compiler-sfc": "^3.5.25",
     "@vue/eslint-config-typescript": "^14.6.0",
-    "astro": "^5.16.4",
+    "astro": "^5.16.5",
     "conventional-changelog-conventionalcommits": "^9.1.0",
-    "eslint": "^9.39.1",
+    "eslint": "^9.39.2",
     "eslint-plugin-astro": "^1.5.0",
     "eslint-plugin-vue": "^10.6.2",
     "husky": "^9.1.7",

package/src/components/Category/CategoriesCarousel.astro

@@ -40,16 +40,12 @@ const activeIndex =
     categories.map(category => (
       <swiper-slide
         itemprop="hasPart"
+        itemscope
+        itemtype="https://schema.org/WebPage"
         role="presentation"
         class={`swiper-slide cats-slide group ${category.slug === activeCategorySlug ? 'active' : ''}`}
       >
-        <a href={getTranslatedLink(`/${category.slug}/`)} class="carousel-item">
-          {
-            // itemprop="url"
-            // role="menuitem"
-            // aria-label={ t(`cat.${category.slug}.name`) }
-          }
-
+        <a itemprop="url" href={getTranslatedLink(`/${category.slug}/`)} class="carousel-item">
           <Image
             src={`${imgDomain}${category.photo}`}
             alt={category.name}

package/src/components/Category/CategoryDetails.astro

@@ -30,37 +30,65 @@ const subcategoryPath = subcategory?.path || `/${category.slug}/${subcategory?.s
     </div>
   </CategorySidebarToggler>
 
-  <div class="overflow-x-auto overflow-y-hidden flex max-w-full items-center">
+  <div
+    class="overflow-x-auto overflow-y-hidden flex max-w-full items-center"
+    itemscope
+    itemtype="https://schema.org/BreadcrumbList"
+  >
     {
       subtitle ? (
         <>
-          <a class="text-lg font-vw-headregular whitespace-nowrap block" href={categoryPath}>
-            {category.name}
-            {titleSmall && <small>{titleSmall}</small>}
-          </a>
+          <div itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
+            <a
+              class="text-lg font-vw-headregular whitespace-nowrap block"
+              href={categoryPath}
+              itemprop="item"
+            >
+              <span itemprop="name">{category.name}</span>
+              {titleSmall && <small>{titleSmall}</small>}
+            </a>
+            <meta itemprop="position" content="1" />
+          </div>
           <span class="text-neutral-lighter text-lg inline-block px-1 font-headlight">/</span>
           {!subsubtitle ? (
-            <h1 class="text-lg py-2.5 sm:py-0 whitespace-nowrap underline underline-offset-6 decoration-blue-300 decoration-0.5">
-              {subtitle} <span class="sr-only"> catalog</span>
-            </h1>
+            <div itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
+              <h1 class="text-lg py-2.5 sm:py-0 whitespace-nowrap underline underline-offset-6 decoration-blue-300 decoration-0.5">
+                <span itemprop="name">{subtitle}</span> <span class="sr-only"> catalog</span>
+              </h1>
+              <meta itemprop="position" content="2" />
+            </div>
           ) : (
             <>
-              <div class="text-lg py-2.5 sm:py-0 whitespace-nowrap">
-                <a href={subcategoryPath}>{subtitle}</a>
+              <div
+                itemprop="itemListElement"
+                itemscope
+                itemtype="https://schema.org/ListItem"
+                class="text-lg py-2.5 sm:py-0 whitespace-nowrap"
+              >
+                <a href={subcategoryPath} itemprop="item">
+                  <span itemprop="name">{subtitle}</span>
+                </a>
+                <meta itemprop="position" content="2" />
               </div>
               <span class="text-neutral-lighter text-lg inline-block px-1 font-headlight">/</span>
-              <h1 class="text-lg py-2.5 sm:py-0 whitespace-nowrap underline underline-offset-6 decoration-blue-300 decoration-0.5">
-                {subsubtitle} <span class="sr-only"> catalog</span>
-              </h1>
+              <div itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
+                <h1 class="text-lg py-2.5 sm:py-0 whitespace-nowrap underline underline-offset-6 decoration-blue-300 decoration-0.5">
+                  <span itemprop="name">{subsubtitle}</span> <span class="sr-only"> catalog</span>
+                </h1>
+                <meta itemprop="position" content="3" />
+              </div>
             </>
           )}
         </>
       ) : (
-        <h1 class="text-lg py-2.5 sm:py-0 whitespace-nowrap">
-          {category.name}
-          {titleSmall && <small>{titleSmall}</small>}
-          <span class="sr-only"> catalog</span>
-        </h1>
+        <div itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
+          <h1 class="text-lg py-2.5 sm:py-0 whitespace-nowrap">
+            <span itemprop="name">{category.name}</span>
+            {titleSmall && <small>{titleSmall}</small>}
+            <span class="sr-only"> catalog</span>
+          </h1>
+          <meta itemprop="position" content="1" />
+        </div>
       )
     }
   </div>