@engie-group/fluid-design-system-webcomponents

v6.1.0

Published

2 months ago

A platform-agnostic Web Components implementation of the ENGIE Fluid Design System components

0High
0Medium
0Low

jintus-engie

kangaxx

Engie's web components 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 components and styles in your project using web components.

This library provides reusable, accessible, and customizable UI components that can be used in any web application, regardless of the framework.

Key Features

🔧 Framework-agnostic - Works with any framework or no framework
♿️ Accessible - Built with WCAG 2.1 guidelines in mind
📱 Responsive - Works across all device sizes
🌐 Modern - Built using the latest Web Components standards

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.

Installation

Package manager

Libraries are distributed on NPM, you can install them in your node package with the following command:

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

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

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

JavaScript

Library should be imported in your application to register web components.

Using package manager

In your javascript entry file:

import '@engie-group/fluid-design-system-webcomponents';

or in a script tag:

<script type="module" src="<your-relative-path-to-node_modules>/@engie-group/fluid-design-system-webcomponents/dist/esm/fluid.js" />

Using CDN

<!-- In your HTML file -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@engie-group/fluid-design-system-webcomponents@<VERSION>/dist/esm/fluid.js" />

CSS

Component styling is based on CSS classes and some CSS custom properties (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.

Using CDN

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-webcomponents@<VERSION>/dist/fluid/fluid.css" rel="stylesheet">

Using package manager

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-webcomponents/dist/fluid/fluid.css" rel="stylesheet">

or in your JavaScript entry file :

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

or in your CSS entry file :

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

/* Or
@import '@engie-group/fluid-design-tokens/lib/css/tokens.css'
@import '@engie-group/fluid-design-system-webcomponents/dist/fluid/fluid.css'

depending on you bundler configuration */

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

Usage

In a Vanilla JS project

In HTML files

<!-- Icon component -->
<nj-icon name="bolt" variant="brand" size="2xl"></nj-icon>

In JavaScript files

// Create and append an icon programmatically
const icon = document.createElement('nj-icon');
icon.setAttribute('name', 'bolt');
icon.setAttribute('variant', 'brand');
icon.setAttribute('size', '2xl');
document.body.appendChild(icon);

In a VueJS project

Setup

Import the library in your main.ts file:

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

Configure your bundler to support web components if necessary.

For exemple for vite, you can add the following to your vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // treat all tags starting with 'nj-' as custom elements
          isCustomElement: (tag) => tag.startsWith('nj-')
        }
      }
    }),
    ...
  ],
  ...
})

If you're using a linter you may have to configure it to accept custom elements as well.

For exemple for eslint with the vue plugin, you can add the following to your eslint.config.ts:

import { defineConfigWithVueTs } from '@vue/eslint-config-typescript'

export default defineConfigWithVueTs(
  {
    name: 'app/files-to-lint',
    files: ['**/*.{ts,mts,tsx,vue}'],
    rules: {
      'vue/no-deprecated-slot-attribute': [
        'error',
        {
          ignoreParents: ['/^nj-/'],
        },
      ],
    },
  },
  ...
)

You can then use Fluid web components in your Vue templates, as it was a vue component:

<template>
  <nj-button emphasis="bold" :variant="variant" @click="handleClick">Click me</nj-button>
</template>

CSS Custom Properties

Some components can be customized using CSS custom properties see respective documentation for further details

Support

TypeScript & ESM Support

This library is ES module compatible and includes TypeScript declarations. You can import types directly:

import { NjIcon } from '@engie-group/fluid-design-system-webcomponents/icon';

Browser Support

Chrome/Chromium (latest 2 versions)
Firefox (latest 2 versions)
Safari (latest 2 versions)
Edge (latest 2 versions)

Troubleshooting and feature requests

For support and issues:

Check our documentation
Open an issue in our GitHub repository
Join the Fluid Design System team on Teams

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Engie's web components of the Fluid design system

Key Features

Versioning

Installation

Package manager

JavaScript

Using package manager

Using CDN

CSS

Using CDN

Using package manager

Usage

In a Vanilla JS project

In HTML files

In JavaScript files

In a VueJS project

Setup

CSS Custom Properties

Support

TypeScript & ESM Support

Browser Support

Troubleshooting and feature requests