Storybook-delaval NPM

Storybook

Commands

Run the storybook in localhost

npm run start or npm run storybook

Run the vue-application without storybook

npm run serve

Build the storybook for dev.storybook.delaval.cloud

npm run build-storybook

Build the common-design

npm run build

How the snapshot tests work

In our files called *.snapshot.spec.js we iterate all stories and take a screenshot of it and compare to the latest screenshot.

This works consistently in the pipelines, however the local version of the same images sometimes have a small offset.

Suggestion of how to handle the difference between local and pipeline-job

Use only images from the pipeline!

The suggested flow is like this:

Commit your changes to a feature branch
Let the pipeline run. Wait until the test-components job fail:
The first time you run this you need a personal token to fetch a artifact from gitlab
- goto the snapshots folder. Run npm install.
- Copy the file .env template to a file called .env
- Create a personal token with api permission here https://gitlab.delaval.cloud/-/profile/personal_access_tokens
- Add the token to the .env file (and dont commit this file, its added to .gitignore)
Run cd snapshots && node index.js
- This will download the artifact from the latest pipeline in you local branch and replace you current images with the new ones.
Commit the new images that you think are correct, and revert the images that are wrong and fix the error in the code.
Then we can see in the MR how the components will change with your new code.

Getting Started Guide for Developers

The DeLaval Design System contains a collection of Vue components that can be used to build accessible and performant Vue applications consistent with DeLaval brand guidelines.

This getting started guide provides the basic instructions to install the DeLaval Design System components as a dependency in your micro frontends and begin using those components. The documentation for each individual component provides more detailed information including:

An overview with contextual usage guidance and best practices
Examples of common variations of the component such as sizes and states using props and slots
Guidance for using the components with accessiblity in mind
A detailed description of available Vue props and slots along with an interactive playground environment

Developing this project

Developing new components and modifying the existing components are required when the programmer sends a request as per his need to UX Designer and UI Developer. Following are the steps needed for new developer to get started as soon as possible.

Jira Stories

Go to Design System UI Components in Jira to see the available component requirement.
Change the status of the story to SELECTED FOR DEVELOPENT.
Assign the task to yourself.

UX Design

UX Designers use Figma. Install Figma and sign in with company email
Go to Figma Designs.
If you don't have the access to these, ask for the access at UX Slack Channel

Code Environment Setup

At this point you have a component to develop, let's say 'Demo Component'.
To develop a new component or modify the component, one requires Storybook repo
Take the latest pull of master branch before starting the new work
Create a feature branch and checkout into it, like this: git checkout -b feature/demo-component
Remember to start the name of the branch with feature/
Install all the dependencies. npm install
To run the standalone vue application: npm run serve
To run the storybook: npm start

Component Guidelines
Do not be create components using other css frameworks like booststrap or Vuetify

For making a new component consider naming convention, folder structure, general style rules
We are following Atomic Design to organize all components
Based on Atomic Design, consider where your component fits in the category (e.g. atom/molecules/organisms/templates/pages)
Create a folder inside respective category as per component. e.g. button, input, toggle, etc.
Inside the folder create a Component.vue file with vue template syntax.

<template>
</template>

<script>
</script>

<style scoped>
</style>

Familiarize with the CSS class naming convention (dl-something). Example.
Use dl- prefix for some main parts of components like wrappers (dl-wrapper, dl-tabs, dl-toggle, dl-segmented-wrapper), containers (dl-accordion, dl-accordion-header) or some other repetitive and distinctive elements (dl-input, dl-label, dl-checkbox). Decided to don't use dl- prefix for nonrepetitive, not distinctive or class used to force some state/mechanism (JavaScript) than CSS style (showmore).
Remember to use scoped CSS for style tag.
If other components are required in your component (e.g. button, toggle, etc ), you can use them. They are registered globally
Follow all the rules and guideline of UX Design of your component. The final component should reflect all the states and variations of the UX design. For doubts, addition and modification of the UX design post the message on UX Slack Channel
For developing the component, you can use both vue standalone and/or Storybook
Ensure backward compatibility of the component. e.g. don't remove/rename props in component modification.
To register the component go to src/components/index.ts. import and export the comonent as below.
The name of the component while exporting must start with Dl as in DeLaval

import DlInput from "./atoms/input/Input.vue";
export { DlInput };

Storybook Guidelines:

Please go through documentation of Storybook.js to learn about how to write stories
Story name must include .stories.js/jsx/ts/tsx at the end of filename. e.g. input.stories.js. Make this file inside the component folder.
Only show props or slots that are required for changing the state and variation of the component
Title parameter in default export should match with atomic design. e.g. atom/Input
Add status of the component with status parameter as below

status: "stable", // stable | beta | deprecated

stable is for finished component. beta is when component is work in progress or test/verification. deprecated is for components that should not be used longer.
Make all the stories as given in UX design

Use a local storybook in plus

Go to https://dev.plus.delaval.cloud/ in browser
Run this on browser console

localStorage.setItem("devtools", true); // returns undefined

Refresh the page. Click on the red icon that will appear in the bottom right corner

override

Override common-design with http://localhost:5000/storybook-main.umd.min.js
In storybook run npm run serve:for-portal this command will rebuild the package on change.
refresh the page to take the effect

Use the component:

Go to https://dev.storybook.delaval.cloud/
Choose any component from the left navigation. Let’s say “Atom/Button” component
Go to Docs section. Change the props as required
Click on “Show code”
Click on “Copy” or copy particular code
<template /> will not create any new node. It will be simply ignored by the vue
Paste the code in the file where you want to render this component in your micro frontend. (e.g., src/components/FileName.vue)
Go to the page location in browser (e.g., customers or settings page) . And refresh the page
Voila ...! There will be the new component
After using the component, make sure the style rules are not in conflict.

Verify with UX Designer

After completing the component, the next step is Test/Verify
Push code of your branch to the gitlab
After the CI/CD pipeline succeeds, your build for storybook is deployed separately for your branch like below
If your branch name is feature/input your storybook deployment should be at https://dev.storybook.delaval.cloud/input/index.html
Send this link to UX Slack Channel
Assign the Jira story to corresponding UX Designer and mark it as TEST/VERIFY
Get the feedback from UX designer and modify the changes.

Verify with Portal Squad

After getting the green light from UX Team, create a merge request to master branch
Share the link on Portal Slack Channel for reviewing the code
Get the feedback from Portal Squad and modify the changes
After the CI/CD pipeline succeeds, you can see the storybook at https://dev.storybook.delaval.cloud/
And yeah ...! These are the only few steps to make the component