JSPM

Kirby Design System

About

Kirby Design System is a UX Component library implementing the Kirby Design Philosophy.

Kirby Components are built on top of Angular and can be used in Angular projects.

The Kirby Cookbook, containing samples, status of components etc. can be accessed from https://cookbook.kirby.design.

Note

Please note: The package currently contains the uncompiled typescript (.ts), markup (.html) and styling (.scss) source code. See the Installation section below on how to enable typescript compilation of the package in your project.

Table of Contents

• Installation
  • devDependencies
  • Typescript Configuration
  • Sass
  • Ionic
  • Icons
  • Testing
• Polyfills
• Chart Components

Installation

Install through npm:

npm i @kirbydesign/designsystem

devDependencies

As devDependencies of the npm package doesn't automatically get installed, you also need to install node-sass, sass-extract, sass-extract-loader and ng-mocks (remember to include the -D flag):

npm i node-sass sass-extract sass-extract-loader ng-mocks@7.7.0 -D

Typescript Configuration

Please note: To enable typescript compilation of the package in your project, you need to add the following to your tsconfig.json:

...
  "include": [
    "./src/**/*",
    "./node_modules/@kirbydesign/designsystem/**/*.ts"
  ],
...

Please also note: If you overwrite include in tsconfig.app.json you need to add the configuration to this file as well - pay attention to the additional folder level (../):

...
  "include": [
    ...,
    "../node_modules/@kirbydesign/designsystem/**/*.ts"
  ],
...

For testing purposes Kirby includes a testing module. To avoid including this in your app, you need to add the following to your src/tsconfig.app.json:

...
  "exclude": [
    ...
    "../node_modules/@kirbydesign/designsystem/testing/**/*.*",
    ...
  ],
...

To enable typescript compilation of the package in your unit tests, you need to add the following to your src/tsconfig.spec.json:

...
  "include": [
    ...
    "../node_modules/@kirbydesign/designsystem/**/*.ts",
    ...
  ],
...

Sass

Include the Kirby global styles in your app:

• Eg. in src/styles.scss:

  @import '~@kirbydesign/designsystem/scss/global-styles';

  In each .scss file where you need to access the Sass utility functions from Kirby (e.g. colors or fonts) you must import the scss utilities:

@import '~@kirbydesign/designsystem/scss/utils';

Ionic

The Kirby web components are build on top of Ionic. The @ionic/angular package should automatically be installed as a dependency of Kirby. If not, please execute the following:

npm i @ionic/angular

Icons

Kirby comes bundled with a default set of icons. Make sure the .svg files used by Kirby are copied to your output folder by adding the following to build > options > assets in angular.json:

{
  ...
  "build": {
    "options": {
      "assets": [
        ...
        {
          "glob": "**/*.svg",
          "input": "node_modules/@kirbydesign/designsystem/icons/svg",
          "output": "./assets/kirby/icons/svg"
        },
        ...
      ],
    }
  }
}

Testing

Kirby includes a testing module for mocking out Kirby components in unit tests. To mock out Kirby in tests of components that use a <kirby- tag, you need to configure your testing module with the following:

import { KirbyTestingModule } from '@kirbydesign/designsystem/testing';

beforeEach(async(() => {
  TestBed.configureTestingModule({
    ...
    imports: [KirbyTestingModule],
    ...
  }).compileComponents();
}));

Autocompletion

To enable autocompletion (e.g. in VS Code), you need to add the following line to your reference.d.ts:

/// <reference path="./node_modules/@kirbydesign/designsystem/index.d.ts" /> Needed for autocompletion and compilation.

Polyfills

Some features of Kirby requires polyfills to ensure compability across all major browsers (e.g. the ResizeObserverService used by the automagic sizing feature of the Kirby Card component).

To enable the polyfill, you register a polyfill loader that checks whether the polyfill is needed or the feature is already supported by the browser (and can skip requesting the polyfill).
To use the sizing feature of Kirby Card across all major browsers, you must copy additional files from the Kirby package to your output folder.
Add the following to build > options > assets in angular.json:

{
  ...
  "build": {
    "options": {
      "assets": [
        ...
        {
          "glob": "**/*",
          "input": "./node_modules/@kirbydesign/designsystem/polyfills",
          "output": "./kirby/polyfills"
        },
        ...
      ],
    }
  }
}

Finally, add the following to index.html:

<head>
  ...
  <script src="kirby/polyfills/resize-observer-polyfill-loader.min.js"></script>
</head>

Please note: If you don't want the additional http request for the polyfill loader, you can copy the contents of node_modules/@kirbydesign/designsystem/polyfills/resize-observer-polyfill-loader.js into a script tag in index.html instead

Chart Components

The Kirby chart components use Highcharts. Note that this is a licensed product.