@engie-group/fluid-design-system-angular/README.md

Fluid Design System Angular

# Engie's Angular components of the Fluid design system

[Fluid](https://www.engie.design/fluid-design-system/) 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](#prerequisites)
- [Versioning](#versioning)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Next Steps](#next-steps)
- [Support and Contributing](#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](https://fluid.design.digital.engie.com/fluid-design-system/storybook/angular/index.html?path=/docs/docs-changelog--documentation) before updating the package after a release.

## Installation

Install the required packages using your preferred package manager:

```bash
# 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:

```jsonc
{
  "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:

```css
@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](https://v19.angular.dev/guide/animations).

> ℹ️ 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](https://github.tools.digital.engie.com/GBSEngieDigitalDesignSystem/fluid-design-system/issues/1454).

## Usage

### Importing Components

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

```typescript
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:

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

### Complete example

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

**app.component.ts**

```typescript
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**

```angular2html
<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](https://fluid.design.digital.engie.com/fluid-design-system/angular/index.html) documentation.
- Check out the design system overall documentation [Fluid documentation](https://www.engie.design/fluid-design-system/).
- 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](https://github.tools.digital.engie.com/GBSEngieDigitalDesignSystem/fluid-design-system/issues)

---

**Happy coding with Fluid Design System! 🚀**