@lmc-eu/spirit-design-tokens v1.1.5

@lmc-eu/spirit-design-tokens

Design tokens for Spirit Design System.

⚠️ Spirit design tokens are managed with and generated by Supernova. DO NOT EDIT MANUALLY!

Table of Contents

1. Available Design Tokens
2. Install
3. Basic Usage
4. @tokens API
5. FAQ

Available Design Tokens

Install

🙋🏻‍♂️ Hold on! Do you already use spirit-web? Then you don't need to install this package because spirit-design-tokens is installed automatically as a dependency of spirit-web.

If you want to use just spirit-design-tokens alone in your project, run:

yarn add @lmc-eu/spirit-design-tokens

or

npm install --save @lmc-eu/spirit-design-tokens

Basic Usage

The recommended approach in Sass is to import all Spirit design tokens at once via the @tokens API:

@use 'sass:map';
@use 'node_modules/@lmc-eu/spirit-design-tokens/scss/@tokens' as tokens;

.MyComponentThatMightGoToSpiritInFuture {
  font-family: map.get(tokens.$body-medium-text-regular, font-family);
  color: tokens.$text-primary-default;
}

This makes it easier to migrate your code to Spirit in the future.

You can also import individual design token files by categories, e.g.:

@use 'sass:map';
@use 'node_modules/@lmc-eu/spirit-design-tokens/scss/colors';
@use 'node_modules/@lmc-eu/spirit-design-tokens/scss/typography';

.MyComponent {
  font-family: map.get(typography.$body-medium-text-regular, font-family);
  color: colors.$text-primary-default;
}

This approach is a bit more descriptive and thus provides slightly better developer experience. You may find it more convenient in situations you don't suppose your code will make its way to Spirit as this approach is incompatible with @tokens API that makes rebranding possible.

In JavaScript

Additionally the design tokens are also provided as a JavaScript object.

import * as SpiritDesignTokens from '@lmc-eu/spirit-design-tokens';

const desktopBreakpoint = SpiritDesignTokens.breakpoints.desktop;

The structure is the same as in the SASS.

@tokens API

@tokens API enables quick and easy rebranding of Spirit Sass styles by replacing the path to design tokens. You need to be familiar with it if you are building your custom design system based on Spirit or you are going to contribute to Spirit.

Accessing @tokens

a) via full path

Access Spirit design tokens via the @tokens API without having to configure load path, just like shown in the basic example. This is a good choice for starting off quickly. However, it doesn't enable rebranding.

b) via load path

To get ready for rebranding, access Spirit design tokens via the @tokens API while keeping them open to be replaced by another set of design tokens:

@use 'sass:map';
@use '@tokens' as tokens;

.MyComponentThatIsReadyForSpirit {
  font-family: map.get(tokens.$body-medium-text-regular, font-family);
  color: tokens.$text-primary-default;
}

Configuring Load Path

Because the @tokens file doesn't exist locally, tell Sass where it should look for unreachable files. This is also a required step if you are importing Spirit components from their Sass source.

sass --load-path=node_modules/@lmc-eu/spirit-design-tokens/scss my-styles.scss

// webpack.config.js

// …
module: {
  rules: [
    {
      test: /\.scss$/,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'sass-loader',
          options: {
            sassOptions: {
              includePaths: [
                path.resolve(__dirname, 'node_modules'),
                path.resolve(__dirname, 'node_modules/@lmc-eu/spirit-design-tokens/scss'),
            },
          },
        },
      ],
    },
  ];
}
// …

Exposing Your Custom Design Tokens

In Spirit, the @tokens.scss file simply @forwards all design tokens exposed by index.scss which in turn @forwards all design token categories. To make your design tokens compatible with Spirit, just create a @tokens.scss file and @forward all your design tokens through it, e.g.:

// @tokens.scss

@forward 'borders';
@forward 'colors';
@forward 'gradients';
@forward 'measures';
@forward 'other';
@forward 'radii';
@forward 'shadows';
@forward 'typography';

FAQ

Because @using the @tokens module without renaming would produce an error:

Error: Invalid Sass identifier "@tokens"
  ╷
1 │ @use '@tokens';
  │ ^^^^^^^^^^^^^^

We prefix the @tokens.scss file with @ to differentiate it from other Sass files in the directory.

In order for developers to know the file behaves differently than usual Sass partials, a @ prefix is added to mark this behavior both in filesystem and inside Sass files. As a result, it's clear why e.g. @use 'tools' refers to a local file and @use '@tokens' does not. However, it's only a naming convention, there is no special tooling or configuration for Sass partials starting with @.

Imported module needs to be renamed to be compatible with SCSS syntax when it's used later on. That's why @use '@tokens' as tokens.

Look at the following snippets and compare which one offers better comprehensibility.

Without @ prefix:

// _Button.scss

@use 'tools'; // Calls './_tools.scss'. You don't have to explain this to me.
@use 'tokens'; // Wait, this file doesn't exist… What's going on here? Is it
// an error?

With @ prefix:

// _Button.scss

@use 'tools'; // Calls './_tools.scss'.
@use '@tokens' as tokens; // OK, './_@tokens.scss' is not here, but the at-sign
// prefix suggests a special behavior. Maybe I'll learn more in the docs?

Creating a custom design system derived from Spirit? Great to hear that! 🎉

While it's perfectly OK to develop custom components that may not find their way back to Spirit, your design tokens need to include all Spirit design tokens anyway, so all Spirit components you are going to reuse work correctly with your brand.

Simply put, if you are going to build a design system based on Spirit:

1. copy and paste all design tokens from here,
2. alter their values to fit your needs,
3. feel free to add anything necessary on top of that,
4. use your design tokens in your code (and compile Spirit with them).

To make your Sass design tokens compatible with Spirit, don't forget to expose them via your custom @tokens API.

License

See the LICENSE file for information.