@aleph-alpha/ui-library 1.15.0 → 1.16.0

package/config.d.ts

@@ -1,4 +1,4 @@
-import type { Preset } from 'unocss';
+import type { Preset, UserConfig } from 'unocss';
 
 /**
  * UnoCSS content configuration for scanning ui-library components.
@@ -206,3 +206,42 @@ export type UiLibraryTypographyShortcut = [string, string];
  * ```
  */
 export declare const getUiLibraryTypographyShortcuts: () => UiLibraryTypographyShortcut[];
+
+/**
+ * Options for `defineUiLibraryConfig`.
+ * Combines theme customization with additional UnoCSS config.
+ */
+export interface UiLibraryConfigOptions extends UiLibraryPresetOptions {
+  /** Additional UnoCSS presets to append after the built-in ones */
+  presets?: Preset[];
+  /** Additional UnoCSS rules */
+  rules?: UserConfig['rules'];
+  /** Additional UnoCSS shortcuts */
+  shortcuts?: UserConfig['shortcuts'];
+  /** Any other UnoCSS config fields (safelist, blocklist, etc.) */
+  [key: string]: unknown;
+}
+
+/**
+ * Creates a complete UnoCSS config with all required presets, content scanning,
+ * font loading, and theme from design tokens.
+ *
+ * This is the recommended way to set up UnoCSS with the UI library.
+ * It replaces manually importing and composing presetWind, presetAnimations,
+ * presetShadcn, presetUiLibraryThemeFromTokens, and presetUiLibraryUtils.
+ *
+ * @example
+ * ```ts
+ * // uno.config.ts — minimal
+ * import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
+ * export default defineUiLibraryConfig()
+ *
+ * // uno.config.ts — with theme customization
+ * import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
+ * export default defineUiLibraryConfig({
+ *   extend: { light: { primary: '#ff5500' } },
+ *   darkSelector: 'html.dark',
+ * })
+ * ```
+ */
+export declare const defineUiLibraryConfig: (options?: UiLibraryConfigOptions) => UserConfig;

package/config.js

@@ -1,8 +1,40 @@
 import { readFileSync } from 'node:fs';
-import { definePreset } from 'unocss';
+import { defineConfig, definePreset } from 'unocss';
+import presetWind from '@unocss/preset-wind4';
+import presetAnimations from 'unocss-preset-animations';
+import presetShadcn from 'unocss-preset-shadcn';
 
 let tokensCache;
 
