Engie's Angular 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 Angular project.

This library provides a comprehensive set of Angular components built as standalone components, making them easy to integrate into your Angular applications.

• Prerequisites
• Versioning
• Installation
• Configuration
• Usage
• Next Steps
• Support and Contributing

Prerequisites

Before you begin, ensure that your Angular project meets the following requirements:

• Angular 20 or higher. This library does not support Angular versions prior to version 20
• An initialized Angular project

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

Install the required packages using your preferred package manager:

# Using pnpm
pnpm add @engie-group/fluid-design-system-angular @engie-group/fluid-design-tokens @angular/cdk@v20-lts

# Using npm
npm install @engie-group/fluid-design-system-angular @engie-group/fluid-design-tokens @angular/cdk@v20-lts

# Using yarn
yarn add @engie-group/fluid-design-system-angular @engie-group/fluid-design-tokens @angular/cdk@v20-lts

Configuration

1. Include styles

Understanding Design Tokens

Design tokens are the visual design atoms of the design system. They store visual design attributes such as colors, typography, spacing, and more. Using design tokens ensures consistency across your application and enables features like light and dark mode theming.

Adding styles to your project

You need to include the design system CSS files in your project. The method depends on your build setup:

For Angular CLI Projects (angular.json)

Add the following styles to the styles array in your angular.json file:

{
  "projects": {
    "your-project-name": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "@engie-group/fluid-design-tokens/lib/css/tokens.css",
              "@engie-group/fluid-design-system-angular/lib/styles/fluid-design-system.css",
              "src/styles.css"
            ]
          }
        }
      }
    }
  }
}

Alternative: Global styles import

If you're using Nx or other tools that don't use angular.json, refers you to the tool documentation, or you can also import the styles directly in your global src/styles.css file:

@import '@engie-group/fluid-design-tokens/lib/css/tokens.css';
@import '@engie-group/fluid-design-system-angular/lib/styles/fluid-design-system.css';

/* Your custom styles here */

Important: We recommend importing Fluid stylesheets before your own stylesheets to avoid any potential style overrides.

2. Setup Angular animations

The Fluid Design System components require Angular animations to work properly. You need to install and configure the animations package:

For detailed instructions on setting up animations, please refer to the official Angular animations guide.

ℹ️ Since Angular 20, animations package is deprecated. We are still using this package for now. Please refer to the v19 documentation for package installation and setup. You can track the migration to the new Angular animation system in this GitHub issue.

Usage

Importing Components

All Fluid components are standalone Angular components. Import them individually as needed:

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { ButtonComponent } from '@engie-group/fluid-design-system-angular';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet, ButtonComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  title = 'my-fluid-app';
}

Using components in templates

Once imported, you can use the components in your templates:

<button nj-button>Hello from Fluid</button>

Complete example

Here's a complete example of a component using Fluid Design System:

app.component.ts

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { ButtonComponent } from '@engie-group/fluid-design-system-angular';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet, ButtonComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  title = 'my-fluid-app';
  
  onButtonClick() {
    console.log('Fluid button clicked!');
  }
}

app.component.html

<div class="app-container">
  <h1>Welcome to {{ title }}</h1>
  <button nj-button (click)="onButtonClick()">
    Hello from Fluid Design System
  </button>
  <router-outlet></router-outlet>
</div>

Next Steps

• Explore the available components in Storybook documentation.
• Check out the design system overall documentation Fluid documentation.
• Customize your application using design tokens for consistent theming

Support and Contributing

If you encounter any issues or would like to request a feature, please open an issue in our GitHub repository

Happy coding with Fluid Design System! 🚀