@engie-group/fluid-design-tokens
v5.9.0
Published
Fluid Design Tokens
Downloads
3,763
Readme
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-tokensHow 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.jsCSS
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: #098765Semantic 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.