= Add Fonts

This page explains how to add new fonts to your UI.
These instructions assume you've forked the default UI and are able to customize it.

There are three steps involved:

. Add the font to your UI project
. Add a font-face declaration to your stylesheet
. Use the new font in your stylesheet

How you reference the font file in the font-face declaration depends on how you decide to manage it.
You can manage the font with npm or download it manually and add it directly to your UI project.
The following sections describe each approach in turn.

== npm managed

You can use npm (or Yarn) to manage the font.
This approach saves you from having to store the font file directly in your UI project.
Here are the steps involved.

. Use npm (or Yarn) to install the font files from a package (e.g., https://www.npmjs.com/package/typeface-open-sans[typeface-open-sans])

 $ npm install --save typeface-open-sans

. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
. In that file, declare the font face:
+
[source,css]
----
@font-face {
  font-family: "Open Sans";
  font-style: normal;
  font-weight: 400;
  src:
    local("Open Sans"),
    local("Open Sans-Regular"),
    url(~typeface-open-sans/files/open-sans-latin-400.woff) format("woff")
}
----
+
The Gulp build recognizes the `~` URL prefix and copies the font from the npm package to the build folder (and hence bundle).
+
You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.

. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
+
[source,css]
----
@import "typeface-open-sans.css";
----

. Repeat the previous steps for each font style and weight you want to use from that package.
. Change the CSS to use your newly imported font:
+
[source,css]
----
html {
  font-family: "Open Sans", sans;
}
----
+
TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.

. Test the new font by previewing your UI:

 $ gulp preview

If you see the new font, you've now successfully added it to your UI.
If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.

== Manual

A simpler approach to adding fonts is to store them directly in your project.
Here are the steps involved.

. Download the font files and add them to the [.path]_src/font_ folder.
Create this folder if it does not exist.
. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
. In that file, declare the font face:
+
[source,css]
----
@font-face {
  font-family: "Open Sans";
  font-style: normal;
  font-weight: 400;
  src:
    local("Open Sans"),
    local("Open Sans-Regular"),
    url(../font/open-sans-latin-400.woff) format("woff")
}
----
+
Note that the path is a relative path starting from the [.path]_src/css_ folder to the [.path]_src/font_ folder.
+
You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.

. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
+
[source,css]
----
@import "typeface-open-sans.css";
----

. Repeat the previous steps for each font style and weight you want to use.
. Change the CSS to use your newly imported font:
+
[source,css]
----
html {
  font-family: "Open Sans", sans;
}
----
+
TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.

. Test the new font by previewing your UI:

 $ gulp preview

If you see the new font, you've now successfully added it to your UI.
If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.