# 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.

### Configuration cases

Use `defineUiLibraryConfig()` for normal app setup. Reach for the lower-level exports only when you need to control preset order or compose the UI Library theme into an existing UnoCSS config.

| Case | Config | Use when |
| ---- | ------ | -------- |
| Default UI Library setup | `defineUiLibraryConfig()` | New apps or apps that can let the UI Library own the UnoCSS preset stack. This is the recommended path. |
| Token overrides | `defineUiLibraryConfig({ extend })` | You need to override a small set of CSS variables while keeping the default token theme. |
| Accessible token set | `defineUiLibraryConfig({ themeMode: 'accessible' })` or `defineUiLibraryConfig({ accessible: true })` | The app should use the WCAG 2.2 token set as its main theme. |
| Runtime accessible theme | `defineUiLibraryConfig({ accessibleTheme: true })` | The app should emit both default and accessible token CSS so users can toggle the accessible theme with `html.accessible-theme`. |
| Manual preset composition | `presetUiLibraryThemeFromTokens()` and `presetUiLibraryUtils()` | You already have a custom UnoCSS config and need explicit control over preset order. |
| Fully custom theme | `presetUiLibraryTheme(theme)` | You want to provide complete light/dark CSS variable maps instead of deriving them from `tokens.json`. |

The generated token utilities use semantic class names such as `bg-background-surface-secondary`, `bg-background-surface-floating`, `bg-background-input-default`, and `border-border-surface-default`. Prefer those explicit token classes when styling UI Library components.

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' } },
  // Configure the root rem base used by typography and spacing utilities
  rootFontSize: '100%',
  // 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',
  // Root font-size for the rem base. Strings are used as CSS values;
  // numbers are treated as px.
  rootFontSize: '100%',
  // 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',
    },
  },
})
```

To make the accessible token set the main theme:

```typescript
// uno.config.ts
import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'

export default defineUiLibraryConfig({
  themeMode: 'accessible',
})
```

To emit an additional accessible-theme block for runtime toggles:

```typescript
// uno.config.ts
import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'

export default defineUiLibraryConfig({
  accessibleTheme: true,
  accessibleSelector: 'html.accessible-theme',
})
```

<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 include `extend`, `theme`, `themeMode`, `accessible`, `accessibleTheme`, `accessibleSelector`, `rootSelector`, `darkSelector`, `rootFontSize`, `includeAllTokens`, `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, border radius utilities, semantic overrides, and typography classes. Options include `extend`, `theme`, `themeMode`, `accessible`, `accessibleTheme`, `accessibleSelector`, `rootSelector`, `darkSelector`, `rootFontSize`, and `includeAllTokens` |
| `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`) |
| `getUiLibraryTokenBorderRadius()` | Returns UnoCSS `theme.borderRadius` config from corner-radius tokens (included automatically by `presetUiLibraryThemeFromTokens`) |
| `getUiLibraryTypographyShortcuts()` | Returns typography class definitions as `[className, cssProperties]` tuples (included automatically by `presetUiLibraryThemeFromTokens`) |
| `vHoverOverlayVariants` | Shared variant names for the `v-hover` overlay directive: `subtle`, `default`, and `strong` |
| `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, or Storybook label such as `beta`, `experimental`, or `deprecated` |
| `get_component_docs` | Get full documentation for a component including labels, 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).
