engie-fluid-material-theme

v21.2.12

Published

18 days ago

Angular Material theme for Fluid Design System

0High
0Medium
0Low

kk1268

engie fluid design-system material theme

Engie Fluid Material Theme

An Angular Material (M3) theme that makes standard Angular Material components look and feel close to ENGIE's Fluid Design System.

⚠️ This theme aims to be visually close to the Fluid Design System, but it is not a perfect one-to-one match.

Overview

This library ships a compiled CSS file plus an Angular Material M3 theme (m3-theme.scss). Once installed and referenced, the default Angular Material components are restyled to resemble their Fluid counterparts — with no change to your component templates in most cases.

The package version is aligned with the supported Angular Material major version (e.g. 21.x targets Angular Material 21).

Prerequisites

Your application must already use Angular Material and the Fluid Design System:

| Dependency | Minimum version | | --- | --- | | @angular/core / @angular/common | >= 21.2.12 | | @angular/material | >= 21.2.10 | | @engie-group/fluid-design-tokens | >= 6.2.1 | | @engie-group/fluid-design-system | latest |

Installation

Install the package:

npm install --save engie-fluid-material-theme

Reference the theme's CSS in the styles array of angular.json. Together with the default stylesheet and the Fluid Design System, it should look like this:

"styles": [
  "src/styles.scss",
  "node_modules/@engie-group/fluid-design-tokens/lib/css/tokens.css",
  "node_modules/@engie-group/fluid-design-system/lib/fluid-design-system.css",
  "node_modules/engie-fluid-material-theme/dist/index.css"
]

Configuration

Load the Material theme in your main styles.scss:

@use 'sass:map';
@use 'engie-fluid-material-theme/dist/m3-theme';
@use '@angular/material' as mat;

@include mat.core;

body {
  @include mat.all-component-themes(m3-theme.$light-theme);

  .error-button {
    @include mat.button-color(m3-theme.$light-theme, $color-variant: error);
  }

  .secondary-button {
    @include mat.button-color(m3-theme.$light-theme, $color-variant: secondary);
  }

  &[data-theme="dark"] {
    @include mat.all-component-colors(m3-theme.$dark-theme);
  }
}

Dark mode is enabled by setting data-theme="dark" on the <body> element.

Configure the default behaviour of Material components by registering these providers in your app.config.ts:

import { MAT_RIPPLE_GLOBAL_OPTIONS } from '@angular/material/core';
import { MAT_FORM_FIELD_DEFAULT_OPTIONS } from '@angular/material/form-field';
import { MAT_TOOLTIP_DEFAULT_OPTIONS } from '@angular/material/tooltip';
import { MAT_SNACK_BAR_DEFAULT_OPTIONS } from '@angular/material/snack-bar';

export const appConfig: ApplicationConfig = {
  providers: [
    // Disable the ripple effect globally
    { provide: MAT_RIPPLE_GLOBAL_OPTIONS, useValue: { disabled: true } },
    // Use the 'outline' appearance for all form fields
    { provide: MAT_FORM_FIELD_DEFAULT_OPTIONS, useValue: { appearance: 'outline', subscriptSizing: 'dynamic' } },
    { provide: MAT_TOOLTIP_DEFAULT_OPTIONS, useValue: { showDelay: 500, hideDelay: 200 } },
    { provide: MAT_SNACK_BAR_DEFAULT_OPTIONS, useValue: { duration: 4000 } },
  ],
};

Usage

With the theme in place, standard Material components render with the Fluid look. A few examples:

Form field

<mat-form-field>
  <mat-label>Label</mat-label>
  <input matInput />
</mat-form-field>

Radio

<mat-radio-button (change)="valueChange()" [checked]="true">Label</mat-radio-button>

Buttons

<button mat-flat-button (click)="buttonClick()">Button</button>
<button mat-stroked-button (click)="buttonClick()">Button</button>
<button mat-button (click)="buttonClick()">Button</button>

When color variations are needed, add the corresponding CSS class (see Utility classes).

Supported components

The theme restyles the following Angular Material components:

| | | | | --- | --- | --- | | Button | Card | Checkbox | | Chip | Datepicker | Dialog | | FAB | Form field | Menu | | Option | Overlay | Radio | | Select | Sidenav | Snackbar | | Spinner | Switch | Tab | | Table | Toggle | Tooltip |

Utility classes

Add these classes to enable color variants, sizes and style options.

Button

| Purpose | Classes | | --- | --- | | Color variants | .secondary-button, .error-button, .ai-button | | Size | .small |

Chip

| Purpose | Classes | | --- | --- | | Accent colors | .teal, .orange, .blue, .lime, .yellow, .red, .green, .pink, .purple, .ultramarine, .brand | | Size | .xs, .sm, .lg |

Badge

A badge is a chip with the .badge class. Combine it with a status color and, optionally, a style modifier.

| Purpose | Classes | | --- | --- | | Base | .badge | | Status colors | .information, .discovery, .success, .warning, .danger, .planet, .ai | | Style modifiers | .minimal, .subtle |

<!-- Solid success badge -->
<mat-chip class="badge success">Success</mat-chip>

<!-- Subtle information badge -->
<mat-chip class="badge subtle information">Info</mat-chip>

<!-- Minimal warning badge -->
<mat-chip class="badge minimal warning">Warning</mat-chip>

Button toggle

Apply a status color to a mat-button-toggle; it is used when the toggle is checked.

| Purpose | Classes | | --- | --- | | Status colors | .information, .discovery, .success, .warning, .danger |

Form field & Select

| Purpose | Classes | | --- | --- | | Size | .small |

Table

| Purpose | Classes | | --- | --- | | Style | .zebra, .quiet |

Developer guide

The theme source lives in the src/ folder. Each component is defined in its own partial under src/components/.

Common commands (run from the project root):

| Command | Description | | --- | --- | | npm run build | Compile src/index.scss into dist/index.css and copy m3-theme.scss to dist/. | | npm run qa:scss | Lint the SCSS sources with Stylelint. | | npm publish | Publish the package to the public npm registry. Bump the version in package.json and update the CHANGELOG first. |

Testing changes locally

The test/ folder contains an Angular demo app used to visualize the theme. During development, edit the theme, rebuild, and preview it in the demo app:

# From the project root: rebuild the theme
npm run build

# From the test/ folder: start the demo app
cd test
npm install
npm start

Contributing

Create a branch and make your changes in src/.
Run npm run qa:scss and verify the result in the demo app.
Update the CHANGELOG and bump the version in package.json.
Open a pull request on the GitHub repository.

License

Released under the EPL-2.0 license.