@engie-group/fluid-design-system

v5.10.2

Published

13 days ago

The Fluid Design System is ENGIE’s open-source library to create, build and deliver ENGIE digital services in a more efficient way.

Downloads

4,031

0High
0Medium
0Low

jintus-engie

kangaxx

engie fluid design-system design system css scss sass js javascript ts typescript responsive front-end framework web

Vanilla Fluid Design System by ENGIE

DISCLAIMER

When installing the package via NPM or importing it via CDN, we recommend fixing the version with the exact package version to avoid breaking change affecting your live website. With never-ending topics like Accessibility and Brand guidelines, we sometimes have to include some minor breaking changes in some minor versions.

Getting started

You can install either with CDN or via NPM.

Installation with CDN

When you only need to include compiled CSS or JS from Fluid, you can use our CDN links:

⚠️ Make sure to replace @<VERSION> with the latest fluid version and to paste the links in the correct order.

<!-- Fonts (Material Icons and Lato) --->
<link href="https://fonts.googleapis.com/css?family=Material+Icons|Lato:300,400,700,900&display=swap" rel="stylesheet"/>

<!-- Styles -->

<!-- If you need a reboot, include the line below: (we moved our reboot to the @engie-group/fluid-4-deprecated package) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@engie-group/fluid-4-deprecated/vanilla/lib/reboot.css">

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

<!-- fluid-design-system.js = javascript for all the fluid components and auto initializer-->
<script src="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-system@<VERSION>"></script>

As far as the CDN installation goes, you're all set!

Head straight to the basic-usage section to learn how to use components, or dive right it through the Storybook.

Installation via NPM

You can install the package inside your application via npmjs:

npm install --save-exact @engie-group/fluid-design-system

This will install fluid-design-system and its dependency fluid-design-tokens.

If you use deprecated components or need the reboot.css, you will need to install and use some styles from the @engie-group/fluid-4-deprecated package.
Please refer to the @engie-group/fluid-4-deprecated README.md for more information.
npm install @engie-group/fluid-4-deprecated

1. Import Font and Icons

Make sure to always include these fonts into the HTML <head>:

<!-- Material icons and Lato font -->
<link href="https://fonts.googleapis.com/css?family=Material+Icons|Lato:300,400,700,900&display=swap" rel="stylesheet"/>

2. Import CSS

You can use the built files from the lib/ directory.

2.1 EITHER include the full library

Include Fluid's global css in your HTML <head>:

<!-- Copy and paste the stylesheet `<link>` into your `<head>` before all other stylesheets to load our CSS -->
<head>
  <!-- meta, title, ... -->
  <!-- base.css = Styles to set correct font properties in your website --> 
  <link href="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/base.css" rel="stylesheet">
  <!-- 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">
</head>

2.2 OR include a single component

For e.g include the Toggle component styles only:

<head>
  <!-- meta, title, ... -->
  <!-- base.css = Styles to set correct font properties in your website -->
  <link href="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/base.css" rel="stylesheet">
  <!-- 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 > lib > components > wanted-component > index.css -->
  <link href="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/components/toggle/index.css" rel="stylesheet">
</head>

3. Import Javascript

Not all components contain a Javascript file. Using the full library is the safest bet to avoid worrying about it.

3.1 EITHER use the full Library

Place the following scripts near the end of your pages, right before the closing </body> tag, to enable components using JS.

<html>
  <head></head>
  <body>
    <!-- ... -->
    <!-- All Fluid components js -->
    <script src="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/fluid-design-system.js"></script>
    <!-- Auto initializer -->
    <script src="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/auto-init.js"></script>
  </body>
</html>

3.2 OR a single component

Include the Collapse component script:

<html>
  <head></head>
  <body>
    <!-- ... -->
    <!-- Fluid collapse component's js -->
    <script src="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/components/collapse/index.js"></script>
    <!-- Auto initializer -->
    <script src="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system/lib/auto-init.js"></script>
  </body>
</html>

Advanced imports using sources (NOT RECOMMENDED)

You can import the source files from the src/ directory, and use your asset builder (Webpack, gulp, grunt...) to bundle the css.

1. SCSS

⚠ Make sure to include the Google material icons first if you import the entire library or the Fluid icon component.

1.1 Either import the full library

@import "@engie-group/fluid-design-system/lib/base.css";
@import "@engie-group/fluid-design-tokens/lib/css/tokens.css";
@import "@engie-group/fluid-design-system/lib/fluid-design-system.css";

1.2 Or import a single component

E.g: Import the Toggle component file only:


@import "@engie-group/fluid-design-system/src/base";
@import "@engie-group/fluid-design-tokens/lib/css/tokens.css";
@import "@engie-group/fluid-design-system/src/components/toggle/_index";

2. JavaScript

Manual initialization for a single component

Components can be initiated manually instead of relying on the auto initializer:

import { Collapse } from '@engie-group/fluid-design-system';

document.addEventListener('DOMContentLoaded', function(event) {
  Collapse.init();
});

Basic usage

Once you've imported Fluid Design System, you can freely use any component.

Check out our Storybook documentation where you will find every component and how to use them.

eg:

<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>
      <span aria-hidden="true" class="nj-form-item__icon material-icons">keyboard_arrow_down</span>
    </div>
  </div>
</body>

Components development state

You can check our state of development on our Components status page

Troubleshooting

If you encounter any issues while setting up Fluid Design System, please create an issue or a request on our library git repository.