npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@engie-group/fluid-design-tokens

v5.10.0

Published

Fluid Design Tokens

Downloads

4,350

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

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.

token-example.jpg

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.