@engie-group/fluid-design-tokens

v5.9.0

Published

2 months ago

Fluid Design Tokens

Downloads

3,903

0High
0Medium
0Low

jintus-engie

kangaxx

engie fluid design-system design system design-tokens token tokens

Engie's design token of the Fluid design system

Fluid is the Engie's design system, a collection of reusable components and styles used to build Engie's digital products.

Here is the package to benefit from Fluid's design tokens in your project.

🚀 NEWS 🚀 v5.4 comes with huge changes, and we are happy to announce that we provide a script to simplify the migration. Check out the migration guide v5.3 to v5.4 and the fluid-scripts' readme for more information.

Versioning

⚠️ This package doesn't follow semantic versioning, breaking changes may be introduced in minor versions.

We recommend fixing the version with the exact package version to avoid breaking changes affecting your live website. Moreover, we recommend checking the CHANGELOG before updating the package after a release.

Getting started

Package installation:

# Using npm
npm install --save-exact @engie-group/fluid-design-tokens

# Using yarn 
yarn add --exact @engie-group/fluid-design-tokens

# Using pnpm 
pnpm add --save-exact @engie-group/fluid-design-tokens

How to use

Fluid Design Tokens come in different flavors. Import the one corresponding to your styling technology choices.

All "ready-to-use" token libraries are located in the lib folder.

.
├── CHANGELOG.md
├── README.md
├── docs
│   └── MIGRATION_GUIDE_V1_TO_V5.md
├── lib
│   ├── css
│   │   └── tokens.css
│   ├── json
│   │   ├── tokens-dark.json
│   │   └── tokens.json
│   ├── tailwind
│   │   └── tailwind.config.js
│   ├── ts
│   │   ├── standalone-tokens-dark.ts
│   │   ├── standalone-tokens.ts
│   │   ├── tokens-dark.ts
│   │   └── tokens.ts
│   └── index.js

CSS

Importing the tokens

To make use of css variables, import them into your code like so:

/* In your css / scss / ... */
@import "@engie-group/fluid-design-tokens/css";

// In projects where you can import css files in the js
import "@engie-group/fluid-design-tokens/css";

<!-- In your HTML -->
<link rel="stylesheet" href="./node_modules/@engie-group/fluid-design-tokens@<VERSION>/lib/css/tokens.css">

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

Using the tokens

Once you've imported the variables, use them like so:

.my-awsome-class {
  background: var(--nj-semantic-color-background-primary-default);
}

Switching to dark theme

The css Fluid tokens provide both the light and dark themes at once:

root, [data-theme] {
  /* Light tokens */
}
[data-theme="dark"] {
  /* Dark tokens */
}

This allows to switch theme easily by adding a data-theme attribute in your html.

<!-- In your html -->
<body data-theme="dark">
    <!-- your content here -->
</body>

// Dynamilly with javascript
document.body.dataset.theme = 'dark';

More resources

For a list of the available variables and a more comprehensive way on how and where to use our tokens, check out the dedicated page on engie.design (coming soon).

Javascript and Typescript

We provide types for typescript autocompletion.

// In JS, you can either import the global object:
import { Tokens } from '@engie-group/fluid-design-system-tokens'; // light
import { TokensDark } from '@engie-group/fluid-design-system-tokens'; // dark

const fromGlobalEasing = Tokens.semantic.color.background.brand.solid.default;

//  ... or import a single token, as we also do single export in the standalone-tokens.js file
import { njSemanticColorBackgroundBrandSolidDefault } from '@engie-group/fluid-design-tokens'; // light
import { njSemanticColorBackgroundBrandSolidDefaultDark } from '@engie-group/fluid-design-tokens'; // dark

const singleExportEasing = njSemanticColorBackgroundBrandSolidDefault;

Json

We also provide Fluid tokens in Json format: tokens.json and tokens-dark.json, though we don't encourage using it.

import tokens from '@engie-group/fluid-design-tokens/lib/json/tokens.json';

const jsonEasing = tokens.semantic.color.background.brand.solid.default;

Tailwind

We also provide Fluid tokens for Tailwind as a theme preset. This preset is in Beta and we will be improving it by gathering more feedback. Core color palette (ex: blue-100) is overriding and not extended. But you can still override it in your own config.

Here is how you can import these presets in your tailwind.configs.

import {FluidTailwindPresets} from '@engie-group/fluid-design-tokens/tailwind';

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [
    FluidTailwindPresets
  ],
  // Your config here
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
  ],
  ...
}

Example usage in code:


<div class="bg-nj-brand-tertiary-default flex flex-col space-y-8">
  <h1
      class="text-nj-accent-blue-primary-default border-2 border-nj-brand-moderate p-8 m-8 font-nj-default font-nj-bold text-nj-heading-1">
    Title
  </h1>
  <h2 class="opacity-nj-disabled">This should have disabled opacity</h2>
  <a class="text-nj-accent-pink-primary-default hover:text-nj-accent-pink-primary-hovered space-y-12"
     href="#">Link</a>
</div>

Note: all default gap- classes like gap-x-1 or gap-1 are overridden by classes using our tokens.

For e.g: gap-1 becomes gap-4 gap-x-1 becomes gap-x-4

You can find here the default gaps with their values in px

Other formats

It is possible to export design tokens to other format or language (iOS, Android, ...). If your technology is not yet available, please contact us to describe your needs.

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, ...).

.brand-colored-text {
  color: var(--nj-semantic-color-text-brand-primary-default);
  
  /* Instead of 
  color: #007acd;
  */ 
}

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-core-color-blue-600: #098765

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-semantic-color-border-brand-strong: var(--nj-core-color-reference-brand-600);

Component tokens

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

--nj-avatar-border-color: var(--nj-semantic-color-border-brand-strong);

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-semantic-color-border-brand-subtle)
}

Token structure

Each tier of tokens has its own structure. A design token’s name describes how it should be used, and each part of its name communicates one piece of its usage.

Prefix: Namespace as a unique identifier and the tier the token belongs to (core, semantic or component)
Family: The type of visual design attribute or foundational style, such as color or elevation.
Property: The UI element the token is being applied to, such as a border, background, shadow, or other property.
Modifier(s): (optional) Additional details about the token’s purpose, such as its color role, emphasis, or interaction state. Not every token has a modifier. Discover the complete guide to design tokens on the getting started figma file

We are mixing and matching modifiers to create the most understandable and intuitive tokens names.

Discover the complete guide to design tokens on the "Fluid Tokens > Getting started" Figma file.

Changelog and migration

The Changelog is available here.

If you're migrating to V5, check out the migration guide v1 to v5

If you're migrating to V5.4, check out the migration guide v5.3 to v5.4. We are providing a script to facilitate this migration!

Troubleshooting

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