@engie-group/fluid-design-system-angular
Version:
Fluid Design System Angular
200 lines (138 loc) • 6.74 kB
Markdown
# Getting Started with Fluid Design System Angular
Welcome to the Angular component library of the official ENGIE Design System: [Fluid](https://www.engie.design/fluid-design-system/).
This library provides a comprehensive set of Angular components built as standalone components, making them easy to integrate into your Angular applications.
## Prerequisites
Before you begin, ensure that your Angular project meets the following requirements:
- **Angular 16 or higher**. This library does not support Angular versions prior to version 16
- An initialized Angular project
## Installation
Install the required packages using your preferred package manager:
```bash
# Using pnpm
pnpm add --save-exact -group/fluid-design-system-angular @engie-group/fluid-design-tokens
# Using npm
npm install --save-exact -group/fluid-design-system-angular @engie-group/fluid-design-tokens
# Using yarn
yarn add --exact -group/fluid-design-system-angular @engie-group/fluid-design-tokens
```
> **Note:** We recommend using the `--save-exact` flag as we don't strictly follow semantic versioning, and some minor versions may contain breaking changes.
> **Important:** Check the [CHANGELOG](https://fluid.design.digital.engie.com/fluid-design-system/storybook/angular/index.html?path=/docs/docs-changelog--documentation) for any breaking changes or updates before upgrading.
### Optional: Deprecated components
Some deprecated components use some styles from the `-group/fluid-4-deprecated` package, you may need to install this package:
```bash
# Using pnpm
pnpm add --save-exact -group/fluid-4-deprecated
# Using npm
npm install --save-exact -group/fluid-4-deprecated
# Using yarn
yarn add --exact -group/fluid-4-deprecated
```
Please refer to the `-group/fluid-4-deprecated` README.md for more information on using deprecated components.
> **Note:** The `-group/fluid-4-deprecated` package is not required for the current components in the Fluid Design System. It is only needed if you are using components that were part of the previous Fluid 4 design system.
## Setup
### 1. Fonts
Add the following link tag to the `<head>` section of your `src/index.html` file to include the required Material Icons and Lato fonts:
```html
<link href="https://fonts.googleapis.com/css?family=Material+Icons|Lato:300,400,700,900|Roboto+Mono:300,400,700,900&display=swap" rel="stylesheet"/>
```
### 2. 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",
// Only if you use deprecated components
// "@engie-group/fluid-4-deprecated/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
'-group/fluid-design-tokens/lib/css/tokens.css';
/*Only if you use deprecated components :
@import '@engie-group/fluid-4-deprecated/tokens/lib/css/tokens.css'; */
'-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.
### 3. 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 for both standalone applications and NgModule-based applications, please refer to the [official Angular animations guide](https://angular.dev/guide/animations).
## Usage
### Importing Components
All Fluid components are standalone Angular components. Import them individually as needed:
```typescript
import { Component } from '/core';
import { RouterOutlet } from '/router';
import { ButtonComponent } from '-group/fluid-design-system-angular';
({
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:
```html
<nj-button>Hello from Fluid</nj-button>
```
### Complete example
Here's a complete example of a component using Fluid Design System:
**app.component.ts**
```typescript
import { Component } from '/core';
import { RouterOutlet } from '/router';
import { ButtonComponent } from '-group/fluid-design-system-angular';
({
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**
```html
<div class="app-container">
<h1>Welcome to {{ title }}</h1>
<nj-button (click)="onButtonClick()">
Hello from Fluid Design System
</nj-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! 🚀**