# Engie's design token of the Fluid design system

[Fluid](https://www.engie.design/fluid-design-system/) 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.

- [Versioning](#versioning)
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
  - [With CSS tokens](#with-css-tokens)
    - [Switching to dark theme](#switching-to-dark-theme)
  - [With Javascript and Typescript](#with-javascript-and-typescript)
  - [With JSON](#with-json)
  - [With Tailwind](#with-tailwind)
  - [Other formats](#other-formats)
- [Changelog and migration](#changelog-and-migration)
- [Troubleshooting](#troubleshooting)

## Versioning

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

Versions are structured as `GLOBAL.BREAKING.MINOR` where:

- `GLOBAL` is the **global version of Fluid Design System** (ex: Fluid 4, Fluid 5, Fluid 6 etc.). We are currently at `Fluid 6`.
- `BREAKING` is incremented for each **breaking-change** (component API change, layout change, etc.).
- `MINOR` is incremented for bug **fixes, features and non-breaking changes**.

We recommend **using `~` semver range** to avoid breaking changes affecting your application.
Moreover, we recommend checking the [CHANGELOG](https://github.com/FluidDesignSystem/fluid-design-system/blob/main/packages/fluid-design-tokens/CHANGELOG.md) before updating the package after a release.

A CLI tool to help migrating between versions is also available [here](https://www.npmjs.com/package/@engie-group/fluid-cli).

## Introduction

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

``` css
.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.**

``` css
--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.

```css
--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.

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

**Override example**:

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

```css
.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.

![token-taxonomy.jpg](https://i.ibb.co/yFQC5Fh/token-taxonomy.jpg)

1) Prefix: Namespace as a unique identifier and the tier the token belongs to (core, semantic or component)
2) Family: The type of visual design attribute or foundational style, such as color or elevation.
3) Property: The UI element the token is being applied to, such as a border, background, shadow, or other property.
4) 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](https://www.figma.com/file/WGmwlBZwjK7cGnYmPmP3ZE/Fluid-Tokens?type=design&node-id=4021%3A7178&mode=design&t=VFXuNfiMWI1QlNxv-1).

![token-example.jpg](https://i.ibb.co/kKY0yMg/tokens-example.jpg)

## Installation

```shell
# Using pnpm 
pnpm add  @engie-group/fluid-design-tokens

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

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

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.

```markdown
.
├── 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:

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

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

```html
<!-- In your HTML -->
<link rel="stylesheet" href="<relative-path-to-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">
```

## Usage

### With CSS tokens

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

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

> 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](https://www.engie.design/fluid-design-system/design-tokens/).

#### Switching to dark theme

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

```css
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.

You also can provide a `"system"` value to the `data-theme` attribute to switch between light and dark theme based on the user's system preferences.

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

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

### With Javascript and Typescript

We provide types for typescript autocompletion.

```javascript
// 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;
```

```javascript
//  ... 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; 
```

### With JSON

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

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

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

### With 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.

```js
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:

```html

<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](https://tailwindcss.com/docs/gap) 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](https://github.com/FluidDesignSystem/fluid-design-system/issues) to describe your needs.

## Changelog and migration

The Changelog is available [here](https://github.com/FluidDesignSystem/fluid-design-system/blob/main/packages/fluid-design-tokens/CHANGELOG.md).

If you're migrating to V5, check out the [migration guide v1 to v5](https://github.com/FluidDesignSystem/fluid-design-system/blob/main/packages/fluid-design-tokens/docs/MIGRATION_GUIDE_V1_TO_V5.md)

If you're migrating to V5.4, check out the [migration guide v5.3 to v5.4](https://github.com/FluidDesignSystem/fluid-design-system/blob/main/packages/fluid-design-tokens/docs/MIGRATION_GUIDE_V5.3_TO_V5.4.md). 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](https://github.com/FluidDesignSystem/fluid-design-system/issues).