Installation

These instructions may change.

The JDS is still in its early days, and we may still make high level changes, such as what we call the package itself, where the repository is located, and how you import components, as the system matures. Keep an eye on Slack #development for updates.

The Jobilla Design System is managed on Gitlab.

Setup for Jobilla frontend repositories

If you're working on a repository that uses the JDS — including most Jobilla frontend projects, such as JobillaWebSPAs — then you need to set up your local development environment so you can install the JDS as a dependency.

This procedure is required to run yarn on your project, and to add the JDS to an existing project.

Requirements

  1. Yarn to install dependencies.
  2. A GitLab account with permissions to access the Jobilla organization.

Setup steps

  1. Obtain a new Gitlab Personal Access Token from your User Settings. Give it the read_api scope to grant access to the package registry.
  2. In your terminal, replacing $GITLAB_TOKEN for the token you just generated, run: 
    npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' $GITLAB_TOKEN
npm config set '//gitlab.com/api/v4/projects/:_authToken' $GITLAB_TOKEN
  3. Run yarn like usual.

Adding the JDS to a project

Follow these instructions to start using JDS components in a frontend project.

  1. Follow the "Setup Steps" above to ensure you can authenticate to Gitlab .
  2. Within your project's .yarnrc file as a separate line: 
     "@jobilla:registry" "https://gitlab.com/api/v4/packages/npm"
    This registers the Jobilla private package registry for @jobilla packages.
  3. In your terminal, while in the project root directory, run: 
     yarn add @jobilla/jobilla-design-system
  4. In your vue entry file (often main.ts), apply the JDS as a vue plugin: 
    import { JobillaDesignSystem }from '@jobilla/jobilla-design-system'
Vue.use(JobillaDesignSystem)
  5. To add the JDS-required CSS to your project, if you're running a Vue frontend, in the src/main.ts (or other entrypoint) file, add: 
     import '@jobilla/jobilla-design-system/jds.css';
  6. JDS components are globally loaded, so you can directly use the component normally: 
    <jds-button>Hello World</jds-button>
  7. The JDS has some top-level Providers which you should place near the top of your DOM tree. These providers let you pass in global configurations to the JDS, which get passed down to JDS components down the tree. See the LocaleProvider and TextProvider.

Peer dependencies

The JDS relies on a few peer dependencies which you are expected to install:

Vue-tippyyarn add vue-tippy@^4.5.1, and Vue.use(VueTippy).
portal-vueyarn add portal-vue@^2.1.7, and Vue.use(PortalVue).
vee-validate v3

yarn add vee-validate@^3.0.0, and: 

import { ValidationProvider, ValidationObserver, extend } from 'vee-validate'

Vue.component('ValidationProvider', ValidationProvider)
Vue.component('ValidationObserver', ValidationObserver)

vue-i18nyarn add vue-i18n@^8.0.0, and wire up to the Jobilla translation management system.
inert

yarn add wicg-inert, and import "wicg-inert" in the main script file.

You may need a separate CSS file, depending on your content security policy settings.

Debugging

  • Getting a 403 Forbidden on yarn add: make sure you've completed the "Setup Steps" to add your authentication token.
JOBILLA DESIGN SYSTEM