@aleph-alpha/ds-components-vue NPM

Aleph Alpha Design System Vue Components

@aleph-alpha/design-system-vue

This package provides a collection of Vue components that adhere to the Aleph Alpha Design System guidelines. It aims to simplify the process of building consistent and visually appealing user interfaces across various projects.

Installation

To integrate the Aleph Alpha Design System Vue Components into your project, install it using your preferred package manager:

pnpm add @aleph-alpha/ds-components-vue

Storybook

The storybook is made available via GitLab pages here: https://gitlab-pages.aleph-alpha.de/engineering/frontend-hub/storybook/ui/

Usage

To use the components in your Vue project, follow these steps:

Install Design System Plugin

Import the DesignSystem plugin in your main application file (usually main.js or main.ts):

// Style imports
import '@unocss/reset/tailwind.css';
import 'uno.css';
import 'virtual:uno.css';

import DesignSystem from '@aleph-alpha/ds-components-vue';
app.use(DesignSystem);

CSS Setup

To get the styling for the components applied in your application, you need to set up UnoCSS in your project. UnoCSS is a utility-first CSS framework that allows for a more efficient and consistent styling approach.

For detailed instructions on setting up UnoCSS, please refer to the UnoCSS Installation Guide. This guide will walk you through the process of installing UnoCSS and configuring it for your project.

After setting up UnoCSS, you need to use the Aleph Alpha CSS preset to apply the styling for the components in your application.

To apply the Aleph Alpha CSS preset, you need to add it to your UnoCSS configuration.

// unocss.config.ts
import { defineConfig } from 'unocss';

import { presetAlephAlpha, designSystemContentPathConfig } from '@aleph-alpha/config-css-preset';
import { presetAlephAlphaIcons } from '@aleph-alpha/ds-icons';

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

Now you can use the components in your Vue components via the global plugin like this:

<template>
  <div>
    <AaButton>Click Me</AaButton>
  </div>
</template>

or you can import the components directly in your components like this:

<template>
  <div>
    <AaButton>Click Me</AaButton>
  </div>
</template>

<script>
import { AaButton } from '@aleph-alpha/ds-components-vue';
</script>

Instructions on theme customization

You can customize the theme by extending it. The theme tokens can be found here

NOTE: This only works for the default light theme. Dark mode is not supported yet.

// unocss.config.ts
export default defineConfig({
  ...getDesignSystemContentPathConfig('vue'),
  presets: [presetAlephAlpha()],
  extendTheme:  (theme) => {
    return {
      ...theme,
      colors: {
        ...theme.colors,
        'brand-bg-brand': 'yellow',
        'core-bg-primary': 'red',
      },
    }
  },
});

For Developers

You can view the components in the storybook by running:

nx run ds-components-vue:storybook

To publish the packages locally, execute

nx run ds-components-vue:build
nx run ds-components-vue:publish:local

To use them in your application go to your app and run

yalc add <PACKAGE>
e.g. yalc add @aleph-alpha/ds-components-vue@0.15.0

For further information see the yalc package

Note: putting a release happens automatically after merging an MR to the main branch. In the case where your commit messages contain commitlint types like "style", "refactor", or "chore", it won't trigger a release.

Contribute

When adding a new component, it needs to adhere to a certain directory structure to be exposed in the published package. Every new components need to be either placed in the elements, patterns or interfaces directory. The component should be placed in a subdirectory with the same name as the component. The component subdirectory needs to include a index.ts, which exports everything you want to expose in the published package. Typically, this would include the component itself, child components and any other types or utilities that are helpful to use the component. The component subdirectory should also include a *.stories.ts file for the storybook and a __tests__ directory for the tests. Here is an example for a new component called AaButton:

ds-components-vue
└── src
    └── components
        └── elements
            └── AaButton
                ├── index.ts
                ├── AaButton.vue
                ├── AaButton.stories.ts
                └── __tests__

// index.ts
export { default as AaButton } from './AaButton.vue';
export * from './types';

Layout / visual regression tests

Layout tests (aka visual regression or snapshot tests) are done using storybook and test-runner (link).

To run the tests locally execute:

nx run ds-components-vue:test:storybook

The executed command will report any stories with detected differences between the expected and the actual screenshot.

If the layout tests fail, but the changes are intended, you can update the reference snapshots (for both local/darwin and CI/linux platforms) by running:

nx run ds-components-vue:test:storybook:update

Caveat: This will override your node_modules with modules from a different store (the store inside the docker container) - so afterward it will be necessary to run pnpm install in your terminal again.