Kolibri Design System

Usage

How to use the Kolibri Design System

Documentation

See https://kolibri-design-system.netlify.com for the latest design system documentation.

This contains resources for designers and developers who are building Kolibri products using the design system patterns and the shared UI library.

Shared UI library

The shared UI library is a node package containing front-end components, utilities, and style definitions supporting the Kolibri Design System and used in Learning Equality applications.

It is currently hosted only on Github, not NPM. To add a particular pinned version to your project using yarn, run:

yarn add https://github.com/learningequality/kolibri-design-system

You can also specify a particular version of the design system. For example, this would specify v1.0.1:

yarn add https://github.com/learningequality/kolibri-design-system#v1.0.1

Importable components and utilities are available under the lib path, for example:

import KButton from 'kolibri-design-system/lib/KButton';

Refer to the documentation for specifics.

The shared UI library is made available as source code, not a built distribution, and requires the external application to supply both build and runtime dependencies such as webpack, Vue, and Sass. These requirements will eventually be specified in /package.json as peerDependencies.

The public API of the shared UI library is only that which is documented in the documentation. Functionality which is not documented should be considered either experimental or a private implementation detail.

Development of the documentation site

How to make updates to the Kolibri Design System

Overview

The design system has two primary components, the shared UI library (under /lib) and the documentation site (under /docs).

The shared UI library code is built from Vue, Javascript, and Sass. It requires the dependencies specified under the dependencies and peerDependencies attributes of /package.json. An external application will import and functionality from kolibri-design-system/lib as described in the documentation, and then generate build artifacts as necessary for the application's specific deployment or distribution requirements.

The documentation site is built using NuxtJS, Storybook, and Vue. It requires the dependencies specified in the devDependencies attribute of /package.json to build and run. The documentation site can either be run locally using the Node.js development server, or exported as a static site and uploaded to a CDN.

Running the documentation locally

Clone this repository using Git, optionally forking it first if you plan to submit changes.

Install the dependencies using yarn:

cd design-system
yarn install

Run the development server using

yarn dev

This will launch a documentation development server at http://localhost:3000/. It also launches a linter and auto-formatter based on the kolibri-tools package.

There are few other commands available:

yarn dev-only    # launch just the dev server without the linter and auto-formatter
yarn generate    # build a static version of the site for upload to CDN
yarn lint-fix    # run the linter and auto-formatter once
yarn lint-watch  # run the linter in watch mode, without the auto-formatter

Making changes

The documentation site is built using NuxtJS (configured in /nuxt.config.js), Storybook, and Vue.

The directories and files in /docs/pages/ are mapped by NuxtJS to URLs. Start with those files for making updates to documentation content.

Common components used in the documentation site are in /docs/common/, and the primary page layout is /docs/layouts/default.vue.

Design of the documentation site

The documentation site itself intentionally does not conform to the design system it describes, for two reasons:

1. The user-interface of the site (links, buttons, headers, etc) is intentionally built without depending on the Kolibri shared UI library. This helps ensure as we update the UI library, we only need to update content and examples in the documentation, not the implementation of the documentation.
2. From a design perspective, it's important that the documentation site looks and feels sufficiently distinct from the design patterns it describes, so that users do not mistakenly immitate it. Instead, users should focus on the patterns that are explicitly documented.

From a coding perspective this means that references to ~~/lib code should in general only appear in ~/pages/ as illustrations of the shared UI library. However, we might decide on a case-by-case basis to have occasional exceptions to this rule. For example, we currently use ~~/lib/KResponsiveElementMixin inside ~/common/Header because it would be excessive to duplicate that functionality.

Routing

We do not use client-side routing. The reason is that we make extensive use of #anchor links, and there are many issues in both NuxtJS and Vue Router with mixing anchors and client-side routing. In practice, this means that there should be no instances of <router-link> or <nuxt-link> in documentation code.

Import aliases

NuxtJS provides two webpack import aliases:

• ~~/ points to the root of the repository
• ~/ points to the /docs directory

These aliases should not be used by code inside the /lib directory because external webpack configurations will not handle them correctly.

Deployment

The documentation site is currently deployed to Netlifty automatically when changes are pushed to one of the primary branches. This is configured in the /netlify.toml file and authenticated with the Netlify GitHub app.

Longer-term, we will likely want to transition to Google Cloud for more control of the deployment. Specifically, we'll want to