@aleph-alpha/ui-library 1.14.0 → 1.16.0

package/docs/public-docs/component-directory.md

@@ -0,0 +1,13 @@
+# Components
+
+Explore the design system components: view variants, try them in isolation, and copy code for your app.
+
+---
+
+## Live playground (Storybook)
+
+The easiest way to browse and try components and see detailed documentation on each component is Storybook. You can switch props, see states and sizes, see provided examples, etc.
+
+**[Open Storybook →](https://dev.aleph-alpha.de/ui-library)**
+
+More soon.

package/docs/public-docs/contributing.md

@@ -0,0 +1,11 @@
+# Contributing
+
+---
+
+## Contribution Guidelines (Workflows & Diagrams)
+
+Coming soon.
+
+## Support (Mattermost, FAQ, Office Hours)
+
+Coming soon.

package/docs/public-docs/external-links.md

@@ -0,0 +1,16 @@
+# External Links
+
+Quick access to Design System resources.
+
+---
+
+## Coming soon
+
+This page will provide:
+
+| Resource | Description | Link |
+|----------|-------------|------|
+| 📘 **Storybook (Live Code)** | Live code and component playground | [Storybook](https://dev.aleph-alpha.de/ui-library) |
+| 🎨 **Figma (Design System)** | Design system files | [Figma](https://www.figma.com/design/SrZQ19QVN1sQkuAMnMC746/AA26--WIP-?node-id=65-520&m=dev) |
+| 🐙 **GitHub Repository** | Source code and issues | [GitHub](https://github.com/Aleph-Alpha/frontend-hub/tree/main/packages/ui-library) |
+

package/docs/public-docs/foundations.md

@@ -0,0 +1,25 @@
+# Foundations
+
+*Links to Storybook.*
+
+---
+
+## Color & Dark Mode
+
+Coming soon.
+
+## Spacing & Grid
+
+Coming soon.
+
+## Typography
+
+Coming soon.
+
+## Elevation & Surfaces
+
+Coming soon.
+
+## Iconography
+
+Coming soon.

package/docs/public-docs/getting-started-designers.md

@@ -0,0 +1,17 @@
+# Getting Started for Designers
+
+---
+
+## Figma Access & Library Links
+
+Figma components and design files:
+
+- **[AA Design System Components (Figma)](https://www.figma.com/design/SrZQ19QVN1sQkuAMnMC746/AA26--WIP-?node-id=580-9181&t=2HPn1uKWpFKHnrMR-1)** — component library and design system.
+
+## Using Design Tokens in Figma
+
+Coming soon.
+
+## Link to Contribution Model
+
+Coming soon.

package/docs/public-docs/index.md

@@ -0,0 +1,5 @@
+# Overview
+
+Coming soon.
+
+

package/docs/public-docs/quick-start.md

@@ -0,0 +1,274 @@
+# Quick Start
+
+Get the UI library integrated into your project in under 5 minutes.
+
+**Designers:** For Figma, design tokens, and the contribution model, see [Getting Started for Designers](getting-started-designers.md).
+
+!!! note "Prerequisites"
+    - **Node.js** (>=20.19.0)
+    - **pnpm** or **npm**
+    - A **Vite + Vue 3** project
+    - **MCP (optional):** An editor that supports MCP (Cursor, VS Code, or Claude Code) if you want AI-assisted component discovery
+
+---
+
+## Installation
+
+**1. Add the library and peer dependencies**
+
+```bash
+pnpm add @aleph-alpha/ui-library
+pnpm add -D unocss @unocss/preset-wind4 @unocss/reset unocss-preset-animations unocss-preset-shadcn
+```
+
+<details>
+<summary>Using npm?</summary>
+
+```bash
+npm install @aleph-alpha/ui-library
+npm install -D unocss @unocss/preset-wind4 @unocss/reset unocss-preset-animations unocss-preset-shadcn
+```
+</details>
+
+!!! warning "Use `@unocss/preset-wind4`, not `preset-wind3`"
+    The library requires **preset-wind4**. Using preset-wind3 will break hover states and colors because wind3 injects opacity variables (`/ var(--un-bg-opacity)`) that conflict with the library's oklch token values.
+
+---
+
+## Setup and configuration
+
+### 2. UnoCSS config
+
+Create or update `uno.config.ts` in your project root:
+
+```typescript
+// uno.config.ts
+import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
+
+export default defineUiLibraryConfig()
+```
+
+This single call sets up everything: `presetWind4`, `presetAnimations`, `presetShadcn`, design token CSS variables (light/dark), token-based theme colors, semantic color overrides, typography classes, font loading, and content scanning.
+
+To customize the theme:
+
+```typescript
+// uno.config.ts
+import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
+
+export default defineUiLibraryConfig({
+  // Override specific theme variables
+  extend: { light: { primary: '#ff5500' } },
+  // Add your own presets
+  presets: [myCustomPreset()],
+})
+```
+
+More complete theme options example:
+
+```typescript
+// uno.config.ts
+import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
+
+export default defineUiLibraryConfig({
+  // Root and dark selectors used for generated CSS variables
+  rootSelector: ':root',
+  darkSelector: 'html.dark',
+  // Include all token vars like --background-surface-secondary
+  includeAllTokens: true,
+  // Extend token-derived theme values
+  extend: {
+    light: {
+      primary: '#ff5500',
+      'accent-default': '#b2d9ff',
+    },
+    dark: {
+      primary: '#ff8a3d',
+    },
+  },
+})
+```
+
+<details>
+<summary>Advanced: manual preset composition</summary>
+
+If you need full control over preset ordering, you can compose the presets individually:
+
+```typescript
+// uno.config.ts
+import { defineConfig } from 'unocss'
+import {
+  getUiLibraryContentConfig,
+  presetUiLibraryThemeFromTokens,
+  presetUiLibraryUtils,
+} from '@aleph-alpha/ui-library/config'
+import presetWind from '@unocss/preset-wind4'
+import presetAnimations from 'unocss-preset-animations'
+import presetShadcn from 'unocss-preset-shadcn'
+
+export default defineConfig({
+  ...getUiLibraryContentConfig(),
+  presets: [
+    presetWind(),
+    presetAnimations(),
+    presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
+    // Must come AFTER presetShadcn
+    presetUiLibraryThemeFromTokens(),
+    presetUiLibraryUtils(),
+  ],
+})
+```
+</details>
+
+### 3. Vite config
+
+Ensure your `vite.config.ts` includes both the Vue plugin and the UnoCSS Vite plugin:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import UnoCSS from 'unocss/vite'
+
+export default defineConfig({
+  plugins: [vue(), UnoCSS()],
+})
+```
+
+### 4. Global styles and app entry
+
+In your main entry (e.g. `main.ts`), import the UnoCSS reset and the generated CSS. These imports must run before your app mounts so that component styles apply everywhere.
+
+```typescript
+// main.ts
+import '@unocss/reset/tailwind.css'
+import 'virtual:uno.css'
+
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')
+```
+
+---
+
+## Test it
+
+Use a component to confirm everything works:
+
+```vue
+<script setup lang="ts">
+import { UiButton, UiBadge } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="min-h-screen bg-background text-foreground p-8">
+    <UiButton>Click me</UiButton>
+    <UiBadge variant="secondary">New</UiBadge>
+  </div>
+</template>
+```
+
+Run your dev server (e.g. `pnpm dev`) and open the app. The button and badge should render with the correct styles and colors matching [Storybook](https://dev.aleph-alpha.de/ui-library).
+
+**If colors look wrong or hover states don't work:**
+
+- Verify you're using `@unocss/preset-wind4` (not wind3) — check your `package.json`
+- Verify `presetUiLibraryThemeFromTokens()` comes **after** `presetShadcn()` in the presets array
+- Clear the Vite cache: `rm -rf node_modules/.vite && pnpm dev`
+
+---
+
+## Dark mode
+
+The library supports dark mode via the `html.dark` class. Toggle it on the document element:
+
+```typescript
+// Toggle dark mode
+document.documentElement.classList.toggle('dark')
+```
+
+Both `presetShadcn` and `presetUiLibraryThemeFromTokens` default to `darkSelector: 'html.dark'`, so CSS variables switch correctly out of the box.
+
+---
+
+## Config exports reference
+
+All config functions are exported from `@aleph-alpha/ui-library/config`:
+
+| Export | Description |
+|--------|-------------|
+| `defineUiLibraryConfig(options?)` | **Recommended.** Complete UnoCSS config with all presets, content scanning, fonts, and tokens. Options: `extend`, `darkSelector`, `presets`, `rules`, `shortcuts`, and any other UnoCSS config |
+| `getUiLibraryContentConfig()` | UnoCSS content/pipeline config to scan library classes |
+| `presetUiLibraryThemeFromTokens(options?)` | Token preset. Bundles token CSS variables, theme colors, semantic overrides, and typography classes. Options: `darkSelector` (default: `'html.dark'`), `includeAllTokens` (default: `true`), `extend`, `theme` |
+| `presetUiLibraryUtils()` | Utility rules required by library components (`w-(--var)`, `h-(--var)`, etc.) |
+| `presetUiLibraryTheme(theme, options?)` | Low-level preset with manually provided theme variables (for custom themes) |
+| `getUiLibraryThemeFromTokens()` | Returns the raw theme object derived from `tokens.json` |
+| `getUiLibraryTokenVars()` | Returns all token-based CSS variables for light and dark modes |
+| `getUiLibraryTokenColors()` | Returns UnoCSS theme colors config for all token-based colors (included automatically by `presetUiLibraryThemeFromTokens`) |
+| `getUiLibraryTypographyShortcuts()` | Returns typography class definitions as `[className, cssProperties]` tuples (included automatically by `presetUiLibraryThemeFromTokens`) |
+| `defineThemeConfig(config)` | Type-safe helper for external theme config files |
+
+---
+
+## MCP Integration
+
+Enable AI assistants (Cursor, Claude Code, etc.) to discover and use UI library components.
+
+!!! warning "Run from your project directory"
+    Run the installer from the **project that uses the UI library** (your app root). It detects the root from the current working directory and writes `.mcp.json` or `.cursor/mcp.json` there. Running it from the wrong folder will use the wrong root or fail.
+
+**1. Run the installer**
+
+```bash
+npx @aleph-alpha/lib-mcp mcp-install
+```
+
+**2. For Cursor**: add the Cursor-specific config:
+
+```bash
+npx @aleph-alpha/lib-mcp mcp-install --cursor
+```
+
+**3. Restart your editor** so it picks up the MCP server.
+
+**Available tools:**
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | Browse all components, optionally filter by name/category/description |
+| `get_component_docs` | Get full documentation for a component including props, examples, and usage |
+| `get_setup_guide` | Get this setup guide (so AI assistants can configure projects correctly) |
+
+### Or add the server manually
+
+If you prefer not to run the installer, add the MCP server yourself.
+
+1. **Where to put the config** (see your editor docs):
+
+   | Editor | Config location / docs |
+   |--------|------------------------|
+   | **Cursor** | [Using mcp.json](https://cursor.com/docs/context/mcp#using-mcpjson) — use `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally |
+   | **VS Code** | [Add and manage MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_configure-the-mcpjson-file) — use `.vscode/mcp.json` (workspace) or user config |
+   | **Claude Code** | [Add a local stdio server](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server) — use `.mcp.json` in your project (project scope) |
+
+2. **Add this server** to your `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "ui-library": {
+      "command": "npx",
+      "args": ["-y", "@aleph-alpha/lib-mcp", "serve"]
+    }
+  }
+}
+```
+
+3. **Restart your editor** so it picks up the MCP server.
+
+---
+
+## Contribute
+
+To contribute to the UI library (guidelines, support, and how to get involved), see [Contributing](contributing.md).

package/docs/public-docs/standards-guidelines.md

@@ -0,0 +1,15 @@
+# Standards & Guidelines
+
+---
+
+## Design Principles
+
+Coming soon.
+
+## Dos and Don'ts (Visual Gallery)
+
+Coming soon.
+
+## ♿ Accessibility (A11y) Standards
+
+Coming soon.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aleph-alpha/ui-library",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/system/lib.js",
@@ -22,7 +22,8 @@
     "config.js",
     "config.d.ts",
     "tailwind.preset.js",
-    "tokens.json"
+    "tokens.json",
+    "docs/public-docs"
   ],
   "description": "Next-gen UI Library for Vue.js projects.",
   "author": "Aleph Alpha GmbH",
@@ -42,11 +43,11 @@
   "devDependencies": {
     "@faker-js/faker": "10.1.0",
     "@playwright/test": "1.57.0",
-    "@storybook/addon-a11y": "^10.1.7",
-    "@storybook/addon-docs": "^10.1.7",
-    "@storybook/addon-themes": "^10.1.7",
-    "@storybook/addon-vitest": "^10.1.7",
-    "@storybook/vue3-vite": "^10.1.7",
+    "@storybook/addon-a11y": "10.2.17",
+    "@storybook/addon-docs": "10.2.17",
+    "@storybook/addon-themes": "10.2.17",
+    "@storybook/addon-vitest": "10.2.17",
+    "@storybook/vue3-vite": "10.2.17",
     "@testing-library/jest-dom": "^6.4.6",
     "@testing-library/vue": "^8.1.0",
     "@unocss/preset-wind3": "^66.5.10",
@@ -59,7 +60,7 @@
     "http-server": "14.1.1",
     "playwright": "^1.57.0",
     "postcss": "8.5.6",
-    "storybook": "^10.1.7",
+    "storybook": "10.2.17",
     "typescript": "^5.2.2",
     "unocss": "66.4.1",
     "unocss-preset-animations": "1.3.0",
@@ -70,11 +71,28 @@
     "vitest": "^3.0.0",
     "vue-tsc": "^2.2.12",
     "wait-on": "9.0.3",
-    "@aleph-alpha/config-css": "0.20.0",
-    "@aleph-alpha/eslint-config-frontend": "0.4.0",
     "@aleph-alpha/prettier-config-frontend": "0.4.0",
+    "@aleph-alpha/eslint-config-frontend": "0.5.0",
+    "@aleph-alpha/config-css": "0.21.0",
     "@aleph-alpha/tsconfig-frontend": "0.5.0"
   },
+  "peerDependencies": {
+    "unocss": ">=66.0.0",
+    "@unocss/preset-wind4": ">=66.0.0",
+    "unocss-preset-animations": ">=1.0.0",
+    "unocss-preset-shadcn": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@unocss/preset-wind4": {
+      "optional": true
+    },
+    "unocss-preset-animations": {
+      "optional": true
+    },
+    "unocss-preset-shadcn": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@floating-ui/vue": "1.1.9",
     "@internationalized/date": "^3.10.1",

package/src/components/UiCalendar/UiCalendar.stories.ts

@@ -31,7 +31,7 @@ const meta: Meta<typeof UiCalendar> = {
     weekStartsOn: {
       control: 'select',
       options: [0, 1, 2, 3, 4, 5, 6],
-      description: 'The day of the week to start on. 0 = Sunday, 1 = Monday, etc.',
+      description: 'The day of the week to start on. 0 is the locale default first day.',
     },
     numberOfMonths: {
       control: { type: 'number', min: 1, max: 3 },
@@ -392,7 +392,6 @@ const date = ref<DateValue>()
   <UiCalendar
     v-model="date"
     locale="de"
-    :week-starts-on="1"
     weekday-format="short"
     class="rounded-md border shadow-sm"
   />
@@ -405,7 +404,6 @@ const date = ref<DateValue>()
 export const GermanLocale: Story = {
   args: {
     locale: 'de',
-    weekStartsOn: 1,
     weekdayFormat: 'short',
   },
   render: (args) => ({
@@ -419,7 +417,6 @@ export const GermanLocale: Story = {
       v-model="date"
       :default-placeholder="placeholder"
       :locale="args.locale"
-      :week-starts-on="args.weekStartsOn"
       :weekday-format="args.weekdayFormat"
       :disabled="args.disabled"
       class="rounded-md border shadow-sm"

package/src/components/UiCalendar/types.ts

@@ -105,7 +105,7 @@ export interface UiCalendarProps {
 
   /**
    * The day of the week to start on.
-   * @default 0 (Sunday)
+   * @default 0
    */
   weekStartsOn?: UiCalendarWeekStartsOn;
 

package/src/components/UiRangeCalendar/UiRangeCalendar.stories.ts

@@ -30,7 +30,7 @@ const meta: Meta<typeof UiRangeCalendar> = {
     weekStartsOn: {
       control: 'select',
       options: [0, 1, 2, 3, 4, 5, 6],
-      description: 'The day of the week to start on. 0 = Sunday, 1 = Monday, etc.',
+      description: 'The day of the week to start on. 0 is the locale default first day.',
     },
     numberOfMonths: {
       control: { type: 'number', min: 1, max: 3 },
@@ -337,7 +337,7 @@ const dateRange = ref<DateRange>()
 </script>
 
 <template>
-  <UiRangeCalendar v-model="dateRange" locale="de" :week-starts-on="1" weekday-format="short" class="rounded-md border shadow-sm" />
+  <UiRangeCalendar v-model="dateRange" locale="de" weekday-format="short" class="rounded-md border shadow-sm" />
 </template>`;
 
 /**
@@ -347,7 +347,6 @@ const dateRange = ref<DateRange>()
 export const GermanLocale: Story = {
   args: {
     locale: 'de',
-    weekStartsOn: 1,
     weekdayFormat: 'short',
   },
   render: (args) => ({
@@ -361,7 +360,6 @@ export const GermanLocale: Story = {
       v-model="dateRange"
       :default-placeholder="placeholder"
       :locale="args.locale"
-      :week-starts-on="args.weekStartsOn"
       :weekday-format="args.weekdayFormat"
       :disabled="args.disabled"
       class="rounded-md border shadow-sm"

package/src/components/UiRangeCalendar/types.ts

@@ -90,7 +90,7 @@ export interface UiRangeCalendarProps {
 
   /**
    * The day of the week to start on.
-   * @default 0 (Sunday)
+   * @default 0
    */
   weekStartsOn?: UiRangeCalendarWeekStartsOn;