Design tokens ​

Prod:

The @zurich/design-tokens NPM package is a package fully based on CSS. This library provides all the necessary design tokens that conform the foundations of the Zurich Design System. it also provides some attribute-based functionalities also described in the foundations that help with things like layouts, themes, basic of assets (like icons or pictograms), animations, transitions, text mixins, etc.

Install ​

We can use two different approaches for the use of the package:

Synergies

If you are going to use @zurich/css-components or @zurich/web-components, the installation mechanisms of the tokens are included as part of the styles imports of those.

Local installation ​

For NPM-style build systems or/and local development, you can install @zurich/design-tokens via NPM. Just use the installation command of you favorite package manager (NPM, Yarn, PNPM, Bun, etc.).

bash
npm i @zurich/design-tokens

Then access the CSS files inside the distribution folder and import the CSS in your JS/TS:

ts
import '@zurich/design-tokens';

Via CDN ​

The fastest way to get going with @zurich/design-tokens is to load it via a CDN. Just import the https://zds.zurich.com/0.5.18/@zurich/design-tokens/index.css file to the <head> of your HTML and start using the design tokens:

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <link 
      rel="stylesheet"
      href="https://zds.zurich.com/0.5.18/@zurich/design-tokens/index.css" 
    />
  </head>
</html>

Imports ​

The main imports of the packages are:

  • /index.css: the main file that contains the default required CSS rules of the package.
  • /base.css: a reduced version of the default /index.css file, that doesn't include the grid system and the headings.
  • /types.d.ts: the file with the TypeScript definitions for the HTML attributes.

Individual imports:

Categorized/chunked imports:

Lazy imports ​

For non-critical CSS, we recommend to load the CSS in a lazy way (like Icons or Pictograms) to speed up the page load:

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <link 
      rel="preload" 
      as="style" 
      href="__URL__" 
      onload="this.onload=null;this.rel='stylesheet'"
    >
  </head>
</html>

Import tree ​

Here's an schema of the imports tree:

Import tree

Import icons ​

Icons as excluded of the general import and need to be loaded manually. There are multiple option for importing the icons in order to optimize as much as possible their use.

If we want to import all the icons, we can use @zurich/design-tokens/dist/Icons.css.

But if we want to be more specific we can go with the following naming convention, where at least one value is required:

@zurich/design-tokens/dist/icons/<category?>/<style?>.css

That way we can import for example:

Check the icons page to check the available options per selector.

Import pictograms ​

It's the same as with the icons, but with no styles (outline or solid). Dark and light themes are included in the same definitions. So the only chunk categorization is done by category as with icons.

The import format would be:

@zurich/design-tokens/dist/pictograms/<category>.css

With examples as:

Check the pictograms page to check the available categories.

Import dev CSS ​

For importing the development CSS tooling, we need to explicitly import @zurich/design-tokens/dev.css. This import should stay out of the final bundle for production to improve performance.

Types, JSDoc, and intellisense ​

...

All the necessary types are set in the following file:

ts
import '@zurich/design-tokens/types';

To get intellisense for the CSS tokens, check the recommendations we make for VSCode.

Vanilla HTML/CSS ​

...

We recommend a local installation and to be added into the CSS code:

css
@import "@zurich/design-tokens";

But can also be used remotely by being added into the HTML code from the CDN:

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <link 
      rel="stylesheet" 
      href="https://zds.zurich.com/0.5.18/@zurich/design-tokens/index.css" 
    />
  </head>
</html>

Frameworks ​

...

Angular ​

...

We just need to import the node_modules/@zurich/design-tokens/dist/index.css file into the projects.<app-name>.architect.build.styles array option in the angular.json file:

json
{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "newProjectRoot": "projects",
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "styles": [
            "node_modules/@zurich/design-tokens/dist/index.css",  
          ],
        },
      },
    }
  }
}

React ​

...

We just need to import the @zurich/design-tokens file into the main.tsx file:

tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';

import '@zurich/design-tokens';  

const root = document.getElementById('root') as HTMLElement;

ReactDOM
  .createRoot(root)
  .render(
    <React.StrictMode>
      <App />
    </React.StrictMode>,
  );

Vue ​

...

We just need to import the @zurich/design-tokens file into the main.ts file:

ts

import { createApp } from 'vue';
import App from './App.vue';

import '@zurich/design-tokens';  

createApp(App)
  .mount('#app');