Fluid Design System Vanilla JS

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 components and styles in your typescript project.

Deprecation notice

@engie-group/fluid-design-system is deprecated. The release containing this notice is the final release of the Vanilla JS library. No new features, bug fixes, security updates, or releases will be provided afterward.

Migrate to @engie-group/fluid-design-system-webcomponents, the supported successor. It is not a drop-in replacement: consult the Web Components documentation for the markup and API of each component.

npm install @engie-group/fluid-design-system-webcomponents @engie-group/fluid-design-tokens

Why this change?

• Increased interoperability: Web Components are natively compatible with all modern frameworks (React, Angular, Vue, etc.) and can be used without any framework.
• Simplified maintenance: A single codebase for all environments, reducing technical debt and making future evolutions easier.
• Standardization: Adoption of web standards ensures better sustainability and scalability.

For migration support, consult the Web Components documentation or contact the Fluid team.

• Versioning
• Getting started
  • NPM installation
  • CDN installation
• Documentation and usage
• Troubleshooting and feature requests

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 before updating the package after a release.

Getting started

This package can be installed directly with NPM or via CDN.

NPM installation

You can install the package inside your application via npmjs:

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

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

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

CSS

Component styling is based on CSS classes and some CSS variables (called design tokens). In order for each component to be rendered as expected, you need to include CSS files as global stylesheet in your project.

You should include them in your HTML <head>:

<!-- tokens.css = Styles to import tokens needed by components -->
<link
  href="<your-relative-path-to-node_modules>/@engie-group/fluid-design-tokens/lib/css/tokens.css"
  rel="stylesheet"
/>
<!-- fluid-design-system.css = Styles of all components -->
<link
  href="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/fluid-design-system.css"
  rel="stylesheet"
/>

or in your JavaScript entry file :

import '@engie-group/fluid-design-tokens/css';
import '@engie-group/fluid-design-system/css';

or in your CSS entry file :

@import '@engie-group/fluid-design-tokens/css';
@import '@engie-group/fluid-design-system/css';

ℹ️ We recommend including the Fluid Design System CSS before your own stylesheets to avoid any conflicts.

Javascript

Some components need JavaScript code to work properly.

When your DOM is rendered, dynamic components will need to be initialized to work properly.

To do so, you will have to initialize them either with a global script which will initialize all components or by initializing each component individually.

Global initialization

You can use the auto initializer script to initialize all components at once.

Add the following script near the end of your pages, right before the closing </body> tag:

<script
  type="module"
  src="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/auto-init.js"
></script>

Individual initialization

You can also initialize each component individually in your JavaScript by calling the static init method of the component.

For example, to initialize all Select components on your page, you can use the following code:

// In a JS file or script tag called right before the end of the body
import { Select } from '@engie-group/fluid-design-system';

Select.init();

CDN installation

It's possible to use Fluid Design System via CDN. This is the recommended way to use Fluid if you don't have a build process or if you want to quickly test Fluid in a project.

As with the NPM installation, you will need to include some CSS and JavaScript files in your project. Installations are very similar.

CSS

Component styling is based on CSS classes and some CSS variables (called design tokens). In order for each component to be rendered as expected, you need to include CSS files as global stylesheet in your project.

You should include them in your HTML <head>:

<!-- tokens.css = Styles to import tokens needed by components -->
<link
  href="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-tokens@<VERSION>/lib/css/tokens.css"
  rel="stylesheet"
/>
<!-- fluid-design-system.css = Styles of all components -->
<link
  href="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-system@<VERSION>/lib/fluid-design-system.css"
  rel="stylesheet"
/>

ℹ️ We recommend including the Fluid Design System CSS before your own stylesheets to avoid any conflicts.

Javascript

Some components need JavaScript code to work properly.

To access components in your code we export a global NJ constant that contains all components. To make it available, you will have to set this script before using any component:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-system@<VERSION>/lib/fluid-design-system.js"
></script>

When your DOM is rendered, dynamic components will need to be initialized to work properly.

To do so, you will have to initialize them either with a global script which will initialize all components or by initializing each component individually.

Global initialization

You can use the auto initializer script to initialize all components at once.

Add the following script near the end of your pages, right before the closing </body> tag:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-system@<VERSION>/lib/auto-init.js"
></script>

Individual initialization

You can also initialize each component individually in your JavaScript by calling the static init method of the component.

For example, to initialize all Select components on your page, you can use the following code:

// In a JS file or script tag called right before the end of the body
NJ.Select.init();

Documentation and usage

For a better comprehension of the components and their usage, we recommend checking our Storybook documentation.

For Fluid overall documentation, you can check our Fluid documentation.

If you have correctly followed the installation steps, you should be able to use Fluid components in your project.

<body>
  <!-- basic Fluid button component -->
  <button type="button" class="nj-btn">Fluid button</button>

  <!-- basic Fluid select component -->
  <div class="nj-form-item nj-form-item--select">
    <div class="nj-form-item__field-wrapper">
      <select class="nj-form-item__field" id="exampleSelect">
        <optgroup label="Group 1">
          <option>Item 1</option>
          <option>Item 2</option>
        </optgroup>
        <optgroup label="Group 2">
          <option>Item 3</option>
          <option>Item 4</option>
          <option>Item 5</option>
        </optgroup>
      </select>
      <label for="exampleSelect" class="nj-form-item__label">Example</label>
      <div class="nj-form-item__trailing">
        <span aria-hidden="true" class="nj-form-item__icon material-icons">keyboard_arrow_down</span>
      </div>
    </div>
  </div>
  <script
    type="module"
    src="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/auto-init.js"
  ></script>
</body>

Troubleshooting and feature requests

If you encounter any issues, or you want any component or feature to be implemented, please create an issue or a feature request on our GitHub repository.