@vcita/design-system
v1.17.7
Published
vcita design system
Downloads
1,370
Maintainers
Keywords
Readme
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.
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.