@aleph-alpha/ui-library 1.13.0 → 1.15.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,230 @@
+# 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 { 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 — bundles token CSS vars, colors, and typography
+    presetUiLibraryThemeFromTokens(),
+    presetUiLibraryUtils(),
+  ],
+})
+```
+
+**What each part does:**
+
+| Config | Purpose |
+|--------|---------|
+| `getUiLibraryContentConfig()` | Scans `node_modules/@aleph-alpha/ui-library` for class usage so UnoCSS generates the right utilities |
+| `presetWind()` | Tailwind-compatible utility classes (must be **wind4**, not wind3) |
+| `presetAnimations()` | CSS animation utilities for transitions |
+| `presetShadcn()` | Base shadcn CSS variables and color utilities |
+| `presetUiLibraryThemeFromTokens()` | Token preset — must come **after** `presetShadcn`. Bundles design token CSS variables (light/dark), token-based theme colors (`bg-background-surface-secondary`, etc.), semantic color overrides (`background`, `foreground`, `modal`, etc.), and typography classes (`heading-48-bold`, `body-14-normal`, `label-12-medium`, etc.) |
+| `presetUiLibraryUtils()` | Utility rules required by library components — Tailwind v4 CSS variable syntax (`w-(--var)`, `h-(--var)`, etc.) not yet supported by preset-wind4 |
+
+### 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 |
+|--------|-------------|
+| `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.13.0",
+  "version": "1.15.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",

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/UiKbd/UiKbd.stories.ts

@@ -332,7 +332,7 @@ export const Group: Story = {
           to open the command palette
         </p>
 
-        <div class="mt-8 w-full max-w-md rounded-lg border bg-popover p-4 shadow-lg">
+        <div class="mt-8 w-full max-w-md rounded-lg border bg-background-surface-floating p-4 shadow-lg">
           <div class="flex items-center gap-2 border-b pb-3">
             <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="text-muted-foreground"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
             <span class="flex-1 text-sm text-muted-foreground">Type a command or search...</span>