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. Runnpm 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)
- goto the
-
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 usedl-
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 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