+let saansFontFaceCssCache;
+const getSaansFontFaceCss = () => {
+  if (saansFontFaceCssCache) return saansFontFaceCssCache;
+
+  const fontsDir = new URL('./src/assets/fonts/Saans/', import.meta.url);
+  const fonts = [
+    { file: 'Saans-Regular.woff2', weight: 400 },
+    { file: 'Saans-Medium.woff2', weight: 500 },
+    { file: 'Saans-SemiBold.woff2', weight: 600 },
+    { file: 'Saans-Bold.woff2', weight: 700 },
+  ];
+
+  saansFontFaceCssCache = fonts
+    .map(({ file, weight }) => {
+      const buffer = readFileSync(new URL(file, fontsDir));
+      const base64 = buffer.toString('base64');
+      return `@font-face {
+  font-display: swap;
+  font-family: 'Saans';
+  font-style: normal;
+  font-weight: ${weight};
+  src: url('data:font/woff2;base64,${base64}') format('woff2');
+}`;
+    })
+    .join('\n');
+
+  return saansFontFaceCssCache;
+};
+
 const getTokens = () => {
   if (tokensCache) return tokensCache;
   const raw = readFileSync(new URL('./tokens.json', import.meta.url), 'utf8');
@@ -517,10 +549,28 @@ export const presetUiLibraryThemeFromTokens = (options = {}) => {
   // Typography shortcuts from design tokens
   const typographyShortcuts = getUiLibraryTypographyShortcuts();
 
-  // Return preset with token-related config: CSS variables, token colors, semantic overrides, typography
+  // Resolve font families from tokens for --font-sans / --font-heading overrides
+  const fontBody = resolveAnyTokenValue('font.font-family.font-body');
+  const fontHeading = resolveAnyTokenValue('font.font-family.font-heading');
+  const fontVariablesCss = `
+:root, :host {
+  --font-sans: '${fontBody}', sans-serif;
+  --font-heading: '${fontHeading}', sans-serif;
+}`.trim();
+
+  // Return preset with token-related config: CSS variables, token colors, semantic overrides, typography, fonts
   return {
     ...basePreset,
+    preflights: [
+      ...(basePreset.preflights || []),
+      { getCSS: () => getSaansFontFaceCss() },
+      { getCSS: () => fontVariablesCss },
+    ],
     theme: {
+      font: {
+        sans: `'${fontBody}', sans-serif`,
+        heading: `'${fontHeading}', sans-serif`,
+      },
       colors: {
         ...tokenColors,
         ...semanticColors,
@@ -552,6 +602,61 @@ export const presetUiLibraryUtils = () =>
     ],
   }))();
 
+/**
+ * Creates a complete UnoCSS config with all required presets, content scanning,
+ * font loading, and theme from design tokens. Drop-in replacement for manually
+ * composing presetWind, presetAnimations, presetShadcn, and the ui-library presets.
+ *
+ * @example
+ * ```ts
+ * // uno.config.ts — minimal
+ * import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
+ * export default defineUiLibraryConfig()
+ *
+ * // uno.config.ts — with customization
+ * import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
+ * export default defineUiLibraryConfig({
+ *   extend: { light: { primary: '#ff5500' } },
+ *   darkSelector: 'html.dark',
+ * })
+ * ```
+ */
+export const defineUiLibraryConfig = (options = {}) => {
+  const {
+    darkSelector,
+    rootSelector,
+    extend,
+    theme,
+    includeAllTokens,
+    presets: extraPresets = [],
+    rules: extraRules = [],
+    shortcuts: extraShortcuts = [],
+    ...restConfig
+  } = options;
+
+  const themeOptions = {};
+  if (darkSelector !== undefined) themeOptions.darkSelector = darkSelector;
+  if (rootSelector !== undefined) themeOptions.rootSelector = rootSelector;
+  if (extend !== undefined) themeOptions.extend = extend;
+  if (theme !== undefined) themeOptions.theme = theme;
+  if (includeAllTokens !== undefined) themeOptions.includeAllTokens = includeAllTokens;
+
+  return defineConfig({
+    ...getUiLibraryContentConfig(),
+    presets: [
+      presetWind(),
+      presetAnimations(),
+      presetShadcn({ color: 'neutral', darkSelector: darkSelector ?? 'html.dark' }),
+      presetUiLibraryThemeFromTokens(themeOptions),
+      presetUiLibraryUtils(),
+      ...extraPresets,
+    ],
+    rules: [...extraRules],
+    shortcuts: [...extraShortcuts],
+    ...restConfig,
+  });
+};
+
 // Typography utilities
 const fontWeightMap = {
   Regular: '400',

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

@@ -41,6 +41,59 @@ npm install -D unocss @unocss/preset-wind4 @unocss/reset unocss-preset-animation
 
 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'
@@ -59,23 +112,13 @@ export default defineConfig({
     presetWind(),
     presetAnimations(),
     presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
-    // Must come AFTER presetShadcn — bundles token CSS vars, colors, and typography
+    // Must come AFTER presetShadcn
     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 |
+</details>
 
 ### 3. Vite config
 
@@ -155,8 +198,9 @@ 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` |
+| `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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aleph-alpha/ui-library",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/system/lib.js",
@@ -43,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",
@@ -60,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",
@@ -71,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/UiStepper/UiStepper.stories.ts

@@ -12,7 +12,7 @@ import {
 import { UiIcon } from '../UiIcon';
 
 const meta: Meta<typeof UiStepper> = {
-  title: 'Primitives/UiStepper',
+  title: 'Components/UiStepper',
   component: UiStepper,
   tags: ['autodocs'],
   argTypes: {