@aleph-alpha/config-unocss

Config UnoCSS

@aleph-alpha/config-unocss

Shared UnoCSS presets for Aleph Alpha frontends. Bundles the design-system token preset, web-fonts preset, and content-pipeline helpers so every app and library can share one UnoCSS configuration.

The design tokens themselves live in @aleph-alpha/config-tokens, and the embedded web fonts live in @aleph-alpha/config-fonts; this package consumes both and exposes them as UnoCSS presets.

Installation

pnpm add -D @aleph-alpha/config-unocss

Usage in applications

Most apps just need:

// uno.config.ts
import { defineAppConfig } from '@aleph-alpha/config-unocss';

export default defineAppConfig();

defineAppConfig() wraps defineConfig from UnoCSS, pre-wires presetsAlephAlpha() and the design-system content paths, and exposes hooks for app-specific extension.

Layering on top

import { defineAppConfig } from '@aleph-alpha/config-unocss';

export default defineAppConfig({
  // Extra presets appended after the defaults
  presets: [/* presetMyApp() */],

  // Extra rules — e.g. local workarounds or brand utilities
  rules: [
    ['my-rule', { color: 'red' }],
  ],

  // Theme overrides — merged into the base theme
  theme: {
    breakpoints: { xs: '480px' },
    colors: { 'brand-bg-brand': '#CCE804' },
  },

  // Pull classes out of additional node_modules packages.
  // filesystem and pipeline.include are union-merged with the DS defaults.
  content: {
    filesystem: ['node_modules/@my-org/some-lib/**/*'],
  },

  // Pass-through options — anything `defineConfig` accepts
  shortcuts: { /* ... */ },
  safelist: [/* ... */],
  transformers: [/* ... */],
});

Composing manually (libraries, advanced apps)

import { defineConfig } from 'unocss';
import { presetsAlephAlpha, getDesignSystemContentPathConfig } from '@aleph-alpha/config-unocss';

export default defineConfig({
  presets: [...presetsAlephAlpha()],
  ...getDesignSystemContentPathConfig('vue'),
});

Migration from legacy @aleph-alpha/config-css

Before (~11 lines):

import {
  getDesignSystemContentPathConfig,
  presetAlephAlpha,
} from '@aleph-alpha/config-css';
import { defineConfig } from 'unocss';

export default defineConfig({
  ...getDesignSystemContentPathConfig('vue'),
  presets: [presetAlephAlpha()],
});

After (3 lines):

import { defineAppConfig } from '@aleph-alpha/config-unocss';

export default defineAppConfig();

Apps with their own brand colors keep them via the theme option. Colors you list here are deep-merged on top of the design-system tokens — only the keys you set are overridden, the rest of the token palette stays available:

import { defineAppConfig } from '@aleph-alpha/config-unocss';

export default defineAppConfig({
  theme: {
    colors: {
      'brand-bg-brand': '#CCE804',
      'core-bg-accent': '#555CF9',
    },
  },
});

Apps that pulled in extra UnoCSS presets (e.g. presetTypography) or transformers (e.g. transformerDirectives for @apply) layer them on via presets and transformers:

import { defineAppConfig } from '@aleph-alpha/config-unocss';
import { presetAlephAlphaIcons } from '@aleph-alpha/ds-icons';
import { presetTypography, transformerDirectives } from 'unocss';

export default defineAppConfig({
  presets: [presetAlephAlphaIcons(), presetTypography()],
  theme: {
    breakpoints: { xs: '480px', sm: '640px', md: '768px', lg: '1024px' },
    colors: { 'brand-bg-brand': '#CCE804' },
  },
  transformers: [transformerDirectives()],
});

Apps that wrapped theme overrides in their own preset (definePreset) keep that pattern unchanged — defineAppConfig accepts any UnoCSS preset alongside the defaults:

import { defineAppConfig } from '@aleph-alpha/config-unocss';
import { presetAlephAlphaIcons } from '@aleph-alpha/ds-icons';
import { definePreset } from 'unocss';

const presetMyAppTheme = definePreset(() => ({
  name: 'my-app-theme',
  theme: { colors: { 'core-bg-primary': '#FBFBFD' } },
}));

export default defineAppConfig({
  presets: [presetAlephAlphaIcons(), presetMyAppTheme()],
});

Apps with local workarounds (e.g. token-specific alpha-hex fixes, spacing-preset shims for older ds-components-vue versions) keep them local and inject via presets or rules:

import { defineAppConfig } from '@aleph-alpha/config-unocss';
import { alphaFixRules } from './local-alpha-fix';

export default defineAppConfig({
  rules: alphaFixRules,
});

ℹ️ Legacy presetAlephAlpha() (singular) is not re-exported — switch to defineAppConfig() as shown above. If you need the raw preset stack for a custom defineConfig, use the plural presetsAlephAlpha() (see Composing manually).

Exports

• defineAppConfig(options?) — app-oriented defineConfig wrapper, bundles presetsAlephAlpha() + design-system content paths.
• presetsAlephAlpha() — full preset stack (Wind, Typography, web fonts, animations, tokens, theme, legacy compat).
• tokenPreset — only the design-system token preset (CSS variables, theme mapping).
• commonPresets — Wind + Typography + web fonts + animations, without tokens.
• createPresets() — token preset + dark-mode theme preset + legacy compat preset.
• getDesignSystemContentPathConfig(framework) — content pipeline config for scanning @aleph-alpha/ds-components-vue or -svelte.
• Theme — TypeScript theme type derived from the design tokens.
• AppConfigOptions — TypeScript options type for defineAppConfig.
• presetWebFontsAlephAlpha — embedded @font-face rules for Raleway, Roboto, Montserrat, Inter.