How to use Fiori Fundamentals SCSS with Angular

The following step-by-step guide will covers how to install Fiori Fundamentals in your angular project, import SCSS in your workflow and explain some built-in functions.

Table of contents

1. Prerequisites and Requirements
2. Configuring Angular Project to use SCSS
3. Installing Fiori Fundamentals via NPM
4. Configuring and Importing SCSS source
5. Selective Imports
6. Core Functions and Mixins

Prerequisites and Requirements

• Familiarity using terminal or command prompt
• This guides assumes that the initial setup was done using Angular 4 or higher and initial setup was doing using Angular CLI
• NPM is installed globally

Configuring Angular Project to use SCSS

Angular CLI does not configure the project to process SCSS files by default. Instead it is set to a CSS file located at the root of src folder. We recommend that you use keep all your SCSS files in one place under src/scss/.

To set the angular project to use SCSS:

1. Type ng set defaults.styleExt scss in command prompt or terminal at project root.

2. Open .angular-cli.json located at the project root and change the styles configuration to "styles": [ "scss/app.scss"]

3. Verify that the styleExt is set to scss

4. Create a folder named scss under the src folder and a also create the main SCSS file named app.scss

5. Remove the src/styles.css file. It will not be used.

The Basic SCSS configuration is now complete.

Installing Fiori Fundamentals via NPM

Fiori Fundamentals is currently available as an NPM package and a compiled and minified CDN file. The following steps will cover how to install it via NPM.

1. Type npm install fiori-fundamentals --save-dev. This will install the package as a dev dependency.
2. Verify the installation was successful by typing npm list fiori-fundamentals

Fiori Fundamentals installation is now complete

Configuring and Importing SCSS source

1. Open scss/app.scss file
2. Add the following line of code to define the icons path:
   
   $fd-icons-path: "~fiori-fundamentals/scss/icons/";
3. Add the following line of code to define the fonts path:
   
   $fd-fonts-path: "~fiori-fundamentals/scss/fonts/";
4. Add the following line of code to import SCSS source file:
   
   @import "~fiori-fundamentals/scss/all.scss";

Importing Fiori Fundamentals SCSS is now complete

Note: In order to render the icons and fonts correctly, you need to define the $fd-icons-path and $fd-fonts-path variables.

At this point, the contents of your scss/app.scss should look like this:

$fd-icons-path: "~fiori-fundamentals/scss/icons/";
$fd-fonts-path: "~fiori-fundamentals/scss/fonts/";
@import "~fiori-fundamentals/scss/all.scss";

You can continue to build out your SCSS workflow based on your project needs.

Selective Imports

Fiori Fundamentals is divided into several functional pieces. You may choose to import key features selectively to reduce the SCSS overhead in your project.

Here is an overview of the SCSS structure -

scss/
 |- components/
 |- core/
 |- helpers/
 |- icons/
 |- layout/
 |- theme/
 all.scss
 components.scss
 core.scss
 helpers.scss
 icons.scss
 layout.scss

• all.scss: Includes all components.
• components.scss: SCSS source for each components. The components are decoupled with little or no dependency on other components.
• core.scss: The main purpose of core is elements and forms. It’s like the reset and foundation.
• helpers.scss: Includes various helper functions.
• icons.scss: Fiori Fundamentals’s custom icon library.
• /theme/fundamental.scss: Includes fonts.
• layout.scss: App level layout components such as top Overview of Core features bar, side nav, containers, panels, etc.

You can choose to selectively import parts of the library that best fits the need of your project. Please note that components, icons, layout and helpers have a dependency on settings.scss. Therefore, settings.scss should always be included in case if you are not importing all.scss. For fonts, make sure you are importing theme/fundamental.scss

For selective import your app.scss content should look like this:

$fd-icons-path: "~fiori-fundamentals/scss/icons/";
@import "~fiori-fundamentals/scss/theme/fundamental";
@import "~fiori-fundamentals/scss/core";
@import "~fiori-fundamentals/scss/{feature}";

Angular components

If you are writing angular components using Fiori Fundamentals toolkit, you will need to import the following in your component’s scss file:

@import "~fiori-fundamentals/scss/core/settings";
@import "~fiori-fundamentals/scss/core/mixins";
@import "~fiori-fundamentals/scss/core/functions";

Core Functions and Mixins

Fiori Fundamentals comes with some very useful built-in functions and mixins to help maintain consistency and quality of your SCSS source files. We recommend that you utilize these functions instead of hard coding colors, spacing, fonts, etc. in your code to keep CSS low specificity. Utilizing functions also helps in retaining the integrity of the theming options and makes it easy to switch between different themes such as a high-contrast theme for accessibility or a brand specific theme.

Note: In order to use the functions and mixins, please ensure that you are importing the functions SCSS files
@import "~fiori-fundamentals/scss/core/functions";
@import "~fiori-fundamentals/scss/core/mixins";

Color Function

If you have a need to apply a color to any of your scss/css class, you can use the built-in color function -
fd-color(group, shade)

.foo {
  background-color: fd-color(neutral, 3); /* renders #ccdaeb */
  color: fd-color(text, 1); /* renders #21262c */
}

You can refer to the colors page for the complete list of the available color options.

Spacing Function

fd-space("value")

The space function can be utilized for heights, padding, margins and other positioning.

The design system defines a variety of spacing increments that are commonly used throughout and all of those are available using the mixin by passing the key. However, there are four units that will be used most often when building and extending components. These are accessible with special keys to apply consistent padding and margins.

.foo {
  padding: fd-space("tiny"); /* renders 8px */
  margin-bottom: fd-space("small"); /* renders 24px */
}

The following spacing options are available -

Type Mixin

You can utilize the type mixin to render size, line height and weight -
fd-type($size, $weight)

.foo__header {
    @include fd-type("3", "bold"); /* renders the css below */
    /* font-size: 1.75rem; */
    /* line-height: 1.4; */
    /* font-weight: 700; */
}