design-system

You can find storybook here

This project's goal is to create a set of tools that will enable future development to be quicker and more standard, while providing the vcita flavor.

Follow these steps to run the storybook locally

It's highly recommended to use the nvm tool to be able to install various versions of node locally

1. nvm install 20 or switch to node v20
2. npm i
3. nvm install 16 or switch to node v16
4. npm run storybook

Notice that ATM we need to install the dependencies in one node version but then execute it using another TODO: standardise node version for both operations https://myvcita.atlassian.net/browse/VCITA2-2439

Getting started

npm i @vcita/design-system

External Dependencies

This package depends on Vuetify as an external dependency, so your project must have it installed. Currently, the needed version is 2.4.0, we will update this from time to time.

Initializing in your project

To initialize the project create plugins/designSystem.js

// plugins/designSystem.js
import DesignSystem from '@vcita/design-system';
import DesignSystemInit from '@vcita/design-system/init/DesignSystem';
import Vue from "vue";

// Use this in case you want to receive all the components from DS
Vue.use(DesignSystem);

// Use this in case you want to load selectively only the components you need
Vue.use(DesignSystem, { 
  components: {
    VcComponent: () => import('@vcita/design-system/src/components/VcComponent/VcComponent.vue'),
    ...
  },
});
export default DesignSystemInit();

Import into src/main.js and into the vue initialization

// src/main.js
import ds from './plugins/designSystem';

new Vue({
    ...
    vuetify: ds,
    ...
    render: h => h(App)
  }).$mount("#app");

If you need to also adjust some values, such as theme or configurations, it will look something like this:

// plugins/designSystem.js
import Vue from "vue";
import DesignSystem from '@vcita/design-system';
import DesignSystemInit from '@vcita/design-system/init/DesignSystem';

Vue.use(DesignSystem);

const config = {
                  // Your configuration choices
               };

export default DesignSystemInit(config);

All configuration options are specified here

Applying the styling to your project

Create the file src/styles/variables.scss and edit to fit your needs. you may only need the import statement.

@import "~@vcita/design-system/styles/variables.scss";

In order to load the variables.scss file, add this to src/main.js

import "@/../styles/variables.scss";

Create the file src/styles/vuetify-variables.scss

@forward "~@vcita/design-system/styles/vuetify-variables.scss";

// Vuetify variables can be modified here,
// BUT! please consider if they should be set here or in the design system project

In order to load the vuetify-variables.scss file, in vue.config.js add this value

css: {
    loaderOptions: {
      sass: {
        // Here we can specify the older indent syntax formatted SASS
        // Note that there is *not* a semicolon at the end of the below line
        additionalData: `@import "@/../styles/vuetify-variables.scss"`
      },
      scss: {
        // Here we can use the newer SCSS flavor of Sass.
        // Note that there *is* a semicolon at the end of the below line
        additionalData: `@import "@/../styles/vuetify-variables.scss";`
      }
    }
  }

Please note: to receive the theme in your components, make sure to initialize your app using the v-app tag. Your App.vue will look something like this:

<template>
  <v-app id="app">
    ... your components here ...
  </v-app>
</template>

The src/styles/variables.scss file can be used to override some styling variables. You can do this by specifying a different value to one or more of the css variables that have been provided.

For example, to use another font

body {
  --primary-font-family: YourFont;
}

All component styling options are specified here

Using the components

You can now use the components from the new library anywhere in the application, as you normally would

<VcButton>label</VcButton>

Available configuration options

Theme

The default theme values are based on default vcita colors, but they can be set according to the current business. Please note that colors must be set as hex values.

To facilitate that the file colorUtil.js has been included, which contains the following functions:

• rgbToHex() - Use this to convert rgb values to hex values.
• hexToRgb() - If you have other areas in your project that require rgb format, you can use this to convert any hex values to rgb.
• pSBC() - This function can calculate various opacity levels, based on an initial color, and return them in hex or rgb formats, as needed

// stringUtil.pSBC(opacity, baseColor)
stringUtil.pSBC(0.6, this.secondaryColor)

During startup

This is how they can be set during startup of the app:

// plugins/designSystem.js
const config = {
    theme: {
        primary: '#0C315E',
        secondary: {
            base: '#0093B8',
            lighten1: '#99D4E3',
            lighten2: '#C2E5EE',
            lighten3: '#EDF7FA'
        },
    }
}

During runtime

import colorUtil from '@vcita/design-system/utils/colorUtil.js';

this.$vuetify.theme.themes.light.primary = colorUtil.rgbToHex(this.primaryColor);
this.$vuetify.theme.themes.light.secondary = {
  base: colorUtil.rgbToHex(this.secondaryColor),
  lighten1: colorUtil.pSBC(0.6, colorUtil.rgbToHex(this.secondaryColor)),
  lighten2: colorUtil.pSBC(0.76, colorUtil.rgbToHex(this.secondaryColor)),
  lighten3: colorUtil.pSBC(0.93, colorUtil.rgbToHex(this.secondaryColor))
}

Localization

There are a few components that contain localized strings. For example, the wizard and modal components.

Initialization

import initI18n from '@vcita/design-system/init/initI18n';
...
Vue.use(DesignSystem);
initI18n();
...

This will enable the components to use the this.$dst function to get the localized strings.

By default, the texts will be presented in English, so should you need to display them in another locale, this is now you can set the locale as needed.

Available locales: en, de, es, fr, he, it, nl, pl, pt, ru, sl, tr

During startup

// plugins/designSystem.js
import DesignSystemInit from '@vcita/design-system/init/DesignSystem';
...
const config = {...};
const locale = 'yourSelection';
export default DesignSystemInit(config, locale);

During runtime

In a component, such as App.vue, add this call

// App.vue
this.$ds.setLocale(locale);

Component configuration options

VcTextField

Usage of VcTextField with googleAddressAutoComplete set to 'true'

// plugins/designSystem.js
const config = { 
                  options: {googleAppKey: 'yourGoogleAddressKey'}
               };

VcToast

Change VcToast default timeout

By default, the VcToast timeout is 3000ms. You can change that for a specific instance by setting the timeout prop to your desired value. In case you want to change that for the entire project, so any instance will use another timeout value, it can be done by calling this code

// plugins/designSystem.js
const config = {
                  options: {toastTimeout: 5000 }
               };

This will set the default timeout for all instances of VcToast in your project. Any instance that is getting a different value in the timeout prop will keep using that value.

Adding external icons

The package comes with a set of icons already included, which can easily be displayed using the VcIcon component. It is possible to extend that set by creating an object with key-value format

export default {
    yourKey1: `<svg ... /></svg>`,
    yourKey2: `<svg ... /></svg>`,
}

And passing that to the DesignSystem initialization

// plugins/designSystem.js
import extIcons from './yourFile.js';
const config = { 
                  extIcons
               };

Then to use the icons

<template>
    <VcIcon>$yourKey1</VcIcon>
</template>

Automation hooks

In order to facilitate automation, each design system component has a prop called dataQa. This prop has a default value matching the component's name. The value set in this prop will become an attribute on the component instance, which you can use in your automation code, to easily locate the component on the page.

To differentiate different instances, you can pass different dataQa values to different instances.