UI Library

📘 View Storybook

Installation

pnpm add @aleph-alpha/ui-library

Required Peer Dependencies

pnpm add -D unocss @unocss/preset-wind4 @unocss/reset unocss-preset-animations unocss-preset-shadcn

Usage

1. Configure UnoCSS

The library exports a helper function getUiLibraryContentConfig() to simplify UnoCSS configuration:

// uno.config.ts
import { defineConfig } from 'unocss'
import { getUiLibraryContentConfig } 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' }),
  ],
})

2. Configure Vite

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import UnoCSS from 'unocss/vite'

export default defineConfig({
  plugins: [vue(), UnoCSS()],
})

3. Import Styles

// main.ts
import '@unocss/reset/tailwind.css'
import 'virtual:uno.css'

import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

4. Use Components

<script setup lang="ts">
import { UiButton, UiBadge } from '@aleph-alpha/ui-library'
</script>

<template>
  <UiButton>Click me</UiButton>
  <UiBadge variant="secondary">New</UiBadge>
</template>

Using with @aleph-alpha/ds-components-vue

If you're using both ui-library and ds-components-vue, configure UnoCSS to include both:

⚠️ Important: Do NOT add presetWind() or presetAnimations() separately when using presetsAlephAlpha(). The DS presets already include these utilities. Adding them again from different packages causes style conflicts.

// uno.config.ts
import { defineConfig } from 'unocss'
import { presetsAlephAlpha, getDesignSystemContentPathConfig } from '@aleph-alpha/config-css'
import { presetAlephAlphaIcons } from '@aleph-alpha/ds-icons'
import { getUiLibraryContentConfig } from '@aleph-alpha/ui-library/config'
import presetShadcn from 'unocss-preset-shadcn'

const uiLibraryConfig = getUiLibraryContentConfig()
const dsConfig = getDesignSystemContentPathConfig('vue')

export default defineConfig({
  presets: [
    // DS presets (already includes presetWind + presetAnimations)
    ...presetsAlephAlpha(),
    presetAlephAlphaIcons(),
    // UI Library preset (for shadcn CSS variables only)
    presetShadcn({ color: 'neutral' }),
  ],
  content: {
    filesystem: [
      ...(uiLibraryConfig.content.filesystem || []),
      ...(dsConfig.content?.filesystem || []),
    ],
    pipeline: {
      include: [
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        'src/**/*.{js,ts,vue}',
        'node_modules/@aleph-alpha/ui-library/**/*.js',
        'node_modules/@aleph-alpha/ds-components-vue/**/*.{js,ts}',
      ],
    },
  },
})

External Resources

• shadcn-vue — The component library we build upon
• Reka UI — Underlying accessible primitives
• TanStack Table — Headless table library (used in UiDataTable)
• WAI-ARIA APG — Accessibility patterns guide
• WCAG 2.2 — Web accessibility guidelines

Documentation

• Architecture — Component structure and design decisions
• Contribution Guidelines — Accessibility requirements and patterns
• Storybook Guidelines — Story patterns and guidelines
• Testing Strategy — What we test and where

Getting Started

Node Version

This project requires Node.js v20.19.0. Use nvm to switch to the correct version:

nvm use

This will automatically read the .nvmrc file in the repository root.

Developing

Commit Messages

We follow the Conventional Commits specification. Commit messages must be structured as follows:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (formatting, etc.)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests
• chore: Changes to the build process or auxiliary tools

Examples:

git commit -m "feat(button): add loading state"
git commit -m "fix(dropdown): resolve keyboard navigation issue"
git commit -m "docs(readme): update installation instructions"

Adding New Components

To add a new component from shadcn-vue, use the following command:

pnpm dlx shadcn-vue@latest add [component]

Example:

pnpm dlx shadcn-vue@latest add tooltip

Please refer to CONTRIBUTION_GUIDELINES.md for more details on the "Strict Facade" pattern and accessibility requirements.

Testing

| Command | Purpose | | --------------------- | ----------------------------------- | | pnpm test | Run unit tests | | pnpm test:storybook | Run Storybook + accessibility tests | | pnpm lint | Run linting including a11y rules |

See Testing Strategy for details on what we test and where.

Pre-commit Workflow

This project uses nx affected in pre-commit hooks to ensure code quality. Because lint and test targets depend on build, commits might hang if the build cache is cold.

If commit hangs:

Run a full build to populate the cache before committing:

pnpm nx run-many --target=build --all

Then try committing again. The pre-commit hook will hit the cache and finish quickly.

Quick unblock (Emergency only)

If you need to bypass hooks:

git commit -m "Your message" --no-verify

Use this sparingly and ensure CI passes.