@engie-group/fluid-design-system-angular
Version:
Fluid Design System Angular
152 lines (109 loc) • 5.27 kB
Markdown
# 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.
- [Versioning](#versioning)
- [Getting started](#getting-started)
- [Documentation and usage](#documentation-and-usage)
- [Troubleshooting and feature requests](#troubleshooting-and-feature-requests)
## Versioning
⚠️ This package doesn't follow semantic versioning, breaking changes may be introduced in minor versions.
We recommend **fixing the version with the exact package version** to avoid breaking changes affecting your live website.
Moreover, we recommend checking the [CHANGELOG](https://github.tools.digital.engie.com/GBSEngieDigitalDesignSystem/fluid-design-system/blob/main/packages/fluid-angular/CHANGELOG.md) before updating the package after a release.
## Getting started
This package can be installed directly with [NPM](https://www.npmjs.com/package/@engie-group/fluid-design-system-angular):
```shell
# Using npm
npm install --save-exact @engie-group/fluid-design-system-angular @engie-group/fluid-design-tokens
# Using pnpm
pnpm add --save-exact @engie-group/fluid-design-system-angular @engie-group/fluid-design-tokens
# Using yarn
yarn add --save-exact @engie-group/fluid-design-system-angular @engie-group/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.
>
> ```shell
> # Using npm
> npm install @engie-group/fluid-4-deprecated
>
> # Using pnpm
> pnpm add @engie-group/fluid-4-deprecated
>
> # Using yarn
> yarn add @engie-group/fluid-4-deprecated
> ```
### Fonts and Icons
In order for the components to work properly, you need to include the Material Icons and Lato font in your project.
You should include them in your HTML `<head>`:
```html
<!-- Material icons, Lato font and Roboto Mono font -->
<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"/>
```
#### CSS
Component styling is based on CSS classes and some CSS variables (called design tokens).
In order for each component to be rendered as expected, you need to include a CSS file as global stylesheet in your project.
You must include it in your `angular.json` file in the `styles` array:
```json
{
"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"
]
}
```
>ℹ️ We recommend including it before your own stylesheets to avoid any conflicts.
### Enabling animations
Some components have animations, you need to enable the Angular animation module in your application for them to work correctly.
For application bootstrapped with the `bootstrapApplication()` function (usually in main.ts), add the `provideAnimations()` function in the provider list:
```ts
import {provideAnimations} from '@angular/platform-browser/animations';
bootstrapApplication(AppComponent, {
providers: [
provideAnimations(),
]
});
```
Or for `NgModule` based applications import `BrowserAnimationModule`, which introduces the animation capabilities into your module:
```ts
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
@NgModule({
declarations: [],
imports: [
BrowserAnimationModule
],
exports: [],
providers: []
})
export class AppModule {
}
```
> See [Angular documentation](https://angular.dev/guide/animations#getting-started)
## Documentation and usage
For a better comprehension of the components and their usage, we recommend checking our [Storybook](https://fluid.design.digital.engie.com/fluid-design-system/angular/index.html) documentation.
For Fluid overall documentation, you can check our [Fluid documentation](https://www.engie.design/fluid-design-system/).
If you have correctly followed the installation steps, you should be able to use Fluid components in your project.
All components are exported in `@engie-group/fluid-design-system-angular`:
```typescript
import {NgModule} from "@angular/core";
import {ButtonComponent} from '@engie-group/fluid-design-system-angular'
@NgModule({
imports: [ButtonComponent]
})
export class AppModule {}
```
or
```typescript
import {Component} from "@angular/core";
import {ButtonComponent} from '@engie-group/fluid-design-system-angular'
@Component({
standalone: true,
template: '<nj-button>Label</nj-button>',
imports: [ButtonComponent]
})
export class CustomComponent {}
```
## Troubleshooting and feature requests
If you encounter any issues, or you want any component or feature to be implemented, please create an issue or a feature request on our [GitHub repository](https://github.tools.digital.engie.com/GBSEngieDigitalDesignSystem/fluid-design-system/issues).