DEMV Design System

This repository contains the design standard for the products of DEMV Systems.

Installation

1. Install the package:

   yarn add @demvsystems/design-components

   The DS needs Tailwind CSS to function properly. See their docs on how to install it.

2. Register the DS in you tailwind.config.js

   module.exports = {
     plugins: [
       // load the design system tailwind plugin
       require('@demvsystems/design-components').tailwindPlugin,
     ],
      
     content: [
       // ...
       // the DS ships without any tailwind css,
       // so you have to reference the components location here
       './node_modules/@demvsystems/design-components/dist/design-components.mjs',
     ],
   };

3. Import the css for our font into your main css file.

   @import url(https://d33aibdhl8v9sf.cloudfront.net/inter.css);

4. Since we're using Font Awesome for the icons, you have to follow these steps to integrate the FA library:

   1. Add this to you .npmrc file (create it in your project root if it doesn't exist):

      @fortawesome:registry=https://npm.fontawesome.com/
      //npm.fontawesome.com/:_authToken=${NPM_FONTAWESOME_AUTH_TOKEN}
      
      @tiptap-pro:registry=https://registry.tiptap.dev/
      //registry.tiptap.dev/:_authToken=${NPM_TIPTAP_PRO_AUTH_TOKEN}

      [!NOTE] The FONT_AWESOME_NPM_TOKEN and NPM_TIPTAP_PRO_AUTH_TOKEN are secrets that you have to get from Bitwarden.

   2. Install these fontawesome packages

      yarn add @fortawesome/fontawesome-svg-core @fortawesome/vue-fontawesome@latest-3 @fortawesome/pro-solid-svg-icons @fortawesome/pro-regular-svg-icons @fortawesome/pro-light-svg-icons @fortawesome/pro-duotone-svg-icons

   3. Add icons that you use to you project like so:

      [!NOTE]
      All icons needed for the design-system are automatically bundled when you import them.

      // example path: /assets/Icons/icons.ts
      import { library } from '@fortawesome/fontawesome-svg-core';
            
      // Solid
      import {
        faCircleNotch as fasCircleNotch,
      } from '@fortawesome/pro-solid-svg-icons';
            
      // Regular
      import {
        faSync as farSync,
      } from '@fortawesome/pro-regular-svg-icons';
            
      library.add(
        fasCircleNotch,
        farSync,
      );

   4. Include your icon configuration in your main setup file (app.ts, main.ts. ...), e.g.

      ...
      import '@/assets/Icons/icons';
      ...

Contributing

Contributions should be done in form of a pull request that is approved by at least one other programmer.

Commit messages must follow the Conventional Commits specification.

Release

Releases are triggered automatically on merge to main by semantic-release. Therefore, it is necessary that the PR merge commit has a semantic commit message.

[!IMPORTANT] Breaking changes should always be communicated by adding BREAKING CHANGE: in the commit footer (See the Conventional Commits specification). This automatically results in a major version change, which indicates a breaking change.

[!WARNING]
Not all semantic commit messages trigger a release. See the semantic-release readme for more information.

Setup

You can set up design-system with docker or locally on your machine.

Docker

1. Copy the .env.dist file to .env:

   cp .env.dist .env

   The NPM_FONTAWESOME_AUTH_TOKEN can be found in Bitwarden.

2. run docker compose up -d

3. (optional) add 127.0.0.1 design.demv.internal to your systems hosts file.

4. design-system should be available at http://localhost:3099 (or http://design.demv.internal)

Local

1. Copy the .huskyrc.dist file to .huskyrc:

   cp .huskyrc.dist .huskyrc

   The NPM_FONTAWESOME_AUTH_TOKEN can be found in Bitwarden.

2. Add the following line to your .bashrc or .zshrc:

   if [ -f .env ]; then
     export $(cat .env | xargs)
   fi

   Then run source ~/.bashrc or source ~/.zshrc to apply the changes.

3. Make sure Node 20 is installed

4. yarn install to install dependencies

5. Start dev watcher yarn dev

6. design-system should be available at http://localhost:3000 (or :3001 if :3000 is occupied etc.)

Creating a new component

Our components are written in Vue 3 TypeScript with the Composition API.

1. Create a folder for your new component in /src/components.
2. Inside the new folder:
   1. Create your component(s). Each component should be prefixed with Ds: Ds<ComponentName>.vue.
   2. Create an index.ts file. Here you should export your component(s), types, composables, etc.
   3. Create a file <componentName>.stories.ts. In here you may later add usage examples in form of stories. See storybook documentation for help.
3. Register your component in /src/components/index.ts
4. Start developing!

Icons

There are two locations to register icons. Which one should be used depends on whether an icon is used in a component or only in a story:

• /src/icons.ts for icons that are used by components and should be included in the bundle
• /.storybook/icons.ts for icons that are only used in a story

Z-Index

Please make sure, DsPopover always uses the max z-index in the whole project. Otherwise, it will interfere with DsModal e.g.

Right now, we have the following stack:

DsPopover - z-[1000]
DsModal - z-[999]
... all the other components

Test changes locally within another repository

If you want to test your changes with a local project where you include the DesignSystem package, do the following:

1. Make your changes
2. run yarn build
3. go to you local project and add the DS dependency like this: "@demvsystems/design-components": "file:/home/xyz/DEMV/design", (obviously use your local path to the DS repo ;))
4. install the dependencies in your local project by running your package manager yarn || pnpm i

Now you should have the local changes available in your project to test against your actual application. If you do further modifications to the DS, you always have to run the build (Step 2) first and then update the ds dependency in the local project like this:

yarn|pnpm upgrade @demvsystems/design-components

This is necessary to reflect every change made in the DS.

Happy testing