@episerver/design-tokens

Design Tokens

Theme variables as JSON, SASS, and LESS. It's used in UI Framework and its dependents. Can be used independently to get Episerver themes, useful for doing a UI Refresh of an existing frontend.

Getting Started

Add @episerver/design-tokens as a dependency

yarn add @episerver/design-tokens

It includes design tokens in JSON, SASS, and LESS.

JSON

import variables from "@episerver/design-tokens/dist/json/variables";

They follow a basic structure of

[
    {
        "name": "token-name",
        "val1": "some value",
        "val2": "some other value"
    }
]

The first element is a flat object:

    {
        "font-family": "Barlow, sans-serif",
        "font-family-monospace": "Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace",
        "font-size-monospace": "13px",
        "font-weight-regular": 400,
        "font-weight-medium": 500,
        "font-weight-bold": 700,
        "text-emphasis-high": 0.87,
        "text-emphasis-medium": 0.6,
        "text-emphasis-disabled": 0.38,
        "text-color-emphasis-high": "rgba(0, 0, 0, 0.87)",
        "text-color-emphasis-medium": "rgba(0, 0, 0, 0.6)",
        "text-color-emphasis-disabled": "rgba(0, 0, 0, 0.38)"
    },

Subsequent elements are either color, typography, or shape:

    {
        "name": "color-primary-500",
        "hex": "1456f1",
        "alpha": 1
    },

    {
        "name": "typography-styles-body1",
        "letterSpacing": 0,
        "lineHeight": 19,
        "font": {
            "postscriptName": "Barlow-Regular",
            "family": "Barlow",
            "size": 16,
            "weight": "regular",
            "stretch": "normal"
        },
        "color": {
            "hex": "000000",
            "alpha": 0.87
        }
    },

    {
        "name": "shape-medium-component-radius",
        "radius": "4px"
    },

The tokens are under rapid development so their interfaces can change at any time.

SASS

@use "@episerver/design-tokens/dist/scss/variables" as epi;

$your-theme-primary: epi.$color-primary-500;

SASS with webpack

Setting up SASS with a project using webpack is very quick.

• Install sass-loader and node-sass. yarn add --dev sass-loader node-sass
• Add a new rule to webpack.config.js for .scss files

{
    test: /\.scss$/,
    loaders: [
        "style-loader",
        "css-loader",
        {
            loader: "sass-loader",
            options: {
                includePaths: ["node_modules"]
            }
        }
    ],
    include: path.resolve(__dirname, "../")
}

LESS

@import "@episerver/design-tokens/dist/less/_variables";

@your-theme-primary: @color-primary-500;

LESS with gulp

Setting up LESS with a project using gulp is very quick.

• Install gulp-less. yarn add --dev gulp-less
• Add a new task to gulpfile.js for .less files, or change an existing task.

task("build-less", () => {
    return src(["**/*.less"]).pipe(
        less({
            paths: [path.join(__dirname, "node_modules")],
        })
    );
});

Fonts

The tokens in the Design System (and the components in the UI Framework) use a custom font which you need to load in the appropriate manner for your application.

Google Fonts

Loading the font via Google Fonts is the preferred approach as it will provide the best performance, and it only requires that you add a link in the head of the HTML document.

<link href="https://fonts.googleapis.com/css?family=Barlow" rel="stylesheet" />

Depending on the site setup, this may require changes to the content security policy for the site. The following rules would be needed in that case:

style-src 'self' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com

Local Fonts

If the application can be used in scenarios where loading external resources is potentially forbidden, then you can bundle the fonts with your application by adding the following to your entry point file. You will need to take a dependency on UI Framework and follow the readme there for "Local Fonts".

Releases

Releases will be created at the team's discretion. This should be done regularly when there are bug fixes or new features available. Releases follow semantic versioning. This means that, until there is a major version, minor versions may contain breaking changes.

See the CHANGELOG.md document for information about what is included in each release.

Internal

See the GUIDELINES.md document for more information about contributing and the release process.