Hi,

Customer wants to align Pega application with their style guideline that covers company's brand identify such as logos, typography (fonts), color palette, etc. In this post, I will show how to install custom web fonts to Pega Platform.

• System fonts vs Web fonts

Let's start with the basics. System fonts (a.k.a Web safe fonts) are fonts that are pre-installed on the most of browsers and devices. They don't have to be downloaded from the website's server to be displayed. This comes with two major benefits:

1. Consistency - Designer can expect typography to appear exactly as intended for all users.
2. Performance - System fonts are stored locally, so your website should load much faster.

However, there are only limited number of System fonts. That’s where Web fonts come in. Web fonts offer an alternative to System fonts because they are hosted on the web and then downloaded by the browser while rendering the web page. To use Web fonts, you'll need to either self-host (on your own server) or use a third-party font delivery service like Google Fonts or Adobe Fonts. In general, it is important to make System fonts available as fallback fonts in case your selected web fonts can't be displayed on a client.

• Pega's out-of-the-box fonts 

Pega uses Opan Sans fonts by default. Open Sans is one of the most popular Web fonts on Google Fonts and it is already imported in the form of Rule-File-Binary as out-of-the-box. You can check available fonts from Skin rule as below. As you can see, there are 16 choices available in the dropdown.

1. Arial
2. Arial Black
3. Arial Narrow
4. Calibri
5. Cambria
6. Candara
7. Comic Sans MS
8. Constantia
9. Corbel
10. Courier New
11. Georgia
12. Open Sans
13. Tahoma
14. Times New Roman
15. Trebuchet MS
16. Verdana

If you want to use other fonts than this list, and if it is a System font, you can simply type the name after selecting "other...", shown as below. The change is reflected right after you save the rule. Be noted, if you enter wrong font name, system doesn't show any error message. You should type the exact name with care.

If you want to use Web font other than Open Sans, you'll need to install it on your own.

• Font file format

There are various types of font file formats and you may wonder which one to use.

Any file format above can be installed on Pega Platform, but our recommendation is to use WOFF2. SVG and EOT are dead formats. TTF / OTF are full System Font for PCs and should not be used for web purposes. WOFF/WOFF2 are web-exclusive and load faster than any other format because they are compressed version of the TTF format. WOFF2 is the next generation of WOFF and it offers a 30% average compression gain over WOFF, so this is the one you should pick for the best performance.

• Installation steps

From here on, I will show how to install Noto Sans JP, license free Web font provided by Google Fonts. Noto Sans JP is one of the most commonly used fonts at Japanese website.

1. Download fonts file

Download fonts file from https://fonts.google.com.

2. Extract the zip file. You should find "NotoSansJP-VariableFont_wght.ttf" file which contains all the weights in a single file. Font weight means the thickness of characters (ex. Regular, Bold, Extra Bold). If you use this file, single upload is sufficient. However, the file is big (9MB) and it is better to decrease the size by dividing it per weight for better performance.

3. In "static" directory, you should find a set of divided TTF files per each weight. I would recommend that you use only selected files that are required by your application. Decreasing the total count of font files will give a better focus on the main content to load faster. In this example, I will use only Regular and Bold, that are the most common weights.

4. Now, convert TTF file to WOFF/WOFF2. Most modern browsers use WOFF2. Internet Explorer 11 exclusively uses WOFF. There are many free conversion tools over the Internet. In this example, I used https://cloudconvert.com and converted Regular / Bold files to WOFF and WOFF2, total four files.

5. WOFF2 and WOFF files are created. You can see the file size is now decreased from 5.5MB to 2 – 3MB. The smaller, the better performance.

6. Log in to Dev Studio and create Rule-File-Binary. Specify webwb for App Name (Directory) and woff2 for File Type (extension) as below.

7. Upload WOFF2 file. Repeat this step for the rest of font files.

8. Repeat this step and make sure four files are imported.

9. Create a Rule-Text. The rule ID name is arbitrary. In this example, I named it "NotoSansJP". Specify webwb for App Name (Directory) and css for File Type (extension).

10. Include below snippet. @font-face is a CSS rule that allows you to specify your own custom font to appear on a website. Quotation marks can be double ("...") or single ('...'). If you are uncertain about syntax, you can also refer to the out-of-the-box css rule that defines Open Sans (search "pzbase-fonts"). For font-weight property, you can use numeric values (100-900). 400 is equal to normal, and 700 is equal to bold.

@font-face {
  font-family: "NotoSansJP";
  src:url("webwb/NotoSansJPRegular.woff2") format("woff2"),
  url("webwb/NotoSansJPRegular.woff") format("woff");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}                    

@font-face {
  font-family: "NotoSansJP";
  src:url("webwb/NotoSansJPBold.woff2") format("woff2"),
  url("webwb/NotoSansJPBold.woff") format("woff");
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

11. Add this css file to Skin rule from Included styles tab.

12. Select "other..." for overall font from Base settings tab and specify "NotoSansJP", which is the font-family name you defined in the css.

13. Make sure the font is reflected on overall application.

• Common weight name mapping

The numerical values 100 to 900 roughly correspond to the following common weight names.

• Gaiji

Some Japanese customers may want to use Gaiji in Pega. I've also posted how to enable Gaiji at another article. Please refer to https://support.pega.com/discussion/how-enable-gaiji-japanese-customer.

Hope this helps.

Thanks,