@world-vision-canada/wvc-design-system NPM

World Vision Canada // Lumen Design System

World Vision Canada's Lumen Design System is intended to be the single source of truth for WVC's UX components across all platforms.

The tool is built on top of Vue.js, Vue Cli 3, Storybook, and Zeplin, and is aimed for designers and front-end developers who have at least basic knowledge of Vue, component based workflows + HTML, SCSS & JavaScript testing procedures.

*Originally based off of Vue Design System*, made by @viljamis and other contributors, and heavily updated and customized for World Vision Canada by Michael Peto. See also the official website of the original Vue Design System and read the article on the processes and workflow the original author uses to get started with a new design system project.

Features

Library of components built as self-contained web components, according to the Web Component Spec.
Components feature extensive customization options and Shadow DOM rendering.
Sandboxed testing environment using Storybook.
Automatically generated component documentation.
Integration with UX handoff tools using Zeplin.
Test driven development through automated specs (Jest unit tests as specification).
Easily export and use the Design System in another Vue project or as a standalone, embedded script via CDN.
Pre-configured Prettier and ESLint setup for auto-formatting code on both save and before commit.
Live Reloading, SCSS, and helper functions, as well as SVG support.
Internal localization using Vue i18n.

Getting Started

Using inside an HTML project

In the <head> place:

<script src="https://unpkg.com/@world-vision-canada/wvc-design-system@1.0.2/dist/wvc.umd.min.js"></script>

Replacing @1.0.2 with the correct version number.

Then in the body, use whatever component you wish, prefixed with wvc-, like so:

<wvc-button></wvc-wvc-button>

Parameters can be passed to components through html properties on the tags. In addition, some components can take in html content within the beginning and end tags, using Vue's slots feature. For example:

<wvc-button size="large">Test Button</wvc-button>

Note: Component parameters that have camelCased names, like backgroundImage, must use kebab-case when they are used in HTML. For example backgroundImage becomes background-image:

<wvc-card background-image="/path/to/test/image">
    <h4>Test Card</h4>
</wvc-card>

Using inside a Vue project

npm install --save @world-vision-canada/wvc-design-system or yarn add @world-vision-canada/wvc-design-system

// main.js
import DesignSystem from '@world-vision-canada/wvc-design-system'

Vue.use(DesignSystem)

// ExamplePage.vue
<template>
    // note that when imported as a Vue component, it is not necessary to add `wvc-` prefix.
    <Button>Example Lumen Component</Button>
</template>

<script>
export default {
  name: 'App',
  // note, no need to specify imported component here
  components: {
  }
}
</script>

Development Installation

Note: This package uses Yarn as a dependency manager (not npm). Please ensure that Nodejs v12.19.0+ (including build tools, if on Windows) and Yarn v.1.22.5+ are installed before using.

Open the command line and type yarn install in the root directory of the project.

Running the Project

To run a local development environment, run yarn dev.
To run the storybook sandbox, run yarn storybook or yarn start.
To lint (error check) your code, run yarn lint.
To run unit tests/specs, run yarn test.
To build the design system for production, run build:js. (Note: for Windows systems, when building locally, run build:js-local).

Development Guides

More detailed documentation on the various elements of Lumen are included in README.md files throughout the source code. For quick reference, please find a few links to important documentation below:

Project Configuration

Vue Cli

Vue Cli and Webpack can be configured using the vue.config.js and vue.system.config.js files, for the HTML build and the Vue build of the component library, respectively. Note that the major difference in the HTML build is the use of the Shadow DOM when rendering components. Please see the official Vue documentation for more information on how to configure Vue for various build environments.

Babel

Babel is a polyfill library used to convert contemporary JS code into forms that older browsers can use when needed. It is currently set up to automatically convert code as necessary to target the browsers listed in the browserList section of package.json. It can be configured in more detph using the babel section in package.json. Please see the official Babel documentation.

ESLint

ESLint is a plugin used to lint (or "autocorrect") simple JS errors and style anomalies. It can be configured using the .eslintignore file and the eslintConfig section in package.json. It is currently set up for compatibility with Vue and the Prettier preset, with some style modifications. Please see the official ESLint documentation. In this project, ESLint is set to run automatically on staged files when code is committed, using Lint Staged. The configuration for Lint Staged is available in the .lintstagedrc file.

Prettier

Prettier is a plugin used to format JavaScript code and ensure that its styling is uniform throughout the codebase. It can be configured using the .prettierrc and .prettierignore files.

CI Using Bitbucket Pipelines

This project is set up to use Continuous Integration provided by Bitbucket Pipelines.

Feature branch commits

When any branch is added to a Pull Request pointing at staging or master, unit tests, a test build, and storybook are run automatically to ensure that the code builds without errors and passes all tests, to make the PR approval process faster.

Staging branch commits

Once code is merged to staging, a series of tests (including unit tests) are run against the code, before a copy of its Storybook files are deployed a static Storybook instance on Chromatic for visual testing and sign off. The link to this sign-off page is available within the Bitbucket Pull Request.

Master branch commits

When a commit is pushed to the master branch in Bitbucket, the code is synchronized with our Zeplin project instance and the NPM package for Lumen is updated.

Configuration

This Bitbucket CI process can be configured using the bitbucket-pipelines.yml file, following Bitbucket's official documentation.

Note: IE11 Compatibility

IE 11 is not officially supported by Vue's Web Components library. However, this project is transpiling the Vue web components library separately as part of the build process, to force IE11 support, using the prebuild script in package.json. This is also why there is a separate babel.config.json file in the root, as well as Babel config in package.json - one is used to transpile the project, and one is used to transpile the Vue core libraries themselves.

When IE11 compatibility is no longer a supported feature, we can move to using vue-cli-service's built in --target wc-async build option for the entire components, elements, and templates folders, and stop using the components.js entrypoint. See the package.json file's build script in older, pre ie11-shim branch commits for this implementation. This would remove the need for a prebuild script and importing components manually via a components.js file, as the built-in Vue web component build process takes care of importing all components within a range of directories (see Vue web component build configuration documentation).