@makesenseorg/design-system

Makesense design system

The makesense design system is build to make makesense design guidelines and Vue component available accross our multiple web applications.

Living styleguide demo: https://makesense-design-system.netlify.com

Table of content

1. Use in a Vue app
   1. Install dependency
   2. Import in the app
   3. Change the theme colors
   4. Import the styles and variables
   5. Usage
2. Use in a Nuxt app
   1. Add as a dependency
   2. Create a plugin
   3. Change the theme colors on client side
   4. Import the styles and variables
   5. Usage
3. Contributing
   1. Developing
   2. Testing
   3. Building
   4. Publishing

Use in a Vue app

1. Install dependency

npm i @makesenseorg/design-system

2. Import in the app

Import the design system in the app entry file (usually index.js or main.js)

import DesignSystem from '@makesenseorg/design-system'
import '@makesenseorg/design-system/dist/system.css'

Vue.use(DesignSystem);
...

3. Change the theme colors

Just below, load the app theme, to get all the colors related to your app. The theme needs to exist in the design system. (list of available themes in ./src/tokens/themes) The default name is base.

...
Vue.prototype.$loadTheme('base')

You can also change the theme using this.$loadTheme(theme_name) inside a view or a component.

4. Import the styles and variables

In order to have access to the design system variables and mixins, you need to import the shared.scss file. Note: You might need to run npm install node-sass@4.14.1 sass-loader@7.1.0

// globally inside vue.config.js
module.exports = {
  css: {
    loaderOptions: {
      sass: {
        data: `@import "@makesenseorg/design-system/dist/shared.scss";`,
      },
    },
  },
};

✨ You're done! You can now use the components, mixins, scss variables. ✨

5. Usage

In your App or in your app components, use the design system components like so :

<template>
    <div class="my-app">
        <mks-heading tag="h1">Hello world !</mks-heading>
    </div>
<template/>

<script>
import MksHeading from "@makesenseorg/design-system/dist/components/Heading.vue";

export default {
  name: "App",
  components: { MksHeading }
}
</script>

<style lang="scss">
.my-app {
  background: $color-primary;
}
</style>

Use in a Nuxt app

1. Add as a dependency

npm i @makesenseorg/design-system

2. Create a plugin

Add the plugin in nuxt.config.js.

plugins: ["~/plugins/design-system"],

Create the file design-system.js in plugins folder.

import Vue from "vue";
import DesignSystem from "@makesenseorg/design-system";

Vue.use(DesignSystem);
...

3. Change the theme colors

In order to change the theme color, you can use the function loadTheme, in plugins/design-system.js. The theme needs to exist in the design system. (list of available themes in ./src/tokens/themes) The default name is base.

...
if (process.client) {
  Vue.prototype.$loadTheme('jobs')
}

You can also change the theme using this.$loadTheme(theme_name) inside a view or a component.

⚠️ Warning ⚠️ It is important to only use loadTheme on the client side, as it would throw a document is not defined error on the server side.

4. Import the global CSS styles

In order to have access to the design system variables and mixins, you need to import the shared.scss file either locally in each component, or once globally in the app. The system.css file is a global file providing reset classes, fonts, and basic styling. The base.css and jobs.css register the design tokens as CSS variables. It is important to load them here to prevent a jump on first client load.

Note: You might need to run npm install node-sass@4.14.1 sass-loader@7.1.0

1. Install style-ressources

In order to load the styles globally, you need to install style-resources module

npm install --save-dev @nuxtjs/style-resources

2. Update nuxt.config.js

In nuxt.config.js, register the module and add the style files

css: [
    "@makesenseorg/design-system/dist/system.css",
    "@makesenseorg/design-system/src/system/tokens/generated/themes/base.css",
    // you need to specify your theme here to make sure it's loaded on server side
    "@makesenseorg/design-system/src/system/tokens/generated/themes/jobs.css"
  ],
modules: [
    '@nuxtjs/style-resources',
],
styleResources: {
    scss: [
      "@makesenseorg/design-system/dist/shared.scss",
    ],
},

✨ You're done! You can now use the components, mixins, scss variables. ✨

5. Usage

In your App or in your app components, use the design system components like so : You can use atoms directly without importing them. However for layouts and molecules, you need to manually import and register the component

<template>
    <div class="my-app">
        <!-- example with an atom -->
        <mks-heading tag="h1">Hello world !</mks-heading>
        <!-- example with a molecule -->
        <mks-site-footer>Made by makesense</mks-site-footer>
    </div>
<template/>

<script>
import MksSiteFooter from "@makesenseorg/design-system/dist/components/SiteFooter.vue";

export default {
  name: "App",
  components: { MksSiteFooter }
}
</script>

<style lang="scss">
.my-app {
  background: $color-primary;
}
</style>

Contributing

npm install

1. Developing

Compiles and hot-reloads living styleguide

npm run dev

2. Testing new components in a live playground

Compiles design system and uses it in a nuxt app. Before publishing new components, please test them in this playground app.

The first time you use the playground, run :

npm run install-playground

When you want to test a component in the playground, run :

npm run playground

Note: the command takes a while because it needs to build the system first in order to inject it as a dependency in the playground.

3. Building

Living styleguide

Compiles living styleguide to ./docs

npm run build

Library

Compiles design system as a library to ./dist

npm run build:system

4. Helper

Serve living styleguide locally

for example to develop on another application with a newer version of the styleguide

npm run serve

Lints and fixes files

npm run lint

5. Publishing

The repo is automatically publish when the version is updated and pushed to master.

Semantic versioning rules

Code status	Stage	Rule	Example version
First release	New product	Start with 1.0.0	1.0.0
Backward compatible bug fixes	Patch release	Increment the third digit	1.0.1
Backward compatible new features	Minor release	Increment the middle digit and reset last digit to zero	1.1.0
Changes that break backward compatibility	Major release	Increment the first digit and reset middle and last digits to zero	2.0.0

Thanks

Thanks to CION design system for providing the design system boilerplate.

License

MIT License - Copyright (c) Makesense