@engie-group/fluid-design-tokens

Fluid Design Tokens by ENGIE

DISCLAIMER

When installing the package via npm or importing it via CDN we recommend fixing the version with the exact package version to avoid breaking change affecting your live website. With never-ending topics like Accessibility and BRAND GUIDELINES we also have to include some minor breaking changes in some minor versions

e.g:

npm install --save @engie-group/fluid-design-tokens@VERSION

or

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-tokens@VERSION/lib/css/tokens.css">

Quick Start

Install this package:

npm install --save @engie-group/fluid-design-tokens@5.0.0

How to use

Get our ready to use token libraries from lib folder.

• lib/css
• lib/json
• lib/js

In SASS/SCSS

@import "~@engie-group/fluid-design-tokens/lib/css/tokens.css"

In HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-tokens@5.0.0/lib/css/tokens.css">

In JS

Object import

// ====>  Object import
import {Token} from '@engie-group/fluid-design-system-tokens';

let easing = Token.motion.bezier["linear-out-slow-in"];

Single variable import

// ====> Added single token export
import { njMotionBezierLinearOutSlowIn } from '@engie-group/fluid-design-tokens';

easing = njMotionBezierLinearOutSlowIn; 

What are design tokens?

Design tokens are pairs of names and values that express concise, reusable design choices. These tokens utilize well thought descriptive names to convey visual styles, rather than relying on fixed, hard-coded numerical values (e.g.: color hex, pixels, ...).

--nj-color-palette-blue-600: #098765

Tiers

Our tokens are split into different tiers, each with a specific use case:

Core tokens

"Private tokens" which should only be used internally to change the overall look of the design. They're responsible for the look of the final product by defining the all values that can be used. This includes the color palette, the radius values, ... We provide them below for reference only.

--nj-color-palette-blue-600: #

Semantic tokens

"Public tokens" that are used throughout the application. Their names describe the intended use of the token. They reference core tokens. We encourage you to directly use those tokens if you need to create new components. You can see them directly in the :root {}

--nj-color-border-brand-bold: var(--nj-color-base-brand-600);

Todo: Ajouter illustration ici

Component tokens

These tokens reference semantic tokens and tie them to a specific component value. They are mainly used for overrides. We currently do not expose them in the root.

--nj-avatar-border-color: var(--nj-color-border-brand-bold);

Override example:

<div class="nj-avatar your-custom-override-class">
  ...
</div>

.your-custom-override-class {
  --nj-avatar-border-color: YOUR-OVERRIDE-VALUE; // e.g. var(--nj-color-border-red-bold)
}

Token structure

Each tier of tokens has its own structure. In each section below we provide the precise structure of the token. We are mixing and matching belows categories to create the most understandable and intuitive tokens names.

--nj-color-background-primary-hover

--namespacing-type-property-scale-state

Namespacing (--nj)

This refers to the --nj prefix that is added to all tokens in the system (like --md in Material design or spectrum- in Adobes system). This namespace serves to prevent conflicts that may arise when Fluid design tokens share the same names as tokens from other systems that are used concurrently. (Such a scenario could occur when integrating Fluid into a project that utilizes a UI kit such as Bootstrap). With this approach, you can gradually implement Fluid into your project.

Type prefix or suffix (color, size, ...)

Prefixing or suffixing is mostly done with the token type (e.g. color, size, ...). This is mostly important for usage in code where developers may get a long list of suggested tokens. Personally I prefer to prefix the type as a kind of top level categorisation, e.g. --color-background—subtle. This allows you to type --color and only get suggestions for color tokens in your IDE. Commonly the namespace uses the name of the design system or organisation in full or an abbreviated form.

Property (background, border, ...)

This property is directly tied to the UI element. --nj-color-background-primary

Scales / emphasis (bold, subtle, ...)

Scales are great when representing multiple elements in one family. Typically, we use either numeric or ordinal. Numeric scale: --nj-color-palette-blue-600 Ordinal scale: --nj-color-border-brand-bold

State

Mainly refers to hover, focus and active states as suffixes.

Troubleshooting

If you have any issues while getting set up with ENGIE Design System, please create an issue here.