@world-vision-canada/wvc-design-system
Version:
WVC Vue Design system is a fork of Vue Design System, an open-source tool for building Design Systems with Vue.js
156 lines (118 loc) • 9.27 kB
Markdown
# 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](https://vuejs.org), [Vue Cli 3](https://cli.vuejs.org/), [Storybook](https://storybook.js.org/), and [Zeplin](https://zeplin.io/), 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 [](https://twitter.com/viljamis) and other contributors, and heavily updated and customized for World Vision Canada by [Michael Peto](mailto:michael_peto@worldvision.ca).
See also [the official website](https://vueds.com) of the original Vue Design System and [read the article](https://viljamis.com/2018/vue-design-system/) 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](https://developer.mozilla.org/en-US/docs/Web/Web_Components).
- Components feature extensive customization options and [Shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) rendering.
- Sandboxed testing environment using [Storybook](https://storybook.js.org/).
- Automatically generated component documentation.
- Integration with UX handoff tools using [Zeplin](https://zeplin.io/).
- 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](https://kazupon.github.io/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](https://vuejs.org/v2/guide/components-slots.html). 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 -vision-canada/wvc-design-system`
or
`yarn add -vision-canada/wvc-design-system`
```
// main.js
import DesignSystem from '-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](https://yarnpkg.com/) as a dependency manager (not npm).*
*Please ensure that [Nodejs](https://nodejs.org/en/) 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:
- [Creating a new component](./src/elements/README.md)
- [Unit testing components](./test/unit/README.md)
- [Writing component stories (Storybook Sandbox)](./src/stories/README.md)
- [CDN embed testing](./test/README.md)
- [Connecting components to Zeplin](./.zeplin/README.md)
- [Updating Design Tokens](./src/tokens/README.md)
- [Updating Light/Dark Theme variables](./src/styles/README.md)
# 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](https://developers.google.com/web/fundamentals/web-components/shadowdom) when rendering components. Please see the [official Vue documentation](https://cli.vuejs.org/config/) 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](https://babeljs.io/docs/en/configuration).
## 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](https://eslint.org/docs/user-guide/configuring).
In this project, ESLint is set to run automatically on staged files when code is committed, using [Lint Staged](https://github.com/okonet/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](https://www.chromatic.com/) 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](https://www.npmjs.com/package/@world-vision-canada/wvc-design-system) is updated.
## Configuration
This Bitbucket CI process can be configured using the `bitbucket-pipelines.yml` file, following [Bitbucket's official documentation](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/).
# Other Documentation
Detailed documentation for each piece of the Design System is located within its respective directory.
# 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](https://cli.vuejs.org/guide/build-targets.html#web-component)).