Add a Custom Web Font

As part of customizing your site's design, you can choose from an array of styles, color schemes and imagery. But one additional level of customization you can go to is adding your own web font. You may want to add a custom font to meet your company's brand guidelines, for example, or to add a touch of style to your site.

While there are a number of considerations concerning the preferable way to use a font on your SCA site, this article will take you through the simplest and most common method.


Before you start it's worth noting that this method uses the CSS3 @font-face rule; thus you are effectively giving the user a copy of the font. This has two potential implications:

  1. You will need to check the license of the font you are using. Unless you are the creator of the font, there will likely be restrictions on how you can use it. For example, some state that you must pay a fee to use it on a commercial site; others do not allow you to distribute copies. Thus you must make sure you have legal clearance to use it.
  2. If you own the font and you use it on your site, it may be possible for users to download and use a copy of it. If your organization is very protective of your font, this method may not be suitable. For alternatives, you can seek a third-party font delivery service that will set up barriers that can help prevent unauthorized usage.

With that said, there are a number of sites that offer freeware fonts. For the purposes of this article I am going to use the Existence Light font from Font Squirrel to change the font of my heading elements, if you want to follow along. I'm going to use the Webfont kit option as this will provide us with font in many different formats, which is imperative for ensuring browser and platform compatibility.

Create the Folder Structure

As is usual, we start by creating a module. For this we're going to set up the font as if it were a custom module and setting up the folder structure for the font.

Under the Modules folder you use for your site's customizations, create a folder structure like the one below, using the name of the font as the folder name. For example, my folder structure looks like this:

  • Modules

    • Custom

      • FontExistenceLight@1.0.0

        • Fonts
        • Sass

Put your font files into the Fonts folder.

After that you'll need to create the ns.package.json file for this module. It should be straightforward, but for reference:

    "gulp": {
        "fonts": [
        "sass": [

Update distro.json

Another standard part of any new module is updating the distribution file so that it is included during the compile process. Open up distro.json in your editor.

First things first: at the top, in modules, add in the location of your module.

Next you need to add in the location of the Sass files for each of the applications' CSS files that you want the font to be used in. I'm going to add it to all of my applications, so for the shopping application I'm going to search for "shopping.css" in distro.json and add it to the list of dependencies. You should do the same and repeat it for the other applications, if you wish.

Save your distro.json file.

Add Styling

So now our font is ready to use, now we just need to add the Sass that will include the @font-face rule and add the styling that will change the font of our titles.

Under FontExistenceLight@1.0.0 > Sass I'm going to create _existencelight.scss and put the following in it:

@font-face {
    font-family: 'existencelight';
    src: url('../fonts/Existence-Light-webfont.eot');
    src: url('../fonts/Existence-Light-webfont.eot?#iefix') format('embedded-opentype'),
         url('../fonts/Existence-Light-webfont.woff') format('woff'),
         url('../fonts/Existence-Light-webfont.ttf') format('truetype'),
         url('../fonts/Existence-Light-webfont.svg#existencelight') format('svg');
    font-weight: normal;
    font-style: normal;
h1, h2, h3, h4, h5, h6 {
    font-family: 'existencelight', 'Helvetica Neue', Helvetica, Arial, sans-serif;

The first part was generated for me by Font Squirrel. What it does is create a new font family, named after my font; I will then be able to use this my CSS. Included in it are references to the locations of each of the formats of the font. If you're going to write your own @font-face rule, then you should read up on the best practices and guidelines for writing them.

The last bit is a simple style change that we're going to make: take all the heading elements and apply the new font to them. Note that you do not have to put the CSS/Sass styles in the same file. You can very easily, for example, include them in any custom Sass file that you have for your site-specific styles; in fact, it may make more sense to do this if it's easier for you to manage where your site's styles are coming from. The important part of it is that it is a standard CSS declaration for changing the font family of some elements.

Test Your Changes

Save everything and run a test on your local server. If it's been successful then you should see your changes.

It is always good advice to check your changes across various devices, platforms and browsers; remember that this method adds in support for various devices and browsers so you should be sure that it works as intended.

Finally, a note on performance: adding a web font can degrade both the loading time of a site and its perceived loading time. If you are concerned about your site's performance, consider whether including a custom web font is appropriate for you.

Further Reading